How It Works
Instead of letting the browser load the next page, swup intercepts link clicks, loads the new page in the background and smoothly animates between the old and new content.
Read on to learn about key concepts of swup.
Swup will not replace the whole body on each page load. Instead, it will only replace the actual
content containers on your page. By default, swup will only replace a
container with the id
#swup but you can configure additional containers like headers or navigation
Swup is built around CSS animations. It will wait for any
animations to finish before replacing
page content. To identify animations to wait for, swup will look for a special type of class added
to content containers:
name is an arbitrary name you can assign
to allow styling different types of animations. This animation selector
can be freely configured.
It is recommended to only add this class to a single element per page. All other elements can be animated independently to allow easier debugging of animations.
Swup applies classes to the
html element to control the page transition process:
||Added before starting the animation. Removed after the whole animation process. Used for showing the loading state.|
||Added before starting the animation. Removed after the content is replaced. Used for defining styles of unloaded pages.|
||Added before starting the animation. Removed right before the content is replaced. Used to identify the leave phase of the animation. Combine with
||Added right before the content is replaced. Removed after the whole animation process. Used to identify the enter phase of the animation. Combine with
||Added for links with a
You can configure swup to add animation classes to the containers instead of the html element.
Use the official JS Plugin to perform animations yourself in JS or with a popular animation library like GSAP.
Swup will update and push to the browser history API. The current URL in the browser always reflects the actual URL of the last requested page. Forward/backward visits will continue to work as expected. On history visits, the scroll position will be restored as well.
Swup emulates native browser behavior for scrolling. Between page visits, the scroll position will be reset to the top. Clicking on an anchor link to the same page will jump to that anchor.
To trigger custom logic or modify swup's behavior, you can register hook handlers.
Swup was designed to be small but modular. Any extended functionality can be added via one of the many official or third-party plugins.