Using an older version of Svelte? Have a look at the v2 docs .

Don't be shy about asking for help in the Discord chatroom .

If that's not you (yet), you may prefer to visit the interactive tutorial or the examples before consulting this reference.

This page contains detailed API reference documentation. It's intended to be a resource for people who already have some familiarity with Svelte.

The -global- part will be removed when compiled, and the keyframe then be referenced using just my-animation-name elsewhere in your code.

If you want to make @keyframes that are accessible globally, you need to prepend your keyframe names with -global- .

To apply styles to a selector globally, use the :global(...) modifier.

This works by adding a class to affected elements, which is based on a hash of the component styles (e.g. svelte-123xyz ).

CSS inside a <style> block will be scoped to that component.

total number of times this component has been created:

` total number of times this component has been created: ${ totalComponents } `

totalComponents += 1 ; console . log ( ` total number of times this component has been created: ${ totalComponents } ` ) ;

totalComponents += 1 ; console . log ( ` total number of times this component has been created: ${ totalComponents } ` ) ;

Variables defined in module scripts are not reactive — reassigning them will not trigger a rerender even though the variable itself will update. For values shared between multiple components, consider using a store .

You cannot export default , since the default export is the component itself.

You can export bindings from this block, and they will become exports of the compiled module.

A <script> tag with a context="module" attribute runs once when the module first evaluates, rather than for each component instance. Values declared in this block are accessible from a regular <script> (and the component markup) but not vice versa.

For interoperability with RxJS Observables, the .subscribe method is also allowed to return an object with an .unsubscribe method, rather than return the unsubscription function directly. Note however that unless .subscribe synchronously calls the subscription (which is not required by the Observable spec), Svelte will see the value of the store as undefined until it does.

You can create your own stores without relying on svelte/store , by implementing the store contract:

Local variables (that do not represent store values) must not have a $ prefix.

Note that the store must be declared at the top level of the component — not inside an if block or a function, for example.

Assignments to $ -prefixed variables require that the variable be a writable store, and will result in a call to the store's .set method.

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.

A store is an object that allows reactive access to a value via a simple store contract. The svelte/store module contains minimal store implementations which fulfil this contract.

If a statement consists entirely of an assignment to an undeclared variable, Svelte will inject a let declaration on your behalf.

export let title ; $ : document . title = title ; $ : { console . log ( ` multiple statements can be combined ` ) ; console . log ( ` the current title is ${ title } ` ) ; }

export let title ; $ : document . title = title ; $ : { console . log ( ` multiple statements can be combined ` ) ; console . log ( ` the current title is ${ title } ` ) ; }

Any top-level statement (i.e. not inside a block or a function) can be made reactive by prefixing it with the $: JS label syntax . Reactive statements run immediately before the component updates, whenever the values that they depend on have changed.

Because Svelte's reactivity is based on assignments, using array methods like .push() and .splice() won't automatically trigger updates. Options for getting around this can be found in the tutorial .

Update expressions ( count += 1 ) and property assignments ( obj.x = y ) have the same effect.

To change component state and trigger a re-render, just assign to a locally declared variable.

You can use reserved words as prop names.

export const thisIs = 'readonly' ; export function greet ( name ) { alert ( ` hello ${ name } ! ` ) ; } export let format = n => n . toFixed ( 2 ) ;

export const thisIs = 'readonly' ; export function greet ( name ) { alert ( ` hello ${ name } ! ` ) ; } export let format = n => n . toFixed ( 2 ) ;

If you export a const , class or function , it is readonly from outside the component. Function expressions are valid props, however.

In development mode (see the compiler options ), a warning will be printed if no default initial value is provided and the consumer does not specify a value. To squelch this warning, ensure that a default initial value is specified, even if it is undefined .

You can specify a default initial value for a prop. It will be used if the component's consumer doesn't specify the prop on the component (or if its initial value is undefined ) when instantiating the component. Note that whenever a prop is removed by the consumer, its value is set to undefined rather than the initial value.

Svelte uses the export keyword to mark a variable declaration as a property or prop, which means it becomes accessible to consumers of the component (see the section on attributes and props for more information).

A <script> block contains JavaScript that runs when a component instance is created. Variables declared (or imported) at the top level are 'visible' from the component's markup. There are four additional rules:

All three sections — script, styles and markup — are optional.

Components are the building blocks of Svelte applications. They are written into .svelte files, using a superset of HTML.

The <svelte:options> element provides a place to specify per-component compiler options, which are detailed in the compiler section . The possible options are:

This element makes it possible to insert elements into document.head . During server-side rendering, head content is exposed separately to the main html content.

As with <svelte:window> , this element allows you to add listeners to events on document.body , such as mouseenter and mouseleave which don't fire on window .

All except scrollX and scrollY are readonly.

You can also bind to the following properties:

