React Error Boundaries Guide

Error boundaries catch JavaScript errors in components and display fallback UI. Here's how to use them effectively.

Basic Error Boundary#

import { Component, ErrorInfo, ReactNode } from 'react';

interface Props {
  children: ReactNode;
  fallback?: ReactNode;
}

interface State {
  hasError: boolean;
  error: Error | null;
}

class ErrorBoundary extends Component<Props, State> {
  constructor(props: Props) {
    super(props);
    this.state = { hasError: false, error: null };
  }

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

  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
    console.error('Error caught by boundary:', error, errorInfo);
  }

  render() {
    if (this.state.hasError) {
      return this.props.fallback || <h1>Something went wrong.</h1>;
    }

    return this.props.children;
  }
}

// Usage
function App() {
  return (
    <ErrorBoundary fallback={<ErrorFallback />}>
      <MyComponent />
    </ErrorBoundary>
  );
}

Error Boundary with Reset#

interface Props {
  children: ReactNode;
  fallback: (props: { error: Error; reset: () => void }) => ReactNode;
}

interface State {
  hasError: boolean;
  error: Error | null;
}

class ErrorBoundary extends Component<Props, State> {
  constructor(props: Props) {
    super(props);
    this.state = { hasError: false, error: null };
  }

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

  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
    // Log to error reporting service
    logErrorToService(error, errorInfo);
  }

  reset = () => {
    this.setState({ hasError: false, error: null });
  };

  render() {
    if (this.state.hasError && this.state.error) {
      return this.props.fallback({
        error: this.state.error,
        reset: this.reset,
      });
    }

    return this.props.children;
  }
}

// Usage
function App() {
  return (
    <ErrorBoundary
      fallback={({ error, reset }) => (
        <div>
          <h2>Something went wrong</h2>
          <p>{error.message}</p>
          <button onClick={reset}>Try again</button>
        </div>
      )}
    >
      <MyComponent />
    </ErrorBoundary>
  );
}

react-error-boundary Library#

import { ErrorBoundary, useErrorBoundary } from 'react-error-boundary';

function ErrorFallback({ error, resetErrorBoundary }) {
  return (
    <div role="alert">
      <h2>Something went wrong</h2>
      <pre>{error.message}</pre>
      <button onClick={resetErrorBoundary}>Try again</button>
    </div>
  );
}

function App() {
  return (
    <ErrorBoundary
      FallbackComponent={ErrorFallback}
      onError={(error, info) => {
        // Log error to service
        logError(error, info);
      }}
      onReset={() => {
        // Reset app state
        queryClient.clear();
      }}
    >
      <MyApp />
    </ErrorBoundary>
  );
}

// Trigger error boundary from event handlers
function DataLoader() {
  const { showBoundary } = useErrorBoundary();

  async function loadData() {
    try {
      const data = await fetchData();
      setData(data);
    } catch (error) {
      showBoundary(error);
    }
  }

  return <button onClick={loadData}>Load Data</button>;
}

Granular Error Boundaries#

// Wrap different sections independently
function Dashboard() {
  return (
    <div className="dashboard">
      <ErrorBoundary fallback={<HeaderError />}>
        <Header />
      </ErrorBoundary>

      <main>
        <ErrorBoundary fallback={<ChartError />}>
          <ChartSection />
        </ErrorBoundary>

        <ErrorBoundary fallback={<TableError />}>
          <DataTable />
        </ErrorBoundary>
      </main>

      <ErrorBoundary fallback={<SidebarError />}>
        <Sidebar />
      </ErrorBoundary>
    </div>
  );
}

// Section-specific fallbacks
function ChartError() {
  return (
    <div className="chart-error">
      <p>Unable to load chart</p>
      <button onClick={() => window.location.reload()}>
        Refresh page
      </button>
    </div>
  );
}

Error Boundary with Retry#

interface RetryBoundaryProps {
  children: ReactNode;
  maxRetries?: number;
}

interface State {
  hasError: boolean;
  error: Error | null;
  retryCount: number;
}

class RetryBoundary extends Component<RetryBoundaryProps, State> {
  constructor(props: RetryBoundaryProps) {
    super(props);
    this.state = { hasError: false, error: null, retryCount: 0 };
  }

  static getDerivedStateFromError(error: Error): Partial<State> {
    return { hasError: true, error };
  }

  retry = () => {
    this.setState(prev => ({
      hasError: false,
      error: null,
      retryCount: prev.retryCount + 1,
    }));
  };

  render() {
    const { maxRetries = 3 } = this.props;
    const { hasError, error, retryCount } = this.state;

    if (hasError) {
      if (retryCount >= maxRetries) {
        return (
          <div>
            <h2>Failed after {maxRetries} attempts</h2>
            <p>{error?.message}</p>
          </div>
        );
      }

      return (
        <div>
          <h2>Something went wrong</h2>
          <p>Attempt {retryCount + 1} of {maxRetries}</p>
          <button onClick={this.retry}>Retry</button>
        </div>
      );
    }

    return this.props.children;
  }
}

