Crate ui 

UI – App UI Primitives & Components

This crate provides a set of UI primitives and components that are used to build all of the elements in the app’s UI.

Related Crates:

• ui_macros - proc_macros support for this crate
• ui_input - the single line input component

Re-exports

pub use prelude::*;

Modules

animation

component_prelude

focus_ring

Focus ring wrapper with a true offset gap.

palette

Role-based color palette for the design system.

prelude

The prelude of this crate. When building UI in this app you almost always want to import this.

scrollbars

semantic

Theme-driven neutral color roles.

shadow

Elevation shadow scale for the design system.

table_row

A newtype for a table row that enforces a fixed column count at runtime.

utils

UI-related utilities

Structs

ActionPanel

A bordered, semantic::elevated_surface-backed section with a fieldset area (arbitrary child fields, e.g. FormFields) followed by a border-t footer with right-aligned Save/Cancel Buttons.

AgentSetupButton

AiSettingItem

A reusable setting item row for AI-related configuration lists.

Alert

A tinted, icon-led message box for one of four severities.

AlertModal

AnnouncementToast

AppShell

Composes an already-styled Navbar (top) and Sidebar (left) around a main content slot. Pure composition — no new styling logic; Navbar and Sidebar own all of their own visuals (colors/borders/width).

Assets

Embedded icon SVG assets (Heroicons, MIT-licensed).

Avatar

An element that renders a user avatar with customizable appearance options.

AvatarAudioStatusIndicator

An indicator that shows the audio status of a player.

AvatarAvailabilityIndicator

Represents the availability and presence status of a collaborator.

Badge

A small pill label conveying status or category.

Banner

Banners provide informative and brief messages without interrupting the user. This component offers four severity levels that can be used depending on the message.

Breadcrumb

A horizontal trail of links showing the user’s location within a hierarchy.

BreadcrumbItem

A single crumb within a Breadcrumb trail.

Button

An element that creates a button with a label and optional icons.

ButtonConfiguration

ButtonGroup

A segmented group of connected buttons: no gap between children, a shared divider border between each pair, and rounding only on the outer corners (first/last child).

ButtonLike

A button-like element that can be used to create a custom button when prebuilt buttons are not sufficient. Use this sparingly, as it is unconstrained and may make the UI feel less consistent.

ButtonLink

A button that takes an underline to look like a regular web link. It also contains an arrow icon to communicate the link takes you out of the app.

Callout

A callout component for displaying important information that requires user attention.

Card

A surface container for grouping related content, with optional header and footer regions. Neutrals are theme-driven (dark/light aware).

Checkbox

Checkbox

Chip

Chips provide a container for an informative label.

CircularProgress

A circular progress indicator that displays progress as an arc growing clockwise from the top.

CollabNotification

Combobox

A typeahead-filtered select: a TextInput (typed filter) plus a DropdownMenu-style popover list of options filtered by case-insensitive substring match (no fuzzy-match / async / remote data — out of scope per plan). Selecting an option sets the input’s display text via TextInput::set_text.

ConfiguredApiCard

Container

A fixed max-width centering wrapper, matching Tailwind’s .container pattern.

ContextMenu

ContextMenuEntry

CopyButton

CountBadge

A small, pill-shaped badge that displays a numeric count.

DecoratedIcon

DescriptionList

A key-value list for displaying structured details (Tailwind “Description List”).

DiffStat

Disclosure

Divider

DocumentationAside

Drawer

A side panel (“slide-over”) anchored to the right edge of its container.

DropdownMenu

EmptyState

A centered placeholder shown when a list/table/collection has no content.

Facepile

An element that displays a collection of (usually) faces stacked horizontally, with the left-most face on top, visually descending from left to right.

Feed

A vertical activity timeline: a left connecting line with avatar + text + timestamp entries (Tailwind “Feed”).

FileInput

A styled file-upload trigger: dashed semantic::border, an icon, and a “Click to upload” label.

FormField

A label + input + help/error/success/warning wrapper for form layouts.

GradientFade

A gradient overlay that fades from a solid color to transparent.

HeaderResizeInfo

Headline

A headline element, used to emphasize some text and create a visual hierarchy.

HighlightedLabel

Icon

IconButton

IconDecoration

The decoration for an icon.

IconDecorationKindIter

An iterator over the variants of IconDecorationKind

IconNameIter

An iterator over the variants of IconName

IconWithIndicator

IndentGuideColors

Represents the colors used for different states of indent guides.

IndentGuideLayout

Represents the layout information for an indent guide.

IndentGuides

Indicator

InputGroup

Wraps an input-like child (typically an Entity<TextInput>) with an optional leading and/or trailing slot (icon or button), presenting a single unified border/background around the whole group.

Key

KeyBinding

KeyIcon

KeybindingHint

Represents a hint for a keybinding, optionally with a prefix and suffix.

KnockoutIconNameIter

An iterator over the variants of KnockoutIconName

Label

A struct representing a label element in the UI.

LabelLike

A label-like element that can be used to create a custom label when prebuilt labels are not sufficient. Use this sparingly, as it is unconstrained and may make the UI feel less consistent.

