Overlays and disclosure

Dialog

<forma-dialog>

Modal presentation built on the platform dialog element and declarative invoker commands.

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

Purpose

A dialog interrupts the page to ask for a decision or a short, bounded piece of work. Forma's dialog is the native dialog element opened as a modal from a button with commandfor and command="show-modal", and closed with command="close", a form method="dialog" submission, or Escape. The browser owns the top layer, making the rest of the page inert, moving focus into the dialog, Escape handling and returning focus to the invoker. Forma provides the centered surface, the dimmed and blurred backdrop, a padded body, a wrapping action row, a full-width phone layout, and heavy-weight entry and exit motion. What the actions do, and whether they are allowed, is application logic.

Use when

  • The user must confirm, choose or supply something before continuing, and the rest of the page should wait.
  • A consequential or destructive action needs an explicit, labelled confirmation step.
  • A short form (one to a few fields) belongs to the current context and should not navigate away.

Avoid when

  • The content is supplemental and the user can keep working: use Popover or Disclosure.
  • The surface holds filters, navigation or record detail anchored to a screen edge: use Flyout.
  • The task is long or multi-step: use a page or Wizard.
  • You are presenting a blocking Aegis fault: use Fault blocking.
  • You only need to report an outcome: use Toast or Alert.

Behavior to know

  • Native modal behavior: top layer, inert background, focus containment, Escape and focus return.
  • Opened and closed declaratively by invoker buttons; no script is needed for the baseline.
  • Width min(38rem, 100vw - 2rem) and height capped to the dynamic viewport; long content scrolls inside the dialog.
  • Heavy perceived weight by default: a short upward settle on entry and a reciprocal exit with the same duration and easing.

Basic example

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

Canonical

Minimal dialog

Rendered from the canonical pattern file.

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

Confirm action

The browser owns modal focus, inertness, Escape behavior, and focus restoration.

HTML · Minimal dialog Raw HTML for HTML · Minimal dialog
<forma-dialog class="forma-component-tag">
<button type="button" commandfor="example-dialog" command="show-modal">Open modal</button>
<dialog
  class="forma-dialog"
  id="example-dialog"
  data-forma-motion-weight="heavy"
  aria-labelledby="example-dialog-title"
  aria-describedby="example-dialog-description">
  <div class="forma-dialog__body">
    <h2 id="example-dialog-title">Confirm action</h2>
    <p id="example-dialog-description">The browser owns modal focus, inertness, Escape behavior, and focus restoration.</p>
  </div>
  <div class="forma-dialog__actions">
    <button type="button" commandfor="example-dialog" command="close">Cancel</button>
  </div>
</dialog>
</forma-dialog>

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

Examples

Scenario

Destructive confirmation

Deleting a project. The dialog's form uses method="dialog", so either button closes the dialog and sets its return value to the button's value for the application to act on. autofocus puts initial focus on the safe choice. Forma has no destructive button variant; the title and the button label carry the consequence.

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

Delete “Atlas migration”?

All 214 work items and their history will be permanently deleted. This cannot be undone.

HTML · Destructive confirmation Raw HTML for HTML · Destructive confirmation
<forma-dialog class="forma-component-tag">
  <button type="button" commandfor="dialog-destructive-confirmation" command="show-modal">Delete project…</button>
  <dialog class="forma-dialog" id="dialog-destructive-confirmation" aria-labelledby="dialog-destructive-confirmation-title" aria-describedby="dialog-destructive-confirmation-description">
    <form method="dialog">
      <div class="forma-dialog__body">
        <h2 id="dialog-destructive-confirmation-title">Delete “Atlas migration”?</h2>
        <p id="dialog-destructive-confirmation-description">All 214 work items and their history will be permanently deleted. This cannot be undone.</p>
      </div>
      <div class="forma-dialog__actions">
        <button type="submit" value="cancel" autofocus>Keep project</button>
        <button type="submit" value="delete">Delete project</button>
      </div>
    </form>
  </dialog>
</forma-dialog>

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

Scenario

Long release notes with light dismiss

Read-only content that does not need a decision. closedby="any" lets a click on the backdrop close the dialog in browsers that support it; Escape and the Close button work everywhere. The content is longer than a phone screen, so the dialog scrolls within its viewport-capped height. The standard motion weight makes entry a little quicker than the heavy default.

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

What's new in 4.2

Scheduled exports

Exports can now run daily or weekly and are delivered to a shared folder. Existing manual exports are unchanged.

