App Nav

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.

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.

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.

Full Example

A complete navigation sidebar as used in the admin pattern:

API

Events

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.