Strategies

Barba implement modern browser strategies to keep your site run as fast as possible.

Summary

1. Cache
2. Prefetch
3. Prevent
4. History

Cache

cacheIgnore

Allows Barba to cache your pages.

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

Use it like this:

1
2
3

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

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

cacheFirstPage

Allows Barba to cache the first rendered page.

In some situations it is useful to cache that page, but most time it is worse to cache the rendered HTML, because it may be modified by other scripts and those scripts have to deal with the cached page later.

Use it like this:

1
2
3

barba.init({
  cacheFirstPage: true
});

barba.cache

When cache is enabled, Barba internally use a cache instance to store cache data of all pages.

Cache data

Using the internal cache.get(url) method, you can easily retrieve cache informations for a specified URL.
Useful in some situations when you need to know request status and progression during a page transition.

It returns a ICacheData object:

See Cache module API documentation to learn more.

Cache target

The cache target contains the targetted URL of the page.

In case of 301 redirection, Barba cares of keeping in the cache the server reseponseURL instead of the requested one. In addition, the browser URL will be properly updated.

Note that if you start prefetching a URL that have a 301 redirection, cache target will be set based on the requested URL since cache status is in “pending” mode. After cache status switch to “fulfilled”, the cache target will contain the final response URL.

Prefetch

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 use this time to start prefetching the next page. Most of time, this is enough to get the next page ready.

Use it like this:

1
2
3

barba.init({
  prefetchIgnore: '/home/'
});

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

Prefetch URL

You can programmatically prefetch some URLs using the barba.prefetch code method:

1

barba.prefetch('about.html');

Note that all prefetched URLs are stored absolute in the barba.cache: if you prefetch about.html, it will be stored in the cache as https://localhost/about.html instead. This prevent caching twice the same page if you omit to prefix your URLs in the output.

Prevent

preventRunning

Tells Barba to prevent page “force reload” when the user clicks on an eligible link during a transition is running.
This option is useful if you don’t want your users to break running transitions, especially if they are long.

1
2
3

barba.init({
  preventRunning: true
});

You can also programmatically check if a transition is running using barba.transitions.isRunning whenever you want in your code.

prevent

Allows you to add a custom “prevent” test on eligible links.
If this function returns true, Barba will be disable for links that pass the test.

1
2
3
4
5

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

Note that you can prevent a link from 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 in a container (div, p, etc.)

History

barba.history

While browsing the website, Barba stores useful navigation informations into the history property. You can access those informations at any time in your application.

history.previous|current

The most useful are the previous and current history attributes. It allows you to access the page namespace, the window scroll position and the page url. For example, if you want to restore scroll position between pages, have a look at the scroll position recipe.

They both shares the same set of properties.

Be careful, barba.history.previous object equals null when your application is starting.

history.add

This method bring the ability to programmatically push or replace history entries to easily keep the history up to date in your application based on user interaction.

1
2
3
4
5

// push a new entry in the history
history.add('push.html', 'barba', 'push');

// replace a history entry
history.add('replace.html', 'barba', 'replace');

See History utility API documentation to learn more.

history.store

In some situation, you may need to store custom information based on user navigation and access them later in your code. Barba now offer a way of doing this with ease using the barba.history.store method.

1
2
3
4
5

barba.history.store({
  id: 2547,
  random: Math.random(),
  href: window.location.href,
});

Be careful, data will be overwritten if you call twice the store method with the same data attribute.

Then later in the code, after a page transition, you can access your custom data from the previous page:

1
2
3

const id = barba.history.previous.data.id;
const random = barba.history.previous.data.random;
const href = barba.history.previous.data.href;

As it’s using replaceState API under the hood, data are automatically rolled within the history, meaning if you call the store method before a page transition, the custom data will be stored inside history.current, then after a page transition, data will be available inside history.previous while history.current stay empty until you put something inside it.

data-barba-history

Sometimes, you may want to “alter” the browser history by replacing the current entry without having to push a new one. This can easily be done with the data-barba-history="replace" attribute.

In the example below, if you come from the index page and click on black link, the barba.history.previous will equal index while barba.history.current will equal black. Clicking on white will replace the current black entry with the white one, while the previous entry remains intact and equal to index.

1
2

<a href="/theme?color=black" data-barba-history="replace">black</a>
<a href="/theme?color=white" data-barba-history="replace">white</a>

The default Barba behavior for history is push, so you don’t have to manually write data-barba-history="push" on all your links.