Layout primitives

Switcher

<forma-switcher>

Keeps related regions side by side when space permits and stacks them without semantic reordering.

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

Purpose

A switcher holds a primary region and a secondary region in one row while both fit at useful widths, and stacks them as whole blocks when they do not. Unlike a cluster, it never leaves a region squeezed at an awkward in-between width: the primary region wants about 28rem and the secondary about 16rem, and as soon as the row cannot hold both, each takes a full line. The decision comes from the switcher's own width, so it behaves the same in a page, a panel or a dialog.

Use when

  • Two related regions, such as a narrative and its supporting material or a form and its help, should sit side by side on wide screens.
  • The primary region should get most of the extra width when both fit.
  • The switch between row and stack should follow available space, not device type.

Avoid when

  • The secondary region is navigation or a filter list of a preferred width: use Sidebar.
  • You need a fixed start or end rail with a known breakpoint: use Rail.
  • There are more than two regions of equal weight: use Grid.
  • Inline items such as buttons should wrap individually: use Cluster.

Behavior to know

  • Regions are aligned to the start of the cross axis, so a short secondary region does not stretch to the primary region's height.
  • When stacked, both regions are full width and in source order.
  • Minimum sizes are clamped to 100%, so neither region overflows a phone screen.

Basic example

The smallest correct markup: the canonical pattern from patterns/switcher.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal switcher

Rendered from the canonical pattern file.

Primary narrative

The main content owns most available width.

HTML · Minimal switcher Raw HTML for HTML · Minimal switcher
<forma-switcher class="forma-component-tag">
<section class="forma-switcher" aria-label="Narrative and supporting material">
  <article class="forma-switcher__primary"><h2>Primary narrative</h2><p>The main content owns most available width.</p></article>
  <aside class="forma-switcher__secondary" aria-label="Supporting material"><h2>Supporting material</h2><p>Secondary content remains adjacent when space permits.</p></aside>
</section>
</forma-switcher>

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

Examples

Scenario

Form with help text

A payment details form with a help panel. The form is the primary region; the help panel sits beside it on wide screens and below it when the pane narrows.

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.

Bank account

HTML · Form with help text Raw HTML for HTML · Form with help text
<forma-switcher class="forma-component-tag">
  <div class="forma-switcher">
    <form class="forma-switcher__primary forma-stack" aria-labelledby="switcher-form-with-help-title">
      <h2 id="switcher-form-with-help-title">Bank account</h2>
      <div class="forma-field">
        <label class="forma-field__label" for="switcher-form-with-help-holder">Account holder</label>
        <input id="switcher-form-with-help-holder" name="holder" type="text" autocomplete="name">
      </div>
      <div class="forma-field">
        <label class="forma-field__label" for="switcher-form-with-help-iban">IBAN</label>
        <input id="switcher-form-with-help-iban" name="iban" type="text" autocomplete="off" spellcheck="false">
      </div>
      <div class="forma-cluster"><button type="submit">Save account</button></div>
    </form>
    <aside class="forma-switcher__secondary forma-surface" aria-labelledby="switcher-form-with-help-help">
      <h3 id="switcher-form-with-help-help">Where to find your IBAN</h3>
      <p>It is printed on your bank statement and shown in your banking app under account details.</p>
    </aside>
  </div>
</forma-switcher>

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

Scenario

Before and after comparison

A change summary with the current configuration as the primary region and the proposed change as the secondary. A narrower gap is set with --forma-switcher-space.

Current policy

Audit logs are kept for 90 days and then deleted. Exports are available for the full period.

Proposed policy

Keep audit logs for 400 days.

