Ukiyo.js

You can install ukiyojs via npm, yarn, or pnpm, or include it directly in your HTML using a CDN link.

Package Managers

# npm
npm install ukiyojs

# yarn
yarn add ukiyojs

# pnpm
pnpm add ukiyojs

CDN

<script src="https://cdn.jsdelivr.net/npm/ukiyojs@4.1.2/dist/ukiyo.min.js"></script>

If you want to control the animation timing yourself (e.g., to sync with other animation libraries), set externalRAF: true in the instance options. You must then manually call the .animate() method within your own requestAnimationFrame loop.

const parallax = new Ukiyo(".ukiyo", {
  externalRAF: true
});

function raf(time) {
  // animate parallax
  parallax.animate();

  requestAnimationFrame(raf);
}

requestAnimationFrame(raf);

To use Ukiyo.js, first mark your target elements in HTML (e.g., using a class like ukiyo). Then, instantiate the Ukiyo class in JavaScript by passing a CSS selector, a NodeList, or an HTMLCollection.

Supported HTML elements

• <img>
• <picture> (apply the class to the <img> inside)
• <video>
• Elements with background-image (apply the class to the <div>)

JavaScript Initialization

You can select elements using standard DOM methods.

import Ukiyo from "ukiyojs";

// Using a CSS selector
new Ukiyo(".ukiyo");

// Using a NodeList
const images = document.querySelectorAll(".ukiyo");
new Ukiyo(images);

// Using an HTMLCollection
const images = document.getElementsByClassName('ukiyo');
new Ukiyo(images);

You can set individual options directly on HTML elements using data-u-* attributes. Note that the option name must be prefixed with u after the data- prefix.

<img
  data-u-scale="2"
  data-u-speed="1.7"
  data-u-wrapper-class="wrapper-name"
  data-u-willchange
>

When instantiating new Ukiyo(element, options), you can pass an options object to customize the parallax behavior.

const parallax = document.querySelector('.image');

new Ukiyo(parallax, {
    scale: 1.5,
    speed: 1.5,
    willChange: true,
    wrapperClass: "ukiyo-wrapper",
    externalRAF: false
});

When using Lenis for smooth scrolling, a bug in Safari may cause parallax effects to become distorted during scrolling.

Workaround: You may need to apply pointer-events: none; to the parallax elements to prevent scroll events from affecting them.

Warning: Applying pointer-events: none; will disable all interaction events (like clicks) on those elements.

The Ukiyo instance provides methods to manage its lifecycle and state.

• reset(): Resets the instance and recalculates the size and position of the elements.
• destroy(): Destroys the instance.

const instance = new Ukiyo(".image");

// Recalculate positions
instance.reset();

// Clean up the instance
instance.destroy();

To manage memory and clean up the DOM, use the following methods:

• reset(): Recalculates damping and resets the internal styles of the wrapper and the element, then re-applies the parallax transformation. Useful if the window is resized or layout changes.
• destroy(): Completely removes the parallax effect. It disconnects any IntersectionObserver, removes all inline styles from the wrapper and the element, and removes the wrapper from the DOM, returning the original element to its original position in the document tree.

// To clean up
parallax.destroy();

The Ukiyo class is the main entrypoint for the library. It manages multiple parallax instances for a set of elements. When instantiated, it automatically checks for browser support and initializes the parallax effect on the provided elements.

Constructor Parameters:

• elements: A TElement (can be a single element or a collection of elements) that must not be null.
• options: An optional UkiyoOptions object to configure the behavior.

If options.externalRAF is set to true, Ukiyo will not start its own internal animation loop, allowing you to control the animation timing manually via the animate() method.

import Ukiyo from 'ukiyo-js';

// Initialize Ukiyo with a single element or a collection
const ukiyo = new Ukiyo(document.querySelectorAll('.parallax-element'), {
  // options here
});

The animate() method triggers the animation cycle for all managed parallax instances.

• If externalRAF was set to false (default) during initialization, calling animate() manually is unnecessary as the library manages its own requestAnimationFrame loop.
• If externalRAF was set to true, you must call animate() manually (e.g., within your own requestAnimationFrame loop) to drive the parallax effect.

// If initialized with externalRAF: true
function loop() {
  ukiyo.animate();
  requestAnimationFrame(loop);
}
loop();

The destroy() method performs full cleanup of the Ukiyo instance. It:

1. Cancels the internal requestAnimationFrame loop.
2. Removes window event listeners for resize and orientationchange.
3. Calls destroy() on every individual parallax instance to free up resources.

ukiyo.destroy();