@barba/core

Barba core manages your page transitions with ease.

Syntax

barba.init(<options>)

<transition> object

name

An optional name for your transition.

Example:

1
2
3
4
5
6
7
8
9
10
11

import barba from '@barba/core';

barba.init({
  transitions: [{
    name: 'svg-circle',
    ...
  }, {
    name: 'svg-slide',
    ...
  }]
});

Hooks

All hooks are methods and receive the same data object.

“Hooks can be run either synchronously or asynchronously using the common this.async() style (see run-async) or returning a promise.

If you use sync: true, as leave and enter will be concurrent, order will differ: all before*, then enter/leave, then all after*.

Note that you can define global hooks using barba.hooks and apply it to all your transitions.

Example:

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

import barba from '@barba/core';

// defines a global hook
barba.hooks.leave((data) => {
  // this hook will be called for each transitions
});

barba.init({
  transitions: [{

    // basic style
    leave(data) {
      // create your stunning leave animation here
    },

    // async/await style
    async leave(data) {
      await asyncAnimation(data.current.container);
    },

    // `this.async()` style
    leave(data) {
      const done = this.async();

      callbackAnimation(data.current.container, {
        onComplete: () => {
          done();
        },
      });
    },

    // using a promise, returned with arrow function
    leave: (data) => asyncAnimation(data.current.container),

    // es6 syntax: `{ current } = data.current`
    leave: ({ current }) => asyncAnimation(current.container);,

    // using a promise
    leave(data) => {
      return new Promise(resolve => {
        callbackAnimation(data.current.container, {
          onComplete: () => {
            resolve();
          },
        });
      });
    },

  }]
});

data argument

Data argument is an object passed to all transition hooks, view hooks subset and custom rules.

current/next properties

Properties attached to data.current and data.next objects.

Depending on rules, sync mode or cache availability, some properties can be undefined.

url properties

Properties attached to data.current.url and data.next.url objects.

route properties

Properties attached to data.current.route and data.next.route objects.

route is available with @barba/router

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

import barba from '@barba/core'

barba.init({
  transitions: [
    {
      name: 'svg-circle',
      leave(data) {
        // retrieves the current page url
        const from = data.current.url
      },
      enter({ next }) {
        // retrieves the next page url (short syntax)
        const to = next.url
      },
    },
  ],
})

Rules

Rules define the transition resolution, concretely “selecting the right transition to use”.
You can combine multiple rules on each transition.

Any rules can be used within from and/or to properties.

Notice that you can use from and to properties independently.

Example:

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

import barba from '@barba/core';

barba.init({
  transitions: [{
    name: 'custom-transition',
    from: {

      // defines a custom rule based on the trigger class
      custom: ({ trigger }) => {
        return trigger.classList && trigger.classList.contains('use-custom-transition');
      },

      // defines rule based on multiple route names
      route: [
        'index',
        'product'
      ]
    },
    to: {

      // defines rule based on multiple namespaces
      namespace: [
        'home',
        'item'
      ]
    }
  }, {
    name: 'other-transition',
    ...
  }]
});

In this example, based on the priority order, Barba will use the custom-transition:

• if the link you clicked contains a .use-custom-transition CSS class
• if you come from the index or product route
• if you are navigating to the home or item namespace AND from the index or product route

Priority

The transition resolution follows this order:

1. Rule(s) priority
2. from and/or to priority
3. Declaration order

The common/default behaviour is to start leave as soon as possible.
enter will be called when leave ends AND next page is “available” (fetched or cached).
If you use some to logic, Barba can not predict and select the right transition until the next page is available.
This also applies when using sync: true.
But this does not apply if to is used with route property because “next route” is known when the click occurs…

Bear with this!

Sync mode

A mode that indicate whether leave and enter hooks should “play together”.
This involves waiting until the next page is available (fetched or cached).

By default the sync mode is set to false.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

import barba from '@barba/core'

