UX Patterns Guide

Decision guide · Feedback, Status, And System State

Empty-state UX: first use, no results, and failed loading

By UX Patterns GuideWorked decision updated Editorial method

Choose the message from the known cause. An empty collection, zero matching results, missing access, and a failed request need different explanations and next actions, even when the visible area has the same blank shape.

Try the live example →Compare alternatives →

Worked decision · constructed example

Is the area genuinely empty, or is the product unable to show its contents?

A project workspace shows no project cards. An administrator can create a project, a reviewer can only view assigned projects, and a filter can hide projects that already exist. The same Create your first project message would mislead at least two of these situations.

Try Empty state →Try No-results recovery →Try Error state →
Resolve the cause before writing the empty-state action
Known causeUseful messageAppropriate next action
Successful load; no projects existExplain what a project enables and that the collection is empty.Offer Create project to someone with creation permission.
Projects exist; none match the filtersExplain that the current criteria have no matches.Show or remove the relevant criteria while preserving independent search context.
The role cannot view projectsExplain the access boundary without disclosing restricted records.Offer an authorized access-request route where one exists.
The request failedState that projects could not be loaded.Offer retry or another supported recovery route rather than creation as a remedy.

Why this choice

The next action should address the cause the system actually knows. A decorative illustration cannot distinguish no data from a service failure, and a creation button is not useful to a read-only reviewer.

Where the decision changes

Terminology differs between design systems: some group error and permission presentations under empty states. The operational distinction matters more than the label. Keep loading, known absence, and inability to retrieve data separate in the state model.

Try these checks

  1. Test first use separately from a filter that returns zero matches.
  2. Repeat with a read-only role and a failed request.
  3. Check that the primary action is possible for the current person.
  4. After recovery, verify that the state changes to the actual loaded result.

What the sources support

  • Carbon distinguishes causes including no data, user-action results, and error management, and emphasizes contextual next steps. Carbon: Empty states ↗

These source claims were checked on . The scenario and decision analysis are illustrative; the checks are a test plan, not reported results from a user study.

Decision first

Choose this pattern when the problem matches

Use when

  • A next setup, creation, import, sample, or access-request action is available or explainable.

Avoid when

  • The absence was caused by filters or search.
  • The system failed to load expected data.
  • The content is still loading or being computed.

Problem it prevents

A next setup, creation, import, sample, or access-request action is available or explainable.

Test the behavior

Try strong and weak versions of the interaction

Open the working example, try its controls, and compare the behavior against the decision guidance.

In the lab you can
  • switch between strong UI, weak UI, strong UX, and weak UX;
  • trigger required, empty, loading, error, and recovery states;
  • inspect keyboard and accessibility expectations beside the demo.
Launch Empty state in the lab
Pattern anatomy

What a strong implementation has to make clear

User need

A next setup, creation, import, sample, or access-request action is available or explainable.

Pattern promise

Explain the legitimate absence in context, name the missing object or prerequisite, and provide one useful next step such as create, import, configure, request access, or view an example.

Required state

First-use empty state before any objects exist.

Failure to inspect

Incorrectly implying user fault.

Access contract

Keep the message in normal reading order near the empty region it explains.

Quality bar

The difference between expert and weak execution

Strong implementation

Specific, visible, recoverable

  • Permission variant explains that projects exist only after an admin grants access and offers Request access instead of Create.
  • Users can create the first project, import existing work, or request access depending on the actual cause.
  • After creating content, the empty state is replaced by the first row and focus moves to the new item.
Weak implementation

Vague, hidden, hard to recover from

  • Oversized decorative art and vague welcome copy that hides the task.
  • A primary Create button is shown to a read-only user and fails after activation.
  • Incorrectly implying user fault.
  • Showing empty state while content is still loading.
UI guidance
  • Render a resolved no-data region with a specific heading, cause text, one primary action when available, optional secondary path, and restrained illustration or icon support.
  • Keep surrounding context such as table title, filters, or workspace name visible so users know exactly what is empty.
UX guidance
  • Help users distinguish legitimate absence from loading, no-results, error, permission, and setup conditions before offering a next step.
  • Move users toward the first useful object or prerequisite, and replace unavailable actions with permission or configuration guidance.
Implementation contract

What the implementation must handle

States

  • First-use empty state before any objects exist.
  • Configured but currently empty state after cleanup or deletion.
  • Permission-limited state where creation is unavailable and request-access or explanation is shown.
  • Prerequisite or setup-empty state where configuration must happen before data appears.

Interaction

  • The empty state identifies what is absent and why the absence is expected.
  • Primary action moves users toward the first meaningful object or prerequisite.
  • Unavailable actions are replaced with explanation or request-access paths instead of disabled mystery controls.
  • The state disappears or changes once content exists.

