Empty State
No projects yet
Create your first project to get started.
No results for “tofu”
Check the spelling or try a broader search.
A centered message shown when there is no content to show and nothing has failed: first run, an empty list, no search results, a cleared inbox. It looks calm and offers the next step: an illustration, a title, an optional description, and an action area at the bottom.
Empty state vs error state
Section titled “Empty state vs error state”Two different concepts (per Nielsen Norman Group):
- Empty state (this component): nothing went wrong, there is simply no content yet. The user needs to get started, so the action is an invitation (“Add a project”, “Clear filters”).
- Error state: something failed (500, timeout, lost connection). The user needs to recover (retry, reload, go back).
Same layout, different intent: the two components share their anatomy on purpose, so a screen can switch between them without moving anything.
When to use
Section titled “When to use”The three empty moments, each with its own copy:
- First use: the feature has never been filled. Explain what will live here and invite the first step. “No projects yet. Create your first project to get started.” The children can hold a learning cue (a short tip, starter links) that teaches how this space gets populated.
- No results: a search or filter came back empty. Show the term, suggest a correction, and offer a way out. “No results for ‘tofu’. Check the spelling or try a broader search.” with a “Clear search” action.
- Cleared by the user: the work is done (an emptied inbox, a completed
list). Celebrate quietly with
status="success". “All done. Nothing needs your attention.”
One timing rule: the empty state appears only after the data has answered. While the request runs, show a Loading or a Skeleton; declaring “nothing here” during a load misleads. The full cycle (initial moment, query running, then content, empty or error) is a composition pattern on the backlog.
Import
Section titled “Import”<script> import EmptyState from "@invisible-ui/svelte/EmptyState.svelte";</script><script setup> import { EmptyState } from "@invisible-ui/vue";</script>import { EmptyState } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-empty-state></ds-empty-state>| Prop | Type | Default | Description |
|---|---|---|---|
title * | string | — | The headline — what this space is for, in plain language. |
description | string | undefined | undefined | Optional secondary line — detail or the suggested next step. |
status | "info" | "success" | "warning" | "danger" | "neutral" | "neutral" | Feedback status driving the fallback icon's color and glyph. |
headingLevel | 1 | 2 | 3 | 4 | 5 | 6 | 2 | Heading level for the title, so it fits the surrounding document outline. |
actionLabel | string | undefined | undefined | Action button label (e.g. "Add a project"). Omit to render no button. |
onAction | (() => void) | undefined | undefined | Called when the action button is pressed. |
actions | { label: string; onAction?: () => void; variant?: ButtonVariant; href?: string; target?: string; }[] | Snippet | [] | Configurable action group. An entry with href renders a Link (a direct pathway, e.g. "Learn more" documentation); the others render Buttons: the first gets the default variant and the rest ghost, unless an entry sets its own variant. Takes precedence over actionLabel. A snippet in its place replaces the whole area. |
size | "md" | "sm" | "md" | Density: md for full pages and sections, sm inside cards, panels and table areas. |
illustration | Snippet | undefined | undefined | Bespoke artwork in place of the fallback FeedbackIcon. |
| Prop | Type | Default | Description |
|---|---|---|---|
title * | string | — | The headline: what this space is for, in plain language. |
description | string | undefined | Optional secondary line: detail or the suggested next step. |
status | FeedbackStatus | "neutral" | Feedback status driving the fallback icon's color and glyph. |
headingLevel | 1 | 2 | 3 | 4 | 5 | 6 | 2 | Heading level for the title, so it fits the surrounding document outline. |
actionLabel | string | undefined | Action button label (e.g. "Add a project"). Omit to render no button. |
onAction | () => void | undefined | Called when the action button is pressed. |
actions | EmptyStateAction[] | () => [] | Configurable action group. An entry with href renders a Link (a direct pathway, e.g. "Learn more" documentation); the others render Buttons: the first gets the default variant and the rest ghost, unless an entry sets its own variant. Takes precedence over actionLabel; the actions slot replaces the whole area. |
size | "md" | "sm" | "md" | Density: md for full pages and sections, sm inside cards, panels and table areas. |
Slots: actions, default, illustration.
| Prop | Type | Default | Description |
|---|---|---|---|
title * | string | — | The headline: what this space is for, in plain language. |
description | string | — | Optional secondary line: detail or the suggested next step. |
status | FeedbackStatus | "neutral" | Feedback status driving the fallback icon's colour and glyph. |
headingLevel | 1 | 2 | 3 | 4 | 5 | 6 | 2 | Heading level for the title, so it fits the surrounding document outline. |
actionLabel | string | — | Action button label (such as "Add a project"). Omit it to render no button. |
onAction | () => void | — | Called when the action button is pressed. |
actions | EmptyStateAction[] | ReactNode | — | The action area: entries, or markup of your own. An entry with href renders a Link; the others render Buttons, the first default and the rest ghost unless an entry sets its own variant. Takes precedence over actionLabel. |
size | "md" | "sm" | "md" | Density: md for pages and sections, sm inside cards, panels and tables. |
illustration | ReactNode | — | Artwork of your own, in place of the fallback FeedbackIcon. |
children | ReactNode | — | Extra content between the description and the actions. |
| Attribute | Reactive | Description |
|---|---|---|
title * | yes | |
description | yes | |
status | yes | |
heading-level | yes | |
size | yes | |
action-label | yes | |
live | yes |
Reactive attributes re-render the element when they change after the first render.
Events: action when the generated action button is pressed.
Every href is rendered as given: pass only URLs you trust or have
sanitized. See Security.
Anatomy & reuse
Section titled “Anatomy & reuse”It composes existing primitives, no new behavior:
- Illustration: the space at the top accepts your own artwork through the
illustrationsnippet (an SVG, an image, anything). Without it, the theme’s FeedbackIcon renders as the fallback (neutralby default, so the tone stays calm). - Actions: Buttons and
Links. One inviting button
comes from
actionLabel/onAction; a configurable group comes from theactionsprop: an array of{ label, onAction, variant, href }where the first action renders in thedefaultvariant and the rest inghost(unless an entry sets its ownvariant), and an entry withhrefrenders as a link (e.g. “Learn more” documentation). For anything else, anactionssnippet replaces the whole area. Omit all three for no actions. - Density:
size="sm"compacts padding, icon and title for use inside cards, panels and table areas; the defaultmdfits pages and sections.
Accessibility
Section titled “Accessibility”- The region is a
role="status"(a polite live region): when content resolves to empty, the change is announced without interrupting what the user is doing. - Meaning never rests on color alone: the title carries it (WCAG 1.4.1).
headingLevel(default2) sets the title’s heading level so it fits the surrounding document outline.
Example
Section titled “Example”<EmptyState title="No projects yet" description="Create your first project to get started." actionLabel="Add a project" onAction={() => createProject()}/>Elements keeps custom illustration, supporting content, and custom actions in
light DOM. The generated action emits a bubbling action event:
<ds-empty-state title="No rules yet" description="Create the first rule to get started." action-label="Add rule"></ds-empty-state>
<script type="module"> document.querySelector("ds-empty-state").addEventListener("action", addRule);</script>Use slot="illustration" to replace the fallback artwork and slot="actions"
to compose multiple buttons or links. Unslotted children add supporting
content.
In React, illustration, actions and children take markup, and
actions also takes entries:
<EmptyState title="No projects yet" description="Create your first project to get started." actions={[ { label: "Add a project", onAction: createProject }, { label: "Learn more", href: "/docs/projects" }, ]}/>Themeable via --ds-empty-state-* (gap, padding, max-width, icon size,
illustration max-width, title size).