⛰️ 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/[email protected]/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

🖥️ 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? 👀

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

📃 License

MIT License