repository·main·Indexed 12 days ago
https://github.com/barbajs/barbaA lightweight library for creating smooth, SPA-like page transitions in websites. It minimizes page load delays and HTTP requests using a hook-based lifecycle system, a plugin architecture, and support for custom markup. Includes core functionality via @barba/core and official plugins such as @barba/css, @barba/prefetch, and @barba/router.
Barba provides several features for building high-quality web experiences:
Promises.data attribute schemas.Transitions and Views.rules to select the appropriate transition.leave and enter hooks to play together.Views.You can install the core package of Barba using npm or yarn. It is recommended to install it as a development dependency.
npm install --save-dev @barba/coreyarn add @barba/core --devYou can install the @barba/router package using npm or yarn as a development dependency.
npm install --save-dev @barba/routeryarn add @barba/router --devYou can install the @barba/css package using npm or yarn as a development dependency.
npm install --save-dev @barba/cssyarn add @barba/css --devTo learn how to use Barba.js, you can access the following resources:
Install the @barba/prefetch package as a development dependency using npm or yarn to enable prefetching capabilities in your Barba.js project.
npm install --save-dev @barba/prefetchThe @barba/router uses several internal interfaces to handle the lifecycle of a route match:
IRouteParsed: Represents a route after its path has been parsed into a regular expression and extracted keys. It contains the path, the generated regex, and the keys array.IRouteResolved: Represents a route that has been successfully matched to a specific location. It contains the route's name and the extracted params (dynamic segments from the URL).IRouteByName: A dictionary-like object where keys are route names and values are IRouteParsed objects.Once @barba/router is installed, it injects a route property into the current and next objects of Barba's transition data. This allows you to access route information within hooks or transition lifecycle methods.
Example usage in a hook:
barba.hooks.beforeEnter((data) => {
const nextRoute = data.next.route;
if (nextRoute && nextRoute.name === 'user') {
console.log('Navigating to user:', nextRoute.params.id);
}
});// The 'route' property is added to current and next transition data
// current.route: IRouteResolved | undefined
// next.route: IRouteResolved | undefinedThe prefetch plugin uses an IntersectionObserver to monitor links on the page.
after hook), it scans the root element for <a> tags. It uses requestIdleCallback to ensure the scanning process doesn't interfere with main thread performance.barba.request() to fetch the page content and stores the resulting Promise in the Barba cache with the action 'prefetch' and status 'pending'.Note: Prefetching will be automatically disabled if barba.prefetchIgnore or barba.cacheIgnore are enabled in your Barba core configuration.
The @barba/css plugin automates the management of CSS classes during Barba.js transitions. It allows you to define transitions using CSS transitions by automatically adding and removing specific classes to the container elements at different stages of the transition lifecycle.
The plugin hooks into the Barba lifecycle and applies classes based on a prefix (defaults to barba). For a given transition kind (e.g., leave, enter, once), the plugin manages the following class states:
{prefix}-{kind} and then {prefix}-{kind}-active.{prefix}-{kind} and adds {prefix}-{kind}-to.{prefix}-{kind}-to and {prefix}-{kind}-active.If the container has a CSS transition-duration greater than 0s, the plugin will automatically wait for the transitionend event before proceeding to the next stage of the Barba transition.
By default, the plugin uses the barba prefix. However, it will automatically use the name property defined in your Barba transition object as the CSS prefix. For example, if your transition is named fade, the classes applied will be fade-leave, fade-leave-active, etc.
add(el: HTMLElement, step: string): voidManually adds a CSS class with the current prefix to an element.
el.classList.add("${this.prefix}-${step}")
remove(el: HTMLElement, step: string): voidManually removes a CSS class with the current prefix from an element.
el.classList.remove("${this.prefix}-${step}")
// Example of how classes are applied conceptually:
// If prefix is 'barba' and kind is 'leave':
// 1. barba-leave
// 2. barba-leave-active
// 3. barba-leave-to
// 4. (transition ends)
// 5. remove barba-leave-to, barba-leave-activeThe @barba/prefetch plugin preloads pages in the background when links enter the viewport, making transitions feel instantaneous.
To use it, install the package and pass the prefetch instance to barba.use(). You can configure the plugin via the IPrefetchOptions object during installation.
| Option | Type | Default | Description |
|---|---|---|---|
root | HTMLElement | HTMLDocument | document.body | The element within which to search for links to observe. |
timeout | number | 2000 | The timeout in milliseconds for the requestIdleCallback used during observation. |
limit | number | 0 | The maximum number of links to observe. If set to 0, all valid links are observed. |
import barba from '@barba/core';
import prefetch from '@barba/prefetch';
barba.use(prefetch, {
root: document.querySelector('.content'),
timeout: 3000,
limit: 10
});
barba.init();