Sidebar

A collapsible app sidebar that renders as a sheet on small screens.

Workspace
"use client"

import { visibility } from "@/theme/visibility"
import type { ElementType } from "react"
import { useState } from "react"
import * as stylex from "@stylexjs/stylex"
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from "@/components/ui/breadcrumb"
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
  collapsibleStyles,
} from "@/components/ui/collapsible"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
import { Separator } from "@/components/ui/separator"
import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarInset,
  SidebarMenu,
  SidebarMenuAction,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarMenuSub,
  SidebarMenuSubButton,
  SidebarMenuSubItem,
  SidebarProvider,
  SidebarRail,
  SidebarTrigger,
  sidebarStyles,
  useSidebar,
} from "@/components/ui/sidebar"
import { HStack, VStack } from "@/components/ui/stack"
import { Text } from "@/components/ui/text"
import { breakpoints } from "@/theme/breakpoints.stylex"
import { color, radius, space } from "@/theme/tokens.stylex"
import { WaveformIcon } from "@phosphor-icons/react/dist/csr/Waveform"
import { SealCheckIcon } from "@phosphor-icons/react/dist/csr/SealCheck"
import { BellIcon } from "@phosphor-icons/react/dist/csr/Bell"
import { BookOpenIcon } from "@phosphor-icons/react/dist/csr/BookOpen"
import { RobotIcon } from "@phosphor-icons/react/dist/csr/Robot"
import { CaretRightIcon } from "@phosphor-icons/react/dist/csr/CaretRight"
import { CaretUpDownIcon } from "@phosphor-icons/react/dist/csr/CaretUpDown"
import { CommandIcon } from "@phosphor-icons/react/dist/csr/Command"
import { CreditCardIcon } from "@phosphor-icons/react/dist/csr/CreditCard"
import { FolderIcon } from "@phosphor-icons/react/dist/csr/Folder"
import { ArrowBendUpRightIcon } from "@phosphor-icons/react/dist/csr/ArrowBendUpRight"
import { FrameCornersIcon } from "@phosphor-icons/react/dist/csr/FrameCorners"
import { CardsIcon } from "@phosphor-icons/react/dist/csr/Cards"
import { SignOutIcon } from "@phosphor-icons/react/dist/csr/SignOut"
import { MapTrifoldIcon } from "@phosphor-icons/react/dist/csr/MapTrifold"
import { DotsThreeIcon } from "@phosphor-icons/react/dist/csr/DotsThree"
import { ChartPieIcon } from "@phosphor-icons/react/dist/csr/ChartPie"
import { PlusIcon } from "@phosphor-icons/react/dist/csr/Plus"
import { SlidersHorizontalIcon } from "@phosphor-icons/react/dist/csr/SlidersHorizontal"
import { SparkleIcon } from "@phosphor-icons/react/dist/csr/Sparkle"
import { NotebookIcon } from "@phosphor-icons/react/dist/csr/Notebook"
import { TrashIcon } from "@phosphor-icons/react/dist/csr/Trash"

const sidebarPrimary = "light-dark(oklch(0.205 0 0), oklch(0.922 0 0))"
const sidebarPrimaryForeground = "light-dark(oklch(0.985 0 0), oklch(0.205 0 0))"

const styles = stylex.create({
  logo: {
    display: "flex",
    aspectRatio: "1",
    width: space.s8,
    height: space.s8,
    flexShrink: 0,
    alignItems: "center",
    justifyContent: "center",
    borderRadius: radius.lg,
    backgroundColor: sidebarPrimary,
    color: sidebarPrimaryForeground,
  },
  lines: { display: "grid", flexGrow: 1, minWidth: 0, textAlign: "left" },
  trailing: { marginInlineStart: "auto" },
  menu: { minWidth: "14rem" },
  teamLogo: {
    display: "flex",
    width: space.s6,
    height: space.s6,
    flexShrink: 0,
    alignItems: "center",
    justifyContent: "center",
    borderRadius: radius.md,
    borderWidth: 1,
    borderStyle: "solid",
    "--arene-icon-size": space.s3_5,
  },
  muted: { color: color.mutedForeground },
  header: { height: space.s16, flexShrink: 0 },
  headerRule: { height: space.s4 },
  grid: {
    display: "grid",
    gap: space.s4,
    gridTemplateColumns: { default: "1fr", [breakpoints.md]: "repeat(3, 1fr)" },
  },
  tile: {
    aspectRatio: "16 / 9",
    borderRadius: radius.xl,
    backgroundColor: `color-mix(in oklab, ${color.muted} 50%, transparent)`,
  },
  canvas: {
    flexGrow: 1,
    borderRadius: radius.xl,
    backgroundColor: `color-mix(in oklab, ${color.muted} 50%, transparent)`,
  },
})

