Primitives Overlays
Dialog
A native modal dialog, centered, at an edge as a drawer, or as an alert dialog that asks for a decision.
Markdown version of this page, for assistants (Markdown for AI)
On this page
Code
<script lang="ts">
// Nothing to import for the dialog itself: the browser owns it. The stylesheets are optional.
import '@svelte-lean/styles/button.css';
import '@svelte-lean/styles/checkbox.css';
import '@svelte-lean/styles/dialog.css';
</script>
<button type="button" data-slean="button" commandfor="settings" command="show-modal">
Settings
</button>
<dialog id="settings" data-slean="dialog" closedby="any" aria-labelledby="settings-title">
<header>
<h2 id="settings-title">Settings</h2>
<p>Changes apply to this device.</p>
</header>
<div class="options">
<label><input type="checkbox" name="telemetry" data-slean="checkbox" /> Send usage statistics</label>
<label><input type="checkbox" name="sounds" data-slean="checkbox" checked /> Play sounds</label>
</div>
<footer>
<button type="button" data-slean="button" data-variant="text" commandfor="settings" command="close">
Cancel
</button>
<button type="button" data-slean="button" commandfor="settings" command="close">Save</button>
</footer>
<button type="button" data-slean-part="close" commandfor="settings" command="close" aria-label="Close"></button>
</dialog>
<style>
.options {
display: grid;
gap: 0.75rem;
}
</style>Examples
Drawer
Code
<script lang="ts">
import '@svelte-lean/styles/button.css';
import '@svelte-lean/styles/checkbox.css';
import '@svelte-lean/styles/dialog.css';
const teams = ['Engineering', 'Design', 'Operations', 'Growth'];
</script>
<button type="button" data-slean="button" data-variant="outlined" commandfor="filters" command="show-modal">
Filters
</button>
<!-- data-slean-side makes it a drawer; closedby="any" closes it on a click outside. -->
<dialog id="filters" data-slean="dialog" data-slean-side="right" closedby="any" aria-labelledby="filters-title">
<header>
<h2 id="filters-title">Filters</h2>
<p>Narrow the list of people.</p>
</header>
<fieldset class="options">
<legend>Team</legend>
{#each teams as team (team)}
<label><input type="checkbox" name="team" value={team} data-slean="checkbox" /> {team}</label>
{/each}
</fieldset>
<footer>
<button type="button" data-slean="button" commandfor="filters" command="close">Show results</button>
</footer>
<button type="button" data-slean-part="close" commandfor="filters" command="close" aria-label="Close"></button>
</dialog>
<style>
.options {
display: grid;
gap: 0.75rem;
margin: 0;
padding: 0;
border: 0;
}
</style>Sides
Code
<script lang="ts">
import '@svelte-lean/styles/button.css';
import '@svelte-lean/styles/dialog.css';
// The side is physical: right stays right in a right-to-left page.
const sides = ['left', 'top', 'bottom'] as const;
</script>
{#each sides as side (side)}
<button type="button" data-slean="button" data-variant="outlined" data-color="neutral" commandfor="drawer-{side}" command="show-modal">
{side}
</button>
<dialog id="drawer-{side}" data-slean="dialog" data-slean-side={side} closedby="any" aria-labelledby="drawer-{side}-title">
<header><h2 id="drawer-{side}-title">Drawer at the {side}</h2></header>
<p>{side === 'left' ? 'A side panel, as tall as the viewport.' : 'A sheet, as tall as its content.'}</p>
<footer>
<button type="button" data-slean="button" data-variant="outlined" data-color="neutral" commandfor="drawer-{side}" command="close">
Close
</button>
</footer>
</dialog>
{/each}Alert dialog
Answer: none yet
Code
<script lang="ts">
import '@svelte-lean/styles/button.css';
import '@svelte-lean/styles/dialog.css';
let answer = $state('none yet');
// returnValue holds the value of the action that closed the dialog. Reset it after reading:
// where closedby is not implemented, Escape closes without changing it.
function onclose(event: Event & { currentTarget: HTMLDialogElement }) {
answer = event.currentTarget.returnValue || 'cancel';
event.currentTarget.returnValue = '';
}
</script>
<button type="button" data-slean="button" data-color="error" commandfor="delete-project" command="show-modal">
Delete project
</button>
<p role="status">Answer: {answer}</p>
<!-- role="alertdialog" and closedby="none": only the two actions close it. -->
<dialog
id="delete-project"
data-slean="dialog"
role="alertdialog"
closedby="none"
aria-labelledby="delete-project-title"
aria-describedby="delete-project-text"
{onclose}
>
<header>
<h2 id="delete-project-title">Delete this project?</h2>
<p id="delete-project-text">The project and its history are removed. This cannot be undone.</p>
</header>
<footer>
<!-- svelte-ignore a11y_autofocus -->
<button type="button" data-slean="button" data-variant="text" data-color="neutral" commandfor="delete-project" command="close" value="cancel" autofocus>
Cancel
</button>
<button type="button" data-slean="button" data-color="error" commandfor="delete-project" command="close" value="delete">
Delete project
</button>
</footer>
</dialog>Form
Ada Byron, ada@example.com
Code
<script lang="ts">
import '@svelte-lean/styles/button.css';
import '@svelte-lean/styles/field.css';
import '@svelte-lean/styles/input.css';
import '@svelte-lean/styles/dialog.css';
let name = $state('Ada Byron');
let email = $state('ada@example.com');
let saved = $state({ name: 'Ada Byron', email: 'ada@example.com' });
// Save submits the form (the browser checks required and type="email" first); Cancel, Escape
// and the close button keep the saved values.
function onclose(event: Event & { currentTarget: HTMLDialogElement }) {
if (event.currentTarget.returnValue === 'save') saved = { name, email };
else ({ name, email } = saved);
event.currentTarget.returnValue = '';
}
</script>
<button type="button" data-slean="button" data-variant="outlined" commandfor="profile" command="show-modal">
Edit profile
</button>
<p>{saved.name}, {saved.email}</p>
<!-- A form method="dialog" child keeps header and footer as the dialog's own. -->
<dialog id="profile" data-slean="dialog" aria-labelledby="profile-title" {onclose}>
<form method="dialog">
<header><h2 id="profile-title">Edit profile</h2></header>
<div class="fields">
<div data-slean="field">
<label for="profile-name" data-slean-part="label">Name</label>
<input id="profile-name" data-slean="input" required bind:value={name} />
</div>
<div data-slean="field">
<label for="profile-email" data-slean-part="label">Email</label>
<input id="profile-email" type="email" data-slean="input" required bind:value={email} />
</div>
</div>
<footer>
<button type="submit" data-slean="button" data-variant="text" value="cancel" formnovalidate>Cancel</button>
<button type="submit" data-slean="button" value="save">Save</button>
</footer>
</form>
</dialog>
<style>
.fields {
display: grid;
gap: 1rem;
}
</style>Scrolling content
Code
<script lang="ts">
import '@svelte-lean/styles/button.css';
import '@svelte-lean/styles/dialog.css';
const sections = [
['Accounts', 'You are responsible for the activity of your account and for keeping its password private.'],
['Content', 'You keep the rights to what you upload. We store it and show it to the people you share it with.'],
['Acceptable use', 'Do not use the service to send spam, to break the law or to probe the security of other customers.'],
['Payments', 'Paid plans renew each month until cancelled. A cancelled plan stays active until the period ends.'],
['Refunds', 'A plan cancelled within fourteen days of its first payment is refunded in full.'],
['Data', 'We keep your data in the region you choose. An export of every project is available at any time.'],
['Availability', 'We announce planned maintenance a week in advance on the status page.'],
['Termination', 'You can close your account at any time. We delete its data within thirty days.'],
['Changes', 'We announce changes to these terms by email at least two weeks before they apply.'],
['Privacy', 'We collect only what the service needs to run and never sell it.'],
['Support', 'Paid plans include support by email on working days.'],
['Liability', 'Our liability is limited to the amount you paid in the twelve months before a claim.']
];
</script>
<button type="button" data-slean="button" data-variant="outlined" commandfor="terms" command="show-modal">
Read the terms
</button>
<!-- The dialog scrolls; its header, its footer and the close button stay in view. -->
<dialog id="terms" data-slean="dialog" data-size="large" aria-labelledby="terms-title">
<header>
<h2 id="terms-title">Terms of service</h2>
<p>Last updated on 1 October 2026.</p>
</header>
{#each sections as [title, text] (title)}
<h3>{title}</h3>
<p>{text}</p>
{/each}
<footer>
<button type="button" data-slean="button" data-variant="text" commandfor="terms" command="close">Decline</button>
<button type="button" data-slean="button" commandfor="terms" command="close">Accept</button>
</footer>
<button type="button" data-slean-part="close" commandfor="terms" command="close" aria-label="Close"></button>
</dialog>Image preview
Code
<script lang="ts">
import '@svelte-lean/styles/button.css';
import '@svelte-lean/styles/dialog.css';
</script>
<button type="button" class="thumb" commandfor="photo" command="show-modal" aria-label="Enlarge: the east pier at night">
<img src="/demo/card-harbor.svg" alt="" width="160" height="90" />
</button>
<dialog id="photo" data-slean="dialog" data-size="large" closedby="any" aria-label="The east pier at night">
<img src="/demo/card-harbor.svg" alt="The east pier at night, a lighthouse against the sky" width="640" height="360" />
<button type="button" data-slean-part="close" commandfor="photo" command="close" aria-label="Close"></button>
</dialog>
<style>
.thumb {
padding: 0;
border: 1px solid var(--slean-border);
border-radius: var(--slean-radius-sm);
background: none;
cursor: zoom-in;
overflow: hidden;
line-height: 0;
}
img {
display: block;
inline-size: 100%;
block-size: auto;
border-radius: var(--slean-radius-sm);
}
</style>Usage
Plain markup with a stylesheet: install @svelte-lean/styles. No JavaScript runs.
npm install @svelte-lean/stylespnpm add @svelte-lean/stylesyarn add @svelte-lean/stylesbun add @svelte-lean/stylesimport '@svelte-lean/styles/dialog.css';Give the dialog an id and a name (aria-labelledby on the title, or aria-label); a button with commandfor and command="show-modal" opens it, command="close" or a <form method="dialog"> closes it. Write <header> with a heading and a <p>, the content, and <footer> with the actions: the stylesheet matches them by element. Add closedby="any" for a click outside to close it.
data-slean-side="right|left|top|bottom" makes it a drawer. role="alertdialog", closedby="none", aria-describedby on the question and autofocus on the least destructive action make it an alert dialog. The package also exports types, and where invoker commands are missing the fallback is the two calls a command would make:
import type { DialogClosedBy, DialogCommand, DialogSide } from '@svelte-lean/primitives/dialog';
const command: DialogCommand = 'show-modal'; // 'show-modal' | 'close' | 'request-close'
const side: DialogSide = 'right'; // data-slean-side: 'top' | 'right' | 'bottom' | 'left'
const closedby: DialogClosedBy = 'none'; // an alert dialog<!-- Only where invoker commands are missing: the same two calls the command would make. -->
<button type="button" onclick={() => settings.showModal()}>Settings</button>
<dialog id="settings" data-slean="dialog" bind:this={settings}>
…
<button type="button" onclick={() => settings.close()}>Close</button>
</dialog>Anatomy
| Part | Element | data-slean-part | Required | Notes |
|---|---|---|---|---|
| root | <dialog id="…"> | – | yes | An id for the invoker and an accessible name (aria-labelledby or aria-label). data-slean-side="right|left|top|bottom" makes it a drawer; role="alertdialog" with closedby="none" an alert dialog. |
| invoker | <button type="button" commandfor="<id>" command="show-modal"> | – | yes | Opens the dialog as a modal. command="close" inside the dialog closes it. |
| header | <header> (a child of the dialog or of its form) | header | styles only | Matched by element; sticky at the top while the dialog scrolls. |
| title | the first heading of the header | title | styles only | The element aria-labelledby points at. |
| description | a <p> right after the title | description | styles only | The question of an alert dialog; reference it with aria-describedby. |
| footer | <footer> (a child of the dialog or of its form) | footer | styles only | The actions, at the inline end; sticky at the bottom. |
| close | <button type="button" aria-label="Close"> | close | no | An icon button drawn at the top end corner; write it last so it is not the first tab stop. command="close" closes the dialog (native). |
Keyboard
| Key | When | Result |
|---|---|---|
| Enter/Space | focus on the invoker | Opens the dialog (native) |
| Escape | dialog open | Closes a modal dialog: cancel, then close (native); nothing on an alert dialog with closedby="none" |
| Tab/Shift+Tab | dialog open | Stays inside the dialog because the rest of the document is inert (native) |
Styling
dialog.css styles the native [open] state and ::backdrop: the entrance uses @starting-style, the exit keeps the element in the top layer through transition-behavior: allow-discrete on display and overlay; a drawer slides from its edge. The header, title, description and footer are matched by element (data-slean-part names a <div> that plays one), header and footer stay in view while the dialog scrolls, and data-slean-part="close" draws the corner button. Sizes are data-size="small" and "large". The tokens it reads and the states it targets:
| Token | Default (light) | Applies to |
|---|---|---|
--slean-space-8 | calc(var(--slean-spacing) * 10) | inline-size, max-block-size |
--slean-dialog-padding | var(--slean-space-6) | padding, inset-block-start, margin, inset-block-end, padding-inline-end, padding-block, padding-right, padding-left, padding-top, padding-inline, padding-bottom |
--slean-dialog-gap | 0px | gap, margin |
--slean-border | var(--slean-neutral-6) | border, border-left, border-right, border-bottom, border-top, border-block-start |
--slean-dialog-radius | var(--slean-radius-lg) | border-radius, border-end-start-radius, border-end-end-radius, border-start-start-radius, border-start-end-radius |
--slean-surface | oklch(100% 0 0) | background |
--slean-fg | var(--slean-neutral-12) | color |
--slean-dialog-elevation | var(--slean-elevation-4) | box-shadow |
--slean-font-sans | Inter, ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif | font-family |
--slean-typography-body1-size | 1rem | font-size |
--slean-typography-body1-weight | 400 | font-weight |
--slean-typography-body1-line-height | 1.5 | line-height |
--slean-duration-normal | 160ms | transition |
--slean-ease | cubic-bezier(0.2, 0, 0, 1) | transition |
--slean-overlay | oklch(0% 0 0 / 0.4) | background |
--slean-space-1 | calc(var(--slean-spacing) * 1) | gap |
--slean-space-4 | calc(var(--slean-spacing) * 4) | padding, inset-block-start, margin, padding-inline-end, padding-block |
--slean-typography-h6-size | 1rem | font-size |
--slean-typography-h6-weight | 600 | font-weight |
--slean-typography-h6-line-height | 1.5 | line-height |
--slean-fg-muted | var(--slean-neutral-11) | color |
--slean-typography-body2-size | 0.875rem | font-size |
--slean-typography-body2-weight | 400 | font-weight |
--slean-typography-body2-line-height | 1.45 | line-height |
--slean-space-2 | calc(var(--slean-spacing) * 2) | gap |
--slean-control-height-sm | 2rem | inline-size, block-size, margin, padding-inline-end |
--slean-radius-full | 9999px | border-radius |
--slean-duration-fast | 100ms | transition |
--slean-icon-close | url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M4.5 4.5l7 7m0-7l-7 7' stroke='black' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round' fill='none'/%3E%3C/svg%3E") | mask |
--slean-muted | var(--slean-neutral-3) | background |
--slean-focus-ring | var(--slean-focus-ring-width) solid var(--slean-focus-ring-color) | outline |
--slean-focus-ring-offset | 2px | outline-offset |
--slean-duration-slow | 240ms | transition |
State selectors the stylesheet targets, all from the platform or ARIA: ::backdrop, :first-child, :focus-visible, :hover, [open], [role="alertdialog"].
Variant attributes: data-size (small, large); data-slean-side (right, left, top, bottom).
Controlled integration
The dialog's state is its open attribute and its returnValue. Listen to the native close and cancel events and call showModal() or close() to open or close from code. The package mirrors nothing and dispatches no slean:* event for a dialog.
<script lang="ts">
let dialog: HTMLDialogElement;
let outcome = $state('');
// The dialog dispatches close after command="close", Escape and a <form method="dialog">
// submit; returnValue carries the button's value. No open state is mirrored.
function onclose() {
outcome = dialog.returnValue;
dialog.returnValue = '';
}
</script>
<button type="button" onclick={() => dialog.showModal()}>Open from code</button>
<dialog id="confirm" data-slean="dialog" aria-labelledby="confirm-title" bind:this={dialog} {onclose}>
…
</dialog>Under the hood
Runtime and size
- Tier
- 0 · Native
- Behavior JS
- 0 B brotli · 0 B gzip ·
fixtures/· methodresults.json (native-only) - Platform features
<dialog>,showModal(),command,commandfor,closedby,top layer,::backdrop,position: sticky- Shared listeners
- none
- Per-instance listeners
- none
- Lazy state
- none
- Native base
<dialog> + command/commandfor
Tier 0: the native-only fixture, a production Vite build of a page with button, dialog and popover markup, has no @svelte-lean/core or @svelte-lean/primitives module, no data-slean selector and no slean: event string in its output. Nothing is attached at hydration: no listener, no state object, no observer, no scroll lock.
Why this implementation
A modal needs a top layer above everything else, an inert page behind it, Escape to close, focus moved in on open and returned on close, and a backdrop. showModal() provides all five, and invoker commands (commandfor, command) let a button call it declaratively.
A drawer and an alert dialog are the same element: the drawer is a geometry (data-slean-side), the alert dialog a role and a close policy the platform already names (role="alertdialog", closedby="none"). So one primitive covers the three (ADR 0011 §1.4), with no open-state controller, focus trap, portal, z-index manager or click listener (ADR 0001).
The browser owns
- opening and closing through command="show-modal" and command="close"
- the modal top layer, the backdrop and page inertness
- Escape (cancel, then close), light dismiss with closedby="any", no dismiss with closedby="none"
- the returnValue of a <form method="dialog"> or a close command
- moving focus into the dialog and returning it to the invoker
- dialog and alertdialog semantics and the relationship of the invoker
Svelte Lean owns
- dialog.css: the surface, sizes, the drawer at four edges, the alert dialog, transitions, sticky header and footer matched by element, the close button
- the contract and the DialogCommand, DialogSide and DialogClosedBy types
- documentation
Accessibility
- A
<dialog>with anidand an accessible name:aria-labelledbypointing at the title, oraria-label. An alert dialog also hasrole="alertdialog"andaria-describedbypointing at the question. - Modal through
command="show-modal". Closing throughcommand="close"inside the dialog, or a<form method="dialog">whose submit button closes it with a return value. A drawer keeps a visible close action: a touch screen may have no Escape key. - Focus:
showModal()moves focus into the dialog, to the element withautofocuswhen there is one; closing returns focus to the element focused before opening. Write the close button last, so it is not the first tab stop. closedby="none"on an alert dialog: Escape and a click outside do nothing where the attribute is implemented, so only an explicit answer closes it.
Platform features
| Feature | Baseline | Outside the target |
|---|---|---|
<dialog>, showModal(), top layer, ::backdrop, page inertness | Widely available (newly available in 2022) | Not applicable within the support policy |
Invoker commands (command, commandfor) | Newly available: Chrome 135, Safari 26 and Firefox 144 (2025); not yet widely available | The dialog stays closed. Fallback: a two-line script calling showModal() and close(). The package ships no polyfill. |
closedby | Chrome 134 and Firefox 141; not in Safari 27 | A click outside does not close a drawer; Escape still cancels an alert dialog (a cancel listener can block it) |
@starting-style, transition-behavior: allow-discrete | Baseline 2024 | The dialog appears and disappears without the transition |
overlay (exit transition) | Chrome 117; not in Firefox or Safari 27 | The dialog closes without the exit transition |
Without JavaScript
With invoker commands supported, every shape opens and closes with no script at all; the playground runs the dialog, drawer and alert dialog assertions with page JavaScript disabled. Without invoker commands and without script it stays closed.
Server rendering and hydration
Static HTML. Modal dialogs open on the client only, so the server never renders an open modal; open may be rendered for a non-modal dialog. Ids are authored, never generated, so aria-labelledby and commandfor are correct in the server HTML.
The delayed-hydration test opens the dialog through its invoker, checks :modal, presses Escape and asserts that focus returned, all before any script has loaded. Hydration attaches nothing to a dialog.
Compatibility
<dialog>, showModal(), the top layer, ::backdrop and inertness are Baseline widely available. Invoker commands are newly available (Chrome 135, Safari 26, Firefox 144); where they are missing the dialog stays closed, and the package does not polyfill the attribute. closedby is in Chrome 134 and Firefox 141, not in Safari 27: there a click outside does not close a drawer and Escape still cancels an alert dialog.
Tests and source
apps/playground/tests/primitives/native.spec.tsPlaywright, with page JavaScript enabled and disabledapps/playground/tests/primitives/inputs-overlays.spec.tsPlaywright, with page JavaScript enabled and disabled: the drawer at its edges, the alert dialog closed only by its actions, a long dialog with sticky header, footer and close button, axeapps/playground/tests/primitives/overlay-exit.spec.tsthe layout of every shape holds while it animates closedapps/playground/tests/primitives/a11y.spec.tsaxe on every playground page and on open dialog, popover and menu statesfixtures/native-onlyconsumer build asserting that no behavior runtime ships (invariant A)packages/primitives/scripts/size.mjsthe native-only build that must contain no runtime
packages/primitives/src/dialog/contract.mdthe contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behaviorpackages/primitives/src/dialog/contract.tstyped constants: name, tier, base, parts, options, eventspackages/styles/css/dialog.cssthe optional stylesheet