Transitions

Barba allows you to define a global transition, that run everywhere on your site, and/or specific transitions using rules that run when navigating from one page to another.

They use all base hooks.

Summary

1. Syntax
2. Rules
3. Self
4. Sync mode

Syntax

1
2
3
4
5
6
7
8
9
10
11

barba.init({
  transitions: [{
    name: 'default-transition',
    leave() {
      // create your stunning leave animation here
    },
    enter() {
      // create your amazing enter animation here
    }
  }]
});

transition name is optional, but recommended.

Rules

Rules define the “transition resolution”, concretely “selecting the right transition to use”.
This allows you to create specific transitions, based on namespace, route or custom logic.

They are made of keyword(s) and condition(s).

Keyword(s)

Rules keyword(s) define the logic to follow, if your transition should play when leaving the current.container, using from, and/or when entering the next.container, using to:

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

barba.init({
  transitions: [{
    name: 'custom-transition',
    from: {
      // set of conditions to be fulfilled
      // to play the transition
    },
    to: {
      // set of conditions to be fulfilled
      // to play the transition
    }
  }]
});

They must contain a set of condition(s), and run within a priority order:

Note that you can use from and to properties independently.

Condition(s)

Rules condition(s) define the logic to fulfilled inside keyword(s) in order to play the transition.

They are defined within keyword(s):

1
2
3
4
5
6
7
8
9
10

barba.init({
  transitions: [{
    name: 'custom-transition',
    from: {
      namespace: [
        'home'
      ]
    }
  }]
});

Condition(s) can be applied to a namespace, route or through a custom function.
Barba will then select the right transition to use and play it only if all conditions are fulfilled.

Any conditions can be used within from and/or to keywords.

Priority

The “transition resolution” follows this steps:

1. Condition(s) priority
2. Keyword(s) priority
3. Declaration order

The common/default behaviour is to start leave as soon as possible.
Then 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 the sync mode, but this does not apply if to is used with route property because “next route” is known when the click occurs.

Bear with this!

Multiple rules

You can combine multiple rules on each transition.
Here is an example of what you could do with multiple rules:

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

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

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

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

      // define rule based on multiple namespaces
      namespace: [
        'home',
        'item'
      ]
    }
  }]
});

Based on the priority order, Barba will play the custom-transition:

• if the link you clicked on 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

Self

Barba have an internal mechanism called “self transition”: it allows you to call a transition when navigating into the same page. Just define a transition with the “magic” name self, then links that point to your current page, like page.html#hash, will call this specific transition.

1
2
3
4
5
6

transitions: [{
  name: 'self',
  enter() {
    // create your self transition here
  },
}]

Like a regular transition, this one can use all base hooks.

Sync mode

A mode that indicates whether leave and enter hooks should “play together”.
The sync mode is disabled by default, but you can easily enable it using the sync option:

1
2
3
4
5
6
7
8
9
10
11

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

This involves waiting until the next page is available: fetched or cached.

In another words, regarding the legacy example, if you have an opacity transition from 1 -> 0 for leave and 0 -> 1 for enter:

• sync: false will play the leave transition first, making your page content goes transparent, then play the enter transition, making the next page content goes opaque (two step transition)

This will immediately run the before, beforeLeave and leave hooks on user click, then it will wait for the next page to be “ready” (prefetched) in order to run the enter transition with the other hooks.

• sync: true will make the current page goes transparent while the next page becomes opaque at the same time (crossfade transition)

This will do nothing on user click, even if doing something inside before or beforeLeave hooks, this mode will always wait for the next page to be “ready” (prefetched) in order to run both leave/enter transitions.