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.

Modals & overlaysComponentTailwind v4

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)} />;
}