Widget Reference

Window (`<window>`)

Automation role: window. Text source: title. Children: single.

Prop	Type	Default	Applied
`title`	string	none	createAndUpdate
`defaultWidth`	int	480	create
`defaultHeight`	int	320	create
`tabGroup`	string	none	create
`toolbarStyle`	unified \| unifiedCompact \| expanded \| preference	unified	create
`frameAutosaveName`	string	none	create
`density`	standard \| compact	standard	create
`testID`	string	none	meta

toolbarStyle, frameAutosaveName, and density shape the macOS unified toolbar and window chrome; see Windows & Chrome for what each one does on each platform.

Event	Handler	Payload
`alertResult`	`onAlertResult`	data
`openFileResult`	`onOpenFileResult`	data
`saveFileResult`	`onSaveFileResult`	data
`newTabRequested`	`onNewTabRequested`	data
`closed`	`onClosed`	data
`focused`	`onFocused`	checked
`sizeChanged`	`onSizeChanged`	data

Imperative commands (via sendCommand(ref.current, …)): showAlert, openFile, saveFile, showAbout, showTabOverview, present. See Dialogs and Native Tabs.

Box (`<box>`)

Automation role: group. Text source: none. Children: multi.

Prop	Type	Default	Applied
`orientation`	vertical \| horizontal	vertical	create
`spacing`	int	-1	createAndUpdate
`testID`	string	none	meta

Event	Handler	Payload
`hoverChanged`	`onHoverChanged`	checked

spacing’s default, -1, is the “platform standard” sentinel: 6 on the GTK backend (the Adwaita gutter), 8 on the AppKit backend. Any non-negative value is used verbatim. See Spacing scale for Spacing/ContentMargin, the typed export built on the same platform-standard numbers.

Label (`<label>`)

Automation role: label. Text source: text. Children: none.

Prop	Type	Default	Applied
`text`	string	(empty)	create
`ellipsize`	bool	false	create
`testID`	string	none	meta

Button (`<button>`)

Automation role: button. Text source: label. Children: none.

Prop	Type	Default	Applied
`label`	string	Button	create
`testID`	string	none	meta
`iconName`	string	none	create
`labelAlign`	start \| center \| end	center	create
`ellipsize`	bool	false	create
`tooltip`	string	none	createAndUpdate
`prominent`	bool	false	createAndUpdate
`badge`	string	none	createAndUpdate
`size`	small \| regular \| large	regular	createAndUpdate

prominent, badge, and size render natively on both backends; see Styling & Design Language for how they map onto each platform’s controls.

Event	Handler	Payload
`clicked`	`onClick`	none
`hoverChanged`	`onHoverChanged`	checked

TextInput (`<textinput>`)

Automation role: textbox. Text source: text. Children: none.

Prop	Type	Default	Applied
`text`	string	(empty)	createAndUpdate
`placeholder`	string	none	createAndUpdate
`editable`	bool	true	createAndUpdate
`testID`	string	none	meta

Event	Handler	Payload
`changed`	`onChanged`	text
`activate`	`onActivate`	text

TextArea (`<textarea>`)

Automation role: textbox. Text source: text. Children: none.

Prop	Type	Default	Applied
`text`	string	(empty)	createAndUpdate
`minContentHeight`	int	120	create
`testID`	string	none	meta

Event	Handler	Payload
`changed`	`onChanged`	text

An empty TextArea collapses to 0 logical height, which fails the automation actionability check until it has content or explicit sizing. See Automation Socket.

Checkbox (`<checkbox>`)

Automation role: checkbox. Text source: label. Children: none.

Prop	Type	Default	Applied
`checked`	bool	false	createAndUpdate
`label`	string	(empty)	createAndUpdate
`testID`	string	none	meta

Event	Handler	Payload
`toggled`	`onToggled`	checked

Radio (`<radio>`)

Automation role: radio. Text source: label. Children: none.

Prop	Type	Default	Applied
`group`	string	none	create
`checked`	bool	false	createAndUpdate
`label`	string	(empty)	createAndUpdate
`testID`	string	none	meta

Event	Handler	Payload
`toggled`	`onToggled`	checked

