# 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](https://kira-e.gitlab.io/scroll-captain/) and let Scroll Captain introduce himself.
---
## Getting started
Here is an example of how to setup Scroll Captain.
### Javascript
``` js
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:
``` html
```
##### 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.
``` html
```
---
## 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.
``` js
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`