ui/components/navigation-list

Navigation List

Terminal-styled navigation sidebar list with selection, keyboard navigation, and composable item parts.

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { NavigationList } from "@/components/ui/navigation-list";5 6 export default function NavigationListDefault() {7   const [selected, setSelected] = useState("review-1");8 9   return (10     <NavigationList selectedId={selected} onSelect={setSelected} aria-label="Reviews">11       <NavigationList.Item id="review-1">12         <NavigationList.Title>feat: add toast component</NavigationList.Title>13         <NavigationList.Meta>14           <NavigationList.Badge variant="info">NEW</NavigationList.Badge>15           <NavigationList.Subtitle>3 files changed</NavigationList.Subtitle>16         </NavigationList.Meta>17       </NavigationList.Item>18       <NavigationList.Item id="review-2">19         <NavigationList.Title>fix: dialog close on escape</NavigationList.Title>20         <NavigationList.Meta>21           <NavigationList.Badge variant="success">PASS</NavigationList.Badge>22           <NavigationList.Subtitle>1 file changed</NavigationList.Subtitle>23         </NavigationList.Meta>24       </NavigationList.Item>25       <NavigationList.Item id="review-3">26         <NavigationList.Title>refactor: menu keyboard handling</NavigationList.Title>27         <NavigationList.Status className="text-error">!</NavigationList.Status>28         <NavigationList.Meta>29           <NavigationList.Badge variant="error">FAIL</NavigationList.Badge>30           <NavigationList.Subtitle>7 files changed</NavigationList.Subtitle>31         </NavigationList.Meta>32       </NavigationList.Item>33       <NavigationList.Item id="review-4" disabled>34         <NavigationList.Title>chore: update dependencies</NavigationList.Title>35         <NavigationList.Meta>36           <NavigationList.Subtitle>archived</NavigationList.Subtitle>37         </NavigationList.Meta>38       </NavigationList.Item>39     </NavigationList>40   );41 }42

Installation

$pnpm exec dgadd add ui/navigation-list

[Installs to]src/components/ui/navigation-list[Item]ui/navigation-list

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS once packages are available.

Usage

tsx

1 "use client";2 3 import { useState } from "react";4 import { NavigationList } from "@/components/ui/navigation-list";5 6 export default function NavigationListDefault() {7   const [selected, setSelected] = useState("review-1");8 9   return (10     <NavigationList selectedId={selected} onSelect={setSelected} aria-label="Reviews">11       <NavigationList.Item id="review-1">12         <NavigationList.Title>feat: add toast component</NavigationList.Title>13         <NavigationList.Meta>14           <NavigationList.Badge variant="info">NEW</NavigationList.Badge>15           <NavigationList.Subtitle>3 files changed</NavigationList.Subtitle>16         </NavigationList.Meta>17       </NavigationList.Item>18       <NavigationList.Item id="review-2">19         <NavigationList.Title>fix: dialog close on escape</NavigationList.Title>20         <NavigationList.Meta>21           <NavigationList.Badge variant="success">PASS</NavigationList.Badge>22           <NavigationList.Subtitle>1 file changed</NavigationList.Subtitle>23         </NavigationList.Meta>24       </NavigationList.Item>25       <NavigationList.Item id="review-3">26         <NavigationList.Title>refactor: menu keyboard handling</NavigationList.Title>27         <NavigationList.Status className="text-error">!</NavigationList.Status>28         <NavigationList.Meta>29           <NavigationList.Badge variant="error">FAIL</NavigationList.Badge>30           <NavigationList.Subtitle>7 files changed</NavigationList.Subtitle>31         </NavigationList.Meta>32       </NavigationList.Item>33       <NavigationList.Item id="review-4" disabled>34         <NavigationList.Title>chore: update dependencies</NavigationList.Title>35         <NavigationList.Meta>36           <NavigationList.Subtitle>archived</NavigationList.Subtitle>37         </NavigationList.Meta>38       </NavigationList.Item>39     </NavigationList>40   );41 }42

Examples

Density Variants

Preview

tsx

