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]"></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');
      },
      // allows ignoring specific visits through a callback
      ignoreVisit: (href, { el } = {}) => el?.closest('[data-no-swup]'),
      // provides a way of rewriting URLs before swup will attempt to load them
      resolveUrl: (url) => {
        if (url.startsWith('/projects/?')) {
          return '/projects/';
        }
        return url;
      }
})

Events.

swup.on('animationInDone', () => {
  //  do something
});
swup.on('animationInStart', () => {
  //  do something
});
swup.on('animationOutDone', () => {
  //  do something
});
swup.on('animationOutStart', () => {
  //  do something
});
swup.on('animationSkipped', () => {
  //  do something
});
swup.on('clickLink', () => {
  //  do something
});
swup.on('contentReplaced', () => {
  //  do something
});
swup.on('disabled', () => {
  //  do something
});
swup.on('enabled', () => {
  //  do something
});
swup.on('hoverLink', () => {
  //  do something
});
swup.on('openPageInNewTab', () => {
  //  do something
});
swup.on('pageLoaded', () => {
  //  do something
});
swup.on('pagePreloaded', () => {
  //  do something
});
swup.on('pageRetrievedFromCache', () => {
  //  do something
});
swup.on('pageView', () => {
  //  do something
});
swup.on('popState', () => {
  //  do something
});
swup.on('pageLoaded', () => {
  //  do something
});
swup.on('samePage', () => {
  //  do something
});
swup.on('samePageWithHash', () => {
  //  do something
});
swup.on('transitionStart', () => {
  //  do something
});
swup.on('transitionEnd', () => {
  //  do something
});
swup.on('willReplaceContent', () => {
  //  do something
});

Changelog:

v3.0.4 (01/30/2023)

• Specify exact types for each type of event handler
• Update package version

v3.0.3 (01/27/2023)

• Use shared browserslist config

v3.0.2 (01/21/2023)

• Make sure ignoreVisit option is called when visiting pages programmatically

v3.0.1 (01/20/2023)

• Fix: remove origin from ignoreVisit parameter

v3.0.0 (01/19/2023)

• Support CSS animations and keyframes
• Allow ignoring visits via callback function
• Export native ESM modules
• Smaller bundle size for modern browsers: 4.5 kB

v2.0.19 (08/24/2022)

• Disable caching of initial page to avoid caching modified DOM
• Gracefully handle missing document title
• Force-reload if next page has no swup containers
• Remove all reliance on global window.swup instance

v2.0.18 (08/10/2022)

• Fixes the buggy behavior when navigating rapidly between pages

v2.0.17 (08/02/2022)

• Gracefully handle missing transitions on container
• Warn about missing container
• Scope transition selector to body
• Normalize cache paths

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