Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(TopNav): add XDSTopNavMenu with hover-triggered overflow menu (#241)

rubyycheung7255ee044547
diff --git a/apps/sandbox/src/app/Sidebar.tsx b/apps/sandbox/src/app/Sidebar.tsx
index 05e0a965c7..c867de60a7 100644
--- a/apps/sandbox/src/app/Sidebar.tsx
+++ b/apps/sandbox/src/app/Sidebar.tsx
@@ -19,6 +19,7 @@ import {usePathname} from 'next/navigation';
const pages = [
{name: 'Home', href: '/'},
{name: 'Example', href: '/pages/example/'},
+ {name: 'TopNav Menu', href: '/pages/topnav-menu/'},
];
const styles = stylex.create({
diff --git a/apps/sandbox/src/app/pages/topnav-menu/page.tsx b/apps/sandbox/src/app/pages/topnav-menu/page.tsx
new file mode 100644
index 0000000000..c5cba84605
--- /dev/null
+++ b/apps/sandbox/src/app/pages/topnav-menu/page.tsx
@@ -0,0 +1,174 @@
+'use client';
+
+import * as stylex from '@stylexjs/stylex';
+import {XDSVStack} from '@xds/core/Layout';
+import {XDSText, XDSHeading} from '@xds/core/Text';
+import {XDSButton} from '@xds/core/Button';
+import {
+ XDSTopNav,
+ XDSTopNavTitle,
+ XDSTopNavTitleIcon,
+ XDSTopNavItem,
+ XDSTopNavMenu,
+} from '@xds/core/TopNav';
+
+const styles = stylex.create({
+ container: {
+ maxWidth: 960,
+ },
+ navWrapper: {
+ borderRadius: 12,
+ overflow: 'hidden',
+ boxShadow: '0 1px 3px rgba(0, 0, 0, 0.08)',
+ },
+});
+
+const LogoIcon = () => (
+ <svg
+ width="16"
+ height="16"
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth="2"
+ strokeLinecap="round"
+ strokeLinejoin="round">
+ <circle cx="12" cy="12" r="3" />
+ <circle cx="12" cy="5" r="1.5" />
+ <circle cx="18.5" cy="8.5" r="1.5" />
+ <circle cx="18.5" cy="15.5" r="1.5" />
+ <circle cx="12" cy="19" r="1.5" />
+ <circle cx="5.5" cy="15.5" r="1.5" />
+ <circle cx="5.5" cy="8.5" r="1.5" />
+ </svg>
+);
+
+const PlaceholderIcon = () => (
+ <svg
+ width="20"
+ height="20"
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth="1.5"
+ strokeLinecap="round"
+ strokeLinejoin="round">
+ <rect x="3" y="3" width="18" height="18" rx="4" />
+ </svg>
+);
+
+const productItems = [
+ {
+ title: 'Approach',
+ description: 'Microbiome science for human health',
+ icon: <PlaceholderIcon />,
+ href: '#approach',
+ },
+ {
+ title: 'Platform',
+ description: 'End-to-end discovery and development',
+ icon: <PlaceholderIcon />,
+ href: '#platform',
+ },
+];
+
+const scienceItems = [
+ {
+ title: 'Research',
+ description: 'Published studies and clinical trials',
+ icon: <PlaceholderIcon />,
+ href: '#research',
+ },
+ {
+ title: 'Publications',
+ description: 'Peer-reviewed papers and white papers',
+ icon: <PlaceholderIcon />,
+ href: '#publications',
+ },
+ {
+ title: 'Team',
+ description: 'Meet our scientific advisory board',
+ icon: <PlaceholderIcon />,
+ href: '#team',
+ },
+];
+
+/**
+ * Demo page for XDSTopNavMenu — a nav item with hover-triggered overflow menu.
+ */
+export default function TopNavMenuPage() {
+ return (
+ <div {...stylex.props(styles.container)}>
+ <XDSVStack gap="space6">
+ <XDSVStack gap="space2">
+ <XDSHeading level={1}>TopNav Menu</XDSHeading>
+ <XDSText type="body" color="secondary">
+ A nav item with a hover-triggered overflow menu. Hover over
+ &quot;Products&quot; or &quot;Science&quot; to see the popover.
+ </XDSText>
+ </XDSVStack>
+
+ {/* Marketing-style nav with overflow menus */}
+ <XDSVStack gap="space3">
+ <XDSHeading level={2}>Marketing Nav</XDSHeading>
+ <div {...stylex.props(styles.navWrapper)}>
+ <XDSTopNav
+ label="Marketing navigation"
+ title={
+ <XDSTopNavTitle
+ title="Marketing"
+ logo={<XDSTopNavTitleIcon icon={<LogoIcon />} size="sm" />}
+ href="#"
+ />
+ }
+ startContent={
+ <>
+ <XDSTopNavMenu label="Products" items={productItems} />
+ <XDSTopNavMenu label="Science" items={scienceItems} />
+ <XDSTopNavItem label="Learn" href="#" />
+ </>
+ }
+ endContent={
+ <>
+ <XDSButton label="Login" variant="ghost" />
+ <XDSButton label="Get started" variant="primary" />
+ </>
+ }
+ />
+ </div>
+ </XDSVStack>
+
+ {/* Simple nav with one overflow menu */}
+ <XDSVStack gap="space3">
+ <XDSHeading level={2}>Simple Nav</XDSHeading>
+ <div {...stylex.props(styles.navWrapper)}>
+ <XDSTopNav
+ label="Simple navigation"
+ title={<XDSTopNavTitle title="App" href="#" />}
+ startContent={
+ <>
+ <XDSTopNavItem label="Home" href="#" isSelected />
+ <XDSTopNavMenu
+ label="More"
+ items={[
+ {
+ title: 'Settings',
+ description: 'Configure your preferences',
+ href: '#settings',
+ },
+ {
+ title: 'Help',
+ description: 'Documentation and support',
+ href: '#help',
+ },
+ ]}
+ />
+ </>
+ }
+ />
+ </div>
+ </XDSVStack>
+ </XDSVStack>
+ </div>
+ );
+}
diff --git a/packages/core/src/TopNav/README.md b/packages/core/src/TopNav/README.md
index 68d1a497b7..d60c54ba51 100644
--- a/packages/core/src/TopNav/README.md
+++ b/packages/core/src/TopNav/README.md
@@ -62,6 +62,14 @@ import {HomeIcon, BellIcon, UserCircleIcon} from '@heroicons/react/24/outline';
/>;
```
+## Components
+
+- **XDSTopNav** — Main navigation container
+- **XDSTopNavTitle** — Title with logo and text
+- **XDSTopNavTitleIcon** — Circular icon container for the title
+- **XDSTopNavItem** — Navigation link item
+- **XDSTopNavMenu** — Navigation item with hover-triggered overflow menu
+
## Props
### XDSTopNav
@@ -100,6 +108,25 @@ import {HomeIcon, BellIcon, UserCircleIcon} from '@heroicons/react/24/outline';
| `icon` | `ReactNode` | — | Optional icon element |
| `children` | `ReactNode` | — | Custom content instead of label |
+### XDSTopNavMenu
+
+| Prop | Type | Default | Description |
+| ----------- | ------------------------- | ------- | ------------------------------------------- |
+| `label` | `string` | — | Visible label for the trigger (required) |
+| `items` | `XDSTopNavMenuItemData[]` | — | Menu items to display in the hover popover |
+| `delay` | `number` | `150` | Delay before showing on hover (ms) |
+| `hideDelay` | `number` | `200` | Delay before hiding after mouse leaves (ms) |
+
+#### XDSTopNavMenuItemData
+
+| Property | Type | Description |
+| ------------- | ------------ | -------------------------------- |
+| `title` | `string` | Display title (required) |
+| `description` | `string` | Optional description below title |
+| `icon` | `ReactNode` | Optional icon on the left |
+| `href` | `string` | URL to navigate to |
+| `onClick` | `() => void` | Callback on click |
+
## Theming
Themes can override `TopNav` styles via `ComponentStyles`:
@@ -124,14 +151,16 @@ const theme: Theme = {
## Files
-| File | Role | Purpose |
-| ------------------------ | ----- | ---------------------------- |
-| `index.ts` | Entry | Exports components and types |
-| `XDSTopNav.tsx` | Core | Main navigation container |
-| `XDSTopNavTitle.tsx` | Core | Title with logo and text |
-| `XDSTopNavTitleIcon.tsx` | Core | Circular icon container |
-| `XDSTopNavItem.tsx` | Core | Navigation link item |
-| `XDSTopNav.test.tsx` | Test | Unit tests |
+| File | Role | Purpose |
+| ------------------------ | ----- | --------------------------------- |
+| `index.ts` | Entry | Exports components and types |
+| `XDSTopNav.tsx` | Core | Main navigation container |
+| `XDSTopNavTitle.tsx` | Core | Title with logo and text |
+| `XDSTopNavTitleIcon.tsx` | Core | Circular icon container |
+| `XDSTopNavItem.tsx` | Core | Navigation link item |
+| `XDSTopNavMenu.tsx` | Core | Nav item with hover overflow menu |
+| `XDSTopNav.test.tsx` | Test | Unit tests for TopNav components |
+| `XDSTopNavMenu.test.tsx` | Test | Unit tests for XDSTopNavMenu |
## Layout Structure
diff --git a/packages/core/src/TopNav/XDSTopNavMenu.test.tsx b/packages/core/src/TopNav/XDSTopNavMenu.test.tsx
new file mode 100644
index 0000000000..ba3886e375
--- /dev/null
+++ b/packages/core/src/TopNav/XDSTopNavMenu.test.tsx
@@ -0,0 +1,57 @@
+/**
+ * @file XDSTopNavMenu.test.tsx
+ * @input Uses vitest, @testing-library/react, XDSTopNavMenu
+ * @output Unit tests for XDSTopNavMenu component
+ * @position Testing; validates XDSTopNavMenu behavior
+ *
+ * SYNC: When XDSTopNavMenu changes, update tests to match new behavior
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {XDSTopNavMenu} from './XDSTopNavMenu';
+
+const mockItems = [
+ {
+ title: 'Analytics',
+ description: 'Track user behavior',
+ href: '/analytics',
+ },
+ {
+ title: 'Messaging',
+ description: 'Real-time communication',
+ href: '/messaging',
+ },
+];
+
+describe('XDSTopNavMenu', () => {
+ it('renders the trigger button with label', () => {
+ render(<XDSTopNavMenu label="Products" items={mockItems} />);
+ expect(screen.getByRole('button', {name: 'Products'})).toBeInTheDocument();
+ });
+
+ it('trigger has aria-haspopup attribute', () => {
+ render(<XDSTopNavMenu label="Products" items={mockItems} />);
+ const trigger = screen.getByRole('button', {name: 'Products'});
+ expect(trigger).toHaveAttribute('aria-haspopup', 'true');
+ });
+
+ it('renders with custom items', () => {
+ const items = [{title: 'Custom Item', description: 'A custom description'}];
+ render(<XDSTopNavMenu label="Menu" items={items} />);
+ expect(screen.getByRole('button', {name: 'Menu'})).toBeInTheDocument();
+ });
+
+ it('renders icon when provided in items', () => {
+ const items = [
+ {
+ title: 'With Icon',
+ description: 'Has an icon',
+ icon: <span data-testid="menu-icon">Icon</span>,
+ },
+ ];
+ render(<XDSTopNavMenu label="Menu" items={items} />);
+ // Icon is in the hover card content, which may not be visible initially
+ expect(screen.getByRole('button', {name: 'Menu'})).toBeInTheDocument();
+ });
+});
diff --git a/packages/core/src/TopNav/XDSTopNavMenu.tsx b/packages/core/src/TopNav/XDSTopNavMenu.tsx
new file mode 100644
index 0000000000..fff938fc9e
--- /dev/null
+++ b/packages/core/src/TopNav/XDSTopNavMenu.tsx
@@ -0,0 +1,278 @@
+/**
+ * @file XDSTopNavMenu.tsx
+ * @input Uses React, StyleX, useXDSHoverCard, XDSTopNavItem tokens
+ * @output Exports XDSTopNavMenu component and related types
+ * @position Navigation item with hover-triggered overflow menu for XDSTopNav
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/TopNav/README.md
+ * - /packages/core/src/TopNav/XDSTopNavMenu.test.tsx
+ * - /packages/core/src/TopNav/index.ts
+ */
+
+import {type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {useXDSHoverCard} from '../Layer/useXDSHoverCard';
+import {
+ colorVars,
+ spacingVars,
+ radiusVars,
+ transitionVars,
+ textSizeVars,
+ fontWeightVars,
+ lineHeightVars,
+} from '../theme/tokens.stylex';
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ trigger: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-2'],
+ paddingBlock: spacingVars['--spacing-2'],
+ paddingInline: spacingVars['--spacing-3'],
+ borderRadius: radiusVars['--radius-element'],
+ fontSize: textSizeVars['--text-base'],
+ lineHeight: lineHeightVars['--leading-base'],
+ fontWeight: fontWeightVars['--font-weight-medium'],
+ color: colorVars['--color-text-secondary'],
+ textDecoration: 'none',
+ cursor: 'pointer',
+ transitionProperty: 'background-color, color',
+ transitionDuration: transitionVars['--transition-fast'],
+ backgroundColor: {
+ default: 'transparent',
+ ':hover': colorVars['--color-hover-overlay'],
+ },
+ outline: {
+ default: null,
+ ':focus-visible': `2px solid ${colorVars['--color-focus-outline']}`,
+ },
+ outlineOffset: {
+ default: '0',
+ ':focus-visible': '2px',
+ },
+ border: 'none',
+ fontFamily: 'inherit',
+ },
+ menuContainer: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: spacingVars['--spacing-2'],
+ minWidth: 280,
+ },
+ menuItem: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-3'],
+ paddingBlock: spacingVars['--spacing-3'],
+ paddingInline: spacingVars['--spacing-3'],
+ borderRadius: radiusVars['--radius-element'],
+ textDecoration: 'none',
+ cursor: 'pointer',
+ transitionProperty: 'background-color',
+ transitionDuration: transitionVars['--transition-fast'],
+ backgroundColor: {
+ default: 'transparent',
+ ':hover': colorVars['--color-hover-overlay'],
+ },
+ border: 'none',
+ outline: {
+ default: null,
+ ':focus-visible': `2px solid ${colorVars['--color-focus-outline']}`,
+ },
+ outlineOffset: {
+ default: '0',
+ ':focus-visible': '2px',
+ },
+ },
+ menuItemIcon: {
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ width: 40,
+ height: 40,
+ borderRadius: radiusVars['--radius-element'],
+ backgroundColor: colorVars['--color-deemphasized'],
+ flexShrink: 0,
+ },
+ menuItemContent: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: spacingVars['--spacing-1'],
+ minWidth: 0,
+ },
+ menuItemTitle: {
+ fontSize: textSizeVars['--text-base'],
+ lineHeight: lineHeightVars['--leading-base'],
+ fontWeight: fontWeightVars['--font-weight-semibold'],
+ color: colorVars['--color-text-primary'],
+ },
+ menuItemDescription: {
+ fontSize: textSizeVars['--text-sm'],
+ lineHeight: lineHeightVars['--leading-snug'],
+ fontWeight: fontWeightVars['--font-weight-normal'],
+ color: colorVars['--color-text-secondary'],
+ },
+});
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * An item in the TopNav overflow menu.
+ */
+export interface XDSTopNavMenuItemData {
+ /**
+ * Display title for the menu item.
+ */
+ title: string;
+
+ /**
+ * Optional description text displayed below the title.
+ */
+ description?: string;
+
+ /**
+ * Optional icon element displayed to the left.
+ */
+ icon?: ReactNode;
+
+ /**
+ * URL to navigate to when clicked.
+ */
+ href?: string;
+
+ /**
+ * Callback when item is clicked.
+ */
+ onClick?: () => void;
+}
+
+export interface XDSTopNavMenuProps {
+ /**
+ * The visible label for the nav item trigger.
+ */
+ label: string;
+
+ /**
+ * Menu items to display in the hover popover.
+ */
+ items: XDSTopNavMenuItemData[];
+
+ /**
+ * Delay before showing the menu on hover (ms).
+ * @default 150
+ */
+ delay?: number;
+
+ /**
+ * Delay before hiding the menu after mouse leaves (ms).
+ * @default 200
+ */
+ hideDelay?: number;
+}
+
+// =============================================================================
+// XDSTopNavMenu
+// =============================================================================
+
+/**
+ * A navigation item that displays a hover-triggered overflow menu.
+ *
+ * Renders as a nav item in XDSTopNav's startContent slot. On hover,
+ * shows a popover with rich menu items containing an icon, title,
+ * and optional description.
+ *
+ * @example
+ * ```tsx
+ * <XDSTopNav
+ * startContent={
+ * <>
+ * <XDSTopNavItem label="Home" href="/" isSelected />
+ * <XDSTopNavMenu
+ * label="Products"
+ * items={[
+ * {
+ * title: 'Analytics',
+ * description: 'Track and analyze user behavior',
+ * icon: <ChartBarIcon />,
+ * href: '/products/analytics',
+ * },
+ * {
+ * title: 'Messaging',
+ * description: 'Real-time communication tools',
+ * icon: <ChatBubbleIcon />,
+ * href: '/products/messaging',
+ * },
+ * ]}
+ * />
+ * </>
+ * }
+ * />
+ * ```
+ */
+export function XDSTopNavMenu({
+ label,
+ items,
+ delay = 150,
+ hideDelay = 200,
+}: XDSTopNavMenuProps) {
+ const hoverCard = useXDSHoverCard({
+ placement: 'below',
+ alignment: 'start',
+ delay,
+ hideDelay,
+ focusTrigger: 'always',
+ });
+
+ return (
+ <>
+ <button
+ ref={hoverCard.ref}
+ type="button"
+ aria-haspopup="true"
+ aria-describedby={hoverCard.describedBy}
+ {...stylex.props(styles.trigger)}>
+ {label}
+ </button>
+ {hoverCard.renderHoverCard(
+ <div
+ role="menu"
+ aria-label={label}
+ {...stylex.props(styles.menuContainer)}>
+ {items.map((item, index) => {
+ const Element = item.href ? 'a' : 'div';
+ return (
+ <Element
+ key={index}
+ role="menuitem"
+ tabIndex={0}
+ href={item.href}
+ onClick={item.onClick}
+ {...stylex.props(styles.menuItem)}>
+ <div {...stylex.props(styles.menuItemIcon)}>{item.icon}</div>
+ <div {...stylex.props(styles.menuItemContent)}>
+ <span {...stylex.props(styles.menuItemTitle)}>
+ {item.title}
+ </span>
+ {item.description && (
+ <span {...stylex.props(styles.menuItemDescription)}>
+ {item.description}
+ </span>
+ )}
+ </div>
+ </Element>
+ );
+ })}
+ </div>,
+ )}
+ </>
+ );
+}
+
+XDSTopNavMenu.displayName = 'XDSTopNavMenu';
diff --git a/packages/core/src/TopNav/index.ts b/packages/core/src/TopNav/index.ts
index 4adcc6e240..345db63bcb 100644
--- a/packages/core/src/TopNav/index.ts
+++ b/packages/core/src/TopNav/index.ts
@@ -21,3 +21,6 @@ export type {
export {XDSTopNavItem} from './XDSTopNavItem';
export type {XDSTopNavItemProps} from './XDSTopNavItem';
+
+export {XDSTopNavMenu} from './XDSTopNavMenu';
+export type {XDSTopNavMenuProps, XDSTopNavMenuItemData} from './XDSTopNavMenu';