Question 1

What is a shadcn empty state?

Accepted Answer

A shadcn empty state is the placeholder UI you show when there's nothing to render — empty inboxes, no search results, first-run onboarding, fresh accounts with zero content. It's the most overlooked surface in any app: every list, table, search bar, and dashboard widget needs one. The shadcn Empty primitive composes Icon + Title + Description + Actions into a centered, dismissible-or-not block that fills the space gracefully.

Question 2

Are these empty state examples free?

Accepted Answer

Yes, every empty state example on shadcn.io is free for personal and commercial use — no attribution requirement, no runtime dependency, no gating.

Question 3

Why does the empty state matter?

Accepted Answer

First impressions and recovery moments. New users land on empty dashboards — what they see in the first 3 seconds decides whether they stay. Users who search for nothing find no results — what you show next decides whether they refine or leave. A blank gray rectangle teaches users your app is broken; a thoughtful empty state with a CTA teaches them what to do next. Treat empty states as growth surfaces, not afterthoughts.

Question 4

When should I render an empty state versus a skeleton or a spinner?

Accepted Answer

Skeleton / Spinner: data is LOADING — temporarily empty, will fill in. Empty state: data has loaded and there's NOTHING — permanently empty (or empty until the user takes action). The wrong pattern erodes trust: showing skeletons forever feels broken; showing "No results" while still fetching feels confusing. Track loading and empty as distinct states in your UI.

Question 5

Which empty state variant fits a search-with-no-results page?

Accepted Answer

Use the search variant. Lead with a Search icon, the title "No matches for {query}", a one-line suggestion to refine ("Try different keywords or remove filters"), and an action button to clear filters. Echo the user's search query back to them so they know the system received it. Don't show the empty state DURING the typing — wait for the request to settle, otherwise users see thrash.

Question 6

How do I build an onboarding empty state for new accounts?

Accepted Answer

Use the actions variant. Lead with an illustration or large icon, title that frames the value ("Welcome to Inbox — add your first conversation"), 1-2 sentences describing what comes next, and a primary action button ("Connect email") plus a secondary link ("Watch the demo"). For multi-step onboarding, render this as the default empty state and let users dismiss it when they've added content.

Question 7

How do I show empty states inside dashboard widgets?

Accepted Answer

Use the data variant — smaller, more compact than full-page empty states. The widget's own header stays visible at the top; only the data area shows the empty state. Lead with an icon, a one-line title ("No transactions yet"), and an action if the user can do something about it ("Connect bank") or a passive note if they can't ("Data appears within 24 hours"). Keep the empty widget's height matching the populated state so the dashboard layout stays stable.

Question 8

How do I install an empty state example?

Accepted Answer

Run the `npx shadcn@latest add` command shown under the Installation heading. The CLI copies the example's TSX source into `components/examples/empty/…`, plus the shadcn/ui Empty primitive (and shared Button + Icon dependencies) if you don't already have them.

Question 9

Should I use an illustration or just an icon in the empty state?

Accepted Answer

Icons (Lucide, Heroicons) work for in-flow empty states (small widgets, search results) — they're lightweight, they theme via currentColor, and they don't compete with surrounding content. Custom illustrations work for first-run / onboarding empty states where the empty state IS the page — they brand the moment and warm up an otherwise sterile screen. Mixing both per page is fine; mixing illustration STYLES across pages is not.

Question 10

How do I gate the action button on the user's permissions?

Accepted Answer

Conditionally render the action button based on the user's role. Read-only viewers shouldn't see a "Create item" CTA they can't fulfill — render a passive description instead ("Ask an admin to create the first item"). For empty states with multiple actions per role, build a small ALLOWED_ACTIONS map keyed by role and render the matching subset.

Question 11

Which libraries do empty state examples depend on?

Accepted Answer

shadcn/ui Empty (the styled wrapper generated into your project), Tailwind CSS, Lucide React (icons + illustrations), and shadcn/ui Button (for action affordances). React 19 baseline. No state library — empty states are pure render. Custom illustrations bring their own SVG assets; we recommend Heroicons or hand-rolled SVG over heavyweight illustration libraries.

Question 12

Are empty state examples accessible for screen reader users?

Accepted Answer

Yes. The Empty wrapper renders semantic markup — `

` or `

` for the title (matching your page heading hierarchy), `
` for the description, and a real `

Question 13

Can I use these empty state examples with React Server Components?

Accepted Answer

Yes — empty states are pure render with no client state. They work cleanly as Server Components. Compute "is the data empty?" on the server and conditionally render the Empty primitive vs the populated UI in your Server Component. The action buttons inside go through whatever pattern your app uses (Server Action, client navigation, modal trigger).

React Empty State Examples for shadcn/ui

Browse every empty state example

Frequently Asked Questions