Layout primitives

Container

<forma-container>

Marketing-layer width container (narrow, default, wide, max) with a breakout escape for full-bleed media.

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

Purpose

A container centers a region and caps its width at one of four token-defined sizes: narrow (45rem) for reading, standard (64rem, the default) for mixed content, wide (75rem) for grids, and max (90rem) for the full page frame. The page background and any tonal band stay full width while the content inside lines up on a shared set of widths. forma-breakout is the companion for regions that should use the full available width, such as a wide figure or table placed between narrow text containers. Both are marketing-layer primitives whose widths come from the site's layout role tokens, so place them inside .forma-site.

Use when

  • Regions of a site page should align to a small set of consistent content widths.
  • Reading content (legal text, articles, forms) should stay narrow while the page background runs edge to edge.
  • A wide figure, chart or table between narrow text blocks should use the full page width.

Avoid when

  • You only need to cap line length of text inside a panel: use Measure.
  • The content is long-form article text: use Prose, which includes the reading measure and rhythm.
  • You are laying out an application view: containers are a site-page tool; use the application's shell such as Workspace shell.

Behavior to know

  • Width is min(100%, var(--forma-container-width)), centered with automatic inline margins.
  • The container adds no padding; the page gutter comes from .forma-site__main in the Marketing shell.
  • forma-breakout widens only relative to its own parent: use it as a sibling of containers, not inside one.

Basic example

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

Canonical

Minimal container

Rendered from the canonical pattern file.

Privacy notice

Narrow containers keep reading-focused regions at a comfortable measure while the page background stays full width.

HTML · Minimal container Raw HTML for HTML · Minimal container
<forma-container class="forma-component-tag">
<div class="forma-site">
  <div class="forma-container" data-forma-width="narrow">
    <h2>Privacy notice</h2>
    <p>Narrow containers keep reading-focused regions at a comfortable measure while the page background stays full width.</p>
  </div>
</div>
</forma-container>

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

Examples

Scenario

Narrow article with a wide figure

Two narrow containers of reading text with an forma-breakout figure between them. The figure spans the full available width while the text keeps its reading width, and all three share one source order.

How replication works

Every write is committed in the primary zone and then copied to two others before it is acknowledged.

Diagram of three availability zones connected in a ring
Writes travel around the ring before acknowledgement.

If a zone is lost, the remaining two continue serving reads and writes without a manual failover.

HTML · Narrow article with a wide figure Raw HTML for HTML · Narrow article with a wide figure
<forma-container class="forma-component-tag">
  <div class="forma-site">
    <div class="forma-container" data-forma-width="narrow">
      <h2>How replication works</h2>
      <p>Every write is committed in the primary zone and then copied to two others before it is acknowledged.</p>
    </div>
    <figure class="forma-breakout forma-frame" style="--forma-frame-ratio: 3 / 1">
      <div class="forma-frame__media"><img src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='1500' height='500'%3E%3Crect width='100%25' height='100%25' fill='%23c9c4b8'/%3E%3C/svg%3E" alt="Diagram of three availability zones connected in a ring"></div>
      <figcaption>Writes travel around the ring before acknowledgement.</figcaption>
    </figure>
    <div class="forma-container" data-forma-width="narrow">
      <p>If a zone is lost, the remaining two continue serving reads and writes without a manual failover.</p>
    </div>
  </div>
</forma-container>

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

Scenario

Wide container for a card grid

A data-forma-width="wide" container holding a card grid. The grid gets more columns than a standard container would allow while staying aligned with other wide regions on the page.

  • Git hosting

    Deploy on every merge to main.

  • Chat

    Post deploy results to a channel.

  • Issue tracker

    Link releases to resolved issues.

HTML · Wide container for a card grid Raw HTML for HTML · Wide container for a card grid
<forma-container class="forma-component-tag">
  <div class="forma-site">
    <div class="forma-container" data-forma-width="wide">
      <ul class="forma-card-grid" data-forma-columns="3" aria-label="Integrations">
        <li><article class="forma-card"><h2 class="forma-card__title">Git hosting</h2><p>Deploy on every merge to main.</p></article></li>
        <li><article class="forma-card"><h2 class="forma-card__title">Chat</h2><p>Post deploy results to a channel.</p></article></li>
        <li><article class="forma-card"><h2 class="forma-card__title">Issue tracker</h2><p>Link releases to resolved issues.</p></article></li>
      </ul>
    </div>
  </div>
</forma-container>

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

Scenario

Custom width for a sign-up form

A form container narrower than the narrow preset, set with --forma-container-width: 28rem. It stays centered and still shrinks to 100% on small screens.

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.

