From f3655125d8cf7b5cfb06c9fc26e6b9ae17efa596 Mon Sep 17 00:00:00 2001 From: Dennis Smuda Date: Wed, 26 Feb 2025 19:58:53 +0100 Subject: [PATCH 1/2] docs: add "useMotionValueEvent" content + fix errors --- docs/components/layout/IsLand.vue | 2 +- docs/content/4.motion-value/0.overview.md | 8 +-- .../1.use-motion-value-event.md | 58 +++++++++++++++++++ 3 files changed, 63 insertions(+), 5 deletions(-) diff --git a/docs/components/layout/IsLand.vue b/docs/components/layout/IsLand.vue index 7fbd36b..6f568d9 100644 --- a/docs/components/layout/IsLand.vue +++ b/docs/components/layout/IsLand.vue @@ -19,7 +19,7 @@ const open = ref(false) const scrollPercentage = ref(0) const { scrollYProgress } = useScroll() -useMotionValue(scrollYProgress, 'change', (value) => { +useMotionValueEvent(scrollYProgress, 'change', (value) => { scrollPercentage.value = value }) diff --git a/docs/content/4.motion-value/0.overview.md b/docs/content/4.motion-value/0.overview.md index c00e714..1e1747d 100644 --- a/docs/content/4.motion-value/0.overview.md +++ b/docs/content/4.motion-value/0.overview.md @@ -53,7 +53,7 @@ const opacity = useTransform( ## Usage -Motion values can be created with the [`useMotionValue`](/motion-value/use-motion-value-event) composable. The string or number passed to `useMotionValue` will act as its initial state. +Motion values can be created with the `useMotionValue` composable. The string or number passed to `useMotionValue` will act as its initial state. ```ts import { useMotionValue } from 'motion-v' @@ -99,10 +99,10 @@ For strings and colors, `getVelocity` will always return 0. ### Events -Listeners can be added to motion values via the `on` method or the [`useMotionValue`](/motion-value/use-motion-value-event) composable. +Listeners can be added to motion values via the `on` method or the [`useMotionValueEvent`](/motion-value/use-motion-value-event) composable. ```ts -useMotionValue(x, 'change', latest => console.log(latest)) +useMotionValueEvent(x, 'change', latest => console.log(latest)) ``` Available events are `"change"`, `"animationStart"`, `"animationComplete"` `"animationCancel"`. @@ -182,7 +182,7 @@ It returns a function that, when called, will unsubscribe the listener. const unsubscribe = x.on('change', latest => console.log(latest)) ``` -You can `on` inside a vue component, or instead use the [`useMotionValue`](/motion-value/use-motion-value-event) composable. +You can use `on` inside a vue component, or instead use the [`useMotionValueEvent`](/motion-value/use-motion-value-event) composable. ### `destroy()` diff --git a/docs/content/4.motion-value/1.use-motion-value-event.md b/docs/content/4.motion-value/1.use-motion-value-event.md index ddc5e00..6722d7d 100644 --- a/docs/content/4.motion-value/1.use-motion-value-event.md +++ b/docs/content/4.motion-value/1.use-motion-value-event.md @@ -4,4 +4,62 @@ description: navigation.icon: 'lucide:ear' --- +`useMotionValueEvent` manages a motion value event handler throughout the lifecycle of a vue component. + +```vue + + + +``` + +When the component is unmounted, event handlers will be safely cleaned up. + +## Usage + +Import from Motion Vue: + +```ts +const color = useMotionValue('#00f') + +useMotionValueEvent(color, 'change', (latest) => { + console.log(latest) +}) +``` + +Available events are: + +- `change` +- `animationStart` +- `animationComplete` +- `animationCancel` + +`change` events are provided the latest value of the motion value. + +## Advanced + +`useMotionValueEvent` is a helper function for a motion value's [on method](/motion-value/overview#on). With `on`, you can start listening to events whenever you like, for instance within an event handler. But remember to also unsubscribe when the component unmounts. + - [Motion React-useMotionValueEvent](https://motion.dev/docs/react-use-motion-value-event) + +```ts +function doSomething() {} + +const color = useMotionValue('#00f') +const unsub = color.on('change', doSomething) + +onUnmounted(() => { + unsub() +}) +``` From c76970f0639d6b942b0d590feaf88110331e150c Mon Sep 17 00:00:00 2001 From: Dennis Smuda Date: Wed, 26 Feb 2025 20:04:16 +0100 Subject: [PATCH 2/2] docs: add missing import section --- docs/content/4.motion-value/1.use-motion-value-event.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/content/4.motion-value/1.use-motion-value-event.md b/docs/content/4.motion-value/1.use-motion-value-event.md index 6722d7d..be39597 100644 --- a/docs/content/4.motion-value/1.use-motion-value-event.md +++ b/docs/content/4.motion-value/1.use-motion-value-event.md @@ -30,6 +30,12 @@ When the component is unmounted, event handlers will be safely cleaned up. Import from Motion Vue: +```ts +import { useMotionValueEvent } from 'motion-v' +``` + +To add an event listener to a motion value, provide the value, event name and callback: + ```ts const color = useMotionValue('#00f')