Select

A flexible component that allows users to select a value from a list of options. Implements the ARIA listbox pattern for proper accessibility support.

Can be controlled or uncontrolled

Full focus management

Typeahead support

Full keyboard navigation

Supports Right to Left direction

Example

Architecture

sc-select-root
Slot: default
sc-select-trigger
Slot: default You need to place an sc-button here.
sc-button
Slot: default
sc-select-icon
sc-select-portal
Slot: default
sc-select-backdrop
sc-select-content
Slot: default Place your content here if you don't need scroll.
sc-select-arrow
Slot: default You can place an arrow here.
sc-select-item
Slot: default
sc-select-item-indicator
Slot: default
sc-select-item-text
Slot: default
sc-select-scroll-area
Slot: default Place your content here if you need scroll.

Reference

  • Root

    The root container that manages the select's state and behavior. Coordinates the interaction between trigger, content, and optional backdrop components.

    • Attributes

      • default-open
        boolean
        /
        default: false

        The initial open state of the select when rendered. Use when you do not need to control the state of the select.

      • default-value
        any | any[]
        /
        default: -

        The initial selected value when the select is rendered. Use when you do not need to control the selected value.

      • direction
        enum
        /
        default: ltr

        The reading direction of the select component. Affects the positioning of the content and arrow.

      • disabled
        boolean
        /
        default: false

        When true, prevents the user from interacting with the select.

      • name
        string
        /
        default: -

        The name of the select when used within a form. Submitted with its owning form as part of a name/value pair.

      • open
        boolean
        /
        default: false

        The controlled open state of the select component. Must be used in conjunction with onOpenChange.

      • required
        boolean
        /
        default: false

        When true, indicates that a value must be selected before the owning form can be submitted.

      • type
        enum
        /
        default: single

        Defines if the selects acts as a single-select or a multi-select.

      • value
        any | any[]
        /
        default: -

        The controlled value of the select. Must be used in conjunction with onValueChange. If type is set to "multiple", it expects an array.

    • Events

      • onFocusChange

        Event handler called when the currently focused item changes. Includes the value of the item.

      • onOpenChange

        Event handler called when the open state of the select changes.

      • onValueChange

        Event handler called when the selected value changes. Use the "value" key if type is "single", otherwise use the "values" key.

  • Trigger

    A wrapper component that must contain an sc-button. The button controls the visibility of the select content. By default, the content positions itself relative to this trigger.

  • Icon

    A visual indicator typically used to show the current state of the select. Usually displayed as a chevron or arrow.

    • Classes

      • open

        Applied when the select is in an open state.

  • Portal

    Renders the select backdrop and content. If position is set to fixed, the content is placed in the CSS top layer, ensuring proper stacking context and visibility above other page elements.

    • Attributes

      • id
        string
        /
        default: -

        ID that is forwarded to the underlying container for DOM manipulation.

      • position
        enum
        /
        default: absolute

        Determines how the select content will be placed on the page. fixed will prevent clipping, but will slightly lag on scroll events.

  • Backdrop

    An optional overlay that renders behind the select content. Typically used to enhance focus on the select options.

    • Attributes

      • id
        string
        /
        default: -

        ID that is forwarded to the underlying container for DOM manipulation.

    • Classes

      • close-transition

        Applied during the closing transition and removed when fully closed.

      • open

        Applied when the select is in an open state.

      • open-transition

        Applied during the opening transition and removed when fully open.

  • Content

    The container that holds the select options. Manages keyboard interactions and positioning behavior.

    • Attributes

      • align
        enum
        /
        default: center

        The preferred alignment against the trigger. May adjust automatically when collisions occur.

      • align-offset
        number
        /
        default: 0

        The offset in pixels from the start or end alignment positions.

      • aria-label
        string
        /
        default: -

        Accessible label for the select content container.

      • aria-labelled-by
        string
        /
        default: -

        References the ID of the element that labels the select content.

      • arrow-padding
        number
        /
        default: 0

        The padding between the arrow and the edges of the content. Prevents arrow overflow with rounded corners.

      • avoid-collisions
        boolean
        /
        default: true

        When true, automatically adjusts positioning to prevent collisions with viewport boundaries.

      • close-autofocus
        boolean
        /
        default: true

        When true, returns focus to the trigger element after the select closes.

      • collision-padding
        number
        /
        default: 0

        The distance in pixels from viewport edges where collision detection should occur.

      • fallback-sides
        enum[]
        /
        default: -

        Alternative sides to try when the content doesn't fit in its primary position.

      • hide-when-detached
        boolean
        /
        default: false

        When true, hides the content when the trigger element becomes fully obscured.

      • id
        string
        /
        default: -

        ID that is forwarded to the underlying container for DOM manipulation.

      • match-anchor-width
        boolean
        /
        default: false

        If true, the content will have the same width as the anchor.

      • side
        enum
        /
        default: bottom

        The preferred side where the select content should appear relative to its trigger.

      • side-offset
        number
        /
        default: 0

        The distance in pixels between the select content and its trigger element.

      • sticky
        enum
        /
        default: partial

        Controls how the content stays within bounds. partial requires the trigger to be partially visible, while always keeps content in bounds regardless.

      • update-position-strategy
        enum
        /
        default: optimized

        Determines how often position updates occur. Use always sparingly as it updates on every animation frame.

    • Events

      • onClickOutside

        Event handler called when a click occurs outside the select content.

      • onCloseTransitionEnd

        Event handler called when the closing transition completes.

      • onEscapeKeydown

        Event handler called when the Escape key is pressed while the select is active.

      • onOpenTransitionEnd

        Event handler called when the opening transition completes.

    • Classes

      • bottom

        Applied when the select content is positioned at the bottom of the trigger.

      • bottom-in

        Applied when content is positioned at the bottom during opening.

      • bottom-out

        Applied when content is positioned at the bottom during closing.

      • close-transition

        Applied during the closing transition.

      • left

        Applied when the select content is positioned to the left of the trigger.

      • left-in

        Applied when content is positioned on the left side during opening.

      • left-out

        Applied when content is positioned on the left side during closing.

      • open

        Applied when the select is in an open state.

      • open-transition

        Applied during the opening transition.

      • right

        Applied when the select content is positioned to the right of the trigger.

      • right-in

        Applied when content is positioned on the right side during opening.

      • right-out

        Applied when content is positioned on the right side during closing.

      • top

        Applied when the select content is positioned at the top of the trigger.

      • top-in

        Applied when content is positioned at the top during opening.

      • top-out

        Applied when content is positioned at the top during closing.

  • Arrow

    An optional visual indicator that points to the trigger element. Must be rendered inside sc-select-content.

    • Attributes

      • id
        string
        /
        default: -

        ID that is forwarded to the underlying element for DOM manipulation.

    • Classes

      • bottom

        Applied when the arrow is positioned at the bottom of the content.

      • left

        Applied when the arrow is positioned on the left side of the content.

      • right

        Applied when the arrow is positioned on the right side of the content.

      • top

        Applied when the arrow is positioned at the top of the content.

  • Item

    A selectable option within the select content. Manages selection state and keyboard navigation.

    • Attributes

      • disabled
        boolean
        /
        default: false

        When true, prevents the user from selecting this item.

      • id
        string
        /
        default: -

        ID that is forwarded to the underlying element for DOM manipulation.

      • text-value
        string
        /
        default: -

        Optional text used for typeahead purposes. When not provided, the item's content will be used.

      • value
        string
        /
        default: -

        The value associated with this item. This value will be submitted when used within a form.

    • Events

      • onSelect

        Is triggered when the select item is clicked or when it detects a Space or Enter keydown event.

  • Item Indicator

    A visual indicator that shows when an item is selected. Typically rendered as a checkmark or similar icon.

  • Item Text

    The textual content of a select item. Used for typeahead functionality and screen readers.

  • Scroll Area

    A scrollable container that allows scrolling in a select, which is in modal mode. All scrolling outside of this container will be prevented.

    • Attributes

      • id
        string
        /
        default: -

        ID that is forwarded to the underlying element.

Keyboard

  • Space

    When trigger is focused, opens the select. When an item is focused, selects it and closes the select.

  • Enter

    When trigger is focused, opens the select. When an item is focused, selects it and closes the select.

  • Opens the select when trigger is focused and focuses the first item. Moves focus to the next item in the list. If focus is on the last item, moves focus to the first item.

  • Opens the select when trigger is focused and focuses the last item. Moves focus to the previous item in the list. If focus is on the first item, moves focus to the last item.

  • Escape

    Closes the select and returns focus to the trigger element.

made for toddle