const data = {
  user: {
    name: "Leonhard Euler",
    email: "euler@example.com",
  },
  teams: [
    { name: "Euler Labs", logo: CardsIcon, plan: "Research" },
    { name: "Noether Group", logo: WaveformIcon, plan: "Teaching" },
    { name: "Curie Studio", logo: CommandIcon, plan: "Personal" },
  ],
  navMain: [
    {
      title: "Notebooks",
      url: "#",
      icon: NotebookIcon,
      isActive: true,
      items: [
        { title: "Recent", url: "#", isActive: true },
        { title: "Pinned", url: "#" },
        { title: "Shared", url: "#" },
      ],
    },
    {
      title: "Models",
      url: "#",
      icon: RobotIcon,
      items: [
        { title: "Fast", url: "#" },
        { title: "Balanced", url: "#" },
        { title: "Thorough", url: "#" },
      ],
    },
    {
      title: "Documentation",
      url: "#",
      icon: BookOpenIcon,
      items: [
        { title: "Introduction", url: "#" },
        { title: "Quick start", url: "#" },
        { title: "Guides", url: "#" },
        { title: "Release notes", url: "#" },
      ],
    },
    {
      title: "Settings",
      url: "#",
      icon: SlidersHorizontalIcon,
      items: [
        { title: "General", url: "#" },
        { title: "Members", url: "#" },
        { title: "Billing", url: "#" },
        { title: "Usage", url: "#" },
      ],
    },
  ],
  projects: [
    { name: "Image archive", url: "#", icon: FrameCornersIcon },
    { name: "Usage metrics", url: "#", icon: ChartPieIcon },
    { name: "Roadmap", url: "#", icon: MapTrifoldIcon },
  ],
}

function TeamSwitcher({ teams }: { teams: { name: string; logo: ElementType; plan: string }[] }) {
  const { isMobile } = useSidebar()
  const [activeTeam, setActiveTeam] = useState(teams[0])

  if (!activeTeam) return null

  return (
    <SidebarMenu>
      <SidebarMenuItem>
        <DropdownMenu>
          <DropdownMenuTrigger render={<SidebarMenuButton size="lg" />}>
            <div {...stylex.props(styles.logo)}>
              <activeTeam.logo />
            </div>
            <div {...stylex.props(styles.lines)}>
              <Text weight="medium" xstyle={sidebarStyles.truncate}>
                {activeTeam.name}
              </Text>
              <Text size="xs" xstyle={sidebarStyles.truncate}>
                {activeTeam.plan}
              </Text>
            </div>
            <CaretUpDownIcon aria-hidden="true" {...stylex.props(styles.trailing)} />
          </DropdownMenuTrigger>
          <DropdownMenuContent
            xstyle={styles.menu}
            align="start"
            side={isMobile ? "bottom" : "right"}
            sideOffset={4}
          >
            <DropdownMenuGroup>
              <DropdownMenuLabel>Teams</DropdownMenuLabel>
              {teams.map((team, index) => (
                <DropdownMenuItem key={team.name} onClick={() => setActiveTeam(team)}>
                  <div {...stylex.props(styles.teamLogo)}>
                    <team.logo />
                  </div>
                  {team.name}
                  <DropdownMenuShortcut>⌘{index + 1}</DropdownMenuShortcut>
                </DropdownMenuItem>
              ))}
            </DropdownMenuGroup>
            <DropdownMenuSeparator />
            <DropdownMenuGroup>
              <DropdownMenuItem>
                <div {...stylex.props(styles.teamLogo)}>
                  <PlusIcon aria-hidden="true" />
                </div>
                <Text weight="medium" tone="muted">
                  Add team
                </Text>
              </DropdownMenuItem>
            </DropdownMenuGroup>
          </DropdownMenuContent>
        </DropdownMenu>
      </SidebarMenuItem>
    </SidebarMenu>
  )
}