Faster search

Search results for large workspaces return in about half the time. Saved searches keep their filters.

Audit log retention

Administrators can extend audit log retention from 90 to 365 days. Longer retention applies from the date it is enabled.

Deprecations

The legacy CSV importer will be removed in 5.0. Use the new importer, which supports column mapping and previews.

HTML · Long release notes with light dismiss Raw HTML for HTML · Long release notes with light dismiss
<forma-dialog class="forma-component-tag">
  <button type="button" commandfor="dialog-light-dismiss-long-content" command="show-modal">What's new in 4.2</button>
  <dialog class="forma-dialog" id="dialog-light-dismiss-long-content" closedby="any" data-forma-motion-weight="standard" aria-labelledby="dialog-light-dismiss-long-content-title">
    <div class="forma-dialog__body">
      <h2 id="dialog-light-dismiss-long-content-title">What's new in 4.2</h2>
      <h3>Scheduled exports</h3>
      <p>Exports can now run daily or weekly and are delivered to a shared folder. Existing manual exports are unchanged.</p>
      <h3>Faster search</h3>
      <p>Search results for large workspaces return in about half the time. Saved searches keep their filters.</p>
      <h3>Audit log retention</h3>
      <p>Administrators can extend audit log retention from 90 to 365 days. Longer retention applies from the date it is enabled.</p>
      <h3>Deprecations</h3>
      <p>The legacy CSV importer will be removed in 5.0. Use the new importer, which supports column mapping and previews.</p>
    </div>
    <div class="forma-dialog__actions">
      <button type="button" commandfor="dialog-light-dismiss-long-content" command="close">Close</button>
    </div>
  </dialog>
</forma-dialog>

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

Short form on a phone

A one-field rename dialog at phone width. The dialog fills the width minus a small margin and its actions stretch to full-width rows.

Live demo. 4 native actions work here and are 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

  • At 44rem and below the dialog is 100vw - 1rem wide and at most 100dvh - 1rem tall, so it fits phones in portrait and landscape and follows the dynamic viewport as browser toolbars appear.
  • Body padding reduces to 1rem and each action button becomes a full-width row, keeping 44px targets and room for long labels.
  • Content taller than the viewport scrolls inside the dialog with overscroll-behavior: contain, so the page behind does not scroll.
  • The on-screen keyboard may cover the lower part of the dialog; keep fields near the top and actions immediately after them.
HTML · Short form on a phone Raw HTML for HTML · Short form on a phone
<forma-dialog class="forma-component-tag">
  <button type="button" commandfor="dialog-mobile-short-form" command="show-modal">Rename board</button>
  <dialog class="forma-dialog" id="dialog-mobile-short-form" aria-labelledby="dialog-mobile-short-form-title">
    <form method="dialog">
      <div class="forma-dialog__body">
        <h2 id="dialog-mobile-short-form-title">Rename board</h2>
        <div class="forma-field">
          <label class="forma-field__label" for="dialog-mobile-short-form-name">Board name</label>
          <input id="dialog-mobile-short-form-name" name="board-name" type="text" value="Quarterly planning" required>
        </div>
      </div>
      <div class="forma-dialog__actions">
        <button type="submit" value="cancel" formnovalidate>Cancel</button>
        <button type="submit" value="save">Save name</button>
      </div>
    </form>
  </dialog>
