swup / docs

Official swup documentation 📘

swup 4 is released  🎉  Check out the release notes and upgrade guide.

Swup

Versatile and extensible page transition library for server-rendered websites.

Features • Demos • Plugins • Themes • Documentation • Discussions

Overview

Swup adds page transitions to server-rendered websites. It manages the complete page load lifecycle and smoothly animates between the current and next page. In addition, it offers many other quality-of-life improvements like caching, smart preloading, native browser history and enhanced accessibility.

Make your site feel like a snappy single-page app — without any of the complexity.

Features

• ✏️ Works out of the box with minimal markup
• ✨ Auto-detects CSS transitions & animations for perfect timing
• 🔗 Updates URLs and preserves native browser history
• 🏓 Manages the scroll position between pages and anchor links
• 🚀 Uses a cache to speed up subsequent page loads
• 📡 Offers hooks to customize and extend the page load lifecycle
• 🔌 Has a powerful plugin system and many official and third-party plugins
• 🎨 Provides ready-to-go themes to get started quickly

Demos

Explore our interactive demos to see swup in action.

Documentation

Visit our official documentation to learn more.

Plugins

Swup is small by design. Extended features can be added via plugins:

• Display a progress bar while loading
• Enable smooth scrolling between visits
• Update meta tags and stylesheets after page loads
• Add support for preloading pages in the background
• Improve accessibility for screen readers
• Perform your animations in JS instead of CSS transitions
• Animate form submissions
• Get help in debug mode

Check out the list of official plugins and third-party integrations.

Themes

Get started quickly with one of three official themes: fade, slide, and overlay.

Examples

Take a look at the interactive demos and sites using swup for more examples.

Having trouble?

If you're having trouble implementing swup, check out the Common Issues section of the docs, look at closed issues or create a new discussion.

Want to Contribute?

We're looking for maintainers!   👀

Become a sponsor on Open Collective or support development through GitHub sponsors.

This project is tested with BrowserStack.

docs's Issues

Allow cookie banner on docs

We're collecting some analytics to see how things are going with traffic on the docs site. As far as I can tell, it's the best indicator of increased/decreased adoption or source of info about whether some promotional article/video was posted.

We likely need to add a banner about cookies usage. Is the information enough (eg. by using this site you agree), or do we need to come up with some cookie control? Is there some service we could use?

I would really like it to be non-invasive if possible. Those banners are everywhere. 😓

Document new option `animationScope`

Document the new option animationScope:

const swup = new Swup({
    animationScope: 'containers' // will add the animation classes to each container instead of the html element
})

Error

typeerror:%20null%20is%20not%20an%20object%20(evaluating%20'document.body.querySelector('[data-swup="'+s+'"]').outerHTML=t.blocks[s]')

<main id="swup" class="main transition-fade" data-uk-height-viewport="expand: true">
	    {% block content %}{% endblock %}
  	</main>

<script src="https://unpkg.com/swup@latest/dist/swup.min.js"></script>
		<script src="/assets/js/swup/SwupScrollPlugin.min.js"></script>
		<script src="/assets/js/swup/SwupProgressPlugin.min.js"></script>
		<script>
			const options = {
				containers: ["#navbar", "#swup", "#content"],
				plugins: [
					new SwupScrollPlugin(
						{
							doScrollingRightAway: false,
							animateScroll: false,
							scrollFriction: 0.3,
							scrollAcceleration: 0.04,
						}
					),
					new SwupProgressPlugin(
						{
							className: 'swup-progress-bar',
							transition: 500,
							delay: 300
						}
					),
				],
				};
			const swup = new Swup(options);
		</script>

{% extends "index.twig" %}
{% set bodyClass = "page-blog" %}

{% block content %}
  <div id="content" class="uk-container uk-container-mini">
    {{ sprig('/blog/_sprig/lists', {
      limit: 3,
      section: 'blog'
    }) }}
  </div>
	

  <!-- This is the modal -->
  <div id="my-modal" class="uk-flex-top uk-modal-container" uk-modal>
    <div class="uk-modal-dialog uk-margin-auto-vertical uk-border-rounded">
			<div class="uk-position-relative">
		      <div class="modal-content">
		      </div>
	      <div class="modal-spinner uk-position-center">
	        <div uk-spinner></div>
	      </div>
	    </div>
		</div>
  </div>
{% endblock %}

