Workspaces and shells

Resizable split pane

<forma-resizable-split-pane>

Split pane whose application-supplied size tracks drag or keys directly, settles without overshoot, and is clamped to legal bounds in CSS.

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

Purpose

A resizable split pane is a Split pane with data-forma-resizable and a focusable role="separator" between the two regions. The application owns the size: pointer drag, Arrow-key steps, collapse, reset and persistence are Limen or application code that writes one custom property, --forma-split-size. Forma turns that value into a three-track grid, clamps it to --forma-split-min and --forma-split-max so no illegal size is ever drawn, tracks it immediately while data-forma-manipulation="resizing", and settles with a damped, non-overshooting transition otherwise. Without application code the separator is focusable but inert.

Use when

  • Users genuinely need to trade space between two regions, such as a code editor and its preview or a document and a long inspector.
  • The application can implement pointer and keyboard resizing through one shared size value and persist it.
  • Both regions have a meaningful minimum width that must never be violated.

Avoid when

  • A fixed proportion is good enough: use Split pane, which needs no script.
  • There is no application or Limen code to implement dragging and keys; an inert separator is a false affordance.
  • The layout is mainly for phones; the separator is hidden at 48rem and below and the panes stack.
  • Users need to hide a panel entirely rather than resize it: use a Disclosure or a Flyout.

Behavior to know

  • The drawn size is clamp(var(--forma-split-min), var(--forma-split-size), var(--forma-split-max)), so bounds are enforced in CSS even mid-transition.
  • Direct phase: while data-forma-manipulation="resizing" the transition duration is 0ms and the primary width equals the written size on the same frame.
  • Keyboard and pointer resizing write the same property and therefore end in the same state.
  • The separator is a 2.75rem-wide hit area with a 2px visible line and a two-tone focus ring.

Basic example

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

Canonical

Minimal resizable split pane

Rendered from the canonical pattern file.

Working surface

The application owns the primary size and writes it to --forma-split-size; CSS clamps it to the legal bounds.

HTML · Minimal resizable split pane Raw HTML for HTML · Minimal resizable split pane
<forma-resizable-split-pane class="forma-component-tag">
<section class="forma-split-pane" data-forma-resizable aria-label="Inspector workspace" style="--forma-split-size: 62%">
  <div class="forma-split-pane__primary" id="resizable-primary">
    <h2>Working surface</h2>
    <p>The application owns the primary size and writes it to <code>--forma-split-size</code>; CSS clamps it to the legal bounds.</p>
  </div>
  <div class="forma-split-pane__separator" role="separator" tabindex="0" aria-orientation="vertical" aria-controls="resizable-primary" aria-label="Resize working surface" aria-valuemin="30" aria-valuemax="80" aria-valuenow="62"></div>
  <aside class="forma-split-pane__secondary" aria-label="Inspector">
    <h3>Inspector</h3>
    <p>Pointer drag and Arrow keys are Limen/application behavior. Both write the same size, so they end in the same state.</p>
  </aside>
</section>
</forma-resizable-split-pane>

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

Examples

Scenario

Collapsed to the minimum

The application has collapsed the primary region with data-forma-collapsed, which pins it to --forma-split-min even though an inline size is still set, giving the preview the remaining width. The separator's aria-valuenow reports the collapsed value and it stays focusable so the user can restore it.

Template source

Source editor collapsed to its minimum width.

HTML · Collapsed to the minimum Raw HTML for HTML · Collapsed to the minimum
<forma-resizable-split-pane class="forma-component-tag">
  <section class="forma-split-pane" data-forma-resizable data-forma-collapsed aria-label="Template editor" style="--forma-split-size: 58%">
    <div id="resizable-split-pane-collapsed-editor-source">
      <h2>Template source</h2>
      <p>Source editor collapsed to its minimum width.</p>
    </div>
    <div class="forma-split-pane__separator" role="separator" tabindex="0" aria-orientation="vertical" aria-controls="resizable-split-pane-collapsed-editor-source" aria-label="Resize template source" aria-valuemin="25" aria-valuemax="75" aria-valuenow="25" aria-valuetext="Collapsed"></div>
    <aside aria-label="Rendered preview">
      <h3>Rendered preview</h3>
      <p>Hello Amara, your order #48213 has shipped and will arrive on Thursday.</p>
    </aside>
  </section>
</forma-resizable-split-pane>

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

Scenario

Mid-drag with custom bounds

A snapshot of the direct phase: the application has set data-forma-manipulation="resizing" and writes --forma-split-size on every pointer move. The instance narrows the legal range with --forma-split-min and --forma-split-max, and a requested 90% is clamped to the maximum.

Log stream

14:02:11 worker-3 retrying job 88213 (attempt 2 of 5)

