Sidebar

The sidebar is a provider plus a vocabulary of parts. There is no Sidebar component that takes your navigation as data — a nav is a layout tree, and a layout tree is children. This page is both the guide and the reference.

The shape

<SidebarProvider>
  <Sidebar>
    <SidebarHeader>{/* what am I looking at — a switcher */}</SidebarHeader>
    <SidebarContent>{/* the navigation itself */}</SidebarContent>
    <SidebarFooter>{/* who am I */}</SidebarFooter>
  </Sidebar>

  <SidebarInset>
    <ShellMain>{children}</ShellMain>   {/* the page — ShellMain owns the <main> */}
  </SidebarInset>
</SidebarProvider>

Each of those three slots is written out below. The app shell and workspace showcases have all three in full, wired together — that is the place to copy from.

SidebarProvider owns the open state, persists it to a sidebar_state cookie, and binds ⌘/Ctrl+B to toggle. Everything below reads that state through useSidebar, which throws outside the provider. Below the md breakpoint the sidebar becomes a Sheet drawer instead of a rail, which is why the navigating composites close it on click.

The navigation

A nav row is a SidebarMenuButton with asChild over your router's link. A group that expands is a Collapsible around a SidebarMenuSub:

<SidebarGroup>
  <SidebarGroupLabel>Platform</SidebarGroupLabel>
  <SidebarMenu>
    <SidebarMenuItem>
      <SidebarMenuButton asChild isActive={isActivePath(pathname, "/jobs")} tooltip="Jobs">
        <NextLink href="/jobs"><PlayIcon />Jobs</NextLink>
      </SidebarMenuButton>
    </SidebarMenuItem>
  </SidebarMenu>
</SidebarGroup>

Wrap the whole thing in a <nav aria-label="Platform">: several labelled blocks is several groups, one per heading, and the label is what tells them apart.

Two behaviours belong to your application rather than to the library, and both are two lines in the showcases:

• A group starts open when one of its children is active — defaultOpen={items.some((i) => isActivePath(pathname, i.href))} on the Collapsible.
• Navigating closes the drawer on mobile — useSidebar().setOpenMobile(false) in the row's onClick. Below the md breakpoint the sidebar is a Sheet, and a Sheet that stays open over the page you just navigated to is the defect.

The identity blocks

SidebarIdentity and its parts are the shared "icon + name + subtitle" row that both a workspace switcher and a signed-in-user footer are made of. Put a Menu around one and you have either:

<SidebarMenuButton size="lg" asChild>
  <MenuTrigger>
    <SidebarIdentity>
      <SidebarIdentityIcon><BoxIcon /></SidebarIdentityIcon>
      <SidebarIdentityText>
        <SidebarIdentityLabel>aemet</SidebarIdentityLabel>
        <SidebarIdentityDescription>production</SidebarIdentityDescription>
      </SidebarIdentityText>
    </SidebarIdentity>
  </MenuTrigger>
</SidebarMenuButton>

A square SidebarIdentityIcon reads as a thing; a round SidebarIdentityAvatar reads as a person. That is the only difference between the two arrangements, and it is why they are one vocabulary rather than two components.

The avatar takes the real Avatar parts as children, so an image, initials, a badge or a presence dot are all available — not a URL and a fallback string.

Anatomy

SidebarInput is exported for the search field a sidebar header usually holds: an Input at the rail's own height, on --background rather than the sidebar's own fill, so it reads as a field against the panel instead of dissolving into it.

SidebarProvider
├── Sidebar
│   ├── SidebarHeader
│   ├── SidebarContent
│   │   └── SidebarGroup
│   │       ├── SidebarGroupLabel
│   │       ├── SidebarGroupAction
│   │       └── SidebarGroupContent
│   │           └── SidebarMenu
│   │               └── SidebarMenuItem
│   │                   ├── SidebarMenuButton
│   │                   ├── SidebarMenuAction
│   │                   ├── SidebarMenuBadge
│   │                   └── SidebarMenuSub
│   │                       └── SidebarMenuSubItem
│   │                           └── SidebarMenuSubButton
│   ├── SidebarSeparator
│   ├── SidebarFooter
│   └── SidebarRail
├── SidebarTrigger
└── SidebarInset

SidebarHeader and SidebarFooter each usually hold a Menu over a SidebarIdentity; SidebarContent holds one <nav> per labelled block.

Sub-menus

SidebarMenuSub is hidden outright when the sidebar collapses to icons — a nested list has no readable form at 48px, so it is dropped rather than squeezed.

Loading

Collapsing

SidebarProvider owns the state; SidebarTrigger toggles it and ⌘B is bound for you. On narrow viewports the whole sidebar becomes a Sheet instead of collapsing in place — that swap is automatic and is why the provider must wrap both the sidebar and the content.

Read the state anywhere below the provider:

const { open, isMobile, toggleSidebar } = useSidebar();

Keyboard

This one is ours, not Ark's: SidebarProvider listens on window, so it fires wherever focus is, text fields included.

API Reference

SidebarProvider

Extends React.ComponentProps<"div">.

Sidebar

collapsible="none" renders a plain static <aside> in normal flow — the right choice when the sidebar is embedded in a panel rather than pinned to the viewport.

SidebarMenuButton

The tooltip only shows while the sidebar is collapsed and not on mobile, so labelled buttons never get a redundant one.

SidebarContent

SidebarMenuAction

SidebarMenuSkeleton

SidebarMenuSubButton

useSidebar

Returns { state, open, setOpen, isMobile, openMobile, setOpenMobile, toggleSidebar }.

Every part's props are exported as an interface — SidebarIdentityProps and SidebarMenuBadgeProps — so a wrapper can take the same props without restating them.