Primitives

Dropdown menu

A Base UI menu on the menu tokens: items, radio groups, submenus, labels, shortcuts, separators

Import

import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuSub,
  DropdownMenuSubContent,
  DropdownMenuSubTrigger,
  DropdownMenuTrigger,
} from "@nyte-ai/ui";

Implemented in packages/ui/src/components/ui/dropdown-menu.tsx, wrapping @nyte-ai/ui/menu. DropdownMenu, DropdownMenuTrigger, DropdownMenuRadioGroup, and DropdownMenuSub are the Base UI parts (Root, Trigger, RadioGroup, SubmenuRoot) re-exported unstyled.

The desktop app has its own richer menu tier (checkbox items, switch items, command menu). See Desktop › Menu. This wrapper is for web hosts and demos.

Usage

Items are actions. For choosing one of several values, use a DropdownMenuRadioGroup; for a form-style select, use the headless Select.
variant="destructive" on the last item, after a separator.
inset on items and labels aligns their text with radio items in the same menu, which reserve --nyte-control-menu-inset on the left for the indicator.
DropdownMenuShortcut is display only. It does not bind the key.

Anatomy

<DropdownMenu>
  <DropdownMenuTrigger />
  <DropdownMenuContent>
    {/* Portal › Positioner › Popup */}
    <DropdownMenuLabel />
    <DropdownMenuItem>
      <DropdownMenuShortcut />
    </DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuRadioGroup>
      <DropdownMenuRadioItem /> {/* includes the indicator */}
    </DropdownMenuRadioGroup>
    <DropdownMenuSub>
      <DropdownMenuSubTrigger /> {/* includes the chevron */}
      <DropdownMenuSubContent /> {/* Content with side="right" */}
    </DropdownMenuSub>
  </DropdownMenuContent>
</DropdownMenu>

Example

<DropdownMenu>
  <DropdownMenuTrigger render={<Button variant="outline" />}>Session</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem>
      Rename
      <DropdownMenuShortcut>⌘R</DropdownMenuShortcut>
    </DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuRadioGroup value={effort} onValueChange={setEffort}>
      <DropdownMenuLabel inset>Effort</DropdownMenuLabel>
      <DropdownMenuRadioItem value="low">Low</DropdownMenuRadioItem>
      <DropdownMenuRadioItem value="high">High</DropdownMenuRadioItem>
    </DropdownMenuRadioGroup>
    <DropdownMenuSub>
      <DropdownMenuSubTrigger>Move to</DropdownMenuSubTrigger>
      <DropdownMenuSubContent>
        <DropdownMenuItem>Archive</DropdownMenuItem>
      </DropdownMenuSubContent>
    </DropdownMenuSub>
    <DropdownMenuItem variant="destructive">Delete</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

Props

DropdownMenu (Root)

Groups all parts of the menu. Doesn't render its own HTML element.

Root Props:

