The components

zgui-ui is a library of styled components. It sits on layer L8, it depends on zgui and its three sibling crates and on nothing else, and it is optional: every component in it is written with the API the guide already covers.

This page is the inventory with props, and then three components taken apart — a button, a dialog and a select — down to the elements, signals, contexts, portals and sheets each one is made of.

What every component does the same way

Three rules hold across the crate (crates/zgui-ui/src/lib.rs).

Appearance is a variants! table and a style! sheet. Each component declares its axes once. The table lowers to a class list and to one data- attribute per axis, and the sheet selects on the attributes. Nothing computes a class name at run time and nothing branches on a variant in Rust.

Interaction state belongs to the style engine. There is no hovered, no focused and no pressed signal anywhere in the crate. :hover, :focus-visible, :active, :disabled, :checked, :indeterminate, :placeholder-shown and :invalid are states the engine already holds. A component that kept a second copy would disagree with the first one on the frame the pointer leaves.

A caller can always add to the element. Every component takes class and an attribute bundle, and merges the caller's values after its own, so the caller wins.

use zgui::prelude::*;
use zgui_ui::prelude::*;

view! {
    Button(class = "w-full", attr:data-testid = "save", a11y:label = "Save changes") {"Save"}
}

Who owns a value

Every component with a value takes three props: value (or checked, pressed, open, index), a default_…, and on_change (or on_open_change). The type of the first decides ownership.

A read-only Signal at one of these props is a compile error. There is no From<Signal<…>> for Binding, and crates/zgui-ui-primitives/src/state/binding.rs carries a compile_fail doctest that asserts it. on_change is told in all three cases, after the binding has been asked, and observes rather than drives.

How to read the tables

Every component below also takes the tail that is left out of the rows:

Reading the prop cells:

• Signal<T> means Signal<T, LocalStorage>. Every one is #[prop(into)], so a plain T and a signal are both accepted.
• Binding<T> is the ownership prop from the table above.
• Option<T> props take a T, never Some(T).
• fn in the children column means ChildrenFn: the child list is built again each time the surface opens, because a surface that was unmounted has to be built a second time.
• A row with no children column entry renders no children.

The inventory

The atoms

ButtonVariant is Default, Secondary, Destructive, Outline, Ghost, Link. ButtonSize is Sm, Md, Lg, Icon. BadgeVariant is Default, Secondary, Destructive, Outline. AvatarSize is Sm, Md, Lg.

The containers

Progress with value = None is the indeterminate case. Alert(live = true) gives the element role Alert and a polite live region; live = false makes it a Group.

The text fields

Input and Textarea render the field element. The text lives in the framework's editing model over that element, not in the component.

The choices

Checked is No, Yes, Mixed. Mixed sets UiState::INDETERMINATE, which :indeterminate matches.

The disclosures

AccordionTrigger(level) is the heading level a reader is told, so an accordion inside a section does not claim to be a top-level heading.

Getting about

page_window(current, pages, slots) -> Vec<Slot> in zgui_ui::pagination computes which page numbers and which gaps to draw. Slot is Page(usize) or Gap.

The surfaces that move

Data

Table and DataTable are different things. Table is presentational: one CSS grid, plus the roles a reader needs. DataTable<T, I> is generic and model-driven, and sorts, filters, pages, selects and virtualises through DataModel<T>.

Column<T>::new(...) builds a column, with .sortable_by(…) and .sized(track). VirtualList builds only the rows in view plus overscan at each edge.

Toasts

Toaster wraps the interface rather than sitting beside it, because it publishes the queue as a context and a context only flows down. use_toaster() -> Option<ToastQueue> reaches it, and queue.push(Toast::new("Saved")) shows one.

Forms

The surfaces that take the window over

An alert dialog has no dismiss_on_outside_press prop because it does not have the behaviour: a stray press past a destructive confirmation must not count as an answer.

The surfaces that float beside a control

A dropdown menu and a context menu differ in what opens them and in nothing else. Both fill their surface with the menu components in the table above.

The lists one thing is chosen from

What those are built out of

These are public, and they are what a surface of your own is written from. AnchoredSurface, ModalSurface, OverlaySurface and OverlayState are exported from the crate root. Elevated, Confined, Scrim and ListboxCatalogueOf are reachable at their module path, zgui_ui::overlay or zgui_ui::listbox, and are absent from the prelude.

Aliases

Several names are the same component twice. They are pub use re-exports, not wrappers.

Deconstruction 1: Button

The whole component, from crates/zgui-ui/src/button/mod.rs:

const SHEET: &str = "zui-button";

