Sidebar

Live demo

Sidebar reads useShell(), so it only renders inside a ShellProvider. Everything it shows — the switcher, the groups, the badge, the disabled row, the nested branch — comes from the nav and workspaces props.

Inside AppShell

Apps rarely mount the sidebar themselves. AppShell wires ShellProvider + Sidebar + AppHeader + MobileMenu in one frame and forwards this component’s props through sidebarProps. In the header-first layout it also flips showWorkspaceSwitcher and showCollapseButton off, because the header has taken both over.

'use client'

import type { ReactNode } from 'react'
import { AppShell } from '@comitor/ui/shell'
import { NAV } from './nav'
import { NewTaskButton } from './new-task-button'
import { StorageMeter } from './storage-meter'

export function TasksLayout({ children }: { children: ReactNode }) {
  return (
    <AppShell
      nav={NAV}
      workspaces={[{ id: 'acme', name: 'Acme Corp', slug: 'acme', plan: 'Business' }]}
      user={{ id: 'u1', name: 'Bình Phan', email: '[email protected]' }}
      // Everything below is forwarded to <Sidebar />.
      sidebarProps={{
        header: <NewTaskButton />,
        footer: <StorageMeter />,
      }}
    >
      {children}
    </AppShell>
  )
}

Collapsed rail

Collapsed, the sidebar is 56px of icon tiles: group labels go (there is no room), badges shrink to a dot, and every row keeps its label in a tooltip on the right. The footer slot is not rendered at this width. Use the button at the bottom to expand it again.

Composing your own frame

SidebarGroup and SidebarMenuItem are exported so an app with its own chrome can still render the shell’s nav — the collapsible group header, the nested branches, the active matching, the badges. They stay inside a ShellProvider either way.

import { SidebarGroup, flattenNavItems } from '@comitor/ui/shell'
import type { NavGroup } from '@comitor/ui/shell'

/**
 * Own chrome, shell nav rendering. Must still sit inside a <ShellProvider>:
 * SidebarGroup delegates to SidebarMenuItem, which reads useShell() for the
 * pathname, the link component and the labels.
 */
export function CustomRail({ nav }: { nav: NavGroup[] }) {
  // Pass EVERY item of the app as `siblings`, not just the ones in this group —
  // otherwise "/tasks" stays lit while you are standing on "/tasks/inbox".
  const items = flattenNavItems(nav)

  return (
    <aside className="flex w-sidebar flex-col border-r border-sidebar-border bg-sidebar">
      <nav aria-label="Main navigation" className="flex flex-1 flex-col gap-4 overflow-y-auto p-2">
        {nav.map((group) => (
          <SidebarGroup key={group.id} group={group} siblings={items} />
        ))}
      </nav>
    </aside>
  )
}

How it works

• Shell context is required. Sidebar pulls nav, currentApp, workspaces, sidebarCollapsed, toggleSidebar and labels out of useShell(). Rendered outside a ShellProvider it throws rather than rendering empty. The provider also supplies the TooltipProvider the icon rail needs.
• Active matching is exact first. The sidebar flattens every group with flattenNavItems() and hands the whole list down as siblings, so a prefix match only wins when no row matches the pathname exactly — /tasks goes dark once you stand on /tasks/inbox.
• Collapse state lives in the shell, in localStorage. Keyed comitor-sidebar:<workspaceId>, so each workspace remembers its own — no cookie, no second provider. Toggle it from the footer button, from ⌘/Ctrl + B, or through setSidebarCollapsed.
• Tablet starts collapsed. Between 768px and 1023px a 256px rail eats a third of the width, so a reader who has never toggled gets the icon rail. Measured once on mount, never on resize, and never written back to storage — a default, not a decision.
• Width comes from two tokens. --sidebar-width (16rem / 256px) and --sidebar-width-icon (3.5rem / 56px) surface as the utilities w-sidebar and w-sidebar-icon, with a 200ms transition between them. The switcher strip is h-header. Override the tokens, not the component.
• Below md it renders nothing. The <aside> is hidden md:flex — pure CSS, no viewport measurement, no hydration mismatch. Narrow screens get MobileMenu, an off-canvas Sheet driven by mobileMenuOpen, which reorders the same content: workspace, current app’s menu, app list, user.
• Colour comes from the sidebar tokens. --sidebar, --sidebar-foreground, --sidebar-border, --sidebar-accent and --sidebar-accent-foreground, so both palettes and both themes stay correct. The active row deliberately does not use the app accent: gold on the active tint measures 1.70:1, which is invisible exactly when it has something to say.

Sidebar props

SidebarGroup props

SidebarMenuItem props

ShellProvider props that drive the sidebar

A subset of ShellProviderProps — AppShell accepts every one of them too and passes them straight through.

Accessibility

• The menu is a real <nav> labelled with labels.navigationLabel. A group with no header — an unlabelled group, one with collapsible: false, or any group in the icon rail — is a role="group" carrying group.label as its accessible name. A labelled collapsible group needs no such role: its visible header button names it already.
• The active row is marked aria-current="page" and is set apart by background, text colour and weight at once — never by a colour-only bar.
• Group headers and parent rows are <button aria-expanded>, so a branch announces whether it is open before it is entered.
• Disabled rows are <span role="link" aria-disabled tabIndex={0}>, not a dimmed <a>: pointer-events-none stops the mouse but not the keyboard. They stay in the tab order on purpose, and are tinted with --muted-foreground (5.01:1 light / 5.35:1 dark) rather than an opacity that would drop them below the threshold. A disabled row that has children is the exception: it is a genuinely disabled <button> and leaves the tab order, because Enter on it would only fail to open a subtree.
• In the icon rail every row keeps a tooltip carrying its label and count, plus an aria-label, so a screen reader hears the same thing at both widths.
• The collapse button carries the long string in its aria-label and the short one as visible text. Keep collapseSidebarShort a substring of collapseSidebar when translating — WCAG 2.5.3, Label in Name.
• Group labels and branch chevrons use --muted-foreground instead of an alpha step, which is the only way both themes clear 4.5:1 for the text and 3:1 for the chevron.

Related