The problem
A whole page replaced by “Something went wrong” throws away everything that did load. Error codes mean nothing to the reader, and without a retry the only way out is reloading and losing work.
When to use it
Use it for
- A section failed to load, a save failed, or the connection dropped.
Not for
- Validation errors on a field: use the field's errorMessage.
- Pages that don't exist: use a 404 page.
Anatomy
- ScopeSection errors use an inline Alert; app-wide problems, like being offline, use a Banner.
- TitleWhat failed, in the reader's words: “Couldn't load leave balances”.
- DescriptionWhy, if known, and what's still safe: “Your requests are saved.”
- ActionRetry, or the next best step: “Contact payroll”.
How to build it
- Catch errors per section, so one failed request doesn't blank the page.
- Show an Alert with tone="danger" where the content would have been.
- Offer Retry, and show the loading state while retrying.
- Keep any data the person entered; save drafts locally if the save failed.
- For connection problems, show a Banner and retry automatically when back online.
- Log the technical detail; show the reader plain language.
app.tsx
import { Alert, Button } from "@nexera-ui/react";
{error ? (
<Alert
tone="danger"
title="Couldn't load leave balances"
description="Check your connection and try again. Your requests are saved."
actions={
<Button size="sm" variant="secondary" onPress={retry} isLoading={isRetrying}>
Try again
</Button>
}
/>
) : (
<Balances data={data} />
)}Accessibility
- Alerts that appear after an action use politeness="assertive"; ones present on load use polite.
- The tone icon has a text label, so “Error” isn't conveyed by colour alone.
- After a failed submit, move focus to the error so keyboard users find it.
Do and don't
DoSay what failed and offer Retry, next to the part that failed.
Don'tReplace the whole page with “Something went wrong”.
DoWrite in plain language and keep the code for support.
Don'tShow “Error 503: upstream timeout”.
DoKeep everything the person typed.
Don'tReset the form after a failed save.