SvelteReference

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.

<script>
	import { SvelteURL } from 'svelte/reactivity';

	const url = new SvelteURL('https://example.com/path');
</script>

<!-- changes to these... -->
<input bind:value={url.protocol} />
<input bind:value={url.hostname} />
<input bind:value={url.pathname} />

<hr />

<!-- will update `href` and vice versa -->
<input bind:value={url.href} />

The utilities provided in svelte/reactivity are automatically reactive with respect to their properties and methods, as seen in the previous example. As such, they don’t need to be wrapped in $state. However, if a variable is reassigned, it needs to be wrapped in a $state in order for this reassignement to be reactive.

<script>
	import { SvelteURL } from 'svelte/reactivity';

	let url = $state(new SvelteURL('https://example.com/path'));
</script>

<!-- these are reactive... -->
Protocol: {url?.protocol ?? "ftp:"}
<br>
Hostname: {url?.hostname ?? "svelte.dev"}
<br>
Path: {url?.pathname ?? ""}

<hr />

<!-- ...even when reassigning -->
<button
	onclick={() => {
		url = undefined;
	}}
>
	Erase
</button>

In a similar manner, the values stored inside e.g. SvelteMap are not automatically reactive, so if more complex values such as objects are used, they need to be wrapped in a $state in order to make their properties reactive as well. Alternatively, the whole object can be rewritten on update, which may actually lead to better performance than deep reactive $state.

<script>
	import { SvelteMap } from 'svelte/reactivity';

	const people = new SvelteMap();

	const alice = {name: "Alice", age: 18};
	people.set("alice", alice);

	const bob = $state({name: "Bob", age: 21});
	people.set("bob", bob);
</script>

{#each people.entries() as [id, person] (id)}
	Name: {person.name}
	<br>
	Age: {person.age}
	<br>
	<br>
{/each}

<hr />

<!-- This will NOT propagate reactively -->
<button
	onclick={() => {
		people.get("alice").age++;
	}}
>
	Alice's birthday
</button>

<!-- This WILL propagate reactively -->
<button
	onclick={() => {
		people.get("bob").age++;
	}}
>
	Bob's birthday
</button>

<!-- This WILL propagate reactively -->
<button
	onclick={() => {
		people.set("carol", {name: "Carol", age: 0});
	}}
>
	Carol was born
</button>

{#if people.has("carol")}
	<!-- This WILL propagate reactively -->
	<button
		onclick={() => {
			const oldValue = people.get("carol");
			people.set("carol", {...oldValue, age: oldValue.age + 1});
		}}
	>
		Carol's birthday
	</button>
{/if}

import {
	class MediaQueryCreates a media query and provides a current property that reflects whether or not it matches.
Use it carefully — during server-side rendering, there is no way to know what the correct value should be, potentially causing content to change upon hydration.
If you can use the media query in CSS to achieve the same effect, do that.
&#x3C;script>
	import { MediaQuery } from 'svelte/reactivity';

	const large = new MediaQuery('min-width: 800px');
&#x3C;/script>

&#x3C;h1>{large.current ? 'large screen' : 'small screen'}&#x3C;/h1>
@extendsReactiveValue<boolean> *
@since5.7.0MediaQuery,
	class SvelteDateSvelteDate,
	class SvelteMap<K, V>SvelteMap,
	class SvelteSet<T>SvelteSet,
	class SvelteURLSvelteURL,
	class SvelteURLSearchParamsSvelteURLSearchParams,
	function createSubscriber(start: (update: () => void) => (() => void) | void): () => voidReturns a subscribe function that, if called in an effect (including expressions in the template),
calls its start callback with an update function. Whenever update is called, the effect re-runs.
If start returns a function, it will be called when the effect is destroyed.
If subscribe is called in multiple effects, start will only be called once as long as the effects
are active, and the returned teardown function will only be called when all effects are destroyed.
It’s best understood with an example. Here’s an implementation of MediaQuery:
import { createSubscriber } from 'svelte/reactivity';
import { on } from 'svelte/events';

export class MediaQuery {
	#query;
	#subscribe;

	constructor(query) {
		this.#query = window.matchMedia(`(${query})`);

		this.#subscribe = createSubscriber((update) => {
			// when the `change` event occurs, re-run any effects that read `this.current`
			const off = on(this.#query, 'change', update);

			// stop listening when all the effects are destroyed
			return () => off();
		});
	}

	get current() {
		this.#subscribe();

		// Return the current state of the query, whether or not we're in an effect
		return this.#query.matches;
	}
}
@since5.7.0createSubscriber
} from 'svelte/reactivity';

MediaQuery

Available since 5.7.0

Creates a media query and provides a current property that reflects whether or not it matches.

Use it carefully — during server-side rendering, there is no way to know what the correct value should be, potentially causing content to change upon hydration. If you can use the media query in CSS to achieve the same effect, do that.

<script>
	import { MediaQuery } from 'svelte/reactivity';

	const large = new MediaQuery('min-width: 800px');
</script>

<h1>{large.current ? 'large screen' : 'small screen'}</h1>

class MediaQuery extends ReactiveValue<boolean> {…}

constructor(query: string, fallback?: boolean | undefined);

query A media query string
fallback Fallback value for the server

SvelteDate

class SvelteDate extends Date {…}

constructor(...params: any[]);

#private;

SvelteMap

class SvelteMap<K, V> extends Map<K, V> {…}

constructor(value?: Iterable<readonly [K, V]> | null | undefined);

set(key: K, value: V): this;

#private;

SvelteSet

class SvelteSet<T> extends Set<T> {…}

constructor(value?: Iterable<T> | null | undefined);

add(value: T): this;

#private;

SvelteURL

class SvelteURL extends URL {…}

get searchParams(): SvelteURLSearchParams;

#private;

SvelteURLSearchParams

class SvelteURLSearchParams extends URLSearchParams {…}

[REPLACE](params: URLSearchParams): void;

#private;

createSubscriber

Available since 5.7.0

Returns a subscribe function that, if called in an effect (including expressions in the template), calls its start callback with an update function. Whenever update is called, the effect re-runs.

If start returns a function, it will be called when the effect is destroyed.

If subscribe is called in multiple effects, start will only be called once as long as the effects are active, and the returned teardown function will only be called when all effects are destroyed.

It’s best understood with an example. Here’s an implementation of MediaQuery:

import { function createSubscriber(start: (update: () => void) => (() => void) | void): () => voidReturns a subscribe function that, if called in an effect (including expressions in the template),
calls its start callback with an update function. Whenever update is called, the effect re-runs.
If start returns a function, it will be called when the effect is destroyed.
If subscribe is called in multiple effects, start will only be called once as long as the effects
are active, and the returned teardown function will only be called when all effects are destroyed.
It’s best understood with an example. Here’s an implementation of MediaQuery:
import { createSubscriber } from 'svelte/reactivity';
import { on } from 'svelte/events';

export class MediaQuery {
	#query;
	#subscribe;

	constructor(query) {
		this.#query = window.matchMedia(`(${query})`);

		this.#subscribe = createSubscriber((update) => {
			// when the `change` event occurs, re-run any effects that read `this.current`
			const off = on(this.#query, 'change', update);

			// stop listening when all the effects are destroyed
			return () => off();
		});
	}

	get current() {
		this.#subscribe();

		// Return the current state of the query, whether or not we're in an effect
		return this.#query.matches;
	}
}
@since5.7.0createSubscriber } from 'svelte/reactivity';
import { function on<Type extends keyof WindowEventMap>(window: Window, type: Type, handler: (this: Window, event: WindowEventMap[Type]) => any, options?: AddEventListenerOptions | undefined): () => void (+4 overloads)Attaches an event handler to the window and returns a function that removes the handler. Using this
rather than addEventListener will preserve the correct order relative to handlers added declaratively
(with attributes like onclick), which use event delegation for performance reasons
on } from 'svelte/events';

