Skip to content
flyingsalmon

Error state

An empty state for content that failed to arrive: it says what happened and what the traveller can do about it, and is announced when it appears.

Installation

npx shadcn@latest add @flyingsalmon/error-state

Usage

import { Button } from '@/components/ui/button'
import {
  EmptyStateActions,
  EmptyStateDescription,
  EmptyStateTitle,
} from '@/components/ui/empty-state'
import { ErrorState } from '@/components/ui/error-state'

export function ErrorStateUsage({ onRetry }: { onRetry: () => void }) {
  return (
    <ErrorState>
      <EmptyStateTitle>The places did not load</EmptyStateTitle>
      <EmptyStateDescription>
        The planner did not answer. Nothing was changed.
      </EmptyStateDescription>
      <EmptyStateActions>
        <Button onClick={onRetry}>Try again</Button>
      </EmptyStateActions>
    </ErrorState>
  )
}

Examples

Small in a card

Small is for one region among others: an icon replaces the sticker and the type shrinks, so the card stays in proportion. Pass as on the title for an H3 inside a section.

Retry

Press Try again. The region shows a skeleton while it loads, then fails once more before it succeeds. The retry replaces the error where it stood, so the traveller never leaves the place they were looking.

Guidelines

When to use

  • When a region that was meant to fill could not: the places did not load, the trip failed to plan.
  • As the failed state of the affected item, with a retry where the traveller is already looking.

When not to use

  • Use Alert for a form’s error. It belongs to the acting surface, in the form’s result slot.
  • Use Notice for a result with no visible home, such as a dialog form that has closed.
  • Use Empty state when the region is legitimately empty and nothing went wrong.

Do and don’t

  • Do
    Say what happened and what was kept, then offer a retry and a way back to the input.The traveller needs to know nothing was lost before they will try again.
  • Do
    Make retry the filled action, and let it show its own loading while the block stays in place.The traveller sees the attempt running where they pressed.
  • Don’t
    Add red, an error icon, or an alert inside the block. A failure looks like an empty state with its own sticker and title.Plain words and a broken-thing sticker say something went wrong. Red on top turns a failure the traveller can recover from into an alarm.
  • Don’t
    Shrink a failed region to a banner. The block takes the place of the content that failed, at its size.The traveller looks for the content where it belongs, and finds the failure and its retry there.

Accessibility

KeyDescription
TabReaches the action buttons in order. Nothing else in the block takes focus.

The block is an alert labelled by its title, so it is announced when it appears, as when it replaces the content that failed, and a screen reader tells it apart from an empty state. The role cannot be changed. Everything else, from the heading level to the tab stops, is the empty state’s.

API

ErrorState

Replaces EmptyState as the root and takes its props except role. Every other part is an empty-state part: EmptyStateTitle, EmptyStateDescription, EmptyStateActions, and the sticker or icon.

PropTypeDefaultDescription
sizeEmptyStateSizeEmptyStateSize.DefaultDefault for a page, Small for a block inside a card.

  • Empty state

    The same block for a region that is legitimately empty.
  • Alert

    Where a form’s error appears.
  • Notice

    Where a result with no visible home appears.
  • Principles

    The feedback rule that ranks these homes.