Skip to content

Empty State

No projects yet

Create your first project to get started.

No results for “tofu”

Check the spelling or try a broader search.

No favorites yet

Star any component and it appears here.

Learn more

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.

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.

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.

<script>
import EmptyState from "@invisible-ui/svelte/EmptyState.svelte";
</script>
PropTypeDefaultDescription
title *string—The headline — what this space is for, in plain language.
descriptionstring | undefinedundefinedOptional 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.
headingLevel1 | 2 | 3 | 4 | 5 | 62Heading level for the title, so it fits the surrounding document outline.
actionLabelstring | undefinedundefinedAction button label (e.g. "Add a project"). Omit to render no button.
onAction(() => void) | undefinedundefinedCalled 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.
illustrationSnippet | undefinedundefinedBespoke artwork in place of the fallback FeedbackIcon.

Every href is rendered as given: pass only URLs you trust or have sanitized. See Security.

It composes existing primitives, no new behavior:

  • Illustration: the space at the top accepts your own artwork through the illustration snippet (an SVG, an image, anything). Without it, the theme’s FeedbackIcon renders as the fallback (neutral by default, so the tone stays calm).
  • Actions: Buttons and Links. One inviting button comes from actionLabel/onAction; a configurable group comes from the actions prop: an array of { label, onAction, variant, href } where the first action renders in the default variant and the rest in ghost (unless an entry sets its own variant), and an entry with href renders as a link (e.g. “Learn more” documentation). For anything else, an actions snippet 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 default md fits pages and sections.
  • 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 (default 2) sets the title’s heading level so it fits the surrounding document outline.
<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).