Component reference

Every built-in element constructor and its builder methods, generated from nd-components.

This page is generated from the source of crates/nd-components each time the docs build, so it lists exactly what the crate exports. For what each component looks like on each OS, open the Gallery example.

Generated from crates/nd-components/src by nd-docs: 118 element constructors in 31 modules. Each lists the builder methods of the element it returns.

controls

icon_button

pub fn icon_button(id : impl Into<SharedString>, icon : Icon) -> Button

A button showing only icon; the platform's toolbar or borderless style.

separator

pub fn separator() -> Separator

form

form

pub fn form() -> Form

A grouped form. Children are [form_section]s.

form_section

pub fn form_section() -> FormSection

A group of rows under an optional title.

form_row

pub fn form_row(label : impl Into<SharedString>) -> FormRow

One row: label on the leading side, its single child control on the trailing side.

forms/choice

option_index

pub fn option_index(options : &[SharedString], value : &str) -> Option<usize>

The index value names among options: the option's title (exact, then ignoring case), or its index.

select

pub fn select(id : impl Into<SharedString>, options : impl IntoIterator<Item = impl Into<SharedString>>) -> Select

segmented

pub fn segmented(id : impl Into<SharedString>, options : impl IntoIterator<Item = impl Into<SharedString>>) -> Select

A segmented control: the options side by side, one selected.

radio_group

pub fn radio_group(id : impl Into<SharedString>, options : impl IntoIterator<Item = impl Into<SharedString>>) -> Select

Radio buttons, one per option, stacked unless .horizontal().

forms/date

date_picker

pub fn date_picker(id : impl Into<SharedString>, value : CivilDateTime) -> DatePicker

color_well

pub fn color_well(id : impl Into<SharedString>, color : Hsla) -> ColorWell

forms/display

label

pub fn label(text : impl Into<SharedString>) -> Label

Text in one of the system's text styles. text() is the plain run; a label is the control a form or window uses for titles and supporting text.

link

pub fn link(id : impl Into<SharedString>, title : impl Into<SharedString>) -> Link

A text link. With a url it opens in the default browser; on_click sees every activation.

progress

pub fn progress(value : Option<f32>) -> Progress

A progress bar at value (0 to 1); None shows an indeterminate bar.

spinner

pub fn spinner() -> Progress

The spinning activity indicator.

forms/rows

settings_group

pub fn settings_group(title : impl Into<SharedString>) -> FormSection

A titled group of rows; form_section under its libadwaita name.

row

pub fn row(title : impl Into<SharedString>) -> FormRow

A row with a title and optional subtitle, holding one trailing control (.child(..)).

switch_row

pub fn switch_row(id : impl Into<SharedString>, title : impl Into<SharedString>) -> SwitchRow

A titled row with a switch, controlled like [switch].

navigation_row

