React useRef Hook: DOM-Refs und Werte, die bleiben

useRef gibt ein Objekt zurück, { current: initialValue }, das React für die ganze Lebensdauer der Komponente behält. ref.current zu ändern rendert nichts neu. Damit sind Refs für zwei Aufgaben richtig: einen DOM-Knoten halten, um Methoden wie focus() darauf aufzurufen, und sich zwischen Renders einen Wert merken, den der Bildschirm nicht zeigen muss.

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

Das Ref-Objekt an ref={inputRef} zu übergeben sagt React, den DOM-Knoten des <input> in inputRef.current zu legen. Ändere focus() zu select(), tippe etwas und klicke erneut: Der Text wird markiert.

Die Syntax

const myRef = useRef(initialValue);

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

• initialValue wird nur beim ersten Render verwendet. Bei DOM-Refs ist er null.
• React gibt bei jedem Render dasselbe Objekt zurück. Nur current ändert sich.
• current zu lesen und zu schreiben ist gewöhnliches JavaScript. React verfolgt es nicht.

Ein Wert, der keine Renders auslöst

State ist für das, was der Bildschirm zeigt. Eine Ref ist für das, was sich die Komponente merken, aber nicht anzeigen muss. Dieser Block hält einen Zähler in einer Ref und einen im State und loggt beide:

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

Klicke ein paar Mal auf Ref + 1. Die Konsole zeigt, wie ref.current steigt, aber die Seite zeigt weiterhin 0, und kein Render wird geloggt. Klicke jetzt auf State + 1: Die Komponente rendert, und der Ref-Zähler auf dem Bildschirm springt auf die Zahl, die die Ref schon hielt. Die Ref hat ihren Wert die ganze Zeit behalten; React hatte nur keinen Grund, ihn zu zeichnen.

Refs vs. State

Wenn du unsicher bist, frag dich, ob das JSX den Wert liest. Wenn ja, gehört er in den State.

Eine Timer-ID speichern

setInterval gibt eine ID zurück, die du später brauchst, um den Timer zu stoppen. Sie passt gut in eine Ref: Der Stop-Handler braucht sie, aber der Bildschirm zeigt sie nie, und in einer einfachen Variablen ginge sie beim nächsten Render verloren.

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

Ersetze useRef(null) durch let intervalRef = { current: null };, probiere Start, warte zwei Sekunden und klicke dann auf Stop: Der Timer läuft weiter. Jeder Tick rendert die Komponente, was ein frisches Objekt erzeugt, also löscht Stop nichts.

Den vorherigen Wert merken

Ein Effekt läuft nach dem Render, also kann er den neuen Wert mit dem in einer Ref gespeicherten vergleichen und dann den neuen für das nächste Mal sichern:

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

Klicke auf green, dann auf blue: Die Konsole loggt changed from red to green und changed from green to blue. Ein Klick auf die bereits gewählte Farbe loggt nichts, weil der Effekt nur läuft, wenn sich color ändert.

Mit dem DOM arbeiten

Refs sind der Weg, Browser-APIs aufzurufen, für die React keine Prop hat: focus(), select(), scrollIntoView(), play() an einem Video oder das Lesen einer Größe mit getBoundingClientRect().

const lastItemRef = useRef(null);

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

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

ref.current ist beim ersten Render null, weil React den DOM-Knoten noch nicht erzeugt hat, und nach dem Entfernen des Elements wieder. Lies ihn in Event-Handlern und Effekten, wo der Knoten existiert. Um ein Element zu messen und etwas zu positionieren, bevor der Browser zeichnet, lies die Ref in useLayoutEffect.

ref.current nicht beim Rendern lesen oder schreiben

React erwartet, dass der Komponentenkörper eine pure Berechnung ist: gleiche Props und gleicher State, gleiches JSX. Eine Ref ändert sich außerhalb dieses Modells, also kann ein Render, der sie liest oder schreibt, für dieselben Eingaben unterschiedliche Ergebnisse zeigen, und React kann den Körper öfter aufrufen, als du erwartest.

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

Lies und schreibe Refs in Event-Handlern und Effekten. Die einzige Ausnahme ist die lazy Initialisierung, bei der du die Ref einmal beim ersten Render füllst:

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

(Die Ref-Zähler-Demo oben liest clicks.current absichtlich im JSX, um zu zeigen, dass der Bildschirm ihm nicht folgt. Übernimm das nicht in echten Code.)

Ref-Callbacks

Statt eines Ref-Objekts kannst du ref eine Funktion übergeben. React ruft sie mit dem DOM-Knoten auf, wenn das Element hinzugefügt wird. In React 19 kann die Funktion ein Cleanup zurückgeben, das React aufruft, wenn das Element entfernt wird. Das ist praktisch für eine Liste, in der du useRef nicht einmal pro Eintrag aufrufen kannst:

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

Beim Laden loggt die Konsole eine Zeile attached pro Eintrag. Klicke auf Remove last, und nur detached Cheese erscheint. trackNode ist außerhalb der Komponente definiert, also ist es bei jedem Render dieselbe Funktion, und React lässt die anderen Einträge in Ruhe. Schreib es stattdessen inline als ref={(node) => { ... }}, und jeder Klick löst jeden Eintrag und hängt ihn wieder an, weil jeder Render eine neue Funktion übergibt.

Eine Ref an deine eigene Komponente übergeben

In React 19 ist ref für Funktionskomponenten eine normale Prop. Das Elternteil erzeugt die Ref, und das Kind setzt sie auf das DOM-Element, das es freigeben will:

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

Vor React 19 brauchte das forwardRef, das weiterhin funktioniert. Die Seite zu forwardRef zeigt beide Versionen und wie du mit useImperativeHandle nur ein paar Methoden freigibst.

Typische Fehler

Einen Ref-Wert im JSX anzeigen. Der Bildschirm folgt ihm nicht. Wenn der Wert sichtbar sein soll, nutze State.

ref.current als Abhängigkeit eines Effekts nutzen. [ref.current] liest den Wert beim Rendern, und React weiß nicht, wann er sich ändert, also läuft der Effekt nicht erneut, wenn er es tut. Nutze einen Ref-Callback, um darauf zu reagieren, dass ein Knoten angehängt wird.

Eine DOM-Ref beim ersten Render lesen. Sie ist null, bis React den Knoten erzeugt hat. Lies sie in einem Effekt oder einem Handler.

Ein neues Objekt erzeugen, statt den Hook zu nutzen. const ref = { current: null } im Komponentenkörper ist bei jedem Render ein frisches Objekt. Nur useRef gibt dir jedes Mal dasselbe.