Hex UIv1

Empty

A zero-state surface for lists, dashboards, and search results with no content. Explains why the slot is empty + provides a call-to-action.

List zero-state

No invoices yet

When you bill a customer, their invoice will show up here. You can export, void, or duplicate any invoice from this list.

Search zero-state

No results for “kubernetes”

Try a broader query or clear active filters.

Onboarding hero

Welcome to Hex UI

Compose accessible interfaces from a tokenized component library. Start from a blank workspace or pull in a starter template.

Installation

pnpm
pnpm dlx @hex-core/cli add empty

Search zero-state

Search returned zero results — show the query + suggest a reset

tsx
<Empty
  icon={<SearchIcon />}
  title="No results found"
  description={`No items match "${query}". Try a different search.`}
  action={<Button variant="secondary" onClick={onReset}>Clear search</Button>}
  size="sm"
/>

Onboarding

Full-page first-run state

tsx
<Empty
  icon={<SparklesIcon />}
  title="Welcome to your dashboard"
  description="Create your first project to get started."
  action={<Button size="lg">Create project</Button>}
  size="lg"
  titleAs="h1"
/>

Variant values

sizeVertical density of the empty-state surface.
ValueDescription
sm
Compact — fits inside a card / panel.
defaultdefault
Standard — for table / list / dashboard widget empty states.
lg
Large — for full-page empty states (no items at all yet).

API Reference

PropTypeDefaultDescription
icon
ReactNode—Icon (typically an <svg>) rendered in a circular muted container above the title.
titlerequired
ReactNode—Heading copy. Becomes the region's accessible name via aria-labelledby.
description
ReactNode—Supporting copy that explains why the slot is empty + what to do next.
action
ReactNode—Call-to-action — typically a <Button> that creates the missing record.
titleAs
"h2" | "h3" | "h4" | "h5" | "h6" | "p"h3Heading level for the title. Pick to match surrounding heading hierarchy.
size
"sm" | "default" | "lg"defaultVisual scale.

AI Guidance

When to use

Use for lists, search results, or dashboards where the request returned successfully but there's nothing to show. Explain why and what to do — the title names the absence, the description sets context, the action gives a way out.

When not to use

Don't use while data is still loading (use Loading). Don't use when something failed (use ErrorState). Don't use for inline form-field 'no options' messages (use Combobox's empty slot or Form's helper text).

Common mistakes

  • Using Empty without an action — leaves the user stuck
  • Long descriptions — keep to one sentence; this is a state surface, not documentation
  • Forgetting titleAs when the page already has an h2 above (heading hierarchy break)

Accessibility

Wrapped in a region landmark labeled by the title (aria-labelledby + auto-generated id). Icon is decorative (aria-hidden). Pair the action with a Button that has a visible label.

Token budget: 350

Verified against @hex-core/components@1.9.0

Edit this page on GitHub