Skip to content

barba-js

  • Group: Animation
  • When it activates: Page transitions with Barba.js (multi-page sites)
  • Installed: Optional: comes with a skill bundle.

Full upstream documentation (English): SKILL.upstream.md (871 lines). Do not read all of it: use the map and read only the section you need (Read with offset/limit or Grep).

  • Use: multi-page site (static HTML, Astro without View Transitions, WordPress, Eleventy) that needs smooth transitions between pages without a full reload.
  • Use: conditional transitions by namespace/route, loading indicator, re-initializing scripts or analytics after each navigation.
  • Do NOT use: React/Next apps with their own router → motion-framer (AnimatePresence); Astro with native View Transitions.
  • Do NOT use: animations within a single page or on scroll → gsap-scrolltrigger.
Task Read only
Start a project/starter SKILL.upstream.md L25-67 (§Wrapper, Container, and Namespace) + L151-183 (§Basic Setup) or scripts/project_setup.py
Create a transition (fade/slide/crossfade) L185-274 (§2-4 Common Patterns) + references/transition_patterns.md
Different transitions per page or route L276-387 (§Transition Rules + §Router Plugin)
Per-page logic / re-init of scripts L121-147 (§Views) + L490-565 (§View-Specific… §Third-Party…)
Debugging / performance L567-669 (§Performance Optimization) + L671-844 (§Common Pitfalls)
Lines Section What for
10-22 Overview What Barba is (7 kb, framework-agnostic)
23-147 Core Concepts DOM structure, async/sync cycle, the 11 hooks, views
25-67 1. Wrapper, Container, and Namespace Required data-barba attributes
69-93 2. Transition Lifecycle Order of steps in async mode vs sync: true
94-120 3. Hooks Execution order and typical use of each hook
149-422 Common Patterns Minimal setup, fade, crossfade, slide, rules, router, loader
424-565 Integration Patterns GSAP timelines, per-view init, analytics, third-party widgets
567-669 Performance Optimization Prefetch, avoiding layout shift, GPU properties, cleaning up listeners, lazy images
671-844 Common Pitfalls Promises not returned, external links, CSS across pages, title/meta, flicker, sync without position absolute
846-871 Resources / Related Skills Index of scripts, references and related skills
  • references/api_reference.md — Full API: init, hooks, transitions, views, router.
  • references/hooks_guide.md — The 11 hooks with execution order and use cases.
  • references/gsap_integration.md — GSAP animation patterns for leave/enter.
  • references/transition_patterns.md — Ready-to-copy transition implementations.
  • scripts/transition_generator.py — Generates the code for a transition: py -3 scripts/transition_generator.py --type slide --sync (or python3 …).
  • scripts/project_setup.py — Creates a Barba + GSAP project structure: py -3 scripts/project_setup.py --name mi-proyecto --transition fade.
  • assets/README.md — Only describes starters; upstream mentions starter_barba/ and examples/ but they do NOT exist in the package.
  • The leave/enter hooks must return a promise (return the tween or async/await); otherwise the transition ends instantly.
  • With sync: true, position the containers with position: absolute (wrapper relative) to avoid layout jumps.
  • Animate only opacity/transform (x, scale, rotation); never width/height/top.
  • Clean up listeners and instances (sliders, lightbox, Locomotive) in beforeLeave; reset scroll and global state in beforeEnter.
  • Update <title> and meta with @barba/head or manually in barba.hooks.after; use prevent to let external links through.
  • Respect prefers-reduced-motion: if it is on, use instant transitions or very short opacity ones.
  • Detect the stack as the front-activation/skill-router skill indicates (senzu/senzu.json → package.json). Barba is vanilla JS: it fits static HTML, Astro (without View Transitions), Vue/Nuxt only in MPA mode. For React/Next use motion-framer; combine with locomotive-scroll (destroy/recreate the instance on each transition) and gsap-scrolltrigger (ScrollTrigger.refresh() in afterEnter).