sidebar

Example

Try the panel button, nested Projects links, workspace switcher, and account control. Desktop icon collapse is explicitly enabled in this example. On mobile, both treatments use the same flush panel with a compact close control. Icons are authored SVG examples, not a dependency or library requirement.

Open docked example · Open inset example

Basic usage — no icons required

This text-only example stays expanded on desktop and becomes a modal panel on narrow containers. Keep the dialog empty and closed in the source: the enhancement moves the existing sidebar into it.

<script type="module" src="sidebar.js"></script>
<m-sidebar-layout variant="docked">
  <m-sidebar id="app-sidebar">
    <header role="presentation">
      <a data-sidebar-item href="/">Your app</a>
      <button type="button" data-sidebar-close aria-label="Close navigation">×</button>
    </header>
    <nav aria-label="Workspace">
      <section>
        <h2>Workspace</h2>
        <a data-sidebar-item href="/overview" aria-current="page">Overview</a>
        <a data-sidebar-item href="/projects">Projects</a>
      </section>
    </nav>
    <footer role="presentation"><a data-sidebar-item href="/account">Account</a></footer>
  </m-sidebar>
  <div data-sidebar-main>
    <header>
      <button type="button" data-sidebar-toggle
              aria-controls="app-sidebar" aria-label="Toggle navigation">Navigation</button>
    </header>
    <main>…page content…</main>
  </div>
  <dialog data-sidebar-dialog aria-label="Workspace navigation"></dialog>
</m-sidebar-layout>

API

An m-avatar inside a named sidebar item counts as its collapsed visual without data-sidebar-icon. Set --avatar-size on the avatar to size it; keep the accompanying text in data-sidebar-label.

Styling

Set these properties on m-sidebar-layout. Semantic surface, text, and border colors come from the normal mica theme.

Enhancement and accessibility

Import sidebar.js to register m-sidebar-layout. The module enhances valid authored markup, adds no icons or links, and has no shared runtime. Below 44rem layout width, it uses a native modal dialog for focus containment and Escape dismissal. Clicking outside or following an ordinary unprevented link also closes the panel. Modified clicks keep their normal behavior.

Desktop collapse state is remembered automatically in a cookie named mica-sidebar- followed by the URL-encoded m-sidebar ID. Keep that ID stable across pages to share the preference; use different IDs for independent sidebars. The cookie stores collapsed or expanded, lasts one year from the last change, and applies across the origin (Path=/, SameSite=Lax, and Secure on HTTPS). Restoration happens when the module connects. Mobile drawers still start closed, and opening or closing them does not change the desktop preference. Invalid collapse anatomy stays expanded without overwriting the cookie. If cookies are unavailable, the sidebar continues to work without persistence.

Set persist="false" on m-sidebar-layout to disable persistence. This leaves any existing cookie untouched; it will be read again on a future connection with persistence enabled.

The layout exposes open(), close(), and toggle(). On mobile they control the dialog; on desktop they expand/collapse the optional rail. Without icon collapse, desktop close() and toggle() leave the panel expanded. Client-side routers that prevent default link navigation can call layout.close() after routing. Mica does not choose the active page or emit custom navigation events.

Without the import, the sidebar remains visible, native links and details work, and inert toggle/close buttons stay hidden. At narrow viewport widths the unenhanced layout stacks its sidebar above content. Missing required controls or dialog anatomy also leaves this fallback intact.

Use a native page header for the banner. Panel header/footer are internal grouping: role="presentation" avoids duplicate page landmarks when they are not nested in a sectioning element. Do not add application-menu roles to navigation links. Keep popovers owned by sidebar controls inside m-sidebar so they move with it and remain usable inside the mobile modal.