## Introduction: Why Context Exists React's data model is simple: data flows down through props. Parent passes data to child. Child passes data to grandchild. It's predictable and easy to trace. Until it isn't. Imagine you have a theme — light or dark — that every component in your app needs to know about. The theme lives in your root `App` component. A deeply nested `Button` component needs to read it to pick the right color. Between `App` and `Button` there are five layers of components, and none of them care about the theme. They just pass it along because `Button` needs it. This is **prop drilling**: threading props through components that don't use them, just so some descendant can access the data. It works, but it creates three problems: 1. **Noise** — Intermediate components have props they don't use, making them harder to read and refactor. 2. **Fragility** — Rename the prop in one layer and you break every layer below it. 3. **Coupling** — Components become entangled with data they have no business knowing about. React Context solves this. It lets you create a "broadcast channel" that any component in the tree can subscribe to, no matter how deeply nested, without the data passing through every layer in between. > Think of prop drilling as passing a note through every person in a room until it reaches someone in the back corner. Context is a PA system — you speak once and everyone who's listening hears it directly. By the end of this guide you will: - Understand what Context is, how it works, and its full API surface - Build real features (theme switcher, auth system) with properly typed Context - Know how to type Context correctly in TypeScript — including the patterns that prevent runtime errors - Understand exactly how Context triggers re-renders and how to optimize them - Combine Context with `useReducer` for scalable state management - Compose multiple providers cleanly - Know when Context is the right tool and when a state management library is better - Avoid the common pitfalls that cause performance problems and bugs - Test components that consume Context Examples in this guide use **TypeScript** so you can see how Context types work in practice. The concepts are the same in JavaScript; the types are there to make the API clear and to give you a reference for your own code. Let's start with the fundamentals. --- ## What Is React Context? At its core, React Context is a way to pass data through the component tree without passing props manually at every level. It consists of three pieces: 1. **`createContext`** — Creates a context object (the "channel") 2. **`Provider`** — A component that broadcasts a value to the tree below it 3. **`useContext`** — A hook that lets any component subscribe to that value Here's the simplest possible example: ```tsx import { createContext, useContext, useState } from 'react'; const NameContext = createContext('Guest'); function Greeting() { const name = useContext(NameContext); return

Hello, {name}!

