Sidebar

Minimal collapsible icon-mode sidebar with a footer SidebarTrigger. The inset shows placeholder content without a header trigger.

Installation

The component is exported from @by/experience-system. Add the package with your package manager:

pnpm add @by/experience-system

In this monorepo, depend on the workspace package (for example via workspace:* or your catalog) so imports resolve to packages/experience-system.

Composition

Use the following composition to build a Sidebar layout:

SidebarProvider
├── Sidebar
│   ├── SidebarHeader (optional)
│   ├── SidebarContent
│   │   └── SidebarGroup
│   │       ├── SidebarGroupLabel (optional)
│   │       ├── SidebarGroupAction (optional)
│   │       ├── SidebarGroupContent
│   │       └── SidebarMenu
│   │           └── SidebarMenuItem
│   │               ├── SidebarMenuButton
│   │               ├── SidebarMenuAction (optional)
│   │               ├── SidebarMenuBadge (optional)
│   │               └── SidebarMenuSub (optional)
│   │                   └── SidebarMenuSubItem
│   │                       └── SidebarMenuSubButton
│   ├── SidebarFooter (optional)
│   └── SidebarRail (optional)
├── SidebarInset
└── SidebarTrigger (optional; often in header or footer)

Wrap the tree in SidebarProvider. Use SidebarInset for the main content region—required when variant="inset". On viewports below the desktop breakpoint, Sidebar renders as a sheet dialog; keep the layout inside ThemeProvider so the portal container resolves. Composition and behavior follow the shadcn/ui Sidebar pattern.

Usage

import {
  Sidebar,
  SidebarContent,
  SidebarGroup,
  SidebarGroupContent,
  SidebarInset,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
} from '@by/experience-system';

Sidebar and its parts are client components ('use client'). Use them inside a Client Component or a dynamic import when using the Next.js App Router.

<SidebarProvider>
  <Sidebar>
    <SidebarContent>
      <SidebarGroup>
        <SidebarGroupContent>
          <SidebarMenu>
            <SidebarMenuItem>
              <SidebarMenuButton isActive tooltip="Home">
                <HomeIcon />
                <span>Home</span>
              </SidebarMenuButton>
            </SidebarMenuItem>
          </SidebarMenu>
        </SidebarGroupContent>
      </SidebarGroup>
    </SidebarContent>
  </Sidebar>
  <SidebarInset>
    <header>
      <SidebarTrigger />
    </header>
    <main>{children}</main>
  </SidebarInset>
</SidebarProvider>

Sidebar vs Drawer

Use this comparison when choosing between Sidebar and Drawer.

When to use

Choose Sidebar when the panel is part of the layout, stays available during work, and hiding it would interrupt the workflow:

• Application or MFE navigation with hierarchical routes, active states, and optional icon-only collapse on desktop.
• Filters, inspector / properties panels, or selection details used repeatedly alongside the main content.
• Layers panels, file explorers, and other tools that support continuous interaction throughout a session.

On mobile, Sidebar typically renders as a sheet—see Pin to dock to start from a Drawer and let users dock navigation when needed.

When not to use

• Temporary tasks the user completes and dismisses (create item, edit details, one-off settings, comments)—use Drawer.
• Simple confirmations or alerts—use Dialog.
• Horizontal top-level site navigation without a vertical rail—use Navigation Menu or Menubar.

Examples

Overview

Default off-canvas sidebar with nested Collapsible sections, truncated labels, and a trigger in the inset header. Use variant="sidebar" (recommended). floating and inset exist for shadcn parity but are not recommended for product layouts.

Collapsible icon mode

Set collapsible="icon" so the desktop sidebar collapses to icons. Tooltips on SidebarMenuButton appear in icon mode; place SidebarTrigger placement="footer" in SidebarFooter to toggle open state (as in the top preview). Ctrl+B / Cmd+B also toggles the sidebar.

Loading skeleton

Use SidebarMenuSkeleton with showIcon while async nav data loads.

