Sidebar

import {
  FolderIcon,
  HomeIcon,
  InboxIcon,
  SearchIcon,
  SettingsIcon,
} from "lucide-react";
import { Avatar } from "@/components/ui/avatar";
import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarInset,
  SidebarMenu,
  SidebarMenuBadge,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
} from "@/components/ui/sidebar";

const items = [
  { title: "Home", icon: HomeIcon, active: true },
  { title: "Inbox", icon: InboxIcon, badge: "12" },
  { title: "Search", icon: SearchIcon },
  { title: "Projects", icon: FolderIcon },
  { title: "Settings", icon: SettingsIcon },
];

export default function SidebarDemo() {
  return (
    // data-sidebar-contained keeps the sidebar inside this box; omit it in a real app layout.
    <div
      data-sidebar-contained
      className="relative h-[420px] w-full overflow-hidden rounded-lg border"
    >
      <SidebarProvider className="h-full min-h-0">
        <Sidebar collapsible="icon">
          <SidebarHeader>
            <SidebarMenu>
              <SidebarMenuItem>
                <SidebarMenuButton size="lg" tooltip="Acme Inc">
                  <span className="flex size-8 shrink-0 items-center justify-center rounded-md bg-primary font-semibold text-primary-foreground text-xs">
                    A
                  </span>
                  <span className="flex flex-col leading-tight">
                    <span className="font-medium">Acme Inc</span>
                    <span className="text-muted-foreground text-xs">
                      Enterprise
                    </span>
                  </span>
                </SidebarMenuButton>
              </SidebarMenuItem>
            </SidebarMenu>
          </SidebarHeader>
          <SidebarContent>
            <SidebarGroup>
              <SidebarGroupLabel>Application</SidebarGroupLabel>
              <SidebarMenu>
                {items.map((item) => (
                  <SidebarMenuItem key={item.title}>
                    <SidebarMenuButton
                      href="#"
                      isActive={item.active}
                      tooltip={item.title}
                    >
                      <item.icon />
                      <span>{item.title}</span>
                    </SidebarMenuButton>
                    {item.badge && (
                      <SidebarMenuBadge>{item.badge}</SidebarMenuBadge>
                    )}
                  </SidebarMenuItem>
                ))}
              </SidebarMenu>
            </SidebarGroup>
          </SidebarContent>
          <SidebarFooter>
            <SidebarMenu>
              <SidebarMenuItem>
                <SidebarMenuButton size="lg" tooltip="Nischal">
                  <Avatar size="md" shape="square" fallback="NT" />
                  <span className="flex flex-col leading-tight">
                    <span className="font-medium">Nischal</span>
                    <span className="text-muted-foreground text-xs">
                      nischal@example.com
                    </span>
                  </span>
                </SidebarMenuButton>
              </SidebarMenuItem>
            </SidebarMenu>
          </SidebarFooter>
        </Sidebar>
        <SidebarInset>
          <header className="flex h-12 items-center gap-2 border-b px-3">
            <SidebarTrigger />
            <span className="font-medium text-sm">Home</span>
          </header>
          <div className="grid flex-1 grid-cols-3 gap-3 p-4">
            <div className="rounded-lg bg-muted" />
            <div className="rounded-lg bg-muted" />
            <div className="rounded-lg bg-muted" />
            <div className="col-span-3 rounded-lg bg-muted" />
          </div>
        </SidebarInset>
      </SidebarProvider>
    </div>
  );
}

Installation

$ pnpm dlx shadcn@latest add @desyne/sidebar

The CLI installs dependencies and any other components this one uses.

Usage

tsx

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

app/(app)/layout.tsxtsx

export default function AppLayout({ children }: { children: React.ReactNode }) {
  return (
    <SidebarProvider>
      <Sidebar collapsible="icon">
        <SidebarHeader>{/* workspace switcher */}</SidebarHeader>
        <SidebarContent>
          <SidebarGroup>
            <SidebarGroupLabel>Application</SidebarGroupLabel>
            <SidebarMenu>
              <SidebarMenuItem>
                <SidebarMenuButton href="/inbox" tooltip="Inbox">
                  <InboxIcon />
                  <span>Inbox</span>
                </SidebarMenuButton>
              </SidebarMenuItem>
            </SidebarMenu>
          </SidebarGroup>
        </SidebarContent>
        <SidebarFooter>{/* user menu */}</SidebarFooter>
      </Sidebar>
      <SidebarInset>
        <header>
          <SidebarTrigger />
        </header>
        {children}
      </SidebarInset>
    </SidebarProvider>
  );
}

SidebarProvider owns the open state and renders the layout wrapper (min-h-svh, full width, flex row). Sidebar reserves its width in that row and positions the panel fixed to the viewport, so the page content in SidebarInset never sits underneath it.

Rendering inside a box

The sidebar is fixed to the viewport by default. To keep it inside a bounded element (a preview, a modal, a dashboard widget), give an ancestor data-sidebar-contained and relative. The panel then uses absolute positioning and the ancestor's height. Every preview on this page does this, and sets className="h-full min-h-0" on SidebarProvider.

When to use

Sidebar — persistent primary navigation for an application with several top-level sections, especially when users switch between them often.
Tabs — a handful of sibling views within one page or object.
Sheet — temporary, secondary content that slides in over the page. On small screens the sidebar already uses a sheet for you.
Menu — a list of actions, or navigation that should stay hidden until requested. Use it inside the sidebar for workspace and account switchers.

Anatomy

tsx

<SidebarProvider>                  {/* state, shortcut, CSS variables, layout row */}
  <Sidebar>                        {/* panel: desktop column or mobile sheet */}
    <SidebarHeader />              {/* top: switcher, search */}
    <SidebarContent>               {/* scrolls */}
      <SidebarGroup>
        <SidebarGroupLabel />
        <SidebarMenu>
          <SidebarMenuItem>
            <SidebarMenuButton />  {/* link (href) or button */}
            <SidebarMenuBadge />   {/* optional count */}
          </SidebarMenuItem>
        </SidebarMenu>
      </SidebarGroup>
    </SidebarContent>
    <SidebarSeparator />
    <SidebarFooter />              {/* bottom: user menu, help */}
  </Sidebar>
  <SidebarInset>                   {/* main content */}
    <SidebarTrigger />
  </SidebarInset>
</SidebarProvider>

Part	Renders	Notes
`SidebarProvider`	`<div>`	Provides context, the ⌘B / Ctrl+B shortcut and the `--sidebar-width` variables. Wraps both the sidebar and the inset.
`Sidebar`	`<div>` (desktop), `Modal` › `Dialog` (mobile), `<div>` (`collapsible="none"`)	The panel. On desktop it renders a spacer (`sidebar-gap`) plus a fixed container (`sidebar-container` › `sidebar-inner`).
`SidebarTrigger`	`Button`	Ghost icon button that calls `toggleSidebar()`. Renders its children in place of the default icon.
`SidebarInset`	`<main>`	The page content next to the sidebar. Gets a margin, border and rounded corners when the sidebar uses `variant="inset"`.
`SidebarHeader` / `SidebarFooter`	`<div>`	Fixed regions above and below the content.
`SidebarContent`	`<div>`	Takes the remaining height and scrolls. Overflow is hidden in icon mode.
`SidebarGroup`	`<div>`	A section of the sidebar.
`SidebarGroupLabel`	`<div>`	Small uppercase heading. Fades out and collapses in icon mode.
`SidebarMenu`	`<ul>`	A list of menu items.
`SidebarMenuItem`	`<li>`	Positions a button and its badge.
`SidebarMenuButton`	`Link` (`<a>`) or `Button`	A link when `href` is set (with `aria-current="page"` when active), a button otherwise. Optional tooltip in icon mode.
`SidebarMenuBadge`	`<div>`	Count or status at the end of a menu item. Hidden in icon mode.
`SidebarSeparator`	`Separator`	Horizontal rule with the sidebar border color.

