provide and inject Across Layers

A dark-mode preference lives in App.vue. The component that renders the toggle is there; the components that need the value — a modal three levels down, a table cell five levels down — are nowhere near it. Prop drilling would thread :theme through Layout, Dashboard, PanelList, Panel, and Cell: five components declaring a prop that only the first and last understand, and every intermediate template gaining a line it has no opinion about.

Vue's targeted solution is dependency injection:

<!-- App.vue: the provider -->
<script setup>
import { ref, provide } from 'vue'
const theme = ref('dark')
provide('app-theme', theme)      // any descendant may now inject 'app-theme'

function toggle() { theme.value = theme.value === 'dark' ? 'light' : 'dark' }
</script>

<!-- deep descendant, e.g. Cell.vue: the consumer -->
<script setup>
import { inject } from 'vue'
const theme = inject('app-theme')      // the SAME ref App.vue provided
</script>
<template>
  <td :class="'cell-' + theme">{{ value }}</td>
</template>

provide(key, value) registers a value on the current component's injection context; inject(key) searches the current component's parent chain at runtime and returns the nearest provided value — skipping every intermediate level. Layout, Dashboard, PanelList, and Panel never see the string app-theme; the contract is strictly between App and Cell. When a theme change re-renders the deep cell, it is because the cell injected the ref itself and its render tracks it — the same reactivity rule as everywhere else: provide the container, not the value.

Two safety valves complete the mechanism:

A default for missing providers. inject(key, defaultValue) returns the fallback when no ancestor provided the key:

const theme = inject('app-theme', 'light')   // usable even outside the expected tree

Without a default, a missing provider logs a dev warning ([Vue warn] injection 'app-theme' not found.) and yields undefined — which is why production-bound library components should always inject with defaults: they will be mounted in trees you don't control.

App-level provides. app.provide('app-theme', themeRef) before mount() makes the value injectable from any component, including the root — this is how Vue's own plugins (vue-router's useRouter, Pinia's useStore) work, and it is the right home for singletons that genuinely belong to the application rather than one subtree.

The mechanism is small; the design discipline is the real content. Provide/inject bypasses the prop chain's visibility: in the props model, Panel.vue's template shows you every input the panel receives; with injection, reading Panel.vue tells you nothing about what data arrives from above — the value's origin is a search through every provide( call in the app. That trade is worth making for genuinely cross-cutting values — theme, current user, locale strings, toast/modal APIs, feature flags — where every intermediate declaration would be noise. It is a bad trade for ordinary feature data that one parent and one child share, which is what props are for. The next two chapters cover the two details that separate a correct injection contract from a fragile one: keyed, typed constants, and the reactivity rules for what you put on the providing side.

The injection key is a string in every example so far, and that is where the drift begins. 'app-theme' typed as 'app-tHEME' in one component injects nothing — a dev warning at runtime, undefined in the value, and no build error anywhere. Two components providing 'user' with different shapes collide silently, with the nearest provider winning. The fix is a shared, typed key module:

// keys.ts — the single source of the contract
import type { InjectionKey } from 'vue'

export interface ThemeContext {
  theme: 'light' | 'dark'
  setTheme: (t: 'light' | 'dark') => void
}

export const themeKey: InjectionKey<ThemeContext> = Symbol('app-theme')

// provider
import { themeKey } from './keys'
provide(themeKey, { theme: themeRef, setTheme })

// consumer — type error if the provider shape changes and this call doesn't
const ctx = inject(themeKey)
if (!ctx) throw new Error('themeKey must be provided above')   // or inject(themeKey, fallback)

InjectionKey<T> is a Symbol subtype carrying the value type, and it delivers three guarantees a string cannot. No typos: the symbol is one JavaScript value; a misspelling is a compile error, not a runtime miss. No collisions: two libraries can each define Symbol('user') and coexist — symbols are unique by identity, so even identically described keys don't meet. Typed both directions: provide(themeKey, wrongShape) fails to compile, and inject(themeKey) comes back typed, so consumers get autocomplete on ctx.setTheme and the compiler catches contract drift on both ends.

The key module itself is the architectural pattern: one file per bounded context (or one per app) exporting the key and its interface together, imported by providers and consumers alike. The interface is the reviewable artifact — a diff to keys.ts is a diff to the app's injection contract, visible in one place instead of scattered across provide and inject call sites.

Two naming details for string keys you can't avoid (a plugin consuming an untyped external key, a legacy codebase): prefix them with your app or library name ('acme:theme') so a third-party provide can never shadow yours by accident, and treat string keys as untyped boundaries — wrap them in your own typed helper immediately:

const theme = inject('acme-theme', null) as ThemeContext | null

Default values deserve a second look in injection specifically. inject(key, fallback) uses the fallback when no provider exists at all — it does not merge, and it never overrides a provider that passed undefined deliberately. For object-shaped defaults, pass a fresh value per consumer (a factory invoked at inject time is the safe habit, mirroring the prop-default rule from Declaring and Validating Props). And the required pattern — no default, must-have data — is the explicit guard, because Vue will not throw for you:

const user = inject(userKey)
if (!user) throw new Error('userKey missing — check app-level provide')

A loud, immediate failure at the missing edge beats a downstream cannot read property 'name' of undefined in a component that merely consumed the value. With the contract typed and guarded, the last question about what crosses it is whether the value itself stays reactive in the consumer's hands.

Injection follows the reactivity system's one rule with no exceptions: inject returns exactly what was provided — the same reference. That fact decides whether a consumer is live or frozen, and it produces three distinct outcomes:

// provider
const count = ref(0)
provide(countKey, count)          // ✅ live: consumers hold the ref
provide(totalKey, count.value)    // ❌ snapshot: 0, forever
const state = reactive({ n: 0 })
provide(stateKey, state)          // ✅ live: same proxy, mutations tracked everywhere

A consumer holding the injected ref reads count.value — the render tracks it, a provider-side mutation re-renders every consuming component, and the loop closes exactly like a prop update, just without the intermediate declarations. A consumer holding an injected number holds a copy: the provider increments its ref, the injected value stays at the old number, and no warning ever fires. The dev-time version of this trap is diagnosable in one line — 'does the consumer read .value?' — but the production version is a UI that updates in the header and not in the deep modal, which is the inject analogue of the detach bugs from the reactivity topics.

Providing a computed gets you the best of both: derived, cached, and read-only in every consumer at once:

// provider: one derivation, every consumer sees it live
provide(cartTotalKey, computed(() => cart.value.items.reduce((s, i) => s + i.price, 0)))

And when sharing a writable injected value, decide deliberately who may write. Consumers of an injected ref can assign count.value = 5 — same ref, same power as the provider. If the contract is read-only, wrap it at the boundary:

import { readonly } from 'vue'
provide(configKey, readonly(configRef))   // consumers read; writes warn in dev

readonly over the provided ref gives every consumer a read-only view while the provider keeps the writable original — one-way data flow extended across the injection boundary instead of trusted to convention.

The final discipline is knowing when not to inject. Three sharper tools often fit better:

Injection's cost is traceability: you cannot read a component and see its inputs, so every key you add should earn it by being genuinely cross-cutting, and every key should be a typed constant with a reactivity-preserving value (ref, reactive, or computed — never a snapshot). Keep the injection surface small — a handful of app-wide keys a new engineer can enumerate from keys.ts — and provide/inject does exactly what the prop-drilling diagrams can't: data that crosses the tree without dragging every level through the paperwork. The last composition tool of this phase hands control the other way — the child supplying data to the parent's markup, in scoped slots.