sveltelean Primitives
Version v0.18.0
Settings

Settings

Changes apply to this device.

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>
Open it and press Escape: focus returns to the button, and the page behind is inert. No script where the browser has invoker commands.

Examples

Drawer

Filters

Filters

Narrow the list of people.

Team
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>
data-slean-side attaches the dialog to an edge; closedby="any" closes it on a click outside.

Sides

Left, top and bottom

Drawer at the left

A side panel, as tall as the viewport.

Drawer at the top

A sheet, as tall as its content.

Drawer at the bottom

A sheet, as tall as its content.

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}
The side is physical: it does not flip in a right-to-left page.

Alert dialog

Delete project

Answer: none yet

Delete this project?

The project and its history are removed. This cannot be undone.

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>
role="alertdialog" and closedby="none": Escape and a click outside do nothing; focus starts on Cancel; the action's value is the returnValue.

Form

Edit profile

Ada Byron, ada@example.com

Edit profile

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>
The browser validates the fields before the dialog closes; Cancel skips validation.

Scrolling content

Terms of service

Terms of service

Last updated on 1 October 2026.

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.

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>
The dialog scrolls; its header, its footer and the close button stay in view.
Lightbox
The east pier at night, a lighthouse against the sky
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/styles
stylesheets
import '@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:

types only; registers nothing
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
fallback where commands are missing
<!-- 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

PartElementdata-slean-partRequiredNotes
root<dialog id="…">–yesAn 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">–yesOpens the dialog as a modal. command="close" inside the dialog closes it.
header<header> (a child of the dialog or of its form)headerstyles onlyMatched by element; sticky at the top while the dialog scrolls.
titlethe first heading of the headertitlestyles onlyThe element aria-labelledby points at.
descriptiona <p> right after the titledescriptionstyles onlyThe question of an alert dialog; reference it with aria-describedby.
footer<footer> (a child of the dialog or of its form)footerstyles onlyThe actions, at the inline end; sticky at the bottom.
close<button type="button" aria-label="Close">closenoAn 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

KeyWhenResult
Enter/Spacefocus on the invokerOpens the dialog (native)
Escapedialog openCloses a modal dialog: cancel, then close (native); nothing on an alert dialog with closedby="none"
Tab/Shift+Tabdialog openStays 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:

TokenDefault (light)Applies to
--slean-space-8calc(var(--slean-spacing) * 10)inline-size, max-block-size
--slean-dialog-paddingvar(--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-gap0pxgap, margin
--slean-bordervar(--slean-neutral-6)border, border-left, border-right, border-bottom, border-top, border-block-start
--slean-dialog-radiusvar(--slean-radius-lg)border-radius, border-end-start-radius, border-end-end-radius, border-start-start-radius, border-start-end-radius
--slean-surfaceoklch(100% 0 0)background
--slean-fgvar(--slean-neutral-12)color
--slean-dialog-elevationvar(--slean-elevation-4)box-shadow
--slean-font-sansInter, ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-seriffont-family
--slean-typography-body1-size1remfont-size
--slean-typography-body1-weight400font-weight
--slean-typography-body1-line-height1.5line-height
--slean-duration-normal160mstransition
--slean-easecubic-bezier(0.2, 0, 0, 1)transition
--slean-overlayoklch(0% 0 0 / 0.4)background
--slean-space-1calc(var(--slean-spacing) * 1)gap
--slean-space-4calc(var(--slean-spacing) * 4)padding, inset-block-start, margin, padding-inline-end, padding-block
--slean-typography-h6-size1remfont-size
--slean-typography-h6-weight600font-weight
--slean-typography-h6-line-height1.5line-height
--slean-fg-mutedvar(--slean-neutral-11)color
--slean-typography-body2-size0.875remfont-size
--slean-typography-body2-weight400font-weight
--slean-typography-body2-line-height1.45line-height
--slean-space-2calc(var(--slean-spacing) * 2)gap
--slean-control-height-sm2reminline-size, block-size, margin, padding-inline-end
--slean-radius-full9999pxborder-radius
--slean-duration-fast100mstransition
--slean-icon-closeurl("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-mutedvar(--slean-neutral-3)background
--slean-focus-ringvar(--slean-focus-ring-width) solid var(--slean-focus-ring-color)outline
--slean-focus-ring-offset2pxoutline-offset
--slean-duration-slow240mstransition

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.

confirm.svelte
<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/results.json (native-only) · method
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 an id and an accessible name: aria-labelledby pointing at the title, or aria-label. An alert dialog also has role="alertdialog" and aria-describedby pointing at the question.
  • Modal through command="show-modal". Closing through command="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 with autofocus when 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
FeatureBaselineOutside the target
<dialog>, showModal(), top layer, ::backdrop, page inertnessWidely 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 availableThe dialog stays closed. Fallback: a two-line script calling showModal() and close(). The package ships no polyfill.
closedbyChrome 134 and Firefox 141; not in Safari 27A click outside does not close a drawer; Escape still cancels an alert dialog (a cancel listener can block it)
@starting-style, transition-behavior: allow-discreteBaseline 2024The dialog appears and disappears without the transition
overlay (exit transition)Chrome 117; not in Firefox or Safari 27The 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