#[component]
pub fn Button(
    #[prop(default = ButtonVariant::Default)] variant: ButtonVariant,
    #[prop(default = ButtonSize::Md)] size: ButtonSize,
    #[prop(into, default = Signal::stored_local(false))] disabled: Signal<bool, LocalStorage>,
    #[prop(optional)] node_ref: Option<NodeRef>,
    #[prop(into, optional)] class: Classes,
    #[prop(attrs)] attrs: Attrs,
    children: Children,
) -> impl IntoView {
    install_stylesheet(SHEET, ButtonStyle::CSS);
    let element = node_ref.unwrap_or_default();
    let variants = ButtonVariants { variant, size };
    let own = variant_attrs(variants.classes(), variants.data_attributes())
        .state(UiState::DISABLED, move || disabled.get())
        .a11y_from(A11yBinding::new(Role::Button).disabled(move || disabled.get()));

    view! {
        control(class = ButtonStyle::CLASS, node_ref = element, tabindex = Focus::Sequential,
                {..own}, {..attrs}, class = class) {
            {children.into_view_once()}
        }
    }
}

What it is made of:

The variants! table is the appearance, and its output is asserted in the crate's own doctest:

let quiet = ButtonVariants { variant: ButtonVariant::Ghost, size: ButtonSize::Sm };
assert_eq!(quiet.class_list(), "zui-button zui-button--ghost zui-button--sm");
assert_eq!(quiet.data_attributes(), [("data-variant", "ghost"), ("data-size", "sm")]);

The sheet selects on those data- attributes, and every interaction state is CSS (crates/zgui-ui/src/button/style.rs):

:scope[data-variant="ghost"] { background-color: transparent; color: var(--zui-color-foreground); }
:scope[data-variant="ghost"]:hover { background-color: var(--zui-color-accent); }
:scope:active { transform: translateY(1px); }
:scope:focus-visible { outline: 2px solid var(--zui-color-ring); outline-offset: 2px; }
:scope:disabled { opacity: 0.5; pointer-events: none; }

disabled is written once, as UiState::DISABLED. That one state is what :disabled matches, what takes the control out of the focus order, what takes it out of the pointer's reach, and what a reader is told. There is no second copy.

To replace it yourself: one control, a variants! table, a sheet and one A11yBinding — about 110 lines, which is what crates/zgui-ui/src/button/ measures (109 code lines over mod.rs and style.rs, blank and comment lines excluded).

Deconstruction 2: Dialog

A dialog is an overlay: a surface drawn over the rest of the window, on a paint band of its own, that takes the interaction over until it is answered.

Dialog itself renders no element. It publishes two contexts and returns its children (crates/zgui-ui/src/dialog/mod.rs):

#[component]
pub fn Dialog(
    #[prop(into, optional)] open: Binding<bool>,
    #[prop(default = false)] default_open: bool,
    #[prop(optional)] on_open_change: Option<UnsyncCallback<bool>>,
    children: Children,
) -> impl IntoView {
    OverlayState::new(open, default_open, on_open_change).provide();
    SurfaceLabels::provide();
    view! { {children.into_view_once()} }
}

OverlayState is Copy and holds three things every part needs: whether it is open, the trigger, and the surface.

pub struct OverlayState {
    open: Controllable<bool>,
    trigger: NodeRef,
    content: NodeRef,
}

That is why DialogClose, three components down in the footer, closes the dialog without a setter threaded through anything: it calls OverlayState::current() and then state.close(). SurfaceLabels is the same trick for the other direction — the surface publishes two empty NodeRef handles on the way down, and DialogTitle and DialogDescription bind themselves to them on the way up, so the surface can point at a title it did not create.

The composition

DialogContent adds a role, the two label relations and two classes, then hands everything to ModalSurface, which is the whole of what a dialog, an alert dialog, a sheet and a drawer share (crates/zgui-ui/src/overlay/modal.rs):

view! {
    Portal(layer = {at.layer()}) {
        Elevated(at = at) {
            Presence(present = open, surface = {state.content()}) {
                if move || scrim {
                    Scrim()
                } else {}
                DismissableLayer(
                    layer = {OverlayLayer::Modal},
                    class = "zui-overlay-layer",
                    on_dismiss = dismiss,
                    dismiss_on_outside_press = dismiss_on_outside_press,
                    dismiss_on_escape = dismiss_on_escape
                ) {
                    FocusScope(options = {FocusTrapOptions::MODAL}, class = "zui-overlay-scope") {
                        OverlaySurface(
                            state = state,
                            role = role,
                            modal = true,
                            class = {class.get_value()},
                            {..attrs.get_value()}
                        ) {
                            {children.get_value().view()}
                        }
                    }
                }
            }
        }
    }
}

