Sidebar

The Sidebar is twelve squares wide. Each row is one square high, with half a square of indentation per level. Labels use regular text; counts and supporting information use small text. Disclosure arrows follow their labels. Selection fills the whole row with 2px corners, scaled with the surface.

A sidebar is navigation: the places of an application, every row a link or a button of its own and a stop for Tab, the current destination the page being shown. With tree it is a tree instead: the things inside one of those places, which a person opens, closes and chooses from.

Design examples

Icons, nested labels and counts share compact navigation rows.

<section class="specimen">
<ds-sidebar label="Exhibition navigation" data-showcase-props='{"items":[{"id":"all","label":"All exhibitions","icon":"image","meta":"12","current":true},{"id":"now","label":"On view","expanded":true},{"id":"light","label":"Rooms of light","depth":1,"meta":"24"},{"id":"sound","label":"A place to listen","depth":1,"meta":"8"},{"id":"archive","label":"Archive","icon":"folder"}]}'></ds-sidebar>
</section>
<style>
.specimen { width: 100%; min-width: 0; --cell: calc(20px * var(--sf, 1)); }
.specimen .line { width: 100%; }
.specimen .grow { flex: 1; min-width: 0; }
.specimen .muted { color: var(--ds-text-color-muted); }
.specimen .mono { --ds-typeface-regular: var(--ds-typeface-mono); font-variant-numeric: tabular-nums; }
.specimen .value { width: calc(4 * var(--cell)); text-align: right; }
.specimen .mark { display: inline-flex; align-items: flex-end; width: var(--cell); height: var(--ds-control-height); flex: 0 0 var(--cell); }
.specimen .columns { display: flex; flex-wrap: wrap; gap: var(--cell); }
.specimen .columns > * { min-width: 0; }
.specimen fieldset { border: 0; padding: 0; margin: 0; }
.specimen legend { padding: 0; }
.specimen label { display: flex; align-items: flex-end; gap: calc(var(--cell) / 2); min-height: var(--cell); }
.specimen ds-panel { height: calc(10 * var(--cell)); }
</style>

(function mountShowcase(root) {
  root.querySelectorAll("[data-showcase-props]").forEach((element) => {
    const props = JSON.parse(element.dataset.showcaseProps);
    Object.assign(element, props);
    if (element.localName === "ds-sidebar") {
      let items = props.items;
      const render = () => {
        let collapsedDepth;
        const visible = items.filter((item) => {
          const depth = item.depth ?? 0;
          if (collapsedDepth !== void 0 && depth > collapsedDepth) return false;
          collapsedDepth = item.expanded === false ? depth : void 0;
          return true;
        });
        Object.assign(element, { items: visible });
      };
      element.addEventListener("sidebar-activate", (event) => {
        const id = event.detail.id;
        items = items.map((item) => ({ ...item, current: item.id === id }));
        render();
      });
      element.addEventListener("sidebar-toggle", (event) => {
        const { id, expanded } = event.detail;
        items = items.map((item) => item.id === id ? { ...item, expanded } : item);
        render();
      });
    }
  });
  root.querySelectorAll("ds-token-field").forEach((field) => {
    field.addEventListener("ds-token-commit", (event) => {
      const { text } = event.detail;
      const input = field.querySelector("input");
      if (!input || !text.trim()) return;
      const token = document.createElement("ds-token");
      token.setAttribute("value", text.trim());
      token.setAttribute("label", text.trim());
      token.setAttribute("remove-label", `Remove ${text.trim()}`);
      field.insertBefore(token, input);
      input.value = "";
      input.dispatchEvent(new Event("input", { bubbles: true }));
    });
    field.addEventListener("ds-token-remove", (event) => {
      const token = event.target;
      if (token instanceof Element && token.localName === "ds-token") token.remove();
    });
  });
  window.addEventListener("message", (event) => {
    if (event.origin !== location.origin || event.source !== parent || event.data?.type !== "ds1-example-theme") return;
    requestAnimationFrame(() => root.querySelectorAll("ds-chart, ds-spark, ds-bars").forEach((chart) => {
      chart.refreshTheme?.();
    }));
  });
})(document);

