# Navigation Components

Navigation components move users around: top-level menus, dropdown and context menus, breadcrumb trails, tab panels, pagination controls, and grouped toggle/button controls. Menu and breadcrumb items follow shared schemas (`MenuItemSchema`, `NavItemSchema`, `BreadcrumbItemSchema`). All accept the shared `props` bag plus `visibility` and `responsive` modules.

```yaml
components:
  - type: navigation-menu
    items:
      - { label: Home, href: / }
      - label: Products
        children:
          - { label: Catalog, href: /catalog, description: 'Browse everything' }
  - type: breadcrumb
    items:
      - { label: Home, href: / }
      - { label: Contacts }
```

## `navigation-menu`

A top-level navigation bar supporting nested items and mega-menu layouts.

| Property | Description                         |
| -------- | ----------------------------------- |
| `items`  | Array of nav items (see below).     |
| `props`  | HTML attributes (e.g. `className`). |

Each nav item (`NavItemSchema`):

| Item property | Description                                                            |
| ------------- | ---------------------------------------------------------------------- |
| `label`       | Display text for the item.                                             |
| `href`        | URL or route path (omit for parent items with `children`).             |
| `description` | Text shown below the label in mega-menu style.                         |
| `icon`        | Lucide icon name displayed next to the label.                          |
| `target`      | Anchor target (typically `_blank` for external links).                 |
| `rel`         | Anchor `rel` attribute (commonly `noopener noreferrer` with `_blank`). |
| `children`    | Child nav items forming a sub-menu or mega-menu.                       |

## `dropdown-menu`

A menu that opens from a trigger button, with optional nested sub-menus.

| Property    | Description                      |
| ----------- | -------------------------------- |
| `trigger`   | The element that opens the menu. |
| `menuItems` | Array of menu items (see below). |

Each menu item (`MenuItemSchema`):

| Item property | Description                                          |
| ------------- | ---------------------------------------------------- |
| `label`       | Display text (omit for a separator).                 |
| `icon`        | Lucide icon name next to the label.                  |
| `shortcut`    | Keyboard-shortcut hint on the right (e.g. `Ctrl+C`). |
| `disabled`    | Visible but not clickable.                           |
| `separator`   | Render a divider line instead of a clickable item.   |
| `variant`     | Visual style (e.g. `destructive` for red text).      |
| `children`    | Nested sub-menu items.                               |
| `action`      | The action invoked when the item is clicked.         |

## `context-menu`

A right-click menu using the same `MenuItemSchema` items as `dropdown-menu`, anchored to the pointer position rather than a trigger button.

| Property    | Description                                  |
| ----------- | -------------------------------------------- |
| `menuItems` | Menu items (same shape as `dropdown-menu`).  |
| `children`  | The element the context menu is attached to. |

## `menubar`

A horizontal application menu bar (File / Edit / View style), each top-level item opening a `MenuItemSchema` menu.

| Property | Description                                            |
| -------- | ------------------------------------------------------ |
| `menus`  | Array of top-level menus, each with a label and items. |

## `breadcrumb`

A breadcrumb trail of navigation segments.

| Property | Description                            |
| -------- | -------------------------------------- |
| `items`  | Array of breadcrumb items (see below). |

Each breadcrumb item (`BreadcrumbItemSchema`):

| Item property | Description                                         |
| ------------- | --------------------------------------------------- |
| `label`       | Display text for the segment.                       |
| `href`        | URL or route path (omit for the current-page item). |
| `icon`        | Lucide icon name displayed before the label.        |

## `tabs`

A tabbed container. Each tab's content is a [`tab-panel`](/en/docs/layout-components#tab-panel) child.

| Property             | Description                                                       |
| -------------------- | ----------------------------------------------------------------- |
| `children`           | `tab-panel` components, one per tab.                              |
| `props.orientation`  | Layout direction of the tab triggers: `horizontal` or `vertical`. |
| `props.defaultValue` | The tab open on initial render.                                   |

## `pagination`

Page-navigation controls for paginated lists/tables.

| Property       | Description                                                     |
| -------------- | --------------------------------------------------------------- |
| `totalPages`   | Total number of pages.                                          |
| `currentPage`  | The currently active page.                                      |
| `siblingCount` | How many page numbers to show on each side of the current page. |

## `toggle` / `toggle-group`

Toggle buttons for navigation/filtering. `toggle` is a single toggle; `toggle-group` groups several. (Also documented as form controls — see [Form Controls](/en/docs/form-controls#toggle--toggle-group).)

| Property            | Description                            |
| ------------------- | -------------------------------------- |
| `props.type`        | `single` or `multiple` active toggles. |
| `props.orientation` | `horizontal` or `vertical`.            |
| `options`           | Toggle options (toggle-group).         |

## `button-group`

A row of related buttons. Combine with a `dropdown-menu` to build a split-button pattern (a primary button plus a dropdown of secondary actions); keyboard navigation works across both.

| Property   | Description                                                     |
| ---------- | --------------------------------------------------------------- |
| `children` | The grouped `button` (and optional `dropdown-menu`) components. |
| `props`    | HTML attributes (e.g. `className`).                             |

## Related Pages

- [Pages Overview](/en/docs/pages-overview) — the component model and actions.
- [Layout Components](/en/docs/layout-components) — `tab-panel`, `sidebar`, app-shell layout.
- [Interactive Components](/en/docs/interactive-components) — buttons and links used in menus.
- [Overlay Components](/en/docs/overlay-components) — popovers and dialogs opened from menus.