LinkPreview

List

ListBulletItem

ListHeader

ListItem

ListSeparator

ListSubHeader

LoadingLabel

MediaObject

A flex row pairing a media element (image/avatar) with a text block — Tailwind’s “Media Object” pattern.

MenuHandleElementState

Modal

ModalFooter

ModalHeader

ModalRow

MultiSelect

A multi-value select: a trigger showing selected values as dismissible Chips plus a DropdownMenu-style checklist popover; toggling an option adds/removes its Chip. Stateful view — create with cx.new(|_| MultiSelect::new(options)).

Navbar

A fixed top bar: leading content (title/logo) on the left, optional trailing actions on the right. Neutrals are theme-driven.

Navigable

An element that can be navigated through via keyboard. Intended for use with scrollable views that want to use

NavigableEntry

An entry of Navigable that can be navigated to.

PageHeading

A top-of-page heading: large bold title, optional muted subtitle, and a right-aligned actions slot (e.g. Buttons). mb_6, justify_between, items_center per Tailwind’s Page Heading pattern.

Pagination

Prev/next + numbered page navigation.

ParallelAgentsIllustration

Popover

A popover is used to display a menu or show some options.

PopoverMenu

PopoverMenuElementState

PopoverMenuFrameState

PopoverMenuHandle

PrepaintState

ProgressBar

A progress bar is a horizontal bar that communicates the status of a process.

RadioButton

A single radio button. Group exclusivity is the caller’s responsibility: the parent holds the selected value and passes checked to each button.

RedistributableColumnsState

RenderIndentGuideParams

Parameters for rendering indent guides.

RenderedIndentGuide

Represents a rendered indent guide with its visual properties and interaction areas.

RequestLayoutState

ResizableColumnsState

State for independently resizable columns (spreadsheet-style).

RightClickMenu

ScrollbarPrepaintState

Scrollbars

SearchInput

A search field: TextInput with a leading MagnifyingGlass icon and a trailing clear (XMark) button shown once the input is non-empty. Stateful view — create with cx.new(|cx| SearchInput::new(cx, "Search…")).

Section

SectionHeader

SectionHeading

A mid-page section heading: bold title with optional grouped content (e.g. a tab bar or filter row) below it. mb_4 per Tailwind’s Section Heading pattern.

SegmentedControl

A horizontal row of connected segments where exactly one is active. Mirrors RadioButton’s checked/on_click pattern, rendered as a single connected pill row (visual family of Phase 2’s ButtonGroup).

Select

A dropdown select: a trigger styled like a text field plus an expandable option list. Stateful view — create with cx.new(|_| Select::new(options)).

Sidebar

A vertical navigation rail. Holds SidebarItems (or any children).

SidebarItem

A single clickable navigation row inside a Sidebar.

SpinnerLabel

A spinner indication, based on the label component, that loops through frames of the specified animation. It implements LabelCommon as well.

SplitButton

/// A button with two parts: a primary action on the left and a secondary action on the right.

StatsCard

A Card-based metric tile: big number, label, and optional trend indicator. Callers compose multiple StatsCards into a grid.

Stepper

A horizontal row of step circles connected by a line, for multi-step flows (e.g. checkout, onboarding wizards).

StepperStep

A single step within a Stepper.

StickyItems

Switch

Switch

SwitchField

SwitchField

Tab

A single tab within a TabBar.

TabBar

Table

A table component

TableInteractionState

TableRenderContext

TextInput

A focusable single-line (or multi-line) text field backed by a real String buffer. Keyboard input is handled via key events (key_char + editing keys), so typed characters genuinely appear and backspace deletes.

ThreadItem

ThreadItemWorktreeInfo

ToastStack

A bottom-right stacking container for crate::AnnouncementToast instances.

ToggleButtonGroup

ToggleButtonPosition

The position of a [ToggleButton] within a group of buttons.

ToggleButtonSimple

ToggleButtonWithIcon

Tooltip

TreeViewItem

UpdateButton

A button component displayed in the title bar to show auto-update status.

Vector

A vector image, such as an SVG.

VectorNameIter

An iterator over the variants of VectorName

VerticalNav

A flat list of navigation links for in-page sub-navigation (e.g. a settings page’s left-hand link list).

VerticalNavItem

A single clickable link within a VerticalNav.

Enums

AgentThreadStatus

AiSettingItemSource

AiSettingItemStatus

AnyIcon

AudioStatus

The audio status of an player, for use in representing their status visually on their avatar.

BadgeColor

Semantic color role of a Badge.

BadgeVariant

Fill style of a Badge.

BorderPosition

ButtonSize

The height of a button.

ButtonStyle

The visual appearance of a button.

CardVariant

Visual style of a Card.

CollaboratorAvailability

Represents the availability status of a collaborator.

Color

Sets a color that has a consistent meaning across all themes.

ColumnWidthConfig

ContextMenuItem

DescriptionListMode

Layout mode of a DescriptionList row.

DividerColor

The color of a Divider.

DocumentationSide

DropdownStyle

DynamicSpacing