function NavMain({
  items,
}: {
  items: {
    title: string
    url: string
    icon?: ElementType
    isActive?: boolean
    items?: { title: string; url: string; isActive?: boolean }[]
  }[]
}) {
  return (
    <SidebarGroup>
      <SidebarGroupLabel>Workspace</SidebarGroupLabel>
      <SidebarMenu>
        {items.map((item) => (
          <Collapsible key={item.title} defaultOpen={item.isActive}>
            <SidebarMenuItem>
              <CollapsibleTrigger render={<SidebarMenuButton tooltip={item.title} />}>
                {item.icon && <item.icon />}
                <span {...stylex.props(sidebarStyles.truncate)}>{item.title}</span>
                <CaretRightIcon
                  aria-hidden="true"
                  {...stylex.props(collapsibleStyles.chevronInline, styles.trailing)}
                />
              </CollapsibleTrigger>
              <CollapsibleContent>
                <SidebarMenuSub>
                  {item.items?.map((subItem) => (
                    <SidebarMenuSubItem key={subItem.title}>
                      <SidebarMenuSubButton
                        render={<a href={subItem.url} />}
                        isActive={subItem.isActive}
                      >
                        <span {...stylex.props(sidebarStyles.truncate)}>{subItem.title}</span>
                      </SidebarMenuSubButton>
                    </SidebarMenuSubItem>
                  ))}
                </SidebarMenuSub>
              </CollapsibleContent>
            </SidebarMenuItem>
          </Collapsible>
        ))}
      </SidebarMenu>
    </SidebarGroup>
  )
}

function NavProjects({
  projects,
}: {
  projects: { name: string; url: string; icon: ElementType }[]
}) {
  const { isMobile } = useSidebar()

  return (
    <SidebarGroup>
      <SidebarGroupLabel>Projects</SidebarGroupLabel>
      <SidebarMenu>
        {projects.map((item) => (
          <SidebarMenuItem key={item.name}>
            <SidebarMenuButton render={<a href={item.url} />}>
              <item.icon />
              <span {...stylex.props(sidebarStyles.truncate)}>{item.name}</span>
            </SidebarMenuButton>
            <DropdownMenu>
              <DropdownMenuTrigger render={<SidebarMenuAction showOnHover aria-label="More" />}>
                <DotsThreeIcon aria-hidden="true" />
              </DropdownMenuTrigger>
              <DropdownMenuContent
                side={isMobile ? "bottom" : "right"}
                align={isMobile ? "end" : "start"}
              >
                <DropdownMenuItem>
                  <FolderIcon aria-hidden="true" {...stylex.props(styles.muted)} />
                  <span>Open project</span>
                </DropdownMenuItem>
                <DropdownMenuItem>
                  <ArrowBendUpRightIcon aria-hidden="true" {...stylex.props(styles.muted)} />
                  <span>Share with team</span>
                </DropdownMenuItem>
                <DropdownMenuSeparator />
                <DropdownMenuItem>
                  <TrashIcon aria-hidden="true" {...stylex.props(styles.muted)} />
                  <span>Move to trash</span>
                </DropdownMenuItem>
              </DropdownMenuContent>
            </DropdownMenu>
          </SidebarMenuItem>
        ))}
        <SidebarMenuItem>
          <SidebarMenuButton xstyle={styles.muted}>
            <DotsThreeIcon aria-hidden="true" />
            <span>More</span>
          </SidebarMenuButton>
        </SidebarMenuItem>
      </SidebarMenu>
    </SidebarGroup>
  )
}

