# Empty States

Explain why a region has nothing to show, and offer the next step that fills it.

## Overview

An empty region can mean missing data, a filter with no matches, finished work, or a failed request. Each cause takes different words and actions. [Empty](/docs/components/empty) composes the parts, and every empty state covers three points:

* **What Is This Place? (Empty.Title):** Names the content that would appear.
* **Why Is It Empty? (Empty.Description):** Explains the cause in one sentence.
* **What Can I Do? (Empty.Actions):** One action that fills the region, if one exists.

## Variants

The cause decides the text and the action. These are reference layouts built from [Surface](/docs/components/surface), [Empty](/docs/components/empty), and [Button](/docs/components/button), not shipped components.

### First Use

```tsx
import { Button, Empty, style, Surface } from '@tempoxyz/ds'
import { History } from '@tempoxyz/ds/icons'

export const fill = true
export function Demo() {
  return (
    <div {...styles.page()}>
      <Surface {...styles.card()}>
        <Surface.Header>
          <Surface.Title>Activity</Surface.Title>
        </Surface.Header>
        <Empty.Root>
          <Empty.Icon>
            <History />
          </Empty.Icon>
          <Empty.Title>No activity yet</Empty.Title>
          <Empty.Description>
            Payments you send and receive appear here. Add funds to make your first payment.
          </Empty.Description>
          <Empty.Actions>
            <Button size="small">Add funds</Button>
          </Empty.Actions>
        </Empty.Root>
      </Surface>
    </div>
  )
}

namespace styles {
  export const card = style({
    boxSizing: 'border-box',
    maxWidth: '26rem !custom',
    width: '100% !custom',
  })

  export const page = style({
    backgroundColor: 'background.primary',
    display: 'grid',
    justifyItems: 'center',
    padding: '16',
  })
}
```

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

Nothing exists yet. State what will appear, and offer the action that creates the first item, such as Add funds or Create key.

### No Results

```tsx
import { Button, Empty, Field, Identicon, ListGroup, style, Surface, TextInput } from '@tempoxyz/ds'
import { Search } from '@tempoxyz/ds/icons'
import { useRef, useState } from 'react'

export const fill = true
const contacts = [
  ['Ada', '0x71C7656EC7ab88b098defB751B7401B5f6d8976F'],
  ['Payroll', '0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC'],
  ['Treasury', '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'],
] as const

export function Demo() {
  const input = useRef<HTMLInputElement>(null)
  const [query, setQuery] = useState('zara')
  const matches = contacts.filter(([name, address]) =>
    `${name} ${address}`.toLowerCase().includes(query.trim().toLowerCase()),
  )

  return (
    <div {...styles.page()}>
      <Surface {...styles.card()}>
        <Surface.Header>
          <Surface.Title>Contacts</Surface.Title>
        </Surface.Header>
        <Field.Root>
          <TextInput.Group>
            <TextInput.Prefix>
              <Search />
            </TextInput.Prefix>
            <TextInput.Control
              aria-label="Search contacts"
              onValueChange={setQuery}
              placeholder="Name or address"
              ref={input}
              type="search"
              value={query}
            />
            <TextInput.Clear />
          </TextInput.Group>
        </Field.Root>
        {/* Stays mounted, so screen readers hear the count change as you type. */}
        <p role="status" {...styles.status()}>
          {matches.length === 1 ? '1 contact' : `${matches.length} contacts`}
        </p>
        {matches.length > 0 ? (
          <div {...styles.rows()}>
            <ListGroup.Root>
              {matches.map(([name, address]) => (
                <ListGroup.Row key={address}>
                  <Identicon address={address} aria-hidden size="24" />
                  <ListGroup.Info>
                    <ListGroup.Title>{name}</ListGroup.Title>
                    <ListGroup.Description>
                      {address.slice(0, 6)}…{address.slice(-4)}
                    </ListGroup.Description>
                  </ListGroup.Info>
                </ListGroup.Row>
              ))}
            </ListGroup.Root>
          </div>
        ) : (
          <Empty.Root>
            <Empty.Icon>
              <Search />
            </Empty.Icon>
            <Empty.Title>No contacts match “{query.trim()}”</Empty.Title>
            <Empty.Description>
              Check the spelling, or search by the full 0x address.
            </Empty.Description>
            <Empty.Actions>
              <Button
                onClick={() => {
                  setQuery('')
                  input.current?.focus()
                }}
                size="small"
                variant="secondary"
              >
                Clear search
              </Button>
            </Empty.Actions>
          </Empty.Root>
        )}
      </Surface>
    </div>
  )
}

namespace styles {
  export const card = style({
    boxSizing: 'border-box',
    maxWidth: '26rem !custom',
    width: '100% !custom',
  })

  export const page = style({
    backgroundColor: 'background.primary',
    display: 'grid',
    justifyItems: 'center',
    padding: '16',
  })

  export const rows = style({ marginBlockStart: '8' })

  export const status = style({
    clipPath: 'inset(50%) !custom',
    height: '1px !custom',
    margin: '0',
    overflow: 'hidden',
    position: 'absolute',
    whiteSpace: 'nowrap',
    width: '1px !custom',
  })
}
```

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

