# Empty

A centered placeholder for empty states.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<ComponentPreview name="empty" title="empty.tsx" previewClassName="h-auto py-8">
<EmptyDemo />
</ComponentPreview>

Empty is a composable placeholder for zero-data screens — inbox, search results, project lists, first-run onboarding. It renders a dashed surface with a stacked icon, title, description, and optional call-to-action.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
```bash
npx frakment add empty
```
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Install the following dependencies:
</Step>

```bash
npm install class-variance-authority
```

<Step>
Copy and paste the following code into your project.
</Step>

<ComponentSource name="empty" title="components/ui/empty.tsx" />

<Step>
Update the import paths to match your project setup.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Composition [#composition]

```text
Empty
├── EmptyHeader
├── EmptyMedia
├── EmptyTitle
├── EmptyDescription
└── EmptyContent
```

## Examples [#examples]

### Without media [#without-media]

Omit `EmptyMedia` entirely for the simplest empty state.

<ComponentPreview name="empty-no-media" title="empty-no-media.tsx" src="examples/empty-no-media.tsx" previewClassName="h-auto py-8">
<EmptyNoMedia />
</ComponentPreview>

```tsx
<Empty>
  <EmptyHeader>
    <EmptyTitle>No results found</EmptyTitle>
    <EmptyDescription>Try adjusting your search or filters.</EmptyDescription>
  </EmptyHeader>
</Empty>
```

### With description link [#with-description-link]

`EmptyDescription` accepts inline links that pick up Frakment underline styling.

<ComponentPreview name="empty-link" title="empty-link.tsx" src="examples/empty-link.tsx" previewClassName="h-auto py-8">
<EmptyLink />
</ComponentPreview>

```tsx
<Empty>
  <EmptyHeader>
    <EmptyMedia variant="icon">
      <Folder />
    </EmptyMedia>
    <EmptyTitle>No projects yet</EmptyTitle>
    <EmptyDescription>
      <a href="#docs">Read the guide</a> to learn how to create one.
    </EmptyDescription>
  </EmptyHeader>
</Empty>
```

### Outline media [#outline-media]

Use `variant="default"` on `EmptyMedia` to render media without a muted background square.

<ComponentPreview name="empty-outline" title="empty-outline.tsx" src="examples/empty-outline.tsx" previewClassName="h-auto py-8">
<EmptyOutline />
</ComponentPreview>

```tsx
<Empty>
  <EmptyHeader>
    <EmptyMedia>
      <Folder />
    </EmptyMedia>
    <EmptyTitle>Nothing here</EmptyTitle>
    <EmptyDescription>
      Use variant="default" to render media without a background.
    </EmptyDescription>
  </EmptyHeader>
</Empty>
```

## In Context [#in-context]

### Zero-data state [#zero-data-state]

<ComponentPreview name="empty-zero-data" title="empty-zero-data.tsx" src="examples/empty-zero-data.tsx">
<EmptyZeroData />
</ComponentPreview>

## API Reference [#api-reference]

All parts extend `React.ComponentProps<"div">` (except **EmptyDescription** which renders a `<div>` too for layout consistency).

### EmptyMedia [#emptymedia]

<PropsTable rows={[{"name":"variant","type":"\"default\" | \"icon\"","defaultValue":"\"default\"","description":"Icon wraps the child in a rounded muted square; default is transparent."}]} />

## Usage [#usage]

```tsx title="empty.tsx"
import { Empty, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from "@/components/ui/empty";
<DocsBaseSwitcher base="web" component="empty" className="mb-6" />
```

```tsx title="empty.tsx"
<Empty>
  <EmptyHeader>
    <EmptyMedia><MessageCircleDashedIcon /></EmptyMedia>
    <EmptyTitle>No messages yet</EmptyTitle>
    <EmptyDescription>Send the first one.</EmptyDescription>
  </EmptyHeader>
</Empty>
```

## Accessibility [#accessibility]

- The `EmptyTitle` renders as a heading; document outline stays flat.
- Pair the icon with the title; icon-only empty states are invisible to screen readers.
- Provide a primary action inside the empty state when possible.

## Best Practices [#best-practices]

- **Explain the empty state.** "No messages" beats "Empty".
- **Offer the first action.** A button or link beats a dead end.
- **Keep it small.** Empty states should not fill the whole page unless the page is empty.
- **Do not hide the empty state during loading.** Use a Skeleton instead.