Options

Swup has a several options that can be passed into a constructor as an object.

const options = {};
const swup = new Swup(options);

Link selector defines link elements that will trigger the transition. By default, the selector takes any link with href attribute starting with /, # or current domain. You can modify this option to include SVG links or exclude some other.

const options = {
  linkSelector:
    'a[href^="' +
    window.location.origin +
    '"]:not([data-no-swup]), a[href^="/"]:not([data-no-swup]), a[href^="#"]:not([data-no-swup])'
};

In case you want to exclude links for some routes, lightbox or any other functionality, extend the selector. By default, you can add [data-no-swup] attribute to the link, if you want to exclude just a few.

Animation Selector

As swup is built on animations, it is required to define the elements that are being animated. Usually, you would like to give the elements some common class or class prefix. By default option is set to [class*='transition-'], which selects all elements with class attribute containing transition-.

const options = {
  animationSelector: '[class*="transition-"]'
};

Containers

Containers option defines the array of selectors of containers, where the content needs to be replaced. Containers option usually contains the main element with the content of the page, but can include any element that is present across all pages. This creates a possibility of animating elements on the page while still replacing it’s parts. Another good example where this is helpful is the change language link, which usually appears the same across the site (no animation needed), but leads to a different URL on each page. Option defaults to the single container of id #swup.
Note: Keep in mind that only elements inside of body tag are supported.

const options = {
  containers: ["#swup"]
};

Cache

Swup has a built-in cache, meaning that it stores previously loaded contents of the pages in memory in a form of an object. This drastically improves speed for static sites but should be disabled for dynamic sites. Cache option defaults to true.

const options = {
  cache: true
};

Request Headers

Swup sets two headers of the request by default and headers can be adjusted with requestHeaders option. This can be useful for returning custom response from a server, or any other processing on a server side.

const options = {
  requestHeaders: {
    "X-Requested-With": "swup", // so we can tell request comes from swup
    Accept: "text/html, application/xhtml+xml" // to explicitly define what response we are expecting
  }
};

Skip popState Handling

Swup is built around browser history API, but sometimes some other tools manipulating the browser history can be used as well. For this reason, swup places a source property into every history state object it creates, so it can be later identified (swup also modifies current history record on start, to include the “swup” source property as well). On popState events, swup only handles the records that were created by swup. This behavior can be modified by skipPopStateHandling option, which is represented by a function returning boolean (false = handle the popstate, true = do nothing). The function accepts one argument - the popstate event. Option defaults to the following:

const options = {
  skipPopStateHandling: function(event) {
    if (event.state && event.state.source == "swup") {
      return false;
    }
    return true;
  }
};

Animate History Browsing

Option enables the animation on popstate events. Swup adds is-popstate class to html tag for the whole process of animation on back/forward browsing.

Note that 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. Default value is false.

const options = {
  animateHistoryBrowsing: false
};

Default Options

The default option object look like…

const options = {
  animateHistoryBrowsing: false,
  animationSelector: '[class*="transition-"]',
  containers: ["#swup"],
  cache: true,
  linkSelector:
    'a[href^="' +
    window.location.origin +
    '"]:not([data-no-swup]), a[href^="/"]:not([data-no-swup]), a[href^="#"]:not([data-no-swup])',
  skipPopStateHandling: function(event) {
    if (event.state && event.state.source == "swup") {
      return false;
    }
    return true;
  }
};