Workspaces and shells

Split pane

<forma-split-pane>

Pairs related regions while preserving their semantic ownership and narrow-screen order.

Authoring tag
<forma-split-pane>
Behavior owner
Application content
Canonical source
patterns/split-pane.html

Purpose

A split pane places two related regions side by side: a primary working region that takes most of the width and a secondary region, such as an inspector, preview or reference, beside it. Each child keeps its own semantics (article, aside, section), and the layout is a plain two-track grid that stacks in source order on narrow screens. The same root also carries the presentation hooks for the Resizable split pane, which are documented here because they live on .forma-split-pane; the fixed split has no behavior at all.

Use when

  • Two regions belong to the same task and benefit from being read side by side, such as a form beside its live summary or a document beside its comments.
  • The primary region should get roughly two thirds of the width and the secondary region has a useful minimum width.
  • The narrow-screen order should simply be primary first, secondary second.

Avoid when

Behavior to know

  • Two tracks, minmax(0, 2fr) and minmax(16rem, 1fr) by default, both exposed as custom properties.
  • Every direct child sets min-inline-size: 0, so long content wraps or scrolls instead of widening the page.
  • At 48rem and below both regions stack in one full-width column in source order.

Basic example

The smallest correct markup: the canonical pattern from patterns/split-pane.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 split pane

Rendered from the canonical pattern file.

HTML · Minimal split pane Raw HTML for HTML · Minimal split pane
<forma-split-pane class="forma-component-tag">
<section class="forma-split-pane" aria-label="Inspector workspace">
  <main class="forma-split-pane__primary"><h2>Working surface</h2><p>The primary task remains first in source order.</p></main>
  <aside class="forma-split-pane__secondary" aria-label="Inspector"><h3>Inspector</h3><p>Contextual properties for the current selection.</p></aside>
</section>
</forma-split-pane>

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

Examples

Scenario

Form beside its order summary

A checkout form as the primary region and a live order summary as the secondary aside. Both columns start at the top, and the summary keeps its 16rem minimum.

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.

Shipping address

HTML · Form beside its order summary Raw HTML for HTML · Form beside its order summary
<forma-split-pane class="forma-component-tag">
  <section class="forma-split-pane" aria-label="Checkout">
    <form aria-labelledby="split-pane-form-with-summary-title">
      <h2 id="split-pane-form-with-summary-title">Shipping address</h2>
      <p class="forma-stack">
        <label for="split-pane-form-with-summary-name">Full name</label>
        <input id="split-pane-form-with-summary-name" name="full-name" autocomplete="name">
      </p>
      <p class="forma-stack">
        <label for="split-pane-form-with-summary-street">Street address</label>
        <input id="split-pane-form-with-summary-street" name="street" autocomplete="street-address">
      </p>
      <button type="submit">Continue to payment</button>
    </form>
    <aside aria-labelledby="split-pane-form-with-summary-summary">
      <h3 id="split-pane-form-with-summary-summary">Order summary</h3>
      <dl class="forma-key-value-list">
        <div><dt>Items</dt><dd>3</dd></div>
        <div><dt>Subtotal</dt><dd>$184.00</dd></div>
        <div><dt>Shipping</dt><dd>Calculated next</dd></div>
      </dl>
    </aside>
  </section>
</forma-split-pane>

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

Scenario

Equal-width comparison

Both tracks overridden to equal flexible widths through the custom properties, for reading an original and a proposed revision side by side. The secondary minimum is lowered so the halves stay equal.

Current policy

Refunds are available within 14 days of purchase for unused items.

Proposed policy

Refunds are available within 30 days of purchase for unused items, and within 14 days for opened items with a restocking fee.

HTML · Equal-width comparison Raw HTML for HTML · Equal-width comparison
<forma-split-pane class="forma-component-tag">
  <section class="forma-split-pane" aria-label="Policy revision" style="--forma-split-primary: minmax(0, 1fr); --forma-split-secondary: minmax(0, 1fr)">
    <article aria-labelledby="split-pane-equal-comparison-current">
      <h3 id="split-pane-equal-comparison-current">Current policy</h3>
      <p>Refunds are available within 14 days of purchase for unused items.</p>
    </article>
    <article aria-labelledby="split-pane-equal-comparison-proposed">
      <h3 id="split-pane-equal-comparison-proposed">Proposed policy</h3>
      <p>Refunds are available within 30 days of purchase for unused items, and within 14 days for opened items with a restocking fee.</p>
    </article>
  </section>
</forma-split-pane>

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 reading order

At phone width the reference aside stacks under the article it supports, in the same order as the source.

Viewport width

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

