DataFree

Empty States

Design what users see when there's nothing to show, so every empty screen explains why and offers the next useful step.

6 states5 edge casesDesktop + Mobile

01The problem

Every list starts empty, and lists become empty again through filtering, completing work or missing permissions. These moments look identical — a blank area — but mean completely different things. A single generic “No data” illustration fails all of them: new users don't know how to start, searchers don't know what to change, and people who finished their work aren't told they're done.

02When to use

Use when

Any list, table, inbox or dashboard that can have zero items
First-use screens before a user has created anything
Search and filter results

Avoid when

Content is still loading — show a skeleton, not an empty state. An empty state that flashes before data arrives is a bug.

03Recommended UX

Statecraft recommendation

Distinguish the four kinds of empty — first use, no results, all done, and no access — and give each its own message and action. First-use states teach and offer the primary create action; no-results states name the query and suggest a change; all-done states confirm completion.

The reason something is empty determines the useful next step. Treating them the same guarantees the wrong advice in most cases.

First use is the highest-leverage screen in onboarding: one clear action beats an illustration and three paragraphs.

“You're all caught up” is a reward. “No items” on a cleared inbox feels like an error.

04Interaction flow

01
List has zero items
Determine why before rendering.
02
Classify
First use, no results, all done, or no access.
03
Render state
Specific message and one primary action.
04
User acts
Create, import, change filters, or request access.
Result
- First item created
- Results found
- Done

05Desktop behaviour

On desktop, the empty state sits where the content would be, inside the same layout, so the toolbar and filters remain visible and usable.

Desktop rules

Keep the page structure (header, toolbar, column headers) — replace only the content area.
One primary action; at most one secondary (e.g. Import, or view a sample).
No-results states repeat the query and list the active filters with a way to clear them.
Use illustrations sparingly; text and the action do the work.

Different reasons, different messages: first use teaches and offers create; no results names the filters to change.

06Mobile behaviour

On mobile, the empty state is often the whole screen. Keep it short and place the action within thumb reach.

Mobile rules

Short title, one sentence, one button.
Primary action as a full-width button or the existing floating create button.
Avoid tall illustrations that push the action below the fold.

All done is a reward, not an error: confirm completion and point to what's next.

07States

First use
Explains the object and offers Create and Import.
No results
Names the query and filters; suggests the change most likely to help.
All done
Confirms completion; links to history or the next task.
No access
Explains that items exist but aren't visible; request access.
Loading
Skeleton — never the empty state — while data loads.
Error
Couldn't load — distinct from empty, with Retry.

08Edge cases

EC-01
Empty state flashes while loading
The list renders “No invoices yet” for 300 ms before data arrives.
Recommendation
Render a skeleton until the first response, and show the empty state only when the server confirms zero items.
EC-02
Error shown as empty
The API fails and the list says “No customers”.
Recommendation
Treat failures as errors with Retry. An empty state on failure tells users their data is gone.
EC-03
Empty because of permissions
A new member sees no projects because they haven't been added to any.
Recommendation
Say so: “You haven't been added to any projects yet. Ask Priya, or create your own.”
EC-04
Filters hidden off-screen
No results, but the active filter is in a collapsed panel.
Recommendation
List every active filter in the empty state with Clear filters, so the cause is visible.
EC-05
Sample data
The product offers to add demo data on first use.
Recommendation
Label sample data clearly and make it removable in one action, so it never mixes with real records.

09Microcopy

First use
Avoid
“No data”
Prefer
“Create your first invoice — or import them from a CSV.”
No results
Avoid
“Nothing found”
Prefer
“No invoices match “acme” with Status: Paid. Clear filters”
All done
Avoid
“No items”
Prefer
“You’re all caught up. 14 approvals handled this week.”
No access
Prefer
“You haven’t been added to any projects yet. Ask Priya for access, or create your own.”

10Accessibility

Empty states use a heading and text, not text baked into an illustration.
Illustrations are decorative (empty alt) unless they convey information.
When filtering produces no results, announce it via the result-count live region.

11Developer notes

01
Return enough context from the API to classify emptiness: total count without filters, whether the user can create, whether hidden items exist.
02
Keep loading, error and empty as separate states in data-fetching code; never derive “empty” from “no data yet”.
03
Make the empty-state component accept a kind and an action so it's consistent across the product.

12Implementation prompt

For Claude Code, Codex or Cursor

Implement empty states across list views.

Requirements:
- A reusable EmptyState component with kinds: first_use, no_results, all_done, no_access.
- Data-fetching hooks expose loading, error and empty separately; skeletons while loading; error with Retry.
- API returns context: unfiltered total, canCreate, hasHiddenItems.
- first_use: explanation + primary Create + optional Import.
- no_results: repeats query and lists active filters with Clear filters.
- all_done: completion message with a link to history.
- no_access: explains and offers Request access, naming who can grant it.
- Keep page structure (header, toolbar) intact; replace only the content area.
- Mobile: short copy, one full-width action.

Do not redesign the existing interface.