Skip to content

Commit 94dc0fa

Browse files
github-actions[bot]svelte-docs-bot[bot]
github-actions[bot]
and
svelte-docs-bot[bot]
authored
Sync svelte docs (#1310)
sync svelte docs Co-authored-by: svelte-docs-bot[bot] <196124396+svelte-docs-bot[bot]@users.noreply.github.com>
1 parent 2161336 commit 94dc0fa

File tree

1 file changed

+155
-19
lines changed

1 file changed

+155
-19
lines changed

‎apps/svelte.dev/content/docs/svelte/98-reference/21-svelte-reactivity.md‎

Lines changed: 155 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -3,25 +3,7 @@ NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-doc
33
title: svelte/reactivity
44
---
55

6-
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.
7-
8-
```svelte
9-
<script>
10-
import { SvelteURL } from 'svelte/reactivity';
11-
12-
const url = new SvelteURL('https://example.com/path');
13-
</script>
14-
15-
<!-- changes to these... -->
16-
<input bind:value={url.protocol} />
17-
<input bind:value={url.hostname} />
18-
<input bind:value={url.pathname} />
19-
20-
<hr />
21-
22-
<!-- will update `href` and vice versa -->
23-
<input bind:value={url.href} />
24-
```
6+
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.
257

268

279

@@ -89,6 +71,37 @@ constructor(query: string, fallback?: boolean | undefined);
8971

9072
## SvelteDate
9173

74+
A reactive version of the built-in [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object.
75+
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))
76+
in an [effect](/docs/svelte/$effect) or [derived](/docs/svelte/$derived)
77+
will cause it to be re-evaluated when the value of the date changes.
78+
79+
```svelte
80+
<script>
81+
import { SvelteDate } from 'svelte/reactivity';
82+
83+
const date = new SvelteDate();
84+
85+
const formatter = new Intl.DateTimeFormat(undefined, {
86+
hour: 'numeric',
87+
minute: 'numeric',
88+
second: 'numeric'
89+
});
90+
91+
$effect(() => {
92+
const interval = setInterval(() => {
93+
date.setTime(Date.now());
94+
}, 1000);
95+
96+
return () => {
97+
clearInterval(interval);
98+
};
99+
});
100+
</script>
101+
102+
<p>The time is {formatter.format(date)}</p>
103+
```
104+
92105
<div class="ts-block">
93106

