ScreenErrorBoundary
One screen's crash stays in that screen: "This part could not load · Retry" while the nav around it keeps working. Retry (or a new resetKey) mounts the children again. No error-boundary dependency.
import { ScreenErrorBoundary } from '@ergasti/bricks';Examples
Contain a screen's crash
A render error inside shows a "Something went wrong" panel with a reload button instead of a blank page; resetKey (the route) clears it when you navigate away. Press the button. (React logs the error to the console; that is expected.)
Code
import { useState } from 'react';
import { Button, Card, ScreenErrorBoundary } from '@ergasti/bricks';
function Crashy() {
const [crash, setCrash] = useState(false);
if (crash) throw new Error('Example crash');
return <Button size="sm" onClick={() => setCrash(true)}>Crash this card</Button>;
}
function Boundary() {
return (
<ScreenErrorBoundary resetKey="docs" onError={() => {}}>
<Card><Card.Header title="A screen" actions={<Crashy />} /></Card>
</ScreenErrorBoundary>
);
}Props
Prop
Type
Design guidance
How the BRICKS design system uses ScreenErrorBoundary. Written in docs/content/components/ScreenErrorBoundary.md; the props above are read from the code, which wins where the two disagree.
An error boundary for one screen: if its children throw while rendering, it shows "This part could not load · Retry" in place of them while the shell around keeps working; wrap each routed screen (or each independent region) in it.
The library adds it so a crash never blanks the whole dashboard. Retry, or a new resetKey (the route), mounts the children again. It has no third-party dependency; it reports the error to onError (default console.error).
Anatomy
- Wrapper (
.kit-shell-err-wrap,display: contents): around the children while they render fine; keyed by the attempt, so Retry remounts them. - Fallback (
.kit-shell-err,role="alert"): a raspberry-50 strip (radius 16, 12px × 16px, 13px--badtext) with "This part could not load · " and a small "Retry" button.
Variants
None. Words come from copy (errorText, retry), the AppShell's copy or the provider.
States
| State | How |
|---|---|
| Normal | Children render. |
| Failed | A render error in the children: fallback shown, onError(error, info) called. |
| Retried | "Retry" or a changed resetKey: children remount. |
Usage
<AppShell brand={brand} nav={nav} activeId={route} onNavigate={go} header={header}>
<ScreenErrorBoundary resetKey={route} onError={(error) => logger.error(error)}>
<CurrentScreen />
</ScreenErrorBoundary>
</AppShell>import { Card, ScreenErrorBoundary, UsageMeter } from '@ergasti/bricks';
// Isolate independent regions so the rest of the page stays usable
export function HomeRow() {
return (
<div className="scr-grid scr-grid--2">
<ScreenErrorBoundary><UsageMeter label="Seat usage" used={321} reserved={17} limit={400} /></ScreenErrorBoundary>
<ScreenErrorBoundary><Card title="Live challenges">…</Card></ScreenErrorBoundary>
</div>
);
}Where it appears
- Around every screen inside the shell (the library's gallery
ShellDemowraps its screens). Not drawn in the v3 mocks.
Guidelines
Do
- Pass the route as
resetKey, so navigating away and back recovers. - Log to your error service in
onError.
Don't
- Don't use it for fetch errors: show the block's error state (
status="error"+onRetry); it only catches render errors. - Don't wrap the shell itself; the nav must survive.
RTL and Arabic
- Arabic: "الجزء ده معرفش يتحمّل · جرّب تاني". The strip mirrors.
Tokens
--rasp-50, --bad; small button tokens.
Accessibility
- The fallback is
role="alert", inserted when the crash happens; most screen readers announce inserted alerts, but focus does not move to it. Retry is a real button. - Retry remounts content; focus may be lost, so the app's
routeKeyfocus management on<main>still applies.
Found in the source
- Roles in the markup:
alert. - Its tests cover: “tries again when resetKey changes (a new route)”.
Read from the component's source and tests. See Accessibility for the patterns the library follows.
Related
BlockState: loading / error / empty for data blocks.EmptyView: a view with nothing yet.AppShell: the frame that stays.
See also: Button · useLanguage · Card · UsageMeter · useAppShell
Source
src/shell/ScreenErrorBoundary.tsx (line 28) on GitHub.