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.
Containers
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
menus.
Automatic animation timing
Swup is built around CSS animations. It will wait for any
transitions and
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: transition-[name], where 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.
Animation classes
Swup applies classes to the html element to control the page transition process:
| Class name | Description |
|---|---|
is-changing |
Added before starting the animation. Removed after the whole animation process. Used for showing the loading state. |
is-animating |
Added before starting the animation. Removed after the content is replaced. Used for defining styles of unloaded pages. |
is-leaving |
Added before starting the animation. Removed right before the content is replaced. Used to identify the leave phase of the animation. Combine with is-animating to create differing leave and enter animations. |
is-rendering |
Added right before the content is replaced. Removed after the whole animation process. Used to identify the enter phase of the animation. Combine with is-animating to create differing leave and enter animations. |
to-[animation-name] |
Added for links with a [data-swup-animation=""] attribute to change the animation for a specific visit. |
You can configure swup to add animation classes to the containers instead of the html element.
Other animation methods
Use the official JS Plugin to perform animations yourself in JS or with a popular animation library like GSAP.
Browser history
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.
Scroll behavior
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.
Hooks
To trigger custom logic or modify swup's behavior, you can register hook handlers.
Plugins
Swup was designed to be small but modular. Any extended functionality can be added via one of the many official or third-party plugins.