zgui
Component library

Components

Reference for every zgui-ui component, grouped by family, with props, defaults, variants and keyboard behaviour.

Every public component in zgui-ui, grouped by family, with its props and defaults. For installation and theming, see the overview. All names are in zgui_ui::prelude unless a section says otherwise.

Props on every component

Every component that renders an element also takes these props. The tables below leave them out.

PropTypeEffect
classClassesclasses merged after the component's own
attribute bundleAttrs, #[prop(attrs)]any attr:, on:, a11y:, style: the caller writes, applied after the component's own
childrenChildren or ChildrenFnthe content

The caller's values are applied last, so they win:

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

How to read the tables

  • Signal<T> means Signal<T, LocalStorage>, declared into, so a plain T works too.
  • Option<T> props take a T; write label = "Name", not label = Some(…).
  • Binding<T> is a value prop; see Who owns a value.
  • In the Children column, yes means the component takes children and opt means they are optional. fn means ChildrenFn: the content is built again each time a surface opens. — means the component takes no children.

Who owns a value

A component with a value takes three props: the value (value, checked, pressed, open, index or page), a default_…, and an on_…change observer. What you pass as the value decides who owns it.

You passOwner
nothingthe component, starting from default_…
an RwSignal<T, LocalStorage>shared: the component reads it and writes it back
Binding::controlled(read, write)you: the control moves only when write changes read

Passing a read-only Signal is a compile error. The observer runs in all three cases, after the value is written. Writes that arrive after the component's scope is disposed are ignored.

on_change, on_open_change, on_page_change and on_select are props, not event listeners. Write on_change = f, never on:change = f.

Basics

ComponentPropsChildren
Buttonvariant: ButtonVariant = Default, size: ButtonSize = Md, disabled: Signal<bool> = false, node_ref: Option<NodeRef>yes
ButtonGrouporientation: ButtonGroupOrientation = Horizontalyes
ButtonGroupText—yes
ButtonGroupSeparator——
Badgevariant: BadgeVariant = Defaultyes
Labelcontrol: Option<NodeRef>, node_ref: Option<NodeRef>yes
Kbd, KbdGroup—yes
Separatororientation: SeparatorOrientation = Horizontal, decorative: bool = true—
Skeleton——
Spinnerlabel: String = "Loading"—
AspectRatioratio: f32 = 1.0yes
Avatarsrc: Signal<Option<String>> = None, size: AvatarSize = Md, label: Option<String>yes
AvatarImagesrc: Signal<Option<String>> = None—
AvatarFallback, AvatarGroupCount—yes
AvatarBadgelabel: Option<String>opt
AvatarGroupsize: AvatarSize = Mdyes
EnumValues
ButtonVariantDefault, Secondary, Destructive, Outline, Ghost, Link
ButtonSizeXs, Sm, Md, Lg, Icon, IconXs, IconSm, IconLg (the Icon… sizes are square)
BadgeVariantDefault, Secondary, Destructive, Success, Warning, Outline, Ghost, Link
AvatarSizeSm, Md, Lg
ButtonGroupOrientation, SeparatorOrientationHorizontal, Vertical
  • Enter and Space press a Button as an ordinary click, so one on:click serves pointer, keyboard and accessibility actions.
  • disabled removes the button from the focus order and from pointer hit testing, and tells assistive technology.
  • Outline buttons have no fill at rest and no shadow; they take the colour of the surface behind them and tint on hover.
  • Spinner is a status region named by label. Use Progress when the amount done is known.

Content

ComponentPropsChildren
Card—yes
CardHeader, CardTitle, CardDescription, CardAction, CardContent, CardFooter—yes
Alertvariant: AlertVariant = Default, live: bool = true, icon: bool = trueyes
AlertTitle, AlertDescription—yes
Empty, EmptyHeader, EmptyTitle, EmptyDescription, EmptyContent—yes
EmptyMediavariant: EmptyMediaVariant = Defaultyes
Itemvariant: ItemVariant = Default, size: ItemSize = Mdyes
ItemGroup, ItemHeader, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemFooter—yes
ItemMediavariant: ItemMediaVariant = Defaultyes
ItemSeparator——
Progressvalue: Signal<Option<f64>> = None, max: f64 = 100.0, label: Option<String>—
EnumValues
AlertVariantDefault, Destructive
EmptyMediaVariantDefault, Icon
ItemVariantDefault, Outline, Muted
ItemSizeMd, Sm
ItemMediaVariantDefault, Icon, Image
  • Alert(live = true) is announced through a polite live region; live = false makes it a plain group.
  • Progress(value = None) is indeterminate.

