Skip to main content
Select dropdowns let users pick one option from a collapsible list. The selected option’s value string is stored in client state, accessible via .rx.

​
Basic Usage

A Select is a container — use the with block to add SelectOption children. Each option needs a value (what gets stored) and a label (what the user sees):

​
Pre-selected Option

Mark an option as selected=True to have it chosen when the component first renders:

​
Sizes

Selects come in two sizes. The "sm" variant is useful when space is tight or when embedding a select alongside other compact controls:

​
With Label

Pair a Select with a Label in a Column for a standard form field pattern:

​
Disabled State

​
Disabled Options

Individual options can be disabled while the rest of the dropdown remains interactive. Disabled options appear dimmed and cannot be selected:

​
Invalid State

Set invalid=True to flag a select with error styling. Pair it with a Label in a form layout to signal that a selection is required or incorrect:

​
Option Groups

Organize long option lists into labeled sections with SelectGroup and SelectLabel. Use SelectSeparator to add visual dividers between groups:

​
Reading the Value

Use .rx to get a reactive reference to the selected option’s value string. When the user picks an option, anything bound to .rx updates automatically: Pick an option and the text updates instantly. The .rx reference holds the value string of whichever option is selected — "magrathea", "betelgeuse", etc. — not the display label.

​
Actions

The on_change parameter fires actions when the selection changes. Inside the action, $event holds the newly selected value string: This is different from .rx — here we’re transforming the value before storing it (prepending “You chose: ”). For simple “show the current selection” cases, .rx is the better approach.

​
API Reference

Select Parameters

​
placeholder
str | None
default:"None"
Placeholder text shown when no option is selected.
​
name
str | None
default:"None"
State key for the selected value. Auto-generated if not provided.
​
size
str
default:"default"
Select size: "default", "sm".
​
side
str | None
default:"None"
Which side of the trigger the dropdown appears on: "top", "right", "bottom", "left".
​
align
str | None
default:"None"
Alignment of the dropdown relative to the trigger: "start", "center", "end".
​
disabled
bool
default:"False"
Whether the select is non-interactive.
​
required
bool
default:"False"
Whether a selection is required for form submission.
​
invalid
bool
default:"False"
Whether the select shows error styling (red border).
​
on_change
Action | list[Action] | None
default:"None"
Action(s) to execute when the selection changes. $event is the value string of the selected option.
​
css_class
str | None
default:"None"
Additional Tailwind CSS classes.

SelectGroup Parameters

​
css_class
str | None
default:"None"
Additional Tailwind CSS classes.

SelectLabel Parameters

​
label
str
required
Display text for the group header.
​
css_class
str | None
default:"None"
Additional Tailwind CSS classes.

SelectSeparator Parameters

​
css_class
str | None
default:"None"
Additional Tailwind CSS classes.

SelectOption Parameters

​
value
str
required
The value stored in state when this option is selected.
​
label
str
required
Display text shown to the user.
​
selected
bool
default:"False"
Whether this option is initially selected.
​
disabled
bool
default:"False"
Whether this option is non-interactive.
​
css_class
str | None
default:"None"
Additional Tailwind CSS classes.

​
Protocol Reference

Select
{
  "type": "Select",
  "children?": "[Component]",
  "let?": "object",
  "name?": "string",
  "placeholder?": "string",
  "size?": "sm | default",
  "side?": "top | right | bottom | left",
  "align?": "start | center | end",
  "disabled?": false,
  "required?": false,
  "invalid?": false,
  "onChange?": "Action | Action[]",
  "cssClass?": "string"
}
SelectGroup
{
  "type": "SelectGroup",
  "children?": "[Component]",
  "cssClass?": "string"
}
SelectLabel
{
  "type": "SelectLabel",
  "label": "string (required)",
  "cssClass?": "string"
}
SelectSeparator
{
  "type": "SelectSeparator",
  "cssClass?": "string"
}
SelectOption
{
  "type": "SelectOption",
  "value": "string (required)",
  "label": "string (required)",
  "selected?": false,
  "disabled?": false,
  "cssClass?": "string"
}
For the complete protocol schema, see Select, SelectGroup, SelectLabel, SelectSeparator, SelectOption.