Why Empty States Deserve Real Design
An empty state is what a screen shows when there is nothing to show: no data yet, no search matches, no items in a list. Left undesigned, these moments read as broken pages. Designed well, they orient the user, explain why the screen is empty, and point to the next action. This block treats the empty state as a first-class component instead of an afterthought.
The block builds on the Shadcn UI Empty component, composing its header, media, title, and description slots with an icon and Tailwind spacing to produce a centered, balanced placeholder. Fittingly, the example's own preview currently renders exactly this pattern while the expanded set of variations is in development.
Screens That Call for an Empty State
First-run experiences are the classic case: a new user opens a dashboard, an inbox, or a project list and everything is empty by definition. Zero-result queries are the second, where a search results screen needs to say nothing matched without feeling like a dead end. The third is cleared content, an emptied cart, an archived task list, a folder with no files.
Empty states also share a border with error pages: both explain an absence and route the user onward. The difference is tone. An empty state is an invitation to act, usually with a create or import button, while an error page is an apology with a way back.
Built on the Shadcn UI Empty Primitives
Technically the block is a React component styled with Tailwind. The Empty primitive supplies the semantic slots: EmptyHeader wraps the visual, EmptyMedia hosts an icon or illustration with an icon variant for framed glyphs, EmptyTitle carries the headline, and EmptyDescription holds the supporting sentence. An optional action button completes the pattern.
Because the structure is slot-based, variations are cheap. Swap the icon per context, shorten the description for inline use inside a card, or add two actions for create-or-import flows. The composition stays identical, which keeps every empty moment in your product visually consistent.
Tuning the Look With CSS Variables
The block colors itself entirely through Shadcn UI design tokens: the icon frame and description use muted tones, the title uses the foreground color, and any action button inherits your primary variable. Adjusting globals.css therefore restyles every empty state in the app at once, and dark mode support is automatic since no color is hard-coded.
This token approach matters for a component that appears in many contexts. The same empty state must sit on a page background, inside a card, and within a modal, and variable-based colors guarantee correct contrast in each without per-context overrides.
Using the Block in Your Own Screens
Install through the shadcn CLI command at the top of the example page, available for npm, pnpm, yarn, and bun, or copy the component from the code tab. As a pro example, the code and CLI install are part of the All Access plan, described on the pricing page.
Integration is a conditional render: when your data array is empty or a query returns nothing, show the block instead of the list. The component is available in React, Vuejs, and Svelte versions, with the Vuejs and Svelte editions built on the shadcn-vue and shadcn-svelte ports, so every framework gets the same placeholder language.