Suspense with Error Boundary#

import { Suspense } from 'react';
import { ErrorBoundary } from 'react-error-boundary';

function AsyncComponent() {
  return (
    <ErrorBoundary
      fallback={<ErrorMessage />}
      onReset={() => {
        // Clear cache or refetch
      }}
    >
      <Suspense fallback={<Loading />}>
        <DataComponent />
      </Suspense>
    </ErrorBoundary>
  );
}

// Combined loading and error states
function AsyncSection() {
  return (
    <ErrorBoundary fallback={<SectionError />}>
      <Suspense fallback={<SectionSkeleton />}>
        <AsyncContent />
      </Suspense>
    </ErrorBoundary>
  );
}

Error Reporting Integration#

import * as Sentry from '@sentry/react';

// Sentry's built-in error boundary
function App() {
  return (
    <Sentry.ErrorBoundary
      fallback={({ error, resetError }) => (
        <ErrorFallback error={error} onReset={resetError} />
      )}
      showDialog
    >
      <MyApp />
    </Sentry.ErrorBoundary>
  );
}

// Custom error boundary with reporting
class ReportingErrorBoundary extends Component<Props, State> {
  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
    // Sentry
    Sentry.captureException(error, {
      extra: { componentStack: errorInfo.componentStack },
    });

    // Or custom logging
    fetch('/api/log-error', {
      method: 'POST',
      body: JSON.stringify({
        message: error.message,
        stack: error.stack,
        componentStack: errorInfo.componentStack,
        url: window.location.href,
        timestamp: new Date().toISOString(),
      }),
    });
  }

  // ... rest of implementation
}

Error Types and Handling#

// Custom error types
class NetworkError extends Error {
  constructor(message: string, public statusCode?: number) {
    super(message);
    this.name = 'NetworkError';
  }
}

class ValidationError extends Error {
  constructor(message: string, public field?: string) {
    super(message);
    this.name = 'ValidationError';
  }
}

// Type-specific fallbacks
function ErrorFallback({ error, resetErrorBoundary }) {
  if (error instanceof NetworkError) {
    return (
      <div>
        <h2>Network Error</h2>
        <p>Please check your connection</p>
        <button onClick={resetErrorBoundary}>Retry</button>
      </div>
    );
  }

  if (error instanceof ValidationError) {
    return (
      <div>
        <h2>Invalid Data</h2>
        <p>{error.message}</p>
        <button onClick={resetErrorBoundary}>Go Back</button>
      </div>
    );
  }

  return (
    <div>
      <h2>Unexpected Error</h2>
      <button onClick={() => window.location.reload()}>
        Refresh Page
      </button>
    </div>
  );
}

Testing Error Boundaries#

import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

// Component that throws
function ThrowError({ shouldThrow }: { shouldThrow: boolean }) {
  if (shouldThrow) {
    throw new Error('Test error');
  }
  return <div>No error</div>;
}

describe('ErrorBoundary', () => {
  // Suppress console.error for expected errors
  const originalError = console.error;
  beforeAll(() => {
    console.error = jest.fn();
  });
  afterAll(() => {
    console.error = originalError;
  });

  it('renders children when no error', () => {
    render(
      <ErrorBoundary fallback={<div>Error</div>}>
        <ThrowError shouldThrow={false} />
      </ErrorBoundary>
    );

    expect(screen.getByText('No error')).toBeInTheDocument();
  });

  it('renders fallback when error occurs', () => {
    render(
      <ErrorBoundary fallback={<div>Error occurred</div>}>
        <ThrowError shouldThrow={true} />
      </ErrorBoundary>
    );

    expect(screen.getByText('Error occurred')).toBeInTheDocument();
  });

  it('resets error state', async () => {
    const user = userEvent.setup();
    let shouldThrow = true;

    function Fallback({ resetErrorBoundary }) {
      return (
        <button onClick={() => {
          shouldThrow = false;
          resetErrorBoundary();
        }}>
          Reset
        </button>
      );
    }

    render(
      <ErrorBoundary FallbackComponent={Fallback}>
        <ThrowError shouldThrow={shouldThrow} />
      </ErrorBoundary>
    );

    await user.click(screen.getByText('Reset'));
    expect(screen.getByText('No error')).toBeInTheDocument();
  });
});

Best Practices#

Placement:
✓ Wrap major sections independently
✓ Place near data fetching components
✓ Keep user-interactive areas recoverable
✓ Don't wrap everything in one boundary

Recovery:
✓ Provide clear error messages
✓ Offer retry or reset options
✓ Clear relevant cache on reset
✓ Log errors for debugging

UX:
✓ Match fallback UI to component style
✓ Preserve surrounding layout
✓ Show actionable recovery steps
✓ Consider automatic retry for network errors

Error boundaries prevent entire app crashes from component errors. Place them strategically around major sections, provide clear recovery options, and integrate with error reporting services. Use the react-error-boundary library for hooks support and advanced features.