Dropdown
⋯
Dropdown Menu renders the Nesra Basic, Submenu, Multiple, and Destructive action-menu layouts and the
Dropdown Item Notif Read and Notif Unread items on Base UI Menu. Multiple shows a long, scrollable list of actions. It does not select multiple values.
Use Select or Combobox when a trigger chooses a value.
import { DropdownMenu } from "@nesra/ui/dropdown-menu";
export function Actions({ onExport }: { onExport: () => void }) { return ( <DropdownMenu> <DropdownMenu.Trigger>Actions</DropdownMenu.Trigger> <DropdownMenu.Content> <DropdownMenu.Item onClick={onExport}>Export report</DropdownMenu.Item> </DropdownMenu.Content> </DropdownMenu> );}DropdownMenu is also exported from @nesra/ui. Content renders the portal, positioner, and
popup. Trigger renders a button by default. Its render prop can compose a custom control.
Composition
Section titled “Composition”DropdownMenu├── DropdownMenu.Trigger└── DropdownMenu.Content ├── DropdownMenu.Item ├── DropdownMenu.NotificationItem ├── DropdownMenu.Group │ ├── DropdownMenu.Label │ └── DropdownMenu.Item ├── DropdownMenu.Separator └── DropdownMenu.Sub ├── DropdownMenu.SubTrigger └── DropdownMenu.SubContentExamples
Section titled “Examples”import { Button } from "@nesra/ui/button";import { useState } from "react";import { DropdownMenu } from "@nesra/ui/dropdown-menu";
export function BasicDropdownMenuExample() { const [lastAction, setLastAction] = useState<string | null>(null);
return ( <div className="flex flex-col items-start gap-nesra-gap-3"> <DropdownMenu> <DropdownMenu.Trigger render={<Button variant="outline" />}> Account actions </DropdownMenu.Trigger> <DropdownMenu.Content align="start"> <DropdownMenu.Group> <DropdownMenu.Label>Account</DropdownMenu.Label> <DropdownMenu.Item onClick={() => setLastAction("Profile")}>Profile</DropdownMenu.Item> <DropdownMenu.Item onClick={() => setLastAction("Settings")}> Settings </DropdownMenu.Item> <DropdownMenu.Item disabled>Billing unavailable</DropdownMenu.Item> </DropdownMenu.Group> </DropdownMenu.Content> </DropdownMenu> <p aria-live="polite">{lastAction ? `Selected: ${lastAction}` : "Select an action"}</p> </div> );}Controlled open state
Section titled “Controlled open state”Use open and onOpenChange when the page needs to observe or control whether the menu is open.
import { Button } from "@nesra/ui/button";import { useState } from "react";import { DropdownMenu } from "@nesra/ui/dropdown-menu";
export function ControlledDropdownMenuExample() { const [open, setOpen] = useState(false);
return ( <div className="flex flex-col items-start gap-nesra-gap-3"> <DropdownMenu open={open} onOpenChange={setOpen}> <DropdownMenu.Trigger render={<Button variant="outline" />}> More actions </DropdownMenu.Trigger> <DropdownMenu.Content align="start"> <DropdownMenu.Item>Edit profile</DropdownMenu.Item> <DropdownMenu.Item>View activity</DropdownMenu.Item> </DropdownMenu.Content> </DropdownMenu> <p aria-live="polite">Menu is {open ? "open" : "closed"}</p> </div> );}Icon-only trigger
Section titled “Icon-only trigger”Give an icon-only trigger an accessible name with aria-label.
import { Button } from "@nesra/ui/button";import { Ellipsis } from "lucide-react";import { useState } from "react";import { DropdownMenu } from "@nesra/ui/dropdown-menu";
export function IconTriggerDropdownMenuExample() { const [lastAction, setLastAction] = useState<string | null>(null);
return ( <div className="flex flex-col items-start gap-nesra-gap-3"> <DropdownMenu> <DropdownMenu.Trigger aria-label="More actions" render={<Button variant="outline" size="icon-md" />} > <Ellipsis aria-hidden="true" size={20} /> </DropdownMenu.Trigger> <DropdownMenu.Content align="start"> <DropdownMenu.Item onClick={() => setLastAction("Copy link")}> Copy link </DropdownMenu.Item> <DropdownMenu.Item onClick={() => setLastAction("Archive")}>Archive</DropdownMenu.Item> </DropdownMenu.Content> </DropdownMenu> <p aria-live="polite">{lastAction ? `Selected: ${lastAction}` : "Select an action"}</p> </div> );}Avatar trigger
Section titled “Avatar trigger”render can supply a custom button. Give the avatar button an aria-label.
import { DropdownMenu } from "@nesra/ui/dropdown-menu";
export function AvatarTriggerDropdownMenuExample() { return ( <DropdownMenu> <DropdownMenu.Trigger render={ <button type="button" aria-label="Account actions" className="flex size-nesra-unit-19 items-center justify-center rounded-full bg-nesra-action-primary-default text-nesra-text-on-brand" /> } > AL </DropdownMenu.Trigger> <DropdownMenu.Content align="start"> <DropdownMenu.Item>Profile</DropdownMenu.Item> <DropdownMenu.Item>Settings</DropdownMenu.Item> <DropdownMenu.Separator /> <DropdownMenu.Item variant="destructive">Sign out</DropdownMenu.Item> </DropdownMenu.Content> </DropdownMenu> );}Keep the menu open
Section titled “Keep the menu open”Set closeOnClick={false} on an action that should leave the menu open after activation.
import { Button } from "@nesra/ui/button";import { DropdownMenu } from "@nesra/ui/dropdown-menu";import { useState } from "react";
export function KeepOpenDropdownMenuExample() { const [refreshCount, setRefreshCount] = useState(0);
return ( <div className="flex flex-col items-start gap-nesra-gap-3"> <DropdownMenu> <DropdownMenu.Trigger render={<Button variant="outline" />}> Preview actions </DropdownMenu.Trigger> <DropdownMenu.Content align="start"> <DropdownMenu.Item closeOnClick={false} onClick={() => setRefreshCount((count) => count + 1)} > Refresh preview </DropdownMenu.Item> <DropdownMenu.Item>Done</DropdownMenu.Item> </DropdownMenu.Content> </DropdownMenu> <p aria-live="polite">Refresh count: {refreshCount}</p> </div> );}Placement
Section titled “Placement”Content forwards side, align, and sideOffset to the positioner. Viewport collisions can
change the rendered placement.
import { Button } from "@nesra/ui/button";import { DropdownMenu } from "@nesra/ui/dropdown-menu";
export function PlacementDropdownMenuExample() { return ( <DropdownMenu> <DropdownMenu.Trigger render={<Button variant="outline" />}>Menu above</DropdownMenu.Trigger> <DropdownMenu.Content side="top" align="end" sideOffset={8}> <DropdownMenu.Item>Move up</DropdownMenu.Item> <DropdownMenu.Item>Move down</DropdownMenu.Item> </DropdownMenu.Content> </DropdownMenu> );}Submenu
Section titled “Submenu”DropdownMenu.Sub owns each nested menu. SubTrigger renders the trailing chevron.
import { Button } from "@nesra/ui/button";import { DropdownMenu } from "@nesra/ui/dropdown-menu";
export function SubmenuDropdownMenuExample() { return ( <DropdownMenu> <DropdownMenu.Trigger render={<Button variant="outline" />}> File actions </DropdownMenu.Trigger> <DropdownMenu.Content align="start"> <DropdownMenu.Item onClick={() => alert("Rename")}>Rename</DropdownMenu.Item> <DropdownMenu.Sub> <DropdownMenu.SubTrigger>Share</DropdownMenu.SubTrigger> <DropdownMenu.SubContent> <DropdownMenu.Item onClick={() => alert("Copy link")}>Copy link</DropdownMenu.Item> <DropdownMenu.Item onClick={() => alert("Send email")}>Send by email</DropdownMenu.Item> </DropdownMenu.SubContent> </DropdownMenu.Sub> </DropdownMenu.Content> </DropdownMenu> );}Multiple
Section titled “Multiple”The popup limits its height to the available viewport space and scrolls long menus.
import { Button } from "@nesra/ui/button";import { DropdownMenu } from "@nesra/ui/dropdown-menu";
export function MultipleDropdownMenuExample() { return ( <DropdownMenu> <DropdownMenu.Trigger render={<Button variant="outline" />}> Recent files </DropdownMenu.Trigger> <DropdownMenu.Content align="start"> <DropdownMenu.Group> <DropdownMenu.Label>Recent files</DropdownMenu.Label> {Array.from({ length: 12 }, (_, index) => ( <DropdownMenu.Item key={index} onClick={() => alert(`Open file ${index + 1}`)}> File {index + 1} </DropdownMenu.Item> ))} </DropdownMenu.Group> </DropdownMenu.Content> </DropdownMenu> );}Destructive
Section titled “Destructive”variant="destructive" changes the item text color. The consuming application owns the action and
any confirmation step.
import { Button } from "@nesra/ui/button";import { DropdownMenu } from "@nesra/ui/dropdown-menu";
export function DestructiveDropdownMenuExample() { return ( <DropdownMenu> <DropdownMenu.Trigger render={<Button variant="outline" />}> Record actions </DropdownMenu.Trigger> <DropdownMenu.Content align="start"> <DropdownMenu.Item onClick={() => alert("Edit")}>Edit</DropdownMenu.Item> <DropdownMenu.Item onClick={() => alert("Duplicate")}>Duplicate</DropdownMenu.Item> <DropdownMenu.Separator /> <DropdownMenu.Item variant="destructive" onClick={() => alert("Delete")}> Delete </DropdownMenu.Item> </DropdownMenu.Content> </DropdownMenu> );}Item content
Section titled “Item content”Icons, shortcuts, and supporting text are children of the item. Set label for typeahead when the
item contains more than its name.
import { Button } from "@nesra/ui/button";import { UserRound } from "lucide-react";import { DropdownMenu } from "@nesra/ui/dropdown-menu";
export function ContentDropdownMenuExample() { return ( <DropdownMenu> <DropdownMenu.Trigger render={<Button variant="outline" />}> More actions </DropdownMenu.Trigger> <DropdownMenu.Content align="start"> <DropdownMenu.Item label="Profile"> <UserRound aria-hidden="true" size={16} /> <span className="flex-1">Profile</span> <span aria-hidden="true" className="text-nesra-text-support"> ⌘P </span> </DropdownMenu.Item> <DropdownMenu.Item label="Settings"> <span className="flex min-w-0 flex-col"> <span>Settings</span> <span className="type-nesra-body-xsmall-regular text-nesra-text-support"> Workspace and billing </span> </span> </DropdownMenu.Item> </DropdownMenu.Content> </DropdownMenu> );}Notifications
Section titled “Notifications”DropdownMenu.NotificationItem renders the Figma Notif Unread and Notif Read items: a bordered icon
tile, the title, a short description, and a time. unread adds the unread dot and the bell-with-dot
icon. The example marks a notification as read when it is activated. The application owns that state.
import { Button } from "@nesra/ui/button";import { DropdownMenu } from "@nesra/ui/dropdown-menu";import { useState } from "react";
const initial = [ { id: "welcome", title: "Welcome to Nesra", description: "Hi Jessie! Set up your profile to make learning more fun.", time: "1h ago", unread: true, }, { id: "report", title: "Weekly report", description: "Your weekly report is ready to review.", time: "2d ago", unread: false, },];
export function NotificationsDropdownMenuExample() { const [notifications, setNotifications] = useState(initial); const unreadCount = notifications.filter((item) => item.unread).length;
return ( <DropdownMenu> <DropdownMenu.Trigger render={<Button variant="outline" />}> Notifications ({unreadCount} unread) </DropdownMenu.Trigger> <DropdownMenu.Content align="start" className="w-[375px]"> {notifications.map((item) => ( <DropdownMenu.NotificationItem description={item.description} key={item.id} onClick={() => setNotifications((current) => current.map((entry) => entry.id === item.id ? { ...entry, unread: false } : entry, ), ) } time={item.time} title={item.title} unread={item.unread} /> ))} </DropdownMenu.Content> </DropdownMenu> );}Light and Dark
Section titled “Light and Dark”The menu follows the Figma Dropdown Menu roles in both modes: the popup uses
--nesra-foundation-bg-neutral with --nesra-stroke-border and shadow-nesra-lg, highlighted items
use --nesra-action-secondary-hover, DropdownMenu.Label uses --nesra-text-support, and
DropdownMenu.Separator uses --nesra-stroke-divider. A notification item uses
--nesra-text-body for the title and --nesra-text-support for the description and time. Its icon
tile is --nesra-surface-card-bg-neutral with a --nesra-stroke-border border and shadow-nesra-xs.
The unread dot and unread icon use --nesra-icon-brand-primary, and the read icon uses
--nesra-icon-muted. Item icons inherit the item text color, so
they read as icon-neutral, icon-disabled, or icon-destructive with the item state. When an icon
sits on a fixed fill that does not switch with the theme, set text-nesra-icon-static-dark or
text-nesra-icon-static-white on that icon. Content on --nesra-action-primary-default, such as
the avatar trigger example, uses text-nesra-text-on-brand.
Accessibility
Section titled “Accessibility”- Give the trigger an accessible name. Icon-only triggers require
aria-label. - Arrow keys move focus among items, typing finds an item by label, and Enter or Space activates it. Right Arrow opens a submenu. Left Arrow returns to its trigger. Escape closes the menu and returns focus to the trigger by default.
- Disabled items remain discoverable by keyboard with
aria-disabled, but cannot activate. DropdownMenu.Labelnames its containing group. Keep item text or the Base UIlabelprop meaningful for typeahead and assistive technology.- Icons, supporting text, shortcuts, and counts belong in item children.
- A notification item is named by its title. An unread item is named “Unread,” followed by the title, so the
state does not depend on the dot alone. The description and time describe the item through
aria-describedby. The unread text is translatable throughNesraI18nProviderorunreadLabel. - The application owns notification read status and updates it when an action requires that change.
API reference
Section titled “API reference”DropdownMenu
Section titled “DropdownMenu”Owns the menu’s open state and forwards Base UI Menu Root props.
| Prop | Type | Default | Effect |
|---|---|---|---|
open |
boolean |
— | Controls whether the menu is open. |
defaultOpen |
boolean |
false |
Sets the initial uncontrolled state. |
onOpenChange |
(open: boolean, details) => void |
— | Runs when the open state changes. |
DropdownMenu.Trigger
Section titled “DropdownMenu.Trigger”Opens the menu. Accepts Base UI Menu Trigger button props, including render for composition and
disabled. Forwards its ref to the button and accepts className.
DropdownMenu.Content
Section titled “DropdownMenu.Content”Renders a portal, positioner, and popup. The ref points to the popup. className styles the popup,
container selects the portal host, and inherited Base UI Positioner props such as side, align,
sideOffset, and collisionPadding control placement. sideOffset defaults to 4px.
The popup renders at 250px width, constrained by the viewport. side defaults to
"bottom" for a root menu, and align defaults to "center". Base UI flips the popup near
viewport edges.
DropdownMenu.Item
Section titled “DropdownMenu.Item”Invokes the inherited onClick handler. disabled blocks activation and closeOnClick defaults
to true. Other Base UI Menu Item props, including label for typeahead, are forwarded.
| Prop | Type | Default | Effect |
|---|---|---|---|
variant |
"default" | "destructive" |
"default" |
Changes the text color for destructive actions. |
The item accepts className and forwards its ref to the rendered item.
DropdownMenu.NotificationItem
Section titled “DropdownMenu.NotificationItem”A DropdownMenu.Item with the Figma notification layout. It forwards Base UI Menu Item props,
including onClick, disabled, closeOnClick, and className, and forwards its ref. It does not
accept children or variant.
| Prop | Type | Default | Effect |
|---|---|---|---|
title |
ReactNode |
Required | Medium 14px header. Names the item. |
description |
ReactNode |
— | Regular 12px text in text-support. Describes the item. |
time |
ReactNode |
— | Regular 12px text at the end. Describes the item after description. |
icon |
ReactNode |
Bell, or bell with dot | 16px icon inside the 28px tile. |
unread |
boolean |
false |
Shows the 6px unread dot, sets data-unread, and prefixes the name. |
unreadLabel |
string |
Translated "Unread" |
Text announced before the title when unread is set. |
label |
string |
title when a string |
Typeahead text. |
DropdownMenu.Group
Section titled “DropdownMenu.Group”Groups related items. Accepts Base UI Menu Group props and className and forwards its ref to the
group element.
DropdownMenu.Label
Section titled “DropdownMenu.Label”Names its containing group. Accepts Base UI Menu Group Label props and className and forwards its
ref to the label element.
DropdownMenu.Separator
Section titled “DropdownMenu.Separator”Separates item groups. Accepts Base UI Menu Separator props and className and forwards its ref to
the separator element.
DropdownMenu.Sub
Section titled “DropdownMenu.Sub”Owns a nested menu and forwards Base UI Menu Submenu Root props. Place SubTrigger and SubContent
inside this root.
DropdownMenu.SubTrigger
Section titled “DropdownMenu.SubTrigger”Opens the nested menu and renders a trailing chevron. Accepts Base UI Menu Submenu Trigger props
and className and forwards its ref to the rendered trigger.
DropdownMenu.SubContent
Section titled “DropdownMenu.SubContent”Uses the same props and rendering as DropdownMenu.Content inside a submenu.
Rendered parts accept className as a string or a Base UI state callback. Their classes are merged
with Nesra’s defaults.
Named prop types are available from @nesra/ui and @nesra/ui/dropdown-menu for wrapping public
parts, such as DropdownMenuItemProps, DropdownMenuNotificationItemProps, and
DropdownMenuContentProps. SubContent uses
DropdownMenuContentProps.
The menu uses the light color roles, typography, layout scale, and shape and elevation tokens.