# Empty states

A React block (a whole screen) in [Beamline](https://beamline.io/)'s [Blocks](https://beamline.io/components/blocks) category. Live demo: https://beamline.io/components/empty-states

The five empty moments every product has, written and wired: first use with a first step, no results with the filters to clear, an error with retry and a copyable error id, no permission with a request for access, and offline with reconnecting.

## Use it for

- A list, table, panel or page that has nothing to show, when the reason matters: never used, filtered to nothing, failed, forbidden or offline.

## Not for

- A plain empty list with one line and one action ([empty-state](https://beamline.io/components/empty-state)).
- Loading ([skeleton](https://beamline.io/components/skeleton)).
- A problem that sits above content that still shows ([alert](https://beamline.io/components/alert)).

## Anatomy

- icon tile
- title
- description
- context (active filters as removable chips, error id with copy, who to ask)
- primary action
- secondary action
- status line (retrying, request sent, back online)

## Variants

- **kind**: first-use, no-results, error, no-permission, offline
- **size**: md, sm

## States

- first use
- no results for a search, for filters, or both
- error: retrying, retry failed again
- no permission: requesting, request sent, request failed
- offline: waiting, back online and retrying

## Keyboard

- Tab reaches each filter chip's remove button, then the actions
- every action is a button; results are announced in a polite status line

## Motion

None of its own: buttons keep their size while busy (button), and the status line swaps text.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` (required) | `"first-use" \| "no-results" \| "error" \| "no-permission" \| "offline"` | — |  |
| `title / description / icon` | `ReactNode` | — | Replace the written defaults for the kind. |
| `size` | `"md" \| "sm"` | `"md"` | sm for panels and table bodies. |
| `first-use: noun, onCreate, createLabel, secondary` | `string / () => void / string / ReactNode` | — |  |
| `no-results: query, filters, onRemoveFilter, onClearFilters, onClearQuery` | `string / { id, label }[] / (id) => void / () => void / () => void` | — |  |
| `error: errorId, onRetry, supportHref` | `string / () => void \| Promise<unknown> / string` | — | A rejected retry says so and keeps the button. |
| `no-permission: resource, owner, onRequestAccess, requested` | `string / string / () => Promise<unknown> / boolean` | — |  |
| `offline: online, onRetry` | `boolean / () => void \| Promise<unknown>` | — | Without online, the browser's connection events are followed and onRetry runs when it comes back. |
| `className` | `string` | — |  |
| `classNames` | `EmptyStatesClassNames` | — |  |
| `style / ref` | `CSSProperties / Ref<HTMLDivElement>` | — |  |
| `emptyStateClassNames` | `EmptyStateClassNames` | — | Shared empty-state icon, title, description and actions. |

## Built from

- [empty-state](https://beamline.io/components/empty-state)
- button
- [copy-button](https://beamline.io/components/copy-button)
- badge

## Dependencies

`lucide-react`

## Import

```tsx
import { EmptyStates } from "@/blocks/empty-states/empty-states";
```

## Get it

Empty states is part of Beamline: 190 React components and screens your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 one payment (regular $200), no subscription, a year of updates, one licence for your whole team. [Get Beamline](https://beamline.io/checkout?pack=complete) · [Connect your agent](https://beamline.io/connect)

## More in Blocks

- [AI agent workspace](https://beamline.io/components/agent-workspace): Threads, a conversation with streamed reasoning, cited answers and a plan that waits for approval then runs step by step, and an artifacts panel with…
- [Analytics dashboard](https://beamline.io/components/analytics-dashboard): A SaaS overview in the app shell, fed by your metrics hook: range and segment filters drive KPIs, new and expansion revenue, channels, plan mix, uptime…
- [Auth page](https://beamline.io/components/auth): The whole sign-in / sign-up route: product mark, a quiet dotted field with a light that follows the mouse, an optional notice, the SignIn and SignupForm…
- [Changelog feed](https://beamline.io/components/changelog-feed): An in-app What's new page: release notes grouped by month with tags, versions, pictures and details, a tag filter with counts, entries since your last…
- [CRM pipeline](https://beamline.io/components/crm): A pipeline screen: KPIs and stage mix derived from a virtualised deals grid with inline edit, bulk moves and delete with undo; a row opens the deal in a…
- [Page header](https://beamline.io/components/page-header): The top of a record or project page: breadcrumb, title with status, description and meta, a primary action with secondary actions that fold into a More…
- [Plan comparison](https://beamline.io/components/plan-comparison): Plans side by side against every feature: prices that roll between monthly and yearly, the current and recommended plan marked, a header that stays in…
- [Settings](https://beamline.io/components/settings): Profile and workspace settings with one draft and real save handler. Personal mode omits workspace data; optional profile fields share validation…
- [Sign in](https://beamline.io/components/sign-in): The sign-in card: email and password, a one-time code or a magic link, passkeys and single sign-on, with validation, progress, errors and a signed-in…
- [Sign up form](https://beamline.io/components/signup-form): The account creation card: single sign-on, name, work email and a password with strength and Caps Lock hints, terms consent, inline validation, your…
- [Step form](https://beamline.io/components/step-form): The finished frame for any multi-step form you compose — onboarding, intake brief, questionnaire, booking, application: a wide card with progress, the…
- [Trading terminal](https://beamline.io/components/trading-terminal): A perpetuals terminal on your feed and your account: ticker tape, market header with funding, candles, book / trades / depth, order ticket, account…
- [Voice agent](https://beamline.io/components/voice-agent): A voice agent in three layouts on one session: a support panel that mixes typing and talking, a call screen with the agent's orb and one call button, and…