Skip to content

Commit 2f684fe

Browse files
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 <[email protected]>
1 parent 3feb34a commit 2f684fe

6 files changed

Lines changed: 35 additions & 24 deletions

File tree

‎.changeset/context-docs-wording.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'svelte': patch
3+
---
4+
5+
docs: clarify that context lookup includes the current component and all ancestors

‎documentation/docs/98-reference/.generated/shared-errors.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -75,10 +75,10 @@ Certain lifecycle methods can only be used during component initialisation. To f
7575
### missing_context
7676

7777
```
78-
Context was not set in a parent component
78+
Context was not set in the current component or any of its ancestors
7979
```
8080

81-
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.
81+
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.
8282

8383
### snippet_without_render_tag
8484

‎packages/svelte/messages/shared-errors/errors.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -62,9 +62,9 @@ Certain lifecycle methods can only be used during component initialisation. To f
6262

6363
## missing_context
6464

65-
> Context was not set in a parent component
65+
> Context was not set in the current component or any of its ancestors
6666
67-
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.
67+
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.
6868

6969
## snippet_without_render_tag
7070

‎packages/svelte/src/internal/client/context.js‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,8 @@ export function set_dev_current_component_function(fn) {
7373
/**
7474
* Returns a `[get, set]` pair of functions for working with context in a type-safe way.
7575
*
76-
* `get` will throw an error if no parent component called `set`.
76+
* `get` will throw an error if `set` has not yet been called in the current component or any of
77+
* its ancestors.
7778
*
7879
* @template T
7980
* @returns {[() => T, (context: T) => T]}
@@ -86,7 +87,9 @@ export function createContext() {
8687
}
8788

8889
/**
89-
* Retrieves the context that belongs to the closest parent component with the specified `key`.
90+
* Retrieves the context set with the specified `key` in the current component or any of its
91+
* ancestors. If multiple components set the same key, the value from the closest one is returned.
92+
* A `setContext` call in the current component is only visible to `getContext` calls that run after it.
9093
* Must be called during component initialisation.
9194
*
9295
* [`createContext`](https://svelte.dev/docs/svelte/svelte#createContext) is a type-safe alternative.
@@ -103,8 +106,8 @@ export function getContext(key) {
103106

104107
/**
105108
* Associates an arbitrary `context` object with the current component and the specified `key`
106-
* and returns that object. The context is then available to children of the component
107-
* (including slotted content) with `getContext`.
109+
* and returns that object. The context is then available to the component itself and all of its
110+
* descendants (including slotted content) with `getContext`.
108111
*
109112
* Like lifecycle functions, this must be called during component initialisation.
110113
*
@@ -136,8 +139,8 @@ export function setContext(key, context) {
136139
}
137140

138141
/**
139-
* Checks whether a given `key` has been set in the context of a parent component.
140-
* Must be called during component initialisation.
142+
* Checks whether a given `key` has been set in the context of the current component or any of
143+
* its ancestors. Must be called during component initialisation.
141144
*
142145
* @param {any} key
143146
* @returns {boolean}
@@ -148,9 +151,9 @@ export function hasContext(key) {
148151
}
149152

150153
/**
151-
* Retrieves the whole context map that belongs to the closest parent component.
152-
* Must be called during component initialisation. Useful, for example, if you
153-
* programmatically create a component and want to pass the existing context to it.
154+
* Retrieves the whole context map that belongs to the current component, including entries
155+
* inherited from its ancestors. Must be called during component initialisation. Useful, for
156+
* example, if you programmatically create a component and want to pass the existing context to it.
154157
*
155158
* @template {Map<any, any>} [T=Map<any, any>]
156159
* @returns {T}

‎packages/svelte/src/internal/shared/errors.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -86,12 +86,12 @@ export function lifecycle_outside_component(name) {
8686
}
8787

8888
/**
89-
* Context was not set in a parent component
89+
* Context was not set in the current component or any of its ancestors
9090
* @returns {never}
9191
*/
9292
export function missing_context() {
9393
if (DEV) {
94-
const error = new Error(`missing_context\nContext was not set in a parent component\nhttps://svelte.dev/e/missing_context`);
94+
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`);
9595

9696
error.name = 'Svelte error';
9797

‎packages/svelte/types/index.d.ts‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -494,13 +494,16 @@ declare module 'svelte' {
494494
/**
495495
* Returns a `[get, set]` pair of functions for working with context in a type-safe way.
496496
*
497-
* `get` will throw an error if no parent component called `set`.
497+
* `get` will throw an error if `set` has not yet been called in the current component or any of
498+
* its ancestors.
498499
*
499500
* @since 5.40.0
500501
*/
501502
export function createContext<T>(): [() => T, (context: T) => T];
502503
/**
503-
* Retrieves the context that belongs to the closest parent component with the specified `key`.
504+
* Retrieves the context set with the specified `key` in the current component or any of its
505+
* ancestors. If multiple components set the same key, the value from the closest one is returned.
506+
* A `setContext` call in the current component is only visible to `getContext` calls that run after it.
504507
* Must be called during component initialisation.
505508
*
506509
* [`createContext`](https://svelte.dev/docs/svelte/svelte#createContext) is a type-safe alternative.
@@ -509,8 +512,8 @@ declare module 'svelte' {
509512
export function getContext<T>(key: any): T;
510513
/**
511514
* Associates an arbitrary `context` object with the current component and the specified `key`
512-
* and returns that object. The context is then available to children of the component
513-
* (including slotted content) with `getContext`.
515+
* and returns that object. The context is then available to the component itself and all of its
516+
* descendants (including slotted content) with `getContext`.
514517
*
515518
* Like lifecycle functions, this must be called during component initialisation.
516519
*
@@ -519,15 +522,15 @@ declare module 'svelte' {
519522
* */
520523
export function setContext<T>(key: any, context: T): T;
521524
/**
522-
* Checks whether a given `key` has been set in the context of a parent component.
523-
* Must be called during component initialisation.
525+
* Checks whether a given `key` has been set in the context of the current component or any of
526+
* its ancestors. Must be called during component initialisation.
524527
*
525528
* */
526529
export function hasContext(key: any): boolean;
527530
/**
528-
* Retrieves the whole context map that belongs to the closest parent component.
529-
* Must be called during component initialisation. Useful, for example, if you
530-
* programmatically create a component and want to pass the existing context to it.
531+
* Retrieves the whole context map that belongs to the current component, including entries
532+
* inherited from its ancestors. Must be called during component initialisation. Useful, for
533+
* example, if you programmatically create a component and want to pass the existing context to it.
531534
*
532535
* */
533536
export function getAllContexts<T extends Map<any, any> = Map<any, any>>(): T;

0 commit comments

Comments
 (0)