Dialog

Centered modal overlay for focused tasks, confirmations, or forms, built on the native <dialog> element.

Related terms: modal, alert dialog, confirmation dialog.

Class reference

Anatomy

.modal is the outer surface and deliberately has no inner padding. Wrap its content in a direct <form> or .stack; that wrapper owns the padding, rhythm, and overflow. Put .stack on the wrapper, never on dialog.modal itself.

For a header band, place <header> directly under dialog.modal, before the body wrapper. Put a flexible .media title region first and a .cluster of controls second. The title has the close control's minimum height; its leading icon and every trailing control share the same center axis. A wrapped title simply makes the row taller.

A direct dialog > header is dialog chrome and forms a distinct header band, painted --surface-subtle. Change the fill with a surface utility on the header (<header class="background-raised">). Put an ordinary content heading inside the padded form or .stack instead.

Keep a corner .close as a direct child of the dialog and put the title in the wrapper's direct <header>. The button then stays outside the content flow while the header reserves enough inline space to keep its title clear.

A .close placed as a direct child of the chrome header is still the corner overlay. That header reserves the same inline room for it, never below its own --modal-pad, so a wrapping title stays clear either way.

The corner close overlays the panel edge, so a body tall enough to scroll would run its scrollbar under the button. Give such a dialog the scrollable anatomy: the close then sits over the fixed header and the scrollbar starts below it.

Add .bleed to that header, or to the wrapper's footer, when it should form a full-width band. It reaches the dialog edges and corners, keeps the modal's inner padding, and takes a surface utility such as .background-subtle.

The wrapper's <footer> is a structural slot: it stays fixed under .scrollable but has no layout of its own. Compose the action row in markup — <footer class="cluster justify-content-end"> for trailing actions, .justify-content-space-between for a split pair.

Where each region lives

Two anatomies are legitimate. Pick one; each owns its scroll, footer, and close placement.

Wrapper header — a <header> inside the form/.stack body. The wrapper owns padding, rhythm, and overflow. With .scrollable the header and footer are fixed rows and the content between them scrolls. The .close stays a direct child of the dialog and the header reserves its inline room.

External header — a direct dialog > header, before the body wrapper. The header is dialog chrome outside the scroll container, so it never scrolls. The footer stays inside the wrapper and is the trailing fixed row under .scrollable. Wrap the .close in the header's trailing .cluster to keep it in flow; a .close that is a direct child of the header is still the absolute corner overlay, and the header reserves its room.

The .scrollable row template follows the regions the wrapper actually holds, so a modal without a header, without a footer, or with an external header all keep the footer reachable and the body scrollable.

Usage

Modals use the platform-native <dialog class="modal"> element with commandfor and command buttons.

Use command="show-modal" to open a modal dialog, or command="--show" to open it non-modally.

Add aria-haspopup="dialog" and aria-controls="<id>" to opening buttons so their semantics are present before either native or framework JavaScript runs. The command runtime is stateless and does not pre-scan triggers.

Use command="request-close" for cancel-style buttons so close requests go through the dialog's cancel lifecycle.

Use closedby="any" as the no-JavaScript light-dismiss path: the native dialog closes on backdrop click and Escape. Add data-dialog-dismissible so the optional runtime takes over backdrop click and closes with the dialog's transition; it rewrites closedby="any" to closedby="closerequest" so the native dialog and the runtime never double-handle. data-dialog-dismissible only gates backdrop click — Escape and explicit close requests always close, unless the application cancels the actual:dialog-cancel event.

Alert dialog

Use this shape when the dialog interrupts the flow and asks for a decision. It has no close icon and no light dismiss; the footer actions are the way out. closedby="none" keeps Escape and backdrop clicks from closing it, so a critical confirmation cannot be dismissed accidentally. With the optional runtime, backdrop clicks give a small static feedback instead of closing.

Confirmation with an icon and an action band

For a compact confirmation with a leading status icon, put a .dialog-icon and the text column in a .media row. The first heading of that column centers on the icon; following copy stays in the same column. The icon well accepts the shared intent and emphasis classes: dialog-icon danger soft is the tinted red circle.

The action band is the footer composed with existing primitives: .bleed reaches the panel edges and corners, .background-subtle paints it, and .cluster.justify-content-space-between splits the decision pair. Keep the cancel-style action first, so it holds the leading edge and never sits next to the committing one.

For a trailing illustration, use a direct <header> as the message region and compose it as a non-wrapping split cluster. .grow keeps the text column flexible while .dialog-icon stays at the inline end.

Use the same anatomy in a .card instead when the surface belongs in page content and does not need modal focus or a backdrop.

Information modal

Use this shape for contextual information or lightweight secondary content. It has no action button; the header close button dismisses the dialog.

Action modal

Use this shape when contextual information leads to one non-destructive next step, such as reviewing a setup before continuing. Unlike an alert dialog, it can be dismissed without choosing the action; unlike an information modal, it has a primary action in a footer.

Use .dialog-icon with the media object for a leading title icon. An .alert belongs in the body only when the dialog contains a distinct status message; the dialog title itself is not an alert.

Scrollable modal

