Author: | gmrchk |
---|---|
Views Total: | 13 views |
Official Page: | Go to website |
Last Update: | January 30, 2023 |
License: | MIT |
Preview:

Description:
The swup JavaScript library lets you apply custom CSS transitions to pages when switching between them. Supports preload, page cache, and event handlers.
See also:
- CSS3 Based Page Transitions – Animate Transition
- Smooth Page Transitions With JavaScript And PJAX – barba.js
Basic usage:
Install the swup library.
# NPM $ npm install swup --save
Import the swup library.
import Swup from 'swup'
Or directly load the swup file in the document.
<script src="./dist/swup.js"></script> <!-- or from a CDN --> <script src="https://unpkg.com/[email protected]"></script>
Initialize the swup library and we’re ready to go.
const swup = new Swup()
Add the CSS ID ‘swup’ to the element you want to animate.
<main id="swup"> Main content here </main>
Add an animation class to the element.
<main id="swup" class="animation-class"> Main content here </main>
Apply your own transition effects to the page.
.animation-class { /* default animation rules */ } html.is-animating .animation-class { /* CSS styles when animating */ } html.is-changing .animation-class { /* CSS styles when changing */ } html.is-leaving .animation-class { /* CSS styles when leaving */ } html.is-rendering .animation-class { /* CSS styles when rendering */ }
All default config options.
const swup = new Swup({ // 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. animateHistoryBrowsing: false, // animation selector animationSelector: '[class*="transition-"]', // defines link elements that will trigger the transition linkSelector: 'a[href^="' + window.location.origin + '"]:not([data-no-swup]), a[href^="/"]:not([data-no-swup]), a[href^="#"]:not([data-no-swup])', // stores previously loaded contents of the pages in memory cache: true, // default container(s) containers: ['#swup'], // request headers requestHeaders: { 'X-Requested-With': 'swup', Accept: 'text/html, application/xhtml+xml' }, // enable/disable plugins // see below plugins: [], // skips popState handling when using other tools manipulating the browser history skipPopStateHandling: function skipPopStateHandling(event) { return !(event.state && event.state.source === 'swup'); }, // allows ignoring specific visits through a callback ignoreVisit: (href, { el } = {}) => el?.closest('[data-no-swup]'), // provides a way of rewriting URLs before swup will attempt to load them resolveUrl: (url) => { if (url.startsWith('/projects/?')) { return '/projects/'; } return url; } })
Events.
swup.on('animationInDone', () => { // do something }); swup.on('animationInStart', () => { // do something }); swup.on('animationOutDone', () => { // do something }); swup.on('animationOutStart', () => { // do something }); swup.on('animationSkipped', () => { // do something }); swup.on('clickLink', () => { // do something }); swup.on('contentReplaced', () => { // do something }); swup.on('disabled', () => { // do something }); swup.on('enabled', () => { // do something }); swup.on('hoverLink', () => { // do something }); swup.on('openPageInNewTab', () => { // do something }); swup.on('pageLoaded', () => { // do something }); swup.on('pagePreloaded', () => { // do something }); swup.on('pageRetrievedFromCache', () => { // do something }); swup.on('pageView', () => { // do something }); swup.on('popState', () => { // do something }); swup.on('pageLoaded', () => { // do something }); swup.on('samePage', () => { // do something }); swup.on('samePageWithHash', () => { // do something }); swup.on('transitionStart', () => { // do something }); swup.on('transitionEnd', () => { // do something }); swup.on('willReplaceContent', () => { // do something });
Changelog:
v3.0.4 (01/30/2023)
- Specify exact types for each type of event handler
- Update package version
v3.0.3 (01/27/2023)
- Use shared browserslist config
v3.0.2 (01/21/2023)
- Make sure ignoreVisit option is called when visiting pages programmatically
v3.0.1 (01/20/2023)
- Fix: remove origin from ignoreVisit parameter
v3.0.0 (01/19/2023)
- Support CSS animations and keyframes
- Allow ignoring visits via callback function
- Export native ESM modules
- Smaller bundle size for modern browsers: 4.5 kB
v2.0.19 (08/24/2022)
- Disable caching of initial page to avoid caching modified DOM
- Gracefully handle missing document title
- Force-reload if next page has no swup containers
- Remove all reliance on global window.swup instance
v2.0.18 (08/10/2022)
- Fixes the buggy behavior when navigating rapidly between pages
v2.0.17 (08/02/2022)
- Gracefully handle missing transitions on container
- Warn about missing container
- Scope transition selector to body
- Normalize cache paths
v2.0.16 (07/01/2022)
- Improve handling of scroll anchors with special characters
v2.0.15 (06/15/2022)
- Update dependencies
v2.0.14 (12/27/2020)
- Bugfix
v2.0.13 (12/07/2020)
- update patch version
v2.0.12 (11/30/2020)
- fix bug where animateHistoryBrowsing option was ignored for OUT animations
v2.0.11 (07/09/2020)
- update version
v2.0.9 (02/26/2020)
- removed destroy of mouseover listener as it was moved to the preload plugin
v2.0.8 (11/01/2019)
- fix problem when ‘<body’ string is present in DOM
v2.0.5 (07/15/2019)
- updated
v2.0.4 (05/31/2019)
- fix wrong uppercase/lowercase letters in imports
v2.0.2 (05/27/2019)
- major update
v1.9.0 (01/07/2019)
- make preloadPage method return Promise
v1.7.18 (01/07/2018)
- fix querySelectorAll issue in form handler and destroy method
v1.7.17 (12/17/2018)
- fix swup getting stuck by errors inside of handlers defined with on method
404…
Fixed. Thank you for reporting.