ESLint Plugin for React Hooks

7.1.1 · active · verified Sun Apr 19

eslint-plugin-react-hooks is the official ESLint plugin maintained by the React team, designed to enforce the fundamental Rules of React Hooks and other best practices within React applications. The current stable version is 7.1.1. This plugin is released in coordination with React and ESLint major versions, with frequent minor updates addressing bug fixes, performance improvements, and support for new ESLint versions (e.g., v10 support was added recently). A key differentiator is its official backing by Facebook/React, ensuring alignment with the latest React paradigms and potentially incorporating experimental 'React Compiler rules' to guide future optimizations and patterns.

Common errors

```
Error: Rule 'react-hooks/component-hook-factories' was not found
```
cause This specific error occurred in version 7.1.0 due to a temporary removal of the rule.

fix Upgrade `eslint-plugin-react-hooks` to version 7.1.1 or newer. If you are on a different version and encounter this, ensure the rule name is correct or remove it if it's deprecated.
```
ESLint couldn't find the plugin 'react-hooks'.
```
cause The plugin is not installed, or ESLint cannot locate it due to incorrect configuration (e.g., wrong path, missing `plugins` array entry).

fix Ensure `eslint-plugin-react-hooks` is installed (`npm install --save-dev eslint-plugin-react-hooks`). Verify your ESLint configuration (either `.eslintrc` or `eslint.config.js`) correctly references the plugin, e.g., in the `plugins` array or through `reactHooks.configs.flat.recommended`.
```
React Hook "useSomething" is called in a function that is neither a React function component nor a custom React Hook function.
```
cause Violation of the 'Rules of Hooks', specifically `react-hooks/rules-of-hooks`, often by calling Hooks outside of valid React component or custom Hook contexts.

fix Ensure all React Hooks (e.g., `useState`, `useEffect`, `useContext`) are called only from within React function components, custom Hooks (functions prefixed with `use`), or from a function passed to a Hook (like the effect callback in `useEffect`).
```
React Hook "useSomething" has a missing dependency: 'dep'. Either include it or remove the dependency array.
```
cause Violation of the 'Rules of Hooks', specifically `react-hooks/exhaustive-deps`, where a dependency array for a Hook (like `useEffect`, `useMemo`, `useCallback`) does not include all variables referenced inside the Hook's callback.

fix Add all relevant variables (props, state, or functions from the component scope) that are used inside the Hook's callback to its dependency array. Alternatively, if the Hook should run on every render, remove the dependency array entirely (though this is rarely the desired behavior for performance).

Warnings

breaking Version 7.1.0 temporarily removed the `component-hook-factories` rule, causing ESLint configuration errors for users referencing it. This was immediately patched in v7.1.1 by re-adding the rule as a deprecated no-op for backward compatibility.
Fix: Upgrade to `eslint-plugin-react-hooks@7.1.1` or higher to resolve the missing rule error.
breaking With the release of ESLint v9 and its Flat Config system, older `.eslintrc` files are no longer directly supported. Users upgrading ESLint to v9+ must migrate their configuration to `eslint.config.js` (Flat Config).
Fix: Migrate your ESLint configuration from `.eslintrc` to `eslint.config.js` using the Flat Config syntax as shown in the quickstart or ESLint documentation. The plugin provides `reactHooks.configs.flat.recommended` for easy migration.
gotcha The `exhaustive-deps` rule includes an `additionalHooks` option to validate dependencies of custom Hooks, but its use is strongly discouraged by the React team. Over-reliance on this option can lead to brittle custom Hook APIs.
Fix: Prefer designing custom Hooks that do not require external dependencies or provide a higher-level API that abstracts dependency management. Use `additionalHooks` very sparingly after careful consideration.
gotcha Using custom rule configurations instead of the `recommended` or `recommended-latest` presets may result in missing new recommended rules as they are added in future plugin versions, leading to incomplete linting coverage.
Fix: Always extend from `reactHooks.configs.flat.recommended` (for Flat Config) or `plugin:react-hooks/recommended` (for Legacy Config) to automatically receive updated and new recommended rules.

Install

npm install eslint-plugin-react-hooks npm
yarn add eslint-plugin-react-hooks yarn
pnpm add eslint-plugin-react-hooks pnpm

Imports

reactHooks
wrong:
```
const reactHooks = require('eslint-plugin-react-hooks');
```
correct:
```
import reactHooks from 'eslint-plugin-react-hooks';
```
This is the primary way to integrate the plugin with ESLint's Flat Config (`eslint.config.js` or `eslint.config.ts`), which primarily uses ES modules. For legacy `.eslintrc` configurations, the plugin is typically referenced via string identifiers (e.g., `'plugin:react-hooks/recommended'`) and does not require a direct JavaScript import in the configuration file itself.

Quickstart

Installs the plugin and demonstrates basic configuration using ESLint's modern Flat Config (`eslint.config.js`), enabling core and example compiler rules.

npm install --save-dev eslint-plugin-react-hooks eslint

// eslint.config.js (for ESLint v9+ Flat Config)
import reactHooks from 'eslint-plugin-react-hooks';
import { defineConfig } from 'eslint/config';

export default defineConfig([
  {
    files: ['**/*.{js,jsx,ts,tsx}'],
    plugins: { 'react-hooks': reactHooks },
    rules: {
      // Core hooks rules
      'react-hooks/rules-of-hooks': 'error',
      'react-hooks/exhaustive-deps': 'warn',

      // Example React Compiler rules (optional, consider 'recommended-latest')
      'react-hooks/set-state-in-effect': 'error',
      'react-hooks/static-components': 'error'
    }
  },
  // Or simply use the recommended preset:
  // reactHooks.configs.flat.recommended,
]);

view raw JSON →