EmptyState

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

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.

Empty State

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

{
  "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:

npm install @heroicons/react@2.2.0