dropdown-menu-v2

DropdownMenu (v2)

This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.

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.