; } function App() { return ( ); } ``` `Greeting` doesn't receive `name` as a prop. It reads it directly from the context. If `Greeting` were buried ten levels deep, it would still work — no props needed in any of the layers in between. ### Mental Model: The Broadcast Channel Think of a context as a radio station: - **`createContext`** sets up the station and picks a default broadcast ("Guest" in the example above). - **`Provider`** is the transmitter. It broadcasts a value (`"Ray"`) to everyone in range (the component subtree inside it). - **`useContext`** is the radio receiver. Any component that tunes in gets the current value from the nearest transmitter above it in the tree. If no transmitter is above you, you hear the default broadcast — the value passed to `createContext`. --- ## The Full API Surface ### `React.createContext(defaultValue)` ```tsx const ThemeContext = createContext<'light' | 'dark'>('light'); ``` This creates a context object. The `defaultValue` is **only** used when a component calls `useContext(ThemeContext)` and there is no `` anywhere above it in the tree. This might sound useless — why would you ever render without a provider? Two scenarios: 1. **Testing** — You render a component in isolation without wrapping it in the full provider tree. The default value acts as a sensible fallback. 2. **Library components** — You export a component that uses context internally. If the consumer forgets to add the provider, they get the default instead of a crash. A common mistake is thinking the default value is the "initial" value of the provider. It's not. The provider's `value` prop is always used when the provider is present. The default only kicks in when there's no provider at all. ### `` ```tsx ``` The `Provider` component accepts a `value` prop. Every descendant that calls `useContext(ThemeContext)` will receive this value. When `value` changes, **every consumer below this provider re-renders**. Key behaviors: - Providers can be **nested**. The closest provider above a consumer wins. - Changing the `value` triggers re-renders in all consumers, even if intermediate components are wrapped in `React.memo`. - The comparison is by **reference equality** (`Object.is`), not deep equality. If you pass a new object on every render, every consumer re-renders. We'll cover how to fix this later. ### `useContext(Context)` ```tsx function Button() { const theme = useContext(ThemeContext); return ; } ``` `useContext` subscribes the component to the context. When the provider's value changes, this component re-renders — regardless of whether its parent re-renders, and regardless of `React.memo`. > Context subscriptions bypass `React.memo`. If a parent is memoized and doesn't re-render, but the context value changes, the consumer child **still** re-renders. This is intentional — context changes are "pushed" directly to subscribers. ### Legacy: `Context.Consumer` (Render Prop) Before hooks, the only way to consume context in function components was the render prop pattern: ```tsx {(theme) => } ``` You'll see this in older codebases. It still works, but `useContext` is simpler and is the standard approach today. There's no reason to use `Consumer` in new code. --- ## Building a Real Feature: Theme Switcher Let's build a complete theme system. This is one of the most common uses for context. ### Step 1: Define the Context ```tsx // theme-context.tsx import { createContext, useContext, useState, useMemo, type ReactNode } from 'react'; type Theme = 'light' | 'dark'; interface ThemeContextValue { theme: Theme; toggleTheme: () => void; } const ThemeContext = createContext(undefined); ``` Notice we pass `undefined` as the default, not a real `ThemeContextValue`. This is deliberate — it forces us to handle the case where the provider is missing (we'll build a safe custom hook in the next step). ### Step 2: Build the Provider ```tsx // theme-context.tsx (continued) export function ThemeProvider({ children }: { children: ReactNode }) { const [theme, setTheme] = useState('light'); const value = useMemo( () => ({ theme, toggleTheme: () => setTheme((prev) => (prev === 'light' ? 'dark' : 'light')), }), [theme] ); return ( {children} ); } ``` We wrap the value in `useMemo` so the object reference stays stable unless `theme` actually changes. Without this, a new object would be created on every render, causing every consumer to re-render. We'll deep-dive into this optimization later. ### Step 3: Build the Custom Hook ```tsx // theme-context.tsx (continued) export function useTheme(): ThemeContextValue { const context = useContext(ThemeContext); if (context === undefined) { throw new Error('useTheme must be used within a ThemeProvider'); } return context; } ``` This custom hook does two things: 1. It narrows the type from `ThemeContextValue | undefined` to `ThemeContextValue` — so consumers never have to check for `undefined`. 2. It gives a clear error message if someone forgets to add the provider. ### Step 4: Consume It ```tsx // Header.tsx import { useTheme } from './theme-context'; function Header() { const { theme, toggleTheme } = useTheme(); return (

My App

); } ``` ```tsx // Card.tsx import { useTheme } from './theme-context'; function Card({ title, body }: { title: string; body: string }) { const { theme } = useTheme(); return (

{title}

