Flexible and Easy to Use Page-Transition Library

Swup is a library that helps you add page transitions to server-side websites. It handles the entire lifecycle of a page visit by intercepting link clicks, loading the new page in the background, replacing content, and transitioning between the old page and the new page.

Its goal is to make adding transitions to a site as simple as possible while providing plenty of other quality-of-life improvements.

Features

✨ Auto-detects CSS transitions for perfect timing
🔗 Updates URLs and preserves native browser history behavior
📦 Uses a cache to speed up subsequent page loads
💡 Offers events for hooking into the lifecycle
🔌 Has a powerful plugin system and many official and third-party plugins
🎨 Provides ready-to-go themes to get started quickly

How to make use of it:

Install the swup library.

# NPM
$ npm install swup --save

Import the swup library.

import Swup from 'swup'

Or immediately load the swup file within the doc.

<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 able to go.

const swup = new Swup()

Add the CSS ID ‘swup’ to the aspect you need to animate.

<main id="swup">
  Main content here
</main>

Add an animation class to the aspect.

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

Apply your individual transition effects to the web 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');
      }

})

Create CSS Transitions When Switching Between Pages, swup Plugin/Github