ui/components/sidebar

Sidebar

Full-height navigation sidebar with tri-state visibility (open/rail/hidden), five active-marker variants, collapsible sections, optional intent tones, mobile sheet, and a configurable global hotkey. Composable parts plus two context providers. The mobile sheet has its own open state that always starts closed and never writes the desktop tri-state.

tsx

1 import {2   Sidebar,3   SidebarContent,4   SidebarFooter,5   SidebarHeader,6   SidebarItem,7   SidebarItemBadge,8   SidebarItemLabel,9   SidebarSection,10   SidebarSectionTitle,11 } from "@/components/ui/sidebar";12 13 export default function SidebarDefault() {14   return (15     <Sidebar embedded className="h-full">16       <SidebarHeader>17         <span className="text-sm font-mono font-bold">Project Explorer</span>18       </SidebarHeader>19       <SidebarContent>20         <SidebarSection>21           <SidebarSectionTitle>Components</SidebarSectionTitle>22           <SidebarItem active href="#button">23             Button24           </SidebarItem>25           <SidebarItem href="#dialog">Dialog</SidebarItem>26           <SidebarItem href="#sidebar">27             <SidebarItemLabel>Sidebar</SidebarItemLabel>28             <SidebarItemBadge>29               <span className="text-xs text-muted-foreground">new</span>30             </SidebarItemBadge>31           </SidebarItem>32           <SidebarItem disabled>Tooltip</SidebarItem>33         </SidebarSection>34         <SidebarSection>35           <SidebarSectionTitle>Hooks</SidebarSectionTitle>36           <SidebarItem href="#use-theme">useTheme</SidebarItem>37           <SidebarItem href="#use-media-query">useMediaQuery</SidebarItem>38         </SidebarSection>39       </SidebarContent>40       <SidebarFooter>41         <span className="text-xs text-muted-foreground font-mono">v1.0.0</span>42       </SidebarFooter>43     </Sidebar>44   );45 }46

Installation

$pnpm exec dgadd add ui/sidebar

[Installs to]src/components/ui/sidebar[Item]ui/sidebar

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 import {2   Sidebar,3   SidebarContent,4   SidebarFooter,5   SidebarHeader,6   SidebarItem,7   SidebarItemBadge,8   SidebarItemLabel,9   SidebarSection,10   SidebarSectionTitle,11 } from "@/components/ui/sidebar";12 13 export default function SidebarDefault() {14   return (15     <Sidebar embedded className="h-full">16       <SidebarHeader>17         <span className="text-sm font-mono font-bold">Project Explorer</span>18       </SidebarHeader>19       <SidebarContent>20         <SidebarSection>21           <SidebarSectionTitle>Components</SidebarSectionTitle>22           <SidebarItem active href="#button">23             Button24           </SidebarItem>25           <SidebarItem href="#dialog">Dialog</SidebarItem>26           <SidebarItem href="#sidebar">27             <SidebarItemLabel>Sidebar</SidebarItemLabel>28             <SidebarItemBadge>29               <span className="text-xs text-muted-foreground">new</span>30             </SidebarItemBadge>31           </SidebarItem>32           <SidebarItem disabled>Tooltip</SidebarItem>33         </SidebarSection>34         <SidebarSection>35           <SidebarSectionTitle>Hooks</SidebarSectionTitle>36           <SidebarItem href="#use-theme">useTheme</SidebarItem>37           <SidebarItem href="#use-media-query">useMediaQuery</SidebarItem>38         </SidebarSection>39       </SidebarContent>40       <SidebarFooter>41         <span className="text-xs text-muted-foreground font-mono">v1.0.0</span>42       </SidebarFooter>43     </Sidebar>44   );45 }46

Mobile

Below the breakpoint the sidebar renders as a Dialog sheet that owns its own open state. That state always starts closed — on a fresh mobile mount and on every breakpoint crossing — and opens only from SidebarTrigger, the Cmd/Ctrl+B hotkey, or useSidebar().onMobileOpenChange. No mobile transition writes state or fires onStateChange, so state/defaultState describe the desktop presentation only: a controlled parent pinning "rail" still gets a working sheet, a desktop → mobile → desktop round trip comes back to exactly the state it left, and persistence layers can mirror onStateChange unconditionally without a phone visit overwriting the stored desktop preference. Sidebars rendered with embedded keep their inline navigation.

Variants

Five active-marker variants — caret, inverted, bar, terminal, and tree — share one rule: structure is permanent, markers appear on the active row. caret and terminal reserve a chevron marker slot that stays invisible at rest, previews dim on hover, and lights to foreground on the active item — terminal adds the TUI rail, a continuous 1px hairline down the rows with no background fill. tree renders bold section headers with stroke-chevron folds and draws its connectors — trunk, tick, corner — as a single CSS hairline; the active item's tick gains a soft background fill. Switch between them below to compare.

tsx

