Make your site feel like a snappy single-page app — without any of the complexity.
Enable smooth page transitions, smart preloading and more with this Astro integration for swup.
Swup is a versatile and extensible page transition library for multi-page apps. It manages the complete page load lifecycle and smoothly animates between the current and next page. In addition, it offers many other quality-of-life improvements like caching, smart preloading, native browser history and enhanced accessibility.
Learn more about swup in the official docs.
First, install the @swup/astro package using your package manager.
npm install @swup/astroThen, apply the integration to your astro.config.* file using the integrations property:
import { defineConfig } from 'astro/config';
import swup from '@swup/astro';
export default defineConfig({
integrations: [swup()]
});Once the integration is installed, swup will handle and animate page visits. The necessary script is automatically added on every page of your website. Try navigating between different pages via links — you should no longer see browser refreshes and find page requests passing through swup under the Network tab in your browser dev tools.
The next step: fine-tune your setup by reading up on available configuration flags.
If you're using semantic markup and your main content area is wrapped in a main tag, swup will
work without modifications to your site. Should you wish to replace other content containers instead
of or in addition to that, edit the containers options.
This integration enables swup's 'fade' theme for animated page transitions out of the box.
If you want to write your own animation styles, disable the theme option. You then need to add an animation class to your animated elements and write the animation styles in CSS. See below for an example fade animation. Refer to the swup docs for a full example setup.
export default defineConfig({
integrations: [
swup({ theme: false })
]
});<main class="transition-fade">
<h1>Welcome</h1>
</main>html.is-changing .transition-fade {
transition: 0.4s;
opacity: 1;
}
html.is-animating .transition-fade {
opacity: 0;
}If you don't need animated page transitions and just want to use swup for its preloading and caching
features, that's fine too! In that case, disable the theme option and pass in a
boolean false for the animationClass option as well.
export default defineConfig({
integrations: [
swup({ theme: false, animationClass: false })
]
});The integration has its own options for enabling and fine-tuning swup features. Change these in the
astro.config.* file which is where your project’s integration settings live. These are the defaults:
import { defineConfig } from 'astro/config';
import swup from '@swup/astro';
export default defineConfig({
integrations: [
swup({
theme: 'fade',
animationClass: 'transition-',
containers: ['main'],
cache: true,
preload: true,
accessibility: true,
forms: false,
morph: false,
parallel: false,
progress: false,
routes: false,
smoothScrolling: true,
updateBodyClass: false,
updateHead: true,
reloadScripts: true,
debug: false,
loadOnIdle: true,
globalInstance: false,
})
]
});Use one of swup's predefined themes to get started with animated page transitions.
Set to false if you want to define your own animation styles.
{
theme: 'fade' | 'slide' | 'overlay' | false
}Pass in an array with the theme name and an object to override specific theme options:
{
theme: ['overlay', { direction: 'to-right' }]
}If you're not using one of the provided themes, you will need this class for defining your own animation styles.
The class prefix for detecting animation timing. Swup will wait for all CSS transitions and
keyframe animations to finish on these elements before swapping in the content of the new page.
The default option will select all elements with class names beginning in transition-.
{
animationClass: 'transition-'
}The content containers to be replaced on page visits. Usually the <main> element with the content
of the page, but can include any other elements that are present across all pages.
Defaults to the first main tag of the page.
Note: Only elements inside of the body tag are supported.
{
containers: ['#content', '#nav']
}The built-in cache keeps previously loaded pages in memory. This improves speed but can be disabled for highly dynamic sites that need up-to-date responses on each request.
{
cache: false
}Smart preloading, enabled by default. Pass in an object to enable or disable preloading features:
{
preload: {
hover: true,
visible: false
}
}Swup will preload links when they are hovered with a mouse, touched with a finger, or focused using the keyboard. Enabled by default.
Preload links as they enter the viewport. Not enabled by default, but recommended for a performance boost to static sites.
In addition to preloading links when interacting with them, you can mark links for preloading
manually by applying a data-swup-preload attribute on the link, or a data-swup-preload-all on a
common parent:
<!-- preload a single link -->
<a href="/about" data-swup-preload>About</a>
<!-- preload all links in a container -->
<nav data-swup-preload-all>
<a href="/about">About</a>
<a href="/contact">Contact</a>
</nav>Enhance accessibility for screen readers by announcing page visits and focussing the newly updated content after page visits.
{
accessibility: true
}If you want swup to handle form submissions as well, enable this option. Note: swup handles reasonable scenarios like search or contact forms. For complex requirements like file uploads or custom serialization, it is recommended to use the swup API directly.
{
forms: true
}Form submissions trigger normal swup navigations: they will animate and replace the content
containers as on other visits. If you'd rather submit the form inline and only animate and
update the form itself, add a data-swup-inline-form attribute and a unique id to the form:
<form id="contact-form" class="transition-form" data-swup-inline-form>The animation classes are then only added to the form itself:
.transition-form.is-changing {
transition: opacity 200ms;
}
.transition-form.is-animating {
opacity: 0;
}To disable swup for specific forms, add a data-no-swup attribute on the form element:
<form action="/" data-no-swup>Morph certain containers into the new page without replacing them entirely. Uses morphdom to only update the attributes, classnames and text content of elements that have changed, instead of replacing the whole container. This keeps any existing state such as event handlers and scroll positions.
The prime use cases are headers and menus on multi-language sites: you might not want to swap these elements out with a transition on each page visit, however you'd still want to update any URLs, labels or classnames when the user switches between languages, without losing event handlers.
{
morph: ['#nav', '#sidebar']
}Swup page transitions usually work in series: hide the current page, update the content, show the new page. If you want to combine the leave/enter animations and keep the previous content visible during the animation, enable this option. Doing so will allow synchronous animations like overlays, crossfades, or slideshows.
For details on the lifecycle and styling of parallel animations, check out the readme of swup's Parallel Plugin.
{
parallel: true
}This will run all animations for all containers in parallel. If you only want to animate certain containers in parallel, pass an array of container selectors:
{
containers: ['nav', 'main']
parallel: ['main']
}Display a progress bar for all requests taking longer than ~300ms.
{
progress: true
}The progress bar has a class name of swup-progress-bar you can use for styling.
.swup-progress-bar {
height: 4px;
background-color: blue;
}Use path and route names to allow choosing between animations. Given a list of URL patterns,
uses path-to-regexp to identify named routes and
adds them as classnames to use for styling animations, e.g. from-route-home or to-route-project.
{
routes: [
{ name: 'home', path: '/:lang?' },
{ name: 'projects', path: '/:lang/projects' },
{ name: 'project', path: '/:lang/project/:slug' }
]
}Navigating from /en/ to /en/project/some-project/ will add these classes:
<html class="is-animating from-route-home to-route-project">Enable acceleration-based smooth scrolling, animated scroll positions between page visits and for anchor jump links.
{
smoothScrolling: true
}Update the body class after each page visit. Useful if you use classes on the body element for styling site sections.
{
updateBodyClass: true
}Update the contents of the head tag after each page visit. Useful if you have differing
stylesheets per section of your site.
{
updateHead: true
}Re-run any script tags inside the head and body on every page view. Helpful as a last resort
for sites with limited control over the included scripts. Beware: Running scripts without destroying
previous ones can cause memory leaks and potentially break your page.
{
reloadScripts: true
}Add debug output by swup and its plugins to the browser console. Useful during development.
{
debug: true
}Swup is a progressive enhancement and doesn't need to be loaded immediately. By default, this
integration will only initialize swup when the browser is idle, after the document has finished
loading. This improves first-load performance of the site. If for whatever reason you need to
initialize swup immediately on load, set this option to false.
{
loadOnIdle: true
}Store the initialized swup instance in window.swup. Useful if you need to add custom hooks or
plugins.
{
globalInstance: true
}For more advanced usage like registering hook handlers or installing custom plugins, you need access
to the swup instance itself. Enable the globalInstance option to have the swup instance available
at window.swup. You can then use swup's API directly.
export default defineConfig({
integrations: [
swup({ globalInstance: true })
]
});<script>
window.swup.use(new MyCustomSwupPlugin())
window.swup.hooks.on('page:view', () => {})
</script>Note: The global instance might not be available immediately since swup is loaded when the
browser is idle. In that case, you can listen for the enable event on the document.
<script>
const setup = () => {
window.swup.use(new MyCustomSwupPlugin())
window.swup.hooks.on('page:view', () => {})
}
if (window.swup) {
setup()
} else {
document.addEventListener('swup:enable', setup)
}
</script>If you need more granularity during the initilization process itself, consider following the manual swup setup instead. As a minimal requirement, you should install the head plugin and the scripts plugin so that client-side components are hydrated correctly.
<!-- Layout.astro or another global file -->
<script>
import Swup from 'swup';
import SwupHeadPlugin from '@swup/head-plugin';
import SwupScriptsPlugin from '@swup/scripts-plugin';
const swup = new Swup({
plugins: [
new SwupHeadPlugin(),
new SwupScriptsPlugin()
]
});
</script>Having trouble implementing swup? Check out the official docs, look at past issues or create a new discussion.
You can also check the Astro Integration Documentation for more on integrations.
This package is maintained by the swup core team. You're welcome to submit an issue or PR.
See Changelog for a history of changes to this integration.
