Dropdown

A component that displays a button that opens a menu with a list of options when clicked. Implements the ARIA menu button pattern for proper accessibility support. The menu can contain various types of items including standard options, checkboxes, radio groups and nested submenus.

Can be controlled or uncontrolled

Supports submenus with configurable reading direction

Supports items, checkable items (single or multiple) with optional indeterminate state

Supports modal and non-modal modes

Customize side, alignment, offsets, collision handling

Optionally render a pointing arrow

Focus is fully managed

Full keyboard navigation

Typeahead support

Dismissing and layering behavior is highly customizable

Example

Architecture

sc-dropdown-root
Slot: default
sc-dropdown-trigger
Slot: default You must place an sc-button here.
sc-button
sc-dropdown-portal
Slot: default
sc-dropdown-content
Slot: default
sc-dropdown-arrow
Slot: default
sc-dropdown-item
Slot: default
sc-dropdown-link-item
Slot: default
sc-dropdown-checkbox
Slot: default
sc-dropdown-checkbox-indicator
Slot: default Place an element here that is rendered when checked.
Slot: indeterminate Place an element here that is rendered when indeterminate.
sc-dropdown-radio-group
Slot: default
sc-dropdown-radio-group-item
Slot: default
sc-dropdown-radio-group-indicator
Slot: default
sc-dropdown-sub
Slot: default
sc-dropdown-sub-trigger
Slot: default You must place an sc-dropdown-item here.
sc-dropdown-item
Slot: default
sc-dropdown-sub-portal
Slot: default
sc-dropdown-sub-content
Slot: default You can place the same elements as in the sc-dropdown-content here.