function NavUser({ user }: { user: { name: string; email: string } }) {
  const { isMobile } = useSidebar()

  return (
    <SidebarMenu>
      <SidebarMenuItem>
        <DropdownMenu>
          <DropdownMenuTrigger render={<SidebarMenuButton size="lg" />}>
            <Avatar>
              <AvatarFallback>LE</AvatarFallback>
            </Avatar>
            <div {...stylex.props(styles.lines)}>
              <Text weight="medium" xstyle={sidebarStyles.truncate}>
                {user.name}
              </Text>
              <Text size="xs" xstyle={sidebarStyles.truncate}>
                {user.email}
              </Text>
            </div>
            <CaretUpDownIcon aria-hidden="true" {...stylex.props(styles.trailing)} />
          </DropdownMenuTrigger>
          <DropdownMenuContent
            xstyle={styles.menu}
            side={isMobile ? "bottom" : "right"}
            align="end"
            sideOffset={4}
          >
            <DropdownMenuGroup>
              <DropdownMenuLabel>
                <HStack gap={2} align="center">
                  <Avatar>
                    <AvatarFallback>LE</AvatarFallback>
                  </Avatar>
                  <div {...stylex.props(styles.lines)}>
                    <Text weight="medium" xstyle={sidebarStyles.truncate}>
                      {user.name}
                    </Text>
                    <Text size="xs" xstyle={sidebarStyles.truncate}>
                      {user.email}
                    </Text>
                  </div>
                </HStack>
              </DropdownMenuLabel>
            </DropdownMenuGroup>
            <DropdownMenuSeparator />
            <DropdownMenuGroup>
              <DropdownMenuItem>
                <SparkleIcon aria-hidden="true" />
                What&apos;s new
              </DropdownMenuItem>
            </DropdownMenuGroup>
            <DropdownMenuSeparator />
            <DropdownMenuGroup>
              <DropdownMenuItem>
                <SealCheckIcon aria-hidden="true" />
                Account
              </DropdownMenuItem>
              <DropdownMenuItem>
                <CreditCardIcon aria-hidden="true" />
                Billing
              </DropdownMenuItem>
              <DropdownMenuItem>
                <BellIcon aria-hidden="true" />
                Notifications
              </DropdownMenuItem>
            </DropdownMenuGroup>
            <DropdownMenuSeparator />
            <DropdownMenuGroup>
              <DropdownMenuItem>
                <SignOutIcon aria-hidden="true" />
                Log out
              </DropdownMenuItem>
            </DropdownMenuGroup>
          </DropdownMenuContent>
        </DropdownMenu>
      </SidebarMenuItem>
    </SidebarMenu>
  )
}

export default function SidebarDemo() {
  return (
    <SidebarProvider>
      <Sidebar collapsible="icon">
        <SidebarHeader>
          <TeamSwitcher teams={data.teams} />
        </SidebarHeader>
        <SidebarContent>
          <NavMain items={data.navMain} />
          <NavProjects projects={data.projects} />
        </SidebarContent>
        <SidebarFooter>
          <NavUser user={data.user} />
        </SidebarFooter>
        <SidebarRail />
      </Sidebar>
      <SidebarInset>
        <HStack render={<header />} gap={2} align="center" paddingInline={4} xstyle={styles.header}>
          <SidebarTrigger />
          <Separator orientation="vertical" xstyle={styles.headerRule} />
          <Breadcrumb>
            <BreadcrumbList>
              <BreadcrumbItem xstyle={visibility.inlineFlexFromMd}>
                <BreadcrumbLink href="#">Notebooks</BreadcrumbLink>
              </BreadcrumbItem>
              <BreadcrumbSeparator xstyle={visibility.inlineFlexFromMd} />
              <BreadcrumbItem>
                <BreadcrumbPage>Recent</BreadcrumbPage>
              </BreadcrumbItem>
            </BreadcrumbList>
          </Breadcrumb>
        </HStack>
        <VStack gap={4} grow paddingInline={4} paddingBlockEnd={4}>
          <div {...stylex.props(styles.grid)}>
            <div {...stylex.props(styles.tile)} />
            <div {...stylex.props(styles.tile)} />
            <div {...stylex.props(styles.tile)} />
          </div>
          <div {...stylex.props(styles.canvas)} />
        </VStack>
      </SidebarInset>
    </SidebarProvider>
  )
}

