diff --git a/site/content/docs/00-introduction.md b/site/content/docs/00-introduction.md new file mode 100644 index 0000000000..4730a0c1d5 --- /dev/null +++ b/site/content/docs/00-introduction.md @@ -0,0 +1,9 @@ +--- +title: Before we begin +--- + +> Temporary note: This document is a work-in-progress. Please forgive any missing or misleading parts, and don't be shy about asking for help in the [Discord chatroom](https://discord.gg/yy75DKs). The [tutorial](tutorial) is more complete; start there. + +This page contains detailed API reference documentation. It's intended to be a resource for people who already have some familiarity with Svelte. + +If that's not you (yet), you may prefer to visit the [interactive tutorial](tutorial) or the [examples](examples) before consulting this reference. diff --git a/site/content/docs/01-component-format.md b/site/content/docs/01-component-format.md new file mode 100644 index 0000000000..f001fee6aa --- /dev/null +++ b/site/content/docs/01-component-format.md @@ -0,0 +1,193 @@ +--- +title: Component format +--- + +--- + +Components are the building blocks of Svelte applications. They are written into `.svelte` files, using a superset of HTML. + +All three sections — script, styles and markup — are optional. + +```html + + + + + +``` + +### <script> + +A ` +``` + +#### 2. Assignments are 'reactive' + +--- + +To change component state and trigger a re-render, just assign to a locally declared variable. + +Update expressions (`count += 1`) and property assignments (`obj.x = y`) have the same effect. + +```html + +``` + +#### 3. `$:` marks a statement as reactive + +--- + +Any top-level statement (i.e. not inside a block or a function) can be made reactive by prefixing it with the `$:` label. Reactive statements run immediately before the component updates, whenever the values that they depend on have changed. + +```html + +``` + +--- + +If a statement consists entirely of an assignment to an undeclared variable, Svelte will inject a `let` declaration on your behalf. + +```html + +``` + +#### 4. Prefix stores with `$` to access their values + +--- + +Any time you have a reference to a store, you can access its value inside a component by prefixing it with the `$` character. This causes Svelte to declare the prefixed variable, and set up a store subscription that will be unsubscribed when appropriate. + +Note that the store must be declared at the top level of the component — not inside an `if` block or a function, for example. + +Local variables (that do not represent store values) must *not* have a `$` prefix. + +```html + +``` + + +### <script context="module"> + +--- + +A ` + + +``` + + +### <style> + +--- + +CSS inside a ` +``` + +--- + +To apply styles to a selector globally, use the `:global(...)` modifier. + +```html + +``` \ No newline at end of file diff --git a/site/content/docs/02-template-syntax.md b/site/content/docs/02-template-syntax.md new file mode 100644 index 0000000000..8778694789 --- /dev/null +++ b/site/content/docs/02-template-syntax.md @@ -0,0 +1,1000 @@ +--- +title: Template syntax +--- + + +### Tags + +--- + +A lowercase tag, like `
`, denotes a regular HTML element. A capitalised tag, such as ``, indicates a *component*. + +```html + + +
+ +
+``` + + +### Attributes + +--- + +By default, attributes work exactly like their HTML counterparts. + +```html +
+ +
+``` + +--- + +As in HTML, values may be unquoted. + +```html + +``` + +--- + +Attribute values can contain JavaScript expressions. + +```html +page {p} +``` + +--- + +Or they can *be* JavaScript expressions. + +```html + +``` + +--- + +An expression might include characters that would cause syntax highlighting to fail in regular HTML, so quoting the value is permitted. The quotes do not affect how the value is parsed: + +```html + +``` + +--- + +When the attribute name and value match (`name={name}`), they can be replaced with `{name}`. + +```html + + + +``` + +--- + +*Spread attributes* allow many attributes or properties to be passed to an element or component at once. + +An element or component can have multiple spread attributes, interspersed with regular ones. + +```html + +``` + + +### Text expressions + +* `{expression}` + +--- + +Text can also contain JavaScript expressions: + +```html +

Hello {name}!

+

{a} + {b} = {a + b}.

+``` + + +### HTML expressions + +* `{@html expression}` + +--- + +In a text expression, characters like `<` and `>` are escaped. With HTML expressions, they're not. + +> Svelte does not sanitize expressions before injecting HTML. If the data comes from an untrusted source, you must sanitize it, or you are exposing your users to an XSS vulnerability. + +```html +
+

