Skip to content

Sync svelte docs #1354

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 23, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions apps/svelte.dev/content/docs/svelte/02-runes/02-$state.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,7 @@ Unlike other frameworks you may have encountered, there is no API for interactin

If `$state` is used with an array or a simple object, the result is a deeply reactive _state proxy_. [Proxies](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) allow Svelte to run code when you read or write properties, including via methods like `array.push(...)`, triggering granular updates.

> [!NOTE] Class instances are not proxied. You can create [reactive state fields](#Classes) on classes that you define. Svelte provides reactive implementations of built-ins like `Set` and `Map` that can be imported from [`svelte/reactivity`](svelte-reactivity).
State is proxified recursively until Svelte finds something other than an array or simple object. In a case like this...
State is proxified recursively until Svelte finds something other than an array or simple object (like a class). In a case like this...

```js
let todos = $state([
Expand Down Expand Up @@ -68,7 +66,7 @@ todos[0].done = !todos[0].done;

### Classes

You can also use `$state` in class fields (whether public or private), or as the first assignment to a property immediately inside the `constructor`:
Class instances are not proxied. Instead, you can use `$state` in class fields (whether public or private), or as the first assignment to a property immediately inside the `constructor`:

```js
// @errors: 7006 2554
Expand Down Expand Up @@ -122,6 +120,8 @@ class Todo {
}
```

> Svelte provides reactive implementations of built-in classes like `Set` and `Map` that can be imported from [`svelte/reactivity`](svelte-reactivity).
## `$state.raw`

In cases where you don't want objects and arrays to be deeply reactive you can use `$state.raw`.
Expand All @@ -146,6 +146,8 @@ person = {

This can improve performance with large arrays and objects that you weren't planning to mutate anyway, since it avoids the cost of making them reactive. Note that raw state can _contain_ reactive state (for example, a raw array of reactive objects).

As with `$state`, you can declare class fields using `$state.raw`.

## `$state.snapshot`

To take a static snapshot of a deeply reactive `$state` proxy, use `$state.snapshot`:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -161,3 +161,7 @@ function foo(+++getBar+++) {
## Creating attachments programmatically

To add attachments to an object that will be spread onto a component or element, use [`createAttachmentKey`](svelte-attachments#createAttachmentKey).

## Converting actions to attachments

If you're using a library that only provides actions, you can convert them to attachments with [`fromAction`](svelte-attachments#fromAction), allowing you to (for example) use them with components.
19 changes: 10 additions & 9 deletions apps/svelte.dev/content/docs/svelte/03-template-syntax/12-bind.md
Original file line number Diff line number Diff line change
Expand Up @@ -143,26 +143,27 @@ Checkboxes can be in an [indeterminate](https://developer.mozilla.org/en-US/docs

## `<input bind:group>`

Inputs that work together can use `bind:group`.
Inputs that work together can use `bind:group` ([demo](/playground/untitled#H4sIAAAAAAAAE62T32_TMBDH_5XDQkpbrct7SCMGEvCEECDxsO7BSW6L2c227EvbKOv_jp0f6jYhQKJv5_P3PvdL1wstH1Bk4hMSGdgbRzUssFaM9VJciFtF6EV23QvubNRFR_BPUVfWXvodEkdfKT3-zl8Zzag5YETuK6csF1u9ZUIGNo4VkYQNvPYsGRfJF5JKJ8s3QRJE6WoFb2Nq6K-ck13u2Sl9Vxxhlc6QUBIFnz9Brm9ifJ6esun81XoNd860FmtwslYGlLYte5AO4aHlVhJ1gIeKWq92COt1iMtJlkhFPkgh1rHZiiF6K6BUus4G5KafGznCTlIbVUMfQZUWMJh5OrL-C_qjMYSwb1DyiH7iOEuCb1ZpWTUjfHqcwC_GWDVY3ZfmME_SGttSmD9IHaYatvWHIc6xLyqad3mq6KuqcCwnWn9p8p-p71BqP2IH81zc9w2in-od7XORP7ayCpd5YCeXI_-p59mObPF9WmwGpx3nqS2Gzw8TO3zOaS5_GqUXyQUkS3h8hOSz0ZhMESHGc0c4Hm3MAn00t1wrb0l2GZRkqvt4sXwczm6Qh8vnUJzI2LV4vAkvqWgfehTZrSSPx19WiVfFfAQAAA==)):

```svelte
<!--- file: BurritoChooser.svelte --->
<script>
let tortilla = $state('Plain');
/** @type {Array<string>} */
/** @type {string[]} */
let fillings = $state([]);
</script>
<!-- grouped radio inputs are mutually exclusive -->
<input type="radio" bind:group={tortilla} value="Plain" />
<input type="radio" bind:group={tortilla} value="Whole wheat" />
<input type="radio" bind:group={tortilla} value="Spinach" />
<label><input type="radio" bind:group={tortilla} value="Plain" /> Plain</label>
<label><input type="radio" bind:group={tortilla} value="Whole wheat" /> Whole wheat</label>
<label><input type="radio" bind:group={tortilla} value="Spinach" /> Spinach</label>
<!-- grouped checkbox inputs populate an array -->
<input type="checkbox" bind:group={fillings} value="Rice" />
<input type="checkbox" bind:group={fillings} value="Beans" />
<input type="checkbox" bind:group={fillings} value="Cheese" />
<input type="checkbox" bind:group={fillings} value="Guac (extra)" />
<label><input type="checkbox" bind:group={fillings} value="Rice" /> Rice</label>
<label><input type="checkbox" bind:group={fillings} value="Beans" /> Beans</label>
<label><input type="checkbox" bind:group={fillings} value="Cheese" /> Cheese</label>
<label><input type="checkbox" bind:group={fillings} value="Guac (extra)" /> Guac (extra)</label>
```

> [!NOTE] `bind:group` only works if the inputs are in the same Svelte component.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,19 @@ Consider the following code:

To fix it, either create callback props to communicate changes, or mark `person` as [`$bindable`]($bindable).

### select_multiple_invalid_value

```
The `value` property of a `<select multiple>` element should be an array, but it received a non-array value. The selection will be kept as is.
```

When using `<select multiple value={...}>`, Svelte will mark all selected `<option>` elements as selected by iterating over the array passed to `value`. If `value` is not an array, Svelte will emit this warning and keep the selected options as they are.

To silence the warning, ensure that `value`:

- is an array for an explicit selection
- is `null` or `undefined` to keep the selection as is

### state_proxy_equality_mismatch

```
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -632,6 +632,25 @@ In some situations a selector may target an element that is not 'visible' to the
</style>
```

### element_implicitly_closed

```
This element is implicitly closed by the following `%tag%`, which can cause an unexpected DOM structure. Add an explicit `%closing%` to avoid surprises.
```

In HTML, some elements are implicitly closed by another element. For example, you cannot nest a `<p>` inside another `<p>`:

```html
<!-- this HTML... -->
<p><p>hello</p>

<!-- results in this DOM structure -->
<p></p>
<p>hello</p>
```

Similarly, a parent element's closing tag will implicitly close all child elements, even if the `</` was a typo and you meant to create a _new_ element. To avoid ambiguity, it's always a good idea to have an explicit closing tag.

### element_invalid_self_closing_tag

```
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ title: svelte/attachments

```js
// @noErrors
import { createAttachmentKey } from 'svelte/attachments';
import { createAttachmentKey, fromAction } from 'svelte/attachments';
```

## createAttachmentKey
Expand Down Expand Up @@ -48,6 +48,52 @@ function createAttachmentKey(): symbol;



## fromAction

Converts an [action](/docs/svelte/use) into an [attachment](/docs/svelte/@attach) keeping the same behavior.
It's useful if you want to start using attachments on components but you have actions provided by a library.

Note that the second argument, if provided, must be a function that _returns_ the argument to the
action function, not the argument itself.

```svelte
<!-- with an action -->
<div use:foo={bar}>...</div>

<!-- with an attachment -->
<div {@attach fromAction(foo, () => bar)}>...</div>
```

<div class="ts-block">

```dts
function fromAction<
E extends EventTarget,
T extends unknown
>(
action:
| Action<E, T>
| ((element: E, arg: T) => void | ActionReturn<T>),
fn: () => T
): Attachment<E>;
```

</div>

<div class="ts-block">

```dts
function fromAction<E extends EventTarget>(
action:
| Action<E, void>
| ((element: E) => void | ActionReturn<void>)
): Attachment<E>;
```

</div>



## Attachment

An [attachment](/docs/svelte/@attach) is a function that runs when an element is mounted
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -811,6 +811,28 @@ If `true`, whitespace inside and between elements is kept as you typed it, rathe

<div class="ts-block-property">

```dts
fragments?: 'html' | 'tree';
```

<div class="ts-block-property-details">

<div class="ts-block-property-bullets">

- <span class="tag">default</span> `'html'`

</div>

Which strategy to use when cloning DOM fragments:

- `html` populates a `<template>` with `innerHTML` and clones it. This is faster, but cannot be used if your app's [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) includes [`require-trusted-types-for 'script'`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/require-trusted-types-for)
- `tree` creates the fragment one element at a time and _then_ clones it. This is slower, but works everywhere

</div>
</div>

<div class="ts-block-property">

```dts
runes?: boolean | undefined;
```
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -653,6 +653,25 @@ In some situations a selector may target an element that is not 'visible' to the
</style>
```

### element_implicitly_closed

```
This element is implicitly closed by the following `%tag%`, which can cause an unexpected DOM structure. Add an explicit `%closing%` to avoid surprises.
```

In HTML, some elements are implicitly closed by another element. For example, you cannot nest a `<p>` inside another `<p>`:

```html
<!-- this HTML... -->
<p><p>hello</p>

<!-- results in this DOM structure -->
<p></p>
<p>hello</p>
```

Similarly, a parent element's closing tag will implicitly close all child elements, even if the `</` was a typo and you meant to create a _new_ element. To avoid ambiguity, it's always a good idea to have an explicit closing tag.

### element_invalid_self_closing_tag

```
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -207,6 +207,19 @@ Consider the following code:
To fix it, either create callback props to communicate changes, or mark `person` as [`$bindable`]($bindable).
### select_multiple_invalid_value
```
The `value` property of a `<select multiple>` element should be an array, but it received a non-array value. The selection will be kept as is.
```
When using `<select multiple value={...}>`, Svelte will mark all selected `<option>` elements as selected by iterating over the array passed to `value`. If `value` is not an array, Svelte will emit this warning and keep the selected options as they are.
To silence the warning, ensure that `value`:
- is an array for an explicit selection
- is `null` or `undefined` to keep the selection as is
### state_proxy_equality_mismatch
```
Expand Down