pub fn navigation_row(id : impl Into<SharedString>, title : impl Into<SharedString>, on_activate : impl Fn(&RowActivated, &mut Window, &mut App) + 'static) -> FormRow

A row that navigates somewhere: a disclosure chevron as its control, firing [RowActivated].

clamp

pub fn clamp() -> Clamp

form_field

pub fn form_field(label : impl Into<SharedString>) -> FormField

button_group

pub fn button_group() -> ButtonGroup

sheet_layout

pub fn sheet_layout(title : impl Into<SharedString>) -> SheetLayout

forms/settings

settings_form

pub fn settings_form<T : Settings>() -> AnyElement

The settings form for T. Without a provided handle it shows the defaults, read-only.

forms/text

text_field

pub fn text_field(id : impl Into<SharedString>) -> TextField

A single-line text field.

secure_field

pub fn secure_field(id : impl Into<SharedString>) -> TextField

A password field: characters hidden, value never exposed to automation reads.

search_field

pub fn search_field(id : impl Into<SharedString>, state : &Entity<TextFieldState>) -> TextField

The platform's search field, bound to state.

text_area

pub fn text_area(id : impl Into<SharedString>) -> TextArea

Multi-line text, scrolling inside its frame.

combo_box

pub fn combo_box(id : impl Into<SharedString>, options : impl IntoIterator<Item = impl Into<SharedString>>) -> ComboBox

A text field with suggestions.

forms/toggle

checkbox

pub fn checkbox(id : impl Into<SharedString>, label : impl Into<SharedString>) -> Checkbox

A checkbox with its title beside it.

switch

pub fn switch(id : impl Into<SharedString>) -> Switch

An on/off switch. Give it a .label(..) when no row title names it.

forms/value

number_text

pub fn number_text(value : f64, digits : Option<u8>) -> String

Formats a number without trailing zeros (0.5, 3), the form automation reads back.

slider

pub fn slider(id : impl Into<SharedString>, value : f32) -> Slider

stepper

pub fn stepper(id : impl Into<SharedString>, value : f64) -> Stepper

Up and down arrows changing value by a step.

glass

glass

pub fn glass() -> Glass

A glass surface. Lays its children out like a div.

glass_group

pub fn glass_group() -> GlassGroup

media/chat

chat_bubble

pub fn chat_bubble(text : impl Into<SharedString>, side : BubbleSide) -> ChatBubble

A message bubble. Its width follows the text up to BUBBLE.max_width.

initials

pub fn initials(name : &str) -> String

The monogram for name: the first letters of its first and last words, uppercased, or # for a name that is empty or a phone number (drawn as a person glyph).

group_layout

pub fn group_layout(count : usize, size : f32) -> Vec<nd_core::Rect>

Where each person of a group sits inside a size circle: up to four mini avatars [AVATAR_GROUP_SCALE] of it, one row for two, one over two for three, two by two for four.

avatar

pub fn avatar(person : Person, size : f32) -> Avatar

A person's photo, or their initials, in a circle size points across.

avatar_group

pub fn avatar_group(people : impl IntoIterator<Item = Person>, size : f32) -> Avatar

A group's avatar: its first four people clustered in one circle.

chat_row

pub fn chat_row(id : impl Into<SharedString>, message : ChatMessage) -> AnyElement

A message laid out as a thread row: aligned to its side, spaced by its run, the sender's avatar and name in a group, a receipt under it. id keys the row's bubble.

media/composer

composer

pub fn composer(id : impl Into<SharedString>, draft : &Draft) -> Composer

The message field over draft.

media/image

image

pub fn image(source : impl Into<ImageSource>) -> Image

A picture from a path, URL or bytes. Size it with the style; a side left open follows the image's aspect.

image_placeholder

pub fn image_placeholder() -> Image

An image node with no picture yet: the placeholder alone, at the size the style gives.

media/lyrics

rows

pub fn rows(lyrics : &Lyrics) -> Vec<Row>

The rows for lyrics: lines with text in time order, interludes in the long gaps, and word fills for every synced line.

lit_at

pub fn lit_at(rows : &[Row], t : f64, previous : usize) -> Lit

The lit rows at t. previous is the anchor last time, kept through gaps.

lyrics_view

pub fn lyrics_view(id : impl Into<SharedString>, lyrics : impl Into<Arc<Lyrics>>, clock : PlaybackClock) -> LyricsView

Lyrics following clock. Size it with the style; it fills what it is given.

media/shelf

shelf

pub fn shelf(id : impl Into<SharedString>, handle : &ShelfHandle) -> Shelf

A sideways-scrolling row of cards. handle keeps its position across renders.

media/transport

seek_bar

pub fn seek_bar(id : impl Into<SharedString>, clock : PlaybackClock) -> SeekBar

A playback scrubber over clock. Give it the track's duration; it fires [Seeked].

player_bar

pub fn player_bar(id : impl Into<SharedString>, now : NowPlaying) -> PlayerBar

volume_icon

pub fn volume_icon(volume : f32, muted : bool) -> Icon

The volume icon for a level, as the system's own volume menu picks it.

media/video

video

pub fn video(source : impl Into<SharedString>) -> Video

A video from a path or URL, paused until [Video::playing] is set.

palette

palette_item

pub fn palette_item(id : impl Into<SharedString>, title : impl Into<SharedString>) -> PaletteItem

command_palette

pub fn command_palette(id : impl Into<SharedString>) -> CommandPalette

A palette over the active window. The element takes no space where it sits; place it anywhere in the window's tree (scaffold().overlay(..) reads best).

panes/dock

empty_dock

pub fn empty_dock<T>() -> DockModel<T>

dock_panel_of

pub fn dock_panel_of<T>(tabs : Vec<DockTab<T>>, active_tab_id : Option<&str>) -> DockPanel<T>

A panel over tabs, active tab defaulting to the first. An empty tab list is not a legal panel ([close_tab] collapses the panel instead).

seed_dock

pub fn seed_dock<T>(groups : Vec<Vec<DockTab<T>>>) -> DockModel<T>

Balanced horizontal dock over one panel per tab group, panel ids "1" to "n". Groups with no tabs are dropped, so every leaf starts with at least one tab.

seed_dock_with

pub fn seed_dock_with<T>(groups : Vec<Vec<DockTab<T>>>, id : impl Fn(&DockPanel<T>, usize) -> String) -> DockModel<T>

dock_panels

pub fn dock_panels<T>(m : &DockModel<T>) -> Vec<(&PaneId, &DockPanel<T>)>

Panels in layout order, as (panel id, panel).

find_dock_panel

pub fn find_dock_panel<'a, T>(m : &'a DockModel<T>, panel_id : &str) -> Option<&'a DockPanel<T>>