Installation

pnpm dlx shadcn@latest add @arene/sidebar

Needs the arene setup first. Also adds Button, Input, Separator, Sheet, Skeleton, Stack and Tooltip.

Usage

app/layout.tsx
import { SidebarProvider, SidebarTrigger } from "@/components/ui/sidebar"
import { AppSidebar } from "@/components/app-sidebar"

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <SidebarProvider>
      <AppSidebar />
      <main>
        <SidebarTrigger />
        {children}
      </main>
    </SidebarProvider>
  )
}
components/app-sidebar.tsx
import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarHeader,
} from "@/components/ui/sidebar"

export function AppSidebar() {
  return (
    <Sidebar>
      <SidebarHeader />
      <SidebarContent>
        <SidebarGroup />
        <SidebarGroup />
      </SidebarContent>
      <SidebarFooter />
    </Sidebar>
  )
}

Composition

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

Above 48rem the Sidebar is a fixed column beside an in-flow spacer that animates its width to push the page over. Below it, the same children render inside a Sheet on the same side.

The variant prop is on SidebarProvider, not on Sidebar as in shadcn. The inset variant styles the wrapper and the SidebarInset beside the sidebar as well, and neither can see a sibling's prop.

There is no RTL section. arene does not support RTL yet, so the offcanvas offset and the rail use LTR physical properties.

Structure

  • SidebarProvider holds the open state and shares it with every part inside it.
  • Sidebar is the panel itself.
  • SidebarHeader is sticky at the top. Use it for branding, titles, or workspace switchers.
  • SidebarFooter is sticky at the bottom. Use it for user menus, settings, or actions.
  • SidebarContent scrolls. It sits between the header and the footer.
  • SidebarGroup is one section of the content, with a label, its own content and an optional action.
  • SidebarMenu is a list of SidebarMenuItem rows. A row holds a link or button and can add a badge, an action or a submenu.
  • SidebarRail is a strip along the sidebar's edge that toggles it.
  • SidebarInset holds the main content in the inset variant.
  • SidebarTrigger is a button that opens and collapses the sidebar.

SidebarProvider

Wrap the layout in a SidebarProvider. It holds the open state for the desktop panel and the mobile sheet, persists the desktop one in a arene-sidebar cookie, and binds ⌘B on Mac and Ctrl+B on Windows.

PropTypeDefault
defaultOpenbooleantrue
openboolean—
onOpenChange(open: boolean) => void—
variant"sidebar" | "floating" | "inset""sidebar"

Width

The panel is 16rem wide, 3rem as an icon rail and 18rem as a sheet. The first two are custom properties on the wrapper. Set them with style on the provider; they are plain custom properties, so every part inside reads them.

const wide = { "--arene-sidebar-width": "20rem", "--arene-sidebar-width-icon": "4rem" }

<SidebarProvider style={wide as CSSProperties}>
  <Sidebar />
</SidebarProvider>

Keyboard shortcut

SIDEBAR_KEYBOARD_SHORTCUT in sidebar.tsx is the key that toggles the sidebar with ⌘ or Ctrl held.

components/ui/sidebar.tsx
const SIDEBAR_KEYBOARD_SHORTCUT = "b"

Sidebar renders the collapsible panel.

PropTypeDefault
side"left" | "right""left"
collapsible"offcanvas" | "icon" | "none""offcanvas"
collapsibleDescription
offcanvasSlides out of view to its side.
iconShrinks to a column of icons.
noneStays open and cannot collapse.

With variant="inset" on the provider, wrap the main content in a SidebarInset. It draws the panel the page is raised in, out of the tray the sidebar sits on, and moves over when the sidebar collapses.

