Layout primitives

Cluster

<forma-cluster>

Wraps related inline items while preserving semantic source order.

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

Purpose

A cluster places related items in a row and lets them wrap onto further rows when the row runs out of space. It is the primitive for action rows, tag and status sets, metadata lines and filter chips: groups whose members are peers and whose count or label length is not known in advance. Items are vertically centered on each line and separated by one gap in both directions. Wrapping is intrinsic, so the same markup works in a toolbar, a card footer and a phone-width panel.

Use when

  • A small set of related actions should sit in one row and wrap when labels are long or the container is narrow.
  • Metadata, status lozenges or tags describe one object and should read as one line when they fit.
  • The number of items varies with data and the layout must not depend on a fixed column count.

Avoid when

  • Items are a vertical sequence: use Stack.
  • Items are peers that should align into columns: use Grid.
  • Commands must be grouped by purpose with a visible group label: use Command group.
  • Too many actions compete for one row and some should collapse behind a disclosure: use Overflow command disclosure.

Behavior to know

  • Wrapping follows source order: the first item is always first, and wrapped items continue on the next line in the inline direction.
  • One gap value applies both between items and between wrapped lines.
  • Items keep their intrinsic width; the cluster never stretches or shrinks them to fill the row.

Basic example

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

Canonical

Minimal cluster

Rendered from the canonical pattern file.

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.

View details
HTML · Minimal cluster Raw HTML for HTML · Minimal cluster
<forma-cluster class="forma-component-tag">
<div class="forma-cluster" aria-label="Related actions">
  <button type="button">Primary action</button>
  <button type="button">Secondary action</button>
  <a href="#details">View details</a>
</div>
</forma-cluster>

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

Examples

Scenario

Form actions

The primary and secondary actions of a form footer. When the translated labels no longer fit on one line, the secondary actions wrap below the primary one instead of overflowing.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

HTML · Form actions Raw HTML for HTML · Form actions
<forma-cluster class="forma-component-tag">
  <div class="forma-cluster" role="group" aria-label="Invoice actions">
    <button type="submit">Send invoice</button>
    <button type="button">Save as draft</button>
    <button type="button">Discard changes</button>
  </div>
</forma-cluster>

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

Scenario

Record metadata line

A cluster of status lozenges and plain metadata under a record title. Each lozenge carries its state in text, so the line survives grayscale and forced colors.

INV-2291 · Northwind Logistics

Overdue 12 days Contact confirmed Owner: Finance operations Updated

HTML · Record metadata line Raw HTML for HTML · Record metadata line
<forma-cluster class="forma-component-tag">
  <article class="forma-stack" data-density="compact" aria-labelledby="cluster-record-metadata-title">
    <h2 id="cluster-record-metadata-title">INV-2291 · Northwind Logistics</h2>
    <p class="forma-cluster">
      <span class="forma-status-lozenge" data-state="attention">Overdue 12 days</span>
      <span class="forma-status-lozenge" data-state="ok">Contact confirmed</span>
      <span>Owner: Finance operations</span>
      <span>Updated <time datetime="2026-09-28">28 Sep 2026</time></span>
    </p>
  </article>
</forma-cluster>

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

Scenario

Tight filter chips

A filter summary with a narrower gap set through --forma-cluster-space. Links remain full-size targets; only the space between them changes.

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 · Tight filter chips Raw HTML for HTML · Tight filter chips
<forma-cluster class="forma-component-tag">
  <nav aria-label="Active filters">
    <p class="forma-cluster" style="--forma-cluster-space: 0.5rem">
      <a href="#status-open">Status: open</a>
      <a href="#owner-me">Owner: me</a>
      <a href="#region-emea">Region: Europe, Middle East and Africa</a>
      <a href="#clear-filters">Clear all filters</a>
    </p>
  </nav>
</forma-cluster>

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 toolbar

Four toolbar buttons at phone width. The row wraps into two lines rather than scrolling or shrinking the buttons.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. 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 320px the buttons no longer fit on one row, so the last ones wrap onto a second line in source order.
  • Buttons keep their intrinsic width and minimum target size; the cluster never compresses them.
  • The same gap separates wrapped rows, so rows stay visibly distinct without borders.
  • In landscape the row usually fits on one line again; no markup or order changes.
HTML · Mobile toolbar Raw HTML for HTML · Mobile toolbar
<forma-cluster class="forma-component-tag">
  <div class="forma-cluster" role="toolbar" aria-label="Document tools">
    <button type="button">Comment</button>
    <button type="button">Suggest edit</button>
    <button type="button">Share</button>
    <button type="button">Download PDF</button>
  </div>
</forma-cluster>

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 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.

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
role.forma-clustergroup | toolbarnoneOptional. Use group with aria-label to name a set of related controls. toolbar implies arrow-key navigation, which the application must implement; Forma does not.
aria-label.forma-clusterstring—Names the group when a role is present.
style.forma-cluster--forma-cluster-space: <length>—Inline override of the cluster gap for one instance.
data-densitysurrounding .forma-stackrelaxed | standard | compact | analytical—Appears on the surrounding stack in the metadata example. It does not change the cluster gap.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-clusterBlock class—Wrapping flex row with centered cross-axis alignment and one gap for items and lines.
--forma-cluster-gapCustom property—Foundation-layer gap variable. The component layer sets the gap from --forma-cluster-space, so setting this alone has no visible effect.
--forma-cluster-spaceCustom propertydefault var(--forma-primitive-spacing-3, 0.75rem)Gap between items and between wrapped lines. Default --forma-primitive-spacing-3 (0.75rem). This is the effective gap.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through focusable items in source order, which matches the wrapped visual order.
Arrow keysNo built-in behavior. If the cluster is marked role="toolbar", the application must implement roving focus.

Form behavior

Not a form control. Buttons inside a cluster submit or reset their form as usual.

States

Cluster states
StateHow it is expressedPresentation
Single lineitems fit the inline sizeAll items share one line, centered on the cross axis.
Wrappeditems exceed the inline sizeItems continue on following lines in source order, separated by the same gap.

Accessibility

Forma provides

  • Wrapping preserves DOM order, so reading and focus order follow the visual order at every width.
  • Adds no role; item semantics are unchanged.
  • Never shrinks items, so child controls keep their minimum target sizes.

Your application supplies

  • Name a cluster of controls with role="group" and aria-label when the group's purpose is not obvious from context.
  • Only use role="toolbar" if the application implements arrow-key focus management.
  • Put the most important action first in source order; do not rely on visual position to signal priority.

Responsive behavior

  • Intrinsic wrapping with flex-wrap; there are no breakpoints.
  • Very long single items can still be wider than a phone; they wrap their own text because Forma sets overflow-wrap: anywhere on text elements.
  • Wrapped lines use the same gap as items, so a wrapped cluster reads as one group, not two.
  • Place a cluster inside a Stack or Surface; it takes the full inline size of its parent.

Motion

  • No animation: items reflow instantly when the container width changes or items are added.

Usage guidance

Do

  • Make the semantic container itself the cluster instead of adding a wrapper.
  • Keep cluster items to a small, related set that reads as one unit.

Avoid

  • Encoding priority or severity in item order alone.
  • Setting --forma-cluster-gap and expecting it to change spacing; use --forma-cluster-space.

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.