Error State

ErrorState is the standard fallback for failed data fetches or unexpected errors. It uses role="alert" so screen readers announce it automatically. Pair it with TanStack Query’s isError state to replace a loading spinner or empty list with a recoverable error message.

Live demo

Usage

import { ErrorState } from "@beacon/design-system";

// Default title
<ErrorState
  description="Could not load invoices. Check your connection and try again."
  action={<button type="button" onClick={refetch}>Retry</button>}
/>

// Custom title
<ErrorState
  title="Failed to send notice"
  description="The certified mail service returned an error. The notice was not sent."
/>

With TanStack Query

const { data, isLoading, isError, refetch } = useQuery(invoiceListQuery);

if (isError) {
  return (
    <ErrorState
      description="Could not load invoices."
      action={<button type="button" onClick={() => refetch()}>Retry</button>}
    />
  );
}

Props

Prop	Type	Default	Description
title	ReactNode	"Something went wrong"	Error heading. Override for context-specific messages.
description	ReactNode	undefined	Details or recovery instructions.
action	ReactNode	undefined	Recovery action (a retry button, a “Go back” link).

Design tokens used

Token	Role
--ds-color-status-danger	Error title accent color.
--ds-color-content-default	Description text.
--ds-space-md	Internal spacing.

Accessibility

The root element renders with role="alert", which triggers a live region announcement. This means the error message is read aloud by screen readers as soon as it appears, without the user having to focus it. Do not wrap ErrorState in an additional aria-live region.

When to use

Any async data boundary that can fail: API calls, file uploads, third-party integrations. ErrorState should be the default catch for isError in every query hook used in the UI.