@wordpress/components

# `Menu` <div class="callout callout-alert"> This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes. </div> `Menu` displays a menu to the user (such as a set of actions or functions). The menu is rendered in a popover (this pattern is also known as a "Dropdown menu"), which is triggered by a button. ## Design guidelines ### Usage #### When to use a `Menu` Use a `Menu` when you want users to: - Choose an action or change a setting from a list, AND - Only see the available choices contextually. `Menu` 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 `Menu` to display a list of actions after the user interacts with a button. **Do** Use a `Menu` to display a list of actions after the user interacts with an icon. **Don’t** use a `Menu` for important actions that should always be visible. Use a `Toolbar` instead. **Don’t** Don’t use a `Menu` for frequently used actions. Use a `Toolbar` instead. #### Behavior Generally, the parent button should indicate that interacting with it will show a `Menu`. The parent button should retain the same visual styling regardless of whether the `Menu` is displayed or not. #### Placement The `Menu` 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 `Menu`, 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 `Menu` correctly. ### `Menu` The root component, used to specify the menu's trigger and its contents. #### Props The component accepts the following props: ##### `trigger`: `React.ReactNode` The button triggering the menu popover. - Required: yes ##### `children`: `React.ReactNode` The contents of the menu (ie. one or more menu items). - Required: yes ##### `defaultOpen`: `boolean` The open state of the menu popover when it is initially rendered. Use when not wanting to control its open state. - Required: no - Default: `false` ##### `open`: `boolean` The controlled open state of the menu popover. Must be used in conjunction with `onOpenChange`. - Required: no ##### `onOpenChange`: `(open: boolean) => void` Event handler called when the open state of the menu popover changes. - Required: no ##### `modal`: `boolean` The modality of the menu popover. 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` ##### `placement`: ``'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end'` The placement of the menu popover. - Required: no - Default: `'bottom-start'` for root-level menus, `'right-start'` for nested menus ##### `gutter`: `number` The distance in pixels from the trigger. - Required: no - Default: `8` for root-level menus, `16` for nested menus ##### `shift`: `number` The skidding of the popover along the anchor element. Can be set to negative values to make the popover shift to the opposite side. - Required: no - Default: `0` for root-level menus, `-8` for nested menus ### `Menu.Item` Used to render a menu item. #### 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. - Required: no ##### `hideOnClick`: `boolean` Whether to hide the menu popover when the menu item is clicked. - Required: no - Default: `true` ##### `disabled`: `boolean` Determines if the element is disabled. - Required: no - Default: `false` ### `Menu.CheckboxItem` Used to render a checkbox item. #### Props The component accepts the following props: ##### `children`: `React.ReactNode` The contents of the item - Required: yes ##### `suffix`: `React.ReactNode` The contents of the item's suffix. - Required: no ##### `hideOnClick`: `boolean` Whether to hide the menu popover when the menu item is clicked. - Required: no - Default: `false` ##### `disabled`: `boolean` Determines if the element is disabled. - Required: no - Default: `false` ##### `name`: `string` The checkbox item's name. - Required: yes ##### `value`: `string` The checkbox item's value, useful when using multiple checkbox items associated to the same `name`. - Required: no ##### `checked`: `boolean` The checkbox item's value, useful when using multiple checkbox items associated to the same `name`. - Required: no ##### `defaultChecked`: `boolean` The checked state of the checkbox menu item when it is initially rendered. Use when not wanting to control its checked state. - Required: no ##### `onChange`: `( event: React.ChangeEvent< HTMLInputElement > ) => void;` Event handler called when the checked state of the checkbox menu item changes. - Required: no ### `Menu.RadioItem` Used to render a radio item. #### Props The component accepts the following props: ##### `children`: `React.ReactNode` The contents of the item - Required: yes ##### `suffix`: `React.ReactNode` The contents of the item's suffix. - Required: no ##### `hideOnClick`: `boolean` Whether to hide the menu popover when the menu item is clicked. - Required: no - Default: `false` ##### `disabled`: `boolean` Determines if the element is disabled. - Required: no - Default: `false` ##### `name`: `string` The radio item's name. - Required: yes ##### `value`: `string | number` The radio item's value. - Required: yes ##### `checked`: `boolean` The checkbox item's value, useful when using multiple checkbox items associated to the same `name`. - Required: no ##### `defaultChecked`: `boolean` The checked state of the radio menu item when it is initially rendered. Use when not wanting to control its checked state. - Required: no ##### `onChange`: `( event: React.ChangeEvent< HTMLInputElement > ) => void;` Event handler called when the checked radio menu item changes. - Required: no ### `Menu.ItemLabel` Used to render the menu item's label. #### Props The component accepts the following props: ##### `children`: `React.ReactNode` The label contents. - Required: yes ### `Menu.ItemHelpText` Used to render the menu item's help text. #### Props The component accepts the following props: ##### `children`: `React.ReactNode` The help text contents. - Required: yes ### `Menu.Group` Used to group menu items. #### Props The component accepts the following props: ##### `children`: `React.ReactNode` The contents of the menu group (ie. an optional menu group label and one or more menu items). - Required: yes ### `Menu.GroupLabel` Used to render a group label. The label text should be kept as short as possible. #### Props The component accepts the following props: ##### `children`: `React.ReactNode` The contents of the menu group label. - Required: yes ### `Menu.Separator` Used to render a visual separator.