Reference

  • Root

    The root container that manages the state and behavior of the dropdown system. Coordinates the interaction between trigger and content components, handling events and state management for the entire dropdown hierarchy.

    • Attributes

      • default-open
        boolean
        /
        default: false

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

      • direction
        enum
        /
        default: ltr

        The reading direction of the dropdown. Affects the positioning of submenus and keyboard navigation behavior.

      • modal
        boolean
        /
        default: true

        When true, interaction with elements outside the dropdown will be disabled and only dropdown content will be visible to screen readers.

      • open
        boolean
        /
        default: -

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

    • Events

      • onOpenChange

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

  • Trigger

    A wrapper component that must contain an sc-button. The button controls the visibility of the dropdown content and automatically receives appropriate ARIA attributes for accessibility.

  • Portal

    Renders the dropdown content absolute or into the CSS top layer, ensuring proper stacking context and visibility above other page elements. This ensures consistent rendering and adequate layering of nested dropdowns.

    • Attributes

      • id
        string
        /
        default: -

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

      • position
        enum
        /
        default: fixed

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

  • Content

    The container that holds the dropdown menu items. Manages keyboard interactions, focus behavior and positioning behavior. Implements proper ARIA attributes for accessibility and handles collision detection with viewport boundaries.

    • Attributes

      • align
        enum
        /
        default: start

        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 dropdown content when a visible label is not present.

      • aria-labelled-by
        string
        /
        default: -

        References the ID of the element that labels the dropdown 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.

      • collision-padding
        number
        /
        default: 0

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

      • id
        string
        /
        default: -

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

      • loop
        boolean
        /
        default: false

        When true, keyboard navigation will loop from last item to first and vice versa.

      • side
        enum
        /
        default: bottom

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

      • side-offset
        number
        /
        default: 0

        The distance in pixels between the dialog and its trigger element.

    • Events

      • onClickOutside

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

      • onCloseTransitionEnd

        Event handler called when the closing transition completes.

      • onEscapeKeydown

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

      • onOpenTransitionEnd

        Event handler called when the opening transition completes.

    • Classes

      • bottom

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

      • bottom-in

        Applied when content is positioned at the bottom during the opening transition.

      • bottom-out

        Applied when content is positioned at the bottom during the closing transition.

      • close-transition

        Applied during the closing transition of the dropdown.

      • left

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

      • left-in

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

      • left-out

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

      • open

        Applied when the dropdown is in an open state.

      • open-transition

        Applied during the opening transition of the dropdown.

      • right

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

      • right-in

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

      • right-out

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

      • top

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

      • top-in

        Applied when content is positioned at the top during the opening transition.

      • top-out

        Applied when content is positioned at the top during the closing transition.

  • Arrow

    An optional visual indicator that points to the trigger element. Must be rendered inside sc-dropdown-content or sc-dropdown-sub-content. Helps visually connect the submenu with its trigger element.

    • 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 item within the dropdown menu. Manages selection state and keyboard navigation while providing proper ARIA attributes for accessibility.

    • 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. By default, the typeahead behavior will use the content of the item. Use this when the content is complex, or you have non-textual content inside.

    • Events

      • onSelect

        Event handler called when the item is clicked or on keydown (Space / Enter).

    • Classes

      • disabled

        Applied when the item is in a disabled state.

      • open

        Applied when the item is used as a trigger and its assigned submenu is open.

  • Link Item

    A selectable link item within the dropdown menu. Manages selection state and keyboard navigation while providing proper ARIA attributes for accessibility.

    • Attributes

      • disabled
        boolean
        /
        default: false

        When true, prevents the user from selecting this item.

      • download
        string
        /
        default: -

        Download attribute that is forwarded to the underlying a element.

      • href
        string
        /
        default: -

        Specifies the URL or destination that the link points to. For more information, see the MDN documentation.

      • id
        string
        /
        default: -

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

      • prerender
        enum
        /
        default: -

        Controls the prerendering behavior of the linked content. none disables prerendering, moderate provides balanced prerendering and eager prerenders as soon as possible. For more information see the toddle documentation.

      • rel
        string
        /
        default: noopener noreferrer

        Specifies the relationship between the current document and the linked document. For security best practices and more information, see the MDN documentation.

      • target
        string
        /
        default: _blank

        Determines where the linked content will be displayed. For detailed information about target values and their behaviors, see the MDN documentation.

      • text-value
        string
        /
        default: -

        Optional text used for typeahead purposes. By default, the typeahead behavior will use the content of the item. Use this when the content is complex, or you have non-textual content inside.

    • Events

    • Classes

      • disabled

        Applied when the item is in a disabled state.

  • Checkbox Item

    A menu item that can be checked, unchecked, or set to an indeterminate state. Implements proper ARIA attributes for accessibility and manages its selection state independently.

    • Attributes

      • checked
        boolean
        /
        default: -

        The controlled checked state of the item. Must be used in conjunction with onCheckedChange.

      • disabled
        boolean
        /
        default: false

        When true, prevents the user from interacting with 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. By default, the typeahead behavior will use the content of the item.

    • Events

    • Classes

      • checked

        Applied when the item is in a checked state.

      • disabled

        Applied when the item is in a disabled state.

  • Checkbox Indicator

    Visual indicator that displays when its parent checkbox item is checked or indeterminate. Can be styled directly or used as a wrapper for an icon to provide visual feedback of the item's state.

    • Classes

      • checked

        Applied when the parent checkbox item is in a checked state.

      • indeterminate

        Applied when the parent checkbox item is in an indeterminate state.

  • Radio Group

    A container for grouping multiple radio items. Ensures that only one item in the group can be selected at a time, maintaining proper ARIA attributes for accessibility.

    • Attributes

      • value
        string
        /
        default: -

        The value of the currently selected radio item in the group. Must be used in conjunction with onValueChange.

    • Events

      • onValueChange

        Event handler called when the selected value in the radio group changes.

  • Radio Group Item

    A selectable item within a radio group that can only be selected exclusively within its group. Implements proper ARIA attributes for accessibility and manages its selection state within the group context.

    • 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. By default, the typeahead behavior will use the content of the item.

      • value
        string
        /
        default: -

        The unique value of the item. Used to identify the selected item within the radio group.

    • Events

      • onSelect

        Event handler called when the radio item is selected.

    • Classes

      • checked

        Applied when the radio item is in a selected state.

      • disabled

        Applied when the radio item is in a disabled state.

  • Radio Group Indicator

    Visual indicator that displays when its parent radio item is selected. Can be styled directly or used as a wrapper for an icon to provide visual feedback of the selection state.

    • Classes

      • checked

        Applied when the parent radio item is in a selected state.

  • Sub

    Container component that manages the state and behavior of a submenu. Coordinates the interaction between trigger and content components, enabling nested menu structures.

    • Attributes

      • default-open
        boolean
        /
        default: false

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

      • open
        boolean
        /
        default: -

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

    • Events

      • onOpenChange

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

  • Sub Trigger

    A wrapper component that must contain an sc-dropdown-item. Controls the visibility of its submenu and automatically receives appropriate ARIA attributes for accessibility.

  • Sub Portal

    Renders the submenu content into the CSS top layer, ensuring proper stacking context and visibility above other page elements, including its parent dropdown.

    • Attributes

      • id
        string
        /
        default: -

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

      • position
        enum
        /
        default: fixed

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

  • Sub Content

    The container that holds the submenu content. Manages keyboard interactions and positioning behavior while maintaining proper focus management within the submenu context.

    • Attributes

      • align
        enum
        /
        default: start

        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 submenu content when a visible label is not present.

      • aria-labelled-by
        string
        /
        default: -

        References the ID of the element that labels the submenu 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.

      • collision-padding
        number
        /
        default: 0

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

      • fallback-sides
        string[]
        /
        default: -

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

      • id
        string
        /
        default: -

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

      • loop
        boolean
        /
        default: false

        When true, keyboard navigation will loop from last item to first and vice versa.

      • side-offset
        number
        /
        default: 0

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

    • Events

      • onClickOutside

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

      • onCloseTransitionEnd

        Event handler called when the closing transition completes.

      • onEscapeKeydown

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

      • onOpenTransitionEnd

        Event handler called when the opening transition completes.

    • Classes

      • bottom

        Applied when the dropdown sub content is positioned at the bottom of the trigger.

      • bottom-in

        Applied when content is positioned at the bottom during the opening transition.

      • bottom-out

        Applied when content is positioned at the bottom during the closing transition.

      • close-transition

        Applied during the closing transition of the sub content.

      • left

        Applied when the dropdown sub content is positioned to the left of the trigger.

      • left-in

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

      • left-out

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

      • open

        Applied when the dropdown sub content is in an open state.

      • open-transition

        Applied during the opening transition.

      • right

        Applied when the dropdown sub content is positioned to the right of the trigger.

      • right-in

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

      • right-out

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

      • top

        Applied when the dropdown sub content is positioned at the top of the trigger.

      • top-in

        Applied when content is positioned at the top during the opening transition.

      • top-out

        Applied when content is positioned at the top during the closing transition.

Keyboard

  • Space

    When focus is on the trigger, opens the dropdown. When focus is on a menu item, activates the item or toggles its checked state.

  • Enter

    When focus is on the trigger, opens the dropdown. When focus is on a menu item, activates the item or toggles its checked state.

  • When focus is on the trigger, opens the dropdown and moves focus to the first menu item. When focus is on a menu item, moves focus to the next menu item. When focus is on the last item, moves focus to the first item if loop is enabled.

  • When focus is on the trigger and the dropdown is open, moves focus to the last menu item. When focus is on a menu item, moves focus to the previous menu item. When focus is on the first item, moves focus to the last item if loop is enabled.

  • When focus is on a sc-dropdown-sub-trigger, opens its submenu when direction is ltr, or closes it when direction is rtl.

  • When focus is on a sc-dropdown-sub-trigger, closes its submenu when direction is ltr, or opens it when direction is rtl.

  • Escape

    Closes the dropdown and returns focus to the trigger element.

made for toddle