Skip to content

Error State

A centered, full-page (or full-section) message shown when something has gone wrong — a failed request, a 500, a lost connection. A status icon, a title, an optional description, and a single recovery button at the bottom (the default button, not a link). It is not dismissable: an error state replaces the content it covers, so there is nothing to close.

These are two different concepts (per Nielsen Norman Group):

  • Error state (this component) — something failed. The system couldn’t do what was asked (500, timeout, no connection). The user needs to recover (retry, reload, go back).
  • Empty state — nothing has gone wrong; there’s simply no content yet (first run, no results, a cleared list). The user needs to get started.

Use ErrorState only for failures. A 404 is a borderline case — it’s an error (the route doesn’t resolve), so it fits here: keep the layout and just change the icon and copy (see the second demo, which swaps a custom glyph through the icon snippet).

<script>
import ErrorState from "@invisible-ui/svelte/ErrorState.svelte";
</script>
PropTypeDefaultDescription
title *string—The headline — what went wrong, in plain language.
descriptionstring | undefinedundefinedOptional secondary line — detail or next step.
status"info" | "success" | "warning" | "danger" | "neutral""danger"Feedback status driving the default icon's color and glyph.
headingLevel1 | 2 | 3 | 4 | 5 | 62Heading level for the title, so it fits the surrounding document outline.
actionLabelstring | undefinedundefinedRecovery button label (e.g. "Try again"). Omit to render no button.
onAction(() => void) | undefinedundefinedCalled when the recovery button is pressed.
actions{ label: string; onAction?: () => void; variant?: ButtonVariant; href?: string; target?: string; }[] | Snippet[]Configurable action group. An entry with href renders a Link (a direct pathway, e.g. "Learn more" documentation); the others render Buttons: the first gets the default variant and the rest ghost, unless an entry sets its own variant. Takes precedence over actionLabel. A snippet in its place replaces the whole area.
size"md" | "sm""md"Density: md for full pages and sections, sm inside cards, panels and table areas.
iconSnippet | undefinedundefinedGlyph or illustration in place of the default FeedbackIcon.

Every href is rendered as given: pass only URLs you trust or have sanitized. See Security.

It composes existing primitives — no new behavior:

  • Icon: a FeedbackIcon (danger by default). Override it with a different glyph or a bespoke illustration via the icon snippet.
  • Actions: Buttons and Links. One recovery button comes from actionLabel/onAction; a configurable group comes from the actions prop: an array of { label, onAction, variant, href } where the first action renders in the default variant and the rest in ghost (unless an entry sets its own variant), and an entry with href renders as a link (e.g. “Contact support”). For anything else, an actions snippet replaces the whole area. Omit all three for no actions.
  • Density: size="sm" compacts padding, icon and title for use inside cards, panels and table areas; the default md fits pages and sections.
  • The region is a role="alert", so when it appears it is announced.
  • Meaning never rests on color alone — the title (and the icon glyph) carry it (WCAG 1.4.1).
  • headingLevel (default 2) sets the title’s heading level so it fits the surrounding document outline (use 1 on a dedicated error page).
<ErrorState
title="Couldn't connect to the server"
description="Check your connection and try again."
actionLabel="Try again"
onAction={() => retry()}
/>

Elements keeps custom icons, supporting content, and custom actions in light DOM. The generated recovery action emits a bubbling action event:

<ds-error-state
title="Couldn't connect to the server"
description="Check your connection and try again."
action-label="Try again"
></ds-error-state>
<script type="module">
document.querySelector("ds-error-state").addEventListener("action", retry);
</script>

Use slot="icon" to replace the fallback icon and slot="actions" to compose multiple buttons or links. Unslotted children add supporting content.

In React, icon, actions and children take markup, and actions also takes entries:

<ErrorState
title="Couldn't connect to the server"
description="Check your connection and try again."
actionLabel="Try again"
onAction={retry}
/>

Themeable via --ds-error-state-* (gap, padding, max-width, icon/title size).