Text fields

ComponentPropsChildren
Input, Textareavalue: Binding<String>, default_value: Option<String>, on_change, placeholder: Option<String>, disabled, read_only, required, invalid (all Signal<bool> = false), label: Option<String>, labelled_by: Option<NodeRef>, node_ref—
InputGroupdisabled, invalid (Signal<bool> = false)yes
InputGroupAddonalign: InputGroupAddonAlign = InlineStartyes
InputGroupText—yes
InputGroupButtonvariant: ButtonVariant = Ghost, size: InputGroupButtonSize = Xs, disabledyes
InputGroupInput, InputGroupTextareavalue: Binding<String>, default_value: String = "", on_change, placeholder: String = "", disabled, invalid, node_ref—
InputOtpvalue: Binding<String>, default_value, on_change, on_complete: Option<UnsyncCallback<String>>, length: usize = 6, groups: Option<Vec<usize>>, disabled, invalid, label, labelled_by, node_ref—
InputOtpGroup—yes
InputOtpSeparator——

InputGroupAddonAlign is InlineStart, InlineEnd, BlockStart, BlockEnd. InputGroupButtonSize is Xs, Sm, IconXs, IconSm.

  • The text is held by zgui's editing model on the field element, not by the component.
  • A read_only field refuses every edit and draws no caret, but its text can still be selected and copied with the pointer and the keyboard.
  • InputOtp draws its own boxes. groups = vec![3, 3] splits six boxes into two runs with a dash between them. on_complete runs when every box is filled.

Forms and fields

ComponentPropsChildren
Fieldorientation: FieldOrientation = Vertical, invalid, disabled (Signal<bool> = false)yes
FieldSet, FieldGroup, FieldContent, FieldLabel, FieldTitle, FieldDescription, FieldError—yes
FieldLegendvariant: FieldLegendVariant = Legendyes
FieldSeparator—opt
Formon_submit: Option<UnsyncCallback<()>>, label, submit_on_enter: bool = true, node_refyes
FormFieldname: String, validate: Option<Validator>yes
FormItem, FormLabel, FormDescription—yes
FormMessage—opt
FormSubmitvariant: ButtonVariant = Default, size: ButtonSize = Md, disabled, node_refyes

FieldOrientation is Vertical, Horizontal. FieldLegendVariant is Legend, Label.

  • Field only handles layout and labelling. Form adds validation and submission: Enter submits, and the first invalid field receives focus.
  • use_form_field() returns the enclosing FormField's context.

Choices

ComponentPropsChildren
Checkboxchecked: Binding<Checked>, default_checked: Checked = No, on_change, disabled, invalid, labelled_by, node_ref—
Switchchecked: Binding<bool>, default_checked: bool = false, on_change, disabled, size: SwitchSize = Md, labelled_by, node_ref—
RadioGroupvalue: Binding<String>, default_value, on_change, disabled, orientation: Orientation = Vertical, labelyes
RadioGroupItemvalue: String, disabled, invalid, label, labelled_by, node_ref—
Togglepressed: Binding<bool>, default_pressed: bool = false, on_change, variant: ToggleVariant = Default, size: ToggleSize = Md, disabled, label, node_refyes
ToggleGroupvalue: Binding<Vec<String>>, default_value, on_change, selection: ToggleSelection = Single, variant: ToggleVariant = Default, size: ToggleSize = Md, spacing: f32 = 0.0, disabled, orientation: Orientation = Horizontal, labelyes
ToggleGroupItemvalue: String, variant: Option<ToggleVariant>, size: Option<ToggleSize>, disabled, label, node_refyes
Slidervalue: Binding<f64>, default_value: f64 = 0.0, on_change, min: f64 = 0.0, max: f64 = 100.0, step: f64 = 1.0, disabled, label, labelled_by, node_ref—
NativeSelectvalue: Binding<String>, default_value, on_change, placeholder, size: NativeSelectSize = Md, disabled, invalid, node_reffn
NativeSelectOptionvalue: String, text: Option<String>, disabled: bool = falseyes
NativeSelectOptGrouplabel: Stringyes
EnumValues
CheckedNo, Yes, Mixed (Mixed matches :indeterminate)
SwitchSize, NativeSelectSizeSm, Md
ToggleVariantDefault, Outline
ToggleSizeSm, Md, Lg
ToggleSelectionSingle, Multiple
OrientationHorizontal, Vertical, Both (from zgui-ui-primitives)
  • RadioGroup and ToggleGroup are one tab stop; the arrow keys move between items. In a radio group the arrow keys also select.
  • Slider: the arrow keys move one step, Page Up/Down move ten steps, Home/End go to the ends.
  • ToggleGroupItem uses the group's variant and size unless it sets its own. spacing is the gap between items in spacing steps; at 0.0 the items join into one strip.
  • Outlined toggles and all fields (input, select, checkbox, radio) have no fill of their own.

