# Navigation menu

## Overview

_[Design to fill]_

- **When to use**: _[Design to fill]_
- **When not to use**: _[Design to fill]_

## Anatomy

_[Design to fill]_

## Props / API

`NavigationMenu` is a compound component. It is built on Base UI's Navigation Menu primitives.

### `NavigationMenu`

The root container.

| Prop       | Type              | Default | Description                                                 |
| ---------- | ----------------- | ------- | ----------------------------------------------------------- |
| `children` | `React.ReactNode` | -       | The menu content, typically a single `NavigationMenu.List`. |

Extends `React.HTMLAttributes<HTMLElement>`. All standard attributes are forwarded via `...rest`.

### `NavigationMenu.List`

The horizontal list of top-level items.

Extends `React.HTMLAttributes<HTMLUListElement>`. All standard attributes are forwarded via `...rest`.

### `NavigationMenu.Item`

A single top-level entry, wrapping either a `NavigationMenu.Link` or a `NavigationMenu.Trigger` & `NavigationMenu.Content` pair.

| Prop     | Type      | Default | Description                |
| -------- | --------- | ------- | -------------------------- |
| `active` | `boolean` | `false` | Marks the item as current. |

Extends `React.HTMLAttributes<HTMLLIElement>`. All standard attributes are forwarded via `...rest`.

### `NavigationMenu.Link`

A top-level navigation link. Requires either an `href` or a `render` element (mutually exclusive).

| Prop     | Type                 | Default | Description                                                               |
| -------- | -------------------- | ------- | ------------------------------------------------------------------------- |
| `active` | `boolean`            | -       | Marks the link as the current destination.                                |
| `href`   | `string`             | -       | Destination URL. Required unless `render` is supplied.                    |
| `render` | `React.ReactElement` | -       | Custom element to render as the link. Required unless `href` is supplied. |

Extends `React.AnchorHTMLAttributes<HTMLAnchorElement>`. All standard attributes are forwarded via `...rest`.

### `NavigationMenu.Trigger`

The button that opens a dropdown for an item.

Type: `React.ButtonHTMLAttributes<HTMLButtonElement>`. All standard `<button>` attributes are forwarded via `...rest`.

### `NavigationMenu.Content`

The dropdown panel opened by a `NavigationMenu.Trigger`. Renders its children inside a `<ul>`.

Extends `React.HTMLAttributes<HTMLDivElement>`. All standard attributes are forwarded via `...rest`.

### `NavigationMenu.Content.Item`

A link inside a dropdown panel. Renders as a `<li>` wrapping an anchor; shows a `checkmark` icon when `active`.

| Prop           | Type                 | Default | Description                                                   |
| -------------- | -------------------- | ------- | ------------------------------------------------------------- |
| `active`       | `boolean`            | `false` | Marks the item as current; renders a trailing checkmark icon. |
| `closeOnClick` | `boolean`            | `true`  | Whether clicking the item closes the dropdown.                |
| `render`       | `React.ReactElement` | -       | Custom element to render as the link (e.g. a router link).    |

Extends `React.AnchorHTMLAttributes<HTMLAnchorElement>`. All standard attributes are forwarded via `...rest`.

## States

- Default (idle)
- Hover
- Focus-visible
- Open
- Active/current

## Code examples

```tsx
import { NavigationMenu } from "@mylighthouse/prism-react";

export default function NavigationMenuExample(): React.JSX.Element {
  return (
    <NavigationMenu>
      <NavigationMenu.List>
        <NavigationMenu.Item>
          <NavigationMenu.Link active href="/overview">
            Overview
          </NavigationMenu.Link>
        </NavigationMenu.Item>
        <NavigationMenu.Item>
          <NavigationMenu.Trigger>Reports</NavigationMenu.Trigger>
          <NavigationMenu.Content>
            <NavigationMenu.Content.Item href="/reports/daily">
              Daily
            </NavigationMenu.Content.Item>
            <NavigationMenu.Content.Item active href="/reports/weekly">
              Weekly
            </NavigationMenu.Content.Item>
            <NavigationMenu.Content.Item href="/reports/monthly">
              Monthly
            </NavigationMenu.Content.Item>
          </NavigationMenu.Content>
        </NavigationMenu.Item>
        <NavigationMenu.Item>
          <NavigationMenu.Link href="/settings">Settings</NavigationMenu.Link>
        </NavigationMenu.Item>
      </NavigationMenu.List>
    </NavigationMenu>
  );
}
```

## A11y intent

_[Design to fill]_

## Cross-references

_[Design to fill]_