Complete, flexible, extensible and easy to use page transition library for your static web.

Description

Currently, the only official way of ignoring links is by appending the link selector option. This can get very complex very easily and it's not possible to do more advanced checks like e.g. ignoring all links inside a specific container. (The unofficial way would be listening to and preventing the click event in the capture phase).

The proposed change will split the check into to phases: select all links by selector, then filter via user-supplied callback.

This feature has been requested a few times and would be something I'd find very useful in my own projects.

Advantages

• Makes the selector much simpler
• Allows ignoring a whole container element with the data-no-swup attribute, not just every link individually
• We can add certain checks that will always skip swup, like target=_blank or the download attr on links
• Plugins can reuse some of the logic for other visit "triggers", e.g. forms plugin

Checks

• [x] The PR is submitted to the ~~master~~next branch
• [x] The code was linted before pushing (npm run lint)
• [x] All tests are passing (npm run test)
• [x] New or updated tests are included
• [x] The documentation was updated as required

Additional information

• This is a breaking change since we're ignoring a[download] elements. Hence submitting to the next branch.

Questions

• How would this tie in with #508 ?

Feature addition to allow multiple transition durations as well as animation keyframes.

Things that currently don't work

• Combining multiple transitions with different durations and having both finish: swup will only wait for the first transition to finish before replacing the content
• Using animation keyframes for page transitions: swup only supports the transition property

What this PR does to make those things work

• Wait for all transitions to finish before replacing the content
• Detect and work with CSS animations as well, choosing whichever is longest

Prior art

Most of the new behavior is lifted straight from Vue's transitions module.
It's working really well so far on a lot of production sites of mine.

Questions

• Is there any argument to be made for NOT waiting for all transitions to finish?
• Should we prefer transitions to animations? The PR currently defaults to whichever has the longest duration in case both are defined.

Notes

• Added tests for simple and complex transitions as well as animation keyframes
• Looks somewhat complex, but will increase bundle size by barely 0.05KB

Fixes the bug described in #187 .

This attempt addresses the described bug by doing two things:

1. Don't execute renderPage if page.url doesn't match getCurrentUrl():

const isCurrentPage = this.getCurrentUrl() === page.url;
if( !isCurrentPage ) return;

2. Remove all swup-related html-classes on popstate, if animateHistoryBrowsing is false:

if( !this.options.animateHistoryBrowsing ) {
  document.documentElement.classList.remove('is-animating');
  cleanupAnimationClasses();
}

I tried to run cypress on this, but I can't get it to work / I have never used it. Manual testing looked fine, though.

Replaces #508

Adds a new global option to swup, that allows to run a callback for how swup should resolve a path.

What is the problem?

Right now, to be able to leave and re-enter control over the browser URL/state by swup, three steps are necessary:

• Use skipPopStateHandling with custom logic
• Manually ignore links with one of the given options (linkSelector, stopPropagation() during the capture phase,...)
• Manually adjust the cache URLs so that back- and forward navigation doesn't need additional server requests

While this kind of behavior is already possible to achieve with the currently available swup API, it adds a lot of boilerplate to each new site that wants to have this. Also, the current cache implementation is less than ideal for that kind of scenario right now. It will either fill itself up with unnecessary duplicates of the same page or have cache misses for pages that were previously already loaded from the server.

Proposed solution

All three of the above topics basically boil down to always the same question: Should various paths actually be resolved to just one by swup?

• on popState: Is the resolved version of the new browser URL the same as the previous one? > ignore
• on clickLink: Is the resolved href of the link the same as the current browser URL? > ignore
• Accordingly to swup ignoring the above events if paths resolve to the same one, the cache can also just keep one copy for all URLs that resolve to the same one.

Demo & Test Site

I have set-up a test site here: https://test.rassohilber.com/swup-resolve-path/test/

On that site, the whole filter logic is done by a custom component that doesn't want swup to interfere. It does everything from updating the URL to rendering the state. Navigation away from the list to one of the character detail pages or to the "about"-page and back again is being handled by swup again. To make it more obvious that there is no page load between filters, I added a staggered animation to the items that only runs if the page is being fully rendered (initially and by swup).

Code Example

const swup = new Swup({
  resolvePath: path => {
    // resolve every URL that contains '/?=filter=xyz' to '/'
    return path.replace(/\/\?filter=.+/, '/');
  }
})

Checks

• [x] The code was linted before pushing
• [x] All tests are passing
• [x] New or updated tests are included
• [ ] The documentation was updated as required
• [ ] Make sure that restoring scroll positions in ScrollPlugin also uses the resolved path

• move all checks out of linkClickHandler and in a dedicated method ignoreLink
• move the el.origin check from the option inside this method

Makes it possible for plugins to call swup.ignoreLink(el)

Related: #551

Set up a simple test site with basic setup and transitions for people to try out swup.

Options:

• Repo with static files and npx serve
• Microsite on docs domain
• REPL on Glitch, CodeSandbox, etc.

Guys, I need help integrating swup to my wordpress site. I try everything, put <main id="swup" class="transition-fade"> around content in my index.php, page.php, single.php, archive.php, search.php..