Examples

Variants

variant changes how the panel sits in the layout. sidebar (default) is a full-height column with a border. floating insets the panel with a margin, rounded corners and a shadow.

import {
  CalendarIcon,
  HomeIcon,
  InboxIcon,
  SettingsIcon,
  UsersIcon,
} from "lucide-react";
import {
  Sidebar,
  SidebarContent,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarInset,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
} from "@/components/ui/sidebar";

const items = [
  { title: "Home", icon: HomeIcon },
  { title: "Inbox", icon: InboxIcon },
  { title: "Calendar", icon: CalendarIcon },
  { title: "Team", icon: UsersIcon },
  { title: "Settings", icon: SettingsIcon },
];

export default function SidebarFloating() {
  return (
    <div
      data-sidebar-contained
      className="relative h-[400px] w-full overflow-hidden rounded-lg border bg-sidebar"
    >
      <SidebarProvider className="h-full min-h-0">
        <Sidebar variant="floating" collapsible="icon">
          <SidebarContent>
            <SidebarGroup>
              <SidebarGroupLabel>Workspace</SidebarGroupLabel>
              <SidebarMenu>
                {items.map((item, i) => (
                  <SidebarMenuItem key={item.title}>
                    <SidebarMenuButton
                      href="#"
                      isActive={i === 1}
                      tooltip={item.title}
                    >
                      <item.icon />
                      <span>{item.title}</span>
                    </SidebarMenuButton>
                  </SidebarMenuItem>
                ))}
              </SidebarMenu>
            </SidebarGroup>
          </SidebarContent>
        </Sidebar>
        <SidebarInset className="bg-transparent">
          <header className="flex h-12 items-center gap-2 px-3">
            <SidebarTrigger />
            <span className="font-medium text-sm">Inbox</span>
          </header>
          <div className="grid flex-1 gap-3 p-4 pt-0">
            <div className="rounded-lg border bg-background" />
          </div>
        </SidebarInset>
      </SidebarProvider>
    </div>
  );
}

inset puts the panel on the sidebar background and turns SidebarInset into a raised, rounded card. Use it for dashboards where the content should read as one surface.

import {
  BarChart3Icon,
  CreditCardIcon,
  HomeIcon,
  PackageIcon,
  UsersIcon,
} from "lucide-react";
import {
  Sidebar,
  SidebarContent,
  SidebarGroup,
  SidebarInset,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
} from "@/components/ui/sidebar";

const items = [
  { title: "Overview", icon: HomeIcon },
  { title: "Analytics", icon: BarChart3Icon },
  { title: "Customers", icon: UsersIcon },
  { title: "Products", icon: PackageIcon },
  { title: "Payouts", icon: CreditCardIcon },
];

export default function SidebarInsetDemo() {
  return (
    <div
      data-sidebar-contained
      className="relative h-[400px] w-full overflow-hidden rounded-lg border"
    >
      <SidebarProvider className="h-full min-h-0">
        <Sidebar variant="inset" collapsible="icon">
          <SidebarContent>
            <SidebarGroup>
              <SidebarMenu>
                {items.map((item, i) => (
                  <SidebarMenuItem key={item.title}>
                    <SidebarMenuButton
                      href="#"
                      isActive={i === 0}
                      tooltip={item.title}
                    >
                      <item.icon />
                      <span>{item.title}</span>
                    </SidebarMenuButton>
                  </SidebarMenuItem>
                ))}
              </SidebarMenu>
            </SidebarGroup>
          </SidebarContent>
        </Sidebar>
        <SidebarInset>
          <header className="flex h-12 items-center gap-2 px-3">
            <SidebarTrigger />
            <span className="font-medium text-sm">Overview</span>
          </header>
          <div className="grid flex-1 grid-cols-3 gap-3 p-4 pt-0">
            <div className="rounded-lg bg-muted" />
            <div className="rounded-lg bg-muted" />
            <div className="rounded-lg bg-muted" />
            <div className="col-span-3 rounded-lg bg-muted" />
          </div>
        </SidebarInset>
      </SidebarProvider>
    </div>
  );
}

It works on either side. With side="right", render SidebarInset before the Sidebar (as for any right sidebar); the card drops its margin on the side next to the panel.

import {
  CalendarIcon,
  MessageSquareIcon,
  PanelRightIcon,
  PaperclipIcon,
  UsersIcon,
} from "lucide-react";
import {
  Sidebar,
  SidebarContent,
  SidebarGroup,
  SidebarInset,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
} from "@/components/ui/sidebar";

const items = [
  { title: "Comments", icon: MessageSquareIcon },
  { title: "Attachments", icon: PaperclipIcon },
  { title: "People", icon: UsersIcon },
  { title: "Schedule", icon: CalendarIcon },
];

export default function SidebarInsetRight() {
  return (
    <div
      data-sidebar-contained
      className="relative h-[400px] w-full overflow-hidden rounded-lg border"
    >
      <SidebarProvider className="h-full min-h-0">
        <SidebarInset>
          <header className="flex h-12 items-center justify-between gap-2 px-3">
            <span className="font-medium text-sm">Launch plan</span>
            <SidebarTrigger aria-label="Toggle panel">
              <PanelRightIcon />
            </SidebarTrigger>
          </header>
          <div className="grid flex-1 grid-cols-2 gap-3 p-4 pt-0">
            <div className="rounded-lg bg-muted" />
            <div className="rounded-lg bg-muted" />
            <div className="col-span-2 rounded-lg bg-muted" />
          </div>
        </SidebarInset>
        <Sidebar side="right" variant="inset" collapsible="icon">
          <SidebarContent>
            <SidebarGroup>
              <SidebarMenu>
                {items.map((item, i) => (
                  <SidebarMenuItem key={item.title}>
                    <SidebarMenuButton
                      href="#"
                      isActive={i === 0}
                      tooltip={item.title}
                    >
                      <item.icon />
                      <span>{item.title}</span>
                    </SidebarMenuButton>
                  </SidebarMenuItem>
                ))}
              </SidebarMenu>
            </SidebarGroup>
          </SidebarContent>
        </Sidebar>
      </SidebarProvider>
    </div>
  );
}

Collapsible modes

collapsible controls what happens when the sidebar is closed on desktop: offcanvas (default) slides it out of view, icon shrinks it to a 3rem rail of icons, and none renders a static panel that can't collapse. Switch modes in the preview and press the trigger.

import { FileTextIcon, FolderIcon, HomeIcon, StarIcon } from "lucide-react";
import { useState } from "react";
import type { Key } from "react-aria-components";
import {
  Sidebar,
  SidebarContent,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarInset,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
} from "@/components/ui/sidebar";
import { ToggleButton } from "@/components/ui/toggle-button";
import { ToggleButtonGroup } from "@/components/ui/toggle-button-group";

type Mode = "offcanvas" | "icon" | "none";

const items = [
  { title: "Home", icon: HomeIcon },
  { title: "Starred", icon: StarIcon },
  { title: "Documents", icon: FileTextIcon },
  { title: "Shared folders", icon: FolderIcon },
];

