Sidebar
The application’s side navigation: an optional logo, labelled sections of
items (icon and label), and a footer. Items are links when given an href,
otherwise buttons that report onSelect. Sections can collapse, the bar itself
can collapse to a rail of icons, and on a narrow viewport the same navigation
goes inside a sheet.
Import
Section titled “Import”<script> import Sidebar from "@invisible-ui/svelte/Sidebar.svelte";</script><script setup> import { Sidebar } from "@invisible-ui/vue";</script>import { Sidebar } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-sidebar></ds-sidebar>In Elements, assign the sections as a property. Icons are SVG path data on a
24 by 24 grid. Items without an href emit select; every item emits
navigate. For a drawer, put the element inside a <ds-sheet-dialog> and
close it on navigate.
<ds-sidebar label="Primary" value="home" rail-toggle> <img slot="logo" src="/logo.svg" alt="Dromio" /> <ds-avatar slot="footer" name="Ada Lovelace"></ds-avatar></ds-sidebar>
<script type="module"> const sidebar = document.querySelector("ds-sidebar"); sidebar.sections = [ { items: [{ value: "home", label: "Home", icon: "M3 12l9-9 9 9M5 10v10h14V10" }] }, ]; sidebar.addEventListener("select", ({ detail }) => { sidebar.value = detail.value; });</script>In React, an icon is any element, logo and footer take markup, and the
rail toggle keeps one name (“Collapse the navigation”) while aria-pressed
says whether the rail is closed. A drawer is mode="drawer", the same
navigation inside a SheetDialog.
<Sidebar label="Primary" value={current} onSelect={setCurrent} collapsed={collapsed} onCollapsedChange={setCollapsed} logo={<img src="/logo.svg" alt="Dromio" />} sections={[{ items: [{ value: "home", label: "Home", icon: <HomeIcon /> }] }]}/>| Prop | Type | Default | Description |
|---|---|---|---|
sections * | SidebarSection[] | — | Groups of items, rendered in order with an optional heading each. |
value | string | null | null | The current destination's value. The application owns it. |
label | string | undefined | undefined | Accessible name for the navigation landmark. Defaults to the catalog's "Main". |
onSelect | ((value: string) => void) | undefined | undefined | Called when an item without an href is activated. |
mode | "inline" | "drawer" | "inline" | How this viewport shows the navigation. The application decides. |
collapsed | boolean | false | The rail: labels hidden from sight, icons kept. |
onCollapsedChange | ((collapsed: boolean) => void) | undefined | undefined | Given, the rail toggle is rendered and reports every press. |
open | boolean | false | Whether the drawer is open (mode="drawer"). |
onOpenChange | ((open: boolean) => void) | undefined | undefined | |
openGroups | string[] | undefined | undefined | Which sections are open, by id. Given it, the application owns the set and this component only reports presses; left out, the component keeps the set itself and opens the section holding the current item. |
onOpenGroupsChange | ((openGroups: string[]) => void) | undefined | undefined | |
closeOnNavigate | boolean | true | Whether following an item closes the drawer. |
side | "inline-start" | "inline-end" | "inline-start" | Which edge the drawer comes from. Follows the writing direction. |
title | string | undefined | undefined | The drawer's accessible name. Falls back to label. |
renderTrigger | boolean | true | Whether the drawer renders its own trigger button. |
returnFocusTo | string | undefined | undefined | Where focus goes when a drawer with no trigger of its own closes. |
trigger | Snippet | undefined | undefined | The drawer trigger's content (mode="drawer"). Defaults to the catalog's label. |
logo | Snippet | undefined | undefined | The logo at the top of the navigation. |
footer | Snippet | undefined | undefined | The footer at the bottom of the navigation. |
| Prop | Type | Default | Description |
|---|---|---|---|
sections * | SidebarSection[] | — | |
value | string | null | null | The current destination's value. The application owns it. |
label | string | undefined | Accessible name for the navigation landmark. Defaults to the catalog's "Main". |
onSelect | (value: string) => void | undefined | |
mode | "inline" | "drawer" | "inline" | |
collapsed | boolean | false | |
onCollapsedChange | (collapsed: boolean) => void | undefined | Given, the rail toggle is rendered and reports every press, as long as every destination carries an icon: without one there would be nothing to show once the labels are hidden. |
open | boolean | false | |
onOpenChange | (open: boolean) => void | undefined | |
openGroups | string[] | undefined | |
onOpenGroupsChange | (openGroups: string[]) => void | undefined | |
closeOnNavigate | boolean | true | |
side | "inline-start" | "inline-end" | "inline-start" | |
title | string | undefined | |
renderTrigger | boolean | true | |
returnFocusTo | string | undefined |
Slots: footer, logo, trigger.
| Prop | Type | Default | Description |
|---|---|---|---|
sections * | SidebarSection[] | — | Groups of items, rendered in order with an optional heading each. |
value | string | null | null | The current destination's value. The application owns it. |
label | string | — | Accessible name for the navigation landmark. Defaults to the catalog's "Main". |
onSelect | (value: string) => void | — | Called when an item without an href is activated. |
mode | "inline" | "drawer" | "inline" | How this viewport shows the navigation. The application decides. |
collapsed | boolean | — | The rail: labels hidden from sight, icons kept. |
onCollapsedChange | (collapsed: boolean) => void | — | Given, the rail toggle is rendered and reports every press, as long as every destination carries an icon: without one there would be nothing to show once the labels are hidden. |
open | boolean | — | Whether the drawer is open (mode="drawer"). |
onOpenChange | (open: boolean) => void | — | |
openGroups | string[] | — | Which sections are open, by id. Given it, the application owns the set and this component only reports presses; left out, the component keeps the set itself and opens the section holding the current item. |
onOpenGroupsChange | (openGroups: string[]) => void | — | |
closeOnNavigate | boolean | true | Whether following an item closes the drawer. |
side | "inline-start" | "inline-end" | "inline-start" | Which edge the drawer comes from. Follows the writing direction. |
title | string | — | The drawer's accessible name. Falls back to label. |
renderTrigger | boolean | true | Whether the drawer renders its own trigger button. |
returnFocusTo | string | — | Where focus goes when a drawer with no trigger of its own closes. |
trigger | ReactNode | — | The drawer trigger's content (mode="drawer"). Defaults to the catalog's label. |
logo | ReactNode | — | The logo at the top of the navigation. |
footer | ReactNode | — | The footer at the bottom of the navigation. |
| Attribute | Reactive | Description |
|---|---|---|
label | yes | the landmark name; "Main" by default |
value | yes | the current destination |
collapsed | yes | the rail |
rail-toggle | yes | renders the button that collapses and expands the rail |
side | yes | inline-start|inline-end |
collapse-label | yes | the rail toggle's name, the same in both states: the button reports the rail through aria-pressed |
Reactive attributes re-render the element when they change after the first render.
Properties: sections, value, openGroups (ids of the open sections).
Emits: bubbling select (detail.value, items without href), navigate (detail.value, every item), collapsed-change (detail.collapsed) and open-groups-change (detail.openGroups).
Every href is rendered as given: pass only URLs you trust or have
sanitized. See Security.
A section becomes a disclosure with collapsible: true, a label and an
id. The id is the name it answers to in openGroups: two sections may share
a label, and sharing a name would mean sharing an open state. A missing or
repeated id is an error in development.
Badges and unavailable destinations
Section titled “Badges and unavailable destinations”Items take the same destinations as the
Navigation Bar, so one
list serves both: pass [{ items: destinations }]. In Flutter,
SidebarItem.fromDestination maps each one.
badgeshows itscontent(a short count) or, without it, a dot. Itslabelis required: it is part of the item’s name (“Alerts, 3 unread”), and when it appears or changes the sidebar announces it once, politely (“Alerts: 3 unread”). Nothing is announced on the first render or when a badge goes away. Setannounce: falsefor a count that changes often. While a modal dialog outside the sidebar is open the announcement waits, and the latest one per item is made after the last one closes (ADR 0016). A sidebar inside its own drawer is on screen, so it announces.unavailable: { reason }keeps the item visible and focusable, shows a lock and the reason under the label, and reads the reason as the item’s description. Activating it does nothing: noonSelect, no link followed, no drawer closed. To hide a destination instead, leave it out of the list. Which of the two fits is your product’s choice; neither is the default.
On the rail the badge sits on the icon and its text stays in the name; the lock
sits at the icon’s lower corner, and the tooltip reads “Billing: Ask an
administrator for access” (sidebar.unavailableTooltip).
<Sidebar value={current} onSelect={go} sections={[ { items: [ { value: "inbox", label: "Inbox", icon: Inbox, badge: { label: "3 unread", content: "3" } }, { value: "billing", label: "Billing", icon: Card, unavailable: { reason: "Ask an administrator for access" }, }, ], }, ]}/>The rail needs an icon on every destination
Section titled “The rail needs an icon on every destination”Collapsing hides the labels, so a destination with no icon would be a control
with an accessible name and nothing to see. Rather than invent a glyph, the
component declines: with any destination lacking an icon the toggle is not
rendered, collapsed keeps the labels, and development says why.
What stays with your application
Section titled “What stays with your application”- The routing. Items with an
hrefare ordinary links. Nothing here intercepts a press or knows about a router. - The current destination. You pass
value; the component marks it witharia-current="page"and never works it out for itself. - The breakpoint policy. You pass
mode. The component reads no media query, so the viewport where navigation becomes a drawer is yours to choose.
Accessibility
Section titled “Accessibility”- A
<nav>landmark with a name (label, or the catalog’s “Main”). Two landmarks of the same kind on one page need different names. - Items are links and buttons in a list, so Tab reaches every one of them.
There is no roving tabindex and no
role="menu": this is navigation, not a menu of actions. - A collapsible section is a disclosure button over its list
(
aria-expanded,aria-controls). - The rail toggle is
aria-pressed, because collapsing hides names from sight and not from a screen reader: every destination keeps its accessible name, and a tooltip shows it on hover or focus. The tooltip sits at the inline end of the destination: on the left in right-to-left text. - The current destination is never marked by colour alone: its label is bold, and on the rail a bar marks it at the inline start. A badge is a count or a dot shape with its text in the name; under forced colors it keeps a border.
- An unavailable item carries
aria-disabled="true"and its reason througharia-describedby; it stays in the tab order so the reason can be heard. - Badge changes are announced through one
aria-live="polite"region inside the landmark. - Assistive technology: not tested. What VoiceOver, NVDA and TalkBack say for the badge, its announcement and the reason has no dated session yet.
- As a drawer the navigation is a modal sheet: focus moves in and is trapped,
and Escape closes it. Focus returns to the trigger, or, when the button
belongs to your page, to whatever
returnFocusTonames.
Styling hooks
Section titled “Styling hooks”The root carries data-mode (inline or drawer), data-side, and
data-collapsed while the rail is closed. Each destination carries
data-current when it is the current one and data-unavailable when it cannot
open, and each collapsible section carries data-state (open or closed).
The badge reads --ds-sidebar-badge-surface and --ds-sidebar-badge-text,
which fall back to the danger and on-status roles.
Sections that open themselves
Section titled “Sections that open themselves”Left alone, the section holding the current destination opens, so the page
never hides where you are, whether the destination moved or the sections did.
Pass openGroups and that stops: the set is yours, a press is reported through
onOpenGroupsChange and changes nothing until you say so, and neither a change
of value nor a change of sections moves anything.
This is the one place a control here does not answer its own press
(ADR 0011 and ADR 0013). Handing the set back as undefined is supported: the
sidebar continues from what was on screen.
<Sidebar {sections} value={current} openGroups={open} onOpenGroupsChange={(next) => (open = next)}/>The drawer, and where its button lives
Section titled “The drawer, and where its button lives”By default the drawer renders its own trigger where you place the component.
When the button belongs to your header instead, turn the trigger off, drive
open yourself, and name the element focus should return to.
<button id="menu-button" onclick={() => (open = true)}>Menu</button>
<Sidebar {sections} mode="drawer" {open} renderTrigger={false} returnFocusTo="#menu-button" onOpenChange={(next) => (open = next)}/>Themeable via --ds-sidebar-*; the former --ds-menu-* names still work.