Dropdown Menu - @ngrok/mantle

Displays a menu to the user (such as a set of actions or functions), triggered by a button. Built on top of Radix Dropdown Menu.

1import { Button } from "@ngrok/mantle/button";2import { DropdownMenu } from "@ngrok/mantle/dropdown-menu";3import { Icon } from "@ngrok/mantle/icon";4import { Tooltip } from "@ngrok/mantle/tooltip";5import { DesktopIcon } from "@phosphor-icons/react/Desktop";6import { GearIcon } from "@phosphor-icons/react/Gear";7import { MoonIcon } from "@phosphor-icons/react/Moon";8import { SignOutIcon } from "@phosphor-icons/react/SignOut";9import { SunIcon } from "@phosphor-icons/react/Sun";10import { useState } from "react";11 12function Example() {⋯13	const [selectedTheme, setSelectedTheme] = useState("system");14	const [enableNotifications, setEnableNotifications] = useState(false);15 16	return (17		<DropdownMenu.Root>⋯18			<DropdownMenu.Trigger asChild>⋯19				<Button type="button" appearance="filled" intent="neutral">⋯20					Open Menu21				</Button>22			</DropdownMenu.Trigger>23			<DropdownMenu.Content>⋯24				<DropdownMenu.Label>corby.pickles@ngork.com</DropdownMenu.Label>25				<DropdownMenu.Separator />26				<DropdownMenu.RadioGroup⋯27					value={selectedTheme}28					onValueChange={(value) => {⋯29						setSelectedTheme(value);30					}}31				>32					<DropdownMenu.RadioItem value="system">⋯33						<Icon svg={<DesktopIcon />} />34						System Preference35					</DropdownMenu.RadioItem>36					<DropdownMenu.RadioItem value="light">⋯37						<Icon svg={<SunIcon />} />38						Light Mode39					</DropdownMenu.RadioItem>40					<DropdownMenu.RadioItem value="dark">⋯41						<Icon svg={<MoonIcon />} />42						Dark Mode43					</DropdownMenu.RadioItem>44				</DropdownMenu.RadioGroup>45				<DropdownMenu.Separator />46				<Tooltip.Root>⋯47					<Tooltip.Trigger asChild>⋯48						<DropdownMenu.Item className="flex items-center gap-2" disabled>⋯49							<Icon svg={<GearIcon />} />50							User Settings51						</DropdownMenu.Item>52					</Tooltip.Trigger>53					<Tooltip.Content side="left">Only winners get user settings.</Tooltip.Content>54				</Tooltip.Root>55				<DropdownMenu.Separator />56				<DropdownMenu.CheckboxItem⋯57					checked={enableNotifications}58					onCheckedChange={(value) => {⋯59						setEnableNotifications(value);60					}}61				>62					Enable Notifications63				</DropdownMenu.CheckboxItem>64				<DropdownMenu.Group>⋯65					<DropdownMenu.Item>Team</DropdownMenu.Item>66					<DropdownMenu.Sub>⋯67						<DropdownMenu.SubTrigger>Invite users</DropdownMenu.SubTrigger>68						<DropdownMenu.SubContent>⋯69							<DropdownMenu.Item>Email</DropdownMenu.Item>70							<DropdownMenu.Item>Message</DropdownMenu.Item>71							<DropdownMenu.Separator />72							<DropdownMenu.Item>More...</DropdownMenu.Item>73						</DropdownMenu.SubContent>74					</DropdownMenu.Sub>75					<DropdownMenu.Item>⋯76						New Team77						<DropdownMenu.Shortcut>⌘+T</DropdownMenu.Shortcut>78					</DropdownMenu.Item>79				</DropdownMenu.Group>80				<DropdownMenu.Separator />81				<DropdownMenu.Item className="flex items-center gap-2">⋯82					<Icon svg={<SignOutIcon />} />83					Log out84				</DropdownMenu.Item>85			</DropdownMenu.Content>86		</DropdownMenu.Root>87	);88}

Layering and z-index

DropdownMenu.Content and DropdownMenu.SubContent render at Tailwind z-50, Mantle's float tier. When composed inside an open Dialog, AlertDialog, or Sheet, they portal into that overlay's positioner and paint above the overlay that owns them. Outside every overlay, they portal to document.body, below the overlay tier (z-60). When sibling floats share a container, the most recently mounted float paints on top.

DropdownMenu does not render a backdrop by default. Modal layers such as Dialog, Sheet, and AlertDialog do render backdrops, so stacking those layers compounds the dim and blur effect on the layers underneath.

Composition

Compose the parts of a DropdownMenu together to build your own:

DropdownMenu.Root├── DropdownMenu.Trigger└── DropdownMenu.Content    ├── DropdownMenu.Group    │   ├── DropdownMenu.Label    │   ├── DropdownMenu.Item    │   │   └── DropdownMenu.Shortcut    │   ├── DropdownMenu.CheckboxItem    │   └── DropdownMenu.RadioGroup    │       └── DropdownMenu.RadioItem    ├── DropdownMenu.Separator    └── DropdownMenu.Sub        ├── DropdownMenu.SubTrigger        └── DropdownMenu.SubContent

Polymorphism

asChild renders the part's single child instead of its default element, and forwards class names, data-* attributes, and ref onto that child. These parts take it:

Part	Reach for it when
`DropdownMenu.Trigger`	The trigger is a `Button`, an `IconButton`, or your own control.
`DropdownMenu.Content`	The panel needs its own element to carry layout or a motion wrapper.
`DropdownMenu.SubContent`	The same, for a submenu panel.
`DropdownMenu.Item`	The item navigates, so it must render an `<a>` or a router `Link`.
`DropdownMenu.CheckboxItem`	The same, for a choice a URL carries.
`DropdownMenu.RadioItem`	The same, for one choice out of a URL-driven set.
`DropdownMenu.SubTrigger`	The submenu opener must be your own element.
`DropdownMenu.Label`	The label needs a heading element for the document outline.
`DropdownMenu.Group`	The group needs its own element.
`DropdownMenu.RadioGroup`	The same, for a radio group.
`DropdownMenu.Separator`	The divider must be a specific element, such as an `<hr>`.

DropdownMenu.SubTrigger, DropdownMenu.CheckboxItem, and DropdownMenu.RadioItem each render a second element beside your children: the submenu caret, or the check indicator. Under asChild, Radix clones your single child as the item element and moves the label span and that element inside it, so the translation guarantee holds on both paths.

API Reference

The DropdownMenu components are built on top of Radix Dropdown Menu.

DropdownMenu.Root

The root, stateful component that manages the open/closed state of the dropdown menu.

Prop	Type	Default	Description
`open?`	`boolean`		The controlled open state of the dropdown menu. Must be used in conjunction with `onOpenChange`.
`onOpenChange?`	`(open: boolean) => void`		Event handler called when the open state of the dropdown menu changes.
`defaultOpen?`	`boolean`	`false`	The open state of the dropdown menu when it is initially rendered. Use when you do not need to control its open state.
`dir?`	`"ltr"` \| `"rtl"`		The reading direction of submenus when applicable.
`modal?`	`boolean`	`true`	The modality of the dropdown menu. When set to `true`, interaction with outside elements will be disabled and only menu content will be visible to screen readers.

DropdownMenu.Trigger

The trigger button that opens the dropdown menu.

Prop	Type	Default	Description
`asChild?`	`boolean`	`false`	Use the `asChild` prop to compose the trigger functionality onto your own component.

DropdownMenu.Content

The container for the dropdown menu content. Appears in a portal with scrolling and animations.

All props from Radix DropdownMenu.Content, plus:

Prop	Type	Default	Description
`width?`	`"trigger"` \| `"content"`		`trigger` will ensure the dropdown content is the same width as the trigger button. `content` will make the dropdown content use the intrinsic content width.
`side?`	`"top"` \| `"right"` \| `"bottom"` \| `"left"`	`"bottom"`	The preferred side of the trigger to render against when open.
`sideOffset?`	`number`		The distance in pixels from the trigger.
`align?`	`"start"` \| `"center"` \| `"end"`	`"center"`	The preferred alignment against the trigger.
`alignOffset?`	`number`	`0`	An offset in pixels from the `start` or `end` alignment options.
`loop?`	`boolean`	`true`	When `true`, keyboard navigation will loop from last item to first, and vice versa.

DropdownMenu.Item

A standard item in the dropdown menu that can be selected or activated.

Prop	Type	Description
`inset?`	`boolean`	When `true`, adds left padding to align with items that have icons.
`disabled?`	`boolean`	When `true`, prevents the user from interacting with the item.
`onSelect?`	`(event: Event) => void`	Event handler called when the user selects an item (via mouse or key). Call `event.preventDefault()` to keep the menu open.

DropdownMenu.CheckboxItem

A menu item with a checkbox that can be controlled or uncontrolled.

children render inside a <span data-slot="dropdown-menu-checkbox-item-label">. The check indicator is a permanent element sibling, so without the span a bare text label is never a lone child: a browser translation engine reparents that text node, and the removal React runs when the label changes shape or goes away throws. The span is display: contents, so an icon and its label stay flex items of the item and keep its gap. Browser translation covers the mechanism and the rules your own components need.