export default function SidebarCollapsible() {
  const [mode, setMode] = useState<Mode>("icon");

  return (
    <div
      data-sidebar-contained
      className="relative h-[400px] w-full overflow-hidden rounded-lg border"
    >
      <SidebarProvider className="h-full min-h-0">
        <Sidebar
          collapsible={mode}
          className={mode === "none" ? "border-r" : undefined}
        >
          <SidebarContent>
            <SidebarGroup>
              <SidebarGroupLabel>Drive</SidebarGroupLabel>
              <SidebarMenu>
                {items.map((item, i) => (
                  <SidebarMenuItem key={item.title}>
                    <SidebarMenuButton
                      href="#"
                      isActive={i === 0}
                      tooltip={item.title}
                    >
                      <item.icon />
                      <span>{item.title}</span>
                    </SidebarMenuButton>
                  </SidebarMenuItem>
                ))}
              </SidebarMenu>
            </SidebarGroup>
          </SidebarContent>
        </Sidebar>
        <SidebarInset>
          <header className="flex h-12 items-center gap-2 border-b px-3">
            {mode !== "none" && <SidebarTrigger />}
            <ToggleButtonGroup
              aria-label="Collapsible mode"
              variant="segmented"
              size="xs"
              disallowEmptySelection
              selectedKeys={[mode]}
              onSelectionChange={(keys: Set<Key>) => {
                const [next] = keys;
                if (next) setMode(next as Mode);
              }}
            >
              <ToggleButton id="offcanvas">offcanvas</ToggleButton>
              <ToggleButton id="icon">icon</ToggleButton>
              <ToggleButton id="none">none</ToggleButton>
            </ToggleButtonGroup>
          </header>
          <div className="flex-1 p-4">
            <div className="h-full rounded-lg bg-muted" />
          </div>
        </SidebarInset>
      </SidebarProvider>
    </div>
  );
}

In icon mode, group labels and badges hide, menu buttons become 32px squares, and text in the last <span> of each button is clipped. Set tooltip on every SidebarMenuButton so collapsed items keep a visible label on hover and focus.

Right side

side="right" docks the panel on the right, for details and inspector panels. Render SidebarInset before the Sidebar so the space is reserved on the correct side. On mobile the sheet slides in from the right. Pass an icon as the trigger's children to point it the right way.

import {
  CalendarIcon,
  FlagIcon,
  PanelRightIcon,
  TagIcon,
  UserIcon,
} from "lucide-react";
import { Avatar } from "@/components/ui/avatar";
import { Badge } from "@/components/ui/badge";
import {
  Sidebar,
  SidebarContent,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarInset,
  SidebarProvider,
  SidebarSeparator,
  SidebarTrigger,
} from "@/components/ui/sidebar";

const fields = [
  {
    label: "Assignee",
    icon: UserIcon,
    value: (
      <span className="flex items-center gap-1.5">
        <Avatar size="xs" colorful fallback="MC" alt="Maya Chen" /> Maya Chen
      </span>
    ),
  },
  {
    label: "Priority",
    icon: FlagIcon,
    value: (
      <Badge variant="dot" color="danger">
        Urgent
      </Badge>
    ),
  },
  { label: "Due", icon: CalendarIcon, value: "Oct 14, 2026" },
  { label: "Labels", icon: TagIcon, value: <Badge size="sm">checkout</Badge> },
];

export default function SidebarRight() {
  return (
    <div
      data-sidebar-contained
      className="relative h-[400px] w-full overflow-hidden rounded-lg border"
    >
      <SidebarProvider className="h-full min-h-0">
        {/* On the right, render SidebarInset first so the space is reserved on the right. */}
        <SidebarInset>
          <header className="flex h-12 items-center justify-between gap-2 border-b px-4">
            <span className="font-medium text-sm">
              ENG-482 · Checkout retries
            </span>
            <SidebarTrigger aria-label="Toggle details">
              <PanelRightIcon />
            </SidebarTrigger>
          </header>
          <div className="grid content-start gap-3 p-4 text-muted-foreground text-sm">
            <p>
              Payments occasionally fail with a timeout from the card network.
              Retry idempotent requests up to three times with exponential
              backoff.
            </p>
            <div className="h-24 rounded-lg bg-muted" />
          </div>
        </SidebarInset>
        <Sidebar side="right">
          <SidebarHeader className="h-12 justify-center border-b px-4">
            <span className="font-medium text-sm">Details</span>
          </SidebarHeader>
          <SidebarContent>
            <SidebarGroup>
              <SidebarGroupLabel>Properties</SidebarGroupLabel>
              <dl className="grid gap-3 px-2 text-sm">
                {fields.map((f) => (
                  <div
                    key={f.label}
                    className="flex items-center justify-between gap-2"
                  >
                    <dt className="flex items-center gap-2 text-sidebar-foreground/70">
                      <f.icon className="size-4" /> {f.label}
                    </dt>
                    <dd>{f.value}</dd>
                  </div>
                ))}
              </dl>
            </SidebarGroup>
            <SidebarSeparator />
            <SidebarGroup>
              <SidebarGroupLabel>Activity</SidebarGroupLabel>
              <p className="px-2 text-sidebar-foreground/70 text-xs">
                Maya moved this to In progress · 2h ago
              </p>
            </SidebarGroup>
          </SidebarContent>
        </Sidebar>
      </SidebarProvider>
    </div>
  );
}

Split long navigation into SidebarGroups with a SidebarGroupLabel each. SidebarFooter stays pinned to the bottom while SidebarContent scrolls; a SidebarSeparator divides them.

import {
  BookOpenIcon,
  BotIcon,
  FrameIcon,
  LayoutDashboardIcon,
  LifeBuoyIcon,
  MapIcon,
  PieChartIcon,
  SendIcon,
  SquareTerminalIcon,
} from "lucide-react";
import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarInset,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarSeparator,
  SidebarTrigger,
} from "@/components/ui/sidebar";

const groups = [
  {
    label: "Platform",
    items: [
      { title: "Dashboard", icon: LayoutDashboardIcon },
      { title: "Playground", icon: SquareTerminalIcon },
      { title: "Models", icon: BotIcon },
      { title: "Documentation", icon: BookOpenIcon },
    ],
  },
  {
    label: "Projects",
    items: [
      { title: "Design Engineering", icon: FrameIcon },
      { title: "Sales & Marketing", icon: PieChartIcon },
      { title: "Travel", icon: MapIcon },
    ],
  },
];

export default function SidebarGroups() {
  return (
    <div
      data-sidebar-contained
      className="relative h-[460px] w-full overflow-hidden rounded-lg border"
    >
      <SidebarProvider className="h-full min-h-0">
        <Sidebar collapsible="icon">
          <SidebarContent>
            {groups.map((group, g) => (
              <SidebarGroup key={group.label}>
                <SidebarGroupLabel>{group.label}</SidebarGroupLabel>
                <SidebarMenu>
                  {group.items.map((item, i) => (
                    <SidebarMenuItem key={item.title}>
                      <SidebarMenuButton
                        href="#"
                        isActive={g === 0 && i === 0}
                        tooltip={item.title}
                      >
                        <item.icon />
                        <span>{item.title}</span>
                      </SidebarMenuButton>
                    </SidebarMenuItem>
                  ))}
                </SidebarMenu>
              </SidebarGroup>
            ))}
          </SidebarContent>
          <SidebarSeparator />
          <SidebarFooter>
            <SidebarMenu>
              <SidebarMenuItem>
                <SidebarMenuButton size="sm" href="#" tooltip="Support">
                  <LifeBuoyIcon />
                  <span>Support</span>
                </SidebarMenuButton>
              </SidebarMenuItem>
              <SidebarMenuItem>
                <SidebarMenuButton size="sm" href="#" tooltip="Feedback">
                  <SendIcon />
                  <span>Feedback</span>
                </SidebarMenuButton>
              </SidebarMenuItem>
            </SidebarMenu>
          </SidebarFooter>
        </Sidebar>
        <SidebarInset>
          <header className="flex h-12 items-center gap-2 border-b px-3">
            <SidebarTrigger />
            <span className="font-medium text-sm">Dashboard</span>
          </header>
          <div className="flex-1 p-4">
            <div className="h-full rounded-lg bg-muted" />
          </div>
        </SidebarInset>
      </SidebarProvider>
    </div>
  );
}