Use modal scrollable when the header and footer should stay visible while the dialog body scrolls. Modal dialogs lock page scroll while a modal is open: the runtime writes html.has-modal-open, and the stylesheet applies overflow: hidden (and reserves the scrollbar gutter with scrollbar-gutter: stable when one was present). The height cap follows the small viewport, so the panel keeps a stable size while mobile browser chrome expands or collapses.

The scrolling body is a scroll container, and browsers make one keyboard-focusable so it can be scrolled without a pointer — it takes a focus ring like any other focusable element, and it can claim initial focus when nothing focusable precedes it. Mark the control you want focused autofocus.

Each non-header/footer child region is its own scrollport, so wrap the body in a single element (<div class="stack">) when there should be one scrollbar.

An external header follows the same contract from the other side: the header is chrome outside the wrapper, the footer stays in the wrapper, and the content between them scrolls.

Overlays inside modals

Flyouts and tooltips opened from inside a modal dialog stay exactly where they are authored. The runtime promotes them to the top layer instead of moving them, which is what keeps them inside every scope that reaches them by inheritance.

Author them inside the dialog. Promotion paints an element above a modal, but it does not lift it out of the modal's inertness — that is computed on the DOM, not on paint order — so an overlay authored outside the dialog would be promoted above it and still unclickable.

JavaScript options

Add options directly on the dialog element. Without JavaScript, modern browsers still use the native dialog behavior; the runtime adds declarative command handling, focus restoration, controlled light dismiss, and optional view transitions.

Available options:

• data-dialog-dismissible gates backdrop click only: the runtime takes over light dismiss and closes the dialog (or rewrites closedby="any" to closedby="closerequest" so the native dialog does not double-handle). It never affects Escape or explicit close requests.
• data-dialog-modal="false" makes direct openDialog() calls use show() instead of showModal(). The show-modal and --show commands override this default.
• data-dialog-view-transition enables a view transition that morphs the dialog to/from its trigger. Only active when the browser supports document.startViewTransition and the user allows motion.
• closedby keeps its native meaning: "any" closes on backdrop click and Escape, "closerequest" closes on Escape only, "none" disables both. The runtime rewrites closedby="any" to closedby="closerequest" only when data-dialog-dismissible opts it into light dismiss, and never overrides closedby="none". Use closedby="none" for critical dialogs that must be closed by an explicit action.

Browser support

Actual relies on the native <dialog> API in its supported JavaScript range (Safari 17+, Firefox 125+, Chromium 116+). No dialog polyfill or fallback shim is shipped.

Animation

The base CSS gives supporting browsers small enter and exit transitions. Exit motion relies on transition-behavior: allow-discrete so the native dialog can remain in the top layer while display and overlay transition out. Browsers without that support keep native close behavior.

The open dialog root intentionally ends at transform: none; fixed flyouts and tooltips authored inside a modal dialog rely on viewport coordinates.

View transition

Add data-dialog-view-transition to morph the dialog to/from its trigger using the View Transition API. The dialog appears to grow out of the trigger on open and shrink back into it on close, communicating the relationship between the two.

The effect is progressive: it only runs when the browser supports document.startViewTransition and the user has not requested reduced motion. Otherwise the dialog simply opens and closes with the baseline dialog transition.

Notes

Web Components

The dialog runtime automatically enhances ordinary page dialogs. Dialogs inside a custom element (including nested light DOM hosts) or a Shadow DOM keep their component's native lifecycle; Actual leaves their command buttons untouched. The .modal styles remain independent of this behavior.

To delegate a light DOM dialog to Actual, add data-enhance="dialog" before inserting it, including when a custom element is only an application container:

<my-app>
  <dialog class="modal" id="preferences" data-enhance="dialog">
    <form method="dialog">…</form>
  </dialog>
</my-app>

For an existing light DOM dialog, use applyEnhancement("dialog", "dialog", scope) from actual-css/js/enhance. Document discovery does not enter shadow roots: a marked shadow dialog is wired on its first routed command. Calling openDialog() from actual-css/js/dialog also explicitly delegates to Actual, in either DOM tree; use Actual's exported close helpers for subsequent programmatic actions. Shadow-root disposal remains application-owned.

Prefer native dialog behavior whenever possible. The framework runtime should not replace the platform modal system; it should only make dialogs declarative, animation-friendly, and consistent across supported browsers.

CSS hooks

• --modal-size — maximum dialog width. Fallback-only, so a class on the dialog or an inherited value both reach it. A dialog is shrink-to-fit: a composition that must fill this width sets inline-size as well.
• --modal-pad — padding of the direct <form> or .stack content wrapper.
• --dialog-viewport-gap — distance kept between the dialog and the viewport edges.
• --dialog-icon-size — diameter of the .dialog-icon circle. The heading beside a leading icon reads the same hook to center on it, so set it on the icon's media row (or the dialog) and both inherit one value. A value on the icon alone sizes only the circle.
• --dialog-icon-glyph-size — size of the glyph centered inside .dialog-icon; same placement as --dialog-icon-size.
• --close-size / --close-icon-size — size of the corner .close and of its X. The header reserves the close size, its edge inset, and a content gap so the title never runs under it.