Skip to content
StrataKit Docs

DropdownMenu API

Component status:
stable

Import

Section titled “Import”
import { DropdownMenu } from "@stratakit/structures";
// OR
import * as DropdownMenu from "@stratakit/structures/DropdownMenu";
Section titled “DropdownMenu.Provider”

A dropdown menu displays a list of actions or commands when the menu button is clicked.

DropdownMenu is a compound component with subcomponents exposed for different parts.

Example:

<DropdownMenu.Provider>
  <DropdownMenu.Button>Actions</DropdownMenu.Button>


  <DropdownMenu.Content>
    <DropdownMenu.Item label="Add" />
    <DropdownMenu.Item label="Edit" />
    <DropdownMenu.Item label="Delete" />
  </DropdownMenu.Content>
</DropdownMenu.Provider>

Note: DropdownMenu should not be used for navigation; it is only intended for actions.

Section titled “children”
Type: ReactNode (optional)
Section titled “defaultOpen”
Type: boolean | undefined (optional)
Default: false

Whether the content should be visible by default.

Section titled “open”
Type: boolean | undefined (optional)
Default: false

Whether the content is visible.

Section titled “placement”
Type: Placement | undefined (optional)
Default: "bottom-start"
Section titled “setOpen”
Type: ((open: boolean) => void) | undefined (optional)

A callback that gets called when the open state changes.

Section titled “DropdownMenu.Button”
Base element: <button>

The button that triggers the dropdown menu to open. Should be used as a child of DropdownMenu.Provider.

Example:

<DropdownMenu.Button>Actions</DropdownMenu.Button>

By default it will render a solid Button with a disclosure arrow. This can be customized by passing a render prop.

<DropdownMenu.Button
  render={<IconButton variant="ghost" label="More" icon={<Icon href={…} />} />}
/>
Section titled “Additional props”
Section titled “DropdownMenu.Content”
Base element: <div>

The actual “menu” portion containing the items shown within the dropdown.

Should be used as a child of DropdownMenu.Provider.

Should include one or more of DropdownMenu.Item, DropdownMenu.CheckboxItem and DropdownMenu.Group as direct descendants.

Section titled “Additional props”
Section titled “DropdownMenu.Item”
Base element: <button>

A single menu item within the dropdown menu. Should be used as a child of DropdownMenu.Content and DropdownMenu.Submenu.

Example:

<DropdownMenu.Item label="Add" />
<DropdownMenu.Item label="Edit" />

Use the submenu prop to display a submenu.

Example:

<DropdownMenu.Item
  label="More"
  submenu={
    <DropdownMenu.Submenu>
      <DropdownMenu.Item label="Add" />
      <DropdownMenu.Item label="Edit" />
    </DropdownMenu.Submenu>
  }
/>
Section titled “label”
Type: ReactNode (required)

The primary text label for the menu-item.

Section titled “icon”
Type: string | Element | undefined (optional)

An optional icon displayed before the menu-item label.

Can be a URL of an SVG from the @stratakit/icons package, or a custom JSX icon.

Section titled “shortcuts”
Type: AnyString | `Control+${AnyString}` | `Shift+${AnyString}` | `Backspace+${AnyString}` | `Command+${AnyString}` | `Down+${AnyString}` | `Eject+${AnyString}` | ... 8 more ... | undefined (optional)

A string defining the keyboard shortcut(s) associated with the menu item.

shortcuts="S" // A single key shortcut

Multiple keys should be separated by the + character. If one of the keys is recognized as a symbol name or a modifier key, it will be displayed as a symbol.

shortcuts="Control+Enter" // A multi-key shortcut, displayed as "Ctrl ⏎"
Section titled “submenu”
Type: ReactNode (optional)

The submenu to display when the item is activated. Must be a DropdownMenu.Submenu component.

Section titled “unstable_dot”
Type: string | undefined (optional)

Dot shown on the right end of the menu-item. Value will be used as accessible description.

Section titled “Additional props”
Section titled “DropdownMenu.CheckboxItem”
Base element: <button>

A single checkbox menu item within the dropdown menu. Should be used as a child of DropdownMenu.Content and DropdownMenu.Submenu.

Example:

<DropdownMenu.CheckboxItem name="add" label="Add" />
<DropdownMenu.CheckboxItem name="edit" label="Edit" />
Section titled “label”
Type: ReactNode (required)

The primary text label for the menu-item.

Section titled “name”
Type: string (required)

The name of the field in the values state.

Section titled “checked”
Type: boolean | undefined (optional)

The controlled checked state of the element. It will set the menu values state if provided.

Section titled “defaultChecked”
Type: boolean | undefined (optional)

The default checked state of the element. It will set the default value in the menu values state if provided.

Section titled “icon”
Type: string | Element | undefined (optional)

An optional icon displayed before the menu-item label.

Can be a URL of an SVG from the @stratakit/icons package, or a custom JSX icon.

Section titled “onChange”
Type: ChangeEventHandler<HTMLInputElement, HTMLInputElement> | undefined (optional)

A function that is called when the checkbox’s checked state changes.

Section titled “value”
Type: string | number | readonly string[] | undefined (optional)

The value of the checkbox. This is useful when the same checkbox store is used for multiple Checkbox elements, in which case the value will be an array of checked values.

Section titled “Additional props”
Section titled “DropdownMenu.Submenu”
Base element: <div>

The submenu portion containing the nested submenu items.

Should be passed into the submenu prop of DropdownMenu.Item.

Should include one or more of DropdownMenu.Item, DropdownMenu.CheckboxItem and DropdownMenu.Group as direct descendants.

Section titled “Additional props”
Section titled “DropdownMenu.Group”
Base element: <div>

A group of menu items within the dropdown menu. Should be used as a child of DropdownMenu.Content and DropdownMenu.Submenu.

Example:

<DropdownMenu.Group
  label="Manage"
  items={[
  <DropdownMenu.Item key="add" label="Add" />,
  <DropdownMenu.Item key="edit" label="Edit" />
  ]}
/>
Section titled “items”
Type: Element[] (required)

The menu items within the group.

Should be an array of DropdownMenu.Item and/or DropdownMenu.CheckboxItem elements.

Section titled “label”
Type: string (required)

The text label for the menu-group.

Section titled “Additional props”