Ukiyojs NPM | npm.io

⛰️ Features

🏞️ Background parallax for <img>, <picture>, <video> and background-image
🚀 Efficient and dynamic animations
📚 No dependencies
📝 TypeScript support

📦 Installation

Install ukiyojs using your package manager of choice.

# npm
npm install ukiyojs

# yarn
yarn add ukiyojs

# pnpm
pnpm add ukiyojs

Import Ukiyo:

import Ukiyo from "ukiyojs";

or import via CDN:

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

🕹️ Usage

HTML

Give the elements cool names like ukiyo to call them in scripts for parallax effects.

🏞 <img>

<img class="ukiyo" src="image.jpg">

🌅 <picture>

<picture>
  <source srcset="~">
  <!-- give a name to img element inside picture element. -->
  <img class="ukiyo" src="image.jpg">
<picture>

🎬 <video>

<video class="ukiyo" src="~" type="~">

🖼️ CSS background-image

<div class="ukiyo"></div>

JavaScript

Instantiate Ukiyo with the cool name you gave to the element as the first argument. The element selection supports the following types:

// CSS selector
new Ukiyo(".ukiyo")

// or node
const images = document.querySelectorAll(".ukiyo")
new Ukiyo(images)

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

There you go, all set! Now let's see it in action.

⚙️ Options

Instance Options

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

new Ukiyo(parallax, {
    scale: 1.5, // 1~2 is recommended
    speed: 1.5, // 1~2 is recommended
    willChange: true,
    wrapperClass: "ukiyo-wrapper",
    externalRAF: false
})

Option	Type	Default	Description
`scale`	`number`	`1.5`	Parallax image scaling factor.
`speed`	`number`	`1.5`	Parallax speed.
`willChange`	`boolean`	`false`	When true is specified, the elements will receive will-change: transform when Parallax is active.
`wrapperClass`	`string`	`null`	Set any class name to the automatically generated wrapper element.
`externalRAF`	`boolean`	`false`	Set it to true if you want to use an external requestAnimationFrame.

Element attributes

Additionally, you can individually set these options for elements using the data-u-* attribute, like this:

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

Attribute	Values	Description
`data-u-scale`	`number`	`scale` option.
`data-u-speed`	`number`	`speed` option.
`data-u-willchange`		`willChange` option. Just add this to the element to enable it.
`data-u-wrapper-class`	`string`	`wrapperClass` option.

Option names start with data-u-*. Don't forget to prefix the option name with a u, if u do.

🚀 Using external requestAnimationFrame

By default, parallax animation is automatically rendered using the library's requestAnimationFrame, but you can use an external requestAnimationFrame to run the animation.

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

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

  requestAnimationFrame(raf)
}

requestAnimationFrame(raf)

Enable the externalRAF option, and then call the animate() method within your custom requestAnimationFrame to trigger the parallax animation.

🔧 Methods

reset()
To reset the instance and recalculate the size and position of the elements, use the following code:

const instance = new Ukiyo(".image")

instance.reset()

destroy()
Destroy instance:

const instance = new Ukiyo(".image")

instance.destroy()

📍Notes

As of July 2023, we have identified a bug in Safari when using it in conjunction with Lenis, which causes parallax effects to become distorted during scrolling. This issue is due to a bug in Safari itself. To address this bug, you may need to apply styles like pointer-events: none; to the parallax elements, preventing scroll events from affecting them. However, please be cautious as this may disable interaction events for those elements.
- https://github.com/studio-freight/lenis/issues/187