# ErrorState

A page that could not be shown.

- Group: Feedback
- Import: `import { ErrorState } from '@misoto22/folio'`
- Page: https://ui.misoto22.com/components/error-state/
- Related: empty-state, alert

## Anatomy

- **Screen** (required) — A section at least one viewport tall, painting its own --paper ground and holding 96px of clearance for a header. It is a page, not a block.
- **Code** (required) — code at the top of the type ladder, aria-hidden. The largest thing on the screen and the one thing a screen reader is never told.
- **Heading** (required) — heading through Heading at --fs-heading, and the first thing said aloud. level defaults to 1 because this replaces the page; the size is fixed, so an error state demoted to an h2 is the same size it was.
- **Message** (required) — message at --measure-record, which is where the explanation of what happened goes.
- **Action** (required) — The way back. Required rather than optional, and the only focusable thing on the screen.

## Best practices

### Do

- Render it instead of the page, not inside it. It is a full viewport with its own ground and its own top clearance, so nested in a layout that already has a header it adds a second screen of blank below the fold.
- Announce it or move focus into it on a client-side failure. There is no role and no live region here, so a route that swaps the whole screen for this one changes everything a sighted reader can see and says nothing at all.
- Point action at a real destination rather than at history. A reader often arrives at an error page cold or from a link, so going back returns them to the page that just failed, or to nothing.

### Don’t

- Do not leave level at 1 inside an app shell that already has an h1. Two h1s on one document leave a heading list that no longer says which one is the page — pass level={2} for a state rendered into a shell rather than instead of one.
- Do not put a request id, a trace or a sentence into code. It is set at --fs-title with leading-none and it is aria-hidden, so anything long becomes the biggest object on the page and is simultaneously invisible to the reader most likely to have to quote it.
- Do not use it when one panel failed and the rest of the page still works. Replacing the whole screen throws away the navigation the reader needed to get out; an Alert inside the panel keeps both the error and the way past it.

## Accessibility

- The big status code is aria-hidden; the heading immediately after says the same thing in words.

## ERROR_ACTION_CLASS

Re-export of `'text-sm text-(--ink) underline decoration-(--rule-2) underline-offset-4 transition-colors duration-(--duration-fast) hover:decoration-(--ink)'`.

The recovery affordance's look, exported so every error page offers the same one rather than each inventing a link style.

## ErrorState

A page that could not be shown. The code is set at the top of the type ladder and marked `aria-hidden` — read aloud, "404" before the sentence explaining it is noise, and the heading immediately after says the same thing in words.

### Props

- `code` (required) — `ReactNode`. The status, set large — "404", "500". Decorative; the heading carries the meaning.
- `heading` (required) — `ReactNode`.
- `message` (required) — `ReactNode`.
- `action` (required) — `ReactNode`. The way back. Render it with ERROR_ACTION_CLASS.
- `level` — `HeadingLevel` default `1`. The heading level `heading` opens, in the document the error state lands in. Defaults to `1`, and that is not a compromise: this component replaces the page rather than sitting inside one — its own ground, its own viewport, its own top clearance — so the page's single `h1` is the one it renders. Kept as the default, existing call sites render exactly the markup they did. The prop exists because the level was previously fixed, and the one piece of advice this component's documentation gives about headings — do not put it inside a shell that already has an `h1` — was advice a caller had no way to take. Now they do: inside a shell that owns the page heading, pass `2`. The size does not follow the level. `heading` renders at `--fs-heading` at every level; a failure demoted in the outline is the same failure.

Also accepts: `HTMLAttributes<HTMLElement>`.

## Example — not found

```tsx
import { ERROR_ACTION_CLASS, ErrorState } from '@misoto22/folio'

<ErrorState
  className="min-h-0 pt-0"
  level={2}
  code="404"
  heading="Page not found"
  message="The page you're looking for has moved, or never existed."
  action={<a href="/" className={ERROR_ACTION_CLASS}>Back home</a>}
/>
```

## Example — a way back

```tsx
import { ERROR_ACTION_CLASS, ErrorState } from '@misoto22/folio'

<ErrorState
  className="min-h-0 pt-0"
  level={2}
  code="500"
  heading="Something went wrong at our end"
  message="The request reached us and failed while it was being handled. Nothing you sent was lost."
  action={
    <div className="flex flex-wrap items-center gap-6">
      <a href="/" className={ERROR_ACTION_CLASS}>Back to the dashboard</a>
      <a href="/status" className={ERROR_ACTION_CLASS}>Service status</a>
    </div>
  }
/>
```

## Example — the trace id

```tsx
import { Code, ERROR_ACTION_CLASS, ErrorState } from '@misoto22/folio'

<ErrorState
  className="min-h-0 pt-0"
  level={2}
  code="500"
  heading="We could not load this deploy"
  message={
    <>
      The build service timed out. Quote <Code>req_8f31c0</Code> if you report it — it
      identifies this request.
    </>
  }
  action={<a href="/support" className={ERROR_ACTION_CLASS}>Contact support</a>}
/>
```