Nav

A navigation list of links with icon slots and a sliding active pill, horizontal or vertical, or a quiet plain variant for a table of contents.

Installation

$
npx shadcn@latest add https://ui.mattdowney.com/r/nav.json

Usage

import { Nav, NavList, NavSection, NavLabel, NavItem } from "@/components/ui/nav"
import { resolveActiveHref } from "@/components/ui/nav-active"

Examples

Default

Horizontal, the top nav pattern. Pass href and handle the click yourself, or swap in a router link with render.

Sizes

size steps items along the control scale: sm (h-7, 12px), default (h-8, 13px), lg (h-10, 14px). One prop on Nav sizes every item, label, and count chip, in both orientations.

With Count

Pass a count to add a counter chip, the same one a TabsTrigger carries: solid accent on the active item, a neutral tint on the rest. size on Nav scales it with the items. Cap large counts at "99+" so a growing number cannot widen the item.

In a header

Nav shares the kit's control heights, so a header lines up when every control in the row is set to the same size: sm is 28px, default 32px, lg 40px, matching Button tier for tier.

Small
Default
Large

Vertical

orientation="vertical" groups items into NavSections with a NavLabel heading, the sidebar pattern.

Vertical with Count

A count sits at the trailing edge of a vertical item, not against the label, so a column of numbers reads as a column. That needs a width on the Nav: items size to their own content, and there is no shared trailing edge to push a count to until you give them one.

Mobile

A composition, not a separate component: a Button opens a Drawer containing the vertical Nav.

Vertical, long labels

truncate on NavItem cuts a long label with an ellipsis inside a fixed-width sidebar instead of running past the active pill. Give it a plain-text label.

Vertical, two lines

description adds a quieter second line to a vertical item, for a list beside an editor. Both lines cut short with an ellipsis, a count stays on the first line, and rows without a description sit in the same list.

Plain

A table of contents beside a pill sidebar: quiet text links on a hairline track, the current one marked in accent, nothing that slides or fills. Use it one size below the sidebar. Vertical only. Pass aria-current="location" for links to spots on the same page, and indent a deeper level with className.

API Reference

PropTypeDefaultDescription
orientationNav"horizontal" | "vertical""horizontal"Lays out the list as a row (top nav) or a column (sidebar) and sizes items to match.
variantNav"pill" | "plain""pill"pill slides a filled indicator to the active item. plain is a quiet text list on a hairline track, the active item in accent text with its stretch of the track in accent, for a table of contents beside a pill sidebar. Vertical only: a horizontal Nav keeps the pill.
sizeNav"sm" | "default" | "lg""default"Steps items and labels along the control scale, from sm (h-7, 12px type) up to lg (h-10, 14px type).
iconNavItemReact.ReactNodeNoneLeading icon rendered before the item's label, e.g. <Star />.
countNavItemReact.ReactNodeNoneCounter chip after the label, matching the TabsTrigger chip tier for tier. Inline in a horizontal nav, pushed to the trailing edge in a vertical one. Add an aria-label where a bare number needs context (aria-label="Inbox, 12 unread"). Arrives and leaves like Button's count.
activeNavItembooleanNoneMarks the item as the current page. Sets aria-current="page" and drives the sliding pill.
aria-currentNavItem"page" | "location" | ..."page"What the active item is to the reader, set only while it is active. Pass location for a link to a spot on the same page, as a table of contents does.
renderNavItemReact.ReactElementNoneSwaps the default <a> for another element, e.g. render={<Link href="/dashboard" />} to compose with a router.
truncateNavItembooleanfalseCuts a long label short with an ellipsis instead of running past the row. Pass a plain-text label; the label of a vertical item may shrink either way, so a long one no longer pushes past the pill.
descriptionNavItemReact.ReactNodeNoneA second line under the label of a vertical item: timing, a status, a short preview. Plain text, one type step smaller and quieter. Both lines cut short with an ellipsis, so the label must be plain text too; a count stays on the first line. A horizontal item ignores it.
orientationNav"horizontal" | "vertical" = "horizontal"Lays out the list as a row (top nav) or a column (sidebar) and sizes items to match.
variantNav"pill" | "plain" = "pill"pill slides a filled indicator to the active item. plain is a quiet text list on a hairline track, the active item in accent text with its stretch of the track in accent, for a table of contents beside a pill sidebar. Vertical only: a horizontal Nav keeps the pill.
sizeNav"sm" | "default" | "lg" = "default"Steps items and labels along the control scale, from sm (h-7, 12px type) up to lg (h-10, 14px type).
iconNavItemReact.ReactNodeLeading icon rendered before the item's label, e.g. <Star />.
countNavItemReact.ReactNodeCounter chip after the label, matching the TabsTrigger chip tier for tier. Inline in a horizontal nav, pushed to the trailing edge in a vertical one. Add an aria-label where a bare number needs context (aria-label="Inbox, 12 unread"). Arrives and leaves like Button's count.
activeNavItembooleanMarks the item as the current page. Sets aria-current="page" and drives the sliding pill.
aria-currentNavItem"page" | "location" | ... = "page"What the active item is to the reader, set only while it is active. Pass location for a link to a spot on the same page, as a table of contents does.
renderNavItemReact.ReactElementSwaps the default <a> for another element, e.g. render={<Link href="/dashboard" />} to compose with a router.
truncateNavItemboolean = falseCuts a long label short with an ellipsis instead of running past the row. Pass a plain-text label; the label of a vertical item may shrink either way, so a long one no longer pushes past the pill.
descriptionNavItemReact.ReactNodeA second line under the label of a vertical item: timing, a status, a short preview. Plain text, one type step smaller and quieter. Both lines cut short with an ellipsis, so the label must be plain text too; a count stays on the first line. A horizontal item ignores it.