{% js %}
  const modalContent = document.querySelector('#my-modal .modal-content');
	const modalSpinner = document.querySelector('#my-modal .modal-spinner');
	const currentTitle = document.title;
	let currentUrl = ''; // variable to store current url

	/**
	 * before send hx-get
	 *    empty modal content and show the spinner
	 *    then show the modal
	 */
	document.addEventListener('htmx:beforeSend', function(event) {
		modalContent.innerHTML = '';
		modalSpinner.classList.remove('uk-hidden');
		currentUrl = window.location.href; // save the current url before a modal is open

		if (event.target.hasAttribute('data-has-modal')) {
			UIkit.modal('#my-modal').show()
				.then(() => {
					const slug = event.target.getAttribute('hx-get');
					console.log('modal shown : ', slug);

					// updating url on modal opened is handled by hx-push-url in lists.twig
				});
		}
	});

	/**
	 * hide the spinner before the content is swapped into modal
	 */
	document.addEventListener('htmx:beforeSwap', function() {
		modalSpinner.classList.add('uk-hidden');
	});

	/**
	 * on close modal
	 *    reset to original document title
	 *    restore previous url by replacing history state
	 * @see https://www.30secondsofcode.org/blog/s/javascript-modify-url-without-reload
	 */
	UIkit.util.on('#my-modal', 'hidden', function () {
		document.title = currentTitle;

		const state = { additionalInformation: 'Updated the URL with JS' };
		// This will replace the current entry in the browser's history, without reloading
		window.history.replaceState(state, currentTitle, currentUrl);
	});
{% endjs %}

Render anchor links for headlines

Useful for quickly referencing sub-sections of pages. Basically the same as in GitHub readmes:

@gmrchk could you look into this? I have no clue how Jekyll works.

[Bug]: Replit demos/embeds no longer working

What did you expect? 🧐

I expected the replit demo links/embeds to be working

What actually happened? 😵‍💫

They no longer work

Swup and plugin versions 📝

(not relevant)

What browsers are you seeing the problem on? 🧭

No response

Relevant log output 🤓

No response

URL to minimal reproduction 🔗

https://swup.js.org/getting-started/demos/

Checked all these? 📚

• I have read and searched the official docs
• I have checked discussions and existing issues for related problems
• I agree to follow this project's Code of Conduct
• I have provided all necessary information to the best of my knowledge

[Feature Request]: Make pretty notes/tips/warnings more compatible to GitHub

Describe the problem 🧐

Not sure how we missed this when we implemented our custom info boxes: There is a convention to display nicer looking boxes on GitHub! It works like this: https://github.com/orgs/community/discussions/16925

Our info boxes don't follow this convention, yet.

Describe the propsed solution 😎

I'd like to migrate all our boxes so that they look great both on swup.js.org as well as on GitHub.

Alternatives considered 🤔

Ignore it

How important is this feature to you? 🧭

Nice to have

Checked all these? 📚

• I have read and searched the official docs
• I have checked discussions and existing issues for related problems
• I agree to follow this project's Code of Conduct
• I have provided all necessary information to the best of my knowledge

Archive v3 docs

• When merging the next branch, the docs for v3 will only be accessible on a GitHub branch
• We should find a way of archiving and linking to the docs of v3
• Look into adding subdomains on JS.org — see example for v4.webpack.js.org
• Might have to fork the repo as a v3 archive going forward
• JS.org also accepts sites on Netlify

How important is this feature to you?

• Nice to have
• Would make the lifes of current v3 users a lot easier
• I cannot use swup without it

Auto-generate API docs

• Automatically generate docs about the public API and available types
• Could live in a separate folder next to the docs themselves
• Investigate typedoc and alternatives

Rewrite Common Issues

• Update Common Issues to reflect current issues and discussions

Migrate from `markdown-it` to `remark`

markdown-it plugins with possible remark counterparts:

• markdown-it-video ➡️ remark-oembed
• markdown-it-anchor ➡️ anchor-links
• markdown-it-attrs ➡️ remark-attr
• markdown-it-shiki ➡️ remark-expressive-code

Add ES module CDN example

• Add example loading swup as ES module from a CDN
• Use module/nomodule pattern
• Skypack? Unpkg with ?module param?
• Try in browser to make sure it's working

<!-- ES module code -->

<script type="module">
      import Swup from "https://unpkg.com/swup@3?module";
      const swup = new Swup();
</script>

<!-- Fallback non-module code -->

<script nomodule src="https://unpkg.com/swup@3"></script>
<script nomodule>
  const swup = new Swup();
</script>

Installation errors

I'm getting installation errors which might be to do with the export of the module?

I installed to local files by putting the unpkg link at the end of my HTML file, before linking to my main script. I added the import and const swup lines to my main script, at the top.

Got a CORS error and resolved it by running local files via http-server (npm package). I then got 'unexpected' style errors which were resolved by adding adding type="module" to my script link. Both of these fixes came from https://medium.com/@mattlag/es6-modules-getting-started-gotchas-2ad154f38e2e They seem to be expected errors when using native ES6 modules.

Next I got 'failed to resolve' errors which I fixed by changing the constant declaration to use the full unpkg URL with ?module appended, as per this recommendation: dplatz.de/blog/2019/es6-bare-imports.html

However, now I'm getting errors asking for an export. Firefox says "import not found" and Chrome says the requested module does not provide an export. I've tried export default and export Swup and export Swup but still get the same errors.

I've probably done something wrong, but it might be worth adding some detail to the instructions to prevent folks from making the same error.

how to use Accessibility Plugin ?

please make a exemple

Improve pages that lead to external ressources

Describe the problem

If you google for example "swup gtag plugin", the first result will be the (empty!) gtag-plugin page on the docs, that's only there to direct visitors directly to what is set in external_link:

Right now these links are broken due to the new docs structure: https://swup.js.org/docs/third-party-integrations/gtag-plugin.html. But they will appear again. This time at https://swup.js.org/docs/third-party-integrations/gtag-plugin/ (without the .html extension):

An empty page with no information.

Describe the proposed solution

We have a few options to make this experience smoother:

