Primitives Feedback
Empty state
What a list, a table or a search result shows when it has nothing: a title, a message, an optional action and a decorative icon.
Markdown version of this page, for assistants (Markdown for AI)
On this page
No invoices yet
Invoices appear here after the first payment.
Code
<script lang="ts">
import '@svelte-lean/styles/button.css';
import '@svelte-lean/styles/empty.css';
</script>
<div data-slean="empty" data-variant="outlined">
<span data-slean-part="icon" aria-hidden="true"></span>
<h3 data-slean-part="title">No invoices yet</h3>
<p data-slean-part="description">Invoices appear here after the first payment.</p>
<div data-slean-part="actions">
<button type="button" data-slean="button">Set up billing</button>
<button type="button" data-slean="button" data-variant="text" data-color="neutral">Read about billing</button>
</div>
</div>Examples
After a search
No projects match “lantern”
Check the spelling or clear the search.
Code
<script lang="ts">
import '@svelte-lean/styles/button.css';
import '@svelte-lean/styles/empty.css';
import '@svelte-lean/styles/field.css';
import '@svelte-lean/styles/input.css';
const projects = ['Harbour survey', 'Lighthouse lamps', 'Pier repairs', 'Tide tables'];
let query = $state('lantern');
const matches = $derived(
projects.filter((p) => p.toLowerCase().includes(query.trim().toLowerCase()))
);
</script>
<div data-slean="field">
<label for="empty-search" data-slean-part="label">Search projects</label>
<input id="empty-search" type="search" data-slean="input" bind:value={query} />
</div>
<ul class="results">
{#each matches as project (project)}
<li>{project}</li>
{/each}
</ul>
<!-- The status region is always in the page; what is written into it is announced. -->
<div role="status">
{#if matches.length === 0}
<div data-slean="empty">
<span data-slean-part="icon" aria-hidden="true">
<svg viewBox="0 0 24 24" width="24" height="24">
<circle cx="10.5" cy="10.5" r="6" fill="none" stroke="currentColor" stroke-width="2" />
<path d="M15 15l5 5" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
</svg>
</span>
<p data-slean-part="title">No projects match “{query}”</p>
<p data-slean-part="description">Check the spelling or clear the search.</p>
<div data-slean-part="actions">
<button type="button" data-slean="button" data-variant="outlined" data-color="neutral" onclick={() => (query = '')}>
Clear search
</button>
</div>
</div>
{/if}
</div>
<style>
.results:empty {
display: none;
}
</style>In a table
| Invoice | Date | Amount |
|---|---|---|
No invoices in September Pick another month to see its invoices. | ||
Code
<script lang="ts">
import '@svelte-lean/styles/empty.css';
</script>
<table>
<thead>
<tr><th>Invoice</th><th>Date</th><th>Amount</th></tr>
</thead>
<tbody>
<tr>
<td colspan="3">
<div data-slean="empty">
<p data-slean-part="title">No invoices in September</p>
<p data-slean-part="description">Pick another month to see its invoices.</p>
</div>
</td>
</tr>
</tbody>
</table>
<style>
table {
inline-size: 100%;
border-collapse: collapse;
}
th {
padding: 0.5rem 0.75rem;
border-block-end: 1px solid var(--slean-border);
text-align: start;
}
</style>In a card
Team
People who can edit this workspace.
You are the only member
Invite people to share the workspace with them.
Code
<script lang="ts">
import '@svelte-lean/styles/button.css';
import '@svelte-lean/styles/card.css';
import '@svelte-lean/styles/empty.css';
</script>
<section data-slean="card" aria-labelledby="empty-team-title">
<header data-slean-part="header">
<h3 id="empty-team-title" data-slean-part="title">Team</h3>
<p data-slean-part="description">People who can edit this workspace.</p>
</header>
<div data-slean-part="body">
<div data-slean="empty">
<p data-slean-part="title">You are the only member</p>
<p data-slean-part="description">Invite people to share the workspace with them.</p>
<div data-slean-part="actions">
<button type="button" data-slean="button" data-size="small">Invite people</button>
</div>
</div>
</div>
</section>Text only
No notifications
You are up to date.
Code
<script lang="ts">
import '@svelte-lean/styles/empty.css';
</script>
<div data-slean="empty">
<p data-slean-part="title">No notifications</p>
<p data-slean-part="description">You are up to date.</p>
</div>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/button.css';
import '@svelte-lean/styles/empty.css';Render the empty state where the content would be, with a heading at the level that fits the page outline, or a <p> title inside a table cell, a menu or a small panel. Say why the place is empty and offer the action that fills it.
When the empty state replaces results after a search or a filter, write it into a role="status" region that is already in the page; the empty state itself has no role.
Anatomy
| Part | Element | data-slean-part | Required | Notes |
|---|---|---|---|---|
| root | <div data-slean="empty"> | – | yes | data-variant="outlined" draws a dashed border. No role of its own. |
| icon | <span aria-hidden="true"> | icon | no | Empty: a drawn tray. With an <svg>: sized to 1.5rem. |
| title | a heading, or <p> | title | no | What is empty, at the heading level that fits the page. |
| description | <p> | description | no | Why, and what fills it. |
| actions | <div> of links or buttons | actions | no | Centred; wraps on narrow widths. |
Keyboard
| Key | When | Result |
|---|---|---|
| Tab | anywhere | Reaches the actions (native); the empty state is not focusable |
Styling
empty.css centres the parts, draws the icon circle and the default tray, sets the title and description text and the dashed outline variant. The tokens it reads:
| Token | Default (light) | Applies to |
|---|---|---|
--slean-space-2 | calc(var(--slean-spacing) * 2) | gap, margin-block-end |
--slean-space-8 | calc(var(--slean-spacing) * 10) | padding-block |
--slean-space-6 | calc(var(--slean-spacing) * 6) | padding-inline |
--slean-fg | var(--slean-neutral-12) | color |
--slean-text-sm | 0.875rem | font-size |
--slean-leading | 1.5 | line-height |
--slean-border-strong | var(--slean-neutral-8) | border |
--slean-radius-lg | calc(var(--slean-radius) * 1.4) | border-radius |
--slean-muted | var(--slean-neutral-3) | background |
--slean-fg-muted | var(--slean-neutral-11) | color |
--slean-radius-sm | calc(var(--slean-radius) * 0.6) | border-end-start-radius, border-end-end-radius |
--slean-text-md | 1rem | font-size |
--slean-font-weight-semibold | 600 | font-weight |
--slean-space-3 | calc(var(--slean-spacing) * 3) | margin-block-start |
State selectors the stylesheet targets, all from the platform or ARIA: :empty.
Variant attributes: data-variant (outlined).
Under the hood
Runtime and size
- Tier
- 0 · Native
- Behavior JS
- 0 B brotli · 0 B gzip ·
fixtures/· methodresults.json (native-only) - Platform features
headings,links and buttons,:empty- Shared listeners
- none
- Per-instance listeners
- none
- Lazy state
- none
- Native base
a heading, a paragraph and an optional action
Tier 0: the empty state is content with a layout. It has no behavior module, the Vite plugin maps empty to no module, and the page ships no Svelte Lean JavaScript for it.
Why this implementation
An empty list is still a place in the page: the reader should learn what would be there, why it is not, and what to do about it. That is a heading, a paragraph and a link or a button; the application renders it when its collection is empty, and no state or script is involved.
empty.css centres the parts in a column, sizes the icon, keeps the message to a readable width and wraps the actions. The contract covers what markup alone does not decide: the heading level, the icon staying decorative, and how an empty search result is announced.
The browser owns
- the heading in the page outline, the paragraph, the link or button action
- hiding the decorative icon (aria-hidden)
Svelte Lean owns
- empty.css: the centred column, the icon circle and its drawn tray, the outlined variant
- the contract: heading level, what to say, how a changed result is announced
- documentation
Accessibility
- The title is a real heading (or a
<p>where a heading does not fit), so the empty section is found by heading navigation. - The icon is
aria-hidden="true"and says nothing the text does not. - Showing an empty state never moves focus; its actions are native links and buttons in the tab order.
- An empty result after a search is announced through a
role="status"region that exists before the search.
Platform features
| Feature | Baseline | Outside the target |
|---|---|---|
Headings, paragraphs, links, buttons | Widely available | Not applicable |
:empty with generated content | Widely available | Not applicable |
Without JavaScript
Fully functional: the text is markup and the actions are native links or buttons.
Server rendering and hydration
Static markup: the server renders the empty state when the collection is empty.
Nothing is attached; the empty state reads the same before and after hydration.
Compatibility
Headings, paragraphs, links, buttons, flex layout and generated content on :empty are Baseline widely available.
Tests and source
apps/playground/tests/primitives/display-extra.spec.tsPlaywright, with page JavaScript enabled and disabled: roles, names, keyboard, geometry, axepackages/styles/testsstatic checks of the stylesheet (layers, tokens, specificity, dark parity)
packages/primitives/src/empty/contract.mdthe contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behaviorpackages/primitives/src/empty/contract.tstyped constants: name, tier, base, parts, options, eventspackages/styles/css/empty.cssthe optional stylesheet