CreamUI applications are normal Rust binaries. Build a widget tree in a closure, return it from run, and let signals rebuild that tree when state changes.
For a standard native app, add the facade crate:
[dependencies]
creamui = { version = "0.1", features = ["jsx"] }Enable image support from the facade when your app displays raster assets:
creamui = { version = "0.1", features = ["jsx", "image-jpeg", "image-webp"] }PNG is enabled by default. JPEG and WebP stay opt-in to keep application builds focused on the formats they use.
creamui::run creates a window. Its final closure receives the current viewport and returns the root widget for that frame.
run(options, Theme::default().surface, |_| {}, move |viewport| {
let theme = Theme::default();
Box::new(jsx! {
<Block style={my_layout(viewport)}>
<Text>"Welcome"</Text>
</Block>
})
});Use Signal<T> for UI state. Calling get() while building subscribes the screen to that value; changing it rebuilds the affected window on the next frame.
let enabled = Signal::new(false);
let set_enabled = enabled.clone();
jsx! {
<Checkbox theme={&theme} checked={enabled.get()}
on_click={move || set_enabled.update(|value| *value = !*value)} />
}use_viewport() reads the current logical window size from any component
building under run; it does not need to be threaded through component props.
use_screen_class() derives Compact (under 640 px), Medium (under 960 px),
or Expanded from that width.
use creamui::{use_screen_class, use_viewport, ScreenClass};
let viewport = use_viewport();
let compact = use_screen_class() == ScreenClass::Compact;
let padding = if compact { 16.0 } else { 28.0 };
let width = viewport.width;The window rebuilds after a resize, so the hook is suitable for swapping navigation patterns, spacing, or layout direction. Prefer these width classes over device labels: a narrow desktop window and a phone should receive the same compact layout.
use_safe_area() reports the logical-pixel bands already occupied by system
UI: the status bar, navigation bar, display cutout, and on-screen keyboard.
Taps in those bands are delivered to the system, so inset toolbars and other
controls by top, right, bottom, and left. Desktop client areas report
zeros. Android reads window insets. A browser page reports
env(safe-area-inset-*) when its viewport uses viewport-fit=cover.
creamui::widgets::layout has a semantic flex API for layout containers:
use creamui::widgets::layout::{Align, Flex, Justify, Wrap};
let toolbar = Flex::row()
.gap(12.0)
.align(Align::Center)
.justify(Justify::Between);
let cards = Flex::row()
.gap_x(16.0)
.gap_y(12.0)
.wrap(Wrap::Wrap);For two-dimensional layout, use Grid and position only the items that need
an explicit cell or span:
use creamui::widgets::layout::{Grid, GridItem, Track};
let dashboard = Grid::new()
.template_columns([Track::px(240.0), Track::fr(1.0), Track::fr(1.0)])
.gap(16.0)
.child(Box::new(GridItem::new().at(1, 1).column_span(2)));The same container is available in JSX when the jsx feature is enabled:
use creamui::core::layout::FlexDirection;
jsx! {
<Flex direction={FlexDirection::Column} gap={12.0}
align={Align::Center} justify={Justify::Center}>
<Text>"Centered content"</Text>
</Flex>
}Flex::row() and Flex::column() are unstyled div-like containers. They
support gap, axis alignment, justify, wrapping, padding, fixed/fill sizes,
and item behavior (grow, shrink, basis, align_self). For the same
chainable properties on any Style, import StyleExt and start with
Style::default().flex_row(), .flex_column(), or .grid().
For advanced layout properties, use the re-exported Taffy types through
creamui::core::layout.
creamui::Style is the component-independent style declaration. It combines
layout, paint, typography, and interaction-state patches; each component uses
only the properties it can render. Interaction patches intentionally exclude
layout so a hover or press cannot move its own hit target.
use creamui::{ColorToken, StateStyle, Style, StyleProp};
use creamui::widgets::layout::StyleExt;
let action = Style::new()
.size(220.0, 48.0)
.background(ColorToken::SurfaceElevated)
.border(ColorToken::Border, 1.0)
.corner_radius(8.0)
.color(ColorToken::TextPrimary)
.font_size(14.0)
.hover(StateStyle::new().background(ColorToken::AccentHover))
.pressed(StateStyle::new().background(ColorToken::AccentPressed))
.focus(StateStyle::new().outline(ColorToken::Accent, 2.0))
.property(StyleProp::parse("min-width", "120px").unwrap());Existing creamui::core::layout::Style values still work anywhere a common
style is accepted through the From/Into adapter. This keeps existing Taffy
struct literals valid while applications migrate declarations incrementally.
Strings are accepted at declaration/build time (.width("10px"),
.color("accent"), or StyleProp::parse). They are immediately compiled into
typed ColorValue and LengthValue values; widgets and the renderer never
interpret CSS strings.
Semantic ColorTokens are resolved against the window's current color scheme
at paint time, so a stored style follows theme changes without being rebuilt.
See the styling scope for the supported declaration boundary and
the CSS features intentionally outside it.
Every built-in component implements the Styled extension trait. A component
does not need its own width, background, or font_size forwarders:
use creamui::core::layout::Style as LayoutStyle;
use creamui::widgets::RawButton;
use creamui::{ColorToken, Styled};
let button = RawButton::new(LayoutStyle::default(), || {})
.width(120.0)
.height(40.0)
.background(ColorToken::Accent)
.corner_radius(8.0);Each builder updates the declaration owned by the concrete component and keeps
its type, so component-specific methods remain chainable. A custom Widget
opts in by implementing only Styled::set_style. For configuration loaded
from strings, use .property(StyleProp::parse(...)?).
The component style matrix identifies which
content fields each built-in family consumes.
The same model is available in JSX. style applies a reusable Rust
declaration, then inline common properties override it:
let card = Style::new().width("100%").background(ColorToken::Surface);
let view = jsx! {
<Block style={card.clone()} corner_radius={12.0}>
<Text color={ColorToken::TextPrimary} font_size={16.0}>"Shared style"</Text>
</Block>
};Run cargo run -p jsx-styles for a complete window that shares a JSX style
between buttons and overrides one inline.
Box paint is centralized: the renderer draws the resolved background, border,
radius, and outline before calling a widget's content-specific paint method.
Pointer, focus, and component-owned disabled states are composed rather than
being mutually exclusive.
WindowHandle::resize(width, height) requests a logical-pixel client size.
WindowHandle::set_min_size(Some((width, height))) changes the native minimum
client size; pass None to clear that constraint. Apply it in the window-ready
callback, then update it when switching layouts with different requirements.
The winit desktop backend forwards the minimum to the native window; native
Wayland sends xdg_toplevel.set_min_size and commits the surface state. Requested
resizes are asynchronous and the window manager owns the final configured size.
- Browse components for the component families and their state model.
- Read theming before creating an application-specific visual language.
- Run
cargo run -p showcasefrom a clone of this repository to explore live controls.