diff --git a/documentation/docs/98-reference/21-svelte-reactivity.md b/documentation/docs/98-reference/21-svelte-reactivity.md
index 6857c1dba80d..8070331f481b 100644
--- a/documentation/docs/98-reference/21-svelte-reactivity.md
+++ b/documentation/docs/98-reference/21-svelte-reactivity.md
@@ -2,24 +2,6 @@
title: svelte/reactivity
---
-Svelte provides reactive versions of various built-ins like `SvelteMap`, `SvelteSet` and `SvelteURL`. These can be imported from `svelte/reactivity` and used just like their native counterparts.
-
-```svelte
-
-
-
-
-
-
-
-
-
-
-
-```
+Svelte provides reactive versions of various built-ins like [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map), [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) and [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) that can be used just like their native counterparts, as well as a handful of additional utilities for handling reactivity.
> MODULE: svelte/reactivity
diff --git a/packages/svelte/src/reactivity/date.js b/packages/svelte/src/reactivity/date.js
index 33da2e176159..721673bc36f3 100644
--- a/packages/svelte/src/reactivity/date.js
+++ b/packages/svelte/src/reactivity/date.js
@@ -5,6 +5,38 @@ import { active_reaction, get, set_active_reaction } from '../internal/client/ru
var inited = false;
+/**
+ * A reactive version of the built-in [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object.
+ * Reading the date (whether with methods like `date.getTime()` or `date.toString()`, or via things like [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat))
+ * in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived)
+ * will cause it to be re-evaluated when the value of the date changes.
+ *
+ * ```svelte
+ *
+ *
+ *
The time is {formatter.format(date)}
+ * ```
+ */
export class SvelteDate extends Date {
#time = source(super.getTime());
diff --git a/packages/svelte/src/reactivity/map.js b/packages/svelte/src/reactivity/map.js
index 3fa2945ef08c..3ae8fe5ad19c 100644
--- a/packages/svelte/src/reactivity/map.js
+++ b/packages/svelte/src/reactivity/map.js
@@ -5,6 +5,47 @@ import { get } from '../internal/client/runtime.js';
import { increment } from './utils.js';
/**
+ * A reactive version of the built-in [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) object.
+ * Reading contents of the map (by iterating, or by reading `map.size` or calling `map.get(...)` or `map.has(...)` as in the [tic-tac-toe example](https://svelte.dev/playground/0b0ff4aa49c9443f9b47fe5203c78293) below) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived)
+ * will cause it to be re-evaluated as necessary when the map is updated.
+ *
+ * Note that values in a reactive map are _not_ made [deeply reactive](https://svelte.dev/docs/svelte/$state#Deep-state).
+ *
+ * ```svelte
+ *
+ *
+ *
+ * {#each Array(9), i}
+ *
+ * {/each}
+ *
+ *
+ * {#if winner}
+ *
{winner} wins!
+ *
+ * {:else}
+ *
{player} is next
+ * {/if}
+ * ```
+ *
* @template K
* @template V
* @extends {Map}
diff --git a/packages/svelte/src/reactivity/set.js b/packages/svelte/src/reactivity/set.js
index be0c2d2cf5d6..4a0b4dfdb398 100644
--- a/packages/svelte/src/reactivity/set.js
+++ b/packages/svelte/src/reactivity/set.js
@@ -10,6 +10,37 @@ var set_like_methods = ['difference', 'intersection', 'symmetricDifference', 'un
var inited = false;
/**
+ * A reactive version of the built-in [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) object.
+ * Reading contents of the set (by iterating, or by reading `set.size` or calling `set.has(...)` as in the [example](https://svelte.dev/playground/53438b51194b4882bcc18cddf9f96f15) below) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived)
+ * will cause it to be re-evaluated as necessary when the set is updated.
+ *
+ * Note that values in a reactive set are _not_ made [deeply reactive](https://svelte.dev/docs/svelte/$state#Deep-state).
+ *
+ * ```svelte
+ *
+ *
+ * {#each ['🙈', '🙉', '🙊'] as monkey}
+ *
+ * {/each}
+ *
+ *
+ *
+ * {#if monkeys.has('🙈')}
see no evil
{/if}
+ * {#if monkeys.has('🙉')}
hear no evil
{/if}
+ * {#if monkeys.has('🙊')}
speak no evil
{/if}
+ * ```
+ *
* @template T
* @extends {Set}
*/
diff --git a/packages/svelte/src/reactivity/url-search-params.js b/packages/svelte/src/reactivity/url-search-params.js
index 13f697199643..c1a8275f150b 100644
--- a/packages/svelte/src/reactivity/url-search-params.js
+++ b/packages/svelte/src/reactivity/url-search-params.js
@@ -5,6 +5,32 @@ import { increment } from './utils.js';
export const REPLACE = Symbol();
+/**
+ * A reactive version of the built-in [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) object.
+ * Reading its contents (by iterating, or by calling `params.get(...)` or `params.getAll(...)` as in the [example](https://svelte.dev/playground/b3926c86c5384bab9f2cf993bc08c1c8) below) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived)
+ * will cause it to be re-evaluated as necessary when the params are updated.
+ *
+ * ```svelte
+ *
+ *
+ *
+ *
+ *
+ *
+ *
?{params.toString()}
+ *
+ * {#each params as [key, value]}
+ *
{key}: {value}
+ * {/each}
+ * ```
+ */
export class SvelteURLSearchParams extends URLSearchParams {
#version = source(0);
#url = get_current_url();
@@ -23,6 +49,7 @@ export class SvelteURLSearchParams extends URLSearchParams {
/**
* @param {URLSearchParams} params
+ * @internal
*/
[REPLACE](params) {
if (this.#updating) return;
diff --git a/packages/svelte/src/reactivity/url.js b/packages/svelte/src/reactivity/url.js
index 5d003be0210a..879006f057dc 100644
--- a/packages/svelte/src/reactivity/url.js
+++ b/packages/svelte/src/reactivity/url.js
@@ -10,6 +10,33 @@ export function get_current_url() {
return current_url;
}
+/**
+ * A reactive version of the built-in [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) object.
+ * Reading properties of the URL (such as `url.href` or `url.pathname`) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived)
+ * will cause it to be re-evaluated as necessary when the URL changes.
+ *
+ * The `searchParams` property is an instance of [SvelteURLSearchParams](https://svelte.dev/docs/svelte/svelte-reactivity#SvelteURLSearchParams).
+ *
+ * [Example](https://svelte.dev/playground/5a694758901b448c83dc40dc31c71f2a):
+ *
+ * ```svelte
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ * ```
+ */
export class SvelteURL extends URL {
#protocol = source(super.protocol);
#username = source(super.username);
diff --git a/packages/svelte/types/index.d.ts b/packages/svelte/types/index.d.ts
index c6000fc4b67f..eec4cc0f8705 100644
--- a/packages/svelte/types/index.d.ts
+++ b/packages/svelte/types/index.d.ts
@@ -1898,11 +1898,77 @@ declare module 'svelte/motion' {
}
declare module 'svelte/reactivity' {
+ /**
+ * A reactive version of the built-in [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object.
+ * Reading the date (whether with methods like `date.getTime()` or `date.toString()`, or via things like [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat))
+ * in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived)
+ * will cause it to be re-evaluated when the value of the date changes.
+ *
+ * ```svelte
+ *
+ *
+ *
The time is {formatter.format(date)}
+ * ```
+ */
export class SvelteDate extends Date {
constructor(...params: any[]);
#private;
}
+ /**
+ * A reactive version of the built-in [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) object.
+ * Reading contents of the set (by iterating, or by reading `set.size` or calling `set.has(...)` as in the [example](https://svelte.dev/playground/53438b51194b4882bcc18cddf9f96f15) below) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived)
+ * will cause it to be re-evaluated as necessary when the set is updated.
+ *
+ * Note that values in a reactive set are _not_ made [deeply reactive](https://svelte.dev/docs/svelte/$state#Deep-state).
+ *
+ * ```svelte
+ *
+ *
+ * {#each ['🙈', '🙉', '🙊'] as monkey}
+ *
+ * {/each}
+ *
+ *
+ *
+ * {#if monkeys.has('🙈')}
see no evil
{/if}
+ * {#if monkeys.has('🙉')}
hear no evil
{/if}
+ * {#if monkeys.has('🙊')}
speak no evil
{/if}
+ * ```
+ *
+ *
+ */
export class SvelteSet extends Set {
constructor(value?: Iterable | null | undefined);
@@ -1910,6 +1976,50 @@ declare module 'svelte/reactivity' {
add(value: T): this;
#private;
}
+ /**
+ * A reactive version of the built-in [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) object.
+ * Reading contents of the map (by iterating, or by reading `map.size` or calling `map.get(...)` or `map.has(...)` as in the [tic-tac-toe example](https://svelte.dev/playground/0b0ff4aa49c9443f9b47fe5203c78293) below) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived)
+ * will cause it to be re-evaluated as necessary when the map is updated.
+ *
+ * Note that values in a reactive map are _not_ made [deeply reactive](https://svelte.dev/docs/svelte/$state#Deep-state).
+ *
+ * ```svelte
+ *
+ *
+ *
+ * {#each Array(9), i}
+ *
+ * {/each}
+ *
+ *
+ * {#if winner}
+ *
{winner} wins!
+ *
+ * {:else}
+ *
{player} is next
+ * {/if}
+ * ```
+ *
+ *
+ */
export class SvelteMap extends Map {
constructor(value?: Iterable | null | undefined);
@@ -1917,11 +2027,64 @@ declare module 'svelte/reactivity' {
set(key: K, value: V): this;
#private;
}
+ /**
+ * A reactive version of the built-in [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) object.
+ * Reading properties of the URL (such as `url.href` or `url.pathname`) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived)
+ * will cause it to be re-evaluated as necessary when the URL changes.
+ *
+ * The `searchParams` property is an instance of [SvelteURLSearchParams](https://svelte.dev/docs/svelte/svelte-reactivity#SvelteURLSearchParams).
+ *
+ * [Example](https://svelte.dev/playground/5a694758901b448c83dc40dc31c71f2a):
+ *
+ * ```svelte
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ * ```
+ */
export class SvelteURL extends URL {
get searchParams(): SvelteURLSearchParams;
#private;
}
const REPLACE: unique symbol;
+ /**
+ * A reactive version of the built-in [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) object.
+ * Reading its contents (by iterating, or by calling `params.get(...)` or `params.getAll(...)` as in the [example](https://svelte.dev/playground/b3926c86c5384bab9f2cf993bc08c1c8) below) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived)
+ * will cause it to be re-evaluated as necessary when the params are updated.
+ *
+ * ```svelte
+ *
+ *
+ *
+ *
+ *
+ *
+ *