# Subnavigation

> Slug: `subnavigation` · Category: Navigation

## When to use
- Secondary, tab-style navigation that links to distinct pages or routes (each tab is an `<a>`).
- Section-level nav inside a page hierarchy (e.g. "Overview / Speeds / Compare" beneath a product page).

## When NOT to use
- For client-side panel switching that doesn't change the URL — use `Tabs` (which uses buttons + ARIA tabs).
- For top-level/global navigation (header, footer) — use a custom nav with `Link`.
- For breadcrumbs — use a breadcrumb pattern (not exported here).

## Variants & decision tree
Single visual component with three style axes:

- **`size`** — `'lg'` (default), `'sm'`, `'xs'`. Match to surrounding density.
- **`alignment`** — `'left'` (default) or `'centered'`. Use `centered` for marketing pages where the subnav sits beneath a hero.
- **`navStyle`** — `'default'` (underline) or `'high-contrast'` (stronger emphasis on dark/branded backgrounds).

## States
- The tab at `selectedIndex` gets `aria-current="page"`.
- Per-tab force-state flags (`hover`, `focused`, `pressed`) for visual testing only.
- `inverse` swaps to dark-background styling and appends `-inverse` to the `aria-label`.

## Props
| Prop | Type | Default | Description |
|---|---|---|---|
| `tabs` | `SubnavigationTab[]` | — | `{ label, href?, hover?, pressed?, focused? }`. |
| `selectedIndex` | `number` | — | Currently selected tab index. |
| `a11yLabel` | `string` | — | `aria-label` for the `<nav>`. Required for distinct subnavs on the same page. |
| `alignment` | `'left' \| 'centered'` | `'left'` | Horizontal alignment. |
| `size` | `'xs' \| 'sm' \| 'lg'` | `'lg'` | Item density. |
| `navStyle` | `'default' \| 'high-contrast'` | `'default'` | Visual style. |
| `inverse` | `boolean` | inherited | Dark-background styling. |

## Usage examples
```tsx
<Subnavigation
  a11yLabel="Plan sections"
  selectedIndex={pathToIndex(location.pathname)}
  tabs={[
    { label: 'Overview', href: '/plans/overview' },
    { label: 'Speeds', href: '/plans/speeds' },
    { label: 'Compare', href: '/plans/compare' },
  ]}
/>
```

## Composition
Place beneath the page hero or below a `Title`. Pair with a router so `selectedIndex` follows the URL. See `tabs.md` for the panel-switching counterpart.

## Accessibility
- Each tab is a real `<a href>` — works without JS, supports browser context-menu actions.
- Provide `a11yLabel` so screen readers can distinguish multiple `<nav>` regions.
- `aria-current="page"` marks the active tab automatically.

## Do / Don't
- Do use `Subnavigation` when each tab represents a different URL.
- Do route the `selectedIndex` from the current path.
- Don't use it for tab-panel switching inside a single page — use `Tabs`.
- Don't omit `a11yLabel` when more than one nav region exists on a page.
