Skip to content
WunderUI

Empty State

Free

A placeholder for a list, table or search that has nothing to show: what is missing, why, and what to do next.

npx wunderui-cli add empty-state

Playground

No projects yet

Projects hold tasks, files and members. Create the first one to get started.

Installation

bash
npx wunderui-cli add empty-state

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
import { EmptyState } from "@/components/wunderui/stat-card"

Then use it:

tsx
import { Button } from "@/components/ui/button"
import { EmptyState } from "@/components/ui/empty-state"
import { FileText } from "lucide-react"

export function NoInvoices() {
  return (
    <EmptyState
      icon={<FileText />}
      title="No invoices yet"
      description="Invoices appear here as soon as the first one is sent."
      action={<Button>New invoice</Button>}
    />
  )
}

Expected result: You see a dashed frame with a round icon, the title No invoices yet, a line of text and a New invoice button, all centred.

When to use

Use Empty State for

  • A list, table or search that has nothing to show, for the first time or after a filter
  • A region that failed to load, or that the person may not open, with a way on

Use something else for

  • Skeleton for content that is still loading
  • Alert for an error or a notice next to content that is still there
  • Toast for a short message that something happened and needs no action

Content

The title says what is missing. A description says why and what will appear, and an icon gives the message a place to start, in that order.

No invoices yet

Invoices appear here as soon as the first one is sent.

Action

Use one button. A call to action when the list is empty for the first time, a plain button to undo a filter or try again, and a link to lead to help.

No invoices yet

Invoices appear here as soon as the first one is sent.

Behavior and motion

What the empty state does with content, the page and motion.

Not a region
EmptyState is a plain div with no role, and its title is a paragraph. Put it inside the empty section, and wrap it in a status region when the result changes while someone types.
Frame
Dashed draws a dashed 1 px border with a 16 px radius, outline the same with a solid border, default no frame at all, and background a muted fill with a 24 px radius.
Size
The empty state fills the width of its container, centres its content and keeps 40 px of padding on every side. Give it a container with a width, such as a card or a column.
Action
The action sits 12 px below the text and can be any node. Buttons in it keep their own focus ring and keyboard behaviour.
Motion and reduced motion
The empty state has no motion of its own. If you animate the swap, use the base duration and entrance curve on opacity and transform, with a reduced motion fallback.

Anatomy

The parts of an empty state, numbered in the figure. Only the title is required; the icon, description and action are optional.

No invoices yet

Invoices appear here as soon as the first one is sent.

  • data-slot="empty-state"

    A centred block of icon, title, description and action, with 40 px of padding. Four frames are available: dashed (the default), outline, none, or a muted background fill.

  • Optional

    The icon, drawn in a round 48 px well at 24 px. Pass a Lucide icon.

  • One short line on what is missing, such as No invoices yet. It renders as a paragraph, not a heading, so it does not change the outline of the page.

  • Optional

    The text under the title: why the place is empty, or what will appear here.

  • Optional

    Below the text, usually one Button that fills the empty place or undoes the filter. It takes any node, also a row of two buttons or a link.

Best practices

  • Do

    Say what is missing, why and what to do next, then offer one action: No invoices yet, Invoices appear here as soon as the first one is sent, and New invoice.

  • Do

    For a search without results, name the query and offer a way out: No results for Anders, with a Clear search action.

  • Do

    For a failure, say what failed and offer the retry as the action: Couldn't load invoices with Try again. Show the pending state on the button while it runs.

  • Do

    Use the frameless look inside a card or panel that already has a border, and the dashed default where the empty state stands on the page.

  • Do

    Wrap an empty state that appears after typing in a status region, so a screen reader announces the change.

  • Don’t

    Don't show a bare No results line. Without a reason and a next step, an empty place looks broken and leaves people stuck.

  • Don’t

    Don't use it while data is still loading. A Skeleton shows that something is on its way; an empty state says that nothing is.

  • Don’t

    Don't offer two equal calls to action. One primary button, with at most a plain secondary one or a link to help.

API reference

EmptyState is a single component with no parts. It takes the props below and no others, so a class name is the only way to style it from outside.

A centred block of icon, title, description and action, with 40 px of padding. Four frames are available: dashed (the default), outline, none, or a muted background fill.

PropTypeDefaultDescription
title requiredstring—One short line on what is missing. Required.
descriptionstring—Why the place is empty or what will appear here, in one or two sentences.
iconReactNode—A Lucide icon, drawn in a round 48 px well above the title.
actionReactNode—The node below the text: a Button, a row of buttons or a link.
variant"default" | "outline" | "dashed" | "background""dashed"The frame: (default), , without a frame, or with a muted fill.
classNamestring—

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("empty-state")
Installnpx wunderui-cli add empty-state

The full library index for assistants is at /llms.txt.