find_dock_tab

pub fn find_dock_tab<'a, T>(m : &'a DockModel<T>, tab_id : &str) -> Option<DockTabLocation<'a, T>>

active_dock_tab

pub fn active_dock_tab<T>(panel : &DockPanel<T>) -> Option<&DockTab<T>>

add_tab

pub fn add_tab<T : Clone>(m : &DockModel<T>, panel_id : &str, tab : DockTab<T>, index : Option<usize>) -> DockModel<T>

Adds a tab to an existing panel and activates it. A tab id already used anywhere in the dock is rejected (same tree), since every op here addresses tabs by id.

close_tab

pub fn close_tab<T : Clone>(m : &DockModel<T>, tab_id : &str) -> DockModel<T>

Closes a tab; the last tab in a panel closes the panel, which collapses the split and gives the space back to the sibling.

activate_tab

pub fn activate_tab<T : Clone>(m : &DockModel<T>, tab_id : &str) -> DockModel<T>

Selects a tab inside its own panel. Focus is a separate op (focus_pane): activating a tab in a background panel should not steal the focus ring.

move_tab

pub fn move_tab<T : Clone>(m : &DockModel<T>, tab_id : &str, target_panel_id : &str, index : Option<usize>) -> DockModel<T>

Moves a tab to index of target_panel_id. Within one panel this is a reorder and leaves the active tab alone; across panels the tab is activated in its new home, which takes the focus with it, and a source panel left empty collapses.

undock_tab

pub fn undock_tab<T : Clone>(m : &DockModel<T>, tab_id : &str, zone : DockEdgeZone) -> DockModel<T>

Pulls a tab out of its panel into a new panel beside it. A panel holding one tab has nothing to undock, so that is a same-tree no-op.

dock_panel

pub fn dock_panel<T : Clone>(m : &DockModel<T>, panel_id : &str, target_panel_id : &str, zone : DockZone) -> DockModel<T>

Relocates a whole panel against another one. Center merges its tabs into the target's stack; the four edges split the target and take that side. [apply_dock_drop] routes a drop here.

hit_test_dock_zone

pub fn hit_test_dock_zone(rect : DockRect, px : f32, py : f32, edge : Option<f32>) -> DockZone

Which zone a pointer at (px, py) lands in over rect. Pure geometry: the outer edge fraction (default 0.25, clamped to [0.01, 0.5]) of each side is that side's zone, the middle is Center. A point past an edge still names that edge; a degenerate rect is all Center.

dock_drag_payload

pub fn dock_drag_payload(kind : DockDragKind, id : &str) -> String

The drag payload a dock drag source carries. Namespaced because the drop side also receives plain text dragged in from other applications, which must not be read as a tab id.

parse_dock_drag

pub fn parse_dock_drag(payload : &str) -> Option<DockDrag>

The inverse and the guard: anything not minted by [dock_drag_payload] is None, which every drop path treats as "not ours, ignore".

dock_panel_rects

pub fn dock_panel_rects<T>(m : &DockModel<T>, size : DockSize) -> Vec<(PaneId, DockRect)>

Every panel's rect inside a dock of size, in layout order, from the split ratios alone.

dock_zone_at

pub fn dock_zone_at<T>(m : &DockModel<T>, panel_id : &str, x : f32, y : f32, size : Option<DockSize>, edge : Option<f32>) -> DockZone

