Правила хуков в React: почему важен порядок и как исправить

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

React хранит значения хуков компонента в списке, привязанном к этому компоненту. При каждом рендере он проходит по списку: первый вызов хука получает первую ячейку, второй вызов вторую и так далее. Имён нет, только позиции. Пример ниже это игрушечная версия этой идеи в нескольких строках обычного JavaScript, а не собственный код React, поэтому его можно безопасно ломать.

import { useState } from 'react';

const slots = [];
let index = 0;

function toyUseState(initial) {
    const i = index++;
    if (!(i in slots)) slots[i] = initial;
    return [slots[i]];
}

function renderForm(showNickname) {
    index = 0;
    const [name] = toyUseState('Ada');
    let nickname = '(no hook called)';
    if (showNickname) {
        [nickname] = toyUseState('Countess');
    }
    const [age] = toyUseState(36);
    return { name, nickname, age };
}

export default function App() {
    const [result, setResult] = useState(() => renderForm(true));
    return (
        <div>
            <button onClick={() => setResult(renderForm(true))}>Render with nickname</button>{' '}
            <button onClick={() => setResult(renderForm(false))}>Render without nickname</button>
            <p>
                name: {String(result.name)}, nickname: {String(result.nickname)}, age:{' '}
                {String(result.age)}
            </p>
            <p style={{ color: '#666' }}>slots: {JSON.stringify(slots)}</p>
        </div>
    );
}

Первый рендер заполняет три ячейки: Ada, Countess, 36. Нажмите «Render without nickname»: вызов по условию пропускается, поэтому вызов age занимает ячейку 1 и читает Countess. Настоящий React в одних случаях замечает несоответствие и выбрасывает ошибку, а в других передаёт неправильное значение неправильному хуку, что хуже. Перенесите вызов toyUseState('Countess') выше if, и обе кнопки дадут правильный возраст.

Два правила в коде

function Profile({ user }) {
    // Good: always called, always in this order
    const [tab, setTab] = useState('posts');
    const theme = useContext(ThemeContext);
    useEffect(() => {
        document.title = user.name;
    }, [user.name]);

    // Bad: inside a condition, a loop or a nested function
    if (user.isAdmin) {
        const [log, setLog] = useState([]); // breaks the order
    }
}

Вызов хука, до которого выполнение доходит всегда и в одном и том же порядке, допустим в любом месте тела, если он стоит до любого раннего return.

Исправление хука, вызванного по условию

Линтер сообщает об этом как React Hook "useEffect" is called conditionally. React Hooks must be called in the exact same order in every component render. Исправление всегда одно и то же: вызывайте хук каждый раз, а условие помещайте внутрь него.

// Broken: the effect exists on some renders and not others
function Notifications({ user }) {
    if (user) {
        useEffect(() => {
            console.log('subscribe for', user.name);
        }, [user]);
    }
    return null;
}

import { useState, useEffect } from 'react';

function Notifications({ user }) {
    useEffect(() => {
        if (!user) return;
        console.log('subscribe for', user.name);
        return () => console.log('unsubscribe for', user.name);
    }, [user]);

    return <p>{user ? `Notifications for ${user.name}` : 'Log in to see notifications'}</p>;
}

export default function App() {
    const [user, setUser] = useState(null);
    return (
        <div>
            <button onClick={() => setUser(user ? null : { name: 'Ada' })}>
                {user ? 'Log out' : 'Log in'}
            </button>
            <Notifications user={user} />
        </div>
    );
}

Эффект объявляется при каждом рендере, а if внутри него решает, делать ли что-нибудь. Несколько раз войдите и выйдите, и Console покажет подписку на каждый вход и отписку на каждый выход.

Хуки после раннего return

Ранний return тоже условие. Этот код даёт "Rendered more hooks than during the previous render" в первый раз, когда loading становится false, потому что этот рендер доходит до хука, который предыдущий никогда не вызывал. Когда рендер вызывает меньше хуков, чем предыдущий, сообщение будет "Rendered fewer hooks than expected".

// Broken: useState is skipped while loading
function Comments({ loading, comments }) {
    if (loading) return <p>Loading...</p>;
    const [expanded, setExpanded] = useState(false);
    return <List items={comments} expanded={expanded} />;
}

import { useState } from 'react';

function Comments({ loading, comments }) {
    const [expanded, setExpanded] = useState(false);

    if (loading) return <p>Loading...</p>;

    const shown = expanded ? comments : comments.slice(0, 2);
    return (
        <div>
            <ul>
                {shown.map((c) => (
                    <li key={c}>{c}</li>
                ))}
            </ul>
            <button onClick={() => setExpanded(!expanded)}>
                {expanded ? 'Show less' : `Show all ${comments.length}`}
            </button>
        </div>
    );
}