What changes at narrow widths

  • At 48rem and below the grid becomes a single minmax(0, 1fr) column; the 16rem secondary minimum no longer applies, so nothing overflows at 320px.
  • Regions stack in source order, so put the region users need first (usually the primary work) first in the markup.
  • The gap between regions stays at the spacing token; consider a heading in the secondary region so its start is obvious after scrolling.
  • Rotating to landscape on a large phone may cross 48rem and restore the side-by-side layout without changing semantics or focus order.
HTML · Mobile reading order Raw HTML for HTML · Mobile reading order
<forma-split-pane class="forma-component-tag">
  <section class="forma-split-pane" aria-label="Incident write-up">
    <article aria-labelledby="split-pane-mobile-title">
      <h3 id="split-pane-mobile-title">Timeline</h3>
      <p>09:12 Alert fired for elevated error rate. 09:20 Rollback started. 09:31 Error rate normal.</p>
    </article>
    <aside aria-labelledby="split-pane-mobile-aside">
      <h3 id="split-pane-mobile-aside">Runbook</h3>
      <p>Roll back first, investigate second. Page the owning team if the rollback fails.</p>
    </aside>
  </section>
</forma-split-pane>

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-labelroot section, asidestring—Names the split region and the secondary landmark when there is no visible heading to reference.
aria-labelledbychild regionsid of the region heading—Names each region by its visible heading.
stylerootcustom property declarations—Where an application sets --forma-split-primary, --forma-split-secondary or --forma-split-space for one instance.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-split-paneBlock class—Root two-track grid. Direct children are the regions; each is allowed to shrink.
.forma-split-pane__separatorElement class—Resize handle used only with data-forma-resizable; see Resizable split pane. Hidden at 48rem and below.
[data-forma-collapsed]Attribute hook—On a resizable pane, pins the primary track to --forma-split-min, overriding any inline size. The application toggles it and keeps separator values in sync.
[data-forma-manipulation]Attribute hook"resizing"Written by application code during a resize. resizing makes the size track --forma-split-size immediately with no transition. Other values (such as settling) keep the damped settle. Presentation only.
[data-forma-motion-weight]Attribute hook"heavy", "light", "standard"Presentation-only perceived mass for resize settling: light, standard (default) or heavy. Has no effect on a fixed split, which does not animate.
[data-forma-resizable]Attribute hook—Switches the root to a three-track resizable layout (primary, separator, secondary) sized by --forma-split-size. Presentation only; see Resizable split pane.
--forma-split-primaryCustom property—Primary track. Default minmax(0, 2fr).
--forma-split-secondaryCustom property—Secondary track. Default minmax(16rem, 1fr).
--forma-split-spaceCustom property—Gap between regions. Default the 1.5rem spacing token.
--forma-split-sizeCustom property—Resizable only: the application's authoritative primary size. Default 60%.
--forma-split-minCustom property—Resizable only: smallest legal primary size. Default 16rem.
--forma-split-maxCustom property—Resizable only: largest legal primary size. Default calc(100% - 16rem).
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through focusable content in source order, primary region first. A fixed split adds no keyboard behavior.

Form behavior

Not a form control. A form may be one of the regions.

States

Split pane states
StateHow it is expressedPresentation
Side by sideviewport wider than 48remPrimary and secondary tracks with a 1.5rem gap, aligned to the top.
Stacked@media (max-width: 48rem)One column, source order.
Resizabledata-forma-resizableThree-track layout driven by --forma-split-size; documented on Resizable split pane.

Accessibility

Forma provides

  • Never reorders the regions: visual, reading and focus order are the source order at every width.
  • Lets each region shrink so content reflows at 320px and 400% zoom without page-level horizontal scrolling.

Your application supplies

  • Give each region its native semantics (article, aside, section, form) and a heading or accessible name.
  • Put the primary work first in the source.
  • Do not use the split to imply that the secondary content is less important for task completion; on phones it comes after the primary region.

Responsive behavior

  • Wide: var(--forma-split-primary) var(--forma-split-secondary); the secondary region never drops below 16rem until the breakpoint.
  • At 48rem and below: grid-template-columns: minmax(0, 1fr) stacks both regions.
  • Direct children set min-inline-size: 0; wide tables or code inside a region need their own Bounded overflow container.
  • The breakpoint is viewport-based. A split nested in a narrow column on a wide screen stays side by side, so choose Switcher for container-driven reflow.

Motion

  • No animation for a fixed split: the columns change instantly at the breakpoint.
  • With data-forma-resizable the track list settles with the damped inertial model after release or a keyboard step, and tracks directly while data-forma-manipulation="resizing"; see Resizable split pane.

Usage guidance

Do

  • Use the custom properties to change proportions for one instance rather than writing new grid CSS.
  • Keep secondary content useful on its own when it stacks below the primary region.

Avoid

  • Placing a critical action only in the secondary region.
  • Nesting split panes to build a full application frame; use Workspace shell.

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.