## Overview

The `nav-ui` pattern provides a complete sidebar navigation tree. Items can be grouped with collapsible headers, separated with dividers, and labeled with section headings. When the nav is collapsed (narrow width), groups show their children in popover flyouts instead of inline.

## Structure

## Groups

Groups are collapsible sections with a header row. They display an icon, label, optional badge, and a caret indicator. Click the header to toggle.

## Items

Standalone items live outside groups. They can have icons, text, badges, and trailing slots (such as keyboard shortcuts).

## Badges

Items and groups both accept a `badge` attribute that renders a small trailing chip. The badge takes any string — numeric counts, "New" / "Beta" callouts, plan tiers, status labels — single visual style, content does the differentiating.

### Counts

Inbox / notifications / pending items. Use literal numbers up to a threshold then "`99+`" or similar to keep the chip width bounded.

### Status callouts

"New" / "Beta" / "Soon" — flag a feature lifecycle stage so users know what's just shipped, what's in preview, and what's coming.

### Plan tiers

Surface paywalled / tier-locked items so users see what their plan unlocks. Pair with a click-handler that opens a billing dialog when a non-eligible plan tries to enter.

### Groups with rollup badges

Group headers carry a badge that summarizes child state — total open count, oldest unread, "needs attention" indicator. The group badge sits on the collapsed header so users see the rollup without expanding.

### Mixed

Real navs combine the above — counts on activity-driven items, status callouts on new features, plan badges on paywalled surfaces, group rollups summarizing child state. The badge slot is one of the cheapest ways to surface "what changed since I last looked" inside a sidebar.

Workspace

Badges hide automatically when `nav-ui[collapsed]` is set — see the Collapsed Mode section. If a badge needs to remain visible in the collapsed rail (e.g., a "9+" attention dot on Inbox), use a custom indicator in the `trailing` slot of the icon-only item instead.

## Labels and Dividers

Use `data-nav-label` for section headings and `data-nav-divider` for visual separation.

Platform

Resources

## Spacer

The `data-nav-spacer` element acts as a flex spacer, pushing subsequent items to the bottom of the sidebar.

## Collapsed Mode

When `collapsed` is set on the nav, labels and badges hide. Only icons remain visible. Clicking a group header opens a popover flyout with its children instead of toggling inline.

Expanded

Collapsed

## Full Example

A complete navigation sidebar as used in the admin pattern:

`⌘K`

Platform

Observe

## API

Element | Attribute | Type | Description
--- | --- | --- | ---
`nav-ui` | `collapsed` | boolean | Show icons only, groups use popover flyouts
`nav-group-ui` | `icon` | string | Phosphor icon name for the group header
`nav-group-ui` | `text` | string | Group label text
`nav-group-ui` | `badge` | string | Badge text on the group header
`nav-group-ui` | `open` | boolean | Expand this group on load
`nav-item-ui` | `icon` | string | Phosphor icon name
`nav-item-ui` | `text` | string | Item label
`nav-item-ui` | `value` | string | Value emitted in nav-select event
`nav-item-ui` | `badge` | string | Badge text
`nav-item-ui` | `selected` | boolean | Marks this item as the current selection

## Events

Event | Target | Detail
--- | --- | ---
`nav-select` | `nav-ui` | `{ item, text, value }`

## Authoring rules

- Always use `nav-ui` + `nav-item-ui` for sidebar and in-page navigation. Never use `menu-ui` in a nav context — `menu-ui` is for popover dropdown menus, not navigation rails.
- Every `nav-item-ui` must have `icon=`. When the sidebar collapses to icon-only mode, items without an icon become invisible. Provide a meaningful Phosphor icon name on every row.
- Use `nav-group-ui` for collapsible sub-navs, never nested `nav-ui`. `nav-group-ui` owns the chevron toggle, open/closed state, and keyboard navigation for the group.
- Use `<hr data-nav-divider />` for visual separators, not bare `<hr>`. The plain `<hr>` renders as a content divider with different spacing; `data-nav-divider` renders as a subtle nav-rail separator.
- The workspace switcher belongs in `<admin-topbar slot="header">`, not inside `nav-ui`. The topbar header is the canonical location for workspace context and brand.
- The user switcher belongs in `<admin-statusbar slot="footer">`. Placing it inside the nav scroll area causes it to scroll out of view on long nav lists.
- Do not put interactive elements (`button-ui`, `switch-ui`) directly inside `nav-ui` — they break the roving tab index and keyboard navigation model. Use `nav-item-ui` with event delegation, or place the control outside the nav rail.