Disclosure

ComponentPropsChildren
Collapsibleopen: Binding<bool>, default_open: bool = false, on_open_change, disabled, node_refyes
CollapsibleTrigger, CollapsibleContent—yes
Accordionvalue: Binding<Vec<String>>, default_value, on_change, selection: AccordionSelection = Single, collapsible: bool = true, disabledyes
AccordionItemvalue: String, disabledyes
AccordionTriggerlevel: usize = 3yes
AccordionContent—yes
Tabsvalue: Binding<String>, default_value: String = "", on_change, orientation: Orientation = Horizontal, activation: TabsActivation = Automatic, label, node_refyes
TabsListvariant: TabsListVariant = Default, labelyes
TabsTriggervalue: String, disabledyes
TabsContentvalue: String, keep_mounted: bool = falsefn

AccordionSelection is Single, Multiple. TabsActivation is Automatic, Manual. TabsListVariant is Default, Line.

  • AccordionTrigger(level) sets the heading level announced to screen readers.
  • With TabsActivation::Manual, the arrow keys move focus and Enter or Space shows the panel.
  • TabsContent builds its content only while its tab is selected. Set keep_mounted to keep input or scroll state in hidden panels.
ComponentPropsChildren
Menubarlabel: Option<String>yes
MenubarMenuvalue: Stringyes
MenubarTrigger, MenubarLabel, MenubarShortcut—yes
MenubarContentplacement: Placement = Placement::BOTTOMfn
MenubarItemon_select, disabled, shortcut: Option<String>yes
MenubarCheckboxItemchecked: Binding<bool>, default_checked: bool = false, on_change, disabled, close_on_select: bool = falseyes
MenubarRadioItemvalue: String, disabled, close_on_select: bool = trueyes
MenubarSeparator——
NavigationMenuvalue: Binding<String>, default_value: String = "", on_change, label: String = "Main", node_refyes
NavigationMenuList, NavigationMenuTrigger—yes
NavigationMenuItemvalue: Stringyes
NavigationMenuContent—fn
NavigationMenuLinkactive: Signal<bool> = falseyes
NavigationMenuIndicator——
Breadcrumblabel: String = "Breadcrumb"yes
BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage—yes
BreadcrumbSeparator—opt
BreadcrumbEllipsislabel: String = "More"—
Paginationlabel: String = "Pagination"yes
PaginationContent, PaginationItem—yes
PaginationLinkpage: Option<usize>, current: Signal<bool> = falseyes
PaginationPreviousdisabled, label: String = "Previous page", text: String = "Previous"—
PaginationNextdisabled, label: String = "Next page", text: String = "Next"—
PaginationEllipsislabel: String = "More pages"—

MenubarGroup and MenubarRadioGroup are MenuGroup and MenuRadioGroup (see Aliases); submenus inside a menubar use MenuSub.

zgui_ui::pagination::page_window(current, pages, slots) returns the Vec<Slot> to draw, where Slot is Page(usize) or Gap.

