SidebarCollapsible [pattern] v1.0.0

A persistent left-rail navigation panel that can collapse from a labeled-icon state (240px) to an icon-only state (56px), preserving navigation while reclaiming canvas space. Common in productivity apps where the main canvas is the focus.

Facts

Label

Collapsible Sidebar

Meta

• License: Apache-2.0
• License Provenance: package-authorship-claim

Problem

Application shells need persistent navigation, but full-width sidebars steal horizontal space from the workspace. Users with wide content (tables, editors, canvases) need to reclaim that space without losing wayfinding.

Solution

A two-state sidebar with a collapse toggle. Collapsed state shows only icons with tooltips; expanded state shows icons + labels + nested sections. State persists across sessions per user.

Structure

    <aside aria-label="Primary navigation" data-state="expanded">
      <header>
        <a href="/" aria-label="Home"><img alt="Logo" /></a>
        <button aria-label="Collapse sidebar" aria-expanded="true" aria-controls="sidebar-nav">
          <svg><!-- chevron --></svg>
        </button>
      </header>
      <nav id="sidebar-nav">
        <ul role="list">
          <li>
            <a href="/inbox" aria-current="page">
              <svg aria-hidden="true"><!-- icon --></svg>
              <span class="label">Inbox</span>
              <span class="badge" aria-label="3 unread">3</span>
            </a>
          </li>
          <li>
            <button aria-expanded="true" aria-controls="proj-group">
              <svg aria-hidden="true"></svg>
              <span class="label">Projects</span>
            </button>
            <ul id="proj-group" role="list">
              <li><a href="/p/web">Web</a></li>
            </ul>
          </li>
        </ul>
      </nav>
      <footer>
        <button aria-label="Account menu"><img alt="" /></button>
      </footer>
    </aside>
  

Uses

• @community/method-heuristic-review

Behavior

• Toggle button switches between expanded (240px) and collapsed (56px) states with width transition (180-220ms ease).
• Persist collapsed state to localStorage so the sidebar restores on next visit.
• In collapsed state, hovering an item shows a tooltip with its label after a 500ms delay.
• Mark active route with aria-current=page and a left accent bar or filled background.
• Nested groups use a chevron + aria-expanded; clicking the row toggles the group.
• On viewports under 768px, collapse to a hidden drawer triggered by a hamburger button.

A11y

• Wrap in <aside aria-label='Primary navigation'> so screen readers announce the landmark.
• Collapse button must have aria-expanded and aria-controls pointing to the nav id.
• Active item must use aria-current='page' — not just a CSS class.
• Icon-only collapsed items still need accessible names (aria-label or visually-hidden text).
• Tooltips in collapsed mode must be triggered by focus, not just hover, and dismissible with Escape.

SidebarCollapsible [pattern] v1.0.0

A persistent left-rail navigation panel that can collapse from a labeled-icon state (240px) to an icon-only state (56px), preserving navigation while reclaiming canvas space. Common in productivity apps where the main canvas is the focus.

Facts

Label

Collapsible Sidebar

Meta

• License: Apache-2.0
• License Provenance: package-authorship-claim

Problem

Application shells need persistent navigation, but full-width sidebars steal horizontal space from the workspace. Users with wide content (tables, editors, canvases) need to reclaim that space without losing wayfinding.

Solution

A two-state sidebar with a collapse toggle. Collapsed state shows only icons with tooltips; expanded state shows icons + labels + nested sections. State persists across sessions per user.

Structure

    <aside aria-label="Primary navigation" data-state="expanded">
      <header>
        <a href="/" aria-label="Home"><img alt="Logo" /></a>
        <button aria-label="Collapse sidebar" aria-expanded="true" aria-controls="sidebar-nav">
          <svg><!-- chevron --></svg>
        </button>
      </header>
      <nav id="sidebar-nav">
        <ul role="list">
          <li>
            <a href="/inbox" aria-current="page">
              <svg aria-hidden="true"><!-- icon --></svg>
              <span class="label">Inbox</span>
              <span class="badge" aria-label="3 unread">3</span>
            </a>
          </li>
          <li>
            <button aria-expanded="true" aria-controls="proj-group">
              <svg aria-hidden="true"></svg>
              <span class="label">Projects</span>
            </button>
            <ul id="proj-group" role="list">
              <li><a href="/p/web">Web</a></li>
            </ul>
          </li>
        </ul>
      </nav>
      <footer>
        <button aria-label="Account menu"><img alt="" /></button>
      </footer>
    </aside>
  

