SidebarNav
Preview appears after the next Storybook update.
<SidebarNav />When to use
Use it for
- Primary navigation of an app with more than five areas, in a left rail that stays visible.
- Group items into titled sections by task (Library, Governance, Workspace).
- collapsible on sections users rarely need, so the rail stays short.
- count for items that need attention, like reviews waiting for you.
Not for
- Switching views inside one page: use Tabs.
- Fewer than five destinations: a top bar is enough.
- Actions (Create token, Sync from Figma): put them in the page header as Buttons, not in the navigation.
Do and don't
Every example is rendered with the real component, so it always matches what ships.
Mark exactly one current page
active on the item for the current URL, including when the user is on a child page of it.
Icons on some items only
A ragged column of icons breaks the scan line. Use icons on every item of a section or none.
Accessibility
- A nav landmark: give it an aria-label when the page has other navigation (Breadcrumb, Pagination).
- Each section is a list labelled by its title.
- The current item has aria-current="page". It also gets a 2px signal mark and ink text, so color is not the only cue.
- Collapsible section titles are buttons with aria-expanded (Base UI Collapsible); Enter and Space toggle them.
- Items are full-width targets at the menu item height (36px comfortable, 30px compact).
Content guidelines
- Name destinations with nouns users know: "Tokens", "Reviews", "Settings".
- Section titles are short nouns in sentence case, not all caps.
- Counts are numbers only; explain them on the destination page.
From the code Generated from the component, not editable here.
Anatomy and tokens
Read from packages/react/src/components/SidebarNav/SidebarNav.module.css at build time. Every value is a token: open one to see its alias chain in both themes.
- Navigation landmark
.sidebar - Section
.section - Section title
.title - Collapsible title button
.trigger - Collapsible title button, hover
@media (hover: hover) .trigger:hover - Collapsible title button, focus
.trigger:focus-visible - Collapse chevron
.chevron - Collapsible panel
.panel - Link list
.list - Link
.item - Link, hover
@media (hover: hover) .item:hover - Link
.item:active - Link, focus
.item:focus-visible - Current page
.active - Signal mark
.indicator - Current page
.active .icon - Count
.count
Motion and interaction
SidebarNav animates on hover and press. Try it in the preview at the top.
| Part | When | What changes | Duration | Easing |
|---|---|---|---|---|
| SidebarNav | Hover | Background and text color | motion.duration.instant75 ms | motion.easing.standardsettles in place |
| SidebarNav | Press | Background | motion.duration.instant75 ms | motion.easing.standardsettles in place |
| Section | Hover | Background and text color | motion.duration.instant75 ms | motion.easing.standardsettles in place |
| Section | Press | Background | motion.duration.instant75 ms | motion.easing.standardsettles in place |
| Item | Hover | Background and text color | motion.duration.instant75 ms | motion.easing.standardsettles in place |
| Item | Press | Background | motion.duration.instant75 ms | motion.easing.standardsettles in place |
With reduced motion turned on, every change happens at once.
It also uses motion.duration.fast, motion.duration.moderate for motion this table does not list yet.
From the code Generated from the component, not editable here.
Props
Parsed from the TypeScript types in packages/react/src/components/SidebarNav/SidebarNav.tsx, so this table cannot drift from the code.
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | none | No description in the code yet. |
Playground
SidebarNav has no typed options to play with: it is a container. Compose it with other components and any native attribute. Here it is in both themes.
Workbench
For contributors: every state with the accessibility panel, in the component workbench (Storybook). The stories double as visual test fixtures; the guidance on this page is the user documentation (open SidebarNav in Storybook).
Embed Storybook stories here (2)
Loads from https://bridge-storybook.floriangouloubi.com (set STORYBOOK_URL at build time). If Storybook is not running, the frames stay empty.
Default
AllStates
From the code Generated from the component, not editable here.
Changelog
- New
Navigation: Tabs (underline with a sliding signal indicator, contained, icons, counts, vertical), Breadcrumb (aria-current, collapsing middle levels), Pagination (full and compact, getPageItems helper) and SidebarNav (sections, collapsible groups, counts, current page mark)
v1.0.0, Nov 11, 2026