Select (`<select>`)

Automation role: combobox. Text source: none. Children: none.

Prop	Type	Default	Applied
`options`	stringList	none	create
`selectedIndex`	int	0	createAndUpdate
`testID`	string	none	meta

Event	Handler	Payload
`selectionChanged`	`onSelectionChanged`	index

options is create-only in v1.

Slider (`<slider>`)

Automation role: slider. Text source: none. Children: none.

Prop	Type	Default	Applied
`min`	float	0	create
`max`	float	100	create
`step`	float	1	create
`value`	float	0	createAndUpdate
`orientation`	horizontal \| vertical	horizontal	create
`testID`	string	none	meta

Event	Handler	Payload
`valueChanged`	`onValueChanged`	value

ProgressBar (`<progressbar>`)

Automation role: progressbar. Text source: none. Children: none.

Prop	Type	Default	Applied
`fraction`	float	0	createAndUpdate
`testID`	string	none	meta

Image (`<image>`)

Automation role: image. Text source: none. Children: none.

Prop	Type	Default	Applied
`path`	string	none	createAndUpdate
`iconName`	string	none	createAndUpdate
`symbolScale`	small \| medium \| large	medium	create
`symbolWeight`	regular \| medium \| semibold \| bold	regular	create
`symbolRenderingMode`	monochrome \| hierarchical \| multicolor	monochrome	create
`testID`	string	none	meta

symbolScale/symbolWeight/symbolRenderingMode configure the resolved SF Symbol on macOS and are inert on GTK; see Icons.

ScrollView (`<scrollview>`)

Automation role: scrollarea. Text source: none. Children: single.

Prop	Type	Default	Applied
`minContentHeight`	int	0	create
`hscroll`	auto \| never	auto	create
`testID`	string	none	meta

Separator (`<separator>`)

Automation role: separator. Text source: none. Children: none.

Prop	Type	Default	Applied
`orientation`	horizontal \| vertical	horizontal	create
`testID`	string	none	meta

Spinner (`<spinner>`)

Automation role: spinner. Text source: none. Children: none.

Prop	Type	Default	Applied
`spinning`	bool	true	createAndUpdate
`testID`	string	none	meta

TabView (`<tabview>`)

Automation role: tablist. Text source: none. Children: multi.

Prop	Type	Default	Applied
`selectedIndex`	int	0	createAndUpdate
`testID`	string	none	meta

Attached props (set on children):

Prop	Type	Default
`tabLabel`	string	(empty)
`tabIcon`	string	(empty)

Attached props apply at attach time only. Changing one after mount is a no-op. selectedIndex takes effect on update; initial page is 0.

On Linux this renders as an AdwViewSwitcher over an AdwViewStack (the modern in-window view switcher), on macOS as an NSTabView. One documented asymmetry: AdwViewStack cannot insert a page at an index, so inserting a page between existing siblings lands it at the END on Linux (insertBefore degenerates to append); macOS honors the position. tabIcon names the page icon shown in the switcher on Linux; document-style tabs remain the <window tabGroup> path.

Grid (`<grid>`)

Automation role: grid. Text source: none. Children: multi.

Prop	Type	Default	Applied
`testID`	string	none	meta

Attached props (set on children):

Prop	Type	Default
`gridRow`	int	0
`gridColumn`	int	0
`gridRowSpan`	int	1
`gridColumnSpan`	int	1

Attached props apply at attach time only. Changing one after mount is a no-op.

ListView (`<listview>`)

Automation role: list. Text source: none. Children: none.

Prop	Type	Default	Applied
`items`	stringList	none	createAndUpdate
`selectedIndex`	int	-1	createAndUpdate
`emptyIconName`	string	none	createAndUpdate
`emptyTitle`	string	none	createAndUpdate
`emptyDescription`	string	none	createAndUpdate
`testID`	string	none	meta

Event	Handler	Payload
`rowActivated`	`onRowActivated`	index

The three empty* props swap in platform empty-state chrome when items is empty; see Native empty states.

itemCount (reported by getTree) is the row count, never a walk of GTK’s recycled row widgets. React item-template components, rendering arbitrary JSX per row, are not implemented. Today <listview> renders native string rows only.

