Dialog
<forma-dialog>
Modal presentation built on the platform dialog element and declarative invoker commands.
- Authoring tag
<forma-dialog>- Category
- Overlays and disclosure
- 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.
Minimal dialog
Rendered from the canonical pattern file.
Live demo. 2 native actions work here and are verified by an outcome test.
<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
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.
<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.
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.
<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.
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.
What changes at narrow widths
- At 44rem and below the dialog is
100vw - 1remwide and at most100dvh - 1remtall, 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.
<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.
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.
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.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
commandfor | invoker button | id of the dialog | — | Connects a button to the dialog it controls. Works without script in browsers with invoker commands. |
command | invoker button | show-modal | close | request-close | — | show-modal opens the dialog as a modal; close closes it. Forma's pattern uses these instead of script. |
aria-labelledby | dialog | id of the dialog heading | — | Required. Names the dialog from its visible title. |
aria-describedby | dialog | id | — | Links the key explanatory sentence so it is announced on open. Keep it short. |
closedby | dialog | any | closerequest | none | closerequest for modals | Which user actions close the dialog. any adds backdrop click (light dismiss) where supported. |
method | form inside the dialog | dialog | — | Submitting closes the dialog and sets returnValue to the submitter's value, without a network request. |
autofocus | a control inside the dialog | boolean | absent | Chooses which element receives focus when the dialog opens; otherwise the first focusable element does. |
data-forma-motion-weight | dialog | light | standard | heavy | heavy | Presentation-only perceived mass for entry and exit. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-dialog | Block 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__actions | Element 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__body | Element 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. |
| Keys | Result |
|---|---|
| Enter / Space on the invoker | Opens the dialog; focus moves to the autofocus element or the first focusable element inside. |
| Tab / Shift+Tab | Moves among focusable elements in the dialog; the page behind is inert and cannot receive focus. |
| Escape | Closes the dialog (fires cancel, then close) unless closedby="none". |
| Enter in a field | Submits a method="dialog" form with its default (first) submit button, closing the dialog. |
| Event | Description |
|---|---|
command | Native event fired on the dialog when an invoker button targets it. |
cancel | Native event fired when the user asks to close (Escape or light dismiss); cancelable. |
close | Native 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
| State | How it is expressed | Presentation |
|---|---|---|
| Closed | no open attribute | Not rendered. While closing, the surface travels down slightly and the backdrop fades before display is removed. |
| Open (modal) | [open] via show-modal | Centered in the top layer over a dimmed, blurred backdrop; the rest of the page is inert. |
| Scrolling content | content taller than max-block-size | The 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 most100dvh - 2remtall, centered by the browser. - At 44rem and below:
100vw - 1remwide,100dvh - 1remtall 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;
displayandoverlayare held until the exit finishes. data-forma-motion-weightchanges perceived mass (heavy is the default). The native open state is always authoritative; motion never delays focus or inertness.- Under
prefers-reduced-motion: reducethe 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:
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.