/ukiyo-js

⛰️ Dynamic, modern, and efficient background parallax effect.

Primary LanguageTypeScriptMIT LicenseMIT

Ukiyo.js
Ukiyo.js

Dynamic, modern, and efficient background parallax effect.

⛰️
DEMO

⛰️ 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

🚧 When using Lenis in combination

  • 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.


🖥️ Browser Support

IE Edge Firefox Chrome Opera Safari iOS Safari
❌No Support ✅Latest ✅Latest ✅Latest ✅Latest ✅Latest ✅Latest

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


🏕️ Examples

How is Ukiyo being used? 👀


📃 License

MIT License