Skip to content
On this page

useTransition

Category
Export Size
1.66 kB
Last Changed
last month

Transition between values

Demo

Cubic bezier curve: 0.00

Custom function: 0.00

Vector: [0.00, 0.00]

Usage

For simple transitions, provide a numeric source value to watch. 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.

js
import { ref } from 'vue'
import { TransitionPresets, useTransition } from '@vueuse/core'

const source = ref(0)

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

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.

js
const source = ref([0, 0, 0])

const output = useTransition(source)

const color = computed(() => {
  const [r, g, b] = output.value
  return `rgb(${r}, ${g}, ${b})`
})
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.

js
useTransition(source, {
  transition: [0.75, 0, 0.25, 1],
})
useTransition(source, {
  transition: [0.75, 0, 0.25, 1],
})

The following transitions are available via the TransitionPresets constant.

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

js
const 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,
})
const 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.

js
useTransition(source, {
  delay: 1000,
  onStarted() {
    // called after the transition starts
  },
  onFinished() {
    // called after the transition ends
  },
})
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.

Type Declarations

Show Type Declarations
typescript
/**
 * Cubic bezier points
 */
export declare type CubicBezierPoints = [number, number, number, number]
/**
 * Easing function
 */
export declare type EasingFunction = (n: number) => number
/**
 * Transition options
 */
export interface UseTransitionOptions {
  /**
   * Milliseconds to wait before starting transition
   */
  delay?: MaybeRef<number>
  /**
   * Disables the transition
   */
  disabled?: MaybeRef<boolean>
  /**
   * Transition duration in milliseconds
   */
  duration?: MaybeRef<number>
  /**
   * Callback to execute after transition finishes
   */
  onFinished?: () => void
  /**
   * Callback to execute after transition starts
   */
  onStarted?: () => void
  /**
   * Easing function or cubic bezier points for calculating transition values
   */
  transition?: MaybeRef<EasingFunction | CubicBezierPoints>
}
/**
 * Common transitions
 *
 * @see https://easings.net
 */
export declare const TransitionPresets: Record<
  | "easeInSine"
  | "easeOutSine"
  | "easeInOutSine"
  | "easeInQuad"
  | "easeOutQuad"
  | "easeInOutQuad"
  | "easeInCubic"
  | "easeOutCubic"
  | "easeInOutCubic"
  | "easeInQuart"
  | "easeOutQuart"
  | "easeInOutQuart"
  | "easeInQuint"
  | "easeOutQuint"
  | "easeInOutQuint"
  | "easeInExpo"
  | "easeOutExpo"
  | "easeInOutExpo"
  | "easeInCirc"
  | "easeOutCirc"
  | "easeInOutCirc"
  | "easeInBack"
  | "easeOutBack"
  | "easeInOutBack",
  CubicBezierPoints
> & {
  linear: EasingFunction
}
export declare function useTransition(
  source: Ref<number>,
  options?: UseTransitionOptions
): ComputedRef<number>
export declare function useTransition<T extends MaybeRef<number>[]>(
  source: [...T],
  options?: UseTransitionOptions
): ComputedRef<{
  [K in keyof T]: number
}>
export declare function useTransition<T extends Ref<number[]>>(
  source: T,
  options?: UseTransitionOptions
): ComputedRef<number[]>
/**
 * Cubic bezier points
 */
export declare type CubicBezierPoints = [number, number, number, number]
/**
 * Easing function
 */
export declare type EasingFunction = (n: number) => number
/**
 * Transition options
 */
export interface UseTransitionOptions {
  /**
   * Milliseconds to wait before starting transition
   */
  delay?: MaybeRef<number>
  /**
   * Disables the transition
   */
  disabled?: MaybeRef<boolean>
  /**
   * Transition duration in milliseconds
   */
  duration?: MaybeRef<number>
  /**
   * Callback to execute after transition finishes
   */
  onFinished?: () => void
  /**
   * Callback to execute after transition starts
   */
  onStarted?: () => void
  /**
   * Easing function or cubic bezier points for calculating transition values
   */
  transition?: MaybeRef<EasingFunction | CubicBezierPoints>
}
/**
 * Common transitions
 *
 * @see https://easings.net
 */
export declare const TransitionPresets: Record<
  | "easeInSine"
  | "easeOutSine"
  | "easeInOutSine"
  | "easeInQuad"
  | "easeOutQuad"
  | "easeInOutQuad"
  | "easeInCubic"
  | "easeOutCubic"
  | "easeInOutCubic"
  | "easeInQuart"
  | "easeOutQuart"
  | "easeInOutQuart"
  | "easeInQuint"
  | "easeOutQuint"
  | "easeInOutQuint"
  | "easeInExpo"
  | "easeOutExpo"
  | "easeInOutExpo"
  | "easeInCirc"
  | "easeOutCirc"
  | "easeInOutCirc"
  | "easeInBack"
  | "easeOutBack"
  | "easeInOutBack",
  CubicBezierPoints
> & {
  linear: EasingFunction
}
export declare function useTransition(
  source: Ref<number>,
  options?: UseTransitionOptions
): ComputedRef<number>
export declare function useTransition<T extends MaybeRef<number>[]>(
  source: [...T],
  options?: UseTransitionOptions
): ComputedRef<{
  [K in keyof T]: number
}>
export declare function useTransition<T extends Ref<number[]>>(
  source: T,
  options?: UseTransitionOptions
): ComputedRef<number[]>

Source

SourceDemoDocs

Contributors

Anthony Fu
Scott Bedard
huodoushigemi
Jelf
wheat
Alex Kozack

Changelog

v9.6.0 on 11/22/2022
0a49e - fix: call pause() to stop useRafFn when disabling (#2360)
v9.1.0 on 8/4/2022
cc865 - fix: improve type of TransitionPresets
v8.9.3 on 7/14/2022
35f33 - fix!: rename type TransitionOptions to UseTransitionOptions (#1893)

Released under the MIT License.