mirror of https://github.com/sveltejs/svelte
ComputerGuy
5 months ago
commit
610420561c
@ -0,0 +1,5 @@
|
||||
---
|
||||
'svelte': patch
|
||||
---
|
||||
|
||||
fix: allow characters in the supplementary special-purpose plane
|
||||
@ -1,139 +0,0 @@
|
||||
---
|
||||
title: Public API of a component
|
||||
---
|
||||
|
||||
### Public API of a component
|
||||
|
||||
Svelte uses the `$props` rune to declare _properties_ or _props_, which means describing the public interface of the component which becomes accessible to consumers of the component.
|
||||
|
||||
> [!NOTE] `$props` is one of several runes, which are special hints for Svelte's compiler to make things reactive.
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
let { foo, bar, baz } = $props();
|
||||
|
||||
// Values that are passed in as props
|
||||
// are immediately available
|
||||
console.log({ foo, bar, baz });
|
||||
</script>
|
||||
```
|
||||
|
||||
You can specify a fallback value for a prop. It will be used if the component's consumer doesn't specify the prop on the component when instantiating the component, or if the passed value is `undefined` at some point.
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
let { foo = 'optional default initial value' } = $props();
|
||||
</script>
|
||||
```
|
||||
|
||||
To get all properties, use rest syntax:
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
let { a, b, c, ...everythingElse } = $props();
|
||||
</script>
|
||||
```
|
||||
|
||||
You can use reserved words as prop names.
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
// creates a `class` property, even
|
||||
// though it is a reserved word
|
||||
let { class: className } = $props();
|
||||
</script>
|
||||
```
|
||||
|
||||
If you're using TypeScript, you can declare the prop types:
|
||||
|
||||
```svelte
|
||||
<script lang="ts">
|
||||
interface Props {
|
||||
required: string;
|
||||
optional?: number;
|
||||
[key: string]: unknown;
|
||||
}
|
||||
|
||||
let { required, optional, ...everythingElse }: Props = $props();
|
||||
</script>
|
||||
```
|
||||
|
||||
If you're using JavaScript, you can declare the prop types using JSDoc:
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
/** @type {{ x: string }} */
|
||||
let { x } = $props();
|
||||
|
||||
// or use @typedef if you want to document the properties:
|
||||
|
||||
/**
|
||||
* @typedef {Object} MyProps
|
||||
* @property {string} y Some documentation
|
||||
*/
|
||||
|
||||
/** @type {MyProps} */
|
||||
let { y } = $props();
|
||||
</script>
|
||||
```
|
||||
|
||||
If you export a `const`, `class` or `function`, it is readonly from outside the component.
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
export const thisIs = 'readonly';
|
||||
|
||||
export function greet(name) {
|
||||
alert(`hello ${name}!`);
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
Readonly props can be accessed as properties on the element, tied to the component using [`bind:this` syntax](bindings#bind:this).
|
||||
|
||||
### Reactive variables
|
||||
|
||||
To change component state and trigger a re-render, just assign to a locally declared variable that was declared using the `$state` rune.
|
||||
|
||||
Update expressions (`count += 1`) and property assignments (`obj.x = y`) have the same effect.
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
let count = $state(0);
|
||||
|
||||
function handleClick() {
|
||||
// calling this function will trigger an
|
||||
// update if the markup references `count`
|
||||
count = count + 1;
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
Svelte's `<script>` blocks are run only when the component is created, so assignments within a `<script>` block are not automatically run again when a prop updates.
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
let { person } = $props();
|
||||
// this will only set `name` on component creation
|
||||
// it will not update when `person` does
|
||||
let { name } = person;
|
||||
</script>
|
||||
```
|
||||
|
||||
If you'd like to react to changes to a prop, use the `$derived` or `$effect` runes instead.
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
let count = $state(0);
|
||||
|
||||
let double = $derived(count * 2);
|
||||
|
||||
$effect(() => {
|
||||
if (count > 10) {
|
||||
alert('Too high!');
|
||||
}
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
For more information on reactivity, read the documentation around runes.
|
||||
@ -1,144 +0,0 @@
|
||||
---
|
||||
title: Reactivity fundamentals
|
||||
---
|
||||
|
||||
Reactivity is at the heart of interactive UIs. When you click a button, you expect some kind of response. It's your job as a developer to make this happen. It's Svelte's job to make your job as intuitive as possible, by providing a good API to express reactive systems.
|
||||
|
||||
## Runes
|
||||
|
||||
Svelte 5 uses _runes_, a powerful set of primitives for controlling reactivity inside your Svelte components and inside `.svelte.js` and `.svelte.ts` modules.
|
||||
|
||||
Runes are function-like symbols that provide instructions to the Svelte compiler. You don't need to import them from anywhere — when you use Svelte, they're part of the language.
|
||||
|
||||
The following sections introduce the most important runes for declare state, derived state and side effects at a high level. For more details refer to the later sections on [state](state) and [side effects](side-effects).
|
||||
|
||||
## `$state`
|
||||
|
||||
Reactive state is declared with the `$state` rune:
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
let count = $state(0);
|
||||
</script>
|
||||
|
||||
<button onclick={() => count++}>
|
||||
clicks: {count}
|
||||
</button>
|
||||
```
|
||||
|
||||
You can also use `$state` in class fields (whether public or private):
|
||||
|
||||
```js
|
||||
// @errors: 7006 2554
|
||||
class Todo {
|
||||
done = $state(false);
|
||||
text = $state();
|
||||
|
||||
constructor(text) {
|
||||
this.text = text;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> [!LEGACY]
|
||||
> In Svelte 4, state was implicitly reactive if the variable was declared at the top level
|
||||
>
|
||||
> ```svelte
|
||||
> <script>
|
||||
> let count = 0;
|
||||
> </script>
|
||||
>
|
||||
> <button on:click={() => count++}>
|
||||
> clicks: {count}
|
||||
> </button>
|
||||
> ```
|
||||
|
||||
## `$derived`
|
||||
|
||||
Derived state is declared with the `$derived` rune:
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
let count = $state(0);
|
||||
let doubled = $derived(count * 2);
|
||||
</script>
|
||||
|
||||
<button onclick={() => count++}>
|
||||
{doubled}
|
||||
</button>
|
||||
|
||||
<p>{count} doubled is {doubled}</p>
|
||||
```
|
||||
|
||||
The expression inside `$derived(...)` should be free of side-effects. Svelte will disallow state changes (e.g. `count++`) inside derived expressions.
|
||||
|
||||
As with `$state`, you can mark class fields as `$derived`.
|
||||
|
||||
> [!LEGACY]
|
||||
> In Svelte 4, you could use reactive statements for this.
|
||||
>
|
||||
> ```svelte
|
||||
> <script>
|
||||
> let count = 0;
|
||||
> $: doubled = count * 2;
|
||||
> </script>
|
||||
>
|
||||
> <button on:click={() => count++}>
|
||||
> {doubled}
|
||||
> </button>
|
||||
>
|
||||
> <p>{count} doubled is {doubled}</p>
|
||||
> ```
|
||||
>
|
||||
> This only worked at the top level of a component.
|
||||
|
||||
## `$effect`
|
||||
|
||||
To run _side-effects_ when the component is mounted to the DOM, and when values change, we can use the `$effect` rune ([demo](/playground/untitled#H4sIAAAAAAAAE31T24rbMBD9lUG7kAQ2sbdlX7xOYNk_aB_rQhRpbAsU2UiTW0P-vbrYubSlYGzmzMzROTPymdVKo2PFjzMzfIusYB99z14YnfoQuD1qQh-7bmdFQEonrOppVZmKNBI49QthCc-OOOH0LZ-9jxnR6c7eUpOnuv6KeT5JFdcqbvbcBcgDz1jXKGg6ncFyBedYR6IzLrAZwiN5vtSxaJA-EzadfJEjKw11C6GR22-BLH8B_wxdByWpvUYtqqal2XB6RVkG1CoHB6U1WJzbnYFDiwb3aGEdDa3Bm1oH12sQLTcNPp7r56m_00mHocSG97_zd7ICUXonA5fwKbPbkE2ZtMJGGVkEdctzQi4QzSwr9prnFYNk5hpmqVuqPQjNnfOJoMF22lUsrq_UfIN6lfSVyvQ7grB3X2mjMZYO3XO9w-U5iLx42qg29md3BP_ni5P4gy9ikTBlHxjLzAtPDlyYZmRdjAbGq7HprEQ7p64v4LU_guu0kvAkhBim3nMplWl8FreQD-CW20aZR0wq12t-KqDWeBywhvexKC3memmDwlHAv9q4Vo2ZK8KtK0CgX7u9J8wXbzdKv-nRnfF_2baTqlYoWUF2h5efl9-n0O6koAMAAA==)):
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
let size = $state(50);
|
||||
let color = $state('#ff3e00');
|
||||
|
||||
let canvas;
|
||||
|
||||
$effect(() => {
|
||||
const context = canvas.getContext('2d');
|
||||
context.clearRect(0, 0, canvas.width, canvas.height);
|
||||
|
||||
// this will re-run whenever `color` or `size` change
|
||||
context.fillStyle = color;
|
||||
context.fillRect(0, 0, size, size);
|
||||
});
|
||||
</script>
|
||||
|
||||
<canvas bind:this={canvas} width="100" height="100" />
|
||||
```
|
||||
|
||||
The function passed to `$effect` will run when the component mounts, and will re-run after any changes to the values it reads that were declared with `$state` or `$derived` (including those passed in with `$props`). Re-runs are batched (i.e. changing `color` and `size` in the same moment won't cause two separate runs), and happen after any DOM updates have been applied.
|
||||
|
||||
> [!LEGACY]
|
||||
> In Svelte 4, you could use reactive statements for this.
|
||||
>
|
||||
> ```svelte
|
||||
> <script>
|
||||
> let size = 50;
|
||||
> let color = '#ff3e00';
|
||||
>
|
||||
> let canvas;
|
||||
>
|
||||
> $: {
|
||||
> const context = canvas.getContext('2d');
|
||||
> context.clearRect(0, 0, canvas.width, canvas.height);
|
||||
>
|
||||
> // this will re-run whenever `color` or `size` change
|
||||
> context.fillStyle = color;
|
||||
> context.fillRect(0, 0, size, size);
|
||||
> }
|
||||
> </script>
|
||||
>
|
||||
> <canvas bind:this={canvas} width="100" height="100" />
|
||||
> ```
|
||||
>
|
||||
> This only worked at the top level of a component.
|
||||
@ -1,111 +0,0 @@
|
||||
---
|
||||
title: Control flow
|
||||
---
|
||||
|
||||
- if
|
||||
- each
|
||||
- await (or move that into some kind of data loading section?)
|
||||
- NOT: key (move into transition section, because that's the common use case)
|
||||
|
||||
Svelte augments HTML with control flow blocks to be able to express conditionally rendered content or lists.
|
||||
|
||||
The syntax between these blocks is the same:
|
||||
|
||||
- `{#` denotes the start of a block
|
||||
- `{:` denotes a different branch part of the block. Depending on the block, there can be multiple of these
|
||||
- `{/` denotes the end of a block
|
||||
|
||||
## {#if ...}
|
||||
|
||||
## {#each ...}
|
||||
|
||||
```svelte
|
||||
<!--- copy: false --->
|
||||
{#each expression as name}...{/each}
|
||||
```
|
||||
|
||||
```svelte
|
||||
<!--- copy: false --->
|
||||
{#each expression as name, index}...{/each}
|
||||
```
|
||||
|
||||
```svelte
|
||||
<!--- copy: false --->
|
||||
{#each expression as name (key)}...{/each}
|
||||
```
|
||||
|
||||
```svelte
|
||||
<!--- copy: false --->
|
||||
{#each expression as name, index (key)}...{/each}
|
||||
```
|
||||
|
||||
```svelte
|
||||
<!--- copy: false --->
|
||||
{#each expression as name}...{:else}...{/each}
|
||||
```
|
||||
|
||||
Iterating over lists of values can be done with an each block.
|
||||
|
||||
```svelte
|
||||
<h1>Shopping list</h1>
|
||||
<ul>
|
||||
{#each items as item}
|
||||
<li>{item.name} x {item.qty}</li>
|
||||
{/each}
|
||||
</ul>
|
||||
```
|
||||
|
||||
You can use each blocks to iterate over any array or array-like value — that is, any object with a `length` property.
|
||||
|
||||
An each block can also specify an _index_, equivalent to the second argument in an `array.map(...)` callback:
|
||||
|
||||
```svelte
|
||||
{#each items as item, i}
|
||||
<li>{i + 1}: {item.name} x {item.qty}</li>
|
||||
{/each}
|
||||
```
|
||||
|
||||
If a _key_ expression is provided — which must uniquely identify each list item — Svelte will use it to diff the list when data changes, rather than adding or removing items at the end. The key can be any object, but strings and numbers are recommended since they allow identity to persist when the objects themselves change.
|
||||
|
||||
```svelte
|
||||
{#each items as item (item.id)}
|
||||
<li>{item.name} x {item.qty}</li>
|
||||
{/each}
|
||||
|
||||
<!-- or with additional index value -->
|
||||
{#each items as item, i (item.id)}
|
||||
<li>{i + 1}: {item.name} x {item.qty}</li>
|
||||
{/each}
|
||||
```
|
||||
|
||||
You can freely use destructuring and rest patterns in each blocks.
|
||||
|
||||
```svelte
|
||||
{#each items as { id, name, qty }, i (id)}
|
||||
<li>{i + 1}: {name} x {qty}</li>
|
||||
{/each}
|
||||
|
||||
{#each objects as { id, ...rest }}
|
||||
<li><span>{id}</span><MyComponent {...rest} /></li>
|
||||
{/each}
|
||||
|
||||
{#each items as [id, ...rest]}
|
||||
<li><span>{id}</span><MyComponent values={rest} /></li>
|
||||
{/each}
|
||||
```
|
||||
|
||||
An each block can also have an `{:else}` clause, which is rendered if the list is empty.
|
||||
|
||||
```svelte
|
||||
{#each todos as todo}
|
||||
<p>{todo.text}</p>
|
||||
{:else}
|
||||
<p>No tasks today!</p>
|
||||
{/each}
|
||||
```
|
||||
|
||||
It is possible to iterate over iterables like `Map` or `Set`. Iterables need to be finite and static (they shouldn't change while being iterated over). Under the hood, they are transformed to an array using `Array.from` before being passed off to rendering. If you're writing performance-sensitive code, try to avoid iterables and use regular arrays as they are more performant.
|
||||
|
||||
## Other block types
|
||||
|
||||
Svelte also provides [`#snippet`](snippets), [`#key`](transitions-and-animations) and [`#await`](data-fetching) blocks. You can find out more about them in their respective sections.
|
||||
@ -1,20 +0,0 @@
|
||||
---
|
||||
title: Data fetching
|
||||
---
|
||||
|
||||
Fetching data is a fundamental part of apps interacting with the outside world. Svelte is unopinionated with how you fetch your data. The simplest way would be using the built-in `fetch` method:
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
let response = $state();
|
||||
fetch('/api/data').then(async (r) => (response = r.json()));
|
||||
</script>
|
||||
```
|
||||
|
||||
While this works, it makes working with promises somewhat unergonomic. Svelte alleviates this problem using the `#await` block.
|
||||
|
||||
## {#await ...}
|
||||
|
||||
## SvelteKit loaders
|
||||
|
||||
Fetching inside your components is great for simple use cases, but it's prone to data loading waterfalls and makes code harder to work with because of the promise handling. SvelteKit solves this problem by providing a opinionated data loading story that is coupled to its router. Learn more about it [in the docs](../kit).
|
||||
@ -1,6 +0,0 @@
|
||||
---
|
||||
title: Reactivity in depth
|
||||
---
|
||||
|
||||
- how to think about Runes ("just JavaScript" with added reactivity, what this means for keeping reactivity alive across boundaries)
|
||||
- signals
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue