# NavigationMenu Component

A horizontal navigation menu component that renders a top-level menu bar with dropdown submenus, keyboard navigation support, and flexible styling options.

## Import path
```tsx
import NavigationMenu from '@hubspot/cms-component-library/NavigationMenu';
```

## Purpose

The NavigationMenu component provides a horizontal navigation menu for HubSpot CMS projects. It automatically integrates with HubSpot's site menu system, supporting multi-level dropdown menus with keyboard navigation, customizable colors for links and backgrounds, and flexible horizontal alignment options.

## Component Structure

```
NavigationMenu/
├── index.tsx                      # Main component wrapper (Island integration)
├── ContentFields.tsx              # HubSpot field definitions for menu selection
├── islands/
│   ├── NavigationMenuIsland.tsx  # Island component with rendering logic
│   ├── types.ts                  # TypeScript type definitions
│   └── index.module.scss         # CSS module with design tokens
└── stories/
    ├── NavigationMenu.stories.tsx # Storybook examples
    └── NavigationMenuDecorator.tsx # Storybook decorator
```

## Components

### NavigationMenu (Main Component)

**Purpose:** Renders a horizontal navigation menu from HubSpot site menu data with dropdown submenus.

**Props:**
```tsx
{
  menuData: SiteMenu;                    // Menu data from useMenu hook (required)
  justifyMenu?: FlexJustifyContent;      // Horizontal alignment (default: 'flex-start')
  navAriaLabel?: string;                 // ARIA label for navigation (default: 'Navigation')
  linkColor?: string;                    // Top-level link text color
  linkColorHover?: string;               // Top-level link hover text color
  backgroundColor?: string;              // Top-level link background color
  backgroundColorHover?: string;         // Top-level link hover background color
  submenuLinkColor?: string;             // Submenu link text color
  submenuLinkColorHover?: string;        // Submenu link hover text color
  submenuBackgroundColor?: string;       // Submenu link background color
  submenuBackgroundColorHover?: string;  // Submenu link hover background color
  className?: string;                    // Additional CSS classes
  style?: React.CSSProperties;           // Inline styles with CSS variables
}
```

## Consuming the Component with useMenu Hook

The NavigationMenu component requires menu data from HubSpot's `useMenu` hook. This hook fetches the site menu structure based on a menu ID defined in your module fields.

### Basic Module Implementation

```tsx
import { ModuleMeta } from '../types/modules.js';
import NavigationMenu from '@hubspot/cms-component-library/NavigationMenu';
import { useMenu, fieldPath } from '@hubspot/cms-components';

export const Component = () => {
  // Fetch menu data using the useMenu hook
  // fieldPath('menu') references the menu field defined in fields.tsx
  const menuData = useMenu(fieldPath('menu'));

  return (
    <NavigationMenu
      menuData={menuData}
      justifyMenu="flex-start"
      navAriaLabel="Main navigation"
    />
  );
};

export { fields } from './fields.js';

export const meta: ModuleMeta = {
  label: 'Main Navigation Menu',
  content_types: [],
  icon: '',
  categories: ['navigation'],
};
```

### Module Fields Definition

```tsx
import { ModuleFields } from '@hubspot/cms-components/fields';
import NavigationMenu from '@hubspot/cms-component-library/NavigationMenu';

export const fields = (
  <ModuleFields>
    <NavigationMenu.ContentFields />
  </ModuleFields>
);
```

**What this does:**
1. `NavigationMenu.ContentFields` creates a HubSpot MenuField in your module
2. This field allows content editors to select which site menu to display
3. The `useMenu(fieldPath('menu'))` hook fetches the selected menu's data
4. The menu data is passed to the NavigationMenu component via the `menuData` prop

## Usage Examples

### Basic Navigation Menu

```tsx
import NavigationMenu from '@hubspot/cms-component-library/NavigationMenu';
import { useMenu, fieldPath } from '@hubspot/cms-components';

export const Component = () => {
  const menuData = useMenu(fieldPath('menu'));

  return <NavigationMenu menuData={menuData} />;
};
```


## HubSpot CMS Integration

### Field Definitions

The NavigationMenu component provides field definitions for menu selection in HubSpot CMS modules.

#### ContentFields

Configurable props for customizing field labels, names, and defaults:

```tsx
<NavigationMenu.ContentFields
  menuLabel="Menu"
  menuName="menu"
  menuDefault="default"
/>
```

**Fields:**
- `menu`: MenuField for selecting which site menu to display (default: 'default')

## Styling

### CSS Variables

The NavigationMenu component uses CSS variables for theming and customization:

**Base Menu Styles:**
- `--hscl-navigationMenu-gap`: Space between top-level menu items
- `--hscl-navigationMenu-color`: Link text color (default: currentColor)
- `--hscl-navigationMenu-backgroundColor`: Link background color (default: transparent)
- `--hscl-navigationMenu-color-hover`: Link hover text color
- `--hscl-navigationMenu-backgroundColor-hover`: Link hover background color

**Submenu-Specific Styles:**
- `--hscl-navigationMenu-submenu-color`: Submenu link text color
- `--hscl-navigationMenu-submenu-backgroundColor`: Submenu link background color
- `--hscl-navigationMenu-submenu-color-hover`: Submenu link hover text color
- `--hscl-navigationMenu-submenu-backgroundColor-hover`: Submenu link hover background color


## Accessibility

The NavigationMenu component follows accessibility best practices:

- **Semantic HTML**: Renders as a `<nav>` element with an unordered list (`<ul>`)
- **ARIA Labels**: Customizable `aria-label` via the `navAriaLabel` prop
- **ARIA Roles**: List items have `role="menuitem"` for proper screen reader support
- **Keyboard Navigation**: Full keyboard support with arrow keys
  - `ArrowDown`: Opens submenu or moves to next item
  - `ArrowUp`: Closes submenu or moves to previous item
  - `ArrowRight`: Moves to next top-level item or opens nested submenu
  - `ArrowLeft`: Moves to previous top-level item or returns to parent
  - `Enter`/`Space`: Activates link
  - `Escape`: Closes submenu
  - `Home`/`End`: Jump to first/last item
- **Focus Management**: Keyboard focus properly managed across menu levels
- **External Links**: Automatically adds `target="_blank"` and `rel="noopener noreferrer"` for external links

## Best Practices

- **Always use useMenu hook**: The NavigationMenu component requires menu data from the `useMenu` hook—never pass hardcoded menu structures
- **Consistent alignment**: Use the same `justifyMenu` value across navigation instances for visual consistency
- **ARIA labels**: Provide descriptive `navAriaLabel` values (e.g., "Main navigation", "Footer navigation")
- **Color contrast**: Ensure sufficient contrast between link colors and backgrounds (WCAG AA minimum)
- **Hover states**: Always define hover colors for better visual feedback
- **Submenu styling**: Use distinct colors for dropdown menus to differentiate them from top-level items
- **Override CSS variables**: Customize appearance using CSS variables rather than overriding class styles
- **Null checking**: Always check if menuData exists before rendering, as useMenu can return null

## Related Components

- **VerticalMenu**: Vertical navigation menu component for sidebar navigation
- **MenuItem**: Used internally to render individual menu items with support for nested children and keyboard navigation
