Skip to content

useTransition

Category
Export Size
912 B
Last Changed
18 hours ago

Transition between values

Demo

Cubic bezier curve: 0.00

Custom function: 0.00

Vector: [0.00, 0.00]

Non-numeric value: Hello

Usage

Define a 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.

ts
import { 
TransitionPresets
,
useTransition
} from '@vueuse/core'
import {
shallowRef
} from 'vue'
const
source
=
shallowRef
(0)
const
output
=
useTransition
(
source
, {
duration
: 1000,
easing
:
TransitionPresets
.
easeInOutCubic
,
})

Transition easing can be customized using cubic bezier curves.

ts
useTransition
(source, {
easing
: [0.75, 0, 0.25, 1],
})

The following transitions are available via the TransitionPresets constant.

For more complex easing, a custom function can be provided.

ts
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, {
easing
:
easeOutElastic
,
})

By default the source must be a number, or array of numbers. For more complex values, define a custom interpolation function. For example, the following would transition a Three.js rotation.

ts
import { 
Quaternion
} from 'three'
const
source
=
ref
(new
Quaternion
())
const
output
=
useTransition
(
source
, {
interpolation
: (
q1
,
q2
,
t
) => new
Quaternion
().slerpQuaternions(
q1
,
q2
,
t
)
})

To control when a transition starts, set a delay value. To choreograph behavior around a transition, define onStarted or onFinished callbacks.

ts
useTransition
(source, {
delay
: 1000,
onStarted
() {
// called after the transition starts },
onFinished
() {
// called after the transition ends }, })

To 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 even more control, transitions can be executed manually via the transition function. This function returns a promise that resolves when the transition is complete. Manual transitions can be cancelled by defining an abort function that returns a truthy value.

ts
import { 
transition
} from '@vueuse/core'
await
transition
(source, from, to, {
abort
() {
if (shouldAbort) return true } })

Type Declarations

Show Type Declarations
ts
/**
 * Cubic bezier points
 */
export type 
CubicBezierPoints
= [number, number, number, number]
/** * Easing function */ export type
EasingFunction
= (
n
: number) => number
/** * Interpolation function */ export type
InterpolationFunction
<
T
> = (
from
:
T
,
to
:
T
,
t
: number) =>
T
/** * Transition options */ export interface
TransitionOptions
<
T
> extends ConfigurableWindow {
/** * Manually abort a transition */
abort
?: () => any
/** * Transition duration in milliseconds */
duration
?:
MaybeRef
<number>
/** * Easing function or cubic bezier points to calculate transition progress */
easing
?:
MaybeRef
<
EasingFunction
|
CubicBezierPoints
>
/** * Custom interpolation function */
interpolation
?:
InterpolationFunction
<
T
>
/** * Easing function or cubic bezier points to calculate transition progress * @deprecated The `transition` option is deprecated, use `easing` instead. */
transition
?:
MaybeRef
<
EasingFunction
|
CubicBezierPoints
>
} export interface
UseTransitionOptions
<
T
> extends
TransitionOptions
<
T
> {
/** * 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
transition
<
T
>(
source
:
Ref
<
T
>,
from
:
MaybeRefOrGetter
<
T
>,
to
:
MaybeRefOrGetter
<
T
>,
options
?:
TransitionOptions
<
T
>,
):
PromiseLike
<void>
/** * Transition from one value to another. * @deprecated The `executeTransition` function is deprecated, use `transition` instead. * * @param source * @param from * @param to * @param options */ export declare function
executeTransition
<
T
>(
source
:
Ref
<
T
>,
from
:
MaybeRefOrGetter
<
T
>,
to
:
MaybeRefOrGetter
<
T
>,
options
?:
TransitionOptions
<
T
>,
):
PromiseLike
<void>
export declare function
useTransition
<
T
extends
MaybeRefOrGetter
<number>[]>(
source
: [...
T
],
options
?:
UseTransitionOptions
<
T
>,
):
ComputedRef
<{
[
K
in keyof
T
]: number
}> export declare function
useTransition
<
T
extends
MaybeRefOrGetter
<number[]>>(
source
:
T
,
options
?:
UseTransitionOptions
<
T
>,
):
ComputedRef
<number[]>
export declare function
useTransition
<
T
>(
source
:
MaybeRefOrGetter
<
T
>,
options
?:
UseTransitionOptions
<
T
>,
):
ComputedRef
<
T
>

Source

SourceDemoDocs

Contributors

Anthony Fu
Scott Bedard
Anthony Fu
IlyaL
SerKo
Byron
Robin
zhiyuanzmj
Alexey Istomin
huodoushigemi
Jelf
wheat
Alex Kozack

Changelog

Pending for release...
cf905 - feat: add support for custom interpolator functions (#5011)
v13.6.0 on
a75f4 - feat: support custom window (#4850)
v12.8.0 on
7432f - feat(types): deprecate MaybeRef and MaybeRefOrGetter in favor of Vue's native (#4636)
v12.3.0 on
59f75 - feat(toValue): deprecate toValue from @vueuse/shared in favor of Vue's native
v12.0.0-beta.1 on
0a9ed - feat!: drop Vue 2 support, optimize bundles and clean up (#4349)
v10.1.0 on
8b330 - fix: fix regression with non-linear transition functions (#2973)
v10.0.0-beta.5 on
cb644 - refactor!: remove isFunction and isString utils

Released under the MIT License.

Build faster with AI
New Masterclass to help you leverage AI in your Vue workflow
Get Early Access