Skip to content

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.

<script>
import Sidebar from "@invisible-ui/svelte/Sidebar.svelte";
</script>

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 /> }] }]}
/>
PropTypeDefaultDescription
sections *SidebarSection[]—Groups of items, rendered in order with an optional heading each.
valuestring | nullnullThe current destination's value. The application owns it.
labelstring | undefinedundefinedAccessible name for the navigation landmark. Defaults to the catalog's "Main".
onSelect((value: string) => void) | undefinedundefinedCalled when an item without an href is activated.
mode"inline" | "drawer""inline"How this viewport shows the navigation. The application decides.
collapsedbooleanfalseThe rail: labels hidden from sight, icons kept.
onCollapsedChange((collapsed: boolean) => void) | undefinedundefinedGiven, the rail toggle is rendered and reports every press.
openbooleanfalseWhether the drawer is open (mode="drawer").
onOpenChange((open: boolean) => void) | undefinedundefined
openGroupsstring[] | undefinedundefinedWhich 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) | undefinedundefined
closeOnNavigatebooleantrueWhether following an item closes the drawer.
side"inline-start" | "inline-end""inline-start"Which edge the drawer comes from. Follows the writing direction.
titlestring | undefinedundefinedThe drawer's accessible name. Falls back to label.
renderTriggerbooleantrueWhether the drawer renders its own trigger button.
returnFocusTostring | undefinedundefinedWhere focus goes when a drawer with no trigger of its own closes.
triggerSnippet | undefinedundefinedThe drawer trigger's content (mode="drawer"). Defaults to the catalog's label.
logoSnippet | undefinedundefinedThe logo at the top of the navigation.
footerSnippet | undefinedundefinedThe footer at the bottom of the navigation.

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.

Items take the same destinations as the Navigation Bar, so one list serves both: pass [{ items: destinations }]. In Flutter, SidebarItem.fromDestination maps each one.

  • badge shows its content (a short count) or, without it, a dot. Its label is 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. Set announce: false for 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: no onSelect, 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.

  • The routing. Items with an href are ordinary links. Nothing here intercepts a press or knows about a router.
  • The current destination. You pass value; the component marks it with aria-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.
  • 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 through aria-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 returnFocusTo names.

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.

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)}
/>

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.