diff --git a/documentation/docs/03-template-syntax/02-if.md b/documentation/docs/03-template-syntax/02-if.md index 2401022fab..1378733e6f 100644 --- a/documentation/docs/03-template-syntax/02-if.md +++ b/documentation/docs/03-template-syntax/02-if.md @@ -2,4 +2,39 @@ title: {#if ...} --- -Coming soon! +```svelte + +{#if expression}...{/if} +``` + +```svelte + +{#if expression}...{:else if expression}...{/if} +``` + +```svelte + +{#if expression}...{:else}...{/if} +``` + +Content that is conditionally rendered can be wrapped in an if block. + +```svelte +{#if answer === 42} +

what was the question?

+{/if} +``` + +Additional conditions can be added with `{:else if expression}`, optionally ending in an `{:else}` clause. + +```svelte +{#if porridge.temperature > 100} +

too hot!

+{:else if 80 > porridge.temperature} +

too cold!

+{:else} +

just right!

+{/if} +``` + +(Blocks don't have to wrap elements, they can also wrap text within elements.) diff --git a/documentation/docs/03-template-syntax/03-each.md b/documentation/docs/03-template-syntax/03-each.md index fffa1d98ac..e4246b6e9a 100644 --- a/documentation/docs/03-template-syntax/03-each.md +++ b/documentation/docs/03-template-syntax/03-each.md @@ -2,4 +2,91 @@ title: {#each ...} --- -Coming soon! +```svelte + +{#each expression as name}...{/each} +``` + +```svelte + +{#each expression as name, index}...{/each} +``` + +Iterating over values can be done with an each block. The values in question can be arrays, array-like objects (i.e. anything with a `length` property), or iterables like `Map` and `Set` — in other words, anything that can be used with `Array.from`. + +```svelte +

Shopping list

+ +``` + +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} +
  • {i + 1}: {item.name} x {item.qty}
  • +{/each} +``` + +## Keyed each blocks + +```svelte + +{#each expression as name (key)}...{/each} +``` + +```svelte + +{#each expression as name, index (key)}...{/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)} +
  • {item.name} x {item.qty}
  • +{/each} + + +{#each items as item, i (item.id)} +
  • {i + 1}: {item.name} x {item.qty}
  • +{/each} +``` + +You can freely use destructuring and rest patterns in each blocks. + +```svelte +{#each items as { id, name, qty }, i (id)} +
  • {i + 1}: {name} x {qty}
  • +{/each} + +{#each objects as { id, ...rest }} +
  • {id}
  • +{/each} + +{#each items as [id, ...rest]} +
  • {id}
  • +{/each} +``` + +## Else blocks + +```svelte + +{#each expression as name}...{:else}...{/each} +``` + +An each block can also have an `{:else}` clause, which is rendered if the list is empty. + +```svelte +{#each todos as todo} +

    {todo.text}

    +{:else} +

    No tasks today!

    +{/each} +``` diff --git a/documentation/docs/03-template-syntax/04-key.md b/documentation/docs/03-template-syntax/04-key.md index 765a14da37..10b6ab4358 100644 --- a/documentation/docs/03-template-syntax/04-key.md +++ b/documentation/docs/03-template-syntax/04-key.md @@ -2,4 +2,23 @@ title: {#key ...} --- -Coming soon! +```svelte + +{#key expression}...{/key} +``` + +Key blocks destroy and recreate their contents when the value of an expression changes. When used around components, this will cause them to be reinstantiated and reinitialised: + +```svelte +{#key value} + +{/key} +``` + +It's also useful if you want a transition to play whenever a value changes: + +```svelte +{#key value} +
    {value}
    +{/key} +``` diff --git a/documentation/docs/03-template-syntax/05-await.md b/documentation/docs/03-template-syntax/05-await.md index 6df9ab5d13..7fe7a963c5 100644 --- a/documentation/docs/03-template-syntax/05-await.md +++ b/documentation/docs/03-template-syntax/05-await.md @@ -2,4 +2,69 @@ title: {#await ...} --- -Coming soon! +```svelte + +{#await expression}...{:then name}...{:catch name}...{/await} +``` + +```svelte + +{#await expression}...{:then name}...{/await} +``` + +```svelte + +{#await expression then name}...{/await} +``` + +```svelte + +{#await expression catch name}...{/await} +``` + +Await blocks allow you to branch on the three possible states of a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — pending, fulfilled or rejected. + +```svelte +{#await promise} + +

    waiting for the promise to resolve...

    +{:then value} + +

    The value is {value}

    +{:catch error} + +

    Something went wrong: {error.message}

    +{/await} +``` + +> [!NOTE] During server-side rendering, only the pending branch will be rendered. +> +> If the provided expression is not a `Promise` only the `:then` branch will be rendered, including during server-side rendering. + +The `catch` block can be omitted if you don't need to render anything when the promise rejects (or no error is possible). + +```svelte +{#await promise} + +

    waiting for the promise to resolve...

    +{:then value} + +

    The value is {value}

    +{/await} +``` + +If you don't care about the pending state, you can also omit the initial block. + +```svelte +{#await promise then value} +

    The value is {value}

    +{/await} +``` + +Similarly, if you only want to show the error state, you can omit the `then` block. + +```svelte +{#await promise catch error} +

    The error is {error}

    +{/await} +``` diff --git a/documentation/docs/03-template-syntax/12-transition.md b/documentation/docs/03-template-syntax/12-transition.md index 26056babe8..114d4d9780 100644 --- a/documentation/docs/03-template-syntax/12-transition.md +++ b/documentation/docs/03-template-syntax/12-transition.md @@ -408,28 +408,3 @@ A custom animation function can also return a `tick` function, which is called _
    {item}
    {/each} ``` - -## {#key ...} - -```svelte - -{#key expression}...{/key} -``` - -Key blocks destroy and recreate their contents when the value of an expression changes. - -This is useful if you want an element to play its transition whenever a value changes. - -```svelte -{#key value} -
    {value}
    -{/key} -``` - -When used around components, this will cause them to be reinstantiated and reinitialised. - -```svelte -{#key value} - -{/key} -``` diff --git a/documentation/docs/03-template-syntax/xx-control-flow.md b/documentation/docs/03-template-syntax/xx-control-flow.md index 84c44568df..b73917997b 100644 --- a/documentation/docs/03-template-syntax/xx-control-flow.md +++ b/documentation/docs/03-template-syntax/xx-control-flow.md @@ -17,43 +17,6 @@ The syntax between these blocks is the same: ## {#if ...} -```svelte - -{#if expression}...{/if} -``` - -```svelte - -{#if expression}...{:else if expression}...{/if} -``` - -```svelte - -{#if expression}...{:else}...{/if} -``` - -Content that is conditionally rendered can be wrapped in an if block. - -```svelte -{#if answer === 42} -

    what was the question?

    -{/if} -``` - -Additional conditions can be added with `{:else if expression}`, optionally ending in an `{:else}` clause. - -```svelte -{#if porridge.temperature > 100} -

    too hot!

    -{:else if 80 > porridge.temperature} -

    too cold!

    -{:else} -

    just right!

    -{/if} -``` - -(Blocks don't have to wrap elements, they can also wrap text within elements!) - ## {#each ...} ```svelte diff --git a/documentation/docs/03-template-syntax/xx-data-fetching.md b/documentation/docs/03-template-syntax/xx-data-fetching.md index ba424e1721..4526d51335 100644 --- a/documentation/docs/03-template-syntax/xx-data-fetching.md +++ b/documentation/docs/03-template-syntax/xx-data-fetching.md @@ -15,71 +15,6 @@ While this works, it makes working with promises somewhat unergonomic. Svelte al ## {#await ...} -```svelte - -{#await expression}...{:then name}...{:catch name}...{/await} -``` - -```svelte - -{#await expression}...{:then name}...{/await} -``` - -```svelte - -{#await expression then name}...{/await} -``` - -```svelte - -{#await expression catch name}...{/await} -``` - -Await blocks allow you to branch on the three possible states of a Promise — pending, fulfilled or rejected. -In SSR mode, only the pending branch will be rendered on the server. -If the provided expression is not a Promise only the fulfilled branch will be rendered, including in SSR mode. - -```svelte -{#await promise} - -

    waiting for the promise to resolve...

    -{:then value} - -

    The value is {value}

    -{:catch error} - -

    Something went wrong: {error.message}

    -{/await} -``` - -The `catch` block can be omitted if you don't need to render anything when the promise rejects (or no error is possible). - -```svelte -{#await promise} - -

    waiting for the promise to resolve...

    -{:then value} - -

    The value is {value}

    -{/await} -``` - -If you don't care about the pending state, you can also omit the initial block. - -```svelte -{#await promise then value} -

    The value is {value}

    -{/await} -``` - -Similarly, if you only want to show the error state, you can omit the `then` block. - -```svelte -{#await promise catch error} -

    The error is {error}

    -{/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).