ComponentPropsChildren
SidebarProvideropen: Binding<bool>, default_open: bool = true, on_open_change, side: SidebarSide = Left, collapse: SidebarCollapse = Icon, variant: SidebarVariant = Sidebar, shortcut: bool = trueyes
Sidebarlabel: String = "Sidebar", side, collapsible, variant (each Option, overriding the provider)opt
SidebarHeader, SidebarContent, SidebarFooter, SidebarInset—yes
SidebarGroup, SidebarGroupLabel, SidebarGroupContent—yes
SidebarGroupActionlabel, disabledyes
SidebarInputvalue: Binding<String>, default_value, on_change, placeholder, disabled, labelled_by, node_ref—
SidebarSeparator——
SidebarMenu, SidebarMenuItem, SidebarMenuSub, SidebarMenuSubItem, SidebarMenuBadge—yes
SidebarMenuButtonactive: Signal<bool> = false, disabled, size: SidebarMenuSize = Default, variant: SidebarMenuVariant = Default, tooltip: Option<String>, labelyes
SidebarMenuActionlabel, disabled, hover_only: bool = falseyes
SidebarMenuSubButtonactive, disabled, size: SidebarSubSize = Md, labelyes
SidebarMenuSkeletonicon: bool = false, width: Option<u8>—
SidebarTrigger, SidebarRaillabel: String = "Toggle sidebar"—
EnumValues
SidebarSideLeft, Right
SidebarCollapseIcon, Offcanvas, None
SidebarVariantSidebar, Floating, Inset
SidebarMenuSizeDefault, Sm, Lg
SidebarMenuVariantDefault, Outline
SidebarSubSizeMd, Sm
  • With shortcut on, the primary modifier + B (Cmd on macOS, Ctrl elsewhere) collapses and expands the sidebar from anywhere in the window.
  • SidebarMenuButton(tooltip) is shown beside the button while the sidebar is collapsed to icons.
  • The sidebar is a desktop panel at every width; there is no mobile sheet.

Scrolling and panels

ComponentPropsChildren
ScrollAreaorientation: Orientation = Vertical, label, node_refyes
ScrollBarorientation: Orientation = Vertical—
ResizablePanelGroupdirection: Orientation = Horizontal, on_change: Option<UnsyncCallback<Vec<f64>>>, label, node_refyes
ResizablePaneldefault_size: f64 = 0.0, min_size: f64 = 0.0, max_size: f64 = 100.0, min_pixels: f64 = 0.0, label, node_refyes
ResizableHandlestep: f64 = 5.0, with_handle: bool = false, label—
Carouselindex: Binding<usize>, default_index: usize = 0, on_change, orientation: Orientation = Horizontal, wrap: bool = false, label, node_refyes
CarouselContent, CarouselItem—yes
CarouselPreviouslabel: String = "Previous slide"—
CarouselNextlabel: String = "Next slide"—
  • ScrollBar draws nothing itself. zgui draws the bar (a transparent track and a slim thumb); ScrollBar adds the accessible role, a focus stop and the keys: arrows scroll by a line, Page Up/Down by a screen, Home/End to the ends.
  • Panel sizes are percentages of the group, applied as each panel's flex-basis. When the declared sizes do not add up to 100, the group distributes the rest.
  • min_pixels is a minimum size in CSS pixels. It is converted to a percentage whenever the group is resized, and the larger of min_pixels and min_size applies.
  • When a panel is removed, the remaining panels are resized from their declared sizes.
  • ResizableHandle: the arrow keys move it by step percentage points, Home/End go to the panel's minimum and maximum, and Enter collapses the panel before it or restores it.

Data

ComponentPropsChildren
Tablecolumns: Signal<String> = "1fr", interactive: bool = false, sticky_header: bool = false, rows: Option<Signal<usize>>, columns_count: Option<Signal<usize>>, label, labelled_by, node_refyes
TableCaption—yes
TableHeader, TableBody, TableFooternode_refyes
TableRowindex: Option<Signal<usize>>, selected: Option<Signal<bool>>, node_refyes
TableHeadindex, align: CellAlign = Start, sort: Signal<ColumnSort> = None, node_refyes
TableCellindex, align: CellAlign = Start, header: bool = false, node_refyes
DataTable<T, I>rows: Signal<Vec<T>>, columns: Vec<Column<T>>, row_id: I, selectable: bool = false, filterable: bool = false, row_match: Option<RowMatch<T>>, page_size: usize = 0, virtualized: bool = false, row_size: f32 = 40.0, body_height: Option<f32>, resizable: bool = true, empty: String = "No results.", label, on_model: Option<UnsyncCallback<DataModel<T>>>, node_ref—
ColumnResizerheader: NodeRef, label: String, on_resize: UnsyncCallback<f32>, step: f32 = 8.0, edge: GripEdge = Trailing, on_reset: Option<UnsyncCallback<()>>—
VirtualList<V, F>count: Signal<usize>, row_size: Signal<f32> = 32.0, overscan: usize = 4, row: F (Fn(usize) -> V), label, node_ref—

CellAlign is Start, Center, End. ColumnSort is None, Ascending, Descending. GripEdge is Trailing, Leading.

