Overview
Install the zgui component library, theme it, and find your way around its components, tokens, icons and primitives.
zgui has an optional component library: buttons, fields, menus, dialogs, tables, charts and more, ported from shadcn/ui. It is built only on zgui's public API, so anything a component does, your own code can do too.
Install and render a first screen
Add the crates. List every crate you use in code. zgui-ui depends on the others for its own
use, but that does not make them available to you.
[dependencies]
zgui = "0.1"
zgui-ui = "0.1"
zgui-ui-tokens = "0.1"
zgui-ui-icons = "0.1" # only if you use icons directlyOr run cargo add zgui zgui-ui zgui-ui-tokens. The crates build on stable Rust 1.90 or newer.
Import the preludes. Each prelude exports every component together with its generated props type.
use zgui::prelude::*;
use zgui_ui::prelude::*;
use zgui_ui_tokens::prelude::*;Wrap the interface in a ThemeProvider. Component style sheets are written with
var(--zui-…) tokens, and zgui-ui does not install the tokens itself. Without a provider, or
custom properties you declare yourself, components render unstyled.
#[component]
fn Deploy() -> impl IntoView {
let branch = RwSignal::new_local("main".to_owned());
let migrate = RwSignal::new_local(true);
view! {
ThemeProvider(scheme = ColorScheme::System) {
Card {
CardHeader {
CardTitle {"Deploy storefront"}
CardDescription {"Ships the branch to production."}
}
CardContent {
Input(value = branch, label = "Branch")
Switch(checked = migrate, a11y:label = "Run migrations")
}
CardFooter {
Button(variant = ButtonVariant::Outline) {"Preview"}
Button {"Deploy"}
}
}
}
}
}ColorScheme::System follows the window's light or dark preference. To change colours, radii or
fonts, see Tokens and theming.
A few names are not in the preludes:
- Style types (
ButtonStyle, …) andvariants!structs (ButtonVariants, …): import them fromzgui_ui. - Icons: import each constant you use, for example
use zgui_ui_icons::set::{chevron::CHEVRON_RIGHT, mark::CHECK};.
zgui_ui::prelude does re-export Binding from the primitives crate, because value props take it.
Add classes and attributes
Every component that renders an element takes class and any attr:, on:, a11y: or style:
attribute. They are applied after the component's own, so your values win:
Button(class = "w-full", attr:data-testid = "save", a11y:label = "Save changes") {"Save"}Control a component's value
A component with a value (value, checked, open, …) lets you choose who owns it:
let dark = RwSignal::new_local(false);
view! {
// The switch owns its value, starting from the default.
Switch(default_checked = true, a11y:label = "Notifications")
// The switch reads and writes your signal.
Switch(checked = dark, a11y:label = "Dark mode")
}For full control, pass Binding::controlled(read, write): the control moves only when write
changes read. See Who owns a value.
How components are styled
- Appearance is CSS. Each component has a
variants!table that becomes classes and onedata-attribute per axis (data-variant,data-size, …), and astyle!sheet that selects on them. - Interaction states are CSS pseudo-classes.
zgui-uihas nohoveredorpressedsignals;:hover,:focus-visible,:active,:disabled,:checked,:indeterminate,:placeholder-shownand:invaliddo that job. Hovering a component restyles it without rebuilding anything. - Class names are stable. Names such as
zui-buttonare safe to select on from your own sheet. - Each component type installs one sheet. A hundred buttons share one style sheet.
Component families
Components lists every component with its props.
| Family | Components |
|---|---|
| Basics | Button, ButtonGroup, Badge, Label, Kbd, Separator, Skeleton, Spinner, AspectRatio, Avatar |
| Content | Card, Alert, Empty, Item, Progress |
| Text fields | Input, Textarea, InputGroup, InputOtp |
| Forms and fields | Field, Form |
| Choices | Checkbox, Switch, RadioGroup, Toggle, ToggleGroup, Slider, NativeSelect |
| Disclosure | Collapsible, Accordion, Tabs |
| Navigation | Menubar, NavigationMenu, Breadcrumb, Pagination, Sidebar |
| Scrolling and panels | ScrollArea, ResizablePanelGroup, Carousel |
| Data | Table, DataTable, VirtualList, Chart, Calendar, DatePicker |
| Settings | Settings and its pages, panes, groups and items |
| Toasts | Toaster, Toast, use_toaster |
| Modal surfaces | Dialog, AlertDialog, Sheet, Drawer |
| Anchored surfaces | Popover, Tooltip, HoverCard |
| Menus | DropdownMenu, ContextMenu, the Menu… parts |
| Listboxes | Select, Combobox, Command |
Differences from shadcn/ui
- Not ported: the chat family (attachment, bubble, marker, message), the chip combobox,
PopoverAnchor, select scroll buttons,DirectionProvider(there is no right-to-left layout) and the sidebar's mobile sheet. - There is no
asChild: every part renders its own element.
The four crates
| Crate | Depends on | Provides |
|---|---|---|
zgui-ui | zgui and the three below | the styled components |
zgui-ui-tokens | zgui | design tokens as CSS custom properties, ThemeProvider, themes and presets |
zgui-ui-icons | zgui | 23 icons and the Icon component |
zgui-ui-primitives | zgui | eight headless behaviours: placement, focus trapping, roving focus, exit animations, dismissal, item order and value ownership |
Nothing in zgui depends on these crates. The last three are independent of each other, and
zgui-ui combines them: each component is a composition of primitives, a style sheet written in
tokens, and an icon where needed.
Which crates to use
| You want | Dependencies | You write |
|---|---|---|
| finished components | zgui, zgui-ui, zgui-ui-tokens | component calls; appearance, keyboard handling and accessibility are done |
| behaviour only | zgui, zgui-ui-primitives | your own elements and sheets, with placement, focus trapping, dismissal, exit timing, roving focus and value ownership provided |
| nothing from the library | zgui | everything, from the element vocabulary up |
Tokens and icons also work on their own: zgui-ui-tokens with your own css! sheets is a design
system without zgui-ui, and Icon is a single component over the vector element.
With and without the library
The same two buttons, written both ways:
use zgui::prelude::*;
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 hand-written button already works: Enter and Space press it, because
zgui handles activation, and state:disabled removes it from the focus order and pointer hit
testing and reports it to assistive technology. The library's Button adds six variants, eight
sizes, colours that follow the theme, and one shared style sheet. For a dialog or a select, the
library adds much more: the portal, exit animation, dismissal, focus trap and placement.
Built on the public API
zgui-ui depends only on zgui and its three sibling crates, and each sibling depends only on
zgui. Tests in crates/zgui-ui/tests/downstream.rs (and matching tests in the tokens and
primitives crates) fail the build if a crate gains another dependency or uses an internal crate.
Two more tests there reject a component that keeps its own copy of an interaction state, or that
renders an element without forwarding the caller's attributes.
The one exception in this section is Devtools, an inspector that reads framework internals.
Next
Components
Every component, its props, variants and behaviour.
Tokens and theming
The 141 tokens, ThemeProvider, themes as CSS, presets and run-time switching.
Primitives
The eight headless behaviours, and using them with your own CSS.
Icons
The 23 icons, sizing, colouring, and adding your own.
Devtools
The inspector: opening it and what each tab shows.
Measurements
Measure your own application with frame probes, counters and the latency trace, then the scenarios, gates and benches behind zgui's own numbers.
Tokens and theming
Theme the zgui component library with ThemeProvider, light and dark schemes, themes written as CSS, presets and run-time switching, plus a reference of all 141 design tokens.