ErrorBoundary

Error boundary container for catching rendering errors in documentation components.

The ErrorBoundary component catches unexpected JavaScript exceptions in its descendant components and displays a clean, user-friendly fallback view instead of crashing the entire page.

Using the ErrorBoundary primitive and its props, you can pass a custom fallback component that receives the thrown error object and a resetErrorBoundary callback to let users retry rendering without reloading the browser:

tsx

// docs/components/CustomErrorWrapper.tsx
import React from 'react'
import { ErrorBoundary, ErrorBoundaryFallback } from 'boltdocs/primitives'

// 1. Define a custom interactive error panel
function MyCustomFallback({ error, resetErrorBoundary }: { error: Error; resetErrorBoundary: () => void }) {
  return (
    <div className="flex flex-col gap-3 p-6 border-2 border-red-500 bg-red-50/50 rounded-xl max-w-md mx-auto text-center">
      <h4 className="font-bold text-red-600">Widget Failure Detected</h4>
      <p className="text-xs text-zinc-500">{error.message}</p>
      <button
        onClick={resetErrorBoundary}
        className="mt-2 px-4 py-2 bg-red-600 hover:bg-red-700 text-white rounded-lg text-xs font-semibold"
      >
        Retry Rendering
      </button>
    </div>
  )
}

// 2. Wrap fragile layout components
export default function SafeLayoutSection({ children }) {
  return (
    <ErrorBoundary
      FallbackComponent={MyCustomFallback}
      onError={(error, info) => {
        // Log failure metadata to external services
        console.error('Failure logged:', error, info)
      }}
      onReset={() => {
        // Clear cached app state or context values before retrying
        console.log('Reset state triggered')
      }}
    >
      {children}
    </ErrorBoundary>
  )
}

The ErrorBoundary primitive provides the following component references:

Component	HTML Tag	Description	Props
`ErrorBoundary`	Wrapper	Catches runtime exceptions from descendants and mounts the fallback UI.	`ErrorBoundary Props`
`ErrorBoundaryFallback`	`<div>`	Default warning-card fallback view containing a Retry button.	`ComponentBaseProps`

Property	Type	Default	Description
`children`	`ReactNode`	`undefined`	Child content elements.
`className`	`string`	`undefined`	Custom utility CSS classes.
`style`	`CSSProperties`	`undefined`	Inline style settings.

Property	Type	Default	Description
`children`	`ReactNode`	Required	Descendant components to monitor for rendering errors.
`FallbackComponent`	`ComponentType<FallbackProps>`	`undefined`	A React component to render when an error is caught. Receives the `error` and `resetErrorBoundary` props.
`fallback`	`ReactNode`	`undefined`	A static React node to render when an error is caught.
`onError`	`(error: Error, info: ErrorInfo) => void`	`undefined`	Callback fired when the boundary intercepts an exception.
`onReset`	`() => void`	`undefined`	Callback fired when the fallback component invokes `resetErrorBoundary`.

The fallback component specified in FallbackComponent receives the following props:

Property	Type	Description
`error`	`Error`	The caught JavaScript exception object.
`resetErrorBoundary`	`() => void`	Triggers state cleanup to retry rendering the component.

The ErrorBoundary primitive is style-neutral: it ships no DOM structure or state attributes of its own — it catches rendering errors and swaps children for the fallback UI you provide. Every visual decision belongs to the theme, because the FallbackComponent (or fallback) you pass is entirely your theme's responsibility.

State / Slot	Mechanism
`ErrorBoundary`	Class component; renders `children` normally and mounts no wrapper element
Error caught	Replaces `children` with `FallbackComponent` (or the static `fallback` node)
`FallbackComponent`	Receives `error` and `resetErrorBoundary`; you own its markup and `className`
Retry	`resetErrorBoundary` clears the error state and re-renders `children` — style the retry control in your fallback
`onError` / `onReset`	Callbacks for logging and reset side effects; no visual output

tsx

function MyFallback({ error, resetErrorBoundary }: FallbackProps) {
  return (
    <div className="rounded-xl border border-subtle bg-surface p-6 text-center">
      <p className="text-sm text-muted">{error.message}</p>
      <button
        onClick={resetErrorBoundary}
        className="mt-3 rounded-lg bg-primary-500 px-4 py-2 text-xs font-semibold text-white hover:bg-primary-600"
      >
        Try again
      </button>
    </div>
  )
}

<ErrorBoundary FallbackComponent={MyFallback}>{children}</ErrorBoundary>

Jesús Alcalá

Last updated on October 18, 2026

ErrorBoundary

Composable Fallback Example

Composable Subcomponents

Component Props

ComponentBaseProps (Common)

`ErrorBoundary` Props

`FallbackProps` Schema

Customization & states

Was this page helpful?

Composable Fallback ExampleLink

Composable SubcomponentsLink

Component PropsLink

ComponentBaseProps (Common)Link

ErrorBoundary PropsLink

FallbackProps SchemaLink

Customization & statesLink