94107
```dts
@@ -108,6 +121,47 @@ constructor(...params: any[]);
108121

109122
## SvelteMap
110123

124+
A reactive version of the built-in [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) object.
125+
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](/playground/0b0ff4aa49c9443f9b47fe5203c78293) below) in an [effect](/docs/svelte/$effect) or [derived](/docs/svelte/$derived)
126+
will cause it to be re-evaluated as necessary when the map is updated.
127+
128+
Note that values in a reactive map are _not_ made [deeply reactive](/docs/svelte/$state#Deep-state).
129+
130+
```svelte
131+
<script>
132+
import { SvelteMap } from 'svelte/reactivity';
133+
import { result } from './game.js';
134+
135+
let board = new SvelteMap();
136+
let player = $state('x');
137+
let winner = $derived(result(board));
138+
139+
function reset() {
140+
player = 'x';
141+
board.clear();
142+
}
143+
</script>
144+
145+
<div class="board">
146+
{#each Array(9), i}
147+
<button
148+
disabled={board.has(i) || winner}
149+
onclick={() => {
150+
board.set(i, player);
151+
player = player === 'x' ? 'o' : 'x';
152+
}}
153+
>{board.get(i)}</button>
154+
{/each}
155+
</div>
156+
157+
{#if winner}
158+
<p>{winner} wins!</p>
159+
<button onclick={reset}>reset</button>
160+
{:else}
161+
<p>{player} is next</p>
162+
{/if}
163+
```
164+
111165
<div class="ts-block">
112166

113167
```dts
@@ -136,6 +190,37 @@ set(key: K, value: V): this;
136190

137191
## SvelteSet
138192

193+
A reactive version of the built-in [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) object.
194+
Reading contents of the set (by iterating, or by reading `set.size` or calling `set.has(...)` as in the [example](/playground/53438b51194b4882bcc18cddf9f96f15) below) in an [effect](/docs/svelte/$effect) or [derived](/docs/svelte/$derived)
195+
will cause it to be re-evaluated as necessary when the set is updated.
196+
197+
Note that values in a reactive set are _not_ made [deeply reactive](/docs/svelte/$state#Deep-state).
198+
199+
```svelte
200+
<script>
201+
import { SvelteSet } from 'svelte/reactivity';
202+
let monkeys = new SvelteSet();
203+
204+
function toggle(monkey) {
205+
if (monkeys.has(monkey)) {
206+
monkeys.delete(monkey);
207+
} else {
208+
monkeys.add(monkey);
209+
}
210+
}
211+
</script>
212+
213+
{#each ['🙈', '🙉', '🙊'] as monkey}
214+
<button onclick={() => toggle(monkey)}>{monkey}</button>
215+
{/each}
216+
217+
<button onclick={() => monkeys.clear()}>clear</button>
218+
219+
{#if monkeys.has('🙈')}<p>see no evil</p>{/if}
220+
{#if monkeys.has('🙉')}<p>hear no evil</p>{/if}
221+
{#if monkeys.has('🙊')}<p>speak no evil</p>{/if}
222+
```
223+
139224
<div class="ts-block">
140225

141226
```dts
@@ -164,6 +249,32 @@ add(value: T): this;
164249

165250
## SvelteURL
166251

252+
A reactive version of the built-in [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) object.
253+
Reading properties of the URL (such as `url.href` or `url.pathname`) in an [effect](/docs/svelte/$effect) or [derived](/docs/svelte/$derived)
254+
will cause it to be re-evaluated as necessary when the URL changes.
255+
256+
The `searchParams` property is an instance of [SvelteURLSearchParams](/docs/svelte/svelte-reactivity#SvelteURLSearchParams).
257+
258+
[Example](/playground/5a694758901b448c83dc40dc31c71f2a):
259+
260+
```svelte
261+
<script>
262+
import { SvelteURL } from 'svelte/reactivity';
263+
264+
const url = new SvelteURL('https://example.com/path');
265+
</script>
266+
267+
<!-- changes to these... -->
268+
<input bind:value={url.protocol} />
269+
<input bind:value={url.hostname} />
270+
<input bind:value={url.pathname} />
271+
272+
<hr />
273+
274+
<!-- will update `href` and vice versa -->
275+
<input bind:value={url.href} size="65" />
276+
```
277+
167278
<div class="ts-block">
168279

169280
```dts
@@ -183,6 +294,31 @@ get searchParams(): SvelteURLSearchParams;
183294

184295
## SvelteURLSearchParams
185296

297+
A reactive version of the built-in [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) object.
298+
Reading its contents (by iterating, or by calling `params.get(...)` or `params.getAll(...)` as in the [example](/playground/b3926c86c5384bab9f2cf993bc08c1c8) below) in an [effect](/docs/svelte/$effect) or [derived](/docs/svelte/$derived)
299+
will cause it to be re-evaluated as necessary when the params are updated.
300+
301+
```svelte
302+
<script>
303+
import { SvelteURLSearchParams } from 'svelte/reactivity';
304+
305+
const params = new SvelteURLSearchParams('message=hello');
306+
307+
let key = $state('key');
308+
let value = $state('value');
309+
</script>
310+
311+
<input bind:value={key} />
312+
<input bind:value={value} />
313+
<button onclick={() => params.append(key, value)}>append</button>
314+
315+
<p>?{params.toString()}</p>
316+
317+
{#each params as [key, value]}
318+
<p>{key}: {value}</p>
319+
{/each}
320+
```
321+
186322
<div class="ts-block">
187323

188324
```dts

0 commit comments

Comments
 (0)