/JOS-Animation-Library

A fullblown in-house animation library that can add instant scroll animation to all elements in your website, making it look beautiful & professional. Comes with tons of customization options but is still easy to use, all in a small footprint

Primary LanguageJavaScriptMIT LicenseMIT


JOS-Animation

JOS : Animation Library

A simple & easy to use animation library for web developers

JOS-Animation npm version

Git Pages · Playground Demo · Report Bug · Request Feature

About This Project

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

jos-animation-Badge jos-animation-Badge

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

jos-animation-Badge jos-animation-Badge

jos-animation-Badge jos-animation-Badge

jos-animation-Badge jos-animation-Badge

jos-animation-logo jos-animation-logo

jos-animation-logo jos-animation-logo jos-animation-logo jos-animation-logo

jos-animation-image jos-animation-image

Video Tutorial

JOS-Animation v0.6 JOS V0.6 Cubes (Outdated | Latest : v0.8.8)


JOS v0.8.8 18 July 2023 Jesvi Jonathan


Built With

Installation

  1. Add the <link> inside the <head> tag :
<link
  id="jos-stylesheet"
  rel="stylesheet"
  href="https://unpkg.com/jos-animation/dist/jos.css"
  crossorigin="anonymous"
/>
  1. Add the <script> right after the <body> tag : 
<script src="https://unpkg.com/jos-animation/dist/jos.min.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

Setup

  1. Use JOS.init(); to initialize the library with default settings.
<!-- Initialize JOS with default settings -->
<script>
  JOS.init();
</script>
  1. (Or) Use JOS.init(options); to overide the default settings with your custom settings.
<!-- Global Parameters -->
<script>
  JOS.init({
    // disable: false, // Disable JOS gloabaly | 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 gloabal 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 (automaticaly 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 :  _% _% _% _%  (automaticaly set)
  });
</script>
  1. Set class="jos" to the element you want to animate :
<!-- JOS class is required to animate the element -->
<div class="jos"></div>
  1. 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_invoke="myCustomFunction"
  data-jos_invoke_out="myCustomFunction_onExit"
  data-jos_anchor="#elementID"
></div>

See JOS Props for full information regarding the animation, attributes, and options.

Custom Animation

  1. 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 */
}
  1. Use your cutom animation by setting the data-jos_animation attribute to my-custom-animation :
<div class="jos" data-jos_animation="my-custom-animation"></div>

Example : Custom Animation

Custom Inverse Animation

  1. 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 */
}
  1. Use your cutom inverse animation by setting the data-jos_animationInverse attribute to my-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.

Example : Custom Inverse Animation

Playable Animation

  1. 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);
  }
}
  1. Use the playable animation by setting the data-jos_animation attribute to my-custom-animation & data-jos_animationInverse attribute to my-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

Custom Timing Function

  1. 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;
}
  1. Use your cutom timing function by setting the data-jos_timing-function attribute to my-custom-timing-function :
<div class="jos" data-jos_timing-function="myCustom-timingFunc"></div>

Example : Custom Timing Function

Anchors to trigger animation

  1. Create an element that you want to use as an anchor & add an id to it :
<!-- My reference anchor element -->
<div id="myElement"></div>
  1. 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

Direction Based Animation

  1. 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 partciluarly useful when you want to animate an element when it is scrolled into view from a particular direction.

Example : Direction Based Animation

Start Visible

  1. 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 visivle when the page is loaded. you can add a delay to it by setting the value in ms :

<!-- My animated element that is visivle with a given timer/delay in ms-->
<div class="jos" data-jos_startVisible="3000"></div>

This sets the element to be visivle when the page is loaded after 3000ms 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 Custom Function

  1. Create a custom function by adding the following code to your script :
// Create a custom function
function myCustomFunction() {
  // Do something
}
  1. Use your cutom function by setting the data-jos_invoke attribute to myCustomFunction :
<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

JOS Attributes

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")

JOS Methods

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)

Bugs and Issues

Moved to issues

Contributing

  • Fork it from main branch
  • Add your useful feature or fix a bug
  • Create a pull request

License

Used In

(Ping Me If you have a demo)

Why use JOS ?

  • 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

Credits

This project was solely developed by Jesvi Jonathan