WebView (`<webview>`)

Automation role: webview. Text source: none. Children: none.

Prop	Type	Default	Applied
`url`	string	(empty)	createAndUpdate
`testID`	string	none	meta

Event	Handler	Payload
`navigate`	`onNavigate`	text
`titleChanged`	`onTitleChanged`	text
`loadingChanged`	`onLoadingChanged`	checked
`backAvailable`	`onBackAvailable`	checked
`forwardAvailable`	`onForwardAvailable`	checked
`loadProgress`	`onLoadProgress`	value
`loadFailed`	`onLoadFailed`	data
`newWindow`	`onNewWindow`	text
`downloadRequested`	`onDownloadRequested`	data
`javaScriptResult`	`onJavaScriptResult`	data

Imperative commands (via sendCommand(ref.current, …)): goBack, goForward, reload, stop, executeJavaScript, setZoom, setUserAgent, openDevTools. See WebView.

NativeView (`<nativeview>`)

Automation role: custom. Text source: none. Children: none (an opaque leaf).

Prop	Type	Default	Applied
`viewKind`	string	none	create
`props`	string	`{}`	createAndUpdate
`testID`	string	none	meta

Event	Handler	Payload
`nativeEvent`	`onNativeEvent`	data

The generic host for an app-owned native plugin widget. Apps use defineNativeComponent rather than this intrinsic directly. See Native Modules for the plugin ABI, build config, and a working example.

SplitView (`<splitview>`)

Automation role: group. Text source: none. Children: multi.

Prop	Type	Default	Applied
`sidebarWidth`	float	0	create
`collapsed`	bool	false	createAndUpdate
`listWidth`	float	0	create
`breakpoint`	int	0	create
`testID`	string	none	meta

Attached props (set on children):

Prop	Type	Default
`slot`	enum (`sidebar` \| `content` \| `list`)	content

Attached props apply at attach time only. Changing one after mount is a no-op. See Windows & Chrome for how this renders on each platform, and Split Views for the three-pane (list slot) pattern.

HeaderBar (`<headerbar>`)

Automation role: toolbar. Text source: title. Children: multi.

Prop	Type	Default	Applied
`title`	string	(empty)	create
`subtitle`	string	none	createAndUpdate
`showTitleButtons`	bool	true	create
`canGoBack`	bool	false	createAndUpdate
`canGoForward`	bool	false	createAndUpdate
`testID`	string	none	meta

Event	Handler	Payload
`back`	`onBack`	none
`forward`	`onForward`	none

Setting either canGoBack or canGoForward opts a headerbar into a pair of native back/forward buttons (a header with neither prop set gets none); each prop only enables/disables its own button, and back/forward fire when the user clicks one.

Attached props (set on children):

Prop	Type	Default
`slot`	enum (`start` \| `end`)	start

Attached props apply at attach time only. Changing one after mount is a no-op. title is create-only, so key the widget on the title if it needs to change (see App Model).

ToolbarView (`<toolbarview>`)

Automation role: group. Text source: none. Children: multi.

Prop	Type	Default	Applied
`topBarStyle`	flat \| raised \| raised-border	flat	create
`bottomBarStyle`	flat \| raised \| raised-border	flat	create
`extendContentToTopEdge`	bool	false	create
`testID`	string	none	meta

Attached props (set on children):

Prop	Type	Default
`slot`	enum	content

Attached props apply at attach time only. Changing one after mount is a no-op.

SearchInput (`<searchinput>`)

Automation role: textbox. Text source: text. Children: none.

Prop	Type	Default	Applied
`text`	string	(empty)	createAndUpdate
`placeholder`	string	none	createAndUpdate
`testID`	string	none	meta

Event	Handler	Payload
`changed`	`onChanged`	text
`activate`	`onActivate`	text

SourceList (`<sourcelist>`)

Automation role: list. Text source: none. Children: none.

Prop	Type	Default	Applied
`items`	objectList	none	createAndUpdate
`selectedIndex`	int	-1	createAndUpdate
`emptyIconName`	string	none	createAndUpdate
`emptyTitle`	string	none	createAndUpdate
`emptyDescription`	string	none	createAndUpdate
`testID`	string	none	meta

