EmptyState
The one component for 'nothing is shown here yet': first-time, empty, no-results and success result screens. Icon, specific title, one-sentence description and the action that fixes the emptiness.
// Plain markup
import { EmptyState } from "@shavin/ui";First-time
The user has never created one: say what it is and give the first action.
No orders yet
Orders appear here as customers check out. Share your shop link to get the first one.
<EmptyState
kind="first-time"
title="No orders yet"
description="Orders appear here as customers check out. Share your shop link to get the first one."
action={<Button iconLeft={<Icon name="link" size="sm" />}>Copy shop link</Button>}
/>Empty
There were items and now there are none: say what is missing and how it comes back.
Your inbox is clear
New messages from customers land here.
<EmptyState
kind="empty"
title="Your inbox is clear"
description="New messages from customers land here."
action={<Button variant="outline">Compose message</Button>}
/>No results
A filter or search matched nothing: echo the filter and offer to clear it. Announced to screen readers when it appears.
No orders match these filters
Status: Refunded. Try another status or clear the filters.
<EmptyState
kind="no-results"
title="No orders match these filters"
description="Status: Refunded. Try another status or clear the filters."
action={<Button variant="outline">Clear filters</Button>}
/>Success result screen
A flow finished. Use focusOnMount so the heading is read when the screen appears.
Your workspace is ready
We set up three sample projects so you can look around.
<EmptyState
kind="success"
size="lg"
focusOnMount
title="Your workspace is ready"
description="We set up three sample projects so you can look around."
action={<Button>Open workspace</Button>}
secondaryAction={<Button variant="ghost">Invite your team</Button>}
/>Bordered and inline
bordered keeps a region visible (a drop zone, a table body); inline fits list footers.
No files in this folder
Drop files here or upload them from your computer.
No comments yet
Start the discussion.
<EmptyState
variant="bordered"
size="sm"
title="No files in this folder"
description="Drop files here or upload them from your computer."
action={<Button variant="outline" size="sm">Upload files</Button>}
/>
<EmptyState
layout="inline"
size="sm"
title="No comments yet"
description="Start the discussion."
action={<Button size="sm" variant="ghost">Add comment</Button>}
/>Props
| Prop | Type | Default | Description |
|---|---|---|---|
| kind | EmptyStateKind | icon | The situation: sets the default icon only (copy always comes from you). first-time = never created one; empty = had items, none now; no-results = a filter or search matched nothing; success = a flow finished (a result screen). |
| title* | string | — | Specific title: "No invoices yet", never "No data" or "Nothing here". |
| description | ReactNode | — | One sentence, at most 25 words: what is missing and how to add it. |
| icon | ReactNode | per | Icon override (use `<Icon name>`). Default per kind: inbox, folder-open, search-x, circle-check. |
| illustration | ReactNode | — | Monochrome illustration; replaces the icon. Rendered aria-hidden. |
| action | ReactNode | — | The one primary action that fixes the emptiness (a Button). |
| secondaryAction | ReactNode | — | A second, quieter action (a ghost Button or Link). |
| titleAs | "h2" | "h3" | "h4" | "h5" | "h6" | "p" | h3 | Heading element, independent of size. Default h3. |
| announce | boolean | true | Announce the title (polite) once on mount, for an empty state that replaces content after the user acts. Default true for no-results, false otherwise. |
| focusOnMount | boolean | — | Move focus to the title on mount. Recommended for kind="success" result screens. |
| layout | "centered" | "inline" | "centered" | — |
| size | "sm" | "md" | "lg" | "md" | — |
| variant | "plain" | "bordered" | "plain" | — |
* required