Stickymate is a tool that designed to help web developers easily create animations without JavaScript knowledge, just setting animation params directly in the HTML markup. Stickymate combines extended sticky positioning and scroll-based animation features, so it can catch an element on the screen and animate it while the user scrolls the page. It is also possible to add and remove classes to control animation from CSS. And one more thing, you can synchronize an animations of different elements to the vertical position of one of them.

Demo

Stickymate demonstration

Installing

• Download and unzip
• Include stickymate.js at the head section or at the end of the body tag.

Usage

• Add a data-sticky, data-animation, data-classes attributes to your element apart or together.

<div data-sticky="..." data-animation="..." data-classes="..."></div>

• Set parameters for attributes.

<div data-sticky="from: 0, duration: 100vh" data-animation="opacity: {0: 1, 100vh: 0}" data-classes="0vh: {add: class2, remove: class1}"></div>

• About keys and values.

<div
    data-sticky="
        from: position,        // position from the top of the viewport when the element sticks to the screen
        duration: position     // position when the element will no longer sticky, extends the min-height of the parent container
    "
    data-animation="
        CSS property: {
            position: value,   // animate from
            position: value,   // optional, intermediate keys (.. to / from ..)
            position: value    // animate to
        },
        CSS property: {...}    // optional, additional CSS properties
    "
    data-classes="
        position: {                      // position from the top of the viewport
            add: classname classname,    // class names (one or more separated by a space) to be added
            remove: classname classname  // class names (one or more separated by a space) to be removed
        },
        position: {...}.                 // optional, another position do add or remove classes
    "
    data-sync-with="
        id: value              // value is an id of the element to synchronize animation with
    "
></div>

• The data-sticky attribute can contain only two params, namely from and duration.
• If you specify duration of data-sticky element greater than 0, the parent container will be automatically extended vertically to the specified height.
• The data-classes attribute can contain add and remove keys separately or together.
• The add and remove keys of the data-classes attribute can contain one classname or several, separated by spaces.
• The data-animation attribute can contain one or more animated CSS properties, separated by commas.
• Every data-animation CSS property can contain two or more position keys, separated by commas.
• Set the name of animated CSS property without any vendor prefixes (-webkit- is added automatically).
• Units of position keys should be px (pixels), vh (viewport height) or vw (viewport width).
• You can set from position for data-sticky attribute like a top / center / bottom.

<div data-sticky="from: center, duration: 100vh"></div>

• Units and values of data-animation CSS property values are set the same as in CSS.
• 0 position can be set without units.
• -100vh = top of element reached the bottom of the viewport.
• 0vh or 0px or just 0 = top of element reached the top of the viewport.
• 100vh = top of element reached the top of the viewport + one screen height has been scrolled after this.

Examples

• A few attributes at once. In this example, the element sticks to the screen and its opacity changes from 1 to 0 while the user scrolls the page one viewport height. After that the class class1 will be added to the element.

<div data-sticky="from: 0, duration: 100vh" data-animation="opacity: {0: 1, 100vh: 0}" data-classes="100vh: {add: class1}"></div>

• Sticky element. When top of the element reaches the top of the viewport (from: 0), it will stick on the screen until you scroll up two viewport height (duration: 200vh) from that moment.

<div data-sticky="from: 0, duration: 200vh"></div>

• Animated element with one CSS property and two position keys. While top of the element traverse from bottom of the viewport -100vh to the middle of the viewport -50vh, its opacity changes from 0 to 1. Same as opacity: 0; and opacity: 1; in the CSS. Visually, this is a fade-in effect.

<div data-animation="opacity: {-100vh: 0, -50vh: 1}"></div>

• Animation with one CSS property and multiple position keys. In this example, the opacity of an element changes in two stages, from 0 to 1 (the top of the element moves along the lower quarter of the viewport: -100vh, -75vh) and then from 1 to 0.25 (the top of the element moves along the upper quarter of the viewport: -25vh, 0vh).

<div data-animation="opacity: {-100vh: 0, -75vh: 1, -25vh: 1, 0vh: .25}"></div>

