Route Name Plugin
Use named routes to allow choosing between swup animations.
Given a list of URL patterns, this plugin will use
path-to-regexp to identify
the previous and current routes and add additional classnames to allow switching
CSS animations based on the route name, e.g.: from-route-home
and
to-route-project
.
Installation
This plugin can be installed with npm
npm install @swup/route-name-plugin
and included with import
import SwupRouteNamePlugin from '@swup/route-name-plugin';
or included from the dist folder
<script src="./dist/SwupRouteNamePlugin.js"></script>
Usage
To run this plugin, include an instance in the swup options.
const swup = new Swup({
plugins: [
new SwupRouteNamePlugin({
routes: [
{ name: 'home', path: '/:lang?' },
{ name: 'projects', path: '/:lang/projects' },
{ name: 'project', path: '/:lang/project/:slug' },
{ name: 'any', path: '(.*)' }
]
})
]
});
Classes
The plugin will add from-route-*
and to-route-*
classes to the html
tag.
<html class="is-animating from-route-home to-route-project">
You can then choose between animations based on the identified routes.
.transition-default {
transition: 300ms opacity ease-in-out, 300ms transform ease-in-out;
opacity: 1;
transform: none;
}
/* Standard transition: fade */
html.is-animating .transition-default {
opacity: 0;
}
/* Transition from homepage: transform instead of fade */
html.is-animating.from-route-home .transition-default {
opacity: 1;
transform: translateX(100%);
}
If from and to routes are identical, it will add the class to-same-route
. This
is mostly useful to disable transitions between pages with identical layout.
<html class="is-animating from-route-project to-route-project to-same-route">
Options
All options with their default values:
{
routes: [{ name: 'any', path: '(.*)' }],
unknownName: 'unknown',
pathToRegexpOptions: {}
}
routes
Array of patterns for identifying named routes. Both name
and path
are
required.
The path
needs to be a valid route pattern that
path-to-regexp will understand.
Order matters: the first found route name is used.
unknownName
Default route name if no match was found among available patterns.
pathToRegexpOptions
Options passed to path-to-regexp for matching. Useful if you want to change case sensitivity, delimiters, etc.