The component library

zgui ships a component library: buttons, fields, menus, dialogs, tables and the rest. No page of this documentation before this one uses it, and no application has to. This page says what the four crates are, shows that they are ordinary consumers of the public API, and writes the same small interface twice — once with the library and once from the element vocabulary — so that what the library buys is visible.

It assumes the guide.

The four crates

The first three know nothing about each other. zgui-ui is the only crate that joins them: a component of its own is a primitive composition, plus a sheet written in tokens, plus an icon where one is wanted.

None of the four is reachable through zgui. Each is a separate line in a Cargo.toml, and a program that names none of them compiles none of them.

Layer L8, and no privileged access

Architecture overview puts these crates on L8, the product layer: crates that consume the public API and are consumed by nothing. For these four the claim is checked rather than asserted. Here are the whole dependency sections of the four manifests:

[dependencies]
zgui = { path = "../zgui", version = "0.1.0" }

[dependencies]
zgui = { path = "../zgui", version = "0.1.0" }
zgui-ui-icons = { path = "../zgui-ui-icons", version = "0.1.0" }
zgui-ui-primitives = { path = "../zgui-ui-primitives", version = "0.1.0" }
zgui-ui-tokens = { path = "../zgui-ui-tokens", version = "0.1.0" }

Three tests hold that shape in place:

zgui-ui-tokens carries the second test too. zgui-ui-icons is covered by its manifest alone; its sources name no internal crate either.

The crate documentation of zgui-ui gives the reason, and calls it a constraint rather than a boast:

if a component needed something the framework does not expose, an application would need it too, so the hole gets fixed rather than reached past.

The dependency rule covers [dependencies] only. The dev-dependencies of zgui-ui do reach lower — zgui-platform-headless, zgui-render-wgpu and a vector rasteriser — because the library's own tests read pixels back off a real graphics device. Nothing an application links carries them.

What you give up by leaving it out

Work, not capability. There is no behaviour in the library that the public API does not also give an application, because the library has nothing else to build from.

The evidence that this is a real choice is in the repository. crates/zgui-examples depends on zgui and nothing else, and its manifest says why:

These are ordinary applications, and an application depends on the umbrella crate and nothing else: if a view, a component, a style sheet or an entry point needed anything further, the examples here would not compile, which is the point.

Six worked applications sit under examples/ — counter.rs, todo.rs, styled.rs, tally.rs, resize.rs and vector.rs — and none of them names zgui-ui.

How to depend on it

[dependencies]
zgui = { path = "../zgui/crates/zgui" }
zgui-ui = { path = "../zgui/crates/zgui-ui" }
zgui-ui-tokens = { path = "../zgui/crates/zgui-ui-tokens" }
zgui-ui-icons = { path = "../zgui/crates/zgui-ui-icons" }   # only if you name an icon yourself

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

view! {
    ThemeProvider(scheme = ColorScheme::System) {
        Card {
            CardHeader {CardTitle {"Settings"}}
            CardContent {Button {"Save"}}
        }
    }
}

The icon constants are not in zgui_ui_icons::prelude. Name the ones you draw: use zgui_ui_icons::set::{chevron::CHEVRON_RIGHT, mark::CHECK};

Three ways to use the stack

The middle row is a real position, not a compromise. zgui-ui-primitives depends on zgui alone, ships its own prelude, and carries a complete popover composition as a doctest. Primitives works through it.

Tokens and icons are separable in the same way. zgui-ui-tokens plus css! is a design system with no zgui-ui in the dependency graph, and Icon is one component over the vector element.

Three rules every styled component obeys

Appearance is a variants! table and a style! sheet. The table lowers to a class list and one data- attribute per axis; 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 engine. There is no hovered, focused or pressed signal anywhere in zgui-ui. A test refuses one by name. :hover, :focus-visible, :active, :disabled, :checked, :indeterminate, :placeholder-shown and :invalid are states the style engine already knows, and a second copy would be a second answer that disagrees on the frame the pointer leaves.

A caller can always add to an element. Every component that renders an element takes class: Classes and #[prop(attrs)] attrs: Attrs, and merges both after its own, so the caller wins. A test walks the sources and fails any component that renders an element and forwards no bundle.

The inventory

Every public component of zgui-ui, by module. Props are on Components.

overlay, listbox and support are absent from the prelude. Name them at their module path — zgui_ui::overlay, zgui_ui::listbox, zgui_ui::support. They are published because a surface of your own needs them.

The same interface, twice

Two buttons in a row. One is outlined, the other goes disabled while a save is in flight.

use zgui::prelude::*;
use zgui::reactive::RwSignal;
use zgui::{component, view};
use zgui_ui::prelude::*;
use zgui_ui_tokens::prelude::*;

#[component]
fn SaveBar() -> impl IntoView {
    let saving = RwSignal::new_local(false);

    view! {
        ThemeProvider(scheme = ColorScheme::System) {
            row {
                Button(variant = ButtonVariant::Outline) {"Cancel"}
                Button(disabled = saving, on:click = move |_| saving.set(true)) {"Save"}
            }
        }
    }
}

The second version is a working button. Enter and Space press it, because activating what has focus is the framework's behaviour and arrives as an ordinary click. disabled takes it out of the focus order, out of pointer reach, and tells a reader — one write, four consumers. zgui-ui's own Button handles none of those things either, for the same reasons.

What the library's Button adds to it:

That is the whole difference for a button. For a dialog or a select the difference is larger — a portal, an exit animation, a dismissal layer, a focus trap and a placement solver, in that order — but it is the same kind of difference. Components takes three of them apart.

What it costs

Nothing structural. A component is a function that installs a sheet and returns elements, so a frame that touches one costs what the cost model says the change costs, and no more.

Two consequences worth stating:

• One sheet per component type, however many instances. Each component calls install_stylesheet with a stable name in its body. Installing a name that is already installed replaces the text and keeps its place in the cascade, so a hundred buttons install one sheet. Asserted by crates/zgui-ui-tokens/tests/theme.rs::a_second_instance_of_a_component_does_not_install_a_second_sheet.
• A pointer crossing a component is a restyle, not a rebuild. Because no component keeps an interaction state in a signal, hovering one is the two-element restyle the cost model measures, and nothing in Rust runs at all.

Next