What is Empty state?

An empty state replaces a blank area when a list, table, inbox or dashboard has nothing to show. A good one tells users why the area is empty and what to do next, usually with a single button. Empty states are often the first thing a new user sees in a product, so they carry more weight than their size suggests: they are onboarding, error handling and navigation in one small block.

Types of empty state

• First use. Nothing has been created yet. Explain the value of the feature and offer the create action, or a sample to start from.
• No results. A search or filter matched nothing. Echo the query, suggest a broader search and offer a button to clear filters.
• Cleared. The user finished everything, like inbox zero. Confirm it and step aside.
• Blocked. The user lacks permission or the data failed to load. These are not really empty; use a distinct error or permission state with its own message.

Anatomy

Keep it to four parts: a small icon or illustration, a short headline, one sentence of explanation, and a primary action. A secondary link to docs is optional. The headline states the situation in plain words ("No invoices yet"), and the sentence says what will appear here and how to get it there. Match the empty state to the size of its container; a full-page illustration inside a 200px card looks broken.

import { EmptyState } from "@/components/ui/empty-state"

export function NoProjects({ onCreate }: { onCreate: () => void }) {
  return (
    <EmptyState
      title="No projects yet"
      description="Projects group your deployments, domains and environment variables."
      actionLabel="Create project"
      onAction={onCreate}
    />
  )
}

Accessibility

• Render the headline as a real heading at the correct level so screen reader users can find it.
• Mark decorative illustrations with alt="" or aria-hidden.
• When results update in place, for example while filtering, announce "No results" through a role="status" live region so the change is not silent.
• Move focus deliberately after actions that empty a list, such as deleting the last item, so keyboard users are not left on a removed element.

Common mistakes

• A bare "No data" with no explanation or action.
• The same message for "nothing created" and "nothing matched your filter".
• Showing an empty state while data is still loading. Show a skeleton screen until the request settles.

MiniDev includes EmptyState, EmptySearch and EmptyTable in the feedback category.