Empty States
Prov1.0.0Five ready empty screens: no results, offline, caught up, not found and first run.
Build for your project
Code/install build
Usage
Import it and pass your content. The props that matter most are listed next.
Example
"use client";
import * as React from "react";
import { OfflineState } from "@/components/ui/notchset/blocks/empty-states";
export function Offline() {
const [status, setStatus] = React.useState<"offline" | "connecting" | "online">("offline");
return (
<OfflineState
status={status}
retryIn={12}
onRetry={() => {
setStatus("connecting");
fetch("/api/ping").then(
(res) => setStatus(res.ok ? "online" : "offline"),
() => setStatus("offline"),
);
}}
body="3 changes are saved on this device and will sync when you reconnect."
/>
);
}Props
EmptyState–{ diagram?, title, children?, actions? }The frame, for a state of your own.
NoResultsState–{ query?, filters, onRemoveFilter, onClearFilters, total, count, matches, title?, body? }Filter chips come off one by one; the bars fill and SHOW n RUNS lists the matches.
OfflineState–{ status, onRetry, retryIn?, service?, title?, body? }status is offline, connecting or online; the countdown rolls.
CaughtUpState–{ earlier, paused?, onPausedChange?, title?, body? }Twelve dots pop in; VIEW EARLIER expands recent history.
NotFoundState–{ label, suggestions, onPick, note?, title, body? }The closest matches as buttons.
FirstRunState–{ steps, done, onStep, title, body? }Steps enable in turn; the rail fills as they are done.
Anatomy
- Five ready states over one frame.
- Each state's data and outcome come from you.
- Use EmptyState for a state of your own in the same language.
EmptyStatedata-slot="empty-state"The frame: diagram, title, line, actions.
NoResultsStatedata-slot="—"Filters to remove and the matches.
OfflineStatedata-slot="—"Retry and the countdown.
CaughtUpStatedata-slot="—"Earlier history and a pause.
NotFoundStatedata-slot="—"The closest matches.
FirstRunStatedata-slot="—"Steps that enable in turn.
Source
components/ui/notchset/blocks/empty-states.tsx
This component is included with Pro.
Try the live preview above. Get Pro to install the source.
Build for your project
Code/install build
Installation
pnpm dlx shadcn@latest add @beautiful-ui-pro/empty-statesNeeds your registry key. Your components.json style picks the Base UI or Radix build: radix-*, new-york and default get Radix, base-* gets Base UI.
Styles didn't apply?
The CLI adds the styles to the CSS file named in components.json (tailwind.css). Check that it points at your global stylesheet, that the project uses Tailwind CSS v4, and that the file is imported in your root layout. Installed by hand: paste styles.css into that file.
For coding agents
Give your coding assistant the Markdown guide instead of screenshots.
Use it for
- Any list, search or page that can be empty, offline or not found
- The first visit before there is any data
Use something else when
- Loading: use Skeleton
- An error that needs a stack trace: show the error
Mistakes to avoid
- Say which filter is the problem in body: the state is only useful when it names the fix
- Keep the countdown honest: retry when it reaches zero
Agents find it by
- empty state, no results, offline state, not found, 404, first run, onboarding empty, zero state, Notchset
Where agents read it
- Guide for this component: https://beautiful-ui.dev/md/empty-states.md
- Every component, for tools without MCP: /llms.txt
- MCP server:
https://beautiful-ui.dev/api/mcp(setup)
Behaviour
Keyboard
- Tab / Enter
- Every action is a button
Accessibility
- Diagrams are decorative (aria-hidden); the title and line say everything
- Removing a filter, retrying and stepping are buttons with full names; lists that expand say so (aria-expanded)
- Countdowns and confirmations are announced (aria-live)
Motion
- No results
- A signal line scans the empty ledger (1800ms); bars grow as filters come off (520ms, 60ms apart)
- Offline
- The broken link blinks; the countdown rolls
- Caught up
- Twelve dots pop in, 40ms apart
- Not found
- A ring pings from the signal dot (1600ms)
- First run
- The rail fills to the next node (520ms)
Responsive
- Diagrams are 240px wide; lists cap at 380–420px and the actions wrap.
Performance
- Small inline SVGs; the only loops are the scan, blink and ping, which stop with motion off.
Changelog
v1.0.0 · 2026-10-03
First release
Part of
Included with Pro
Pro is in early access.
