Dropdown Menu

Displays a menu to the user—such as a set of actions or functions—triggered by a button.

Features

    Can be controlled or uncontrolled.

    Supports submenus with configurable reading direction.

    Supports items, labels, groups of items.

    Supports checkable items (single or multiple) with optional indeterminate state.

    Supports modal and non-modal modes.

    Customize side, alignment, offsets, collision handling.

    Optionally render a pointing arrow.

    Focus is fully managed.

    Full keyboard navigation.

    Typeahead support.

    Dismissing and layering behavior is highly customizable.

Installation

Install the component from your command line.

npm install @tealess/dropdown-menu

Anatomy

Import all parts and piece them together.

import * as DropdownMenu from "@tealess/dropdown-menu";
export default () => (
<DropdownMenu.Root>
<DropdownMenu.Trigger />
<DropdownMenu.Portal>
<DropdownMenu.Content>
<DropdownMenu.Label />
<DropdownMenu.Item />
<DropdownMenu.Group>
<DropdownMenu.Item />
</DropdownMenu.Group>
<DropdownMenu.CheckboxItem>
<DropdownMenu.ItemIndicator />
</DropdownMenu.CheckboxItem>
<DropdownMenu.RadioGroup>
<DropdownMenu.RadioItem>
<DropdownMenu.ItemIndicator />
</DropdownMenu.RadioItem>
</DropdownMenu.RadioGroup>
<DropdownMenu.Sub>
<DropdownMenu.SubTrigger />
<DropdownMenu.Portal>
<DropdownMenu.SubContent />
</DropdownMenu.Portal>
</DropdownMenu.Sub>
<DropdownMenu.Separator />
<DropdownMenu.Arrow />
</DropdownMenu.Content>
</DropdownMenu.Portal>
</DropdownMenu.Root>
);

API Reference

Root

Contains all the parts of a dropdown menu.

PropTypeDefault
defaultOpen
boolean
No default value
open
boolean
No default value
onOpenChange
function
No default value
modal
boolean
true
dir
enum
No default value

Trigger

The button that toggles the dropdown menu. By default, the DropdownMenu.Content will position itself against the trigger.

PropTypeDefault
asChild
boolean
false
Data attributeValues
[data-state]"open" | "closed"
[data-disabled]

Present when disabled

Portal

When used, portals the content part into the body.

PropTypeDefault
forceMount
boolean
No default value
container
HTMLElement
document.body

Content

The component that pops out when the dropdown menu is open.

PropTypeDefault
asChild
boolean
false
loop
boolean
false
onCloseAutoFocus
function
No default value
onEscapeKeyDown
function
No default value
onPointerDownOutside
function
No default value
onFocusOutside
function
No default value
onInteractOutside
function
No default value
forceMount
boolean
No default value
side
enum
"bottom"
sideOffset
number
0
align
enum
"center"
alignOffset
number
0
avoidCollisions
boolean
true
collisionBoundary
Boundary
[]
collisionPadding
number | Padding
0
arrowPadding
number
0
sticky
enum
"partial"
hideWhenDetached
boolean
false
Data attributeValues
[data-state]"open" | "closed"
[data-side]"left" | "right" | "bottom" | "top"
[data-align]"start" | "end" | "center"
[data-orientation]"vertical" | "horizontal"
CSS VariableDescription
--radix-dropdown-menu-content-transform-originThe transform-origin computed from the content and arrow positions/offsets
--radix-dropdown-menu-content-available-widthThe remaining width between the trigger and the boundary edge
--radix-dropdown-menu-content-available-heightThe remaining height between the trigger and the boundary edge
--radix-dropdown-menu-trigger-widthThe width of the trigger
--radix-dropdown-menu-trigger-heightThe height of the trigger

Arrow

An optional arrow element to render alongside the dropdown menu. This can be used to help visually link the trigger with the DropdownMenu.Content. Must be rendered inside DropdownMenu.Content.

PropTypeDefault
asChild
boolean
false
width
number
10
height
number
5

Item

The component that contains the dropdown menu items.

PropTypeDefault
asChild
boolean
false
disabled
boolean
No default value
onSelect
function
No default value
textValue
string
No default value
Data attributeValues
[data-orientation]"vertical" | "horizontal"
[data-highlighted]

