---
title: "EmptyState"
description: "Explains why there is no data and offers a way out. The title names the absence; the description and action show how to continue."
kind: component
id: C-023
registry: "empty-state"
docs: "https://koten.codehive.com.co/components/empty-state"
markdown: "https://koten.codehive.com.co/md/components/empty-state.md"
install: "npx shadcn@latest add https://koten.codehive.com.co/r/empty-state.json"
language: en
---

# EmptyState · 空状態

> Component C-023 in the Koten UI catalog.

Explains why there is no data and offers a way out. The title names the absence; the description and action show how to continue.

> Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031).

## Install

Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project.

```bash
# Node
npx shadcn@latest add https://koten.codehive.com.co/r/empty-state.json

# Bun
bunx shadcn@latest add https://koten.codehive.com.co/r/empty-state.json
```

## Files

- `@/components/ui/empty-state.tsx`
- `@/lib/koten/cn.ts`
- `@/lib/koten/format.ts`
- `@/lib/koten/intl.ts`
- `@/lib/koten/labels.ts`
- `@/lib/koten/provider.tsx`

## Examples

### With an action

The action takes the user out of the empty state; without it, the block only informs.

```tsx
<EmptyState
  title="No orders"
  description="No orders match the selected filters. Try another warehouse or clear the search."
  action={<Button size="sm" variant="outline">Clear filters</Button>}
/>
```

### Custom icon, no action

In a read-only panel, an icon, title and a short hint are enough.

```tsx
<EmptyState
  icon={<Search className="size-5" aria-hidden="true" />}
  title="No results"
  description="Try a different code or clear the search."
/>
```

## Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `title` | `ReactNode` | `requerido` | Rendered as an h3 and names the absence; do not use it for a long sentence. |
| `description` | `ReactNode` | `—` | Explains the reason and the next step in one or two sentences. |
| `icon` | `ReactNode` | `—` | Replaces the inbox icon; it must be decorative (aria-hidden). |
| `action` | `ReactNode` | `—` | Button or link to leave the state; use a single primary action. |
| `div props` | `ComponentProps<"div">` | `—` | Forwarded to the container; className adjusts the block width. |

## Accessibility

- The title renders as an h3 inside the page hierarchy; do not add another heading with the same text.
- The action has an explicit name that describes the result, not an ambiguous “see more”.
- The icon is decorative; the title and description carry all the meaning.

## Sources

- Catalog page: https://koten.codehive.com.co/components/empty-state
- Markdown: https://koten.codehive.com.co/md/components/empty-state.md
- Repository: https://github.com/codehive-colombia/koten