size="lg" (48px) for workspace and user switchers with two lines of text, default (32px) for primary navigation, and sm (28px) for dense or secondary lists.

import { FolderIcon, HashIcon } from "lucide-react";
import { Avatar } from "@/components/ui/avatar";
import {
  Sidebar,
  SidebarContent,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
} from "@/components/ui/sidebar";

export default function SidebarMenuSizes() {
  return (
    <div className="h-[360px] w-64 overflow-hidden rounded-lg border">
      <SidebarProvider className="h-full min-h-0">
        <Sidebar collapsible="none" className="w-full">
          <SidebarContent>
            <SidebarGroup>
              <SidebarGroupLabel>lg</SidebarGroupLabel>
              <SidebarMenu>
                <SidebarMenuItem>
                  <SidebarMenuButton size="lg">
                    <Avatar
                      size="md"
                      shape="square"
                      colorful
                      fallback="AC"
                      alt="Acme"
                    />
                    <span className="flex flex-col leading-tight">
                      <span className="font-medium">Acme Inc</span>
                      <span className="text-sidebar-foreground/60 text-xs">
                        Enterprise
                      </span>
                    </span>
                  </SidebarMenuButton>
                </SidebarMenuItem>
              </SidebarMenu>
            </SidebarGroup>
            <SidebarGroup>
              <SidebarGroupLabel>default</SidebarGroupLabel>
              <SidebarMenu>
                <SidebarMenuItem>
                  <SidebarMenuButton isActive>
                    <FolderIcon />
                    <span>Projects</span>
                  </SidebarMenuButton>
                </SidebarMenuItem>
              </SidebarMenu>
            </SidebarGroup>
            <SidebarGroup>
              <SidebarGroupLabel>sm</SidebarGroupLabel>
              <SidebarMenu>
                {["general", "design", "releases"].map((c) => (
                  <SidebarMenuItem key={c}>
                    <SidebarMenuButton size="sm">
                      <HashIcon />
                      <span>{c}</span>
                    </SidebarMenuButton>
                  </SidebarMenuItem>
                ))}
              </SidebarMenu>
            </SidebarGroup>
          </SidebarContent>
        </Sidebar>
      </SidebarProvider>
    </div>
  );
}

Collapsible submenus

Nest a SidebarMenu inside a React Aria Disclosure, and give the SidebarMenuButton slot="trigger" to toggle it. The button gets aria-expanded automatically. Animate the panel height with --disclosure-panel-height, as the Disclosure component does.

import {
  BookOpenIcon,
  ChevronRightIcon,
  LayoutDashboardIcon,
  SettingsIcon,
} from "lucide-react";
import { Disclosure, DisclosurePanel } from "react-aria-components";
import {
  Sidebar,
  SidebarContent,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarInset,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
} from "@/components/ui/sidebar";

const nav = [
  {
    title: "Dashboard",
    icon: LayoutDashboardIcon,
    items: ["Overview", "Reports", "Exports"],
  },
  {
    title: "Documentation",
    icon: BookOpenIcon,
    items: ["Introduction", "Get started", "Tutorials", "Changelog"],
  },
  {
    title: "Settings",
    icon: SettingsIcon,
    items: ["General", "Team", "Billing", "Limits"],
  },
];

export default function SidebarSubmenu() {
  return (
    <div
      data-sidebar-contained
      className="relative h-[460px] w-full overflow-hidden rounded-lg border"
    >
      <SidebarProvider className="h-full min-h-0">
        <Sidebar>
          <SidebarContent>
            <SidebarGroup>
              <SidebarGroupLabel>Platform</SidebarGroupLabel>
              <SidebarMenu>
                {nav.map((section, s) => (
                  <SidebarMenuItem key={section.title}>
                    <Disclosure
                      defaultExpanded={s === 1}
                      className="group/collapsible"
                    >
                      <SidebarMenuButton slot="trigger">
                        <section.icon />
                        <span>{section.title}</span>
                        <ChevronRightIcon className="ml-auto transition-transform duration-200 group-data-expanded/collapsible:rotate-90" />
                      </SidebarMenuButton>
                      <DisclosurePanel className="h-(--disclosure-panel-height) overflow-hidden transition-[height] duration-200 ease-out motion-reduce:transition-none">
                        <SidebarMenu className="mt-1 ml-3.5 gap-0.5 border-sidebar-border border-l pl-2.5">
                          {section.items.map((item, i) => (
                            <SidebarMenuItem key={item}>
                              <SidebarMenuButton
                                size="sm"
                                href="#"
                                isActive={s === 1 && i === 1}
                              >
                                <span>{item}</span>
                              </SidebarMenuButton>
                            </SidebarMenuItem>
                          ))}
                        </SidebarMenu>
                      </DisclosurePanel>
                    </Disclosure>
                  </SidebarMenuItem>
                ))}
              </SidebarMenu>
            </SidebarGroup>
          </SidebarContent>
        </Sidebar>
        <SidebarInset>
          <header className="flex h-12 items-center gap-2 border-b px-3">
            <SidebarTrigger />
            <span className="font-medium text-sm">Get started</span>
          </header>
          <div className="flex-1 p-4">
            <div className="h-full rounded-lg bg-muted" />
          </div>
        </SidebarInset>
      </SidebarProvider>
    </div>
  );
}

Active item and routing

Mark the current page with isActive; for links it also sets aria-current="page". Derive it from your router's current path, and wrap the app in React Aria's RouterProvider so menu links use client-side navigation. The preview uses a local stand-in for the router.

import {
  BarChart3Icon,
  CreditCardIcon,
  HomeIcon,
  PackageIcon,
  UsersIcon,
} from "lucide-react";
import { useState } from "react";
import { RouterProvider } from "react-aria-components";
import {
  Sidebar,
  SidebarContent,
  SidebarGroup,
  SidebarInset,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
} from "@/components/ui/sidebar";

const routes = [
  { href: "#overview", title: "Overview", icon: HomeIcon },
  { href: "#analytics", title: "Analytics", icon: BarChart3Icon },
  { href: "#customers", title: "Customers", icon: UsersIcon },
  { href: "#products", title: "Products", icon: PackageIcon },
  { href: "#payouts", title: "Payouts", icon: CreditCardIcon },
];

export default function SidebarRouter() {
  // Stand-in for your router. In Next.js use `usePathname()` and pass
  // `useRouter().push` to RouterProvider in your app's providers.
  const [pathname, setPathname] = useState("#overview");
  const current = routes.find((r) => r.href === pathname);

  return (
    <RouterProvider navigate={setPathname}>
      <div
        data-sidebar-contained
        className="relative h-[400px] w-full overflow-hidden rounded-lg border"
      >
        <SidebarProvider className="h-full min-h-0">
          <Sidebar collapsible="icon">
            <SidebarContent>
              <SidebarGroup>
                <SidebarMenu>
                  {routes.map((r) => (
                    <SidebarMenuItem key={r.href}>
                      <SidebarMenuButton
                        href={r.href}
                        isActive={pathname === r.href}
                        tooltip={r.title}
                      >
                        <r.icon />
                        <span>{r.title}</span>
                      </SidebarMenuButton>
                    </SidebarMenuItem>
                  ))}
                </SidebarMenu>
              </SidebarGroup>
            </SidebarContent>
          </Sidebar>
          <SidebarInset>
            <header className="flex h-12 items-center gap-2 border-b px-3">
              <SidebarTrigger />
              <span className="font-medium text-sm">{current?.title}</span>
            </header>
            <div className="flex-1 p-4 text-muted-foreground text-sm">
              Rendered for <code className="text-foreground">{pathname}</code>.
            </div>
          </SidebarInset>
        </SidebarProvider>
      </div>
    </RouterProvider>
  );
}