export default function App() {
    const [loading, setLoading] = useState(true);
    return (
        <div>
            <button onClick={() => setLoading(!loading)}>Toggle loading</button>
            <Comments loading={loading} comments={['Nice!', 'Agreed.', 'First.', 'Thanks']} />
        </div>
    );
}

Каждый хук стоит выше return, поэтому обе ветки вызывают одни и те же хуки. Нажмите «Toggle loading», раскройте список, затем дважды переключите загрузку: список помнит, что был раскрыт, потому что состояние никогда не пропускалось.

Хуки в цикле

Нельзя вызывать useState по разу на каждый элемент в цикле, потому что число элементов меняется. Дайте каждому элементу собственный компонент и вызывайте хук там; у каждого экземпляра свои ячейки.

import { useState } from 'react';

function Item({ name }) {
    const [qty, setQty] = useState(0);
    return (
        <li>
            {name}: {qty} <button onClick={() => setQty(qty + 1)}>+</button>
        </li>
    );
}

export default function App() {
    const [items, setItems] = useState(['Tea', 'Milk']);
    return (
        <div>
            <ul>
                {items.map((name) => (
                    <Item key={name} name={name} />
                ))}
            </ul>
            <button onClick={() => setItems([...items, `Item ${items.length + 1}`])}>
                Add item
            </button>
        </div>
    );
}

«Invalid hook call»

Сообщение начинается с "Invalid hook call. Hooks can only be called inside of the body of a function component." У него три обычные причины:

1. Хук выполняется, когда React не рендерит функциональный компонент. В обработчике события, внутри колбэка эффекта, в классовом компоненте или на уровне модуля. Перенесите его в тело компонента или в пользовательский хук и вызывайте пользовательский хук из компонента.
2. Версии react и react-dom не совпадают. Установите одну и ту же версию обоих.
3. Есть две копии React. Связанный локальный пакет или библиотека, которая включает собственный React, приносят вторую копию, а хуки из одной копии не работают с рендерером другой. Выполните npm ls react и убедитесь, что появляется только одна версия.

npm ls react

Превью здесь работает как продакшен-сборка, которая не выводит эти сообщения: хук, вызванный из обработчика события, падает с обычным TypeError вроде "Cannot read properties of null", а собственные ошибки React приходят как короткие коды "Minified React error". Чтобы прочитать полный текст, запускайте приложение в режиме разработки.

Пусть правила проверяет линтер

eslint-plugin-react-hooks проверяет оба правила по мере ввода, а также проверяет массивы зависимостей эффектов. Его включают шаблон React для Vite и конфигурация ESLint в Next.js. В плоской конфигурации ESLint включите его рекомендуемый пресет:

// eslint.config.js
import reactHooks from 'eslint-plugin-react-hooks';
import { defineConfig } from 'eslint/config';

export default defineConfig([reactHooks.configs.flat.recommended]);

Два основных правила это react-hooks/rules-of-hooks (ошибка) и react-hooks/exhaustive-deps (предупреждение). Начиная с версии 7 пресет также включает правила, пришедшие из React Compiler, например react-hooks/purity и react-hooks/refs, которые отмечают нечистые рендеры и чтение рефов во время рендера. Чтобы выбирать правила по одному, зарегистрируйте плагин как plugins: { 'react-hooks': reactHooks } и перечислите нужные правила.

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

Исключение: use

use, добавленный в React 19, читает промис или контекст и, в отличие от всех остальных хуков, может вызываться внутри условия или цикла. Но вызывать его всё равно нужно во время рендера, внутри компонента или хука.

import { createContext, use, useState } from 'react';

const ThemeContext = createContext('light');

function Heading({ children, themed }) {
    let color = '#000';
    if (themed) {
        const theme = use(ThemeContext);
        color = theme === 'dark' ? '#7aa7ff' : '#c0392b';
    }
    return <h3 style={{ color }}>{children}</h3>;
}

export default function App() {
    const [theme, setTheme] = useState('light');
    return (
        <ThemeContext value={theme}>
            <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
                Theme: {theme}
            </button>
            <Heading>Plain heading</Heading>
            <Heading themed>Themed heading</Heading>
        </ThemeContext>
    );
}

При смене темы цвет меняет только заголовок с темой. Попробуйте то же самое с useContext внутри if, и линтер это отметит. Чтение промисов через него разбирает страница о хуке use.