Sidenav
Vertical multi-level navigation with collapsible submenus. Use for sidebars, section navigation, documentation trees, and admin areas; submenus expand and collapse inline via the collapsible utility.
Usage
When to use
- Persistent sidebar navigation alongside long-form content
- Documentation trees and admin areas with a deep, hierarchical link structure
- Section-level navigation that benefits from inline expand and collapse
When not to use
- Primary horizontal site navigation - use navbar
- Off-canvas mobile menus - use mobilenav inside a drawer
- Page-level table of contents for a single article - use toc
- A flat list of unrelated links - use linklist
Do
- Mark the current item explicitly so the active branch is obvious without color alone
- Keep the tree shallow when possible; deeper than three levels is hard to scan in a narrow rail
- Use the
is_collapsiblearg to let users hide siblings of the current branch
Don't
- Don't combine sidenav with navbar dropdowns showing the same tree - pick one navigation surface
- Don't override the collapsible behavior with custom JS - reuse the shared utility for keyboard and ARIA correctness
- Don't use sidenav for a single-page table of contents - toc is purpose-built for that
API
Props
| Prop | Type | Default | Description |
|---|---|---|---|
items | array | - | Tree of navigation items. Each item may have url, text, icon, description, badge, is_active_trail, is_current, is_disabled, is_external, is_section, is_divider, and a nested items array. |
label | string | - | Accessible label for the navigation landmark. |
is_collapsible | boolean | true | When true, parent items become inline expand/collapse triggers via the collapsible utility. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.subtle | Emphasis | - | Lower emphasis; a muted, quieter weight. |
.neutral | Emphasis | Yes | Default emphasis; the standard weight at balanced contrast. |
.accent | Emphasis | - | Higher emphasis; a stronger, louder weight. |
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.animated | Motion | Yes | Honors the animations option. |
.still | Motion | - | Forces motion off regardless of the option. |
Attributes
| Attribute | Set by | Required | Description |
|---|---|---|---|
data-sidenav | Consumer | Yes | Marks the sidenav root. Required for the JS to enhance the navigation tree. |
data-collapsible-panel | Consumer | - | Set on each generated submenu wrapper so the collapsible utility wires up the expand/collapse interaction. The roving-focus reads it to skip links inside collapsed submenus. |
data-collapsible-collapsed | Script | - | Present on a submenu owner while its panel is collapsed. The roving-focus reads it to skip hidden links. |
Examples
Sizes
The three size values, which scale the link font size and the link padding together.
Flat
A single level with no nesting, for a quick-links list that has no hierarchy to collapse.
In scrollbox
Four levels inside a viewport shorter than the tree, so the sidebar has to scroll independently of the page.
Accessibility
- WCAG 2.2 AA
- Wrapped in
<nav>with an accessible name via thelabelarg - Submenu triggers expose
aria-expandedandaria-controlsfrom the collapsible utility - Current item is marked with
aria-current="page"so assistive tech announces position in the tree - Reduced-motion preferences disable the collapsible expand and collapse animation
Dependencies
- collapsible - drives submenu expand and collapse