olivier3lanc / Scroll-Btween

ScrollBtween uses scroll position of document - or any DOM element - to tween CSS values on any DOM element.

Scroll Btween

Documentation and examples

Scroll Btween was crafted to simply tween any CSS values on any DOM element in relation with its position into the viewport.

Showcase

Examples

• Colors
• Image reveal
• Page progress
• Parallax
• Star Wars
• Text background clip
• Text slides
• Without Ola
• With Ola

Key Features

• Native Javascript
• No dependencies
• Easy to use see usage
• You can tween multiple CSS properties at the same time
• You can add multiple tweens on the same CSS property

Support

Browser	Mobile	Desktop
Chrome	✅	✅
Safari	✅	✅
Firefox	✅	✅
Opera	✅	✅
Chromium based browsers (Vivaldi, Brave, ...)	✅	✅

Demo on parallax images

Installation

Include Javascript file scroll-btween.js just before the end body tag </body>. For smoother results, use the great tweener library ola.js

Place Ola always before scroll-btween.js

Local

• Download ola.min.js (optional)
• Download scroll-btween.js

<!-- Optional - but recommended - always before scroll-btween.js -->
<script src="path/to/ola.min.js"></script>
<!-- Required -->
<script src="path/to/scroll-btween.js"></script>

CDN

via https://www.jsdelivr.com/

<!-- Ola.js lastest version -->
https://cdn.jsdelivr.net/gh/franciscop/ola/ola.min.js
<!-- Minified Scroll Btween lastest version -->
https://cdn.jsdelivr.net/gh/olivier3lanc/Scroll-Btween/js/scroll-btween.min.js

Usage

Documentation

The Scroll Btween syntax follows the CSS value inline syntax. You can add as much tweens as you want. You can even add multiple tweens on the same CSS property. You can specify the tween to apply as follows:

Global parameters

Documentation

Adjustable global parameters accessible in scoll-btween.js

scrollBtween.defaults.	Type	Default	Description
tweenerIntervalinMs	integer	300	Smoothness of the change. Available only if Ola tweener is enabled, duration between to tweens

<!-- Syntax -->
<div    scroll-btween="[YOUR_UNIQUE_ID]"
        data-[CSS_PROPERTY]="|[X1] to [Y1]|...|[X2] to [Y2]|..."></div>

<!-- Example 1 -->
<p scroll-btween="foo" data-left="|-50 to 50|%">A paragraph</p>
<!-- Example 2 -->
<p  scroll-btween="foo2" 
    data-transform="translateX(|-100 to 0|%) translateY(|50 to 0|%) scale(|1 to 2|)">Another paragraph</p>
<!-- Example 3 -->
<p  scroll-btween="foo3" 
    data-background-color="rgba(|34 to 255|, |255 to 128|, 50, |1 to 0.2|)" 
    data-padding="|2 to 3|em |1 to 3|em">Another paragraph</p>

• scroll-btween="[YOUR_UNIQUE_ID]" Declaration to assign CSS tweening on this node.
• data-[CSS_PROPERTY]="|X to Y|" Enter standard CSS value expression specifying numeric values to tween between pipes |X to Y|.
  • data-[CSS_PROPERTY] specifies the CSS property onto which applying the tween. For example data-color or data-width etc.
  • X is the start value when the element not visible into the viewport yet - intersection is below 0.
  • [space]to[space] is the operator to enter between X start value and Y end value.
  • Y is the end value when the element has passed the viewport - intersection is over 1.

Detector

Documentation

By default, scroll binded elements are their own detector: It means the intersection is computed in relation with this element itself. But it possible to assign another DOM element as detector for the intersection.

<h2 scroll-btween="foo" 
    data-detector="detector" 
    data-background-color="rgb(|0 to 255|,|255 to 0|,0)">
    I am foo: Green until detector passes.<br>
    I fade to red when my detector passes the viewport.
</h2>
<p id="detector">I am the detector for <strong>foo</strong></p>

Keyframes

Documentation

As seen earlier, intersection is based on the position of the element - or its detector - into the viewport. It is possible to split the transition into multiple parts using keyframes with the following syntax:

• data-[CSS_PROPERTY]="|0:V to a:W to b:X to c:Y to 100:Z|" A CSS property is set with keyframes.
• 0, a, b and c, 100 are percentages of the element's position into the viewport. a < b < c keyframes percentages always start from 0 and go to 100.
• V is the start value of the CSS property when intersection is equal (in percent) to 0.
• W is the start value of the CSS property when intersection is equal (in percent) to a.
• X is the start value of the CSS property when intersection is equal (in percent) to b.
• Y is the intermediate value of the CSS property when intersection is equal (in percent) to c.
• Z is the intermediate value of the CSS property when intersection is equal (in percent) to 100.
• etc

<h2 scroll-btween="foo"
    data-padding-left="|0:0 to 50:150 to 100:150|px">
    I get 150px of padding left and sto growing when i reach the middle of the screen.
</h2>
<h2 scroll-btween="bar"
    data-padding-left="|0:0 to 40:0 to 60:150 to 100:150|px">
    I go from 0px to 150px of padding left when i roam between 40% and 60% of the screen.
</h2>

Methods

Scroll Btween comes with the following methods.

• scrollBtween.getIntersection(element) Returns the intersection value of the specified element.
• scrollBtween.update() Start Scroll Btween or update instances if DOM has changed.
• scrollBtween.stop() Stops all tweens, disable all tweens.
• scrollBtween.start() Start all tweens.

How it works

Documentation

The following playground shows the associated intersection with its id which is the key value to sync CSS properties.

• Below 0 the element is below the viewport.
• Between 0 and 1 the element is into the viewport.
  • Just above zero, the top of the element has just entered the viewport.
  • Around 0.5, the middle of the element is at the middle of the viewport.
  • Just inferior to 1, the bottom of the element is about to leave the viewport.
• Above 1 the element has been already scrolled into the viewport.

Credits

Photo credits Olivier 3lanc

License

MIT License

Copyright 2022 Olivier 3lanc

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.