Sidebar

<Sidebar /> is the vertical navigation rail that lives inside an AppShell's sidebar slot — or stands alone with its own width — and powers the left-hand nav of dashboards, admin panels, docs sites, and internal tools.

• Compound primitive: Sidebar.Header, Sidebar.Section, Sidebar.Item, Sidebar.SubItems, Sidebar.Spacer, Sidebar.Footer.
• Rail mode (collapsed): item labels go sr-only, items auto-wrap in Tooltips, section labels collapse. Wired to useAppShell().isSidebarCollapsed when inside an AppShell.
• Active-state matching at the root via activeHref + activeMatchStrategy (exact or prefix). Each Item self-decides aria-current="page" against the pure helper isActiveHref({ current, itemHref, strategy }).
• Compound interactive elements — <a> for nav targets, <button> for actions, <button aria-expanded> for expandable groups. No roving tabindex (each item is a tab stop, matching the W3C Disclosure pattern).
• asChild anywhere (<Sidebar.Item asChild>) for router-Link integration.

Anatomy

import { Sidebar, useAppShell } from 'apx-ds';

function AppNav() {
  const { isSidebarCollapsed } = useAppShell();
  return (
    <Sidebar collapsed={isSidebarCollapsed} activeHref={router.pathname}>
      <Sidebar.Header>
        <Logo />
      </Sidebar.Header>
      <Sidebar.Section label="Workspace">
        <Sidebar.Item href="/" icon={<HomeIcon />}>Home</Sidebar.Item>
        <Sidebar.Item href="/inbox" icon={<InboxIcon />} badge={3}>Inbox</Sidebar.Item>
      </Sidebar.Section>
      <Sidebar.Section label="Projects" collapsible defaultOpen>
        <Sidebar.Item href="/p/launch" icon={<FolderIcon />}>Launch</Sidebar.Item>
      </Sidebar.Section>
      <Sidebar.Spacer />
      <Sidebar.Footer>
        <UserMenu />
      </Sidebar.Footer>
    </Sidebar>
  );
}

import { Sidebar, useAppShell } from 'apx-ds';

function AppNav() {
  const { isSidebarCollapsed } = useAppShell();
  return (
    <Sidebar collapsed={isSidebarCollapsed} activeHref={router.pathname}>
      <Sidebar.Header>
        <Logo />
      </Sidebar.Header>
      <Sidebar.Section label="Workspace">
        <Sidebar.Item href="/" icon={<HomeIcon />}>Home</Sidebar.Item>
        <Sidebar.Item href="/inbox" icon={<InboxIcon />} badge={3}>Inbox</Sidebar.Item>
      </Sidebar.Section>
      <Sidebar.Section label="Projects" collapsible defaultOpen>
        <Sidebar.Item href="/p/launch" icon={<FolderIcon />}>Launch</Sidebar.Item>
      </Sidebar.Section>
      <Sidebar.Spacer />
      <Sidebar.Footer>
        <UserMenu />
      </Sidebar.Footer>
    </Sidebar>
  );
}

API — <Sidebar> root

API — <Sidebar.Item>

API — <Sidebar.Section>

Active-href matching

The pure helper isActiveHref({ current, itemHref, strategy }) decides each item's active state. Trailing slashes are normalized. Under prefix, the boundary check ensures /p does not wrongly match /photos — the helper requires current to start with itemHref + '/'.

import { isActiveHref } from 'apx-ds';

isActiveHref({ current: '/inbox/42', itemHref: '/inbox', strategy: 'prefix' }); // true
isActiveHref({ current: '/photos',  itemHref: '/p',     strategy: 'prefix' }); // false
isActiveHref({ current: '/inbox/',  itemHref: '/inbox', strategy: 'exact'  }); // true

import { isActiveHref } from 'apx-ds';

isActiveHref({ current: '/inbox/42', itemHref: '/inbox', strategy: 'prefix' }); // true
isActiveHref({ current: '/photos',  itemHref: '/p',     strategy: 'prefix' }); // false
isActiveHref({ current: '/inbox/',  itemHref: '/inbox', strategy: 'exact'  }); // true

Rail (collapsed) mode

Set collapsed on the root — typically wired to useAppShell().isSidebarCollapsed:

• Item labels become sr-only (kept in the DOM for SR announcement).
• Each item is wrapped in a <Tooltip content={label} placement="right"> so the visible cue on hover/focus is the label text itself.
• Section labels go sr-only by default; opt out via hideLabelWhenCollapsed={false}.
• End icons + visible badges hide; numeric badge contents are mirrored to a sr-only span so unread counts still reach AT.

Examples

Accessibility

• Root renders as <nav aria-label={ariaLabel}> (default "Sidebar"). Does NOT use <aside> because AppShell already labels its own <aside> sidebar slot; nesting two landmarks would add noise.
• <Sidebar.Item href> → <a> (navigation target). With aria-current="page" when active.
• <Sidebar.Item onClick> → <button type="button">.
• <Sidebar.Item expandable> → <button aria-expanded aria-controls> (Disclosure pattern).
• <Sidebar.SubItems> → <ul role="group">.
• Section labels: static → <h3>; collapsible → <button aria-expanded>.
• Disabled items get aria-disabled="true" and tabIndex={-1}; clicks are neutralized.
• No roving tabindex — every item is a tab stop. This matches Linear / GitHub / Notion / VS Code, and the W3C Disclosure / Landmarks patterns (navigation is browsable with Tab; role="menu" patterns are for menus, not navigation).
• axe-core: zero violations across flat / sections / collapsible / expandable / rail / active configurations.

RTL

• The root flex column is direction-agnostic.
• Inline borders use border-inline-end / border-inline-start so the bordered variant lands on the correct logical side.
• Padding + icon order use logical properties throughout.
• Rail-mode Tooltip uses placement="right" which flips via Floating UI's flip middleware under dir="rtl".

Theming

Sidebar reads from theme.components.Sidebar.styleOverrides.{root, item, sectionLabel, sectionBody, disclosure, header, footer, subItems}. Consumer className always wins via tailwind-merge.

Do / Don't

• Do wire collapsed to useAppShell().isSidebarCollapsed when nested in AppShell. That's the canonical pattern — Sidebar then degrades into a rail in sync with the header hamburger.
• Do use activeMatchStrategy="prefix" for nested route highlighting; the boundary check is built-in so /p does not match /photos.
• Do put icons on every item that might appear in rail mode — without an icon the rail has nothing visible to show.
• Do use asChild to integrate with your router (<RouterLink>, <NavLink>, etc.) instead of adding onClick={navigate} handlers.
• Don't add roving tabindex — sidebar items are tab stops, not menu items.
• Don't nest a Sidebar inside another Sidebar. Use <Sidebar.Item expandable> + <Sidebar.SubItems> for hierarchical navigation.
• Don't render a Sidebar as the AppShell's aside slot — the aside is for context panels (details / settings / chat), not navigation.