Present when highlighted

[data-disabled]

Present when disabled

Group

Used to group multiple DropdownMenu.Items.

PropTypeDefault
asChild
boolean
false

Label

Used to render a label. It won't be focusable using arrow keys.

PropTypeDefault
asChild
boolean
false

CheckboxItem

An item that can be controlled and rendered like a checkbox.

PropTypeDefault
asChild
boolean
false
checked
boolean | 'indeterminate'
No default value
onCheckedChange
function
No default value
disabled
boolean
No default value
onSelect
function
No default value
textValue
string
No default value
Data attributeValues
[data-state]"checked" | "unchecked" | "indeterminate"
[data-highlighted]

Present when highlighted

[data-disabled]

Present when disabled

RadioGroup

Used to group multiple DropdownMenu.RadioItems.

PropTypeDefault
asChild
boolean
false
value
string
No default value
onValueChange
function
No default value

RadioItem

An item that can be controlled and rendered like a radio.

PropTypeDefault
asChild
boolean
false
value*
string
No default value
disabled
boolean
No default value
onSelect
function
No default value
textValue
string
No default value
Data attributeValues
[data-state]"checked" | "unchecked" | "indeterminate"
[data-highlighted]

Present when highlighted

[data-disabled]

Present when disabled

ItemIndicator

Renders when the parent DropdownMenu.CheckboxItem or DropdownMenu.RadioItem is checked. You can style this element directly, or you can use it as a wrapper to put an icon into, or both.

PropTypeDefault
asChild
boolean
false
forceMount
boolean
No default value
Data attributeValues
[data-state]"checked" | "unchecked" | "indeterminate"

Separator

Used to visually separate items in the dropdown menu.

PropTypeDefault
asChild
boolean
false

Sub

Contains all the parts of a submenu.

PropTypeDefault
defaultOpen
boolean
No default value
open
boolean
No default value
onOpenChange
function
No default value

SubTrigger

An item that opens a submenu. Must be rendered inside DropdownMenu.Sub.

PropTypeDefault
asChild
boolean
false
disabled
boolean
No default value
textValue
string
No default value
Data attributeValues
[data-state]"open" | "closed"
[data-highlighted]

Present when highlighted

[data-disabled]

Present when disabled

CSS VariableDescription
--radix-dropdown-menu-content-transform-originThe transform-origin computed from the content and arrow positions/offsets
--radix-dropdown-menu-content-available-widthThe remaining width between the trigger and the boundary edge
--radix-dropdown-menu-content-available-heightThe remaining height between the trigger and the boundary edge
--radix-dropdown-menu-trigger-widthThe width of the trigger
--radix-dropdown-menu-trigger-heightThe height of the trigger

SubContent

The component that pops out when a submenu is open. Must be rendered inside DropdownMenu.Sub.

PropTypeDefault
asChild
boolean
false
loop
boolean
false
onEscapeKeyDown
function
No default value
onPointerDownOutside
function
No default value
onFocusOutside
function
No default value
onInteractOutside
function
No default value
forceMount
boolean
No default value
sideOffset
number
0
alignOffset
number
0
avoidCollisions
boolean
true
collisionBoundary
Boundary
[]
collisionPadding
number | Padding
0
arrowPadding
number
0
sticky
enum
"partial"
hideWhenDetached
boolean
false
Data attributeValues
[data-state]"open" | "closed"
[data-side]"left" | "right" | "bottom" | "top"
[data-align]"start" | "end" | "center"
[data-orientation]"vertical" | "horizontal"

Examples

With submenus

You can create submenus by using DropdownMenu.Sub in combination with its parts.

<DropdownMenu.Root>
<DropdownMenu.Trigger></DropdownMenu.Trigger>
<DropdownMenu.Portal>
<DropdownMenu.Content>
<DropdownMenu.Item></DropdownMenu.Item>
<DropdownMenu.Item></DropdownMenu.Item>
<DropdownMenu.Separator />
<DropdownMenu.Sub>
<DropdownMenu.SubTrigger>Sub menu →</DropdownMenu.SubTrigger>
<DropdownMenu.Portal>
<DropdownMenu.SubContent>
<DropdownMenu.Item>Sub menu item</DropdownMenu.Item>
<DropdownMenu.Item>Sub menu item</DropdownMenu.Item>
<DropdownMenu.Arrow />
</DropdownMenu.SubContent>
</DropdownMenu.Portal>
</DropdownMenu.Sub>
<DropdownMenu.Separator />
<DropdownMenu.Item></DropdownMenu.Item>
</DropdownMenu.Content>
</DropdownMenu.Portal>
</DropdownMenu.Root>

