Key takeaway
- React Context API explained: createContext, useContext and use() in React 19, when to pick props or composition instead, and avoiding extra re-renders.
The React Context API lets a parent component share a value with every component below it, however deep, without passing it through props at each level. You create a context with createContext, provide a value from an ancestor, and read it with useContext (or use in React 19).
Use it for values many components need, such as a theme, the signed-in user or the locale. For most other cases, plain props or component composition are simpler. This guide follows the current React documentation, and links to our guides on React project structure and React performance.
What is the React Context API?
Props are the direct way to pass data down a component tree. When the data must pass through many components that do not use it, this becomes verbose. The React docs call this "prop drilling" and describe context as a way for a parent to make information available to any component below it, "no matter how deep", without passing it explicitly through props.
A context object does not hold the data itself. As the createContext reference puts it, it represents which context other components read or provide. Typical uses named in the docs are theming, the current account, routing and, combined with a reducer, state shared by distant components.
How do you create, provide and read a context?
There are three steps, as the React learning guide sets out: create the context, use it in the component that needs the data, and provide it from an ancestor.
import { createContext, useContext } from 'react';
export const ThemeContext = createContext('light'); // 1. create
function Button() {
const theme = useContext(ThemeContext); // 2. use
return <button className={theme}>Save</button>;
}
export default function App() {
return (
<ThemeContext value="dark"> {/* 3. provide (React 19) */}
<Button />
</ThemeContext>
);
}
The argument to createContext is the default value. React uses it only when there is no matching provider above the reading component. The docs call it a "last resort" fallback that is static and never changes. If you have no meaningful default, they suggest null. To change a value over time, keep it in state and pass that state to the provider.
What changed in React 19 for context providers?
Since React 19, you can render <SomeContext> directly as the provider. The React team announced this in the React 19 release post (5 December 2024). In older versions you write <SomeContext.Provider>. The reference page describes .Provider as the legacy way before React 19, and the release post says <Context.Provider> will be deprecated in future versions. The react.dev versions page lists React 19.3 (9 September 2026) as the latest release at the time of writing; confirm the current version on the official page.
How do useContext, use() and Context.Consumer differ?
| API | What it does | Where you can call it | Status per react.dev |
|---|---|---|---|
useContext(Context) | Returns the value from the closest matching provider above the component | Top level of a component | Current, recommended for reading context |
use(Context) | Reads the same value, and also reads promises | Inside if and loops as well as at the top level | Current (React 19 onwards); reading context with use is not supported in Server Components |
<Context.Consumer> | Passes the value to a function child | In JSX | Legacy, "not recommended"; new code should use useContext |
Both useContext and use look for the closest provider above the calling component. A provider rendered by the same component does not affect its own useContext call. Details are on the useContext and use reference pages.
How do you choose between props, composition and context?
The React docs advise starting with props, because it makes clear which components use which data. Next, try extracting components and passing JSX as children, which reduces the layers between the data and the component that needs it. Only if neither works well should you consider context. In the docs' words, needing to pass props several levels deep does not mean the data belongs in context.
| Situation | Better fit | Why |
|---|---|---|
| Data passes through one or two levels | Props | Explicit and easy to trace |
| A layout wraps content that needs the data | Composition with children | Fewer layers between source and consumer |
| Theme, current user or locale needed across the tree | Context | Many components at different depths read the same value |
| Shared state that distant components update | Context with a reducer | Pattern described in the docs under "Scaling Up with Reducer and Context" |
What causes extra re-renders with context?
When the value passed to a provider changes, React re-renders every component that reads that context. React compares old and new values with Object.is. Wrapping a component in memo does not stop it from receiving a fresh context value.
Passing a new object or function on each render of the provider changes the value every time. The docs show wrapping the object in useMemo and functions in useCallback so consumers re-render only when something they read has changed. They describe this as a performance optimisation that is usually unnecessary in smaller apps. For deeper profiling, see our guide to profiling a React application.
Should you split one big context into several?
Separate contexts for separate concerns, such as theme and user, keep unrelated updates apart. The docs also note that different React contexts do not override each other, so you can nest providers for each concern and read each with its own useContext call.
What are common context mistakes?
- Missing or misnamed value prop: a provider without
value, or with a different prop name, behaves likevalue={undefined}. - Expecting the default to apply: the default is used only when there is no provider above at all. An explicit
undefinedvalue from a provider is passed to consumers as is. - Provider and consumer in the same component: the provider must sit above the component that reads it.
- Duplicate module copies: provider and consumer must use exactly the same context object, compared with
===, so duplicated bundles or symlinks can break it.
How does this apply to enterprise front ends?
For engineering leads, the useful rule is to keep context for stable, cross-cutting values and to treat anything that changes often, or needs audit, as application state with a clear owner. Our guides on learning React and testing React with Jest cover the surrounding practices. Note that React context is a UI mechanism and is unrelated to the governed decision context discussed below.
Where front ends sit on top of AI agents, ElixirData Context OS keeps governed context, versioned policy and decision traces in one decision layer above AI agents, and ElixirClaw is an agentic OS platform to build, orchestrate and govern AI agents and automation workflows while keeping humans in control.
To map one decision your agents should make, and the context and policy it depends on, book a Context Workshop. See what happens in the workshop.
FAQ
When should I use the React Context API?
When many components at different depths need the same value, such as a theme, the current user or a locale. React recommends trying props and component composition first.
What is the difference between useContext and use()?
Both read the value from the closest provider above the component. use() can also be called inside conditions and loops, and it can read promises. Reading context with use is not supported in Server Components.
Is Context.Provider deprecated?
The React 19 release post says Context.Provider will be deprecated in future versions. From React 19 you can render the context itself as the provider. Confirm the current status on react.dev.
Why do all consumers re-render when the value changes?
React re-renders every component that reads a context when the provider value changes, compared with Object.is. Memoising the value with useMemo and useCallback avoids changes that are not real.
Is Context a replacement for a state management library?
The docs show context combined with a reducer for sharing state between distant components. Whether that is enough depends on how often the state changes and how many components read it.
Conclusion
The Context API is the React-supported way to share cross-cutting values without prop drilling. Create the context, provide it from an ancestor, read it with useContext or use, and keep provider values stable. If props or composition solve the problem, prefer them.
Explore the XenonStack platform family: ElixirData · ElixirClaw · ElixirHub · NexaStack · MetaSecure · Neural AI · AgentGRC · AgentSRE · AgentAnalyst · AgentInstruct · AgentRAI · AgentScrum · AgentSearch · AgentForce · AI Aviator · SAIF Aviator · CohortIQ · XenonStack AI · XenonStack UAE