Sidebar

v2.1.5

Documentation Under Review

Catalyst Sidebar is a fully-accessible, collapsible navigation sidebar composed from a set of building-block primitives — SidebarProvider, SidebarRoot, SidebarHeader, SidebarContent, SidebarFooter, and more — giving you a production-ready application shell with keyboard shortcuts, icon-only collapse, and design-token styling out of the box.

Installation

npm install @pmi/catalyst-sidebar

import {
  SidebarProvider,
  SidebarRoot,
  SidebarHeader,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarGroupContent,
  SidebarMenu,
  SidebarMenuItem,
  SidebarMenuButton,
  SidebarMenuAction,
  SidebarMenuBadge,
  SidebarMenuSub,
  SidebarMenuSubItem,
  SidebarMenuSubButton,
  SidebarRail,
  SidebarTrigger,
} from '@pmi/catalyst-sidebar';

Common Patterns

Logo Mark with Text

Use a smaller logo mark alongside a title and subtitle text in the header.

Icon with Text Header

Use any custom icon alongside a title and subtitle text in the header.

Avatar with Text Header

Display a user avatar and name in the header, typically for user-scoped workspaces.

API Reference

Sidebar is a compound component. The sections below document the API surface for each part.

useSidebar

Returns the current sidebar context. Must be called inside a component tree wrapped by SidebarProvider. Throws if called outside of a provider.

const { open, state, setOpen, toggleSidebar } = useSidebar();

SidebarProvider

Wrapper that provides shared open/collapsed state to all sidebar primitives.

SidebarRoot

The main sidebar container. Renders an <aside> with collapsible behavior and a keyboard shortcut.

SidebarHeader

Header section of the sidebar, typically used for branding or user identity.

SidebarContent

Main content area of the sidebar. Houses navigation groups and menus.

SidebarFooter

Footer section of the sidebar, typically used for user profiles or quick actions.

SidebarGroup

Groups related menu items together with an optional label and action.

SidebarGroupLabel

Label heading displayed above a group of menu items.

SidebarGroupContent

Wrapper for the content within a SidebarGroup.

SidebarGroupAction

An optional action button displayed alongside a group label.

SidebarMenu

Container for a list of menu items. Accepts a title prop used as aria-label.

SidebarMenuItem

Individual menu item. Typically wraps SidebarMenuButton and optional action/badge.

SidebarMenuButton

The clickable button inside a menu item. Supports asChild for rendering as a Link.

SidebarMenuAction

An icon-button rendered alongside the menu item, visible on hover.

SidebarMenuBadge

A numeric or text badge displayed alongside a sub-menu item.

SidebarMenuSub

Container for a nested list of sub-menu items. Accepts a title prop for aria-label.

SidebarMenuSubItem

Individual sub-menu item. Wraps SidebarMenuSubButton and optional badge.

SidebarMenuSubButton

The clickable button inside a sub-menu item. Supports asChild for rendering as a Link.

SidebarTrigger

A button that toggles the sidebar open or closed from outside the sidebar.

SidebarRail

A thin interactive rail at the edge of the sidebar that acts as a collapse affordance.

Accessibility

Sidebar is designed to meet WCAG 2.2 AA standards. The sections below document keyboard behavior and ARIA semantics.

Keyboard Interactions

ARIA

• SidebarRoot renders an <aside> element with aria-label="Sidebar expanded" or aria-label="Sidebar collapsed" to reflect current state. Pass a custom aria-label to SidebarRoot to override the default (e.g. aria-label="Primary navigation" when multiple sidebars are on the page).
• SidebarTrigger automatically sets aria-expanded and a state-aware aria-label ("Collapse sidebar" / "Expand sidebar"). It also carries aria-keyshortcuts="Control+b Meta+b" to expose the keyboard shortcut in the AT tree. Override either attribute via props if needed.
• SidebarMenu and SidebarMenuSub accept a title prop that is applied as aria-label on the underlying <ul>. Always pass title to label navigation regions for screen-reader landmark navigation.
• Expandable menu items (disclosure pattern) must carry aria-expanded to announce open/closed state to assistive technology. data-open is a CSS styling hook used by Tailwind selectors (group-data-[open=true]/menu-button) and carries no ARIA semantics. Do not add aria-haspopup — it implies an ARIA menu widget with arrow-key navigation, which SidebarMenuSub is not. Optionally add aria-controls="<submenu-id>" when the submenu element has a stable, persistent ID.
• SidebarMenuAction defaults to aria-label="More actions". Always override with a specific label describing the action in context (e.g. aria-label="More actions for Routing").
• SidebarGroupLabel must use asChild with a semantic heading element (e.g. <h5>) to preserve heading structure for screen-reader navigation.
• SidebarMenuBadge numeric content (e.g. "7") is announced without context. Include the count in the accessible name of the adjacent menu item — for example, aria-label="General, 7 unread" on the SidebarMenuSubButton or link.
• Avatar images used purely as decorative marks or brand icons should use aria-hidden. User-identity avatars (e.g. a profile photo in SidebarFooter) are meaningful and must carry descriptive alt text (e.g. alt="Sophie Richardson") so screen readers can announce whose account is represented.
• Catalyst provides the visual styling; consumers are responsible for meaningful link text, button labels, and ARIA attributes.

See WCAG 2.2 SC 2.1.1 Keyboard and SC 4.1.2 Name, Role, Value for the relevant success criteria.

Choosing the Right Component

Use Sidebar when you need persistent, collapsible application navigation on the side of the viewport. Reach for a different primitive when:

Related

• NavigationMenu
• Sheet
• ScrollArea