barba.init({
  transitions: [
    {
      sync: true,
      leave() {
        // transition that will play concurrently to `enter`
      },
      enter() {
        // transition that will play concurrently to `leave`
      },
    },
  ],
})

<view> object

Views allow you to have some logic related to the content of a namespace.
You can see it as “lifecycle” into Barba. It is a good place to init or destroy things…
They use a subset of transition hooks and receive the same data object.

Available hooks are:

• beforeAppear
• afterAppear
• beforeLeave
• afterLeave
• beforeEnter
• afterEnter

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

import barba from '@barba/core'

barba.init({
  views: [
    {
      namespace: 'index',
      beforeLeave(data) {
        // do something before leaving the current `index` namespace
      },
    },
    {
      namespace: 'contact',
      beforeEnter(data) {
        // do something before entering the `contact` namespace
      },
    },
  ],
})

debug

Useful console.info about transition used, for debugging purpose only.
It sets logLevel to debug. Default is off.

Example:

1
2
3
4
5

import barba from '@barba/core'

barba.init({
  debug: true,
})

logLevel

1
2
3
4
5

0. off
1. error   = console.error()
2. warning = console.warn()
3. info    = console.info()
4. debug   = console.log()

schema

Allows you to override data attributes. See default schemaAttribute.

Example:

1
2
3
4
5
6
7
8

import barba from '@barba/core'

barba.init({
  // overrides defaults and create a custom prefix for wrapper, containers, etc.
  schema: {
    prefix: 'data-custom',
  },
})

cacheIgnore

Allows Barba to cache your pages.

Saving pages in the cache result in less bandwidth usage and less server-side load: no XMLHttpRequest are made for pages that have already been visited.

If disabled, Barba will retrieve each page from the server on every request: this could be useful if your page contains scripts that need to be evaluated on each page call.

You can also define “route” pattern(s) (see @barba/router).

Cache lifetime is restricted to Barba instance and will be cleared when leaving the site.

Example:

1
2
3
4
5

import barba from '@barba/core'

barba.init({
  cacheIgnore: ['/contact/', '/:category/post?'],
})

prefetchIgnore

Allows Barba to prefetch your pages on mouseover or touchstart events.

Since there is a 100-300ms delay during the user hover and the click, Barba is using this time to start prefetching the next page. Most of the time this dead time is enough to get the next page ready!

If follows the same logic as the above cacheIgnore option…

To prefetch all eligible links that enter the viewport, use the @barba/prefetch module.

Example:

1
2
3
4
5

import barba from '@barba/core'

barba.init({
  prefetchIgnore: false,
})

prevent

Allows you to add a custom “prevent” test.
If your function returns true, Barba will not be enabled.

Example:

1
2
3
4
5
6
7

import barba from '@barba/core'

barba.init({
  // defines a custom function that will prevent Barba
  // from working on link that contains a `prevent` CSS class
  prevent: ({ el }) => el.classList && el.classList.contains('prevent'),
})

Note that you can prevent a link of using Barba with the data-barba-prevent attribute:

1. data-barba-prevent or data-barba-prevent="self" prevents the current link
2. data-barba-prevent="all" prevents all children links of a container (div, p, etc.)

requestError

Allows you to catch request errors.
If this function returns false, wrong links will not be “force” triggered.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

import barba from '@barba/core'

barba.init({
  requestError: (trigger, action, url, response) => {
    // go to a custom 404 page if the user click on a link that return a 404 response status
    if (action === 'click' && response.status && response.status === 404) {
      barba.go('/404')
    }

    // prevents Barba from redirecting the user to the requested URL
    // this is equivalent to e.preventDefault()
    return false
  },
})

Note that if you use barba.go() directive without returning false, you will be redirected to the requested URL because Barba uses barba.force() to reach the page.

Partial output

Barba sends a custom HTTP Header named x-barba in the XMLHttpRequest.

If you are using a server side language like PHP, you can detect this custom HTTP Header and output just the container instead of the entire page: this could result in less bandwidth usage and less server-side load.

Note that doing so, you have to manually handle the upate of the page title.