Error State

import {
  ERROR_KIND_ICONS,
  ERROR_STATE_MESSAGES,

When to use it#

Use an error state in the place where content should have been, when loading it failed: a table that could not load, a chart, a whole page. It says what went wrong in plain words and, when trying again could help, gives a button to do so.

It is for a failed load. For a problem with something the person typed, use a Field error. For a message about the data that is still on screen, use an Alert. When the load worked but there is nothing to show, use Empty.

You will rarely build one by hand. Async Content picks the right words for the kind of error and draws this component for you. Use the parts on their own when you want a custom layout.

Import#

Copyimport {
  ErrorState,
  ErrorStateMedia,
  ErrorStateHeader,
  ErrorStateTitle,
  ErrorStateDescription,
  ErrorStateActions,
  ErrorStateRetry,
  ErrorStateDetails,
} from "@hel/ui/error-state"

Anatomy#

An error state is built like Empty, and has the same size.

• ErrorState is the wrapper. It is announced to screen readers when it appears. Set announce={false} when it is on the page from the start, so it does not interrupt.
• ErrorStateMedia is the icon tile, tinted for an error. tone="neutral" makes it the plain tile, for a state that is not really a failure, such as being offline.
• ErrorStateHeader holds the ErrorStateTitle and the ErrorStateDescription.
• ErrorStateActions holds the buttons. ErrorStateRetry is the "Try again" button.
• ErrorStateDetails is a folded section for support, such as a request id or an error code.

Kinds of errors#

Not every failure deserves the same words. The library sorts an error into one of five kinds from its status, and each has its own icon and text.

Retrying is only offered where asking again can change the answer. Asking again for something you may not see, or that is gone, gives the same answer.

ERROR_KIND_ICONS and errorKindText give you the icon and the words of a kind, as the example does. describeError and useErrorDescription turn a real error into its kind, request id and wording. An app can change them all in one place through errors.describe in its config.

import {
  ERROR_KIND_ICONS,
  ERROR_STATE_MESSAGES,

Retrying#

ErrorStateRetry takes pending, which makes it spin and blocks a second press. If the retry fails again, say so, and after a couple of failures give people another way out, such as a link to support. This example fails every time, so you can see all three stages.

import * as React from "react"

import { Button } from "@hel/ui/button"

Props#

ErrorState#

ErrorStateMedia#

ErrorStateRetry#

It also takes the props of a Button.