Hook useId

Gere um ID único e estável para atributos de acessibilidade que seja consistente entre servidor e cliente.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

const id = useId();
 
// Use para elementos de formulário acessíveis
<label htmlFor={id}>Email</label>
<input id={id} type="email" />
 
// Derive múltiplos IDs a partir de um
<label htmlFor={`${id}-first`}>Nome</label>
<input id={`${id}-first`} />
<label htmlFor={`${id}-last`}>Sobrenome</label>
<input id={`${id}-last`} />

Quando usar: Você precisa de um ID único para htmlFor, aria-labelledby, aria-describedby, ou qualquer atributo DOM que exija um ID - especialmente em SSR ou componentes reutilizáveis.

Exemplo de Trabalho

"use client";
 
import { useId, useState } from "react";
 
interface TextFieldProps {
  label: string;
  helpText?: string;
}
 
export function TextField({ label, helpText }: TextFieldProps) {
  const id = useId();
  const helpId = `${id}-help`;
  const [value, setValue] = useState("");
 
  return (
    <div className="space-y-1">
      <label htmlFor={id} className="block text-sm font-medium">
        {label}
      </label>
      <input
        id={id}
        value={value}
        onChange={(e) => setValue(e.target.value)}
        aria-describedby={helpText ? helpId : undefined}
        className="border rounded px-3 py-2 w-full"
      />
      {helpText && (
        <p id={helpId} className="text-xs text-gray-500">
          {helpText}
        </p>
      )}
    </div>
  );
}
 
export function SignupForm() {
  return (
    <form className="space-y-4 max-w-sm">
      <TextField label="Email" helpText="Nunca compartilharemos seu e-mail." />
      <TextField label="Senha" helpText="Pelo menos 8 caracteres." />
      <TextField label="Nome de usuário" />
    </form>
  );
}

O que isso demonstra:

• Cada instância de TextField obtém seu próprio ID único de useId
• O ID vincula <label> a <input> via htmlFor e vincula o texto de ajuda via aria-describedby
• Múltiplas instâncias do mesmo componente coexistem sem colisões de ID
• IDs são estáveis entre renderizações de servidor e cliente, evitando dessincronizações de hidratação

Mergulho Profundo

Como Funciona

• useId gera um ID baseado na posição do componente na árvore React
• O ID é determinístico - o mesmo componente na mesma posição na árvore sempre obtém o mesmo ID
• A string gerada inclui um caractere : (por exemplo, :r1:) para evitar colisões com IDs definidos pelo usuário
• No servidor, o React gera os mesmos IDs que no cliente, garantindo consistência na hidratação
• Múltiplas chamadas useId no mesmo componente produzem IDs diferentes

Parâmetros e Valores de Retorno

Variações

Listbox acessível:

function Listbox({ label, options }: ListboxProps) {
  const id = useId();
  const labelId = `${id}-label`;
  const listId = `${id}-list`;
 
  return (
    <div>
      <span id={labelId}>{label}</span>
      <ul id={listId} role="listbox" aria-labelledby={labelId}>
        {options.map((opt, i) => (
          <li key={opt.value} id={`${id}-option-${i}`} role="option">
            {opt.label}
          </li>
        ))}
      </ul>
    </div>
  );
}

identifierPrefix personalizado para micro-frontends:

// Em createRoot ou hydrateRoot
const root = createRoot(container, {
  identifierPrefix: "app1-",
});
// IDs gerados: ":app1-r1:", ":app1-r2:", etc.

Notas TypeScript

// useId sempre retorna uma string - nenhum genérico é necessário
const id: string = useId();
 
// Ao construir uma biblioteca de componentes, aceite um override opcional
interface InputProps {
  id?: string;
  label: string;
}
 
function Input({ id: propId, label }: InputProps) {
  const generatedId = useId();
  const inputId = propId ?? generatedId;
  return (
    <>
      <label htmlFor={inputId}>{label}</label>
      <input id={inputId} />
    </>
  );
}

Armadilhas

• Não use para chaves de lista - useId gera um único ID por chamada de hook, não por item da lista. Não é adequado para props key. Correção: Use chaves baseadas em dados (item.id) ou identificadores estáveis para chaves de lista.

• IDs contêm dois pontos - O formato do ID gerado (:r1:) inclui dois pontos, que são válidos em atributos id HTML, mas podem causar problemas com seletores CSS como #\:r1\:. Correção: Use seletores de atributo [id="valor"] ou escape os dois pontos em CSS.

• Não pode ser usado condicionalmente - Como todos os hooks, useId não pode ser chamado dentro de condições ou loops. Correção: Chame useId no nível superior e derive sub-IDs com concatenação de strings.

• Múltiplas raízes sem prefixo - Duas raízes React separadas na mesma página podem gerar IDs conflitantes. Correção: Use a opção identifierPrefix em createRoot ou hydrateRoot.

Alternativas

Por que não usar apenas um ID aleatório? IDs aleatórios gerados durante a renderização diferem entre servidor e cliente, causando dessincronizações de hidratação e avisos do React. useId resolve isso derivando IDs da árvore de componentes.

FAQs

const id = useId();
const nameId = `${id}-name`;
const emailId = `${id}-email`;
const helpId = `${id}-help`;

const root = createRoot(container, { identifierPrefix: "app1-" });
// IDs: ":app1-r1:", ":app1-r2:", etc.

// useId sempre retorna string -- nenhum genérico é necessário
const id: string = useId();

interface InputProps {
  id?: string;
  label: string;
}
 
function Input({ id: propId, label }: InputProps) {
  const generatedId = useId();
  const inputId = propId ?? generatedId;
  return (
    <>
      <label htmlFor={inputId}>{label}</label>
      <input id={inputId} />
    </>
  );
}

Relacionado

• useRef - acesse elementos DOM diretamente sem IDs
• Custom Hooks - crie primitivas de formulário acessíveis usando useId
• use - primitivas do React 19 que funcionam em conjunto com useId