With the Next.js App Router:

app/providers.tsxtsx

"use client";

import { useRouter } from "next/navigation";
import { RouterProvider } from "react-aria-components";

export function Providers({ children }: { children: React.ReactNode }) {
  const router = useRouter();
  return <RouterProvider navigate={router.push}>{children}</RouterProvider>;
}

components/nav-main.tsxtsx

"use client";

import { usePathname } from "next/navigation";

export function NavMain({ items }: { items: { href: string; title: string; icon: React.ElementType }[] }) {
  const pathname = usePathname();
  return (
    <SidebarMenu>
      {items.map((item) => (
        <SidebarMenuItem key={item.href}>
          <SidebarMenuButton href={item.href} isActive={pathname === item.href} tooltip={item.title}>
            <item.icon />
            <span>{item.title}</span>
          </SidebarMenuButton>
        </SidebarMenuItem>
      ))}
    </SidebarMenu>
  );
}

Controlled

Pass open and onOpenChange to SidebarProvider to own the desktop state, for example to persist it in a cookie or user setting. On desktop, the trigger, the keyboard shortcut and anything calling setOpen all go through onOpenChange. The mobile sheet keeps its own state.

import { FileTextIcon, HomeIcon, InboxIcon } from "lucide-react";
import { useState } from "react";
import {
  Sidebar,
  SidebarContent,
  SidebarGroup,
  SidebarInset,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
} from "@/components/ui/sidebar";
import { Switch } from "@/components/ui/switch";

const items = [
  { title: "Home", icon: HomeIcon },
  { title: "Inbox", icon: InboxIcon },
  { title: "Drafts", icon: FileTextIcon },
];

export default function SidebarControlled() {
  const [open, setOpen] = useState(true);

  return (
    <div
      data-sidebar-contained
      className="relative h-[360px] w-full overflow-hidden rounded-lg border"
    >
      <SidebarProvider
        open={open}
        onOpenChange={setOpen}
        className="h-full min-h-0"
      >
        <Sidebar collapsible="icon">
          <SidebarContent>
            <SidebarGroup>
              <SidebarMenu>
                {items.map((item, i) => (
                  <SidebarMenuItem key={item.title}>
                    <SidebarMenuButton isActive={i === 0} tooltip={item.title}>
                      <item.icon />
                      <span>{item.title}</span>
                    </SidebarMenuButton>
                  </SidebarMenuItem>
                ))}
              </SidebarMenu>
            </SidebarGroup>
          </SidebarContent>
        </Sidebar>
        <SidebarInset>
          <header className="flex h-12 items-center justify-between gap-2 border-b px-3">
            <SidebarTrigger />
            <Switch size="sm" isSelected={open} onChange={setOpen}>
              Show sidebar
            </Switch>
          </header>
          <div className="flex-1 p-4 text-muted-foreground text-sm">
            The sidebar is {open ? "expanded" : "collapsed"}.
          </div>
        </SidebarInset>
      </SidebarProvider>
    </div>
  );
}

tsx

// Persist the state between visits.
const [open, setOpen] = useState(defaultOpenFromCookie);

<SidebarProvider
  open={open}
  onOpenChange={(value) => {
    setOpen(value);
    document.cookie = `sidebar_state=${value}; path=/; max-age=31536000`;
  }}
/>;

useSidebar

Any component inside SidebarProvider can read and change the state with useSidebar(). Use it for custom triggers, or to adapt content to the collapsed state. It throws if called outside a provider.

import {
  HomeIcon,
  InboxIcon,
  PanelLeftCloseIcon,
  PanelLeftOpenIcon,
  SettingsIcon,
} from "lucide-react";
import { Button } from "@/components/ui/button";
import { Kbd, KbdGroup } from "@/components/ui/kbd";
import {
  Sidebar,
  SidebarContent,
  SidebarGroup,
  SidebarInset,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  useSidebar,
} from "@/components/ui/sidebar";

// Any component inside SidebarProvider can read and change the sidebar state.
function SidebarToggle() {
  const { state, toggleSidebar } = useSidebar();
  const expanded = state === "expanded";
  return (
    <Button variant="outline" size="sm" onPress={toggleSidebar}>
      {expanded ? <PanelLeftCloseIcon /> : <PanelLeftOpenIcon />}
      {expanded ? "Hide sidebar" : "Show sidebar"}
      <KbdGroup>
        <Kbd size="sm">⌘</Kbd>
        <Kbd size="sm">B</Kbd>
      </KbdGroup>
    </Button>
  );
}

const items = [
  { title: "Home", icon: HomeIcon },
  { title: "Inbox", icon: InboxIcon },
  { title: "Settings", icon: SettingsIcon },
];

export default function SidebarUseSidebar() {
  return (
    <div
      data-sidebar-contained
      className="relative h-[360px] w-full overflow-hidden rounded-lg border"
    >
      <SidebarProvider className="h-full min-h-0">
        <Sidebar>
          <SidebarContent>
            <SidebarGroup>
              <SidebarMenu>
                {items.map((item, i) => (
                  <SidebarMenuItem key={item.title}>
                    <SidebarMenuButton isActive={i === 0}>
                      <item.icon />
                      <span>{item.title}</span>
                    </SidebarMenuButton>
                  </SidebarMenuItem>
                ))}
              </SidebarMenu>
            </SidebarGroup>
          </SidebarContent>
        </Sidebar>
        <SidebarInset>
          <header className="flex h-12 items-center gap-2 border-b px-3">
            <SidebarToggle />
          </header>
          <div className="flex-1 p-4">
            <div className="h-full rounded-lg bg-muted" />
          </div>
        </SidebarInset>
      </SidebarProvider>
    </div>
  );
}

collapsible="none" renders a plain, always-visible <div> with no container, spacer or mobile sheet. Use it for secondary navigation inside a page, such as settings.

It stays inline on every screen size, as in shadcn/ui: below 768px it doesn't become a sheet or hide, and SidebarTrigger and the shortcut don't affect it. It's a normal flex item, so it never overlays the page, but in a row it shrinks with the layout; on narrow screens you may want to stack it above the content or swap it for a Select or Tabs.

import {
  BellIcon,
  CreditCardIcon,
  KeyRoundIcon,
  PaletteIcon,
  ShieldIcon,
  UserIcon,
} from "lucide-react";
import {
  Sidebar,
  SidebarContent,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
} from "@/components/ui/sidebar";

const groups = [
  {
    label: "Account",
    items: [
      { title: "Profile", icon: UserIcon },
      { title: "Appearance", icon: PaletteIcon },
      { title: "Notifications", icon: BellIcon },
    ],
  },
  {
    label: "Workspace",
    items: [
      { title: "Security", icon: ShieldIcon },
      { title: "API keys", icon: KeyRoundIcon },
      { title: "Billing", icon: CreditCardIcon },
    ],
  },
];

