Socket
Socket
Sign inDemoInstall

swup

Package Overview
Dependencies
Maintainers
1
Versions
142
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

swup - npm Package Compare versions

Comparing version 0.2.5 to 0.2.6

4

package.json
{
"name": "swup",
"version": "0.2.5",
"description": "Animated page transitions with css - simple, quick and fun.",
"version": "0.2.6",
"description": "Animated page transitions with css.",
"main": "lib/index.js",

@@ -6,0 +6,0 @@ "scripts": {

177

readme.md
# swup
Animated page transitions with css - simple, quick and fun.
**Animated page transitions with css.**
**Note:** In case you like to do your animations in JS, you may also checkout [swupjs](https://www.npmjs.com/package/swupjs).
**Note:** In case you like to do your animations in JavaScript, you may also check out [swupjs](https://github.com/gmrchk/swupjs).
## Table of contents
[Introduction](#introduction)
* [What it does](#what-it-does)
* [What it doesn't do](#what-it-doesnt-do)
[Installation](#installation)
[How it works](#how-it-works)
* [Example](#example)
* [Example of different transitions for different pages](#example-of-different-transitions-for-different-pages)
[Options](#options)
* [Link Selector](#link-selector)
* [Element](#elements)
* [Animation Selector](#animation-selector)
* [Cache](#cache)
* [Page Class Prefix](#page-class-prefix)
* [Scroll](#scroll)
* [Support](#support)
* [Disable IE](#disable-ie)
* [Debug Mode](#debug-mode)
* [Default values](#default-values)
[Events](#events)
[API](#api)
## Introduction
Swup enables animated transitions between pages powered by CSS. All you need to do is define how your page looks in the transition state, and swup takes care of the rest. Here's a little [preview](https://gmrchk.github.io/swup/).
### What it does
* Swup takes care of browser history... without breaking it - animation is disabled for popstate events, browsers native window scrollTop amount is remembered and your page won't be jumping around on that iOS/OSX swipe for previous/next page.
* Swup works with your code. Need to attach your JS on the loaded content? Need to trigger some analytics events? ...or simply want to close a sidebar on page transition. No problem. Swup emits whole bunch of events that you can use in your code.
* Swup takes care of timing. Is your "out" animation done before page is loaded? It'll wait for the page to load to continue... Is your page loaded before animation is done? It'll wait for all your css transitions to finish... All you need is to define that buttery smooth transition, and swup does the rest.
* Swup takes care of browser history... without breaking it - animation is disabled for popState events, browsers scroll control is preserved and your page won't be jumping around on that iOS/OSX swipe a previous/next page.
* Swup works with your code. Need to attach your JavaScript on the loaded content? Need to trigger some analytics events? Simply want to close a sidebar on page change? No problem. Swup emits a bunch of events that you can use in your code.
* Swup takes care of timing. It automatically detects when your css transitions are finished, and of course, when the next page is loaded. All you need to do is define that buttery smooth transition, and leave the rest to swup.
### What it doesn't
* Swup never loads same page twice (when cache option is enabled). Actually, once you've visited several pages of site, you can even disable your internet connection and continue browsing.
* Swup doesn't wait for next page to be loaded to start the animation - it all happens at the same time. While user is trying to process what is happening on screen, your request is being served. With preload option enabled it can even start loading your page before you click the link... and don't worry, swup won't start another request to the same page in case you click the link while it's being preloaded.
* Swup works with any server side rendered content and it doesn't require any setup on server. While it would be possible to limit the data sent from server to minimum and serve only blocks required by swup, it would require setup on server... and let's face it, those few extra lines of html is usually not what's slowing your load time.
### What it doesn't do
* Swup never loads the same page twice (when cache option is enabled). Actually, once you've visited several pages of site, you can even disable your internet connection and continue browsing.
* Swup doesn't wait for next page to be loaded to start the animation - it all happens at the same time. While a user is trying to process what is happening on screen, your request is being served. With preload option enabled it can even start loading your page before you click the link. But don't worry, swup won't start another request to the same page in case you click the link while it's being preloaded. At the same time, it won't spam your server with requests in case user hovers over a list of links of some sort - maximum number of requests being created/processed by swup at once is two.
* Swup works with any server-side rendered content and it doesn't require any setup on the server. However, it is possible to implement a transfer of only required data on the server based on `X-Requested-With` request header. In that case, swup can be easily modified based on your solution.
**Note:** Swup is currently stable and production-ready. However, it is a "one-man show" and any contributions or suggestions are welcome.

@@ -23,14 +53,13 @@ ## Installation

## How it works
Apart from simply loading the contents of the new page and replacing it in html, swup is built around the css animation - you defined the transition and timing in css and swup handles the rest. Swup detects end of transition of animated elements and proceeds to replacing the content and animating your content back. For the animations based on css to be possible, swup uses several classes that are assign to html tag through the process of page transition.
Apart from simply loading the contents of the new page and replacing it in HTML, swup is built around css animation - you defined the transition and timing in CSS and swup handles the rest. Swup detects the end of transition of animated elements and proceeds to replacing the content and animating your page back. For the animations based on CSS to be possible, swup uses several classes that are assigned to the html tag through the process of page transition.
* **is-animating** - this class is assigned to the html once link is clicked and is removed shortly after the content of the page is replaced
* **is-leaving** - assigned once link is clicked and removed when content is replaced
* **is-rendering** - assigned once content is replaced and removed when all css animations are done
* **is-changing** - assigned once link is clicked and remove whe all css animations are done
* `is-animating` - This class is assigned to the html tag once link is clicked and is removed shortly after the content of the page is replaced. (used for defining styles for an unloaded page)
* `is-changing` - Assigned once a link is clicked and removed when the whole process of transition of pages is done. (used for showing some loading)
* `is-leaving` - Assigned once a link is clicked and removed right before the content is replaced. (just in case.. maybe different animations for in/out transition?)
* `is-rendering` - Assigned right before the content is replaced and removed when the whole process of transition of pages is done. (same as above)
`is-animating` is the main class you should worry about, as it enables the animations. `is-leaving` and `is-rendering` can be used for defining different animations for animating the elements in/out. `is-changing` may be used for displaying some kind of loading while the transition is being done.
### Example
While developing the site, simply define the elements that are being animated and need to be replaced. Lets assume we want to fade in/out the main content of the page.
While developing the site, simply define the elements that are being animated and need to be replaced. Let's assume we want to fade in/out the main content of the page.
```html

@@ -52,3 +81,3 @@ <html>

First thing we need to do is enable swup.
The first thing we need to do is enable swup.
```javascript

@@ -59,9 +88,12 @@ import Swup from 'swup'

Add the `swup` id to the main element in html so it is replaced with the main element of the loaded page. Also add class that handles animations of the element - `a-fade`.
Add the `swup` id to the main element in HTML so it is replaced with the main element of the loaded page. Also, add the class that handles animations of our faded element - `a-fade`.
```html
<main id="swup" class="a-fade">
...
</main>
<div class="a-fade">
<main id="swup">
...
</main>
</div>
<div class="loading">We are loading...</div>
```
Add your css for the element transition.

@@ -77,3 +109,4 @@ ```css

```
If you'd like to display the loading element while the transition is done, css would be...
In case you'd like to display the loading element while the transition is done, css would be...
```css

@@ -87,10 +120,13 @@ .loading {

```
And that's it! Swup loads the page, handles classes for the css animation, waits for the animation to finish/page to load, replaces content and fades your content back. Swup also changes title of your page to the loaded one, and exchanges classes of body element (more in options section).
And that's it, we're all set, or at least for our fade in/fade out example.
In some cases there is a need to animate elements that are common for all pages, but may for example display or hide for some pages, change color or whatever.. Let's assume we want navigation to change background color for different pages, based on body class. In that case you would usually like to start the animation on the click of the link, instead of when the next page is loaded. For this purpose there is special class added to your html tag on transition start and removed once the process of page transition is done.
This special class takes form of `to-{whatever is the route of new page}`, where only exception is homepage, which does not have any route and so `to-homepage` is used.
Swup loads the page, handles classes for the css animation, waits for the animation to finish/page to load, replaces content and fades your content back. Swup also changes the title of your page to the loaded one, and exchanges classes of body element (more in [options](#options) section).
Animation to dynamic pages with unknown routes (blog posts, etc.) can be animated to using data attribute `data-swup-class` set on link element. Swup takes the content of the attribute of clicked link and adds class name on html tag in a format `to-{content of the attribute}`, and also removes it after the whole process of routing is done. So for blog posts, you would want to add `data-swup-class="blog-post"`, which would be added to html tag as `to-blog-post`.
### Example of different transitions for different pages
In case you would like to animate the state of an element that stays on the page, but only changes it's style based on the page you're visiting, we've got you covered as well. Let's assume we want our navigation to change the background color for different pages, based on body class. In that case, you would probably like to start the change of background on the click of the link, but we can't really know what is the next body class going to be before the content of next page is loaded. For this purpose, there is special class added to your html tag on transition start and removed once the process of page transition is done.
This special class takes form of `to-{route of next page in URL friendly form}`, where the only exception is the homepage, which does not have any route and so `to-homepage` is used.
Let's assume we want our header to be blue on homepage (/), but yellow in about (/about) page.
In case we want to use same feature with dynamic pages with unknown routes (blog posts, etc.) data attribute `data-swup-class` set on link element will do the trick. Swup takes the content of the attribute of clicked link and adds class name on html tag in a format `to-{content of the attribute}`, and also removes it after the whole process of transition is done (so for blog posts, you would want to add something like `data-swup-class="blog-post"` on the link, which would result in `to-blog-post` class on html tag).
More practical example - let's assume we want our header to be blue on the homepage (/), but yellow in the about (/about) page.
```css

@@ -107,2 +143,3 @@ header {

```
For the color to start changing right after the click on the link, simply add...

@@ -117,3 +154,3 @@ ```css

```
**Note:** For popState events the process is disabled and the content of page is replaced right away, to avoid tedious back button clicking and ensure proper functionality on mobile devices.
**Note:** For popState events (back/forward) the process is disabled and the content of the page is replaced right away, to avoid tedious back button clicking and ensure proper functionality on touch devices (back/forward on horizontal drag).

@@ -128,12 +165,17 @@ ## Options

### Link Selector
Link selector defines link elements that will trigger the transition. Default form is shown below.
Link selector defines link elements that will trigger the transition. By default, the selector takes any link with `href` attribute starting with `/`, `#` or with `xlink` attribute for SVG elements. The raw selector form is shown below.
```javascript
LINK_SELECTOR: 'a[href^="/"]:not([data-no-swup]), a[href^="#"]:not([data-no-swup]), a[xlink\\:href]'
```
In case you want to exclude links for some routes, lightbox or any other functionality, simply extend the selector. By default, you can simply add **data-no-swup** attribute if you want to exclude just a few.
In case you want to exclude links for some routes, lightbox or any other functionality, simply extend the selector. By default, you can simply add `data-no-swup` attribute to the link, if you want to exclude just a few.
**Note:** it is recommended to disable transition between language versions of your site, for multiple reasons (replacing of header/footer, analytics...).
**Tip:** In most cases, it is good to disable transition between language versions of your site for multiple reasons - replacing of header/footer, analytics, etc.
### Elements
Elements option defines the array of elements to be replaced. Elements option usually contains the main element with content of the page. However, elements can include any element that is common for all transitioned pages. Example of such additional element is the "change language" link, which appears the same across site, but leads to a different link on each page. Option defaults to the single element of id `#swup`.
Elements option defines the array of selectors of elements to be replaced.
Elements option usually contains the main element with the content of the page.
However, elements can include any element that is common for all transitioned pages.
This creates a possibility of animating elements on the page while still replacing it's parts.
Another good example is the "change language" link, which usually appears the same across the site, but leads to a different URL on each page.
Option defaults to the single element of id `#swup`.
```javascript

@@ -146,3 +188,3 @@ options = {

### 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^='a-']`, which selects all elements with class attribute beginning with prefix `a-`.
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^='a-']`, which selects all elements with class attribute beginning with prefix `a-`.
```javascript

@@ -153,3 +195,3 @@ animationSelector: '[class^="a-"]'

### Cache
Swup has a built in cache, meaning that it stores previously loaded contents of the pages in memory in a form of object. This drastically improves speed for static sites, but should be disabled for dynamic sites. Cache option defaults to `true`.
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`.
```javascript

@@ -159,11 +201,18 @@ cache: true

### Preload
When enabled, swup starts loading the page on hover of the link and does not wait for the user to click. In case the page is not loaded at the time of clicking on the link, swup simply waits for the request to finish and does not create a new request. Also, swup only creates one preload request at the time, so your server won't be overwhelmed by people just passing their cursor through some grid of links.
If cache is disabled, swup still preloads pages of hovered links, but the content of cache is removed after each page transition.
In case you want to preload some page automatically without any trigger by the user, `data-swup-preload` on the link will do the trick.
```javascript
preload: true
```
### Page Class Prefix
Css styles are very often based on the class of the page defined in body element. Swup replaces the body classes for each loaded page. However, the site may use the body class attribute for functionality such as opening of some sort of menu by adding class to the body element. In that case, you may want to define a prefix for your page style classes such as `page-`, so only those are replaced. By default option is set to `''` and all classes of body element are replaced during the transition. In case of no classes are used on body element, simply set option to `false`.
Some CSS styles are very often based on the class of the page defined in the body element. Swup replaces the body classes for each loaded page. However, the site may use the body class attribute for functionality such as opening of some sort of menu by adding class to the body element. In that case, you may want to define a prefix for your page style classes such as `page-`, so only those are replaced. By default option is set to `''` and all classes of body element are replaced during the transition.
```javascript
pageClassPrefix: 'page-'
pageClassPrefix: ''
```
### Scroll
Swup has a built in scroll control, where page smoothly scrolls to the top on desktop, and jumps directly to the top on mobile. Scroll to the anchor elements in url are also handled. This feature can be turned off and you can use your own scroll based on the emitted events discussed in events section. By default the option is set to `true`. Scrolling has several other options, such as `scrollDuration` - duration of the scroll, which is set to 0 by default (expects the page to be fully invisible while transitioning). Another options are `animateScrollToAnchor` and `animateScrollOnMobile`, where the name speaks for itself. Last is `doScrollingRightAway`, which determines whether scroll starts immediately after click on link, or after the content is replaced.
Swup has a built-in scroll control. Scroll to the anchor element in URL is also handled. This feature can be turned off and you can use your own scroll based on the emitted events discussed in [events](#events) section. By default, the option is set to `true`.
```javascript

@@ -174,3 +223,4 @@ scroll: true

### Support
Due to the use of promises, transitionEnd and pushState features of javascript, swup has a basic support check built in to avoid breaking of the site in case of older browser that do not support used features. However, as there may always be some exceptions for browsers, or different polyfills may be used on page (that may or may not work), this support check can be disabled and you can use your own support check before creating the instance. Support option is enabled by default.
Due to the use of promises, transitionEnd and pushState features of JavaScript, swup has a basic support check built in to avoid breaking of the site in case of an older browser that doesn't support used features.
However, as there may always be some exceptions for browsers or polyfills can be used on the page (that may or may not work), this support check can be disabled and you can use your own support check before creating the instance. Support option is enabled by default.
```javascript

@@ -180,12 +230,4 @@ support: true

### Preload
Preload is an additional feature that can be used in combination with cache. When enabled, swup starts loading the page on hover of the link and does not wait for the user to click on the link. In case the page is not loaded at the time of clicking on the link, swup simply waits for the request to finish and does not create new request. Also, swup only creates one request at the time, so don't worry, your server won't be overwhelmed by few people just passing their cursor through some grid of links.
If cache is disabled, swup still preloads pages of hovered links, but the contents of cache are removed after each page transition.
In case you want to preload some page automatically without any trigger by user, `data-swup-preload` on the link will do the trick.
```javascript
preload: true
```
### Disable IE
While swup itself should run without problem in IE Edge (or other IE with help of some polyfills), I have ran into multiple problems on IE (including Edge), related to updating browser history, replacing large parts of page with javascript or performance of animation on large elements. That's why swup allows to simply disable the whole thing in all IE browsers with `disableIE` option. Swup is enabled in IE by default.
While swup itself should run without problem in IE Edge (or other IE with help of some polyfills), I have encountered multiple problems on IE (including Edge) in some particular situations, related to updating browser history, rendering large parts of page replaced with javascript or performance of animation on large elements. That's why swup allows to simply disable the whole thing in all IE browsers with `disableIE` option. This option is intended as a last resort to save your computer from physical damage caused by an angry developer. Swup is enabled in IE by default.
```javasrripts

@@ -196,3 +238,3 @@ disableIE: false

### Debug Mode
Debug mode is very useful for integrating swup into your site. When enabled, swup displays emitted events (see events section) in console, as well as contents of the cache when changed. Option defaults to false.
Debug mode is useful for integrating swup into your site. When enabled, swup displays emitted events (see [events](#events) section) in the console, as well as contents of the cache when changed. Swup instance is also accessible globally as `window.swup` in debug mode. Option defaults to false.
```javasrripts

@@ -202,3 +244,3 @@ debugMode: false

### Example with default values
### Default values
```javascript

@@ -217,7 +259,3 @@ let options = {

support: true,
disableIE: false,
animateScrollToAnchor: false,
animateScrollOnMobile: false,
doScrollingRightAway: false,
scrollDuration: 0,
disableIE: false
}

@@ -227,3 +265,3 @@ ```

## Events
As it usually is when loading page with JS, there may be many constrains such as analytics or enabling the scripts for replaced content. For this purpose, swup emits whole bunch of events triggered on document while working, which can be used as follows:
As we are replacing the native functionality of the browser, there may be some constraints related to that. For this purpose, swup emits bunch of events triggered on the document while working. We can use those events to enable our JavaScript, trigger some analytics, etc.
```javascripts

@@ -241,4 +279,4 @@ // trigger page view for GTM

document.addEventListener('swup:contentReplaced', event => {
swup.options.elements.forEach((element) => {
loadComponents(document.querySelector(element))
swup.options.elements.forEach((selector) => {
// load scripts for all elements with 'selector'
})

@@ -251,4 +289,4 @@ });

* **swup:pageView** - similar as previous, except it is once trigger on load of the page
* **swup:hoverLink** - triggers when link for transition is hovered
* **swup:clickLink** - triggers when link for transition is clicked
* **swup:hoverLink** - triggers when link is hovered
* **swup:clickLink** - triggers when link is clicked
* **swup:animationOutDone** - triggers when transition of all animated elements is done (after click of link and before content is replaced)

@@ -265,16 +303,23 @@ * **swup:pagePreloaded** - triggers when the preload of some page is done

## API
Instance of the swup can be imported and used across your sites javascript to enable some additional features. When debugMode (see options section) is enabled, instance is also available in `window` object as `window.swup` so you can play with it.
You can for example access some of the information used by swup such as the elements to be replaced:
The instance of the swup can be imported and used across your sites JavaScript to enable some additional features. When debug mode (see [options](#options) section) is enabled, instance is also available in `window` object as `window.swup`.
We can access some of the information used by swup such as used options:
```javascript
swup.options.elements.forEach((element) => {
swup.options.elements.forEach((selector) => {
// do whatever for each replaced element
})
swup.options.cache; // true/false
```
or use built in function for your own stuff
or change options
```javascript
// enable cache
swup.options.cache = true;
```
or use built in functions
```javascript
// navigates to /someRoute with the animations and all...
swup.loadPage('/someRoute', false)
// or disable swup
// disable swup
swup.destroy()
```
Sky is the limit here.

@@ -281,0 +326,0 @@ 

.idea/workspace.xml

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc