L'hook useRef di React: ref al DOM e valori persistenti

useRef restituisce un oggetto, { current: initialValue }, che React conserva per tutta la vita del componente. Cambiare ref.current non provoca alcun nuovo render. Questo rende i ref adatti a due compiti: tenere un nodo DOM così da poterci chiamare metodi come focus(), e ricordare tra un rendering e l'altro un valore che lo schermo non ha bisogno di mostrare.

import { useRef } from 'react';

export default function App() {
    const inputRef = useRef(null);

    function handleClick() {
        inputRef.current.focus();
        console.log('focused:', inputRef.current.tagName);
    }

    return (
        <div>
            <input ref={inputRef} placeholder="Click the button" />{' '}
            <button onClick={handleClick}>Focus the input</button>
        </div>
    );
}

Passare l'oggetto ref a ref={inputRef} dice a React di mettere il nodo DOM dell'<input> in inputRef.current. Cambia focus() in select(), scrivi qualcosa e clicca di nuovo: il testo viene evidenziato.

La sintassi

const myRef = useRef(initialValue);

myRef.current;          // read
myRef.current = value;  // write, no re-render

• initialValue viene usato solo al primo rendering. Per i ref al DOM è null.
• React restituisce lo stesso oggetto a ogni rendering. Cambia solo current.
• Leggere e scrivere current è normale JavaScript. React non lo traccia.

Un valore che non provoca rendering

Lo stato serve per ciò che lo schermo mostra. Un ref serve per ciò che il componente deve ricordare ma non mostrare. Questo blocco tiene un contatore in un ref e uno nello stato, e li registra entrambi:

import { useRef, useState } from 'react';

export default function App() {
    const clicks = useRef(0);
    const [renders, setRenders] = useState(0);

    console.log('render: ref =', clicks.current, ', state =', renders);

    function addToRef() {
        clicks.current = clicks.current + 1;
        console.log('ref.current is now', clicks.current, '(no render)');
    }

    return (
        <div>
            <p>Ref counter: {clicks.current}</p>
            <p>State counter: {renders}</p>
            <button onClick={addToRef}>Ref + 1</button>{' '}
            <button onClick={() => setRenders(renders + 1)}>State + 1</button>
        </div>
    );
}

Clicca Ref + 1 qualche volta. La console mostra ref.current che sale, ma la pagina dice ancora 0 e non viene registrato alcun rendering. Ora clicca State + 1: il componente si renderizza, e il contatore del ref sullo schermo salta al numero che il ref conteneva già. Il ref ha mantenuto il suo valore per tutto il tempo; React semplicemente non aveva motivo di disegnarlo.

Ref vs stato

Se hai dubbi, chiediti se il JSX legge il valore. Se lo legge, va nello stato.

Memorizzare l'id di un timer

setInterval restituisce un id che ti serve più tardi per fermare il timer. È perfetto per un ref: il gestore Stop ne ha bisogno, ma lo schermo non lo mostra mai, e tenerlo in una semplice variabile lo perderebbe al rendering successivo.

import { useRef, useState } from 'react';

export default function App() {
    const [seconds, setSeconds] = useState(0);
    const intervalRef = useRef(null);

    function start() {
        if (intervalRef.current !== null) return;
        intervalRef.current = setInterval(() => setSeconds((s) => s + 1), 1000);
        console.log('started timer', intervalRef.current);
    }

    function stop() {
        clearInterval(intervalRef.current);
        console.log('stopped timer', intervalRef.current);
        intervalRef.current = null;
    }

    return (
        <div>
            <p>{seconds} s</p>
            <button onClick={start}>Start</button>{' '}
            <button onClick={stop}>Stop</button>
        </div>
    );
}

Sostituisci useRef(null) con let intervalRef = { current: null }; e prova Start, aspetta due secondi, poi Stop: il timer continua. Ogni tick renderizza il componente, che crea un oggetto nuovo, quindi Stop non cancella nulla.

Ricordare il valore precedente

Un effetto viene eseguito dopo il rendering, quindi può confrontare il nuovo valore con quello memorizzato in un ref, e poi salvare quello nuovo per la volta successiva:

import { useEffect, useRef, useState } from 'react';

export default function App() {
    const [color, setColor] = useState('red');
    const previous = useRef(null);

    useEffect(() => {
        if (previous.current !== null) {
            console.log('changed from', previous.current, 'to', color);
        }
        previous.current = color;
    }, [color]);

    return (
        <div>
            {['red', 'green', 'blue'].map((c) => (
                <button key={c} onClick={() => setColor(c)}>{c}</button>
            ))}
            <p style={{ color }}>The color is {color}</p>
        </div>
    );
}