export class class MediaQueryMediaQuery {
	#query;
	#subscribe;

	constructor(query: anyquery) {
		this.#query = var window: Window & typeof globalThisMDN Reference
window.function matchMedia(query: string): MediaQueryListMDN Reference
matchMedia(`(${query: anyquery})`);

		this.#subscribe = function createSubscriber(start: (update: () => void) => (() => void) | void): () => voidReturns a subscribe function that, if called in an effect (including expressions in the template),
calls its start callback with an update function. Whenever update is called, the effect re-runs.
If start returns a function, it will be called when the effect is destroyed.
If subscribe is called in multiple effects, start will only be called once as long as the effects
are active, and the returned teardown function will only be called when all effects are destroyed.
It’s best understood with an example. Here’s an implementation of MediaQuery:
import { createSubscriber } from 'svelte/reactivity';
import { on } from 'svelte/events';

export class MediaQuery {
	#query;
	#subscribe;

	constructor(query) {
		this.#query = window.matchMedia(`(${query})`);

		this.#subscribe = createSubscriber((update) => {
			// when the `change` event occurs, re-run any effects that read `this.current`
			const off = on(this.#query, 'change', update);

			// stop listening when all the effects are destroyed
			return () => off();
		});
	}

	get current() {
		this.#subscribe();

		// Return the current state of the query, whether or not we're in an effect
		return this.#query.matches;
	}
}
@since5.7.0createSubscriber((update: () => voidupdate) => {
			// when the `change` event occurs, re-run any effects that read `this.current`
			const const off: () => voidoff = on<MediaQueryList, "change">(element: MediaQueryList, type: "change", handler: (this: MediaQueryList, event: MediaQueryListEvent) => any, options?: AddEventListenerOptions | undefined): () => void (+4 overloads)Attaches an event handler to an element and returns a function that removes the handler. Using this
rather than addEventListener will preserve the correct order relative to handlers added declaratively
(with attributes like onclick), which use event delegation for performance reasons
on(this.#query, 'change', update: () => voidupdate);

			// stop listening when all the effects are destroyed
			return () => const off: () => voidoff();
		});
	}

	get MediaQuery.current: booleancurrent() {
		this.#subscribe();

		// Return the current state of the query, whether or not we're in an effect
		return this.#query.MediaQueryList.matches: booleanMDN Reference
matches;
	}
}

function createSubscriber(
	start: (update: () => void) => (() => void) | void
): () => void;

Edit this page on GitHub

previous next

svelte/reactivity/window svelte/server