# Empty

Fills a region that has nothing to show yet.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Empty.tsx)

Figma: [Messaging/Progress Panel](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-3967) (`Empty.Root`)

## Overview

A centered placeholder with a title, a description, an optional icon, and actions.

## Examples

### Basic

```tsx
import { Button, Empty } from '@tempoxyz/ds'
import { Clipboard } from '@tempoxyz/ds/icons'

export function Demo() {
  return (
    <Empty.Root>
      <Empty.Icon>
        <Clipboard />
      </Empty.Icon>
      <Empty.Title>No activity yet</Empty.Title>
      <Empty.Description>Transactions will appear here once you send or receive.</Empty.Description>
      <Empty.Actions>
        <Button size="small">Refresh</Button>
        <Button size="small" variant="secondary">
          Learn more
        </Button>
      </Empty.Actions>
    </Empty.Root>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Empty/Basic.tsx)

### Progress

Use a [Spinner](/docs/components/spinner) instead of the icon while the region waits on another task, such as a checkout in another window. Frame it in a `medium` [Surface](/docs/components/surface) for a panel.

```tsx
/** An empty state in a medium surface that waits on a checkout in another window. @module */
import { Empty, Spinner, Surface } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Surface size="medium">
      <Empty.Root>
        <Spinner aria-label="Waiting for checkout" />
        <Empty.Title>Finish checkout in the window that opened</Empty.Title>
        <Empty.Description>Buying $10.00 of MACH. This updates when it lands.</Empty.Description>
      </Empty.Root>
    </Surface>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Empty/Progress.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Empty } from '@tempoxyz/ds'

<Empty.Root>
  <Empty.Icon />
  <Empty.Title />
  <Empty.Description />
  <Empty.Actions />
</Empty.Root>
```

## Guidelines

### When to Use

* Fill a list or table with no records yet.
* Replace results when a search or filter matches nothing.
* Confirm that a list is clear on purpose, such as a retry queue with nothing left.

### When Not to Use

* Use [Skeleton](/docs/components/skeleton) while the request runs. Show the empty state only after it returns no records.
* Use a `negative` [Alert](/docs/components/alert) with a Retry action if the data fails to load.
* Use `Combobox.Empty` of [Combobox](/docs/components/combobox) or `Autocomplete.Empty` of [Autocomplete](/docs/components/autocomplete) for a popup list with no matches.

### Explain Why, Then Offer a Next Step

* **`Empty.Title`:** States what belongs here.
* **`Empty.Description`:** States why there is nothing.
* **`Empty.Actions`:** Holds a [Button](/docs/components/button) for the next step.

**Do:** Say what will appear and offer the action that adds it.

```tsx
/**
 * Do example for "Explain Why, Then Offer a Next Step" on the Empty page.
 * Say what will appear and offer the action that adds it.
 * @module
 */
import { Button, Empty } from '@tempoxyz/ds'
import { Key } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Empty.Root>
      <Empty.Icon>
        <Key />
      </Empty.Icon>
      <Empty.Title>No API keys yet</Empty.Title>
      <Empty.Description>Create a key to call the Tempo API from your server.</Empty.Description>
      <Empty.Actions>
        <Button size="small">Create key</Button>
      </Empty.Actions>
    </Empty.Root>
  )
}
```

**Don't:** Show a bare No data with no reason or next step.

```tsx
/**
 * Don't example for "Explain Why, Then Offer a Next Step" on the Empty page.
 * Don't show a bare No data with no reason or next step.
 * @module
 */
import { Empty } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Empty.Root>
      <Empty.Title>No data</Empty.Title>
    </Empty.Root>
  )
}
```

### Match the Message to the Cause

* **Nothing Created Yet:** Offer the action that adds the first item.
* **No Search Results:** Repeat the query and offer to clear it.
* **Filters Exclude All:** Offer to clear the filters.
* **Cleared on Purpose:** Offer no action, or a link to the logs.

### Offer One Primary Action

Add a `secondary` button only for a real alternative, such as View docs. Use `size="small"` to match the centered text.

**Do:** Give `Empty.Actions` one `primary` button that resolves the empty state.

```tsx
/**
 * Do example for "Offer One Primary Action" on the Empty page.
 * Give `Empty.Actions` one `primary` button that resolves the empty state.
 * @module
 */