1 "use client";2 3 import { NavigationList } from "@/components/ui/navigation-list";4 5 const densities = [6   { value: "compact", padding: "6px" },7   { value: "default", padding: "12px" },8   { value: "comfortable", padding: "20px" },9 ] as const;10 11 export default function NavigationListDensity() {12   return (13     <div className="flex flex-col gap-6">14       {densities.map(({ value: density, padding }) => (15         <div key={density}>16           <div className="text-xs text-muted-foreground uppercase font-bold mb-2">17             {density} · {padding}18           </div>19           <NavigationList defaultSelectedId="item-0" aria-label={`${density} list`}>20             <NavigationList.Item id="item-0" density={density}>21               <NavigationList.Title>{density} density item 1</NavigationList.Title>22               <NavigationList.Meta>23                 <NavigationList.Subtitle>{density} spacing profile</NavigationList.Subtitle>24               </NavigationList.Meta>25             </NavigationList.Item>26             <NavigationList.Item id="item-1" density={density}>27               <NavigationList.Title>{density} density item 2</NavigationList.Title>28               <NavigationList.Meta>29                 <NavigationList.Subtitle>{density} spacing profile</NavigationList.Subtitle>30               </NavigationList.Meta>31             </NavigationList.Item>32           </NavigationList>33         </div>34       ))}35     </div>36   );37 }38

Controlled Selection

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { NavigationList } from "@/components/ui/navigation-list";5 6 export default function NavigationListInteractive() {7   const [selected, setSelected] = useState<string>("src");8 9   const files = [10     { id: "src", name: "src/index.ts", badge: "M", variant: "warning" as const },11     { id: "test", name: "src/index.test.ts", badge: "A", variant: "success" as const },12     { id: "config", name: "tsconfig.json", badge: "M", variant: "warning" as const },13     { id: "readme", name: "README.md", badge: "D", variant: "error" as const },14   ];15 16   return (17     <NavigationList selectedId={selected} onSelect={setSelected} aria-label="Changed files">18       {files.map((file) => (19         <NavigationList.Item key={file.id} id={file.id}>20           <NavigationList.Title>{file.name}</NavigationList.Title>21           <NavigationList.Meta>22             <NavigationList.Badge variant={file.variant}>{file.badge}</NavigationList.Badge>23           </NavigationList.Meta>24         </NavigationList.Item>25       ))}26     </NavigationList>27   );28 }29

Progress Bars

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { NavigationList } from "@/components/ui/navigation-list";5 6 // The Status slot is muted by default. A semantic tone is passed only where the7 // label carries that meaning — running is a warning, blocked is an error.8 const stages = [9   { id: "build", title: "Build", progress: 100, status: "DONE", tone: "text-success" },10   { id: "test", title: "Lint & Test", progress: 80, status: "RUNNING", tone: "text-warning" },11   { id: "scan", title: "Security Scan", progress: 60, status: "RUNNING", tone: "text-warning" },12   { id: "staging", title: "Deploy Staging", progress: 0, status: "PENDING", tone: undefined },13   { id: "prod", title: "Deploy Prod", progress: 0, status: "BLOCKED", tone: "text-error" },14 ];15 16 export default function NavigationListProgress() {17   const [selected, setSelected] = useState("build");18   return (19     <div className="w-80 border border-border">20       <NavigationList selectedId={selected} onSelect={setSelected} aria-label="Pipeline">21         {stages.map((stage) => (22           <NavigationList.Item key={stage.id} id={stage.id}>23             <NavigationList.Title>{stage.title}</NavigationList.Title>24             <NavigationList.Status className={stage.tone}>{stage.status}</NavigationList.Status>25             <NavigationList.Meta>26               <NavigationList.Progress value={stage.progress} />27             </NavigationList.Meta>28           </NavigationList.Item>29         ))}30       </NavigationList>31     </div>32   );33 }34

