` element.
**Viewport Props:**
| Name | Type | Default | Description |
| -------- | ------------------------------------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------ |
| children | JSX.Element | - | The content to render inside the transition container. |
| class | JSX.ClassValue \| ((state) => JSX.ClassValue) | - | CSS class applied to the element, or a function that
returns a class based on the component's state. |
| style | JSX.CSSProperties \| string \| ((state) => JSX.CSSProperties \| string \| undefined) | - | Style applied to the element, or a function that
returns a style object based on the component's state. |
| render | keyof JSX.IntrinsicElements \| Component \| ((props, state) => JSX.Element) | - | Replace the default element with a tag name, component, or render function. |
**Viewport Data Attributes:**
| Name | Type | Default | Description |
| ------------------------- | ---------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| data-activation-direction | ` `$\{'left' \| 'right' \| ''} $\{'down' \| 'up' \| ''}` ` | - | Indicates the direction from which the popup was activated.
This can be used to create directional animations based on how the popup was triggered.
Contains space-separated values for both horizontal and vertical axes. |
| data-current | - | - | Applied to the direct child of the viewport when no transitions are present or the new content when it's entering. |
| data-instant | 'click' \| 'dismiss' \| 'group' \| 'trigger-change' | - | Present if animations should be instant. |
| data-previous | - | - | Applied to the direct child of the viewport that contains the exiting content when transitions are present. |
| data-transitioning | - | - | Indicates that the viewport is currently transitioning between old and new content. |
**Viewport CSS Variables:**
| Name | Type | Default | Description |
| -------------- | ---- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| --popup-height | | - | The height of the parent popup.
This variable is placed on the 'previous' container and stores the height of the popup when the previous content was rendered.
It can be used to freeze the dimensions of the popup when animating between different content. |
| --popup-width | | - | The width of the parent popup.
This variable is placed on the 'previous' container and stores the width of the popup when the previous content was rendered.
It can be used to freeze the dimensions of the popup when animating between different content. |
#### Viewport.State
```typescript
type MenuViewportState = {
/** The activation direction of the transitioned content. */
activationDirection: string | undefined;
/** Whether the viewport is currently transitioning between contents. */
transitioning: boolean;
/** Present if animations should be instant. */
instant: 'dismiss' | 'click' | 'group' | 'trigger-change' | undefined;
};
```
### Group
Groups related menu items with the corresponding label.
Renders a `
` element.
**Group Props:**
| Name | Type | Default | Description |
| -------- | ------------------------------------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------ |
| children | JSX.Element | - | The content of the component. |
| class | JSX.ClassValue \| ((state) => JSX.ClassValue) | - | CSS class applied to the element, or a function that
returns a class based on the component's state. |
| style | JSX.CSSProperties \| string \| ((state) => JSX.CSSProperties \| string \| undefined) | - | Style applied to the element, or a function that
returns a style object based on the component's state. |
| render | keyof JSX.IntrinsicElements \| Component \| ((props, state) => JSX.Element) | - | Replace the default element with a tag name, component, or render function. |
#### Group.State
```typescript
type MenuGroupState = {};
```
### GroupLabel
An accessible label that is automatically associated with its parent group.
Renders a `
` element.
**GroupLabel Props:**
| Name | Type | Default | Description |
| ------ | ------------------------------------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------ |
| class | JSX.ClassValue \| ((state) => JSX.ClassValue) | - | CSS class applied to the element, or a function that
returns a class based on the component's state. |
| style | JSX.CSSProperties \| string \| ((state) => JSX.CSSProperties \| string \| undefined) | - | Style applied to the element, or a function that
returns a style object based on the component's state. |
| render | keyof JSX.IntrinsicElements \| Component \| ((props, state) => JSX.Element) | - | Replace the default element with a tag name, component, or render function. |
#### GroupLabel.State
```typescript
type MenuGroupLabelState = {};
```
### Separator
A separator element accessible to screen readers.
Renders a `
` element.
**Separator Props:**
| Name | Type | Default | Description |
| ----------- | ------------------------------------------------------------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------ |
| orientation | Orientation | `'horizontal'` | The orientation of the separator. |
| class | JSX.ClassValue \| ((state) => JSX.ClassValue) | - | CSS class applied to the element, or a function that
returns a class based on the component's state. |
| style | JSX.CSSProperties \| string \| ((state) => JSX.CSSProperties \| string \| undefined) | - | Style applied to the element, or a function that
returns a style object based on the component's state. |
| render | keyof JSX.IntrinsicElements \| Component \| ((props, state) => JSX.Element) | - | Replace the default element with a tag name, component, or render function. |
**Separator Data Attributes:**
| Name | Type | Default | Description |
| ---------------- | -------------------------- | ------- | ------------------------------------------- |
| data-orientation | 'horizontal' \| 'vertical' | - | Indicates the orientation of the separator. |
#### Separator.State
```typescript
type MenuSeparatorState = {
/** The orientation of the separator. */
orientation: Orientation;
};
```
### Empty
A message shown when the menu has no matching items.
Requires the menu to be wrapped in `Menu.FilterProvider`.
Renders a `
` element.
**Empty Props:**
| Name | Type | Default | Description |
| ------ | ------------------------------------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------ |
| class | JSX.ClassValue \| ((state) => JSX.ClassValue) | - | CSS class applied to the element, or a function that
returns a class based on the component's state. |
| style | JSX.CSSProperties \| string \| ((state) => JSX.CSSProperties \| string \| undefined) | - | Style applied to the element, or a function that
returns a style object based on the component's state. |
| render | keyof JSX.IntrinsicElements \| Component \| ((props, state) => JSX.Element) | - | Replace the default element with a tag name, component, or render function. |
#### Empty.State
```typescript
type MenuEmptyState = {};
```
### SubmenuRoot
Groups all parts of a submenu.
Doesn't render its own HTML element.
**SubmenuRoot Props:**
| Name | Type | Default | Description |
| -------------------- | ---------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| defaultOpen | boolean | `false` | Whether the menu is initially open. To render a controlled menu, use the `open` prop instead. |
| open | boolean | - | Whether the menu is currently open. |
| onOpenChange | ((open: boolean, eventDetails: Menu.SubmenuRoot.ChangeEventDetails) => void) | - | Event handler called when the menu is opened or closed. |
| highlightItemOnHover | boolean | `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. |
| actionsRef | RefObject\
| - | A ref to imperative actions. `unmount`: Ends the closing phase of the menu after an externally controlled closing animation finishes.
Call `preventUnmountOnClose()` in `onOpenChange` first, otherwise the menu completes closing on its own.
Whether it leaves the DOM is decided by `keepMounted` on the portal.`close`: Closes the menu imperatively when called.`highlightItem`: Moves or clears the highlight while the menu is open.
`'next'` and `'previous'` move sequentially through the items and wrap unless `loopFocus`
is disabled. `'first'` and `'last'` highlight the first or last item. `'none'` clears the
highlight and hands focus back to the popup.
Calling this action does not open the menu. To highlight an item after opening it, call
the action from `onOpenChangeComplete` when `open` is `true`.
Highlight changes requested through this action report the reason `'imperative-action'`
to `onItemHighlighted`. |
| closeParentOnEsc | boolean | `false` | When in a submenu, determines whether pressing the Escape key
closes the entire menu, or only the current child menu. |
| loopFocus | boolean | `true` | Whether to loop keyboard focus back to the first item
when the end of the list is reached while using the arrow keys. |
| onItemHighlighted | ((highlightedItem: HTMLElement \| undefined, eventDetails: Menu.Root.HighlightEventDetails) => void) | - | Callback fired when an item is highlighted or unhighlighted.
Receives the highlighted item element (or `undefined` if no item is highlighted) and details
containing the reason for the change, the event, and the item's text label.
The `reason` can be: `'keyboard'`: the highlight changed due to keyboard navigation.`'pointer'`: the highlight changed due to pointer hovering. The event may be a `MouseEvent`
rather than a `PointerEvent`.`'imperative-action'`: the highlight changed via `actionsRef`'s `highlightItem`.`'none'`: the highlight changed for another reason, such as automatic highlighting while
filtering, the item list changing, or the popup opening or closing. |
| onOpenChangeComplete | ((open: boolean) => void) | - | Event handler called after any animations complete when the menu is opened or closed. |
| disabled | boolean | `false` | Whether the component should ignore user interaction. |
| orientation | Menu.Root.Orientation | `'vertical'` | The visual orientation of the menu.
Controls whether roving focus uses up/down or left/right arrow keys. |
| children | JSX.Element | - | The content of the submenu. |
#### SubmenuRoot.State
```typescript
type MenuSubmenuRootState = {};
```
#### SubmenuRoot.ChangeEventReason
```typescript
type MenuSubmenuRootChangeEventReason =
| 'trigger-hover'
| 'trigger-focus'
| 'trigger-press'
| 'outside-press'
| 'focus-out'
| 'list-navigation'
| 'escape-key'
| 'item-press'
| 'close-press'
| 'sibling-open'
| 'cancel-open'
| 'imperative-action'
| 'none';
```
#### SubmenuRoot.ChangeEventDetails
```typescript
type MenuSubmenuRootChangeEventDetails = (
| { reason: 'none'; event: Event }
| { reason: 'trigger-hover'; event: MouseEvent }
| { reason: 'trigger-focus'; event: FocusEvent }
| { reason: 'trigger-press'; event: KeyboardEvent | MouseEvent | TouchEvent | PointerEvent }
| { reason: 'outside-press'; event: MouseEvent | TouchEvent | PointerEvent }
| { reason: 'focus-out'; event: FocusEvent | KeyboardEvent }
| { reason: 'list-navigation'; event: KeyboardEvent }
| { reason: 'escape-key'; event: KeyboardEvent }
| { reason: 'item-press'; event: KeyboardEvent | MouseEvent | PointerEvent }
| { reason: 'close-press'; event: KeyboardEvent | MouseEvent | PointerEvent }
| { reason: 'sibling-open'; event: Event }
| { reason: 'cancel-open'; event: MouseEvent }
| { reason: 'imperative-action'; event: Event }
) & {
/** Cancels Base UI from handling the event. */
cancel: () => void;
/** Allows the event to propagate in cases where Base UI will stop the propagation. */
allowPropagation: () => void;
/** Indicates whether the event has been canceled. */
isCanceled: boolean;
/** Indicates whether the event is allowed to propagate. */
isPropagationAllowed: boolean;
/** The element that triggered the event, if applicable. */
trigger: Element | undefined;
/** Prevents the popup from unmounting until the `unmount` action is called. */
preventUnmountOnClose: () => void;
};
```
### SubmenuTrigger
A menu item that opens a submenu.
Renders a `` element.
**SubmenuTrigger Props:**
| Name | Type | Default | Description |
| ------------ | ------------------------------------------------------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| label | string | - | Overrides the text used for keyboard text navigation and filtering.
Falls back to the rendered text when not provided. |
| onClick | ((event: BaseUIEvent\
>) => void) | - | - |
| nativeButton | boolean | `false` | Whether the component renders a native `