Intro

Gallery

Hosting

Learn

Components

API Reference

Onboarding

Getting Started

Tutorial

Hosting

Reflex Deploy

Self Hosting

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

rx.select.root(
    rx.select.trigger(),
    rx.select.content(
        rx.select.group(
            rx.select.label("Fruits"),
            rx.select.item("Orange", value="orange"),
            rx.select.item("Apple", value="apple"),
            rx.select.item(
                "Grape", value="grape", disabled=True
            ),
        ),
        rx.select.separator(),
        rx.select.group(
            rx.select.label("Vegetables"),
            rx.select.item("Carrot", value="carrot"),
            rx.select.item("Potato", value="potato"),
        ),
    ),
    default_value="apple",
)

Usage

Disabling

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

rx.select.root(
    rx.select.trigger(placeholder="Select a Fruit"),
    rx.select.content(
        rx.select.group(
            rx.select.item("Apple", value="apple"),
            rx.select.item(
                "Grape", value="grape", disabled=True
            ),
            rx.select.item("Pineapple", value="pineapple"),
        ),
    ),
)

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

rx.select.root(
    rx.select.trigger(placeholder="This is Disabled"),
    rx.select.content(
        rx.select.group(
            rx.select.item("Apple", value="apple"),
            rx.select.item("Grape", value="grape"),
        ),
    ),
    disabled=True,
)

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.

rx.select.root(
    rx.select.trigger(placeholder="pick a fruit"),
    rx.select.content(
        rx.select.group(
            rx.select.item("Apple", value="apple"),
            rx.select.item("Grape", value="grape"),
        ),
    ),
)

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.

rx.select.root(
    rx.select.trigger(),
    rx.select.content(
        rx.select.group(
            rx.select.item("Apple", value="apple"),
            rx.select.item("Grape", value="grape"),
        ),
    ),
    default_value="apple",
)

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.

class SelectState2(rx.State):
    values: list[str] = ["apple", "grape", "pear"]

    value: str = ""

    def choose_randomly(self):
        """Change the select value var."""
        original_value = self.value
        while self.value == original_value:
            self.value = random.choice(self.values)


def select_example2():
    return rx.vstack(
        rx.select.root(
            rx.select.trigger(placeholder="No Selection"),
            rx.select.content(
                rx.select.group(
                    rx.foreach(
                        SelectState2.values,
                        lambda x: rx.select.item(
                            x, value=x
                        ),
                    )
                ),
            ),
            value=SelectState2.value,
            on_change=SelectState2.set_value,
        ),
        rx.button(
            "Choose Randomly",
            on_click=SelectState2.choose_randomly,
        ),
        rx.button(
            "Reset", on_click=SelectState2.set_value("")
        ),
    )

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.

class SelectState8(rx.State):
   is_open: bool = False
   
def select_example8():    
   return rx.flex(
       rx.select.root(
           rx.select.trigger(placeholder="No Selection"),
           rx.select.content(
               rx.select.group(
                   rx.select.item("Apple", value="apple"),
                   rx.select.item("Grape", value="grape"),
               ),
           ),
           open=SelectState8.is_open,
           on_open_change=SelectState8.set_is_open,
       ),
       rx.button("Toggle", on_click=SelectState8.set_is_open(~SelectState8.is_open)),
       spacing="2",
   )

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

{}

class FormSelectState(rx.State):
    form_data: dict = {}

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


def form_select():
    return rx.flex(
        rx.form.root(
            rx.flex(
                rx.select.root(
                    rx.select.trigger(),
                    rx.select.content(
                        rx.select.group(
                            rx.select.label("Fruits"),
                            rx.select.item(
                                "Orange", value="orange"
                            ),
                            rx.select.item(
                                "Apple", value="apple"
                            ),
                            rx.select.item(
                                "Grape", value="grape"
                            ),
                        ),
                        rx.select.separator(),
                        rx.select.group(
                            rx.select.label("Vegetables"),
                            rx.select.item(
                                "Carrot", value="carrot"
                            ),
                            rx.select.item(
                                "Potato", value="potato"
                            ),
                        ),
                    ),
                    default_value="apple",
                    name="select",
                ),
                rx.button("Submit"),
                width="100%",
                direction="column",
                spacing="2",
            ),
            on_submit=FormSelectState.handle_submit,
            reset_on_submit=True,
        ),
        rx.divider(size="4"),
        rx.heading("Results"),
        rx.text(FormSelectState.form_data.to_string()),
        width="100%",
        direction="column",
        spacing="2",
    )

