EmptyState

EmptyState

<EmptyState
  icon={<InboxIcon />}
  title="Nothing here yet"
  description="Connect a project to start collecting events."
  actions={<Button>Connect a project</Button>}
/>

Install: @helixui/core

import { EmptyState } from '@helixui/core'

status: stable · since: 0.2.0

Tags: placeholder, no-data, cta

Anatomy

        [icon]
      Title
   short description
     [ Action ]

Layout

• display — block
• width — fill
• height — content
• intrinsicSize — centered, ~280px tall
• stackable — false
• fullBleed — false

Visual

A centered column with a large muted icon, a heading, a description, and an optional primary action button. Used inside an empty Card, empty list, or empty page.

Props

Name	Type	Default	Description
icon	ReactNode	—	Optional leading icon.
title	ReactNode	—	Headline.
description	ReactNode	—	Supporting text.
actions	ReactNode	—	Buttons or links to recover from the empty state.
size	'sm' | 'md'	md	Compact or full size.

Tokens used

color.bg.action.neutral.default, color.text.primary, color.text.secondary, color.text.muted, radius.full, space.2, space.3, space.6, space.12, font.family.sans, font.size.sm, font.size.md, font.size.lg, font.weight.semibold

Accessibility

Role: status

Notes

• The container uses role="status" so screen readers announce the empty state when it appears.
• Always include actions if there’s a path to recover (create the first item, retry, …).

Composes with

Component	Relation	Note
Card	parent	Often inside a Card to show “no data yet”.
Button	child	Primary CTA below the description.
Banner	sibling

Prompt examples

These are the AI prompt → JSX mappings used by the helixui prompt DSL and integrations like Cursor / Claude Code.

empty inbox

“no messages placeholder with a Compose button”

<EmptyState
  icon={<InboxIcon />}
  title="No messages"
  description="When someone writes you, it appears here."
  action={<Button>Compose</Button>}
/>

Related

• Banner