{post.title}

+ {@html post.content} +
+``` + + +### If blocks + +* `{#if expression}...{/if}` +* `{#if expression}...{:else if expression}...{/if}` +* `{#if expression}...{:else}...{/if}` + +--- + +Content that is conditionally rendered can be wrapped in an if block. + +```html +{#if answer === 42} +

what was the question?

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

too hot!

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

too cold!

+{:else} +

just right!

+{/if} +``` + + +### Each blocks + +* `{#each expression as name}...{/each}` +* `{#each expression as name, index}...{/each}` +* `{#each expression as name, index (key)}...{/each}` +* `{#each expression as name}...{:else}...{/each}` + +--- + +Iterating over lists of values can be done with an each block. + +```html +

Shopping list

+
    + {#each items as item} +
  • {item.name} x {item.qty}
  • + {/each} +
+``` + +--- + +An each block can also specify an *index*, equivalent to the second argument in an `array.map(...)` callback: + +```html +{#each items as item, i} +
  • {i + 1}: {item.name} x {item.qty}
  • +{/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. + +```html +{#each items as item, i (item.id)} +
  • {i + 1}: {item.name} x {item.qty}
  • +{/each} +``` + +--- + +You can freely use destructuring patterns in each blocks. + +```html +{#each items as { id, name, qty }, i (id)} +
  • {i + 1}: {name} x {qty}
  • +{/each} +``` + +--- + +An each block can also have an `{:else}` clause, which is rendered if the list is empty. + +```html +{#each todos as todo} +

    {todo.text}

    +{:else} +

    No tasks today!

    +{/each} +``` + + +### Await blocks + +* `{#await expression}...{:then name}...{:catch name}...{/await}` +* `{#await expression}...{:then name}...{/await}` +* `{#await expression then name}...{/await}` + +--- + +Await blocks allow you to branch on the three possible states of a Promise — pending, fulfilled or rejected. + +```html +{#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). + +```html +{#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. + +```html +{#await promise then value} +

    The value is {value}

    +{/await} +``` + + +### DOM events + +* `on:eventname={handler}` +* `on:eventname|modifiers={handler}` + +--- + +Use the `on:` directive to listen to DOM events. + +```html + + + +``` + +--- + +Handlers can be declared inline with no performance penalty. As with attributes, directive values may be quoted for the sake of syntax highlighters. + +```html + +``` + +--- + +Add *modifiers* to DOM events with the `|` character. + +The following modifiers are available: + +* `preventDefault` — calls `event.preventDefault()` before running the handler +* `stopPropagation` — calls `event.stopPropagation()`, preventing the event reaching the next element +* `passive` — improves scrolling performance on touch/wheel events (Svelte will add it automatically where it's safe to do so) +* `capture` — fires the handler during the *capture* phase instead of the *bubbling* phase +* `once` — remove the handler after the first time it runs + +Modifiers can be chained together, e.g. `on:click|once|capture={...}`. + +```html +
    + +
    +``` + +--- + +If the `on:` directive is used without a value, the component will *forward* the event, meaning that a consumer of the component can listen for it. + +```html + +``` + + +### Component events + +* `on:eventname={handler}` + +--- + +Components can emit events using [createEventDispatcher](#docs/createEventDispatcher), or by forwarding DOM events. Listening for component events looks the same as listening for DOM events: + +```html + +``` + + + +### Element bindings + +* `bind:property={value}` + +--- + +Data ordinarily flows down, from parent to child. The `bind:` directive allows data to flow the other way, from child to parent. Most bindings are specific to particular elements. + +The simplest bindings reflect the value of a property, such as `input.value`. + +```html + + + + +``` + +--- + +If the name matches the value, you can use a shorthand. + +```html + + + +``` + +--- + +Numeric input values are coerced; even though `input.value` is a string as far as the DOM is concerned, Svelte will treat it as a number. If the input is empty or invalid (in the case of `type="number"`), the value is `undefined`. + +```html + + +``` + +--- + +Inputs that work together can use `bind:group`. + +```html + + + + + + + + + + + + +``` + +--- + +A ` + + + + +``` + +--- + +A ` + + + + + +``` + +--- + +When the value of an `