An empty state explains why a region has no content to display. Show one after the application knows the reason for the absence. A request that is waiting or has failed needs different feedback, even when the screen currently contains no records.

Choose the message by cause

Choose the components

EmptyState provides a titled section, optional description and icon, and a children area for actions. It does not inspect a collection or distinguish errors from absence. The application chooses when to render it and supplies any Button or Link actions.

Use ProgressIndicator while loading. Use Banner or in-context error text when a request fails, retaining any useful previous content. An illustration is optional; the explanation and next step must stand on their own.

Follow the interaction sequence

1. Determine whether loading succeeded and what collection or criteria were evaluated.
2. Choose the message for that known condition.
3. Offer the most useful available action, such as “Create project” or “Clear filters.”
4. Carry out that action in the application.
5. Replace the empty state when content becomes available, preserving sensible focus.

For “No projects match these filters,” retain the filter summary and query. A generic “Create project” action can distract from the actual problem when existing projects are merely excluded by the current criteria.

States and recovery

Do not briefly show an empty state before the first request finishes. For refresh failures, explain the failure separately from the last known contents. After deleting the final item, move focus to a useful heading or action instead of leaving it on a removed control.

If creation fails, preserve the draft and show the error in the creation flow. If clearing filters still produces no matches, update the explanation to reflect the new criteria rather than keeping stale instructions.

Content and accessibility

Use a specific title and a short explanation that adds information. Avoid blaming the person for no results. Name actions by their result and do not offer actions that are unavailable to the current user.

EmptyState renders a named section with an h2 title. Check that this fits the surrounding heading hierarchy; do not place it deep in a page and assume a configurable heading level. Its icon is decorative, so put essential meaning in text.

The component is not a live region. If absence appears after a search or update, provide an appropriate concise announcement in the surrounding application. Keep the next action keyboard-accessible and review long text at narrow widths.

Related implementation

See EmptyState, Button, and Link. Read Search, Filtering, and Loading for transitions into this state.

Further reading

• Apple: Feedback
• Apple: Loading