Layout primitives

Sidebar

<forma-sidebar>

Composes a supporting region with primary content and deterministic source-order reflow.

Authoring tag
<forma-sidebar>
Behavior owner
Native CSS
Canonical source
patterns/sidebar.html

Purpose

A sidebar pairs a supporting region of a preferred width with a primary region that takes all remaining space. When the primary region would fall below a minimum share of the row, the two regions wrap and stack, in source order, without a breakpoint: the switch is driven by the space the sidebar itself has. A viewport fallback forces one column at phone widths. Use it for settings navigation beside a form, filters beside results, or an article beside its related links.

Use when

  • A secondary region (local navigation, filters, table of contents, metadata) belongs beside the primary content on wide screens.
  • The pair must reflow correctly inside panes of different widths, not only at viewport breakpoints.
  • The supporting region should keep a comfortable width while the primary region absorbs extra space.

Avoid when

  • The supporting column needs a fixed track with a start or end placement and a fixed breakpoint: use Rail.
  • Both regions are roughly equal peers: use Switcher.
  • The whole application frame needs navigation, main and inspector regions: use Workspace shell or Navigation shell.
  • Users resize the two regions: use Split pane with application-owned resize behavior.

Behavior to know

  • Source order decides which region comes first when stacked; Forma never reorders them.
  • The sidebar stretches to the row height by default, so a background or rule runs the full height of the content.
  • Only the two element classes are styled; the regions keep their own semantics (aside, nav, article).

Basic example

The smallest correct markup: the canonical pattern from patterns/sidebar.html inside its public tag. Copy this first, then adapt labels, names and state. This component owns a page's main landmark, so it renders in its own document below.

Canonical

Minimal sidebar

Rendered from the canonical pattern file.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

HTML · Minimal sidebar Raw HTML for HTML · Minimal sidebar
<forma-sidebar class="forma-component-tag">
<section class="forma-sidebar" aria-label="Workspace">
  <aside class="forma-sidebar__side"><nav aria-label="Workspace navigation"><a href="#overview" aria-current="page">Overview</a><a href="#evidence">Evidence</a></nav></aside>
  <main class="forma-sidebar__content" id="overview"><h2>Overview</h2><p>The main region grows while the sidebar preserves a useful measure.</p></main>
</section>
</forma-sidebar>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

Settings with section navigation

Account settings: a local navigation list in the sidebar and a form in the content region. On a wide screen they sit side by side; in a narrow pane the navigation wraps above the form.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

HTML · Settings with section navigation Raw HTML for HTML · Settings with section navigation
<forma-sidebar class="forma-component-tag">
  <div class="forma-sidebar">
    <nav class="forma-sidebar__side" aria-label="Settings sections">
      <ul class="forma-stack" data-density="compact">
        <li><a href="#sidebar-settings-navigation-profile" aria-current="page">Profile</a></li>
        <li><a href="#sidebar-settings-navigation-security">Security</a></li>
        <li><a href="#sidebar-settings-navigation-billing">Billing</a></li>
      </ul>
    </nav>
    <section class="forma-sidebar__content forma-stack" aria-labelledby="sidebar-settings-navigation-profile">
      <h2 id="sidebar-settings-navigation-profile">Profile</h2>
      <div class="forma-field">
        <label class="forma-field__label" for="sidebar-settings-navigation-name">Display name</label>
        <input id="sidebar-settings-navigation-name" name="display-name" type="text" autocomplete="name">
      </div>
      <div class="forma-field">
        <label class="forma-field__label" for="sidebar-settings-navigation-email">Email</label>
        <input id="sidebar-settings-navigation-email" name="email" type="email" autocomplete="email">
      </div>
      <div class="forma-cluster"><button type="submit">Save profile</button></div>
    </section>
  </div>
</forma-sidebar>

Click or tap the code once to select all of it, then copy.

Scenario

Article with related links after it

The article comes first in the source and the related links second, so the sidebar sits at the inline end on wide screens and below the article when stacked. The sidebar width is narrowed with --forma-sidebar-width.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

Rotating API keys without downtime

Issue the new key, deploy it alongside the old one, confirm traffic has moved, then revoke the old key. Each step can be rolled back independently.

Keys issued before March 2026 cannot be rotated in place and must be replaced.

HTML · Article with related links after it Raw HTML for HTML · Article with related links after it
<forma-sidebar class="forma-component-tag">
  <div class="forma-sidebar" style="--forma-sidebar-width: 14rem">
    <article class="forma-sidebar__content forma-stack" aria-labelledby="sidebar-article-end-sidebar-title">
      <h2 id="sidebar-article-end-sidebar-title">Rotating API keys without downtime</h2>
      <p>Issue the new key, deploy it alongside the old one, confirm traffic has moved, then revoke the old key. Each step can be rolled back independently.</p>
      <p>Keys issued before March 2026 cannot be rotated in place and must be replaced.</p>
    </article>
    <aside class="forma-sidebar__side forma-stack" data-density="compact" aria-labelledby="sidebar-article-end-sidebar-related">
      <h3 id="sidebar-article-end-sidebar-related">Related</h3>
      <a href="#key-scopes">Key scopes and permissions</a>
      <a href="#audit-log">Reading the audit log</a>
    </aside>
  </div>
