Skip to main content

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_collapsible arg 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​

PropTypeDefaultDescription
itemsarray-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.
labelstring-Accessible label for the navigation landmark.
is_collapsiblebooleantrueWhen true, parent items become inline expand/collapse triggers via the collapsible utility.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.subtleEmphasis-Lower emphasis; a muted, quieter weight.
.neutralEmphasisYesDefault emphasis; the standard weight at balanced contrast.
.accentEmphasis-Higher emphasis; a stronger, louder weight.
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.animatedMotionYesHonors the animations option.
.stillMotion-Forces motion off regardless of the option.

Attributes​

AttributeSet byRequiredDescription
data-sidenavConsumerYesMarks the sidenav root. Required for the JS to enhance the navigation tree.
data-collapsible-panelConsumer-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-collapsedScript-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 the label arg
  • Submenu triggers expose aria-expanded and aria-controls from 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​

  • navbar - horizontal site navigation with dropdown panels
  • mobilenav - off-canvas mobile equivalent inside a drawer
  • toc - in-page table of contents for a single article