Error State
Couldn't connect to the server
An unknown error occurred.
Page not found
The page you're looking for doesn't exist or was moved.
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.
Error state vs empty state
Section titled “Error state vs empty state”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).
Import
Section titled “Import”<script> import ErrorState from "@invisible-ui/svelte/ErrorState.svelte";</script><script setup> import { ErrorState } from "@invisible-ui/vue";</script>import { ErrorState } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-error-state></ds-error-state>| Prop | Type | Default | Description |
|---|---|---|---|
title * | string | — | The headline — what went wrong, in plain language. |
description | string | undefined | undefined | Optional secondary line — detail or next step. |
status | "info" | "success" | "warning" | "danger" | "neutral" | "danger" | Feedback status driving the default icon's color and glyph. |
headingLevel | 1 | 2 | 3 | 4 | 5 | 6 | 2 | Heading level for the title, so it fits the surrounding document outline. |
actionLabel | string | undefined | undefined | Recovery button label (e.g. "Try again"). Omit to render no button. |
onAction | (() => void) | undefined | undefined | Called 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. |
icon | Snippet | undefined | undefined | Glyph or illustration in place of the default FeedbackIcon. |
| Prop | Type | Default | Description |
|---|---|---|---|
title * | string | — | The headline: what went wrong, in plain language. |
description | string | undefined | Optional secondary line: detail or next step. |
status | FeedbackStatus | "danger" | Feedback status driving the default icon's color and glyph. |
headingLevel | 1 | 2 | 3 | 4 | 5 | 6 | 2 | Heading level for the title, so it fits the surrounding document outline. |
actionLabel | string | undefined | Recovery button label (e.g. "Try again"). Omit to render no button. |
onAction | () => void | undefined | Called when the recovery button is pressed. |
actions | ErrorStateAction[] | () => [] | 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; the actions slot replaces the whole area. |
size | "md" | "sm" | "md" | Density: md for full pages and sections, sm inside cards, panels and table areas. |
Slots: actions, default, icon.
| Prop | Type | Default | Description |
|---|---|---|---|
title * | string | — | The headline: what went wrong, in plain language. |
description | string | — | Optional secondary line: detail or next step. |
status | FeedbackStatus | "danger" | Feedback status driving the default icon's colour and glyph. |
headingLevel | 1 | 2 | 3 | 4 | 5 | 6 | 2 | Heading level for the title, so it fits the surrounding document outline. |
actionLabel | string | — | Recovery button label (such as "Try again"). Omit it to render no button. |
onAction | () => void | — | Called when the recovery button is pressed. |
actions | ErrorStateAction[] | ReactNode | — | The action area: entries, or markup of your own. An entry with href renders a Link; the others render Buttons, the first default and the rest ghost unless an entry sets its own variant. Takes precedence over actionLabel. |
size | "md" | "sm" | "md" | Density: md for pages and sections, sm inside cards, panels and tables. |
icon | ReactNode | — | A glyph or artwork of your own, in place of the status FeedbackIcon. |
children | ReactNode | — | Extra content between the description and the actions. |
| Attribute | Reactive | Description |
|---|---|---|
title * | yes | |
description | yes | |
status | yes | |
heading-level | yes | |
size | yes | |
action-label | yes | |
live | yes |
Reactive attributes re-render the element when they change after the first render.
Events: action when the generated recovery button is pressed.
Every href is rendered as given: pass only URLs you trust or have
sanitized. See Security.
Anatomy & reuse
Section titled “Anatomy & reuse”It composes existing primitives — no new behavior:
- Icon: a FeedbackIcon
(
dangerby default). Override it with a different glyph or a bespoke illustration via theiconsnippet. - Actions: Buttons and
Links. One recovery button
comes from
actionLabel/onAction; a configurable group comes from theactionsprop: an array of{ label, onAction, variant, href }where the first action renders in thedefaultvariant and the rest inghost(unless an entry sets its ownvariant), and an entry withhrefrenders as a link (e.g. “Contact support”). For anything else, anactionssnippet 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 defaultmdfits pages and sections.
Accessibility
Section titled “Accessibility”- 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(default2) sets the title’s heading level so it fits the surrounding document outline (use1on a dedicated error page).
Example
Section titled “Example”<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).