Sidebar

Implemented

Vertical navigation sidebar with grouped items, active-state indicator (aria-current), and a built-in mobile drawer (portal + scrim + focus trap + Escape + scroll lock). Persistent at >= breakpoint; overlay drawer below it. Real implementation; the organisms/sidebar stories twin was removed per ADR-035.

Categorymolecules

Sourcecomponents/molecules/Sidebar/Sidebar.tsx

AI HintNavigation surface for app shells (dashboard, docs, account). Vertical nav with grouped items and active-section highlighting; ships its own mobile drawer (focus trap + Escape + scroll lock). For general overlay panels use Drawer; for blocking decisions use Modal; for quick-action palettes use CommandMenu.

Vertical navigation panel with grouped items.

Sidebar

molecules

Renders a sticky vertical nav with grouped items, active-item accents, optional badges, and expandable sub-items. A collapsible mode swaps to a mobile drawer below the configured breakpoint.

Usage

Pass a logo node and an ordered groups array. Item accents attach to stable item positions (ADR-031 §3) — never cycle them over dynamic collections. Set collapsible to get the toggle button and mobile drawer.

For generic controlled side panels see Drawer; centered dialogs see Modal; ⌘K palettes see CommandMenu.

import { Sidebar } from '@epasslive/design-system'

<Sidebar
  logo={<span>ePassLive</span>}
  groups={[
    {
      id: 'main',
      label: 'Main',
      items: [
        { id: 'dashboard', label: 'Dashboard', active: true },
        { id: 'events', label: 'Events' },
      ],
    },
  ]}
/>

Props

Prop

Type

Default

Description

logo*

React.ReactNode

—

Brand node rendered above the nav groups.

groups*

SidebarGroup[]

—

Grouped navigation items (id, label, items).

activeKey

string

—

Id or href of the active item.

onItemClick

(key: string) => void

—

Fired when a leaf item is activated.

ariaLabel

string

"Primary navigation"

Accessible name for the nav landmark.

collapsible

boolean

—

Enables the toggle button and mobile drawer mode.

breakpoint

"sm" | "md" | "lg" | "xl"

"lg"

Min-width above which the static panel renders.

defaultOpen

boolean

false

Initial open state for the mobile drawer (persisted to localStorage).

storageKey

string

"epasslive-sidebar"

localStorage key for drawer open-state persistence. Cross-tab sync via the storage event.

toggleLabel

string

"Open navigation"

Accessible label for the hamburger toggle when the drawer is closed.

closeLabel

string

"Close navigation"

Accessible label for the hamburger toggle (open) and the drawer × button.

className

string

—

Additional CSS classes on the aside.

id

string

—

Stable id prefix for the panel and drawer.

Props

Prop

Type

Required

Default

Description

logo

React.ReactNode

Required

—

Brand/logo node rendered at the top of the sidebar.

groups

SidebarGroup[]

Required

—

Nav groups (id, label, items). SidebarItem supports icon, href, active, badge, nested children, and an ADR-031 accent for the active indicator bar.

activeKey

string

Optional

—

Highlights the item whose id equals this key; an explicit per-item `active` overrides the match.

onItemClick

(key: string) => void

Optional

—

Called with the item's id when a nav item is activated.

ariaLabel

string

Optional

'Primary navigation'

Accessible name for the nav landmark.

className

string

Optional

—

Class applied to the root element.

id

string

Optional

'sidebar'

Root element id.

collapsible

boolean

Optional

false

Enables the hamburger toggle + overlay drawer below `breakpoint`. Not a desktop icon-rail collapse.

breakpoint

SidebarBreakpoint

Optional

'lg'

Min-width at which the persistent sidebar replaces the mobile drawer ('lg' = 1024px).

defaultOpen

boolean

Optional

false

Initial open state of the mobile drawer.

storageKey

string

Optional

'epasslive-sidebar'

localStorage key persisting the drawer open state.

toggleLabel

string

Optional

'Open navigation'

Accessible label for the hamburger toggle button.

closeLabel

string

Optional

'Close navigation'

Accessible label for the overlay close button.

Quick use:<Sidebar />

Usage

Import

tsxSnippet

import { Sidebar } from "@epasslive/design-system"

Example 1

tsxSnippet

<Sidebar logo={logo} groups={navGroups} activeKey={pathname} />

Example 2

tsxSnippet

<Sidebar logo={logo} groups={navGroups} collapsible breakpoint="lg" />

Example 3

tsxSnippet

const { isOpen, toggle } = useSidebarState('app-sidebar')

Anti-patterns

— Do not hand-roll a fixed <aside> + hamburger — the molecule ships the mobile drawer with focus trap and aria-current

— Do not set per-item active:false while relying on activeKey — explicit false overrides the key match

— Do not use for transient overlay panels — Drawer and Modal are the overlay primitives