Shadcn Empty State: Placeholder Screens That Guide Users
An empty state is what users see when there is nothing to show yet: no results, no data, no connection, or a page that does not exist. The shadcn empty state component gives these moments structure, pairing an icon or illustration with a title, a short explanation, and a next action, all styled with Tailwind CSS.
This page collects copy-paste empty state examples for React and Next.js projects, from a simple placeholder to variants with avatars, an outline treatment, a maintenance mode screen, a 404 page, and a no connection fallback, so every dead end in your app can point somewhere useful.
Why use the Shadcn Empty State?
- Turns dead ends into paths: A good empty screen explains why nothing is here and offers the next step, like creating the first project or clearing filters.
- Consistent anatomy: Media, title, description, and action always sit in the same structure, so empty moments feel designed rather than broken.
- Covers error pages too: The 404, no connection, and maintenance mode examples extend the same pattern to full error screens.
- People-centric variants: The avatar-based examples suit invite flows and team screens where the missing thing is a person.
- Zero dependencies: It is layout and typography only, so it adds nothing to your bundle beyond the markup itself.
Production tips
- Write the reason, not just the fact: No results found is weaker than No results for that filter, try removing the date range. Explain and suggest in one line.
- Always offer an action: Nearly every empty state deserves a button: create, invite, retry, or go back. A dead end without an exit frustrates users.
- Distinguish empty from loading: Never flash an empty state while data is still fetching. Show a skeleton or spinner first, and only render empty when the result is truly empty.
- Keep first-run states warm: The first empty screen a new user sees is onboarding. Friendly copy and a clear first action there directly affect activation.
Works well with other components
Empty states end with an action, so a button is almost always part of the composition. Inside a card they fill widget bodies on dashboards, while a data table with zero rows is one of the most common hosts. During fetches, a skeleton or spinner should hold the space before the empty state renders.
Our dashboard blocks use these placeholders throughout list views and detail pages, which is a quick way to see the pattern in a complete interface.
Under the hood
There is no primitive behind this component, and that is by design. As described in the shadcn empty docs, it is plain accessible markup, a media slot, heading, paragraph, and content area, arranged with Tailwind CSS utilities and fully typed in TypeScript.
Because nothing is interactive by default, every variant slots into Radix UI and Base UI interfaces with no rework. Any behavior comes from the components you place inside it, such as the action button.