With disabled items

You can add special styles to disabled items via the data-disabled attribute.

// index.jsx
import * as DropdownMenu from "@tealess/dropdown-menu";
import "./styles.css";
export default () => (
<DropdownMenu.Root>
<DropdownMenu.Trigger></DropdownMenu.Trigger>
<DropdownMenu.Portal>
<DropdownMenu.Content>
<DropdownMenu.Item className="DropdownMenuItem" disabled>
</DropdownMenu.Item>
<DropdownMenu.Item className="DropdownMenuItem"></DropdownMenu.Item>
</DropdownMenu.Content>
</DropdownMenu.Portal>
</DropdownMenu.Root>
);
/* styles.css */
.DropdownMenuItem[data-disabled] {
color: gainsboro;
}

With separators

Use the Separator part to add a separator between items.

<DropdownMenu.Root>
<DropdownMenu.Trigger></DropdownMenu.Trigger>
<DropdownMenu.Portal>
<DropdownMenu.Content>
<DropdownMenu.Item></DropdownMenu.Item>
<DropdownMenu.Separator />
<DropdownMenu.Item></DropdownMenu.Item>
<DropdownMenu.Separator />
<DropdownMenu.Item></DropdownMenu.Item>
</DropdownMenu.Content>
</DropdownMenu.Portal>
</DropdownMenu.Root>

With labels

Use the Label part to help label a section.

<DropdownMenu.Root>
<DropdownMenu.Trigger></DropdownMenu.Trigger>
<DropdownMenu.Portal>
<DropdownMenu.Content>
<DropdownMenu.Label>Label</DropdownMenu.Label>
<DropdownMenu.Item></DropdownMenu.Item>
<DropdownMenu.Item></DropdownMenu.Item>
<DropdownMenu.Item></DropdownMenu.Item>
</DropdownMenu.Content>
</DropdownMenu.Portal>
</DropdownMenu.Root>

With checkbox items

Use the CheckboxItem part to add an item that can be checked.

import React from "react";
import { CheckIcon } from "@tealess/icons";
import * as DropdownMenu from "@tealess/dropdown-menu";
export default () => {
const [checked, setChecked] = React.useState(true);
return (
<DropdownMenu.Root>
<DropdownMenu.Trigger></DropdownMenu.Trigger>
<DropdownMenu.Portal>
<DropdownMenu.Content>
<DropdownMenu.Item></DropdownMenu.Item>
<DropdownMenu.Item></DropdownMenu.Item>
<DropdownMenu.Separator />
<DropdownMenu.CheckboxItem checked={checked} onCheckedChange={setChecked}>
<DropdownMenu.ItemIndicator>
<CheckIcon />
</DropdownMenu.ItemIndicator>
Checkbox item
</DropdownMenu.CheckboxItem>
</DropdownMenu.Content>
</DropdownMenu.Portal>
</DropdownMenu.Root>
);
};

With radio items

Use the RadioGroup and RadioItem parts to add an item that can be checked amongst others.

import React from "react";
import { CheckIcon } from "@tealess/icons";
import * as DropdownMenu from "@tealess/dropdown-menu";
export default () => {
const [color, setColor] = React.useState("blue");
return (
<DropdownMenu.Root>
<DropdownMenu.Trigger></DropdownMenu.Trigger>
<DropdownMenu.Portal>
<DropdownMenu.Content>
<DropdownMenu.RadioGroup value={color} onValueChange={setColor}>
<DropdownMenu.RadioItem value="red">
<DropdownMenu.ItemIndicator>
<CheckIcon />
</DropdownMenu.ItemIndicator>
Red
</DropdownMenu.RadioItem>
<DropdownMenu.RadioItem value="blue">
<DropdownMenu.ItemIndicator>
<CheckIcon />
</DropdownMenu.ItemIndicator>
Blue
</DropdownMenu.RadioItem>
<DropdownMenu.RadioItem value="green">
<DropdownMenu.ItemIndicator>
<CheckIcon />
</DropdownMenu.ItemIndicator>
Green
</DropdownMenu.RadioItem>
</DropdownMenu.RadioGroup>
</DropdownMenu.Content>
</DropdownMenu.Portal>
</DropdownMenu.Root>
);
};

