React Reference ยท Concepts and Pitfalls
React hooks cheat sheet
A quick guide to choosing the right React hook: state, refs, effects, context, performance, transitions, forms and server data, with examples and rules.
React ships with around twenty built-in hooks. They fall into a few families, and most apps use five or six of them daily. This page is a decision guide: start from the job you need to do, find the hook, and follow the link for details. All hooks follow the same rules: call them at the top level of a function component or another hook, never inside conditions, loops or nested functions (the only exception is use, which may be called conditionally).
const [value, setValue] = useState(initial); // remember something and re-render const ref = useRef(null); // remember something without re-rendering useEffect(() => { /* sync */ return cleanup; }, [dep]); // talk to the outside world
Try it
Click "Ref click" several times: the number does not change until something else renders the component (try "State click" next).
Choosing a hook
Remember values
| Need | Hook |
|---|---|
| A value that changes the UI when it changes | useState |
| Complex state with several related fields or many transitions | useReducer |
| A mutable value that must not re-render (timer id, previous value, counters) | useRef |
| A handle to a DOM element | useRef with the ref prop (useRef for the DOM) |
| Expose methods from a child to its parent | useImperativeHandle |
| A value shared by a whole subtree without passing props | useContext |
| A value from outside React (browser API, global store) | useSyncExternalStore |
Synchronize with the outside world
| Need | Hook |
|---|---|
| Subscribe, fetch from the client, set timers, touch non-React widgets | useEffect |
| Measure layout and update before the browser paints | useLayoutEffect |
| Inject styles for a CSS-in-JS library | useInsertionEffect |
| Read the latest props or state inside an effect without re-running it | useEffectEvent (React 19.2) |
Performance
| Need | Hook or API |
|---|---|
| Cache an expensive calculation | useMemo |
| Keep a function's identity stable | useCallback |
| Skip re-rendering a component when props are equal | memo |
| Keep typing responsive during a heavy update | useTransition, startTransition |
| Show a lagging copy of a value | useDeferredValue |
Forms, async data and utilities
| Need | Hook |
|---|---|
| State and pending flag for a form action | useActionState |
| Know if the enclosing form is submitting | useFormStatus |
| Show a result before the server confirms | useOptimistic |
| Read a promise or context in render (suspends) | use |
| A stable unique id for labels and ARIA | useId |
| A label for a custom hook in DevTools | useDebugValue |
Quick rules of thumb
- Can you compute it from props or state? Do not store it. Calculate during render (see Derived state).
- Does a change need to update the screen? Use state. If not, use a ref.
- Is it a reaction to a user action? Put the code in the event handler, not in an effect (see Effects vs event handlers).
- Do you need an effect at all? Many effects only copy data between states or fetch data a framework could load for you (see You might not need an effect).
- Every effect that sets something up should clean it up.
- Add memoization after measuring, not before (see Memoization guide).
- Extract repeated hook logic into a custom hook named
useSomething. Custom hooks can call any hook and share logic, not state.
Usage notes
- Order matters. React identifies hooks by call order, so the same hooks must run in the same order on every render. See Rules of Hooks.
- Server Components cannot use state or effects;
useanduseIdwork there (see Server Components). - Classes had equivalents for most of this; see Migrating class to hooks.
- Dependency arrays use
Object.is; the ESLint plugin keeps them honest (see ESLint plugin).
Related
useState,useEffect,useRef,useMemo,useContext- Lessons: Hooks cheat sheet, Custom hooks, Rules of hooks