useTransition ​
Transition between values
Demo ​
Cubic bezier curve: 0.00
Custom function: 0.00
Vector: [0.00, 0.00]
Usage ​
Define a numeric source value to follow, and when changed the output will transition to the new value. If the source changes while a transition is in progress, a new transition will begin from where the previous one was interrupted.
import { TransitionPresets, useTransition } from '@vueuse/core'
import { ref } from 'vue'
const source = ref(0)
const output = useTransition(source, {
duration: 1000,
transition: TransitionPresets.easeInOutCubic,
})
To synchronize transitions, use an array of numbers. As an example, here is how we could transition between colors.
const source = ref([0, 0, 0])
const output = useTransition(source)
const color = computed(() => {
const [r, g, b] = output.value
return `rgb(${r}, ${g}, ${b})`
})
Transition easing can be customized using cubic bezier curves. Transitions defined this way work the same as CSS easing functions.
useTransition(source, {
transition: [0.75, 0, 0.25, 1],
})
The following transitions are available via the TransitionPresets
constant.
linear
easeInSine
easeOutSine
easeInOutSine
easeInQuad
easeOutQuad
easeInOutQuad
easeInCubic
easeOutCubic
easeInOutCubic
easeInQuart
easeOutQuart
easeInOutQuart
easeInQuint
easeOutQuint
easeInOutQuint
easeInExpo
easeOutExpo
easeInOutExpo
easeInCirc
easeOutCirc
easeInOutCirc
easeInBack
easeOutBack
easeInOutBack
For more complex transitions, a custom function can be provided.
function easeOutElastic(n) {
return n === 0
? 0
: n === 1
? 1
: (2 ** (-10 * n)) * Math.sin((n * 10 - 0.75) * ((2 * Math.PI) / 3)) + 1
}
useTransition(source, {
transition: easeOutElastic,
})
To control when a transition starts, set a delay
value. To choreograph behavior around a transition, define onStarted
or onFinished
callbacks.
useTransition(source, {
delay: 1000,
onStarted() {
// called after the transition starts
},
onFinished() {
// called after the transition ends
},
})
To temporarily stop transitioning, define a boolean disabled
property. Be aware, this is not the same a duration
of 0
. Disabled transitions track the source value synchronously. They do not respect a delay
, and do not fire onStarted
or onFinished
callbacks.
For more control, transitions can be executed manually by using executeTransition
. This function returns a promise that resolves upon completion. Manual transitions can be cancelled by defining an abort
function that returns a truthy value.
import { executeTransition } from '@vueuse/core'
await executeTransition(source, from, to, {
duration: 1000,
})
Type Declarations ​
Show Type Declarations
/**
* Cubic bezier points
*/
export type CubicBezierPoints = [number, number, number, number]
/**
* Easing function
*/
export type EasingFunction = (n: number) => number
/**
* Transition options
*/
export interface TransitionOptions {
/**
* Manually abort a transition
*/
abort?: () => any
/**
* Transition duration in milliseconds
*/
duration?: MaybeRef<number>
/**
* Easing function or cubic bezier points for calculating transition values
*/
transition?: MaybeRef<EasingFunction | CubicBezierPoints>
}
export interface UseTransitionOptions extends TransitionOptions {
/**
* Milliseconds to wait before starting transition
*/
delay?: MaybeRef<number>
/**
* Disables the transition
*/
disabled?: MaybeRef<boolean>
/**
* Callback to execute after transition finishes
*/
onFinished?: () => void
/**
* Callback to execute after transition starts
*/
onStarted?: () => void
}
declare const _TransitionPresets: {
readonly easeInSine: readonly [0.12, 0, 0.39, 0]
readonly easeOutSine: readonly [0.61, 1, 0.88, 1]
readonly easeInOutSine: readonly [0.37, 0, 0.63, 1]
readonly easeInQuad: readonly [0.11, 0, 0.5, 0]
readonly easeOutQuad: readonly [0.5, 1, 0.89, 1]
readonly easeInOutQuad: readonly [0.45, 0, 0.55, 1]
readonly easeInCubic: readonly [0.32, 0, 0.67, 0]
readonly easeOutCubic: readonly [0.33, 1, 0.68, 1]
readonly easeInOutCubic: readonly [0.65, 0, 0.35, 1]
readonly easeInQuart: readonly [0.5, 0, 0.75, 0]
readonly easeOutQuart: readonly [0.25, 1, 0.5, 1]
readonly easeInOutQuart: readonly [0.76, 0, 0.24, 1]
readonly easeInQuint: readonly [0.64, 0, 0.78, 0]
readonly easeOutQuint: readonly [0.22, 1, 0.36, 1]
readonly easeInOutQuint: readonly [0.83, 0, 0.17, 1]
readonly easeInExpo: readonly [0.7, 0, 0.84, 0]
readonly easeOutExpo: readonly [0.16, 1, 0.3, 1]
readonly easeInOutExpo: readonly [0.87, 0, 0.13, 1]
readonly easeInCirc: readonly [0.55, 0, 1, 0.45]
readonly easeOutCirc: readonly [0, 0.55, 0.45, 1]
readonly easeInOutCirc: readonly [0.85, 0, 0.15, 1]
readonly easeInBack: readonly [0.36, 0, 0.66, -0.56]
readonly easeOutBack: readonly [0.34, 1.56, 0.64, 1]
readonly easeInOutBack: readonly [0.68, -0.6, 0.32, 1.6]
}
/**
* Common transitions
*
* @see https://easings.net
*/
export declare const TransitionPresets: Record<
keyof typeof _TransitionPresets,
CubicBezierPoints
> & {
linear: EasingFunction
}
/**
* Transition from one value to another.
*
* @param source
* @param from
* @param to
* @param options
*/
export declare function executeTransition<T extends number | number[]>(
source: Ref<T>,
from: MaybeRefOrGetter<T>,
to: MaybeRefOrGetter<T>,
options?: TransitionOptions,
): PromiseLike<void>
export declare function useTransition(
source: MaybeRefOrGetter<number>,
options?: UseTransitionOptions,
): ComputedRef<number>
export declare function useTransition<T extends MaybeRefOrGetter<number>[]>(
source: [...T],
options?: UseTransitionOptions,
): ComputedRef<{
[K in keyof T]: number
}>
export declare function useTransition<T extends MaybeRefOrGetter<number[]>>(
source: T,
options?: UseTransitionOptions,
): ComputedRef<number[]>
Source ​
Contributors ​
Changelog ​
Pending for release...
59f75
- feat(toValue): deprecate toValue
from @vueuse/shared
in favor of Vue's nativev12.0.0-beta.1
on 11/21/2024v10.1.0
on 4/22/2023v10.0.0-beta.5
on 4/13/2023cb644
- refactor!: remove isFunction
and isString
utilsv10.0.0-beta.4
on 4/13/20234d757
- feat(types)!: rename MaybeComputedRef
to MaybeRefOrGetter
0a72b
- feat(toValue): rename resolveUnref
to toValue
v10.0.0-beta.1
on 3/23/2023v10.0.0-beta.0
on 3/14/2023v9.6.0
on 11/22/2022