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.
Planning failed
It stopped while planning the days in Lisbon. Your trip details are saved. Try again or change them first.
Installation
npx shadcn@latest add @flyingsalmon/error-stateUsage
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.
Travellers did not load
The list of people on this trip could not be fetched.
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.
The places did not load
The planner did not answer. Nothing was changed.
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
- DoSay 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.
- DoMake 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’tAdd 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’tShrink 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
| Key | Description |
|---|---|
| Tab | Reaches 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| size | EmptyStateSize | EmptyStateSize.Default | Default for a page, Small for a block inside a card. |