Empty State
Empty states appear when a list, table, or section has no content to display. They guide users toward the next action and prevent the UI from feeling broken.
Overview
Every empty state has three required elements: an icon, a title, and a description. An optional CTA button is included when there's a clear action the user can take. The icon is placed in a rounded square container (64px, 16px radius, bg:#F1F5F9).
Be specific: Empty state messages should be context-aware. "No records found" is better than "No data". Include a hint about what the user can do next.
Variants
Token Reference
| Part | Class | Value |
|---|---|---|
| Container | .empty-state | text-align:center, padding:48px 24px |
| Icon wrap | .empty-icon-wrap | 64×64px, radius:16px, bg:#F1F5F9 (error: bg:#FDE2E2) |
| Icon | — | 28×28px SVG, color:#94A3B8 (error: #F05252), stroke-width:1.5 |
| Title | .empty-title | 16px, fw-800, #0F172A, letter-spacing:-.3px |
| Description | .empty-desc | 13px, #64748B, max-width:300px, line-height:1.6, margin:0 auto 24px |
| Actions | .empty-actions | flex, justify-content:center, gap:10px |
AI Implementation Notes
For AI coding assistants: Every list page and table must have an empty state. The empty state renders when the data array is empty. Icon uses
stroke-width:1.5 (thinner than regular UI icons at stroke-width:2) to feel lighter. No emoji in empty states — SVG icons only. Error empty states change icon wrap background to #FDE2E2 and icon stroke to #F05252.
When to Use
Use Empty State when
- A list or table has no data to display
- A filter or search returned zero results
- A section failed to load (error empty state)
- A feature area has not yet been set up
Don't omit Empty State when
- Never show a blank/empty area without an empty state
- Never leave a table with only headers and no rows
- Never use "No data" alone without guidance on next steps
Properties
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
| icon | ReactNode | required | — | SVG icon, 24-28px, stroke-width:1.5. Wrap in .empty-icon-wrap (56-64px, radius:14-16px). Error states use bg:#FDE2E2. |
| title | string | required | — | Short heading. 14-16px fw-800. Be specific: "No users yet" not "No data". |
| description | string | optional | undefined | 1-2 sentence guidance. max-width:240-300px centered. Guides next action. |
| action | ReactNode | optional | undefined | CTA button. "No data" states get primary CTA. "No results" gets outline "Clear Filters". Error gets outline "Retry". |
Design Decisions
Why stroke-width:1.5 for empty state icons instead of the standard 2?
Empty states represent absence — the lighter stroke weight (1.5 vs 2) gives the icon a more delicate, less assertive feel that matches the "nothing here yet" context. Standard UI icons at stroke-width:2 feel active and purposeful, which would be tonally wrong for an empty context.
Changelog
v1.0.0July 2026Added
- 3 types: no-data, no-results, error
- Error variant with red icon bg (#FDE2E2)
- Centered layout with icon, title, description, action slot
States
No items yet
No data
Neutral icon bg, primary CTA
Failed to load
Error
Red icon bg (#FDE2E2)
Accessibility
| Requirement | Implementation |
|---|---|
| aria-live | Empty state container should have aria-live="polite" so screen readers announce it when data is removed. |
| Role | No specific ARIA role needed — empty state is purely informational content. |
Composition
Allowed
Inside table area when data.length === 0
Inside card body when content is absent
Full-page for 404/403 error screens
Forbidden
Multiple empty states on same page
Empty state without a clear CTA when one exists
Best Practices
Do
Differentiate between "no data yet" and "no results found" with different messages and CTAs.
Different contexts require different guidance — first-time users need to add data, filter users need to adjust filters.
Don't
Show "No data" without any guidance on what to do next.
Empty states without CTAs leave users stuck with no path forward.
Related Components
Anatomy
1
Icon Wrapper
div.empty-icon-wrap. width:56-64px, height:56-64px, border-radius:14-16px, bg:#F1F5F9 (error: #FDE2E2). Centered with margin:0 auto.
2
Icon
Inline SVG, 24-28px, color:#94A3B8 (error: #F05252). stroke-width:1.5 — thinner than UI icons to convey absence.
3
Title
div.empty-title. 14-16px fw-800. Be specific: "No users yet" not "No data".
4
Description
div.empty-desc. 12-13px #64748B. max-width:240-300px, centered. 1-2 sentences guiding next action.
5
Actions
div.empty-actions. flex, justify-content:center, gap:10px. Primary CTA for "no data", outline "Clear Filters" for no results, outline "Retry" for errors.
Content Rules
No data yet
No users yet · Start by adding your first user.
Names the entity, tells user what to do next.
Generic
No data available.
Vague, provides no context or guidance.
Behavior
Empty states are conditional renders — they appear when data.length === 0 and disappear when data exists. No animation on show/hide. The CTA button in the empty state triggers the same action as the primary "Add" button in the page header. For "no results" type, the "Clear Filters" button resets all filter controls to their default values and re-runs the query.