React Reference ยท Rules of React
eslint-plugin-react-hooks
Reference for eslint-plugin-react-hooks: the rules-of-hooks and exhaustive-deps rules, how to configure them, and the real bugs each one prevents.
eslint-plugin-react-hooks is the official ESLint plugin for React. It reads your code without running it and reports places where the Rules of Hooks are broken or where an effect, memo or callback lists the wrong dependencies. Most React projects (Vite, Next.js and others) install it by default, and editors show its messages as you type.
Two rules have been part of the plugin from the start: react-hooks/rules-of-hooks and react-hooks/exhaustive-deps. Recent versions also ship rules that check what the React Compiler needs, such as pure rendering and no mutation of props or state.
// eslint.config.js (flat config) import reactHooks from 'eslint-plugin-react-hooks'; export default [ { plugins: { 'react-hooks': reactHooks }, rules: { 'react-hooks/rules-of-hooks': 'error', 'react-hooks/exhaustive-deps': 'warn', }, }, ];
Try it
A linter cannot run in the browser, so these two examples show the bugs that each rule exists to stop. The first one breaks the Rules of Hooks on purpose. The component calls a hook only after a click, so the hook count changes between renders, and React throws. An error boundary prints the message.
The second example is the bug that exhaustive-deps catches. The effect reads step but the dependency array is empty, so the interval keeps using the step value from the first render.
Press the button and keep watching: the label says step = 10, yet the total still grows by 1 each tick. Adding step to the array fixes it.
Syntax
| Part | Description |
|---|---|
react-hooks/rules-of-hooks |
Reports hooks called inside conditions, loops, nested functions, after an early return, in class components, or in functions that are neither a component (name starts with a capital letter) nor a custom hook (name starts with use). Usually set to error. |
react-hooks/exhaustive-deps |
Checks the dependency array of useEffect, useLayoutEffect, useMemo, useCallback and useImperativeHandle. Reports missing, unnecessary and unstable dependencies and offers an automatic fix. Usually set to warn. |
| Compiler-oriented rules | Newer releases add rules for render purity, mutation of values, refs read during render, state set during render and similar problems. They are included in the plugin's recommended presets, whose exact names depend on the plugin version. |
additionalHooks option |
A regular expression naming your own hooks whose last argument is a dependency array, for example `'(useMyEffect |
'react-hooks/exhaustive-deps': ['warn', { additionalHooks: '(useMyEffect)' }],
What the rules cannot see: the plugin works on one file at a time and on names, not on runtime values. A function called useThing that is not really a hook, or a hook hidden behind a variable, can confuse it.
Usage notes
- Do not silence
exhaustive-depswith a comment (// eslint-disable-next-line) just to make the warning go away. The warning almost always points at a real stale-value bug. Fix the cause: move the function inside the effect, use the updater form ofsetState, or use useEffectEvent for values that should not restart the effect. - Objects and functions created in render are new every time. If the rule says a dependency "changes on every render", wrap it in
useMemooruseCallback, or move it outside the component. - Refs are exempt. The
.currentof auseRefand the setter fromuseStateare known to be stable, so they need no entry. - Autofix is a suggestion. Adding a dependency can make an effect fire more often. Read the change before accepting it.
- Naming matters. The rule recognizes hooks by the
useprefix. A custom hook namedfetchUserthat callsuseStatewill be reported. - A rule violation is not always a crash. Conditional hooks often work until the condition changes, which is why they slip through testing and why a lint rule is so valuable.
- Nothing here changes your bundle: the plugin is a development tool and never ships to browsers.