For AI agents: the complete documentation index is at llms.txt. Markdown versions are available by appending .md or sending Accept: text/markdown.
Square Banner
NewReflex Build On-Prem: A Secure Builder Running in Your Environment. Learn more
Square Banner
Reflex Logo
Docs Logo
Library

/

Forms

/

Select

/

Low

High Level

Low Level

Select

Displays a list of options for the user to pick from, triggered by a button.

Basic Example

Usage

Disabling

It is possible to disable individual items in a select using the disabled prop associated with the rx.select.item.

To prevent the user from interacting with select entirely, set the disabled prop to True on the rx.select.root component.

Setting Defaults

It is possible to set several default values when constructing a select.

The placeholder prop in the rx.select.trigger specifies the content that will be rendered when value or default_value is empty or not set.

The default_value in the rx.select.root specifies the value of the select when initially rendered. The default_value should correspond to the value of a child rx.select.item.

Fully controlled

The on_change event trigger is fired when the value of the select changes. In this example the rx.select_root value prop specifies which item is selected, and this can also be controlled using state and a button without direct interaction with the select component.

Expand

The open prop and on_open_change event trigger work similarly to value and on_change to control the open state of the select. If on_open_change handler does not alter the open prop, the select will not be able to be opened or closed by clicking on the select_trigger.

Expand

Submitting a Form with Select

When a select is part of a form, the name prop of the rx.select.root sets the key that will be submitted with the form data.

The value prop of rx.select.item provides the value to be associated with the name key when the form is submitted with that item selected.

When the required prop of the rx.select.root is True, it indicates that the user must select a value before the form may be submitted.

Results

{}

Expand

Real World Example

Reflex Swag

$99

Reflex swag with a sense of nostalgia, as if they carry whispered tales of past adventures

Color

Size

Expand

API Reference

rx.select.root

Displays a list of options for the user to pick from, triggered by a button.

rx.select.root(
rx.select.trigger(),
rx.select.content(
rx.select.group(
rx.select.item("apple", value="apple"),
rx.select.item("grape", value="grape"),
rx.select.item("pear", value="pear"),
),
),
default_value="pear",
size="1",
disabled=False,
)
size
disabled

Props

PropTypeDescription
size
"1""2""3"

The size of the select trigger.

default_value
str

The value that's selected when the dropdown first renders. Use this when you want the select to start with a specific option but don't need to track the user's choice in app state. The value must match one of the options in the list. If both value and default_value are provided, value takes precedence.

value
str

The currently selected value of the dropdown. When set, the component reflects this value and you must update it via an on_change event handler. Use this when you need the selected value to drive other parts of your app, like filtering a table, updating a chart, or saving to a database. For a simpler pattern where you only need to set the initial value, use default_value instead.

default_open
bool

Whether the dropdown menu is open when the component first renders.

open
bool

Controls whether the dropdown menu is currently open. When set, you must update this prop via an on_open_change event handler. Use this to programmatically open or close the dropdown. For example, opening it automatically when a user clicks a related button elsewhere on the page, or closing it after a successful selection in a multi-step form.

name
str

The name attribute used when the select is submitted as part of an HTML form. This becomes the key in the submitted form data. If omitted, the select's value won't be included in form submissions. See Forms for more on integrating selects with form validation and submission.

disabled
bool

When True, the user cannot interact with the select. The trigger appears in a muted style and clicking has no effect.

required
bool

When True and the select is inside an rx.form.root, the form cannot be submitted until the user selects a value.

Event Triggers

See the full list of default event triggers
TriggerDescription
on_changeFires when the user selects a different option from the dropdown. The handler receives the new value as a string. Use this with `value` to create a fully reactive select bound to state. The event also fires when the value is updated programmatically via state, so it's a reliable signal for any value change, not just user clicks.
on_open_changeFires when the dropdown menu opens or closes. The handler receives a boolean, `True` when opening, `False` when closing. Useful for triggering analytics events, prefetching data for the dropdown options when the menu opens, or animating related UI elements (like a sidebar or tooltip) when the menu appears.

rx.select.trigger

The button that toggles the select.

