React useContext Guide

useContext provides a way to share values between components without passing props through every level of the tree.

Basic Usage#

import { createContext, useContext } from 'react';

// Create context with default value
const ThemeContext = createContext('light');

// Provider component
function App() {
  return (
    <ThemeContext.Provider value="dark">
      <Toolbar />
    </ThemeContext.Provider>
  );
}

// Consuming context
function Toolbar() {
  return <ThemedButton />;
}

function ThemedButton() {
  const theme = useContext(ThemeContext);
  return <button className={theme}>Click me</button>;
}

Creating Context with Types#

// Define context type
interface User {
  id: number;
  name: string;
  email: string;
}

interface UserContextType {
  user: User | null;
  login: (user: User) => void;
  logout: () => void;
}

// Create with undefined default (requires null check)
const UserContext = createContext<UserContextType | undefined>(undefined);

// Custom hook with null check
function useUser() {
  const context = useContext(UserContext);
  if (context === undefined) {
    throw new Error('useUser must be used within UserProvider');
  }
  return context;
}

Provider Pattern#

import { createContext, useContext, useState, useMemo } from 'react';

const AuthContext = createContext(null);

function AuthProvider({ children }) {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);

  const login = async (credentials) => {
    setLoading(true);
    const user = await authService.login(credentials);
    setUser(user);
    setLoading(false);
  };

  const logout = async () => {
    await authService.logout();
    setUser(null);
  };

  // Memoize value to prevent unnecessary re-renders
  const value = useMemo(() => ({
    user,
    loading,
    login,
    logout,
    isAuthenticated: !!user
  }), [user, loading]);

  return (
    <AuthContext.Provider value={value}>
      {children}
    </AuthContext.Provider>
  );
}

// Custom hook
function useAuth() {
  const context = useContext(AuthContext);
  if (!context) {
    throw new Error('useAuth must be used within AuthProvider');
  }
  return context;
}

// Usage
function App() {
  return (
    <AuthProvider>
      <Navigation />
      <MainContent />
    </AuthProvider>
  );
}

function Navigation() {
  const { user, logout } = useAuth();

  return (
    <nav>
      {user ? (
        <>
          <span>Hello, {user.name}</span>
          <button onClick={logout}>Logout</button>
        </>
      ) : (
        <LoginButton />
      )}
    </nav>
  );
}

Multiple Contexts#

// Theme context
const ThemeContext = createContext({ theme: 'light', toggleTheme: () => {} });

// Language context
const LanguageContext = createContext({ language: 'en', setLanguage: () => {} });

// Combined providers
function AppProviders({ children }) {
  return (
    <ThemeProvider>
      <LanguageProvider>
        <AuthProvider>
          {children}
        </AuthProvider>
      </LanguageProvider>
    </ThemeProvider>
  );
}

// Consume multiple contexts
function Settings() {
  const { theme, toggleTheme } = useContext(ThemeContext);
  const { language, setLanguage } = useContext(LanguageContext);

  return (
    <div>
      <button onClick={toggleTheme}>
        Theme: {theme}
      </button>
      <select value={language} onChange={e => setLanguage(e.target.value)}>
        <option value="en">English</option>
        <option value="es">Spanish</option>
      </select>
    </div>
  );
}

Context with Reducer#

import { createContext, useContext, useReducer } from 'react';

// Define actions
const ACTIONS = {
  ADD_TODO: 'ADD_TODO',
  TOGGLE_TODO: 'TOGGLE_TODO',
  DELETE_TODO: 'DELETE_TODO'
};

// Reducer
function todoReducer(state, action) {
  switch (action.type) {
    case ACTIONS.ADD_TODO:
      return [...state, {
        id: Date.now(),
        text: action.payload,
        completed: false
      }];
    case ACTIONS.TOGGLE_TODO:
      return state.map(todo =>
        todo.id === action.payload
          ? { ...todo, completed: !todo.completed }
          : todo
      );
    case ACTIONS.DELETE_TODO:
      return state.filter(todo => todo.id !== action.payload);
    default:
      return state;
  }
}

// Separate contexts for state and dispatch
const TodoStateContext = createContext();
const TodoDispatchContext = createContext();

function TodoProvider({ children }) {
  const [todos, dispatch] = useReducer(todoReducer, []);

  return (
    <TodoStateContext.Provider value={todos}>
      <TodoDispatchContext.Provider value={dispatch}>
        {children}
      </TodoDispatchContext.Provider>
    </TodoStateContext.Provider>
  );
}

// Custom hooks
function useTodos() {
  const context = useContext(TodoStateContext);
  if (context === undefined) {
    throw new Error('useTodos must be within TodoProvider');
  }
  return context;
}

function useTodoDispatch() {
  const context = useContext(TodoDispatchContext);
  if (context === undefined) {
    throw new Error('useTodoDispatch must be within TodoProvider');
  }
  return context;
}

// Usage
function TodoList() {
  const todos = useTodos();
  const dispatch = useTodoDispatch();

  return (
    <ul>
      {todos.map(todo => (
        <li key={todo.id}>
          <span
            style={{ textDecoration: todo.completed ? 'line-through' : 'none' }}
            onClick={() => dispatch({
              type: ACTIONS.TOGGLE_TODO,
              payload: todo.id
            })}
          >
            {todo.text}
          </span>
          <button onClick={() => dispatch({
            type: ACTIONS.DELETE_TODO,
            payload: todo.id
          })}>
            Delete
          </button>
        </li>
      ))}
    </ul>
  );
}

Performance Optimization#

import { createContext, useContext, useState, useMemo, useCallback, memo } from 'react';

// Split context to avoid unnecessary re-renders
const CountContext = createContext();
const CountActionsContext = createContext();

