Widget Reference

Note

This page is a faithful port of docs/widgets.md, which is generated by tools/codegen.ts from schema/widgets.json (schema version 1). The schema is the source of truth — if this page and the schema ever disagree, the schema wins. Do not hand-edit widget shapes anywhere else.

Window (<window>)

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

Prop	Type	Default	Applied
title	string	—	createAndUpdate
defaultWidth	int	480	create
defaultHeight	int	320	create
testID	string	—	meta

Box (<box>)

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

Prop	Type	Default	Applied
orientation	vertical | horizontal	vertical	create
spacing	int	0	createAndUpdate
testID	string	—	meta

Label (<label>)

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

Prop	Type	Default	Applied
text	string	(empty)	create
testID	string	—	meta

Button (<button>)

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

Prop	Type	Default	Applied
label	string	Button	create
testID	string	—	meta
iconName	string	—	create
labelAlign	start | center | end	center	create

Event	Handler	Payload
clicked	onClick	none

TextInput (<textinput>)

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

Prop	Type	Default	Applied
text	string	(empty)	createAndUpdate
placeholder	string	—	createAndUpdate
editable	bool	true	createAndUpdate
testID	string	—	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	—	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	—	meta

Event	Handler	Payload
toggled	onToggled	checked

Radio (<radio>)

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

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

Event	Handler	Payload
toggled	onToggled	checked

Select (<select>)

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

Prop	Type	Default	Applied
options	stringList	—	create
selectedIndex	int	0	createAndUpdate
testID	string	—	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	—	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	—	meta

Image (<image>)

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

Prop	Type	Default	Applied
path	string	—	createAndUpdate
iconName	string	—	createAndUpdate
testID	string	—	meta

ScrollView (<scrollview>)

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

Prop	Type	Default	Applied
minContentHeight	int	0	create
testID	string	—	meta

Separator (<separator>)

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

Prop	Type	Default	Applied
orientation	horizontal | vertical	horizontal	create
testID	string	—	meta

Spinner (<spinner>)

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

Prop	Type	Default	Applied
spinning	bool	true	createAndUpdate
testID	string	—	meta

TabView (<tabview>)

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

Prop	Type	Default	Applied
selectedIndex	int	0	createAndUpdate
testID	string	—	meta

Attached props (set on children):

Prop	Type	Default
tabLabel	string	(empty)

Attached props are attach-time-only; changing them after mount is a no-op. selectedIndex takes effect on update; initial page is 0.

Grid (<grid>)

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

Prop	Type	Default	Applied
testID	string	—	meta

Attached props (set on children):

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

Attached props are attach-time-only; changing them after mount is a no-op.

ListView (<listview>)

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

Prop	Type	Default	Applied
items	stringList	—	createAndUpdate
selectedIndex	int	-1	createAndUpdate
testID	string	—	meta

Event	Handler	Payload
rowActivated	onRowActivated	index

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 deferred — v1 renders native string rows only.

WebView (<webview>)

Caution

v1 stub — renders a placeholder Label, not a real web view.

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

Prop	Type	Default	Applied
url	string	—	create
testID	string	—	meta

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
testID	string	—	meta

Attached props (set on children):

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

Attached props are attach-time-only; changing them 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
testID	string	—	meta

Attached props (set on children):

Prop	Type	Default
slot	enum (start | end)	start

Attached props are attach-time-only; changing them after mount is a no-op. title is create-only — 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
testID	string	—	meta

SearchInput (<searchinput>)

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

Prop	Type	Default	Applied
text	string	(empty)	createAndUpdate
placeholder	string	—	createAndUpdate
testID	string	—	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	—	createAndUpdate
selectedIndex	int	-1	createAndUpdate
testID	string	—	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	—	meta

Menu (<menu>)

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

Prop	Type	Default	Applied
label	string	(empty)	create
testID	string	—	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	—	create
accelerator	string	—	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	—	meta

Event	Handler	Payload
selected	onSelect	none