`Sidebar` — spec¶

Synthesized from shadcn-ui sidebar (the flagship Radix-based primitive). A persistent navigation panel — collapsible, themed, often the primary nav surface in dashboards / docs sites / IDE-style apps.

	Sidebar	Drawer
Persistence	Always visible (collapsible)	Modal or persistent; usually toggled
Use	Primary navigation in apps	Secondary nav, mobile-only nav
Desktop	Standard	Sometimes overkill
Mobile	Becomes a sheet	Full-screen takeover

Anatomy¶

┌────────────┬───────────────────────────┐
│ [logo]     │                           │
│ ──────     │                           │
│ Header     │                           │
│            │                           │
│ Workspace  │                           │
│  ▶ Project │      Main content         │
│    Inbox   │                           │
│    Tasks   │                           │
│            │                           │
│ Settings   │                           │
│ ──────     │                           │
│ [user]     │                           │
└────────────┴───────────────────────────┘
       ↑
   Sidebar

API¶

<Sidebar>
  <Sidebar.Header>
    <Logo />
    <WorkspaceSwitcher />
  </Sidebar.Header>

  <Sidebar.Content>
    <Sidebar.Group>
      <Sidebar.GroupLabel>Workspace</Sidebar.GroupLabel>
      <Sidebar.Menu>
        <Sidebar.MenuItem>
          <Sidebar.MenuButton href="/projects" active>
            <FolderIcon /> Projects
          </Sidebar.MenuButton>
          <Sidebar.MenuSub>
            <Sidebar.MenuSubItem href="/projects/active">Active</Sidebar.MenuSubItem>
            <Sidebar.MenuSubItem href="/projects/archive">Archive</Sidebar.MenuSubItem>
          </Sidebar.MenuSub>
        </Sidebar.MenuItem>
        <Sidebar.MenuItem>
          <Sidebar.MenuButton href="/inbox">
            <InboxIcon /> Inbox
            <Sidebar.MenuBadge>12</Sidebar.MenuBadge>
          </Sidebar.MenuButton>
        </Sidebar.MenuItem>
      </Sidebar.Menu>
    </Sidebar.Group>
  </Sidebar.Content>

  <Sidebar.Footer>
    <UserMenu />
  </Sidebar.Footer>
</Sidebar>

<SidebarTrigger /> {/* in main content header — toggles sidebar */}

Composition¶

Part	Purpose
`Sidebar`	Wrapper
`Header`	Top section (logo, workspace switcher)
`Content`	Scrollable middle (groups + menus)
`Footer`	Bottom section (user menu, settings)
`Group`	Logical section
`GroupLabel`	Section heading
`Menu`	List of items
`MenuItem`	Single item wrapper
`MenuButton`	Clickable item
`MenuSub`	Nested sub-menu (collapsible)
`MenuSubItem`	Sub-menu item
`MenuBadge`	Count / indicator on menu item
`MenuAction`	Right-aligned secondary action (e.g., "More" menu)
`Separator`	Visual divider
`Trigger`	Renders elsewhere; toggles sidebar

States¶

State	Visual
Expanded (default desktop)	Full width with labels
Collapsed (icon-only)	~64px width; only icons visible
Mobile (offcanvas)	Off-screen by default; opens as Sheet on trigger
Item active	Highlighted bg + brand-color indicator
Item hover	Subtle bg shift
Sub-menu collapsed	Hidden, parent item shows chevron
Sub-menu expanded	Items revealed, parent chevron rotated

Variants¶

Width modes¶

<Sidebar variant="sidebar" />      // standard fixed
<Sidebar variant="floating" />     // detached, with shadow
<Sidebar variant="inset" />        // inset within rounded shell

Collapsibility¶

<Sidebar collapsible="offcanvas" />  // mobile-style: slides off-canvas
<Sidebar collapsible="icon" />       // collapses to icon-only
<Sidebar collapsible="none" />       // always full width

Side¶

<Sidebar side="left" />   // default
<Sidebar side="right" />  // for tools / settings panels

Responsive behavior¶

Desktop (≥ 1024px):
  Expanded → user can collapse to icon mode

Tablet (768-1023px):
  Default to icon mode → user can expand

Mobile (< 768px):
  Offcanvas → invisible until trigger; opens as Sheet

State persists in localStorage so collapse preference survives sessions.

Tokens consumed¶

