Skip to Content
BBRICKSv0.7.4
ShellOther

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

  1. Wrapper (.kit-shell-err-wrap, display: contents): around the children while they render fine; keyed by the attempt, so Retry remounts them.
  2. Fallback (.kit-shell-err, role="alert"): a raspberry-50 strip (radius 16, 12px × 16px, 13px --bad text) 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

StateHow
NormalChildren render.
FailedA 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 ShellDemo wraps 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 routeKey focus 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.

  • 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.

On this page