Section Groups

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { NavigationList } from "@/components/ui/navigation-list";5 6 export default function NavigationListSections() {7   const [selected, setSelected] = useState("pr-1");8 9   return (10     <NavigationList selectedId={selected} onSelect={setSelected} aria-label="Project items">11       <NavigationList.Group label="Pull Requests" count={3}>12         <NavigationList.Item id="pr-1">13           <NavigationList.Title>Fix auth flow</NavigationList.Title>14           <NavigationList.Status>ready</NavigationList.Status>15         </NavigationList.Item>16         <NavigationList.Item id="pr-2">17           <NavigationList.Title>Update deps</NavigationList.Title>18           <NavigationList.Meta>19             <NavigationList.Badge variant="neutral">draft</NavigationList.Badge>20           </NavigationList.Meta>21         </NavigationList.Item>22         <NavigationList.Item id="pr-3">23           <NavigationList.Title>Add tests</NavigationList.Title>24         </NavigationList.Item>25       </NavigationList.Group>26       <NavigationList.Group label="Issues" count={4}>27         <NavigationList.Item id="issue-1">28           <NavigationList.Title>Memory leak #42</NavigationList.Title>29           <NavigationList.Meta>30             <NavigationList.Badge variant="error">bug</NavigationList.Badge>31           </NavigationList.Meta>32         </NavigationList.Item>33         <NavigationList.Item id="issue-2">34           <NavigationList.Title>Dark mode #38</NavigationList.Title>35         </NavigationList.Item>36         <NavigationList.Item id="issue-3">37           <NavigationList.Title>API docs #35</NavigationList.Title>38         </NavigationList.Item>39         <NavigationList.Item id="issue-4">40           <NavigationList.Title>Perf audit #31</NavigationList.Title>41         </NavigationList.Item>42       </NavigationList.Group>43       <NavigationList.Group label="Discussions" count={2} defaultExpanded={false}>44         <NavigationList.Item id="disc-1">45           <NavigationList.Title>RFC: new API</NavigationList.Title>46         </NavigationList.Item>47         <NavigationList.Item id="disc-2">48           <NavigationList.Title>Roadmap Q3</NavigationList.Title>49         </NavigationList.Item>50       </NavigationList.Group>51     </NavigationList>52   );53 }54

Tree View

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { NavigationList } from "@/components/ui/navigation-list";5 6 export default function NavigationListTree() {7   const [selected, setSelected] = useState("input-tsx");8 9   return (10     <NavigationList selectedId={selected} onSelect={setSelected} aria-label="File tree">11       <NavigationList.Group label="src" variant="tree">12         <NavigationList.Group label="components" variant="tree">13           <NavigationList.Item id="button-tsx">14             <NavigationList.Title>Button.tsx</NavigationList.Title>15           </NavigationList.Item>16           <NavigationList.Item id="input-tsx">17             <NavigationList.Title>Input.tsx</NavigationList.Title>18           </NavigationList.Item>19           <NavigationList.Item id="dialog-tsx">20             <NavigationList.Title>Dialog.tsx</NavigationList.Title>21           </NavigationList.Item>22         </NavigationList.Group>23         <NavigationList.Group label="hooks" variant="tree">24           <NavigationList.Item id="use-float-ts">25             <NavigationList.Title>useFloat.ts</NavigationList.Title>26           </NavigationList.Item>27         </NavigationList.Group>28         <NavigationList.Item id="utils-ts">29           <NavigationList.Title>utils.ts</NavigationList.Title>30         </NavigationList.Item>31       </NavigationList.Group>32       <NavigationList.Group label="tests" variant="tree" defaultExpanded={false}>33         <NavigationList.Item id="button-test">34           <NavigationList.Title>Button.test.tsx</NavigationList.Title>35         </NavigationList.Item>36         <NavigationList.Item id="input-test">37           <NavigationList.Title>Input.test.tsx</NavigationList.Title>38         </NavigationList.Item>39       </NavigationList.Group>40     </NavigationList>41   );42 }43

Indicator Variants

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { NavigationList } from "@/components/ui/navigation-list";5 6 const items = [7   { id: "dashboard", title: "Dashboard" },8   { id: "settings", title: "Settings" },9   { id: "profile", title: "Profile" },10   { id: "help", title: "Help" },11 ];12 13 export default function NavigationListIndicators() {14   const [selected, setSelected] = useState("settings");15 16   return (17     <div className="grid grid-cols-2 gap-4">18       {(["bar", "bar-thick", "arrow", "bracket"] as const).map((indicator) => (19         <div key={indicator} className="border border-border">20           <div className="px-3 py-1 text-2xs uppercase tracking-wider text-muted-foreground border-b border-border">21             {indicator}22           </div>23           <NavigationList24             indicator={indicator}25             selectedId={selected}26             onSelect={setSelected}27             aria-label={`${indicator} indicator`}28           >29             {items.map((item) => (30               <NavigationList.Item key={item.id} id={item.id}>31                 <NavigationList.Title>{item.title}</NavigationList.Title>32               </NavigationList.Item>33             ))}34           </NavigationList>35         </div>36       ))}37     </div>38   );39 }40

API Reference

NavigationList

Name	Type	Default	Description
selectedId	string \| null	—	Controlled selected item id.
defaultSelectedId	string \| null	null	Initial selected id for uncontrolled mode.
highlighted	string \| null	—	Controlled highlighted (focused) item id.
defaultHighlighted	string \| null	null	Initial highlighted id for uncontrolled mode.
onSelect	(id: string) => void	—	Fired when an item is activated by click, Enter, or Space — including the already-selected item.
onEnter	(id: string, event: KeyboardEvent) => void	—	Fired when Enter activates an item. Receives the raw keyboard event for modifier-key handling.
onHighlightChange	(id: string \| null) => void	—	Fired when the highlighted item changes.
onNavigationBoundaryReached	(direction: "previous" \| "next", event: KeyboardEvent, key: string) => void	—	Fired when arrow navigation reaches the first/last item with wrap disabled, enabling cross-list navigation.
focused	boolean	true	When false, removes the active visual treatment from the selected/highlighted item (useful when focus is elsewhere).
wrap	boolean	true	When true, arrow navigation wraps at list boundaries.
typeahead	boolean	true	Enable type-ahead character search to jump to matching items. Disable when every printable key the list's screen advertises belongs to an external hotkey layer.
indicator	"bar" \| "bar-thick" \| "arrow" \| "bracket"	"bar"	Visual indicator style for the active/selected item. bar is a 4px rail at 40% fill, bar-thick an 8px rail at full fill; arrow and bracket mark the title glyph instead.
autoFocus	boolean	false	Auto-focus the list on mount.
aria-label	string	—	Accessible name for the list container.
childrenrequired	ReactNode	—	NavigationList.Item children.

NavigationList.Item

Name	Type	Default	Description
idrequired	string	—	Stable identifier matched against selectedId/highlighted.
density	"compact" \| "default" \| "comfortable"	"default"	Padding scale for the item content.
disabled	boolean	false	Disables activation; item is rendered with aria-disabled.
childrenrequired	ReactNode	—	Item subparts (Title, Status, Meta, Badge, Subtitle).

NavigationList.Title

Name	Type	Default	Description
childrenrequired	ReactNode	—	Primary label. Used as aria-labelledby for the item.

NavigationList.Status

Name	Type	Default	Description
childrenrequired	ReactNode	—	Top-right status marker.
className	string	—	Merged onto the marker. The slot is muted by default; pass a semantic tone (text-warning, text-error, text-success) at call sites where the status carries that meaning.

NavigationList.Meta

Name	Type	Default	Description
childrenrequired	ReactNode	—	Container for inline metadata (badges, dates). Wired to aria-describedby.

NavigationList.Subtitle

Name	Type	Default	Description
childrenrequired	ReactNode	—	Secondary metadata text. Wired to aria-describedby.

NavigationList.Badge

Name	Type	Default	Description
variant	"success" \| "warning" \| "error" \| "info" \| "neutral"	"neutral"	Semantic color token. Picks foreground, background, border, and dot color together for the Badge. See Badge for full prop reference.
size	"sm" \| "md" \| "lg"	"sm"	Padding and font-size / Badge size token.
children	ReactNode	—	Badge label.

NavigationList.Group

Name	Type	Default	Description
labelrequired	string	—	Group header text.
expanded	boolean	—	Controlled expanded state.
defaultExpanded	boolean	true	Initial expanded state for uncontrolled mode.
onExpandedChange	(expanded: boolean) => void	—	Fired when expanded state changes.
count	number	—	Optional count shown next to the label in section variant.
variant	"tree" \| "section"	"section"	Visual treatment. "section" shows uppercase headers with counts, "tree" shows indented hierarchy with ASCII connectors.
headerId	string	—	Stable header identity. Defaults to a per-instance generated value.
expandLabel	string	"expand"	Accessible action word appended to the header name while collapsed. Override it to localize the disclosure verb.
collapseLabel	string	"collapse"	Accessible action word appended to the header name while expanded. Override it to localize the disclosure verb.
childrenrequired	ReactNode	—	NavigationList.Item or nested NavigationList.Group children.

NavigationList.Progress

Name	Type	Default	Description
valuerequired	number	—	Progress percentage (0-100). Values are clamped to that range; non-finite values become zero.
variant	"block" \| "bar"	"block"	Bar style. "block" uses █░ characters, "bar" uses [==-] characters.
width	number	10	Number of characters for the progress bar. Values are rounded down and capped at 200; negative and non-finite values become zero.
color	"auto" \| "success" \| "warning" \| "error" \| "muted"	"auto"	Color token. Auto selects color based on value thresholds.
showLabel	boolean	true	Shows percentage text after the bar.

Data attributes

Attribute	Applies to	Values	Description
data-highlighted	NavigationList.Item	present when highlighted	Marks the active descendant for keyboard and pointer styling.
data-selected	NavigationList.Item	present when selected	Marks the currently selected item.
data-value	NavigationList.Item	item id	Stable item id used by keyboard navigation.
data-indicator	NavigationList.Item indicator slot (non-tree items)	"bar" \| "bar-thick" \| "arrow" \| "bracket"	Active indicator visual treatment. Emitted on the leading indicator cell inside the item, not on the option root.
data-state	NavigationList.Group header	"open" \| "closed"	Group disclosure state changed by pointer or keyboard activation.

Accessibility

Keyboard Navigation

Arrow keys and their vim aliases j/k navigate between items with wrapping. Enter activates the highlighted item. Home and End jump to the first and last items.

Key	Action
ArrowUp / k	Moves highlight to the previous enabled item.
ArrowDown / j	Moves highlight to the next enabled item.
Home / End	Moves highlight to the first or last enabled item.
Enter	Activates the highlighted item via onEnter or onSelect.
ArrowRight	Expands the highlighted group header when it is collapsed.
ArrowLeft	Collapses the highlighted group header when it is expanded.
Enter / Space	Toggles the highlighted group header.
Boundary ArrowUp / ArrowDown / k / j	Calls onNavigationBoundaryReached with the pressed key when wrap is false and focus attempts to leave the list.

External @diffgazer/keys navigation

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { NavigationList } from "@/components/ui/navigation-list";5 6 export default function NavigationListInteractive() {7   const [selected, setSelected] = useState<string>("src");8 9   const files = [10     { id: "src", name: "src/index.ts", badge: "M", variant: "warning" as const },11     { id: "test", name: "src/index.test.ts", badge: "A", variant: "success" as const },12     { id: "config", name: "tsconfig.json", badge: "M", variant: "warning" as const },13     { id: "readme", name: "README.md", badge: "D", variant: "error" as const },14   ];15 16   return (17     <NavigationList selectedId={selected} onSelect={setSelected} aria-label="Changed files">18       {files.map((file) => (19         <NavigationList.Item key={file.id} id={file.id}>20           <NavigationList.Title>{file.name}</NavigationList.Title>21           <NavigationList.Meta>22             <NavigationList.Badge variant={file.variant}>{file.badge}</NavigationList.Badge>23           </NavigationList.Meta>24         </NavigationList.Item>25       ))}26     </NavigationList>27   );28 }29

Notes

Current-location mark

The library spells "you are here" one way: a 2px left rail in --primary (registry/lib/marker-rail.ts). Full-bleed inversion is reserved for the TRANSIENT keyboard highlight; a row that is both the current location and the highlight keeps the inversion and flips its rail to --primary-foreground so the mark survives. The rail is reserved transparently in the resting state and pulled back by its own width, so a row's label never shifts horizontally when it becomes current — that anti-shift geometry is the contract, and it is why the rail costs 0px of label width at 375/390 where a full-bleed fill reads as a solid slab. NavigationList therefore draws a rail on the selected row instead of relying on the full-bleed fill alone, and the inner indicator no longer halves its opacity in `bar` mode.

Composition Contract

Use NavigationList.Item and its static parts as explicit children in the NavigationList JSX tree. Custom item UI belongs inside NavigationList.Item. Components that create items internally from an opaque wrapper are not part of the current public contract.

Density

density prop controls item padding — compact (6px), default (12px), or comfortable (20px).

Rich Items

NavigationList.Item supports compound parts: NavigationList.Title, NavigationList.Meta, NavigationList.Badge, NavigationList.Subtitle, and NavigationList.Status.

Built-in Keyboard API

NavigationList includes arrow-key navigation with the vim aliases j/k and exposes highlighted, onHighlightChange, onEnter, onNavigationBoundaryReached, autoFocus, focused, and onKeyDown for controlled highlight state or extra app-level shortcuts.

Group Expand/Collapse

Group headers participate in list navigation. ArrowRight expands a collapsed group, ArrowLeft collapses an expanded group, and Enter or Space toggles the highlighted group.

Source

Install via CLI: pnpm exec dgadd add ui/navigation-list. Keyboard hooks are included as standalone copies. For the full experience, use --integration keys.

Highlighted source loads after this disclosure opens. Browse the source repository.

Navigation List

Installation

Usage

Examples

Density Variants

Controlled Selection

Progress Bars

Section Groups

Tree View

Indicator Variants

API Reference

NavigationList

NavigationList.Item

NavigationList.Title

NavigationList.Status

NavigationList.Meta

NavigationList.Subtitle

NavigationList.Badge

NavigationList.Group

NavigationList.Progress

Data attributes

Accessibility

Keyboard Navigation

External @diffgazer/keys navigation

Notes

Current-location mark

Composition Contract

Density

Rich Items

Built-in Keyboard API

Group Expand/Collapse

Source

View component source (43 files)