Mastering React Context in TypeScript: From Basics to Advanced Patterns

October 23, 2025
•
Rabra Hierpa
Mastering react context in typescript

React Context is a powerful feature for sharing state across your component tree without prop drilling. However, writing type-safe, maintainable contexts in TypeScript requires understanding several patterns and best practices. In this post, we’ll progress from traditional context patterns to advanced type-safe approaches that leverage TypeScript’s type system.

The Traditional Way: Basic Context Setup

Let’s start with the most straightforward approach you’ll see in the React documentation. We’ll build a theme context as our example.

import React, { createContext, useContext, useState, ReactNode } from 'react';

// Define our context type
type Theme = 'light' | 'dark';

interface ThemeContextType {
  theme: Theme;
  toggleTheme: () => void;
}

// Create context with undefined default value
const ThemeContext = createContext<ThemeContextType | undefined>(undefined);

// Provider component
export function ThemeProvider({ children }: { children: ReactNode }) {
  const [theme, setTheme] = useState<Theme>('light');

  const toggleTheme = () => {
    setTheme(prev => prev === 'light' ? 'dark' : 'light');
  };

  return (
    <ThemeContext.Provider value={{ theme, toggleTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

// Consumer hook
export function useTheme() {
  const context = useContext(ThemeContext);
  if (context === undefined) {
    throw new Error('useTheme must be used within a ThemeProvider');
  }
  return context;
}

Usage

function App() {
  return (
    <ThemeProvider>
      <Header />
      <Main />
    </ThemeProvider>
  );
}

function Header() {
  const { theme, toggleTheme } = useTheme();

  return (
    <header style={{ background: theme === 'light' ? '#fff' : '#333' }}>
      <button onClick={toggleTheme}>
        Switch to {theme === 'light' ? 'dark' : 'light'} mode
      </button>
    </header>
  );
}

Problems with This Approach

While this pattern works, it has several issues:

  1. Boilerplate: Every context requires the same setup pattern
  2. Separate exports: Provider and hook are separate, easy to forget one
  3. Runtime error: Type safety fails if you forget the provider
  4. No provider props typing: Adding configuration to the provider requires manual typing

Better Pattern: Encapsulated Context Factory

Let’s improve this by creating a reusable factory function that encapsulates the context creation logic.

import React, { createContext, useContext, ReactNode } from 'react';

export function createContextProvider<T>(hookValue: () => T, displayName?: string) {
  const Context = createContext<T | undefined>(undefined);

  if (displayName) {
    Context.displayName = displayName;
  }

  function Provider({ children }: { children: ReactNode }) {
    const value = hookValue();
    return <Context.Provider value={value}>{children}</Context.Provider>;
  }

  function useContextHook() {
    const context = useContext(Context);
    if (context === undefined) {
      throw new Error(
        `use${displayName || 'Context'} must be used within ${displayName || 'Context'}Provider`
      );
    }
    return context;
  }

  return [Provider, useContextHook] as const;
}

Usage with Factory

import { useState } from 'react';

// Define the hook that contains our context logic
function useThemeState() {
  const [theme, setTheme] = useState<'light' | 'dark'>('light');

  const toggleTheme = () => {
    setTheme(prev => prev === 'light' ? 'dark' : 'light');
  };

  return { theme, toggleTheme };
}

// Create the provider and hook in one go
const [ThemeProvider, useTheme] = createContextProvider(useThemeState, 'Theme');

export { ThemeProvider, useTheme };

This is cleaner, but we still have limitations: the Provider doesn’t accept any props beyond children.

Advanced Pattern: Provider with Props using typeof

Now let’s level up. Often, you want your context provider to accept configuration props. Here’s where TypeScript’s typeof operator becomes powerful.

import React, { createContext, useContext, ReactNode, ComponentType } from 'react';

export function createSafeContext<TValue, TProviderProps = {}>() {
  const Context = createContext<TValue | undefined>(undefined);

  function useContextHook(contextName?: string) {
    const context = useContext(Context);
    if (context === undefined) {
      throw new Error(
        `use${contextName || 'Context'} must be used within a ${contextName || 'Context'}Provider`
      );
    }
    return context;
  }

  return {
    Context,
    useContextHook,
    createProvider: <TProps extends TProviderProps>(
      useValue: (props: TProps) => TValue
    ) => {
      const Provider = ({ children, ...props }: TProps & { children: ReactNode }) => {
        const value = useValue(props as TProps);
        return <Context.Provider value={value}>{children}</Context.Provider>;
      };
      return Provider;
    },
  };
}

Usage with Configurable Provider

import { useState, useCallback } from 'react';

// Define provider props
interface ThemeProviderProps {
  initialTheme?: 'light' | 'dark';
  onThemeChange?: (theme: 'light' | 'dark') => void;
}

// Define context value
interface ThemeContextValue {
  theme: 'light' | 'dark';
  toggleTheme: () => void;
  setTheme: (theme: 'light' | 'dark') => void;
}

// Create the context structure
const { useContextHook, createProvider } = createSafeContext<
  ThemeContextValue,
  ThemeProviderProps
>();

// Create the provider with configuration
const ThemeProvider = createProvider(({ initialTheme = 'light', onThemeChange }) => {
  const [theme, setThemeState] = useState<'light' | 'dark'>(initialTheme);

  const setTheme = useCallback((newTheme: 'light' | 'dark') => {
    setThemeState(newTheme);
    onThemeChange?.(newTheme);
  }, [onThemeChange]);

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

  return { theme, toggleTheme, setTheme };
});

// Export hook with proper name
export const useTheme = () => useContextHook('Theme');
export { ThemeProvider };

Using the Advanced Provider

function App() {
  return (
    <ThemeProvider 
      initialTheme="dark"
      onThemeChange={(theme) => {
        console.log('Theme changed to:', theme);
        localStorage.setItem('theme', theme);
      }}
    >
      <Header />
      <Main />
    </ThemeProvider>
  );
}

The Ultimate Pattern: Type Extraction with typeof

Let’s take it one step further. We can use TypeScript’s typeof to extract the provider’s component props automatically, ensuring type consistency.

import React, { createContext, useContext, ReactNode } from 'react';

/**
 * Creates a type-safe context with automatic type inference
 */
export function createTypedContext<TValue>() {
  const Context = createContext<TValue | undefined>(undefined);

  const Provider = Context.Provider;

  function useTypedContext(hookName?: string) {
    const context = useContext(Context);
    if (context === undefined) {
      const name = hookName || 'this context';
      throw new Error(`use${name} must be used within a ${name}Provider`);
    }
    return context;
  }

  return [Provider, useTypedContext, Context] as const;
}

/**
 * Helper to create a context with a custom provider component
 */
export function defineContext<TValue, TProps = {}>() {
  const Context = createContext<TValue | undefined>(undefined);

  function useDefinedContext(hookName?: string) {
    const context = useContext(Context);
    if (context === undefined) {
      throw new Error(
        `${hookName || 'useContext'} must be used within the corresponding Provider`
      );
    }
    return context;
  }

  function defineProvider<P extends TProps & { children: ReactNode }>(
    useProviderValue: (props: Omit<P, 'children'>) => TValue
  ) {
    const ProviderComponent = (props: P) => {
      const { children, ...otherProps } = props;
      const value = useProviderValue(otherProps as Omit<P, 'children'>);
      return <Context.Provider value={value}>{children}</Context.Provider>;
    };

    return ProviderComponent;
  }

  return {
    useContext: useDefinedContext,
    defineProvider,
    Context,
  };
}

Real-World Example: Authentication Context

import { useState, useCallback, useEffect } from 'react';

interface User {
  id: string;
  email: string;
  name: string;
}

interface AuthContextValue {
  user: User | null;
  isLoading: boolean;
  isAuthenticated: boolean;
  login: (email: string, password: string) => Promise<void>;
  logout: () => void;
  refreshUser: () => Promise<void>;
}

// Create the context structure
const { useContext: useAuthContext, defineProvider, Context: AuthContext } = 
  defineContext<AuthContextValue>();

// Define the provider
const AuthProvider = defineProvider<{
  children: ReactNode;
  apiUrl?: string;
  onAuthChange?: (user: User | null) => void;
}>(({ apiUrl = '/api', onAuthChange }) => {
  const [user, setUser] = useState<User | null>(null);
  const [isLoading, setIsLoading] = useState(true);

  const login = useCallback(async (email: string, password: string) => {
    setIsLoading(true);
    try {
      const response = await fetch(`${apiUrl}/auth/login`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ email, password }),
      });
      const userData = await response.json();
      setUser(userData);
      onAuthChange?.(userData);
    } finally {
      setIsLoading(false);
    }
  }, [apiUrl, onAuthChange]);

  const logout = useCallback(() => {
    setUser(null);
    onAuthChange?.(null);
  }, [onAuthChange]);

  const refreshUser = useCallback(async () => {
    setIsLoading(true);
    try {
      const response = await fetch(`${apiUrl}/auth/me`);
      const userData = await response.json();
      setUser(userData);
      onAuthChange?.(userData);
    } finally {
      setIsLoading(false);
    }
  }, [apiUrl, onAuthChange]);

  useEffect(() => {
    refreshUser();
  }, [refreshUser]);

  return {
    user,
    isLoading,
    isAuthenticated: user !== null,
    login,
    logout,
    refreshUser,
  };
});

// Export with explicit type using typeof - THIS IS THE KEY PATTERN
export { AuthProvider };
export const useAuth = () => useAuthContext('Auth');

// You can also extract the provider props type
export type AuthProviderProps = React.ComponentProps<typeof AuthProvider>;

Extracting and Using Provider Types

The power of typeof shines when you need to reference provider props elsewhere:

// Extract the props type from the provider component
type AuthProviderConfiguration = Omit<
  React.ComponentProps<typeof AuthProvider>, 
  'children'
>;

// Use it in a configuration object
const authConfig: AuthProviderConfiguration = {
  apiUrl: process.env.REACT_APP_API_URL,
  onAuthChange: (user) => {
    console.log('Auth state changed:', user);
  },
};

// Compose providers with type safety
function AppProviders({ children }: { children: ReactNode }) {
  return (
    <AuthProvider {...authConfig}>
      <ThemeProvider initialTheme="dark">
        {children}
      </ThemeProvider>
    </AuthProvider>
  );
}

Advanced: Composing Multiple Contexts

When working with multiple contexts, you can create a composer utility:

import React, { ReactNode, ComponentType } from 'react';

type ProviderProps = { children: ReactNode };
type Provider = ComponentType<ProviderProps> | [ComponentType<any>, Record<string, any>];

export function composeProviders(...providers: Provider[]) {
  return function ComposedProviders({ children }: ProviderProps) {
    return providers.reduceRight((acc, provider) => {
      if (Array.isArray(provider)) {
        const [ProviderComponent, props] = provider;
        return <ProviderComponent {...props}>{acc}</ProviderComponent>;
      }
      const ProviderComponent = provider;
      return <ProviderComponent>{acc}</ProviderComponent>;
    }, children as React.ReactElement);
  };
}

Usage

// Without props
const AppProviders = composeProviders(
  AuthProvider,
  ThemeProvider,
  NotificationProvider
);

// With props using tuples
const AppProviders = composeProviders(
  [AuthProvider, { apiUrl: '/api/v1' }],
  [ThemeProvider, { initialTheme: 'dark' }],
  NotificationProvider
);

function App() {
  return (
    <AppProviders>
      <YourApp />
    </AppProviders>
  );
}

Best Practices

1. Always Provide Display Names

const ThemeProvider = defineProvider(/* ... */);
ThemeProvider.displayName = 'ThemeProvider';

2. Use Separate Files for Complex Contexts

contexts/
├── auth/
│   ├── AuthContext.tsx
│   ├── AuthProvider.tsx
│   ├── useAuth.ts
│   └── index.ts
└── theme/
    ├── ThemeContext.tsx
    ├── ThemeProvider.tsx
    ├── useTheme.ts
    └── index.ts

3. Memoize Context Values

const AuthProvider = defineProvider(({ apiUrl }) => {
  // ... state declarations

  // Memoize the context value
  const value = useMemo(
    () => ({
      user,
      isLoading,
      isAuthenticated: user !== null,
      login,
      logout,
      refreshUser,
    }),
    [user, isLoading, login, logout, refreshUser]
  );

  return value;
});

4. Split Contexts by Responsibility

Don’t create one giant context for everything. Split by domain:

// ✅ Good - separate contexts
<AuthProvider>
  <ThemeProvider>
    <NotificationProvider>
      <App />
    </NotificationProvider>
  </ThemeProvider>
</AuthProvider>

// ❌ Bad - one context for everything
<AppProvider> {/* contains auth, theme, notifications, etc. */}
  <App />
</AppProvider>

5. Provide Sensible Defaults When Possible

const { defineProvider } = defineContext<ThemeContextValue>();

const ThemeProvider = defineProvider<{
  children: ReactNode;
  initialTheme?: 'light' | 'dark'; // Optional with default
  storageKey?: string; // Optional with default
}>(({ initialTheme = 'light', storageKey = 'app-theme' }) => {
  // Implementation with defaults
  const [theme, setTheme] = useState<'light' | 'dark'>(
    () => (localStorage.getItem(storageKey) as 'light' | 'dark') || initialTheme
  );

  // ...
});

Performance Considerations

Context Splitting for Performance

If parts of your context update frequently, split them:

// Split into separate contexts
const [UserProvider, useUser] = createContextProvider(/* user data */);
const [UserActionsProvider, useUserActions] = createContextProvider(/* actions */);

// Compose them
function AuthProvider({ children }: { children: ReactNode }) {
  return (
    <UserProvider>
      <UserActionsProvider>
        {children}
      </UserActionsProvider>
    </UserProvider>
  );
}

Use Context Selectors for Large State

For complex state, consider using a library like use-context-selector or implement your own:

import { useContextSelector } from 'use-context-selector';

// Instead of
const { user, settings, preferences } = useApp();

// Use selectors
const userName = useContextSelector(AppContext, state => state.user.name);
const theme = useContextSelector(AppContext, state => state.settings.theme);

Testing Context Providers

import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

describe('ThemeProvider', () => {
  it('provides theme value and toggle function', () => {
    function TestComponent() {
      const { theme, toggleTheme } = useTheme();
      return (
        <div>
          <span data-testid="theme">{theme}</span>
          <button onClick={toggleTheme}>Toggle</button>
        </div>
      );
    }

    render(
      <ThemeProvider initialTheme="light">
        <TestComponent />
      </ThemeProvider>
    );

    expect(screen.getByTestId('theme')).toHaveTextContent('light');
  });

  it('calls onThemeChange callback', async () => {
    const onThemeChange = jest.fn();
    const user = userEvent.setup();

    function TestComponent() {
      const { toggleTheme } = useTheme();
      return <button onClick={toggleTheme}>Toggle</button>;
    }

    render(
      <ThemeProvider initialTheme="light" onThemeChange={onThemeChange}>
        <TestComponent />
      </ThemeProvider>
    );

    await user.click(screen.getByText('Toggle'));
    expect(onThemeChange).toHaveBeenCalledWith('dark');
  });
});

Conclusion

React Context in TypeScript has evolved significantly. By using these patterns, you can:

  • Reduce boilerplate with factory functions
  • Improve type safety with proper TypeScript patterns
  • Enable configuration by accepting provider props
  • Leverage typeof for automatic type extraction
  • Compose contexts cleanly with minimal nesting complexity

The key insight is using typeof with your provider components to extract prop types automatically. This ensures type consistency across your application and makes refactoring safer.

Start with the simple pattern for small contexts, but don’t hesitate to use the advanced patterns for complex, configurable contexts that need to be shared across your application.

Additional Resources


R

Rabra Hierpa

Software Engineer, GIS Developer, and FOSS enthusiast sharing insights on web development, GIS technologies, and open-source tools.