Atomico Context

useContext — Consume a Context Value

Reads the current value from the nearest ancestor context provider.

API

const value = useContext(ContextConstructor);

Basic Example

import { c, createContext, useContext, css } from "atomico";

const MyContext = createContext({ name: "Atomico" });

const MyComponent = c(
    () => {
        const { name } = useContext(MyContext);

        return (
            <host shadowDom>
                <strong>{name}</strong>
            </host>
        );
    },
    {
        styles: css`:host { display: grid; }`
    }
);

customElements.define("my-context", MyContext);
customElements.define("my-component", MyComponent);

HTML Usage

<my-context value='{"name": "Custom Name"}'>
    <my-component></my-component>
</my-context>

useProvider — Provide a Context Value

Provides a value for a context to all descendants. This is the lower-level API used internally by createContext.

API

useProvider(ContextConstructor, value);

Custom Provider Pattern

const AppState = createContext({ count: 0, theme: "dark" });

const AppProvider = c(
    () => {
        const [count, setCount] = useState(0);

        useProvider(AppState, {
            count,
            increment: () => setCount((c) => c + 1)
        });

        return (
            <host shadowDom>
                <slot />
            </host>
        );
    }
);

Nested Context and Value Override

Contexts can be nested to override values at different tree levels:

const MyContext = createContext({ name: "Atomico" });

const MyComponent = c(
    () => {
        const { name } = useContext(MyContext);

        return (
            <host shadowDom>
                <strong>{name}</strong>

                <div>
                    <strong>Dynamic Slot</strong>
                    {/* Override context for slotted children */}
                    <MyContext value={{ name: name + "-x2" }}>
                        <slot />
                    </MyContext>
                </div>

                <div>
                    <strong>Static Slot</strong>
                    <MyContext value={{ name: "Static!" }}>
                        <slot name="static" />
                    </MyContext>
                </div>
            </host>
        );
    },
    {
        styles: css`
            :host { display: grid; }
            div {
                padding: 0 1rem;
                border-left: 1px solid red;
            }
        `
    }
);

HTML for Nested Example

<my-component>
    <!-- Receives "Atomico-x2" from dynamic override -->
    <my-component slot="">
        <!-- Receives "Atomico-x2-x2" — double nesting -->
        <my-component></my-component>
    </my-component>

    <!-- Receives "Static!" from named slot override -->
    <my-component slot="static"></my-component>
</my-component>

How It Works Internally

1. Provider listens for ConnectContext events (bubbles + composed)
2. Consumer dispatches ConnectContext with context ID and a connect callback
3. Provider intercepts the event, stops propagation, and calls the connect callback
4. Provider dispatches ChangedValue events when the value updates
5. Consumer listens for ChangedValue on the provider element and re-renders

This event-based mechanism transparently crosses shadow DOM boundaries.

Best Practices

✅ Register contexts as custom elements

customElements.define("my-context", MyContext);

✅ Use constructor instances in JSX (for type safety)

<MyContext value={{ name: "Override" }}>
    <MyConsumer />
</MyContext>

✅ Default values as fallback

If no provider is found, useContext falls back to the default value passed to createContext.

❌ Don't mutate context values

Always provide new object references to trigger updates:

// ❌ Mutation doesn't trigger update
context.name = "New";

// ✅ New object reference triggers update
useProvider(MyContext, { ...context, name: "New" });