Hook useRef w React: refy do DOM i trwałe wartości

useRef zwraca obiekt, { current: initialValue }, który React przechowuje przez cały czas życia komponentu. Zmiana ref.current niczego nie renderuje ponownie. Dlatego refy nadają się do dwóch zadań: trzymania węzła DOM, żeby wywoływać na nim metody takie jak focus(), i zapamiętywania między renderowaniami wartości, której ekran nie musi pokazywać.

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>
    );
}

Przekazanie obiektu refa do ref={inputRef} mówi Reactowi, żeby umieścił węzeł DOM <input> w inputRef.current. Zmień focus() na select(), wpisz coś i kliknij ponownie: tekst zostanie zaznaczony.

Składnia

const myRef = useRef(initialValue);

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

• initialValue jest używane tylko przy pierwszym renderowaniu. Dla refów do DOM jest to null.
• React zwraca ten sam obiekt przy każdym renderowaniu. Zmienia się tylko current.
• Odczyt i zapis current to zwykły JavaScript. React tego nie śledzi.

Wartość, która nie powoduje renderowania

Stan służy do tego, co pokazuje ekran. Ref służy do tego, co komponent musi pamiętać, ale nie wyświetla. Ten blok trzyma jeden licznik w refie, a drugi w stanie, i wypisuje oba:

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>
    );
}

Kliknij kilka razy Ref + 1. Konsola pokazuje, że ref.current rośnie, ale strona wciąż pokazuje 0 i nie ma logu renderowania. Teraz kliknij State + 1: komponent się renderuje, a licznik refa na ekranie skacze do liczby, którą ref już miał. Ref cały czas trzymał swoją wartość; React po prostu nie miał powodu jej narysować.

Refy a stan

Jeśli masz wątpliwości, sprawdź, czy JSX czyta tę wartość. Jeśli tak, należy do stanu.

Przechowywanie ID timera

setInterval zwraca ID, którego potrzebujesz później, żeby zatrzymać timer. Dobrze pasuje do refa: handler Stop go potrzebuje, ale ekran nigdy go nie pokazuje, a trzymanie go w zwykłej zmiennej zgubiłoby je przy następnym renderowaniu.

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>
    );
}

Zastąp useRef(null) przez let intervalRef = { current: null };, kliknij Start, odczekaj dwie sekundy, a potem Stop: timer działa dalej. Każde tyknięcie renderuje komponent, co tworzy świeży obiekt, więc Stop niczego nie czyści.

Zapamiętywanie poprzedniej wartości

Efekt uruchamia się po renderowaniu, więc może porównać nową wartość z tą zapisaną w refie, a potem zapisać nową na następny raz:

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>
    );
}

Kliknij green, potem blue: konsola wypisuje changed from red to green i changed from green to blue. Kliknięcie koloru, który już jest wybrany, niczego nie wypisuje, bo efekt uruchamia się tylko wtedy, gdy zmienia się color.

Praca z DOM

Refy pozwalają wywoływać API przeglądarki, dla których React nie ma propsa: focus(), select(), scrollIntoView(), play() na wideo albo odczyt rozmiaru przez getBoundingClientRect().

const lastItemRef = useRef(null);

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

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

ref.current ma wartość null podczas pierwszego renderowania, bo React nie utworzył jeszcze węzła DOM, i znowu po usunięciu elementu. Odczytuj go w handlerach zdarzeń i efektach, gdzie węzeł istnieje. Żeby zmierzyć element i coś ustawić, zanim przeglądarka odmaluje ekran, odczytaj ref w useLayoutEffect.

Nie odczytuj ani nie zapisuj ref.current podczas renderowania

React oczekuje, że ciało komponentu to czyste obliczenie: te same propsy i stan, ten sam JSX. Ref zmienia się poza tym modelem, więc renderowanie, które go odczytuje albo zapisuje, może dać różne wyniki dla tych samych danych wejściowych, a React może wywoływać ciało częściej, niż się spodziewasz.

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

Odczytuj i zapisuj refy w handlerach zdarzeń i efektach. Jedynym wyjątkiem jest leniwa inicjalizacja, gdy wypełniasz ref raz, przy pierwszym renderowaniu:

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

(Demo z licznikiem w refie powyżej celowo odczytuje clicks.current w JSX, żeby pokazać, że ekran za nim nie podąża. Nie kopiuj tego do prawdziwego kodu.)

Ref callback

Zamiast obiektu refa możesz przekazać do ref funkcję. React wywołuje ją z węzłem DOM, gdy element zostaje dodany. W React 19 funkcja może zwrócić funkcję czyszczącą, którą React wywołuje przy usuwaniu elementu. Przydaje się to w liście, w której nie możesz wywołać useRef raz na element:

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>
    );
}

Przy ładowaniu konsola wypisuje jedną linię attached na każdy element. Kliknij Remove last, a pojawi się tylko detached Cheese. trackNode jest zdefiniowane poza komponentem, więc przy każdym renderowaniu to ta sama funkcja i React zostawia pozostałe elementy w spokoju. Napisz ją zamiast tego w linii jako ref={(node) => { ... }}, a każde kliknięcie odłączy i ponownie podłączy każdy element, bo każde renderowanie przekazuje nową funkcję.

Przekazywanie refa do własnego komponentu

W React 19 ref jest zwykłym propsem komponentów funkcyjnych. Rodzic tworzy ref, a dziecko umieszcza go na elemencie DOM, który chce udostępnić:

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>
    );
}

Przed React 19 wymagało to forwardRef, które nadal działa. Strona o forwardRef pokazuje obie wersje i to, jak udostępnić tylko kilka metod przez useImperativeHandle.

Częste błędy

Pokazywanie wartości refa w JSX. Ekran za nią nie podąża. Jeśli użytkownik ma widzieć wartość, użyj stanu.

Używanie ref.current jako zależności efektu. [ref.current] odczytuje wartość podczas renderowania, a React nie wie, kiedy się ona zmienia, więc efekt nie uruchamia się ponownie, gdy to nastąpi. Żeby zareagować na podłączenie węzła, użyj ref callback.

Odczyt refa do DOM podczas pierwszego renderowania. Jest null, dopóki React nie utworzy węzła. Odczytuj go w efekcie albo handlerze.

Tworzenie nowego obiektu zamiast używania hooka. const ref = { current: null } w ciele komponentu to świeży obiekt przy każdym renderowaniu. Tylko useRef za każdym razem daje ten sam.