--sidebar-width                  (default 16rem / 256px)
--sidebar-width-icon             (collapsed; default 4rem / 64px)
--sidebar-bg                     (sidebar background, slightly different from main)
--sidebar-fg                     (text)
--sidebar-fg-muted               (group labels)
--sidebar-item-hover-bg
--sidebar-item-active-bg
--sidebar-item-active-fg
--sidebar-border                 (right border)
--space-xs, --space-sm, --space-md
--motion-medium                  (collapse animation)
--ease-out
--z-fixed                        (when fixed-position)

shadcn names them --sidebar-* so they don't conflict with main app theme.

Accessibility¶

Sidebar: <aside aria-label="Main navigation">.
Active item: aria-current="page" (not just visual).
Menu: <ul> semantically; items as <li>.
MenuButton: real <a> for nav links, <button> for actions.
Sub-menus: aria-expanded on parent toggle, aria-controls referencing sub-menu id.
Collapsed icon-only mode: each icon button needs aria-label (e.g., <button aria-label="Inbox">).
Mobile offcanvas: opens as Sheet with focus trap.
Keyboard: Tab navigates items; arrow keys can navigate within menu (optional, depends on design).

Code example¶

function AppShell({ children }: Props) {
  return (
    <SidebarProvider>
      <Sidebar collapsible="icon">
        <Sidebar.Header>
          <Logo />
        </Sidebar.Header>
        <Sidebar.Content>
          <Sidebar.Group>
            <Sidebar.GroupLabel>Workspace</Sidebar.GroupLabel>
            <Sidebar.Menu>
              {workspaceItems.map(item => (
                <Sidebar.MenuItem key={item.path}>
                  <Sidebar.MenuButton href={item.path} active={pathname === item.path}>
                    <item.icon />
                    <span>{item.label}</span>
                    {item.count && <Sidebar.MenuBadge>{item.count}</Sidebar.MenuBadge>}
                  </Sidebar.MenuButton>
                </Sidebar.MenuItem>
              ))}
            </Sidebar.Menu>
          </Sidebar.Group>
        </Sidebar.Content>
        <Sidebar.Footer>
          <UserMenu />
        </Sidebar.Footer>
      </Sidebar>

      <main>
        <header>
          <SidebarTrigger />
          <h1>{pageTitle}</h1>
        </header>
        {children}
      </main>
    </SidebarProvider>
  );
}

Korean apps¶

Sidebar 너비: 한글 메뉴는 영문보다 약간 더 넓은 너비가 필요 (typically 18rem instead of 16rem).
Group label: 한글 ("워크스페이스", "관리") works well; keep concise.
Active item indicator: 좌측 색상 막대 + 배경 강조; classic KR enterprise pattern.

Edge cases¶

Long item labels: truncate with ellipsis; show full text in tooltip on hover.
Many items (50+): scroll inside Content; pin Header + Footer.
Nested too deep: 3+ levels = navigation pain. Cap at 2 levels.
Sidebar in nested layouts: only one Sidebar per layout root; nested sidebars indicate over-decomposition.
Cross-tab sync: collapse state via localStorage works across tabs after refresh.
Reduced motion: skip collapse animation; instant width change.
Right-to-left: side="right" becomes left; borders swap.

Don't¶

Don't omit collapse on icon mode for desktop — power users need it.
Don't put non-navigation items (status, ads) in Sidebar — that's main content territory.
Don't lock to one width; respect collapse preference.
Don't omit aria-current="page" on active items.
Don't put 30 ungrouped items — use Group + GroupLabel.
Don't overload icon-only mode with no tooltip — users see only icons.

References¶

shadcn-ui: sidebar — flagship primitive
Patterns: VS Code, Linear, Notion sidebars

Cross-reference¶

examples/component-drawer.md — modal nav alternative
examples/component-sheet.md — mobile offcanvas variant
examples/component-navigation-menu.md — top nav alternative
knowledge/patterns/mobile-navigation.md

Sidebar — spec¶

When to use Sidebar vs Drawer¶

Anatomy¶

API¶

Composition¶

States¶

Variants¶

Width modes¶

Collapsibility¶

Side¶

Responsive behavior¶

Tokens consumed¶

Accessibility¶

Code example¶

Korean apps¶

Edge cases¶

Don't¶

References¶

Cross-reference¶

`Sidebar` — spec¶