Overlays and disclosure

Disclosure

<forma-disclosure>

Expandable content built on details and summary with no runtime behavior layer; where interpolate-size is supported the panel settles to its intrinsic height, otherwise it opens instantly.

Authoring tag
<forma-disclosure>
Behavior owner
Native HTML
Canonical source
patterns/disclosure.html

Purpose

A disclosure hides optional content behind a labelled row that the user opens when needed: advanced options, explanations, secondary detail. It is a native details element with class="forma-disclosure", a summary, and an forma-disclosure__content wrapper. The browser owns the open state (open attribute), keyboard toggling, the expanded announcement, find-in-page auto-expansion, and exclusive accordions via the name attribute. Forma draws top and bottom rules, a 44px summary row with a "+" indicator that turns to "×" when open, and light entry motion. Content inside stays in normal flow and pushes the page down.

Use when

  • Content is optional or secondary and most users do not need it.
  • A long page of questions and answers or settings should be scannable by heading first.
  • Advanced form fields should be available without crowding the common case.

Avoid when

  • The hidden content is needed to understand consequential state, scope or unresolved work: keep that visible and disclose only the evidence with Overview disclosure.
  • The content is commands: use Overflow command disclosure or Action menu.
  • Sections are peers the user switches between: use Tabs.
  • The content should overlay the page: use Popover.

Behavior to know

  • Native details/summary; no script and no second state machine.
  • The whole summary row is at least 44px tall and toggles the content.
  • Open and closed are shown by the indicator's shape (+ versus ×), not color.
  • Adjacent disclosures share a single rule between them, forming a stacked list.

Basic example

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

Canonical

Minimal disclosure

Rendered from the canonical pattern file.

Live demo. 1 native action works here and is verified by an outcome test.

Advanced options

Additional controls or explanatory content go here.

HTML · Minimal disclosure Raw HTML for HTML · Minimal disclosure
<forma-disclosure class="forma-component-tag">
<details class="forma-disclosure" data-forma-motion-weight="light">
  <summary>Advanced options</summary>
  <div class="forma-disclosure__content">
    <p>Additional controls or explanatory content go here.</p>
  </div>
</details>
</forma-disclosure>

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

Examples

Scenario

Exclusive FAQ list

Three adjacent disclosures sharing name="disclosure-exclusive-faq", so opening one closes the others (a native exclusive accordion in supporting browsers; elsewhere they open independently). Adjacent rules collapse into single dividers.

Live demo. 3 native actions work here and are verified by an outcome test.

Can I change my plan later?

Yes. Upgrades apply immediately; downgrades apply at the start of the next billing period.

What happens to my data if I cancel?

Your workspace becomes read-only for 30 days so you can export it. After that it is deleted.

Do you offer discounts for non-profits?

Registered non-profits receive 40% off any paid plan. Contact support with your registration number.

HTML · Exclusive FAQ list Raw HTML for HTML · Exclusive FAQ list
<forma-disclosure class="forma-component-tag">
  <div>
    <details class="forma-disclosure" name="disclosure-exclusive-faq" open>
      <summary>Can I change my plan later?</summary>
      <div class="forma-disclosure__content">
        <p>Yes. Upgrades apply immediately; downgrades apply at the start of the next billing period.</p>
      </div>
    </details>
    <details class="forma-disclosure" name="disclosure-exclusive-faq">
      <summary>What happens to my data if I cancel?</summary>
      <div class="forma-disclosure__content">
        <p>Your workspace becomes read-only for 30 days so you can export it. After that it is deleted.</p>
      </div>
    </details>
    <details class="forma-disclosure" name="disclosure-exclusive-faq">
      <summary>Do you offer discounts for non-profits?</summary>
      <div class="forma-disclosure__content">
        <p>Registered non-profits receive 40% off any paid plan. Contact support with your registration number.</p>
      </div>
    </details>
  </div>
</forma-disclosure>

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

Scenario

Advanced settings open with fields

A disclosure that starts open because the user changed one of its fields last time. It contains form fields, which submit whether the disclosure is open or closed. The standard motion weight gives the larger panel a slightly slower settle.

Live demo. 1 native action works here and is verified by an outcome test.

Advanced delivery settings

How many times to retry a failed webhook before giving up.

HTML · Advanced settings open with fields Raw HTML for HTML · Advanced settings open with fields
<forma-disclosure class="forma-component-tag">
  <details class="forma-disclosure" data-forma-motion-weight="standard" open>
    <summary>Advanced delivery settings</summary>
    <div class="forma-disclosure__content forma-stack">
      <div class="forma-field">
        <label class="forma-field__label" for="disclosure-advanced-fields-open-retries">Retry attempts</label>
        <p class="forma-field__description" id="disclosure-advanced-fields-open-retries-help">How many times to retry a failed webhook before giving up.</p>
        <input id="disclosure-advanced-fields-open-retries" name="retries" type="number" min="0" max="10" value="3" aria-describedby="disclosure-advanced-fields-open-retries-help">
      </div>
      <div class="forma-field">
        <label class="forma-field__label" for="disclosure-advanced-fields-open-timeout">Timeout in seconds</label>
        <input id="disclosure-advanced-fields-open-timeout" name="timeout" type="number" min="1" max="60" value="10">
      </div>
    </div>
  </details>
