barba.js [v2]

stability-beta
CircleCI
Coverage Status
Commitizen friendly
Conventional Commits
License
Slack channel

Barba.js is a small (7kb minified and compressed) and easy-to-use library that helps you creating fluid and smooth transitions between your website’s pages.

It helps reducing the delay between your pages, minimizing browser HTTP requests and enhancing your user’s web experience.

Notice: this guide assumes intermediate level knowledge of HTML, CSS, and JavaScript. It is worth mentioning that all the code examples use ES6+ syntax. If you are not comfortable with, we encourage you to grasp the basics then come back.

In case of emergency, check this “legacy” code example.

Install

Using npm:

1
npm install @barba/core

or using yarn:

1
yarn add @barba/core

or using a CDN:

1
<script src="https://unpkg.com/@barba/core"></script>

Getting started

See @barba/core for more details…

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
// do not import Barba like this if you load the library through the browser
import barba from '@barba/core';

// basic default transition (with no rules and minimal hooks)
barba.init({
  transitions: [{
    leave({ current, next, trigger }) {
      // do something with `current.container` for your leave transition
      // then return a promise or use `this.async()`
    },
    enter({ current, next, trigger }) {
      // do something with `next.container` for your enter transition
      // then return a promise or use `this.async()`
    }
  }]
});

// dummy example to illustrate rules and hooks
barba.init({
  transitions: [{
    name: 'dummy-transition',

    // apply only when leaving `[data-barba-namespace="home"]`
    from: 'home',

    // apply only when transitioning to `[data-barba-namespace="products | contact"]`
    to: {
      namespace: [
        'products',
        'contact'
      ]
    },

    // apply only if clicked link contains `.cta`
    custom: ({ current, next, trigger })
      => trigger.classList && trigger.classList.contains('cta'),

    // do leave and enter concurrently
    sync: true,

    // available hooks…
    beforeAppear() {},
    appear() {},
    afterAppear() {},
    beforeLeave() {},
    leave() {},
    afterLeave() {},
    beforeEnter() {},
    enter() {},
    afterEnter() {}
  }]
});

Browser support

Barba.js can be viewed as a progressive enhancement.
Main “modern features” used are:

@barba/prefetch also uses IntersectionObserver

Cross-browser support is as follows:

  • without polyfills: modern browsers (Chrome, Firefox, Edge, Safari, Opera)
  • with polyfills for abovementioned: + IE10

You can use polyfill.io:

1
2
3
4
<script
  crossorigin="anonymous"
  src="https://polyfill.io/v3/polyfill.min.js?features=default%2CArray.prototype.find%2CIntersectionObserver"
></script>

or implement your own solution (es6-promise and Core.js or es6-shim, …).

Markup