import { Button, Empty } from '@tempoxyz/ds'
import { Key } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Empty.Root>
      <Empty.Icon>
        <Key />
      </Empty.Icon>
      <Empty.Title>No API keys yet</Empty.Title>
      <Empty.Description>Create a key to call the Tempo API from your server.</Empty.Description>
      <Empty.Actions>
        <Button size="small" variant="secondary">
          View docs
        </Button>
        <Button size="small">Create key</Button>
      </Empty.Actions>
    </Empty.Root>
  )
}
```

**Don't:** Offer several `primary` buttons.

```tsx
/** Don't example for "Offer One Primary Action" on the Empty page. Don't offer several `primary` buttons. @module */
import { Button, Empty } from '@tempoxyz/ds'
import { Key } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Empty.Root>
      <Empty.Icon>
        <Key />
      </Empty.Icon>
      <Empty.Title>No API keys yet</Empty.Title>
      <Empty.Description>Create a key to call the Tempo API from your server.</Empty.Description>
      <Empty.Actions>
        <Button size="small">View docs</Button>
        <Button size="small">Import key</Button>
        <Button size="small">Create key</Button>
      </Empty.Actions>
    </Empty.Root>
  )
}
```

### Keep It Inside the Region It Replaces

**Do:** Render `Empty.Root` in place of the list or table body. Keep the heading and filters around it.

```tsx
/**
 * Do example for "Keep It Inside the Region It Replaces" on the Empty page.
 * Render `Empty.Root` in place of the list or table body. Keep the heading and filters around it.
 * @module
 */
import { Empty, style, Surface, TextInput } from '@tempoxyz/ds'
import { Search } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Surface size="medium" {...styles.card()}>
      <div {...styles.heading()}>Payments</div>
      <TextInput.Group>
        <TextInput.Prefix>
          <Search />
        </TextInput.Prefix>
        <TextInput.Control aria-label="Search payments" defaultValue="0x8f3c" />
      </TextInput.Group>
      <Empty.Root>
        <Empty.Title>No results for "0x8f3c"</Empty.Title>
        <Empty.Description>Check the address, or search by amount.</Empty.Description>
      </Empty.Root>
    </Surface>
  )
}

namespace styles {
  export const card = style({
    boxSizing: 'border-box',
    display: 'flex',
    flexDirection: 'column',
    gap: '16',
    width: '100% !custom',
  })

  export const heading = style({ color: 'content.primary', typography: 'body.b1Strong' })
}
```

**Don't:** Replace the heading and filters with the empty state.

```tsx
/**
 * Don't example for "Keep It Inside the Region It Replaces" on the Empty page.
 * Don't replace the heading and filters with the empty state.
 * @module
 */
import { Empty, style, Surface } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Surface size="medium" {...styles.card()}>
      <Empty.Root>
        <Empty.Title>No results for "0x8f3c"</Empty.Title>
        <Empty.Description>Check the address, or search by amount.</Empty.Description>
      </Empty.Root>
    </Surface>
  )
}

namespace styles {
  export const card = style({
    boxSizing: 'border-box',
    display: 'flex',
    flexDirection: 'column',
    gap: '16',
    width: '100% !custom',
  })
}
```

Use `Empty.Icon` for an icon that names the content type, such as `Key` for API keys. Leave out status icons such as `AlertTriangle`.

## Content

* **Title:** State what is missing, such as No activity yet, without a period.
* **Description:** In one sentence, state when content appears or why it is hidden, such as Transactions appear here once you send or receive. It wraps at 22.5rem.
* **Tone:** Avoid blame and jokes. Write No payments match these filters, not You haven't made any payments.
* **Action:** Start with a verb and name the object, such as Create key. Avoid Get started.

## Accessibility

An empty state renders plain elements with no ARIA wiring, in the order you compose them.

### Semantics

* **Empty.Title (h3):** Titles the empty state below a section heading.
* **Empty.Description (p):** Explains why the area is empty or what to do.
* **Empty.Icon (aria-hidden):** A decorative badge that screen readers skip.
* **Empty.Actions:** Holds the buttons or links you pass.

### Keyboard

* **Move Through the Actions (Tab):** Moves focus to each action, in order.
* **Activate an Action (Enter or Space):** Actions keep native keys and focus outlines.

### Your Responsibilities

* **Keep the Heading Order (h2 then h3):** Put the empty state under a section heading to keep the outline in order (SC 1.3.1).
* **Announce New Results (role="status"):** Not a live region. If it replaces results after a search, announce it in a status element.

## Related

[Skeleton](/docs/components/skeleton)

Use for content that is still loading.

[Alert](/docs/components/alert)

Use for a failed load with a retry.

[Button](/docs/components/button)

Use for the action that fills the state.

[Empty States](/docs/patterns/empty-states)

Covers first-use, no-results, and cleared states.
