> For AI agents: the complete documentation index is at [llms.txt](https://reflex.dev/docs/llms.txt). Markdown versions are available by appending `.md` or sending `Accept: text/markdown`.

---
components:
  - rx.select
  - rx.select.root
  - rx.select.trigger
  - rx.select.content
  - rx.select.group
  - rx.select.item
  - rx.select.label
  - rx.select.separator

HighLevelSelect: |
  lambda **props: rx.select(["apple", "grape", "pear"], default_value="pear", **props)

SelectRoot: |
  lambda **props: 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",
      **props
  )

SelectTrigger: |
  lambda **props: rx.select.root(
      rx.select.trigger(**props),
      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",
  )

SelectContent: |
  lambda **props: 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"),
          ),
          **props,
      ),
      default_value="pear",
  )

SelectItem: |
  lambda **props: rx.select.root(
      rx.select.trigger(),
      rx.select.content(
          rx.select.group(
              rx.select.item("apple", value="apple", **props),
              rx.select.item("grape", value="grape", **props),
              rx.select.item("pear", value="pear", **props),
          ),
      ),
      default_value="pear",
  )
---

```python exec
import random
import reflex as rx
```

# Select

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

```python demo exec
class SelectState(rx.State):
    value: str = "apple"

    @rx.event
    def change_value(self, value: str):
        """Change the select value var."""
        self.value = value


def select_intro():
    return rx.center(
        rx.select(
            ["apple", "grape", "pear"],
            value=SelectState.value,
            on_change=SelectState.change_value,
        ),
        rx.badge(SelectState.value),
    )
```

```python demo exec
class SelectState3(rx.State):
    values: list[str] = ["apple", "grape", "pear"]

    value: str = "apple"

    def set_value(self, value: str):
        self.value = value

    @rx.event
    def change_value(self):
        """Change the select value var."""
        self.value = random.choice(self.values)


def select_example3():
    return rx.vstack(
        rx.select(
            SelectState3.values,
            value=SelectState3.value,
            on_change=SelectState3.set_value,
        ),
        rx.button("Change Value", on_click=SelectState3.change_value),
    )
```

The `on_open_change` event handler acts in a similar way to the `on_change` and is called when the open state of the select changes.

```python demo
rx.select(
    ["apple", "grape", "pear"],
    on_change=rx.window_alert("on_change event handler called"),
)
```

### Submitting a form using select

The `name` prop is needed to submit with its owning form as part of a name/value pair.

When the `required` prop is `True`, it indicates that the user must select a value before the owning form can be submitted.

```python demo exec
class FormSelectState(rx.State):
    form_data: dict = {}

    @rx.event
    def handle_submit(self, form_data: dict):
        """Handle the form submit."""
        self.form_data = form_data


def select_form_example():
    return rx.card(
        rx.vstack(
            rx.heading("Example Form"),
            rx.form.root(
                rx.flex(
                    rx.select(
                        ["apple", "grape", "pear"],
                        default_value="apple",
                        name="select",
                        required=True,
                    ),
                    rx.button("Submit", flex="1", type="submit"),
                    width="100%",
                    spacing="3",
                ),
                on_submit=FormSelectState.handle_submit,
                reset_on_submit=True,
            ),
            rx.divider(),
            rx.hstack(
                rx.heading("Results:"),
                rx.badge(FormSelectState.form_data.to_string()),
            ),
            align_items="left",
            width="100%",
        ),
        width="50%",
    )
```

### Using Select within a Drawer component

If using within a [Drawer](/docs/library/overlay/drawer) component, set the `position` prop to `"popper"` to ensure the select menu is displayed correctly.

```python demo
rx.drawer.root(
    rx.drawer.trigger(rx.button("Open Drawer")),
    rx.drawer.overlay(z_index="5"),
    rx.drawer.portal(
        rx.drawer.content(
            rx.vstack(
                rx.drawer.close(rx.box(rx.button("Close"))),
                rx.select(["apple", "grape", "pear"], position="popper"),
            ),
            width="20em",
            padding="2em",
            background_color=rx.color("gray", 1),
        ),
    ),
    direction="left",
)
```

## API Reference

### rx.select