• Completely exclude these pages but still have them in the menu (I'm not sure if this is easily possible)
• Keep the pages around for search engines but improve their layout, for example (my favorite solution):

• We could even improve the pages but also introduce a <meta name="robots" content="noindex, follow"> tag

What's your opinion on this?

Couple of Questions

Hi there

Thanks for this awesome and easy to implement library for page swapping. I have few questions and would highly appreciate any help. Some may sound silly and sorry for that in advance but confirmation is better then ignorance.

1- If I change the swup container with custom selector then in that case when using preload plugin how data-swup-preload can be changed for example I change the swup container with something like data-page or class="data-page". How I can incorporate with data-swup-preload attribute or I have to leave it as it is.

2- Does swup caches the page by default or I have to write code mention in docs as below. BTW I tested the cache code in my application but I did not see the page in cache storage in dev tools and it downloads the page every time I go back forward.

3- When using plugin we pass the plugins array under swup instance as follows:

const options = {
cache: true,
animateHistoryBrowsing: true
};
const swup = new Swup({
options, // is it the right palce to put options here
plugins: [new SwupPreloadPlugin()]
});

swup.cache.cacheUrl({
title: 'Page title',
pageClass: 'body-class',
originalContent: 'html content of page',
blocks: ['

'],
responseURL: '/redirected-url'
});

So the thing is my placement of options object is correct? and animate history browsing does not seem to work (page transition does not play).

Thanks & Regards,
Shehzad Asif

Find a way to not auto-format code snippets in md files

Describe the problem

npm run lint right now also formats .md files. While doing so, it applies some undesired changes to the code snippets in those.

Describe the proposed solution

The only thing that comes to mind is to exclude .md files alltogether. Any other ideas?

How important is this feature to you?

• Nice to have
• Would make my life a lot easier
• I cannot use swup without it

Ensure running `lint` when pushing

Would be nice to automatically npm run lint when pushing/committing on the docs as well. Just played around with husky a bit, but wasn't able to get it to work. Maybe one of the other maintainers wants to tackle this?

swup.getCurrentPage section duplicate

There is a duplicate on the getCurrentPage section in the file: docs/api/cache.md.

Have a nice day ;)

Problem reloading carousel ( flickity in swup )

i don t know if this is the right place but might someone can help me.
i m trying to use Flickity in my Swup container.

var elem = document.querySelector('.main-carousel');
var flkty = new Flickity( elem, {
// options
cellAlign: 'left',
contain: true
});

// element argument can be a selector string
// for an individual element
var flkty = new Flickity( '.main-carousel', {
// options
});

carousel will be in home page but when i click on other page the carousel disappear.

what i have to do ? Thanks

Exclude some pages from the search

The next step after updating pagefind to 1.0.2 could be to programmatically exclude some pages from the search results. The second result "Announcing swup 2" for example would be nice to be excluded from the search IMO:

How to do this

We could maybe introduce a new frontmatter property "exclude-from-search: true" and add the attribute data-pagefind-body only if the property isn't set to true.

How important is this feature to you?

• Nice to have

Convert list of events from table to list

Describe the problem

Right now, the list of events is a table. This has tow downsides IMO:

• You can't link to a specific event using a hash URL
• On mobile, everything becomes pretty dense and small

Describe the proposed solution

I would propose to convert the table to <h3>eventName</h3><p>Event description</p>.....

Different animations with different routes

Hi,
I would like to create two type of transitions. Once between pages, another only from the Homepage to the single portfolio pages, that I called case (which have slug /case/...). The second does not work. Only the first transition between pages works.

I've this code for transition page:

const options = [
		{
		from: '(.*)',
		to: '(.*)',
		in: function (next) {
			TweenLite.fromTo(document.querySelector('#mainContent'), 0.6, {
				autoAlpha: 0,
				y: 100,
			}, {
				y: 0,
				autoAlpha: 1,
				ease: Expo.easeOut,
				onComplete: next
			});
		},
		out: (next) => {
			TweenLite.fromTo(document.querySelector('#mainContent'), 0.6, {
				autoAlpha: 1,
				y: 0,
			}, {
				y: 100,
				autoAlpha: 0,
				ease: Expo.easeIn,
				onComplete: next
			});
		}
	}
	];

I think I'll have to create a new one:

// animation from Home to single Case
{ from: '/', to: '/case' },

How should I structure the from and to properties to make them work with the case pages?
Is this the only thing to check or should I fix other things too??

Thanks,
M.

doScrollingRightAway scrolls to top straight away

Hi there

Loving Swup. Am currently trying to use the ScrollPlugin. Have set

doScrollingRightAway: false

However, this seems to make the page jump to the top straight away before replacing the content. I am using the JSPlugin as want to use GSAP to animate.

Any initial thoughts or fixes?

Thanks

James

Create showcase page with examples and screenshots

It'd be nice to have a visually attractive page with current examples of sites built using swup.

Evaluate options for embeddable demos

Need to find an alternative for hosting our demos — Replit doesn't support deployments for team accounts.

Options

• CodeSandbox: Check history scroll restoration support
• ???

Revamp documentation site

New design, new core structure. Ideally, all that would stay is the MD files, since those have been heavily improved over time.

Could be a good based https://www.11ty.dev/.

First, we should probably collect any design ideas.

Transition object

Document switching from swup.transition to swup.context.transition.name

Document current browser support

#58

Move docs to 11ty

Deploy 11ty to GitHub pages:
https://www.rockyourcode.com/how-to-deploy-eleventy-to-github-pages-with-github-actions/

Head plugin effecting fade in transitions

Hi thanks for making this awesome library, I encountered a problem with how the HeadPlugin is effecting animations and determined a work around and thought I'd post it here, in-case anybody is running into the same issue and also to notify you guys if you weren't aware of this. Also all of this may be misinformed and I might be missing something so please let me know.

The Scenario:
Let us say we want to use different stylesheets for different pages on our site, then we can use the HeadPlugin to do so.

The Problem:
When changing stylesheets the fade out animation will work but the fade in animation will not work.
(note: if the elements within the stylesheet have the same name in the two pages being transitioned between the fade in animation will work some of the time, depending on the element and the animation.)

A Solution:
To create a separate stylesheet defining all the animations between all your pages and include it in every html page. Then have a separate stylesheet for the rest of the styling for the individual pages or as you see fit. This way you can still style the rest of your elements sharing the same ids/classes differently between pages.
(Drawback: initial load time of the stylesheet containing all the animations, but this file should be lazy loaded :D)

Another Solution (me no like) :
Have one big stylesheet with the styles for all the elements in every page (excluding the inline CSS of course).
(Drawback1: initial load time of the stylesheet containing all the animations and other styles, this file should not be lazy loaded, unless you split the animation CSS and non animation CSS into separate files. In which case just the initial load time of your style file, unless all the critical styles are done inline in which case you could lazy load both files XD.)
(Drawback2: can't have elements sharing the same ids/classes on different pages unless using inline CSS to define the differences.)

Potential solution? (haven't tried):
Using inline CSS to define the animations O_O, idk if this is even possible but probably not a good idea.

I can post some examples demonstrating the problems etc if anybody needs.

If there is a belter way then pls let me know, otherwise hope this helps OwO.