Recipes

Debug with Barba

debug

This property displays useful console.info about transition used, for debugging purpose only.
It sets logLevel to debug. Default is off.

Enable it like this:

1
2
3
barba.init({
debug: true
});

We recommend you to enable the debugger only in development environment to properly catch transition errors.

logLevel

When debugging with Barba, you can easily set the log level of debug informations that the browser display:

  • off → log is disabled
  • error → use console.error()
  • warning → use console.warn()
  • info → use console.info()
  • debug → use console.log()

Use this syntax to adjust the log level:

1
2
3
barba.init({
logLevel: 'error'
});

Manage containers

During a page transition, Barba use two data-barba="container" to discern current and next page, leading the wrapper to contain both at the same time until the transition is done. In order to make a fluent transition and prevent containers to be badly positioned, use one of this mechanism:

  • default: do nothing and let Barba remove the container itself
  • data.current.container.remove(): manually remove the current container when you need to, this is useful if you need to “clean” the DOM before calling some custom scripts
  • position: absolute: keep containers superimposed, this is useful when making a sync (crossfade) transition

Scroll position

After a page transition, the browser won’t “hard reload” the current tab, meaning that you will need to “reset” the scroll position before entering a new page. This can be easily done using a global hook.

Wait… my browser still continue to restore the scroll position when I am using backward/forward buttons, why? Because this is the default behavior in most modern browsers. To disable it, you will need to set the scroll restoration to be “manual” instead of “auto”:

1
2
3
if (history.scrollRestoration) {
history.scrollRestoration = 'manual';
}

Note that some third party plugins like LocomotiveScroll implement this feature.

If you need to restore the scroll position while history.scrollRestoration is enabled, you can store the x/y scroll position using the Barba history object, like this:

1
2
3
4
5
6
7
8
9
10
let scrollX = 0
let scrollY = 0

barba.hooks.leave(() => {
scrollX = barba.history.current.scroll.x;
scrollY = barba.history.current.scroll.y;
});

// then later in the code...
window.scrollTo(scrollX, scrollY);

Manage browser requests

requestError

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

Argument Type Description
trigger HTMLElement The clicked/hovered HTMLElement
String 'barba' Programmatic navigation
String 'back' | 'forward' Browser backward/forward button
action String The user action on the link: 'enter' when hovering, 'click' when clicking, or 'prefetch' when prefetching with @barba/prefetch
url String Requested URL
response Object Fetch error with message or response with status, statusText, etc.

Here is an example to manage 404 server responses with a custom page:

1
2
3
4
5
6
7
8
9
10
11
12
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');
}

// prevent Barba from redirecting the user to the requested URL
// this is equivalent to e.preventDefault() in this context
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.

timeout

On slow network or with a high page weight, the server can take time to give a response to the user. In case the page take more than timeout to be loaded, it lead Barba to abort the transition and display a Timeout error message.

To prevent this behavior, you can increase the timeout:

1
2
3
barba.init({
timeout: 5000
});

In addition, you can properly catch the error by using the requestError callback.

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.

1
2
3
4
5
6
7
8
<?php
// check for the server side x-barba request header
if (isset($_SERVER['HTTP_X_BARBA'])) {

// this content will only be displayed if the page is called with BarbaJS
echo "I ❤ Barba";
}
?>

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