• Animation of transform CSS property with several values at once.

<div data-animation="transform: {-100vh: scale(1) translate(0, 0) rotate(0), -50vh: scale(.5) translate(50%, 0) rotate(22.5deg)}"></div>

• Animation with multiple CSS properties. Each CSS property has its own positioning keys and values.

<div data-animation="opacity: {-100vh: 0, -75vh: 1}, transform: {-100vh: scale(.75), -50vh: scale(1)}"></div>

• Adding and Removing Classes. Examples can be seen in the right column of the Demo, where active keys are highlighted by classes.

<div data-classes="25vh: {add: class1}, 50vh: {add: class2 class3, remove: class1}, 75vh: {remove: class2 class3}"></div>

• Synchronize an animations of different elements (followers) to one of them (leader). It works as if the follower's vertical position pretend to be the same as the leader's vertical position (without moving physically), just like a follower is located exactly where leader is located vertically. That is, when the leader's top touches the top of the viewport, it will be 0vh for him and for all of the followers too, and their animations will fire simultaneously.

<div data-animation="..." id="leader"></div>
<div data-animation="..." data-sync-with="id: leader"></div>

Animated CSS properties

• You can animate any CSS property whose value contains just numbers or numbers in %, px, vw, vh, em, rem, deg.
• You cannot animate a color CSS property and a properties whose value contains: left, right, top, bottom, center, none, auto, transparent etc.
• Validated CSS properties:
  • transform: matrix() scale() translate() rotate() translate3D() rotate3D()
  • opacity: 0-1
  • background-size: ...
  • background-position: ...
  • border: ...
  • font-size: ...

Browser compatibility

All modern browsers that support ECMAScript 6

• Chrome: 56
• Edge: 16
• Firefox: 48
• Internet Explorer: No
• Opera: 43
• Safari: 10
• Chrome on Android: 56
• Firefox on Android: 59
• Safari on iOS: 10

Version history

• 1.2.5
  • Parameters setting has been simplified. Old syntax: data-sticky='{"from": "0vh", "duration": "100vh"}'. New syntax: data-sticky="from: 0vh, duration: 100vh".
  • New data-classes attribute. Now you can add/remove one or more CSS classnames to element on specified key.
  • Multiple transform values, like scale(...), translate(...) etc, are now automatically sorted in the same order for every key.
  • Release on npm.
• 1.3.0
  • Tracking elements with IntersectionObserver instead of constantly listening for the scroll event.
• 1.3.3
  • Incorrect calculation of parent element position type has been fixed.
• 1.3.6
  • Keys are now automatically sorted in order, which eliminates animation glitches if keys are specified in random order.
• 1.4.0
  • Added data-sync-with attribute that help to fire an animations of different elements simultaneously.

Known minor issues

• Sticky element and parents overflow property. Any parent of data-sticky element should not have an overflow property. Read more about the issue: Support position:sticky inside an overflow:hidden|auto on general parents. If your animation overflows an element (any transformation that enlarges an element and creates a horizontal scroll bar) and you need to use overflow: hidden, just follow this scheme:
  • Doesn't work: element with overflow: hidden > sticky & animated element.
  • Work: sticky element with overflow: hidden > animated element.
• Matrix and rotation. Don't try to rotate the element with the transform: matrix() because script doesn't calculate sin and cos for correct transformation. To rotate, use transform: rotate().
• Scrolling in Edge (EdgeHTML only). Periodic bugs in positioning animated elements inside parent with overflow: hidden when scrolling in the opposite direction.
• Setting animations to subelements of SVG line path or line. The first issue is that IntersectionObserver can't detect SVG in some cases so you need to turn it off by replacing value true to false on line 537 in the stickymate.js. The second issue is getting correct vertical position of subelements inside SVG that is complicated because SVG has its own inner html structure. The workaround is to use data-sync-with="id: ..." attribute and sync animated subelements with some other element like its parrent/wrapper.

Author and license

Michael Rafailyk - michaelrafailyk on GitHub. Project is licensed under the MIT License - see the LICENSE.md file for details.