</forma-dialog>

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. 2 native actions work here and are 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
commandforinvoker buttonid of the dialog—Connects a button to the dialog it controls. Works without script in browsers with invoker commands.
commandinvoker buttonshow-modal | close | request-close—show-modal opens the dialog as a modal; close closes it. Forma's pattern uses these instead of script.
aria-labelledbydialogid of the dialog heading—Required. Names the dialog from its visible title.
aria-describedbydialogid—Links the key explanatory sentence so it is announced on open. Keep it short.
closedbydialogany | closerequest | nonecloserequest for modalsWhich user actions close the dialog. any adds backdrop click (light dismiss) where supported.
methodform inside the dialogdialog—Submitting closes the dialog and sets returnValue to the submitter's value, without a network request.
autofocusa control inside the dialogbooleanabsentChooses which element receives focus when the dialog opens; otherwise the first focusable element does.
data-forma-motion-weightdialoglight | standard | heavyheavyPresentation-only perceived mass for entry and exit.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-dialogBlock class—The dialog surface: border, primary surface, shadow, width min(38rem, 100vw - 2rem), viewport-capped height and contained overscroll. Also styles the backdrop.
.forma-dialog__actionsElement class—Wrapping action row aligned to the inline end with a top rule; at 44rem and below its buttons stretch to full width.
.forma-dialog__bodyElement class—Padded content region (1.5rem, 1rem at 44rem and below).
[data-forma-motion-weight]Attribute hook"heavy", "light", "standard"Presentation-only perceived mass: heavy (default for dialogs), standard or light. Never encodes severity or destructiveness.
[open]Attribute hook—Native open state, set by the browser. [open] switches the surface to its resting position and the backdrop to its dimmed, blurred state, while preserving the shared spring timing in both directions.
Keyboard interaction
KeysResult
Enter / Space on the invokerOpens the dialog; focus moves to the autofocus element or the first focusable element inside.
Tab / Shift+TabMoves among focusable elements in the dialog; the page behind is inert and cannot receive focus.
EscapeCloses the dialog (fires cancel, then close) unless closedby="none".
Enter in a fieldSubmits a method="dialog" form with its default (first) submit button, closing the dialog.
Events
EventDescription
commandNative event fired on the dialog when an invoker button targets it.
cancelNative event fired when the user asks to close (Escape or light dismiss); cancelable.
closeNative event fired after the dialog closes. Read returnValue to find which form button closed it.

Form behavior

A form method="dialog" inside the dialog closes it on submission and records the submitter's value in dialog.returnValue; field values are not sent anywhere. Use formnovalidate on a cancel button so required fields do not block cancelling.

States

Dialog states
StateHow it is expressedPresentation
Closedno open attributeNot rendered. While closing, the surface travels down slightly and the backdrop fades before display is removed.
Open (modal)[open] via show-modalCentered in the top layer over a dimmed, blurred backdrop; the rest of the page is inert.
Scrolling contentcontent taller than max-block-sizeThe dialog scrolls internally with contained overscroll. Actions scroll with the content; they are not pinned.
Phone layout@media (max-width: 44rem)Near full-width surface, reduced padding and full-width action buttons.

Accessibility

Forma provides

  • Builds on native modal dialog behavior for focus containment, inertness, Escape and focus restoration.
  • Keeps the surface within the dynamic viewport and contains overscroll so the page does not scroll behind it.
  • Keeps a visible border in forced-colors mode and removes the backdrop blur and spatial travel under reduced motion.

Your application supplies

  • Always name the dialog with aria-labelledby pointing at a visible heading.
  • Put initial focus on the safest control for destructive confirmations (autofocus).
  • Write action labels that say what happens ("Delete project", "Keep project"), not "OK"/"Cancel" alone.
  • Provide a visible close or cancel control; do not rely on Escape or backdrop clicks alone.
  • Act on the result (returnValue or click) in application code and re-check legality at that moment.

Responsive behavior

  • Above 44rem: min(38rem, 100vw - 2rem) wide, at most 100dvh - 2rem tall, centered by the browser.
  • At 44rem and below: 100vw - 1rem wide, 100dvh - 1rem tall at most, 1rem body padding, full-width action buttons.
  • Long content scrolls inside the dialog; long titles and labels wrap.
  • A true full-screen mobile mode and pinned (sticky) action rows are not provided.

Motion

  • Entry: the surface rises from 0.75rem below and scales from 98.5% to rest over the heavy inertial duration with spring easing; the backdrop dims and blurs by perceptual interpolation, independent of mass.
  • Exit: the same path reversed over the same inertial duration and easing as entry, and the backdrop fades; display and overlay are held until the exit finishes.
  • data-forma-motion-weight changes perceived mass (heavy is the default). The native open state is always authoritative; motion never delays focus or inertness.
  • Under prefers-reduced-motion: reduce the travel and scale are removed, the backdrop blur is dropped, and remaining transitions are 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

Confirm action

The browser owns modal focus, inertness, Escape behavior, and focus restoration.

standardpresentation only

Confirm action

The browser owns modal focus, inertness, Escape behavior, and focus restoration.

heavypresentation only

Confirm action

The browser owns modal focus, inertness, Escape behavior, and focus restoration.

Usage guidance

Do

  • Keep one decision per dialog and a title that states it.
  • Place the dismissive action first and the committing action last in the actions row, consistently across the product.

Avoid

  • Opening a dialog on page load or without a user action.
  • Stacking dialogs on top of dialogs.
  • Using heavy motion weight or a special style to imply that an action is dangerous; say so in words.

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.