The <svelte:window> element allows you to add event listeners to the window object without worrying about removing them when the component is destroyed, or checking for the existence of window when server-side rendering.

If this is falsy, no component is rendered.

The <svelte:component> element renders a component dynamically, using the component constructor specified as the this property. When the property changes, the component is destroyed and recreated.

It cannot appear at the top level of your markup; it must be inside an if or each block to prevent an infinite loop.

The <svelte:self> element allows a component to include itself, recursively.

Named slots can also expose values. The let: directive goes on the element with the slot attribute.

The usual shorthand rules apply — let:item is equivalent to let:item={item} , and <slot {item}> is equivalent to <slot item={item}> .

Slots can be rendered zero or more times, and can pass values back to the parent using props. The parent exposes the values to the slot template using the let: directive.

Named slots allow consumers to target specific areas. They can also have fallback content.

The content is exposed in the child component using the <slot> element, which can contain fallback content that is rendered if no children are provided.

Components can have child content, in the same way that elements can.

Note that we can't do {cart.empty} since cart is undefined when the button is first rendered and throws an error.

Components also support bind:this , allowing you to interact with component instances programmatically.

You can bind to component props using the same syntax as for elements.

As with DOM events, 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.

Components can emit events using createEventDispatcher , or by forwarding DOM events. Listening for component events looks the same as listening for DOM events:

import { cubicOut } from 'svelte/easing' ; function whizz ( node , { from , to } , params ) { const dx = from . left - to . left ; const dy = from . top - to . top ; const d = Math . sqrt ( dx * dx + dy * dy ) ; return { delay : 0 , duration : Math . sqrt ( d ) * 120 , easing : cubicOut , tick : ( t , u ) => Object . assign ( node . style , { color : t > 0.5 ? 'Pink' : 'Blue' } ) ; } ; }

import { cubicOut } from 'svelte/easing' ; function whizz ( node , { from , to } , params ) { const dx = from . left - to . left ; const dy = from . top - to . top ; const d = Math . sqrt ( dx * dx + dy * dy ) ; return { delay : 0 , duration : Math . sqrt ( d ) * 120 , easing : cubicOut , tick : ( t , u ) => Object . assign ( node . style , { color : t > 0.5 ? 'Pink' : 'Blue' } ) ; } ; }

If it's possible to use css instead of tick , do so — CSS animations can run off the main thread, preventing jank on slower devices.

A custom animation function can also return a tick function, which is called during the animation with the same t and u arguments.

import { cubicOut } from 'svelte/easing' ; function whizz ( node , { from , to } , params ) { const dx = from . left - to . left ; const dy = from . top - to . top ; const d = Math . sqrt ( dx * dx + dy * dy ) ; return { delay : 0 , duration : Math . sqrt ( d ) * 120 , easing : cubicOut , css : ( t , u ) => ` transform: translate( ${ u * dx } px, ${ u * dy } px) rotate( ${ t * 360 } deg); ` } ; }

import { cubicOut } from 'svelte/easing' ; function whizz ( node , { from , to } , params ) { const dx = from . left - to . left ; const dy = from . top - to . top ; const d = Math . sqrt ( dx * dx + dy * dy ) ; return { delay : 0 , duration : Math . sqrt ( d ) * 120 , easing : cubicOut , css : ( t , u ) => ` transform: translate( ${ u * dx } px, ${ u * dy } px) rotate( ${ t * 360 } deg); ` } ; }

The function is called repeatedly before the animation begins, with different t and u arguments.

The t argument passed to css is a value that goes from 0 and 1 after the easing function has been applied. The u argument is equal to 1 - t .

If the returned object has a css method, Svelte will create a CSS animation that plays on the element.

Animations can use custom functions that provide the node , an animation object and any paramaters as arguments. The animation parameter is an object containing from and to properties each containing a DOMRect describing the geometry of the element in its start and end positions. The from property is the DOMRect of the element in its starting position, the to property is the DOMRect of the element in its final position after the list has been reordered and the DOM updated.

