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

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

Supports modal and non-modal modes

Focus is fully managed

Full keyboard navigation

Typeahead support

Architecture

so-dropdown
Slot: trigger You must place an so-button here.
so-button
Slot: content
so-dropdown-content
Slot: default
so-dropdown-item
Slot: default
so-dropdown-checkbox
Slot: default
so-dropdown-radio-group
Slot: default
so-dropdown-radio-group-item
Slot: default
so-dropdown-sub
Slot: trigger You must place an so-dropdown-item here.
so-dropdown-item
Slot: default
Slot: content
so-dropdown-sub-content
Slot: default You can place the same elements as in the so-dropdown-content here.

Reference

  • Dropdown

    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.

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

  • 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

      • 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 menu content.

  • Item

    An interactive menu item that can trigger an action when selected. Supports disabled states and keyboard navigation with proper ARIA attributes for accessibility.

    • Attributes

      • disabled
        boolean
        /
        default: false

        When true, prevents the user from selecting this item.

      • shortcut
        string
        /
        default: -

        Displays a keyboard shortcut hint for the menu item. This is purely informational and does not trigger the shortcut functionality.

    • Events

      • onSelect

        Event handler called when the item is clicked or has a keydown event (Space or Enter).

  • Checkbox

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

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

    • Events

      • onCheckedChange

        Event handler called when the checked state of the item changes.

  • Radio Group

    A container for grouping multiple radio items. Ensures that only one item in the group can be selected at a time.

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

    • Attributes

      • disabled
        boolean
        /
        default: false

        When true, prevents the user from selecting this 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 user selects the item.

  • Sub

    Container component that manages the state and behavior of a submenu. Coordinates the interaction between trigger and content components.

  • Sub Content

    The container that holds the submenu content. Manages keyboard interactions, positioning behavior and implements proper ARIA attributes for accessibility.

    • Attributes

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

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 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 dropdown sub-trigger, opens its submenu.

  • When focus is on a dropdown sub-trigger, closes its submenu.

  • Escape

    Closes the dropdown and returns focus to the trigger element.

made for toddle