Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

React Hook "useState" cannot be called at the top level, or in a function that is not a component

ErrorReact Hook "useState" cannot be called at the top level. React Hooks must be called in a React function component or a custom React Hook function

Short answer

The lint rule found a hook outside a component or custom hook. React only allows hooks at the top level of a function component or of a function whose name starts with use. Rename the function to PascalCase or use..., or move the hook out of the nested callback, loop, condition or module scope.

  • Applies to React 19, React Native 0.8x, eslint-plugin-react-hooks
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run ESLint on the file. The line and function name in the message show which of the causes below you have.

    npx eslint src/
  2. 2Match what you see, then jump to its fix

    1. 1The flagged hook sits in a function with a lower-case name that does not start with useThe function name is not a component name or a hook nameFix
    2. 2The flagged hook sits inside onClick, a callback, or a function passed to useEffect or useMemoThe hook is inside a callback or event handlerFix
    3. 3The flagged hook is at the top of the file, in a class method, or after an if or returnThe hook is at module level, inside a class, or after a conditionFix

What does the error look like?

  • React Hook "useState" cannot be called at the top level. React Hooks must be called in a React function component or a custom React Hook function
  • The lint points at a useState line inside a helper function, an onClick handler or the top of a module

Cause 1 of 3

The function name is not a component name or a hook name

1Check

The React docs treat a function as a component when its name is capitalized, and as a custom hook when it starts with use. A helper such as setOnlineStatus or formatPrice is neither.

grep -rnE "^(export )?(default )?(async )?function [a-z]" src/ | grep -v "function use"

2Fix

Rename the function to a component (PascalCase, returns JSX) or to a custom hook (use prefix), and call it that way.

// before: lower-case helper holding state
function formatPrice(price) {
  const [currency] = useState('USD');
  return `${currency} ${price}`;
}

// after: a custom hook
function useFormattedPrice(price) {
  const [currency] = useState('USD');
  return `${currency} ${price}`;
}

3Verify

Run the lint again; the error for that function is gone.

npx eslint src/

Confirmed by react.dev

Did this fix it?

Cause 2 of 3

The hook is inside a callback or event handler

1Check

Hooks cannot be called in nested functions such as event handlers, or inside the functions passed to useMemo, useReducer and useEffect.

grep -rn -B3 "useState(" src/ | grep -E "=>|function"

2Fix

Declare the state at the top level of the component and use the setter in the handler.

function Counter() {
  const [clicked, setClicked] = useState(false);
  return <button onClick={() => setClicked(true)}>Tap</button>;
}

3Verify

Lint passes and the handler still updates state.

npx eslint src/Counter.jsx

Confirmed by react.dev

Did this fix it?

Cause 3 of 3

The hook is at module level, inside a class, or after a condition

1Check

The lint lists hooks at module level, in class methods, in conditions, loops, try/catch, async functions and after an early return as invalid.

grep -rn "^const .* = use[A-Z]" src/

2Fix

Move a module-level hook into a component or custom hook. Turn a class component into a function component. Move the hook above any early return or condition and apply the condition to the result instead.

// before
const globalState = useState(0);

// after
function Screen() {
  const [count, setCount] = useState(0);
  if (count > 3) return null; // return after all hooks
  return null;
}

3Verify

Lint passes for the file.

npx eslint src/

Confirmed by react.dev

Did this fix it?

How do I stop it coming back?

  • Keep eslint-plugin-react-hooks on with react-hooks/rules-of-hooks set to error.
  • Name every function that calls a hook either as a component or with the use prefix.
  • Put all hooks at the top of the component, before any early return.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

Expo app never leaves the splash screen

App shows the splash screen forever and no error appears

After SplashScreen.preventAutoHideAsync() the splash stays until you hide it yourself.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.