Sidebar

A collapsible side navigation column with header, body, footer, grouped items, and automatic mobile-drawer behaviour.

stable
since v0.1.0
12.0 kB
navigation
sidebar
accessible

Preview

tsx

import {
  Sidebar,
  SidebarBody,
  SidebarFooter,
  SidebarGroup,
  SidebarHeader,
  SidebarItem,
  SidebarNav,
  SidebarProvider,
  SidebarSeparator,
} from '@arshad-shah/cynosure-react';

const IconHome = () => (
  <svg
    aria-hidden="true"
    width="16"
    height="16"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    strokeWidth="2"
    strokeLinecap="round"
    strokeLinejoin="round"
  >
    <path d="M3 9l9-7 9 7v11a2 2 0 0 1-2 2h-4a2 2 0 0 1-2-2v-5h-2v5a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z" />
  </svg>
);
const IconInbox = () => (
  <svg
    aria-hidden="true"
    width="16"
    height="16"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    strokeWidth="2"
    strokeLinecap="round"
    strokeLinejoin="round"
  >
    <polyline points="22 12 16 12 14 15 10 15 8 12 2 12" />
    <path d="M5.45 5.11 2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.45-6.89A2 2 0 0 0 16.76 4H7.24a2 2 0 0 0-1.79 1.11z" />
  </svg>
);
const IconGear = () => (
  <svg
    aria-hidden="true"
    width="16"
    height="16"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    strokeWidth="2"
    strokeLinecap="round"
    strokeLinejoin="round"
  >
    <circle cx="12" cy="12" r="3" />
    <path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-4 0v-.09a1.65 1.65 0 0 0-1-1.51 1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06A1.65 1.65 0 0 0 4.6 15a1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1 0-4h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z" />
  </svg>
);

export default function Example() {
  return (
    <SidebarProvider>
      <Sidebar>
        <SidebarHeader>Cynosure</SidebarHeader>
        <SidebarBody>
          <SidebarNav aria-label="Primary">
            <SidebarGroup label="Workspace">
              <SidebarItem icon={<IconHome />} label="Dashboard" isActive />
              <SidebarItem icon={<IconInbox />} label="Inbox" badge="12" />
            </SidebarGroup>
            <SidebarSeparator />
            <SidebarGroup label="Account">
              <SidebarItem icon={<IconGear />} label="Settings" />
            </SidebarGroup>
          </SidebarNav>
        </SidebarBody>
        <SidebarFooter>v1.0.0</SidebarFooter>
      </Sidebar>
    </SidebarProvider>
  );
}

Usage

import {
  Sidebar,
  SidebarProvider,
  SidebarHeader,
  SidebarBody,
  SidebarFooter,
  SidebarNav,
  SidebarGroup,
  SidebarItem,
  SidebarSeparator,
  SidebarTrigger,
} from "@arshad-shah/cynosure-react";

<SidebarProvider>
  <Sidebar>
    <SidebarHeader>App</SidebarHeader>
    <SidebarBody>
      <SidebarNav aria-label="Primary">
        <SidebarGroup label="Workspace">
          <SidebarItem icon={<DashboardIcon />} label="Dashboard" isActive />
          <SidebarItem icon={<InboxIcon />} label="Inbox" badge="12" />
        </SidebarGroup>
      </SidebarNav>
    </SidebarBody>
    <SidebarFooter>v1.0.0</SidebarFooter>
  </Sidebar>
</SidebarProvider>

SidebarProvider owns collapsed and mobile-open state. On viewports matching mobileQuery (default (max-width: 47.99em)) the sidebar renders inside a Drawer automatically; on desktop it collapses to an icon rail when collapsible="icon" (the default).

Variants

Collapsible icon rail

Use SidebarTrigger anywhere to toggle the collapsed state. When collapsed, item labels are hidden but tooltips reveal them on hover.

Preview

Open

tsx

import {
  Sidebar,
  SidebarBody,
  SidebarGroup,
  SidebarHeader,
  SidebarItem,
  SidebarNav,
  SidebarProvider,
  SidebarTrigger,
} from '@arshad-shah/cynosure-react';

const IconHome = () => (
  <svg
    aria-hidden="true"
    width="16"
    height="16"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    strokeWidth="2"
    strokeLinecap="round"
    strokeLinejoin="round"
  >
    <path d="M3 9l9-7 9 7v11a2 2 0 0 1-2 2h-4a2 2 0 0 1-2-2v-5h-2v5a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z" />
  </svg>
);
const IconInbox = () => (
  <svg
    aria-hidden="true"
    width="16"
    height="16"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    strokeWidth="2"
    strokeLinecap="round"
    strokeLinejoin="round"
  >
    <polyline points="22 12 16 12 14 15 10 15 8 12 2 12" />
    <path d="M5.45 5.11 2 12v6a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-6l-3.45-6.89A2 2 0 0 0 16.76 4H7.24a2 2 0 0 0-1.79 1.11z" />
  </svg>
);

