# EmptyState

> Explains why an area is empty and offers the next step.

Category: Feedback · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/empty-state

Use EmptyState for first-run screens, empty search results and cleared filters. Say what would normally be here, why it is empty, and give one clear action. Keep the tone helpful and brief.

## Import

```tsx
import { EmptyState } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### First run

```tsx
import { Button, EmptyState, Icon } from '@bindshq/stance-react';

export function Basic() {
  return (
    <EmptyState
      icon={<Icon name="pen-nib" />}
      title="No signature templates yet"
      description="Create a template to give everyone in your organisation a consistent, on-brand signature."
      action={<Button leadingIcon={<Icon name="plus" />}>Create template</Button>}
      secondaryAction={<Button variant="ghost">Browse gallery</Button>}
    />
  );
}
```

### No results

```tsx
import { Button, EmptyState, Icon } from '@bindshq/stance-react';

export function NoResults() {
  return (
    <EmptyState
      icon={<Icon name="search" />}
      title="No contracts match these filters"
      description="Try removing a filter or searching for a different counterparty."
      action={<Button variant="outline">Clear filters</Button>}
    />
  );
}
```

### Compact and bordered

```tsx
import { Button, EmptyState, Icon } from '@bindshq/stance-react';

export function Sizes() {
  return (
    <div
      style={{
        display: 'grid',
        gap: 16,
        gridTemplateColumns: 'repeat(auto-fit, minmax(240px, 1fr))',
      }}
    >
      <EmptyState
        size="sm"
        bordered
        icon={<Icon name="inbox" />}
        title="No notifications"
        description="You’re all caught up."
      />
      <EmptyState
        size="sm"
        bordered
        icon={<Icon name="upload" />}
        title="No users imported"
        description="Upload a CSV to add people in bulk."
        action={<Button size="sm">Upload CSV</Button>}
      />
    </div>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| EmptyState | `title` (required) | `ReactNode` | None | Short headline. |
| EmptyState | `description` | `ReactNode` | None | One or two sentences of explanation. |
| EmptyState | `icon` | `ReactNode` | None | Decorative icon or illustration. |
| EmptyState | `action` | `ReactNode` | None | Primary action. |
| EmptyState | `secondaryAction` | `ReactNode` | None | Secondary action. |
| EmptyState | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Spacing and type scale. |
| EmptyState | `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `3` | Heading level of the title. |
| EmptyState | `bordered` | `boolean` | `false` | Dashed border around the area. |

## Accessibility

- The title is a real heading; set headingLevel to fit the surrounding outline.
- The icon is decorative and hidden from assistive technology.
- When results empty out after filtering, pair this with a live results count (see FilterBar) so the change is announced.

## Guidelines

**Do**

- Offer the action that fills the space.
- For no results, suggest clearing filters.

**Don’t**

- Blame the user or use jokes in error-adjacent states.

## Related

- https://stanceui.com/components/filter-bar
- https://stanceui.com/components/skeleton
- https://stanceui.com/components/alert