EmptyState
Centered placeholder block for 'no data yet' and 'no results' states, built from an optional icon, a heading, supporting text, and an optional call-to-action.
Playground
No items yet
Get started by adding the first item.
<EmptyState
description="Get started by adding the first item."
title="No items yet"
>
{#snippet cta()}
<Button intent="primary">
<PlusIcon />
Add item
</Button>
{/snippet}
</EmptyState>01 Examples
With icon and CTA
No apartments yet
Get started by adding the first apartment.
<EmptyState
icon={BuildingIcon}
title="No apartments yet"
description="Get started by adding the first apartment."
>
{#snippet cta()}
<Button intent="primary"><PlusIcon />Add apartment</Button>
{/snippet}
</EmptyState>Compact — for inline empty rows
No matches
Try adjusting your filter.
<EmptyState
density="compact"
icon={FunnelIcon}
title="No matches"
description="Try adjusting your filter."
/>Embedded inside a Card
Recent activity
Nothing here yet
New events will show up as they happen.
<Card variant="outlined" padding="md">
<h3 class="text-text-primary mb-3 text-sm font-semibold">Recent activity</h3>
<EmptyState
density="compact"
headingLevel={4}
icon={SearchIcon}
title="Nothing here yet"
description="New events will show up as they happen."
/>
</Card>02 Customization
Pair with any icon from @urbicon-ui/blocks. Its round container is filled with
the neutral surface tokens, not the accent: an empty state is not the call to action —
the button under it is. On the page ground that fill reads as a faint wash, and inside an
elevated container — a Card, a Popover — it disappears,
because surface-subtle and surface-elevated are the same colour. Override
any slot with slotClasses, unstyled, or a preset.
For a fill that always reads, or for the accent back, pass slotClasses={{ iconWrapper: 'bg-primary-subtle text-primary-text' }}, or set it once for every empty state through the provider's defaults.EmptyState.slotClasses.iconWrapper.
Use the cta snippet for the primary action; render your own markup via children for richer empty states (e.g. tutorials, illustrations).
03 Accessibility
The icon is decorative
The decorative icon is hidden from screen readers via its built-in aria-hidden.
The title takes the rank you give it
The title renders as an <h3> by default, the rank for an empty state
inside a titled section or card. Elsewhere, set headingLevel to the rank that
continues the page's outline: 2 directly under the page's <h1>. The title is styled by class, not by tag, so the rank changes none
of its own styling.
04 API Reference
12 propsProp | Type | Default | Description | |
|---|---|---|---|---|
title required | string | — | Heading line. | |
children | Snippet | — | Optional richer content rendered below the description. | |
class | string | — | Extra classes merged onto the wrapper. | |
cta | Snippet | — | Action buttons rendered below the description. | |
density | compactdefault | 'default' | Visual density. compact is suitable for inline empty rows in tables
or cards; default for full-page empty states. | |
description | string | — | Supporting paragraph below the title. | |
headingLevel | 1234 +2 more | 3 | Heading level of the title, clamped to 1..6. h3 fits an empty state
inside a titled section or card; pass the rank that continues the
embedding page's outline — 2 directly under the page's h1. The title
is styled by class, not by tag, so the level changes none of the component's own styling. | |
icon | Component<IconProps> | — | Icon component rendered above the title. Pass any icon from
@urbicon-ui/blocks (or a compatible stroke icon). Its round container is
filled bg-surface-subtle text-text-tertiary — an empty state is not the
call to action, cta is. That fill reads as a faint wash on the page
ground and as nothing at all inside an elevated container (Card, Popover),
where surface-subtle and surface-elevated resolve to the same colour.
For a fill that always reads, or for the accent back, pass
slotClasses={{ iconWrapper: 'bg-primary-subtle text-primary-text' }}. | |
preset | string | — | Apply a named preset registered via <BlocksProvider presets={{ EmptyState: {...} }}>.
Prefer this over class overrides when the same look should be reused
across the project. | |
slotClasses | Partial<Record<EmptyStateSlots, string>> | — | Per-slot class overrides. Slots: base | iconWrapper | title | description | children | cta | |
unstyled | boolean | — | Remove all default tv classes. | |
...HTMLAttributes<HTMLDivElement> inherited | HTMLAttributes | — | HTML attributes (excluding: 'children' | 'title') |
05 Types
Name | Kind | Category | Used by | Description | |
|---|---|---|---|---|---|
EmptyStateProps | interface | props | — | — | |
IconProps | interface | props | — | — |
06 Installation
Import
import { EmptyState, BuildingIcon } from '@urbicon-ui/blocks';