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:
- Boilerplate: Every context requires the same setup pattern
- Separate exports: Provider and hook are separate, easy to forget one
- Runtime error: Type safety fails if you forget the provider
- 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
typeoffor 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.
Comments
Sign in with GitHub to comment or react. Threads live in GitHub Discussions, so you can also reply from GitHub.