# EmptyState

- Page: https://jiguang132.com/resources/astryx/docs/empty-state
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

EmptyState shows a placeholder when a content area has no data. Use it for empty lists, zero search results, first-time setups, or cleared inboxes. Always include a title and a next step so the user is not stuck.

## Installation

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

Requires React 19+, base CSS and a Theme provider. See [Setup](/resources/astryx/docs/getting-started).

## Empty State

EmptyState shows a placeholder when a content area has no data. Use it for empty lists, zero search results, first-time setups, or cleared inboxes. Always include a title and a next step so the user is not stuck.

| Prop | Type | Default | Description |
|---|---|---|---|
| title * | string |  | Primary message rendered as an <h3> heading inside the empty state. |
| description | string |  | Optional secondary text providing additional context below the title. |
| icon | ReactNode |  | Optional icon or illustration displayed above the title; rendered as decorative (aria-hidden="true"). |
| actions | ReactNode |  | Optional action buttons displayed below the description, laid out horizontally by default and stacked vertically when isCompact is true. |
| headingLevel | 1 \| 2 \| 3 \| 4 \| 5 \| 6 | 3 | Controls only the rendered HTML heading tag (h1-h6) so the title fits the document outline. This is a semantic change for accessibility and does not change the visual size of the title, which stays fixed regardless of level. |
| isCompact | boolean | false | Enables the compact variant with reduced spacing for constrained content areas. |
| xstyle | StyleXStyles |  | StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}. |

### Usage guidance

- Include a clear title and a call-to-action button so users know how to proceed.
- Use an illustration or icon that reinforces the context of the empty state.
- Use the compact variant inside cards or sidebars where space is limited.
- Avoid: Leave an empty state without guidance; always explain what happened and what the user can do next.
- Avoid: Use a generic message like "No data"; be specific about what is empty and why.
- Avoid: Use an EmptyState for error messages that require immediate action; use a Banner instead.

### Theming API

```json
{
  "targets": [
    {
      "className": "astryx-empty-state",
      "visualProps": [
        "variant"
      ]
    },
    {
      "className": "astryx-empty-state-title",
      "visualProps": [
        "variant"
      ]
    },
    {
      "className": "astryx-empty-state-description",
      "visualProps": [
        "variant"
      ]
    }
  ]
}
```

### Anatomy

- **Icon**: A visual cue above the title that reinforces the context, like a search icon for no results.
- **Title**: Primary message explaining what is empty: "No projects yet" not "No data".
- **Description**: Additional context explaining why it is empty or what the user can do.
- **Actions**: One or two buttons guiding the user to a next step, like "Create project" or "Clear filters".


## Examples

- Empty State: A no-results empty state with an icon, descriptive message, and a call-to-action button.
- EmptyState — Actions: Full empty state with icon, message, and action buttons. Use when a search returns no results, a filter clears all items, or a list has been emptied. The buttons give the user a way forward: go back, clear filters, or try a different query.
- EmptyState — Compact: Smaller empty state with reduced spacing for constrained areas. Use inside sidebar panels, card widgets, or notification drawers where a full-size empty state would overwhelm the layout.
- EmptyState — Container: Empty state wrapped in a Card for first-time setup or onboarding. Use when the user has not created any items yet, like a project list, team roster, or dashboard widget that will fill with data once they take action.

## Complete example dependencies

Some examples import optional icons. The per-example install command in the examples list identifies exactly what that example needs. For all examples on this page:

```bash
npm install @heroicons/react@2.2.0
```

---

Index of all JGuang resources: https://jiguang132.com/llms.txt