Try it

Open a section, choose a document, or navigate with the arrow keys.

<ds-sidebar label="Library"></ds-sidebar>

const sidebar = document.querySelector('ds-sidebar');
let expanded = true;
let selected = 'overview';
function render() {
  sidebar.items = [
    { id: 'overview', label: 'Overview', current: selected === 'overview' },
    { id: 'projects', label: 'Projects', expanded, meta: '3' },
    ...(expanded ? [
      { id: 'atlas', label: 'Atlas', depth: 1, current: selected === 'atlas' },
      { id: 'harbor', label: 'Harbor', depth: 1, current: selected === 'harbor' },
      { id: 'studio', label: 'Studio', depth: 1, disabled: true, meta: 'Unavailable' },
    ] : []),
    { id: 'guidelines', label: 'Guidelines', current: selected === 'guidelines' },
  ];
}
sidebar.addEventListener('sidebar-toggle', event => { expanded = event.detail.expanded; render(); });
sidebar.addEventListener('sidebar-activate', event => { selected = event.detail.id; render(); });
render();

Data and behaviour

Set the items property to an array of visible rows. Each row has a unique id and a label; optional fields are depth, href, expanded, current, disabled, icon (a name from the icon library), meta, and action: { id, label }. Omit expanded for a leaf. Collapsed children must be omitted from the array.

The application owns the hierarchy, filtering, selected destination and saved expansion state. The Unit owns the row layout, disclosure controls, focus and keyboard navigation. Supply a label for the navigation landmark and empty for its empty state. The header and footer slots hold optional search and supporting controls. When the host has a constrained height, only the navigation rows scroll; header and footer controls stay visible.

Event	Detail	Application response
`sidebar-activate`	`{ id }`	Cancel with `preventDefault()` to handle routing or guard unsaved changes.
`sidebar-toggle`	`{ id, expanded }`	Update the visible items if expansion is accepted.
`sidebar-action`	`{ id, action }`	Run the independent trailing action.

Links retain their native destinations, context menus and modified clicks. Buttons support Enter and Space. Up and Down move between available rows; Home and End move to the first and last. Right expands a closed section or enters its children; Left collapses an open section or moves to its parent. Tab also reaches disclosure and trailing actions.

A label too long for its row ends in an ellipsis and shows in full in the shared tooltip on hover or focus; a label that fits has none, and no row carries the browser’s title. The Sidebar loads the tooltip module itself.

Call focusItem(id) after updateComplete to focus a row, or scrollToCurrent() to reveal the current destination. --ds-sf scales the width, rows, text, icons and indentation. A containing layout may set the host width to another whole number of squares.

The rows’ fills and the current row’s weight are the shared row tokens (--ds-row-fill-hover, --ds-row-fill-current, --ds-row-current-weight), so a navigation row and a tree’s selected row look the same.

In React, Sidebar from react/sidebar.ts takes items, label, empty, tree, onToggle, onSelect, onActivate and onAction.

Tree

Open a folder, choose a file, or move with the arrow keys. Enter or a double click opens a file.

<ds-sidebar tree label="Files"></ds-sidebar>

const tree = document.querySelector('ds-sidebar[tree]');
const files = [
  { id: 'projects', label: 'Projects', icon: 'folder', children: [
    { id: 'atlas', label: 'Atlas', icon: 'folder', children: [{ id: 'intro', label: 'intro.mp4', icon: 'video', meta: '12 MB' }, { id: 'notes', label: 'notes.md', icon: 'page', meta: '2 KB' }] },
    { id: 'harbor', label: 'Harbor', icon: 'folder', children: [{ id: 'plan', label: 'plan.pdf', icon: 'pdf', meta: '340 KB' }] },
  ] },
  { id: 'trash', label: 'Trash', icon: 'delete', children: [] },
];
const open = new Set(['projects', 'atlas']);
let selected = 'notes';
function rows(nodes, depth = 0) {
  return nodes.flatMap(node => [
    { id: node.id, label: node.label, icon: node.icon, meta: node.meta, depth, selected: node.id === selected,
      expanded: node.children ? open.has(node.id) : undefined },
    ...(node.children && open.has(node.id) ? rows(node.children, depth + 1) : []),
  ]);
}
function render() { tree.items = rows(files); }
tree.addEventListener('sidebar-toggle', event => { event.detail.expanded ? open.add(event.detail.id) : open.delete(event.detail.id); render(); });
tree.addEventListener('sidebar-select', event => { selected = event.detail.id; render(); });
tree.addEventListener('sidebar-activate', event => { document.querySelector('#event-output').textContent = 'Opened ' + event.detail.id; });
render();