export default function SidebarNone() {
  return (
    <div className="flex h-[380px] w-full overflow-hidden rounded-lg border">
      <SidebarProvider className="h-full min-h-0">
        <Sidebar collapsible="none" className="w-52 border-r">
          <SidebarContent>
            {groups.map((group) => (
              <SidebarGroup key={group.label}>
                <SidebarGroupLabel>{group.label}</SidebarGroupLabel>
                <SidebarMenu>
                  {group.items.map((item) => (
                    <SidebarMenuItem key={item.title}>
                      <SidebarMenuButton
                        href="#"
                        isActive={item.title === "Appearance"}
                      >
                        <item.icon />
                        <span>{item.title}</span>
                      </SidebarMenuButton>
                    </SidebarMenuItem>
                  ))}
                </SidebarMenu>
              </SidebarGroup>
            ))}
          </SidebarContent>
        </Sidebar>
        <main className="grid flex-1 content-start gap-1 p-6">
          <h2 className="font-semibold text-lg">Appearance</h2>
          <p className="text-muted-foreground text-sm">
            Choose a theme and density for your workspace.
          </p>
        </main>
      </SidebarProvider>
    </div>
  );
}

Mobile

Below 768px (max-width: 767px) the desktop panel is hidden, and Sidebar renders as a modal sheet from its side instead. The trigger and the shortcut toggle the sheet (openMobile), which is separate from the desktop open state, so collapsing on desktop doesn't affect mobile. The sheet has a backdrop, traps focus, and closes on Esc or an outside click.

Pressing a link inside the sheet closes it, with the mouse, touch or Enter. This covers any <a href> in the sheet, whether it's a SidebarMenuButton link or a link in your own markup. Clicks that open a new tab or window (with a modifier key, target="_blank" or download) leave it open, and so do button items. Pass closeOnNavigate={false} to keep the sheet open, or call setOpenMobile(false) from useSidebar() to close it after a button press.

className and style on Sidebar also apply to the sheet. Use max-md: classes to style only the sheet, and md: classes to style only the desktop panel.

import { HomeIcon, InboxIcon, SettingsIcon, UsersIcon } from "lucide-react";
import { useState } from "react";
import { RouterProvider } from "react-aria-components";
import {
  Sidebar,
  SidebarContent,
  SidebarGroup,
  SidebarInset,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
} from "@/components/ui/sidebar";

const items = [
  { href: "/home", title: "Home", icon: HomeIcon },
  { href: "/inbox", title: "Inbox", icon: InboxIcon },
  { href: "/team", title: "Team", icon: UsersIcon },
  { href: "/settings", title: "Settings", icon: SettingsIcon },
];

export default function SidebarMobile() {
  // Stand-in for your router. In Next.js use `useRouter().push` and `usePathname()`.
  const [pathname, setPathname] = useState("/home");
  const page = items.find((item) => item.href === pathname);

  return (
    <RouterProvider navigate={setPathname}>
      <div
        data-sidebar-contained
        className="relative h-[360px] w-full overflow-hidden rounded-lg border"
      >
        <SidebarProvider className="h-full min-h-0">
          {/* max-md: classes only reach the mobile sheet. */}
          <Sidebar className="max-md:w-72">
            <SidebarContent>
              <SidebarGroup>
                <SidebarMenu>
                  {items.map((item) => (
                    <SidebarMenuItem key={item.href}>
                      <SidebarMenuButton
                        href={item.href}
                        isActive={item.href === pathname}
                      >
                        <item.icon />
                        <span>{item.title}</span>
                      </SidebarMenuButton>
                    </SidebarMenuItem>
                  ))}
                </SidebarMenu>
              </SidebarGroup>
            </SidebarContent>
          </Sidebar>
          <SidebarInset>
            <header className="flex h-12 items-center gap-2 border-b px-3">
              <SidebarTrigger />
              <span className="font-medium text-sm">{page?.title}</span>
            </header>
            <p className="p-4 text-muted-foreground text-sm">
              On a phone, open the sheet and pick a page: it closes as the route
              changes.
            </p>
          </SidebarInset>
        </SidebarProvider>
      </div>
    </RouterProvider>
  );
}

The breakpoint is based on the viewport width (via useIsMobile()), not the container, so contained previews on a wide screen always show the desktop sidebar. Resize the browser window to see the sheet.

Recipes

App shell

An inset sidebar with icon collapsing: a workspace switcher Menu in the header, primary navigation with a badge, a projects group, and an account menu in the footer. The content area has a trigger and Breadcrumbs.

import {
  ChevronsUpDownIcon,
  FolderKanbanIcon,
  HomeIcon,
  InboxIcon,
  LogOutIcon,
  PlusIcon,
  SettingsIcon,
  UserIcon,
  UsersIcon,
} from "lucide-react";
import { Avatar } from "@/components/ui/avatar";
import { Breadcrumb, Breadcrumbs } from "@/components/ui/breadcrumbs";
import {
  MenuContent,
  MenuItem,
  MenuSection,
  MenuSeparator,
  MenuTrigger,
} from "@/components/ui/menu";
import { Separator } from "@/components/ui/separator";
import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarInset,
  SidebarMenu,
  SidebarMenuBadge,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
} from "@/components/ui/sidebar";

const main = [
  { title: "Home", icon: HomeIcon },
  { title: "Inbox", icon: InboxIcon, badge: "4" },
  { title: "Projects", icon: FolderKanbanIcon, active: true },
  { title: "Members", icon: UsersIcon },
];

const projects = [
  { title: "Checkout v2", color: "bg-emerald-500" },
  { title: "Mobile app", color: "bg-sky-500" },
  { title: "Brand refresh", color: "bg-amber-500" },
];

