provide & consume
Ancestors broadcast a value, descendants subscribe to it. The context protocol replaces chains of attributes that exist only to reach a nested component.
During SSR, providers are resolved into context frames and consumers read from the nearest ancestor. In the browser the same declarations use the context-request event, with live updates when a provider's value changes.
Signature
export const provide:
| Map<ContextKey, ContextValue>
| Record<string | symbol, ContextValue>
export const consume:
| ContextKey[]
| Record<string, ContextKey | { context: ContextKey, default?: any }>
type ContextKey = string | symbol
type ContextValue = any | ((context: CoraliteContextProviderContext) => any)
interface CoraliteContextProviderContext {
state: Readonly<Record<string, any>>
route: CoraliteRoute
root: HTMLElement | null
refs: (name: string) => HTMLElement | null
slots: CoraliteSlotsHelper
isServer: boolean
signal: AbortSignal
}
createContext(key?) returns the key unchanged, or a fresh Symbol when called without an argument. Use a namespaced string such as 'acme:theme' when the key must be shared between modules; a symbol only works when both sides import the same module instance.
Provider
provide is an object or a Map. Values can be constants or functions. A function is evaluated against the provider's context and re-evaluated when the state keys it read change, so the consumer receives the new value without any extra wiring.
export const attributes = {
theme: { type: String, default: 'dark' }
}
export const provide = {
'acme:theme': ({ state }) => state.theme
}
Prefer a function when the value comes from state. A constant is captured once and never updates, which is fine for configuration and a bug for anything interactive.
Consumer
consume accepts an array of keys or an object that maps keys to local state properties. The array shorthand stores the value under the context key itself, which is why the docs examples read state[ThemeContext] for symbol keys.
The object form is easier to type and supports defaults:
export const consume = {
theme: { context: 'acme:theme', default: 'light' }
}
export const getters = {
label: ({ state }) => `Switch to ${state.theme === 'dark' ? 'light' : 'dark'} mode`
}
| Form | State key | Default |
|---|---|---|
['acme:theme'] | 'acme:theme' | None |
{ theme: 'acme:theme' } | theme | None |
{ theme: { context: 'acme:theme', default: 'light' } } | theme | 'light' |
Defaults are applied when no ancestor provides the key. They are not a fallback for an undefined value from a provider that exists: a provider that returns undefined has still answered the request.
Resolution
Resolution walks ancestors from the consumer outward and stops at the nearest provider that declares the key. Nesting a provider inside another provider intentionally overrides it for that subtree, which is the point of the protocol.
Consumed values are hydrated into state during SSR, so the first render already sees the provided value. There is no client-only flash and no need to guard against a missing context in the template.
Reactivity
When the provider is a function, Coralite tracks the state it reads. A change notifies every subscribed consumer with the new value, and the consumer's getters and template update through normal state reactivity. The consumer does not need a client() block for this.
The subscription is removed when the consumer disconnects. Long-lived providers do not keep detached consumers alive.
When to use it
- Theme, locale and direction. Values every descendant needs and no intermediate component owns.
- Shared form state. A fieldset that validates its children without threading a controller through each one.
- Composition slots. A layout that lets a child know which region it is in.
Do not use context as a global store. It follows the DOM tree, and two sibling subtrees does not mean one value. For application-wide data, use the configured store instead.
Diagnostics
CORALITE-E106reports a provider that is not an object orMap, or a consumer with an unsupported shape.CORALITE-E104reports a consumed property that collides with a framework-reserved context key.
Related
- Component overview for the export contract.
- attributes for values that travel down one level.
- getters for reading consumed state.