Alert

Example

<div data-slean="alert" data-variant="info">
	<span data-slean-part="icon" aria-hidden="true"></span>
	<p data-slean-part="title">Exports include the time zone</p>
	<p data-slean-part="description">CSV files now carry an offset column. Older imports keep working.</p>
</div>
<div data-slean="alert" data-variant="success">
	<span data-slean-part="icon" aria-hidden="true"></span>
	<p data-slean-part="title">Domain verified</p>
	<p data-slean-part="description">Mail for harbor.studio now arrives in the workspace.</p>
</div>
<div data-slean="alert" data-variant="warning">
	<span data-slean-part="icon" aria-hidden="true"></span>
	<p data-slean-part="title">The trial ends in three days</p>
	<p data-slean-part="description">Choose a plan to keep the projects and their history.</p>
	<div data-slean-part="actions">
		<button type="button" data-slean="button" data-size="sm">Choose a plan</button>
		<button type="button" data-slean="button" data-size="sm" data-variant="ghost">Later</button>
	</div>
</div>
<div data-slean="alert" data-variant="danger">
	<span data-slean-part="icon" aria-hidden="true"></span>
	<p data-slean-part="title">The last deploy failed</p>
	<p data-slean-part="description">The build stopped at the type check. The previous version is still live.</p>
</div>

<script lang="ts">
	// Nothing to import at runtime: the alert is markup. The stylesheets are optional.
	import '@svelte-lean/styles/button.css';
	import '@svelte-lean/styles/alert.css';
</script>

<div data-slean="alert" data-variant="info">
	<span data-slean-part="icon" aria-hidden="true"></span>
	<p data-slean-part="title">Exports include the time zone</p>
	<p data-slean-part="description">CSV files now carry an offset column. Older imports keep working.</p>
</div>
<div data-slean="alert" data-variant="success">
	<span data-slean-part="icon" aria-hidden="true"></span>
	<p data-slean-part="title">Domain verified</p>
	<p data-slean-part="description">Mail for harbor.studio now arrives in the workspace.</p>
</div>
<div data-slean="alert" data-variant="warning">
	<span data-slean-part="icon" aria-hidden="true"></span>
	<p data-slean-part="title">The trial ends in three days</p>
	<p data-slean-part="description">Choose a plan to keep the projects and their history.</p>
	<div data-slean-part="actions">
		<button type="button" data-slean="button" data-size="sm">Choose a plan</button>
		<button type="button" data-slean="button" data-size="sm" data-variant="ghost">Later</button>
	</div>
</div>
<div data-slean="alert" data-variant="danger">
	<span data-slean-part="icon" aria-hidden="true"></span>
	<p data-slean-part="title">The last deploy failed</p>
	<p data-slean-part="description">The build stopped at the type check. The previous version is still live.</p>
</div>

Why this implementation exists

An alert is text in a tinted box. What decides whether a screen reader user hears it is the live region: role="status" for a polite message, role="alert" for an urgent one, and the rule that a region is announced when its content changes, not when it arrives together with its text.

Svelte Lean ships the box and the rule. alert.css draws the tones from the soft status tokens and one mark per tone, so the tone does not rest on color alone. An empty alert draws nothing, so the root can wait in the page as the status region the application writes into.

Usage

The markup needs no package. Install @svelte-lean/styles for the stylesheet; @svelte-lean/primitives adds the typed contract and nothing at runtime.

npm install @svelte-lean/styles

pnpm add @svelte-lean/styles

yarn add @svelte-lean/styles

bun add @svelte-lean/styles

import '@svelte-lean/styles/alert.css';

Choose the role by when the message appears. Rendered with the page: no role. Written after an action and not urgent: role="status" on an element that is already in the page. Urgent: role="alert".

Set the tone with data-variant. Put the meaning in the title: the color and the icon are not read.

Anatomy

Runtime profile

Tier 0: the alert has no behavior module, the Vite plugin maps alert to no module, and the page ships no Svelte Lean JavaScript for it. The live region is the browser’s; the status example below uses one line of application state, not a package runtime.

Accessibility contract

• A message present at load has no live role: it is read in order with the rest of the page.
• role="status" (polite) for a message written after an action, on a region that exists before the message: an empty alert root, or a wrapper that stays.
• role="alert" (assertive) only for a message that needs attention now.
• The drawn icon is aria-hidden="true" and has no text.
• Showing an alert never moves focus; a message that needs an answer is an alert dialog.

Keyboard

Platform features

Without JavaScript

A message rendered with the page is fully visible and readable. A message that appears after an action needs the application’s script, or a new page from the server on which the message is present at load.

Server rendering

Render standing messages on the server without a live role. Render the region for later messages empty, so it exists before the first message is written into it.

Before hydration

Nothing is attached. An empty status region rendered on the server is the same element after hydration, so the first message written into it is a change the screen reader announces.

Styling

alert.css lays the parts out in two columns (the icon, then the text), tints the surface and the border per tone from the soft status tokens, colors the title and the icon with the tone’s foreground and keeps the description in the text color. An empty icon part draws an i, a check, an exclamation mark or a cross from its two pseudo-elements; under forced colors the box keeps its border and the marks their shapes. The tokens it reads:

State selectors the stylesheet targets, all from the platform or ARIA: :empty.

Variant attributes: data-variant (success, warning, danger, info).

Compatibility notes

The live region roles are ARIA 1.1 and exposed by every current browser. Screen readers differ in when and how they speak a change, which is why the contract keeps to the patterns that hold across them. color-mix() for the tone borders is Baseline 2023; without it the border is the neutral one.

Examples

Status after an action

The region is in the page from the start and empty; an empty alert draws nothing. Saving writes the title into it, the box appears, and a screen reader announces the change. Focus stays on the button.

<script lang="ts">
	let saved = $state(false);
</script>

<button type="button" data-slean="button" onclick={() => (saved = true)}>Save changes</button>

<!-- In the page from the start and empty, so the change is announced. -->
<div data-slean="alert" data-variant="success" role="status">
	{#if saved}
		<span data-slean-part="icon" aria-hidden="true"></span>
		<p data-slean-part="title">Changes saved</p>
	{/if}
</div>

Urgent message

role="alert" is assertive: it interrupts what the screen reader is saying. It fits a message that needs attention now, and an element inserted with it is announced.

<!-- Inserted when the session is about to expire: announced at once, focus stays. -->
<div data-slean="alert" data-variant="danger" role="alert">
	<span data-slean-part="icon" aria-hidden="true"></span>
	<p data-slean-part="title">The session ends in two minutes</p>
	<div data-slean-part="actions">
		<button type="button" data-slean="button" data-size="sm">Stay signed in</button>
	</div>
</div>

Testing

• apps/playground/tests/primitives/feedback-navigation.spec.ts Playwright: roles, names and states in the accessibility tree, keyboard, RTL, reduced motion, axe
• packages/styles/tests static checks of the stylesheet (layers, tokens, specificity, dark parity)

Source

• packages/primitives/src/alert/contract.md the contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behavior
• packages/primitives/src/alert/contract.ts typed constants: name, tier, base, parts, options, events
• packages/styles/css/alert.css the optional stylesheet