function CountProvider({ children }) {
  const [count, setCount] = useState(0);

  // Memoize actions
  const actions = useMemo(() => ({
    increment: () => setCount(c => c + 1),
    decrement: () => setCount(c => c - 1),
    reset: () => setCount(0)
  }), []);

  return (
    <CountContext.Provider value={count}>
      <CountActionsContext.Provider value={actions}>
        {children}
      </CountActionsContext.Provider>
    </CountContext.Provider>
  );
}

// Component that only reads count
const CountDisplay = memo(function CountDisplay() {
  const count = useContext(CountContext);
  console.log('CountDisplay rendered');
  return <div>Count: {count}</div>;
});

// Component that only uses actions
const CountButtons = memo(function CountButtons() {
  const { increment, decrement, reset } = useContext(CountActionsContext);
  console.log('CountButtons rendered');

  return (
    <div>
      <button onClick={decrement}>-</button>
      <button onClick={increment}>+</button>
      <button onClick={reset}>Reset</button>
    </div>
  );
});

Default Values#

// Context with meaningful default
const ThemeContext = createContext({
  theme: 'light',
  toggleTheme: () => {
    console.warn('toggleTheme called outside provider');
  }
});

// Can use without provider (fallback to default)
function Button() {
  const { theme } = useContext(ThemeContext);
  return <button className={`btn-${theme}`}>Click</button>;
}

// Provider overrides default
function App() {
  const [theme, setTheme] = useState('light');

  const value = useMemo(() => ({
    theme,
    toggleTheme: () => setTheme(t => t === 'light' ? 'dark' : 'light')
  }), [theme]);

  return (
    <ThemeContext.Provider value={value}>
      <Button />
    </ThemeContext.Provider>
  );
}

Nested Providers#

// Providers can be nested and override
function App() {
  return (
    <ThemeContext.Provider value="light">
      <Header />
      <ThemeContext.Provider value="dark">
        <Sidebar />
      </ThemeContext.Provider>
      <Footer />
    </ThemeContext.Provider>
  );
}

// Header and Footer get "light"
// Sidebar gets "dark"

Context Selectors (Custom Pattern)#

// Without selectors: all consumers re-render on any change
const BigContext = createContext();

function useBigContext() {
  return useContext(BigContext);
}

// Every component re-renders when anything changes
function UserName() {
  const { user } = useBigContext();  // Re-renders on any context change
  return <span>{user.name}</span>;
}

// With selector pattern (using useSyncExternalStore or libraries)
import { useSyncExternalStore } from 'react';

function createStore(initialState) {
  let state = initialState;
  const listeners = new Set();

  return {
    getState: () => state,
    setState: (newState) => {
      state = { ...state, ...newState };
      listeners.forEach(l => l());
    },
    subscribe: (listener) => {
      listeners.add(listener);
      return () => listeners.delete(listener);
    }
  };
}

function useSelector(store, selector) {
  return useSyncExternalStore(
    store.subscribe,
    () => selector(store.getState())
  );
}

// Only re-renders when selected value changes
function UserName({ store }) {
  const name = useSelector(store, state => state.user.name);
  return <span>{name}</span>;
}

Testing with Context#

// Component using context
function Greeting() {
  const { user } = useAuth();
  return <h1>Hello, {user?.name || 'Guest'}</h1>;
}

// Test wrapper
function renderWithAuth(ui, { user = null } = {}) {
  const mockAuth = {
    user,
    login: jest.fn(),
    logout: jest.fn()
  };

  return render(
    <AuthContext.Provider value={mockAuth}>
      {ui}
    </AuthContext.Provider>
  );
}

// Tests
test('shows guest when not logged in', () => {
  renderWithAuth(<Greeting />);
  expect(screen.getByText('Hello, Guest')).toBeInTheDocument();
});

test('shows user name when logged in', () => {
  renderWithAuth(<Greeting />, { user: { name: 'John' } });
  expect(screen.getByText('Hello, John')).toBeInTheDocument();
});

Common Patterns#

// Feature flag context
const FeatureFlagContext = createContext({});

function useFeatureFlag(flag) {
  const flags = useContext(FeatureFlagContext);
  return flags[flag] ?? false;
}

function NewFeature() {
  const enabled = useFeatureFlag('newDashboard');

  if (!enabled) return null;
  return <NewDashboard />;
}

// Modal context
const ModalContext = createContext();

function ModalProvider({ children }) {
  const [modal, setModal] = useState(null);

  const openModal = useCallback((content) => setModal(content), []);
  const closeModal = useCallback(() => setModal(null), []);

  return (
    <ModalContext.Provider value={{ openModal, closeModal }}>
      {children}
      {modal && (
        <div className="modal-overlay" onClick={closeModal}>
          <div className="modal" onClick={e => e.stopPropagation()}>
            {modal}
          </div>
        </div>
      )}
    </ModalContext.Provider>
  );
}

Best Practices#

Context Design:
✓ Split state and dispatch contexts
✓ Memoize context values
✓ Create custom hooks
✓ Use meaningful defaults

Performance:
✓ Keep context values stable
✓ Split contexts by update frequency
✓ Use memo for consumers
✓ Consider external state libraries for complex needs

Organization:
✓ One context per concern
✓ Colocate provider with related components
✓ Export custom hooks, not raw context
✓ Document context requirements

Avoid:
✗ Putting everything in one context
✗ Frequent context value updates
✗ Deeply nested providers
✗ Using context for local state

useContext eliminates prop drilling and enables clean state sharing across component trees. Create custom hooks to encapsulate context access, split contexts by update frequency for performance, and memoize values to prevent unnecessary re-renders. For complex state management, consider combining context with useReducer or external libraries.