Empty states

A React block (a whole screen) in Beamline's Blocks category.

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).
Loading (skeleton).
A problem that sits above content that still shows (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

Dependencies

lucide-react

Import

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 · Connect your agent