Repeat the query in the title, so the reader can spot a typo. Offer Clear search or Clear filters as a `secondary` button, and keep the search field and filters visible above the empty state.

**Do:** Repeat the query and offer a way to widen the search.

```tsx
<Empty.Root>
  <Empty.Icon>
    <Search />
  </Empty.Icon>
  <Empty.Title>No results for "rent"</Empty.Title>
  <Empty.Description>Check the spelling or search for another payment.</Empty.Description>
  <Empty.Actions>
    <Button size="small" variant="secondary">Clear search</Button>
  </Empty.Actions>
</Empty.Root>
```

**Don't:** If a filter hides existing items, don't show the first use state.

```tsx
<Empty.Root>
  <Empty.Icon>
    <Wallet />
  </Empty.Icon>
  <Empty.Title>No payments yet</Empty.Title>
  <Empty.Description>Payments you send or receive appear here.</Empty.Description>
  <Empty.Actions>
    <Button size="small">Add funds</Button>
  </Empty.Actions>
</Empty.Root>
```

### Cleared

```tsx
import { Button, Empty, style, Surface } from '@tempoxyz/ds'
import { CheckCircle } from '@tempoxyz/ds/icons'

export const fill = true
export function Demo() {
  return (
    <div {...styles.page()}>
      <Surface {...styles.card()}>
        <Surface.Header>
          <Surface.Title>Payment requests</Surface.Title>
        </Surface.Header>
        <Empty.Root>
          <Empty.Icon>
            <CheckCircle />
          </Empty.Icon>
          <Empty.Title>No pending requests</Empty.Title>
          <Empty.Description>
            You've paid or declined every request. New requests appear here.
          </Empty.Description>
          <Empty.Actions>
            <Button size="small" variant="secondary">
              View history
            </Button>
          </Empty.Actions>
        </Empty.Root>
      </Surface>
    </div>
  )
}

namespace styles {
  export const card = style({
    boxSizing: 'border-box',
    maxWidth: '26rem !custom',
    width: '100% !custom',
  })

  export const page = style({
    backgroundColor: 'background.primary',
    display: 'grid',
    justifyItems: 'center',
    padding: '16',
  })
}
```

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

If the reader processed everything, such as every payment request, confirm that nothing is left. Leave out the primary action. If a history exists, link to it.

**Do:** Confirm the reader finished, and state what will appear next.

```tsx
<Empty.Root>
  <Empty.Icon>
    <Check />
  </Empty.Icon>
  <Empty.Title>All caught up</Empty.Title>
  <Empty.Description>New requests appear here when someone asks you to pay.</Empty.Description>
</Empty.Root>
```