Uses

• @community/method-heuristic-review

Behavior

• Toggle button switches between expanded (240px) and collapsed (56px) states with width transition (180-220ms ease).
• Persist collapsed state to localStorage so the sidebar restores on next visit.
• In collapsed state, hovering an item shows a tooltip with its label after a 500ms delay.
• Mark active route with aria-current=page and a left accent bar or filled background.
• Nested groups use a chevron + aria-expanded; clicking the row toggles the group.
• On viewports under 768px, collapse to a hidden drawer triggered by a hamburger button.

A11y

• Wrap in <aside aria-label='Primary navigation'> so screen readers announce the landmark.
• Collapse button must have aria-expanded and aria-controls pointing to the nav id.
• Active item must use aria-current='page' — not just a CSS class.
• Icon-only collapsed items still need accessible names (aria-label or visually-hidden text).
• Tooltips in collapsed mode must be triggered by focus, not just hover, and dismissible with Escape.

Examples

• @community/example-linear-sidebar
• @community/example-notion-sidebar
• @community/example-vercel-sidebar

Relations

related: [@community/pattern-progressive-disclosure, @community/example-vercel-sidebar, @community/check-focus-visible, @community/rule-aria-current-page, @community/rule-aria-label-in-name, @community/check-skip-link, @community/rule-keyboard-tab-order] compatible: [@community/pattern-progressive-disclosure, @community/pattern-command-palette]

Label

Collapsible Sidebar

Meta

• License: Apache-2.0
• License Provenance: package-authorship-claim

Problem

Application shells need persistent navigation, but full-width sidebars steal horizontal space from the workspace. Users with wide content (tables, editors, canvases) need to reclaim that space without losing wayfinding.

Solution

A two-state sidebar with a collapse toggle. Collapsed state shows only icons with tooltips; expanded state shows icons + labels + nested sections. State persists across sessions per user.

Structure

    <aside aria-label="Primary navigation" data-state="expanded">
      <header>
        <a href="/" aria-label="Home"><img alt="Logo" /></a>
        <button aria-label="Collapse sidebar" aria-expanded="true" aria-controls="sidebar-nav">
          <svg><!-- chevron --></svg>
        </button>
      </header>
      <nav id="sidebar-nav">
        <ul role="list">
          <li>
            <a href="/inbox" aria-current="page">
              <svg aria-hidden="true"><!-- icon --></svg>
              <span class="label">Inbox</span>
              <span class="badge" aria-label="3 unread">3</span>
            </a>
          </li>
          <li>
            <button aria-expanded="true" aria-controls="proj-group">
              <svg aria-hidden="true"></svg>
              <span class="label">Projects</span>
            </button>
            <ul id="proj-group" role="list">
              <li><a href="/p/web">Web</a></li>
            </ul>
          </li>
        </ul>
      </nav>
      <footer>
        <button aria-label="Account menu"><img alt="" /></button>
      </footer>
    </aside>
  

Uses

• @community/method-heuristic-review

Behavior

• Toggle button switches between expanded (240px) and collapsed (56px) states with width transition (180-220ms ease).
• Persist collapsed state to localStorage so the sidebar restores on next visit.
• In collapsed state, hovering an item shows a tooltip with its label after a 500ms delay.
• Mark active route with aria-current=page and a left accent bar or filled background.
• Nested groups use a chevron + aria-expanded; clicking the row toggles the group.
• On viewports under 768px, collapse to a hidden drawer triggered by a hamburger button.

A11y

• Wrap in <aside aria-label='Primary navigation'> so screen readers announce the landmark.
• Collapse button must have aria-expanded and aria-controls pointing to the nav id.
• Active item must use aria-current='page' — not just a CSS class.
• Icon-only collapsed items still need accessible names (aria-label or visually-hidden text).
• Tooltips in collapsed mode must be triggered by focus, not just hover, and dismissible with Escape.

Compatible

• @community/pattern-progressive-disclosure
• @community/pattern-command-palette