An icon you pass as a child is now a grandchild of the item, so a [&>svg] class of your own no longer reaches it. Match the part's own variant instead: [&>[data-slot=dropdown-menu-checkbox-item-label]>svg]:size-4. A [&_svg] class or a class on the icon itself loses to the item's default, which carries one more attribute selector.

All props from Radix DropdownMenu.CheckboxItem, including:

Prop	Type	Description
`checked?`	`boolean` \| `"indeterminate"`	The controlled checked state of the item. Must be used with `onCheckedChange`.
`onCheckedChange?`	`(checked: boolean) => void`	Event handler called when the checked state changes.
`disabled?`	`boolean`	When `true`, prevents the user from interacting with the item.

Data attributes

Data Attribute	Value	Description
`data-slot`	`"dropdown-menu-checkbox-item"`	On the item element.
`data-slot`	`"dropdown-menu-checkbox-item-label"`	On the `<span>` wrapping `children`.

DropdownMenu.RadioGroup

A radio group container for exclusive selection within the dropdown menu.

Prop	Type	Default	Description
`value?`	`string`		The value of the selected item in the group.
`onValueChange?`	`(value: string) => void`		Event handler called when the value changes.

DropdownMenu.RadioItem

A radio item where only one item in the group can be selected at a time.

children render inside a <span data-slot="dropdown-menu-radio-item-label">. The check indicator is a permanent element sibling, so without the span a bare text label is never a lone child: a browser translation engine reparents that text node, and the removal React runs when the label changes shape or goes away throws. The span is display: contents, so an icon and its label stay flex items of the item and keep its gap. Browser translation covers the mechanism and the rules your own components need.

An icon you pass as a child is now a grandchild of the item, so a [&>svg] class of your own no longer reaches it. Match the part's own variant instead: [&>[data-slot=dropdown-menu-radio-item-label]>svg]:size-4. A [&_svg] class or a class on the icon itself loses to the item's default, which carries one more attribute selector.

All props from Radix DropdownMenu.RadioItem, including:

Prop	Type	Default	Description
`value`	`string`		The unique value of the item.
`disabled?`	`boolean`		When `true`, prevents the user from interacting with the item.

Data attributes

Data Attribute	Value	Description
`data-slot`	`"dropdown-menu-radio-item"`	On the item element.
`data-slot`	`"dropdown-menu-radio-item-label"`	On the `<span>` wrapping `children`.

DropdownMenu.Label

A label for grouping and describing sections within the dropdown menu.

Prop	Type	Default	Description
`inset?`	`boolean`		When `true`, adds left padding to align with items that have icons.

DropdownMenu.Group

A group container for organizing related dropdown menu items. Accepts all props from Radix DropdownMenu.Group.

DropdownMenu.Separator

A visual separator for dividing sections within the dropdown menu. All props from Separator.

DropdownMenu.Shortcut

A keyboard shortcut indicator for dropdown menu items. It locks translate="no", because a translated key name names the wrong key. All props from span except translate.

DropdownMenu.Sub

A submenu container for creating nested dropdown menus. Accepts all props from Radix DropdownMenu.Sub.

Prop	Type	Description
`open?`	`boolean`	The controlled open state of the submenu. Must be used in conjunction with `onOpenChange`.
`onOpenChange?`	`(open: boolean) => void`	Event handler called when the open state of the submenu changes.
`defaultOpen?`	`boolean`	The open state of the submenu when it is initially rendered.

DropdownMenu.SubTrigger

A trigger for a dropdown menu sub-menu. It opens the submenu on hover, or on ArrowRight or Enter.

children render inside a <span data-slot="dropdown-menu-sub-trigger-label">. The caret is a permanent element sibling, so without the span a bare text label is never a lone child: a browser translation engine reparents that text node, and the removal React runs when the label changes shape or goes away throws. The span is display: contents, so an icon and its label stay flex items of the item and keep its gap. Browser translation covers the mechanism and the rules your own components need.

An icon you pass as a child is now a grandchild of the item, so a [&>svg] class of your own no longer reaches it. Match the part's own variant instead: [&>[data-slot=dropdown-menu-sub-trigger-label]>svg]:size-4. A [&_svg] class or a class on the icon itself loses to the item's default, which carries one more attribute selector.

Prop	Type	Default	Description
`inset?`	`boolean`		When `true`, adds left padding to align with items that have icons.

Data attributes

Data Attribute	Value	Description
`data-slot`	`"dropdown-menu-sub-trigger"`	On the item element.
`data-slot`	`"dropdown-menu-sub-trigger-label"`	On the `<span>` wrapping `children`.

DropdownMenu.SubContent

The content container for submenu items. Appears in a portal with scrolling and animations.

Prop	Type	Default	Description
`loop?`	`boolean`	`true`	When `true`, keyboard navigation will loop from last item to first, and vice versa.