Nav

Usage guidelines

• Recursive by construction — a group's list may hold further groups, to any depth, with no second set of parts for the nesting.
• One tab stop — the whole tree is a single tab stop; arrow keys move focus between rows, and typing seeks a row by its label.
• Rows hold actions — Nav.Item is a div with role="button" rather than an anchor, so a menu affordance can sit inside it. Swap in a real link with render.
• Depth is a variable — each list publishes its own --nav-depth, so one indent rule covers every level.
• The guide is cumulative — rail implies indent, and branches implies both. See Why the guide is a ladder.
• Persists nothing itself — the open set goes out through onExpandedChange and comes back as defaultExpanded, so where it is kept is yours.
• Get started — see Quick start to add the package.

Anatomy

<Nav.Root>
  <Nav.List>
    <Nav.Item>
      <Nav.Icon />
      <Nav.Label />
      <Nav.Action />
    </Nav.Item>
    <Nav.Group>
      <Nav.Trigger>
        <Nav.Label />
      </Nav.Trigger>
      <Nav.List />
    </Nav.Group>
  </Nav.List>
</Nav.Root>

A sidebar tree with a rail, one branch open on load, and rows that route:

<Nav.Root guide="rail" defaultExpanded={stored ?? ["docs"]} onExpandedChange={save}>
  <Nav.List>
    <Nav.Item value="overview" active={pathname === "/"} render={<Link href="/" />}>
      <Nav.Label>Overview</Nav.Label>
    </Nav.Item>
    <Nav.Group value="docs">
      <Nav.Trigger>
        <Nav.Label>Documentation</Nav.Label>
      </Nav.Trigger>
      <Nav.List>
        <Nav.Item value="quick-start" render={<Link href="/quick-start" />}>
          <Nav.Label>Quick start</Nav.Label>
        </Nav.Item>
      </Nav.List>
    </Nav.Group>
  </Nav.List>
</Nav.Root>

Examples

Choosing a guide

guide sets what every list draws down its left edge. Set the default on Nav.Root and override it per list.

The attributes are cumulative, so a stylesheet asking for [data-rail] gets branches too. See Why the guide is a ladder.

The package publishes the signal; the geometry is yours. This is what draws the rail and branches trees above — copy it and change the numbers.

/* The lane. `indent` is the first rung and every rung above it emits this too,
   so one rule sizes the lane for all of them. */
[data-nav-list][data-indent] {
  /* Where the elbow aims. Not 50% of the child: a child may itself be a group
     several rows tall. */
  --nav-row: 2rem;

  margin-top: 2px;
  margin-left: 15px;
  padding-left: 7px;
}

/* Both halves are laid out unconditionally and only the borders switch on: a
   box with no edges drawn takes no space and paints nothing. */
[data-nav-list][data-rail] > *::before,
[data-nav-list][data-rail] > *::after {
  content: "";
  position: absolute;
  left: -7px;
  border-color: var(--rail-color);
  border-left-width: 1px;
}

[data-nav-list][data-rail] > * {
  position: relative;
  /* Never `hidden`: these pseudo-elements sit outside the row's own box, so
     clipping them erases the rail. Truncate the label instead. */
  overflow: visible;
}

/* The top half: down to the row's centre, 6px wide so an elbow fits. */
[data-nav-list][data-rail] > *::before {
  top: -2px;
  width: 6px;
  height: calc(var(--nav-row) / 2 + 2px);
}

/* …and the rail carries on to the next row. Never past the last one: a line
   running into empty space reads as a list that got cut off. */
[data-nav-list][data-rail] > *::after {
  top: calc(var(--nav-row) / 2 - 6px);
  bottom: -2px;
}

[data-nav-list][data-rail] > *:last-child::after {
  display: none;
}

/* The elbow — only on groups. One at every leaf turns the rail into a comb and
   buries the thing worth spotting, which is where the tree forks. Group and
   Item carry different identity attributes precisely so CSS can tell them
   apart without the package taking a view. */
[data-nav-list][data-branches] > [data-nav-group]::before {
  border-bottom-width: 1px;
  border-bottom-left-radius: 6px;
}

The four numbers are all load-bearing. 15px hangs the rail under the centre of a size-4 icon at px-2, so it drops out of the parent's icon rather than beside it. 7px is the lane, and it is the list's padding rather than the row's, because an active row paints a background and would cover a line drawn inside its own box. 6px is the elbow's radius, and the curve pulls the vertical away that early, so the continuation has to start 6px above the row's centre or every branch leaves a radius of rail missing. 2px is the row gap, bridged so the line reads as unbroken.

