A simple & easy to use animation library for web developers
Git Pages
·
Playground Demo
·
Report Bug
·
Request Feature
JOS-Animation, Javascript On Scroll Animation library is a simple & easy to use animation library package to instantly add professional animation to your website. It was built to make my life easier while developing websites & comes with tons of features and is fully customizable. It is lightweight & has a very small footprint. The best part of all is that it has no (*minimum) toll on performance.
- Open source, no download or tiring setup, just add a script tag (Embed).
- Includes Preset and expert custom animation options.
- Works with all major browsers & Platforms.
- Fast, light and small with no/min toll on performance.
- Simple & easy to setup for both beginners & experts.
- Customize animation settings and build your own scroll invoked functions
- npm & CDNjs approved library for the fastest deliveries
- And lots more stuff... explore it yourself.
This project is currently being developed by me & the dev community, So you can expect more features and updates quite often..
Was inspired by GSAP, AOS libraries. I wanted something easier to use, with great performance and wanted to make the implementation better. So I worked on this project from scratch.
Feel free to report an issue or request a feature in this repository :)
& for more information, Check out the JOS Webpage.
Badges
<a
target="\_blank"
rel="noopener noreferrer nofollow"
href="https://github.com/jesvijonathan/JOS-Animation-Library"
>
<img
src="https://cdn.jsdelivr.net/gh/jesvijonathan/JOS-Animation-Library@master/res/badge/jos_github%20default.svg"
alt="JOS-Animation"
style="max-width: 100%;"
/></a>
Video Tutorial
- JOS V0.6 Cubes (Outdated | Latest : v0.9.1)
- JOS V0.8.8 (Outdated | [Latest : v0.9.1](https://github.com/jesvijonathan/JOS-Animation-Library/releases/latest))
JOS
v0.9.2
11 Nov 2023
Jesvi Jonathan
You have the option to use the latest version of JOS from a variety of sources :
<script
src="https://cdnjs.cloudflare.com/ajax/libs/jos-animation/0.9.2/jos.js"
integrity="sha512-ZbNmgrMmWwQspNz6WQ1HnqLEPMXE4PyJBVnuc10e4gwJhrycze2IzjDQPx4CxkOBnUyt5wNCekdeTRJOe8J4WA=="
crossorigin="anonymous"
referrerpolicy="no-referrer"
></script>
(or) JSDELIVR
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/jos.js"></script>
Click here to check out other Sources / CDNs
-
<script src="https://cdn.jsdelivr.net/gh/jesvijonathan/JOS-Animation-Library/dist/jos.js"></script>
(or)
<script src="https://cdn.jsdelivr.net/npm/jos-animation/dist/jos.js"></script>
(or)
<script src="https://cdn.jsdelivr.net/gh/jesvijonathan/JOS-Animation-Library/dist/v0.9.2/jos.js"></script>
-
<script src="https://unpkg.com/jos-animation"></script>
(or)
<script src="https://unpkg.com/[email protected]/dist/jos.js"></script>
-
<script src="https://raw.githubusercontent.com/jesvijonathan/JOS-Animation-Library/master/dist/jos.js"></script>
You can add minified version of the script by replacing jos.js
with
jos.min.js
in the above script tag.
jos.js
for basic. -jos.min.js
for production use. -jos.debug.js
for debugging along with some other function Fromv0.9
onwards, by defaultjos.js
does not require you to add the stylesheetjos.css
, it will be exported along with the script. But you can still add the stylesheet if you want to for some reason. ### Importing JOS 1. Install JOS using npm (yarn or pnpm) : ```bash npm install jos-animation
- Latest :
jos-animation@latest
- Stable :
[email protected]
- Beta :
[email protected]
So it would be https://unpkg.com/jos-animation/@latest/dist/jos.js
(embed) for the latest version. or jos-animation/@0.8.8/dist/jos.js
(npm install) for a specific version.
- Install JOS using npm (yarn or pnpm) :
npm install jos-animation
- Import JOS in your project :
// import "jos-animation/dist/jos.css";
// Above is required only for v0.8.8 & below (or) if you want to overide jos by using style from the stylesheet
import JOS from "jos-animation";
// Other ways to import JOS
// import JOS from "jos-animation/dist/jos.js";
// import JOS from "jos-animation/dist/jos.min.js";
// import JOS from "jos-animation/dist/jos.debug.js";
Vue / Nuxt.js
// main.js
import { createApp } from "vue";
import { watch, nextTick } from "vue";
import JOS from "jos-animation"; // jos-animation/dist/jos.debug.js
import App from "./App.vue";
const app = createApp(App);
app.mount("#app");
JOS.init();
//JOS.version();
watch(
() => router.currentRoute.value,
() => {
nextTick(() => {
JOS.refresh();
});
}
);
// To observe elements after a route change
Used in : https://jos-animation.vercel.app/
This above example for Vue.js is also applicable for Nuxt.js
React
// index.js
import JOS from "jos-animation/dist/jos.js";
onload = () => {
const options = {
debugMode: true,
animation: "flip",
duration: 0.7,
rootMargin: "0% 0% 0% 0%",
};
JOS.init(options);
//JOS.version();
};
function Main() {
useEffect(() => {
JOS.refresh();
}, []);
// To observe elements after a route change
return (
<React.StrictMode>
<App />
</React.StrictMode>
);
}
ReactDOM.createRoot(document.getElementById("root")).render(<Main />);
Used in : https://azzle.netlify.app
This above example is for React.js is also applicable for Next.js & Preact.js
Next.js
// app/layout.tsx
import jos from "jos-animation/dist/jos.js";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
const jos_options = {
debugMode: false,
passive: true,
animation: "fade",
duration: 0.4,
rootMargin: "20% 0% 30% 0%",
};
useEffect(() => {
jos.init(jos_options);
}, []); // Once
useEffect(() => {
jos.refresh();
}); // For every update
return ();
}
// To observe elements after a route change
Used in : https://bitspace-nextjs-jos.vercel.app
Angular
import { Component, OnInit, AfterViewChecked } from '@angular/core';
import JOS from 'jos-animation';
@Component({
selector: 'app-root',
templateUrl: './app.component.html',
styleUrls: ['./app.component.css']
})
export class AppComponent implements OnInit, AfterViewChecked {
ngOnInit(): void {
JOS.init(); // Once
}
ngAfterViewChecked(): void {
JOS.refresh(); // For every update
}
// ... rest of your code
}
You can check this discussion thread for more information : JOS for Angular
- Use
JOS.init();
to initialize the library with default settings.
<!-- Initialize JOS with default settings -->
<script>
JOS.init();
</script>
- (Or) Use
JOS.init(options);
to overide the default settings with your custom settings.
<!-- Global Parameters -->
<script>
JOS.init({
// disable: false, // Disable JOS globally | Values : 'true', 'false'
debugMode: true, // Enable JOS debug mode | Values : 'true', 'false'
passive: false, // Set the passive option for the scroll event listener | Values : 'true', 'false'
once: false, // Disable JOS after first animation | Values : 'true', 'false' || Int : 0-1000
animation: "fade", // JOS global animation type | Values : 'fade', 'slide', 'zoom', 'flip', 'fade-right', 'fade-left', 'fade-up', 'fade-down', 'zoom-in-right', 'zoom-in-left', 'zoom-in-up', 'zoom-in-down', 'zoom-out-right', 'zoom-out-left', 'zoom-out-up', 'zoom-out-down', 'flip-right', 'flip-left', 'flip-up', 'flip-down, spin, revolve, stretch, "my-custom-animation"
// animationInverse: "static", // Set the animation type for the element when it is scrolled out of view | Values : 'fade', 'slide', 'zoom', 'flip', 'fade-right', 'fade-left', 'fade-up', 'fade-down', 'zoom-in-right', 'zoom-in-left', 'zoom-in-up', 'zoom-in-down', 'zoom-out-right', 'zoom-out-left', 'zoom-out-up', 'zoom-out-down', 'flip-right', 'flip-left', 'flip-up', 'flip-down, spin, revolve, stretch, "my-custom-animation"
timingFunction: "ease-in-out", // JOS global timing function | Values : 'ease', 'ease-in', 'ease-out', 'ease-in-out', 'linear', 'step-start', 'step-end', 'steps()', 'cubic-bezier()', 'my-custom-timing-function'
//mirror : false, // Set whether the element should animate back when scrolled out of view | Values : 'true', 'false'
threshold: 0, // Set global the threshold for the element to be visible | Values : 0-1
delay: 0, // Set global the delay for the animation to start | Values : 0,1,2,3,4,5
duration: 0.7, // Set global the duration for the animation playback | Values : flota : 0-1 & int : 0,1,2,3,4,5
// startVisible: "true", // Set whether the element should animate when the page is loaded | Values : 'true', 'false' || MS : 0-10000
// scrollDirection: "down", // Set the scroll direction for the element to be visible | Values : 'up', 'down', 'none'
//scrollProgressDisable: true // disable or enable scroll callback function | Values : 'true', 'false'
// intersectionRatio: 0.4, // Set the intersection ratio between which the element should be visible | Values : 0-1 (automatically set)
// rootMargin_top: "0%", // Set by which percent the element should animate out (Recommended value between 10% to -30%)
// rootMargin_bottom: "-50%", // Set by which percent the element should animate out (Recommended value between -10% to -60%)
// rootMargin: "0% 0% -50% 0%", // Set the root margin for the element to be visible | Values : _% _% _% _% (automatically set)
});
</script>
- Set
class="jos"
to the element you want to animate :
<!-- JOS class is required to animate the element -->
<div class="jos"></div>
- Set
data-jos
*attributes to customize the element you want to animate,
(although these attributes are optional and will work without them) :
<!-- JOS attributes are optional and will work without them (class="jos" is mandatory). these attributes can be used to customize the animation of the element -->
<div
class="jos"
data-jos_animation="zoom"
data-jos_once="false"
data-jos_duration="0.4"
data-jos_delay="0.1"
data-jos_timing-function="ease-in-out"
data-jos_mirror="true"
data-jos_rootMargin="0% 0% -50% 0%"
data-jos_rootMargin_top="-10%"
data-jos_rootMargin_bottom="-50%"
data-jos_scrollDirection="down"
data-jos_startVisible="false"
data-jos_threshold="0.4"
data-jos_passive="false"
data-jos_invoke="myCustomFunction"
data-jos_invoke_out="myCustomFunction_onExit"
data-jos_scroll="your_callbackFunction"
data-jos_anchor="#elementID"
></div>
See JOS Props for full information regarding the animation, attributes, and options.
- Create a custom animation by adding the following code to your stylesheet :
/* Custom animation class name starts with 'jos-' keyword followed by the animation name*/
.jos-my-custom-animation {
/* Set the initial state of the element */
}
- Use your custom animation by setting the
data-jos_animation
attribute tomy-custom-animation
:
<div class="jos" data-jos_animation="my-custom-animation"></div>
Example : Custom Animation
- Create a custom inverse animation by adding the following code to your stylesheet :
/* Custom inverse animation class name starts with 'jos-' keyword followed by the animation name*/
.jos-my-custom-animation-inverse {
/* Set the initial state of the element */
}
- Use your custom inverse animation by setting the
data-jos_animationInverse
attribute tomy-custom-animation-inverse
:
<div class="jos" data-jos_animationInverse="my-custom-animation-inverse"></div>
This is especially useful when you want to animate an element when it is scrolled out of its rootMargin, this gives more customizability for beautiful animations.
You can also use a combination of both data-jos_animation
("none", "static", no-transition, etc) & data-jos_animationInverse
attributes to create a custom animation.
Example : Custom Inverse Animation
- Create a playable animation by adding the following code to your stylesheet :
/* Custom playable animation class name starts with 'jos-' keyword followed by the animation name*/
/* My Custom Playable Animation */
.jos-my-custom-animation {
transition: 1s;
animation: jos-my-custom-animation 1s ease-in-out infinite;
transform: translateX(100px);
}
/* Add Keyframes */
@keyframes jos-my-custom-animation {
0% {
opacity: 1;
}
50% {
transform: translateX(-100px);
}
}
- Use the playable animation by setting the
data-jos_animation
attribute tomy-custom-animation
&data-jos_animationInverse
attribute tomy-custom-animation-play
:
<div
class="jos"
data-jos_animation="my-custom-animation"
data-jos_animationinverse="static"
></div>
Here the data-jos_animationinverse
attribute is set to static
to prevent the element from animating out of view & to keep it in the final state. The Playable animation is triggered and starts playing when the element is scrolled into view.
Example : Playable Animation
- Create a custom timing function by adding the following code to your stylesheet :
/* Custom timing function attribute name starts with 'data-jos_timing_function' keyword & a custom name of your choice */
[data-jos_timing_function="myCustom-timingFunc"] {
/* Set the timing of the element */
transition-timing-function: cubic-bezier(0.2, 0.5, 0.2, 0.5) !important;
}
- Use your custom timing function by setting the
data-jos_timing-function
attribute tomy-custom-timing-function
:
<div class="jos" data-jos_timing-function="myCustom-timingFunc"></div>
Example : Custom Timing Function
- Create an element that you want to use as an anchor & add an
id
to it :
<!-- My reference anchor element -->
<div id="myElement"></div>
- Create an element that you want to animate & add the
data-jos_anchor
attribute to it, with the id starting with suffix#
:
<!-- My animated element -->
<div class="jos" data-jos_anchor="#myElement"></div>
This triggers the animation when the myElement
element is scrolled into view.
This feature is useful especially when you want to animate an element which is in a fixed position.
Example : Anchor
- Create an element that you want to animate & add the
data-jos_scrollDirection
attribute to it :
<!-- My animated element -->
<div class="jos" data-jos_scrollDirection="down"></div>
This triggers the animation when the element is scrolled into view from the up to down
direction.
& you can do the same for down to up
direction.
This is particularly useful when you want to animate an element when it is scrolled into view from a particular direction.
Example : Direction Based Animation
- Create an element that you want to have a visible state when the page is loaded & add the
data-jos_startVisible
attribute to it :
<!-- My animated element -->
<div class="jos" data-jos_startVisible="true"></div>
This sets the element to be visible when the page is loaded. you can add a delay to it by setting the value in ms
:
<!-- My animated element that is visible with a given timer/delay in ms-->
<div class="jos" data-jos_startVisible="3000"></div>
This sets the element to be visible when the page is loaded after 3000
ms or instantly if the value is 0
(or) true
.
This feature is useful especially when you want an element which is in a fixed position, or is present in the landing page to be at initially in a visible state with no animation .
Example : Start Visible
- Create a custom function by adding the following code to your script :
// Create a custom function
function myCustomFunction() {
// Do something
}
- Use your custom function by setting the
data-jos_invoke
attribute tomyCustomFunction
:
<div class="jos" data-jos_invoke="myCustomFunction"></div>
This triggers the myCustomFunction() function when the element is scrolled into view.
You can use data-jos_invoke_out
attribute to trigger the function when the element is scrolled out of view.
Example : Custom Function
- Create an element that you want to animate & add the
data-jos_scroll
attribute to it :
<div id="elem1" class="jos" data-jos_scroll="your_callbackFunction">
Scroll Trigger Element
</div>
- Create a custom function by adding the following code to your script :
your_callbackFunction = (element) => {
// windowScrollProgress : element scroll pixel
console.log(element.id, element.jos.windowScrollProgress);
// scrollProgress : 0-1
element.style.opacity = element.jos.scrollProgress;
// rootScrollProgress : +-0 to +-1
element.style.innerHTML = element.jos.rootScrollProgress;
};
This triggers the your_callbackFunction() function when the element is scrolled. This way you can handle the scroll progress of the element.
Example : Custom Function
- Create an parent element that you want to animate & add the
data-jos_stagger
attribute to it along withjos
class :
<div
class="jos parent_elem"
id="stagger"
data-jos_stagger="spin"
data-jos_staggerinverse="none"
data-jos_stagger_anchor="#elementID"
data-jos_stagger_sequence="0.1"
data-jos_stagger_delay="0"
data-jos_stagger_duration="0.4"
data-jos_stagger_timing-function="ease-in-out"
data-jos_stagger_mirror="true"
data-jos_stagger_rootMargin="0% 0% -50% 0%"
data-jos_stagger_invoke="myCustomFunction"
data-jos_stagger_invoke_out="myCustomFunction_onExit"
data-jos_stagger_scroll="your_callbackFunction"
data-jos_stagger_startVisible="false"
data-jos_stagger_scrollDirection="down"
data-jos_stagger_once="false"
>
<!-- data-jos_stagger="true" # this attribute along with 'jos' class in parent element is Required/Must to enable staggering -->
<!-- data-jos_stagger_anchor="true" # auto sets parent element's id & uses it as a anchor's -->
<!-- Element 1 -->
<div class="child_elem"></div>
<!-- Element 2 -->
<div class="child_elem"></div>
<!-- Element 3 -->
<div class="child_elem"></div>
<!-- Element n -->
</div>
The data-jos_stagger
attribute along with jos
class in parent element is Required/Must to enable staggering even if you are using other attributes.
data-jos_stagger
=true
would auto asign id for parent element & use it as a anchor for child elements.data-jos_stagger
=#id
would use the given id as a anchor for child elements.- not using
data-jos_stagger_anchor
make the element independent of the parent element.
data-jos_stagger_seq
is used to set the delay between each element in the sequence (to trigger one after other) whereas data-jos_stagger_delay
total delay for each element as a whole.
Example : Staggering Animation
Attribute | Type | Default | Description | Values |
---|---|---|---|---|
data-jos_animation | string | fade | Set the animation type for the element. | fade , slide , zoom , flip , fade-right , fade-left , fade-up , fade-down , zoom-in-right , zoom-in-left , zoom-in-up , zoom-in-down , zoom-out-right , zoom-out-left , zoom-out-up , zoom-out-down , flip-right , flip-left , flip-up , flip-down , rotate , rotate-right , spin , spin-right , revolve , revolve-right , stretch , stretch-vertical , my-custom-animation |
data-jos_animationInverse | string | static | Set the Inverse animation type for the element. | fade , slide , zoom , flip , fade-right , fade-left , fade-up , fade-down , zoom-in-right , zoom-in-left , zoom-in-up , zoom-in-down , zoom-out-right , zoom-out-left , zoom-out-up , zoom-out-down , flip-right , flip-left , flip-up , flip-down , rotate , rotate-right , spin , spin-right , revolve , revolve-right , stretch , stretch-vertical , my-custom-animation |
data-jos_once | boolean | false | Set whether the element should animate only once. | true , false |
data-jos_delay | int | 0 | Set the delay for the animation to start. | (float: 0-1) & (int: 0, 1, 2, 3, 4, 5) |
data-jos_duration | float | 0.4 | Set the duration for the animation playback. | (float: 0-1) & (int: 0, 1, 2, 3, 4, 5) |
data-jos_timing-function | string | ease | Set the timing function for the animation playback. | ease , ease-in , ease-out , ease-in-out , linear , step-start , step-end , steps(1, start) , steps(1, end) , cubic-bezier(0.1, 0.7, 1.0, 0.1) , my-custom-timingFunc |
data-jos_invoke | string | null | Set the function to be invoked when the element is scrolled into view. | function , myCustomFunction |
data-jos_invoke_out | string | null | Set the function to be invoked when the element is scrolled out of view. | function , myCustomFunction |
data-once | boolean & int | false | Set whether the element should animate only | (boolean: true, false) & (int: 0-infinity) |
data-jos_rootMargin | string | 0% -10% 0% -50% | Sets the margin for an element to animate on in a viewport when scrolled. | (string: "right% top% left% bottom%") |
data-jos_rootMargin_top | string | 0% | Sets the margin for an element to animate on the top of a viewport when scrolled. | (string: "top%") |
data-jos_rootMargin_bottom | string | 0% | Sets the margin for an element to animate on the bottom of a viewport when scrolled. | (string: "bottom%") |
data-jos_scrollDirection | string | down | Sets the direction for an element to animate on ina viewport when scrolled. | (string: "up", "down", "none") |
data-jos_startVisible | boolean & int | false | Set whether the element should start at the final state when the page is loaded (also works with delay). | (boolean: true, false) & (int: 0-10000 ms) |
data-jos_anchor | string | null | Sets the anchor element for an element to animate on in a viewport when scrolled. | (string: "#elementID") |
data-jos_scroll | string | null | Sets the callback function for an element to animate on in a viewport when scrolled. | function , your_callbackFunction |
data-jos_stagger | string | fade | Sets the stagger animation for an child stagger element to animate on in a viewport when scrolled. | string , fade |
data-jos_staggerinverse | string | static | Sets the stagger inverse animation for an child stagger element to animate on in a viewport when scrolled (play animation). | string , fade-play |
data-jos_stagger_anchor | string | null | Sets the anchor element for an child stagger element to animate on in a viewport when scrolled. | string , #elementID |
data-jos_stagger_seq | float | null | Sets the sequence delay for an child stagger element to animate on in a viewport when scrolled. | float , 0-1 |
data-jos_stagger_delay | float | null | Sets the delay for an child stagger element to animate on in a viewport when scrolled. | float , 0-1 |
data-jos_stagger_duration | float | null | Sets the duration for an element to child stagger animate on in a viewport when scrolled. | float , 0-1 |
data-jos_stagger_timing-function | string | null | Sets the timing function for an child stagger element to animate on in a viewport when scrolled. | string , ease |
data-jos_stagger_mirror | boolean | null | Sets the mirror animation for an child stagger element to animate on in a viewport when scrolled. | boolean , true , false |
data-jos_stagger_rootMargin | string | null | Sets the margin for an child stagger element to animate on in a viewport when scrolled. | (string: "right% top% left% bottom%") |
data-jos_stagger_scrollDirection | string | null | Sets the direction for an child stagger element to animate on ina viewport when scrolled. | (string: "up", "down", "none") |
data-jos_stagger_startVisible | boolean & int | null | Set whether the child stagger element should start at the final state when the page is loaded (also works with delay). | (boolean: true, false) & (int: 0-10000 ms) |
data-jos_stagger_once | boolean | null | Set whether the element should animate only once or n count. | true , false , int |
data-jos_stagger_scroll | string | null | Sets the callback function for an child stagger to animate on in a viewport when scrolled. | function , your_callbackFunction |
data-jos_stagger_invoke | string | null | Set the function to be invoked when the child stagger element is scrolled into view. | function , myCustomFunction |
data-jos_stagger_invoke_out | string | null | Set the function to be invoked when the child stagger element is scrolled out of view. | function , myCustomFunction |
Method | Description | Parameters |
---|---|---|
init() | Initialize/Reset JOS | options = {} (refer JOS.Init(options) ) |
refresh() | Refresh JOS | none |
stop() | Stop/Pause JOS | state = (0 - Stop at final state, 1 - Stop at initial state, -1 - Pause at current state) |
start() | Start/Resume JOS Service | state = (0 - Normal/Full start, -1 - Resume from current state) |
destroy() | Destroy JOS Instance | state = (0 - Destroy JOS instance excluding stylesheet, 1 - Full Destroy along with JOS-stylesheet) |
Once you are done and have finished developing a version of JOS, you can bundle it using the following command from project root :
# JOS-Animation-Library
# |-dev
# |-dist
# |-bundler
# |-config
# |-export <-- Check this folder for the output files
# |-jos.css
# |-jos.js
# |...
# |-original
# |-bundle.sh <-- Run this file to bundle JOS
# ...
# Change/Move to bundler directory
cd ./bundler
# Bundle the project
sh bundle.sh
# View the output files
ls ./export
Moved to issues
- Fork it from main branch
- Add your useful feature or fix a bug
- Commit your changes
- Create a pull request
Maybe even bundle it and test it out before sharing it with the world ;
- JOS is licensed under the MIT License.
- CIT Takshashila 23
- JOS Playground
- JOS Demo (Old)
- Jesvi Jonathan
- CSC
- Bitspace
- MS Agency
- AI Avenue
- portfolio-glasc
- resort-maquetacion
- mystep
- kazifi-landing
- npas-technoverse
- Azzle AI
(Ping Me If you have a demo ;))
- Performance, JOS has a implementation, different from others.
- Easy to use, you can use it in your projects with very minimal effort.
- JOS is lightweight (<2kb)
- Customizable with own attributes and animation.
- Open sourced and free to use