# Menu > Component for displaying lists of links or actions that the user can take. ## Import ```js import { Menu } from '@gemini-suite/vera-react'; // you may also access Menu's context via hook: // import { useMenuContext } from '@gemini-suite/vera-react'; ``` Menu is a compound component that consists of multiple parts to help you create all kinds of menus: - `Menu.Root`: The wrapper that contains all the parts of a menu and provides context for its children. - `Menu.Trigger`: The trigger that toggles the menu. - `Menu.Icon`: The default chevron icon used as an open/close indicator. - `Menu.ContextTrigger`: A wrapper around the target area that opens the context menu upon right-clicking. - `Menu.Content`: The container that pops out when the menu is open. - `Menu.Group`: The container used to group multiple, related menu items. - `Menu.Label`: The component that renders the label of Menu.Group. - `Menu.Item`: A single item of the menu. - `Menu.CheckboxItem`: A single item of the menu that acts as a checkbox. - `Menu.RadioGroup`: A wrapper for a group of mutually exclusive radio menu items. - `Menu.RadioItem`: A single item of the menu that acts as a radio button and participates in a Menu.RadioGroup. - `Menu.Separator`: The component that renders a horizontal divider between menu items and groups. ## Examples ### Basic `Menu` works in an uncontrolled way by default, meaning each `Menu` component instance is responsible for managing its own state internally. ```jsx }> {'Open Menu'} console.log('First')}>{'First'} {'Second'} {'Third'} ``` ### Controlled Menu You can easily make the menu controlled, by passing your own state to `isOpen` prop. `onIsOpenChange` handler is called when the state of the menu changes, allowing you to sync state. ```jsx () => { const [isOpen, setIsOpen] = React.useState(false); return ( }> {isOpen ? 'Close Menu' : 'Open Menu'} console.log('First')}> {'First'} {'Second'} {'Third'} ); }; ``` ### Menu items Use the `Menu.Item` component to configure `Menu` options. By passing the `startElement` prop, you can add icon to each `Menu.Item` to help clarify the intent of the item's action. To add a command (or hotkey) to menu item, you can use the `endElement` prop. Use `onSelect` handler that is triggered on click and enter + space key down to add interactivity to the `Menu.Item`. ```jsx }> {'Open Menu'} } endElement={⌘N} onSelect={() => alert('New file')} > {'New file'} } onSelect={() => alert('Copy file')} > {'Copy file'} } endElement={⌘E} onSelect={() => alert('Edit file')} > {'Edit file'} ``` To prevent the user from interacting with the `Menu.Item`, use `isDisabled` property. This will make the item unselectable via keyboard navigation, and it will be skipped when pressing the up/down arrows. ```jsx }> {'Open Menu'} }> {'New file'} } onSelect={() => alert('Copy file')} > {'Copy file'} }> {'Edit file'} ``` For destructive actions such as deleting something, you can set the menu item's `intent` to `danger`. When using this feature, you may want to consider providing a confirmation via a [Dialog component](/components/dialog). ```jsx () => { const [isConfirmationOpen, setIsConfirmationOpen] = React.useState(false); const toastManager = useToastManager(); return ( }> {'Open Menu'} }> {'New file'} }> {'Copy file'} }> {'Edit file'} } intent="danger" onSelect={() => { setIsConfirmationOpen(true); }} > {'Delete file'} Delete file? {'Cancel'} ); }; ``` ### Groups and labels Related items can be grouped inside `Menu.Group`. Use `Menu.Label` component, to render an accessible label for the menu group. To visually divide groups of items in the menu, use `Menu.Separator` . ```jsx {'Complex menu'} console.log('Share')}>{'Share'} ⌘M}>{'Move'} ⌘R}>{'Rename'} Group with icons }> {'First item'} }> {'Second Item'} }> {'Third Item'} }> {'Fourth item'} A Group {'Fifth item'} {'Sixth Item disabled'} {'Seventh Item'} {'Eight item with longer label'} } > {'Item with avatar'} ``` ### With a custom trigger You can choose to have a different trigger for the `Menu` depending on the application's context. ```jsx {'Fritjof Snorre'} {'snorre.fritjof@invera-tech.com'} My Settings System Configurations Help & Feedback { alert('Log Out'); }} > Log Out } onSelect={event => console.log('Edit')} > {'Edit'} }> {'Duplicate'} }> {'Archive'} }> {'Move'} } endElement={⌘⇧D} intent="danger" > {'Delete'} ``` ### Placement By default the menu will be placed below your trigger if it can fit, but this can be customised via the `placement` prop. For example, when the trigger is right-aligned within its container, you can set the `placement` to bottom right. `Menu` is using [Positioner](/components/utility/positioner) internally to dynamically position it's content based on the available space. The passed `position` might get overwritten by smart positioning when necessary. ```jsx {'Bottom left menu'} console.log('First')}>{'First'} {'Second'} {'Third'} {'Bottom right menu'} console.log('First')}>{'First'} {'Second'} {'Third'} ``` ### Sizes Use the `size` prop to control the size of the `Menu.Content`. `medium` and `small` sizes are available, with the `medium` size used by default ```jsx () => { const [branch, setBranch] = React.useState('main'); return ( }> {'Actions'} } endElement={⌘P} > {'Pull'} } endElement={⇧⌘P} > {'Push'} }> {'Open on Github'} Branches main develop } intent="danger" > {'Delete repo'} } > {'Actions'} } endElement={⌘P} > {'Pull'} } endElement={⇧⌘P} > {'Push'} }> {'Open on Github'} Branches main develop } intent="danger" > {'Delete repo'} ); }; ``` ### Item overflow When there are many items in a menu it will grow to a maximum height and the overflowing items will be scrollable. ```jsx {'Tall menu'} {Array.from({ length: 20 }, (_, i) => ( One of many items ))} ``` You can use `css` prop to control the `maxWidth` of the menu content. Long labels will be truncated to avoid blowing out the content. ```jsx {'Truncated menu'} Very long labels will be truncated when the max width is met } endElement={⌘U} > Very long labels will be truncated when the max width is met ``` ### Typeahead search When focus is on the `Menu.Trigger` or within the `Menu.Content` and you type a letter key, a search begins. Focus will move to the first `Menu.Item` that starts with the letter you typed. When user repeats typed character focus cycles among items that starts with the typed character. Try it with following example and repeatedly type character c. If the content of `Menu.Item` is too complex or non-textual, pass the `textValue` property to `Menu.Item` to indicate that the text will be used for typeahead purposes. ```jsx {'Tools'} } onSelect={event => console.log('Edit')} > {'Edit'} }>{'Copy'} }> {'Archive'} }> {'Move'} }>{'Cut'} } endElement={⌘⇧D} intent="danger" > {'Delete'} Custom item ``` ### Context menu To display a menu located at the pointer, triggered by a right-click or a long-press, wrap the area that should open the context menu with `Menu.ContextTrigger`. ```jsx Right Click me }>{'Edit'} }>{'Rename'} } intent="danger"> {'Delete'} ``` ### Single selection You can render a list of menu items as radios to allow users to make a single selection. Menu radio items must be used inside `Menu.RadioGroup`. Consider using specialized [Single Select Menu component](/components/forms/select-menu/single-select-menu) to handle selection. `Menu` component is carrying accessibility/semantic of a [WAI-ARIA Menu Button design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubutton/), while [Single Select Menu](/components/forms/select-menu/single-select-menu) follows [WAI ARIA Listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/). ```jsx () => { const [sortBy, setSortBy] = React.useState('popular'); const [order, setOrder] = React.useState('0'); return ( }> {'Sort by'} {sortBy ? {sortBy} : null} Popular Newest Oldest }> {'Order'} } > Ascending } > Descending ); }; ``` ### Multiple selection You can render a list of menu items as checkboxes to allow users to select multiple items at a time. Consider using specialized [Multi Select Menu component](/components/forms/select-menu/multi-select-menu) to handle multi-selection. ```jsx () => { const checkboxItems = [ { label: 'Email', state: React.useState(false) }, { label: 'Phone', state: React.useState(true) }, { label: 'State', state: React.useState(false) }, { label: 'Country', state: React.useState(false) }, { label: 'Type', state: React.useState(false), isDisabled: true } ]; return ( }> {'Show'} {checkboxItems.map( ({ label, state: [isChecked, setIsChecked], isDisabled }) => ( {label} ) )} ); }; ``` --- ## Accessibility **Menu** implements the [WAI-ARIA Menu Button design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubutton/). --- ## API Reference ### Menu.Root | Name | Type | Default | Description | Required | | ---------------- | --------------------------- | ------- | ---------------------------------------------------------------------------------------------------- | -------- | | `isOpen` | `boolean` | `false` | The controlled open state of the menu. Use in conjunction with `onIsOpenChange`. | | | `defaultIsOpen` | `boolean` | | The open state of the menu when it's first rendered. Use when you do not need to control open state. | | | `onIsOpenChange` | `(isOpen: boolean) => void` | | Event handler called when the open state of the menu changes. | | ### Menu.Trigger | Name | Type | Default | Description | Required | | ----- | --------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `as` | `keyof JSX.IntrinsicElements \| React.ComponentType` | `button` | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node. For more details, read our [Composition](/get-started/composition#polymorphism) guide. | | | `css` | `StitchesCss` | | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants. | | ### Menu.ContextTrigger | Name | Type | Default | Description | Required | | ----- | --------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `as` | `keyof JSX.IntrinsicElements \| React.ComponentType` | `span` | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node. For more details, read our [Composition](/get-started/composition#polymorphism) guide. | | | `css` | `StitchesCss` | | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants. | | ### Menu.Icon | Name | Type | Default | Description | Required | | ----- | ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `css` | `StitchesCss` | | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants. | | ### Menu.Content | Name | Type | Default | Description | Required | | ---------------------- | -------------------------------------------------------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `as` | `keyof JSX.IntrinsicElements \| React.ComponentType` | `div` | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node. For more details, read our [Composition](/get-started/composition#polymorphism) guide. | | | `css` | `StitchesCss` | | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants. | | | `placement` | `"top" \| "top_left" \| "top_right" \| "bottom" \| "bottom_left" \| "bottom_right" \| "left" \| "right"` | `"bottom_left"` | Placement of the menu content. Smart positioning might override this. | | | `size` | `"small" \| "medium"` | `medium` | The size of the menu content. | | | `anchorOffset` | `number` | | Distance from the trigger to the menu content. | | | `onExitComplete` | `() => void` | `() => void` | Event handler called when the menu content has completed animating out. | | | `onPointerDownOutside` | `(event: Event) => void` | | Event handler called when a pointer event occurs outside the bounds of the menu content. It can be prevented with `event.preventDefault`. | | | `loop` | `boolean` | `false` | When `true` keyboard focus will loop from last item to the first item, and vice versa. | | ### Menu.Group | Name | Type | Default | Description | Required | | ----- | --------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `as` | `keyof JSX.IntrinsicElements \| React.ComponentType` | `div` | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node. For more details, read our [Composition](/get-started/composition#polymorphism) guide. | | | `css` | `StitchesCss` | | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants. | | ### Menu.Label | Name | Type | Default | Description | Required | | ----- | --------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `as` | `keyof JSX.IntrinsicElements \| React.ComponentType` | `div` | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node. For more details, read our [Composition](/get-started/composition#polymorphism) guide. | | | `css` | `StitchesCss` | | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants. | | ### Menu.Item | Name | Type | Default | Description | Required | | -------------- | --------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `as` | `keyof JSX.IntrinsicElements \| React.ComponentType` | `div` | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node. For more details, read our [Composition](/get-started/composition#polymorphism) guide. | | | `css` | `StitchesCss` | | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants. | | | `isDisabled` | `boolean` | `false` | When `true`, the item will be disabled, preventing the user from interacting with it. | | | `textValue` | `string` | | By default the typeahead behavior will use the `.textContent` of the item. When the content is complex or non-textual, this property can be used to specify text for the typeahead search purposes. | | | `onSelect` | `(event: Event) => void` | | Event handler called when item is selected (via mouse or keyboard). Use this to perform actions. Calling `event.preventDefault` will prevent the menu from closing upon selection. | | | `startElement` | `React.ReactElement` | | `ReactElement` to render to the left of the item's children. | | | `endElement` | `React.ReactElement` | | `ReactElement` to render to the right of the item's children. | | | `intent` | `"danger"` | | Sets the visual intent of the item. | | ### Menu.CheckboxItem The `Menu.CheckboxItem` extends all the `Menu.Item` properties and adds the following ones: | Name | Type | Default | Description | Required | | ------------------- | ------------------------------ | ------- | -------------------------------------------------------------------------------------- | -------- | | `isChecked` | `boolean` | | The controlled checked state of the item. Use in conjunction with `onIsCheckedChange`. | | | `onIsCheckedChange` | `(isChecked: boolean) => void` | | Event handler called when the checked state changes. | | ### Menu.RadioGroup The `Menu.RadioGroup` extends all the `Menu.Group` properties and adds the following ones: | Name | Type | Default | Description | Required | | --------------- | ------------------------- | ------- | -------------------------------------------- | -------- | | `value` | `string` | | Value of the radio item. | | | `onValueChange` | `(value: string) => void` | | Event handler called when the value changes. | | ### Menu.RadioItem The `Menu.RadioItem` extends all the `Menu.Item` properties and adds the following ones: | Name | Type | Default | Description | Required | | ------- | -------- | ------- | ---------------------------- | -------- | | `value` | `string` | | The value of the radio item. | Yes | ### Menu.Separator | Name | Type | Default | Description | Required | | ----- | --------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | `as` | `keyof JSX.IntrinsicElements \| React.ComponentType` | `div` | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node. For more details, read our [Composition](/get-started/composition#polymorphism) guide. | | | `css` | `StitchesCss` | | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants. | |