> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/zayne-labs/ui/llms.txt
> Use this file to discover all available pages before exploring further.

# ErrorBoundary

> Catch and handle React errors with declarative error boundaries

The ErrorBoundary component catches JavaScript errors anywhere in the component tree, logs errors, and displays a fallback UI instead of crashing the entire app.

## When to Use

* Prevent entire app crashes from component errors
* Display user-friendly error messages
* Provide recovery mechanisms (retry buttons)
* Log errors for monitoring and debugging
* Isolate errors to specific parts of the UI

## Basic Usage

<CodeGroup>
  ```tsx Simple Fallback theme={null}
  import { ErrorBoundary } from "@zayne-labs/ui-react/common/error-boundary";

  function App() {
    return (
      <ErrorBoundary fallback={<div>Something went wrong</div>}>
        <MyComponent />
      </ErrorBoundary>
    );
  }
  ```

  ```tsx Render Function theme={null}
  import { ErrorBoundary } from "@zayne-labs/ui-react/common/error-boundary";

  function App() {
    return (
      <ErrorBoundary
        fallback={({ error, resetErrorBoundary }) => (
          <div>
            <h1>Error</h1>
            <pre>{error.message}</pre>
            <button onClick={resetErrorBoundary}>Try Again</button>
          </div>
        )}
      >
        <MyComponent />
      </ErrorBoundary>
    );
  }
  ```
</CodeGroup>

## Component API

<ParamField path="children" type="React.ReactNode" required>
  Components to wrap with error boundary protection
</ParamField>

<ParamField path="fallback" type="React.ReactNode | ((props: ErrorFallbackProps) => React.ReactNode)">
  UI to display when an error is caught. Can be a static component or render function
</ParamField>

<ParamField path="onError" type="(context: { error: Error; info: React.ErrorInfo }) => void">
  Callback fired when an error is caught. Useful for error logging services
</ParamField>

<ParamField path="onReset" type="(context: ResetContext) => void">
  Callback fired when the error boundary is reset, either imperatively or via resetKeys
</ParamField>

<ParamField path="resetKeys" type="unknown[]">
  Array of values that will reset the error boundary when they change. Useful for resetting on prop/state changes
</ParamField>

### ErrorFallbackProps

<ParamField path="error" type="Error">
  The error that was caught
</ParamField>

<ParamField path="resetErrorBoundary" type="(...args: unknown[]) => void">
  Function to reset the error boundary and re-render children
</ParamField>

## Examples

### Error Logging

```tsx theme={null}
import { ErrorBoundary } from "@zayne-labs/ui-react/common/error-boundary";

function App() {
  const handleError = ({ error, info }) => {
    // Send to error monitoring service
    console.error("Error caught:", error);
    console.error("Component stack:", info.componentStack);

    // Example: Send to Sentry
    // Sentry.captureException(error, { contexts: { react: info } });
  };

  return (
    <ErrorBoundary
      onError={handleError}
      fallback={({ error }) => (
        <div>
          <h1>Oops! Something went wrong</h1>
          <details>
            <summary>Error details</summary>
            <pre>{error.message}</pre>
          </details>
        </div>
      )}
    >
      <App />
    </ErrorBoundary>
  );
}
```

### Auto-Reset on Key Change

```tsx theme={null}
import { ErrorBoundary } from "@zayne-labs/ui-react/common/error-boundary";

function UserProfile({ userId }) {
  return (
    <ErrorBoundary
      resetKeys={[userId]}
      fallback={({ error, resetErrorBoundary }) => (
        <div>
          <p>Failed to load user: {error.message}</p>
          <button onClick={resetErrorBoundary}>Retry</button>
        </div>
      )}
    >
      <UserData userId={userId} />
    </ErrorBoundary>
  );
}
```

<Info>
  When `userId` changes, the error boundary automatically resets and re-renders the children.
</Info>

### Nested Error Boundaries

```tsx theme={null}
import { ErrorBoundary } from "@zayne-labs/ui-react/common/error-boundary";

function Dashboard() {
  return (
    <div>
      <ErrorBoundary fallback={<div>Header failed to load</div>}>
        <Header />
      </ErrorBoundary>

      <ErrorBoundary fallback={<div>Sidebar failed to load</div>}>
        <Sidebar />
      </ErrorBoundary>

      <ErrorBoundary
        fallback={({ error, resetErrorBoundary }) => (
          <div>
            <p>Main content error: {error.message}</p>
            <button onClick={resetErrorBoundary}>Reload</button>
          </div>
        )}
      >
        <MainContent />
      </ErrorBoundary>
    </div>
  );
}
```

