Partial Component

Page Transitions

The Page Transitions partial enables smooth page transitions using SWUP. It intercepts internal link clicks, fetches pages via AJAX, and swaps the content of the#swupcontainer with a fade animation. The partial has no visual output of its own; its manifest loads the transition styles and scripts.

This very site uses the partial: navigate to any other page and back to see the fade transition in action.

Manifest

json

{
  "name": "page-transitions",
  "type": "partial",
  "styles": ["page-transitions.css"],
  "scripts": ["page-transitions.js"],
  "requires": []
}

Dependencies

The partial requires npm packages that are not bundled with the component:

bash

npm install swup @swup/head-plugin @swup/scroll-plugin @swup/preload-plugin

Usage

Unlike most partials, page-transitions is not configured through frontmatter. It is included once in the base layout:

nunjucks

{% include "components/_partials/page-transitions/page-transitions.njk" %}

The layout needs a main element that serves as the SWUP container. Content inside it is replaced during transitions; content outside (header, footer) persists:

html

<main class="transition-fade" id="swup">
  <!-- Page content that gets swapped -->
</main>

Initialize the PageTransitions registry at the very top of the bundler entry point (main.js) so it exists before any component script runs:

javascript

if (!window.PageTransitions) {
  const componentRegistry = new Map();
  const cleanupRegistry = new Map();

  window.PageTransitions = {
    registerComponent: (name, initFn) => componentRegistry.set(name, initFn),
    registerCleanup: (name, cleanupFn) => cleanupRegistry.set(name, cleanupFn),
    _componentRegistry: componentRegistry,
    _cleanupRegistry: cleanupRegistry
  };
}

Component Registration

Components with JavaScript register an init function so they re-initialize after each page swap, and optionally a cleanup function for intervals or observers:

javascript

if (window.PageTransitions) {
  window.PageTransitions.registerComponent('my-component', initMyComponent);
  window.PageTransitions.registerCleanup('my-component', cleanupMyComponent);
}

Components guard against duplicate setup by checkingelement.dataset.initializedbefore binding event listeners.

Notes

Sites with multiple layouts need a distinguishing class (e.g.with-sidebar) on the body; the partial detects layout changes and forces a full reload between different layouts
Non-HTML resources (.zip,.pdf, images) are excluded from transitions via SWUP'signoreVisitoption
Registration is conditional (if (window.PageTransitions)), so components keep working on sites without page transitions