1 "use client";2 3 import { useState } from "react";4 import {5   Sidebar,6   SidebarContent,7   SidebarHeader,8   SidebarItem,9   SidebarItemBadge,10   SidebarItemLabel,11   SidebarSection,12   SidebarSectionTitle,13   type SidebarVariant,14 } from "@/components/ui/sidebar";15 import { createToggleGroup } from "@/components/ui/toggle-group";16 17 const VARIANTS = [18   "caret",19   "inverted",20   "bar",21   "terminal",22   "tree",23 ] as const satisfies readonly SidebarVariant[];24 25 const SidebarVariantGroup = createToggleGroup(VARIANTS);26 27 export default function SidebarVariants() {28   const [variant, setVariant] = useState<SidebarVariant>("caret");29 30   return (31     // w-64 matches the sidebar so the demo stays rail-shaped inside layout32     // frames. The h-11 label row keeps its hairline collinear with the33     // docs-frame topbar rendered beside this example.34     <div className="flex h-full w-64 flex-col">35       <div className="flex h-11 items-center border-b border-border px-3">36         <span className="font-mono text-2xs uppercase tracking-widest text-muted-foreground">37           Variant38         </span>39       </div>40       <div className="border-b border-border px-2 py-2">41         <SidebarVariantGroup42           value={variant}43           onChange={(v) => v && setVariant(v)}44           label="Sidebar variant"45           variant="bracket"46           wrap47         >48           {VARIANTS.map((value) => (49             <SidebarVariantGroup.Item key={value} value={value} className="min-h-7 px-1">50               {value}51             </SidebarVariantGroup.Item>52           ))}53         </SidebarVariantGroup>54       </div>55 56       <Sidebar embedded variant={variant} className="flex-1">57         <SidebarHeader>58           <span className="text-sm font-mono font-bold">Docs</span>59         </SidebarHeader>60         <SidebarContent>61           <SidebarSection>62             <SidebarSectionTitle>Getting Started</SidebarSectionTitle>63             <SidebarItem>Install</SidebarItem>64             <SidebarItem>Quickstart</SidebarItem>65             <SidebarItem>Theming</SidebarItem>66           </SidebarSection>67           <SidebarSection>68             <SidebarSectionTitle>Components</SidebarSectionTitle>69             <SidebarItem active>Sidebar</SidebarItem>70             <SidebarItem>Dialog</SidebarItem>71             <SidebarItem>72               <SidebarItemLabel>Stepper</SidebarItemLabel>73               <SidebarItemBadge>74                 <span className="text-xs text-muted-foreground">new</span>75               </SidebarItemBadge>76             </SidebarItem>77           </SidebarSection>78         </SidebarContent>79       </Sidebar>80     </div>81   );82 }83

Examples

Variant — terminal

tsx

1 import {2   Sidebar,3   SidebarContent,4   SidebarHeader,5   SidebarItem,6   SidebarItemBadge,7   SidebarItemLabel,8   SidebarSection,9   SidebarSectionTitle,10 } from "@/components/ui/sidebar";11 12 export default function SidebarVariantTerminal() {13   return (14     <Sidebar embedded variant="terminal" className="h-full">15       <SidebarHeader>16         <span className="text-xs font-mono text-muted-foreground">~/ui/docs</span>17       </SidebarHeader>18       <SidebarContent>19         <SidebarSection>20           <SidebarSectionTitle>getting-started</SidebarSectionTitle>21           <SidebarItem>install</SidebarItem>22           <SidebarItem>quickstart</SidebarItem>23           <SidebarItem>theming</SidebarItem>24         </SidebarSection>25         <SidebarSection>26           <SidebarSectionTitle>primitives</SidebarSectionTitle>27           <SidebarItem>dialog</SidebarItem>28           <SidebarItem active>toggle-group</SidebarItem>29           <SidebarItem>30             <SidebarItemLabel>stepper</SidebarItemLabel>31             <SidebarItemBadge>32               <span className="text-xs text-muted-foreground">new</span>33             </SidebarItemBadge>34           </SidebarItem>35           <SidebarItem disabled>sidebar</SidebarItem>36         </SidebarSection>37         <SidebarSection>38           <SidebarSectionTitle>cli</SidebarSectionTitle>39           <SidebarItem>add</SidebarItem>40           <SidebarItem>remove</SidebarItem>41           <SidebarItem>diff</SidebarItem>42         </SidebarSection>43       </SidebarContent>44     </Sidebar>45   );46 }47

Variant — tree

tsx

1 import {2   Sidebar,3   SidebarContent,4   SidebarHeader,5   SidebarItem,6   SidebarSection,7   SidebarSectionContent,8   SidebarSectionTitle,9 } from "@/components/ui/sidebar";10 11 export default function SidebarVariantTree() {12   return (13     <Sidebar embedded variant="tree" className="h-full">14       <SidebarHeader>15         <span className="text-xs font-mono text-muted-foreground">[ 01 / FS_TREE ]</span>16       </SidebarHeader>17       <SidebarContent>18         <SidebarSection collapsible defaultOpen>19           <SidebarSectionTitle>diffgazer</SidebarSectionTitle>20           <SidebarSectionContent>21             <SidebarItem>Overview</SidebarItem>22             <SidebarItem>CLI Setup</SidebarItem>23           </SidebarSectionContent>24         </SidebarSection>25         <SidebarSection collapsible defaultOpen>26           <SidebarSectionTitle>@diffgazer/ui</SidebarSectionTitle>27           <SidebarSectionContent>28             <SidebarItem active>Getting Started</SidebarItem>29             <SidebarItem>Components (47)</SidebarItem>30             <SidebarItem>Hooks (11)</SidebarItem>31             <SidebarItem>Theme Config</SidebarItem>32           </SidebarSectionContent>33         </SidebarSection>34         <SidebarSection collapsible defaultOpen>35           <SidebarSectionTitle>@diffgazer/keys</SidebarSectionTitle>36           <SidebarSectionContent>37             <SidebarItem>Core Concepts</SidebarItem>38             <SidebarItem>Focus Management</SidebarItem>39             <SidebarItem>Shortcuts</SidebarItem>40           </SidebarSectionContent>41         </SidebarSection>42       </SidebarContent>43     </Sidebar>44   );45 }46

Collapsible sections

tsx

1 import {2   Sidebar,3   SidebarContent,4   SidebarFooter,5   SidebarHeader,6   SidebarItem,7   SidebarItemBadge,8   SidebarItemLabel,9   SidebarSection,10   SidebarSectionContent,11   SidebarSectionTitle,12 } from "@/components/ui/sidebar";13 14 // `bar` variant — items use a soft fill plus a 2px left edge on active rather15 // than the chevron marker prefix; the section title's own chevron is the16 // single disclosure cue per group, avoiding double-decoration. Items wrapped17 // in `<SidebarSectionContent>` are the only ones that honor the section's18 // open state — items rendered outside that wrapper stay visible regardless.19 export default function SidebarCollapsible() {20   return (21     <Sidebar embedded variant="bar" className="h-full">22       <SidebarHeader>23         <span className="text-sm font-mono font-bold">File Browser</span>24       </SidebarHeader>25       <SidebarContent>26         <SidebarSection collapsible defaultOpen>27           <SidebarSectionTitle>src/</SidebarSectionTitle>28           <SidebarSectionContent>29             <SidebarItem active href="#src-index">30               index.ts31             </SidebarItem>32             <SidebarItem href="#src-utils">utils.ts</SidebarItem>33             <SidebarItem href="#src-config">config.ts</SidebarItem>34           </SidebarSectionContent>35         </SidebarSection>36         <SidebarSection collapsible defaultOpen={false}>37           <SidebarSectionTitle>tests/</SidebarSectionTitle>38           <SidebarSectionContent>39             <SidebarItem href="#tests-index">index.test.ts</SidebarItem>40             <SidebarItem href="#tests-utils">utils.test.ts</SidebarItem>41           </SidebarSectionContent>42         </SidebarSection>43         <SidebarSection collapsible defaultOpen>44           <SidebarSectionTitle>docs/</SidebarSectionTitle>45           <SidebarSectionContent>46             <SidebarItem href="#docs-readme">47               <SidebarItemLabel>README.md</SidebarItemLabel>48               <SidebarItemBadge>49                 <span className="text-xs text-muted-foreground">draft</span>50               </SidebarItemBadge>51             </SidebarItem>52             <SidebarItem href="#docs-changelog">CHANGELOG.md</SidebarItem>53           </SidebarSectionContent>54         </SidebarSection>55       </SidebarContent>56       <SidebarFooter>57         <span className="text-xs text-muted-foreground font-mono">3 sections</span>58       </SidebarFooter>59     </Sidebar>60   );61 }62

Rail mode

tsx

1 "use client";2 3 import { Kbd } from "@/components/ui/kbd";4 import {5   Sidebar,6   SidebarContent,7   SidebarHeader,8   SidebarItem,9   SidebarItemLabel,10   SidebarProvider,11   SidebarSection,12   SidebarSectionTitle,13   SidebarTrigger,14 } from "@/components/ui/sidebar";15 16 // Stand-in for the app content the rail sits next to — the tri-state (open,17 // rail, hidden) is only judgeable against a populated pane.18 const CONTENT_ROWS = [19   { name: "registry/ui/sidebar/sidebar.tsx", meta: "M  +42 −8" },20   { name: "registry/ui/sidebar/sidebar-item.tsx", meta: "M  +12 −3" },21   { name: "registry/ui/sidebar/sidebar.css", meta: "A  +64 −0" },22   { name: "docs/content/components/sidebar.mdx", meta: "M  +9 −9" },23 ];24 25 // In rail mode (48px) each item collapses to an icon-only row: the label and26 // section titles hide via the nav's `data-state="rail"` group while the glyph27 // tile stays visible. SidebarItem preserves the accessible name automatically28 // by rendering an sr-only copy of the label while collapsed; `title` only adds29 // the native hover tooltip.30 export default function SidebarRail() {31   return (32     <SidebarProvider defaultState="rail">33       <div className="flex items-stretch h-80 bg-background">34         <Sidebar embedded variant="bar">35           <SidebarHeader>36             <span className="text-xs font-mono font-bold">DG</span>37           </SidebarHeader>38           <SidebarContent>39             <SidebarSection>40               <SidebarSectionTitle>getting-started</SidebarSectionTitle>41               <RailItem glyph="↓" label="install" />42               <RailItem glyph="»" label="quickstart" active />43               <RailItem glyph="◐" label="theming" />44             </SidebarSection>45             <SidebarSection>46               <SidebarSectionTitle>cli</SidebarSectionTitle>47               <RailItem glyph="+" label="add" />48               <RailItem glyph="−" label="remove" />49               <RailItem glyph="±" label="diff" />50             </SidebarSection>51           </SidebarContent>52         </Sidebar>53         <div className="flex min-w-0 flex-1 flex-col gap-3 border-l border-border p-4 text-xs text-muted-foreground font-mono">54           <div className="flex items-center gap-2">55             <SidebarTrigger className="border border-border px-2 py-1" />56             <span className="truncate">~/diffgazer/libs/ui</span>57           </div>58           <ul className="flex flex-col gap-1">59             {CONTENT_ROWS.map((row) => (60               <li key={row.name} className="flex items-center justify-between gap-4">61                 <span className="truncate text-foreground/80">{row.name}</span>62                 <span className="shrink-0">{row.meta}</span>63               </li>64             ))}65           </ul>66           <p>67             Toggle the rail with the trigger or <Kbd size="sm">Cmd/Ctrl</Kbd>68             <Kbd size="sm">B</Kbd>; <Kbd size="sm">Shift</Kbd>69             <Kbd size="sm">Cmd/Ctrl</Kbd>70             <Kbd size="sm">B</Kbd> toggles the hidden state.71           </p>72         </div>73       </div>74     </SidebarProvider>75   );76 }77 78 // Glyph tile icon stand-in — swap for Lucide / inline SVG in real consumers.79 function RailItem({ glyph, label, active }: { glyph: string; label: string; active?: boolean }) {80   return (81     <SidebarItem active={active} href={`#${label}`} title={label}>82       <span83         aria-hidden="true"84         className="flex size-6 shrink-0 items-center justify-center rounded-sm border border-border"85       >86         {glyph}87       </span>88       <SidebarItemLabel>{label}</SidebarItemLabel>89     </SidebarItem>90   );91 }92

Mobile sheet

tsx

1 "use client";2 3 import type { ReactNode } from "react";4 import {5   Sidebar,6   SidebarContent,7   SidebarHeader,8   SidebarItem,9   SidebarProvider,10   SidebarSection,11   SidebarSectionTitle,12   SidebarTrigger,13 } from "@/components/ui/sidebar";14 15 function NavBody() {16   return (17     <>18       <SidebarHeader>19         <span className="text-xs font-mono font-bold">~/ui/docs</span>20       </SidebarHeader>21       <SidebarContent>22         <SidebarSection>23           <SidebarSectionTitle>primitives</SidebarSectionTitle>24           <SidebarItem href="#dialog">dialog</SidebarItem>25           <SidebarItem href="#toggle-group">toggle-group</SidebarItem>26           <SidebarItem active href="#stepper">27             stepper28           </SidebarItem>29           <SidebarItem href="#sidebar">sidebar</SidebarItem>30         </SidebarSection>31         <SidebarSection>32           <SidebarSectionTitle>cli</SidebarSectionTitle>33           <SidebarItem href="#add">add</SidebarItem>34           <SidebarItem href="#remove">remove</SidebarItem>35           <SidebarItem href="#diff">diff</SidebarItem>36         </SidebarSection>37       </SidebarContent>38     </>39   );40 }41 42 function Pane({ label, children }: { label: string; children: ReactNode }) {43   return (44     <div className="flex flex-col gap-2">45       <span className="font-mono text-2xs uppercase tracking-widest text-muted-foreground">46         {label}47       </span>48       {children}49     </div>50   );51 }52 53 /**54  * Renders the sidebar in its mobile sheet mode. `breakpoint={9999}` forces55  * `isMobile=true` so the sheet branch renders regardless of viewport width —56  * useful for previewing the mobile experience on a docs page. In real apps57  * leave `breakpoint` at the default (1024) and let the viewport drive it.58  * `shortcutKey={null}` releases the global Cmd/Ctrl+B hotkey so the sheet59  * does not pop open when several sidebar demos share one docs page.60  *61  * The left pane renders the same nav with `embedded` so the sheet body stays62  * visible at rest: the sheet is a Dialog and only exists while open, which a63  * static page cannot show without trapping focus on load.64  *65  * Below the breakpoint the sheet has its own open state that starts closed, and66  * opening or closing it never writes the provider's tri-state.67  */68 export default function SidebarMobileSheet() {69   return (70     <div className="flex flex-wrap items-start gap-6 p-4 bg-background">71       <Pane label="sheet body (86vw, max 320px)">72         <div className="h-80 w-[280px] overflow-hidden border border-border">73           <SidebarProvider breakpoint={9999} shortcutKey={null}>74             <Sidebar embedded variant="caret" aria-label="Sheet navigation" className="w-full">75               <NavBody />76             </Sidebar>77           </SidebarProvider>78         </div>79       </Pane>80 81       <Pane label="closed — tap the trigger">82         <SidebarProvider breakpoint={9999} shortcutKey={null}>83           <div className="flex max-w-[280px] flex-col gap-3">84             <div className="flex items-center gap-2 font-mono text-xs text-muted-foreground">85               <SidebarTrigger className="border border-border px-2 py-1" />86               <span>~/ui/docs</span>87             </div>88             <Sidebar variant="caret" aria-label="Primary navigation">89               <NavBody />90             </Sidebar>91             <p className="text-xs text-muted-foreground font-mono">92               Tap [≡] to open the sheet over the page. ESC or an outside click closes it and returns93               focus to the trigger.94             </p>95           </div>96         </SidebarProvider>97       </Pane>98     </div>99   );100 }101

Iframe viewport ownership

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { createPortal } from "react-dom";5 import {6   Sidebar,7   SidebarContent,8   SidebarHeader,9   SidebarItem,10   SidebarProvider,11   SidebarTrigger,12 } from "@/components/ui/sidebar";13 14 const FRAME_DOCUMENT = `<!doctype html>15 <html>16   <head></head>17   <body></body>18 </html>`;19 20 function syncHostStylesIntoFrame(frameDocument: Document): Promise<void> {21   const frameHtml = frameDocument.documentElement;22   const hostHtml = document.documentElement;23 24   for (const { name, value } of Array.from(hostHtml.attributes)) {25     if (name === "class" || name.startsWith("data-")) {26       frameHtml.setAttribute(name, value);27     }28   }29 30   const head = frameDocument.head;31   const reset = frameDocument.createElement("style");32   reset.textContent = "html,body{height:100%;margin:0}";33   head.append(reset);34 35   const loads: Promise<void>[] = [];36   for (const node of document.head.querySelectorAll('link[rel="stylesheet"], style')) {37     const clone = node.cloneNode(true);38     if (clone instanceof HTMLLinkElement) {39       loads.push(40         new Promise((resolve) => {41           clone.addEventListener("load", () => resolve(), { once: true });42           clone.addEventListener("error", () => resolve(), { once: true });43         }),44       );45     }46     head.append(clone);47   }48 49   return loads.length > 0 ? Promise.all(loads).then(() => undefined) : Promise.resolve();50 }51 52 export default function SidebarOwnerWindow() {53   const [frameBody, setFrameBody] = useState<HTMLElement | null>(null);54   // Mounted by default so the frame renders a sidebar instead of an empty box55   // on first paint; the buttons still exercise the mount/unmount lifecycle.56   // The sheet's viewport is the iframe, not the host page: with breakpoint 60057   // and a 420px frame the nav is a mobile sheet however wide the host window is,58   // and resizing the host alone never flips it.59   const [mounted, setMounted] = useState(true);60 61   return (62     <div className="flex flex-col gap-3 p-4 bg-background">63       <div className="flex gap-2">64         <button65           type="button"66           className="border border-border px-2 py-1 font-mono text-xs"67           disabled={!frameBody || mounted}68           onClick={() => setMounted(true)}69         >70           Mount frame sidebar71         </button>72         <button73           type="button"74           className="border border-border px-2 py-1 font-mono text-xs"75           disabled={!mounted}76           onClick={() => setMounted(false)}77         >78           Unmount frame sidebar79         </button>80       </div>81       <iframe82         title="Sidebar owner window"83         srcDoc={FRAME_DOCUMENT}84         className="h-72 border border-border bg-background"85         style={{ width: 420 }}86         onLoad={(event) => {87           const frameDocument = event.currentTarget.contentDocument;88           if (!frameDocument) return;89           void syncHostStylesIntoFrame(frameDocument).then(() => setFrameBody(frameDocument.body));90         }}91       />92       {mounted && frameBody93         ? createPortal(94             <SidebarProvider breakpoint={600} shortcutKey={null}>95               <div className="flex items-center gap-2 border-b border-border px-2 py-1 font-mono text-xs">96                 <SidebarTrigger />97                 <span>~/frame</span>98               </div>99               <Sidebar aria-label="Frame navigation">100                 <SidebarHeader>iframe viewport</SidebarHeader>101                 <SidebarContent>102                   <SidebarItem as="button" active>103                     overview104                   </SidebarItem>105                   <SidebarItem as="button">requests</SidebarItem>106                   <SidebarItem as="button">console</SidebarItem>107                 </SidebarContent>108               </Sidebar>109             </SidebarProvider>,110             frameBody,111           )112         : null}113     </div>114   );115 }116

Auto-tone intent dots

tsx

1 import {2   Sidebar,3   SidebarContent,4   SidebarHeader,5   SidebarItem,6   SidebarItemBadge,7   SidebarItemLabel,8   SidebarSection,9   SidebarSectionTitle,10 } from "@/components/ui/sidebar";11 12 /**13  * Demonstrates `autoTone` with explicit intents. Each row keeps a unique navigation `value`, while14  * `intent` supplies the status dot independently of that identifier and takes precedence over the15  * built-in value dictionary. Color is decoration only; the badge text carries the same meaning for16  * assistive tech.17  */18 export default function SidebarAutoTone() {19   return (20     <Sidebar embedded autoTone variant="bar" className="h-full">21       <SidebarHeader>22         <span className="text-xs font-mono text-muted-foreground">~/ci/pipeline</span>23       </SidebarHeader>24       <SidebarContent>25         <SidebarSection>26           <SidebarSectionTitle>build</SidebarSectionTitle>27           <SidebarItem value="lint" intent="success">28             <SidebarItemLabel>lint</SidebarItemLabel>29             <SidebarItemBadge>30               <span className="text-xs text-muted-foreground">passed</span>31             </SidebarItemBadge>32           </SidebarItem>33           <SidebarItem value="typecheck" intent="success">34             <SidebarItemLabel>typecheck</SidebarItemLabel>35             <SidebarItemBadge>36               <span className="text-xs text-muted-foreground">passed</span>37             </SidebarItemBadge>38           </SidebarItem>39           <SidebarItem active value="compile" intent="success">40             <SidebarItemLabel>compile</SidebarItemLabel>41             <SidebarItemBadge>42               <span className="text-xs text-muted-foreground">passed</span>43             </SidebarItemBadge>44           </SidebarItem>45         </SidebarSection>46         <SidebarSection>47           <SidebarSectionTitle>test</SidebarSectionTitle>48           <SidebarItem value="unit" intent="warning">49             <SidebarItemLabel>unit</SidebarItemLabel>50             <SidebarItemBadge>51               <span className="text-xs text-muted-foreground">3 warn</span>52             </SidebarItemBadge>53           </SidebarItem>54           <SidebarItem value="integration" intent="danger">55             <SidebarItemLabel>integration</SidebarItemLabel>56             <SidebarItemBadge>57               <span className="text-xs text-muted-foreground">1 fail</span>58             </SidebarItemBadge>59           </SidebarItem>60           <SidebarItem value="e2e" intent="info">61             <SidebarItemLabel>e2e</SidebarItemLabel>62             <SidebarItemBadge>63               <span className="text-xs text-muted-foreground">running</span>64             </SidebarItemBadge>65           </SidebarItem>66         </SidebarSection>67         <SidebarSection>68           <SidebarSectionTitle>deploy</SidebarSectionTitle>69           <SidebarItem value="preview" intent="neutral">70             <SidebarItemLabel>preview</SidebarItemLabel>71             <SidebarItemBadge>72               <span className="text-xs text-muted-foreground">pending</span>73             </SidebarItemBadge>74           </SidebarItem>75           <SidebarItem value="production" intent="danger">76             <SidebarItemLabel>production</SidebarItemLabel>77             <SidebarItemBadge>78               <span className="text-xs text-muted-foreground">blocked</span>79             </SidebarItemBadge>80           </SidebarItem>81         </SidebarSection>82       </SidebarContent>83     </Sidebar>84   );85 }86

Render-prop items

tsx

1 "use client";2 3 import {4   Sidebar,5   SidebarContent,6   SidebarFooter,7   SidebarHeader,8   SidebarItem,9   SidebarItemBadge,10   SidebarItemLabel,11   SidebarSection,12   SidebarSectionTitle,13 } from "@/components/ui/sidebar";14 15 export default function SidebarRenderProp() {16   return (17     <Sidebar embedded className="h-full">18       <SidebarHeader>19         <span className="text-sm font-mono font-bold">Navigation</span>20       </SidebarHeader>21       <SidebarContent>22         <SidebarSection>23           <SidebarSectionTitle>Pages</SidebarSectionTitle>24           <SidebarItem active>25             {({ itemPrefix, ref, ...itemProps }) => (26               <a {...itemProps} ref={ref} href="/dashboard">27                 {itemPrefix}28                 <SidebarItemLabel>Dashboard</SidebarItemLabel>29                 <SidebarItemBadge>30                   <span className="text-xs text-muted-foreground">3</span>31                 </SidebarItemBadge>32               </a>33             )}34           </SidebarItem>35           <SidebarItem>36             {({ itemPrefix, ref, ...itemProps }) => (37               <a {...itemProps} ref={ref} href="/settings">38                 {itemPrefix}39                 <SidebarItemLabel>Settings</SidebarItemLabel>40               </a>41             )}42           </SidebarItem>43           <SidebarItem disabled>44             {({ itemPrefix, ref, disabled, ...itemProps }) => (45               <a {...itemProps} ref={ref} aria-disabled={disabled}>46                 {itemPrefix}47                 <SidebarItemLabel>Admin</SidebarItemLabel>48               </a>49             )}50           </SidebarItem>51         </SidebarSection>52       </SidebarContent>53       <SidebarFooter>54         <span className="text-xs text-muted-foreground font-mono">Render prop pattern</span>55       </SidebarFooter>56     </Sidebar>57   );58 }59

API Reference

Sidebar

Name	Type	Default	Description
variant	"caret" \| "inverted" \| "bar" \| "terminal" \| "tree"	"caret"	Visual variant. "caret" reserves a chevron marker slot shown on the active row; "inverted" full-bleeds the active row with bg-foreground; "bar" draws a 2px left edge with a soft fill on active; "terminal" shows the chevron prompt on the active item and draws a 1px hairline left rail with no background fill; "tree" renders bold section headers with stroke-chevron folds and single-hairline connectors with a soft active fill. Propagated to items via context and exposed as data-variant on the nav root.
autoTone	boolean	false	When true, renders a small intent dot before each item label and derives intent from the item value via the built-in dictionary unless overridden by an explicit intent prop on the item. Color is decoration only (WCAG 1.4.1) — pair with a text/glyph cue.
embedded	boolean	false	When true, keeps navigation inline on mobile instead of portaling into the built-in Dialog sheet. Use when a parent shell already owns the mobile drawer or overlay.
childrenrequired	ReactNode	—	Sidebar subparts (Header, Content, Footer, Trigger).

Sidebar.Provider

Name	Type	Default	Description
state	"open" \| "rail" \| "hidden"	—	Documented exception to the `value`/`onChange` control convention: the sidebar exposes a tri-state value (`"open" \| "rail" \| "hidden"`), so the boolean `collapsed`/`onCollapsedChange` shape cannot represent it. `state` and `onStateChange` are the semantic names for this tri-state control.
defaultState	"open" \| "rail" \| "hidden"	"open"	Initial visibility state for uncontrolled use. Below the breakpoint this value is not used for presentation — the mobile sheet has its own internal open state that always starts closed — but it is preserved untouched for the next desktop layout.
onStateChange	(state: "open" \| "rail" \| "hidden") => void	—	Fired when the visibility state changes (controlled and uncontrolled).
breakpoint	number	1024	Viewport width (px) below which the sidebar collapses into a mobile sheet. Default matches Tailwind lg.
shortcutKey	string \| null	"b"	Case-insensitive hotkey. On desktop Cmd/Ctrl+<key> cycles open ↔ rail and Shift+Cmd/Ctrl+<key> toggles hidden. On mobile both combinations toggle the sheet, and neither writes the desktop state. Pass null to disable.
childrenrequired	ReactNode	—	Sidebar and main content that need access to the state via useSidebar().

Sidebar.Trigger

Name	Type	Default	Description
aria-label	string	"Expand sidebar" / "Collapse sidebar" / "Open navigation" / "Close navigation"	Accessible name. Defaults to a state- and device-derived label.
children	ReactNode	"[≡]" (collapsed) / "[×]" (open)	Trigger button content (typically an icon).

Sidebar.Header

Name	Type	Default	Description
children	ReactNode	—	Top region content.

Sidebar.Content

Name	Type	Default	Description
children	ReactNode	—	Scrollable middle region. The complete Sidebar nav shell becomes aria-hidden and inert in the hidden state.

Sidebar.Section

Name	Type	Default	Description
collapsible	boolean	false	When true, Sidebar.SectionTitle becomes a disclosure toggle that expands/collapses the section.
open	boolean	—	Controlled open state for the section.
defaultOpen	boolean	true	Initial open state for the section.
onOpenChange	(open: boolean) => void	—	Fired when the section open state changes.
children	ReactNode	—	Section subparts (SectionTitle, SectionContent, Items).

Sidebar.SectionTitle

Name	Type	Default	Description
headingLevel	"h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6"	"h3"	Heading level rendered for the section title. Default h3 keeps screen-reader heading-rotor navigation predictable. Collapsible sections wrap a button with aria-expanded/aria-controls inside the heading.
handle	ReactNode \| null	<Chevron open={isOpen} size="sm" />	Custom handle element for collapsible sections. Pass null to hide.
children	ReactNode	—	Section label.

Sidebar.SectionContent

Name	Type	Default	Description
children	ReactNode	—	Panel for collapsible sections. Wires the section title's aria-controls, stays mounted for animation, and becomes aria-hidden and inert while closed. For non-collapsible sections this is a no-op wrapper and may be omitted.

Sidebar.Item

Name	Type	Default	Description
as	"a" \| "button"	"a"	Rendered element. Items are navigation links by default; pass as="button" for non-navigation actions.
active	boolean	false	Marks the item as the current page. Adds aria-current="page", data-selected, and the variant's active styling.
value	string	auto-generated id	Stable identifier exposed as data-value for keyboard navigation and intent lookup.
intent	"neutral" \| "info" \| "success" \| "warning" \| "danger" \| "accent"	undefined (or auto from value when autoTone is enabled)	Item intent. Renders as data-intent and tints the auto-tone dot from semantic tokens: neutral → --muted-foreground, info → --info-strong, success → --success-strong, warning → --warning-strong, danger → --error-strong, accent → --action. When autoTone is enabled on Sidebar and intent is omitted, it is inferred from value via the built-in dictionary. Color is decoration only — pair with a text/glyph cue.
disabled	boolean	false	Disables the item. Adds aria-disabled and removes from tab order.
childrenrequired	ReactNode \| (props: SidebarItemRenderProps<HTMLAnchorElement>) => ReactNode	—	Sidebar subparts/item content or a render function (for framework Link components) that receives ref, className, disabled, aria-current, aria-disabled, data-selected, data-intent, data-value, onClick, tabIndex, and itemPrefix. itemPrefix is a ReactNode (intent dot, variant glyph) that must be rendered as the element's leading content, never spread onto the element.

Sidebar.ItemLabel

Name	Type	Default	Description
children	ReactNode	—	Truncated label text.

Sidebar.ItemBadge

Name	Type	Default	Description
children	ReactNode	—	Trailing badge or metadata (e.g. count, status).

Sidebar.Footer

Name	Type	Default	Description
children	ReactNode	—	Bottom region content.

Data attributes

Attribute	Applies to	Values	Description
data-state	Sidebar / Sidebar.Content	"open" \| "rail" \| "hidden"	Current provider visibility state used for root and content styling.
data-state	Sidebar.Trigger	"open" \| "collapsed"	Binary visual state: open when the sidebar is visible at full width, collapsed for desktop rail and hidden states.
data-state	Sidebar.Section / Sidebar.SectionContent	"open" \| "closed"	Collapsible section disclosure state.
data-variant	Sidebar	"caret" \| "inverted" \| "bar" \| "terminal" \| "tree"	Active-marker variant applied to the nav root and consumed by descendants.
data-selected	Sidebar.Item	present when active	Marks the current page/action row.
data-intent	Sidebar.Item	"neutral" \| "info" \| "success" \| "warning" \| "danger" \| "accent"	Optional or auto-derived tone for the decorative intent dot.
data-value	Sidebar.Item	item value	Stable navigation and auto-tone lookup value.
data-auto-tone	Sidebar	present when enabled	Marks roots that derive item intent from values.
data-mobile	Sidebar mobile sheet	"true"	Marks the off-canvas mobile sheet instance.

Accessibility

Keyboard Navigation

Sidebar.Content owns roving arrow navigation for visible items. SidebarProvider also binds the global Cmd/Ctrl+B shortcut by default and skips editable targets.

Key	Action
ArrowUp / ArrowDown	Moves focus to the previous or next visible Sidebar.Item.
Home / End	Moves focus to the first or last visible item.
Enter / Space	Activates a focused button item; links use their native activation behavior.
Cmd/Ctrl+B	Cycles desktop open ↔ rail, or opens/closes the mobile sheet.
Shift+Cmd/Ctrl+B	Toggles the desktop hidden state, or opens/closes the mobile sheet.

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. The `bar` variant is that shared rail. `caret`, `terminal` and `tree` are deliberate alternative idioms with their own gutter grammar, and `inverted` is the loud full-bleed option; pick `bar` when you want the library-standard mark.

Requires @diffgazer/keys (package mode)

Sidebar's arrow-key navigation imports from the required @diffgazer/keys peer. Package consumers must install @diffgazer/keys with @diffgazer/ui; packages are not yet published to npm, so until the first release install both from locally packed tarballs. Importing @diffgazer/ui/components/sidebar without keys fails at module load with an error naming the missing @diffgazer/keys package. Copy/dgadd consumers do not need the package — copy mode rewrites the keyboard hooks to local source.

Tri-state visibility

Sidebar tracks three states via SidebarProvider: "open" (full width), "rail" (collapsed glyph rail, desktop only), and "hidden" (off-canvas). Below the breakpoint the tri-state describes the desktop layout only — the sheet is driven by its own internal open state, so a desktop → mobile → desktop round trip restores the exact state it started with. Hidden desktop navigation marks the complete nav shell aria-hidden and inert, including Header, Content, and Footer. Keep a SidebarTrigger outside that shell or use the provider hotkey so users can reopen it. The provider exposes state/defaultState/onStateChange and helpers toggleSidebar (desktop open ↔ rail) and toggleHidden (desktop open ↔ hidden); on mobile both toggle the sheet instead.

Mobile sheet

Below the breakpoint (default 1024px) the nav renders inside a Dialog sheet anchored to the viewport's left edge. The sheet starts closed and opens from SidebarTrigger, the global hotkey, or useSidebar().onMobileOpenChange. No mobile transition — entering the sheet, opening it, closing it, or leaving for desktop — emits onStateChange. state and defaultState control the desktop presentation only, so a controlled parent pinning a value does not block the sheet. The breakpoint is configurable on SidebarProvider.

Global hotkey

An explicit SidebarProvider binds a configurable global shortcut. On desktop Cmd/Ctrl+<key> cycles open ↔ rail and Shift+Cmd/Ctrl+<key> toggles hidden; on mobile both toggle the sheet and neither writes the desktop state. Default key is "b" (VS Code convention). Pass shortcutKey={null} to disable. A Sidebar used without a provider never binds the hotkey — global keys are an app-level contract, so opt in by mounting the provider. Editable targets (input/textarea/contenteditable/select) skip the handler.

SidebarProvider vs standalone

Wrap Sidebar in SidebarProvider when you need to control state from outside the sidebar, react to it elsewhere (e.g. a header trigger), or enable the global hotkey. When Sidebar is used without a provider it instantiates one internally without the hotkey. Read state, isMobile, openMobile, onStateChange, and onMobileOpenChange from any descendant via useSidebar().

Visual variants

Five active-marker variants share one rule — structure is permanent, markers appear on the active row: caret (reserved chevron marker slot; invisible at rest, dim on hover, foreground on active), inverted (full-bleed bg-foreground row), bar (2px border-l plus soft fill on active), terminal (chevron prompt on active; 1px hairline left rail, no bg fill), tree (bold section headers with stroke-chevron folds; single-hairline CSS connectors — trunk/tick/corner — with soft active fill). Selected via <Sidebar variant=…> and propagated to items via context. Exposed as data-variant on the nav root.

Auto-tone (intent dot)

Opt-in via <Sidebar autoTone>. Renders a small dot before each item label whose color is derived from the item value through a built-in dictionary (added → success, deleted → danger, modified → warning, etc.) or from an explicit intent prop on SidebarItem. Color is decoration only (WCAG 1.4.1) — always pair with a text/glyph cue (the label, a badge).

Collapsible sections

SidebarSection accepts collapsible. SidebarSectionTitle renders an ARIA disclosure (h3 wrapping a button with aria-expanded/aria-controls). A title rendered through an opaque consumer wrapper registers after mount so the role=group keeps its accessible name; for server-rendered opaque wrappers, give the heading a stable id and pass it to Sidebar.Section through aria-labelledby. SidebarSectionContent stays mounted for the close animation and becomes aria-hidden and inert while closed. Supports controlled open/onOpenChange or uncontrolled defaultOpen.

Rail mode naming

In rail state the visible label and badge collapse to display:none, leaving an icon-only row. SidebarItem automatically preserves the accessible name by rendering an sr-only copy of its label content that appears in the accessibility tree only while the sidebar is in rail state, so icon-only links and buttons keep a non-empty name. Render-prop items own their own markup, so supply an aria-label (or sr-only text) for the rail state yourself.

Item render props

SidebarItem supports a render-prop children for custom elements (e.g. framework Link components). The render function receives ref, className, disabled, aria-current, aria-disabled, data-selected, data-intent, data-value, onClick, tabIndex, and itemPrefix — a ReactNode carrying the intent dot and variant glyph. Destructure itemPrefix and render it as the element's leading content; never spread it onto the element.

SSR persistence

The provider exports SIDEBAR_STATE_COOKIE but intentionally does not read or write it. SSR frameworks should parse the cookie in their loader, pass the resolved value as defaultState, and mirror onStateChange writes back via document.cookie (SameSite=Lax, 1y). Mirroring is unconditional: mobile transitions never fire it, so the stored desktop preference survives a phone visit.

Source

Install via CLI: pnpm exec dgadd add ui/sidebar. 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.

Sidebar

Installation

Usage

Mobile

Variants

Examples

Variant — terminal

Variant — tree

Collapsible sections

Rail mode

Mobile sheet

Iframe viewport ownership

Auto-tone intent dots

Render-prop items

API Reference

Sidebar

Sidebar.Provider

Sidebar.Trigger

Sidebar.Header

Sidebar.Content

Sidebar.Section

Sidebar.SectionTitle

Sidebar.SectionContent

Sidebar.Item

Sidebar.ItemLabel

Sidebar.ItemBadge

Sidebar.Footer

Data attributes

Accessibility

Keyboard Navigation

Notes

Current-location mark

Requires @diffgazer/keys (package mode)

Tri-state visibility

Mobile sheet

Global hotkey

SidebarProvider vs standalone

Visual variants

Auto-tone (intent dot)

Collapsible sections

Rail mode naming

Item render props

SSR persistence

Source

View component source (80 files)