useRef — cos'è, l'hook di riferimento e il lavoro con il DOM in React

Cos'è useRef in React

useRef è un hook aggiunto in React 16.8 che restituisce un oggetto ref mutabile con una singola proprietà .current. Il valore iniziale viene assegnato a .current al montaggio del componente. La differenza principale da una variabile normale è che l'oggetto ref sopravvive ai re-render: nei render successivi React non ricrea il ref ma restituisce lo stesso oggetto.

Internamente, useRef utilizza lo stesso meccanismo di useState e useEffect — una lista collegata di hook sul nodo fiber. Tuttavia, a differenza di useState, React non traccia le modifiche all'oggetto ref, non accoda aggiornamenti e non pianifica re-render. Questo rende useRef un hook estremamente leggero, senza impatto sulle prestazioni anche con modifiche frequenti.

Secondo il Team React — Hooks FAQ (2025), useRef è essenzialmente una “scatola” che memorizza un valore. Zucchero sintattico: const ref = useRef(valoreIniziale) equivale a const ref = { current: valoreIniziale } con la differenza che React garantisce che l'oggetto ref sarà lo stesso ad ogni render. Nessuna magia — solo un riferimento stabile gestito da React.

import { useRef } from 'react';

function Component() {
    const countRef = useRef(0);
    // countRef.current = 0 inizialmente
    // countRef.current = 5 dopo la mutazione
    // Nessun re-render si verifica!
}

Accesso agli elementi DOM con useRef

Il caso d'uso più comune di useRef è ottenere l'accesso diretto a un elemento DOM. React assegna a elementRef.current un riferimento al nodo DOM dopo il montaggio del componente. Ciò è necessario per focalizzare un input, misurare le dimensioni degli elementi, integrarsi con librerie di animazione e librerie che non utilizzano il rendering React.

React gestisce automaticamente i riferimenti ref al DOM: al montaggio assegna il nodo DOM effettivo, allo smontaggio lo annulla (lo imposta a null). Ciò garantisce che .current abbia sempre il valore aggiornato e previene perdite di memoria attraverso riferimenti pendenti a elementi rimossi. Non è richiesta pulizia manuale.

function AutoFocusInput() {
    const inputRef = useRef(null);

    useEffect(() => {
        // Focusare l'input dopo il montaggio del componente
        inputRef.current?.focus();
    }, []);

    return <input ref={inputRef} type="text" />;
}

Secondo la documentazione React — Refs e DOM (2025), non usare ref per operazioni dichiarative — aprire/chiudere modali, gestire la visibilità. Per questi scopi esistono state e props. Le ref sono destinate a operazioni imperative che non possono essere espresse dichiarativamente: focus, selezione di testo, integrazione con librerie di terze parti.

Memorizzare valori mutabili senza re-render

Il secondo caso d'uso più importante è la memorizzazione di valori arbitrari che devono persistere tra i render ma le cui modifiche non devono attivare un re-render. Esempi tipici: identificatori di timer (setInterval/setTimeout), flag di annullamento richieste, valori precedenti di props per confronto e qualsiasi dato che non influisca sull'output dell'interfaccia.

Ciò è particolarmente utile in useEffect: useRef memorizza l'identificatore del timer e la pulizia lo elimina. Se timerId fosse memorizzato in useState, ogni chiamata a setTimerId provocherebbe un re-render non necessario, non richiesto né per la logica né per l'interfaccia. useRef risolve questo problema senza overhead e senza re-render non necessari.

function Timer() {
    const intervalRef = useRef(null);

    const start = () => {
        intervalRef.current = setInterval(() => {
            console.log('tic');
        }, 1000);
    };

    const stop = () => {
        clearInterval(intervalRef.current);
    };

    useEffect(() => stop, []);

    return <><button onClick={start}>Start</button><button onClick={stop}>Stop</button></>;
}

useRef vs useState: quando usare cosa

Il dilemma principale — scegliere tra useRef e useState — si risolve con una domanda: “È necessario un re-render quando il valore cambia?”. Se sì — useState. Se no — useRef. useState memorizza lo stato che influenza l'output del componente; useRef memorizza i dati necessari per la logica interna ma che non influenzano l'interfaccia.

In pratica, gli sviluppatori usano spesso useRef per memorizzare callback al fine di evitare problemi con le chiusure. Ad esempio, se useEffect si iscrive a un evento e il callback necessita dello stato corrente — memorizza il callback in useRef. Ad ogni render, aggiorna ref.current con una nuova funzione, e l'effetto invocherà sempre il callback fresco senza doversi re-iscrivere.

Esiste un anti-pattern: usare useRef per dati necessari in JSX ma le cui modifiche non devono causare re-render. Ciò porta a desincronizzazione — l'interfaccia mostra dati vecchi mentre ref.current è già nuovo. Se il valore viene visualizzato nell'interfaccia — usa useState. Se usato solo internamente — useRef.

useRef in combinazione con useEffect

La combinazione useRef + useEffect è il modello standard per tracciare i valori precedenti delle props. Memorizza il valore precedente in ref, confrontalo con il valore corrente in useEffect e prendi decisioni basate sulla differenza. Ciò è particolarmente utile nelle animazioni quando hai bisogno di sapere quale valore aveva prima della modifica.

function PriceDisplay({ price }) {
    const prevPriceRef = useRef(price);

    useEffect(() => {
        const prevPrice = prevPriceRef.current;
        if (price > prevPrice) {
            animateUp();
        } else if (price < prevPrice) {
            animateDown();
        }
        prevPriceRef.current = price;
    }, [price]);

    return <span>${price}</span>;
}

Secondo la documentazione React — Hooks FAQ (2025), questo modello è chiamato “modello del valore precedente”. Funziona perché useRef conserva il valore tra i render e useEffect viene eseguito dopo la conferma delle modifiche. Prima il DOM viene aggiornato con il nuovo price, poi useEffect lo confronta con il precedente (ancora in ref) e aggiorna ref.current al valore corrente.

Errori comuni con useRef

L'errore più frequente è leggere ref.current durante la fase di render per calcolare JSX. Poiché modificare ref.current non attiva un re-render, il componente potrebbe utilizzare un valore obsoleto. Se .current partecipa all'output dell'interfaccia — usa useState. Se devi sincronizzare ref e state, usa useEffect per aggiornare lo state da ref.

• Ref in JSX — leggere ref.current all'interno di una funzione di render porta alla desincronizzazione tra interfaccia e dati.
• Ref come dipendenza di useEffect — ref.current non dovrebbe essere nell'array delle dipendenze; React non traccia le sue modifiche.
• Controllo null dimenticato — allo smontaggio ref.current diventa null; verifica prima di accedere.
• Memorizzare funzioni in ref — aggiorna ref.current ad ogni render se usi il modello del callback fresco.

// ❌ Non leggere ref.current durante il render per la visualizzazione
function BadComponent() {
    const valRef = useRef(0);
    return <p>{valRef.current}</p>; // NON verrà aggiornato alla mutazione
}

// ✅ Usa state per la visualizzazione, ref per la logica
function GoodComponent() {
    const [val, setVal] = useState(0);
    const valRef = useRef(0);
    return <p>{val}</p>;
}

Un altro errore comune è usare useRef come unico modo per memorizzare lo stato in un componente quando i dati influenzano effettivamente l'interfaccia. Gli sviluppatori scelgono useRef per evitare re-render “non necessari”, ma finiscono con un'interfaccia che non si aggiorna. L'approccio corretto: usa useState per i dati dell'interfaccia e useRef solo per valori ausiliari che non partecipano al rendering.