Event	Handler	Payload
`selectionChanged`	`onSelectionChanged`	index
`rowActivated`	`onRowActivated`	index

Menubar (`<menubar>`)

Automation role: menubar. Text source: none. Children: multi (<menu> elements). Declared as a child of <window>, alongside the content child. See Menu Bar for platform rendering (real NSApp.mainMenu on macOS, primary hamburger menu on GNOME).

Prop	Type	Default	Applied
`defaults`	bool	true	create
`testID`	string	none	meta

Menu (`<menu>`)

Automation role: menu. Text source: label. Children: multi (<menuitem> elements).

Prop	Type	Default	Applied
`label`	string	(empty)	create
`testID`	string	none	meta

MenuItem (`<menuitem>`)

Automation role: menuitem. Text source: label. Children: none. An item has either a role (native behavior) or an onSelect handler; if both are set, onSelect wins.

Prop	Type	Default	Applied
`label`	string	(empty)	create
`iconName`	string	none	create
`iconVisible`	bool	false	create
`accelerator`	string	none	create
`role`	none \| separator \| about \| settings \| quit \| undo \| redo \| cut \| copy \| paste \| delete \| selectAll \| close \| minimize \| zoom \| fullscreen	none	create
`enabled`	bool	true	createAndUpdate
`testID`	string	none	meta

Event	Handler	Payload
`selected`	`onSelect`	none

iconVisible opts an item’s iconName back in on macOS 27, where menu-item symbol images are hidden by default; see Icons.

CommandPalette (`<commandpalette>`)

Automation role: dialog. Text source: none. Children: none.

Prop	Type	Default	Applied
`open`	bool	false	createAndUpdate
`placeholder`	string	none	createAndUpdate
`query`	string	(empty)	createAndUpdate
`items`	objectList (`CommandPaletteItem[]`)	none	createAndUpdate
`testID`	string	none	meta

Event	Handler	Payload
`queryChanged`	`onQueryChanged`	text
`activate`	`onActivate`	text
`submit`	`onSubmit`	text
`cancel`	`onCancel`	none

A controlled Cmd-K style overlay: the app owns query/items and does all filtering and ranking, the widget only renders rows and reports interaction. See Command Palette for the full pattern, platform presentation, and automation notes.

Widget Reference

Window (<window>)

Box (<box>)

Label (<label>)

Button (<button>)

TextInput (<textinput>)

TextArea (<textarea>)

Checkbox (<checkbox>)

Radio (<radio>)

Select (<select>)

Slider (<slider>)

ProgressBar (<progressbar>)

Image (<image>)

ScrollView (<scrollview>)

Separator (<separator>)

Spinner (<spinner>)

TabView (<tabview>)

Grid (<grid>)

ListView (<listview>)

WebView (<webview>)

NativeView (<nativeview>)

SplitView (<splitview>)

HeaderBar (<headerbar>)

ToolbarView (<toolbarview>)

SearchInput (<searchinput>)

SourceList (<sourcelist>)

Menubar (<menubar>)

Menu (<menu>)

MenuItem (<menuitem>)

CommandPalette (<commandpalette>)

Window (`<window>`)

Box (`<box>`)

Label (`<label>`)

Button (`<button>`)

TextInput (`<textinput>`)

TextArea (`<textarea>`)

Checkbox (`<checkbox>`)

Radio (`<radio>`)

Select (`<select>`)

Slider (`<slider>`)

ProgressBar (`<progressbar>`)

Image (`<image>`)

ScrollView (`<scrollview>`)

Separator (`<separator>`)

Spinner (`<spinner>`)

TabView (`<tabview>`)

Grid (`<grid>`)

ListView (`<listview>`)

WebView (`<webview>`)

NativeView (`<nativeview>`)

SplitView (`<splitview>`)

HeaderBar (`<headerbar>`)

ToolbarView (`<toolbarview>`)

SearchInput (`<searchinput>`)

SourceList (`<sourcelist>`)

Menubar (`<menubar>`)

Menu (`<menu>`)

MenuItem (`<menuitem>`)

CommandPalette (`<commandpalette>`)