</forma-sidebar>

Click or tap the code once to select all of it, then copy.

Mobile

Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.

Mobile example

Mobile filters above results

A filter panel beside search results. At phone width the viewport fallback makes the sidebar a one-column grid, so filters stack above results in source order.

Static specimen. Submitting or resetting it needs the consuming application's form handling, which this documentation does not have. Its controls are shown for their markup and appearance and cannot be operated here.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • At 30rem and below the sidebar switches to a one-column grid and both regions take the full width.
  • Above that, stacking still happens intrinsically whenever the content region would drop below 60% of the row.
  • Filters come first because they are first in the source; move them after the results in the markup if results should lead on phones.
  • Nothing scrolls horizontally; long filter labels wrap inside the full-width region.
HTML · Mobile filters above results Raw HTML for HTML · Mobile filters above results
<forma-sidebar class="forma-component-tag">
  <div class="forma-sidebar">
    <form class="forma-sidebar__side forma-stack" data-density="compact" aria-label="Filter orders">
      <div class="forma-field">
        <label class="forma-field__label" for="sidebar-mobile-filters-status">Status</label>
        <select id="sidebar-mobile-filters-status" name="status">
          <option>Any status</option>
          <option>Awaiting payment</option>
          <option>Shipped</option>
        </select>
      </div>
      <div class="forma-cluster"><button type="submit">Apply filters</button></div>
    </form>
    <section class="forma-sidebar__content forma-stack" aria-labelledby="sidebar-mobile-filters-results">
      <h2 id="sidebar-mobile-filters-results">24 orders</h2>
      <p>Showing orders from the last 30 days.</p>
    </section>
  </div>
</forma-sidebar>

Click or tap the code once to select all of it, then copy.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

Viewport width

Frames narrower than the selected width show the component at the width available.

API and configuration

Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
aria-label.forma-sidebar__side / regionstring—Names a nav, aside or form in the sidebar so its landmark is distinguishable.
aria-labelledbyregionsid of the region heading—Names a region by its visible heading.
aria-currentnavigation linkpage—Marks the current section in sidebar navigation.
style.forma-sidebar--forma-sidebar-width / --forma-sidebar-content-min / --forma-sidebar-space—Per-instance override of the sidebar's preferred width, content minimum or gap.
data-densitynested .forma-stackcompact—Used on stacks inside the regions; it does not affect the sidebar itself.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-sidebarBlock class—Wrapping flex container for the two regions.
.forma-sidebar__contentElement class—Primary region. Absorbs remaining space and wraps below or above the side when it would be narrower than --forma-sidebar-content-min.
.forma-sidebar__sideElement class—Supporting region. Grows from --forma-sidebar-width but yields to the content region.
--forma-sidebar-content-minCustom propertydefault 60%Minimum share of the row the content region keeps before the pair stacks. Default 60%.
--forma-sidebar-spaceCustom propertydefault var(--forma-primitive-spacing-5, 1.5rem)Gap between the regions, in both directions. Default --forma-primitive-spacing-5 (1.5rem).
--forma-sidebar-widthCustom propertydefault 18remPreferred width of the side region. Default 18rem.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through the side region and then the content region, or the reverse, following source order.

Form behavior

Not a form control. A form may be either region.

States

Sidebar states
StateHow it is expressedPresentation
Side by sidecontent region can keep at least --forma-sidebar-content-minSide region at its preferred width, content region fills the rest.
Stacked (intrinsic)content would fall below the minimumRegions wrap onto separate rows in source order; each takes the full row.
Stacked (viewport)viewport at or below 30remOne-column grid with both regions at full width.

Accessibility

Forma provides

  • Never reorders regions, so reading, focus and visual order match at every width (verified by the composition browser tests).
  • Adds no landmarks; regions keep the semantics of the elements the author chooses.
  • Contained reflow means no horizontal page scrolling at 320px.

Your application supplies

  • Choose the source order deliberately: whichever region comes first is read first and shown first when stacked.
  • Label navigation, aside and form regions so multiple landmarks can be told apart.
  • Mark the current item in sidebar navigation with aria-current.

Responsive behavior

  • Container-driven: stacking happens when the sidebar's own inline size cannot hold the side width plus the content minimum.
  • Viewport fallback at 30rem converts the layout to a one-column grid.
  • Both regions can contain long content; the content region has a minimum of min(100%, 60%), so it never overflows the row.
  • Place wide tables in the content region inside Bounded overflow.

Motion

  • No animation: regions wrap instantly when space changes.

Usage guidance

Do

  • Keep the sidebar region short and supportive; the primary task belongs in the content region.
  • Use the same sidebar composition in panes and full pages; it adapts to its own width.

Avoid

  • Using CSS order to put the sidebar after the content on phones; change the source order instead.
  • Putting the only path to critical actions in the sidebar where it may be far from the content when stacked.

Verification specimens

Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.