⛰️ Features
- 🏞️ Background parallax for
<img>
,<picture>
,<video>
andbackground-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 au
, 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? 👀
- UKIYO - from @yitengjun
- YTNG - Portfolio - from @yitengjun