Give rows an explicit height. Text at a fractional line-height makes a padded row land on a fraction of a pixel, and then nothing in the tree lines up. --nav-row has to match whatever height you set.

Animating a group open

height: auto is not interpolable, so a collapse can only animate between lengths. --nav-list-height holds a measured pixel value while a transition runs and is released the moment it finishes, so an open, settled list is auto and grows freely. The demo below is slowed to 500ms; open the outer group, then the inner one, and watch the outer keep growing.

[data-nav-group] > [data-nav-list] {
  height: var(--nav-list-height);
  overflow: hidden;
  opacity: 1;
  /* Not ease-out: the last row is the bottom sliver of the height, and
     ease-out spends its whole tail crawling through exactly that stretch —
     which reads as the row popping in at the end. */
  transition:
    height 200ms cubic-bezier(0.4, 0, 0.2, 1),
    opacity 200ms ease-out;
}

[data-nav-list][data-starting-style],
[data-nav-list][data-ending-style] {
  height: 0;
  opacity: 0;
}

/* The collapsing list squeezes to nothing, and a flex item shrinks below its
   own height when the column runs short — so without this the rows compress
   instead of sliding up behind the clip. */
[data-nav-list] > * {
  flex-shrink: 0;
}

With the variable released, height: var(--nav-list-height) is invalid at computed-value time and height lands back on auto, which is what a settled list wants without inheriting anything from an ancestor.

Persisting the open set

onExpandedChange reports the open set out and defaultExpanded takes it back in, so where it is kept is yours.

// A server component reads it before the first paint …
const stored = readNavState((await cookies()).toString());

// … and the tree reports every change back.
<Nav.Root
  defaultExpanded={stored ?? ["docs"]}
  onExpandedChange={(expanded) => writeNavState(expanded)}
>

Validate what comes back out of storage — Array.isArray(x) && x.every((v) => typeof v === "string") is the whole check for Nav — so a stale or hand-edited value falls back to the default rather than reaching the tree. See Shell for why the value has to arrive as a prop rather than be read at init.

Driving the tree from outside

useNavStore(store, selector) is the outside-the-tree twin of useNav, taking an explicit Nav.createStore() handle. There is no global fallback, which is what stops a tree being driven by accident from somewhere that merely imported it.

Why the guide is a ladder

What a list draws down its left edge is a ladder rather than three independent flags, because each rung implies the one before it. A rail lives in the indent lane, and an elbow needs a rail to turn off.

Expressing them as booleans would mean guarding against combinations that mean nothing — branches without a rail, a rail with no lane to sit in. Making the attributes cumulative instead keeps the ladder readable in CSS without wrapping every selector in :is().

Keyboard

These are the widget's own keys, not global ones: the handler sits on Nav.Root, so nothing fires unless focus is already inside the tree.

A field inside the nav keeps its own arrow keys — an input, a textarea, a select, or anything contenteditable — or the caret could never move.

API reference

Every part accepts className, style, and render (see Styling) and emits a bespoke part attribute (data-<part>) unless noted. Every part also carries data-depth and, when nested inside a group, data-nested.

Nav.Root

The provider and container. Renders data-nav, and owns the keyboard handling for the whole tree.

Nav.List

A level of the tree. Renders data-nav-list. A list inside a group is that group's collapsible panel; a top-level list is not collapsible, because there is no trigger above it.

Nav.Group

A collapsible branch. Renders data-nav-group set to its value, and provides the group context its trigger and list read.

Nav.Trigger

The row that opens a group — its heading and its disclosure in one, because in a sidebar they are the same thing you click. Renders data-nav-trigger set to the group's value. Takes no value: it belongs to the group it is written inside.

Nav.Item

A leaf row. Renders data-nav-item set to its value.

Nav.Label

The row's text. Renders a <span> with data-nav-label — its own element so it can truncate while the row does not. A row must never be overflow: hidden itself, because the rail's pseudo-elements sit outside its box.

Nav.Icon

Decoration. Renders a <span> with data-nav-icon and aria-hidden, so it stays out of the row's accessible name.

Nav.Action

A control inside a row — the affordance that opens a menu, say. Renders data-nav-action as a role="button" with tabIndex="-1": out of the roving order, so arrowing walks rows rather than stopping at every affordance, and it stops every event it handles — anything that escaped would activate the row on its way out of opening the menu.

useNav

Read which groups are open from anywhere inside <Nav.Root>:

const isOpen = useNav((nav) => nav.expanded.has("docs"));