tree makes the sidebar a tree: folders and files, groups and their samples, a page’s parts. Each row is one square high and each level stands one square further in, so a row’s disclosure arrow stands under its parent’s label. The arrow and an optional icon each take a square of their own; a leaf keeps the arrow’s square empty, so labels at one level line up. The rows are the same items, with selected for the row chosen instead of current; labels are shown as written, never translated.

The application owns the hierarchy, the expansion and the selection. The tree owns the rows’ layout, their roles, the focus and the keyboard.

Event	Detail	Application response
`sidebar-toggle`	`{ id, expanded }`	Show or hide the row’s children and set its `expanded`.
`sidebar-select`	`{ id }`	Set `selected` on that row, and show what it holds.
`sidebar-activate`	`{ id }`	Open the row’s thing: a file in its editor, a sample played.

A click on the arrow opens or closes the row; a click anywhere else selects it, and a double click activates it. itemFromEvent(event) names the row under a context menu or a drag of the application’s own. focusItem(id) moves the focus to a row and scrollToCurrent() brings the selected row into view.

The tree is one stop for Tab: the selected row, or the row last focused. Then, as in the tree pattern: Down and Up move to the next or previous row, skipping unavailable ones; Home and End to the first and last; Right opens a closed row, or moves into an open one; Left closes an open row, or moves to its parent; Space selects; Enter selects and activates; a letter or digit moves to the next row whose label starts with it.

The rows are role="treeitem" inside a role="tree", each with aria-level, aria-setsize and aria-posinset, aria-expanded on a parent and aria-selected on every row. The arrow is drawn, not announced: the row says whether it is open. The pointer over a row fills it as any pressable row, and the selected row is drawn as the current destination. The tree scrolls its rows when its height is constrained.

Whole rows and independent actions

The native link or button covers the whole navigation row, including its empty space. Its text, indentation and disclosure stay in the same place. A section with no href toggles when pressed anywhere; a linked section still navigates and has a separate disclosure button. Optional actions remain independent of both.

An icon action uses the same action event and keeps its accessible label:

sidebar.items = [
  { id: "pages", label: "Pages", expanded: true,
    action: { id: "create", label: "Add page", icon: "plus" } },
  { id: "intro", label: "Introduction", depth: 1, href: "/intro" },
];

Set action.disabled to disable only that action; item.disabled disables all of the row’s controls. No plus button appears unless the application supplies it.

Optional reordering

Set sidebar.reorderable = true to enable desktop HTML drag-and-drop in navigation mode. Drop in the top or bottom half of a sibling row to request a move before or after it. Alt+Up and Alt+Down request the same moves from the keyboard. Set an item’s reorderable: false to exclude it. Disabled rows, other parents, external drags and tree mode are excluded. Touch dragging and reparenting are not implemented.

sidebar-move carries { id, targetId, position: "before" | "after" }. The component never changes or saves items: validate permissions and the hierarchy in the application, move the whole subtree when moving a parent, then replace items if the move is accepted. Keep reorderable false while saving. A rejected request leaves the order intact. After accepting a keyboard move, call focusItem(id) after updateComplete to retain focus. Supply translated keyboard guidance alongside any reorderable surface.

The React adapter exposes reorderable, onMove, expandIcon and collapseIcon as props. These options are off unless supplied; the documentation navigation does not enable editing or reordering.