High level wrapper for the Select component.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | Literal["1", "2", "3"], Breakpoints[str, Literal["1", "2", "3"]] | - | The size of the select: "1", "2", "3". |
| `default_value` | str | - | The value of the select when initially rendered. Use when you do not need to control the state of the select. |
| `value` | str | - | The controlled value of the select. Should be used in conjunction with on_change. |
| `default_open` | bool | - | The open state of the select when it is initially rendered. Use when you do not need to control its open state. |
| `open` | bool | - | The controlled open state of the select. Must be used in conjunction with on_open_change. |
| `name` | str | - | The name of the select control when submitting the form. |
| `disabled` | bool | - | When True, prevents the user from interacting with select. |
| `required` | bool | - | When True, indicates that the user must select a value before the owning form can be submitted. |
| `items` | Sequence[str] | - | The items of the select. |
| `placeholder` | str | - | The placeholder of the select. |
| `label` | str | - | The label of the select. |
| `color_scheme` | Literal["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 color of the select. |
| `high_contrast` | bool | - | Whether to render the select with higher contrast color against background. |
| `variant` | Literal["classic", "surface", "soft", "ghost"] | - | The variant of the select. |
| `radius` | Literal["none", "small", "medium", "large", "full"] | - | The radius of the select. |
| `width` | str | - | The width of the select. |
| `position` | Literal["item-aligned", "popper"] | - | The positioning mode to use. Default is "item-aligned". |

#### Event Triggers

Base event triggers: https://reflex.dev/docs/api-reference/event-triggers/

Component-specific event triggers:

| Event Trigger | Description |
| --- | --- |
| `on_change` | Fired when the value of the select changes. |
| `on_open_change` | Fired when the select is opened or closed. |

### rx.select.root

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

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | Literal["1", "2", "3"], Breakpoints[str, Literal["1", "2", "3"]] | - | The size of the select: "1", "2", "3". |
| `default_value` | str | - | The value of the select when initially rendered. Use when you do not need to control the state of the select. |
| `value` | str | - | The controlled value of the select. Should be used in conjunction with on_change. |
| `default_open` | bool | - | The open state of the select when it is initially rendered. Use when you do not need to control its open state. |
| `open` | bool | - | The controlled open state of the select. Must be used in conjunction with on_open_change. |
| `name` | str | - | The name of the select control when submitting the form. |
| `disabled` | bool | - | When True, prevents the user from interacting with select. |
| `required` | bool | - | When True, indicates that the user must select a value before the owning form can be submitted. |

#### Event Triggers

Base event triggers: https://reflex.dev/docs/api-reference/event-triggers/

Component-specific event triggers:

| Event Trigger | Description |
| --- | --- |
| `on_change` | Fired when the value of the select changes. |
| `on_open_change` | Fired when the select is opened or closed. |

### rx.select.trigger

The button that toggles the select.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | Literal["classic", "surface", "soft", "ghost"] | - | Variant of the select trigger. |
| `color_scheme` | Literal["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 color of the select trigger. |
| `radius` | Literal["none", "small", "medium", "large", "full"] | - | The radius of the select trigger. |
| `placeholder` | str | - | The placeholder of the select trigger. |

#### Event Triggers

Base event triggers: https://reflex.dev/docs/api-reference/event-triggers/

### rx.select.content

The component that pops out when the select is open.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | Literal["solid", "soft"] | - | The variant of the select content. |
| `color_scheme` | Literal["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 color of the select content. |
| `high_contrast` | bool | - | Whether to render the select content with higher contrast color against background. |
| `position` | Literal["item-aligned", "popper"] | - | The positioning mode to use, item-aligned is the default and behaves similarly to a native MacOS menu by positioning content relative to the active item. popper positions content in the same way as our other primitives, for example Popover or DropdownMenu. |
| `side` | Literal["top", "right", "bottom", "left"] | - | The preferred side of the anchor to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled. Only available when position is set to popper. |
| `side_offset` | int | - | The distance in pixels from the anchor. Only available when position is set to popper. |
| `align` | Literal["start", "center", "end"] | - | The preferred alignment against the anchor. May change when collisions occur. Only available when position is set to popper. |
| `align_offset` | int | - | The vertical distance in pixels from the anchor. Only available when position is set to popper. |

#### Event Triggers

Base event triggers: https://reflex.dev/docs/api-reference/event-triggers/

Component-specific event triggers:

| Event 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.

#### Event Triggers

Base event triggers: https://reflex.dev/docs/api-reference/event-triggers/

### rx.select.item

The component that contains the select items.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | str | - | The value given as data when submitting a form with a name. |
| `disabled` | bool | - | Whether the select item is disabled. |

#### Event Triggers

Base 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.

#### Event Triggers

Base event triggers: https://reflex.dev/docs/api-reference/event-triggers/

### rx.select.separator

Used to visually separate items in the Select.

#### Event Triggers

Base event triggers: https://reflex.dev/docs/api-reference/event-triggers/