Table is presentational: one CSS grid with table roles. DataTable is driven by a model that sorts, filters, selects, pages and virtualises.

let columns = vec![
    Column::new("item", "Item", |line: &Line| line.item.clone())
        .sortable_by(|a: &Line, b: &Line| a.item.cmp(&b.item)),
    Column::new("cost", "Cost", |line: &Line| format!("{}p", line.pence))
        .aligned(CellAlign::End)
        .sized("120px"),
];
view! {
    DataTable(
        rows = lines,
        columns = columns,
        row_id = |line: &Line| line.id.to_string(),
        label = "Invoice lines",
        selectable = true,
        filterable = true,
        page_size = 25_usize
    )
}
  • on_model gives you the DataModel<T>: set_sort, set_filter, go_to_page, set_page_size, selection, set_all_selected and more. set_sort(state) restores a saved SortState; a state naming a missing or unsortable column is refused.
  • virtualized = true builds only the visible rows, so row_size must match the row's styled height. Paging and virtualisation are alternatives; setting both virtualises.
  • ColumnResizer reports the new width through on_resize instead of applying it. The arrow keys move it by step pixels. edge = Leading puts the grip on the leading edge, for a column to the right of a flexible one. A double click calls on_reset, where you can restore the column's default width.
  • VirtualList builds the visible rows plus overscan on each side. row_size may be a signal; changing it moves the rows and the scroll extent together. The extent is capped at zgui_ui::virtualize::MAX_EXTENT (4,000,000 CSS pixels); beyond that the scrollbar maps rows proportionally, so use VirtualWindow::offset_of(index) to scroll a row into view.

Charts and dates

ComponentPropsChildren
Chartseries: Signal<Vec<Series>>, kind: ChartKind = Bar, width: f64 = 480.0, height: f64 = 240.0, ticks: usize = 5, legend: bool = true, tooltip: bool = true, indicator: ChartIndicator = Dot, label, node_ref—
ChartContainernode_refyes
ChartTooltipContentlabel, entries: Vec<ChartEntry>, indicator: ChartIndicator = Dot, hide_label: bool = false, hide_indicator: bool = false—
ChartLegendContententries: Vec<LegendEntry>, align: LegendAlign = Bottom, label: String = "Series"—
Calendarvalue: Binding<Option<Date>>, default_value, on_change, mode: CalendarMode = Single, range: Binding<Option<DateRange>>, default_range, on_range_change, months: usize = 1, default_month: Option<Date>, today: Option<Date>, available: Option<DateFilter>, disabled, label, node_ref—
CalendarDaydate: Date, in_month: bool, today: bool, unavailable: bool = false, on_choose: UnsyncCallback<Date>—
DatePickerCalendar's props except default_month, plus open: Binding<bool>, on_open_change, placeholder: String = "Pick a date", labelled_by—

ChartKind is Bar, Line, Area. ChartIndicator is Dot, Line, Dashed. LegendAlign is Bottom, Top. CalendarMode is Single, Range.

  • Each chart mark is a focusable element with an accessible name, so Tab moves through the data. Series colours come from --zui-color-chart-1 … -5.
  • A chart is sized by width and height in CSS pixels; it does not resize to fit its box.
  • Calendar(mode = CalendarMode::Range) reads and writes range instead of value. months shows several months side by side.

Settings

ComponentPropsChildren
Settingspage: Binding<String>, default_page: String = "", on_page_change, label, node_refyes
SettingsPageslabelyes
SettingsPagevalue: String, disabledyes
SettingsPanevalue: String, keep_mounted: bool = falsefn
SettingsGroup, SettingsGroupLabel, SettingsGroupDescription—yes
SettingsItemlabel: String, description: Option<String>, disabled, control: Option<NodeRef>yes
Settings(default_page = "appearance", label = "Preferences") {
    SettingsPages {
        SettingsPage(value = "appearance") {"Appearance"}
        SettingsPage(value = "terminal") {"Terminal"}
    }
    SettingsPane(value = "appearance") {
        SettingsGroup {
            SettingsGroupLabel {"Theme"}
            SettingsItem(label = "Dark mode") {
                Switch(checked = dark, {..use_settings_item_attrs()})
            }
        }
    }
}
  • The page list is a vertical tab list: Up/Down wrap, Home/End go to the ends, and disabled pages are skipped. Left and right arrows are left to the controls in the pane.
  • Spread {..use_settings_item_attrs()} on the control so its label and description are announced.
  • Pass the same NodeRef to SettingsItem(control) and to the control's node_ref so that pressing the label focuses the control.
  • An item's disabled fades the row and blocks the pointer. Disable the control too, so assistive technology reports the same state.