{body}

); } ``` ### Step 5: Wire Up the Provider ```tsx // App.tsx import { ThemeProvider } from './theme-context'; import Header from './Header'; import Card from './Card'; function App() { return (

); } ``` That's it. `Header` and `Card` both read the theme directly. No prop drilling. Adding 20 more components that need the theme is trivial — they just call `useTheme()`. --- ## Building a Real Feature: Auth Context Let's build something more complex: an authentication context that tracks the current user, provides login/logout functions, and can protect routes. ### The Context ```tsx // auth-context.tsx import { createContext, useContext, useState, useMemo, useCallback, type ReactNode } from 'react'; interface User { id: string; name: string; email: string; role: 'admin' | 'user'; } interface AuthContextValue { user: User | null; isAuthenticated: boolean; login: (email: string, password: string) => Promise; logout: () => void; } const AuthContext = createContext(undefined); export function useAuth(): AuthContextValue { const context = useContext(AuthContext); if (context === undefined) { throw new Error('useAuth must be used within an AuthProvider'); } return context; } ``` ### The Provider ```tsx // auth-context.tsx (continued) export function AuthProvider({ children }: { children: ReactNode }) { const [user, setUser] = useState(null); const login = useCallback(async (email: string, password: string) => { const response = await fetch('/api/auth/login', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email, password }), }); if (!response.ok) { throw new Error('Invalid credentials'); } const userData: User = await response.json(); setUser(userData); }, []); const logout = useCallback(() => { setUser(null); }, []); const value = useMemo( () => ({ user, isAuthenticated: user !== null, login, logout, }), [user, login, logout] ); return ( {children} ); } ``` ### Consuming Auth ```tsx // Navbar.tsx import { useAuth } from './auth-context'; function Navbar() { const { user, isAuthenticated, logout } = useAuth(); return ( ); } ``` ### A Protected Route Component ```tsx // ProtectedRoute.tsx import { useAuth } from './auth-context'; import { Navigate } from 'react-router-dom'; interface ProtectedRouteProps { children: React.ReactNode; requiredRole?: 'admin' | 'user'; } function ProtectedRoute({ children, requiredRole }: ProtectedRouteProps) { const { isAuthenticated, user } = useAuth(); if (!isAuthenticated) { return ; } if (requiredRole && user?.role !== requiredRole) { return ; } return <>{children}; } ``` ```tsx // Usage in routing } /> ``` This pattern keeps authentication logic centralized. Any component in the app can check auth status with `useAuth()`, and you can protect routes declaratively. --- ## Typing Context Properly in TypeScript TypeScript and Context have a notorious rough edge: the default value. Here are the three approaches, from simplest to most robust. ### Approach 1: Non-Null Assertion (Quick and Dirty) ```tsx const ThemeContext = createContext(null!); ``` The `null!` tells TypeScript "trust me, this will never actually be null." It works, but you lose type safety — if someone consumes the context outside a provider, they get `null` at runtime with no type error at compile time. **Verdict:** Acceptable for small apps where you control every usage site. Not recommended for libraries or large codebases. ### Approach 2: Undefined Default + Custom Hook (Recommended) This is the pattern we used in the Theme and Auth examples above: ```tsx const ThemeContext = createContext(undefined); export function useTheme(): ThemeContextValue { const context = useContext(ThemeContext); if (context === undefined) { throw new Error('useTheme must be used within a ThemeProvider'); } return context; } ``` The context type is `ThemeContextValue | undefined`. The custom hook narrows it to `ThemeContextValue` and throws a descriptive error if the provider is missing. Consumers call `useTheme()` and get a guaranteed non-undefined value. **Verdict:** The best balance of safety and ergonomics. Use this for most contexts. ### Approach 3: Generic Context Factory (DRY) If you're creating many contexts, the undefined-plus-custom-hook pattern gets repetitive. You can extract it into a factory: ```tsx function createSafeContext(displayName: string) { const Context = createContext(undefined); Context.displayName = displayName; function useSafeContext(): T { const context = useContext(Context); if (context === undefined) { throw new Error(`use${displayName} must be used within a ${displayName}Provider`); } return context; } return [Context.Provider, useSafeContext] as const; } ``` Now creating a new context is one line: ```tsx const [ThemeProvider, useTheme] = createSafeContext('Theme'); const [AuthProvider, useAuth] = createSafeContext('Auth'); ``` The factory handles the `undefined` default, the type narrowing, and the error message automatically. **Verdict:** Great for teams and larger codebases. Keeps context creation consistent. ### Comparison | Approach | Type Safety | Error Clarity | Boilerplate | |----------|------------|---------------|-------------| | `null!` assertion | Low | None (silent null) | Minimal | | `undefined` + custom hook | High | Clear error message | Moderate | | Generic factory | High | Clear error message | Minimal (per context) | --- ## How Context Re-Renders Work (Under the Hood) This is the most misunderstood part of Context. Getting it wrong is the #1 source of performance problems. ### The Rule When a provider's `value` changes, **every component that calls `useContext` for that context re-renders**. Not "might re-render." Not "re-renders if it needs the changed data." **Every consumer, unconditionally.** React uses `Object.is` to compare the old value and new value. If `Object.is(oldValue, newValue)` returns `false`, all consumers re-render. ### Why Inline Objects Are Dangerous Consider this provider: ```tsx function App() { const [user, setUser] = useState(null); const [theme, setTheme] = useState<'light' | 'dark'>('light'); return ( ); } ``` Every time `App` re-renders (which happens on every state change), a **new object** is created for the `value` prop: `{ user, theme, setUser, setTheme }`. Even if `user` and `theme` haven't changed, the object reference is different. `Object.is(oldObj, newObj)` returns `false` because they're different object references. So **every consumer in the entire tree re-renders**, even though the actual data is identical. ### Visualizing the Re-Render Cascade ``` App (state changes) └── AppContext.Provider (new value object → Object.is returns false) ├── Header (useContext → RE-RENDERS) │ ├── Logo (no useContext → skipped*) │ └── ThemeToggle (useContext → RE-RENDERS) ├── Sidebar (React.memo, no useContext → SKIPPED) │ └── NavLink (useContext → RE-RENDERS even though Sidebar didn't) └── Main ├── UserProfile (useContext → RE-RENDERS) └── PostList (no useContext → re-renders because Main re-rendered) * "Skipped" means React.memo prevented re-render. But context consumers bypass React.memo — they always re-render. ``` Notice `NavLink`: its parent `Sidebar` is wrapped in `React.memo` and didn't re-render. But `NavLink` consumes context, so it re-renders anyway. Context subscriptions are **direct** — they don't flow through the parent. ### What `Object.is` Checks ```tsx Object.is('dark', 'dark') // true — same primitive Object.is(42, 42) // true — same primitive Object.is(userObj, userObj) // true — same reference Object.is(userObj, { ...userObj }) // false — different reference, even if same contents Object.is({ a: 1 }, { a: 1 }) // false — two different objects ``` This is why primitives are "free" — `Object.is('dark', 'dark')` is `true`, so consumers don't re-render. But objects and arrays need to be the same reference, which means you must **memoize** them. --- ## Performance Optimization Patterns Now that you understand the re-render mechanics, here are the patterns to keep things fast. ### Pattern 1: Memoize the Provider Value The first and most important optimization: wrap your provider value in `useMemo`. ```tsx // BAD — new object on every render function AppProvider({ children }: { children: ReactNode }) { const [count, setCount] = useState(0); return ( {children} ); } // GOOD — stable reference when count hasn't changed function AppProvider({ children }: { children: ReactNode }) { const [count, setCount] = useState(0); const value = useMemo(() => ({ count, setCount }), [count]); return ( {children} ); } ``` With `useMemo`, the object is only recreated when `count` changes. `setCount` is stable (React guarantees this for state setters), so it doesn't need to be in the dependency array. > For a deeper look at how `useMemo` works and when to use it, see the **useMemo vs useCallback: The Complete Deep Dive** article. ### Pattern 2: Split Read and Write Contexts The most powerful optimization: separate state from dispatch. Consider a context with both user data and a setter function. Components that only need to read the user (e.g., displaying the name) should not re-render when some other component calls the setter — but with a single context, they do. The fix: two contexts. ```tsx // split-context.tsx import { createContext, useContext, useState, useMemo, type ReactNode } from 'react'; interface User { id: string; name: string; } type UserDispatch = React.Dispatch>; const UserStateContext = createContext(undefined); const UserDispatchContext = createContext(undefined); export function UserProvider({ children }: { children: ReactNode }) { const [user, setUser] = useState(null); return ( {children} ); } export function useUserState(): User | null { const context = useContext(UserStateContext); if (context === undefined) { throw new Error('useUserState must be used within a UserProvider'); } return context; } export function useUserDispatch(): UserDispatch { const context = useContext(UserDispatchContext); if (context === undefined) { throw new Error('useUserDispatch must be used within a UserProvider'); } return context; } ``` Now `useUserState()` subscribers only re-render when the user data changes. Components that call `useUserDispatch()` to get the setter never re-render because of context — `setUser` is a stable reference. ```tsx // DisplayName only re-renders when user changes function DisplayName() { const user = useUserState(); return {user?.name ?? 'Guest'}; } // LogoutButton never re-renders from context (setUser is stable) function LogoutButton() { const setUser = useUserDispatch(); return ; } ``` ### Pattern 3: Component Composition (Children Pattern) Sometimes the best optimization is architectural. Instead of wrapping a massive tree in a provider where the provider also holds state, lift the state-consuming part out so the rest of the tree is passed as `children`. ```tsx // BAD — Counter state causes entire tree to re-render function App() { const [count, setCount] = useState(0); return (

); } // GOOD — ExpensiveTree is passed as children and doesn't re-render function Counter({ children }: { children: ReactNode }) { const [count, setCount] = useState(0); return (

{children}

); } function App() { return ( ); } ``` `ExpensiveTree` is created in `App`, not inside `Counter`. When `Counter` re-renders, `children` is the same JSX reference — React skips re-rendering it. This pattern applies directly to context providers. ### Pattern 4: `React.memo` on Consumer Children If a context consumer renders expensive children that don't depend on context, memoize them: ```tsx const MemoizedChart = React.memo(Chart); function Dashboard() { const { theme } = useTheme(); return (

); } ``` `Dashboard` re-renders when the theme changes, but `MemoizedChart` only re-renders if its `data` prop changes. If `staticData` is a stable reference, the chart stays put. ### Optimization Decision Tree ``` Is the context value an object or array? ├── YES → Wrap in useMemo │ └── Do different consumers need different parts? │ ├── YES → Split into multiple contexts (read vs write) │ └── NO → Single context with useMemo is fine └── NO (primitive like string or number) → No optimization needed ``` --- ## Context + useReducer: The "Mini Redux" Pattern For complex state with multiple actions, `useReducer` is a better fit than `useState`. Combined with context, it gives you a centralized, predictable state management system — often called "mini Redux." ### Why useReducer? `useState` is great for simple state. But when you have state that involves multiple sub-values, or when the next state depends on the previous state in complex ways, `useReducer` is clearer: ```tsx // With useState — multiple related setters, easy to get out of sync setItems([...items, newItem]); setTotal(total + newItem.price); setCount(count + 1); // With useReducer — one dispatch, one place where state changes dispatch({ type: 'ADD_ITEM', payload: newItem }); ``` ### Full Example: Shopping Cart ```tsx // cart-context.tsx import { createContext, useContext, useReducer, useMemo, type ReactNode, type Dispatch, } from 'react'; // --- Types --- interface CartItem { id: string; name: string; price: number; quantity: number; } interface CartState { items: CartItem[]; total: number; } type CartAction = | { type: 'ADD_ITEM'; payload: Omit } | { type: 'REMOVE_ITEM'; payload: { id: string } } | { type: 'UPDATE_QUANTITY'; payload: { id: string; quantity: number } } | { type: 'CLEAR_CART' }; // --- Reducer --- function cartReducer(state: CartState, action: CartAction): CartState { switch (action.type) { case 'ADD_ITEM': { const existing = state.items.find((item) => item.id === action.payload.id); if (existing) { const items = state.items.map((item) => item.id === action.payload.id ? { ...item, quantity: item.quantity + 1 } : item ); return { items, total: state.total + action.payload.price }; } const items = [...state.items, { ...action.payload, quantity: 1 }]; return { items, total: state.total + action.payload.price }; } case 'REMOVE_ITEM': { const item = state.items.find((i) => i.id === action.payload.id); if (!item) return state; const items = state.items.filter((i) => i.id !== action.payload.id); return { items, total: state.total - item.price * item.quantity }; } case 'UPDATE_QUANTITY': { const item = state.items.find((i) => i.id === action.payload.id); if (!item) return state; const diff = action.payload.quantity - item.quantity; const items = state.items.map((i) => i.id === action.payload.id ? { ...i, quantity: action.payload.quantity } : i ); return { items, total: state.total + diff * item.price }; } case 'CLEAR_CART': return { items: [], total: 0 }; default: return state; } } // --- Contexts (split state and dispatch) --- const CartStateContext = createContext(undefined); const CartDispatchContext = createContext | undefined>(undefined); // --- Provider --- const initialState: CartState = { items: [], total: 0 }; export function CartProvider({ children }: { children: ReactNode }) { const [state, dispatch] = useReducer(cartReducer, initialState); return ( {children} ); } // --- Hooks --- export function useCartState(): CartState { const context = useContext(CartStateContext); if (context === undefined) { throw new Error('useCartState must be used within a CartProvider'); } return context; } export function useCartDispatch(): Dispatch { const context = useContext(CartDispatchContext); if (context === undefined) { throw new Error('useCartDispatch must be used within a CartProvider'); } return context; } ``` Notice that we split into `CartStateContext` and `CartDispatchContext`. The `dispatch` function from `useReducer` is stable (React guarantees this), so components that only dispatch actions never re-render from context changes. ### Using the Cart ```tsx // AddToCartButton.tsx — only uses dispatch, never re-renders from cart changes function AddToCartButton({ item }: { item: { id: string; name: string; price: number } }) { const dispatch = useCartDispatch(); return ( ); } ``` ```tsx // CartSummary.tsx — reads state, re-renders when cart changes function CartSummary() { const { items, total } = useCartState(); return (

