lax.js

Simple & lightweight (<4kb gzipped) vanilla JavaScript library to create sm...

Scrolling
alexfoxy/lax.jslax.js

README

lax.js


Simple & lightweight (<4kb gzipped) vanilla JavaScript library to create smooth & beautiful animations when you scroll.

Lax 2.0 Gif

>> DEMO <<

What's new with Lax.js 2.0

Lax.js 2.0 has been completely re-written with a focus on modularity and flexibility giving you more tools to create awesome animations.
- New javascript animation syntax, allowing for more advanced effect combos
- Use any value to drive animations, for example mouse position, time of day .. and of course scroll!
- Animations can be given inertia when scrolling
- Create custom CSS bindings
- Animation easings
- And much more..

Examples

- Scroll effect
- Horizontal snap scroll
- Inertia
- Video/Gif playback
- Cursor position
- Text input
- Update HTML content
- Preset Explorer


Documentation


1. Getting started


- Setup
- Using presets
- Usage with UI frameworks
- Adding drivers
- Adding elements

2. Going deeper


- Custom animations
- Optimising performance

3. Glossary


- CSS properties
- Special values
- Supported easings

Getting started


NPM Setup


  1. ``` sh
  2. # https://www.npmjs.com/package/lax.js

  4. npm install lax.js
  5. yarn add lax.js
  6. ```
  1. ``` js
  2. import lax from 'lax.js'
  3. ```

HTML setup


  1. ``` html
  2. <script src="path-to-lax.min.js"></script>
  3. <script src="https://cdn.jsdelivr.net/npm/lax.js" ></script>
  4. ```


Setup


To implement lax you need to create at least one _driver_, to provide values for animations, as well as the element animation bindings. Below is a simple example:

  1. ``` html
  3. <script>
  4.   window.onload = function () {
  5.     lax.init()
  7.     // Add a driver that we use to control our animations
  8.     lax.addDriver('scrollY', function () {
  9.       return window.scrollY
  10.     })
  12.     // Add animation bindings to elements
  13.     lax.addElements('.selector', {
  14.       scrollY: {
  15.         translateX: [
  16.           ["elInY", "elCenterY", "elOutY"],
  17.           [0, 'screenWidth/2', 'screenWidth'],
  18.         ]
  19.       }
  20.     })
  21.   }
  22. </script>
  23. <div class="selector">Hello</div>
  24. ```

Using presets


The easiest way to get started is to use presets via html classes. For example:

  1. ``` html
  2. <div class="lax lax_preset_fadeIn:50:100 lax_preset_spin"></div>
  3. ```

Multiple presets can be chained together and they can be customised to suit your needs. Use the preset explorer to explore effects and see a simple example here.

DOM behavior and usage with Frameworks


To increase performance, lax.js indexes the list of elements to animate when the page loads. If you're using a library like React, Vue or EmberJS, it is likely that you are adding elements after the initial window.onload. Because of this you will need to call lax.addElements when you add components to the DOM that you want to animate, and lax.removeElements when the component unmounts.

Please find a React example here. Other examples will be available soon for Vue.js and Angular.

Adding drivers


Drivers provide the values that _drive_ your animations. To set up a driver just call lax.addDriver with a name and a function which returns a number. This method is called every frame to calculate the animations so keep the method as computationally _light_ as possible. The example below will be the most common use case for lax which returns the scrollY position of the window.

  1. ``` js
  2. lax.addDriver(
  3.   'scrollY',                          // Driver name
  4.   function(laxFrame) {                    
  5.     return window.scrollY    // Value method
  6.   },
  7.   { }                                 // Options
  8. )
  9. ```

Driver options


inertiaEnabled: boolean = false


If enabled, the driver will calculate the speed at which its value is changing. Used to add inertia to elements using the inertia element option.

See this in action in the here.

frameStep: number = 1


By default each driver updates its value every animation frame, around 60 times per second. You can use the frameStep to reduce frequency of the driver value updating. For example a value of 2 would only update 30 times per second and a value of 60 would only update about once per second.

Adding elements


You can add lax animations to an element using the addElements method:

  1. ``` js
  2. lax.addElements(
  3.   '.selector',  // Element selector rule
  4.   {             // Animation data
  5.     scrollY: {  
  6.       opacity: [
  7.         [0, 100],
  8.         [1, 0]
  9.       ]
  10.     }
  11.   },
  12.   {            
  13.     style: {}   // Element options
  14.   }
  15. )
  16. ```

Element options


style: StyleObject


Add static CSS to each element, for example:

  1. ```css
  2. {
  3.   transform: '200ms scale ease-in-out';
  4. }
  5. ```

onUpdate: (driverValues: Object, domElement: DomElement) => void

