Sidebar primitive

Headless Sidebar: the behavior, keyboard support and ARIA of the WAI-ARIA Dialog (modal) pattern, with no styles.

@ndop/primitives/sidebar
WAI-ARIA: Dialog (modal)

Import

Primitives ship in the @ndop/primitives package and have no styles. Their state is on data attributes for you to style. The styled Sidebar is built on this one.

import {
  NdSidebarGap,
  NdSidebarMenuButton,
  NdSidebarProvider,
  NdSidebar,
  NdSidebarContainer,
  NdSidebarRail,
  NdSidebarTrigger,
} from '@ndop/primitives/sidebar';

Accessibility

Implements the Dialog (modal) pattern of the WAI-ARIA Authoring Practices.

Keyboard

Keys the component handles.

Key	Action
`Ctrl+b`	Toggles the sidebar (`⌘B` on a Mac), unless `shortcut` is `null`.
`Enter`	On the trigger, toggles the sidebar.
`Escape`	Closes the mobile sidebar and returns focus.
`Tab`	Moves through the sidebar's content; on mobile, it stays inside.

Focus

Opening the mobile sidebar focuses its first focusable element; closing it returns focus to the trigger, or wherever focus was before.
Collapsing the desktop sidebar off-canvas while focus is inside moves focus to the trigger that collapsed it.

Right-to-left

start and end are logical: the start sidebar is on the right in right-to-left layouts, on desktop and on mobile.

API reference

NdSidebarGap

[ndSidebarGap]from @ndop/primitives/sidebar

Keeps the sidebar's room in the page's flow; decorative.

Manages aria-hidden.

NdSidebarMenuButton

[ndSidebarMenuButton]from @ndop/primitives/sidebar

A link or button in the sidebar's menu. active marks the current page with aria-current="page"; on mobile, following it when it's a link closes the sidebar. A button stays put, since it may open a submenu or a menu inside the sidebar.

Manages aria-current.

NdSidebarMenuButton binding	Type	Default
`[active]` Marks the link to the current page.	`boolean`	`false`

Data attribute	Values
`data-active`	—

NdSidebarProvider

[ndSidebarProvider]from @ndop/primitives/sidebar

Holds a sidebar's state for the page around it: expanded or collapsed on desktop, open or closed on mobile, and which applies, from the CDK's BreakpointObserver. Ctrl+B (⌘B on a Mac) toggles it. The server renders the desktop layout.

NdSidebarProvider binding	Type	Default
`[defaultOpen]` Whether the desktop sidebar starts expanded, when `open` isn't bound.	`boolean`	`true`
`[mobileQuery]` The CSS media query below which the sidebar is a mobile dialog.	`string`	`'(max-width: 767.98px)'`
`[shortcut]` The letter that toggles the sidebar with `Ctrl` or `⌘`, or `null`.	`string \| null`	`'b'`
`[(open)]` Whether the desktop sidebar is expanded. Two-way bindable.	`boolean`	`true`
`[(openMobile)]` Whether the mobile sidebar is open. Two-way bindable.	`boolean`	`false`

Data attribute	Values
`data-state`	—
`data-mobile`	—

NdSidebar

[ndSidebar]from @ndop/primitives/sidebar

The sidebar: its side and how it collapses, as data attributes for the styled layer. Its NdSidebarContainer holds the content.

NdSidebar binding	Type	Default
`[side]` The side it sits on: `start` or `end`.	`'start' \| 'end'`	`'start'`
`[collapsible]` How it collapses on desktop.	`'none' \| 'offcanvas' \| 'icon'`	`'offcanvas'`

Data attribute	Values
`data-state`	—
`data-collapsible`	—
`data-side`	—
`data-mobile`	—

NdSidebarContainer

[ndSidebarContainer]role region, dialog on mobilefrom @ndop/primitives/sidebar

The panel holding the sidebar's content: a named landmark (role="region"). Collapsed off-canvas on desktop, it's inert. On mobile it's hidden until opened, then moves into an overlay at its side as a modal dialog with a focus trap, closed by Escape or a backdrop click. Name it with aria-label.

Manages id, aria-modal, inert, hidden.

NdSidebarContainer binding	Type	Default
`[backdropClass]` Classes of the mobile overlay's backdrop.	`string`	`'cdk-overlay-dark-backdrop'`

Data attribute	Values
`data-state`	—
`data-mobile`	—

NdSidebarRail

button[ndSidebarRail]from @ndop/primitives/sidebar

A thin strip along the sidebar's edge that toggles it with the pointer. It repeats the trigger, so it's out of the tab order and hidden from assistive technology.

Manages aria-hidden, tabindex.

NdSidebarTrigger

button[ndSidebarTrigger]from @ndop/primitives/sidebar

The button that toggles the sidebar: the desktop one, or the mobile one on mobile. Name it with text, visible or sr-only.

Manages aria-expanded, aria-controls.

Data attribute	Values
`data-state`	—