Build · New

Empty State

Fills a region that has no content yet, says why, and points to the next step.

Preview

Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.

Installation

SoonInstalling from the registry opens at launch. Until then the command below is what it will be.

npx shadcn@latest add @ritla/empty

Usage

import { Empty } from "@/components/ui/empty";

<Empty
  illustration="empty-wallet"
  title="No transactions yet"
  description="When you send or receive money, it will show up here."
  primary={{ label: "Add money", href: "/add-money" }}
/>

Examples

No results

No results isn't first use: it repeats the search, offers Clear search, and is announced (announce="status") while focus stays in the field. Change the search to see the list.

Couldn't load

Say what went wrong in plain words and offer Try again.

Compact, in a card

size="compact" for small regions: no illustration, a smaller title, the action.

Stacked actions

stacking="vertical" for long labels, primary on top.

Illustrations

Twenty-four Figma illustrations in token colors, so they follow dark mode. Pick the one that matches the content; never recolor, crop or mirror one.

API reference

Empty

Prop	Type	Default	Description
`illustration`	`EmptyIllustrationName \| ReactNode`		The illustration slot: an illustration's name or any node.
`title`	`ReactNode`		Figma's Title: what's missing; a heading.
`description`	`ReactNode`		Figma's Description: what will appear here, or how to fill it.
`headingLevel`	`2 \| 3 \| 4 \| 5 \| 6`	`3`	The title's heading level.
`primary / secondary`	`{ label; href?; render?; onClick? }`		The primary (Filled) and secondary (Tonal) actions.
`stacking`	`"horizontal" \| "vertical"`	`"horizontal"`	Figma's Stacking.
`size`	`"default" \| "compact"`	`"default"`	`compact` for cards and small regions.
`announce`	`"status"`		For no-results messages after a search or filter.

EmptyIllustration

Prop	Type	Default	Description
`name`	`EmptyIllustrationName`		One of the 24 illustrations; always decorative.

Accessibility

Keyboard

Keys are written for left-to-right. In right-to-left the arrow keys swap: the one pointing toward the reading direction moves forward.

Key	Action
`Tab`	To the primary action, then the secondary.

ARIA

The title is a real heading (h3 by default) so screen readers can find it.
Illustrations are decorative and hidden from screen readers; the explanation is never only in the picture.
No-results messages are announced with status; focus stays where it was and never jumps to them.

Arabic and RTL notes

Mirrors

The text stays centered and the primary action comes first: on the right.

Does not mirror

Illustrations don't mirror.

Numerals: Numbers in the description follow the numerals setting; format them with formatNumber.
Arabic typography: Title body-20 Medium (body-16 when compact), description body-14.
Mixed-direction text: What the person searched for goes in <bdi>, since it can be in either language.

All components ›