Empty State

<EmptyState>TailwindCSS Modules

Empty states explain why a collection has no content and help people take the next step. Combine a clear title, supporting description, optional icon, and a focused action for first-use screens, filtered results, and quiet inboxes.

InstallationColoxo CLI
npx coloxo add empty-state --style coloxo-css
ES Module ImportPlayground / npm package
import { EmptyState } from '@coloxo/ui';

Design Tokens:

--cx-color-text-primary--cx-color-bg-secondaryicon container: 48px--cx-space-8: 32pxdescription max-width: 28rem

1. Empty state patterns

Use specific copy to distinguish a new collection, an unsuccessful search, and a completed task.

First use

No projects yet

Create your first project to organize your team's work.

No results

No results found

Try a different search term or clear your filters.

All caught up

You're all caught up

New notifications will appear here when there is an update.

2. Actions & composition

Use actionLabel with onAction for a built-in small primary button, or supply action for custom controls. A custom action takes precedence over actionLabel.

Simple action

No projects yet

Custom action slot

Build your team

Invite teammates or import an existing directory.

3. Interactive Props Configurator

Visual Render CanvasPATTERN: PROJECTS
No projects yet

Create your first project to organize your team's work.

tsx
<EmptyState  icon={<FolderOpen />}  title="No projects yet"  description="Create your first project to organize your team's work."  actionLabel="Create project"  onAction={handleAction}/>

4. Dark theme

Semantic tokens adapt the icon, title, description, and actions to dark surfaces.

First use
No projects yet

Your workspace is ready for its first project.

All caught up
You're all caught up

There are no unread notifications right now.

5. Enterprise layout compositions

Keep the surrounding context visible and make the recovery action useful. Try these local demos to see content replace an empty state.

Projects
Manage the work in your workspace.
Start your first project

Bring tasks, files, and teammates together in one place.

Team directory
Filtered by "Design team"
No matching members

No team members match the current filters. Clear them to see everyone.

Accessibility

Clear text

Explain the empty state in the title and description. Decorative icons should not be the only way to understand the message.

Keyboard actions

The built-in action is a native button that supports Tab, Enter, and Space. Use accessible buttons or links in custom action slots.

Dynamic updates

EmptyState does not add a live region or heading role automatically. Announce asynchronous results in an appropriate status region and add heading semantics when needed.

Props

NameTypeDefaultDescription
titleReactNode—Required title explaining the empty state.
descriptionReactNode—Supporting text rendered in a paragraph below the title.
iconReactNode—Optional icon rendered in a 48px circular container.
actionLabelstring—Label for the built-in small primary action button.
onAction() => void—Click handler for the built-in action button.
actionReactNode—Custom action slot. Takes precedence over the built-in action when non-nullish.
classNamestring—Additional classes on the root div. Other HTML div attributes are forwarded to the root.