A dropdown list of actions that opens from a button.
import { Menu } from '@oztix/roadie-components/menu'
Pass the button to Menu.Trigger with render. Menu.Content wraps the portal, positioner and popup, and opens below the trigger, aligned to its start edge. Give each item an icon and, where a key binding exists, a shortcut. Put a destructive action last, after a separator, with intent='danger'.
Give Menu.Item an href, like every Roadie link, and it renders as a link. Internal paths route through RoadieLinkProvider, and external URLs open in a new tab. The menu closes when a link is followed.
Menu.Group with a Menu.GroupLabel names a set of related items. Screen readers announce the label as the group's name.
Menu.CheckboxItem toggles a setting on and off and shows a check when on. The menu stays open, so people can change several at once.
Menu.RadioGroup holds one choice from a set. Each Menu.RadioItem takes a value.
Wrap a Menu.SubmenuTrigger and its own Menu.Content in Menu.SubmenuRoot. The submenu opens beside its trigger on hover, click or the arrow key, with its first item level with the trigger.
side and align on Menu.Content place the menu. Align to end when the trigger sits at the right of a row, so the menu opens back over the row.
Disable an item that can't run right now. It stays in place, so the menu doesn't change shape, and keyboard focus skips over it.
Do
Use a menu for actions on one thing, like an event row, and for view settings like columns and sort order.
Don’t
Don't use a menu to pick a form value. Use a Select, which shows the chosen value and works inside a Field.
<Menu.Separator /><Menu.Item intent='danger'>Cancel event</Menu.Item>
Do
Put the most used action first. Separate a destructive action and put it last, in the danger intent.
Don’t
Don't run a destructive action straight from the menu when it can't be undone. Open a Dialog to confirm it.
<IconButton aria-label='More actions'>…</IconButton>
Do
Give an icon-only trigger an aria-label that says what the menu holds.
Don’t
Don't nest more than one level of submenu. Deep menus are hard to steer with a pointer and hard to follow with a screen reader.
aria-haspopup='menu' and aria-expanded. The popup has the menu role and items have menuitem, menuitemcheckbox or menuitemradio.Whether the menu is initially open. To render a controlled menu, use the `open` prop instead.
Defaults to false.
Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys.
Defaults to true.
Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.
Defaults to true.
Determines if the menu enters a modal state when open. - `true`: user interaction is limited to the menu: document page scroll is locked and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior. Nested menus ignore this prop, and menus opened by hover are never modal.
Defaults to true.
Event handler called when the menu is opened or closed.
Event handler called after any animations complete when the menu is opened or closed.
Whether the menu is currently open.
The visual orientation of the menu. Controls whether roving focus uses up/down or left/right arrow keys.
Defaults to 'vertical'.
Whether the component should ignore user interaction.
Defaults to false.
When in a submenu, determines whether pressing the Escape key closes the entire menu, or only the current child menu.
Defaults to false.
A ref to imperative actions. - `unmount`: Manually unmounts the menu. Call this after any externally controlled closing animation finishes. - `close`: When specified, the menu can be closed imperatively.
ID of the trigger that the menu is associated with. This is useful in conjunction with the `open` prop to create a controlled menu. There's no need to specify this prop when the menu is uncontrolled (that is, when the `open` prop is not set).
ID of the trigger that the menu is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open menu.
A handle to associate the menu with a trigger. If specified, allows external triggers to control the menu's open state.
The content of the menu. This can be a regular React node or a render function that receives the `payload` of the active trigger.
CSS class applied to the element, or a function that returns a class based on the component's state.
Pass a bold Phosphor icon; it is sized for you.
e.g. `⌘D`. Visual only; bind the keys yourself.
Inherited from MenuCheckboxItemProps
Whether the checkbox item is currently ticked. To render an uncontrolled checkbox item, use the `defaultChecked` prop instead.
Whether the checkbox item is initially ticked. To render a controlled checkbox item, use the `checked` prop instead.
Defaults to false.
Event handler called when the checkbox item is ticked or unticked.
The click handler for the menu item.
Whether the component should ignore user interaction.
Defaults to false.
Overrides the text label to use when the item is matched during keyboard text navigation.
@ignore
Whether to close the menu when the item is clicked.
Defaults to false.
Inherited from NonNativeButtonProps
Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button.
Defaults to false.
CSS class applied to the element, or a function that returns a class based on the component's state.
Defaults to 'bottom', or 'inline-end' in a submenu.
Defaults to 'start'.
Gap between trigger and menu, in px.
Defaults to 8, or 4 in a submenu.
Shift along the trigger's edge, in px.
Defaults to 0, or -4 in a submenu.
Inherited from MenuPopupProps
@ignore
Determines the element to focus when the menu is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing.
CSS class applied to the element, or a function that returns a class based on the component's state.
Inherited from MenuGroupProps
The content of the component.
No additional props. It forwards all standard HTML attributes to the underlying element.
Pass a bold Phosphor icon; it is sized for you.
e.g. `⌘D`. Visual only; bind the keys yourself.
Makes the row a link. Internal paths route through `RoadieLinkProvider`; external URLs open in a new tab.
`danger` for a destructive action.
Inherited from MenuItemProps
Overrides the text label to use when the item is matched during keyboard text navigation.
@ignore
The click handler for the menu item.
Whether the component should ignore user interaction. A disabled link row can't be followed.
Defaults to false.
Whether to close the menu when the item is clicked.
Defaults to true.
CSS class applied to the element, or a function that returns a class based on the component's state.
Inherited from MenuPopupProps
@ignore
Determines the element to focus when the menu is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing.
CSS class applied to the element, or a function that returns a class based on the component's state.
Inherited from MenuPortalProps
Whether to keep the portal mounted in the DOM while the popup is hidden.
Defaults to false.
A parent element to render the portal element into.
CSS class applied to the element, or a function that returns a class based on the component's state.
Inherited from MenuPositionerProps
How to align the popup relative to the specified side. Submenus and menubars default to `'start'`.
Defaults to start.
Which side of the anchor element to align the popup against. May automatically change to avoid collisions. Submenus and vertical menubars default to `'inline-end'`.
Defaults to 'bottom'.
Inherited from UseAnchorPositioningSharedParameters
Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side. @example ```jsx <Positioner sideOffset={({ side, align, anchor, positioner }) => { return side === 'top' || side === 'bottom' ? anchor.height : anchor.width; }} /> ```
Defaults to 0.
Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side. @example ```jsx <Positioner alignOffset={({ side, align, anchor, positioner }) => { return side === 'top' || side === 'bottom' ? anchor.width : anchor.height; }} /> ```
Defaults to 0.
An element to position the popup against. By default, the popup will be positioned against the trigger.
Determines which CSS `position` property to use.
Defaults to 'absolute'.
An element or a rectangle that delimits the area that the popup is confined to.
Defaults to 'clipping-ancestors'.
Additional space to maintain from the edge of the collision boundary.
Defaults to 5.
Whether to maintain the popup in the viewport after the anchor element was scrolled out of view.
Defaults to false.
Minimum distance to maintain between the arrow and the edges of the popup. Use it to prevent the arrow element from hanging out of the rounded corners of a popup.
Defaults to 5.
Whether to disable the popup from tracking any layout shift of its positioning anchor.
Defaults to false.
Determines how to handle collisions when positioning the popup. `side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`): - `'flip'`: keep the requested side when it fits; otherwise try the opposite side (`top` and `bottom`, or `left` and `right`). - `'shift'`: never change side; keep the requested side and move the popup within the clipping boundary so it stays visible. - `'none'`: do not correct side-axis overflow. `align` controls overflow on the alignment axis (`start`/`center`/`end`): - `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows. - `'shift'`: keep side and requested alignment, then nudge the popup along the alignment axis to fit. - `'none'`: do not correct alignment-axis overflow. `fallbackAxisSide` controls fallback behavior on the perpendicular axis when the preferred axis cannot fit: - `'start'`: allow perpendicular fallback and try the logical start side first (`top` before `bottom`, or `left` before `right` in LTR). - `'end'`: allow perpendicular fallback and try the logical end side first (`bottom` before `top`, or `right` before `left` in LTR). - `'none'`: do not fallback to the perpendicular axis. When `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`. If `align` is omitted, it defaults to `'flip'`. @example ```jsx <Positioner collisionAvoidance={{ side: 'shift', align: 'shift', fallbackAxisSide: 'none', }} /> ```
CSS class applied to the element, or a function that returns a class based on the component's state.
Inherited from MenuRadioGroupProps
The content of the component.
The controlled value of the radio item that should be currently selected. To render an uncontrolled radio group, use the `defaultValue` prop instead.
The uncontrolled value of the radio item that should be initially selected. To render a controlled radio group, use the `value` prop instead.
Function called when the selected value changes.
Whether the component should ignore user interaction.
Defaults to false.
CSS class applied to the element, or a function that returns a class based on the component's state.
Pass a bold Phosphor icon; it is sized for you.
e.g. `⌘D`. Visual only; bind the keys yourself.
Inherited from MenuRadioItemProps
Value of the radio item. This is the value that will be set in the MenuRadioGroup when the item is selected.
The click handler for the menu item.
Whether the component should ignore user interaction.
Defaults to false.
Overrides the text label to use when the item is matched during keyboard text navigation.
@ignore
Whether to close the menu when the item is clicked.
Defaults to false.
Inherited from NonNativeButtonProps
Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button.
Defaults to false.
CSS class applied to the element, or a function that returns a class based on the component's state.
Inherited from SeparatorProps
The orientation of the separator.
Defaults to 'horizontal'.
Inherited from MenuSubmenuRootProps
Event handler called when the menu is opened or closed.
When in a submenu, determines whether pressing the Escape key closes the entire menu, or only the current child menu.
Defaults to false.
The content of the submenu.
Inherited from MenuRootProps
Whether the component should ignore user interaction.
Defaults to false.
The visual orientation of the menu. Controls whether roving focus uses up/down or left/right arrow keys.
Defaults to 'vertical'.
Whether the menu is initially open. To render a controlled menu, use the `open` prop instead.
Defaults to false.
Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys.
Defaults to true.
Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.
Defaults to true.
Event handler called after any animations complete when the menu is opened or closed.
Whether the menu is currently open.
A ref to imperative actions. - `unmount`: Manually unmounts the menu. Call this after any externally controlled closing animation finishes. - `close`: When specified, the menu can be closed imperatively.
CSS class applied to the element, or a function that returns a class based on the component's state.
Pass a bold Phosphor icon; it is sized for you.
Inherited from MenuSubmenuTriggerProps
Overrides the text label to use when the item is matched during keyboard text navigation.
@ignore
Whether the component should ignore user interaction.
Defaults to false.
How long to wait before the menu may be opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.
Defaults to 100.
How long to wait before closing the menu that was opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.
Defaults to 0.
Whether the menu should also open when the trigger is hovered.
Defaults to true.
Inherited from NonNativeButtonProps
Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button.
Defaults to false.
CSS class applied to the element, or a function that returns a class based on the component's state.
Inherited from MenuTriggerProps
Whether the component should ignore user interaction.
Defaults to false.
A handle to associate the trigger with a menu.
A payload to pass to the menu when it is opened.
How long to wait before the menu may be opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.
Defaults to 100.
How long to wait before closing the menu that was opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.
Defaults to 0.
Whether the menu should also open when the trigger is hovered.
Inherited from NonNativeButtonProps
Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button.
Defaults to false.