(The double {{curlies}} aren't a special syntax; this is an object literal inside an expression tag.)

As with actions and transitions, animations can have parameters.

Animations can be used with Svelte's built-in animation functions or custom animation functions .

An animation is triggered when the contents of a keyed each block are re-ordered. Animations do not run when an element is removed, only when the each block's data is reordered. Animate directives must be on an element that is an immediate child of a keyed each block.

Unlike with transition: , transitions applied with in: and out: are not bidirectional — an in transition will continue to 'play' alongside the out transition, rather than reversing, if the block is outroed while the transition is in progress. If an out transition is aborted, transitions will restart from scratch.

Similar to transition: , but only applies to elements entering ( in: ) or leaving ( out: ) the DOM.

Local transitions only play when the block they belong to is created or destroyed, not when parent blocks are created or destroyed.

< p transition: fly=" { { y : 200 , duration : 2000 } } " on: introstart=" { ( ) => status = 'intro started' } " on: outrostart=" { ( ) => status = 'outro started' } " on: introend=" { ( ) => status = 'intro ended' } " on: outroend=" { ( ) => status = 'outro ended' } " >

An element with transitions will dispatch the following events in addition to any standard DOM events:

If a transition returns a function instead of a transition object, the function will be called in the next microtask. This allows multiple transitions to coordinate, making crossfade effects possible.

If it's possible to use css instead of tick , do so — CSS animations can run off the main thread, preventing jank on slower devices.

A custom transition function can also return a tick function, which is called during the transition with the same t and u arguments.

The function is called repeatedly before the transition begins, with different t and u arguments.

The t argument passed to css is a value between 0 and 1 after the easing function has been applied. In transitions run from 0 to 1 , out transitions run from 1 to 0 — in other words 1 is the element's natural state, as though no transition had been applied. The u argument is equal to 1 - t .

Transitions can use custom functions. If the returned object has a css function, Svelte will create a CSS animation that plays on the element.

(The double {{curlies}} aren't a special syntax; this is an object literal inside an expression tag.)

By default intro transitions will not play on first render. You can modify this behaviour by setting intro: true when you create a component .

The transition: directive indicates a bidirectional transition, which means it can be smoothly reversed while the transition is in progress.

When a block is transitioning out, all elements inside the block, including those that do not have their own transitions, are kept in the DOM until every transition in the block has completed.

A transition is triggered by an element entering or leaving the DOM as a result of a state change.

Don't worry about the fact that we're redeclaring the foo function for every component instance — Svelte will hoist any functions that don't depend on local state out of the component definition.

An action can have a parameter. If the returned value has an update method, it will be called whenever that parameter changes, immediately after Svelte has applied updates to the markup.

Actions are functions that are called when an element is created. They can return an object with a destroy method that is called after the element is unmounted:

A class: directive provides a shorter way of toggling a class on an element.

To get a reference to a DOM node, use bind:this .

Inputs that work together can use bind:group .

Block-level elements have 4 readonly bindings, measured using a technique similar to this one :

Media elements ( <audio> and <video> ) have their own set of bindings — six readonly ones...

When the value of an <option> matches its text content, the attribute can be omitted.

A <select> value binding corresponds to the value property on the selected <option> , which can be any value (not just strings, as is normally the case in the DOM).

On <input> elements with type="file" , you can use bind:files to get the FileList of selected files .

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 .

If the name matches the value, you can use a shorthand.

The simplest bindings reflect the value of a property, such as input.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.

It's possible to have multiple event listeners for the same event:

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.

The following modifiers are available:

Handlers can be declared inline with no performance penalty. As with attributes, directive values may be quoted for the sake of syntax highlighters.

Use the on: directive to listen to DOM events.

As well as attributes, elements can have directives, which control the element's behaviour in some way.

The {@debug} tag without any arguments will insert a debugger statement that gets triggered when any state changes, as opposed to the specified variables.

The {@debug ...} tag offers an alternative to console.log(...) . It logs the values of specific variables whenever they change, and pauses code execution if you have devtools open.

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.

The expression should be valid standalone HTML — {@html "<div>"}content{@html "</div>"} will not work, because </div> is not valid HTML.

In a text expression, characters like < and > are escaped; however, with HTML expressions, they're not.

If you don't care about the pending state, you can also omit the initial block.

The catch block can be omitted if you don't need to render anything when the promise rejects (or no error is possible).

Await blocks allow you to branch on the three possible states of a Promise — pending, fulfilled or rejected.

An each block can also have an {:else} clause, which is rendered if the list is empty.

You can freely use destructuring and rest patterns in each blocks.

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.

An each block can also specify an index, equivalent to the second argument in an array.map(...) callback:

You can use each blocks to iterate over any array or array-like value — that is, any object with a length property.

Iterating over lists of values can be done with an each block.

Additional conditions can be added with {:else if expression} , optionally ending in an {:else} clause.

Content that is conditionally rendered can be wrapped in an if block.

Comments beginning with svelte-ignore disable warnings for the next block of markup. Usually these are accessibility warnings; make sure that you're disabling them for a good reason.

The value attribute of an input element or its children option elements must not be set with spread attributes when using bind:group or bind:checked . Svelte needs to be able to see the element's value directly in the markup in these cases so that it can link it to the bound variable.

$$restProps contains only the props which are not declared with export . It can be used to pass down other unknown attributes to an element in a component. It shares the same optimisation problems as $$props , and is likewise not recommended.

$$props references all props that are passed to a component, including ones that are not declared with export . It is not generally recommended, as it is difficult for Svelte to optimise. But it can be useful in rare cases – for example, when you don't know at compile time what props might be passed to a component.

An element or component can have multiple spread attributes, interspersed with regular ones.

Spread attributes allow many attributes or properties to be passed to an element or component at once.

As with elements, name={name} can be replaced with the {name} shorthand.

By convention, values passed to components are referred to as properties or props rather than attributes, which are a feature of the DOM.

When the attribute name and value match ( name={name} ), they can be replaced with {name} .

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:

All other attributes are included unless their value is nullish ( null or undefined ).

Boolean attributes are included on the element if their value is truthy and excluded if it's falsy .

Or they can be JavaScript expressions.

As in HTML, values may be unquoted.

By default, attributes work exactly like their HTML counterparts.

A lowercase tag, like <div> , denotes a regular HTML element. A capitalised tag, such as <Widget> or <Namespace.Widget> , indicates a component.

Run time

svelte

The svelte package exposes lifecycle functions and the context API.

onMount

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. < script > import { onMount } from 'svelte' ; onMount ( ( ) => { console . log ( 'the component has mounted' ) ; } ) ; </ script >

If a function is returned from onMount , it will be called when the component is unmounted. < script > import { onMount } from 'svelte' ; onMount ( ( ) => { const interval = setInterval ( ( ) => { console . log ( 'beep' ) ; } , 1000 ) ; return ( ) => clearInterval ( interval ) ; } ) ; </ script >

This behaviour will only work when the function passed to onMount synchronously returns a value. async functions always return a Promise , and as such cannot synchronously return a function.

beforeUpdate

beforeUpdate ( callback : ( ) => void )

Schedules a callback to run immediately before the component is updated after any state change. The first time the callback runs will be before the initial onMount < script > import { beforeUpdate } from 'svelte' ; beforeUpdate ( ( ) => { console . log ( 'the component is about to update' ) ; } ) ; </ script >

afterUpdate

afterUpdate ( callback : ( ) => void )

Schedules a callback to run immediately after the component has been updated. < script > import { afterUpdate } from 'svelte' ; afterUpdate ( ( ) => { console . log ( 'the component just updated' ) ; } ) ; </ script >

onDestroy

onDestroy ( callback : ( ) => void )

Schedules a callback to run once the component is unmounted. Out of onMount , beforeUpdate , afterUpdate and onDestroy , this is the only one that runs inside a server-side component. < script > import { onDestroy } from 'svelte' ; onDestroy ( ( ) => { console . log ( 'the component is being destroyed' ) ; } ) ; </ script >

tick

promise : Promise = tick ( )

Returns a promise that resolves once any pending state changes have been applied, or in the next microtask if there are none. < script > import { beforeUpdate , tick } from 'svelte' ; beforeUpdate ( async ( ) => { console . log ( 'the component is about to update' ) ; await tick ( ) ; console . log ( 'the component just updated' ) ; } ) ; </ script >

setContext

setContext ( key : any , context : any )

Associates an arbitrary context object with the current component and the specified key . The context is then available to children of the component (including slotted content) with getContext . Like lifecycle functions, this must be called during component initialisation. < script > import { setContext } from 'svelte' ; setContext ( 'answer' , 42 ) ; </ script >

Context is not inherently reactive. If you need reactive values in context then you can pass a store into context, which will be reactive.

getContext

context : any = getContext ( key : any )

Retrieves the context that belongs to the closest parent component with the specified key . Must be called during component initialisation. < script > import { getContext } from 'svelte' ; const answer = getContext ( 'answer' ) ; </ script >

createEventDispatcher

dispatch : ( ( name : string , detail ? : any ) => void ) = createEventDispatcher ( ) ;

Creates an event dispatcher that can be used to dispatch component events. Event dispatchers are functions that can take two arguments: name and detail . Component events created with createEventDispatcher create a CustomEvent. These events do not bubble and are not cancellable with event.preventDefault() . The detail argument corresponds to the CustomEvent.detail property and can contain any type of data. < script > import { createEventDispatcher } from 'svelte' ; const dispatch = createEventDispatcher ( ) ; </ script > < button on: click=" { ( ) => dispatch ( 'notify' , 'detail value' ) } " > Fire Event </ button >

Events dispatched from child components can be listened to in their parent. Any data provided when the event was dispatched is available on the detail property of the event object. < script > function callbackFunction ( event ) { console . log ( ` Notify fired! Detail: ${ event . detail } ` ) } </ script > < Child on: notify=" { callbackFunction } " />

The svelte/store module exports functions for creating readable, writable and derived stores.

Keep in mind that you don't have to use these functions to enjoy the reactive $store syntax in your components. Any object that correctly implements .subscribe , unsubscribe, and (optionally) .set is a valid store, and will work both with the special syntax, and with Svelte's built-in derived stores.

This makes it possible to wrap almost any other reactive state handling library for use in Svelte. Read more about the store contract to see what a correct implementation looks like.

writable

store = writable ( value : any )

store = writable ( value : any , ( set : ( value : any ) => void ) => ( ) => void )

Function that creates a store which has values that can be set from 'outside' components. It gets created as an object with additional set and update methods. set is a method that takes one argument which is the value to be set. The store value gets set to the value of the argument if the store value is not already equal to it. update is a method that takes one argument which is a callback. The callback takes the existing store value as its argument and returns the new value to be set to the store. import { writable } from 'svelte/store' ; const count = writable ( 0 ) ; count . subscribe ( value => { console . log ( value ) ; } ) ; count . set ( 1 ) ; count . update ( n => n + 1 ) ;

If a function is passed as the second argument, it will be called when the number of subscribers goes from zero to one (but not from one to two, etc). That function will be passed a set function which changes the value of the store. It must return a stop function that is called when the subscriber count goes from one to zero. import { writable } from 'svelte/store' ; const count = writable ( 0 , ( ) => { console . log ( 'got a subscriber' ) ; return ( ) => console . log ( 'no more subscribers' ) ; } ) ; count . set ( 1 ) ; const unsubscribe = count . subscribe ( value => { console . log ( value ) ; } ) ; unsubscribe ( ) ;

readable

store = readable ( value : any , ( set : ( value : any ) => void ) => ( ) => void )

Creates a store whose value cannot be set from 'outside', the first argument is the store's initial value. The second argument to readable is the same as the second argument to writable , except that it is required with readable (since otherwise there would be no way to update the store value). import { readable } from 'svelte/store' ; const time = readable ( null , set => { set ( new Date ( ) ) ; const interval = setInterval ( ( ) => { set ( new Date ( ) ) ; } , 1000 ) ; return ( ) => clearInterval ( interval ) ; } ) ;

derived

store = derived ( a , callback : ( a : any ) => any )

store = derived ( a , callback : ( a : any , set : ( value : any ) => void ) => void | ( ) => void , initial_value : any )

store = derived ( [ a , ... b ] , callback : ( [ a : any , ... b : any [ ] ] ) => any )

store = derived ( [ a , ... b ] , callback : ( [ a : any , ... b : any [ ] ] , set : ( value : any ) => void ) => void | ( ) => void , initial_value : any )

Derives a store from one or more other stores. Whenever those dependencies change, the callback runs. In the simplest version, derived takes a single store, and the callback returns a derived value. import { derived } from 'svelte/store' ; const doubled = derived ( a , $a => $a * 2 ) ;

The callback can set a value asynchronously by accepting a second argument, set , and calling it when appropriate. In this case, you can also pass a third argument to derived — the initial value of the derived store before set is first called. import { derived } from 'svelte/store' ; const delayed = derived ( a , ( $a , set ) => { setTimeout ( ( ) => set ( $a ) , 1000 ) ; } , 'one moment...' ) ;

If you return a function from the callback, it will be called when a) the callback runs again, or b) the last subscriber unsubscribes. import { derived } from 'svelte/store' ; const tick = derived ( frequency , ( $frequency , set ) => { const interval = setInterval ( ( ) => { set ( Date . now ( ) ) ; } , 1000 / $frequency ) ; return ( ) => { clearInterval ( interval ) ; } ; } , 'one moment...' ) ;

