barba-js

Use Barba.js to intercept link clicks and swap page containers with animated transitions. Add data-barba="wrapper" and data-barba="container" attributes to your HTML, then define leave and enter hooks with GSAP animations in barba.init().

Return GSAP tweens or timelines from Barba's leave and enter hooks, since GSAP animations return promises that Barba awaits. Use gsap.set() in beforeEnter to establish initial states and prevent content flashing before the enter animation.

The transition hook is not returning a promise, so Barba does not wait for the animation. Fix it by returning the GSAP tween directly or declaring the hook as async and awaiting the animation.

Barba.js only swaps the container content by default, so head tags stay stale. Install the @barba/head plugin to automatically update title, meta, and link tags, or update them manually in the after hook.

Async mode (default) runs the leave animation, swaps containers, then runs enter. Sync mode with sync: true runs leave and enter simultaneously for crossfade effects, but requires absolute positioning to prevent layout shift.

Avoid Barba.js when building a true SPA with React or Vue, where framework routers like Next.js routing or Framer Motion fit better. It also adds complexity for simple sites where full reloads are acceptable.