Repository files navigation

Aswup plugin for managing animations in JS.

• Use JavaScript for timing animations instead of CSS
• Successor to the deprecatedswupjs library

Install the plugin from npm and import it into your bundle.

npm install @swup/js-plugin

importSwupJsPluginfrom'@swup/js-plugin';

Or include the minified production file from a CDN:

<scriptsrc="https://unpkg.com/@swup/js-plugin@3"></script>

To run this plugin, include an instance in the swup options.

constswup=newSwup({plugins:[newSwupJsPlugin({animations:[/* your custom animation functions */]})]});

The plugin expects anarray of animation objects.The example below is the default setup and defines two animations, whereout is theanimation function being executed before the content is being replaced, andin isthe animation being executed after the content is replaced:

{animations:[{from:'(.*)',// matches any routeto:'(.*)',// matches any routeout:done=>done(),// immediately continuesin:done=>done()// immediately continues}]}

This is also the fallback animation in case no other matching animations were found.

Animations are chosen based on thefrom andto properties of the object, which arecompared against the current visit (urls of current and next page).Learn more onchoosing the animation below.

The animation function is executed for each corresponding animation phase. Inside the animationfunction, you manage the animation yourself and signal when it has finished. It receives twoarguments: adone function and adata object.

out:(done,data)=>{// Signal the end of the animation by calling done()// Access info about the animation inside the data argument}

Calling thedone() function signals to swup that the animation has finished and it can proceedto the next step: replacing the content or finishing the visit. You can pass along thedone()function as a callback to your animation library. The example below will wait for two seconds before replacing the content.

out:(done)=>{setTimeout(done,2000);}

If your animation library returns Promises, you can also return the Promise directly from youranimation function. Swup will consider the animation to be finished when the Promise resolves.Thedone function is then no longer required.

out:()=>{returnmyAnimationLibrary.animate(/* */).then(()=>{});}

This also allowsasync/await syntax for convenience.

out:async()=>{awaitmyAnimationLibrary.animate(/* */);}

The second parameter is an object that contains useful data about the animation, such as the visitobject (containing actual before/after routes), thefrom andto parameters of theanimation object, and the route params.

{visit:{/* */},// swup global visit objectdirection:'in',from:{url:'/',pattern:'(.*)',params:{}},to:{url:'/about',pattern:'(.*)',params:{}}}

Basic usage examples for a fade transition implemented in popular animation libraries:

{from:'(.*)',to:'(.*)',in:async()=>{constcontainer=document.querySelector('#swup');awaitcontainer.animate([{opacity:0},{opacity:1}],250).finished;},out:async()=>{constcontainer=document.querySelector('#swup');awaitcontainer.animate([{opacity:1},{opacity:0}],250).finished;}}

{from:'(.*)',to:'(.*)',out:async()=>{awaitgsap.to('#swup',{opacity:0,duration:0.25});},in:async()=>{awaitgsap.fromTo('#swup',{opacity:0},{opacity:1,duration:0.25});}}

{from:'(.*)',to:'(.*)',out:async()=>{awaitanime({targets:'#swup',opacity:0,duration:250,easing:'linear'}).finished;},in:async()=>{awaitanime({targets:'#swup',opacity:[0,1],duration:250,easing:'linear'}).finished;}}

As mentioned above, the animation is chosen based on thefrom andto properties of the animation object.Those properties can take several forms:

• a string (matching a route exactly)
• a regular expression
• A route pattern like/foo/:bar) parsed bypath-to-regexp
• a custom animation name taken from thedata-swup-animation attribute of the clicked link

The most fitting route is always chosen.Keep in mind, that two routes can be evaluated as "same fit".In this case, the first one defined in the options is used, so usually you would like to define the more specific routes first.See the example below for more info.

[// animation 1{from:'/',to:'custom'},// animation 2{from:'/',to:'/post'},// animation 3{from:'/',to:'/post/:id'},// animation 4{from:'/',to:/pos(.*)/},// animation 5{from:'(.*)',to:'(.*)'},];

• from/ to/post → animation2
• from/ to/posting → animation4
• from/ to/post/12 → animation3
• from/ to/some-route → animation5
• from/ to/post withdata-swup-animation="custom" → animation1