export default function SidebarRecipeAppShell() {
  return (
    <div
      data-sidebar-contained
      className="relative h-[520px] w-full overflow-hidden rounded-lg border"
    >
      <SidebarProvider className="h-full min-h-0">
        <Sidebar variant="inset" collapsible="icon">
          <SidebarHeader>
            <SidebarMenu>
              <SidebarMenuItem>
                <MenuTrigger>
                  <SidebarMenuButton size="lg" tooltip="Acme Inc">
                    <Avatar
                      size="md"
                      shape="square"
                      colorful
                      fallback="A"
                      alt="Acme Inc"
                    />
                    <span className="flex flex-1 flex-col leading-tight">
                      <span className="font-medium">Acme Inc</span>
                      <span className="text-sidebar-foreground/60 text-xs">
                        Pro plan
                      </span>
                    </span>
                    <ChevronsUpDownIcon className="ml-auto" />
                  </SidebarMenuButton>
                  <MenuContent
                    placement="bottom start"
                    popoverClassName="min-w-56"
                  >
                    <MenuSection title="Workspaces">
                      <MenuItem>Acme Inc</MenuItem>
                      <MenuItem>Globex Labs</MenuItem>
                    </MenuSection>
                    <MenuSeparator />
                    <MenuItem>
                      <PlusIcon /> Create workspace
                    </MenuItem>
                  </MenuContent>
                </MenuTrigger>
              </SidebarMenuItem>
            </SidebarMenu>
          </SidebarHeader>
          <SidebarContent>
            <SidebarGroup>
              <SidebarMenu>
                {main.map((item) => (
                  <SidebarMenuItem key={item.title}>
                    <SidebarMenuButton
                      href="#"
                      isActive={item.active}
                      tooltip={item.title}
                    >
                      <item.icon />
                      <span>{item.title}</span>
                    </SidebarMenuButton>
                    {item.badge && (
                      <SidebarMenuBadge>{item.badge}</SidebarMenuBadge>
                    )}
                  </SidebarMenuItem>
                ))}
              </SidebarMenu>
            </SidebarGroup>
            <SidebarGroup>
              <SidebarGroupLabel>Projects</SidebarGroupLabel>
              <SidebarMenu>
                {projects.map((p) => (
                  <SidebarMenuItem key={p.title}>
                    <SidebarMenuButton href="#" tooltip={p.title}>
                      <span className="flex size-4 shrink-0 items-center justify-center">
                        <span className={`size-2 rounded-full ${p.color}`} />
                      </span>
                      <span>{p.title}</span>
                    </SidebarMenuButton>
                  </SidebarMenuItem>
                ))}
              </SidebarMenu>
            </SidebarGroup>
          </SidebarContent>
          <SidebarFooter>
            <SidebarMenu>
              <SidebarMenuItem>
                <MenuTrigger>
                  <SidebarMenuButton size="lg" tooltip="Maya Chen">
                    <Avatar size="md" colorful fallback="MC" alt="Maya Chen" />
                    <span className="flex flex-1 flex-col leading-tight">
                      <span className="font-medium">Maya Chen</span>
                      <span className="text-sidebar-foreground/60 text-xs">
                        maya@acme.dev
                      </span>
                    </span>
                    <ChevronsUpDownIcon className="ml-auto" />
                  </SidebarMenuButton>
                  <MenuContent
                    placement="top start"
                    popoverClassName="min-w-56"
                  >
                    <MenuItem>
                      <UserIcon /> Account
                    </MenuItem>
                    <MenuItem>
                      <SettingsIcon /> Settings
                    </MenuItem>
                    <MenuSeparator />
                    <MenuItem>
                      <LogOutIcon /> Log out
                    </MenuItem>
                  </MenuContent>
                </MenuTrigger>
              </SidebarMenuItem>
            </SidebarMenu>
          </SidebarFooter>
        </Sidebar>
        <SidebarInset>
          <header className="flex h-12 shrink-0 items-center gap-2 px-3">
            <SidebarTrigger />
            <Separator
              orientation="vertical"
              className="mx-1 h-4 self-center"
            />
            <Breadcrumbs size="sm">
              <Breadcrumb href="#">Projects</Breadcrumb>
              <Breadcrumb>Checkout v2</Breadcrumb>
            </Breadcrumbs>
          </header>
          <div className="grid flex-1 auto-rows-min gap-3 p-4 pt-0 sm:grid-cols-3">
            <div className="aspect-video rounded-lg bg-muted" />
            <div className="aspect-video rounded-lg bg-muted" />
            <div className="aspect-video rounded-lg bg-muted" />
            <div className="h-40 rounded-lg bg-muted sm:col-span-3" />
          </div>
        </SidebarInset>
      </SidebarProvider>
    </div>
  );
}

Mail

Folders and labels with unread counts in SidebarMenuBadge. The Compose button reads useSidebar() to collapse to an icon and show its tooltip only in icon mode, matching the menu buttons.

import {
  ArchiveIcon,
  FileIcon,
  InboxIcon,
  PencilIcon,
  SendIcon,
  StarIcon,
  Trash2Icon,
} from "lucide-react";
import { Button } from "@/components/ui/button";
import {
  Sidebar,
  SidebarContent,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarInset,
  SidebarMenu,
  SidebarMenuBadge,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
  useSidebar,
} from "@/components/ui/sidebar";
import { Tooltip, TooltipTrigger } from "@/components/ui/tooltip";

// Shows its tooltip only when the sidebar is collapsed to icons, like SidebarMenuButton.
function ComposeButton() {
  const { state, isMobile } = useSidebar();
  return (
    <TooltipTrigger isDisabled={state !== "collapsed" || isMobile}>
      <Button
        aria-label="Compose"
        className="w-full group-data-[collapsible=icon]:size-8 group-data-[collapsible=icon]:p-0"
      >
        <PencilIcon />
        <span className="group-data-[collapsible=icon]:hidden">Compose</span>
      </Button>
      <Tooltip placement="right">Compose</Tooltip>
    </TooltipTrigger>
  );
}

const folders = [
  { title: "Inbox", icon: InboxIcon, count: 128 },
  { title: "Starred", icon: StarIcon },
  { title: "Drafts", icon: FileIcon, count: 9 },
  { title: "Sent", icon: SendIcon },
  { title: "Archive", icon: ArchiveIcon },
  { title: "Trash", icon: Trash2Icon },
];

const labels = [
  { title: "Customers", color: "bg-sky-500", count: 12 },
  { title: "Invoices", color: "bg-emerald-500" },
  { title: "Hiring", color: "bg-violet-500", count: 3 },
];

const messages = [
  {
    from: "Stripe",
    subject: "Your payout of $4,120.00 is on the way",
    time: "9:41",
  },
  {
    from: "Lena Park",
    subject: "Re: Offer letter for the design role",
    time: "8:15",
  },
  {
    from: "Linear",
    subject: "3 issues were assigned to you",
    time: "Yesterday",
  },
];

export default function SidebarRecipeMail() {
  return (
    <div
      data-sidebar-contained
      className="relative h-[480px] w-full overflow-hidden rounded-lg border"
    >
      <SidebarProvider className="h-full min-h-0">
        <Sidebar collapsible="icon">
          <SidebarHeader>
            <ComposeButton />
          </SidebarHeader>
          <SidebarContent>
            <SidebarGroup>
              <SidebarMenu>
                {folders.map((f, i) => (
                  <SidebarMenuItem key={f.title}>
                    <SidebarMenuButton
                      href="#"
                      isActive={i === 0}
                      tooltip={f.title}
                    >
                      <f.icon />
                      <span>{f.title}</span>
                    </SidebarMenuButton>
                    {f.count && <SidebarMenuBadge>{f.count}</SidebarMenuBadge>}
                  </SidebarMenuItem>
                ))}
              </SidebarMenu>
            </SidebarGroup>
            <SidebarGroup>
              <SidebarGroupLabel>Labels</SidebarGroupLabel>
              <SidebarMenu>
                {labels.map((l) => (
                  <SidebarMenuItem key={l.title}>
                    <SidebarMenuButton href="#" tooltip={l.title}>
                      <span className="flex size-4 shrink-0 items-center justify-center">
                        <span className={`size-2 rounded-full ${l.color}`} />
                      </span>
                      <span>{l.title}</span>
                    </SidebarMenuButton>
                    {l.count && <SidebarMenuBadge>{l.count}</SidebarMenuBadge>}
                  </SidebarMenuItem>
                ))}
              </SidebarMenu>
            </SidebarGroup>
          </SidebarContent>
        </Sidebar>
        <SidebarInset>
          <header className="flex h-12 shrink-0 items-center gap-2 border-b px-3">
            <SidebarTrigger />
            <span className="font-medium text-sm">Inbox</span>
          </header>
          <ul className="divide-y overflow-auto">
            {messages.map((m) => (
              <li key={m.subject} className="grid gap-0.5 px-4 py-3 text-sm">
                <div className="flex items-center justify-between gap-2">
                  <span className="font-medium">{m.from}</span>
                  <span className="text-muted-foreground text-xs">
                    {m.time}
                  </span>
                </div>
                <span className="truncate text-muted-foreground">
                  {m.subject}
                </span>
              </li>
            ))}
          </ul>
        </SidebarInset>
      </SidebarProvider>
    </div>
  );
}

Documentation

A documentation layout: title and SearchField in the header, small link items grouped by section, and a scrolling content area.

import { BookOpenIcon } from "lucide-react";
import { SearchField } from "@/components/ui/search-field";
import {
  Sidebar,
  SidebarContent,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarInset,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
} from "@/components/ui/sidebar";