Toasts

ComponentPropsChildren
Toastercorner: ToastCorner = BottomRight, limit: usize = 3, label: String = "Notifications", dismiss_label: String = "Dismiss"yes
ToastItemqueued: Queued, dismiss_label: String = "Dismiss"—

Wrap your interface in a Toaster; it provides the toast queue as a context. Anything inside it gets the queue with use_toaster():

let toasts = use_toaster();
view! {
    Button(on:click = move |_| {
        if let Some(toasts) = toasts {
            toasts.push(
                Toast::new("Project deleted")
                    .kind(ToastKind::Success)
                    .action("Undo", move || restore()),
            );
        }
    }) {"Delete"}
}
Toast builderEffect
Toast::new(title)a toast with a title
.description(text)a second line
.kind(ToastKind)Normal, Success, Info, Warning, Error, Loading; sets the icon and how urgently it is announced
.duration(d), .persistent()how long it stays (default Toast::DEFAULT_DURATION, 4 s), or until dismissed
.action(label, f)a button that runs f
.destructive_action(label, f)the same, drawn in the destructive fill (ToastActionTone::Destructive)
.cancel(label, f)a button that dismisses the toast
  • push returns a ToastId. replace(id, toast) shows a new message in the same place and restarts its timer; use it to report progress in one toast. dismiss(id) and clear() remove toasts with their exit animation.
  • Beyond limit, the oldest toasts are removed. Toasts are drawn on the toast overlay band, above everything else. ToastCorner is BottomRight, BottomLeft, TopRight, TopLeft.
ComponentPropsChildren
Dialog, AlertDialog, Sheet, Draweropen: Binding<bool>, default_open: bool = false, on_open_changeyes
DialogContentdismiss_on_outside_press: Signal<bool> = true, dismiss_on_escape: Signal<bool> = true, dismiss_control: bool = truefn
AlertDialogContentdismiss_on_escape: Signal<bool> = true, size: AlertDialogSize = Defaultfn
SheetContentside: SheetSide = Right, dismiss_on_outside_press, dismiss_on_escape, dismiss_control: bool = truefn
DrawerContentdirection: SheetSide = Bottom, handle: bool = true, dismiss_on_outside_press, dismiss_on_escapefn
DialogTriggervariant: ButtonVariant = Default, size: ButtonSize = Mdyes
DialogClosevariant: ButtonVariant = Ghost, size: ButtonSize = Mdyes
DialogHeader, DialogTitle, DialogDescription—yes
DialogFooterclose_control: bool = falseyes
DialogDismiss, SheetDismiss, DrawerHandle——
SheetHeader, SheetTitle, SheetDescription, SheetFooter—yes
AlertDialogTriggervariant = Default, size = Mdyes
AlertDialogActionvariant = Default, size = Md, node_refyes
AlertDialogCancelvariant = Outline, size = Mdyes
AlertDialogMedia—yes

SheetSide is Top, Right, Bottom, Left. AlertDialogSize is Default, Sm (narrow, centred, answers sharing the width).

  • Content is built only while open, and stays mounted until its exit animation ends.
  • Escape closes the surface and Tab stays inside it. On close, focus returns to the trigger unless something else has taken focus in the meantime.
  • DialogTitle labels the surface and DialogDescription describes it. A dialog with no title is announced as unlabelled.
  • dismiss_control draws a close button in the surface's corner (DialogDismiss). DialogFooter(close_control = true) adds a "Close" button to the footer.
  • A press outside an alert dialog does not close it, so a stray click cannot answer it. Escape still closes it.
  • On AlertDialogAction, AlertDialogCancel and DialogClose, your on:click runs before the surface closes. AlertDialogAction(node_ref) records the button so you can focus it.
  • Drawer has no drag-to-dismiss gesture; DrawerHandle is decorative.

Anchored surfaces