In both cases, an array of arguments can be passed as the first argument instead of a single store. import { derived } from 'svelte/store' ; const summed = derived ( [ a , b ] , ( [ $a , $b ] ) => $a + $b ) ; const delayed = derived ( [ a , b ] , ( [ $a , $b ] , set ) => { setTimeout ( ( ) => set ( $a + $b ) , 1000 ) ; } ) ;

get

value : any = get ( store )

Generally, you should read the value of a store by subscribing to it and using the value as it changes over time. Occasionally, you may need to retrieve the value of a store to which you're not subscribed. get allows you to do so. This works by creating a subscription, reading the value, then unsubscribing. It's therefore not recommended in hot code paths. import { get } from 'svelte/store' ; const value = get ( store ) ;

The svelte/motion module exports two functions, tweened and spring , for creating writable stores whose values change over time after set and update , rather than immediately.

tweened

store = tweened ( value : any , options )

Tweened stores update their values over a fixed duration. The following options are available:

delay ( number , default 0) — milliseconds before starting

( , default 0) — milliseconds before starting duration ( number , default 400) — milliseconds the tween lasts

( , default 400) — milliseconds the tween lasts easing ( function , default t => t ) — an easing function

( , default ) — an easing function interpolate ( function ) — see below

store.set and store.update can accept a second options argument that will override the options passed in upon instantiation.