Accessibility

  • Keep the message in normal reading order near the empty region it explains.
  • Ensure the primary action has a descriptive label such as Create project or Import CSV.
  • If the empty state appears after async loading, announce the resolved status with a polite live region when appropriate.
  • Primary and secondary actions follow normal button or link behavior.

Review

  • Can users tell what object is missing and whether the absence is expected?
  • Is the primary action available to this user right now?
Evidence trail

Source-backed claims behind this guidance

Carbon Design System Empty States Pattern

IBM Carbon Design System - checked

Carbon distinguishes no-data, user-action no-results, and error-management empty states and describes matching the state to cause.

Atlassian Design System Empty State

Atlassian Design System - checked

Atlassian documents empty states with explanation, action, and variants for permission, filtered, and error causes.

SAP Fiori Illustrated Message

SAP Fiori - checked

SAP Fiori documents contextual empty/message states with situation-matched title, description, illustration, and optional actions.

Shopify Polaris Empty State

Shopify Polaris - checked

Polaris documents empty states for missing content or first-use setup with focused explanation, illustration, and primary/secondary actions.

Full agent/debug reference

Problem Context

  • A list, dashboard, workspace, inbox, or collection can legitimately contain no objects.
  • The user may be arriving for the first time, after cleanup, before configuration, or without permission to create content.
  • The system has already resolved that this is not loading, search no-results, or an unexpected load failure.

Selection Rules

  • Choose empty state only after the system knows the area is legitimately empty rather than loading, filtered, or failed.
  • Name the exact object, collection, or prerequisite that is absent.
  • Offer one primary action only when the user can complete it in the current role or context.
  • Use secondary actions for import, sample data, docs, or request access only when they clarify the next path instead of competing.
  • Tailor copy to first-use, configured-empty, deleted-all, permission, or setup states instead of using one welcome message everywhere.
  • Keep optional illustrations small and explanatory; they must not replace cause, consequence, or action text.

Required States

  • First-use empty state before any objects exist.
  • Configured but currently empty state after cleanup or deletion.
  • Permission-limited state where creation is unavailable and request-access or explanation is shown.
  • Prerequisite or setup-empty state where configuration must happen before data appears.
  • Post-action state after creating or importing the first object.
  • Loading-resolved transition so the empty state appears only after data status is known.

Interaction Contract

  • The empty state identifies what is absent and why the absence is expected.
  • Primary action moves users toward the first meaningful object or prerequisite.
  • Unavailable actions are replaced with explanation or request-access paths instead of disabled mystery controls.
  • The state disappears or changes once content exists.
  • If the absence came from search or filters, the UI switches to no-results recovery rather than first-use empty copy.
  • If content should exist but failed to load, the UI switches to an error state with retry or fallback.

Implementation Checklist

  • Gate empty-state rendering behind a resolved data status.
  • Name the missing object type in the heading.
  • Explain the most likely legitimate cause in one short sentence.
  • Provide one primary next action when the user has permission.
  • Use secondary actions only for clearly distinct paths such as import, sample data, docs, or request access.
  • Track first-use, permission, setup, and cleanup variants separately.
  • Do not hide table headers, filters, or context users need to understand what is empty.

Common Generated-UI Mistakes

  • Showing a blank page with no explanation.
  • Using marketing copy instead of a task-specific next step.
  • Telling users to create something they do not have permission to create.
  • Showing empty state while content is still loading.
  • Using first-use onboarding when filters produced zero matches.
  • Replacing an error or offline condition with cheerful empty copy.

Critique Questions

  • Can users tell what object is missing and whether the absence is expected?
  • Is the primary action available to this user right now?
  • Would the same surface become no-results, error, loading, or permission messaging under a different cause?
Accessibility
  • Keep the message in normal reading order near the empty region it explains.
  • Ensure the primary action has a descriptive label such as Create project or Import CSV.
  • Do not rely on illustration alone to communicate the cause.
  • If the empty state appears after async loading, announce the resolved status with a polite live region when appropriate.
Keyboard Behavior
  • Primary and secondary actions follow normal button or link behavior.
  • Focus should reach the empty state action naturally after the region heading.
  • When creation or import completes, focus should move to the new content or a confirmation that content now exists.
  • Disabled or unavailable actions should be replaced with reachable explanatory text or request-access controls.
Variants
  • First-run empty state
  • Configured but empty state
  • Permission empty state
  • Setup required empty state
  • Deleted-all empty state
  • Sample-data empty state

Verification

Source trail checked:

Saved items