ComponentPropsChildren
Popoveropen: Binding<bool>, default_open: bool = false, on_open_changeyes
PopoverContentplacement: Signal<Placement> = Placement::BOTTOM, offset: f32 = 4.0, dismiss_on_outside_press, dismiss_on_escapefn
PopoverHeader, PopoverTitle, PopoverDescription—yes
Tooltipopen, default_open, on_open_change, delay: Option<Duration>, close_delay: Option<Duration>yes
TooltipProviderdelay: Duration = 0 ms, close_delay: Duration = 150 msyes
TooltipTrigger—yes
TooltipContentplacement = Placement::TOP, offset: f32 = tooltip::DEFAULT_OFFSET, arrow: bool = truefn
TooltipArrow——
HoverCardopen, default_open, on_open_change, delay: Duration = 700 ms, close_delay: Duration = 300 msyes
HoverCardTrigger—yes
HoverCardContentplacement = Placement::BOTTOM, offset: f32 = 4.0fn

Placement, Side and Align come from zgui-ui-primitives. A surface flips to the other side when it does not fit, and slides along the edge to stay on screen.

Tooltips

  • A tooltip opens on hover, or when its trigger receives focus from the keyboard. Focus from a pointer press, from code or from an opening focus trap does not show it. Escape hides it without moving focus.
  • A tooltip describes a control and cannot contain interactive content. Use HoverCard or Popover for that.
  • TooltipProvider sets the delays for every tooltip inside it; a Tooltip's own delay wins. Under one provider only one tooltip shows at a time: moving to the next trigger opens it at once and drops the previous one without an exit animation.
  • The arrow points at the centre of the trigger. DEFAULT_OFFSET leaves room for it plus a 4 px gap; with the arrow on, a smaller offset is increased to fit the arrow. Set arrow = false to drop it, or place TooltipArrow yourself.
  • Colours come from --zui-color-tooltip, -tooltip-foreground and -tooltip-border. By default a tooltip inverts the page.
ComponentPropsChildren
DropdownMenu, ContextMenu, MenuSubopen: Binding<bool>, default_open: bool = false, on_open_changeyes
DropdownMenuTriggervariant: ButtonVariant = Default, size: ButtonSize = Md, disabledyes
DropdownMenuContentplacement = Placement::new(Side::Bottom, Align::Start), offset: f32 = 4.0fn
ContextMenuTrigger—yes
ContextMenuContentplacement = Placement::new(Side::Bottom, Align::Start)fn
MenuItemdisabled, destructive: bool = false, inset: bool = false, close_on_select: bool = true, on_select, shortcut: Option<String>yes
MenuCheckboxItemchecked: Binding<bool>, default_checked: bool = false, on_change, disabled, close_on_select: bool = trueyes
MenuRadioGroupvalue: Binding<String>, default_value, on_change, labelyes
MenuRadioItemvalue: String, disabled, close_on_select: bool = trueyes
MenuGrouplabel: Option<String>yes
MenuLabelinset: bool = falseyes
MenuShortcut—yes
MenuSeparator——
MenuSubTriggerdisabled, inset: bool = falseyes
MenuSubContentplacement = Placement::new(Side::Right, Align::Start)fn

A dropdown menu and a context menu differ only in what opens them. Both are filled with the Menu… parts.

  • The arrow keys move through the items and wrap; typing a letter jumps to a matching item; → opens a submenu, and ← closes it and returns focus to its trigger. ↓/↑ on a DropdownMenuTrigger also open it.
  • A disabled DropdownMenuTrigger does not open and leaves the focus order.
  • A submenu opens when the pointer rests on its trigger for menu::sub::OPEN_DELAY (120 ms), or immediately when the trigger is pressed.
  • ContextMenuTrigger opens at the pointer on a right-click or press-and-hold. To open it from the keyboard, call ContextMenuPlace::current() inside the trigger and open_at(point) with a point in window CSS pixels, such as the corner of the focused row.
  • MenuItem(inset = true) lines a plain item up with the labels of checkbox and radio items.

Listboxes

ComponentPropsChildren
Select, Comboboxvalue: Binding<String>, default_value, on_change, open: Binding<bool>, default_open, on_open_changeyes
SelectTriggerdisabled, invalid, size: SelectTriggerSize = Md, label, labelled_byyes
SelectValueplaceholder: Option<String>—
SelectContent, ComboboxContentplacement = Placement::new(Side::Bottom, Align::Start), offset: f32 = 4.0fn
SelectItemvalue: String, text: Option<String>, disabledyes
ComboboxInputplaceholder, disabled, label, labelled_by—
ComboboxItemvalue: String, text: Option<String>, disabled, on_select: Option<UnsyncCallback<()>>fn
ComboboxEmpty—fn
Commandvalue: Binding<String>, default_value, on_changeyes
CommandInputplaceholder, disabled, label: String = "Search", labelled_by—
CommandList, CommandGrouplabel: Option<String>yes
CommandDialogopen: Binding<bool>, default_open, on_open_change, title: String = "Commands", dismiss_control: bool = truefn

