Sidebar

Groups and items

A float rail 16px inside the screen edges, with the brand at the top, a search action, labelled groups of links, and an account row ruled off at the bottom. Put it inside an App shell, which owns its collapsed and drawer states.

• SidebarGroup: names its list with its label, a small uppercase line with a dot.
• SidebarItem: a link with an icon, a label and an optional count at the end.
• Current page: shown as an ink pill, and its group's dot lights up.

import { AppShell } from '@snapshot-ui/react';
import type { ReactElement } from 'react';
import { ShellHeader, ShellNav, ShellPage } from './shell-nav';

export default function SidebarGroups(): ReactElement {
  return (
    <div className="stage-shell">
      <AppShell sidebar={<ShellNav label="Main, groups" />} header={<ShellHeader />}>
        <ShellPage />
      </AppShell>
    </div>
  );
}

Collapsed

Collapsed, the rail is a 72px column of icons. Each name shows as a tooltip on hover and keyboard focus. A count becomes a dot on the icon's corner, with its number and words on the tooltip's second line. Every item stays a tab stop, and the labels are hidden from view, not removed, so no name changes.

import { AppShell } from '@snapshot-ui/react';
import type { ReactElement } from 'react';
import { ShellHeader, ShellNav, ShellPage } from './shell-nav';

export default function SidebarCollapsed(): ReactElement {
  return (
    <div className="stage-shell">
      <AppShell defaultSidebarCollapsed sidebar={<ShellNav label="Main, icons" />} header={<ShellHeader />}>
        <ShellPage />
      </AppShell>
    </div>
  );
}

The drawer

Below 1024px the rail is hidden. SidebarTrigger, an outline menu button for the page header, opens the same rail as a drawer from the start edge. The drawer always shows the labels and opens with focus on the current page. Pressing any item closes it, including the current one. This example opens the real drawer from a button, at any width.

'use client';

import { AppShell, Button, Card, CardBody, useAppShell } from '@snapshot-ui/react';
import type { ReactElement } from 'react';
import { ShellHeader, ShellNav } from './shell-nav';

/** The button spans the card's foot, so it stops at the card's corner inset and keeps its own shape. */
const CLEAR_OF_FOOT = { marginBlockEnd: 'calc(var(--holder-corner-inset) - var(--holder-pad))' };

/** Opens the drawer at any width, as the header's menu button does below 1024px. */
function OpenTheMenu(): ReactElement {
  const { openDrawer } = useAppShell();
  return (
    <Button onPress={openDrawer} style={CLEAR_OF_FOOT}>
      Open the menu
    </Button>
  );
}

export default function SidebarDrawer(): ReactElement {
  return (
    <div className="stage-shell">
      {/* The page's button is the one way in here, so the header draws no menu button of its own. */}
      <AppShell sidebar={<ShellNav label="Main, drawer" />} header={<ShellHeader hasTrigger={false} />}>
        <div style={{ padding: '0 var(--spacing-inset) var(--spacing-inset)' }}>
          <Card>
            <CardBody>
              <p style={{ margin: '0 0 16px' }}>The drawer is the rail a phone sees, here at any width.</p>
              <OpenTheMenu />
            </CardBody>
          </Card>
        </div>
      </AppShell>
    </div>
  );
}

Long labels

A long label wraps onto a second line, with the icon beside the first. It is never truncated, since that would hide which page the item opens.

import { AppShell } from '@snapshot-ui/react';
import type { ReactElement } from 'react';
import { ShellHeader, ShellNav, ShellPage } from './shell-nav';

export default function SidebarLongLabels(): ReactElement {
  return (
    <div className="stage-shell">
      <AppShell sidebar={<ShellNav label="Main, long labels" isLong />} header={<ShellHeader />}>
        <ShellPage />
      </AppShell>
    </div>
  );
}

The current page

The library cannot see the router, so the app marks the current page. Read usePathname() in a client component and pass isCurrent to the item and its group. There is no built-in prefix match: whether /budgets/2026 makes Budgets current is the app's rule.

'use client';

import { SidebarGroup, SidebarItem } from '@snapshot-ui/react';
import { ChartColumn, PiggyBank } from 'lucide-react';
import { usePathname } from 'next/navigation';

export function InsightsGroup() {
  const pathname = usePathname();
  return (
    <SidebarGroup label="Insights" isCurrent={['/reports', '/budgets'].includes(pathname)}>
      <SidebarItem href="/reports" icon={<ChartColumn />} isCurrent={pathname === '/reports'}>
        Reports
      </SidebarItem>
      <SidebarItem href="/budgets" icon={<PiggyBank />} isCurrent={pathname === '/budgets'}>
        Budgets
      </SidebarItem>
    </SidebarGroup>
  );
}

Slots

Each slot renders only when given.

• brand: a SidebarBrand, the mark and name as a link home. Collapsed, it keeps the mark, with the name as a tooltip.
• search: a SidebarSearch, a pill that opens the app's search in onPress. Collapsed, it keeps its icon, with the name as a tooltip.
• footer: anything, such as the signed-in account. Collapsed, it is centered. Read useSidebar().isCollapsed to show the account as an avatar alone.

While the drawer is open, the slots render twice, once in the rail and once in the drawer. Generate any id inside a slot with useId, never a fixed string, and read useSidebar().inDrawer to tell the copies apart. The same applies to SidebarGroup: an id you pass is repeated in the drawer copy, so leave the id to the library.

Usage

Sidebar and its parts are client components, and a server component can render them. Put the Sidebar in the shell's sidebar slot and a SidebarTrigger in its header.

• Search shortcut: shortcut takes keys separated by spaces, such as "Mod K", shown as a key chip. After the page loads, Mod becomes Cmd on Apple platforms and Ctrl elsewhere. The server's HTML says Mod.
• Search name: the chip is part of the button's name in both states, such as "Search or jump to, Ctrl K".
• Counts: an item's count comes with its countLabel, so the item reads "Transactions, 12 to review".
• Links: items and the brand are React Aria links. href works before any script runs, a RouterProvider routes every press as Routing shows, and render draws a router's own link for one item.

Props

On Sidebar, className and ref go on the rail's root. The drawer copy also gets the class, but the id and other attributes stay on the rail. Each part takes className and ref on its own element, with the class merged after the library's.

Accessibility

The rail is a <nav> named by its aria-label. Each group's list is named by the group's label, which is a paragraph, not a heading. The current page has aria-current="page". Tab walks the rail in order, with no arrow keys to learn.

• Names never depend on state: a collapsed label stays in the name, and a count's words are always in it.
• The collapse button names what it will do and says whether the rail is expanded.
• The drawer opens with focus on the current page, keeps Tab inside, hides the page behind it, and returns focus to the menu button when it closes.

Design rules

What keeps the rail in the system.