</forma-disclosure>

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

Long summary on a phone

A disclosure with a long, translated summary at phone width. The summary text wraps beside the indicator, and the row stays a single tap target.

Live demo. 1 native action works here and is verified by an outcome test.

Viewport width

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

What changes at narrow widths

  • The summary is a flex row: the text wraps onto several lines while the + / × indicator stays at the inline end.
  • The row is at least 44px tall and grows with the wrapped text; tapping anywhere on it toggles the content.
  • Opened content is in normal flow and pushes the page down; nothing overlays or scrolls sideways at 320px.
  • There are no breakpoints; orientation changes only reflow the text.
HTML · Long summary on a phone Raw HTML for HTML · Long summary on a phone
<forma-disclosure class="forma-component-tag">
  <details class="forma-disclosure" lang="fr">
    <summary>Pourquoi certaines transactions apparaissent-elles deux fois sur mon relevé mensuel ?</summary>
    <div class="forma-disclosure__content">
      <p>Une préautorisation peut apparaître avant le débit définitif. Elle disparaît généralement sous trois jours ouvrés.</p>
    </div>
  </details>
</forma-disclosure>

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.

Live demo. 1 native action works here and is verified by an outcome test.

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
opendetailsbooleanabsent (closed)Initial open state. The browser adds and removes it as the user toggles.
namedetailsstringabsentGroups disclosures into an exclusive accordion: opening one closes the others with the same name. Supported in current browsers; elsewhere each opens independently.
data-forma-motion-weightdetailslight | standard | heavylightPresentation-only perceived mass for the indicator and content settle.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-disclosureBlock class—The details element: top and bottom functional rules; a following .forma-disclosure drops its top rule so stacks share dividers. Its summary becomes a 44px flex row with the native marker removed and a + / × indicator.
.forma-disclosure__contentElement class—Wrapper for the revealed content, with bottom padding and the entry fade and settle.
[data-forma-motion-weight]Attribute hook"heavy", "light", "standard"Presentation-only perceived mass: light (default for disclosures), standard or heavy.
[open]Attribute hook—Native open state. [open] rotates the indicator 45° (+ becomes ×) and, where supported, lets ::details-content settle to its intrinsic height.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves focus to the summary, then into the open content.
Enter / SpaceToggles the disclosure (native summary behavior).
Events
EventDescription
toggleNative event fired on the details element after it opens or closes.

Form behavior

Fields inside a closed disclosure still belong to their form and are submitted. Invalid fields inside a closed disclosure can block submission out of sight; keep required fields outside or open the disclosure on error.

States

Disclosure states
StateHow it is expressedPresentation
Closedno open attributeOnly the summary row is shown, with a + indicator.
Opendetails[open]Content visible below the summary; indicator rotated to ×.
Pressed:active on summaryThe indicator scales down slightly while pressed; the row does not move.
Focus:focus-visible on summaryShared two-tone focus ring on the summary.

Accessibility

Forma provides

  • Uses native details/summary, so the summary is a focusable disclosure button with an announced expanded state.
  • Keeps a 44px summary row and a shape-based open/closed indicator that does not rely on color.
  • Keeps content in normal flow and supports find-in-page expansion of closed content where the browser does.

Your application supplies

  • Write summaries that say what is inside ("Advanced delivery settings"), not "More".
  • Do not hide information needed to make a decision; use Overview disclosure for consequential state.
  • Do not put interactive elements inside summary.
  • Add a heading inside the content, or wrap the summary text in a heading, when disclosures form part of the page outline.

Responsive behavior

  • Intrinsic sizing: the disclosure fills its container; the summary text wraps beside the indicator.
  • Content reflows in normal flow; there is no fixed height and no horizontal overflow.
  • No breakpoints.

Motion

  • The + indicator rotates to × over the light inertial duration with spring easing; pressing the summary briefly scales the indicator with damped easing.
  • Newly opened content fades in (perceptual) and settles from 0.25rem above (inertial, damped) using @starting-style.
  • Where interpolate-size and ::details-content are supported, the content region animates its block size from 0 to its intrinsic height with the inertial duration; elsewhere it opens instantly. The native open state is always immediate.
  • data-forma-motion-weight changes perceived mass (light by default).
  • Under prefers-reduced-motion: reduce the height transition is removed entirely (so content is never delayed), and the indicator and content transitions become effectively instant.

Motion weights

Forma motion is physics-derived: perceived mass changes how a surface accelerates and settles, never what state it is in. Compare the three presentation weights of the same markup:

lightpresentation only
Advanced options

Additional controls or explanatory content go here.

standardpresentation only
Advanced options

Additional controls or explanatory content go here.

heavypresentation only
Advanced options

Additional controls or explanatory content go here.

Usage guidance

Do

  • Group related disclosures as adjacent siblings so they read as one list.
  • Use name for exclusive accordions only when comparing sections side by side is not useful.

Avoid

  • Nesting disclosures more than one level deep.
  • Hiding required fields or error messages inside a closed disclosure.
  • Adding your own open/closed classes; the open attribute is the only state.

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.