SideNav
Collapsible sidebar navigation with optional icons and one level of grouping
Category: navigation · WCAG 2.2-AA · navigation, sidebar, app-shell, collapsible
States
- expanded
- collapsed
Props
| Prop | Type | Default | Description |
|---|---|---|---|
groups | SideNavGroup[] | — | Grouped navigation items rendered under optional group labels. |
showCollapseToggle | boolean | true | Show the collapse/expand toggle control. |
items | SideNavItem[] | — | { label, href?, icon?, active?, items?, onClick?, disabled?, tone?, trailing?, render? } — an onClick-only item renders a focusable <button>; nested items render expandable menus (links, action sub-items with onSelect/selected, separators, labels); render() is an alignment-preserving escape hatch |
collapsed | boolean | — | Controlled collapsed state (rail mode) |
defaultCollapsed | boolean | false | Whether the rail is collapsed on first render (uncontrolled). |
onCollapsedChange | (collapsed: boolean) => void | — | Called with the new collapsed state when it changes. |
ariaLabel | string | Side navigation | Accessible label for the component. |
collapseLabel | string | Collapse navigation | Accessible label for the collapse control. |
expandLabel | string | Expand navigation | Accessible label for the expand control. |
expandOnHover | boolean | false | Widens the rail as an overlay on hover/focus-within; suppresses tooltips/flyouts |
header | ReactNode | — | Content rendered above the items, inside the item padding context (e.g. app-context pickers) |
footer | ReactNode | — | Content rendered above the collapse toggle (e.g. version string, user info) |
className | string | — | Additional CSS class names merged onto the root element. |
Design tokens
--cascivo-sidenav-inline-size--cascivo-sidenav-rail-inline-size--cascivo-sidenav-bg--cascivo-color-surface--cascivo-color-border--cascivo-color-text--cascivo-color-text-subtle--cascivo-color-bg-subtle--cascivo-color-accent--cascivo-color-accent-subtle--cascivo-color-destructive--cascivo-color-warning--cascivo-color-success--cascivo-focus-ring--cascivo-motion-enter--cascivo-motion-exit--cascivo-motion-emphasis
When to use
- Persistent primary navigation along the side of an app shell
- Grouping nav items one level deep with collapsible groups
- Saving space with a collapsible icon rail (collapsed / expandOnHover)
When not to use
- Top-level horizontal navigation — use Header or ShellHeader nav
- A transient contextual menu — use Dropdown
How to build an accessible SideNav in React →
Examples
Basic
<SideNav items={[{ label: 'Home', href: '/', active: true }, { label: 'Reports', href: '/reports' }]} />With a group
<SideNav items={[{ label: 'Settings', items: [{ label: 'Profile', href: '/profile' }] }]} />Icon rail
Collapsed rail: icons-only with tooltips, grapheme fallback for icon-less items, flyout menus for groups
import { Home } from '@cascivo/icons'
<SideNav collapsed items={[{ label: 'Home', href: '/', icon: <Home size={16} /> }]} />Expand on hover
Rail widens as CSS overlay on hover without reflowing adjacent content
<SideNav collapsed expandOnHover items={items} />Related components
- ShellHeader — The header hamburger toggles SideNav collapse