@288-toolkit/animations v4.1.1
Animations
npm i @288-toolkit/animations
A collection of functions and actions to animate elements.
createAnimationArchitect()
An architect allows you to register animation functions that will get played when transitioning out
from a page, which is useful to coordinate multiple outro animations. The architect instance has to
be initialized with the provided start
function in order to work, which is a wrapper around
registerTransition
.
The animations will not be played if the user has reduced motion.
Options
outDuration
The outro duration in ms that the animations must be played for. Default: 400
.
Returns
start
A wrapper around registerTransition
that initializes the architect. This function MUST be called
at component initialization. It accepts the same arguments and returns the $transitioning
store
for the registered transition.
registerAnimation
The function to register your outro animation. The outro animation is simply a function that
receives the duration
in seconds and durationMs
in milliseconds, which is the outDuration
passed to the architect.
Example
const architect = createAnimationArchitect({ outDuration: 350 });
<script lang="ts">
import { architect } from '$lib/animations/defaultArchitect';
architect.start('default');
</script>
<script lang="ts">
import {onMount} from 'svelte';
let myEl: HTMLElement
onMount(() => {
architect.registerAnimation(({ durationMs }) => {
// ... animate myEl before navigating away from the page
})
})
</script>
createMotionArchitect
A wrapper around createAnimationArchitect
to handle Motion animations.
It accepts the same arguments and An architect instance extended with registerMotionAnimation
.
This function takes the animation controls returned from animate
or timline
and automatically
reverses the animation when transitioning out.
<script lang="ts">
onMount(() => {
architect.registerMotionAnimation(
animate(
myEl,
{
opacity: [0, 1]
},
{ duration: 0.3 }
)
);
});
</script>
use:playMotionAnimationInView
Plays a Motion animation when the element comes into view, using
Motion's inView
function. Registers it with an optional
architect (see createMotionArchitect
) so that if the element is in view when a navigation occurs,
the animation will be reversed (which can be turned off with reverse: false
). Make sure that the
animation is set to autoplay: false
, otherwise it will play immediately, potentially before the
element is in view.
The animation will be skipped to its final state if the user has reduced motion.
Options
animation
The animation to play, returned from either animate
or timeline
from Motion.
animation: AnimationControls;
architect
The architect to register the animation with. If provided, the animation will be unregistered when the element is out of view and reversed if the element is in view when a navigation occurs.
architect?: ReturnType<typeof createMotionArchitect>;
reverse
Whether to reverse the animation when the element is out of view. DEFAULT: true
.
reverse?: boolean;
inViewOptions
The options to pass to the inView
function.
inViewOptions?: InViewOptions;
Example
<div
use:playMotionAnimationInView={{
animation: animate(el, {
/*...*/
}),
reverse: false,
inViewOptions: {
amount: 0.8
}
}}
></div>
use:animateInView
Wraps playMotionAnimationInView
and:
- Makes sure that the
animation
hasautoplay: false
- Provides a nice API to select multiple elements within the node.
- Allows disabling the animation.
Options
animateInView
has the same options as playMotionAnimationInView
except animation
, as well as
the following.
keyframes
The keyframes of the animation.
keyframes: MotionKeyframesDefinition;
options
The animation options.
options?: AnimationOptionsWithOverrides;
selector
A CSS selector find elements within the node to animate. If omitted, the node itself will be animated.
selector?: string;
disabled
Disables the animation. DEFAULT: false.
disabled?: boolean;
Example
<ul
use:playMotionAnimationInView={{
keyframes: {
transform: ['translateY(4rem)', 'none'],
opacity: [0, 1]
},
options: {
transform: {
easing: expoOut,
duration: 0.7
},
opacity: {
easing: 'linear',
duration: 0.2
},
delay: stagger(0.1)
},
selector: 'li',
inViewOptions: {
amount: 0.4
}
}}
>
{#each items as item}
<li>{item}</li>
{/each}
</ul>
use:slide
An action to animate the height of an element.It uses tweened
store to animate the element, which
you can configure.
!NOTE Why not use slide
from svelte/transition
? It's still a very good choice, but svelte
transitions require the elements to be mounted/unmounted from the DOM to be animated. Sometimes you
might want to keep the elements in the DOM, for example to get a better SEO score for the page. In
that case, the slide
action is prefered.
Options
open
Determines if the element is collapsed or not.
open: boolean;
options
The options of the tweened
store, so you can adjust the duration, easing, etc. The duration
will
be overriden to 0 if the user has reduced motion.
options: Parameters < typeof tweened < number >> [1];
closedHeight
The height of the element when open
is false.
closedHeight: number;
Example
<div
use:slide={{ open: $open, options: { duration: 700, easing: expoOut }, closedHeight: 50 }}
></div>
use:parallax
Creates a parallax effect on an element using Motion. The parallax will be re-initialized when the options change, so you can update them dynamically to match certain conditions, like mobile and desktop options.
Options
speed
Speed of the animation. Negative values invert the direction. 0 disables the animation. DEFAULT: 0.2.
speed?: number;
easing
Easing of the animation. DEFAULT: 'linear'.
easing?: Easing;
keyframes
Extra keyframes to add more animation effects.
keyframes?: MotionKeyframesDefinition;
Example
<script lang="ts">
import { createMatchMediaStore } from '@288-toolkit/device/media';
const isDesktop = createMatchMediaStore('(min-width: 1200px)');
</script>
<div
use:parallax={{
speed: $isDesktop ? 0.4 : 0.2
}}
></div>
use:parallaxFade
Adds a fade animation to the basic parallax.
Options
from
Opacity at the start of the animation. DEFAULT: 0.
from?: number;
to
Opacity at the end of the animation. DEFAULT: 1.
to?: number;
speed
Speed of the animation. Negative values invert the direction. 0 disables the animation. DEFAULT: 0.2.
speed?: number;
easing
Easing of the animation. DEFAULT: 'linear'.
easing?: Easing;
use:parallaxScale
Adds a scale animation to the basic parallax. The element has a scale of 1 at the middle of the animation.
Options
from
Scale at the start of the animation. DEFAULT: 0.5.
from?: number;
to
Scale at the end of the animation. DEFAULT: 0.5.
to?: number;
speed
Speed of the animation. Negative values invert the direction. 0 disables the animation. DEFAULT: 0.2.
speed?: number;
easing
Easing of the animation. DEFAULT: 'linear'.
easing?: Easing;
augmentedParallax()
A convenience function to augment the basic parallax
action with more animation effects.
See parallaxFade
and parallaxScale
for
examples.