Sidebar

Install

pnpm dlx shadcn@latest add @vegastack/sidebar

Usage

import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
} from "@/components/ui/sidebar";

<SidebarProvider>
  <Sidebar aria-label="Main navigation">
    <SidebarHeader>…logo / workspace switcher…</SidebarHeader>
    <SidebarContent>
      <SidebarGroup>
        <SidebarGroupLabel>Workspace</SidebarGroupLabel>
        <SidebarMenu>
          <SidebarMenuItem>
            <SidebarMenuButton isActive render={<a href="/" />}>
              <Home />
              <span>Home</span>
            </SidebarMenuButton>
          </SidebarMenuItem>
          <SidebarMenuItem>
            <SidebarMenuButton render={<a href="/inbox" />}>
              <Inbox />
              <span>Inbox</span>
            </SidebarMenuButton>
          </SidebarMenuItem>
        </SidebarMenu>
      </SidebarGroup>
    </SidebarContent>
    <SidebarFooter>
      <SidebarMenuButton render={<a href="/settings" />}>
        <Settings />
        <span>Settings</span>
      </SidebarMenuButton>
    </SidebarFooter>
  </Sidebar>
  <div className="flex min-w-0 flex-1 flex-col">
    <header>
      {/* Always mounted: collapses the desktop rail and opens the mobile Sheet. */}
      <SidebarTrigger />
    </header>
    {/* …your page content… */}
  </div>
</SidebarProvider>;

Persistence

While persist is on — it is by default — every desktop toggle writes a sidebar_state cookie (path=/, max-age ~1 year) so the sidebar can restore its state across page loads. The cookie is the only piece of application policy this component holds, so it is deliberately switchable:

persist={false} gates the write only. onOpenChange still fires on every toggle either way, so nothing about the component's behaviour changes except that it stops touching document.cookie.

SidebarProvider only ever WRITES the cookie, client-side, in response to a user action; it never reads document.cookie at render (that would differ between server and client and trigger a hydration mismatch). To restore state on the next load, read the cookie in your server layout and pass it as defaultOpen:

// app/layout.tsx (Server Component)
import { cookies } from "next/headers";

export default async function Layout({
  children,
}: {
  children: React.ReactNode;
}) {
  const defaultOpen = (await cookies()).get("sidebar_state")?.value !== "false";
  return (
    <SidebarProvider defaultOpen={defaultOpen}>{children}</SidebarProvider>
  );
}

Anatomy

Sidebar is a compound component. SidebarProvider owns the expanded/collapsed state and lays the rail out next to your page content; everything else composes inside the <nav> landmark:

<SidebarProvider defaultOpen>
  <Sidebar aria-label="Main navigation">
    <SidebarHeader>…app switcher / logo + SidebarTrigger…</SidebarHeader>
    <SidebarContent>
      <SidebarGroup>
        <SidebarGroupLabel>Group</SidebarGroupLabel>
        <SidebarMenu>
          <SidebarMenuItem>
            <SidebarMenuButton isActive>
              <Icon />
              <span>Label</span>
            </SidebarMenuButton>
            <SidebarMenuBadge>3</SidebarMenuBadge>
          </SidebarMenuItem>
        </SidebarMenu>
      </SidebarGroup>
      <SidebarSeparator />
    </SidebarContent>
    <SidebarFooter>…user menu…</SidebarFooter>
  </Sidebar>
</SidebarProvider>

• SidebarProvider — owns the open state (controlled open/onOpenChange or uncontrolled defaultOpen), the mobile Sheet's openMobile state, and exposes both via useSidebar(). Registers ⌘/Ctrl+B to toggle, and — unless persist={false} — writes the sidebar_state cookie on every desktop toggle (see "Persistence" below).
• Sidebar — the <nav> rail (data-slot="sidebar"). Carries data-state="expanded|collapsed", data-collapsible, and data-variant for descendant styling, and animates its width between states. On desktop it stays anchored to the viewport while the adjacent document scrolls. Below the mobile breakpoint (768px by default) it renders its children inside a Sheet instead — see "Mobile" below.
• SidebarHeader / SidebarFooter — the non-shrinking top and bottom regions (logo / app switcher, user menu). The footer remains at the viewport bottom on desktop.
• SidebarContent — the flexible, scrollable middle region that holds the groups. When navigation is taller than the viewport, scroll this region rather than the header/footer or entire rail.
• SidebarGroup + SidebarGroupLabel — a labelled section; the label fades out when collapsed.
• SidebarMenu / SidebarMenuItem — the <ul> / <li> list structure for nav entries.
• SidebarMenuButton — the interactive row. Renders a <button> by default; pass render={<a />} for a nav link. isActive applies the accent background, leading rail, and aria-current="page".
• SidebarMenuBadge — an optional count/status pill on a menu item; it becomes a compact status dot in the collapsed icon rail while retaining its text for assistive technology.
• SidebarMenuSkeleton — a loading placeholder shaped like a SidebarMenuButton row.
• SidebarSeparator — a thin inset rule between sections.
• SidebarTrigger — a PanelLeft icon button that toggles the rail (or, on mobile, the Sheet); place it in a header.
• SidebarRail — a thin click-to-toggle edge strip; render it as a child of Sidebar.
• SidebarInset — the main-content wrapper for variant="inset"; render it as Sidebar's sibling.