HTML · Before and after comparison Raw HTML for HTML · Before and after comparison
<forma-switcher class="forma-component-tag">
  <section class="forma-switcher" style="--forma-switcher-space: 1rem" aria-label="Retention policy change">
    <article class="forma-switcher__primary forma-surface" aria-labelledby="switcher-comparison-before-after-current">
      <h2 id="switcher-comparison-before-after-current">Current policy</h2>
      <p>Audit logs are kept for 90 days and then deleted. Exports are available for the full period.</p>
    </article>
    <article class="forma-switcher__secondary forma-surface" aria-labelledby="switcher-comparison-before-after-proposed">
      <h2 id="switcher-comparison-before-after-proposed">Proposed policy</h2>
      <p>Keep audit logs for 400 days.</p>
    </article>
  </section>
</forma-switcher>

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 stacked regions

A release note with a supporting download panel at phone width. The row cannot hold both minimums, so the regions stack.

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.

What changes at narrow widths

  • Below roughly 45rem of available width (28rem + 16rem + gap) the regions wrap and each takes the full width.
  • The primary region stays first because it is first in the source.
  • Minimum sizes use min(100%, …), so at 320px neither region forces horizontal scrolling.
  • In landscape on a large phone the regions may fit side by side again; the markup is unchanged.
HTML · Mobile stacked regions Raw HTML for HTML · Mobile stacked regions
<forma-switcher class="forma-component-tag">
  <div class="forma-switcher">
    <article class="forma-switcher__primary forma-stack" aria-labelledby="switcher-mobile-stacked-title">
      <h2 id="switcher-mobile-stacked-title">Version 5.1</h2>
      <p>Offline mode now syncs drafts automatically when the connection returns.</p>
    </article>
    <aside class="forma-switcher__secondary" aria-labelledby="switcher-mobile-stacked-download">
      <h3 id="switcher-mobile-stacked-download">Download</h3>
      <p><a href="#release-5-1">Release notes and installers</a></p>
    </aside>
  </div>
</forma-switcher>

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.

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-labelledbyregionsid of the region heading—Names each region by its visible heading.
aria-label.forma-switcherstring—Names the pair when the switcher element is a section.
style.forma-switcher--forma-switcher-space: <length>—Per-instance gap override.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-switcherBlock class—Wrapping flex container with start-aligned regions.
.forma-switcher__primaryElement class—Primary region: flex basis 28rem, grows strongly, minimum min(100%, 20rem).
.forma-switcher__secondaryElement class—Secondary region: flex basis 16rem, minimum min(100%, 16rem).
--forma-switcher-spaceCustom propertydefault var(--forma-primitive-spacing-5, 1.5rem)Gap between the regions in both directions. Default --forma-primitive-spacing-5 (1.5rem).
--forma-switcher-thresholdCustom propertydefault 42remDeclared with a default of 42rem but not read by any rule; setting it currently has no effect. The switch point comes from the region flex bases.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through the primary region, then the secondary, in source order.

Form behavior

Not a form control.

States

Switcher states
StateHow it is expressedPresentation
Side by siderow holds both flex basesPrimary region takes most of the width; secondary keeps about 16rem.
Stackedrow too narrow for bothEach region is full width, in source order.

Accessibility

Forma provides

  • Never reorders regions; reading, focus and visual order match in both states.
  • Adds no landmarks or roles.
  • Clamped minimum sizes keep both regions inside a 320px viewport.

Your application supplies

  • Put the region users need first earlier in the source.
  • Name aside and section regions so landmarks are distinguishable.
  • Do not place content in the secondary region that must be read before the primary one.

Responsive behavior

  • Container-driven wrap with no media queries: the switch happens when the switcher's own width cannot hold both flex bases.
  • When stacked, both regions stretch to the full row.
  • Long words wrap inside each region; the regions never force page overflow.
  • For a switch point you control exactly, use Rail (fixed 48rem breakpoint).

Motion

  • No animation: regions switch between row and stack instantly.

Usage guidance

Do

  • Use the switcher for exactly two related regions.
  • Keep secondary content short enough to read comfortably at 16rem.

Avoid

  • Relying on --forma-switcher-threshold to control the switch point; it is not wired to any rule.
  • Putting a third child in the switcher; only the primary and secondary element classes are sized.

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.