EmptyState

Empty-content message with an icon and optional action.

Overview

  • Explain why content is missing and provide an action when the user can resolve the condition.

Aliases

blank slate

When to use

  • Use EmptyState when no content is available or no results match a filter.
  • Provide an action when users can resolve the empty condition.

When not to use

  • Use inline text when the empty condition needs no separate action or illustration.
  • Do not overload it with too many competing actions.

Structural parts

blank-slate shell

root

Carries spacing, tone, and structural rhythm.

optional visual cue

icon

Optional symbol or lightweight illustration cue.

primary heading

title

Short statement of the missing or empty condition.

supporting guidance

description

Clarifies why the space is empty or what to do next.

optional call-to-action area

actions

Supports the primary next step.

Public interface

Props
NameTypeDefaultDescription
tone'neutral' | 'brand' | 'warning''neutral'Chooses the blank-slate tone.
size'sm' | 'md' | 'lg''md'Sets the component size.
titlestring'No items'Primary empty-state heading.
descriptionstring''Optional explanation or guidance.
themeThemeContract—Sets the theme used to resolve component styles.
Slots
NameDescription
iconOptional icon or symbol.
defaultOptional richer body content.
actionsOptional actions area.

Variants, sizes, and states

Variants

  • neutral: Neutral empty-state styling.
  • brand: Brand-colored empty-state styling.
  • warning: Warning styling for an empty condition that needs attention.

Sizes

  • sm: Compact inline empty state.
  • md: Default empty state.
  • lg: More spacious blank-slate surface for isolated pages.

States

  • rest: Static guidance surface.

Accessibility

Semantics

  • EmptyState is a structural guidance surface and inherits semantics from its content.

Keyboard

  • Only embedded actions participate in keyboard flow.

Screen readers

  • Explain the empty condition in text; do not rely on the icon.

Checklist

  • Verify that the control has an accessible name.
  • Verify that keyboard focus is visible in every state and size.
  • Identify disabled, selected, and error states with text or symbols as well as color.

Tokens and CSS variables

root

--dk-empty-bg
#f2f5fb
--dk-empty-fg
#16181c
--dk-empty-border
#95989d
--dk-empty-radius
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-empty-padding
clamp(2.37rem, 2.1728rem + 0.878vw, 2.963rem)
--dk-empty-gap
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)

icon

--dk-empty-icon-size
2rem
--dk-empty-icon-color
#2072e4
--dk-empty-icon-shell-bg
#e5e8ed

title

--dk-empty-title-color
#16181c
--dk-empty-title-size
clamp(1.778rem, 1.6296rem + 0.658vw, 2.222rem)
--dk-empty-title-weight
680

description

--dk-empty-description-color
#16181c
--dk-empty-description-size
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)

actions

--dk-empty-actions-gap
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)

Examples

Starter

First-use surface

An empty-state message with an icon.

<EmptyState title="No items yet" description="Create your first item to get started."><svelte:fragment slot="icon">◎</svelte:fragment></EmptyState>

Common patterns

Onboarding message

Use the brand tone for the primary empty state.

<EmptyState tone="brand" title="Start your workspace" description="Invite the first team members to begin." />

Edge cases

No results after filtering

Warning tone works when the absence may be unexpected or corrective.

<EmptyState tone="warning" title="No matching results" description="Adjust the filters and try again." />

Mathematical fixtures

Calculated fixtures; browser evidence is not collected. Layout estimates use declared text behavior and maximum token values.

neutral-md

pass

size=md|tone=neutral

  • Evidence: mathematical
  • Coverage: complete (2 / 2 declared kinds evaluated)
  • Declared: contrast, layout
  • Evaluated: contrast, layout
  • Contrast: 98.5 Lc, 98.5 Lc
  • Layout: root · single-line 0 px single-line estimate; 0 px minimum width
    280 px: pass 360 px: pass 480 px: pass

brand-md

pass

size=md|tone=brand

  • Evidence: mathematical
  • Coverage: complete (2 / 2 declared kinds evaluated)
  • Declared: contrast, layout
  • Evaluated: contrast, layout
  • Contrast: 98.5 Lc, 98.5 Lc
  • Layout: root · single-line 0 px single-line estimate; 0 px minimum width
    280 px: pass 360 px: pass 480 px: pass

danger-lg

pass

size=lg|tone=danger

  • Evidence: mathematical
  • Coverage: complete (2 / 2 declared kinds evaluated)
  • Declared: contrast, layout
  • Evaluated: contrast, layout
  • Contrast: 98.5 Lc, 98.5 Lc
  • Layout: root · single-line 0 px single-line estimate; 0 px minimum width
    280 px: pass 360 px: pass 480 px: pass