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
permalink
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 startingduration
(number
|function
, default 400) — milliseconds the tween lastseasing
(function
, defaultt => t
) — an easing functioninterpolate
(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() {
// this is equivalent to size.update(n => n + 1)
$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
permalink
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
, default0.15
) — a value between 0 and 1 where higher means a 'tighter' springdamping
(number
, default0.8
) — a value between 0 and 1 where lower means a 'springier' springprecision
(number
, default0.01
) — determines the threshold at which the spring is considered to have 'settled', where lower means more precise
All of the options above can be changed while the spring is in motion, and will take immediate effect.
const size = spring(100);
size.stiffness = 0.3;
size.damping = 0.4;
size.precision = 0.005;
As with tweened
stores, set
and update
return a Promise that resolves if the spring settles.
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 }
.
const coords = spring({ x: 50, y: 50 });
// updates the value immediately
coords.set({ x: 100, y: 200 }, { hard: true });
// preserves existing momentum for 1s
coords.update(
(target_coords, coords) => {
return { x: target_coords.x, y: coords.y };
},
{ soft: 1 }
);
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;