A method called every frame with the current driverValues and domElement. This could be used to toggle classes on an element or set innerHTML. See it in action here.

The driver values are formatted as follows:
  1. ``` js
  2. {
  3.   scrollY: [  // Driver name
  4.     100,      // Driver value
  5.     0         // Driver inertia
  6.   ]
  7. }
  8. ```

Going deeper


Custom animations

Custom animations are defined using an object.

  1. ``` js
  2. // Animation data
  3. {
  4.   scrollY: {                // Driver name
  5.     translateX: [           // CSS property
  6.       ['elInY', 'elOutY'],  // Driver value map
  7.       [0, 'screenWidth'],   // Animation value map
  8.       {
  9.         inertia: 10        // Options
  10.       }
  11.     ],
  12.     opacity: [
  13.       // etc
  14.     ]
  15.   }
  16. }
  17. ```

Driver name

The name of the driver you want to use as a source of values to map to your animation, for example, the document's scrollY position. Read about adding drivers here.

CSS property

The name of the CSS property you want to animate, for example opacity or rotate. See a list of supported properties here.

Some CSS properties, for example box-shadow, require a custom function to build the style string. To do this use the cssFn element option.


Value maps

The value maps are used to interpolate the driver value and output a value for your CSS property. For example:

  1. ``` js
  2. [0, 200, 800]  // Driver value map
  3. [0, 10,  20]   // Animation value map

  5. // Result

  7. | In  | Out |
  8. | --- | --- |
  9. | 0   | 0   |
  10. | 100 | 5   |
  11. | 200 | 10  |
  12. | 500 | 15  |
  13. | 800 | 20  |
  14. ```

Within the maps you can use strings for simple formulas as well as use special values. e.g:

  1. ``` js
  2. ['elInY', 'elCenterY-200', 'elCenterY',
  3. ```

See a list of available values here.

You can also use mobile breakpoints within animation maps for more flexibility.

  1. ``` js
  2. scrollY: {
  3.   translateX: [
  4.     ['elInY', 'elCenterY', 'elOutY'],
  5.     {
  6.       500: [10, 20, 50], // Screen width < 500
  7.       900: [30, 40, 60], // Screen width > 500 and < 900
  8.       1400: [30, 40, 60], // Screen width > 900
  9.     },
  10.   ];
  11. }
  12. ```

Options


modValue: number | undefined

Set this option to modulus the value from the driver, for example if you want to loop the animation value as the driver value continues to increase.

frameStep: number = 1

By default each animation updates its value every animation frame, around 60 times per second. You can use the frameStep to reduce frequency of the animation updating. For example a value of 2 would only update 30 times per second and a value of 60 would only update about once per second.

inertia: number

Use to add inertia to your animations. Use in combination with the inertiaEnabled driver option.

See inertia in action here.


inertiaMode: "normal" | "absolute"

Use in combination with inertia. If set to absolute the inertia value will always be a positive number via the Math.abs operator.

cssUnit: string = ""

Define the unit to be appended to the end of the value, for example
For example px deg

cssFn: (value: number, domElement: DomElement) => number | string

Some CSS properties require more complex strings as values. For example, box-shadow has multiple values that could be modified by a lax animation.

  1. ``` js
  2. // Box-shadow example
  3. (val) => {
  4.   return `${val}px ${val}px ${val}px rgba(0,0,0,0.5)`;
  5. };
  6. ```

easing: string

See a list of available values here.

Optimising performance

Lax.js has been designed to be performant but there are a few things to bare in mind when creating your websites.
- Smaller elements perform better.
- Postion fixed and absolute elements perform best as they do not trigger a layout change when updated.
- Off-screen elements do not need to be updated so consider that when creating your animation value maps.
- The css properties blur, hue-rotate and brightness are graphically intensive and do not run as smoothly as the other available properties.

Glossary


CSS properties


name
----------
opacity
scaleX
scaleY
scale
skewX
skewY
skew
rotateX
rotateY
rotate
translateX
translateY
translateZ
blur
hue-rotate
brightness

Special values


keyvalue
--------------------------------------------------------------------------------------------
screenWidthcurrent
screenHeightcurrent
pageWidthwidth
pageHeightheight
elWidthwidth
elHeightheight
elInYwindow
elOutYwindow
elCenterYwindow
elInXwindow
elOutXwindow
elCenterXwindow
indexindex

Supported easings


name
--------------
easeInQuad
easeOutQuad
easeInOutQuad
easeInCubic
easeOutCubic
easeInOutCubic
easeInQuart
easeOutQuart
easeInOutQuart
easeInQuint
easeOutQuint
easeInOutQuint
easeOutBounce
easeInBounce
easeOutBack
easeInBack