Bug: Improve ESLint error message for invalid hook usage

[salamafazlul]

The current ESLint error message for invalid hook usage (e.g., calling hooks conditionally) is not very descriptive. It fails to explain why the error occurred or provide guidance on how to fix it. This can be particularly confusing for beginners, who may not understand the rules of hooks.

React version: 19.0.0

Steps To Reproduce

1. Create a React component with the following code

function UserForm() {
  const [userType, setUserType] = useState('student');

  if (userType === 'student') {
    const [studentId, setStudentId] = useState('');
  } else if (userType === 'teacher') {
    const [teacherId, setTeacherId] = useState('');
  }

  return (
    <div>
      <h2>User Form</h2>
      <label>
        Select User Type:
        <select value={userType} onChange={(e) => setUserType(e.target.value)}>
          <option value="student">Student</option>
          <option value="teacher">Teacher</option>
        </select>
      </label>

      {userType === 'student' && (
        <div>
          <label>
            Student ID:
            <input
              type="text"
              value={studentId}
              onChange={(e) => setStudentId(e.target.value)}
            />
          </label>
        </div>
      )}

      {userType === 'teacher' && (
        <div>
          <label>
            Teacher ID:
            <input
              type="text"
              value={teacherId}
              onChange={(e) => setTeacherId(e.target.value)}
            />
          </label>
        </div>
      )}
    </div>
  );
}

export default UserForm;

2. The error message you’ll see is
   React Hook "useState" is called conditionally. React Hooks must be called in the exact same order in every component render

The current behavior

The error message is generic and doesn't provide enough detail

The expected behavior

The error message could include

• A clear explanation of why the error occurred (e.g., hooks cannot be used inside loops, conditions, or nested functions).
• A link to the React Hooks documentation for further reading.

[NamPNQ]

I think it's enough clear, and you forgot read the docs, hook cant used under conditional, because the hooks are arrayed

if (userType === 'student') {
    const [studentId, setStudentId] = useState('');
  } else if (userType === 'teacher') {
    const [teacherId, setTeacherId] = useState('');
  }

[salamafazlul]

Hi @NamPNQ

Thank you for your response! I understand that the rules of hooks are documented, and I’m aware that hooks cannot be used conditionally because of how React tracks them internally (e.g., using an array-like structure).

However, the current error message (React Hook "useState" is called conditionally. React Hooks must be called in the exact same order in every component render) doesn’t explain why this is a problem or provide guidance on how to fix it. For beginners, this can be confusing, as they might not immediately understand the connection between the error and the rules of hooks.

[NamPNQ]

As I remember, the error also have link to document. If the beginer can't read this, I think they can be fired by AI.