**Don't:** Use playful filler in place of a clear outcome.

```tsx
<Empty.Root>
  <Empty.Icon>
    <Clipboard />
  </Empty.Icon>
  <Empty.Title>Nothing here!</Empty.Title>
  <Empty.Description>Looks like it is pretty quiet. Check back later!</Empty.Description>
</Empty.Root>
```

### Error-Empty

```tsx
import { Button, Empty, ListGroup, style, Surface } from '@tempoxyz/ds'
import { AlertCircle } from '@tempoxyz/ds/icons'
import { useState } from 'react'

export const fill = true
function Failed(props: { onRetry: () => void; retrying: boolean }) {
  return (
    <Empty.Root>
      <Empty.Icon>
        <AlertCircle />
      </Empty.Icon>
      <Empty.Title>Couldn't load activity</Empty.Title>
      <Empty.Description>
        Check your connection, then try again. Your balance and payments aren't affected.
      </Empty.Description>
      <Empty.Actions>
        <Button loading={props.retrying} onClick={props.onRetry} size="small">
          Try again
        </Button>
      </Empty.Actions>
    </Empty.Root>
  )
}

export function Demo() {
  const [loaded, setLoaded] = useState(false)
  const [retrying, setRetrying] = useState(false)

  return (
    <div {...styles.page()}>
      <Surface {...styles.card()}>
        <Surface.Header>
          <Surface.Title>Activity</Surface.Title>
        </Surface.Header>
        {loaded ? (
          <div {...styles.rows()}>
            <ListGroup.Root>
              <ListGroup.Row>
                <ListGroup.Label>Received from 0x3C44…93BC</ListGroup.Label>
                120.00 USDC
              </ListGroup.Row>
              <ListGroup.Row>
                <ListGroup.Label>Sent to 0x71C7…976F</ListGroup.Label>
                25.00 USDC
              </ListGroup.Row>
            </ListGroup.Root>
          </div>
        ) : (
          <Failed
            onRetry={() => {
              setRetrying(true)
              setTimeout(() => {
                setRetrying(false)
                setLoaded(true)
              }, 1000)
            }}
            retrying={retrying}
          />
        )}
      </Surface>
    </div>
  )
}

namespace styles {
  export const card = style({
    boxSizing: 'border-box',
    maxWidth: '26rem !custom',
    width: '100% !custom',
  })

  export const page = style({
    backgroundColor: 'background.primary',
    display: 'grid',
    justifyItems: 'center',
    padding: '16',
  })

  export const rows = style({ marginBlockStart: '8' })
}
```

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

If the request fails, write Couldn't load followed by the content, and offer Try again. Set `loading` on the [Button](/docs/components/button) while the retry runs.

## Guidelines

### Explain the Cause and the Next Step

Write the title as a short statement of what is missing, such as No API keys yet. Use the description for the cause and what the action does.

**Do:** State what is missing and offer the action that adds it.

```tsx
/**
 * Do example for "Explain the Cause and the Next Step" on the Empty States page.
 * State what is missing 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 message with nothing to do next.

```tsx
/**
 * Don't example for "Explain the Cause and the Next Step" on the Empty States page.
 * Don't show a bare No data message with nothing to do next.
 * @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>
  )
}
```

### Never Show a Failed Request as Empty

An empty list after a failed request falsely reports no activity. Keep empty states for successful requests with no content.

**Do:** State that the content couldn't load, and offer Try again.

```tsx
/**
 * Do example for "Never Show a Failed Request as Empty" on the Empty States page.
 * State that the content couldn't load, and offer Try again.
 * @module
 */
import { Button, Empty } from '@tempoxyz/ds'
import { AlertCircle } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Empty.Root>
      <Empty.Icon>
        <AlertCircle />
      </Empty.Icon>
      <Empty.Title>Couldn't load activity</Empty.Title>
      <Empty.Description>Check your connection, then try again.</Empty.Description>
      <Empty.Actions>
        <Button size="small">Try again</Button>
      </Empty.Actions>
    </Empty.Root>
  )
}
```

**Don't:** Show No activity yet after the request failed.

```tsx
/**
 * Don't example for "Never Show a Failed Request as Empty" on the Empty States page.
 * Don't show No activity yet after the request failed.
 * @module
 */