<SidebarProvider variant="inset">
  <Sidebar />
  <SidebarInset>
    <main>{children}</main>
  </SidebarInset>
</SidebarProvider>

useSidebar

useSidebar reads and changes the sidebar's state from any component inside the provider.

import { useSidebar } from "@/components/ui/sidebar"

export function AppSidebar() {
  const { state, open, setOpen, openMobile, setOpenMobile, isMobile, toggleSidebar } = useSidebar()
}
PropertyTypeDescription
state"expanded" | "collapsed""expanded" when open is true, else "collapsed".
openbooleantrue while the desktop panel is open.
setOpen(open: boolean) => voidOpens or closes the desktop panel.
openMobilebooleantrue while the mobile sheet is open.
setOpenMobile(open: boolean) => voidOpens or closes the mobile sheet.
isMobilebooleantrue when the viewport is narrower than 48rem.
toggleSidebar() => voidToggles the panel on desktop and the sheet on mobile.

SidebarHeader

SidebarHeader stays at the top of the sidebar while the content scrolls.

components/app-sidebar.tsx
<Sidebar>
  <SidebarHeader>
    <SidebarMenu>
      <SidebarMenuItem>
        <DropdownMenu>
          <DropdownMenuTrigger render={<SidebarMenuButton />}>
            Euler Labs
            <CaretDownIcon {...stylex.props(styles.trailing)} />
          </DropdownMenuTrigger>
          <DropdownMenuContent>
            <DropdownMenuItem>Euler Labs</DropdownMenuItem>
            <DropdownMenuItem>Noether Group</DropdownMenuItem>
          </DropdownMenuContent>
        </DropdownMenu>
      </SidebarMenuItem>
    </SidebarMenu>
  </SidebarHeader>
</Sidebar>

A menu button that is an open menu's trigger keeps its hover fill while the menu is open. The aria-expanded rule in interop.css does this.

SidebarFooter

SidebarFooter stays at the bottom of the sidebar while the content scrolls.

<Sidebar>
  <SidebarFooter>
    <SidebarMenu>
      <SidebarMenuItem>
        <SidebarMenuButton>
          <UserIcon /> Leonhard Euler
        </SidebarMenuButton>
      </SidebarMenuItem>
    </SidebarMenu>
  </SidebarFooter>
</Sidebar>

SidebarContent

SidebarContent is the scrolling area between the header and the footer. Put your SidebarGroup components in it.

<Sidebar>
  <SidebarContent>
    <SidebarGroup />
    <SidebarGroup />
  </SidebarContent>
</Sidebar>

SidebarGroup

SidebarGroup is one section of the sidebar's content.

It holds a SidebarGroupLabel, a SidebarGroupContent and, when the section needs one, a SidebarGroupAction. Give the action an aria-label. It is an icon-only button, so there is no text for a screen reader to announce.

<SidebarGroup>
  <SidebarGroupLabel>Projects</SidebarGroupLabel>
  <SidebarGroupAction aria-label="Add project">
    <PlusIcon />
  </SidebarGroupAction>
  <SidebarGroupContent></SidebarGroupContent>
</SidebarGroup>

A group collapses when you wrap it in a Collapsible and render its label as the trigger. collapsibleStyles.chevron turns the chevron with the panel.

<Collapsible defaultOpen>
  <SidebarGroup>
    <SidebarGroupLabel render={<CollapsibleTrigger />}>
      Documentation
      <CaretDownIcon {...stylex.props(collapsibleStyles.chevron, styles.trailing)} />
    </SidebarGroupLabel>
    <CollapsibleContent>
      <SidebarGroupContent />
    </CollapsibleContent>
  </SidebarGroup>
</Collapsible>

SidebarMenu

SidebarMenu is the list of rows inside a SidebarGroup.

<SidebarMenu>
  {projects.map((project) => (
    <SidebarMenuItem key={project.name}>
      <SidebarMenuButton render={<a href={project.url} />}>
        <project.icon />
        <span {...stylex.props(sidebarStyles.truncate)}>{project.name}</span>
      </SidebarMenuButton>
    </SidebarMenuItem>
  ))}
