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 install ukiyojs
yarn add ukiyojs
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 class="ukiyo" src="image.jpg">
<picture>
<source srcset="~">
<img class="ukiyo" src="image.jpg">
<picture>
<video class="ukiyo" src="~" type="~">
<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:
new Ukiyo(".ukiyo")
const images = document.querySelectorAll(".ukiyo")
new Ukiyo(images)
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,
speed: 1.5,
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) {
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
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 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