Scroll Captain

ScrollCaptain is a JS library that simplifies the creation of interactive scroll effects. It enables the definition of a trigger element whose visibility is monitored within a predefined animation area. As soon as this element enters, leaves or passes through the area, various provided actions such as CSS animations or class assignments can be triggered.

Click here and let Scroll Captain introduce himself.

---

Getting started

Here is an example of how to setup Scroll Captain.

Javascript

import { ScrollCaptain } from 'scroll-captain';

// Get the root element of the animation
const $scrollCaptain = document.querySelector('[data-scrollcaptain="root"]');

// Define a new Scroll Captain instance
if ($scrollCaptain) {
    const animation = new ScrollCaptain($scrollCaptain, {
        // Basic options
        initAttr: 'data-scrollcaptain',
        top: '-100px',
        bottom: '20%',
        triggerPosition: 0.5,
        
        // Animation options
        animateText: {
            targetSuffix: 'text',
            easing: 'ease-out',
            duration: 0.5,
            onscroll: true,
            translateY: { 0: -100, 100: 0 }
        }
    });
}

HTML

Assign the data attributes to your HTML elements.

If the root element should act as the trigger:

<section data-scrollcaptain="root">
    <p data-scrollcaptain="target">I will be animated.</p>
</section>

If an element within the root element should act as the trigger:

Enter a name in the triggerSuffix option, e.g. 'trigger' and assign the data attribute with the suffix to the desired element.

<section data-scrollcaptain="root">
    <div data-scrollcaptain="trigger">
        <p data-scrollcaptain="target">I will be animated.</p>
    </div>
</section>

---

Instance options

Basic options

Option	Type	Default value	Description
initAttr	string	data-scrollcaptain	Identifying data attribute.
triggerSuffix	string	null	Suffix for defining a trigger element within the passed root element.
triggerIndex	number	-1	Current instance index among several instances (only necessary for animation of global elements to identify the trigger priority).
triggerPosition	number	0	Value between 0 and 1 that specifies how much of the trigger must be in the animation area to trigger the animation. Examples: 0: As soon as a part is visible, 0.8: at least 80%, 1: Full element
top	string	null	Defines the upper limit of the animation area. The value describes the distance to the upper viewport border and can be specified in px or %. null: Upper viewport border, '200px': 200px below the upper viewport border, '-40%': 40% above the upper viewport border
bottom	string	null	Defines the lower limit of the animation area. The value describes the distance to the lower viewport border and can be specified in px or %. For more information see the section top
cssSpace	string	null	Name for a CSS variable that is passed to the root element and contains the height of the animation area as a value.
onInit	function	null	A callback function that is called when the instance is initialised (the animation progress is passed as a parameter).
onEnter	function	null	A callback function that is called when the trigger enters the animation area (the animation progress is passed as a parameter).
onLeave	function	null	A callback function that is called when the trigger leaves the animation area (the animation progress is passed as a parameter).
onScroll	function	null	A callback function that is called for each scroll event when the trigger scrolls through the animation area (the animation progress is passed as a parameter).
onResize	function	null	A callback function that is called when the size of the browser window is changed (the animation progress is passed as a parameter).
updateOnResize	function	null	A callback function that is called when the size of the browser window is changed. Useful for adjusting options that affect the animation area before the change.
devMode	boolean	false	Logs information about the animation settings to the console.
breakpoints	object	null	An object with settings for different screen sizes. Breakpoints function as minimum values for the screen width.
animate + CustomKey	object		See section Animation options.

Animation options

Several animations can be defined per instance. This means that one and the same trigger can initiate different actions. All you need to do is create a key containing the word "animate" in the options. It is then recognised as a new animation object and receives standard options that can be overwritten as required. The following options can be used:

Option	Type	Default value	Description
targetSuffix	string	target	Suffix for defining the target elements on which the animation is to be triggered.
globalTarget	boolean	false	Defines whether the target elements are to be searched for in the root element or in the entire DOM.
sticky	boolean	false	Sets the target elements sticky along the entire animation area.
class	string	null	A class that is added to the target elements when the animation is active and removed when it is inactive.
onscroll	boolean	false	Specifies the animation type. If activated, animations are triggered synchronously with the user's scrolling behaviour. If deactivated, animations are triggered in one go via keyframe animation.
resetOnScrollDown	boolean	true	If activated, keyframe animations are reset and classes are removed as soon as the animation area is exited when scrolling down. Otherwise they remain unchanged.
resetOnScrollUp	boolean	true	If activated, CSS animations are reset and classes are removed as soon as the animation area is exited when scrolling upwards. Otherwise they remain unchanged.
improvePerformance	boolean	true	By default, the element is assigned the will-change property to improve performance. If this is not desired, it can be deactivated.
easing	string	linear	Determines the speed of a transition. All values permitted for the CSS property Easing can be used.
duration	number or object of type { time: number, multiplier: number }	0.2	Defines the transition duration. If there are several elements, the duration can be multiplied for each additional element.
delay	number or object of type { time: number, multiplier: number }	null	Defines the transition delay. If there are several elements, the delay can be multiplied for each additional element.
opacity	number or object with animation sections, e.g. { 0: number, 50: number, 100: number }	null	If a number is defined, the animation is animated from the initial state of the element to this value. If an object with animation sections is defined, the animation is animated according to the current animation progress between the specified values.
backgroundColor, color, borderColor, borderTopColor, borderRightColor, borderBottomColor, borderLeftColor, fill, stroke	string or object with animation sections, e.g. { 0: string, 50: string, 100: string }	null	Defines a new colour value for the corresponding CSS property. If a string is defined with a colour value, the original colour value of the element is animated to this value. If an object is defined with animation sections, the animation is animated according to the current animation progress between the specified colour values. The colour string may look as follows: 'rgb(r,g,b)', 'rgba(r,g,b,a)', '#rgb', '#rgba','#rrggbb' or '#rrggbbaa'.
translateX, translateY, translateZ, perspective, rotate, rotateX, rotateY, rotateZ, scale, scaleX, scaleY, scaleZ, skewX, skewY	number or object with animation sections, e.g. { 0: number, 50: number, 100: number }	null	Defines a new value for the corresponding Transform property. If an object is defined with animation sections, the animation is animated according to the current animation progress between the specified values.

---

Methods

Update

The update method can be used to perform an update after changes have been made to the options.

const animation = new ScrollCaptain($scrollCaptain, {
    top: '20px'
    // Other options ...
});

animation.defaultOptions.top = '50px';
animation.update();

---

Customisable options

These options can be changed using breakpoints or the update method:

Instance options

top, bottom, triggerPosition, cssSpace

Animation options

sticky, easing, duration, delay, opacity, backgroundColor, color, borderColor, borderTopColor, borderRightColor, borderBottomColor, borderLeftColor, fill, stroke, translateX, translateY, translateZ, perspective, rotate, rotateX, rotateY, rotateZ, scale, scaleX, scaleY, scaleZ, skewX, skewY