Pin to dock

Pin navigation from a left Drawer (overlay; main content stays full width) into a docked Sidebar + SidebarInset layout (sidebar reserves width and shifts content). Place a pin control in the drawer header to dock; use PinOff in SidebarHeader to return to the drawer.

API Reference

The tables below mirror the shadcn/ui Sidebar API and the @by/experience-system implementation in packages/experience-system/src/components/Sidebar. Design-system extensions (RTL defaults, token styling, truncated-label tooltips) are called out inline.

SidebarProvider

Root wrapper. Provides sidebar context and sets width CSS variables on the provider element.

Forwards standard div props (className, style, children, …).

Set --sidebar-width-mobile on Sidebar (mobile sheet) via style when overriding mobile width (default 18rem).

useSidebar

Hook to read and control sidebar state. Must be used inside SidebarProvider.

Sidebar

Main sidebar panel. On mobile, renders as a Radix Dialog sheet.

Forwards standard div props.

SidebarTrigger

Button that toggles the sidebar. Extends Button props (variant, size, className, …).

placement: Footer (default) toggles ColumnShow / ColumnHide with RTL mirroring. Header uses LayoutSidebar on desktop and Menu on mobile; header icons are not mirrored in RTL. Stacks above SidebarRail (z-30 vs rail z-20) so the end-aligned footer trigger stays visible and clickable.

SidebarRail

Invisible edge control that toggles the sidebar on click.

SidebarInset

Main content region beside the sidebar. Renders a main element.

SidebarHeader

Sticky header region inside Sidebar.

SidebarFooter

Sticky footer region inside Sidebar.

SidebarContent

Scrollable area between header and footer.

SidebarGroup

Section wrapper for a block of navigation.

SidebarGroupLabel

Label for a SidebarGroup.

SidebarGroupAction

Action control aligned with a group label.

SidebarGroupContent

Content container under a group label.

SidebarMenu

<ul> menu list inside a group.

SidebarMenuItem

<li> wrapper for a menu row.

SidebarMenuButton

Primary nav control in a menu item.

tooltip: Shows in collapsed icon mode; when expanded, wraps a trailing <span> label with overflow tooltip (SidebarTruncatedLabel) unless labelOverflow="wrap".

SidebarMenuAction

Secondary action on a menu row (for example overflow menu trigger).

SidebarMenuBadge

Badge aligned to a menu item.

SidebarMenuSkeleton

Placeholder row while nav data loads.

SidebarMenuSub

Nested submenu list.

SidebarMenuSubItem

<li> wrapper for a submenu row.

SidebarMenuSubButton

Submenu link or button. Default element is <a> for leaf navigation (asChild + router link is preferred). When isFolder is set, renders <button type="button"> for collapsible section triggers (use with CollapsibleTrigger asChild).

SidebarSeparator

Horizontal rule between menu blocks.

SidebarTruncatedLabel

Utility span that shows a tooltip when label text overflows. Used internally by menu buttons when tooltip is set.

labelOverflow: truncate (default) ellipsizes overflowing text and shows a tooltip on hover. wrap breaks long labels across multiple lines with no overflow tooltip.

Accessibility

Use landmark and navigation semantics in the page shell (nav, aria-current on active routes via isActive styling). SidebarTrigger and SidebarRail expose Toggle Sidebar labels. On mobile, the sidebar sheet uses Radix Dialog focus management (Dialog accessibility).

Keyboard interactions

For collapsible sections inside the sidebar, see Collapsible keyboard interactions on CollapsibleTrigger. Nested branch rows must keep SidebarMenuSubItem (<li>) children inside SidebarMenuSub (<ul>). Folder sub-rows with isFolder render as <button> so aria-expanded from CollapsibleTrigger is valid.

Source in the repo: packages/experience-system/src/components/Sidebar/Sidebar.tsx. Agent-oriented contracts: packages/experience-system/src/components/Sidebar/Sidebar.instructions.md.