An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file NavHeadingMenuItem.tsx
* @input Uses React, StyleX, Icon, Text, NavMenuContext, useLinkComponent
* @output Exports NavHeadingMenuItem component and NavHeadingMenuItemProps type
* @position Core implementation; consumed by index.ts
*
* SYNC: When modified, update:
* - /packages/core/src/NavMenu/index.ts
*/
import React, {useCallback, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {renderIconSlot, type IconType} from '../Icon';
import {Text} from '../Text';
import {
colorVars,
spacingVars,
typographyVars,
typeScaleVars,
radiusVars,
} from '../theme/tokens.stylex';
import {composeEventHandlers} from '../utils/composeEventHandlers';
import {mergeProps} from '../utils/mergeProps';
import {useFocusAcrossSwap} from '../utils/useFocusAcrossSwap';
import type {BaseProps} from '../BaseProps';
import {useNavHeadingMenuContext} from './NavMenuContext';
import {useLinkComponent} from '../Link/useLinkComponent';
import {themeProps} from '../utils/themeProps';
import {isRenderable} from '../utils/isRenderable';
import {keepDisabledRowUnfocused} from '../DropdownMenu/menuItemRoles';
const styles = stylex.create({
root: {
boxSizing: 'border-box',
// A held pointer slides across the items; it selects no item text.
// Caller content beside the items stays selectable.
userSelect: 'none',
display: 'flex',
alignItems: 'center',
gap: spacingVars['--spacing-2'],
width: '100%',
borderRadius: radiusVars['--radius-element'],
fontFamily: typographyVars['--font-family-body'],
fontSize: typeScaleVars['--text-label-size'],
color: colorVars['--color-text-primary'],
backgroundColor: {
default: 'transparent',
':focus': colorVars['--color-overlay-hover'],
':hover:where(:not(:disabled,[aria-disabled="true"]))': {
'@media (hover: hover)': colorVars['--color-overlay-hover'],
},
},
borderWidth: 0,
borderStyle: 'none',
cursor: {
default: 'pointer',
':is(:disabled,[aria-disabled="true"])': 'default',
},
textAlign: 'start',
outline: 'none',
textDecoration: 'none',
},
content: {
display: 'flex',
flexDirection: 'column',
flex: 1,
minWidth: 0,
},
disabled: {
opacity: 0.5,
cursor: 'default',
},
});
const sizeStyles = stylex.create({
sm: {
paddingBlock: spacingVars['--spacing-1'],
paddingInline: spacingVars['--spacing-2'],
},
md: {
paddingBlock: spacingVars['--spacing-2'],
paddingInline: spacingVars['--spacing-2'],
},
lg: {
paddingBlock: spacingVars['--spacing-3'],
paddingInline: spacingVars['--spacing-3'],
},
});
export interface NavHeadingMenuItemProps extends Omit<
BaseProps<HTMLElement>,
'onClick'
> {
ref?: React.Ref<HTMLElement>;
/** Icon to display before the label. */
icon?: ReactNode | IconType;
/** Primary label text. */
label: ReactNode;
/** Secondary description text displayed below the label. */
description?: ReactNode;
/** URL to navigate to. Renders as an anchor element when provided. */
href?: string;
/** Callback when the item is selected. */
onClick?: () => void;
/** Whether the item is disabled. @default false */
isDisabled?: boolean;
}
/**
* Menu item for nav heading popovers.
*
* Reads size from the parent NavHeadingMenu for consistent padding.
* Automatically dismisses the menu on click via context.
* Renders as a link when `href` is provided.
*
* @example
* ```
* <NavHeadingMenu>
* <NavHeadingMenuItem label="Dashboard" href="/dashboard" />
* <NavHeadingMenuItem label="Settings" icon={GearIcon} onClick={open} />
* </NavHeadingMenu>
* ```
*/
export function NavHeadingMenuItem({
ref,
icon,
label,
description,
href,
onClick,
isDisabled = false,
xstyle,
className,
style,
'data-testid': testId,
...restProps
}: NavHeadingMenuItemProps) {
const ctx = useNavHeadingMenuContext();
const size = ctx?.size ?? 'md';
const handleClick = useCallback(() => {
if (isDisabled) {
return;
}
onClick?.();
ctx?.closeMenu();
}, [isDisabled, onClick, ctx]);
const LinkComponent = useLinkComponent();
// A disabled link item must not navigate (spec:AST-085 FR2). Cancelling the
// click would leave the destination live for middle-click, assistive
// technology activation, and "open in new tab", so the item drops its href
// instead. The router LinkComponent is skipped too: some routers reject a
// missing destination. A plain anchor keeps the row's element shape.
// (Mirrors the disabled paths of Link, Tab, and TopNavItem.)
const Element = href ? (isDisabled ? 'a' : LinkComponent) : 'div';
// The element type above changes when `isDisabled` flips, so React replaces
// the row; focus follows to the replacement (spec:AST-085 FR4).
const itemRef = useFocusAcrossSwap<HTMLElement>(ref);
return (
<Element
{...restProps}
onMouseDown={composeEventHandlers(
restProps.onMouseDown,
isDisabled ? keepDisabledRowUnfocused : undefined,
)}
ref={itemRef}
role="menuitem"
// Every row, disabled included, takes focus but is not a Tab stop.
tabIndex={-1}
aria-disabled={isDisabled || undefined}
href={isDisabled ? undefined : href}
// A menu row is never a draggable link: a mouse press that slides to
// another row would start a drag and cancel the press.
draggable={href != null ? false : undefined}
onClick={handleClick}
data-testid={testId}
{...mergeProps(
themeProps('nav-heading-menu-item', {size}),
stylex.props(
styles.root,
sizeStyles[size],
isDisabled && styles.disabled,
xstyle,
),
className,
style,
)}>
{icon && renderIconSlot(icon, {size: 'sm', color: 'secondary'})}
<span {...stylex.props(styles.content)}>
{typeof label === 'string' ? (
<Text type="body" maxLines={1}>
{label}
</Text>
) : (
label
)}
{isRenderable(description) && (
<Text type="supporting" maxLines={1}>
{description}
</Text>
)}
</span>
</Element>
);
}
NavHeadingMenuItem.displayName = 'NavHeadingMenuItem';