Empty & error states

5 min · Pattern

Empty and error states tell users what happened and what to do next. Compose them with Column, Icon, Heading, Text, and Button — not generic placeholder divs.

What this pattern covers

Every data-driven UI needs three non-happy paths:

Empty — query succeeded but returned zero results
Error — fetch failed or action was rejected
No access — user lacks permission to view content

These are different from loading states (skeletons and spinners). Show empty/error only after the request resolves.

Empty state anatomy

A good empty state has four parts:

Icon or illustration (muted, not decorative)
Heading — what is empty
Text — why it might be empty or what to do
Primary action Button (optional secondary)

<Column fillWidth center padding="48" gap="16" maxWidth="xs">
  <Icon name="inbox" size="l" onBackground="neutral-weak" />
  <Heading as="h3" variant="heading-strong-s" align="center">
    No projects yet
  </Heading>
  <Text variant="body-default-s" onBackground="neutral-weak" align="center">
    Create your first project to start tracking work.
  </Text>
  <Button arrowIcon>Create project</Button>
</Column>

Center the block inside its parent with center on Column. Use maxWidth="xs" so text lines stay readable.

Inside a table or list panel

When a table has no rows, replace the Table with an empty state inside the same surface panel:

<Column background="surface" border="neutral-alpha-weak" radius="l" padding="24" gap="24">
  <Row fillWidth horizontal="between" vertical="center">
    <Heading as="h2" variant="heading-strong-m">Projects</Heading>
    <Button size="s" prefixIcon="plus">New</Button>
  </Row>
  {/* if rows.length === 0 → empty state Column */}
  {/* else → Table */}
</Column>

Keep the panel header (title + action button) visible even when empty. Only the body swaps to the empty state.

Error state anatomy

Error states add a retry path and use danger-adjacent colors sparingly:

<Column fillWidth center padding="48" gap="16" maxWidth="xs">
  <Icon name="alertCircle" size="l" onBackground="danger-medium" />
  <Heading as="h3" variant="heading-strong-s" align="center">
    Couldn't load projects
  </Heading>
  <Text variant="body-default-s" onBackground="neutral-weak" align="center">
    Check your connection and try again.
  </Text>
  <Row gap="12">
    <Button onClick={retry}>Try again</Button>
    <Button variant="secondary">Contact support</Button>
  </Row>
</Column>

5 min · Pattern

Empty and error states tell users what happened and what to do next. Compose them with Column, Icon, Heading, Text, and Button — not generic placeholder divs.

What this pattern covers

Every data-driven UI needs three non-happy paths:

Empty — query succeeded but returned zero results
Error — fetch failed or action was rejected
No access — user lacks permission to view content

These are different from loading states (skeletons and spinners). Show empty/error only after the request resolves.

Empty state anatomy

A good empty state has four parts:

Icon or illustration (muted, not decorative)
Heading — what is empty
Text — why it might be empty or what to do
Primary action Button (optional secondary)

<Column fillWidth center padding="48" gap="16" maxWidth="xs">
  <Icon name="inbox" size="l" onBackground="neutral-weak" />
  <Heading as="h3" variant="heading-strong-s" align="center">
    No projects yet
  </Heading>
  <Text variant="body-default-s" onBackground="neutral-weak" align="center">
    Create your first project to start tracking work.
  </Text>
  <Button arrowIcon>Create project</Button>
</Column>

Center the block inside its parent with center on Column. Use maxWidth="xs" so text lines stay readable.

Inside a table or list panel

When a table has no rows, replace the Table with an empty state inside the same surface panel:

<Column background="surface" border="neutral-alpha-weak" radius="l" padding="24" gap="24">
  <Row fillWidth horizontal="between" vertical="center">
    <Heading as="h2" variant="heading-strong-m">Projects</Heading>
    <Button size="s" prefixIcon="plus">New</Button>
  </Row>
  {/* if rows.length === 0 → empty state Column */}
  {/* else → Table */}
</Column>

Keep the panel header (title + action button) visible even when empty. Only the body swaps to the empty state.

Error state anatomy

Error states add a retry path and use danger-adjacent colors sparingly:

<Column fillWidth center padding="48" gap="16" maxWidth="xs">
  <Icon name="alertCircle" size="l" onBackground="danger-medium" />
  <Heading as="h3" variant="heading-strong-s" align="center">
    Couldn't load projects
  </Heading>
  <Text variant="body-default-s" onBackground="neutral-weak" align="center">
    Check your connection and try again.
  </Text>
  <Row gap="12">
    <Button onClick={retry}>Try again</Button>
    <Button variant="secondary">Contact support</Button>
  </Row>
</Column>

Scope	When	Layout
Inline	Single widget failed (chart, sidebar widget)	Compact Column inside the widget's bounds
Section	Main content area failed	Centered empty state in content Column
Full page	Route-level failure	Column with `minHeight` filling the viewport

<Column center padding="24" gap="8">
  <Text variant="body-default-s" onBackground="neutral-weak" align="center">
    Failed to load chart data.
  </Text>
  <Button size="s" variant="secondary">Retry</Button>
</Column>

Situation	Heading	Action
No data yet	"No projects yet"	Create / import Button
Filters returned zero	"No matching projects"	Clear filters Button (secondary)
Search returned zero	"No results for '{query}'"	Adjust search Text, no Button needed

<Column center gap="16" padding="48">
  <Heading as="h3" variant="heading-strong-s">No matching projects</Heading>
  <Text variant="body-default-s" onBackground="neutral-weak">
    Try adjusting your filters or search terms.
  </Text>
  <Button variant="secondary" onClick={clearFilters}>Clear filters</Button>
</Column>

Failure type	Surface
Page/section fetch failed	Inline or section error state
Form submit rejected	Toast + keep form visible with field errors
Background sync failed	Toast notification

✅ Once UI way	❌ Common mistake
Icon + Heading + Text + Button stack	Plain "No data" string centered in a div
Empty state inside existing panel	Remove panel chrome when empty
Retry Button on errors	Error with no recovery path
"Clear filters" for filtered empty	Same copy as truly-empty state
Toast for transient action failures	Full-page error for a failed save

What this pattern covers

Empty state anatomy

Inside a table or list panel

Error state anatomy

What this pattern covers

Empty state anatomy

Inside a table or list panel

Error state anatomy

Inline error vs full-page error

Filtered empty vs truly empty

Toast vs inline error

Agent checklist

Write this / not this

Check yourself

Empty & error states

What this pattern covers

Empty state anatomy

Inside a table or list panel

Error state anatomy

What this pattern covers

Empty state anatomy

Inside a table or list panel

Error state anatomy

Inline error vs full-page error

Filtered empty vs truly empty

Toast vs inline error

Agent checklist

Write this / not this

Check yourself

Related