Six layers, and the order is the design. A headless primitive is a component from zgui-ui-primitives that carries one behaviour and no appearance; Primitives covers them properly.

Two details in that block repay reading twice.

The scrim is a sibling of the dismissable layer, not a wrapper around it. A press on the scrim has to count as a press outside the surface. That sibling relationship is the whole of "press the backdrop to close".

Scrim is its own component. It reads use_presence(), and a context is only reachable from a scope below the one that published it. Written inline it would vanish on the frame the dialog closed and take its own fade with it. OverlaySurface is its own component for the same reason.

The elements, the signals and the sheets

The behaviour boxes are told to leave the layout alone, and the depth becomes a z-index (crates/zgui-ui/src/overlay/style.rs):

.zui-overlay-layer, .zui-overlay-scope, .zui-overlay-depth { display: contents; }
.zui-overlay-scrim, .zui-overlay-positioner, .zui-surface { z-index: var(--zui-overlay-depth, 0); }

The depth has to be stated because mount order is the reverse of what is wanted: a surface opened from inside another is built while that one's content is, so it reaches the band first and would otherwise be painted underneath the surface that opened it. SurfaceElevation::raise gives the higher of the two bands and one more depth:

pub fn raise(wanted: OverlayLayer) -> Self {
    match Self::current() {
        Some(under) => Self {
            band: wanted.max(under.band),
            depth: under.depth.saturating_add(1),
        },
        None => Self { band: wanted, depth: 0 },
    }
}

So a select opened inside a dialog rises to the modal band and one step above it. You cannot get a popover to draw under the dialog that opened it.

The surface's motion composes two custom properties rather than one transform, because placement and entry are independent:

.zui-surface {
    transform: var(--zui-surface-place, translate(0px, 0px))
               var(--zui-surface-motion, translateY(0px) scale(1));
}
.zui-surface[data-state="closed"] { opacity: 0; --zui-surface-motion: translateY(-2px) scale(0.98); }

DialogStyle then sets --zui-surface-place: translate(-50%, -50%) to centre the panel on the window. A shared rule writing transform outright would discard that centring.

To replace it yourself: the open-state context, the label handles, the elevation model, the scroll lock, the shared surface sheet and the three behaviours it composes — about 1 600 code lines (crates/zgui-ui/src/dialog/ 296, crates/zgui-ui/src/overlay/ 681, plus Presence 267, DismissableLayer 317 and FocusScope 54 in zgui-ui-primitives, blank and comment lines excluded).

Deconstruction 3: Select

A listbox is a list of options with a keyboard that never leaves the control that opened it. The arrow keys walk the options while the caret stays on the trigger, and the option being walked is named to a reader through active_descendant rather than by being focused. Moving focus into the list would take the caret out of the field.

Select renders no element either. It publishes two contexts:

let surface = OverlayState::new(open, default_open, on_open_change).provide();
Listbox::new(surface, value, default_value, on_change).provide();
view! { {children.into_view_once()} }

Listbox is the registry, and its fields are the whole state of the control (crates/zgui-ui/src/listbox/registry.rs):

pub struct Listbox {
    collection: Collection,                                      // the options, in tree order
    options: RwSignal<BTreeMap<ItemId, ListboxOption>, LocalStorage>,
    active: RwSignal<Option<ItemId>, LocalStorage>,              // the one the arrows are on
    value: Controllable<String>,                                 // the one that is chosen
    filter: RwSignal<String, LocalStorage>,
    labels: ListboxLabels,                                       // what each value reads as
    surface: OverlayState,
    dismisses: bool,
}

Collection is the primitive that keeps registered items in tree order, recomputed on read. Registration order would be wrong, because a keyed list rebuilds only the rows that moved.

The four parts

SelectTrigger renders one control and keeps the keyboard the whole time:

control(
    node_ref = {state.trigger()},
    class = {SelectStyle::CLASS},
    class = "zui-select",
    tabindex = {Focus::Sequential},
    on:click = move |_| {
        if !disabled.get_untracked() {
            let was_open = state.is_open_untracked();
            state.toggle();
            if !was_open && let Some(listbox) = listbox {
                listbox.highlight_chosen();
            }
        }
    },
    on:key_down = on_key_down,
    {..own}, {..attrs}, class = class
) {
    {children.into_view_once()}
    Icon(icon = CHEVRON_DOWN, size = {IconSize::Sm}, class = "zui-select__chevron")
}

Its key listener delegates to the registry and stops the event only when the registry claimed the key:

if let Some(listbox) = listbox
    && listbox.handle(&ev.key)
{
    ev.prevent_default();
    ev.stop_propagation();
}

