# Empty state

> A centered placeholder for empty lists and searches. A native Pyzed component for Python desktop GUIs, with a live preview, code examples and its API.

Source: https://albakore.github.io/pyzed/library/empty-state/

:::tip[In plain words]
What a screen shows when there is nothing in it yet, with a hint of what to do next.
:::

A centered icon, title, description and actions for a place that has nothing to show yet.

`ui.empty_state` · Category: [Feedback](https://albakore.github.io/pyzed/library/#feedback) · [Full reference →](https://albakore.github.io/pyzed/reference/ui/#empty_state)

**Code:**

```python
ui.empty_state("No results", "Try a different search.", icon="search",
               actions=[ui.button("Clear filters", on_clear, size="sm")])
```

## When to use

- For an empty list, a search with no results, or a panel before the first file is opened.
- Offer the next step as an action (Create, Clear filters, Open folder).

## Usage

```python
from pyzed import ui

ui.empty_state("No results", "Try a different search.", icon="search",
               actions=[ui.button("Clear filters", on_clear, size="sm")])
```

## Variants

:::note[About these captures]
Each capture is recorded by pyzed itself, off-screen at 2x, in One Dark or One Light to match this site's theme, and cropped to the component so it shows at its real size. The pointer hovers, presses or types into it; a component that does not react to the pointer cycles through a few themes. With reduced motion you see the first frame. Open **Code** under a capture to see the snippet that draws it; free names such as `on_save` stand for your own callbacks.
:::

### Content

```python
ui.empty_state("No notifications")
```

```python
ui.empty_state("No results", "Try a different search.", icon="search")
```

```python
ui.empty_state("No projects yet", "Create one to get started.", icon="folder-plus",
               actions=[ui.button("New project", on_new, variant="solid", size="sm")])
```

### States and events

```python
ui.empty_state("No results", "Try another search", icon="search", size="sm", height="shrink")
```

```python
ui.empty_state("No projects", "Create one to start", icon="folder", size="lg", height=220)
```

## Events

Empty state has no events of its own: it shows what you give it. Like every widget it also has the **18 common events** (`click`, `double_click`, `right_click`, `mouse_enter`, `drag`, `key_down`, `resize`…), attached with `.on(...)`: see [Events](https://albakore.github.io/pyzed/guides/events/) and [Events of every component](https://albakore.github.io/pyzed/library/events/).

## Properties and API

### `ui.empty_state`

```python
empty_state(
    title,
    description=None,
    *,
    icon='inbox',
    actions=(),
    size='md',
    height='fill',
    theme=None,
)
```

A centered placeholder for empty lists, searches with no results, etc.

| Property | Default | Description |
| --- | --- | --- |
| `title` | *required* | Title. |
| `description` | `None` | Secondary text. |
| `icon` | `"inbox"` | Name of a Lucide icon (`pyzed icons` lists them). |
| `actions` | `()` | Extra widgets (usually buttons) shown as actions. |
| `size` | `"md"` | `"sm"`, `"md"` or `"lg"`. |
| `height` | `"fill"` | `"fill"` (default), pixels or `"shrink"`. |
| `theme` | `None` | Theme to use instead of the current one (`pyzed.theme.current()`). |

[Full reference →](https://albakore.github.io/pyzed/reference/ui/#empty_state)

## Related

- [Callout](https://albakore.github.io/pyzed/library/callout/): An inline notice with a title, text and actions.
- [Keybinding hint](https://albakore.github.io/pyzed/library/keybinding-hint/): A muted “Open file Ctrl P” hint.
- [Card](https://albakore.github.io/pyzed/library/card/): A bordered surface with an optional title and actions.