EmptyState

Stable

A message for an area with nothing in it: a drawing, a title that says why, one line, and one button.

Also known as blank slate, zero state, no results, no data

Install with npm install @tattva/ui (setup), or copy the code from the kit in Downloads.

Start by adding a document

Documents give the assistant something to read.

<EmptyState
  variant="first-use"
  title="Start by adding a document"
  action={<Button>Add a document</Button>}
  secondary={<Button variant="ghost">Learn how documents work</Button>}
>
  Documents give the assistant something to read.
</EmptyState>

A truly empty area invites the first step. The title is positive and the button does what it says.

Usage Code Design Accessibility

When to use it

Fills an area that has nothing to show with a reason and one next step. Saying the cause first stops people wondering whether something broke.

Made of: Drawing · "Action needed" tag (permission and usage limit) · Title · Text · Main button · Second link

Use it for

A first visit, before anything has been made.
A search or filter with no results.
An area where everything is done, or that cannot load, is private or is offline.

Not for

A short error inside a page or reply: use ErrorState.
A usage limit inside a chat: use RateLimitNotice.
Content that is still loading: use Skeleton.

Do and avoid

No results for these filters

Try a shorter search or clear the filters.

Do. Says why it is empty and gives one next step.

Nothing here.

Avoid. A blank dead end gives no reason and no way forward.

Do

Say why in the title and what to do next on the button.
Treat a filtered list differently from one that is truly empty.
Offer one main button and at most one second link.
Keep words short and plain, and never point to another part of the app as the only way out.

Avoid

Do not leave a dead end. Every screen needs a way forward, or a reason there is none.
Do not use amber unless a person must act.
Do not let the drawing be the only explanation.
Do not use several drawings on one screen.

On a phone

The panel fills the width, with the art, text and buttons stacked in one column.
Text is capped at 44 characters wide and the title breaks anywhere, so long titles do not overflow.
The action and secondary buttons wrap onto separate lines when they do not fit, and each button has a 44px tap area on touch screens.

Seen in products

Carbon's empty states pattern lists up to five elements: an optional image, a title, a body, a primary action and an optional secondary action or link.
Carbon names three types: no data (first use), user action (no search results, completion) and error management (permissions, system problem, required configuration).
Carbon asks for positive titles such as Start by adding, short copy without product jargon, no references to other areas of the app and no dead ends. In small spaces it centers the image above left-aligned text or omits the image. Decorative images get an empty alt.
NN/g says empty states should communicate system status, because a blank area could mean loading, error or filters. They should give learning cues and a direct pathway.
Shopify's app home pattern names the cause in the heading and puts the next step in the action, separates filtered-empty from truly empty, uses one primary and one secondary button, and skips the graphic in dense contexts.
Material's guidance, seen in a snippet, asks for neutral or humorous on-brand images, avoids imagery that expresses urgency or confusion, and treats the image and tagline as non-interactive.

Properties

Prop	Type	Default	Description
variant	"first-use" \| "no-results" \| "cleared" \| "error" \| "permission" \| "offline" \| "rate-limit"	"first-use"	Sets default art, copy, tone and live behavior.
art	ReactNode \| null	none	Replaces the variant's illustration. Pass an Illustration or a Pictogram, or null for none.
title	string	none	Names the cause or invites the first step. Defaults per variant.
children	ReactNode	none	One-line body with the next step. Defaults per variant.
action	ReactNode	none	The one primary action, usually a Button.
secondary	ReactNode	none	Optional secondary link or ghost button.
layout	"center" \| "start"	"center"	Center for full panels. Start left-aligns text in small areas.
compact	boolean	false	Omits the art and tightens spacing.
headingLevel	2 \| 3 \| 4	3	Heading level of the title.
live	boolean	none	Overrides role="status". By default it is on for no-results and offline only.
attentionLabel	string	"Action needed"	Text of the amber chip in the permission and rate-limit variants.
className	string	none	Extra classes for the container.

"Show code under the preview gives the code for the example on the stage."

In Figma

In Figma, one EmptyState switches all of this from its properties panel, across 28 variants. Each property sets the React prop beside it, so design and code use the same names.

EmptyState in Figma: each property and the React prop it sets
Figma property	React	Values
Variant	`variant`	First-use, No-results, Cleared, Error, Permission, Offline, Rate-limit
Layout	`layout`	Center, Start
Compact	`compact`	On or off
Title	`title`	Any text
Text	`children`	Any text

States

States this part has beyond its default look. Build each one your screen can reach. States set by a property are in the Code tab.

first use: The default variant shows an empty-chat drawing, a title and a short body for a first visit.
no results: Set variant to no-results for a search drawing; it is announced to screen readers as a status.
cleared: Set variant to cleared for a success drawing when everything is done.
error: Set variant to error for an error drawing and a message that the work is safe.
permission: Set variant to permission for a lock drawing and an Action needed tag.
offline: Set variant to offline for a plug drawing; it is announced as a status.
rate limit: Set variant to rate-limit for an hourglass drawing and an Action needed tag.
compact: Pass compact to drop the drawing and tighten the padding.

Tokens

Change one of these and every part that uses it follows.

--surface
--border
--fg-muted
--attention-soft
--attention-fg
--radius-control
--radius-card

First use