Zone a drop point over panel_id lands in. x and y are panel-local, so the hit test runs against a rect at the origin. No size, or a panel not in the model, means Center, the one zone that needs no geometry.

apply_dock_drop

pub fn apply_dock_drop<T : Clone>(m : &DockModel<T>, payload : &str, target_panel_id : &str, zone : DockZone) -> DockModel<T>

Turns one drop into one model op, and is the whole drop policy:

• a panel drag is [dock_panel], merging into the target's tab stack on Center and splitting the target on an edge;
• a tab dropped on Center is [move_tab] into the target's stack;
• a tab dropped on an edge is [move_tab] followed by [undock_tab], landing it in a new panel on that side. A tab alone in its panel takes the [dock_panel] path instead: the panel IS that tab, so moving it keeps its id and its already-docked no-op.

A drag that ends where it started returns the same tree.

serialize_dock

pub fn serialize_dock<T : Clone>(m : &DockModel<T>) -> DockSnapshot<T>

deserialize_dock

pub fn deserialize_dock<T>(raw : DockSnapshot<T>, is_data : impl Fn(&T) -> bool) -> DockModel<T>

Rebuilds a dock from persisted data, on migrate_panes terms: anything malformed rejects the whole tree back to [empty_dock]. A panel with no tabs, a tab without an id, tab data failing is_data and a tab id used twice all count as malformed; an active_tab_id naming a tab that is gone is repaired to the panel's first tab instead.

panes/tiles

empty_tiles

pub fn empty_tiles<T>(columns : i32) -> TileModel<T>

seed_tiles

pub fn seed_tiles<T : Clone>(items : Vec<TilePlacement<T>>, columns : i32) -> TileModel<T>

Places items in order, each one dropped at its requested cell and pushed clear of what is already down. Ids default to "1" to "n".

find_tile

pub fn find_tile<'a, T>(m : &'a TileModel<T>, id : &str) -> Option<&'a Rc<Tile<T>>>

place_tile

pub fn place_tile<T : Clone>(m : &TileModel<T>, placement : TilePlacement<T>) -> TileModel<T>

Adds a tile at the cells it asks for, pushing whatever was there down. An id already in the model is rejected (same tree), the way add_tab rejects a duplicate tab id.

remove_tile

pub fn remove_tile<T>(m : &TileModel<T>, id : &str) -> TileModel<T>

move_tile

pub fn move_tile<T : Clone>(m : &TileModel<T>, id : &str, x : i32, y : i32) -> TileModel<T>

resize_tile

pub fn resize_tile<T : Clone>(m : &TileModel<T>, id : &str, w : i32, h : i32) -> TileModel<T>

raise_tile

pub fn raise_tile<T>(m : &TileModel<T>, id : &str) -> TileModel<T>

Moves a tile last in layout order, which is the top of the paint order.

update_tile

pub fn update_tile<T : Clone + PartialEq>(m : &TileModel<T>, id : &str, f : impl FnOnce(&T) -> T) -> TileModel<T>

Replaces a tile's data with f(current). Equal data is a same-tree no-op.

tile_drag_payload

pub fn tile_drag_payload(id : &str) -> String

The drag payload a tile carries, namespaced for the same reason as dock_drag_payload: text dragged in from another application arrives on the same drop handler.

parse_tile_drag

pub fn parse_tile_drag(payload : &str) -> Option<&str>

tile_cell_at

pub fn tile_cell_at<T>(m : &TileModel<T>, size : TileSize, x : f32, y : f32) -> TileCell

Cell under a point in the grid's coordinate space. Cells are taken as uniform, which is what the grid draws when every tile expands. Points outside the grid clamp to its edge cells.

apply_tile_drop

pub fn apply_tile_drop<T : Clone>(m : &TileModel<T>, payload : &str, size : TileSize, x : f32, y : f32) -> TileModel<T>

Turns one drop into one model op: the cell under the pointer becomes the dragged tile's top-left, and [move_tile] pushes whatever it lands on clear. A tile dropped back on the cell it already occupies returns the same tree, as does a payload from anything but a tile.

serialize_tiles

pub fn serialize_tiles<T : Clone>(m : &TileModel<T>) -> TileSnapshot<T>

deserialize_tiles

pub fn deserialize_tiles<T : Clone>(raw : TileSnapshot<T>, columns : i32, is_data : impl Fn(&T) -> bool) -> TileModel<T>