Prop	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.Root.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	`React.RefObject<Menu.Root.Actions \| null>`	-	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.
closeParentOnEsc	`boolean`	`false`	When in a submenu, determines whether pressing the Escape key closes the entire menu, or only the current child menu.
defaultTriggerId	`string \| null`	-	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.
handle	`Menu.Handle<Payload>`	-	A handle to associate the menu with a trigger. If specified, allows external triggers to control the menu's open state.
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.
modal	`boolean`	`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.
onOpenChangeComplete	`((open: boolean) => void)`	-	Event handler called after any animations complete when the menu is opened or closed.
triggerId	`string \| null`	-	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).
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	`React.ReactNode \| PayloadChildRenderFunction<Payload>`	-	The content of the menu. This can be a regular React node or a render function that receives the `payload` of the active trigger.

DropdownMenuContent

StyledProps<Menu.Popup.Props> plus the positioning subset forwarded to Menu.Positioner:

Prop	Type	Default	Description
`side`	`Menu.Positioner.Props["side"]`	`"bottom"`	Which side of the trigger.
`align`	`Menu.Positioner.Props["align"]`	`"start"`	Alignment along that side.
`sideOffset`	`number`	`4`	Gap from the trigger.
`alignOffset`	`Menu.Positioner.Props["alignOffset"]`	`0`	Shift along the alignment axis.

DropdownMenuSubContent takes the same props with defaults side="right", align="start", sideOffset={0}, alignOffset={-3}.

A container for the menu items. Renders a <div> element.

Popup Props:

Prop	Type	Default	Description
finalFocus	`boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| void \| HTMLElement \| null)`	-	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.
children	`React.ReactNode`	-	-
className	`string \| ((state: Menu.Popup.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Menu.Popup.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Menu.Popup.State) => ReactElement)`	-	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Popup Data Attributes:

Attribute	Type	Description
data-open	-	Present when the menu is open.
data-closed	-	Present when the menu is closed.
data-align	`'start' \| 'center' \| 'end'`	Indicates how the popup is aligned relative to specified side.
data-instant	`'click' \| 'dismiss' \| 'group' \| 'trigger-change'`	Present if animations should be instant.
data-side	`'top' \| 'bottom' \| 'left' \| 'right' \| 'inline-end' \| 'inline-start'`	Indicates which side the popup is positioned relative to the anchor.
data-starting-style	-	Present when the menu begins animating in.
data-ending-style	-	Present when the menu is animating out.

DropdownMenuItem

StyledProps<Menu.Item.Props> plus:

Prop	Type	Default	Description
`inset`	`boolean`	`false`	Left padding to align with radio items.
`variant`	`"default" \| "destructive"`	`"default"`	Destructive color; highlighted wash matches.

Sets data-slot="dropdown-menu-item", data-variant, and data-inset.

An individual interactive item in the menu. Renders a <div> element.

Item Props:

Prop	Type	Default	Description
label	`string`	-	Overrides the text label to use when the item is matched during keyboard text navigation.
onClick	`((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void)`	-	The click handler for the menu item.
closeOnClick	`boolean`	`true`	Whether to close the menu when the item is clicked.
nativeButton	`boolean`	`false`	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.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
className	`string \| ((state: Menu.Item.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Menu.Item.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Menu.Item.State) => ReactElement)`	-	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Item Data Attributes:

Attribute	Type	Description
data-highlighted	-	Present when the menu item is highlighted.
data-disabled	-	Present when the menu item is disabled.

DropdownMenuRadioGroup, DropdownMenuRadioItem

DropdownMenuRadioItem is StyledProps<Menu.RadioItem.Props> plus inset. It renders the RadioItemIndicator with a check glyph in an IconBox.

Groups related radio items. Renders a <div> element.

RadioGroup Props:

Prop	Type	Default	Description
defaultValue	`any`	-	The uncontrolled value of the radio item that should be initially selected. To render a controlled radio group, use the `value` prop instead.
value	`any`	-	The controlled value of the radio item that should be currently selected. To render an uncontrolled radio group, use the `defaultValue` prop instead.
onValueChange	`((value: any, eventDetails: Menu.RadioGroup.ChangeEventDetails) => void)`	-	Function called when the selected value changes.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
children	`React.ReactNode`	-	The content of the component.
className	`string \| ((state: Menu.RadioGroup.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Menu.RadioGroup.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Menu.RadioGroup.State) => ReactElement)`	-	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

A menu item that works like a radio button in a given group. Renders a <div> element.

RadioItem Props:

Prop	Type	Default	Description
label	`string`	-	Overrides the text label to use when the item is matched during keyboard text navigation.
value*	`any`	-	Value of the radio item. This is the value that will be set in the Menu.RadioGroup when the item is selected.
onClick	`((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void)`	-	The click handler for the menu item.
closeOnClick	`boolean`	`false`	Whether to close the menu when the item is clicked.
nativeButton	`boolean`	`false`	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.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
className	`string \| ((state: Menu.RadioItem.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Menu.RadioItem.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Menu.RadioItem.State) => ReactElement)`	-	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

RadioItem Data Attributes:

Attribute	Type	Description
data-checked	-	Present when the menu radio item is selected.
data-unchecked	-	Present when the menu radio item is not selected.
data-highlighted	-	Present when the menu radio item is highlighted.
data-disabled	-	Present when the menu radio item is disabled.

DropdownMenuSubTrigger

StyledProps<Menu.SubmenuTrigger.Props> plus inset. Renders a trailing chevron.

A menu item that opens a submenu. Renders a <div> element.

SubmenuTrigger Props:

Prop	Type	Default	Description
label	`string`	-	Overrides the text label to use when the item is matched during keyboard text navigation.
onClick	`((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void)`	-	-
nativeButton	`boolean`	`false`	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.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
openOnHover	`boolean`	`true`	Whether the menu should also open when the trigger is hovered.
delay	`number`	`100`	How long to wait before the menu may be opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.
closeDelay	`number`	`0`	How long to wait before closing the menu that was opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.
className	`string \| ((state: Menu.SubmenuTrigger.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Menu.SubmenuTrigger.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Menu.SubmenuTrigger.State) => ReactElement)`	-	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

SubmenuTrigger Data Attributes:

Attribute	Type	Description
data-popup-open	-	Present when the corresponding submenu is open.
data-highlighted	-	Present when the submenu trigger is highlighted.
data-disabled	-	Present when the submenu trigger is disabled.

DropdownMenuLabel

StyledProps<Menu.GroupLabel.Props> plus inset.

An accessible label that is automatically associated with its parent group. Renders a <div> element.

GroupLabel Props:

Prop	Type	Default	Description
className	`string \| ((state: Menu.GroupLabel.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Menu.GroupLabel.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Menu.GroupLabel.State) => ReactElement)`	-	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

DropdownMenuSeparator

A separator element accessible to screen readers. Renders a <div> element.

Separator Props:

Prop	Type	Default	Description
orientation	`Orientation`	`'horizontal'`	The orientation of the separator.
className	`string \| ((state: SeparatorState) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: SeparatorState) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: SeparatorState) => ReactElement)`	-	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

DropdownMenuShortcut

StyledProps<React.ComponentProps<"span">>. Pushed to the right with margin-left: auto, in --nyte-color-muted-foreground at --nyte-font-size-detail.

Accessibility

Base UI's menu model, unchanged:

Popup has role="menu"; items role="menuitem", radio items role="menuitemradio" with aria-checked, submenu triggers aria-haspopup="menu" and aria-expanded.
Arrow Down/Up move the highlight and wrap; Home/End jump; typing matches item text (override with label); Enter and Space activate; Escape closes and returns focus to the trigger.
Arrow Right opens a submenu and moves focus into it; Arrow Left closes it. Submenus also open on hover (openOnHover).
Disabled items are aria-disabled, skipped by keyboard navigation, and set data-disabled.
Separators are role="separator".

Styling

Token	Role
`--nyte-layer-menu`	z-index (60), above dialogs
`--nyte-menu-min-width`, `-max-width`, `-max-height`	Popup box, bound to `--available-*`
`--nyte-radius-menu`, `--nyte-elevation-menu`, `--nyte-color-popover`	Popup surface
`--nyte-font-size-label` / `--nyte-leading-label`	Items
`--nyte-color-muted-hover`	`[data-highlighted]` and `[data-popup-open]`
`--nyte-color-destructive`, `-muted`	Destructive item and its highlight
`--nyte-control-menu-inset`	Indicator gutter / `inset`
`--nyte-motion-normal`	Fade + 0.98 scale on `[data-starting-style]` / `[data-ending-style]`