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.
| Prop | Type | Effect |
|---|---|---|
class | Classes | classes merged after the component's own |
| attribute bundle | Attrs, #[prop(attrs)] | any attr:, on:, a11y:, style: the caller writes, applied after the component's own |
children | Children or ChildrenFn | the 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>meansSignal<T, LocalStorage>, declaredinto, so a plainTworks too.Option<T>props take aT; writelabel = "Name", notlabel = 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 pass | Owner |
|---|---|
| nothing | the 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
| Component | Props | Children |
|---|---|---|
Button | variant: ButtonVariant = Default, size: ButtonSize = Md, disabled: Signal<bool> = false, node_ref: Option<NodeRef> | yes |
ButtonGroup | orientation: ButtonGroupOrientation = Horizontal | yes |
ButtonGroupText | — | yes |
ButtonGroupSeparator | — | — |
Badge | variant: BadgeVariant = Default | yes |
Label | control: Option<NodeRef>, node_ref: Option<NodeRef> | yes |
Kbd, KbdGroup | — | yes |
Separator | orientation: SeparatorOrientation = Horizontal, decorative: bool = true | — |
Skeleton | — | — |
Spinner | label: String = "Loading" | — |
AspectRatio | ratio: f32 = 1.0 | yes |
Avatar | src: Signal<Option<String>> = None, size: AvatarSize = Md, label: Option<String> | yes |
AvatarImage | src: Signal<Option<String>> = None | — |
AvatarFallback, AvatarGroupCount | — | yes |
AvatarBadge | label: Option<String> | opt |
AvatarGroup | size: AvatarSize = Md | yes |
| Enum | Values |
|---|---|
ButtonVariant | Default, Secondary, Destructive, Outline, Ghost, Link |
ButtonSize | Xs, Sm, Md, Lg, Icon, IconXs, IconSm, IconLg (the Icon… sizes are square) |
BadgeVariant | Default, Secondary, Destructive, Success, Warning, Outline, Ghost, Link |
AvatarSize | Sm, Md, Lg |
ButtonGroupOrientation, SeparatorOrientation | Horizontal, Vertical |
- Enter and Space press a
Buttonas an ordinary click, so oneon:clickserves pointer, keyboard and accessibility actions. disabledremoves the button from the focus order and from pointer hit testing, and tells assistive technology.Outlinebuttons have no fill at rest and no shadow; they take the colour of the surface behind them and tint on hover.Spinneris a status region named bylabel. UseProgresswhen the amount done is known.
Content
| Component | Props | Children |
|---|---|---|
Card | — | yes |
CardHeader, CardTitle, CardDescription, CardAction, CardContent, CardFooter | — | yes |
Alert | variant: AlertVariant = Default, live: bool = true, icon: bool = true | yes |
AlertTitle, AlertDescription | — | yes |
Empty, EmptyHeader, EmptyTitle, EmptyDescription, EmptyContent | — | yes |
EmptyMedia | variant: EmptyMediaVariant = Default | yes |
Item | variant: ItemVariant = Default, size: ItemSize = Md | yes |
ItemGroup, ItemHeader, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemFooter | — | yes |
ItemMedia | variant: ItemMediaVariant = Default | yes |
ItemSeparator | — | — |
Progress | value: Signal<Option<f64>> = None, max: f64 = 100.0, label: Option<String> | — |
| Enum | Values |
|---|---|
AlertVariant | Default, Destructive |
EmptyMediaVariant | Default, Icon |
ItemVariant | Default, Outline, Muted |
ItemSize | Md, Sm |
ItemMediaVariant | Default, Icon, Image |
Alert(live = true)is announced through a polite live region;live = falsemakes it a plain group.Progress(value = None)is indeterminate.
Text fields
| Component | Props | Children |
|---|---|---|
Input, Textarea | value: 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 | — |
InputGroup | disabled, invalid (Signal<bool> = false) | yes |
InputGroupAddon | align: InputGroupAddonAlign = InlineStart | yes |
InputGroupText | — | yes |
InputGroupButton | variant: ButtonVariant = Ghost, size: InputGroupButtonSize = Xs, disabled | yes |
InputGroupInput, InputGroupTextarea | value: Binding<String>, default_value: String = "", on_change, placeholder: String = "", disabled, invalid, node_ref | — |
InputOtp | value: 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
fieldelement, not by the component. - A
read_onlyfield refuses every edit and draws no caret, but its text can still be selected and copied with the pointer and the keyboard. InputOtpdraws its own boxes.groups = vec![3, 3]splits six boxes into two runs with a dash between them.on_completeruns when every box is filled.
Forms and fields
| Component | Props | Children |
|---|---|---|
Field | orientation: FieldOrientation = Vertical, invalid, disabled (Signal<bool> = false) | yes |
FieldSet, FieldGroup, FieldContent, FieldLabel, FieldTitle, FieldDescription, FieldError | — | yes |
FieldLegend | variant: FieldLegendVariant = Legend | yes |
FieldSeparator | — | opt |
Form | on_submit: Option<UnsyncCallback<()>>, label, submit_on_enter: bool = true, node_ref | yes |
FormField | name: String, validate: Option<Validator> | yes |
FormItem, FormLabel, FormDescription | — | yes |
FormMessage | — | opt |
FormSubmit | variant: ButtonVariant = Default, size: ButtonSize = Md, disabled, node_ref | yes |
FieldOrientation is Vertical, Horizontal. FieldLegendVariant is Legend, Label.
Fieldonly handles layout and labelling.Formadds validation and submission: Enter submits, and the first invalid field receives focus.use_form_field()returns the enclosingFormField's context.
Choices
| Component | Props | Children |
|---|---|---|
Checkbox | checked: Binding<Checked>, default_checked: Checked = No, on_change, disabled, invalid, labelled_by, node_ref | — |
Switch | checked: Binding<bool>, default_checked: bool = false, on_change, disabled, size: SwitchSize = Md, labelled_by, node_ref | — |
RadioGroup | value: Binding<String>, default_value, on_change, disabled, orientation: Orientation = Vertical, label | yes |
RadioGroupItem | value: String, disabled, invalid, label, labelled_by, node_ref | — |
Toggle | pressed: Binding<bool>, default_pressed: bool = false, on_change, variant: ToggleVariant = Default, size: ToggleSize = Md, disabled, label, node_ref | yes |
ToggleGroup | value: Binding<Vec<String>>, default_value, on_change, selection: ToggleSelection = Single, variant: ToggleVariant = Default, size: ToggleSize = Md, spacing: f32 = 0.0, disabled, orientation: Orientation = Horizontal, label | yes |
ToggleGroupItem | value: String, variant: Option<ToggleVariant>, size: Option<ToggleSize>, disabled, label, node_ref | yes |
Slider | value: 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 | — |
NativeSelect | value: Binding<String>, default_value, on_change, placeholder, size: NativeSelectSize = Md, disabled, invalid, node_ref | fn |
NativeSelectOption | value: String, text: Option<String>, disabled: bool = false | yes |
NativeSelectOptGroup | label: String | yes |
| Enum | Values |
|---|---|
Checked | No, Yes, Mixed (Mixed matches :indeterminate) |
SwitchSize, NativeSelectSize | Sm, Md |
ToggleVariant | Default, Outline |
ToggleSize | Sm, Md, Lg |
ToggleSelection | Single, Multiple |
Orientation | Horizontal, Vertical, Both (from zgui-ui-primitives) |
RadioGroupandToggleGroupare one tab stop; the arrow keys move between items. In a radio group the arrow keys also select.Slider: the arrow keys move onestep, Page Up/Down move ten steps, Home/End go to the ends.ToggleGroupItemuses the group'svariantandsizeunless it sets its own.spacingis the gap between items in spacing steps; at0.0the items join into one strip.- Outlined toggles and all fields (input, select, checkbox, radio) have no fill of their own.
Disclosure
| Component | Props | Children |
|---|---|---|
Collapsible | open: Binding<bool>, default_open: bool = false, on_open_change, disabled, node_ref | yes |
CollapsibleTrigger, CollapsibleContent | — | yes |
Accordion | value: Binding<Vec<String>>, default_value, on_change, selection: AccordionSelection = Single, collapsible: bool = true, disabled | yes |
AccordionItem | value: String, disabled | yes |
AccordionTrigger | level: usize = 3 | yes |
AccordionContent | — | yes |
Tabs | value: Binding<String>, default_value: String = "", on_change, orientation: Orientation = Horizontal, activation: TabsActivation = Automatic, label, node_ref | yes |
TabsList | variant: TabsListVariant = Default, label | yes |
TabsTrigger | value: String, disabled | yes |
TabsContent | value: String, keep_mounted: bool = false | fn |
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. TabsContentbuilds its content only while its tab is selected. Setkeep_mountedto keep input or scroll state in hidden panels.
Navigation
| Component | Props | Children |
|---|---|---|
Menubar | label: Option<String> | yes |
MenubarMenu | value: String | yes |
MenubarTrigger, MenubarLabel, MenubarShortcut | — | yes |
MenubarContent | placement: Placement = Placement::BOTTOM | fn |
MenubarItem | on_select, disabled, shortcut: Option<String> | yes |
MenubarCheckboxItem | checked: Binding<bool>, default_checked: bool = false, on_change, disabled, close_on_select: bool = false | yes |
MenubarRadioItem | value: String, disabled, close_on_select: bool = true | yes |
MenubarSeparator | — | — |
NavigationMenu | value: Binding<String>, default_value: String = "", on_change, label: String = "Main", node_ref | yes |
NavigationMenuList, NavigationMenuTrigger | — | yes |
NavigationMenuItem | value: String | yes |
NavigationMenuContent | — | fn |
NavigationMenuLink | active: Signal<bool> = false | yes |
NavigationMenuIndicator | — | — |
Breadcrumb | label: String = "Breadcrumb" | yes |
BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage | — | yes |
BreadcrumbSeparator | — | opt |
BreadcrumbEllipsis | label: String = "More" | — |
Pagination | label: String = "Pagination" | yes |
PaginationContent, PaginationItem | — | yes |
PaginationLink | page: Option<usize>, current: Signal<bool> = false | yes |
PaginationPrevious | disabled, label: String = "Previous page", text: String = "Previous" | — |
PaginationNext | disabled, label: String = "Next page", text: String = "Next" | — |
PaginationEllipsis | label: 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.
Sidebar
| Component | Props | Children |
|---|---|---|
SidebarProvider | open: Binding<bool>, default_open: bool = true, on_open_change, side: SidebarSide = Left, collapse: SidebarCollapse = Icon, variant: SidebarVariant = Sidebar, shortcut: bool = true | yes |
Sidebar | label: String = "Sidebar", side, collapsible, variant (each Option, overriding the provider) | opt |
SidebarHeader, SidebarContent, SidebarFooter, SidebarInset | — | yes |
SidebarGroup, SidebarGroupLabel, SidebarGroupContent | — | yes |
SidebarGroupAction | label, disabled | yes |
SidebarInput | value: Binding<String>, default_value, on_change, placeholder, disabled, labelled_by, node_ref | — |
SidebarSeparator | — | — |
SidebarMenu, SidebarMenuItem, SidebarMenuSub, SidebarMenuSubItem, SidebarMenuBadge | — | yes |
SidebarMenuButton | active: Signal<bool> = false, disabled, size: SidebarMenuSize = Default, variant: SidebarMenuVariant = Default, tooltip: Option<String>, label | yes |
SidebarMenuAction | label, disabled, hover_only: bool = false | yes |
SidebarMenuSubButton | active, disabled, size: SidebarSubSize = Md, label | yes |
SidebarMenuSkeleton | icon: bool = false, width: Option<u8> | — |
SidebarTrigger, SidebarRail | label: String = "Toggle sidebar" | — |
| Enum | Values |
|---|---|
SidebarSide | Left, Right |
SidebarCollapse | Icon, Offcanvas, None |
SidebarVariant | Sidebar, Floating, Inset |
SidebarMenuSize | Default, Sm, Lg |
SidebarMenuVariant | Default, Outline |
SidebarSubSize | Md, Sm |
- With
shortcuton, 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
| Component | Props | Children |
|---|---|---|
ScrollArea | orientation: Orientation = Vertical, label, node_ref | yes |
ScrollBar | orientation: Orientation = Vertical | — |
ResizablePanelGroup | direction: Orientation = Horizontal, on_change: Option<UnsyncCallback<Vec<f64>>>, label, node_ref | yes |
ResizablePanel | default_size: f64 = 0.0, min_size: f64 = 0.0, max_size: f64 = 100.0, min_pixels: f64 = 0.0, label, node_ref | yes |
ResizableHandle | step: f64 = 5.0, with_handle: bool = false, label | — |
Carousel | index: Binding<usize>, default_index: usize = 0, on_change, orientation: Orientation = Horizontal, wrap: bool = false, label, node_ref | yes |
CarouselContent, CarouselItem | — | yes |
CarouselPrevious | label: String = "Previous slide" | — |
CarouselNext | label: String = "Next slide" | — |
ScrollBardraws nothing itself. zgui draws the bar (a transparent track and a slim thumb);ScrollBaradds 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_pixelsis a minimum size in CSS pixels. It is converted to a percentage whenever the group is resized, and the larger ofmin_pixelsandmin_sizeapplies.- When a panel is removed, the remaining panels are resized from their declared sizes.
ResizableHandle: the arrow keys move it bysteppercentage points, Home/End go to the panel's minimum and maximum, and Enter collapses the panel before it or restores it.
Data
| Component | Props | Children |
|---|---|---|
Table | columns: Signal<String> = "1fr", interactive: bool = false, sticky_header: bool = false, rows: Option<Signal<usize>>, columns_count: Option<Signal<usize>>, label, labelled_by, node_ref | yes |
TableCaption | — | yes |
TableHeader, TableBody, TableFooter | node_ref | yes |
TableRow | index: Option<Signal<usize>>, selected: Option<Signal<bool>>, node_ref | yes |
TableHead | index, align: CellAlign = Start, sort: Signal<ColumnSort> = None, node_ref | yes |
TableCell | index, align: CellAlign = Start, header: bool = false, node_ref | yes |
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 | — |
ColumnResizer | header: 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_modelgives you theDataModel<T>:set_sort,set_filter,go_to_page,set_page_size,selection,set_all_selectedand more.set_sort(state)restores a savedSortState; a state naming a missing or unsortable column is refused.virtualized = truebuilds only the visible rows, sorow_sizemust match the row's styled height. Paging and virtualisation are alternatives; setting both virtualises.ColumnResizerreports the new width throughon_resizeinstead of applying it. The arrow keys move it bysteppixels.edge = Leadingputs the grip on the leading edge, for a column to the right of a flexible one. A double click callson_reset, where you can restore the column's default width.VirtualListbuilds the visible rows plusoverscanon each side.row_sizemay be a signal; changing it moves the rows and the scroll extent together. The extent is capped atzgui_ui::virtualize::MAX_EXTENT(4,000,000 CSS pixels); beyond that the scrollbar maps rows proportionally, so useVirtualWindow::offset_of(index)to scroll a row into view.
Charts and dates
| Component | Props | Children |
|---|---|---|
Chart | series: 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 | — |
ChartContainer | node_ref | yes |
ChartTooltipContent | label, entries: Vec<ChartEntry>, indicator: ChartIndicator = Dot, hide_label: bool = false, hide_indicator: bool = false | — |
ChartLegendContent | entries: Vec<LegendEntry>, align: LegendAlign = Bottom, label: String = "Series" | — |
Calendar | value: 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 | — |
CalendarDay | date: Date, in_month: bool, today: bool, unavailable: bool = false, on_choose: UnsyncCallback<Date> | — |
DatePicker | Calendar'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
widthandheightin CSS pixels; it does not resize to fit its box. Calendar(mode = CalendarMode::Range)reads and writesrangeinstead ofvalue.monthsshows several months side by side.
Settings
| Component | Props | Children |
|---|---|---|
Settings | page: Binding<String>, default_page: String = "", on_page_change, label, node_ref | yes |
SettingsPages | label | yes |
SettingsPage | value: String, disabled | yes |
SettingsPane | value: String, keep_mounted: bool = false | fn |
SettingsGroup, SettingsGroupLabel, SettingsGroupDescription | — | yes |
SettingsItem | label: 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
NodeReftoSettingsItem(control)and to the control'snode_refso that pressing the label focuses the control. - An item's
disabledfades the row and blocks the pointer. Disable the control too, so assistive technology reports the same state.
Toasts
| Component | Props | Children |
|---|---|---|
Toaster | corner: ToastCorner = BottomRight, limit: usize = 3, label: String = "Notifications", dismiss_label: String = "Dismiss" | yes |
ToastItem | queued: 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 builder | Effect |
|---|---|
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 |
pushreturns aToastId.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)andclear()remove toasts with their exit animation.- Beyond
limit, the oldest toasts are removed. Toasts are drawn on the toast overlay band, above everything else.ToastCornerisBottomRight,BottomLeft,TopRight,TopLeft.
Modal surfaces
| Component | Props | Children |
|---|---|---|
Dialog, AlertDialog, Sheet, Drawer | open: Binding<bool>, default_open: bool = false, on_open_change | yes |
DialogContent | dismiss_on_outside_press: Signal<bool> = true, dismiss_on_escape: Signal<bool> = true, dismiss_control: bool = true | fn |
AlertDialogContent | dismiss_on_escape: Signal<bool> = true, size: AlertDialogSize = Default | fn |
SheetContent | side: SheetSide = Right, dismiss_on_outside_press, dismiss_on_escape, dismiss_control: bool = true | fn |
DrawerContent | direction: SheetSide = Bottom, handle: bool = true, dismiss_on_outside_press, dismiss_on_escape | fn |
DialogTrigger | variant: ButtonVariant = Default, size: ButtonSize = Md | yes |
DialogClose | variant: ButtonVariant = Ghost, size: ButtonSize = Md | yes |
DialogHeader, DialogTitle, DialogDescription | — | yes |
DialogFooter | close_control: bool = false | yes |
DialogDismiss, SheetDismiss, DrawerHandle | — | — |
SheetHeader, SheetTitle, SheetDescription, SheetFooter | — | yes |
AlertDialogTrigger | variant = Default, size = Md | yes |
AlertDialogAction | variant = Default, size = Md, node_ref | yes |
AlertDialogCancel | variant = Outline, size = Md | yes |
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.
DialogTitlelabels the surface andDialogDescriptiondescribes it. A dialog with no title is announced as unlabelled.dismiss_controldraws 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,AlertDialogCancelandDialogClose, youron:clickruns before the surface closes.AlertDialogAction(node_ref)records the button so you can focus it. Drawerhas no drag-to-dismiss gesture;DrawerHandleis decorative.
Anchored surfaces
| Component | Props | Children |
|---|---|---|
Popover | open: Binding<bool>, default_open: bool = false, on_open_change | yes |
PopoverContent | placement: Signal<Placement> = Placement::BOTTOM, offset: f32 = 4.0, dismiss_on_outside_press, dismiss_on_escape | fn |
PopoverHeader, PopoverTitle, PopoverDescription | — | yes |
Tooltip | open, default_open, on_open_change, delay: Option<Duration>, close_delay: Option<Duration> | yes |
TooltipProvider | delay: Duration = 0 ms, close_delay: Duration = 150 ms | yes |
TooltipTrigger | — | yes |
TooltipContent | placement = Placement::TOP, offset: f32 = tooltip::DEFAULT_OFFSET, arrow: bool = true | fn |
TooltipArrow | — | — |
HoverCard | open, default_open, on_open_change, delay: Duration = 700 ms, close_delay: Duration = 300 ms | yes |
HoverCardTrigger | — | yes |
HoverCardContent | placement = Placement::BOTTOM, offset: f32 = 4.0 | fn |
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
HoverCardorPopoverfor that. TooltipProvidersets the delays for every tooltip inside it; aTooltip's owndelaywins. 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_OFFSETleaves room for it plus a 4 px gap; with the arrow on, a smaller offset is increased to fit the arrow. Setarrow = falseto drop it, or placeTooltipArrowyourself. - Colours come from
--zui-color-tooltip,-tooltip-foregroundand-tooltip-border. By default a tooltip inverts the page.
Menus
| Component | Props | Children |
|---|---|---|
DropdownMenu, ContextMenu, MenuSub | open: Binding<bool>, default_open: bool = false, on_open_change | yes |
DropdownMenuTrigger | variant: ButtonVariant = Default, size: ButtonSize = Md, disabled | yes |
DropdownMenuContent | placement = Placement::new(Side::Bottom, Align::Start), offset: f32 = 4.0 | fn |
ContextMenuTrigger | — | yes |
ContextMenuContent | placement = Placement::new(Side::Bottom, Align::Start) | fn |
MenuItem | disabled, destructive: bool = false, inset: bool = false, close_on_select: bool = true, on_select, shortcut: Option<String> | yes |
MenuCheckboxItem | checked: Binding<bool>, default_checked: bool = false, on_change, disabled, close_on_select: bool = true | yes |
MenuRadioGroup | value: Binding<String>, default_value, on_change, label | yes |
MenuRadioItem | value: String, disabled, close_on_select: bool = true | yes |
MenuGroup | label: Option<String> | yes |
MenuLabel | inset: bool = false | yes |
MenuShortcut | — | yes |
MenuSeparator | — | — |
MenuSubTrigger | disabled, inset: bool = false | yes |
MenuSubContent | placement = 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
DropdownMenuTriggeralso open it. - A disabled
DropdownMenuTriggerdoes 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. ContextMenuTriggeropens at the pointer on a right-click or press-and-hold. To open it from the keyboard, callContextMenuPlace::current()inside the trigger andopen_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
| Component | Props | Children |
|---|---|---|
Select, Combobox | value: Binding<String>, default_value, on_change, open: Binding<bool>, default_open, on_open_change | yes |
SelectTrigger | disabled, invalid, size: SelectTriggerSize = Md, label, labelled_by | yes |
SelectValue | placeholder: Option<String> | — |
SelectContent, ComboboxContent | placement = Placement::new(Side::Bottom, Align::Start), offset: f32 = 4.0 | fn |
SelectItem | value: String, text: Option<String>, disabled | yes |
ComboboxInput | placeholder, disabled, label, labelled_by | — |
ComboboxItem | value: String, text: Option<String>, disabled, on_select: Option<UnsyncCallback<()>> | fn |
ComboboxEmpty | — | fn |
Command | value: Binding<String>, default_value, on_change | yes |
CommandInput | placeholder, disabled, label: String = "Search", labelled_by | — |
CommandList, CommandGroup | label: Option<String> | yes |
CommandDialog | open: Binding<bool>, default_open, on_open_change, title: String = "Commands", dismiss_control: bool = true | fn |
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.
SelectValueshows 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.
Commandis a command palette built on the combobox. InsideCommandDialogit 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.
| Component | Props | Children |
|---|---|---|
ModalSurface | state: OverlayState, role: Role = Dialog, dismiss_on_outside_press, dismiss_on_escape, scrim: bool = true | fn |
AnchoredSurface | state: 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_escape | fn |
OverlaySurface | state: OverlayState, role: Role = GenericContainer, modal: bool = false | yes |
MenuContent | state: OverlayState, placement = Placement::BOTTOM, offset: f32 = 4.0, dismiss_on_outside_press | fn |
MenuTypeahead, MenubarArrows | — (MenubarArrows takes bar: Option<RovingContext>) | yes |
zgui_ui::overlay::Elevated | at: SurfaceElevation | fn |
zgui_ui::overlay::Confined | trap: 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:
| Layer | From | Job |
|---|---|---|
Portal(layer) | zgui | draws on an overlay band, outside any clipping ancestor |
Elevated | zgui-ui | stacks a surface opened from another one above it (--zui-overlay-depth) |
Presence | primitives | keeps the surface mounted until its exit animation ends |
Scrim + DismissableLayer | zgui-ui + primitives | dims the window; closes on Escape or a press outside |
FocusScope | primitives | keeps Tab inside and restores focus |
OverlaySurface | zgui-ui | the 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 as | Is |
|---|---|
SheetTrigger, DrawerTrigger, PopoverTrigger | DialogTrigger |
SheetClose, DrawerClose, PopoverClose | DialogClose |
AlertDialogHeader, AlertDialogTitle, AlertDialogDescription, AlertDialogFooter | the Dialog… parts |
DrawerHeader, DrawerTitle, DrawerDescription, DrawerFooter | the Sheet… parts |
SelectGroup, SelectLabel, SelectSeparator | MenuGroup, MenuLabel, MenuSeparator |
ComboboxGroup, ComboboxLabel, ComboboxSeparator | MenuGroup, MenuLabel, MenuSeparator |
MenubarGroup, MenubarRadioGroup | MenuGroup, MenuRadioGroup |
CommandItem, CommandEmpty | ComboboxItem, ComboboxEmpty |
CommandSeparator, CommandShortcut | MenuSeparator, 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 onedata-attribute per axis (zui-button zui-button--ghost zui-button--sm,data-variant="ghost",data-size="sm"). Thestyle!sheet selects on those attributes. - Hover, focus, press and disabled are CSS pseudo-classes, not signals.
install_stylesheetwith 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
Tokens and theming
The custom properties every component sheet reads, and how to change them.
Primitives
The headless behaviours under the overlays, lists and groups above.
Icons
The Icon component, the shipped set, and adding your own.
Overlays and portals
The same overlay problem, solved with the framework alone.
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.
Primitives
Reference for zgui-ui-primitives, the headless behaviours behind the component library — placement, focus trapping, roving focus, exit animations, dismissal, item order and value ownership — and how to style them with your own CSS.