Error Boundary no React: Como Usar e Evitar Tela Branca

Error Boundary no React: Como Usar e Evitar Tela Branca

Um error boundary no React é um componente que captura erros de JavaScript ocorridos durante a renderização de seus filhos e exibe uma interface alternativa (fallback) em vez de deixar a aplicação inteira quebrar. Sem ele, um único erro em um componente pode desmontar toda a árvore e deixar o usuário diante de uma tela branca.

Se você cria sites e sistemas com React, Vite e Supabase, esse é um dos recursos mais baratos de implementar e que mais protege a experiência do usuário em produção.

O que é um error boundary e por que ele importa

Por padrão, quando um componente React lança um erro durante a renderização, o React desmonta a árvore inteira. Para o usuário, isso aparece como uma página em branco, sem explicação e sem saída.

O error boundary funciona como um try/catch para a interface. Ele isola a falha em uma parte da tela e mantém o resto funcionando.

Os benefícios principais são:

• Evitar a tela branca em produção.
• Mostrar uma mensagem amigável e um botão para tentar de novo.
• Registrar o erro em uma ferramenta de monitoramento.
• Isolar falhas em widgets, listas ou gráficos sem afetar a página toda.

Como criar um error boundary com classe

A documentação oficial do React descreve o error boundary como um componente de classe que implementa getDerivedStateFromError e, opcionalmente, componentDidCatch. Ainda hoje não existe um equivalente com hooks para essa função.

import { Component } from "react";

class ErrorBoundary extends Component {
  state = { hasError: false };

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

  componentDidCatch(error, info) {
    console.error("Erro capturado:", error, info.componentStack);
  }

  render() {
    if (this.state.hasError) {
      return <p>Algo deu errado. Tente recarregar a página.</p>;
    }
    return this.props.children;
  }
}

Para usar, basta envolver a parte da interface que você quer proteger:

<ErrorBoundary>
  <DashboardChart />
</ErrorBoundary>

Usando a biblioteca react-error-boundary

Na prática, a maioria dos projetos usa o pacote react-error-boundary, que entrega um componente pronto, sem precisar escrever classe. Ele oferece fallback customizado, botão de reset e callback para registrar erros.

import { ErrorBoundary } from "react-error-boundary";

function Fallback({ error, resetErrorBoundary }) {
  return (
    <div role="alert">
      <p>Não foi possível carregar este bloco.</p>
      <button onClick={resetErrorBoundary}>Tentar novamente</button>
    </div>
  );
}

<ErrorBoundary FallbackComponent={Fallback} onError={logToService}>
  <DashboardChart />
</ErrorBoundary>

O botão de reset é o que transforma um erro em uma experiência recuperável: o usuário tenta de novo sem recarregar a página inteira.

Onde posicionar os error boundaries

Um único boundary na raiz evita a tela branca, mas esconde tudo. Uma estratégia melhor usa camadas:

1. Boundary global: envolve o app inteiro, como última rede de segurança.
2. Boundary por rota: se uma página falha, a navegação e o layout continuam funcionando.
3. Boundary por widget: gráficos, listas e blocos que dependem de dados externos ficam isolados.

Em apps com Vite e React Router, o boundary por rota combina bem com código carregado sob demanda (lazy loading), já que falhas de carregamento de chunk também podem ser tratadas ali.

O que o error boundary não captura

Esse é um ponto que gera muita confusão. Segundo a documentação do React, error boundaries não capturam erros em:

• Event handlers (como onClick), que exigem try/catch próprio.
• Código assíncrono, como setTimeout e fetch com async/await.
• Renderização no servidor (SSR).
• Erros lançados dentro do próprio error boundary.

Para chamadas ao Supabase, por exemplo, trate o erro retornado pela requisição e mostre o estado de erro na interface. Se quiser que o boundary capture um erro assíncrono, uma técnica comum é guardar o erro no estado e relançá-lo durante a renderização.

Novidades do React 19 para tratamento de erros

O React 19 adicionou as opções onCaughtError, onUncaughtError e onRecoverableError ao criar a raiz com createRoot. Elas centralizam o registro de erros: onCaughtError recebe os erros tratados por um error boundary, e onUncaughtError recebe os que não foram capturados por nenhum. Isso facilita enviar tudo para uma ferramenta de monitoramento como o Sentry em um único ponto.

Perguntas Frequentes

O que é um error boundary no React? É um componente que captura erros de renderização nos seus filhos e exibe uma interface de fallback, evitando que a aplicação inteira quebre e fique com tela branca.

Posso criar um error boundary com function component e hooks? Não diretamente. A API oficial exige um componente de classe. A alternativa prática é usar a biblioteca react-error-boundary, que oferece um componente pronto para uso em projetos com hooks.

Error boundary captura erros de fetch e de eventos de clique? Não. Erros em event handlers e em código assíncrono precisam de try/catch próprio ou de tratamento do estado de erro, por exemplo nas respostas do Supabase.

Quantos error boundaries devo usar? Vários, em camadas: um global como rede de segurança, um por rota e outros em blocos críticos que dependem de dados externos.

Conclusão

Adicionar um error boundary no React leva poucos minutos e muda a forma como seu app falha: em vez de uma tela branca, o usuário vê uma mensagem clara e uma chance de tentar de novo. Comece por um boundary global e outro por rota, e evolua para widgets críticos.

Na Stormcore, criamos sites, sistemas e automações com React e Supabase pensando justamente nesse tipo de robustez, para que o projeto continue de pé mesmo quando algo inesperado acontece.