Join the beta

HTML · Custom width for a sign-up form Raw HTML for HTML · Custom width for a sign-up form
<forma-container class="forma-component-tag">
  <div class="forma-site">
    <form class="forma-container forma-stack" style="--forma-container-width: 28rem" aria-labelledby="container-custom-width-title">
      <h2 id="container-custom-width-title">Join the beta</h2>
      <div class="forma-field">
        <label class="forma-field__label" for="container-custom-width-email">Work email</label>
        <input id="container-custom-width-email" name="email" type="email" autocomplete="email" required>
      </div>
      <div class="forma-cluster"><button type="submit">Request access</button></div>
    </form>
  </div>
</forma-container>

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 page width

Narrow and standard containers at phone width. Every preset is wider than the screen, so each resolves to 100% and the page gutter alone controls the edges.

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

  • All presets are at least 45rem, so on phones min(100%, …) makes every container full width.
  • The container adds no padding; the side gutter comes from .forma-site__main in a full page (the preview here has none).
  • forma-breakout is also 100% on phones, so wide figures fall back to the column width; put wide tables in Bounded overflow.
  • Landscape tablets may show the narrow preset at its full 45rem with centered margins.
HTML · Mobile page width Raw HTML for HTML · Mobile page width
<forma-container class="forma-component-tag">
  <div class="forma-site">
    <div class="forma-container" data-forma-width="narrow">
      <h2>Terms of service</h2>
      <p>These terms apply to every workspace created after 1 September 2026.</p>
    </div>
    <div class="forma-container">
      <p><a href="#previous-terms">Read the previous terms</a></p>
    </div>
  </div>
</forma-container>

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-width.forma-containernarrow | wide | maxabsent (standard, 64rem)Selects a width preset from the layout role tokens.
style.forma-container / .forma-breakout--forma-container-width / --forma-breakout-max / --forma-frame-ratio—Per-instance width override, or the frame ratio in the figure example.
aria-labelledbyformid of the heading—Names the sign-up form by its heading.
data-forma-columns.forma-card-grid3—Card grid column preference, used in the wide container example.
aria-label.forma-card-gridstring—Names the card collection.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-containerBlock class—Centered region capped at --forma-container-width (falls back to --forma-layout-width-standard).
[data-forma-width]Attribute hook"max", "narrow", "wide"narrow = --forma-layout-width-narrow (45rem), wide = --forma-layout-width-wide (75rem), max = --forma-layout-width-max (90rem).
--forma-container-widthCustom propertydefault var(--forma-layout-width-narrow)Maximum width of the container. Set by data-forma-width, or directly for a custom width.
.forma-breakoutBlock class—Region at min(100%, --forma-breakout-max) with max-inline-size: none. Not centered by itself; place it directly in the page's main region beside containers.
--forma-breakout-maxCustom property—Maximum width of a breakout region. Default 90rem.
--forma-layout-width-standardCustom property—Site role token for the default container width (64rem by default); themes may retarget it.

Form behavior

Not a form control. A form can be a container.

No keyboard interaction beyond the browser defaults for the elements in the markup.

States

Container states
StateHow it is expressedPresentation
Standardno data-forma-widthCapped at 64rem and centered.
Narrow / wide / maxdata-forma-widthCapped at 45rem, 75rem or 90rem and centered.
Fluidparent narrower than the cap100% of the parent.

Accessibility

Forma provides

  • Width constraints only; no roles, landmarks or order changes.
  • Narrow widths keep reading regions at a comfortable line length.
  • Caps are clamped to 100%, so containers never cause horizontal scrolling at 320px or 400% zoom.

Your application supplies

  • Keep one source order for text and wide regions; do not reorder to fit the width system.
  • Use headings inside containers to structure the page; containers are not landmarks.
  • Provide alt text and captions for breakout media.

Responsive behavior

  • Intrinsic: each container is min(100%, cap), so presets collapse to full width on narrow screens without breakpoints.
  • Widths come from site role tokens; a theme can retarget them without changing markup.
  • forma-breakout does not escape an ancestor container; it is only as wide as its parent allows.
  • Container widths are fixed rem values that scale with the user's root font size.

Motion

  • No animation: widths are static.

Usage guidance

Do

  • Use narrow for reading, standard for mixed content, wide for grids and max only for full-frame regions.
  • Keep text and its wide media as siblings in the page flow.

Avoid

  • Nesting containers to fine-tune width; set --forma-container-width instead.
  • Putting forma-breakout inside a narrow container and expecting it to widen.

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.