Context API

Share data across your component tree without prop drilling

Context provides a way to pass data through the component tree without having to pass props down manually at every level. It’s designed to share data that can be considered “global” for a tree of Preact components.

When to Use Context

Context is ideal for sharing data that is needed by many components at different nesting levels:

• Current authenticated user
• Theme preferences (dark/light mode)
• Language/locale settings
• UI state (modals, notifications)

Don’t use Context just to avoid passing props a few levels down. Context makes component reuse more difficult.

Creating Context

Use createContext to create a new context object. It accepts a default value that’s used when a component doesn’t have a matching Provider above it.

import { createContext } from 'preact';

const ThemeContext = createContext('light');

Implementation Details

The createContext function is implemented in src/create-context.js. It returns a special component that acts as both Provider and Consumer:

// Simplified from src/create-context.js
export function createContext(defaultValue) {
  function Context(props) {
    // Provider implementation
    return props.children;
  }
  
  Context._id = '__cC' + i++;
  Context._defaultValue = defaultValue;
  Context.Consumer = (props, contextValue) => props.children(contextValue);
  Context.Provider = Context;
  
  return Context;
}

Reference: src/create-context.js:6-60

Provider Component

Every Context object comes with a Provider component that allows consuming components to subscribe to context changes.

Consuming Context

There are two ways to consume context in Preact:

useContext Hook (Recommended)

The useContext hook is the recommended way to consume context in function components:

import { createContext } from 'preact';
import { useContext } from 'preact/hooks';

const ThemeContext = createContext('light');

function ThemedButton() {
  const theme = useContext(ThemeContext);
  
  return (
    <button className={`btn-${theme}`}>
      Button
    </button>
  );
}

How useContext Works

The useContext hook is implemented in hooks/src/index.js. It reads the context value from the current component’s context and subscribes to updates:

// Simplified from hooks/src/index.js:367-385
export function useContext(context) {
  const provider = currentComponent.context[context._id];
  const state = getHookState(currentIndex++, 9);
  
  if (!provider) return context._defaultValue;
  
  if (state._value == null) {
    state._value = true;
    provider.sub(currentComponent);  // Subscribe to updates
  }
  
  return provider.props.value;
}

Reference: hooks/src/index.js:367-385

Consumer Component

You can also use the Consumer component with a render prop pattern:

import { createContext } from 'preact';

const ThemeContext = createContext('light');

function ThemedButton() {
  return (
    <ThemeContext.Consumer>
      {theme => (
        <button className={`btn-${theme}`}>
          Button
        </button>
      )}
    </ThemeContext.Consumer>
  );
}

The Consumer pattern is less common now that hooks are available. Use useContext for cleaner code.

Practical Examples

Theme Context

import { createContext } from 'preact';
import { useContext, useState } from 'preact/hooks';

const ThemeContext = createContext('light');

export function ThemeProvider({ children }) {
  const [theme, setTheme] = useState('light');

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

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

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

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

function Header() {
  const { theme, toggleTheme } = useTheme();
  
  return (
    <header className={theme}>
      <button onClick={toggleTheme}>
        Switch to {theme === 'light' ? 'dark' : 'light'} mode
      </button>
    </header>
  );
}

Best Practices

Performance Considerations

Context updates cause all consuming components to re-render. Here are strategies to optimize:

Split Contexts

Split frequently changing values into separate contexts:

// Instead of one context with both
const AppContext = createContext({ theme, user });

// Use separate contexts
const ThemeContext = createContext('light');
const UserContext = createContext(null);

Now components that only need theme won’t re-render when user changes.

Memoize Context Values

Use useMemo to prevent creating new objects on every render:

function Provider({ children }) {
  const [state, setState] = useState(initialState);

  const value = useMemo(() => ({
    state,
    setState
  }), [state]);

  return <Context.Provider value={value}>{children}</Context.Provider>;
}

Component Splitting

Split components so only parts that need context re-render:

// Before: Entire component re-renders on context change
function Profile() {
  const user = useContext(UserContext);
  return (
    <div>
      <ExpensiveComponent />
      <p>{user.name}</p>
    </div>
  );
}

// After: Only UserName re-renders
function Profile() {
  return (
    <div>
      <ExpensiveComponent />
      <UserName />
    </div>
  );
}

function UserName() {
  const user = useContext(UserContext);
  return <p>{user.name}</p>;
}

Next Steps

Hooks

Learn more about hooks including useContext

Refs

Work with DOM references and forward refs