Dropdown menu
A menu button following the ARIA menu pattern: arrow keys with wrap-around, Home and End, typeahead, Escape to close and return focus, Tab to leave, and click-outside to dismiss. Composable parts for groups with labels, separators, icons, keyboard shortcut hints with aria-keyshortcuts, disabled and destructive items, and checkbox items that stay open while toggling.
Source
"use client";
import {
createContext, useCallback, useContext, useEffect, useId, useRef, useState,
type ButtonHTMLAttributes, type HTMLAttributes, type KeyboardEvent, type MouseEvent, type PointerEvent as ReactPointerEvent,
type ReactNode,
} from "react";
import { Check } from "lucide-react";
import { cn } from "@/lib/utils";
type FocusTarget = "first" | "last" | null;
interface MenuContextValue {
open: boolean;
setOpen: (open: boolean, options?: { focus?: FocusTarget; restoreFocus?: boolean }) => void;
pendingFocus: { current: FocusTarget };
triggerRef: { current: HTMLButtonElement | null };
menuRef: { current: HTMLDivElement | null };
triggerId: string;
menuId: string;
}
const MenuContext = createContext<MenuContextValue | null>(null);
function useMenu(component: string) {
const context = useContext(MenuContext);
if (!context) throw new Error(`<${component}> must be used inside <DropdownMenu>.`);
return context;
}
const ITEM_SELECTOR = '[role="menuitem"],[role="menuitemcheckbox"],[role="menuitemradio"]';
function items(menu: HTMLElement | null) {
return Array.from(menu?.querySelectorAll<HTMLElement>(ITEM_SELECTOR) ?? []).filter((item) => item.getAttribute("aria-disabled") !== "true");
}
export interface DropdownMenuProps {
children: ReactNode;
open?: boolean;
defaultOpen?: boolean;
onOpenChange?: (open: boolean) => void;
className?: string;
}
export function DropdownMenu({ children, open: controlled, defaultOpen = false, onOpenChange, className }: DropdownMenuProps) {
const id = useId();
const [uncontrolled, setUncontrolled] = useState(defaultOpen);
const open = controlled ?? uncontrolled;
const rootRef = useRef<HTMLDivElement>(null);
const triggerRef = useRef<HTMLButtonElement | null>(null);
const menuRef = useRef<HTMLDivElement | null>(null);
const pendingFocus = useRef<FocusTarget>(null);
const setOpen = useCallback((next: boolean, options: { focus?: FocusTarget; restoreFocus?: boolean } = {}) => {
pendingFocus.current = next ? options.focus ?? null : null;
if (controlled === undefined) setUncontrolled(next);
onOpenChange?.(next);
if (!next && options.restoreFocus) triggerRef.current?.focus();
}, [controlled, onOpenChange]);
// Pointer down outside closes the menu without stealing focus from what was clicked.
useEffect(() => {
if (!open) return;
function handlePointer(event: PointerEvent) {
if (!rootRef.current?.contains(event.target as Node)) setOpen(false);
}
document.addEventListener("pointerdown", handlePointer);
return () => document.removeEventListener("pointerdown", handlePointer);
}, [open, setOpen]);
return (
<MenuContext.Provider value={{ open, setOpen, pendingFocus, triggerRef, menuRef, triggerId: `${id}-trigger`, menuId: `${id}-menu` }}>
<div ref={rootRef} className={cn("relative inline-flex", className)}>{children}</div>
</MenuContext.Provider>
);
}
export const triggerClassName =
"inline-flex h-9 items-center justify-center gap-2 rounded-md border border-border bg-background px-3.5 text-sm font-medium " +
"text-foreground shadow-xs outline-hidden transition-colors hover:bg-accent focus-visible:ring-[3px] focus-visible:ring-ring/50 " +
"aria-expanded:bg-accent dark:border-input dark:bg-input/20 dark:hover:bg-input/40 dark:aria-expanded:bg-input/40 [&_svg]:size-4 [&_svg]:shrink-0";
/** The menu button. Pass className to restyle it, or `unstyled` to start from nothing. */
export function DropdownMenuTrigger({ className, unstyled, onClick, onKeyDown, ...props }: ButtonHTMLAttributes<HTMLButtonElement> & { unstyled?: boolean }) {
const { open, setOpen, triggerRef, triggerId, menuId } = useMenu("DropdownMenuTrigger");
return (
<button
ref={triggerRef}
id={triggerId}
type="button"
aria-haspopup="menu"
aria-expanded={open}
aria-controls={open ? menuId : undefined}
onClick={(event) => {
onClick?.(event);
if (!event.defaultPrevented) setOpen(!open, { focus: "first" });
}}
onKeyDown={(event) => {
onKeyDown?.(event);
if (event.defaultPrevented) return;
if (event.key === "ArrowDown" || event.key === "ArrowUp") {
event.preventDefault();
setOpen(true, { focus: event.key === "ArrowDown" ? "first" : "last" });
}
}}
className={cn(!unstyled && triggerClassName, className)}
{...props}
/>
);
}
export interface DropdownMenuContentProps extends HTMLAttributes<HTMLDivElement> {
align?: "start" | "end";
side?: "bottom" | "top";
}
export function DropdownMenuContent({ align = "start", side = "bottom", className, children, ...props }: DropdownMenuContentProps) {
const { open, setOpen, pendingFocus, menuRef, triggerId, menuId } = useMenu("DropdownMenuContent");
const typed = useRef({ text: "", timer: undefined as ReturnType<typeof setTimeout> | undefined });
// Opened from the keyboard or a click: move focus to the first or last item.
useEffect(() => {
if (!open) return;
const target = pendingFocus.current;
pendingFocus.current = null;
const list = items(menuRef.current);
if (target === "first") list[0]?.focus();
else if (target === "last") list[list.length - 1]?.focus();
}, [open, pendingFocus, menuRef]);
useEffect(() => () => clearTimeout(typed.current.timer), []);
function handleKeyDown(event: KeyboardEvent<HTMLDivElement>) {
const list = items(menuRef.current);
const index = list.indexOf(document.activeElement as HTMLElement);
const focusAt = (next: number) => list[(next + list.length) % list.length]?.focus();
switch (event.key) {
case "ArrowDown":
event.preventDefault();
focusAt(index + 1);
return;
case "ArrowUp":
event.preventDefault();
focusAt(index < 0 ? -1 : index - 1);
return;
case "Home":
case "PageUp":
event.preventDefault();
focusAt(0);
return;
case "End":
case "PageDown":
event.preventDefault();
focusAt(-1);
return;
case "Escape":
event.preventDefault();
event.stopPropagation();
setOpen(false, { restoreFocus: true });
return;
case "Tab":
setOpen(false);
return;
}
// Typeahead: jump to the next item whose text starts with what was typed in the last half second.
if (event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey && event.key !== " ") {
const state = typed.current;
clearTimeout(state.timer);
state.text += event.key.toLowerCase();
state.timer = setTimeout(() => (state.text = ""), 500);
const repeated = state.text.split("").every((char) => char === state.text[0]);
const query = repeated ? state.text[0] : state.text;
const ordered = [...list.slice(index + 1), ...list.slice(0, index + 1)];
const start = repeated || index < 0 ? ordered : [list[index], ...ordered];
const match = start.find((item) => (item.dataset.textValue ?? item.textContent ?? "").trim().toLowerCase().startsWith(query));
match?.focus();
}
}
if (!open) return null;
return (
<div
ref={menuRef}
id={menuId}
role="menu"
aria-labelledby={triggerId}
aria-orientation="vertical"
tabIndex={-1}
onKeyDown={handleKeyDown}
className={cn(
"absolute z-50 flex w-max min-w-[13rem] max-w-[min(20rem,calc(100vw-2rem))] flex-col rounded-lg border border-border",
"bg-popover p-1 text-popover-foreground shadow-[0_16px_40px_-12px_rgb(0_0_0/0.25),0_2px_6px_-2px_rgb(0_0_0/0.08)] outline-hidden",
"dark:shadow-[0_16px_40px_-12px_rgb(0_0_0/0.7)] transition-[opacity,translate,scale] duration-150 ease-out starting:opacity-0",
side === "bottom" ? "top-[calc(100%+6px)] origin-top motion-safe:starting:-translate-y-1" : "bottom-[calc(100%+6px)] origin-bottom motion-safe:starting:translate-y-1",
"motion-safe:starting:scale-[0.97]",
align === "start" ? "left-0" : "right-0",
className,
)}
{...props}
>
{children}
</div>
);
}
const itemClassName =
"relative flex h-8 w-full cursor-default select-none items-center gap-2.5 rounded-md px-2 text-sm outline-hidden " +
"aria-disabled:pointer-events-none aria-disabled:opacity-45 [&_svg]:size-4 [&_svg]:shrink-0";
const itemTone = {
default: "text-popover-foreground focus:bg-accent focus:text-accent-foreground",
destructive: "text-destructive focus:bg-destructive/10 focus:text-destructive dark:focus:bg-destructive/15",
};
function Shortcut({ children }: { children: ReactNode }) {
return <kbd className="ml-auto pl-4 font-sans text-xs tracking-wide text-muted-foreground">{children}</kbd>;
}
export interface DropdownMenuItemProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect" | "onClick" | "onKeyDown"> {
/** Runs on click, Enter or Space. Call event.preventDefault() to keep the menu open. */
onSelect?: (event: MouseEvent<HTMLDivElement> | KeyboardEvent<HTMLDivElement>) => void;
icon?: ReactNode;
/** Shown on the right, such as "⌘D". Wire the actual key handling yourself. */
shortcut?: string;
/** Exposed as aria-keyshortcuts, such as "Meta+D". */
keyshortcuts?: string;
destructive?: boolean;
disabled?: boolean;
/** Text used for typeahead when the children are not plain text. */
textValue?: string;
}
function useActivate(onActivate: (event: MouseEvent<HTMLDivElement> | KeyboardEvent<HTMLDivElement>) => boolean | void, disabled?: boolean) {
const { setOpen, menuRef } = useMenu("DropdownMenuItem");
function run(event: MouseEvent<HTMLDivElement> | KeyboardEvent<HTMLDivElement>) {
if (disabled) return;
const keepOpen = onActivate(event);
if (!keepOpen && !event.defaultPrevented) setOpen(false, { restoreFocus: true });
}
return {
onClick: run,
onKeyDown: (event: KeyboardEvent<HTMLDivElement>) => {
if (event.key === "Enter" || event.key === " ") {
run(event);
// Also stops the key from clicking the trigger, which receives focus as the menu closes.
event.preventDefault();
}
},
// Hover moves focus, as in native menus; leaving clears it.
onPointerMove: (event: ReactPointerEvent<HTMLDivElement>) => {
if (!disabled && event.pointerType === "mouse" && document.activeElement !== event.currentTarget) event.currentTarget.focus();
},
onPointerLeave: () => menuRef.current?.focus(),
};
}
export function DropdownMenuItem({
onSelect, icon, shortcut, keyshortcuts, destructive, disabled, textValue, className, children, ...props
}: DropdownMenuItemProps) {
const handlers = useActivate((event) => onSelect?.(event), disabled);
return (
<div
role="menuitem"
tabIndex={-1}
aria-disabled={disabled || undefined}
aria-keyshortcuts={keyshortcuts}
data-text-value={textValue}
data-destructive={destructive || undefined}
{...props}
{...handlers}
className={cn(itemClassName, destructive ? itemTone.destructive : itemTone.default, className)}
>
{icon && <span aria-hidden="true" className={cn("flex", destructive ? "text-destructive" : "text-muted-foreground")}>{icon}</span>}
<span className="truncate">{children}</span>
{shortcut && <Shortcut>{shortcut}</Shortcut>}
</div>
);
}
export interface DropdownMenuCheckboxItemProps extends Omit<DropdownMenuItemProps, "onSelect" | "icon" | "destructive"> {
checked: boolean;
onCheckedChange: (checked: boolean) => void;
}
/** A toggle inside the menu. It stays open after toggling so several options can be set in a row. */
export function DropdownMenuCheckboxItem({
checked, onCheckedChange, shortcut, keyshortcuts, disabled, textValue, className, children, ...props
}: DropdownMenuCheckboxItemProps) {
const handlers = useActivate(() => {
onCheckedChange(!checked);
return true;
}, disabled);
return (
<div
role="menuitemcheckbox"
tabIndex={-1}
aria-checked={checked}
aria-disabled={disabled || undefined}
aria-keyshortcuts={keyshortcuts}
data-text-value={textValue}
{...props}
{...handlers}
className={cn(itemClassName, itemTone.default, className)}
>
<span aria-hidden="true" className="flex size-4 items-center justify-center text-foreground">
{checked && <Check />}
</span>
<span className="truncate">{children}</span>
{shortcut && <Shortcut>{shortcut}</Shortcut>}
</div>
);
}
export function DropdownMenuGroup({ label, children, className }: { label?: ReactNode; children: ReactNode; className?: string }) {
const id = useId();
return (
<div role="group" aria-labelledby={label ? id : undefined} className={cn("flex flex-col", className)}>
{label && <div id={id} className="px-2 pb-1 pt-1.5 text-xs font-medium text-muted-foreground">{label}</div>}
{children}
</div>
);
}
export function DropdownMenuSeparator({ className }: { className?: string }) {
return <div role="separator" aria-orientation="horizontal" className={cn("-mx-1 my-1 h-px bg-border", className)} />;
}
