Sidebar

Sidebar

<Sidebar label="Workspace nav">
  <Sidebar.Header>
    <Avatar fallback="HX" /> <Text weight="semibold">helixui</Text>
  </Sidebar.Header>

  <Sidebar.Group title="Workspace">
    <Sidebar.Item href="/" icon={<Home />} active>
      Dashboard
    </Sidebar.Item>
    <Sidebar.Item href="/users" icon={<Users />} trailing="3">
      Users
    </Sidebar.Item>
  </Sidebar.Group>

  <Sidebar.Group title="Settings">
    <Sidebar.Item href="/billing">Billing</Sidebar.Item>
  </Sidebar.Group>

  <Sidebar.Footer>
    <Stack direction="row" align="center" gap={2}>
      <Avatar fallback="ST" size="sm" />
      <Text size="sm">Jordan Lee</Text>
    </Stack>
  </Sidebar.Footer>
</Sidebar>

Install: @helixui/core

import { Sidebar } from '@helixui/core'

status: stable · since: 0.2.0

Tags: nav, vertical, rail, sections, grouped, persistent

Anatomy

┌─────────────────────────┐
│ Sidebar.Header          │   ← brand / search
├─────────────────────────┤
│ Sidebar.Group "title"   │
│   • Sidebar.Item active │   ← active uses aria-current=page
│   • Sidebar.Item        │
│   • Sidebar.Item   [3]  │   ← trailing content (badge, count)
│                         │
│ Sidebar.Group "title"   │
│   • Sidebar.Item        │
├─────────────────────────┤
│ Sidebar.Footer          │   ← pinned to bottom
└─────────────────────────┘
 ↑ wrapped in <nav aria-label>

Layout

• display — flex
• width — fixed:240px (default), tunable via parent
• height — fill
• intrinsicSize — full-height vertical column, footer pinned
• stackable — false
• fullBleed — false

Visual

A muted vertical column. Items are pill-shaped (radius.md) with subtle hover (action.neutral.default at low alpha) and a tinted brand background (action.brand.subtle) when active. Group titles are tiny uppercase labels (font.size.xs + font.weight.semibold) with low contrast. Icons sit at space.2 from the label. The footer is separated by border.default and contains compact identity (Avatar + name).

Props

Name	Type	Default	Description
label	string	Primary	aria-label on the wrapping <nav>.

Slots

• Sidebar.Header — brand / search at the top
• Sidebar.Group — group of items with optional title
• Sidebar.Item — anchor (when href) or button. active adds aria-current=page. Optional icon and trailing.
• Sidebar.Footer — pinned bottom slot

Tokens used

color.bg.action.neutral.default, color.bg.action.brand.subtle, color.text.primary, color.text.secondary, color.text.muted, color.text.action.brand, color.border.default, color.border.focus, radius.md, space.1, space.2, space.3, font.family.sans, font.size.sm, font.size.xs, font.weight.semibold, font.weight.medium

Accessibility

Notes

• Wraps in <nav aria-label>. Active item is rendered with aria-current="page".
• Items can be <a> or <button> depending on whether href is provided.

Composes with

Component	Relation	Note
AppShell	slot	Fills the sidebar slot of AppShell on desktop.
Sheet	parent	Render the same Sidebar inside Sheet (side=‘start’) for the mobile drawer.
NavigationMenu	alternative	Use NavigationMenu for a horizontal top-bar nav.
BottomNav	alternative	Mobile-only horizontal nav at the bottom of the viewport.
Avatar	child	Common in Sidebar.Header and Sidebar.Footer.

Prompt examples

These are the AI prompt → JSX mappings used by the helixui prompt DSL and integrations like Cursor / Claude Code.

basic side navigation

“sidebar with Dashboard, Users, Billing”

<Sidebar label="Workspace nav">
  <Sidebar.Group>
    <Sidebar.Item href="/" active>Dashboard</Sidebar.Item>
    <Sidebar.Item href="/users">Users</Sidebar.Item>
    <Sidebar.Item href="/billing">Billing</Sidebar.Item>
  </Sidebar.Group>
</Sidebar>

grouped navigation with counts

“sidebar with two sections, show unread count next to Inbox”

<Sidebar label="Mail">
  <Sidebar.Group title="Mail">
    <Sidebar.Item href="/inbox" trailing="12" active>Inbox</Sidebar.Item>
    <Sidebar.Item href="/sent">Sent</Sidebar.Item>
  </Sidebar.Group>
  <Sidebar.Group title="Workspace">
    <Sidebar.Item href="/team">Team</Sidebar.Item>
  </Sidebar.Group>
</Sidebar>

sidebar with brand + user identity

“side nav with logo at the top and current user at the bottom”

<Sidebar>
  <Sidebar.Header>
    <Avatar fallback="HX" /> <Text weight="semibold">helixui</Text>
  </Sidebar.Header>
  <Sidebar.Group>
    <Sidebar.Item href="/" active>Home</Sidebar.Item>
  </Sidebar.Group>
  <Sidebar.Footer>
    <Avatar fallback="ST" size="sm" /> <Text size="sm">Jordan Lee</Text>
  </Sidebar.Footer>
</Sidebar>

mobile drawer reuse

“use the same sidebar inside a sheet on mobile”

<Sheet side="start" isOpen={open} onOpenChange={setOpen}>
  <Sidebar>...</Sidebar>
</Sheet>

Related

• AppShell
• NavigationMenu
• Sheet