export default function Example() {
  return (
    <SidebarProvider defaultCollapsed collapsible="icon">
      <Sidebar>
        <SidebarHeader>
          <SidebarTrigger hideLabel />
        </SidebarHeader>
        <SidebarBody>
          <SidebarNav aria-label="Primary">
            <SidebarGroup>
              <SidebarItem icon={<IconHome />} label="Dashboard" isActive />
              <SidebarItem icon={<IconInbox />} label="Inbox" />
            </SidebarGroup>
          </SidebarNav>
        </SidebarBody>
      </Sidebar>
    </SidebarProvider>
  );
}

Groups with collapsible sections

Pass collapsible to SidebarGroup (with optional defaultOpen) for accordion-style sections. An action slot beside the label is useful for a ”+” button.

Preview

Open

tsx

import {
  Sidebar,
  SidebarBody,
  SidebarGroup,
  SidebarHeader,
  SidebarItem,
  SidebarNav,
  SidebarProvider,
} from '@arshad-shah/cynosure-react';

const IconPlus = () => (
  <svg
    aria-hidden="true"
    width="14"
    height="14"
    viewBox="0 0 24 24"
    fill="none"
    stroke="currentColor"
    strokeWidth="2"
    strokeLinecap="round"
    strokeLinejoin="round"
  >
    <line x1="12" y1="5" x2="12" y2="19" />
    <line x1="5" y1="12" x2="19" y2="12" />
  </svg>
);

export default function Example() {
  return (
    <SidebarProvider>
      <Sidebar>
        <SidebarHeader>Workspace</SidebarHeader>
        <SidebarBody>
          <SidebarNav aria-label="Primary">
            <SidebarGroup label="Pinned" collapsible defaultOpen>
              <SidebarItem label="Dashboard" isActive />
              <SidebarItem label="Tasks" />
            </SidebarGroup>
            <SidebarGroup
              label="Projects"
              collapsible
              defaultOpen={false}
              action={
                <button
                  type="button"
                  aria-label="New project"
                  style={{
                    display: 'inline-flex',
                    alignItems: 'center',
                    justifyContent: 'center',
                    width: 20,
                    height: 20,
                    border: 0,
                    background: 'transparent',
                    cursor: 'pointer',
                    color: 'var(--cynosure-color-fg-muted)',
                  }}
                >
                  <IconPlus />
                </button>
              }
            >
              <SidebarItem label="Cynosure" />
              <SidebarItem label="Studio" />
            </SidebarGroup>
          </SidebarNav>
        </SidebarBody>
      </Sidebar>
    </SidebarProvider>
  );
}

Use SidebarSubNav to nest items under a parent. When the rail is collapsed, sub-navs automatically render as a flyout Popover triggered by the parent item.

Preview

Open

tsx

import {
  Sidebar,
  SidebarBody,
  SidebarGroup,
  SidebarHeader,
  SidebarItem,
  SidebarNav,
  SidebarProvider,
  SidebarSubItem,
  SidebarSubNav,
} from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <SidebarProvider>
      <Sidebar>
        <SidebarHeader>Docs</SidebarHeader>
        <SidebarBody>
          <SidebarNav aria-label="Docs">
            <SidebarGroup>
              <SidebarSubNav
                parentLabel="Components"
                defaultOpen
                trigger={<SidebarItem label="Components" />}
              >
                <SidebarSubItem isActive>Tabs</SidebarSubItem>
                <SidebarSubItem>Stepper</SidebarSubItem>
                <SidebarSubItem>Pagination</SidebarSubItem>
              </SidebarSubNav>
              <SidebarItem label="Tokens" />
              <SidebarItem label="Recipes" />
            </SidebarGroup>
          </SidebarNav>
        </SidebarBody>
      </Sidebar>
    </SidebarProvider>
  );
}

Pass side="right" to SidebarProvider (or directly to Sidebar) to mirror the layout.

Preview

Open

tsx

import {
  Sidebar,
  SidebarBody,
  SidebarGroup,
  SidebarHeader,
  SidebarItem,
  SidebarNav,
  SidebarProvider,
} from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <SidebarProvider side="right">
      <Sidebar>
        <SidebarHeader>Inspector</SidebarHeader>
        <SidebarBody>
          <SidebarNav aria-label="Inspector">
            <SidebarGroup label="Details">
              <SidebarItem label="Overview" isActive />
              <SidebarItem label="Activity" />
              <SidebarItem label="Files" />
            </SidebarGroup>
          </SidebarNav>
        </SidebarBody>
      </Sidebar>
    </SidebarProvider>
  );
}