const sections = [
  {
    label: "Getting started",
    pages: ["Introduction", "Installation", "Theming", "Dark mode"],
  },
  {
    label: "Components",
    pages: ["Button", "Dialog", "Select", "Sidebar", "Tabs", "Tooltip"],
  },
  { label: "Guides", pages: ["Forms", "Routing", "Server components"] },
];

export default function SidebarRecipeDocs() {
  return (
    <div
      data-sidebar-contained
      className="relative h-[480px] w-full overflow-hidden rounded-lg border"
    >
      <SidebarProvider className="h-full min-h-0">
        <Sidebar>
          <SidebarHeader className="gap-3">
            <div className="flex items-center gap-2 px-2 pt-1 font-semibold text-sm">
              <BookOpenIcon className="size-4" /> Acme Docs
            </div>
            <SearchField aria-label="Search docs" size="sm" shortcut="⌘K" />
          </SidebarHeader>
          <SidebarContent>
            {sections.map((section) => (
              <SidebarGroup key={section.label} className="py-1">
                <SidebarGroupLabel>{section.label}</SidebarGroupLabel>
                <SidebarMenu className="gap-0.5">
                  {section.pages.map((page) => (
                    <SidebarMenuItem key={page}>
                      <SidebarMenuButton
                        size="sm"
                        href="#"
                        isActive={page === "Sidebar"}
                      >
                        <span>{page}</span>
                      </SidebarMenuButton>
                    </SidebarMenuItem>
                  ))}
                </SidebarMenu>
              </SidebarGroup>
            ))}
          </SidebarContent>
        </Sidebar>
        <SidebarInset>
          <header className="flex h-12 shrink-0 items-center gap-2 border-b px-3">
            <SidebarTrigger />
            <span className="text-muted-foreground text-sm">Components</span>
          </header>
          <article className="grid content-start gap-2 p-6">
            <h2 className="font-semibold text-xl tracking-tight">Sidebar</h2>
            <p className="max-w-prose text-muted-foreground text-sm">
              A collapsible app sidebar. The navigation scrolls on its own while
              the header with search stays in place.
            </p>
          </article>
        </SidebarInset>
      </SidebarProvider>
    </div>
  );
}

Accessibility

SidebarMenuButton renders a real link when given href, with aria-current="page" when isActive, so middle-click, "open in new tab" and screen-reader link lists work. Without href it's a button.
Wrap navigation in landmarks as your layout needs; SidebarInset renders the page's <main>.
In icon mode, give every SidebarMenuButton a tooltip. The text stays in the DOM and keeps naming the item for assistive tech; the tooltip gives sighted users the same label.
Tooltips only show when the sidebar is collapsed to icons on desktop; they're disabled when expanded and on mobile.
SidebarTrigger has aria-label="Toggle sidebar". Pass your own aria-label to change it.
On mobile the sidebar is a modal Dialog labelled "Sidebar": focus moves into it, is trapped while open and returns to the trigger on close.
The ⌘B / Ctrl+B shortcut is registered on window by each SidebarProvider and calls preventDefault(), so it replaces any browser or editor shortcut on the same keys while the page is focused. Advertise it with a Kbd hint.

Keyboard

Key	Action
`⌘`+`B` / `Ctrl`+`B`	Toggles the sidebar (the sheet on mobile)
`Tab` / `Shift`+`Tab`	Moves between menu items and other controls
`Enter`	Follows a link item, or presses a button item
`Space`	Presses a button item (or a submenu trigger)
`Esc`	Closes the mobile sheet

Styling

Data attributes

On the desktop Sidebar root (data-slot="sidebar", which also has the group and peer classes):

Attribute	Values
`data-state`	`expanded` or `collapsed`
`data-collapsible`	The `collapsible` mode while collapsed (`offcanvas` or `icon`); empty while expanded
`data-variant`	`sidebar`, `floating` or `inset`
`data-side`	`left` or `right`

Style anything inside the sidebar by state with group-data-*, for example group-data-[collapsible=icon]:hidden to hide an element in icon mode. Style siblings after it with peer-data-*. SidebarInset styles itself for the inset variant from the wrapper (group-has-* on sidebar-wrapper), so it works whether it comes before or after the Sidebar. The mobile sheet instead has data-slot="sidebar", data-mobile="true" and data-side.

On SidebarMenuButton:

Attribute	Present when
`data-active`	`"true"` when `isActive`, `"false"` otherwise
`data-hovered` / `data-pressed`	Hovered / being pressed
`data-focused` / `data-focus-visible`	Focused / focused with the keyboard
`data-disabled`	`isDisabled` is true
`data-current`	Link items with `isActive` (from `aria-current`)

Slots

`data-slot`	Element
`sidebar-wrapper`	`SidebarProvider` root
`sidebar`	`Sidebar` root
`sidebar-gap`	Spacer that reserves the sidebar's width on desktop
`sidebar-container`	The fixed (or contained absolute) panel on desktop
`sidebar-inner`	The panel's background surface
`sidebar-trigger`	`SidebarTrigger`
`sidebar-inset`	`SidebarInset`
`sidebar-header`, `sidebar-content`, `sidebar-footer`	Regions
`sidebar-group`, `sidebar-group-label`	Groups
`sidebar-menu`, `sidebar-menu-item`, `sidebar-menu-button`, `sidebar-menu-badge`	Menu parts
`sidebar-separator`	`SidebarSeparator`

CSS variables

Variable	Default	Used for
`--sidebar-width`	`16rem`	Expanded width, desktop and mobile
`--sidebar-width-icon`	`3rem`	Width in icon mode

Set them on SidebarProvider with style:

tsx

<SidebarProvider
  style={{ "--sidebar-width": "18rem", "--sidebar-width-icon": "3.5rem" } as React.CSSProperties}
/>

The colors come from theme tokens: --sidebar (background), --sidebar-foreground, --sidebar-border, --sidebar-accent and --sidebar-accent-foreground (active item), --sidebar-primary (active item icon) and --sidebar-ring. See Theming.

Customizing

On desktop, className and other props on Sidebar go to sidebar-container, the fixed panel. With collapsible="none" they go to the root <div>. On mobile, className and style go to the sheet (the Modal); other <div> props aren't applied there.
SidebarMenuButton truncates its last <span>, so wrap labels in a <span> and put icons first.
SidebarMenuBadge is absolutely positioned for the default button height. Add padding to the button (pr-8) if long labels could run under it.

`sidebarMenuButtonVariants`

The tailwind-variants function behind SidebarMenuButton. Use it to give other elements, such as a Next.js Link, the look of a menu item.

tsx

import { sidebarMenuButtonVariants } from "@/components/ui/sidebar";

sidebarMenuButtonVariants({ size: "sm" });

API Reference

SidebarProvider

Prop

Type

Also accepts every prop of <div>.

Prop

Type

Also accepts every prop of <div>.

SidebarMenuButton

Prop

Type

Also accepts every prop of React Aria's Link (with href) or Button (without).

SidebarTrigger

A ghost, icon-sm Button with a panel icon. Pass children to replace the icon, for example <PanelRightIcon /> for a right sidebar, or text with size="sm". It keeps aria-label="Toggle sidebar" unless you pass your own, so with visible text pass a matching aria-label (or aria-label={undefined}). Accepts every button prop; onPress runs before the sidebar toggles.

Type

useIsMobile

useIsMobile(): boolean — true when (max-width: 767px) matches. Subscribes to the media query, and returns false during server rendering.

Sheet — the modal panel the sidebar becomes on mobile.
Menu — workspace and account switchers.
Tooltip — labels for icon-only items.
Breadcrumbs — show the current location in the content header.
Tabs — navigation between views within a page.