Real World Example

Reflex Swag

$99

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

Color

Size

rx.card(
    rx.flex(
        rx.image(
            src="/reflex_banner.png",
            width="100%",
            height="auto",
        ),
        rx.flex(
            rx.heading(
                "Reflex Swag", size="4", margin_bottom="4px"
            ),
            rx.heading(
                "$99", size="6", margin_bottom="4px"
            ),
            direction="row",
            justify="between",
            width="100%",
        ),
        rx.text(
            "Reflex swag with a sense of nostalgia, as if they carry whispered tales of past adventures",
            size="2",
            margin_bottom="4px",
        ),
        rx.divider(size="4"),
        rx.flex(
            rx.flex(
                rx.text(
                    "Color",
                    size="2",
                    margin_bottom="4px",
                    color_scheme="gray",
                ),
                rx.select.root(
                    rx.select.trigger(),
                    rx.select.content(
                        rx.select.group(
                            rx.select.item(
                                "Light", value="light"
                            ),
                            rx.select.item(
                                "Dark", value="dark"
                            ),
                        ),
                    ),
                    default_value="light",
                ),
                direction="column",
            ),
            rx.flex(
                rx.text(
                    "Size",
                    size="2",
                    margin_bottom="4px",
                    color_scheme="gray",
                ),
                rx.select.root(
                    rx.select.trigger(),
                    rx.select.content(
                        rx.select.group(
                            rx.select.item(
                                "24", value="24"
                            ),
                            rx.select.item(
                                "26", value="26"
                            ),
                            rx.select.item(
                                "28",
                                value="28",
                                disabled=True,
                            ),
                            rx.select.item(
                                "30", value="30"
                            ),
                            rx.select.item(
                                "32", value="32"
                            ),
                            rx.select.item(
                                "34", value="34"
                            ),
                            rx.select.item(
                                "36", value="36"
                            ),
                        ),
                    ),
                    default_value="30",
                ),
                direction="column",
            ),
            rx.button(rx.icon(tag="plus"), "Add"),
            align="end",
            justify="between",
            spacing="2",
            width="100%",
        ),
        width="15em",
        direction="column",
        spacing="2",
    ),
)

API Reference

HighLevelSelect

High level wrapper for the Select component.

Prop	Type	Description
`items`	List	The items of the select.
`placeholder`	str	The placeholder of the select.
`label`	str	The label of the select.
`color_scheme`	Literal	The color of the select.
`high_contrast`	bool	Whether to render the select with higher contrast color against background.
`variant`	Literal	The variant of the select.
`radius`	Literal	The radius of the select.
`width`	str	The width of the select.
`position`	Literal	The positioning mode to use. Default is "item-aligned".
`size`	Literal	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

Trigger	Description
`on_open_change`	The on_open_change event handler is called when the open state of the component changes.
`on_change`	The on_change event handler is called when the value or checked state of the component changes.

SelectRoot

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

Prop	Type	Description
`size`	Literal	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

Trigger	Description
`on_open_change`	The on_open_change event handler is called when the open state of the component changes.
`on_change`	The on_change event handler is called when the value or checked state of the component changes.

SelectTrigger

The button that toggles the select.

Prop	Type	Description
`variant`	Literal	Variant of the select trigger
`color_scheme`	Literal	The color of the select trigger
`radius`	Literal	The radius of the select trigger
`placeholder`	str	The placeholder of the select trigger

Event Triggers

See the full list of default event triggers

SelectContent

The component that pops out when the select is open.

Prop	Type	Description
`variant`	Literal	The variant of the select content
`color_scheme`	Literal	The color of the select content
`high_contrast`	bool	Whether to render the select content with higher contrast color against background
`position`	Literal	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	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	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

Trigger	Description
`on_close_auto_focus`	The on_close_auto_focus event handler is called when focus moves to the trigger after closing. It can be prevented by calling event.preventDefault.
`on_escape_key_down`	The on_escape_key_down event handler is called when the escape key is down. It can be prevented by calling event.preventDefault.
`on_pointer_down_outside`	The on_pointer_down_outside event handler is called when a pointer event occurs outside the bounds of the component. It can be prevented by calling event.preventDefault.