React Hook "useState" cannot be called at the top level, or in a function that is not a component
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 functionShort 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.
Fix it fast
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/2Match what you see, then jump to its fix
- 1
The 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
The flagged hook sits inside onClick, a callback, or a function passed to useEffect or useMemoThe hook is inside a callback or event handlerFix - 3
The 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
- 1
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 functionThe 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
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.jsxConfirmed by react.dev
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
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
React says a Hook was called where React is not rendering a component
Uncaught TypeError: Cannot read properties of null (reading 'useState')
A Hook only works while React is rendering a function component or a custom Hook.
4 causes, each with a fixWeb apps
ESLint says a React Hook is called conditionally, in useCallback or any other hook
Did you accidentally call a React Hook after an early return?
React matches hooks to state by call order, so every render must call the same hooks in the same order.
4 causes, each with a fixWeb apps
Axios get works with a URL string but ignores the object passed as the second argument
The server log shows a GET with no query string
axios.get takes a URL and an optional config object.
3 causes, each with a fixWeb 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 fixWeb apps
NativeViewGestureHandler must be used as a descendant of GestureHandlerRootView
Error: NativeViewGestureHandler must be used as a descendant of GestureHandlerRootView. Otherwise the gestures will not be recognized.
react-native-gesture-handler only recognises gestures inside GestureHandlerRootView.
3 causes, each with a fixWeb apps
React: Maximum update depth exceeded or Too many re-renders
Maximum update depth exceeded
React stops a component that sets state again and again without end.
3 causes, each with a fix