SelectTriggerSize is Sm, Md.

  • Focus stays on the trigger or input while the arrow keys move through the list; the highlighted option is announced as the active descendant. Enter chooses, Escape closes.
  • SelectValue shows the chosen option's text, taken from the option itself.
  • While a select is closed, its option bodies are built once more out of sight so the trigger can show the chosen value's text. Side effects in an option body therefore run twice.
  • Command is a command palette built on the combobox. Inside CommandDialog it fills the dialog's height.
  • There is no chip (multi-value) combobox and no scroll buttons on a long select list.

Building blocks for your own surfaces

These are in the crate root or their module, not in the prelude.

ComponentPropsChildren
ModalSurfacestate: OverlayState, role: Role = Dialog, dismiss_on_outside_press, dismiss_on_escape, scrim: bool = truefn
AnchoredSurfacestate: OverlayState, layer: OverlayLayer = Popover, placement: Signal<Placement> = Placement::BOTTOM, offset: f32 = 4.0, role: Role = GenericContainer, trap: Option<FocusTrapOptions>, dismiss_on_outside_press, dismiss_on_escapefn
OverlaySurfacestate: OverlayState, role: Role = GenericContainer, modal: bool = falseyes
MenuContentstate: OverlayState, placement = Placement::BOTTOM, offset: f32 = 4.0, dismiss_on_outside_pressfn
MenuTypeahead, MenubarArrows— (MenubarArrows takes bar: Option<RovingContext>)yes
zgui_ui::overlay::Elevatedat: SurfaceElevationfn
zgui_ui::overlay::Confinedtrap: Option<FocusTrapOptions>fn
zgui_ui::overlay::Scrim——
zgui_ui::listbox::ListboxCatalogueOf—fn

OverlayState holds a surface's open state and its trigger and content handles. OverlayState::new(open, default_open, on_open_change).provide() provides one as context; parts below get it with OverlayState::current(). zgui_ui::support has variant_attrs and the editing helpers the components use.

A modal surface is composed of these layers, from the outside in:

LayerFromJob
Portal(layer)zguidraws on an overlay band, outside any clipping ancestor
Elevatedzgui-uistacks a surface opened from another one above it (--zui-overlay-depth)
Presenceprimitiveskeeps the surface mounted until its exit animation ends
Scrim + DismissableLayerzgui-ui + primitivesdims the window; closes on Escape or a press outside
FocusScopeprimitiveskeeps Tab inside and restores focus
OverlaySurfacezgui-uithe surface element, its data-state and its role

AnchoredSurface has the same layers, with a Popper positioner instead of the scrim, and an optional focus trap. See Primitives for each behaviour.

Aliases

These names are re-exports (pub use) of another component, not wrappers.

Written asIs
SheetTrigger, DrawerTrigger, PopoverTriggerDialogTrigger
SheetClose, DrawerClose, PopoverCloseDialogClose
AlertDialogHeader, AlertDialogTitle, AlertDialogDescription, AlertDialogFooterthe Dialog… parts
DrawerHeader, DrawerTitle, DrawerDescription, DrawerFooterthe Sheet… parts
SelectGroup, SelectLabel, SelectSeparatorMenuGroup, MenuLabel, MenuSeparator
ComboboxGroup, ComboboxLabel, ComboboxSeparatorMenuGroup, MenuLabel, MenuSeparator
MenubarGroup, MenubarRadioGroupMenuGroup, MenuRadioGroup
CommandItem, CommandEmptyComboboxItem, ComboboxEmpty
CommandSeparator, CommandShortcutMenuSeparator, MenuShortcut

How a component is built

Button, from crates/zgui-ui/src/button/mod.rs, is a typical component:

#[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("zui-button", 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()}
        }
    }
}
  • The variants! table becomes classes and one data- attribute per axis (zui-button zui-button--ghost zui-button--sm, data-variant="ghost", data-size="sm"). The style! sheet selects on those attributes.
  • Hover, focus, press and disabled are CSS pseudo-classes, not signals.
  • install_stylesheet with a fixed name installs one sheet per component type, no matter how many instances exist.
  • Stable class names (zui-button, zui-icon, …) are safe to select on from your own sheet.

Next

On this page