The variant prop on SidebarProvider adjusts the surface treatment: "sidebar" (default) sits flush, "floating" is detached with a shadow, "inset" is recessed inside the page background.

Preview

Open

tsx

import {
  Sidebar,
  SidebarBody,
  SidebarHeader,
  SidebarItem,
  SidebarNav,
  SidebarProvider,
} from '@arshad-shah/cynosure-react';

function Demo({ variant }: { variant: 'sidebar' | 'floating' | 'inset' }) {
  return (
    <SidebarProvider variant={variant}>
      <Sidebar>
        <SidebarHeader>{variant}</SidebarHeader>
        <SidebarBody>
          <SidebarNav aria-label="Demo">
            <SidebarItem label="Home" isActive />
            <SidebarItem label="Inbox" />
          </SidebarNav>
        </SidebarBody>
      </Sidebar>
    </SidebarProvider>
  );
}

export default function Example() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '1.5rem' }}>
      <Demo variant="sidebar" />
      <Demo variant="floating" />
      <Demo variant="inset" />
    </div>
  );
}

SidebarFooter is a free-form slot — use it for user menus, version pills, or upgrade prompts.

Preview

Open

tsx

import {
  Sidebar,
  SidebarBody,
  SidebarFooter,
  SidebarHeader,
  SidebarItem,
  SidebarNav,
  SidebarProvider,
  SidebarSeparator,
} from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <SidebarProvider>
      <Sidebar>
        <SidebarHeader>Cynosure</SidebarHeader>
        <SidebarBody>
          <SidebarNav aria-label="Primary">
            <SidebarItem label="Dashboard" isActive />
            <SidebarItem label="Projects" />
          </SidebarNav>
        </SidebarBody>
        <SidebarSeparator />
        <SidebarFooter>
          <div style={{ display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
            <div
              style={{
                width: 28,
                height: 28,
                borderRadius: 'var(--cynosure-radius-full)',
                background: 'var(--cynosure-color-accent-solid)',
              }}
              aria-hidden="true"
            />
            <div style={{ display: 'flex', flexDirection: 'column' }}>
              <span style={{ fontSize: '0.875rem', fontWeight: 600 }}>Arshad</span>
              <span style={{ fontSize: '0.75rem', color: 'var(--cynosure-color-fg-muted)' }}>
                Pro plan
              </span>
            </div>
          </div>
        </SidebarFooter>
      </Sidebar>
    </SidebarProvider>
  );
}

API

PropTypeDefaultDescription

side

"left"|"right"

—

Override the provider's `side`. Useful when a single layout has both a left and a right sidebar.

mobileTitle

ReactNode

Sidebar

Visually-hidden title used as the mobile Drawer's accessible name.

mobileDescription

ReactNode

—

Visually-hidden description for the mobile Drawer (`aria-describedby`).

Accessibility

The sidebar renders as <aside> containing a <nav> (SidebarNav); pass aria-label to SidebarNav for an explicit landmark name.
SidebarItem carries aria-current="page" when isActive is set, and aria-disabled="true" when disabled.
A roving tabindex is implemented internally (useRovingFocus) so arrow keys move between sidebar items without trapping Tab.
When the rail is collapsed (icon-only mode), each SidebarItem is automatically wrapped in a Tooltip that announces its label.
On mobile, the sidebar renders inside a Drawer with a hidden title (mobileTitle, default "Sidebar") so screen readers can identify the dialog.
SidebarTrigger toggles aria-expanded and aria-pressed and updates its accessible name ("Expand" / "Collapse" / "Open" / "Close") automatically.

Recipes

Wrap your whole app in SidebarProvider so the collapsed state persists across routes.
Use collapsible="offcanvas" instead of "icon" when you want the desktop sidebar to slide away entirely rather than shrink to a rail.
Pair SidebarItem asChild with a router <Link> to keep client-side navigation while inheriting the styled chrome.
Set tooltip={false} on items that already have an obvious meaning when collapsed (e.g. avatars).
Use variant="floating" for marketing-style dashboards and variant="inset" when the sidebar should look set into the page background.

Sidebar

Usage

Variants

Collapsible icon rail

Groups with collapsible sections

Sub-navigation

Right-aligned sidebar

Variants — sidebar, floating, inset

With footer actions

API

Accessibility

Recipes