With complex items

You can add extra decorative elements in the Item parts, such as images.

import * as DropdownMenu from "@tealess/dropdown-menu";
export default () => (
<DropdownMenu.Root>
<DropdownMenu.Trigger></DropdownMenu.Trigger>
<DropdownMenu.Portal>
<DropdownMenu.Content>
<DropdownMenu.Item>
<img src="" />
Adolfo Hess
</DropdownMenu.Item>
<DropdownMenu.Item>
<img src="" />
Miyah Myles
</DropdownMenu.Item>
</DropdownMenu.Content>
</DropdownMenu.Portal>
</DropdownMenu.Root>
);

Constrain the content/sub-content size

You may want to constrain the width of the content (or sub-content) so that it matches the trigger (or sub-trigger) width. You may also want to constrain its height to not exceed the viewport.

We expose several CSS custom properties such as --radix-dropdown-menu-trigger-width and --radix-dropdown-menu-content-available-height to support this. Use them to constrain the content dimensions.

// index.jsx
import * as DropdownMenu from "@tealess/dropdown-menu";
import "./styles.css";
export default () => (
<DropdownMenu.Root>
<DropdownMenu.Trigger></DropdownMenu.Trigger>
<DropdownMenu.Portal>
<DropdownMenu.Content className="DropdownMenuContent" sideOffset={5}>
</DropdownMenu.Content>
</DropdownMenu.Portal>
</DropdownMenu.Root>
);
/* styles.css */
.DropdownMenuContent {
width: var(--radix-dropdown-menu-trigger-width);
max-height: var(--radix-dropdown-menu-content-available-height);
}

Origin-aware animations

We expose a CSS custom property --radix-dropdown-menu-content-transform-origin. Use it to animate the content from its computed origin based on side, sideOffset, align, alignOffset and any collisions.

// index.jsx
import * as DropdownMenu from "@tealess/dropdown-menu";
import "./styles.css";
export default () => (
<DropdownMenu.Root>
<DropdownMenu.Trigger></DropdownMenu.Trigger>
<DropdownMenu.Portal>
<DropdownMenu.Content className="DropdownMenuContent"></DropdownMenu.Content>
</DropdownMenu.Portal>
</DropdownMenu.Root>
);
/* styles.css */
.DropdownMenuContent {
transform-origin: var(--radix-dropdown-menu-content-transform-origin);
animation: scaleIn 0.5s ease-out;
}
@keyframes scaleIn {
from {
opacity: 0;
transform: scale(0);
}
to {
opacity: 1;
transform: scale(1);
}
}

Collision-aware animations

We expose data-side and data-align attributes. Their values will change at runtime to reflect collisions. Use them to create collision and direction-aware animations.

// index.jsx
import * as DropdownMenu from "@tealess/dropdown-menu";
import "./styles.css";
export default () => (
<DropdownMenu.Root>
<DropdownMenu.Trigger></DropdownMenu.Trigger>
<DropdownMenu.Portal>
<DropdownMenu.Content className="DropdownMenuContent"></DropdownMenu.Content>
</DropdownMenu.Portal>
</DropdownMenu.Root>
);
/* styles.css */
.DropdownMenuContent {
animation-duration: 0.6s;
animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1);
}
.DropdownMenuContent[data-side="top"] {
animation-name: slideUp;
}
.DropdownMenuContent[data-side="bottom"] {
animation-name: slideDown;
}
@keyframes slideUp {
from {
opacity: 0;
transform: translateY(10px);
}
to {
opacity: 1;
transform: translateY(0);
}
}
@keyframes slideDown {
from {
opacity: 0;
transform: translateY(-10px);
}
to {
opacity: 1;
transform: translateY(0);
}
}

Accessibility

