Hook useId

Genera una ID única y estable para atributos de accesibilidad que sea consistente entre servidor y cliente.

Receta

Tarjeta de referencia rápida - lista para copiar y pegar.

const id = useId();
 
// Usa para elementos de formulario accesibles
<label htmlFor={id}>Email</label>
<input id={id} type="email" />
 
// Deriva múltiples IDs de una
<label htmlFor={`${id}-first`}>First Name</label>
<input id={`${id}-first`} />
<label htmlFor={`${id}-last`}>Last Name</label>
<input id={`${id}-last`} />

Cuándo usarlo: Necesitas una ID única para htmlFor, aria-labelledby, aria-describedby, o cualquier atributo DOM que requiera una ID - especialmente en SSR o componentes reutilizables.

Ejemplo Funcional

"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="We'll never share your email." />
      <TextField label="Password" helpText="At least 8 characters." />
      <TextField label="Username" />
    </form>
  );
}

Lo que demuestra esto:

• Cada instancia de TextField obtiene su propia ID única de useId
• La ID vincula <label> a <input> mediante htmlFor y vincula el texto de ayuda mediante aria-describedby
• Múltiples instancias del mismo componente coexisten sin colisiones de IDs
• Las IDs son estables entre renderizados de servidor y cliente, evitando desincronización de hidratación

Exploración Profunda

Cómo Funciona

• useId genera una ID basada en la posición del componente en el árbol de React
• La ID es determinística - el mismo componente en la misma posición del árbol siempre obtiene la misma ID
• La cadena generada incluye un carácter : (por ejemplo, :r1:) para evitar colisiones con IDs definidas por el usuario
• En el servidor, React genera las mismas IDs que en el cliente, asegurando consistencia de hidratación
• Múltiples llamadas a useId en el mismo componente producen diferentes IDs

Parámetros y Valores de Retorno

Variaciones

Listbox accesible:

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:

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

Notas de TypeScript

// useId siempre devuelve una cadena - no se necesita genérico
const id: string = useId();
 
// Al construir una librería de componentes, acepta una ID opcional para sobrescribir
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} />
    </>
  );
}

Trampas

• No uses para keys de lista - useId genera una única ID por llamada de hook, no por elemento de lista. No es adecuado para props key. Solución: Usa keys impulsadas por datos (item.id) o identificadores estables para keys de lista.

• Las IDs contienen dos puntos - El formato de ID generado (:r1:) incluye dos puntos, que son válidos en atributos id HTML pero pueden causar problemas con selectores CSS como #\:r1\:. Solución: Usa selectores de atributo [id="value"] o escapa los dos puntos en CSS.

• No se puede usar condicionalmente - Como todos los hooks, useId no se puede llamar dentro de condiciones o loops. Solución: Llama a useId al nivel superior y deriva sub-IDs con concatenación de cadenas.

• Múltiples raíces sin prefijo - Dos raíces React separadas en la misma página pueden generar IDs en conflicto. Solución: Usa la opción identifierPrefix en createRoot o hydrateRoot.

Alternativas

¿Por qué no solo usar una ID aleatoria? Las IDs aleatorias generadas durante el renderizado difieren entre servidor y cliente, causando desincronización de hidratación y advertencias de React. useId resuelve esto derivando IDs de la posición del árbol 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 siempre devuelve cadena -- no se necesita genérico
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 - accede a elementos DOM directamente sin IDs
• Custom Hooks - construye primitivas de formulario accesibles usando useId
• use - primitivas de React 19 que funcionan junto a useId