useDeferredValue в React: пусть медленные части отстают

useDeferredValue даёт копию значения, которой разрешено отставать. Когда значение меняется, React сначала перерисовывает экран со старой копией, что сохраняет ввод мгновенным, а затем в фоне рендерит медленную часть с новым значением.

import { memo, useDeferredValue, useState } from 'react';

function SlowItem({ text }) {
    const start = performance.now();
    while (performance.now() - start < 1) {
        // each row takes 1 ms to render
    }
    return <li>{text}</li>;
}

const SlowList = memo(function SlowList({ query }) {
    console.log('SlowList rendering for', JSON.stringify(query));
    const rows = [];
    for (let i = 0; i < 250; i++) {
        rows.push(<SlowItem key={i} text={`${query || 'result'} #${i + 1}`} />);
    }
    return <ul style={{ maxHeight: 150, overflow: 'auto' }}>{rows}</ul>;
});

export default function App() {
    const [query, setQuery] = useState('');
    const deferredQuery = useDeferredValue(query);
    const isStale = query !== deferredQuery;

    return (
        <div>
            <input
                value={query}
                onChange={(e) => setQuery(e.target.value)}
                placeholder="Type fast"
            />
            <div style={{ opacity: isStale ? 0.5 : 1 }}>
                <SlowList query={deferredQuery} />
            </div>
        </div>
    );
}

Быстро наберите слово. Поле успевает за вводом, а список тускнеет, пока отстаёт. Console выводит по строке SlowList rendering на каждую букву, потому что SlowList выводит сообщение, как только React начинает его рендерить, но списки для промежуточных значений так и не доходят до экрана: каждая новая буква прерывала фоновый рендер, и React начинал заново с последним текстом. Замените query={deferredQuery} на query={query} и снова попечатайте: теперь каждое нажатие клавиши ждёт список четверть секунды.

Синтаксис

const deferredValue = useDeferredValue(value);
const deferredValue = useDeferredValue(value, initialValue); // React 19

• value это всё, что вы рендерите: строка из поля, число, объект. Лучше всего работают примитивы, потому что новый объект при каждом рендере всегда считается изменением.
• Возвращаемое значение большую часть времени равно value. Сразу после изменения value оно на один рендер хранит предыдущее значение и догоняет в фоновом рендере.

Как это работает

Каждое изменение даёт два рендера:

1. Срочный рендер с новым value и старым deferredValue. Поле показывает новый текст. Компоненты, которые получают только deferredValue, получают те же пропсы, что и раньше.
2. Фоновый рендер с новым deferredValue. Это медленный рендер. React рендерит его частями и бросает, если value снова изменится до его завершения, а затем начинает заново с последним значением.

Это можно увидеть, выводя оба значения:

import { useDeferredValue, useState } from 'react';

export default function App() {
    const [text, setText] = useState('');
    const deferredText = useDeferredValue(text);

    console.log('render: text =', JSON.stringify(text), 'deferred =', JSON.stringify(deferredText));

    return (
        <input
            value={text}
            onChange={(e) => setText(e.target.value)}
            placeholder="Type one letter"
        />
    );
}

Наберите одну букву, скажем a, и Console выведет ещё две строки: сначала text = "a" с deferred = "", затем оба "a". Именно первый рендер сохраняет ввод быстрым, но только если медленная часть может его пропустить. Поэтому SlowList в первом примере обёрнут в memo: во время срочного рендера его пропс query не изменился, и React его пропускает. Без memo срочный рендер всё равно выполнял бы весь медленный список, только со старым текстом, и вы ничего бы не выиграли.

Показ устаревшего содержимого

Пока идёт фоновый рендер, value и отложенное значение различаются. Сравните их, чтобы сообщить пользователю, что содержимое устарело, не скрывая его:

const isStale = query !== deferredQuery;

<div style={{ opacity: isStale ? 0.5 : 1, transition: 'opacity 0.2s' }}>
    <SlowList query={deferredQuery} />
</div>

