# Error Pages

> React error pages in one block: 404 not found, 500 server error, maintenance, offline and no permission, full page or inside an app shell.

- Type: React block (Blocks)
- Access: Pro (the source needs a Wingo UI Pro plan, see https://wingo-ui.com/pricing)
- Version: 1.1.0
- Install: `npx wingo-ui@latest add error-pages`
- Docs: https://wingo-ui.com/components/error-pages

## Interaction

The illustration rises in and the 404 compass needle swings and settles once; everything else fades up in order when the page mounts on the client (reduced motion keeps only short fades). 404: "Back to the home page" and "Go back" (history back, or home without history); the search focuses with / and Enter searches (a live region says what is being searched); the four suggestion cards are links that lift on hover and press in on tap. 500: "Try again" spins while it checks; a failed try shows a red alert with the time, the error id copies with one click ("Copied"), and "Technical details" opens the time, the path and the stack trace (the code block scrolls sideways on phones and has its own copy button). Maintenance: a live countdown to the end with the return date under it, the status page and support links, a 30 day uptime bar (hover, tap or arrow keys read each day) and "Notify me", an email field that validates when you leave it and ends in a confirmation; when the countdown reaches zero the page says "Maintenance is over" and the primary action becomes "Reload". Offline: an automatic retry every retryInterval seconds with a thin progress bar and "Trying again in 8 s", "Try now" at any time; the browser's online event retries at once, draws the cloud's slash away, says "You are back online" and then reloads (or calls onReconnect); pages saved on the device stay one tap away. Forbidden: "Request access" opens a dialog (a bottom sheet on phones) with an admin picker and a reason of at least 10 characters; submitting empty shows both errors, a valid request closes it, the button turns into a disabled "Request sent · 4:42 PM" and a green confirmation takes focus; "Switch account" signs out, and the signed-in account is shown. State changes are announced politely, never every second; the title takes focus when the page is reached by navigation.

## Installation

```bash
npx wingo-ui@latest add error-pages
```

Pro item: run `npx wingo-ui@latest login` once with a Pro account. The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add @wingo-ui/error-pages` (needs the @wingo-ui registry with your API key in components.json)

Files:

- `components/blocks/error-pages.tsx`
- `components/blocks/error-pages-data.ts`

npm dependencies: `npm i motion lucide-react react-hook-form zod`

Wingo UI dependencies (installed automatically):

- [Marketing Section](https://wingo-ui.com/components/marketing-section) ([Markdown](https://wingo-ui.com/components/marketing-section.md))
- [Alert](https://wingo-ui.com/components/alert) ([Markdown](https://wingo-ui.com/components/alert.md))
- [Avatar](https://wingo-ui.com/components/avatar) ([Markdown](https://wingo-ui.com/components/avatar.md))
- [Badge](https://wingo-ui.com/components/badge) ([Markdown](https://wingo-ui.com/components/badge.md))
- [Button](https://wingo-ui.com/components/button) ([Markdown](https://wingo-ui.com/components/button.md))
- [Code Block](https://wingo-ui.com/components/code-block) ([Markdown](https://wingo-ui.com/components/code-block.md))
- [Collapsible](https://wingo-ui.com/components/collapsible) ([Markdown](https://wingo-ui.com/components/collapsible.md))
- [Copy Button](https://wingo-ui.com/components/copy-button) ([Markdown](https://wingo-ui.com/components/copy-button.md))
- [Countdown](https://wingo-ui.com/components/countdown) ([Markdown](https://wingo-ui.com/components/countdown.md))
- [Dialog](https://wingo-ui.com/components/dialog) ([Markdown](https://wingo-ui.com/components/dialog.md))
- [Input](https://wingo-ui.com/components/input) ([Markdown](https://wingo-ui.com/components/input.md))
- [Search Input](https://wingo-ui.com/components/search-input) ([Markdown](https://wingo-ui.com/components/search-input.md))
- [Select](https://wingo-ui.com/components/select) ([Markdown](https://wingo-ui.com/components/select.md))
- [Textarea](https://wingo-ui.com/components/textarea) ([Markdown](https://wingo-ui.com/components/textarea.md))
- [Toast](https://wingo-ui.com/components/toast) ([Markdown](https://wingo-ui.com/components/toast.md))
- [Tracker](https://wingo-ui.com/components/tracker) ([Markdown](https://wingo-ui.com/components/tracker.md))
- [useCooldown](https://wingo-ui.com/components/use-cooldown) ([Markdown](https://wingo-ui.com/components/use-cooldown.md))
- [Date utils](https://wingo-ui.com/components/date-utils) ([Markdown](https://wingo-ui.com/components/date-utils.md))
- [Form validation](https://wingo-ui.com/components/form-validation) ([Markdown](https://wingo-ui.com/components/form-validation.md))
- [Motion presets](https://wingo-ui.com/components/motion) ([Markdown](https://wingo-ui.com/components/motion.md))
- [Navigation](https://wingo-ui.com/components/navigation) ([Markdown](https://wingo-ui.com/components/navigation.md))
- [Number format](https://wingo-ui.com/components/number-format) ([Markdown](https://wingo-ui.com/components/number-format.md))
- [Relative time](https://wingo-ui.com/components/relative-time) ([Markdown](https://wingo-ui.com/components/relative-time.md))
- [Tones](https://wingo-ui.com/components/tones) ([Markdown](https://wingo-ui.com/components/tones.md))
- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

```tsx
// app/not-found.tsx
"use client";

import Link from "next/link";
import { useRouter } from "next/navigation";
import { ErrorPage } from "@/components/blocks/error-pages";

export default function NotFound() {
  const router = useRouter();
  return (
    <ErrorPage
      variant="404"
      linkComponent={Link}
      onBack={() => router.back()}
      onSearch={(query) => router.push(`/search?q=${encodeURIComponent(query)}`)}
    />
  );
}

// app/error.tsx: <ErrorPage variant="500" error={error} errorId={error.digest} onRetry={reset} />
// inside the admin layout: <ErrorPage variant="forbidden" layout="inline" resource="Financial reports" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant?` | `"404" \| "500" \| "maintenance" \| "offline" \| "forbidden"` | `"404"` | Which error screen to show. |
| `layout?` | `"page" \| "inline"` | `"page"` | page: min-h-dvh with the logo on top and a small footer; inline: fills a shell's main (min-h-[70dvh]) without logo or footer. |
| `background?` | `"plain" \| "soft" \| "glow" \| "aurora" \| "grid" \| "dots"` | `"grid"` | The page layout's background: plain is the bare page color with a dotted field behind the illustration; the others tint the page and add a glow, an aurora, a grid or dots over the first screen. The inline layout keeps the shell's background. |
| `backgroundColor?` | `string` | `"oklch(0.62 0.14 275)"` | The tint and glow color of the page background. |
| `title?` | `ReactNode` | `""` | Replaces the variant's title. |
| `description?` | `ReactNode` | `""` | Replaces the variant's description. |
| `illustration?` | `ReactNode \| false` |  | The art above the eyebrow; default ErrorIllustration for the variant, false hides it. |
| `homeHref?` | `string` | `"/"` | The logo and "Back to the home page". |
| `onBack?` | `() => void` |  | 404 "Go back". Default: history.back() when there is history, otherwise the home link. |
| `supportHref?` | `string` | `"mailto:support@acme.com"` | "Contact support" on every variant. |
| `statusHref?` | `string` | `"https://status.acme.com"` | The status page in the header, the footer and the maintenance actions; "" hides those links. |
| `showSearch?` | `boolean` | `true` | 404: the search field (role search). |
| `onSearch?` | `(query: string) => void` |  | 404: runs on Enter. Default: navigates to /search?q=. |
| `searchShortcut?` | `string` | `"/"` | Focuses the 404 search from anywhere; "" binds nothing. |
| `suggestions?` | `ErrorPageSuggestion[]` |  | 404 link cards { label, href, icon?, description? }; default ERROR_PAGE_SUGGESTIONS (Dashboard, Clients, Invoices, Help); [] hides them. |
| `errorId?` | `string` | `"ERR-7F3K-2026"` | 500: the id to quote to support, copyable under the actions and in the details; "" hides it. |
| `error?` | `Error \| { message: string; stack?: string }` |  | 500: the details, a sample TypeError by default. Without a stack the details show the message only. |
| `errorPath?` | `string` | `"/invoices/2026-0412"` | 500: the page that failed, in the details. |
| `occurredAt?` | `Date \| number \| string` | `"2026-09-24T16:40:12"` | 500: when it failed, in the details. |
| `showDetails?` | `boolean` | `true` | 500: the "Technical details" collapsible. |
| `defaultDetailsOpen?` | `boolean` | `false` | 500: the details start open. |
| `onRetry?` | `() => (void \| Promise<unknown>)` |  | 500 retry, offline check and the maintenance reload. A rejection shows the failure (500 alert, offline keeps waiting). Default: 500 fails the first try and reloads on the next, offline passes once the browser fired online, maintenance reloads. |
| `until?` | `Date \| number \| string` | `"2026-09-27T04:00:00"` | Maintenance: the end. In the past the page already says "Maintenance is over". |
| `statusHistory?` | `TrackerDatum[]` |  | Maintenance: the uptime bar, default ERROR_PAGES_SAMPLE.statusHistory (30 days, one partial day on Sep 18, 2026). |
| `uptime?` | `number` | `0.9995` | Maintenance: the uptime share shown next to the bar (99.95%). |
| `showStatus?` | `boolean` | `true` | Maintenance: the uptime history. |
| `showSubscribe?` | `boolean` | `true` | Maintenance: the "Notify me" email form. |
| `defaultEmail?` | `string` | `""` | Maintenance: prefills the email. |
| `onSubscribe?` | `(email: string) => (void \| Promise<unknown>)` |  | Maintenance: saves the email; a rejection shows its message under the field. Default: simulated. |
| `retryInterval?` | `number` | `10` | Offline: seconds between automatic retries (0 = off); each failed try starts a new wait. |
| `onReconnect?` | `() => void` |  | Offline: runs 1.6 s after the connection came back (and on "Continue"). Default: reloads the page. |
| `offlinePages?` | `ErrorPageOfflinePage[]` |  | Offline: pages saved on the device { label, href, savedAt, icon? }; default ERROR_PAGE_OFFLINE_PAGES; [] hides the list. |
| `admins?` | `{ id: string; name: string; avatar?: string; role?: string }[]` |  | Forbidden: who can grant access (Emma Carter, Ryan Brooks). [] shows only the support link. |
| `resource?` | `ReactNode` | `"Financial reports"` | Forbidden: what was refused. |
| `onRequestAccess?` | `(input: ErrorPageAccessRequest) => (void \| Promise<unknown>)` |  | Forbidden: sends { adminId, reason }; a rejection shows its message in the dialog. Default: simulated. |
| `defaultRequestSent?` | `{ adminId: string; sentAt: Date \| number \| string }` |  | Forbidden: opens on the request sent state. |
| `onSwitchAccount?` | `() => void` |  | Forbidden: "Switch account". Default: a toast. |
| `account?` | `{ name: string; email: string; avatar?: string; team?: string } \| null` |  | Forbidden: who is signed in (Noah Hayes, Sales team); null hides the card and shows the home link instead of "Switch account". |
| `logo?` | `ReactNode` |  | Page layout: the header mark, default the Acme CRM logo. |
| `footer?` | `ReactNode` |  | Extra content at the start of the footer links (inline layout: under the page). |
| `autoFocusTitle?` | `boolean` | `true` | Page layout: the title takes focus when the page mounts after a navigation, never on the first load. |
| `tone?` | `Tone` | `"neutral"` | The primary actions, the illustration's accent, the countdown tiles and the retry bar. |
| `radius?` | `"sm" \| "md" \| "lg"` | `"md"` | Panels, cards, tiles and buttons. |
| `animateIn?` | `boolean` | `true` | The illustration and the sections rise in once when the page mounts on the client (server html is already final). |
| `labels?` | `ErrorPageLabelsInput` |  | Every visible string, one group per variant plus common, validation, countdown, tracker and trackerStatuses: DEFAULT_ERROR_PAGE_LABELS (English) by default, ERROR_PAGE_LABELS_RO for the ready Romanian set. |
| `locale?` | `string` | `"en-US"` | Dates, times, numbers and the page language. |
| `now?` | `Date \| number` |  | The reference time for relative times and the maintenance countdown (which then runs live from mount). Default useNow(). |
| `linkComponent?` | `(props: LinkComponentProps) => ReactNode` |  | The router link for every link (next/link); default <a>. |
| `classNames?` | `Partial<Record<ErrorPageSlot, string>>` |  | Classes for header, main, content, illustration, eyebrow, title, description, actions, extra, help and footer. |

## Parts

### ErrorIllustration (component)

The theme-aware line art of each error kind, drawn in foreground tints with one accent in the tone color. Use it alone in your own empty or error screens.

### DEFAULT_ERROR_PAGE_LABELS (constant)

Every English string of the five screens, with the strings of the items they compose. Spread it and override what you translate.

### ERROR_PAGE_LABELS_EN (constant)

An alias of DEFAULT_ERROR_PAGE_LABELS, kept so older imports keep working.

### ERROR_PAGE_LABELS_RO (constant)

A ready Romanian set of every string, including the Romanian strings of the composed items. Pass it as labels for a Romanian site.

### ERROR_PAGE_SUGGESTIONS (constant)

The default links of the not found screen (Dashboard, Clients, Invoices, Help), each with its icon. Replace it with your own popular pages.

### ERROR_PAGE_OFFLINE_PAGES (constant)

The default pages the offline screen lists as saved for offline reading, each with its icon.

### withSuggestionIcons (function)

Turns items whose icon is a key ("dashboard", "clients", "invoices", "help"...) into items with the matching icon, so suggestions can come from JSON or a CMS.

### ERROR_PAGES_SAMPLE (constant)

The demo content: suggestions, the sample error, offline pages, the status history, the admins and the signed in account. Replace it with your own data.

### ERROR_PAGES_SAMPLE_EN (constant)

The same demo content under its older name, kept so existing imports keep working.

## Examples

- **Server error**: 500 with the technical details open; the first retry fails and shows the time, the second one works.
- **Scheduled maintenance**: A live countdown to Sunday 04:00, the 30 day uptime bar and the notify-me form.
- **Offline**: Retries every 10 seconds; the footer link fires the online event and the page comes back.
- **No access, request sent**: The forbidden page after asking Ryan Brooks for access three minutes ago.
- **Inside the admin shell**: layout="inline" fills the shell's main for a missing report at /reports/q5.
- **Brand tone**: tone="brand" on the primary action and the compass needle, with larger radii.
- **Romanian copy**: ERROR_PAGE_LABELS_RO with locale ro-RO on the forbidden page: the ready Romanian set for the page and its parts.

## See also

- [Empty State](https://wingo-ui.com/components/empty-state) ([Markdown](https://wingo-ui.com/components/empty-state.md))
- [Alert](https://wingo-ui.com/components/alert) ([Markdown](https://wingo-ui.com/components/alert.md))
- [Tracker](https://wingo-ui.com/components/tracker) ([Markdown](https://wingo-ui.com/components/tracker.md))
- [Countdown](https://wingo-ui.com/components/countdown) ([Markdown](https://wingo-ui.com/components/countdown.md))
- [Login Page](https://wingo-ui.com/components/login-page) ([Markdown](https://wingo-ui.com/components/login-page.md))

---

Canonical: https://wingo-ui.com/components/error-pages
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt