Sidebar

Structure

Wrap the page in SidebarProvider, render a Sidebar beside a SidebarInset for the main content, and put a SidebarTrigger anywhere inside the provider. This page documents the API with code only – the sidebar takes over the full viewport, so see the showcase for a live demo.

<SidebarProvider>
  <Sidebar>
    <SidebarHeader />
    <SidebarContent>
      <SidebarGroup>
        <SidebarGroupLabel>Platform</SidebarGroupLabel>
        <SidebarGroupContent>
          <SidebarMenu>
            <SidebarMenuItem>
              <SidebarMenuButton>
                <Home />
                <span>Dashboard</span>
              </SidebarMenuButton>
            </SidebarMenuItem>
          </SidebarMenu>
        </SidebarGroupContent>
      </SidebarGroup>
    </SidebarContent>
    <SidebarFooter />
    <SidebarRail />
  </Sidebar>
  <SidebarInset>
    <header className="flex h-14 items-center border-b px-4">
      <SidebarTrigger />
    </header>
    <div className="p-6">Page content</div>
  </SidebarInset>
</SidebarProvider>

Installation

npx shadcn@latest add https://espresso-base-ui.vercel.app/r/sidebar.json

Usage

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

The provider usually lives in a layout so the sidebar persists across routes. It reads and writes a sidebar_state cookie (7-day max-age), so you can restore the last state on the server:

// app/layout.tsx
import { cookies } from "next/headers"

export default async function Layout({ children }) {
  const cookieStore = await cookies()
  const defaultOpen = cookieStore.get("sidebar_state")?.value === "true"

  return (
    <SidebarProvider defaultOpen={defaultOpen}>
      <AppSidebar />
      <SidebarInset>{children}</SidebarInset>
    </SidebarProvider>
  )
}

Collapsible modes

collapsible controls what happens when the sidebar closes: offcanvas (default) slides it fully out of view, icon shrinks it to a 3rem icon rail – menu buttons show their tooltip and labels, badges and submenus hide – and none renders a fixed, non-collapsing column.

<Sidebar collapsible="offcanvas" />  // slides out of view (default)
<Sidebar collapsible="icon" />       // collapses to a 3rem icon rail
<Sidebar collapsible="none" />       // always expanded

side and variant combine with any mode: floating wraps the content in a padded, rounded, ring-bordered card and inset pairs with SidebarInset to render the main content as a raised, rounded panel.

<Sidebar side="right" variant="floating" collapsible="icon">
  ...
</Sidebar>

Menus

SidebarMenu renders a ul of SidebarMenuItems. A menu button takes isActive for the current route, tooltip for the icon-collapsed state, and hosts an optional trailing SidebarMenuAction or SidebarMenuBadge; nested links go in a SidebarMenuSub.

<SidebarMenu>
  <SidebarMenuItem>
    <SidebarMenuButton tooltip="Inbox" isActive>
      <Inbox />
      <span>Inbox</span>
    </SidebarMenuButton>
    <SidebarMenuBadge>12</SidebarMenuBadge>
  </SidebarMenuItem>

  <SidebarMenuItem>
    <SidebarMenuButton tooltip="Projects">
      <Folder />
      <span>Projects</span>
    </SidebarMenuButton>
    <SidebarMenuAction showOnHover title="Add project">
      <Plus />
    </SidebarMenuAction>
    <SidebarMenuSub>
      <SidebarMenuSubItem>
        <SidebarMenuSubButton href="#" isActive>
          <span>Design System</span>
        </SidebarMenuSubButton>
      </SidebarMenuSubItem>
      <SidebarMenuSubItem>
        <SidebarMenuSubButton href="#">
          <span>Marketing Site</span>
        </SidebarMenuSubButton>
      </SidebarMenuSubItem>
    </SidebarMenuSub>
  </SidebarMenuItem>
</SidebarMenu>

Parts that render interactive elements (SidebarMenuButton, SidebarMenuSubButton, SidebarMenuAction, SidebarGroupLabel, SidebarGroupAction) accept a Base UI render prop to swap the underlying tag – for example a Next.js Link or a DropdownMenuTrigger:

<SidebarMenuButton render={<Link href="/dashboard" />}>
  <Home />
  <span>Dashboard</span>
</SidebarMenuButton>

While data loads, SidebarMenuSkeleton renders a placeholder row with a random 50–90% text width:

<SidebarMenu>
  {Array.from({ length: 5 }).map((_, i) => (
    <SidebarMenuItem key={i}>
      <SidebarMenuSkeleton showIcon />
    </SidebarMenuItem>
  ))}
</SidebarMenu>

useSidebar

Any component under the provider can read and drive the sidebar through the useSidebar hook. It throws if called outside a SidebarProvider.

function CloseOnNavigate() {
  const { isMobile, setOpenMobile, toggleSidebar } = useSidebar()

  return (
    <SidebarMenuButton
      onClick={() => {
        if (isMobile) setOpenMobile(false)
      }}
    >
      ...
    </SidebarMenuButton>
  )
}

API reference

Two components take configuration props; every other part is a styled wrapper that accepts className and the props of the element it renders.

Parts

Every part tags itself with a data-slot attribute (and most with a legacy data-sidebar attribute) for CSS targeting:

Behavior & styling hooks

The provider listens for Cmd/Ctrl+B to toggle the sidebar and writes every change to a sidebar_state cookie with a 7-day max-age. Below 768px (useIsMobile) the sidebar renders inside a Sheet with an sr-only title and description, controlled by openMobile instead of open. On desktop the outer element exposes data-state="expanded | collapsed", data-collapsible (set only while collapsed), data-variant and data-side – internal parts style themselves against these via group-data-[collapsible=icon]-style selectors, and you can target them the same way. Widths come from the --sidebar-width and --sidebar-width-icon CSS variables, and colors from the bg-sidebar theme token family.