Обычно это приятнее спиннера: старые результаты остаются читаемыми и меняются на месте, когда новые готовы. Та же идея работает с Suspense: если отложенное значение заставляет компонент приостановиться при загрузке данных, React продолжает показывать старое содержимое вместо запасного варианта, пока новое не будет готово (см. Suspense и lazy).

Начальное значение (React 19)

По умолчанию первому рендеру не от чего отставать, поэтому отложенное значение с самого начала равно настоящему. Начиная с React 19 можно передать второй аргумент. При первом рендере хук возвращает initialValue, а затем React снова рендерит в фоне с настоящим значением. Это позволяет сразу показать что-то дешёвое и сразу после заполнить дорогую часть.

import { memo, useDeferredValue } from 'react';

const Preview = memo(function Preview({ text }) {
    console.log('Preview render:', JSON.stringify(text));
    if (!text) return <p>Loading preview...</p>;
    return <p>{text}</p>;
});

export default function App() {
    const article = 'React renders the cheap version first, then this one.';
    const deferred = useDeferredValue(article, '');
    return <Preview text={deferred} />;
}

Console показывает два рендера: сначала с "", затем с полным текстом. Уберите второй аргумент, и выведется только один рендер, сразу с полным текстом.

useDeferredValue или useTransition

Оба помечают работу как несрочную и используют один и тот же механизм рендеринга. Разница в том, где их ставить:

• useTransition оборачивает обновление. Вы вызываете startTransition(() => setQuery(text)), поэтому нужен сеттер. isPending вы получаете бесплатно.
• useDeferredValue оборачивает значение. Вы вызываете его там, где значение используется, поэтому он работает, когда значение приходит как пропс или из хука, который вы не контролируете. «Ожидание» вы вычисляете сами через value !== deferredValue.

// You own the state: either works, a transition is direct
startTransition(() => setQuery(nextQuery));

// You only receive the value
function SearchResults({ query }) {
    const deferredQuery = useDeferredValue(query);
    return <SlowList query={deferredQuery} />;
}

useDeferredValue, debounce и throttle

Debounce ждёт фиксированное время после последнего изменения; throttle обновляет не чаще одного раза за интервал. Оба заранее выбирают задержку, поэтому на быстром ноутбуке делают страницу медленнее, чем нужно, а на медленном телефоне задержки всё равно может не хватить.

У useDeferredValue задержки нет. Фоновый рендер начинается сразу, поэтому на быстром устройстве список обновляется почти мгновенно, а на медленном React сохраняет отзывчивость поля и рендерит список так часто, как может. К тому же фоновую работу можно прервать, а рендер после debounce нельзя: начавшись, он блокирует, пока не закончится.

Чего он не делает, так это не сокращает сетевые запросы. Если каждое новое значение запускает fetch, отложенное значение всё равно меняется с каждым завершённым рендером, поэтому применяйте debounce к самому запросу, когда важен объём запросов.

Частые ошибки

• Забыть memo. Как показано выше, медленный компонент должен иметь возможность пропустить срочный рендер. Если он не обёрнут в memo или один из его других пропсов при каждом рендере новый объект, он рендерится дважды за нажатие клавиши вместо одного раза.
• Передать новый объект. useDeferredValue({ query }) при каждом рендере создаёт новый объект, поэтому отложенное значение всегда выглядит изменившимся, и React каждый раз запускает лишний фоновый рендер. Откладывайте примитив (useDeferredValue(query)) и собирайте объекты из него.
• Ожидать меньше запросов. Компонент, который загружает данные по отложенному значению, всё равно загружает их для каждого значения, рендер которого завершился.

Когда за него браться

Используйте useDeferredValue, когда одно поле управляет частью страницы, которая медленно рендерится, медленную часть можно мемоизировать, и вас устраивает на мгновение показывать немного устаревшие результаты: результаты поиска, график, который перерисовывается по фильтру, превью форматированного текста. Если медленная часть медленная по причине, которую можно исправить, например рендер 5000 строк, когда видно 50, сначала исправьте это. Вариант этого шаблона, когда сеттер принадлежит вам, описан на странице о useTransition.