zgui
Component library

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.

Cargo.toml
[dependencies]
zgui = "0.1"
zgui-ui = "0.1"
zgui-ui-tokens = "0.1"
zgui-ui-icons = "0.1"   # only if you use icons directly

Or 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, …) and variants! structs (ButtonVariants, …): import them from zgui_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 one data- attribute per axis (data-variant, data-size, …), and a style! sheet that selects on them.
  • Interaction states are CSS pseudo-classes. zgui-ui has no hovered or pressed signals; :hover, :focus-visible, :active, :disabled, :checked, :indeterminate, :placeholder-shown and :invalid do that job. Hovering a component restyles it without rebuilding anything.
  • Class names are stable. Names such as zui-button are 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.

FamilyComponents
BasicsButton, ButtonGroup, Badge, Label, Kbd, Separator, Skeleton, Spinner, AspectRatio, Avatar
ContentCard, Alert, Empty, Item, Progress
Text fieldsInput, Textarea, InputGroup, InputOtp
Forms and fieldsField, Form
ChoicesCheckbox, Switch, RadioGroup, Toggle, ToggleGroup, Slider, NativeSelect
DisclosureCollapsible, Accordion, Tabs
NavigationMenubar, NavigationMenu, Breadcrumb, Pagination, Sidebar
Scrolling and panelsScrollArea, ResizablePanelGroup, Carousel
DataTable, DataTable, VirtualList, Chart, Calendar, DatePicker
SettingsSettings and its pages, panes, groups and items
ToastsToaster, Toast, use_toaster
Modal surfacesDialog, AlertDialog, Sheet, Drawer
Anchored surfacesPopover, Tooltip, HoverCard
MenusDropdownMenu, ContextMenu, the Menu… parts
ListboxesSelect, 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

CrateDepends onProvides
zgui-uizgui and the three belowthe styled components
zgui-ui-tokenszguidesign tokens as CSS custom properties, ThemeProvider, themes and presets
zgui-ui-iconszgui23 icons and the Icon component
zgui-ui-primitiveszguieight 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 wantDependenciesYou write
finished componentszgui, zgui-ui, zgui-ui-tokenscomponent calls; appearance, keyboard handling and accessibility are done
behaviour onlyzgui, zgui-ui-primitivesyour own elements and sheets, with placement, focus trapping, dismissal, exit timing, roving focus and value ownership provided
nothing from the libraryzguieverything, 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

On this page