--- url: /migration-guides/1.0-2.0.md --- # v1.x → v2.x You will find on this page documentation on all the breaking changes included in the v2.x of the package. \[\[toc]] ## ScrollAnimation components have been refactored The `ScrollAnimation` family of components has been refactored for better performance and flexibility. The new API uses `ScrollAnimationTimeline` as a parent component that manages scroll progress, with `ScrollAnimationTarget` children that handle individual animations. ### Summary of component renames | v1.x (deprecated) | v2.x (new) | | ------------------------------ | --------------------------------------------------- | | `ScrollAnimation` | `ScrollAnimationTimeline` + `ScrollAnimationTarget` | | `ScrollAnimationParent` | `ScrollAnimationTimeline` | | `ScrollAnimationChild` | `ScrollAnimationTarget` | | `ScrollAnimationChildWithEase` | `ScrollAnimationTarget` with `dampFactor` option | | `ScrollAnimationWithEase` | `ScrollAnimationTimeline` + `ScrollAnimationTarget` | | `animationScrollWithEase` | Extend `ScrollAnimationTarget` instead | ### Benefits of the new API The refactored API provides several benefits: 1. **Better performance**: The timeline only watches one element for scroll position, reducing the number of intersection observers 2. **Independent damping**: Each target can have its own `dampFactor`, allowing different animation speeds within the same timeline 3. **Simpler markup**: No need for a `target` ref — the component animates itself 4. **Clearer naming**: `Timeline` and `Target` clearly describe the parent-child relationship 5. **More flexible**: Easier to coordinate multiple animations with different play ranges ### Replace `ScrollAnimation` with `ScrollAnimationTimeline` and `ScrollAnimationTarget` The standalone `ScrollAnimation` component has been removed. Use `ScrollAnimationTimeline` with `ScrollAnimationTarget` children instead. **Before (v1.x):** ```html
Content to animate
``` ```js import { Base, createApp } from '@studiometa/js-toolkit'; import { ScrollAnimation } from '@studiometa/ui'; class App extends Base { static config = { name: 'App', components: { ScrollAnimation, }, }; } export default createApp(App, document.body); ``` **After (v2.x):** ```html
Content to animate
``` ```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); ``` ::: tip Key differences * The `target` ref is no longer needed — `ScrollAnimationTarget` animates itself * Animation options (`from`, `to`, `playRange`, etc.) are now on `ScrollAnimationTarget` * Multiple targets can share the same timeline for coordinated animations ::: ### Replace `ScrollAnimationParent` with `ScrollAnimationTimeline` The `ScrollAnimationParent` component has been renamed to `ScrollAnimationTimeline`. **Before (v1.x):** ```html
...
``` ```js import { ScrollAnimationParent, ScrollAnimationChild } from '@studiometa/ui'; ``` **After (v2.x):** ```html
...
``` ```js import { ScrollAnimationTimeline, ScrollAnimationTarget } from '@studiometa/ui'; ``` ### Replace `ScrollAnimationChild` with `ScrollAnimationTarget` The `ScrollAnimationChild` component has been renamed to `ScrollAnimationTarget`. ```diff -
+
...
``` ```diff - import { ScrollAnimationChild } from '@studiometa/ui'; + import { ScrollAnimationTarget } from '@studiometa/ui'; ``` ### Replace `ScrollAnimationChildWithEase` with `ScrollAnimationTarget` The `ScrollAnimationChildWithEase` component has been removed. Use `ScrollAnimationTarget` with the `dampFactor` option instead. **Before (v1.x):** ```html
...
``` ```js import { ScrollAnimationChildWithEase } from '@studiometa/ui'; ``` **After (v2.x):** ```html
...
``` ```js import { ScrollAnimationTarget } from '@studiometa/ui'; ``` ::: tip Each `ScrollAnimationTarget` can have its own `dampFactor` value, allowing for different animation speeds within the same timeline. ::: ### Replace `ScrollAnimationWithEase` with `ScrollAnimationTimeline` and `ScrollAnimationTarget` The `ScrollAnimationWithEase` component has been removed. Use `ScrollAnimationTimeline` with `ScrollAnimationTarget` children that have the `dampFactor` option. **Before (v1.x):** ```html
...
``` **After (v2.x):** ```html
...
``` ### Remove `animationScrollWithEase` decorator The `animationScrollWithEase` decorator has been removed without a direct replacement. If you were using it to create custom scroll animation components, extend `ScrollAnimationTarget` instead. **Before (v1.x):** ```js import { Base } from '@studiometa/js-toolkit'; import { animationScrollWithEase } from '@studiometa/ui'; class MyScrollAnimation extends animationScrollWithEase(Base) { // ... } ``` **After (v2.x):** ```js import { ScrollAnimationTarget } from '@studiometa/ui'; class MyScrollAnimation extends ScrollAnimationTarget { static config = { ...ScrollAnimationTarget.config, name: 'MyScrollAnimation', }; // Override methods as needed } ```