Cart ({items.length} items)

{item.name} × {item.quantity} — ${(item.price * item.quantity).toFixed(2)}

Total: ${total.toFixed(2)}

); } ``` ```tsx // CartItem.tsx — reads state AND dispatches function CartItemRow({ item }: { item: CartItem }) { const dispatch = useCartDispatch(); return (

{item.name} dispatch({ type: 'UPDATE_QUANTITY', payload: { id: item.id, quantity: parseInt(e.target.value, 10) }, }) } />

); } ``` This is a production-ready pattern. The reducer is pure, testable, and all state transitions are centralized. The split contexts keep re-renders minimal. ### When to Use useReducer vs useState with Context | Scenario | Use | |----------|-----| | 1-2 simple state values | `useState` | | Multiple related values that change together | `useReducer` | | Complex state transitions with many action types | `useReducer` | | State machine behavior (e.g., loading → success → error) | `useReducer` | | You want to pass dispatch to deeply nested children | `useReducer` (dispatch is stable) | --- ## Nested and Composed Providers Real apps have multiple contexts: theme, auth, locale, cart, notifications, feature flags. Nesting them in `App` can get unwieldy: ```tsx // The "provider hell" problem function App() { return ( ); } ``` This works, but it's hard to read and maintain. Here's how to clean it up. ### Compose Providers ```tsx // compose-providers.tsx import type { ReactNode, ComponentType } from 'react'; interface ProviderProps { children: ReactNode; } export function ComposeProviders({ providers, children, }: { providers: ComponentType[]; children: ReactNode; }) { return providers.reduceRight( (acc, Provider) => {acc}, children ); } ``` Now the app is flat and readable: ```tsx function App() { return ( ); } ``` ### Provider Ordering Order matters when providers depend on each other. If `CartProvider` needs to read the auth context (e.g., to load the user's saved cart), `AuthProvider` must be higher in the tree: ```tsx providers={[ ThemeProvider, // No dependencies AuthProvider, // No dependencies CartProvider, // Depends on AuthProvider NotificationProvider, // Depends on AuthProvider ]} ``` A provider can only consume contexts that are above it in the tree. If you get the order wrong, the custom hook will throw the "must be used within" error, which is exactly the safety net we built. ### Nested Providers (Same Context, Different Values) You can nest the same provider to override values for a subtree: ```tsx {/* light theme */}

{/* reads "light" */} {/* override for this subtree */} {/* reads "dark" */}

React Context: The Complete Deep Dive