Page Transitions (Swup)

This page is dedicated primarily to developers who are extending Zero One.

From version 4.1.0 we integrated optional page transitions using Swup library.

Build and compile

But that's not all there is. We included the whole JS build and compile system in the assets/js/ folder. That system is based on Build Tool Boilerplate by Chris Ferdinandi, but we extended it further to work also on Windows and to support JS import modules as Parcel for example does it.

You can see everything about how it works by opening assets/js/readme.md file. Although it can do more than just JS, we didn't want to strip other options.

To use it only for JS, there are only three commands you should care about:

• npm install to instal all dependencies

• npm run js to build and compile JS

• npm run watch-js to watch for JS changes

You develop assets/js/src/js/main.js file, it is the main file in which you import all others. You can of course add new subfolders there and import additional JS libraries you need.

After build the compiled files are in the assets/js/dist/js/ folder.

How Swup works?

You can learn more about how Swup works at https://swup.js.org/getting-started/how-it-works

Although they say it is an easy library, it actually isn't. Every library that changes the DOM should be integrated with great care and should be thoroughly tested.

We are working for a few years with Swup, and have it live on several websites so we know what we are doing. You can see the Zero One Swup set up in the assets/js/src/js/main.js file.

In Zero One there are three separate containers: #swup (page content + footer), #navbar and #mobile-menu. You will see that navbar stays still while page content changes.

What is the main issue if you extend Zero One and want to use Swup page transitions?

Now, we come to the main reason why this documentation page exists.

Swup library automatically detects all links (<a></a> tags), and do its magic. But... Not all links are links that should be included in the page transitions process. Some links types Swup excludes by default, for example, links that point to a different domain, and we excluded in our setup links that have target="_blank". And that's fine.

But, there are links you need to exclude manually.

Links like modals, toggles, lightbox, etc. Mostly Javascript links.

You do that by adding [data-no-swup] attribute to the link. For example:

// Modal example from Zero One
<div><a href="#modal-full" data-no-swup uk-search-icon uk-toggle></a></div>

We did that everywhere in Zero One where it needs to be added, but when you are extending Zero One and adding your additional templates and code, you should add [data-no-swup] attribute to the link whenever you want that link to exclude from the transition process.