repository·main·Indexed 25 days ago
https://github.com/vueuse/motionA Vue composables library providing smooth, declarative animations for components, HTML, and SVG elements. Inspired by Framer Motion and built on Popmotion, it features the v-motion directive, the useMotion composable, and support for SSR and Nuxt. It includes built-in animation presets and supports spring and keyframe transitions.
@vueuse/motion provides composables to add smooth animations to your Vue components. It is a declarative API inspired by Framer Motion and uses Popmotion for its animation engine.
Key features include:
You can use delay and duration shorthand props to quickly configure transition properties for v-motion.
If you have specified a visible, visible-once, or enter variant, these shorthand properties will be applied to each of them. Otherwise, they will be applied to the initial variant.
To use @vueuse/motion in your project, install the package using your preferred package manager.
yarn add @vueuse/motionIf you prefer not to install the plugin globally, you can import the MotionDirective and register it locally within a specific component to use the v-motion directive only there.
import { MotionDirective as motion } from '@vueuse/motion'
export default {
directives: {
motion: motion(),
},
}@vueuse/motion comes with a set of pre-defined animation presets that allow you to implement animations immediately after installation without defining custom keyframes.
To use these presets, apply them via the v-motion directive or the useMotion API. If you want to extend the library with your own animations, you can define Custom Directives.
You can define custom variants within the :variants prop and trigger them programmatically using the useMotions hook.
:variants object.v-motion directive (e.g., v-motion="'customName'").useMotions() to get the motion instance for that element and update its .variant.value property.<template>
<div v-motion="'customElement'" :initial="{ scale: 1, }" :variants="{ custom: { scale: 2, transition: { type: 'spring', stiffness: 100 } } }" />
</template>
<script setup>
import { useMotions } from '@vueuse/motion'
// Access the motion instance using useMotions.
const { customElement } = useMotions()
// Trigger the custom variant
const yourCustomEvent = () => {
customElement.variant.value = 'custom'
}
</script>The <Motion> component allows you to implement animations directly within your template. It is an alternative to the v-motion directive that works better in Server-Side Rendering (SSR) environments. You can specify which element to render using the is prop (defaults to div).
<template>
<Motion is="p" preset="slideVisibleLeft">Text in Motion!</Motion>
</template>To test the latest changes before a stable release, install the nightly release channel:
npm install @vueuse/motion@npm:vueuse-motion-nightlyThe v-motion directive allows you to define animations directly in your Vue templates without wrapper components. It works on HTML elements, SVG elements, and Vue components. You can define animation states using specific variant props or a single :variants object.
<template>
<div
v-motion
:initial="{ opacity: 0, y: 100 }"
:enter="{ opacity: 1, y: 0, scale: 1 }"
:variants="{ custom: { scale: 2 } }"
:hovered="{ scale: 1.2 }"
:delay="200"
:duration="1200"
/>
</template>The useMotion composable is the core way to create animations within the Composition API setup hook. It allows you to bind animations to a target element using variants.
useMotion accepts three parameters:
target: An HTML or SVG element, or a Vue ref pointing to one.variants: An object defining different animation states (e.g., initial, enter).Calling useMotion returns a Motion Instance, which provides methods to control and trigger animations programmatically.
<script setup>
import { ref } from 'vue'
import { useMotion } from '@vueuse/motion'
const target = ref<HTMLElement>()
const motionInstance = useMotion(target, {
initial: {
opacity: 0,
y: 100
},
enter: {
opacity: 1,
y: 0
}
})
</script>
<template>
<div ref="target">Animated Element</div>
</template>To use the motion features, you must register the MotionPlugin in your Vue application entry file (e.g., main.js or app.ts).
import { createApp } from "vue";
import { MotionPlugin } from "@vueuse/motion";
import App from "./App.vue";
const app = createApp(App);
app.use(MotionPlugin);
app.mount("#app");To use @vueuse/motion in a Nuxt project (supporting nuxt3 and @nuxt/bridge), install the package and add @vueuse/motion/nuxt to your modules array in nuxt.config.js. This implementation simplifies the declaration of custom directives.
// nuxt.config.js
{
modules: ['@vueuse/motion/nuxt']
}