# `DropdownMenu` (v2)

<div class="callout callout-alert">
This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
</div>

`DropdownMenu` displays a menu to the user (such as a set of actions or functions) triggered by a button.


## Design guidelines

### Usage

#### When to use a DropdownMenu

Use a DropdownMenu when you want users to:

-   Choose an action or change a setting from a list, AND
-   Only see the available choices contextually.

`DropdownMenu` is a React component to render an expandable menu of buttons. It is similar in purpose to a `<select>` element, with the distinction that it does not maintain a value. Instead, each option behaves as an action button.

If you need to display all the available options at all times, consider using a Toolbar instead. Use a `DropdownMenu` to display a list of actions after the user interacts with a button.

**Do**
Use a `DropdownMenu` to display a list of actions after the user interacts with an icon.

**Don’t** use a `DropdownMenu` for important actions that should always be visible. Use a `Toolbar` instead.

**Don’t**
Don’t use a `DropdownMenu` for frequently used actions. Use a `Toolbar` instead.

#### Behavior

Generally, the parent button should indicate that interacting with it will show a `DropdownMenu`.

The parent button should retain the same visual styling regardless of whether the `DropdownMenu` is displayed or not.

#### Placement

The `DropdownMenu` should typically appear directly below, or below and to the left of, the parent button. If there isn’t enough space below to display the full `DropdownMenu`, it can be displayed instead above the parent button.

## Development guidelines

This component is still highly experimental, and it's not normally accessible to consumers of the `@wordpress/components` package.

The component exposes a set of components that are meant to be used in combination with each other in order to implement a `DropdownMenu` correctly.

### `DropdownMenu`

The root component, used to specify the menu's trigger and its contents.

#### Props

The component accepts the following props:

##### `trigger`: `React.ReactNode`

The trigger button

- Required: yes

##### `children`: `React.ReactNode`

The contents of the dropdown

- Required: yes

##### `defaultOpen`: `boolean`

The open state of the dropdown menu when it is initially rendered. Use when you do not need to control its open state.

- Required: no

##### `open`: `boolean`

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

- Required: no

##### `onOpenChange`: `(open: boolean) => void`

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

- Required: no

##### `modal`: `boolean`

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

- Required: no
- Default: `true`

##### `side`: `"bottom" | "left" | "right" | "top"`

The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled.

- Required: no
- Default: `"bottom"`

##### `sideOffset`: `number`

The distance in pixels from the trigger.

- Required: no
- Default: `0`

##### `align`: `"end" | "start" | "center"`

The preferred alignment against the trigger. May change when collisions occur.

- Required: no
- Default: `"center"`

##### `alignOffset`: `number`

An offset in pixels from the "start" or "end" alignment options.

- Required: no
- Default: `0`

### `DropdownMenuItem`

Used to render a menu item.

#### Props

The component accepts the following props:

##### `children`: `React.ReactNode`

The contents of the item

- Required: yes

##### `disabled`: `boolean`

- Required: no
- Default: `false`

##### `onSelect`: `(event: Event) => void`

Event handler called when the user selects an item (via mouse or keyboard). Calling `event.preventDefault` in this handler will prevent the dropdown menu from closing when selecting that item.

- Required: no

##### `textValue`: `string`

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

- Required: no

##### `prefix`: `React.ReactNode`

The contents of the item's prefix.

- Required: no

##### `suffix`: `React.ReactNode`

The contents of the item's suffix.

- Required: no

### `DropdownSubMenu`

Used to render a nested submenu.

#### Props

The component accepts the following props:
##### `trigger`: `React.ReactNode`

The contents rendered inside the trigger. The trigger should be an instance of the `DropdownSubMenuTrigger` component.

- Required: yes

##### `children`: `React.ReactNode`

The contents of the dropdown

- Required: yes

##### `defaultOpen`: `boolean`

The open state of the dropdown menu when it is initially rendered. Use when you do not need to control its open state.

- Required: no

##### `open`: `boolean`

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

- Required: no

##### `onOpenChange`: `(open: boolean) => void`

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

- Required: no

##### `disabled`: `boolean`

When `true`, prevents the user from interacting with the item.

- Required: no

##### `textValue`: `string`

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

- Required: no

### `DropdownSubMenuTrigger`

Used to render a submenu trigger.

#### Props

The component accepts the following props:

##### `children`: `React.ReactNode`

The contents of the item

- Required: yes

##### `prefix`: `React.ReactNode`

The contents of the item's prefix.

- Required: no

##### `suffix`: `React.ReactNode`

The contents of the item's suffix.

- Default: a chevron icon
- Required: The standard chevron icon for a submenu trigger

### `DropdownMenuCheckboxItem`

Used to render a checkbox item.

#### Props

The component accepts the following props:

##### `children`: `React.ReactNode`

The contents of the checkbox item

- Required: yes

##### `checked`: `boolean`

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

- Required: no
- Default: `false`

##### `onCheckedChange`: `(checked: boolean) => void)`

Event handler called when the checked state changes.

- Required: no

##### `disabled`: `boolean`

When `true`, prevents the user from interacting with the item.

- Required: no

##### `onSelect`: `(event: Event) => void`

Event handler called when the user selects an item (via mouse or keyboard). Calling `event.preventDefault` in this handler will prevent the dropdown menu from closing when selecting that item.

- Required: no

##### `textValue`: `string`

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

- Required: no

##### `suffix`: `React.ReactNode`

The contents of the checkbox item's suffix.

- Required: no

### `DropdownMenuRadioGroup`

Used to render a radio group.

#### Props

The component accepts the following props:

##### `children`: `React.ReactNode`

The contents of the radio group

- Required: yes

##### `value`: `string`

The value of the selected item in the group.

- Required: no

##### `onValueChange`: `(value: string) => void`

Event handler called when the value changes.

- Required: no

### `DropdownMenuRadioItem`

Used to render a radio item.

#### Props

The component accepts the following props:

##### `children`: `React.ReactNode`

The contents of the item.

- Required: yes

##### `value`: `string`

The unique value of the item.

- Required: yes

##### `disabled`: `boolean`

When `true`, prevents the user from interacting with the item.

- Required: no

##### `onSelect`: `(event: Event) => void`

Event handler called when the user selects an item (via mouse or keyboard). Calling `event.preventDefault` in this handler will prevent the dropdown menu from closing when selecting that item.

- Required: no

##### `textValue`: `string`

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

- Required: no

##### `suffix`: `React.ReactNode

The contents of the radio item's suffix.

- Required: no

### `DropdownMenuLabel`

Used to render a group label.

#### Props

The component accepts the following props:

##### `children`: `React.ReactNode`

The contents of the group.

- Required: yes

### `DropdownMenuGroup`

Used to group menu items.

#### Props

The component accepts the following props:

##### `children`: `React.ReactNode`

The contents of the group.

- Required: yes

### `DropdownMenuSeparatorProps`

Used to render a visual separator.