Clicca green, poi blue: la console registra changed from red to green e changed from green to blue. Cliccare il colore già selezionato non registra nulla, perché l'effetto viene eseguito solo quando color cambia.

Lavorare con il DOM

I ref sono il modo per chiamare API del browser per cui React non ha una prop: focus(), select(), scrollIntoView(), play() su un video, oppure leggere una dimensione con getBoundingClientRect().

const lastItemRef = useRef(null);

function scrollToLast() {
    lastItemRef.current.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
}

<li ref={lastItemRef}>Last item</li>

ref.current è null durante il primo rendering, perché React non ha ancora creato il nodo DOM, e di nuovo dopo che l'elemento è stato rimosso. Leggilo nei gestori di eventi e negli effetti, dove il nodo esiste. Per misurare un elemento e posizionare qualcosa prima che il browser disegni la pagina, leggi il ref in useLayoutEffect.

Non leggere né scrivere ref.current durante il rendering

React si aspetta che il corpo del componente sia un calcolo puro: stesse props e stesso stato, stesso JSX. Un ref cambia al di fuori di questo modello, quindi un rendering che lo legge o lo scrive può mostrare risultati diversi per gli stessi input, e React potrebbe chiamare il corpo più spesso di quanto ti aspetti.

function Bad() {
    const count = useRef(0);
    count.current++;              // writing during render
    return <p>{count.current}</p>; // reading during render
}

Leggi e scrivi i ref nei gestori di eventi e negli effetti. L'unica eccezione è l'inizializzazione lazy, in cui riempi il ref una volta al primo rendering:

const playerRef = useRef(null);
if (playerRef.current === null) {
    playerRef.current = new VideoPlayer(); // runs once
}

(La demo del contatore con ref qui sopra legge clicks.current nel JSX di proposito, per mostrare che lo schermo non lo segue. Non copiarlo nel codice reale.)

Ref callback

Invece di un oggetto ref, puoi passare una funzione a ref. React la chiama con il nodo DOM quando l'elemento viene aggiunto. In React 19 la funzione può restituire una funzione di cleanup, che React chiama quando l'elemento viene rimosso. È comodo per una lista, dove non puoi chiamare useRef una volta per ogni voce:

import { useState } from 'react';

function trackNode(node) {
    console.log('attached', node.textContent);
    return () => console.log('detached', node.textContent);
}

export default function App() {
    const [items, setItems] = useState(['Apples', 'Bread', 'Cheese']);

    return (
        <div>
            <button onClick={() => setItems(items.slice(0, -1))}>Remove last</button>
            <ul>
                {items.map((item) => (
                    <li key={item} ref={trackNode}>{item}</li>
                ))}
            </ul>
        </div>
    );
}

Al caricamento la console registra una riga attached per ogni voce. Clicca Remove last e compare solo detached Cheese. trackNode è definita fuori dal componente, quindi è la stessa funzione a ogni rendering e React lascia stare le altre voci. Scrivila invece in linea come ref={(node) => { ... }} e ogni clic stacca e riattacca ogni voce, perché ogni rendering passa una funzione nuova.

Passare un ref al tuo componente

In React 19, ref è una prop normale per i function component. Il genitore crea il ref, e il figlio lo mette sull'elemento DOM che vuole esporre:

import { useRef } from 'react';

function SearchInput({ ref, ...props }) {
    return <input ref={ref} {...props} style={{ padding: 6 }} />;
}

export default function App() {
    const searchRef = useRef(null);

    return (
        <div>
            <SearchInput ref={searchRef} placeholder="Search" />{' '}
            <button onClick={() => searchRef.current.focus()}>Focus search</button>
        </div>
    );
}

Prima di React 19 questo richiedeva forwardRef, che funziona ancora. La pagina su forwardRef mostra entrambe le versioni e come esporre solo alcuni metodi con useImperativeHandle.

Errori comuni

Mostrare il valore di un ref nel JSX. Lo schermo non lo segue. Se l'utente deve vedere il valore, usa lo stato.

Usare ref.current come dipendenza di un effetto. [ref.current] legge il valore durante il rendering e React non sa quando cambia, quindi l'effetto non viene rieseguito quando succede. Usa un ref callback per reagire al collegamento di un nodo.

Leggere un ref al DOM durante il primo rendering. È null finché React non ha creato il nodo. Leggilo in un effetto o in un gestore.

Creare un nuovo oggetto invece di usare l'hook. const ref = { current: null } nel corpo del componente è un oggetto nuovo a ogni rendering. Solo useRef ti dà ogni volta lo stesso.