Feedback

EmptyState

Centered placeholder with optional icon, title, description, and call-to-action for views that have no data to render.

import { EmptyState } from '@lostgradient/cinder';
feedbackempty
01

Overview

Reference usage

Placeholder layout for zero-data views, with optional illustration, heading, and action.

Usage

svelte 
<script lang="ts">
  import { Button } from '@lostgradient/cinder';
  import { EmptyState } from '@lostgradient/cinder';
</script>

<EmptyState title="No results found" description="Try adjusting your filters or search query.">
  {#snippet action()}
    <Button variant="primary" label="Clear filters" />
  {/snippet}
</EmptyState>

Start-aligned — the content reads from the inline start instead of the centre, for a state that explains what to do rather than marking an absence:

svelte 
<script lang="ts">
  import { EmptyState } from '@lostgradient/cinder';
</script>

<EmptyState
  align="start"
  title="No provider is configured"
  description="Add a model provider to create an agent."
/>

Pick the kind that says why the view is empty. first-use is the default and shows the action snippet. filtered means a filter or search hid items that exist, so it offers a Clear filters button from onClearFilters. done means the work is finished, so it shows no action at all:

svelte 
<script lang="ts">
  import { EmptyState } from '@lostgradient/cinder';

  let query = $state('overdue');
</script>

<EmptyState
  kind="filtered"
  title="No runs match"
  description="Nothing matches the current filters. Clear them to see every run."
  onClearFilters={() => (query = '')}
/>

<EmptyState kind="done" title="Inbox zero" description="Every approval has been answered." />

Use size="compact" inside a tab or a panel, where the default page-region padding and disc are too large:

svelte 
<script lang="ts">
  import { EmptyState } from '@lostgradient/cinder';
</script>

<EmptyState size="compact" title="No comments yet" description="Replies appear here." />

The icon snippet renders inside a tinted disc: neutral for filtered, accented for first-use, and success-tinted for done. The description keeps a readable measure of about 42 characters however wide the region is, and the action row wraps with even spacing.

Live preview

Basic empty state

No results found

Try adjusting your filters or search query.

02

When to use

Use when
  • Communicating that a list, table, or workspace has no items yet and suggesting a next step.
  • Replacing a primary content region after a filter or search returns no results.
  • Confirming that all work is finished with the done kind, or that a filter hid every item with the filtered kind.
Avoid when
  • Indicating that data is still loading — use skeleton or spinner instead.
  • Reporting a transient error — use alert, banner, or toast-region.
03

Examples

Basic empty state

Title, description, and an action button.

Compact for tabs and panels

size="compact" tightens the padding, disc, and type for a tab or a panel.

First use, filtered, and done

Three reasons a view is empty: nothing yet, a filter hid everything, and all work finished.

With icon

An icon snippet above the title.

04

Props

Props for empty-state
Name
Type
Default
Description
title required text Primary heading text rendered as a heading element at the configured headingLevel.
description text Secondary descriptive text rendered as a paragraph below the title.
headingLevel 123456 3 Heading level for the title element.
align 'center' | 'start' 'center' Alignment of the content. 'center' centres the icon, text, and action in the region; 'start' aligns them to the inline start, for a state that reads as instructions rather than a placeholder.
kind 'first-use' | 'filtered' | 'done' 'first-use' Why the view is empty. 'first-use' shows the action snippet, 'filtered' adds a "Clear filters" button when onClearFilters is set, and 'done' shows no action at all, even when action is passed, because there is nothing left to do.
size 'default' | 'compact' 'default' Scale of the state. 'compact' tightens the padding, disc, and type so the state fits a tab or a panel rather than a whole page region.
onClearFilters () => void Called when the "Clear filters" button of a 'filtered' state is pressed. The button renders only when this is set.
clearFiltersLabel text 'Clear filters' Label of the "Clear filters" button.
icon snippet Icon rendered above the title, centred in a tinted disc. Decorative, so it is hidden from assistive technology.
action snippet Call-to-action content rendered below the description, after the "Clear filters" button when both exist.