Skip to main content

​
Import

from reflex_ui import select

​
Description

A custom select dropdown component with searchable items, size variants, and extensive customization options.

​
Basic Usage

# High-level API
select(
    items=["Option 1", "Option 2", "Option 3"],
    placeholder="Select an option",
    size="md"
)

# With value binding
select(
    items=State.options,
    value=State.selected,
    on_value_change=State.set_selected
)

​
High-Level Props

​
items
Var[list[str]] | list[str]
required
List of items to display in the select dropdown.
​
placeholder
Var[str] | str
Placeholder text to display when no item is selected.
​
size
Literal['xs', 'sm', 'md', 'lg', 'xl'] | Var[...]
default:"md"
Size of the select component.

​
Root Props

​
name
Var[str] | str
Identifies the field when a form is submitted.
​
value
Any | Var[Any]
The controlled value of the select.
​
default_value
Any | Var[Any]
The uncontrolled value when initially rendered.
​
disabled
Var[bool] | bool
default:"False"
Whether the component should ignore user interaction.
​
read_only
Var[bool] | bool
default:"False"
Whether the user should be unable to choose a different option.
​
required
Var[bool] | bool
default:"False"
Whether the user must choose a value before submitting a form.
​
multiple
Var[bool] | bool
default:"False"
Whether multiple items can be selected.
​
modal
Var[bool] | bool
default:"True"
Whether the select enters a modal state when open, locking scroll and disabling outside interactions.
​
open
Var[bool] | bool
Whether the select popup is currently open (controlled).
​
default_open
Var[bool] | bool
Whether the select popup is initially open (uncontrolled).

​
Event Handlers

​
on_value_change
EventType[()] | EventType[str]
Callback fired when the value changes.
​
on_open_change
EventType[()] | EventType[bool]
Event handler called when the select popup is opened or closed.
​
on_open_change_complete
EventType[()] | EventType[bool]
Event handler called after animations complete when popup is opened or closed.

​
Positioner Props

​
side
Literal['bottom', 'inline-end', 'inline-start', 'left', 'right', 'top'] | Var[...]
default:"bottom"
Which side of the anchor element to align the popup against.
​
align
Literal['start', 'center', 'end'] | Var[...]
default:"center"
How to align the popup relative to the specified side.
​
side_offset
Var[int] | int
default:"4"
Distance between the anchor and the popup in pixels.
​
align_offset
Var[int] | int
default:"0"
Additional offset along the alignment axis in pixels.
​
align_item_with_trigger
Var[bool] | bool
default:"False"
Whether the positioner overlaps the trigger so selected item aligns with trigger value text.
​
collision_padding
Var[int | list[int]] | int | list[int]
default:"5"
Additional space to maintain from the edge of the collision boundary.
​
sticky
Var[bool] | bool
default:"False"
Whether to maintain the popup in viewport after anchor is scrolled out of view.

​
Size Variants

  • xs - Extra small
  • sm - Small
  • md - Medium (default)
  • lg - Large
  • xl - Extra large

​
Subcomponents

​
select.root

Groups all parts of the select. 
select.root(
    select.trigger(...),
    select.portal(...),
    **props
) -> SelectRoot

​
select.trigger

A button that opens the select menu. 
select.trigger(render_=button(...), **props) -> SelectTrigger

​
select.value

Text label of the currently selected item. 
select.value(placeholder="Choose", **props) -> SelectValue

​
select.icon

Icon that indicates the trigger opens a menu. 
select.icon(arrow_icon, **props) -> SelectIcon

​
select.portal

Moves the popup to a different part of the DOM. 
select.portal(
    select.positioner(...),
    container="body",
    **props
) -> SelectPortal

​
select.positioner

Positions the select menu popup. 
select.positioner(
    select.popup(...),
    side="bottom",
    side_offset=4,
    **props
) -> SelectPositioner

​
select.popup

A container for the select items. 
select.popup(*children, **props) -> SelectPopup

​
select.item

An individual option in the select menu. 
select.item(
    select.item_text("Option"),
    select.item_indicator(icon),
    value="option",
    **props
) -> SelectItem

​
select.item_text

Text label of the select item. 
select.item_text("Label", **props) -> SelectItemText

​
select.item_indicator

Indicates whether the select item is selected. 
select.item_indicator(check_icon, **props) -> SelectItemIndicator

​
select.group

Groups related select items with a label. 
select.group(
    select.group_label("Group"),
    *items,
    **props
) -> SelectGroup

​
select.separator

A separator element. 
select.separator(**props) -> SelectSeparator

​
Class Names Reference

select.class_names.TRIGGER          # Trigger button classes
select.class_names.VALUE            # Value text classes
select.class_names.ICON             # Icon classes
select.class_names.POPUP            # Popup container classes
select.class_names.ITEM             # Item classes
select.class_names.ITEM_INDICATOR   # Item indicator classes
select.class_names.ITEM_TEXT        # Item text classes
select.class_names.GROUP            # Group container classes
select.class_names.GROUP_LABEL      # Group label classes
select.class_names.SEPARATOR        # Separator classes

​
Method Signature

@classmethod
def create(
    cls,
    *children,
    items: Var[list[str]] | list[str] | None = None,
    placeholder: Var[str] | str | None = None,
    size: Literal["lg", "md", "sm", "xl", "xs"] | Var[...] | None = None,
    value: Any | Var[Any] | None = None,
    default_value: Any | Var[Any] | None = None,
    on_value_change: EventType[()] | EventType[str] | None = None,
    disabled: Var[bool] | bool | None = None,
    **props
) -> HighLevelSelect

​
Return Type

HighLevelSelect - Returns a complete select component with trigger, popup, and items.

Build docs developers (and LLMs) love

Get started for freeTalk to us