A client-side component —that is, a component compiled with `generate: 'dom'` (or the `generate` option left unspecified) is a JavaScript class.
```js
import App from './App.svelte';
const app = new App({
target: document.body,
props: {
// assuming App.svelte contains something like
// `export let answer`:
answer: 42
}
});
```
The following initialisation options can be provided:
| option | default | description |
| --- | --- | --- |
| `target` | **none** | An `HTMLElement` to render to. This option is required
| `anchor` | `null` | A child of `target` to render the component immediately before
| `props` | `{}` | An object of proeprties to supply to the component
| `hydrate` | `false` | See below
| `intro` | `false` | If `true`, will play transitions on initial render, rather than waiting for subsequent state changes
Existing children of `target` are left where they are.
---
The `hydrate` option instructs Svelte to upgrade existing DOM (usually from server-side rendering) rather than creating new elements. It will only work if the component was compiled with the `hydratable: true` option.
Whereas children of `target` are normally left alone, `hydrate: true` will cause any children to be removed. For that reason, the `anchor` option cannot be used alongside `hydrate: true`.
The existing DOM doesn't need to match the component — Svelte will 'repair' the DOM as it goes.
Programmatically sets props on an instance. `component.$set({ x: 1 })` is equivalent to `x = 1` inside the component's `<script>` block.
Calling this method schedules an update for the next microtask — the DOM is *not* updated synchronously.
```js
app.$set({ answer: 42 });
```
* `component.$on(event, callback)`
---
Causes the `callback` function to be called whenever the component dispatches an `event`.
```js
app.$on('selected', event => {
console.log(event.detail.selection);
});
```
* `component.$destroy()`
Removes a component from the DOM and triggers any `onDestroy` handlers.
* `component.prop`
* `component.prop = value`
---
If a component is compiled with `accessors: true`, each instance will have getters and setters corresponding to each of the component's props. Setting a value will cause a *synchronous* update, rather than the default async update caused by `component.$set(...)`.
By default, `accessors` is `false`, unless you're compiling as a custom element.
```js
console.log(app.count);
app.count += 1;
```
### Custom element API
* TODO
### Server-side component API
* `const result = Component.render(...)`
---
Unlike client-side components, server-side components don't have a lifespan after you render them — their whole job is to create some HTML and CSS. For that reason, the API is somewhat different.
A server-side component exposes a `render` method that can be called with optional props. It returns an object with `head`, `html`, and `css` properties, where `head` contains the contents of any `<svelte:head>` elements encountered.
```js
const App = require('./App.svelte');
const { head, html, css } = App.render({
answer: 42
});
```
### svelte
The `svelte` package exposes [lifecycle functions](tutorial/onmount) and the [context API](tutorial/context-api).
* `onMount(() => void)`
* `onMount(() => () => void)`
* `onMount(callback: () => void)`
* `onMount(callback: () => () => void)`
---
The `onMount` function schedules a callback to run as soon as the component has been mounted to the DOM. It must be called during the component's initialisation (but doesn't need to live *inside* the component; it can be called from an external module).
`onMount` does not run inside a server-side component.
`onMount` does not run inside a [server-side component](docs#server-side-component-api).
```html
<script>
@ -164,7 +44,7 @@ If a function is returned from `onMount`, it will be called when the component i
</script>
```
* `beforeUpdate(() => void)`
* `beforeUpdate(callback: () => void)`
---
@ -182,7 +62,7 @@ Schedules a callback to run immediately before the component is updated after an
</script>
```
* `afterUpdate(() => void)`
* `afterUpdate(callback: () => void)`
---
@ -198,7 +78,7 @@ Schedules a callback to run immediately after the component has been updated.
</script>
```
* `onDestroy(() => void)`
* `onDestroy(callback: () => void)`
---
@ -326,8 +206,25 @@ unsubscribe(); // logs 'no more subscribers'
Creates a store whose value cannot be set from 'outside'. Instead, the function passed to `readable`, which is called when the subscriber count goes from zero to one, must call the provided `set` value. It must return a function that is called when the subscriber count goes from one to zero.
If a second argument is provided, it becomes the store's initial value.
A client-side component —that is, a component compiled with `generate: 'dom'` (or the `generate` option left unspecified) is a JavaScript class.
```js
import App from './App.svelte';
const app = new App({
target: document.body,
props: {
// assuming App.svelte contains something like
// `export let answer`:
answer: 42
}
});
```
The following initialisation options can be provided:
| option | default | description |
| --- | --- | --- |
| `target` | **none** | An `HTMLElement` to render to. This option is required
| `anchor` | `null` | A child of `target` to render the component immediately before
| `props` | `{}` | An object of proeprties to supply to the component
| `hydrate` | `false` | See below
| `intro` | `false` | If `true`, will play transitions on initial render, rather than waiting for subsequent state changes
Existing children of `target` are left where they are.
---
The `hydrate` option instructs Svelte to upgrade existing DOM (usually from server-side rendering) rather than creating new elements. It will only work if the component was compiled with the `hydratable: true` option.
Whereas children of `target` are normally left alone, `hydrate: true` will cause any children to be removed. For that reason, the `anchor` option cannot be used alongside `hydrate: true`.
The existing DOM doesn't need to match the component — Svelte will 'repair' the DOM as it goes.
Programmatically sets props on an instance. `component.$set({ x: 1 })` is equivalent to `x = 1` inside the component's `<script>` block.
Calling this method schedules an update for the next microtask — the DOM is *not* updated synchronously.
```js
app.$set({ answer: 42 });
```
* `component.$on(event, callback)`
---
Causes the `callback` function to be called whenever the component dispatches an `event`.
```js
app.$on('selected', event => {
console.log(event.detail.selection);
});
```
* `component.$destroy()`
Removes a component from the DOM and triggers any `onDestroy` handlers.
* `component.prop`
* `component.prop = value`
---
If a component is compiled with `accessors: true`, each instance will have getters and setters corresponding to each of the component's props. Setting a value will cause a *synchronous* update, rather than the default async update caused by `component.$set(...)`.
By default, `accessors` is `false`, unless you're compiling as a custom element.
```js
console.log(app.count);
app.count += 1;
```
### Custom element API
* TODO
### Server-side component API
* `const result = Component.render(...)`
---
Unlike client-side components, server-side components don't have a lifespan after you render them — their whole job is to create some HTML and CSS. For that reason, the API is somewhat different.
A server-side component exposes a `render` method that can be called with optional props. It returns an object with `head`, `html`, and `css` properties, where `head` contains the contents of any `<svelte:head>` elements encountered.
Richard Harris
7 years ago