# Barba.js — Fluid Page Transitions for Multi-Page Websites

> A small JavaScript library that intercepts link clicks, fetches new pages via AJAX, and swaps content with smooth CSS or JS transitions, turning multi-page sites into app-like experiences.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# Barba.js — Fluid Page Transitions for Multi-Page Websites

## Quick Use
```bash
npm install @barba/core
```
```javascript
import barba from '@barba/core';
barba.init({
  transitions: [{
    leave: ({ current }) => current.container.animate([{ opacity: 1 }, { opacity: 0 }], 300).finished,
    enter: ({ next }) => next.container.animate([{ opacity: 0 }, { opacity: 1 }], 300).finished
  }]
});
```

## Introduction
Barba.js creates seamless page transitions between URLs without requiring a single-page application framework. It hijacks navigation, fetches the next page in the background, and applies enter/leave animations to swap content, preserving the multi-page architecture while delivering SPA-like fluidity.

## What Barba.js Does
- Intercepts internal link clicks and browser back/forward navigation
- Prefetches linked pages on hover for near-instant transitions
- Swaps page content containers while preserving persistent layout elements
- Runs leave and enter transition hooks with promises for async animation control
- Maintains browser history, scroll position, and URL state correctly

## Architecture Overview
Barba.js wraps the browser's navigation with a lifecycle engine. When a link is clicked, it prevents default, fetches the target HTML via XMLHttpRequest, parses the new document, and identifies the replacement container. A transition manager runs leave(), swap, and enter() hooks sequentially. Plugins extend behavior: @barba/prefetch adds intersection-observer-based preloading, @barba/css enables class-based CSS transitions, and @barba/router adds route-specific transition rules.

## Self-Hosting & Configuration
- Install core and optional plugins via npm
- Wrap page content in a data-barba="container" element with a data-barba-namespace
- Define transitions as objects with leave/enter functions or use @barba/css for class-driven animations
- Add rules to match transitions to specific route patterns or namespaces
- Works with any backend (WordPress, Rails, static HTML) since it operates on rendered HTML

## Key Features
- Namespace-based transition routing applies different animations per page type
- Prefetch plugin preloads pages on link hover or viewport intersection
- CSS plugin adds/removes classes automatically for pure-CSS transition workflows
- Views API runs page-specific initialization code after transitions complete
- Hooks system (before, after, once) enables analytics tracking and cleanup logic

## Comparison with Similar Tools
- **Turbo (Hotwire)** — full page replacement with minimal animation; Barba focuses on creative transitions
- **PJAX** — simpler fetch-and-replace; no built-in animation lifecycle
- **Swup** — similar concept; Barba offers more granular transition routing and plugin ecosystem
- **SPA frameworks** — React Router, Next.js provide transitions but require full SPA architecture
- **View Transitions API** — native browser feature (limited support); Barba works everywhere today

## FAQ
**Q: Does Barba.js work with WordPress?**
A: Yes. Add data-barba attributes to your theme templates and initialize Barba in your JS bundle.

**Q: How do I handle page-specific scripts?**
A: Use Barba's Views API to run init/destroy functions scoped to each namespace.

**Q: Does it break SEO?**
A: No. Pages remain fully server-rendered HTML. Barba only enhances navigation in the browser.

**Q: Can I use GSAP for transitions?**
A: Yes. Return GSAP timeline promises from leave/enter hooks for full animation control.

## Sources
- https://github.com/barbajs/barba
- https://barba.js.org/docs/

---
Source: https://tokrepo.com/en/workflows/barba-js-fluid-page-transitions-multi-page-websites-b0f897b0
Author: AI Open Source