Estado de erro

Estado de erro com anúncio acessível (role=alert), mensagem explicativa e ação de recuperação (onRetry ou ação personalizada). No código: error-state — src/components/error-state.tsx · Feedback e estados

Quando usar

Quando uma seção ou página inteira falhar ao carregar dados remotos (erro 500, timeout 504, erro de rede ou falha de sincronização) e existir uma possibilidade de recuperação pelo próprio usuário (ex.: tentar novamente).

Quando não usar

Para validação de campos de formulário (use FormField e ErrorSummary). Para avisos flutuantes temporários (use Toast). Para estados normais em que a busca simplesmente não retornou registros (use EmptyState).

Acessibilidade

  • Usa role="alert" e aria-live="assertive" para anunciar imediatamente a falha aos leitores de tela.
  • O ícone decorativo possui aria-hidden="true" para não poluir a leitura.
  • Não depende apenas de cor: conta com título explícito, ícone de alerta e mensagem textual clara com instrução de como proceder.
  • Ação de recuperação (onRetry ou action) é sempre um botão ou elemento focável e acionável por teclado (Enter/Espaço).

Props

PropTipoDescrição
titlestringTítulo principal descrevendo a falha de forma clara e direta.
descriptionstringExplicação complementar da causa e orientação de ação para o usuário.
onRetry() => voidCallback disparado ao clicar no botão de tentar novamente.
retryLabelstringTexto do botão de tentar novamente (padrão: "Tentar novamente").
variant"default" | "inline"default para páginas ou blocos principais; inline para cards e tabelas.
iconReactNodeÍcone customizado opcional. Por padrão exibe AlertCircle.
actionReactNodeElemento ou botão de ação customizado em substituição ao botão padrão de retry.

Preview

Variantes e composição

Prop / grupoValores
variantdefault · inline
propstitle · description · icon · action · onRetry · retryLabel · variant · titleAs (padrão h3; p no inline)
a11yrole=alert · aria-live=assertive · ícones com aria-hidden

Uso

Fonte do componente