--- url: /reference/items/ScrollAnimation/js-api.md --- # JS API ## ScrollAnimationTimeline A parent component that manages scroll-based animations for its children `ScrollAnimationTarget` components. The timeline watches for its position in the viewport and propagates the scroll progress to all its children. This component is based on the [`withScrolledInView`](https://js-toolkit.studiometa.dev/api/decorators/withScrolledInView.html) decorator from the `@studiometa/js-toolkit` package and inherits all of its options. ### Usage ```js import { Base, createApp } from '@studiometa/js-toolkit'; import { ScrollAnimationTimeline, ScrollAnimationTarget } from '@studiometa/ui'; class App extends Base { static config = { name: 'App', components: { ScrollAnimationTimeline, ScrollAnimationTarget, }, }; } export default createApp(App, document.body); ``` ```html
Content
``` ### Options #### `debug` * Type: `boolean` * Default: `false` Enable debug mode to display visual markers showing the scroll animation's start/end positions and current progress. This is useful during development to understand how the scroll animation is triggered. :::warning To use the debug option, you must wrap your `ScrollAnimationTimeline` with the `withScrollAnimationDebug` decorator. This allows the debug code to be tree-shaken from production bundles. ::: When enabled, the following elements are displayed: * A dashed outline around the timeline element * Start and end markers on the right side of the viewport * A progress bar and percentage indicator ```js {5,12} import { Base, createApp } from '@studiometa/js-toolkit'; import { ScrollAnimationTimeline, ScrollAnimationTarget, withScrollAnimationDebug, } from '@studiometa/ui'; class App extends Base { static config = { name: 'App', components: { ScrollAnimationTimeline: withScrollAnimationDebug(ScrollAnimationTimeline), ScrollAnimationTarget, }, }; } ``` ```html {2}
...
``` :::code-group ```js import { registerComponent } from '@studiometa/js-toolkit'; import { ScrollAnimationTimeline, ScrollAnimationTarget, withScrollAnimationDebug, } from '@studiometa/ui'; registerComponent( withScrollAnimationDebug(ScrollAnimationTimeline), 'ScrollAnimationTimeline', ); registerComponent(ScrollAnimationTarget); ``` ::: #### `offset` * Type: `string` * Default: `"start end / end start"` Defines the limits used to calculate the progress of the scroll. The value is a string composed of two parts separated by a slash (`/`). Each part defines the point on which the progress calculation should be based. ``` / ``` The default value `start end / end start` could be read as: calculate the progress of the target from when the **start** of the target crosses the **end** of the viewport to when the **end** of the target crosses the **start** of the viewport. Each point accepts the following values: * A **number** between `0` and `1` * A **named string**, either `start`, `end` or `center` which will be mapped to values between `0` and `1` * A **string** representing a CSS value with one of the following unit: `%`, `px`, `vw`, `vh`, `vmin`, `vmax` **Common offset patterns:** | Offset | Description | | ----------------------------- | ------------------------------------------------------------------- | | `"start end / end start"` | Default. Animation plays while element is visible in viewport | | `"start center / end center"` | Animation plays while element crosses the center of viewport | | `"start start / end start"` | Animation plays while element is at the top of viewport | | `"start end / end end"` | Animation plays while element is at the bottom of viewport | | `"start start / end end"` | Animation plays from when element enters until it completely leaves | ```html {2}
Animates as element crosses viewport center
``` :::code-group ```js import { registerComponent } from '@studiometa/js-toolkit'; import { ScrollAnimationTimeline, ScrollAnimationTarget, withScrollAnimationDebug, } from '@studiometa/ui'; registerComponent( withScrollAnimationDebug(ScrollAnimationTimeline), 'ScrollAnimationTimeline', ); registerComponent(ScrollAnimationTarget); ``` ::: ### Children Components #### `ScrollAnimationTarget` * Type: `ScrollAnimationTarget[]` Array of child animation targets that will be animated based on the scroll progress of the timeline. *** ## ScrollAnimationTarget A component that animates based on scroll progress from a parent `ScrollAnimationTimeline`. Each target can have its own animation keyframes, play range, and damping settings. ### Usage ```html
First element
Second element
``` ### Options #### `playRange` * Type: `[number, number] | [number, number, number]` * Default: `[0, 1]` Define the scroll progress range when the animation should play. Values between 0 and 1, where 0 is when the timeline enters the viewport and 1 is when it exits. ```html {4,11}
First (animates from 0% to 50% scroll)
Second (animates from 50% to 100% scroll)
``` ##### Staggered animation Staggered scroll animation can be created by giving 3 numbers to the `playRange` option: * `index`: the current index of the items in the staggered list * `length`: the length of the staggered items * `step`: the delay to apply between each item in the staggered list ```html {4,10}
...
...
``` The following example uses Twig `loop.index0` and `loop.length` variables to generate `data-option-play-range` attributes with a staggered effect. :::code-group ```js import { registerComponent } from '@studiometa/js-toolkit'; import { ScrollAnimationTimeline, ScrollAnimationTarget } from '@studiometa/ui'; registerComponent(ScrollAnimationTimeline); registerComponent(ScrollAnimationTarget); ``` ::: ##### Sequentially ordered animation Use the `[index, length, step]` format for the `data-option-play-range` attribute value with a `step` value set to `1 / length` to make each animation play sequentially. :::code-group ```js import { registerComponent } from '@studiometa/js-toolkit'; import { ScrollAnimationTimeline, ScrollAnimationTarget } from '@studiometa/ui'; registerComponent(ScrollAnimationTimeline); registerComponent(ScrollAnimationTarget); ``` ::: #### `from` * Type: `object` * Default: `{}` Initial keyframe for the animation. Define CSS properties as key-value pairs. ```html {4}
...
``` #### `to` * Type: `object` * Default: `{}` Final keyframe for the animation. Define CSS properties as key-value pairs. ```html {4}
...
``` #### `keyframes` * Type: `keyFrame[]` * Default: `[]` Array of keyframes for complex animations. When provided, `from` and `to` are ignored. ```html
...
``` See the following types definitions and [the `animate` documentation](https://js-toolkit.studiometa.dev/utils/css/animate.html) for more advanced documentation on keyframes. ```ts twoslash import { TransformProps } from '@studiometa/js-toolkit/utils'; type EasingFunction = (value: number) => number; type BezierCurve = [number, number, number, number]; type CSSCustomPropertyName = `--${string}`; interface KeyFrame extends TransformProps { opacity?: number; transformOrigin?: string; easing?: EasingFunction | BezierCurve; offset?: number; [key: CSSCustomPropertyName]: number; } ``` #### `easing` * Type: `[number, number, number, number]` * Default: `[0, 0, 1, 1]` Cubic-bezier easing values for the animation timing. ```html {4}
...
``` ##### Common easing values | Easing | Cubic bezier | | ---------- | ----------------------------- | | Linear | `[0, 0, 1, 1]` | | InBack | `[0.6, -0.28, 0.735, 0.045]` | | InCirc | `[0.6, 0.04, 0.98, 0.335]` | | InCubic | `[0.55, 0.055, 0.675, 0.19]` | | InExpo | `[0.95, 0.05, 0.795, 0.035]` | | InQuad | `[0.55, 0.085, 0.68, 0.53]` | | InQuart | `[0.895, 0.03, 0.685, 0.22]` | | InQuint | `[0.755, 0.05, 0.855, 0.06]` | | InSine | `[0.47, 0, 0.745, 0.715]` | | OutBack | `[0.175, 0.885, 0.32, 1.275]` | | OutCirc | `[0.075, 0.82, 0.165, 1]` | | OutCubic | `[0.215, 0.61, 0.355, 1]` | | OutExpo | `[0.19, 1, 0.22, 1]` | | OutQuad | `[0.25, 0.46, 0.45, 0.94]` | | OutQuart | `[0.165, 0.84, 0.44, 1]` | | OutQuint | `[0.23, 1, 0.32, 1]` | | OutSine | `[0.39, 0.575, 0.565, 1]` | | InOutBack | `[0.68, -0.55, 0.265, 1.55]` | | InOutCirc | `[0.785, 0.135, 0.15, 0.86]` | | InOutCubic | `[0.645, 0.045, 0.355, 1]` | | InOutExpo | `[1, 0, 0, 1]` | | InOutQuad | `[0.455, 0.03, 0.515, 0.955]` | | InOutQuart | `[0.77, 0, 0.175, 1]` | | InOutQuint | `[0.86, 0, 0.07, 1]` | | InOutSine | `[0.445, 0.05, 0.55, 0.95]` | #### `dampFactor` * Type: `number` * Default: `0.1` Damping factor for smooth scroll animations. Lower values create smoother, slower animations. Each `ScrollAnimationTarget` can have its own damping factor, allowing for different animation speeds within the same timeline. ```html {4,9}
Slow and smooth
Fast and snappy
``` #### `dampPrecision` * Type: `number` * Default: `0.001` Precision threshold for damping calculations. Lower values increase precision but may impact performance. ### Methods #### `render(progress)` * Parameters: * `progress` (`number`): animation progress between 0 and 1 * Returns: `void` Manually render the animation at a specific progress value. ### Properties #### `target` * Type: `HTMLElement` The element being animated. Defaults to the component's root element (`$el`). #### `animation` * Type: `Animation` The animation instance created from the keyframes and easing options. See [`animate` documentation](https://js-toolkit.studiometa.dev/utils/css/animate.html). #### `dampedCurrent` * Type: `{ x: number, y: number }` Current damped scroll position values for both axes. #### `dampedProgress` * Type: `{ x: number, y: number }` Current damped progress values (0-1) for both axes. #### `playRange` * Type: `[number, number]` The computed play range for the animation, taking into account the staggered format if used. *** ## ScrollAnimation (deprecated) {#scrollanimation-deprecated} :::warning Deprecated The `ScrollAnimation` component is deprecated. Use `ScrollAnimationTimeline` with `ScrollAnimationTarget` children instead. ::: A standalone component that watches its own position in the viewport and animates a target element. This component requires a `target` ref. ### Usage ```html
Content to animate
``` ### Refs #### `target` * Type: `HTMLElement` The element to animate. Required for this component. ### Options The `ScrollAnimation` component supports the same options as `ScrollAnimationTarget`: * [`playRange`](#playrange) * [`from`](#from) * [`to`](#to) * [`keyframes`](#keyframes) * [`easing`](#easing) *** ## withScrollAnimationDebug A decorator that adds debug capabilities to `ScrollAnimationTimeline`. When the `debug` option is enabled, it displays visual markers to help understand how the scroll animation is triggered. This decorator is exported separately to allow tree-shaking the debug code from production bundles. ### Usage ```js import { Base, createApp } from '@studiometa/js-toolkit'; import { ScrollAnimationTimeline, ScrollAnimationTarget, withScrollAnimationDebug, } from '@studiometa/ui'; class App extends Base { static config = { name: 'App', components: { ScrollAnimationTimeline: withScrollAnimationDebug(ScrollAnimationTimeline), ScrollAnimationTarget, }, }; } export default createApp(App); ``` ```html
...
``` ### Debug features When the `debug` option is enabled on a `ScrollAnimationTimeline` component wrapped with this decorator: * **Outline**: A dashed border around the timeline element * **Start marker**: A horizontal line showing where in the viewport the animation starts * **End marker**: A horizontal line showing where in the viewport the animation ends * **Progress indicator**: A progress bar and percentage showing the current scroll progress Each timeline gets a different color for easy identification when multiple timelines are on the same page. ### Parameters * `BaseClass` (`typeof ScrollAnimationTimeline`): The `ScrollAnimationTimeline` class to decorate ### Return value * `typeof ScrollAnimationTimeline`: The decorated class with debug capabilities