Events

As we are replacing the native lifecycle of a browser visit, we need events that let us imitate that lifecycle in our scripts.

Swup emits a list of events that can be used to implement custom logic, initialize components, trigger analytics, and much more. Listen to events using the on() and off methods.

// Add a new handler
swup.on('pageView', () => {
  console.log('New page loaded');
});

swup.off('pageView', handler); // remove a single handler
swup.off('pageView'); // remove all 'pageView' handlers
swup.off(); // remove all handlers for all events

For backward compatibility, all events are also triggered on the document with a swup: prefix.

document.addEventListener('swup:contentReplaced', () => {});

List of all events

Event name	Description
animationInDone	triggers when transition of all animated elements is done (after content is replaced)
animationInStart	triggers when animation IN starts (class `is-animating` is removed from html tag)
animationOutDone	triggers when transition of all animated elements is done (after click of link and before content is replaced)
animationOutStart	triggers when animation OUT starts (class `is-animating` is added to html tag)
animationSkipped	triggers when transition is skipped (on back/forward buttons)
clickLink	triggers when link is clicked
contentReplaced	triggers right after the content of page is replaced
disabled	triggers on `destroy()`
enabled	triggers when swup instance is created or re-enabled after call of `destroy()`
hoverLink	triggers when link is hovered
openPageInNewTab	triggers when page is opened to new tab (link clicked when control key is pressed)
pageLoaded	triggers when loading of some page is done
pagePreloaded	triggers when the preload of some page is done (differs from pageLoaded only by the source of event - hover/click)
pageRetrievedFromCache	triggers when page is retrieved from cache and no request is necessary
pageView	similar to contentReplaced, except it is once triggered on load
popState	triggers on popstate events (back/forward button)
samePage	triggers when link leading to the same page is clicked
samePageWithHash	triggers when link leading to the same page with `#someElement` in the href attribute is clicked
transitionStart	triggers when transition start (`loadPage` method is called)
transitionEnd	triggers when transition ends (content is replaced and all animations are done
willReplaceContent	triggers right before the content of page is replaced

Examples

Trigger analytics page views

swup.on('pageView', () => {
  dataLayer.push({
    event: 'VirtualPageview',
    virtualPageURL: window.location.pathname,
    virtualPageTitle: document.title
  });
});

Initialize new components on the page

swup.on('contentReplaced', () => {
  swup.options.containers.forEach((selector) => {
    // load scripts for all elements with 'selector'
  });
});

Listening to swup's DOM events

document.addEventListener('swup:contentReplaced', () => {
  // do something
});