L'hook useId di React: id univoci per label e ARIA

useId restituisce un id univoco per ogni istanza di un componente, e lo stesso id a ogni rendering. Usalo per collegare una <label> al suo <input>, o un input al suo suggerimento tramite aria-describedby, quando il componente può comparire più di una volta in una pagina.

import { useId } from 'react';

function PasswordField({ label }) {
    const id = useId();
    const hintId = `${id}-hint`;
    return (
        <div style={{ marginBottom: 16 }}>
            <label htmlFor={id}>{label}</label>
            <br />
            <input id={id} type="password" aria-describedby={hintId} />
            <p id={hintId} style={{ margin: '4px 0', fontSize: 13, color: '#666' }}>
                At least 12 characters.
            </p>
            <code style={{ fontSize: 12 }}>
                id = {id}, hint id = {hintId}
            </code>
        </div>
    );
}

export default function App() {
    return (
        <form>
            <PasswordField label="Password" />
            <PasswordField label="Confirm password" />
        </form>
    );
}

Lo stesso componente viene renderizzato due volte e riceve due id diversi, stampati sotto ogni campo. Clicca il testo "Confirm password" e il focus salta al secondo input, perché il suo htmlFor corrisponde solo all'id di quell'input. Scrivi direttamente id="password" al posto di useId() ed entrambe le label puntano al primo input.

La sintassi

const id = useId();

useId non accetta argomenti e restituisce una stringa. Chiamalo al livello più alto del componente, come ogni hook. Il suo formato esatto è interno ed è cambiato tra una versione e l'altra: React 18 produceva :r1:, e React 19.2 produce _r_1_ per un componente renderizzato per la prima volta nel browser e un id che inizia con _R_, costruito dalla posizione nell'albero, per uno renderizzato sul server. Non analizzarlo mai e non fare affidamento sulla sua forma.

Perché non Math.random o un contatore

Gli id per l'accessibilità devono coincidere tra l'HTML che il server invia e l'albero che React costruisce nel browser. I due modi ovvi di creare un id falliscono entrambi questa prova.

// Changes on every render, and differs between server and browser
const id = 'field-' + Math.random().toString(36).slice(2);

// The server's counter keeps growing across requests, the browser starts at 0
let nextId = 0;
const id = 'field-' + nextId++;

Con il rendering lato server (Next.js, la modalità framework di React Router, qualsiasi configurazione con hydrateRoot), il server stampa id="field-4817" nell'HTML, il primo rendering del browser calcola field-0, e React segnala un hydration mismatch. useId costruisce l'id dalla posizione del componente nell'albero, che è identica da entrambe le parti.

Anche senza un server, un id costruito durante il rendering può cambiare a ogni rendering. Questo esempio mostra la differenza senza alcun server coinvolto:

import { useId, useState } from 'react';

let nextId = 0;

function Field({ label }) {
    const stable = useId();
    const unstable = `field-${nextId++}`;
    console.log(label, 'useId:', stable, '| counter:', unstable);
    return (
        <p>
            <label htmlFor={stable}>{label}</label> <input id={stable} />
            <br />
            <small>useId: {stable}, counter: {unstable}</small>
        </p>
    );
}

export default function App() {
    const [renders, setRenders] = useState(0);
    return (
        <div>
            <button onClick={() => setRenders(renders + 1)}>Render again ({renders})</button>
            <Field label="Name" />
            <Field label="Email" />
        </div>
    );
}

Clicca il pulsante qualche volta. Il valore di useId resta fermo mentre l'id del contatore sale a ogni rendering, quindi qualsiasi cosa puntasse al vecchio id (un aria-describedby, una label) ora non punta a nulla. Racchiudere il contatore in useState(() => nextId++) risolverebbe i nuovi render ma non la discrepanza con il server.

Più id da una sola chiamata

Un componente con più campi non ha bisogno di più chiamate a useId. Genera una sola base e aggiungi un suffisso per ogni elemento.

import { useId, useState } from 'react';

function SignupForm() {
    const id = useId();
    const [email, setEmail] = useState('');
    const invalid = email !== '' && !email.includes('@');

    return (
        <form onSubmit={(e) => e.preventDefault()}>
            <p>
                <label htmlFor={`${id}-name`}>Name</label>{' '}
                <input id={`${id}-name`} />
            </p>
            <p>
                <label htmlFor={`${id}-email`}>Email</label>{' '}
                <input
                    id={`${id}-email`}
                    value={email}
                    onChange={(e) => setEmail(e.target.value)}
                    aria-invalid={invalid}
                    aria-describedby={invalid ? `${id}-error` : undefined}
                />
            </p>
            {invalid && (
                <p id={`${id}-error`} style={{ color: '#c0392b' }}>
                    An email needs an @.
                </p>
            )}
            <small>Base id: {id}</small>
        </form>
    );
}

export default function App() {
    return <SignupForm />;
}

Scrivi una parola senza @ nel campo email: compare l'errore e l'aria-describedby dell'input punta a esso, così uno screen reader legge l'errore quando l'input riceve il focus. Renderizza <SignupForm /> due volte in App e ogni copia riceve il proprio id di base.

Non per le key delle liste

Key e id risolvono problemi diversi. Una key dice a React quale voce è quale tra un rendering e l'altro, quindi deve arrivare dai dati. useId dà un id per ogni istanza di componente, e non puoi chiamarlo dentro map.

// Wrong: breaks the rules of hooks, and the key is unrelated to the item
{todos.map((todo) => <Todo key={useId()} todo={todo} />)}

// Right: the key comes from the data
{todos.map((todo) => <Todo key={todo.id} todo={todo} />)}

Quando i tuoi dati non hanno un id, creane uno quando la voce viene creata (crypto.randomUUID() nel gestore di eventi che la aggiunge), non durante il rendering. La pagina su liste e key spiega perché la key deve restare con la sua voce.

Più root React in una pagina

Se due app React separate vengono renderizzate nella stessa pagina, i loro id potrebbero entrare in conflitto. Dai a ogni root un prefisso:

createRoot(document.getElementById('cart'), { identifierPrefix: 'cart-' });
createRoot(document.getElementById('chat'), { identifierPrefix: 'chat-' });

Con il rendering lato server, passa lo stesso identifierPrefix al renderer del server e a hydrateRoot così entrambe le parti producono gli stessi id.

Errori comuni

Renderizzare un albero diverso sul server e nel browser. useId dipende dalla posizione del componente, quindi un ramo come typeof window === 'undefined' ? <A /> : <B /> sopra un campo può spostare gli id tra i due rendering. Mantieni l'albero uguale durante l'hydration e cambialo dopo, in un effetto.

Cercare l'elemento tramite il suo id. document.getElementById(id) funziona, ma un ref è il modo React per raggiungere un nodo DOM e non ha bisogno di alcun id.

Usarlo come valore casuale. L'id è univoco all'interno dell'app, non casuale, ed è prevedibile a partire dall'albero. Non usarlo per token di sicurezza, chiavi di cache o qualsiasi cosa memorizzata tra una sessione e l'altra.

Quando usarlo

Usa useId ogni volta che un componente riutilizzabile ha bisogno di un attributo id: campi di form costruiti da un componente usato molte volte, un tooltip collegato con aria-describedby, una finestra di dialogo con aria-labelledby, schede con aria-controls. Quando un id collega solo una label al suo input, puoi anche fare a meno dell'id e annidare l'input dentro la label (<label>Name <input /></label>); usa useId quando gli elementi non possono essere annidati.