rx.select.root(
rx.select.trigger(,
variant="classic",
color_scheme="tomato",
radius="none",
),
rx.select.content(
rx.select.group(
rx.select.item("apple", value="apple"),
rx.select.item("grape", value="grape"),
rx.select.item("pear", value="pear"),
),
),
default_value="pear",
)
variant
color_scheme
radius

Props

PropTypeDescription
variant
"classic""surface""soft""ghost"

The visual style of the trigger. Same options and behavior as the variant prop on rx.select.root. Setting it here allows different visual styles between the trigger and content when composing custom selects.

color_scheme
"tomato""red""ruby""crimson""pink""plum""purple""violet""iris""indigo""blue""cyan""teal""jade""green""grass""brown""orange""sky""mint""lime""yellow""amber""gold""bronze""gray"

The text color of the trigger label. Accepts any Reflex color token. Use to make the trigger text stand out. For example, a red trigger color for an error state, or muted gray for a placeholder-like appearance.

radius
"none""small""medium""large""full"

The border radius of the trigger. Same behavior as the radius prop on rx.select.root, but scoped to just the trigger button when using the low-level API.

placeholder
str

The text displayed in the trigger button when no option is selected. Same behavior as the placeholder prop on rx.select.root, but set on the trigger directly in the low-level API. Hidden automatically once a value is selected.

Event Triggers

See the full list of default event triggers

rx.select.content

The component that pops out when the select is open.

rx.select.root(
rx.select.trigger(),
rx.select.content(
rx.select.group(
rx.select.item("apple", value="apple"),
rx.select.item("grape", value="grape"),
rx.select.item("pear", value="pear"),
),
variant="solid",
color_scheme="tomato",
high_contrast=False,
align="start",
),
default_value="pear",
)
variant
color_scheme
high_contrast
align

Props

PropTypeDescription
variant
"solid""soft"

The visual style of the dropdown menu surface.

color_scheme
"tomato""red""ruby""crimson""pink""plum""purple""violet""iris""indigo""blue""cyan""teal""jade""green""grass""brown""orange""sky""mint""lime""yellow""amber""gold""bronze""gray"

Overrides the theme's accent color for the dropdown menu specifically. Affects the highlight color when hovering or arrow-key-navigating through items. Can differ from the trigger's color_scheme for stylistic effect.

high_contrast
bool

When True, increases the contrast inside the dropdown menu. Particularly useful when the menu opens over a busy background.

position
"item-aligned""popper"

Controls how the dropdown menu positions itself relative to the trigger. Same behavior as position on rx.select.root.

side
"top""right""bottom""left"

Which side of the trigger the dropdown should appear on when using position="popper".

side_offset
int

The distance in pixels between the trigger and the dropdown menu when position="popper".

align
"start""center""end"

Horizontal alignment of the dropdown menu relative to the trigger when position="popper".

align_offset
int

Pixel offset for the alignment when position="popper".

Event Triggers

See the full list of default event triggers
TriggerDescription
on_close_auto_focusFired when the select content is closed.
on_escape_key_downFired when the escape key is pressed.
on_pointer_down_outsideFired when a pointer down event happens outside the select content.

rx.select.group

Used to group multiple items.

Props

No component specific props

Event Triggers

See the full list of default event triggers

rx.select.item

The component that contains the select items.

rx.select.root(
rx.select.trigger(),
rx.select.content(
rx.select.group(
rx.select.item("apple", value="apple",
disabled=False,
),
rx.select.item("grape", value="grape",
disabled=False,
),
rx.select.item("pear", value="pear",
disabled=False,
),
),
),
default_value="pear",
)
disabled

Props

PropTypeDescription
value
str

The value associated with this option. Required. When this item is selected, the select's on_change handler receives this value. The display label is set via the item's children. Separating value from label is the main reason to use the low-level Select API instead of the high-level rx.select.

disabled
bool

When True, this specific item cannot be selected. It appears muted and clicking does nothing.

Event Triggers

See the full list of default event triggers

rx.select.label

Used to render the label of a group, it isn't focusable using arrow keys.

Props

No component specific props

Event Triggers

See the full list of default event triggers

rx.select.separator

Used to visually separate items in the Select.

Props

No component specific props

Event Triggers

See the full list of default event triggers
Built with Reflex