useAnimate

useAnimate provides a way of using the animate function that is scoped to the elements within your component.

This allows you to use manual animation controls, timelines, selectors scoped to your component, and automatic cleanup.

It provides a scope ref, and an animate function where every DOM selector is scoped to this ref.

<script setup>
import { useAnimate } from 'motion-v'

const [scope, animate] = useAnimate()

onMounted(() => {
  // This "li" selector will only select children
  // of the element that receives `scope`
  animate('li', { opacity: 1 })
})
</script>

<template>
  <ul ref="scope">
    <slot />
  </ul>
</template>

Additionally, when the component calling useAnimate is removed, all animations started with its animate function will be cleaned up automatically.

Usage

Import from Motion:

import { useAnimate } from "motion-v"

useAnimate returns two arguments, a scope ref and an animate function.

<script setup>
import { useAnimate } from 'motion-v'

const [scope, animate] = useAnimate()
</script>

This scope ref must be passed to either a regular HTML/SVG element or a motion component.

<script setup>
import { useAnimate } from 'motion-v'

const [scope, animate] = useAnimate()
</script>

<template>
  <ul ref="scope">
    <slot />
  </ul>
</template>

This scoped animate function can now be used in effects and event handlers to animate elements.

We can either use the scoped element directly:

animate(scope.current, { opacity: 1 }, { duration: 1 })

Or by passing it a selector:

animate("li", { backgroundColor: "#000" }, { ease: "linear" })

This selector is "li", but we're not selecting all li elements on the page, only those that are a child of the scoped element.

Scroll-triggered animations

Animations can be triggered when the scope scrolls into view by combining useAnimate with useInView.

<script setup>
import { useAnimate, useInView } from 'motion-v'

const [scope, animate] = useAnimate()
const isInView = useInView(scope)

watch(isInView, (inView) => {
  if (inView) {
    animate(scope.value, { opacity: 1 })
  }
})
</script>

<template>
  <ul ref="scope">
    <li />
    <li />
    <li />
  </ul>
</template>