A dynamic spacing system that adjusts spacing based on UiDensity.

ElevationIndex

Today, elevation is primarily used to add shadows to elements, and set the correct background for elements like buttons.

EmptyMessage

HeadlineSize

The size of a Headline element

IconButtonShape

The shape of an IconButton.

IconDecorationKind

IconName

IconPosition

IconSize

InputValidationState

Visual validation state of a TextInput, reflected in its border/focus ring color.

KeybindingPosition

KnockoutIconName

An icon silhouette used to knockout the background of an element for an icon to sit on top of it, emulating a stroke/border.

LabelSize

Sets the size of a label

LineHeightStyle

Sets the line height of a label

ListItemSpacing

PlatformStyle

The platform style to use when rendering UI.

ScrollAxes

ScrollbarStyle

Severity

Severity levels that determine the style of the component. Usually, it affects the background. Most of the time, it also follows with an icon corresponding the severity level.

Shadow

Named elevation levels. Values mirror the Tailwind box-shadow scale.

SortDirection

Sort direction shown by a Table sortable column header indicator.

SpinnerVariant

Different types of spinner animations

SplitButtonKind

SplitButtonStyle

StaticColumnWidths

StatsTrend

Direction of a StatsCard trend indicator.

SwitchColor

Defines the color for a switch component.

SwitchLabelPosition

Defines the color for a switch component.

TabBarStyle

Visual style for TabBar and its child Tabs.

TableResizeBehavior

TextSize

A utility for getting the size of various semantic text sizes.

TintColor

ToggleButtonGroupSize

ToggleButtonGroupStyle

ToggleStyle

The visual style of a toggle.

VectorName

WorktreeKind

Constants

BASE_REM_SIZE_IN_PX

The base size of a rem, in pixels.

DRAWER_WIDTH

Default width for a Drawer (Tailwind w-96 ~= 384px).

EDITOR_SCROLLBAR_WIDTH

EXAMPLE_FACES

POPOVER_Y_PADDING

Y height added beyond the size of the contents.

TOAST_STACK_MAX_VISIBLE

Default cap on simultaneously visible toasts (Tailwind reference spec: max 3 visible).

Traits

ButtonBuilder

ButtonCommon

A common set of traits all buttons must implement.

CommonAnimationExt

An extension trait for adding common animations to animatable components.

LabelCommon

A common set of traits all labels must implement.

PopoverTrigger

ScrollableHandle

SelectableButton

A trait for buttons that can be Selected. Enables setting the ButtonStyle of a button when it is selected.

StickyCandidate

StickyItemsDecoration

A decoration for a StickyItems. This can be used for various things, such as rendering indent guides, or other visual effects.

StyledShadow

Extends gpui::Styled with a named shadow scale.

StyledTypography

Extends gpui::Styled with typography-related styling methods.

WithScrollbar

Functions

bind_redistributable_columns

checkbox

Creates a new checkbox.

combobox_preview

Standalone gallery preview for Combobox (not registered in the Component catalog since it is a stateful Entity, matching Select’s existing convention in this crate).

divider

h_flex

Horizontally stacks elements. Sets flex(), flex_row(), items_center()

h_group

Creates a horizontal group with consistent spacing.

h_group_lg

Creates a horizontal group with consistent spacing.

h_group_sm

Creates a horizontal group with tight, consistent spacing.

h_group_xl

Creates a horizontal group with consistent spacing.

highlight_ranges

indent_guides

multi_select_preview

Standalone gallery preview for MultiSelect (not registered in the Component catalog since it is a stateful Entity, matching Select’s existing convention in this crate).

on_new_scrollbars

rems_from_px

Returns a rem value derived from the provided pixel value and the base rem size (16px).

render_keybinding_keystroke

render_modifiers

render_redistributable_columns_resize_handles

render_table_header

render_table_row

right_click_menu

Creates a RightClickMenu

search_input_preview

Standalone gallery preview for SearchInput (not registered in the Component catalog since it is a stateful Entity, matching Select’s existing convention in this crate).

sticky_items

switch

Creates a new switch.

text_for_action

Returns a textual representation of the key binding for the given Action.

text_for_keybinding_keystrokes

text_for_keystroke

text_for_keystrokes

theme_is_transparent

Returns if the window and it’s surfaces are expected to be transparent.

tooltip_container

ui_density

Returns the current UiDensity setting. Use this to modify or show something in the UI other than spacing.

v_flex

Vertically stacks elements. Sets flex(), flex_col()

v_group

Creates a vertical group with consistent spacing.

v_group_lg

Creates a vertical group with consistent spacing.

v_group_sm

Creates a vertical group with tight, consistent spacing.

v_group_xl

Creates a vertical group with consistent spacing.

vertical_divider

vh

Returns a Length corresponding to the specified percentage of the viewport’s height.

vw

Returns a Length corresponding to the specified percentage of the viewport’s width.

Type Aliases

Textarea

A multi-line text field. Construct with cx.new(|cx| Textarea::new(cx).multiline(true)).

UncheckedTableRow

Represents an unchecked table row, which is a vector of elements. Will be converted into TableRow<T> internally