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).
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
| Prop | Tipo | Descrição |
|---|---|---|
title | string | Título principal descrevendo a falha de forma clara e direta. |
description | string | Explicação complementar da causa e orientação de ação para o usuário. |
onRetry | () => void | Callback disparado ao clicar no botão de tentar novamente. |
retryLabel | string | Texto 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. |
icon | ReactNode | Ícone customizado opcional. Por padrão exibe AlertCircle. |
action | ReactNode | Elemento ou botão de ação customizado em substituição ao botão padrão de retry. |
Preview
Variantes e composição
| Prop / grupo | Valores |
|---|---|
variant | default · inline |
props | title · description · icon · action · onRetry · retryLabel · variant · titleAs (padrão h3; p no inline) |
a11y | role=alert · aria-live=assertive · ícones com aria-hidden |