Barba JS

Barba.js

Modern page transition library for creating fluid, smooth transitions between website pages. Barba.js makes multi-page websites feel like Single Page Applications (SPAs) by hijacking navigation and managing transitions without full page reloads.

Overview

Barba.js is a lightweight (7kb minified and compressed) JavaScript library that intercepts navigation between pages, fetches new content via AJAX, and smoothly transitions between old and new containers. It reduces page load delays and HTTP requests while maintaining the benefits of traditional multi-page architecture.

Core Features:

• Smooth page transitions without full reloads
• Lifecycle hooks for precise control over transition phases
• View-based logic for page-specific behaviors
• Built-in routing with @barba/router plugin
• Extensible plugin system
• Small footprint and high performance
• Framework-agnostic (works with vanilla JS, GSAP, anime.js, etc.)

Core Concepts

1. Wrapper, Container, and Namespace

Barba.js uses a specific DOM structure to manage transitions:

HTML Structure:

<body data-barba="wrapper">
  <!-- Static elements (header, nav) stay outside container -->
  <header>
    <nav>
      <a href="/">Home</a>
      <a href="/about">About</a>
    </nav>
  </header>

  <!-- Dynamic content goes in container -->
  <main data-barba="container" data-barba-namespace="home">
    <!-- This content changes on navigation -->
    <h1>Home Page</h1>
    <p>Content that will transition out...</p>
  </main>

  <!-- Static footer outside container -->
  <footer>© 2025</footer>
</body>

Three Key Elements:

1. Wrapper (data-barba="wrapper")

• Outermost container
• Everything inside wrapper but outside container stays persistent
• Ideal for headers, navigation, footers that don't change

1. Container (data-barba="container")

• Dynamic content area that updates on navigation
• Only this section gets replaced during transitions
• Must exist on every page

1. Namespace (data-barba-namespace="home")

• Unique identifier for each page type
• Used in transition rules and view logic
• Examples: "home", "about", "product", "blog-post"

2. Transition Lifecycle

Barba.js follows a precise lifecycle for each navigation:

Default Async Flow:

1. User clicks link
2. Barba intercepts navigation
3. Prefetch next page (via AJAX)
4. Cache new content
5. Leave hook - Animate current page out
6. Wait for leave animation to complete
7. Remove old container, insert new container
8. Enter hook - Animate new page in
9. Wait for enter animation to complete
10. Update browser history

Sync Flow (with sync: true):

1. User clicks link
2. Barba intercepts navigation
3. Prefetch next page
4. Wait for new page to load
5. Leave and Enter hooks run simultaneously (crossfade effect)
6. Swap containers
7. Update browser history

3. Hooks

Barba provides 11 lifecycle hooks for controlling transitions:

Hook Execution Order:

Initial page load:
  beforeOnce → once → afterOnce

Every navigation:
  before → beforeLeave → leave → afterLeave →
  beforeEnter → enter → afterEnter → after

Hook Types:

• Global hooks: Run on every transition (barba.hooks.before())
• Transition hooks: Defined within specific transition objects
• View hooks: Defined within view objects for page-specific logic

Common Hook Use Cases:

• beforeLeave - Reset scroll position, prepare animations
• leave - Animate current page out
• afterLeave - Clean up old page
• beforeEnter - Prepare new page (hide elements, set initial states)
• enter - Animate new page in
• afterEnter - Initialize page scripts, analytics tracking

4. Views

Views are page-specific logic containers that run based on namespace:

barba.init({
  views: [{
    namespace: 'home',
    beforeEnter() {
      // Home-specific setup
      console.log('Entering home page');
    },
    afterEnter() {
      // Initialize home page features
      initHomeSlider();
    }
  }, {
    namespace: 'product',
    beforeEnter() {
      console.log('Entering product page');
    },
    afterEnter() {
      initProductGallery();
    }
  }]
});

Common Patterns

1. Basic Setup

Installation:

npm install --save-dev @barba/core
# or
yarn add @barba/core --dev

Minimal Configuration:

import barba from '@barba/core';

barba.init({
  transitions: [{
    name: 'default',
    leave({ current }) {
      // Fade out current page
      return gsap.to(current.container, {
        opacity: 0,
        duration: 0.5
      });
    },
    enter({ next }) {
      // Fade in new page
      return gsap.from(next.container, {
        opacity: 0,
        duration: 0.5
      });
    }
  }]
});

2. Fade Transition (Async)

Classic fade-out, fade-in transition:

import barba from '@barba/core';
import gsap from 'gsap';

barba.init({
  transitions: [{
    name: 'fade',
    async leave({ current }) {
      await gsap.to(current.container, {
        opacity: 0,
        duration: 0.5,
        ease: 'power2.inOut'
      });
    },
    async enter({ next }) {
      // Start invisible
      gsap.set(next.container, { opacity: 0 });

      // Fade in
      await gsap.to(next.container, {
        opacity: 1,
        duration: 0.5,
        ease: 'power2.inOut'
      });
    }
  }]
});

3. Crossfade Transition (Sync)

Simultaneous fade between pages:

barba.init({
  transitions: [{
    name: 'crossfade',
    sync: true, // Enable sync mode
    leave({ current }) {
      return gsap.to(current.container, {
        opacity: 0,
        duration: 0.8,
        ease: 'power2.inOut'
      });
    },
    enter({ next }) {
      return gsap.from(next.container, {
        opacity: 0,
        duration: 0.8,
        ease: 'power2.inOut'
      });
    }
  }]
});

4. Slide Transition with Overlap

Slide old page out, new page in with overlap:

barba.init({
  transitions: [{
    name: 'slide',
    sync: true,
    leave({ current }) {
      return gsap.to(current.container, {
        x: '-100%',
        duration: 0.7,
        ease: 'power3.inOut'
      });
    },
    enter({ next }) {
      // Start off-screen right
      gsap.set(next.container, { x: '100%' });

      // Slide in from right
      return gsap.to(next.container, {
        x: '0%',
        duration: 0.7,
        ease: 'power3.inOut'
      });
    }
  }]
});

5. Transition Rules (Conditional Transitions)

Define different transitions based on navigation context:

barba.init({
  transitions: [
    // Home to any page: fade
    {
      name: 'from-home-fade',
      from: { namespace: 'home' },
      leave({ current }) {
        return gsap.to(current.container, {
          opacity: 0,
          duration: 0.5
        });
      },
      enter({ next }) {
        return gsap.from(next.container, {
          opacity: 0,
          duration: 0.5
        });
      }
    },
    // Product to product: slide left
    {
      name: 'product-to-product',
      from: { namespace: 'product' },
      to: { namespace: 'product' },
      leave({ current }) {
        return gsap.to(current.container, {
          x: '-100%',
          duration: 0.6
        });
      },
      enter({ next }) {
        gsap.set(next.container, { x: '100%' });
        return gsap.to(next.container, {
          x: '0%',
          duration: 0.6
        });
      }
    },
    // Default fallback
    {
      name: 'default',
      leave({ current }) {
        return gsap.to(current.container, {
          opacity: 0,
          duration: 0.3
        });
      },
      enter({ next }) {
        return gsap.from(next.container, {
          opacity: 0,
          duration: 0.3
        });
      }
    }
  ]
});

6. Router Plugin for Route-Based Transitions

Use @barba/router for route-specific transitions:

Installation: