ESLint Plugin for React

7.37.5 · active · verified Sun Apr 19

eslint-plugin-react provides React-specific linting rules for ESLint, helping developers enforce best practices, identify potential bugs, and maintain consistent code styles in React projects. As of version 7.37.5, it supports a wide range of React features and idioms, including Hooks, JSX, and functional/class components. The project maintains an active development and release cadence, with frequent patch and minor updates to address issues and add new rules. Its key differentiators include comprehensive coverage of React patterns, automatic detection of React versions, and integration with ESLint's ecosystem for a robust static analysis setup. It is the de-facto standard for linting React codebases with ESLint.

Common errors

```
Error: Failed to load plugin 'react' declared in '.eslintrc.json': Cannot find module 'eslint-plugin-react'
```
cause The `eslint-plugin-react` npm package is not installed as a dependency in your project.

fix Run `npm install eslint-plugin-react --save-dev` or `yarn add eslint-plugin-react --dev` to install the plugin.
```
Parsing error: Cannot find module 'react' when using JSX (or similar 'React' must be in scope error).
```
cause ESLint's parser is not configured to understand JSX syntax, or the plugin is not properly recognizing the React environment. This often happens with React < 17 and `react/react-in-jsx-scope` rule, or when `jsx-runtime` is not configured for React 17+.

fix Ensure your `.eslintrc*` file includes `parserOptions.ecmaFeatures.jsx: true` and `settings.react.version: "detect"`. If using React 17+, add `"plugin:react/jsx-runtime"` to your `extends` array to disable the `react/react-in-jsx-scope` rule.
```
Warning: React version not specified in 'eslint-plugin-react settings'. See https://github.com/jsx-eslint/eslint-plugin-react/blob/master/README.md#configuration.
```
cause The `eslint-plugin-react` cannot determine which React version your project is using, which can lead to incorrect linting results for version-specific rules.

fix Add `"settings": { "react": { "version": "detect" } }` to your `.eslintrc*` configuration file to enable automatic React version detection.

Warnings

breaking ESLint v9 introduced a new flat configuration system (`eslint.config.js`). Legacy `.eslintrc*` files are deprecated and will not work without a compatibility layer. The plugin provides flat config presets, but migration is required for ESLint v9+ projects.
Fix: Migrate your ESLint configuration to `eslint.config.js` using the new flat config format. Refer to `eslint-plugin-react`'s official documentation for updated flat config examples.
gotcha When using React 17's new JSX transform (which automatically imports the `jsx` runtime), certain rules in `plugin:react/recommended` (like `react/react-in-jsx-scope`) become redundant and can cause errors if `plugin:react/jsx-runtime` is not extended.
Fix: Ensure you add `"plugin:react/jsx-runtime"` to your `extends` array in your ESLint configuration.
gotcha Many rules in `eslint-plugin-react` depend on knowing the exact React version installed in your project. If `settings.react.version` is not configured correctly or omitted, rules may produce incorrect warnings/errors or behave unexpectedly.
Fix: Always set `settings.react.version: "detect"` in your ESLint configuration for automatic detection from `package.json`. Alternatively, specify the exact version string (e.g., `"18.0"`) if autodetection is problematic or you need to override it.
breaking `eslint-plugin-react` has strict peer dependency requirements for `eslint` itself (e.g., `^3 || ^4 || ^5 || ^6 || ^7 || ^8 || ^9.7`). Installing incompatible `eslint` versions can lead to runtime errors where the plugin fails to load or function correctly.
Fix: Ensure your `eslint` package version in `package.json` and `node_modules` matches the peer dependency range specified by `eslint-plugin-react`. Use `npm ls eslint` to check and adjust as needed.

Install

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

Imports

Configuring the plugin
wrong:
```
plugins: [require('eslint-plugin-react')]
```
correct:
```
plugins: ['react']
```
Registers the 'react' plugin with ESLint in the legacy .eslintrc* configuration.
Recommended Ruleset
wrong:
```
extends: ['react/recommended']
```
correct:
```
extends: ['plugin:react/recommended']
```
Applies the recommended set of React-specific rules. Used in legacy .eslintrc* configs.
JSX Runtime Ruleset
wrong:
```
Omitting this when using React 17+ new JSX transform.
```
correct:
```
extends: ['plugin:react/jsx-runtime']
```
Disables rules that become redundant or problematic with React 17's new JSX transform (e.g., 'react/react-in-jsx-scope').
React Version Detection
wrong:
```
settings: { react: { version: 'latest' } } (or omitting entirely)
```
correct:
```
settings: { react: { version: 'detect' } }
```
Crucial for rules that depend on the installed React version. 'detect' automatically infers from package.json.

Flat Config (ESLint v9+)

wrong:

Using `extends: ['plugin:react/recommended']` in `eslint.config.js`.

correct:

import reactPlugin from 'eslint-plugin-react';
export default [
  reactPlugin.configs.flat.recommended,
  reactPlugin.configs.flat['jsx-runtime'],
  // ... other configs
];

For ESLint v9+, configurations are defined in `eslint.config.js` using a flat array of config objects. The plugin exposes its configurations under `reactPlugin.configs.flat`.

Quickstart

Demonstrates how to install `eslint-plugin-react` and configure it using both the legacy `.eslintrc.json` format (for ESLint < v9) and the new flat config `eslint.config.js` format (for ESLint v9+), including recommended presets and React version detection.

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

// .eslintrc.json (Legacy ESLint config)
{
  "env": {
    "browser": true,
    "es2021": true,
    "node": true
  },
  "extends": [
    "eslint:recommended",
    "plugin:react/recommended",
    "plugin:react/jsx-runtime" // For React 17+ new JSX transform
  ],
  "parserOptions": {
    "ecmaFeatures": {
      "jsx": true
    },
    "ecmaVersion": "latest",
    "sourceType": "module"
  },
  "plugins": [
    "react"
  ],
  "settings": {
    "react": {
      "version": "detect" // Automatically detects React version
    }
  },
  "rules": {
    // Add or override specific rules here, e.g.,
    // "react/prop-types": "off"
  }
}

// For ESLint v9+ (eslint.config.js)
// You would need to install @eslint/js for `js.configs.recommended`
// import globals from "globals";
// import js from "@eslint/js";
// import reactPlugin from "eslint-plugin-react";

// export default [
//   js.configs.recommended,
//   {
//     files: ["**/*.{js,jsx,mjs,cjs,ts,tsx}"],
//     ...reactPlugin.configs.flat.recommended,
//     ...reactPlugin.configs.flat['jsx-runtime'], // For React 17+ new JSX transform
//     languageOptions: {
//       globals: {
//         ...globals.browser,
//         ...globals.node
//       },
//       parserOptions: {
//         ecmaFeatures: {
//           jsx: true
//         },
//         ecmaVersion: "latest",
//         sourceType: "module"
//       }
//     },
//     settings: {
//       react: {
//         version: "detect"
//       }
//     },
//     rules: {
//       // Add or override specific rules here
//     }
//   }
// ];

view raw JSON →