# NavItem

> A navigation row — an icon in the rail that opens its peek, a labelled row in a panel.

- **Level**: molecule · **Status**: stable · **Role**: navigation
- **Import**: `import { NavItem } from "@rrios-forge/ui/molecules/nav-item";`
- **Source**: `packages/ui/src/molecules/nav-item`

Renders <a> when href is provided, otherwise <button>. active sets aria-current=page; collapsed compresses to icon-only with sr-only label. Patterns consulted: Patterns/Navigation · NavigationLayers, Patterns/Visual Priority · QuietSecondaryActions.

## Use it for

- App frame / navigation → **The rail that peeks (ADR-044) — the default and the recommendation.** `PageShell` (defaults: `sidebarMode="rail"`, `sidebarPresentation="inset"`, `mobileNav="tabs"`) + `SidebarSection aria-label` + ONE untitled `NavGroup`: home, search, the rooms, settings — same size, same gap. Wrap every `NavItem` in `PageShell.RailPeek` and compose its panel with `PageShell.PeekHeader` / `PeekFacts` / `PeekLinks`. Search is a button row opening `CommandMenu` (⌘K); settings' peek holds the quick controls; phones get `PageShell.MobileTabBar` (≤ 5). No `TopBar` in an app frame. Opt-ins only when a product needs them: the labelled panel (`sidebarMode="auto"`, ⌘\\ collapse, ADR-040), `island`/`column` (ADR-025), the bubble (`mobileNav="bubble"`)

## Axes

| Axis | Part | Values | Default | Meaning |
|---|---|---|---|---|
| `active` | — | `true` `false` | `false` | The current destination or item: marked as current to assistive tech. |
| `disabled` | — | `true` `false` | `false` | Not available: dimmed, skipped by the keyboard, ignores the pointer. |
| `collapsed` | — | `true` `false` | `false` | Folded to its compact form (an icon rail, a closed group). |

## Stories

- [Playground](/?path=/story/components-molecules-navitem--playground) · frame: `/iframe.html?id=components-molecules-navitem--playground&viewMode=story`
- [Active](/?path=/story/components-molecules-navitem--active) · frame: `/iframe.html?id=components-molecules-navitem--active&viewMode=story`
- [With badge](/?path=/story/components-molecules-navitem--with-badge) · frame: `/iframe.html?id=components-molecules-navitem--with-badge&viewMode=story`
- [Collapsed](/?path=/story/components-molecules-navitem--collapsed) · frame: `/iframe.html?id=components-molecules-navitem--collapsed&viewMode=story`
- [Disabled](/?path=/story/components-molecules-navitem--disabled) · frame: `/iframe.html?id=components-molecules-navitem--disabled&viewMode=story`
- [As button](/?path=/story/components-molecules-navitem--button-branch) · frame: `/iframe.html?id=components-molecules-navitem--button-branch&viewMode=story`
- [With a router link](/?path=/story/components-molecules-navitem--as-child-with-link) · frame: `/iframe.html?id=components-molecules-navitem--as-child-with-link&viewMode=story`
- [Client-side navigation](/?path=/story/components-molecules-navitem--as-child-prevents-navigation) — interaction test · frame: `/iframe.html?id=components-molecules-navitem--as-child-prevents-navigation&viewMode=story`
- [In the rail, with a tooltip](/?path=/story/components-molecules-navitem--collapsed-with-tooltip) · frame: `/iframe.html?id=components-molecules-navitem--collapsed-with-tooltip&viewMode=story`
- [With a trailing action](/?path=/story/components-molecules-navitem--with-trailing-action) · frame: `/iframe.html?id=components-molecules-navitem--with-trailing-action&viewMode=story`
- [Plain link (deprecated)](/?path=/story/components-molecules-navitem--plain-link) · frame: `/iframe.html?id=components-molecules-navitem--plain-link&viewMode=story`

## Decisions that name it

- ADR-005 — Visual operational rules: surfaces, interaction, motion
- ADR-009 — Editorial Frame: PageShell v3 + new `TopBar` molecule
- ADR-010 — PageShell v4: bottom dock + mobile floating bubble
- ADR-011 — PageShell v5: adaptive lateral sidebar + mobile nav bubble
- ADR-014 — PageShell: Apple Mail / macOS Big Sur visual register
- ADR-017 — Actionable components adopt the `asChild` slot pattern for framework-aware routing
- ADR-018 — Motion language as a Pattern Layer contract
- ADR-025 — The sidebar is an island, not a wall (amended: two stagings)
- ADR-037 — Continuity motion: a decelerating curve, a travelling indicator, view transitions and the SegmentedControl

## Always

- Tokens only (R04); variants are semantic axes, never appearance (R02).
- Typography and actions are Poesía atoms, never raw HTML with utilities.
- Vibrant panes need a ground and never nest (ADR-027).