</SidebarMenu>

SidebarMenuButton

SidebarMenuButton is the clickable part of a SidebarMenuItem.

It is a button unless you pass render, for example render={<a href="#" />} or your router's Link.

isActive marks the row for the current page.

<SidebarMenuButton render={<a href="#" />} isActive>
  Home
</SidebarMenuButton>

Put a label that can outgrow the row in a span with sidebarStyles.truncate. StyleX has no [&>span:last-child], so the row cannot select the label. The label takes the truncation style itself.

Pass tooltip to label the row while the sidebar is collapsed to icons. A string is the label; an object is TooltipContent's props. The tooltip renders only in that state.

<SidebarMenuButton tooltip="Notebooks">
  <NotebookIcon />
  <span>Notebooks</span>
</SidebarMenuButton>

SidebarMenuAction

SidebarMenuAction is an icon button at the end of a SidebarMenuItem. Give it an aria-label.

<SidebarMenuItem>
  <SidebarMenuButton render={<a href="#" />}>
    <HouseIcon />
    <span>Home</span>
  </SidebarMenuButton>
  <SidebarMenuAction aria-label="Add project">
    <PlusIcon />
  </SidebarMenuAction>
</SidebarMenuItem>

Pass showOnHover to hide the action until the row is hovered or holds focus. Below 48rem it always shows; there is no pointer to hover with.

The action registers with its SidebarMenuItem after mount, and the button then pads its end so a long label truncates before the icon. Prerendered HTML ships without that padding, so a label that reaches the action moves by 2rem on hydration.

SidebarMenuSub

SidebarMenuSub is a nested list inside a SidebarMenuItem.

<SidebarMenuItem>
  <SidebarMenuButton />
  <SidebarMenuSub>
    <SidebarMenuSubItem>
      <SidebarMenuSubButton />
    </SidebarMenuSubItem>
  </SidebarMenuSub>
</SidebarMenuItem>

SidebarMenuBadge

SidebarMenuBadge shows a count or a short label at the end of a SidebarMenuItem.

<SidebarMenuItem>
  <SidebarMenuButton />
  <SidebarMenuBadge>24</SidebarMenuBadge>
</SidebarMenuItem>

The badge measures itself after mount, and the button pads its end by the badge's width so a long label truncates before it. As with the action, prerendered HTML ships without that padding.

SidebarMenuSkeleton

SidebarMenuSkeleton is a placeholder row for a menu that is still loading. The text bar is between 50% and 90% wide, chosen from the element's id so the server and the client agree.

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

SidebarTrigger

SidebarTrigger is a button that opens and collapses the sidebar. It is a ghost icon-sm Button and takes every prop one does.

import { useSidebar } from "@/components/ui/sidebar"

export function CustomTrigger() {
  const { toggleSidebar } = useSidebar()

  return <button onClick={toggleSidebar}>Toggle sidebar</button>
}

SidebarRail

SidebarRail is a thin strip along the sidebar's edge that toggles it. It is out of the tab order, so keyboard users toggle the sidebar with the trigger.

<Sidebar>
  <SidebarHeader />
  <SidebarContent>
    <SidebarGroup />
  </SidebarContent>
  <SidebarFooter />
  <SidebarRail />
</Sidebar>

Controlled sidebar

Pass open and onOpenChange to SidebarProvider to keep the open state in your own component.

export function AppSidebar() {
  const [open, setOpen] = useState(false)

  return (
    <SidebarProvider open={open} onOpenChange={setOpen}>
      <Sidebar />
    </SidebarProvider>
  )
}

Theming

The sidebar reads its own tokens, so it can differ from the page around it. They are in tokens.stylex.ts beside the rest.

