# NavLink

> Navigation anchor primitive for site chrome such as `SiteHeader`, drawers and in-page navs. Renders an underlying `next/link`; on the exact current page it renders a non-focusable `<span aria-current='page'>` instead of a link, and a section link that is an ancestor of the current route gets `aria-current='true'`.

- Status: stable
- Group: navigation
- Page: https://www.digitaltableteur.com/design-system/components/nav-link
- Contract: https://www.digitaltableteur.com/contracts/v1/NavLink.contract.json

## When to use

NavLink is the router-aware navigation link for site chrome: headers, drawers and sidebars. It compares the current pathname against `href` (prefix match by default, exact with `exact`) and reflects the result both as `aria-current` and as the active/inactive class pair. When pathname equals `href` exactly, the item renders as a non-interactive `<span aria-current="page">` instead of a link; an ancestor section link keeps its link and gets `aria-current="true"`. Use it inside a labelled `<nav>`; for inline prose links use Link instead. Styling is deliberately className-driven (Tailwind tokens by default) so each navigation surface owns its look while the active-state contract stays shared.

## When not to use

- Do not use inside body prose; that is `Link`.
- Do not use as a button; primary actions belong on `Button`.
- Do not use NavLink for inline body links; that is Link's job; NavLink's route tracking is navigation-chrome behavior.

## Look-alikes

- BlogNav: Do not use BlogNav as site-wide navigation; use SiteHeader or NavLink instead.
- CategoryFilter: Do not use as primary navigation; `CategoryFilter` is a UI control, not a nav surface; use `NavLink` for routes.
- Link: Do not use NavLink for inline body links; that is Link's job; NavLink's route tracking is navigation-chrome behavior.
- Tabs: Do not use tabs for page navigation; that is NavLink in a nav landmark; tabs switch views inside one page.

## Props

| Prop | Type | Default | Description | Required |
| --- | --- | --- | --- | --- |
| `href` | `string` | none | Route path for next/link. | Yes |
| `children` | `ReactNode` | none | Navigation link label. | Yes |
| `exact` | `boolean` | `false` | Match href exactly for the active state instead of by prefix. | No |
| `className` | `string` | none | Base class names applied in every state. | No |
| `activeClassName` | `string` | `text-foreground` | Class names applied when the route is active. | No |
| `inactiveClassName` | `string` | text-muted-foreground hover:text-foreground | Class names applied when the route is inactive. | No |
| `onClick` | `() => void` | none | Called when the link is activated. Fires only for the navigable anchor; the current-page indicator is a non-interactive span and never calls it. Lets containers (the mobile drawer) close as soon as the visitor taps a destination instead of waiting for the route change to land. | No |

## Variants

No variant dimensions and no props with a fixed set of values.

## Invalid combinations

The contract records no invalid combinations.

## Keyboard

| Key | Behaviour |
| --- | --- |
| Tab | Focuses each link. The exact current-page item is a <span> with no href or tabindex, so it is skipped. |
| Enter | Follows the link. |

## Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

| Level | Rule | How it is checked |
| --- | --- | --- |
| MUST | ARIA: Marks the active item with aria-current so it is announced. The exact current page is a `<span aria-current='page'>`; with the default prefix match, a section link whose href is a parent of the current path (href /work on /work/foo) stays a link with `aria-current='true'`, because it is the current section, not the current page. | Not yet verified: no evidence record. WCAG 4.1.2. |
| MUST | ARIA: Renders a real `<a>` (via next/link) for native browser behaviour, except on the exact current page: there it renders a `<span aria-current='page'>` with no href, so the item leaves the Tab order and screen-reader link lists. | Not yet verified: no evidence record. WCAG 4.1.2. |
| MUST | Required stories produce no axe violations at the configured severity. | Automated by `npm run test:stories:matrix:ci`. WCAG 2.5.8. |
| MUST | The accessibility tree (role, name, state) matches the committed snapshot for every required story. | Automated by `npm run test:stories:matrix:ci`. WCAG 1.3.1, 4.1.2. |
| MUST | The component remains legible and operable under a real browser forced-colors: active pass. | Automated by `npm run test:stories:hc`. |
| MUST | Every documented keyboard interaction works as specified. | Not yet verified: no evidence record. WCAG 2.1.1, 2.1.2. |
| MUST | A human completed an end-to-end accessibility review of this component. | Manual review, last on 2026-11-04. |
| SHOULD | Wrap groups in a labelled <nav aria-label="Primary"> so assistive tech can jump to the landmark. | Not stated in the contract. |
| SHOULD | Use exact on short roots like "/"; prefix matching would otherwise mark Home active on every route. | Not stated in the contract. |
| SHOULD | Keep active styling redundant with aria-current: weight or underline plus color, never color alone. | Not stated in the contract. |
| SHOULD | Override className/activeClassName per surface instead of wrapping; the active-state logic is the shared part. | Not stated in the contract. |
| SHOULD NOT | Do not hand-set aria-current on children; the component derives it from the route. | Not stated in the contract. |

## Install and import

- Install: `npm install @digitaltableteur/react` (version 0.9.1, restricted access on npm).
- Import: `import { NavLink } from "@digitaltableteur/react";`
- Entry point: `@digitaltableteur/react/navigation` exports it too.
- Styles: import `@digitaltableteur/react/style.css` once at the app boundary.
- Also available as the custom element `<dt-nav-link>`; see the custom elements manifest.

## Links

- Machine-readable contract (Design System Contract 1.0): https://www.digitaltableteur.com/contracts/v1/NavLink.contract.json
- Markdown version of this page: https://www.digitaltableteur.com/design-system/components/nav-link.md
- Component index as JSON: https://www.digitaltableteur.com/design-system/components.json
- All components: https://www.digitaltableteur.com/design-system/components
- Source: The implementation lives in a private repository. This page, its Markdown twin and the contract are generated from it at build time and are the public source of truth.