Hook useId: Identificadores Únicos para Acessibilidade WAI-ARIA e Hidratação SSR
Hook useId: Identificadores Únicos para Acessibilidade WAI-ARIA e Hidratação SSR
Vincular rótulos a campos de formulário e conectar descrições de acessibilidade via atributos ARIA exige identificadores id rigorosamente únicos no DOM. Descubra como o hook useId gera identificadores estáveis sem colisões e resolve de forma definitiva o pesadelo dos erros de divergência de hidratação (Hydration Mismatch) em aplicações com Server-Side Rendering (SSR).
📑 Índice do Conteúdo
1. O Dilema Histórico dos IDs em Componentes Reutilizáveis
Em HTML semântico e normas de acessibilidade (a11y), atributos id são obrigatórios para conectar elementos:
- Vincular
<label htmlFor="email">ao seu respectivo<input id="email">. - Conectar mensagens de ajuda e erros com
aria-describedby="hint-id error-id". - Vincular títulos de diálogos modais com
aria-labelledby="dialog-title".
O Problema dos IDs Fixos (Hardcoded)
Se você fixar uma string como id="user-email" dentro de um componente reutilizável:
// ❌ PROBLEMA: Componente com ID fixo
function EmailField() {
return (
<div>
<label htmlFor="email-input">E-mail:</label>
<input id="email-input" />
</div>
);
}
// Se a página renderizar dois componentes EmailField (ex: Newsletter no topo e no rodapé):
// O DOM terá DOIS elementos com id="email-input"!
// Clicar no label do rodapé moverá o cursor para o input do topo! (Quebra grave de usabilidade)
Por que Math.random() ou Contadores Globais Quebram o SSR?
Tentativas de contornar isso com Math.random() ou contadores globais (let idCounter = 0) geram erros fatais de Hydration Mismatch em frameworks como Next.js e Remix. O servidor gera um ID (ex: "input-1") e o cliente no navegador gera outro (ex: "input-5"). O React acusa incompatibilidade entre o HTML renderizado no servidor e o código do cliente!
2. A Solução do React 18+: O Hook useId
Introduzido no React 18, o hook useId gera identificadores estáveis e únicos calculados a partir da posição exata do nó na árvore de componentes (árvore Fiber):
import { useId } from 'react';
function EmailField() {
// Retorna uma string segura e estável, como ':r1:' ou ':r2:'
const id = useId();
return (
<div>
<label htmlFor={id}>Seu E-mail:</label>
<input id={id} type="email" />
</div>
);
}
useId utiliza a hierarquia de nós na árvore Fiber para compor a string, o código executado no servidor Node.js e a hidratação no navegador do cliente calculam rigorosamente a mesma string (ex: :r0:), eliminando 100% dos avisos de mismatch de hidratação!
3. O Padrão de Sufixos Derivados para Múltiplos Elementos
Quando um único componente possui vários campos relacionados (como rótulo, input, dica e mensagem de erro), não chame useId várias vezes. A melhor prática corporativa é invocar o hook uma única vez e derivar identificadores adicionando sufixos:
import { useId } from 'react';
export function AccessibleTextField({ label, helperText, errorMessage }) {
// 1. Invoca o hook uma única vez
const id = useId();
const inputId = `${id}-input`;
const hintId = `${id}-hint`;
const errorId = `${id}-error`;
return (
<div className="form-field">
<label htmlFor={inputId}>{label}</label>
<input
id={inputId}
aria-describedby={`${hintId} ${errorMessage ? errorId : ''}`}
aria-invalid={Boolean(errorMessage)}
/>
<span id={hintId} className="helper-text">
{helperText}
</span>
{errorMessage && (
<span id={errorId} className="error-message" role="alert">
{errorMessage}
</span>
)}
</div>
);
}
4. O Que o useId NÃO DEVE Ser Usado Para Fazer (Antipadrões)
| Uso Permitido & Recomendado | Antipadrão Proibido (Evite useId) |
|---|---|
Conectar <label htmlFor> com <input id>. |
NUNCA use useId para gerar chaves (key) em listas de .map()! As chaves devem vir dos dados do banco ou array (ex: item.id). |
Atributos ARIA (aria-labelledby, aria-describedby, aria-controls). |
Não use IDs gerados por useId como seletores CSS em folhas de estilo (a sintaxe com dois-pontos :r0: exige escape especial no CSS). |
| Comunicação e vinculação de Tabs, Modais, Drawers e Tooltips acessíveis. | Não use useId como chave primária de registros em requisições de banco de dados. |
5. Laboratório Prático: Simulador de Acessibilidade e SSR com useId
No laboratório interativo abaixo, teste na prática o problema da colisão de IDs. Veja dois formulários idênticos renderizados na mesma página: o formulário da esquerda usa IDs fixos (clicar no rótulo de baixo rouba o foco do campo de cima!), enquanto o formulário da direita utiliza o useId com sufixos derivados, garantindo foco isolado e conformidade com o validador de hidratação SSR!
Aplique o que você aprendeu nesta lição
Utilize nossas ferramentas online gratuitas para experimentar os conceitos ou teste o código ao vivo no Playground IDE.
Editor de Códigos Web Online
Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.
Abrir Ferramenta OnlinePlayground Web Online
Escreva seu código HTML, CSS ou JavaScript e veja o resultado renderizado ao vivo no navegador com zero configuração.
⚡ Codificar no Playground IDE