Both functions return a Promise that resolves when the tween completes. If the tween is interrupted, the promise will never resolve.

Out of the box, Svelte will interpolate between two numbers, two arrays or two objects (as long as the arrays and objects are the same 'shape', and their 'leaf' properties are also numbers). < script > import { tweened } from 'svelte/motion' ; import { cubicOut } from 'svelte/easing' ; const size = tweened ( 1 , { duration : 300 , easing : cubicOut } ) ; function handleClick ( ) { $size += 1 ; } </ script > < button on: click= { handleClick } style="transform: scale( { $size } ); transform-origin: 0 0" > embiggen </ button >

If the initial value is undefined or null , the first value change will take effect immediately. This is useful when you have tweened values that are based on props, and don't want any motion when the component first renders. const size = tweened ( undefined , { duration : 300 , easing : cubicOut } ) ; $ : $size = big ? 100 : 10 ;

The interpolate option allows you to tween between any arbitrary values. It must be an (a, b) => t => value function, where a is the starting value, b is the target value, t is a number between 0 and 1, and value is the result. For example, we can use the d3-interpolate package to smoothly interpolate between two colours. < script > import { interpolateLab } from 'd3-interpolate' ; import { tweened } from 'svelte/motion' ; const colors = [ 'rgb(255, 62, 0)' , 'rgb(64, 179, 255)' , 'rgb(103, 103, 120)' ] ; const color = tweened ( colors [ 0 ] , { duration : 800 , interpolate : interpolateLab } ) ; </ script > { #each colors as c } < button style="background-color: { c } ; color: white; border: none;" on: click=" { e => color . set ( c ) } " > { c } </ button > { /each } < h1 style="color: { $color } " > { $color } </ h1 >

spring

store = spring ( value : any , options )

A spring store gradually changes to its target value based on its stiffness and damping parameters. Whereas tweened stores change their values over a fixed duration, spring stores change over a duration that is determined by their existing velocity, allowing for more natural-seeming motion in many situations. The following options are available:

stiffness ( number , default 0.15 ) — a value between 0 and 1 where higher means a 'tighter' spring

( , default ) — a value between 0 and 1 where higher means a 'tighter' spring damping ( number , default 0.8 ) — a value between 0 and 1 where lower means a 'springier' spring

( , default ) — a value between 0 and 1 where lower means a 'springier' spring precision ( number , default 0.001 ) — determines the threshold at which the spring is considered to have 'settled', where lower means more precise

As with tweened stores, set and update return a Promise that resolves if the spring settles. The store.stiffness and store.damping properties can be changed while the spring is in motion, and will take immediate effect. Both set and update can take a second argument — an object with hard or soft properties. { hard: true } sets the target value immediately; { soft: n } preserves existing momentum for n seconds before settling. { soft: true } is equivalent to { soft: 0.5 } . See a full example on the spring tutorial. < script > import { spring } from 'svelte/motion' ; const coords = spring ( { x : 50 , y : 50 } , { stiffness : 0.1 , damping : 0.25 } ) ; </ script >

If the initial value is undefined or null , the first value change will take effect immediately, just as with tweened values (see above). const size = spring ( ) ; $ : $size = big ? 100 : 10 ;

The svelte/transition module exports seven functions: fade , blur , fly , slide , scale , draw and crossfade . They are for use with Svelte transitions .

fade

transition:fade= { params }

in:fade= { params }

out:fade= { params }

Animates the opacity of an element from 0 to the current opacity for in transitions and from the current opacity to 0 for out transitions. fade accepts the following parameters: delay ( number , default 0) — milliseconds before starting

( , default 0) — milliseconds before starting duration ( number , default 400) — milliseconds the transition lasts You can see the fade transition in action in the transition tutorial. < script > import { fade } from 'svelte/transition' ; </ script > { # if condition } < div transition: fade=" { { delay : 250 , duration : 300 } } " > fades in and out </ div > { / if }

blur

transition:blur= { params }

in:blur= { params }

out:blur= { params }

Animates a blur filter alongside an element's opacity. blur accepts the following parameters: delay ( number , default 0) — milliseconds before starting

( , default 0) — milliseconds before starting duration ( number , default 400) — milliseconds the transition lasts

( , default 400) — milliseconds the transition lasts easing ( function , default cubicInOut ) — an easing function

( , default ) — an easing function opacity ( number , default 0) - the opacity value to animate out to and in from

( , default 0) - the opacity value to animate out to and in from amount ( number , default 5) - the size of the blur in pixels < script > import { blur } from 'svelte/transition' ; </ script > { # if condition } < div transition: blur=" { { amount : 10 } } " > fades in and out </ div > { / if }

fly

transition:fly= { params }

in:fly= { params }

out:fly= { params }

Animates the x and y positions and the opacity of an element. in transitions animate from an element's current (default) values to the provided values, passed as parameters. out transitions animate from the provided values to an element's default values. fly accepts the following parameters: delay ( number , default 0) — milliseconds before starting

( , default 0) — milliseconds before starting duration ( number , default 400) — milliseconds the transition lasts

( , default 400) — milliseconds the transition lasts easing ( function , default cubicOut ) — an easing function

( , default ) — an easing function x ( number , default 0) - the x offset to animate out to and in from

( , default 0) - the x offset to animate out to and in from y ( number , default 0) - the y offset to animate out to and in from

( , default 0) - the y offset to animate out to and in from opacity ( number , default 0) - the opacity value to animate out to and in from You can see the fly transition in action in the transition tutorial. < script > import { fly } from 'svelte/transition' ; import { quintOut } from 'svelte/easing' ; </ script > { # if condition } < div transition: fly=" { { delay : 250 , duration : 300 , x : 100 , y : 500 , opacity : 0.5 , easing : quintOut } } " > flies in and out </ div > { / if }

slide

transition:slide= { params }

in:slide= { params }

out:slide= { params }

Slides an element in and out. slide accepts the following parameters: delay ( number , default 0) — milliseconds before starting

( , default 0) — milliseconds before starting duration ( number , default 400) — milliseconds the transition lasts

( , default 400) — milliseconds the transition lasts easing ( function , default cubicOut ) — an easing function < script > import { slide } from 'svelte/transition' ; import { quintOut } from 'svelte/easing' ; </ script > { # if condition } < div transition: slide=" { { delay : 250 , duration : 300 , easing : quintOut } } " > slides in and out </ div > { / if }

scale

transition:scale= { params }

in:scale= { params }

out:scale= { params }

Animates the opacity and scale of an element. in transitions animate from an element's current (default) values to the provided values, passed as parameters. out transitions animate from the provided values to an element's default values. scale accepts the following parameters: delay ( number , default 0) — milliseconds before starting

( , default 0) — milliseconds before starting duration ( number , default 400) — milliseconds the transition lasts

( , default 400) — milliseconds the transition lasts easing ( function , default cubicOut ) — an easing function

( , default ) — an easing function start ( number , default 0) - the scale value to animate out to and in from

( , default 0) - the scale value to animate out to and in from opacity ( number , default 0) - the opacity value to animate out to and in from < script > import { scale } from 'svelte/transition' ; import { quintOut } from 'svelte/easing' ; </ script > { # if condition } < div transition: scale=" { { duration : 500 , delay : 500 , opacity : 0.5 , start : 0.5 , easing : quintOut } } " > scales in and out </ div > { / if }

draw

transition:draw= { params }

in:draw= { params }

out:draw= { params }

Animates the stroke of an SVG element, like a snake in a tube. in transitions begin with the path invisible and draw the path to the screen over time. out transitions start in a visible state and gradually erase the path. draw only works with elements that have a getTotalLength method, like <path> and <polyline> . draw accepts the following parameters: delay ( number , default 0) — milliseconds before starting

( , default 0) — milliseconds before starting speed ( number , default undefined) - the speed of the animation, see below.

( , default undefined) - the speed of the animation, see below. duration ( number | function , default 800) — milliseconds the transition lasts

( | , default 800) — milliseconds the transition lasts easing ( function , default cubicInOut ) — an easing function The speed parameter is a means of setting the duration of the transition relative to the path's length. It is modifier that is applied to the length of the path: duration = length / speed . A path that is 1000 pixels with a speed of 1 will have a duration of 1000ms , setting the speed to 0.5 will double that duration and setting it to 2 will halve it. < script > import { draw } from 'svelte/transition' ; import { quintOut } from 'svelte/easing' ; </ script > < svg viewBox = " 0 0 5 5 " xmlns = " http://www.w3.org/2000/svg " > { # if condition } < path transition: draw=" { { duration : 5000 , delay : 500 , easing : quintOut } } " d = " M2 1 h1 v1 h1 v1 h-1 v1 h-1 v-1 h-1 v-1 h1 z " fill = " none " stroke = " cornflowerblue " stroke-width = " 0.1px " stroke-linejoin = " round " /> { / if } </ svg >

The svelte/animate module exports one function for use with Svelte animations.

flip

animate:flip= { params }

The flip function calculates the start and end position of an element and animates between them, translating the x and y values. flip stands for First, Last, Invert, Play.

flip accepts the following parameters:

delay ( number , default 0) — milliseconds before starting

( , default 0) — milliseconds before starting duration ( number | function , default d => Math.sqrt(d) * 120 ) — see below

( | , default ) — see below easing ( function , default cubicOut ) — an easing function

duration can be be provided as either:

a number , in milliseconds.

, in milliseconds. a function, distance: number => duration: number , receiving the distance the element will travel in pixels and returning the duration in milliseconds. This allows you to assign a duration that is relative to the distance travelled by each element.

You can see a full example on the animations tutorial < script > import { flip } from 'svelte/animate' ; import { quintOut } from 'svelte/easing' ; let list = [ 1 , 2 , 3 ] ; </ script > { #each list as n ( n ) } < div animate: flip=" { { delay : 250 , duration : 250 , easing : quintOut } } " > { n } </ div > { /each }

Easing functions specify the rate of change over time and are useful when working with Svelte's built-in transitions and animations as well as the tweened and spring utilities. svelte/easing contains 31 named exports, a linear ease and 3 variants of 10 different easing functions: in , out and inOut .

You can explore the various eases using the ease visualiser in the examples section.

ease in out inOut back backIn backOut backInOut bounce bounceIn bounceOut bounceInOut circ circIn circOut circInOut cubic cubicIn cubicOut cubicInOut elastic elasticIn elasticOut elasticInOut expo expoIn expoOut expoInOut quad quadIn quadOut quadInOut quart quartIn quartOut quartInOut quint quintIn quintOut quintInOut sine sineIn sineOut sineInOut

To render Svelte components in Node.js without bundling, use require('svelte/register') . After that, you can use require to include any .svelte file.

require ( 'svelte/register' ) ; const App = require ( './App.svelte' ) . default ; ... const { html , css , head } = App . render ( { answer : 42 } ) ;

The .default is necessary because we're converting from native JavaScript modules to the CommonJS modules recognised by Node. Note that if your component imports JavaScript modules, they will fail to load in Node and you will need to use a bundler instead.

To set compile options, or to use a custom file extension, call the register hook as a function:

require ( 'svelte/register' ) ( { extensions : [ '.customextension' ] , preserveComments : true } ) ;

Client-side component API

Creating a component

const component = new Component ( options )

A client-side component — that is, a component compiled with generate: 'dom' (or the generate option left unspecified) is a JavaScript class.

import App from './App.svelte' ; const app = new App ( { target : document . body , props : { 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 properties 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. Hydration of <head> elements only works properly if the server-side rendering code was also compiled with hydratable: true , which adds a marker to each element in the <head> so that the component knows which elements it's responsible for removing during hydration. 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. import App from './App.svelte' ; const app = new App ( { target : document . querySelector ( '#server-rendered-html' ) , hydrate : true } ) ;

component . $set ( props )

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. component . $set ( { answer : 42 } ) ;

component . $on ( event , callback )

Causes the callback function to be called whenever the component dispatches an event . A function is returned that will remove the event listener when called. const off = app . $on ( 'selected' , event => { console . log ( event . detail . selection ) ; } ) ; off ( ) ;

component . $destroy ( )

Removes a component from the DOM and triggers any onDestroy handlers.

Component props

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. console . log ( app . count ) ; app . count += 1 ;

Custom element API

Svelte components can also be compiled to custom elements (aka web components) using the customElement: true compiler option. You should specify a tag name for the component using the <svelte:options> element. < svelte: options tag = " my-element " /> < script > export let name = 'world' ; </ script > < h1 > Hello { name } ! </ h1 > < slot > </ slot >

Alternatively, use tag={null} to indicate that the consumer of the custom element should name it. import MyElement from './MyElement.svelte' ; customElements . define ( 'my-element' , MyElement ) ;

Once a custom element has been defined, it can be used as a regular DOM element: document . body . innerHTML = ` <my-element> <p>This is some slotted content</p> </my-element> ` ;

By default, custom elements are compiled with accessors: true , which means that any props are exposed as properties of the DOM element (as well as being readable/writable as attributes, where possible). To prevent this, add accessors={false} to <svelte:options> . const el = document . querySelector ( 'my-element' ) ; console . log ( el . name ) ; el . name = 'everybody' ;

Custom elements can be a useful way to package components for consumption in a non-Svelte app, as they will work with vanilla HTML and JavaScript as well as most frameworks. There are, however, some important differences to be aware of:

Styles are encapsulated, rather than merely scoped. This means that any non-component styles (such as you might have in a global.css file) will not apply to the custom element, including styles with the :global(...) modifier

file) will not apply to the custom element, including styles with the modifier Instead of being extracted out as a separate .css file, styles are inlined into the component as a JavaScript string

Custom elements are not generally suitable for server-side rendering, as the shadow DOM is invisible until JavaScript loads

In Svelte, slotted content renders lazily. In the DOM, it renders eagerly. In other words, it will always be created even if the component's <slot> element is inside an {#if ...} block. Similarly, including a <slot> in an {#each ...} block will not cause the slotted content to be rendered multiple times

element is inside an block. Similarly, including a in an block will not cause the slotted content to be rendered multiple times The let: directive has no effect

directive has no effect Polyfills are required to support older browsers

Server-side component API

const result = Component . render ( ... )