Empty State

Empty State Variants

Layout Variants

Empty State Properties

Important: The title should be concise (5–8 words) and action-oriented when possible. "No projects yet" is better than "This section is empty" because it implies the user can create one. The description should provide context and guidance without being verbose.

Design Token Mappings

Illustrations should use design tokens for fill colors so they adapt to light/dark mode. Avoid hardcoded colors in SVGs — use currentColor or CSS custom properties.

Empty State States

Transition note: When an empty state transitions to populated content (e.g., user creates their first item), avoid a jarring jump. Fade the empty state out and the first item in. A 200ms opacity transition is sufficient.

Accessibility Requirements

Semantic Structure:

• Use heading elements (<h2> or <h3>, matching the page hierarchy) for the empty state title. Do not use <p> with bold styling — screen readers won't identify it as a heading.
• Illustrations should be decorative (aria-hidden="true", role="presentation"). They don't convey information that isn't also in the text.
• The container can use role="status" if the empty state appears dynamically (e.g., after filtering removes all results), triggering a polite screen reader announcement.

WCAG Compliance:

• SC 1.4.3 (Contrast – Minimum): Title text requires 4.5:1 contrast. Description text (often in muted colors) must also meet this threshold — verify with Contrast Checker. Muted gray (#999) on white (#fff) is only 2.85:1 and fails.
• SC 1.4.11 (Non-text Contrast): Illustration elements meaningful to understanding (rare, since they're decorative) need 3:1 contrast.
• SC 2.4.6 (Headings and Labels): The title should be descriptive — "No results found" is better than "Oops!" for screen reader users scanning headings.
• SC 2.4.7 (Focus Visible): The CTA button must have a visible focus indicator. This is inherited from your Button component.
• SC 1.3.1 (Info and Relationships): The heading level must reflect the document hierarchy. An empty state inside a section with an <h2> should use <h3>.

Dynamic Empty States: When an empty state appears after user action (clearing filters, deleting all items), announce the change to assistive technology. Use aria-live="polite" on the container or programmatically move focus to the empty state title.

Usage Guidelines

Do:

• Always include a primary call-to-action. An empty state without an action is a dead end.
• Match the tone to the context: welcoming for first-use, helpful for no-results, apologetic for errors.
• Use illustrations that are lightweight (SVG preferred) and adapt to dark mode via design tokens.
• Show the empty state in the same container where content would appear. Don't redirect to a separate page.
• For "no results" states, suggest helpful alternatives: "Try adjusting your filters", "Check your spelling", or show a clear-all-filters button.

Don't:

• Don't use generic messages like "Nothing here" without guidance on what to do next.
• Don't use heavy raster images (PNG/JPG) for illustrations — SVGs scale better and load faster.
• Don't hide the empty state behind a loading spinner indefinitely. If data fetch completes with zero results, show the empty state immediately.
• Don't blame the user. "No results for your search" is fine; "You searched wrong" is hostile.
• Don't overdesign the empty state to the point where it's more visually prominent than populated content. The goal is to guide users away from the empty state by encouraging content creation.
• Don't use the same illustration for every empty state. Context-specific illustrations (empty inbox vs. empty project list) significantly improve comprehension.

Material Design 3 does not define a formal "Empty State" component, but provides extensive guidance on "empty conditions" in its content design documentation. MUI developers typically compose empty states from Box, Typography, Button, and custom SVG illustrations. The Material guideline recommends using the product's brand illustration style and keeping messaging instructional rather than whimsical.

Ant Design provides an Empty component with description (text or ReactNode), image (defaults to a built-in SVG), imageStyle, and a children slot for action buttons. Ant offers two built-in illustrations: Empty.PRESENTED_IMAGE_DEFAULT (detailed) and Empty.PRESENTED_IMAGE_SIMPLE (minimal outline). The Empty.PRESENTED_IMAGE_SIMPLE variant is preferred for inline contexts like Select dropdowns. Ant also supports Empty.useEmpty() to globally configure the empty state across all Ant components.

Chakra UI does not include a dedicated Empty State component. Developers compose one using VStack, Heading, Text, Image, and Button. Community templates exist but there's no official primitive.

Radix UI and Headless UI do not provide Empty State components, as they are purely presentational with no interaction patterns requiring headless abstraction.

Atlassian Design System provides EmptyState with header, description, primaryAction, secondaryAction, tertiaryAction, imageUrl, imageWidth, imageHeight, and maxImageWidth. Atlassian's three-tier action hierarchy (primary button, secondary button, tertiary link) is a thoughtful pattern worth adopting. Their guidelines mandate that every empty state must have at least one action — no dead ends.

Polaris (Shopify) provides EmptyState with heading, image, action, secondaryAction, fullWidth, and children. Polaris includes built-in empty state illustrations matching Shopify's brand. Their documentation emphasizes tone: first-use states should be "encouraging", error states should be "reassuring", and no-results states should be "helpful".