Examples

Multiple labelled groups, each with its own menu items:

The collapsed icon rail — labels and group headings hide, leaving only icons (toggle it with the trigger):

Right edge

Set side="right" to dock the rail on the trailing edge — it picks up a left border and orders itself after the page content:

Menu button sizes

SidebarMenuButton accepts a size of sm (h-7), md (h-8), or lg (h-10):

Controlled mode

Drive the open state yourself with open / onOpenChange on SidebarProvider, and read or toggle it from any descendant with useSidebar() — here an external button outside the rail:

Variants

variant="floating" detaches the rail into its own bordered, shadowed panel:

variant="inset" keeps the rail flush, and instead makes SidebarInset (the main content) the rounded/bordered/shadowed panel. Pair it with SidebarRail for a click-to-toggle edge strip alongside the explicit trigger:

Off-canvas collapse

collapsible="offcanvas" slides the rail fully off-screen (instead of shrinking to an icon rail) when toggled — page content reflows to fill the space:

collapsible="none" is also available for a rail that should never collapse at all (and never becomes the mobile Sheet) — useful inside a fixed-size panel where collapsing doesn't make sense.

Loading state

SidebarMenuSkeleton composes Skeleton into an icon-circle + text-line row shaped like SidebarMenuButton. Pass each row's index so the text-line widths vary — deterministically, off a small fixed cycle, never Math.random() — instead of every row rendering identically:

Mobile

Below the mobile breakpoint (768px by default — override with SidebarProvider's mobileBreakpoint), Sidebar renders its children inside a Sheet (side="left" by default, following the side prop) instead of the static rail — you get focus trapping, scroll locking, and Escape-to-close for free from Sheet. SidebarProvider tracks this as openMobile, separate from desktop open: collapsing to icons and sliding a Sheet in are different interactions that can't share one boolean. useSidebar() also exposes isMobile if you need to branch on it directly.

Place SidebarTrigger (or any custom control that calls toggleSidebar()) OUTSIDE Sidebar — typically in your persistent page header — not inside SidebarHeader. Below the breakpoint, Sidebar's own children (the trigger included, if nested inside it) only mount once the Sheet is already open; nesting the one control that opens it in there is a dead end. A layout that needs to work at every width composes it like this:

<SidebarProvider>
  <SidebarTrigger />{" "}
  {/* outside Sidebar — always mounted, opens the Sheet on mobile */}
  <Sidebar aria-label="Main navigation">…</Sidebar>
  <SidebarInset>…page content…</SidebarInset>
</SidebarProvider>

Switch the preview's width toggle (the toolbar's phone icon) to mobile to watch the rail collapse into a Sheet you open from the header trigger. This is viewport-driven in a real app; the toggle only constrains a container, so this demo forces the branch to make it visible without resizing your window.

API Reference

SidebarProvider

Sidebar

SidebarMenuButton

SidebarMenuSkeleton

SidebarSeparator

SidebarTrigger

SidebarHeader, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupLabel, SidebarMenu, SidebarMenuItem, SidebarMenuBadge, SidebarRail, and SidebarInset add no props of their own — each accepts everything its underlying element accepts (<div>, <h3>, <ul>, <li>, <span>, <button>, <main>), plus className and ref.

Accessibility

• Sidebar renders a <nav> landmark — pass an aria-label to name it (e.g. "Main navigation") so screen readers can distinguish it from other navigation regions.
• SidebarGroupLabel renders a heading for grouped navigation content.
• The active item sets aria-current="page" in addition to the visual highlight, so assistive tech announces the current location.
• SidebarMenuButton and SidebarTrigger are real <button> (or <a>) elements. On hover/press they climb the surface ladder through the shared surfaceInteractive recipe (hover:bg-surface-2 active:bg-surface-3, with text-sidebar-accent-foreground). The active row adds a leading rail and rests on data-[active=true]:bg-surface-3, then steps back DOWN to surface-2 on hover and returns to surface-3 while pressed — so a selected row still visibly moves under the cursor. Neither element carries a per-component :focus-visible style — keyboard focus relies on the design system's global :focus-visible outline ring (outline-ring, since they never set outline: none). Consumers who do not load the global focus rule fall back to the user-agent default outline, so verify a visible focus indicator in your own shell.
• SidebarTrigger carries an aria-label="Toggle sidebar"; the icon is aria-hidden. Its visible box is 28px — an invisible ::before hit-area expansion brings the effective target to ~44px (WCAG 2.5.8) without changing the visible icon.
• SidebarRail is a real, focusable <button> (not a mouse-only edge-drag handle) with the same aria-label/title, so keyboard users can reach and operate it too.
• On mobile, the rail renders inside Sheet — focus trapping, scroll locking, and Escape-to-close all come from Sheet.
• The collapse toggle is also bound to ⌘/Ctrl+B by default; set keyboardShortcut={false} or pass a custom key on SidebarProvider when embedding the sidebar in a context with conflicting shortcuts.

Do / Don't