Skip to content

Design system

Documentation

DesignComponents / EmptyState

Components / EmptyState

Beta

EmptyState

Explain why a content area has no items and offer a useful next action.

On this page

Examples

No data and no results

Explain whether content has not been created or a search/filter returned no matches.

No projects yet

Create a project to keep its tasks and reports together.

No matching projects

Try a shorter name or remove one of the filters.

Empty collection and no search results

Try the props

Choose the reason for the empty result and an optional next action.

No matching projects

Try a shorter name or remove one of the filters.

EmptyState property playground

When to use

Use kind="empty" when a collection has not been created yet and kind="no-results" when the current search or filters match nothing. The feature owns the underlying query and any action behavior.

Usage

import { EmptyState } from "@phuctech/ui/components/empty-state";
import { Button } from "@phuctech/ui/components/button";

<EmptyState kind="empty" heading="No projects yet" description="Create a project to get started." action={<Button type="button">Create project</Button>} />

API

Component API
PropTypeDefaultDescriptionConstraints
kind"empty" | "no-results""empty"Selects the default icon and records the reason in data-kind.Use no-results for a query with no matches, not an empty source collection.
headingstringrequiredVisible, programmatic name for the region.Keep it specific to the content area.
descriptionReactNode—Optional supporting explanation.Use concise text that explains the next step.
iconReactNode | nullkind-specific iconOverrides the decorative icon; null hides it.The heading and description carry the meaning.
actionReactNode—Optional action group below the explanation.Use public controls and keep action logic in the feature.
children / section propsReactNode / HTMLSectionElement props—Additional content and native section attributes.Do not add unrelated status messages inside the empty view.

Tokens

Component tokens
TokenRoleEffective valueUsage
card / mutedSurface and icon backgroundSemantic surfacesKeeps the empty view legible in both themes.
borderBoundaryDashed neutral borderMarks an available content region without using an error color.

Accessibility

The section is a named region linked to its heading. The default icon is decorative. Actions remain regular controls with their own accessible names and keyboard behavior.

Do and don’t

Do

Explain whether content is absent or the current query has no matches.

Don’t

Use an empty state to represent loading or a failed request.

  • Skeleton represents content while it loads.
  • Result presents the outcome of a completed flow.
  • Alert explains an important current status.