theme/tokens.stylex.ts
sidebar: "light-dark(oklch(0.985 0 0), oklch(0.205 0 0))",
sidebarForeground: "light-dark(oklch(0.145 0 0), oklch(0.985 0 0))",
sidebarPrimary: "light-dark(oklch(0.205 0 0), oklch(0.922 0 0))",
sidebarPrimaryForeground: "light-dark(oklch(0.985 0 0), oklch(0.205 0 0))",
sidebarAccent: "light-dark(oklch(0.95 0 0), oklch(0.269 0 0))",
sidebarAccentForeground: "light-dark(oklch(0.205 0 0), oklch(0.985 0 0))",
sidebarBorder: "light-dark(oklch(0.922 0 0), oklch(1 0 0 / 10%))",

Styling

Every part takes xstyle. A part that changes with the sidebar's state reads that state from context, so there is no group-data-[collapsible=icon] to key on. Read useSidebar and pass a conditional style instead.

const { state } = useSidebar()

<SidebarGroup xstyle={[state === "collapsed" && styles.hidden]} />

API reference

Pass render to replace a part's element or compose it with another component.

Every part renders a plain element, or Base UI's useRender where it takes render. Each part also takes xstyle and className.

SidebarProvider

PropTypeDefault
defaultOpenbooleantrue
openboolean—
onOpenChange(open: boolean) => void—
variant"sidebar" | "floating" | "inset""sidebar"
PropTypeDefault
side"left" | "right""left"
collapsible"offcanvas" | "icon" | "none""offcanvas"

SidebarMenuButton

PropTypeDefault
renderReactElement | (props, state) => ReactElement—
isActivebooleanfalse
variant"default" | "outline""default"
size"default" | "sm" | "lg""default"
tooltipstring | TooltipContentProps—

SidebarMenuAction

PropTypeDefault
renderReactElement | (props, state) => ReactElement—
showOnHoverbooleanfalse

SidebarMenuSubButton

PropTypeDefault
renderReactElement | (props, state) => ReactElement—
isActivebooleanfalse
size"sm" | "md""md"

SidebarMenuSkeleton

PropTypeDefault
showIconbooleanfalse

sidebarStyles

The style maps behind the menu buttons, exported so the same row can be put on another element.

KeyDescription
menuButtonThe row: box, hover fill, focus ring, icon size
menuButtonVariantsOne style per variant
menuButtonSizesOne style per size, with the height and type
menuSubButtonThe nested row, one step shorter
truncateEllipsis for the label span in a row

Data attributes

AttributeOnEffect
data-slot="sidebar-wrapper"the provider's div
data-variantwrapper, sidebarMirrors the provider's variant
data-slot="sidebar"the sidebar rootAbsent below 48rem, where the sheet renders
data-statethe sidebar root"expanded" or "collapsed"
data-collapsiblethe sidebar rootThe collapsible prop while collapsed, "" while open
data-sideroot, containerMirrors side
data-slot="sidebar-gap"the in-flow spacerAnimates its width with the panel
data-slot="sidebar-container"the fixed panelWhere xstyle and className land
data-slot="sidebar-inner"the panel's surfaceFill, and the floating variant's raised shadow
data-sidebar="sidebar", data-mobilethe sheet popupWritten beside the sheet's own data-slot
data-slot="sidebar-trigger"the trigger
data-slot="sidebar-rail"the rail
data-slot="sidebar-inset"the main
data-slot="sidebar-header", -footer, -contenteach region
data-slot="sidebar-group", -label, -action, -contenteach group part
data-slot="sidebar-menu", -item, -sub, -sub-itemeach list part
data-slot="sidebar-menu-button"a rowReplaced by the trigger's slot when rendered through render
data-sidebar="menu-button"a rowWhere interop.css keys the open-menu fill
data-variant, data-size, data-activea row, a nested rowMirror the props; data-active is present only when true
data-slot="sidebar-menu-action"an actionReplaced by the trigger's slot when rendered through render
data-sidebar="menu-action"an actionWhere interop.css keys the open-menu opacity
data-slot="sidebar-menu-badge"a badge
data-slot="sidebar-menu-skeleton", -icon, -textthe skeleton parts
aria-haspopup, aria-expandeda row that opens a menuBase UI writes them