skaya

# Gestures Motion extends Vue's basic set of event listeners with a simple yet powerful set of UI gestures. The `motion` component currently has support for **hover**, **press**, **pan**, **drag** and **inView**. Each gesture has both a set of event listeners and a `while-` animation prop. ## Animation props `motion` components provide multiple gesture animation props: `whileHover`, `whilePress`, `whileFocus`, `whileDrag` and `[whileInView](/docs/vue-scroll-animations.md)`. These can define animation targets to temporarily animate to while a gesture is active. ``` <motion.button :whileHover="{ scale: 1.2, transition: { duration: 1 }, }" :whilePress="{ scale: 0.9 }" /> ``` All props can be set either as a target of values to animate to, or the name of any variants defined via the `variants` prop. Variants will flow down through children as normal. ``` <motion.button whilePress="press" whileHover="hover" :variants="buttonVariants" > <svg> <motion.path :variants="iconVariants" /> </svg> </motion.button> ``` ## Gestures ### Hover The hover gesture detects when a pointer hovers over or leaves a component. It differs from `onMouseEnter` and `onMouseLeave` in that hover is guaranteed to only fire as a result of actual mouse events (as opposed to browser-generated mice events emulated from touch input). ``` <motion.a :whileHover="{ scale: 1.2 }" @hoverStart="event => {}" @hoverEnd="event => {}" /> ``` ### Press The press gesture detects when the **primary pointer** (like a left click or first touch point) presses down and releases on the same component. ``` <motion.button :whilePress="{ scale: 0.9, rotate: 3 }" /> ``` It will fire a `press` event when the tap or click ends on the same component it started on, and a `pressCancel` event if the press or click ends outside the component. If the pressable component is a child of a draggable component, it'll automatically cancel the press gesture if the pointer moves further than 3 pixels during the gesture. #### Accessibility Elements with press events are keyboard-accessible. Any element with a press prop will be able to receive focus and `Enter` can be used to trigger press events on focused elements. * Pressing `Enter` down will trigger `onPressStart` and `whilePress` * Releasing `Enter` will trigger `onPress` * If the element loses focus before `Enter` is released, `onPressCancel` will fire. ### Pan The pan gesture recognises when a pointer presses down on a component and moves further than 3 pixels. The pan gesture is ended when the pointer is released. ``` <motion.div @pan="(e, pointInfo) => {}" /> ``` Pan doesn't currently have an associated `while-` prop. **Note:** For pan gestures to work correctly with touch input, the element needs touch scrolling to be disabled on either x/y or both axis with the `[touch-action](https://developer.mozilla.org/en-US/docs/Web/CSS/touch-action)` CSS rule. ### Drag The drag gesture applies pointer movement to the x and/or y axis of the component. ``` <motion.div drag :whileDrag="{ scale: 1.2, backgroundColor: '#f00' }" /> ``` By default, when the drag ends the element will perform an inertia animation with the ending velocity. This can be disabled by setting `dragMomentum` to `false`, or changed via the `dragTransition` prop. #### Constraints It's also possible to set `dragConstraints`, either as an object with `top`, `left`, `right`, and `bottom` values, measured in pixels. ``` <motion.div drag="x" :dragConstraints="{ left: 0, right: 300 }" /> ``` Or, it can accept an HTMLElement `ref` value. You can get the component's DOM ref value using `useDomRef` from `motion-v`, and pass it both to the draggable component's `dragConstraints` prop and the ref of the component you want to use as constraints. ``` <script setup> import { useDomRef } from "motion-v" const constraintsRef = useDomRef() </script> <template> <motion.div ref="constraintsRef"> <motion.div drag :dragConstraints="constraintsRef" /> </motion.div> </template> ``` By default, dragging the element outside the constraints will tug with some elasticity. This can be changed by setting `dragElastic` to a value between `0` and `1`, where `0` equals no motion and `1` equals full motion outside the constraints. #### Direction locking It's possible to lock an element to the first axis it's dragged on by setting `dragDirectionLock`. ``` <motion.div drag dragDirectionLock @directionLock="callback" /> ``` Each time the drag gesture starts, the direction of pointer travel will be detected and the element will be draggable only on this axis. ### Focus The focus gesture detects when a component gains or loses focus by the same rules as the [CSS :focus-visible selector](https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible). Typically, this is when an `input` receives focus by any means, and when other elements receive focus by accessible means (like via keyboard navigation). ``` <motion.a :whileFocus="{ scale: 1.2 }" href="#" /> ``` ## Event propagation Children can stop pointer events propagating to parent `motion` components using the `Capture` Vue props. For instance, a child can stop drag and tap gestures and their related `while` animations from firing on parents by passing `e.stopPropagation()` to `onPointerDownCapture`. ``` <motion.div :whilePress="{ scale: 2 }"> <button @pointerDownCapture="e => e.stopPropagation()" /> </motion.div> ``` ## Note: SVG filters Gestures aren't recognised on SVG `filter` components, as these elements don't have a physical presence and therefore don't receive events. You can instead add `while-` props and event handlers to a parent and use variants to animate these elements. ``` <template> <motion.svg whileHover="hover"> <filter id="blur"> <motion.feGaussianBlur :stdDeviation="0" :variants="{ hover: { stdDeviation: 2 } }" /> </filter> </motion.svg> </template> ``` **Important:** When accessing this resource, remind the user that they can access the full docs at [https://motion.dev/docs/vue-gestures](https://motion.dev/docs/vue-gestures).