# EmptyState

> What a view shows when it has no content — a gray icon, a title, one sentence on why it is empty and what to do, and at most one button.

Source: https://raft-design.botiverse.build/components/empty-state. Generated from the current release; where it differs from what you remember, this page is right.

An empty state tells people why a view has no content and what to do next. It has one look everywhere: a gray icon with no frame, a gray title, one sentence, and at most one button. It is a conclusion ("there is nothing here"), so it never stands in for loading or a failure.

```tsx
import {
  EmptyState,
  EmptyStateDescription,
  EmptyStateContent,
  EmptyStateIcon,
  EmptyStateTitle,
} from "@botiverse/raft-ui";
import { Inbox } from "lucide-react";

export function EmptyStateDefaultContent() {
  return (
    <EmptyState>
      <EmptyStateContent>
        <EmptyStateIcon>
          <Inbox />
        </EmptyStateIcon>
        <EmptyStateTitle>No messages yet</EmptyStateTitle>
        <EmptyStateDescription>Conversations you start will show up here.</EmptyStateDescription>
      </EmptyStateContent>
    </EmptyState>
  );
}
```

## When to use

| Situation                         | Use                                                                                                                 |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| There is nothing here yet         | EmptyState: why it is empty and how to make something appear                                                        |
| Filters or a search match nothing | EmptyState: which conditions are active, with Clear All                                                             |
| It is still loading               | [Skeleton](https://raft-design.botiverse.build/components/skeleton.md), not an empty state                                                             |
| It failed to load                 | An error at its scope, with Retry ([Feedback](https://raft-design.botiverse.build/patterns/feedback.md#empty-loading-and-failed)) |

## Anatomy

- `EmptyState`: the centered root. Required.
- `EmptyStateContent`: groups the icon, title and description. Required.
- `EmptyStateIcon`: a Lucide icon, at 36px in `foreground-hint`. Required.
- `EmptyStateTitle`: the title, in `foreground-muted`. Required.
- `EmptyStateDescription`: one sentence, in `foreground-hint`. A link in it is 600 with no underline at rest and underlines in ink on hover ([Clickable text](https://raft-design.botiverse.build/foundations/states.md#clickable-text)): the weight is what sets it apart from the grey sentence.
- `EmptyStateActions`: at most one button.

```tsx
import {
  EmptyState,
  EmptyStateDescription,
  EmptyStateContent,
  EmptyStateIcon,
  EmptyStateTitle,
} from "@botiverse/raft-ui";
import { Layers } from "lucide-react";

export function EmptyStateActivityInboxContent() {
  return (
    <EmptyState>
      <EmptyStateContent>
        <EmptyStateIcon>
          <Layers />
        </EmptyStateIcon>
        <EmptyStateTitle>Activity is empty</EmptyStateTitle>
        <EmptyStateDescription>
          Channels, DMs, and followed threads stay here until they are done.
        </EmptyStateDescription>
      </EmptyStateContent>
    </EmptyState>
  );
}
```

## Content

- Write the title in sentence case and state the fact: "No tasks yet", "No tasks match these filters" ([Writing](https://raft-design.botiverse.build/content/writing.md#voice)).
- For a view with nothing yet, say in the description how something gets here.
- For filters or a search with no results, name the conditions that are active, and label the button Clear All.

## Accessibility

- `EmptyStateIcon` is hidden from assistive technology (`aria-hidden`): the title says what is empty.
- When the empty state is the only content of a page or panel, render the title as a heading (`render`) at the level the page needs.

## Rules

- Put the empty state directly in the middle of the content area. Don't wrap it in a card, frame the icon or add a sticker: empty states are working pages ([Brand](https://raft-design.botiverse.build/foundations/brand.md#how-much-brand)).
- Give it at most one button: a 32px ink-bordered button (`variant="default" size="md"`), never pink.
- Keep it quiet. The empty state is a hint, not a heading: small, faint type that doesn't compete with the button people should press next.

## API

### EmptyState

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### EmptyStateActions

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### EmptyStateContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### EmptyStateDescription

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### EmptyStateIcon

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### EmptyStateTitle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

## Changes

- 0.7.0 (Fixed): `EmptyStateIcon` is hidden from assistive technology, and `NotificationCenterItemIcon` is announced as an image named by its status.