Rebuilds a tile layout from persisted data. An empty or duplicate id, or data failing is_data, rejects the whole layout back to empty_tiles(columns); columns is also the fallback when the persisted column count is absent. Loaded tiles are clamped and pushed clear of each other, so a hand-edited file cannot land an overlapping layout.

panes/views

pane_tree

pub fn pane_tree<T : 'static>(id : impl Into<SharedString>, tree : &PaneTree<T>, leaf : impl Fn(Leaf<'_, T>, bool) -> AnyElement + 'static) -> PaneTreeView<T>

Renders tree; leaf draws each leaf, told whether it is the focused one.

dock_view

pub fn dock_view<T : 'static>(id : impl Into<SharedString>, model : &DockModel<T>, tab : impl Fn(&DockTab<T>) -> AnyElement + 'static) -> DockView<T>

Renders model; tab draws a tab's content. Every tab stays mounted, so a terminal or a page in a background tab keeps running.

tiles_view

pub fn tiles_view<T : 'static>(id : impl Into<SharedString>, model : &TileModel<T>, row_height : Pixels, tile : impl Fn(&Tile<T>) -> AnyElement + 'static) -> TilesView<T>

rich

text_color

pub fn text_color(theme : &Theme, color : TextColor, ink : Option<Hsla>) -> Hsla

The colour color names under theme. ink is the ink of a filled surface the text sits on (a sent bubble): every token but a custom colour resolves to it there, since the surface's own ink is the only colour that reads on it at 4.5:1.

scaffold

scaffold

pub fn scaffold() -> Scaffold

sidebar

pub fn sidebar() -> Pane

The sidebar. On macOS its material, width and collapse come from the split view.

inspector

pub fn inspector() -> Pane

The inspector, on the trailing side.

source_list

source_node

pub fn source_node(id : impl Into<SharedString>, title : impl Into<SharedString>) -> SourceNode

A row with id showing title.

source_section

pub fn source_section(id : impl Into<SharedString>, title : impl Into<SharedString>) -> SourceNode

A section header; rows name it as their parent. Expanded unless the app collapses it.

source_action

pub fn source_action(id : impl Into<SharedString>, icon : Icon) -> SourceAction

source_tree

pub fn source_tree(id : impl Into<SharedString>) -> SourceTree

source_item

pub fn source_item(id : impl Into<SharedString>, title : impl Into<SharedString>) -> SourceItem

One row: an id the app selects by, a title, and optionally an icon, a badge and children.

source_list

pub fn source_list(id : impl Into<SharedString>) -> SourceTree

A sidebar of fixed places in titled sections: [SourceTree::section] and [SourceTree::items] fill it.

split

split

pub fn split(id : impl Into<SharedString>, axis : Axis) -> Split

A split of two panes along axis. id keys it, so the panes keep their content when a sibling appears or goes.

split_pane

pub fn split_pane() -> SplitPane

status_page

status_page

pub fn status_page(title : impl Into<SharedString>) -> StatusPage

An empty state titled title, centred in the room it is given.

tabs

tab_strip

pub fn tab_strip(id : impl Into<SharedString>) -> TabStrip

tab_page

pub fn tab_page(id : impl Into<SharedString>, title : impl Into<SharedString>) -> TabPage

tab_view

pub fn tab_view(id : impl Into<SharedString>) -> TabView

In-window tabs. id keys the strip, which is what automation finds (setValue with a tab's title or id selects it); each page is keyed by its tab's id.

titlebar

titlebar

pub fn titlebar() -> Titlebar

toast

toast

pub fn toast(id : impl Into<SharedString>, title : impl Into<SharedString>) -> Toast

A toast with id (echoed in its events) showing title for [DEFAULT_TIMEOUT].

toast_overlay

pub fn toast_overlay(id : impl Into<SharedString>) -> ToastOverlay

The window's toasts. Takes no space where it sits; one per window.

banner

pub fn banner(id : impl Into<SharedString>, title : impl Into<SharedString>) -> Banner

A message bar across its container: title and an optional button. Hidden until revealed.

toolbar

system_item

pub fn system_item(item : SystemItem) -> AnyElement

toolbar_sidebar_toggle

pub fn toolbar_sidebar_toggle() -> AnyElement

The system sidebar toggle.

toolbar

pub fn toolbar() -> Toolbar