From 2f684fefd79f6c9ac7975cc18410ba95319a34d6 Mon Sep 17 00:00:00 2001 From: Nic Polumeyv Date: Thu, 20 Aug 2026 09:45:42 -0400 Subject: [PATCH] docs: clarify that context lookup includes the current component and all ancestors (#18581) Fixes #7916. Context lookup starts at the current component, not the closest parent. `setContext` followed by `getContext` with the same key in the same component returns the value. --------- Co-authored-by: Simon H <5968653+dummdidumm@users.noreply.github.com> --- .changeset/context-docs-wording.md | 5 +++++ .../98-reference/.generated/shared-errors.md | 4 ++-- .../svelte/messages/shared-errors/errors.md | 4 ++-- .../svelte/src/internal/client/context.js | 21 +++++++++++-------- packages/svelte/src/internal/shared/errors.js | 4 ++-- packages/svelte/types/index.d.ts | 21 +++++++++++-------- 6 files changed, 35 insertions(+), 24 deletions(-) create mode 100644 .changeset/context-docs-wording.md diff --git a/.changeset/context-docs-wording.md b/.changeset/context-docs-wording.md new file mode 100644 index 0000000000..6ec9d47ed9 --- /dev/null +++ b/.changeset/context-docs-wording.md @@ -0,0 +1,5 @@ +--- +'svelte': patch +--- + +docs: clarify that context lookup includes the current component and all ancestors diff --git a/documentation/docs/98-reference/.generated/shared-errors.md b/documentation/docs/98-reference/.generated/shared-errors.md index 739bd58b35..d7596fc068 100644 --- a/documentation/docs/98-reference/.generated/shared-errors.md +++ b/documentation/docs/98-reference/.generated/shared-errors.md @@ -75,10 +75,10 @@ Certain lifecycle methods can only be used during component initialisation. To f ### missing_context ``` -Context was not set in a parent component +Context was not set in the current component or any of its ancestors ``` -The [`createContext()`](svelte#createContext) utility returns a `[get, set]` pair of functions. `get` will throw an error if `set` was not used to set the context in a parent component. +The [`createContext()`](svelte#createContext) utility returns a `[get, set]` pair of functions. `get` will throw an error if `set` was not used to set the context in the current component or any of its ancestors. ### snippet_without_render_tag diff --git a/packages/svelte/messages/shared-errors/errors.md b/packages/svelte/messages/shared-errors/errors.md index 3ff474768e..43dca57ac8 100644 --- a/packages/svelte/messages/shared-errors/errors.md +++ b/packages/svelte/messages/shared-errors/errors.md @@ -62,9 +62,9 @@ Certain lifecycle methods can only be used during component initialisation. To f ## missing_context -> Context was not set in a parent component +> Context was not set in the current component or any of its ancestors -The [`createContext()`](svelte#createContext) utility returns a `[get, set]` pair of functions. `get` will throw an error if `set` was not used to set the context in a parent component. +The [`createContext()`](svelte#createContext) utility returns a `[get, set]` pair of functions. `get` will throw an error if `set` was not used to set the context in the current component or any of its ancestors. ## snippet_without_render_tag diff --git a/packages/svelte/src/internal/client/context.js b/packages/svelte/src/internal/client/context.js index f4890d0409..0a7b2cdf31 100644 --- a/packages/svelte/src/internal/client/context.js +++ b/packages/svelte/src/internal/client/context.js @@ -73,7 +73,8 @@ export function set_dev_current_component_function(fn) { /** * Returns a `[get, set]` pair of functions for working with context in a type-safe way. * - * `get` will throw an error if no parent component called `set`. + * `get` will throw an error if `set` has not yet been called in the current component or any of + * its ancestors. * * @template T * @returns {[() => T, (context: T) => T]} @@ -86,7 +87,9 @@ export function createContext() { } /** - * Retrieves the context that belongs to the closest parent component with the specified `key`. + * Retrieves the context set with the specified `key` in the current component or any of its + * ancestors. If multiple components set the same key, the value from the closest one is returned. + * A `setContext` call in the current component is only visible to `getContext` calls that run after it. * Must be called during component initialisation. * * [`createContext`](https://svelte.dev/docs/svelte/svelte#createContext) is a type-safe alternative. @@ -103,8 +106,8 @@ export function getContext(key) { /** * Associates an arbitrary `context` object with the current component and the specified `key` - * and returns that object. The context is then available to children of the component - * (including slotted content) with `getContext`. + * and returns that object. The context is then available to the component itself and all of its + * descendants (including slotted content) with `getContext`. * * Like lifecycle functions, this must be called during component initialisation. * @@ -136,8 +139,8 @@ export function setContext(key, context) { } /** - * Checks whether a given `key` has been set in the context of a parent component. - * Must be called during component initialisation. + * Checks whether a given `key` has been set in the context of the current component or any of + * its ancestors. Must be called during component initialisation. * * @param {any} key * @returns {boolean} @@ -148,9 +151,9 @@ export function hasContext(key) { } /** - * Retrieves the whole context map that belongs to the closest parent component. - * Must be called during component initialisation. Useful, for example, if you - * programmatically create a component and want to pass the existing context to it. + * Retrieves the whole context map that belongs to the current component, including entries + * inherited from its ancestors. Must be called during component initialisation. Useful, for + * example, if you programmatically create a component and want to pass the existing context to it. * * @template {Map} [T=Map] * @returns {T} diff --git a/packages/svelte/src/internal/shared/errors.js b/packages/svelte/src/internal/shared/errors.js index a4ad8cecff..9e41788dc1 100644 --- a/packages/svelte/src/internal/shared/errors.js +++ b/packages/svelte/src/internal/shared/errors.js @@ -86,12 +86,12 @@ export function lifecycle_outside_component(name) { } /** - * Context was not set in a parent component + * Context was not set in the current component or any of its ancestors * @returns {never} */ export function missing_context() { if (DEV) { - const error = new Error(`missing_context\nContext was not set in a parent component\nhttps://svelte.dev/e/missing_context`); + const error = new Error(`missing_context\nContext was not set in the current component or any of its ancestors\nhttps://svelte.dev/e/missing_context`); error.name = 'Svelte error'; diff --git a/packages/svelte/types/index.d.ts b/packages/svelte/types/index.d.ts index aab3f4c0b4..b752ef5e07 100644 --- a/packages/svelte/types/index.d.ts +++ b/packages/svelte/types/index.d.ts @@ -494,13 +494,16 @@ declare module 'svelte' { /** * Returns a `[get, set]` pair of functions for working with context in a type-safe way. * - * `get` will throw an error if no parent component called `set`. + * `get` will throw an error if `set` has not yet been called in the current component or any of + * its ancestors. * * @since 5.40.0 */ export function createContext(): [() => T, (context: T) => T]; /** - * Retrieves the context that belongs to the closest parent component with the specified `key`. + * Retrieves the context set with the specified `key` in the current component or any of its + * ancestors. If multiple components set the same key, the value from the closest one is returned. + * A `setContext` call in the current component is only visible to `getContext` calls that run after it. * Must be called during component initialisation. * * [`createContext`](https://svelte.dev/docs/svelte/svelte#createContext) is a type-safe alternative. @@ -509,8 +512,8 @@ declare module 'svelte' { export function getContext(key: any): T; /** * Associates an arbitrary `context` object with the current component and the specified `key` - * and returns that object. The context is then available to children of the component - * (including slotted content) with `getContext`. + * and returns that object. The context is then available to the component itself and all of its + * descendants (including slotted content) with `getContext`. * * Like lifecycle functions, this must be called during component initialisation. * @@ -519,15 +522,15 @@ declare module 'svelte' { * */ export function setContext(key: any, context: T): T; /** - * Checks whether a given `key` has been set in the context of a parent component. - * Must be called during component initialisation. + * Checks whether a given `key` has been set in the context of the current component or any of + * its ancestors. Must be called during component initialisation. * * */ export function hasContext(key: any): boolean; /** - * Retrieves the whole context map that belongs to the closest parent component. - * Must be called during component initialisation. Useful, for example, if you - * programmatically create a component and want to pass the existing context to it. + * Retrieves the whole context map that belongs to the current component, including entries + * inherited from its ancestors. Must be called during component initialisation. Useful, for + * example, if you programmatically create a component and want to pass the existing context to it. * * */ export function getAllContexts = Map>(): T;