` component using a motion preset on a `` element:
10 |
11 | ```vue
12 |
13 | Text in Motion!
14 |
15 | ```
16 |
17 |
18 |
19 | ## ``
20 |
21 | The `` can be used to apply motion configuration to all of its child elements, this component is renderless by default and can be used as a wrapper by passing a value to the `:is` prop.
22 |
23 | ```vue
24 |
25 |
26 |
27 | Product 1
28 | Description text
29 |
30 |
31 | Product 2
32 | Description text
33 |
34 |
35 | Product 3
36 | Description text
37 |
38 |
39 |
40 | ```
41 |
42 |
43 |
44 |
45 | ## Props
46 |
47 | The `` and `` components allow you to define animation properties (variants) as props.
48 |
49 | - **`is`**: What element should rendered (`div` by default for ``).
50 | - **`preset`**: Motion preset to use (expects camel-case string), see [Presets](/features/presets).
51 |
52 | ### Variant props
53 |
54 | - **`initial`**: Properties the element will have before it is mounted.
55 | - **`enter`**: Properties the element will have after it is mounted.
56 | - **`visible`**: Properties the element will have whenever it is within view. Once out of view, the `initial` properties are reapplied.
57 | - **`visible-once`**: Properties the element will have once it enters the view.
58 | - **`hovered`**: Properties the element will have when hovered.
59 | - **`focused`**: Properties the element will have when it receives focus.
60 | - **`tapped`**: Properties the element will have upon being clicked or tapped.
61 |
62 | Variants can be passed as an object using the `:variants` prop.
63 |
64 | The `:variants` prop combines with other variant properties, allowing for the definition of custom variants from this object.
65 |
66 | Additional variant properties can be explored on the [Variants](/features/variants) page.
67 |
68 | ### Shorthand Props
69 |
70 | We support shorthand props for quickly setting transition properties:
71 |
72 | - **`delay`**
73 | - **`duration`**
74 |
75 | These properties apply to `visible`, `visible-once`, or `enter` variants if specified; otherwise, they default to the `initial` variant.
76 |
77 | ```vue
78 |
79 |
87 | Content to animate!
88 |
89 |
90 | ```
91 |
92 |
--------------------------------------------------------------------------------
/docs/content/2.features/6.motion-instance.md:
--------------------------------------------------------------------------------
1 | # Motion Instance
2 |
3 | Motion instance is the object exposed when binding to a target element using [v-motion](/features/directive-usage) or [useMotion](/features/composable-usage).
4 |
5 | It is composed of three properties, allowing you to interact with the element.
6 |
7 | ## Variant
8 |
9 | The variant is a string reference, that you can modify and watch.
10 |
11 | It represents the current variant name of the element.
12 |
13 | By modifying this variant, you will trigger a transition between the current variant and the one you just set.
14 |
15 | ```vue
16 |
42 | ```
43 |
44 | ##### _Call customEvent to enable the custom variant_ ☝️
45 |
46 | ## Apply
47 |
48 | Apply is a function that lets you animate to a variant definition, without changing the current variant.
49 |
50 | This is useful when used with event listeners, or any temporary modification to the motion properties of the element.
51 |
52 | This is also useful for orchestration, as apply returns a promise, you can await it and chain variant applying.
53 |
54 | Apply accepts both a [Variant Declaration](/features/variants) or a key from the motion instance variants.
55 |
56 | ```vue
57 |
87 | ```
88 |
89 | ##### _Call customEvent to Zboing the element_ ☝️
90 |
91 | ## Stop
92 |
93 | Stop is a function that lets you stop ongoing animations for a specific element.
94 |
95 | Calling it without argument will be stopping all the animations.
96 |
97 | Calling it with an array of [Motion Properties](/features/motion-properties) keys will stop every specified key.
98 |
99 | Calling it with a single motion property key will stop the specified key.
100 |
101 | ```vue
102 |
122 | ```
123 |
124 | ##### _Call customEvent to stop the animations_ ☝️
125 |
--------------------------------------------------------------------------------
/src/utils/style.ts:
--------------------------------------------------------------------------------
1 | import type { ValueType } from 'style-value-types'
2 | import { alpha, color, complex, degrees, filter, number, progressPercentage, px, scale } from 'style-value-types'
3 |
4 | type ValueTypeMap = Record
5 |
6 | /**
7 | * ValueType for "auto"
8 | */
9 | export const auto: ValueType = {
10 | test: (v: any) => v === 'auto',
11 | parse: v => v,
12 | }
13 |
14 | /**
15 | * ValueType for ints
16 | */
17 | const int = {
18 | ...number,
19 | transform: Math.round,
20 | }
21 |
22 | export const valueTypes: ValueTypeMap = {
23 | // Color props
24 | color,
25 | backgroundColor: color,
26 | outlineColor: color,
27 | fill: color,
28 | stroke: color,
29 |
30 | // Border props
31 | borderColor: color,
32 | borderTopColor: color,
33 | borderRightColor: color,
34 | borderBottomColor: color,
35 | borderLeftColor: color,
36 | borderWidth: px,
37 | borderTopWidth: px,
38 | borderRightWidth: px,
39 | borderBottomWidth: px,
40 | borderLeftWidth: px,
41 | borderRadius: px,
42 | radius: px,
43 | borderTopLeftRadius: px,
44 | borderTopRightRadius: px,
45 | borderBottomRightRadius: px,
46 | borderBottomLeftRadius: px,
47 |
48 | // Positioning props
49 | width: px,
50 | maxWidth: px,
51 | height: px,
52 | maxHeight: px,
53 | size: px,
54 | top: px,
55 | right: px,
56 | bottom: px,
57 | left: px,
58 |
59 | // Spacing props
60 | padding: px,
61 | paddingTop: px,
62 | paddingRight: px,
63 | paddingBottom: px,
64 | paddingLeft: px,
65 | margin: px,
66 | marginTop: px,
67 | marginRight: px,
68 | marginBottom: px,
69 | marginLeft: px,
70 |
71 | // Transform props
72 | rotate: degrees,
73 | rotateX: degrees,
74 | rotateY: degrees,
75 | rotateZ: degrees,
76 | scale,
77 | scaleX: scale,
78 | scaleY: scale,
79 | scaleZ: scale,
80 | skew: degrees,
81 | skewX: degrees,
82 | skewY: degrees,
83 | distance: px,
84 | translateX: px,
85 | translateY: px,
86 | translateZ: px,
87 | x: px,
88 | y: px,
89 | z: px,
90 | perspective: px,
91 | transformPerspective: px,
92 | opacity: alpha,
93 | originX: progressPercentage,
94 | originY: progressPercentage,
95 | originZ: px,
96 |
97 | // Misc
98 | zIndex: int,
99 | filter,
100 | WebkitFilter: filter,
101 |
102 | // SVG
103 | fillOpacity: alpha,
104 | strokeOpacity: alpha,
105 | numOctaves: int,
106 | }
107 |
108 | /**
109 | * Return the value type for a key.
110 | *
111 | * @param key
112 | */
113 | export const getValueType = (key: string) => valueTypes[key]
114 |
115 | /**
116 | * Transform the value using its value type if value is a `number`, otherwise return the value.
117 | *
118 | * @param value
119 | * @param type
120 | */
121 | export function getValueAsType(value: any, type?: ValueType) {
122 | return type && typeof value === 'number' && type.transform ? type.transform(value) : value
123 | }
124 |
125 | /**
126 | * Get default animatable
127 | *
128 | * @param key
129 | * @param value
130 | */
131 | export function getAnimatableNone(key: string, value: string): any {
132 | let defaultValueType = getValueType(key)
133 | if (defaultValueType !== filter)
134 | defaultValueType = complex
135 | // If value is not recognised as animatable, ie "none", create an animatable version origin based on the target
136 | return defaultValueType.getAnimatableNone ? defaultValueType.getAnimatableNone(value) : undefined
137 | }
138 |
--------------------------------------------------------------------------------
/src/presets/roll.ts:
--------------------------------------------------------------------------------
1 | import type { MotionVariants } from '../types'
2 |
3 | // Roll from left
4 |
5 | export const rollLeft: MotionVariants = {
6 | initial: {
7 | x: -100,
8 | rotate: 90,
9 | opacity: 0,
10 | },
11 | enter: {
12 | x: 0,
13 | rotate: 0,
14 | opacity: 1,
15 | },
16 | }
17 |
18 | export const rollVisibleLeft: MotionVariants = {
19 | initial: {
20 | x: -100,
21 | rotate: 90,
22 | opacity: 0,
23 | },
24 | visible: {
25 | x: 0,
26 | rotate: 0,
27 | opacity: 1,
28 | },
29 | }
30 |
31 | export const rollVisibleOnceLeft: MotionVariants = {
32 | initial: {
33 | x: -100,
34 | rotate: 90,
35 | opacity: 0,
36 | },
37 | visibleOnce: {
38 | x: 0,
39 | rotate: 0,
40 | opacity: 1,
41 | },
42 | }
43 |
44 | // Roll from right
45 |
46 | export const rollRight: MotionVariants = {
47 | initial: {
48 | x: 100,
49 | rotate: -90,
50 | opacity: 0,
51 | },
52 | enter: {
53 | x: 0,
54 | rotate: 0,
55 | opacity: 1,
56 | },
57 | }
58 |
59 | export const rollVisibleRight: MotionVariants = {
60 | initial: {
61 | x: 100,
62 | rotate: -90,
63 | opacity: 0,
64 | },
65 | visible: {
66 | x: 0,
67 | rotate: 0,
68 | opacity: 1,
69 | },
70 | }
71 |
72 | export const rollVisibleOnceRight: MotionVariants = {
73 | initial: {
74 | x: 100,
75 | rotate: -90,
76 | opacity: 0,
77 | },
78 | visibleOnce: {
79 | x: 0,
80 | rotate: 0,
81 | opacity: 1,
82 | },
83 | }
84 |
85 | // Roll from top
86 |
87 | export const rollTop: MotionVariants = {
88 | initial: {
89 | y: -100,
90 | rotate: -90,
91 | opacity: 0,
92 | },
93 | enter: {
94 | y: 0,
95 | rotate: 0,
96 | opacity: 1,
97 | },
98 | }
99 |
100 | export const rollVisibleTop: MotionVariants = {
101 | initial: {
102 | y: -100,
103 | rotate: -90,
104 | opacity: 0,
105 | },
106 | visible: {
107 | y: 0,
108 | rotate: 0,
109 | opacity: 1,
110 | },
111 | }
112 |
113 | export const rollVisibleOnceTop: MotionVariants = {
114 | initial: {
115 | y: -100,
116 | rotate: -90,
117 | opacity: 0,
118 | },
119 | visibleOnce: {
120 | y: 0,
121 | rotate: 0,
122 | opacity: 1,
123 | },
124 | }
125 |
126 | // Roll from bottom
127 |
128 | export const rollBottom: MotionVariants = {
129 | initial: {
130 | y: 100,
131 | rotate: 90,
132 | opacity: 0,
133 | },
134 | enter: {
135 | y: 0,
136 | rotate: 0,
137 | opacity: 1,
138 | },
139 | }
140 |
141 | export const rollVisibleBottom: MotionVariants = {
142 | initial: {
143 | y: 100,
144 | rotate: 90,
145 | opacity: 0,
146 | },
147 | visible: {
148 | y: 0,
149 | rotate: 0,
150 | opacity: 1,
151 | },
152 | }
153 |
154 | export const rollVisibleOnceBottom: MotionVariants = {
155 | initial: {
156 | y: 100,
157 | rotate: 90,
158 | opacity: 0,
159 | },
160 | visibleOnce: {
161 | y: 0,
162 | rotate: 0,
163 | opacity: 1,
164 | },
165 | }
166 |
167 | export default {
168 | rollLeft,
169 | rollVisibleLeft,
170 | rollVisibleOnceLeft,
171 | rollRight,
172 | rollVisibleRight,
173 | rollVisibleOnceRight,
174 | rollTop,
175 | rollVisibleTop,
176 | rollVisibleOnceTop,
177 | rollBottom,
178 | rollVisibleBottom,
179 | rollVisibleOnceBottom,
180 | }
181 |
--------------------------------------------------------------------------------
/src/directive/index.ts:
--------------------------------------------------------------------------------
1 | import type { Directive, DirectiveBinding, Ref, VNode } from 'vue'
2 | import defu from 'defu'
3 | import { ref, toRaw, unref } from 'vue'
4 | import { motionState } from '../features/state'
5 | import type { MotionInstance, MotionVariants } from '../types'
6 | import { useMotion } from '../useMotion'
7 | import { resolveVariants } from '../utils/directive'
8 | import { variantToStyle } from '../utils/transform'
9 | import { registerVisibilityHooks } from '../features/visibilityHooks'
10 |
11 | export function directive(
12 | variants?: MotionVariants,
13 | isPreset = false,
14 | ): Directive {
15 | const register = (el: HTMLElement | SVGElement, binding: DirectiveBinding, node: VNode>) => {
16 | // Get instance key if possible (binding value or element key in case of v-for's)
17 | const key = (binding.value && typeof binding.value === 'string' ? binding.value : node.key) as string
18 |
19 | // Cleanup previous motion instance if it exists
20 | if (key && motionState[key])
21 | motionState[key].stop()
22 |
23 | // We deep copy presets to prevent global mutation
24 | const variantsObject = isPreset ? structuredClone(toRaw(variants) || {}) : variants || {}
25 |
26 | // Initialize variants with argument
27 | const variantsRef = ref(variantsObject) as Ref>
28 |
29 | // Set variants from v-motion binding
30 | if (typeof binding.value === 'object')
31 | variantsRef.value = binding.value
32 |
33 | // Resolve variants from node props
34 | resolveVariants(node, variantsRef)
35 |
36 | // Disable visibilityHooks, these will be registered in `mounted`
37 | const motionOptions = { eventListeners: true, lifeCycleHooks: true, syncVariants: true, visibilityHooks: false }
38 |
39 | // Create motion instance
40 | const motionInstance = useMotion(
41 | el,
42 | variantsRef as MotionVariants,
43 | motionOptions,
44 | )
45 |
46 | // Pass the motion instance via the local element
47 | // @ts-expect-error - we know that the element is a HTMLElement
48 | el.motionInstance = motionInstance
49 |
50 | // Set the global state reference if the name is set through v-motion="`value`"
51 | if (key)
52 | motionState[key] = motionInstance
53 | }
54 |
55 | const mounted = (
56 | el: (HTMLElement | SVGElement) & { motionInstance?: MotionInstance> },
57 | _binding: DirectiveBinding,
58 | _node: VNode> }, Record>,
59 | ) => {
60 | // Visibility hooks
61 | // eslint-disable-next-line ts/no-unused-expressions
62 | el.motionInstance && registerVisibilityHooks(el.motionInstance)
63 | }
64 |
65 | return {
66 | created: register,
67 | mounted,
68 | getSSRProps(binding, node) {
69 | // Get initial value from binding
70 | let { initial: bindingInitial } = binding.value || (node && node?.props) || {}
71 |
72 | bindingInitial = unref(bindingInitial)
73 |
74 | // Merge it with directive initial variants
75 | const initial = defu({}, variants?.initial || {}, bindingInitial || {})
76 |
77 | // No initial
78 | if (!initial || Object.keys(initial).length === 0)
79 | return
80 |
81 | // Resolve variant
82 | const style = variantToStyle(initial)
83 |
84 | return {
85 | style,
86 | }
87 | },
88 | }
89 | }
90 |
91 | export default directive
92 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # 🤹 @vueuse/motion
2 |
3 | [](https://www.npmjs.com/package/@vueuse/motion)
4 | [](https://www.npmjs.com/package/vueuse-motion-nightly)
5 | [](https://npm-stat.com/charts.html?package=@vueuse/motion)
6 | [](https://www.npmjs.com/package/@vueuse/motion)
7 | [](https://app.netlify.com/sites/vueuse-motion/deploys)
8 |
9 | Vue Composables putting your components in motion
10 |
11 | - 🏎 **Smooth animations** based on [Popmotion](https://popmotion.io/)
12 | - 🎮 **Declarative** API inspired by [Framer Motion](https://www.framer.com/motion/)
13 | - 🚀 **Plug** & **play** with **20+ presets**
14 | - 🌐 **SSR Ready**
15 | - 🚚 First-class support for **Nuxt 3**
16 | - ✨ Written in **TypeScript**
17 | - 🏋️♀️ Lightweight with **<25kb** bundle size
18 |
19 | [🌍 Documentation](https://motion.vueuse.org)
20 |
21 | [👀 Demos](https://vueuse-motion-demo.netlify.app)
22 |
23 | ## Quick Start
24 |
25 | Let's get started by installing the package and adding the plugin.
26 |
27 | From your terminal:
28 |
29 | ```bash
30 | npm install @vueuse/motion
31 | ```
32 |
33 | In your Vue app entry file:
34 |
35 | ```javascript
36 | import { createApp } from "vue";
37 | import { MotionPlugin } from "@vueuse/motion";
38 | import App from "./App.vue";
39 |
40 | const app = createApp(App);
41 |
42 | app.use(MotionPlugin);
43 |
44 | app.mount("#app");
45 | ```
46 |
47 | You can now animate any of your component, HTML or SVG elements using `v-motion`.
48 |
49 | ```vue
50 |
51 |
62 |
63 | ```
64 |
65 | To see more about how to use directives, check out [Directive Usage](https://motion.vueuse.org/features/directive-usage).
66 |
67 | To see more about what properties you can animate, check out [Motion Properties](https://motion.vueuse.org/features/motion-properties).
68 |
69 | To see more about how to create your own animation styles, check out [Transition Properties](https://motion.vueuse.org/features/transition-properties).
70 |
71 | To see more about what are variants and how you can use them, check out [Variants](https://motion.vueuse.org/features/variants).
72 |
73 | To see more about how to control your declared variants, check out [Motion Instance](https://motion.vueuse.org/features/motion-instance).
74 |
75 | ## Nightly release channel
76 |
77 | You can try out the latest changes before a stable release by installing the nightly release channel.
78 |
79 | ```bash
80 | npm install @vueuse/motion@npm:vueuse-motion-nightly
81 | ```
82 |
83 | ## Credits
84 |
85 | This package is heavily inspired by [Framer Motion](https://www.framer.com/motion/) by [@mattgperry](https://twitter.com/mattgperry).
86 |
87 | If you are interested in using [WAAPI](https://developer.mozilla.org/fr/docs/Web/API/Web_Animations_API), check out [Motion.dev](https://motion.dev/)!
88 |
89 | I would also like to thank [antfu](https://github.com/antfu), [patak-dev](https://github.com/patak-dev) and [kazupon](https://github.com/kazupon) for their kind help!
90 |
91 | If you like this package, consider following me on [GitHub](https://github.com/Tahul) and on [Twitter](https://twitter.com/yaeeelglx).
92 |
93 | 👋
94 |
--------------------------------------------------------------------------------
/docs/components/content/PresetSection.vue:
--------------------------------------------------------------------------------
1 |
54 |
55 |
56 |
57 |
58 | {{ name.replace(/[A-Z]/g, (s: any) => ` ${s}`) }}
59 |
60 |
61 |
62 |
63 |
64 | {{ `
65 |
66 | ` }}
67 |
68 |
69 |
70 |
89 |
90 |