HTML · Mid-drag with custom bounds Raw HTML for HTML · Mid-drag with custom bounds
<forma-resizable-split-pane class="forma-component-tag">
  <section class="forma-split-pane" data-forma-resizable data-forma-manipulation="resizing" aria-label="Log explorer" style="--forma-split-size: 90%; --forma-split-min: 12rem; --forma-split-max: calc(100% - 12rem)">
    <div id="resizable-split-pane-active-drag-logs">
      <h2>Log stream</h2>
      <p>14:02:11 worker-3 retrying job 88213 (attempt 2 of 5)</p>
    </div>
    <div class="forma-split-pane__separator" role="separator" tabindex="0" aria-orientation="vertical" aria-controls="resizable-split-pane-active-drag-logs" aria-label="Resize log stream" aria-valuemin="20" aria-valuemax="80" aria-valuenow="80"></div>
    <aside aria-label="Log entry details">
      <h3>Entry details</h3>
      <p>Job 88213 · queue billing-sync</p>
    </aside>
  </section>
</forma-resizable-split-pane>

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

Scenario

Heavy settling weight

data-forma-motion-weight="heavy" gives the settle after release or a keyboard step a slower, more damped response for a large, content-heavy pane. Weight is presentation only and never signals importance.

Master services agreement

Section 7.2: Either party may terminate for convenience with 90 days' written notice.

HTML · Heavy settling weight Raw HTML for HTML · Heavy settling weight
<forma-resizable-split-pane class="forma-component-tag">
  <section class="forma-split-pane" data-forma-resizable data-forma-motion-weight="heavy" aria-label="Contract review" style="--forma-split-size: 55%">
    <div id="resizable-split-pane-heavy-settle-contract">
      <h2>Master services agreement</h2>
      <p>Section 7.2: Either party may terminate for convenience with 90 days' written notice.</p>
    </div>
    <div class="forma-split-pane__separator" role="separator" tabindex="0" aria-orientation="vertical" aria-controls="resizable-split-pane-heavy-settle-contract" aria-label="Resize agreement" aria-valuemin="30" aria-valuemax="80" aria-valuenow="55"></div>
    <aside aria-label="Reviewer comments">
      <h3>Comments</h3>
      <p>Legal: 90 days is longer than our standard 60.</p>
    </aside>
  </section>
</forma-resizable-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 without a separator

At phone width the resizable pane stacks and the separator is hidden, because there is no meaningful horizontal size to adjust.

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 column and .forma-split-pane__separator is display: none, so it leaves the tab order and the accessibility tree.
  • --forma-split-size is ignored while stacked; the saved desktop size is kept by the application and applies again when the viewport widens.
  • There is no touch resize on phones. If a region needs to be hidden to save space, offer a Disclosure or a button, not a gesture.
  • Landscape on a tablet can cross 48rem and restore the separator; its 2.75rem-wide hit area and touch-action: none are there for touch dragging handled by the application.
HTML · Mobile without a separator Raw HTML for HTML · Mobile without a separator
<forma-resizable-split-pane class="forma-component-tag">
  <section class="forma-split-pane" data-forma-resizable aria-label="Query editor" style="--forma-split-size: 50%">
    <div id="resizable-split-pane-mobile-query">
      <h2>Query</h2>
      <p><code>select region, sum(total) from orders group by region</code></p>
    </div>
    <div class="forma-split-pane__separator" role="separator" tabindex="0" aria-orientation="vertical" aria-controls="resizable-split-pane-mobile-query" aria-label="Resize query" aria-valuemin="30" aria-valuemax="70" aria-valuenow="50"></div>
    <aside aria-label="Query results">
      <h3>Results</h3>
      <p>4 rows · 38 ms</p>
    </aside>
  </section>
