Intuitive and predictable spring animation library powered by CSS Transition
npm install @css-spring-animation/vueEnglish | 日本語
An intuitive and predictable spring animation library powered by CSS Transition. It is inspired by Animate with springs of WWDC 2023. The features of this library are:
- Implementing spring animation with CSS Transition
- Animation options are intuitive and predictable
- bounce: Bounciness of an animation
- duration: Perceptive animation duration
- Graceful degradation with requestAnimationFrame for browsers that do not support the features used in the library
There is a Vue binding of the library. Install it with npm (or yarn, pnpm):
``sh`
$ npm install @css-spring-animation/vue
When you use
:spring-style="{
translate: moved ? '100px' : '0px',
}"
:duration="600"
:bounce="0.3"
>
`
The property name after spring. bounce duration You should use All numbers in a style value must have the same unit and must be appeared in the same order. For example, the following This is because the library parses the numbers in the style value, then calculate the animation for each number in the style value. The library cannot understand the meaning of The library sets spring animation expression in an animating CSS value including a custom property that representing elapsed time (let's say // Set initial state // Set spring animatioin expression including --t // Re-render The library also provides a graceful degradation for browsers that do not support It renders a native HTML element as same tag name as the property name (e.g. Props - Props - - Inherited props from Vue's Events - Props - - Inherited props from Vue's Events - A composable function to generate spring animation style. It also returns the real value and velocity of the corresponding number in the style value. They are as same shape as the style value except that its values are the array of numbers. The first argument is a function or ref that returns the style object to be animated. The second argument is an options object. It also can be a function or ref that returns the options. The options object expectes the following properties: - It is expected to be used in a complex situation that It is expected to be used out of is the tag name to be rendered. For example, renders element. The element has the style specified on :spring-style prop. Spring animation will be triggered when the value of :spring-style prop is changed.bounceBounce and Duration
and duration options are used to specify the bounciness and perceptive duration of an animation.disabled
Bounciness of an animation. The value is between -1 and 1. The default value is 0.
Perceptive duration (ms) of an animation. The default value is 1000. vs. relocating component and useSpring composable have disabled and relocating options. They both stop ongoing animation and the component/composable will not trigger animations for further style changes.disabled when you want to disable a spring animation but keep rendering an element move by continuously updating the style value, then trigger a spring animation again with using velocity of the style value updates. You can see the example of it in Swipe demo. disabled is true while you drag an element and trigger spring animation with the inherited velocity of the dragging when releasing it.relocating is used in case of updating the style value without triggering a spring animation and you will immediately trigger an animation with using the inherited velocity of the previous animation. In Picker demo, you can rotate the picker by mouse wheel endlessly. To do that, it rewinds the picker to the opposite side of the rotation with relocating = true while keeping the rotation animation.:spring-styleSpring Style Caveats
value is invalid and will not work as expected:`vue`
>translate, scale nor predict the difference between 100% and 100px. To fix the above example, you need to specify both translate and scale in the same order and always use the same unit:`vue`
transform: flag
? 'scale(1) translate(100px, 100px)'
: 'scale(2) translate(0, 0)',
}"
>--tHow It Works
here). Then register --t by using CSS.registerProperty to be able to apply CSS Transition on it. The pseudo code of the spring animation expression looks like below:`js`
// Register --t
CSS.registerProperty({
name: '--t',
syntax: '
inherits: false,
initialValue: 0,
})
el.style.setProperty('--t', 0)
el.style.translate = 'calc(P (A var(--t) + B) exp(-C var(--t)) - Q)'
requestAnimationFrame(() => {
// Trigger animation
el.style.setProperty('--t', 1)
el.style.transition = '--t 1000ms linear'
})CSS.registerProperty and exp() function of CSS. In this case, the library will use requestAnimationFrame to animate the style value instead of CSS Transition.API Reference
$3
renders element).spring-style: Style object to be animatedbounce
- duration
- disabled
- relocating
- `vue${position.value}px
translate: ,`
}"
:duration="600"
:bounce="0.3"
>$3
is a spring animation version of Vue's component. It triggers animation from enter-from style to spring-style on entering and from spring-style to leave-to on leaving.spring-style: Default style of a child element.enter-from
- : Style of a child element before entering.leave-to
- : Style of a child element after leaving. Fallback to enter-from style if not specified.bounce
- duration
- component:name
- mode
- enterFromClass
- enterActiveClass
- enterToClass
- leaveFromClass
- leaveActiveClass
- leaveToClass
- before-enterafter-enter
- enter-cancelled
- before-leave
- after-leave
- leave-cancelled
- `vue
translate: '0',
}"
:enter-from="{
translate: '-100px',
}"
:leave-to="{
translate: '100px',
}"
:duration="600"
:bounce="0"
>
`$3
is a spring animation version of Vue's component. It can have spring-style, enter-from and leave-to props as same as .spring-style: Default style of a child element.enter-from
- : Style of a child element before entering.leave-to
- : Style of a child element after leaving. Fallback to enter-from style if not specified.bounce
- duration
- component:tag
- name
- enterFromClass
- enterActiveClass
- enterToClass
- leaveFromClass
- leaveActiveClass
- leaveToClass
- before-enterafter-enter
- enter-cancelled
- before-leave
- after-leave
- leave-cancelled
- `vue
:spring-style="{
opacity: 1,
}"
:enter-from="{
opacity: 0,
}"
:leave-to="{
opacity: 0,
}"
:duration="800"
:bounce="0"
>
`bounce$3
duration
- disabled
- relocating
- component is not suitable to be used.`vue`
useSpring provides onFinishCurrent and onSettleCurrent functions for waiting until the current animation is finished or settled. You can register a callback function that will be called when an ongoing animation is finished/settled.`vue`v-spring-style$3
directive is used to specify the style to be animated. v-spring-options directive is used to specify the options of the animation.