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

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/[email protected]/dist/ukiyo.min.js"></script>

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>

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.

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
})

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
>

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

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.

• 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()

Parallax animations are automatically disabled in browsers that do not support them.

How is Ukiyo being used? 👀

• UKIYO - from @yitengjun
• YTNG - Portfolio - from @yitengjun

MIT License