GPUI Deck

Forms

The native settings example is a complete consumer of the public API.

The native settings example is a complete consumer of the public API. Run it in either appearance using the commands in the README. It combines Button, Input, Select, Textarea, Field, Label, Combobox, Calendar, DatePicker, Checkbox, Switch, RadioGroup, Slider, Progress, Toggle, and ToggleGroup with the navigation and overlay controls, without putting appearance in the library. The navigation and overlay guide describes its tabs and keyboard-help popover. The layout and data guide covers the Schedule table and the form's ScrollArea composition.

Call gpui_deck::init(cx) once and host window content in gpui_deck::Root. Root supplies Tab traversal and contains it inside an open Dialog. Give each control a stable element ID and an accessible label.

State ownership

ControlState ownerUpdating the application
TextareaRetained Entity<TextareaState>Observe for surrounding presentation; the existing Input events report edits
FieldApplication label, help, requirement, and validation errorRender current metadata around an existing Input, Textarea, or Combobox query; no new input state
LabelApplication text, target FocusHandle, and disabled flagFocus the existing control on click; keep its accessible name and disabled state in sync
ComboboxRetained Entity<ComboboxState>Observe for rendering; ComboboxEvent::Change reports the committed user-selected values
CalendarRetained Entity<CalendarState>Observe for rendering; CalendarEvent::Change reports the changed single/multiple/range selection
DatePickerRetained Entity<DatePickerState> composing existing Calendar/Popover stateObserve for selection/popup rendering; single and complete-range events follow popup closure, partial/multiple events retain it
CheckboxApplication field of type CheckboxState or boolon_change reports the next state; store it and call cx.notify()
ToggleApplication boolon_change requests the next pressed value; render it back with pressed
ToggleGroupRetained Entity<ToggleGroupState>Observe for rendering; ToggleGroupEvent::Change reports selected values in item order
SwitchApplication boolon_change reports the next value; store it and call cx.notify()
RadioGroupRetained Entity<RadioGroupState>Observe the entity for rendering; subscribe to RadioGroupEvent::Change for user selection changes
SelectRetained Entity<SelectState>Observe the entity for rendering; subscribe to SelectEvent::Change for committed user changes
SliderRetained Entity<SliderState>Observe for rendering; SliderEvent::Change reports the changed ordered values
ProgressApplication percentage and indeterminate flagPass the current value and state on each render; no interaction callback

Checkbox and Switch are controlled. Rendering them never changes application state. If the application leaves the supplied value unchanged after a callback, the control keeps showing that value. A programmatic field change is applied on the next render and does not call on_change.

Keep retained entities and their subscriptions in the view, as the native example does. Recreating a RadioGroupState in every render would discard its selection and stable option focus handles.

Keyboard and disabled behavior

InputCheckbox / SwitchRadioGroup
Tab / Shift-TabEnter or leave an enabled controlEnter at the selected enabled option, or the first enabled option when unselected; one Tab stop for the whole group
Space / EnterRequest the next value through the native activation pathSelect the focused option
Right / DownNo selection navigationSelect and focus the next enabled option, wrapping at the end
Left / UpNo selection navigationSelect and focus the previous enabled option, wrapping at the beginning
EscapePropagates to the containing surfacePropagates to the containing surface

RadioGroup arrow selection is immediate. Select keeps a pending keyboard cursor while its popup is open and commits only on activation. Both skip disabled options. An empty or entirely disabled RadioGroup has no Tab stop.

Disabled controls ignore activation and are skipped during Tab traversal. If a focused control becomes disabled, it retains its focus binding until focus leaves so Tab and Shift-Tab can still reach the neighboring control.

Verification boundary

The existing GPUI tests cover pointer and native key event routing, checked/mixed metadata, disabled behavior, group navigation, numeric controls, and representative settings flows across both appearances. Headless event simulation does not validate an operating system IME, screen reader, mixed-DPI display, or the rendered appearance of a native window. Those checks remain separate from automated behavior tests.