Adheres to the Menu Button WAI-ARIA design pattern and uses roving tabindex to manage focus movement among menu items.

Keyboard Interactions

KeyDescription
Space
When focus is on DropdownMenu.Trigger, opens the dropdown menu and focuses the first item.
When focus is on an item, activates the focused item.
Enter
When focus is on DropdownMenu.Trigger, opens the dropdown menu and focuses the first item.
When focus is on an item, activates the focused item.
ArrowDown
When focus is on DropdownMenu.Trigger, opens the dropdown menu.
When focus is on an item, moves focus to the next item.
ArrowUp
When focus is on an item, moves focus to the previous item.
ArrowRightArrowLeft
When focus is on DropdownMenu.SubTrigger, opens or closes the submenu depending on reading direction.
Esc
Closes the dropdown menu and moves focus to DropdownMenu.Trigger.

Custom APIs

Create your own API by abstracting the primitive parts into your own component.

Abstract the arrow and item indicators

This example abstracts the DropdownMenu.Arrow and DropdownMenu.ItemIndicator parts. It also wraps implementation details for CheckboxItem and RadioItem.

Usage

import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuLabel, DropdownMenuItem, DropdownMenuGroup, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, } from "./your-dropdown-menu";
export default () => (
<DropdownMenu>
<DropdownMenuTrigger>DropdownMenu trigger</DropdownMenuTrigger>
<DropdownMenuContent>
<DropdownMenuItem>Item</DropdownMenuItem>
<DropdownMenuLabel>Label</DropdownMenuLabel>
<DropdownMenuGroup>Group</DropdownMenuGroup>
<DropdownMenuCheckboxItem>CheckboxItem</DropdownMenuCheckboxItem>
<DropdownMenuSeparator>Separator</DropdownMenuSeparator>
<DropdownMenuRadioGroup>
<DropdownMenuRadioItem>RadioItem</DropdownMenuRadioItem>
<DropdownMenuRadioItem>RadioItem</DropdownMenuRadioItem>
</DropdownMenuRadioGroup>
</DropdownMenuContent>
</DropdownMenu>
);

Implementation

// your-dropdown-menu.jsx
import React from "react";
import * as DropdownMenuPrimitive from "@tealess/dropdown-menu";
import { CheckIcon, DividerHorizontalIcon } from "@tealess/icons";
export const DropdownMenu = DropdownMenuPrimitive.Root;
export const DropdownMenuTrigger = DropdownMenuPrimitive.Trigger;
export const DropdownMenuContent = React.forwardRef(({ children, ...props }, forwardedRef) => {
return (
<DropdownMenuPrimitive.Portal>
<DropdownMenuPrimitive.Content {...props} ref={forwardedRef}>
{children}
<DropdownMenuPrimitive.Arrow />
</DropdownMenuPrimitive.Content>
</DropdownMenuPrimitive.Portal>
);
});
export const DropdownMenuLabel = DropdownMenuPrimitive.Label;
export const DropdownMenuItem = DropdownMenuPrimitive.Item;
export const DropdownMenuGroup = DropdownMenuPrimitive.Group;
export const DropdownMenuCheckboxItem = React.forwardRef(({ children, ...props }, forwardedRef) => {
return (
<DropdownMenuPrimitive.CheckboxItem {...props} ref={forwardedRef}>
{children}
<DropdownMenuPrimitive.ItemIndicator>
{props.checked === "indeterminate" && <DividerHorizontalIcon />}
{props.checked === true && <CheckIcon />}
</DropdownMenuPrimitive.ItemIndicator>
</DropdownMenuPrimitive.CheckboxItem>
);
});
export const DropdownMenuRadioGroup = DropdownMenuPrimitive.RadioGroup;
export const DropdownMenuRadioItem = React.forwardRef(({ children, ...props }, forwardedRef) => {
return (
<DropdownMenuPrimitive.RadioItem {...props} ref={forwardedRef}>
{children}
<DropdownMenuPrimitive.ItemIndicator>
<CheckIcon />
</DropdownMenuPrimitive.ItemIndicator>
</DropdownMenuPrimitive.RadioItem>
);
});
export const DropdownMenuSeparator = DropdownMenuPrimitive.Separator;
PreviousDialog
NextForm