import { Empty } from '@tempoxyz/ds'
import { History } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Empty.Root>
      <Empty.Icon>
        <History />
      </Empty.Icon>
      <Empty.Title>No activity yet</Empty.Title>
      <Empty.Description>Payments you send and receive appear here.</Empty.Description>
    </Empty.Root>
  )
}
```

### Offer One Primary Action

Make it the task that fills the region. Add a secondary button only for a related step, such as a guide, and use `Button.Link` if the action opens another page.

**Do:** Pair one primary action with an optional secondary one.

```tsx
/**
 * Do example for "Offer One Primary Action" on the Empty States page.
 * Pair one primary action with an optional secondary one.
 * @module
 */
import { Button, Empty } from '@tempoxyz/ds'
import { Link } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Empty.Root>
      <Empty.Icon>
        <Link />
      </Empty.Icon>
      <Empty.Title>No webhooks</Empty.Title>
      <Empty.Description>Add an endpoint to receive payment events.</Empty.Description>
      <Empty.Actions>
        <Button size="small">Add webhook</Button>
        <Button size="small" variant="secondary">
          Read the guide
        </Button>
      </Empty.Actions>
    </Empty.Root>
  )
}
```

**Don't:** Offer several primary actions that compete for attention.

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

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Empty.Root>
      <Empty.Icon>
        <Link />
      </Empty.Icon>
      <Empty.Title>No webhooks</Empty.Title>
      <Empty.Description>Add an endpoint to receive payment events.</Empty.Description>
      <Empty.Actions>
        <Button size="small">Add webhook</Button>
        <Button size="small">Import</Button>
        <Button size="small">Test event</Button>
      </Empty.Actions>
    </Empty.Root>
  )
}
```

### Fit the State to the Region

* **Pages and Cards:** Use the full empty state with an icon that hints at the content.
* **Small Regions:** In a small region, such as a [Popover](/docs/components/popover), use a short line of text and no icon.
* **Comboboxes (Combobox.Empty):** Render it in a [Combobox](/docs/components/combobox), so an empty result is announced instead of an empty popup.
* **Keep the Frame:** Keep the heading and filters. In a [Table](/docs/components/table), put the empty state below the header row.

### Don't Show an Empty State While Loading

* **Load First (Skeleton):** Show a [Skeleton](/docs/components/skeleton) until the request settles. An empty state that flashes first reads as a missing balance.
* **Then Decide:** After the request settles, choose content, an empty state, or an error (see [Loading](/docs/patterns/loading)).

## States

* **Disabled:** If the reader lacks permission for the action, leave it out and state who can act.
* **Success (Toast):** The new item replaces the empty state, and a [Toast](/docs/components/toast) confirms it.

## Content

* **Title (Sentence case):** Name what is missing, such as "No payments yet".
* **Description (1 sentence):** Address the reader as "you".
* **Action (Verb):** Lead with a verb, such as "Add funds".

## Accessibility

* **Heading Level (h3):** Place the state under an `h2`, such as a `Surface.Title`, so heading levels stay in order.
* **Announce Results (role=status):** The parts render no live region. If results change on input, announce the count in a polite region that stays mounted.
* **Focus After Clearing:** After Clear search, move focus to the search field.

## Related

[Empty](/docs/components/empty)

Use for the component parts.

[Combobox](/docs/components/combobox)

Use for empty popups.

[Loading](/docs/patterns/loading)

Covers what shows before content.

[Feedback and Status](/docs/patterns/feedback-and-status)

Covers the Couldn't load state.

[Tables and Lists](/docs/patterns/tables-and-lists)

Covers empty tables.