That is what leaves Tab alone. action_for is the whole key map, and it differs in one place between an open list and a closed one:

let down = Key::Named(NamedKey::ArrowDown);
assert_eq!(action_for(&down, false), Some(ListboxAction::Step(1)));
let enter = Key::Named(NamedKey::Enter);
assert_eq!(action_for(&enter, true), Some(ListboxAction::Choose));
assert_eq!(action_for(&enter, false), None, "a closed list has nothing to choose");

The trigger's semantics are one A11yBinding: role ComboBox, has_popup(Listbox), expanded(…), controls(state.content()) and active_descendant(…) reading the registry's active node. The chevron is turned over in CSS, from the data-state the trigger already carries:

:scope[data-state="open"] .zui-select__chevron { transform: rotate(180deg); }

SelectValue renders a text node whose content is listbox.chosen_text(), or the placeholder, and toggles UiState::PLACEHOLDER_SHOWN. The text comes from the option, not from a prop, so the trigger and the list cannot say different things about one value.

SelectContent returns two views side by side, not one wrapper:

let list = view! {
    AnchoredSurface(state = state, placement = placement, offset = offset,
                    role = {Role::ListBox}, {..own}, {..attrs}, class = class) {
        {children.get_value().view()}
    }
};
let described = view! {
    if move || !state.is_open() {
        ListboxCatalogueOf {{children.get_value().view()}}
    } else {}
};
(list.into_view(), described.into_view())

A wrapper would put a box in the caller's layout, and the list contributes nothing where it is written because it is portalled. The second view is the subtle part: while the list is closed the options are built once more, out of sight, purely so they register what their values read as. Without it a select handed a value would show its placeholder over it until somebody had opened the list and closed it again. The two are never mounted together, so nothing registers twice.

SelectItem renders a box — deliberately not focusable — with data-value, data-state, data-active, data-disabled, UiState::CHECKED, UiState::DISABLED, an A11yBinding of role ListBoxOption, a click that chooses and a pointer_enter that highlights. The highlight is data-active, not :hover and not :focus:

.zui-select__item[data-active="true"] {
    background-color: var(--zui-color-accent);
    color: var(--zui-color-accent-foreground);
}

:focus would match nothing here. The caret never leaves the trigger, so the walked option has to be said out loud.

The list surface

AnchoredSurface is the non-modal twin of ModalSurface: the same behaviours, in the same order, with a positioner innermost and the focus trap optional.

Popper is the primitive that places a floating surface: it measures the anchor, the surface and the window, solves place, then flip, then shift, and writes data-side and data-align for where it actually went. exclude = state.trigger() is load-bearing. Without it a press on the trigger counts as outside the surface, the layer dismisses, the press becomes a click, and the trigger opens again what it had closed.

To replace it yourself: the registry, the key map, the closed-list catalogue, the trigger and the anchored surface — about 1 100 code lines beyond the overlay machinery the dialog already needed (crates/zgui-ui/src/select/ 344 and crates/zgui-ui/src/listbox/ 448, plus Popper at 349 in zgui-ui-primitives, blank and comment lines excluded).

What is settled and what is not

Changing· The whole library Every crate here is at version = "0.1.0" (workspace Cargo.toml). No name in the inventory is promised to keep its spelling. The behaviour below is what the tree does today: 35 test binaries in crates/zgui-ui/tests/, five more in crates/zgui-ui-primitives/tests/, and device-backed cases under crates/zgui-ui/tests/device/ and crates/zgui-ui/tests/painted/.

Nothing in the library is a stub. Three components do less than their name suggests, and each limitation is visible in the source:

Everything else in the inventory is Stable· complete in the sense that matters here: it renders, it is operable from the keyboard listed in crates/zgui-ui/src/lib.rs, and it has tests.

What it costs

Each component calls install_stylesheet(NAME, XStyle::CSS) in its body with a stable name, so one sheet is installed per component type however many instances exist. Installing under a name replaces the sheet and keeps its place in the cascade. The repository asserts this by name: a_second_instance_of_a_component_does_not_install_a_second_sheet (crates/zgui-ui-tokens/tests/theme.rs).

Beyond that, a component costs what its elements cost. There is no library-wide overhead to account for: a Button is one control, and one class toggled on one element is measured at 11.34 µs (docs/performance.md, taken apart in the cost model).

Two costs are worth knowing before you meet them:

• A surface kept mounted while closed, without setting Popper's active prop to false, is placed again on every frame in which anything scrolls. The default composition unmounts instead, so this only applies to a surface of your own.
• SelectContent mounts its option bodies a second time while the list is closed. A side effect written in an option body runs twice, once per mount, never concurrently.

Next