</forma-resizable-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
data-forma-resizableroot .forma-split-panebooleanabsentRequired. Switches the split to the three-track resizable layout.
styleroot--forma-split-size (and optional --forma-split-min, --forma-split-max)--forma-split-size: 60%The application writes the authoritative primary size here, usually restored from saved preferences.
roleseparatorseparator—Required. A focusable separator is announced as a window splitter with a value.
tabindexseparator0—Makes the separator focusable so keyboard users can resize.
aria-orientationseparatorverticalhorizontal for separatorThe separator line runs vertically between side-by-side panes.
aria-controlsseparatorid of the primary region—Identifies the region whose size the separator changes.
aria-labelseparatorstring—Names what is being resized, for example "Resize working surface".
aria-valuenowseparatornumber—Current primary size in the application's unit (usually percent). The application must update it together with --forma-split-size.
aria-valueminseparatornumber—Smallest legal size. Keep it consistent with --forma-split-min.
aria-valuemaxseparatornumber—Largest legal size. Keep it consistent with --forma-split-max.
aria-valuetextseparatorstring—Optional human wording such as "Collapsed" when a number alone is unclear.
data-forma-manipulationrootresizingabsentSet by the application only while a drag is in progress; removed on release so the pane settles.
data-forma-collapsedrootbooleanabsentSet by the application to pin the primary region to its minimum.
data-forma-motion-weightrootlight | standard | heavystandardPresentation-only settle weight.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-split-paneBlock class—Root. With data-forma-resizable its tracks are clamped primary size, separator, remaining space.
.forma-split-pane__separatorElement class—The handle: 2.75rem-wide hit area, 2px drawn line, col-resize cursor and touch-action: none so application pointer handling is not interrupted by scrolling.
[data-forma-resizable]Attribute hook—Enables the resizable track list and the settle transition.
[data-forma-manipulation]Attribute hook—resizing removes the transition and shows a col-resize cursor, so the pane follows the written size exactly.
[data-forma-collapsed]Attribute hook—Overrides the track list to var(--forma-split-min) auto minmax(0, 1fr), winning over the inline size.
[data-forma-motion-weight]Attribute hook—Light, standard or heavy settle response.
--forma-split-sizeCustom property—Authoritative primary size written by the application. Default 60%.
--forma-split-minCustom property—Minimum legal primary size. Default 16rem.
--forma-split-maxCustom property—Maximum legal primary size. Default calc(100% - 16rem), which reserves 16rem for the secondary region.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves focus to and from the separator. This is the only native behavior; the separator is a focusable div.
Left / Right ArrowApplication or Limen must implement: step the size down or up and write --forma-split-size and aria-valuenow.
Home / EndApplication or Limen should implement: jump to the minimum or maximum legal size.
EnterApplication or Limen may implement: toggle data-forma-collapsed and restore the previous size.

Form behavior

Not a form control. Persisting the size is application state, not form data.

States

Resizable split pane states
StateHow it is expressedPresentation
Restingdata-forma-resizable with --forma-split-sizePrimary width is the clamped size; changes settle with a damped inertial transition.
Resizingdata-forma-manipulation="resizing"No transition: the width tracks every write immediately, with a col-resize cursor.
Collapseddata-forma-collapsedPrimary pinned to --forma-split-min, regardless of the inline size.
Clamped--forma-split-size outside min/maxDrawn at the nearest legal bound; the application should also clamp its stored value and aria-valuenow.
Separator focus:focus-visible on .forma-split-pane__separatorTwo-tone inset ring on the handle.
Stacked@media (max-width: 48rem)Single column; the separator is hidden.

Accessibility

Forma provides

  • Provides a separator hit area at least 44px wide and tall, and a visible focus ring that works on light and dark surfaces.
  • Clamps the drawn size to legal bounds in CSS, so users never see a pane narrower than its minimum.
  • Draws the separator line in CanvasText under forced colors.
  • Stacks the panes and removes the separator at narrow widths so small screens do not depend on resizing.

Your application supplies

  • Implement keyboard resizing (Arrow keys at minimum) on the focused separator; resizing must never require a pointer drag.
  • Keep aria-valuenow, aria-valuemin and aria-valuemax in sync with --forma-split-size and the CSS bounds.
  • Label the separator with what it resizes and point aria-controls at the primary region.
  • Offer a way to reset the size (for example Enter or a double-click handled by the application) and persist the user's choice if expected.
  • Keep focus on the separator after keyboard steps and after collapse or restore.

Responsive behavior

  • Wide: clamp(var(--forma-split-min), var(--forma-split-size), var(--forma-split-max)) auto minmax(0, 1fr) with no column gap; the separator provides the spacing.
  • At 48rem and below: one column; the separator is not displayed.
  • Percent sizes are relative to the pane, so the same saved value adapts to different window widths, still within bounds.
  • Both regions shrink with min-inline-size: 0; wide content inside needs its own Bounded overflow region.

Motion

  • Direct manipulation: while data-forma-manipulation="resizing" the transition duration is --forma-motion-direct-duration (0ms), so there is no pointer lag.
  • Settling after release, a keyboard step or collapse animates grid-template-columns with the inertial duration and the damped easing: no overshoot, and a new write re-targets from the current position.
  • Because the track list is clamped, the settle can never pass through an illegal size.
  • data-forma-motion-weight changes perceived mass for the settle only.
  • Under prefers-reduced-motion: reduce the transition is 0.01ms, so the pane jumps directly to its final size.

Usage guidance

Do

  • Write a single size value from both pointer and keyboard code paths so they always agree.
  • Choose bounds that keep both regions usable, and mirror them in the separator's aria values.

Avoid

  • Shipping the separator without keyboard support or without any application behavior.
  • Animating during the drag itself; remove data-forma-manipulation only on release.
  • Using a resizable split when neither region benefits from more width.

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.