### Using the Hook

```tsx theme={null}
import { useErrorBoundary } from "@zayne-labs/ui-react/common/error-boundary";

function DataFetcher() {
  const { showBoundary, resetBoundary } = useErrorBoundary();
  const [data, setData] = useState(null);

  const fetchData = async () => {
    try {
      const response = await fetch("/api/data");
      if (!response.ok) throw new Error("Failed to fetch");
      const json = await response.json();
      setData(json);
    } catch (error) {
      showBoundary(error);
    }
  };

  return (
    <div>
      <button onClick={fetchData}>Load Data</button>
      {data && <pre>{JSON.stringify(data, null, 2)}</pre>}
    </div>
  );
}

function App() {
  return (
    <ErrorBoundary fallback={({ error, resetErrorBoundary }) => (
      <div>
        <p>Error: {error.message}</p>
        <button onClick={resetErrorBoundary}>Reset</button>
      </div>
    )}>
      <DataFetcher />
    </ErrorBoundary>
  );
}
```

### Custom Error UI

```tsx theme={null}
import { ErrorBoundary } from "@zayne-labs/ui-react/common/error-boundary";

function ErrorFallback({ error, resetErrorBoundary }) {
  return (
    <div className="error-container">
      <div className="error-icon">⚠️</div>
      <h2>Something unexpected happened</h2>
      <p className="error-message">{error.message}</p>
      <div className="error-actions">
        <button onClick={resetErrorBoundary} className="btn-primary">
          Try Again
        </button>
        <button onClick={() => window.location.href = '/'} className="btn-secondary">
          Go Home
        </button>
      </div>
    </div>
  );
}

function App() {
  return (
    <ErrorBoundary fallback={ErrorFallback}>
      <MyApp />
    </ErrorBoundary>
  );
}
```

## Comparison to Native Patterns

### Class Component Error Boundary

```tsx theme={null}
class ErrorBoundary extends React.Component {
  state = { hasError: false, error: null };

  static getDerivedStateFromError(error) {
    return { hasError: true, error };
  }

  componentDidCatch(error, info) {
    console.error(error, info);
  }

  render() {
    if (this.state.hasError) {
      return <div>Error: {this.state.error.message}</div>;
    }
    return this.props.children;
  }
}
```

### With Zayne Labs ErrorBoundary

```tsx theme={null}
import { ErrorBoundary } from "@zayne-labs/ui-react/common/error-boundary";

<ErrorBoundary
  onError={({ error, info }) => console.error(error, info)}
  fallback={({ error }) => <div>Error: {error.message}</div>}
>
  {children}
</ErrorBoundary>
```

## Common Use Cases

### Protecting Route Components

```tsx theme={null}
import { ErrorBoundary } from "@zayne-labs/ui-react/common/error-boundary";

function RouteErrorFallback({ error, resetErrorBoundary }) {
  return (
    <div className="route-error">
      <h1>Page Error</h1>
      <p>{error.message}</p>
      <button onClick={resetErrorBoundary}>Reload Page</button>
    </div>
  );
}

function Router() {
  return (
    <Routes>
      <Route
        path="/"
        element={
          <ErrorBoundary fallback={RouteErrorFallback}>
            <HomePage />
          </ErrorBoundary>
        }
      />
      <Route
        path="/profile"
        element={
          <ErrorBoundary fallback={RouteErrorFallback}>
            <ProfilePage />
          </ErrorBoundary>
        }
      />
    </Routes>
  );
}
```

### Form Validation Errors

```tsx theme={null}
import { ErrorBoundary } from "@zayne-labs/ui-react/common/error-boundary";

function FormContainer() {
  return (
    <ErrorBoundary
      fallback={({ error, resetErrorBoundary }) => (
        <div className="form-error">
          <p>Form submission failed: {error.message}</p>
          <button onClick={resetErrorBoundary}>Try Again</button>
        </div>
      )}
    >
      <ComplexForm />
    </ErrorBoundary>
  );
}
```

<Note>
  This component is based on the [react-error-boundary](https://github.com/bvaughn/react-error-boundary) package with enhanced TypeScript support.
</Note>

<Warning>
  Error boundaries do NOT catch errors in:

  * Event handlers (use try-catch instead)
  * Asynchronous code (setTimeout, promises)
  * Server-side rendering
  * Errors thrown in the error boundary itself
</Warning>