An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file DropdownMenuItem.tsx
* @output Exports DropdownMenuItem component
* @position Sub-component; used inside DropdownMenu
*
* Interactive menu item with role="menuitem". Keyboard navigation
* is handled by useListFocus on the parent menu container.
*
* Composes Item for the shared start content + label + description + end content layout.
* Passes role="menuitem" so Item puts onClick on the root div instead of
* creating an invisible button (keyboard access is provided by the parent menu).
* With an `href` the root is a real anchor carrying the role.
*
* Host attributes and DOM handlers the caller passes (aria-*, data-*, id, drag
* and drop, …) reach that row root; the row's own role, tab stop and hover
* focus are set after them, so a caller cannot overwrite them.
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
* - /packages/core/src/DropdownMenu/DropdownMenuItem.doc.mjs
* - /packages/core/src/DropdownMenu/DropdownMenu.test.tsx
* - /packages/core/src/DropdownMenu/index.ts
* - /apps/storybook/stories/DropdownMenu.stories.tsx
* - /packages/cli/assets/templates/blocks/components/DropdownMenu/ (showcase blocks)
*/
import {
useCallback,
type MouseEvent,
type PointerEvent,
type ReactNode,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {renderIconSlot, type IconType} from '../Icon';
import {Item} from '../Item';
import {useLinkComponent} from '../Link/useLinkComponent';
import {
colorVars,
spacingVars,
typographyVars,
typeScaleVars,
focusVars,
} from '../theme/tokens.stylex';
import {composeEventHandlers, mergeProps} from '../utils';
import type {BaseProps} from '../BaseProps';
import {useDropdownMenuContext} from './DropdownMenuContext';
import {focusOutlineStyles} from '../utils/focusOutline.stylex';
import {menuPressLitRowStyle} from '../privateAttributes/menuPressLit.stylex';
import {focusMenuItemOnHover} from './menuItemHover';
import {isModifiedClick, keepDisabledRowUnfocused} from './menuItemRoles';
import {themeProps} from '../utils/themeProps';
import {usePressFeedback} from '../hooks/usePressFeedback';
const menuItemStyles = stylex.create({
root: {
boxSizing: 'border-box',
width: '100%',
paddingBlock: spacingVars['--spacing-2'],
paddingInline: spacingVars['--spacing-2'],
borderRadius: `max(0px, calc(var(--_dropdown-menu-radius, ${spacingVars['--spacing-2']}) - var(--_dropdown-menu-padding, ${spacingVars['--spacing-1']})))`,
fontFamily: typographyVars['--font-family-body'],
fontSize: typeScaleVars['--text-label-size'],
color: colorVars['--color-text-primary'],
backgroundColor: {
default: 'transparent',
// menuPressLitRowStyle sets the variable on the row a held finger or pen
// lights.
':focus': `var(--_menu-row-focus-paint, ${colorVars['--color-overlay-hover']})`,
// The pressed look only where hover exists. Under a finger the row a
// press BEGAN on would otherwise stay painted while the highlight (focus)
// moves to the row under the finger — two rows lit. A held finger or pen
// sets the variable on the menu. Then only the lit row keeps the look.
'@media (hover: hover)': {
default: null,
':active:where(:not(:disabled,[aria-disabled="true"]))': `var(--_menu-row-active-paint, ${colorVars['--color-overlay-pressed']})`,
},
},
borderWidth: 0,
borderStyle: 'none',
cursor: {
default: 'pointer',
':is(:disabled,[aria-disabled="true"])': 'default',
},
textAlign: 'start',
// Rows show focus with a translucent overlay, which forced colors replace
// with the page color. The standard focus ring (focusOutlineStyles), drawn
// inside the row by its own width, marks the focused row in every mode.
outlineOffset: `calc(-1 * ${focusVars['--focus-outline-width']})`,
},
disabled: {
opacity: 0.5,
cursor: 'default',
},
destructive: {
// Only recolor the text/icon; the hover / focus background stays the shared
// neutral overlay from `root` so the hover state matches every other menu
// item. The semantic status foreground covers the label, description, icon,
// and any bare text on a plain surface.
color: colorVars['--color-text-error'],
'--_item-label-color': colorVars['--color-text-error'],
'--_item-description-color': colorVars['--color-text-error'],
},
});
const itemSizeStyles = stylex.create({
sm: {
paddingBlock: spacingVars['--spacing-1'],
paddingInline: spacingVars['--spacing-2'],
},
md: {
paddingBlock: spacingVars['--spacing-1-5'],
},
lg: {},
});
export interface DropdownMenuItemProps extends Omit<
BaseProps,
'role' | 'tabIndex'
> {
/** Icon to display before the label. */
icon?: ReactNode | IconType;
/** Primary label text. */
label: ReactNode;
/** Secondary description text displayed below the label. */
description?: ReactNode;
/**
* Callback when the item is selected. Receives the activating click; a
* keyboard activation (Enter / Space) arrives as a synthesized click that
* carries the key's modifiers. On a row with an `href` it runs before the
* browser navigates, and is skipped for a modified click (⌘, Ctrl, Shift,
* Alt, a middle button), which is left to the browser.
*/
onClick?: (event: MouseEvent) => void;
/**
* Address the row navigates to. The row then renders as a real anchor with
* `role="menuitem"` — a modified click and a middle click keep the
* browser's meaning (a new tab), and `LinkProvider` routes it.
*/
href?: string;
/** Link target. Only used with `href`. */
target?: '_blank' | '_self';
/**
* Link relationship. `noopener noreferrer` is added for `target="_blank"`.
* Only used with `href`.
*/
rel?: string;
/** Whether the item is disabled. @default false */
isDisabled?: boolean;
/** Additional content to render after the label/description. */
endContent?: ReactNode;
/**
* Whether activating the item closes the menu. Set `false` for an action
* that reports its result on the item itself (a copy row swapping to
* "Copied"), matching the checkbox and radio items, which already decide
* this for themselves.
* @default true
*/
hasCloseOnSelect?: boolean;
/**
* Visual variant. `'destructive'` renders the label, description, and icon in
* the error color for dangerous actions (e.g. Delete). @default 'default'
*/
variant?: 'default' | 'destructive';
/**
* Ref forwarded to the row root — the element carrying `role="menuitem"`.
* Lets a caller register the row with an element-keyed observer (an
* IntersectionObserver for an impression, a measurement, a debug overlay)
* the way `Item` and `DropdownMenuDivider` already allow.
*/
ref?: React.Ref<HTMLElement>;
}
/**
* An interactive dropdown menu item with icon, label, and optional description.
*
* Must be used inside DropdownMenu. Keyboard navigation is provided
* automatically by the parent via useListFocus.
*
* @example
* ```
* <DropdownMenu button={{ label: 'Actions' }}>
* <DropdownMenuItem icon={PencilIcon} label="Edit" onClick={handleEdit} />
* <DropdownMenuItem label="Delete" variant="destructive" onClick={handleDelete} />
* </DropdownMenu>
* ```
*/
export function DropdownMenuItem({
icon,
label,
description,
onClick,
href,
target,
rel,
isDisabled = false,
endContent,
hasCloseOnSelect = true,
variant = 'default',
xstyle,
className,
style,
ref,
onPointerMove,
onAuxClick,
...rest
}: DropdownMenuItemProps) {
const ctx = useDropdownMenuContext();
const menuSize = ctx?.menuSize ?? 'md';
// Item marks itself as a pressable surface too; naming the row here as well
// keeps this file's own press arms (above) verifiably reachable by the
// touch press controller (pressableCoverage.test.ts).
const pressable = usePressFeedback();
const handleClick = useCallback(
(event: MouseEvent) => {
if (isDisabled) {
// A disabled link row has no href, but a stray click must still not
// navigate anywhere.
event.preventDefault();
return;
}
// A modified click on a link row is the browser's: it opens the
// address its own way, so the row's handler stays out of it.
// The menu still closes: the row acted.
const isBrowserNavigation = href != null && isModifiedClick(event);
if (!isBrowserNavigation) {
onClick?.(event);
}
if (hasCloseOnSelect) {
ctx?.closeMenu();
}
},
[isDisabled, href, onClick, hasCloseOnSelect, ctx],
);
// A middle click fires `auxclick`, never `click`, so the row's own click
// handler never sees it: the tab opened and the menu stayed open behind
// it. The browser does the navigating; the row only has to close.
const handleAuxClick = useCallback(
(event: MouseEvent) => {
if (isDisabled) {
event.preventDefault();
return;
}
// Button 1 is the middle button. A right click opens the context menu
// and must leave the row's menu alone.
if (href == null || event.button !== 1) {
return;
}
if (hasCloseOnSelect) {
ctx?.closeMenu();
}
},
[isDisabled, href, hasCloseOnSelect, ctx],
);
const handlePointerMove = useCallback(
(e: PointerEvent<HTMLElement>) => focusMenuItemOnHover(e, isDisabled),
[isDisabled],
);
const isDestructive = variant === 'destructive';
const LinkComponent = useLinkComponent();
return (
<Item
{...rest}
onMouseDown={composeEventHandlers(
rest.onMouseDown,
isDisabled ? keepDisabledRowUnfocused : undefined,
)}
ref={ref}
// A row that navigates IS the link: its root is the application's
// anchor, so a modified click, a middle click, copying the address and
// the status bar all keep the browser's meaning. A row without an
// address keeps the default root.
as={href != null ? LinkComponent : undefined}
role="menuitem"
tabIndex={-1}
// The row's own handling runs first, then the caller's.
onPointerMove={composeEventHandlers(handlePointerMove, onPointerMove)}
{...pressable}
startContent={
icon
? renderIconSlot(icon, {
size: 'sm',
color: isDestructive ? 'error' : 'secondary',
})
: undefined
}
label={label}
description={description}
endContent={endContent}
onClick={handleClick}
onAuxClick={composeEventHandlers(handleAuxClick, onAuxClick)}
href={href}
target={target}
rel={rel}
// A menu row is never a draggable link. Under a mouse, the browser's
// native link drag starts a few pixels into a press and cancels the
// pointer stream (`pointercancel`), so the press model could not let
// the row under the release act.
draggable={href != null ? false : undefined}
isDisabled={isDisabled}
xstyle={[
focusOutlineStyles.focusVisible,
menuItemStyles.root,
menuPressLitRowStyle,
itemSizeStyles[menuSize],
isDestructive && menuItemStyles.destructive,
isDisabled && menuItemStyles.disabled,
xstyle,
]}
{...mergeProps(
themeProps('dropdown-menu-item', {
size: menuSize,
variant: isDestructive ? 'destructive' : null,
}),
{
className,
style,
},
)}
/>
);
}
DropdownMenuItem.displayName = 'DropdownMenuItem';