Create CSS Transitions When Switching Between Pages – swup

Preview:

Description:

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:

• CSS3 Based Page Transitions – Animate Transition
• Smooth Page Transitions With JavaScript And PJAX – barba.js

Basic usage:

Install the swup library.

# NPM
$ 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="https://unpkg.com/[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
</main>

Add an animation class to the element.

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

Apply your own transition effects to the page.

.animation-class {
  /* default animation rules */
}
html.is-animating .animation-class {
  /* CSS styles when animating  */
}
html.is-changing .animation-class {
  /* CSS styles when changing  */
}
html.is-leaving .animation-class {
  /* CSS styles when leaving  */
}
html.is-rendering .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');
      }
})

Changelog:

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