Create function in my function.php

 function pro_adding_scripts() {
	 wp_register_script('swup-pro-script', get_template_directory_uri() . '/swup.min.js', array('jquery'), '1.2', false);
	 wp_enqueue_script( 'swup-pro-script');
	 
	 wp_register_script('swup-pro-script2', get_template_directory_uri() . '/script.js', array('jquery'), '1.2', false);
	 wp_enqueue_script( 'swup-pro-script2');
}
add_action( 'wp_enqueue_scripts', 'pro_adding_scripts' ); 

import script in header.php

<script src="/swup.min.js"></script>
<script src="/script.js"></script>

Use this in my script.js file:

import Swup from 'swup';

const swup = new Swup({
 		LINK_SELECTOR: `a[href*="${domain}"]:not([data-no-swup]), a[href^="/"]:not([data-no-swup]), a[href^="#"]:not([data-no-swup]), a[xlink\\:href]`,
 	});

and add this css:

.transition-fade {
  transition: 0.4s;
  opacity: 1;
}

html.is-animating .transition-fade {
  opacity: 0;
}

Nothing happened... when press any link page just reloads normal. I'm not sure what I doing wrong.

Hi guys,

which is the best way to use Swup page transition with VueJs components?

I need to use Swup because the project is based on CMS and I need to manage dynamic routes. So, I tried to use the Vue method $destroy and re-mount the same instance but I've a common navbar components (the same for all pages) that after first page transition stop to be reactive.

Any ideas?

Hello, awesome library. am loving it so far. I'm having difficulty figuring out how to replace different elements for different pageLoads, or indeed if this is possible. swup initialised with elements: ['#main__wrap','#hdr-crt-lnk']

works fine for all links.

however, i do a custom pageLoad for form submission where I set elements: ['#contact--form']

As I only want to replace the form on submission. all works as expected apart from the new form content is loaded into #main_wrap instead of #contact--form.

I hope this makes sense. I'll continue you to investigate (read fiddle & play) to see if i can figure it out, but any assistance would be greatly appreciated.

thanks in advance cheers gwil

The default swup behaviour is skipping animations when you go back in history. I tried to animate the pages by assigning to options.skipPopStateHandling a function which always returns true (prevents the default behaviour) and loads the page by loadPage() so it does animate. But this also creates a new entry in browser history and when you now try to go back it loads the same page over and over. So the only way would be altering the Swup files. Thank you for taking this into consideration

When a first page-load has <style> tags in a container used by Swup, it will not add them to the cache. Navigating back will result in the page not having the <style> tags that it initially existed.

This issue does not present itself with subsequent page-loads, loaded by mouse-over, for example. It that case, the tags get added to the cache properly.

Workaround

For now, you can turn off the cache:

const options = {
  cache: true
}

This isn't ideal (the caching Swup does is the reason I'm using it, and it rocks when it works), but this will prevent any lost styles. The issue is especially pungent on Wordpress 5.9+ sites that insert dynamic <style> blocks.

Discussed in https://github.com/swup/swup/discussions/557

For swup@3 we'll need to introduce proper peerDependencies for all plugins, when we migrate them to use swup's updated API functions:

https://nodejs.org/es/blog/npm/peer-dependencies/

• [x] Use native URL objects for parsing URL parts
• [x] Create a helper to instantiate URLs from HTML and SVG links
• [ ] Find a better solution than the custom address getter

Related to #551

The upcoming implementation of ignoreLinks has one flaw: it doesn't ignore links with protocols like tel: or mailto:. We'll need to add that check before the release and add tests as well.

Edit: Actually, it does. We're checking for link.origin and comparing to location.origin, that includes the protocol. Still, we should make sure it's either http or https in any case.

new URL(document.URL, document.baseURI)
new URL(window.location.pathname, document.baseURI)

Some questions to ask:

• Should we move the origin check into a separate function that cannot be overriden? I'm actually not sure what the advantage is of allowing cross-origin requests
• Should we switch to the native URL object instead of swup's Link class? Makes more sense to me
• Maybe look for inspiration in Turbo's URL module

Ongoing effort to switch all CI checks to GitHub actions.

Goals

• Avoid CircleCI usage limits (test runs are hidden when free quota is met)
• Speed up test runs (GitHub actions looks to be 50-70% faster than CircleCI)

Tasks

• [x] Create GitHub action for E2E tests with Cypress (see workflow runs)
• [x] Run the build script only once, instead of three times:
  • as part of npm ci
  • as a separate npm run build
  • as part of npm run test
• [ ] Add back Cypress recording integration (project id and record key)
• [ ] Integrate lint step here as well?

Hi swup/swup!

This is a one-off automatically generated pull request from LGTM.com :robot:. You might have heard that we’ve integrated LGTM’s underlying CodeQL analysis engine natively into GitHub. The result is GitHub code scanning!

With LGTM fully integrated into code scanning, we are focused on improving CodeQL within the native GitHub code scanning experience. In order to take advantage of current and future improvements to our analysis capabilities, we suggest you enable code scanning on your repository. Please take a look at our blog post for more information.

This pull request enables code scanning by adding an auto-generated codeql.yml workflow file for GitHub Actions to your repository — take a look! We tested it before opening this pull request, so all should be working :heavy_check_mark:. In fact, you might already have seen some alerts appear on this pull request!

Where needed and if possible, we’ve adjusted the configuration to the needs of your particular repository. But of course, you should feel free to tweak it further! Check this page for detailed documentation.

Questions? Check out the FAQ below!

FAQ