> For AI agents: the complete documentation index is at [llms.txt](https://reflex.dev/docs/llms.txt). For a Markdown version, remove the trailing slash from the page URL and append `.md`. The docs home is available at [index.md](http://localhost:3000/docs/index.md). [High Level](https://reflex.dev/docs/library/forms/select/) [Low Level](https://reflex.dev/docs/library/forms/select/low/) # Select Displays a list of options for the user to pick from, triggered by a button. ## Basic Example [Start Building Now!](https://build.reflex.dev/) ## Usage ## Disabling It is possible to disable individual items in a `select` using the `disabled` prop associated with the `rx.select.item`. [Start Building Now!](https://build.reflex.dev/) To prevent the user from interacting with select entirely, set the `disabled` prop to `True` on the `rx.select.root` component. [Start Building Now!](https://build.reflex.dev/) ## 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. [Start Building Now!](https://build.reflex.dev/) 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`. [Start Building Now!](https://build.reflex.dev/) ## 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. [Start Building Now!](https://build.reflex.dev/) 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`. [Start Building Now!](https://build.reflex.dev/) ### 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. [Start Building Now!](https://build.reflex.dev/) ## Results {} ## Real World Example [Start Building Now!](https://build.reflex.dev/) ![Reflex banner image](https://web.reflex-assets.dev/other/reflex_banner.png) ## Reflex Swag ## $99 Reflex swag with a sense of nostalgia, as if they carry whispered tales of past adventures Color Size ## 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 | Prop | Type | Description | | --- | --- | --- | | `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](https://reflex.dev/docs/library/forms/form/) 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](https://reflex.dev/docs/api-reference/event-triggers/) | Trigger | Description | | --- | --- | | `on_change` | Fires 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_change` | Fires 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 | Prop | Type | Description | | --- | --- | --- | | `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](https://reflex.dev/docs/api-reference/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 | Prop | Type | Description | | --- | --- | --- | | `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](https://reflex.dev/docs/api-reference/event-triggers/) | Trigger | Description | | --- | --- | | `on_close_auto_focus` | Fired when the select content is closed. | | `on_escape_key_down` | Fired when the escape key is pressed. | | `on_pointer_down_outside` | Fired 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](https://reflex.dev/docs/api-reference/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 | Prop | Type | Description | | --- | --- | --- | | `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](https://reflex.dev/docs/api-reference/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](https://reflex.dev/docs/api-reference/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](https://reflex.dev/docs/api-reference/event-triggers/)