Create CSS Transitions When Switching Between Pages – swup

Category: Animation , Javascript , Recommended | July 1, 2022
Views Total:4 views
Official Page:Go to website
Last Update:July 1, 2022


Create CSS Transitions When Switching Between Pages – swup


The swup JavaScript library lets you apply custom CSS transitions to pages when switching between them. Supports preload, page cache, and event handlers.

See also:

Basic usage:

Install the swup library.

$ npm install swup --save

Import the swup library.

import Swup from 'swup'

Or directly load the swup file in the document.

<script src="./dist/swup.js"></script>
<!-- or from a CDN -->
<script src="[email protected]/dist/swup.min.js"></script>

Initialize the swup library and we’re ready to go.

const swup = new Swup()

Add the CSS ID ‘swup’ to the element you want to animate.

<main id="swup">
  Main content here

Add an animation class to the element.

<main id="swup" class="animation-class">
  Main content here

Apply your own transition effects to the page.

.animation-class {
  /* default animation rules */
} .animation-class {
  /* CSS styles when animating  */
} .animation-class {
  /* CSS styles when changing  */
} .animation-class {
  /* CSS styles when leaving  */
} .animation-class {
  /* CSS styles when rendering  */

All default config options.

const swup = new Swup({
      // when this option is enabled, swup disables browser native scroll control (sets scrollRestoration to manual) and takes over this task. 
      // This means that position of scroll on previous page(s) is not preserved (but can be implemented manually based on use case). 
      // Otherwise swup scrolls to top/#element on popstate as it does with normal browsing.
      animateHistoryBrowsing: false,
      // animation selector
      animationSelector: '[class*="transition-"]',
      // defines link elements that will trigger the transition
      linkSelector: 'a[href^="' + window.location.origin + '"]:not([data-no-swup]), a[href^="/"]:not([data-no-swup]), a[href^="#"]:not([data-no-swup])',
      // stores previously loaded contents of the pages in memory
      cache: true,
      // default container(s)
      containers: ['#swup'],
      // request headers
      requestHeaders: {
        'X-Requested-With': 'swup',
        Accept: 'text/html, application/xhtml+xml'
      // enable/disable plugins
      // see below
      plugins: [],
      // skips popState handling when using other tools manipulating the browser history
      skipPopStateHandling: function skipPopStateHandling(event) {
        return !(event.state && event.state.source === 'swup');


v2.0.16 (07/01/2022)

  • Improve handling of scroll anchors with special characters

v2.0.15 (06/15/2022)

  • Update dependencies

v2.0.14 (12/27/2020)

  • Bugfix

v2.0.13 (12/07/2020)

  • update patch version

v2.0.12 (11/30/2020)

  • fix bug where animateHistoryBrowsing option was ignored for OUT animations

v2.0.11 (07/09/2020)

  • update version

v2.0.9 (02/26/2020)

  • removed destroy of mouseover listener as it was moved to the preload plugin

v2.0.8 (11/01/2019)

  • fix problem when ‘<body’ string is present in DOM

v2.0.5 (07/15/2019)

  • updated

v2.0.4 (05/31/2019)

  • fix wrong uppercase/lowercase letters in imports

v2.0.2 (05/27/2019)

  • major update

v1.9.0 (01/07/2019)

  • make preloadPage method return Promise

v1.7.18 (01/07/2018)

  • fix querySelectorAll issue in form handler and destroy method

v1.7.17 (12/17/2018)

  • fix swup getting stuck by errors inside of handlers defined with on method

You Might Be Interested In:

2 thoughts on “Create CSS Transitions When Switching Between Pages – swup

Leave a Reply