VueUse Gesture

Common errors

• Failed to resolve import "vue-use-gesture" from "src/components/MyComponent.vue". Does the file exist?

  cause Attempting to import from the old, unmaintained package name `vue-use-gesture`.
  fix Change the import path to `@vueuse/gesture`: `import { useDrag } from '@vueuse/gesture'`.

• [Vue warn]: Failed to resolve component: v-drag
  If this is a custom element, make sure to add it to GlobalComponents property.

  cause The `v-drag` directive was used without being registered with the Vue application.
  fix Globally register the `DragDirective` at your app's entry point: `import { DragDirective } from '@vueuse/gesture'; app.directive('drag', DragDirective);`.

• [Vue warn]: inject() can only be used inside setup() or functional components.

  cause Attempting to use `@vueuse/gesture` composables in a Vue 2 project without installing `@vue/composition-api`, or using them outside a `setup` function context.
  fix For Vue 2, ensure `@vue/composition-api` is installed and registered. Ensure all `use*` hooks are called directly within the `setup` function of a component.

Warnings

• breaking The original `vue-use-gesture` package by koca has been superseded and re-homed under the VueUse organization as `@vueuse/gesture`. Ensure you are installing and importing from the `@vueuse/gesture` package.
  Fix: Update your package.json to `@vueuse/gesture` and adjust import paths accordingly. E.g., `npm install @vueuse/gesture` or `yarn add @vueuse/gesture`.
• gotcha When creating draggable elements, it is crucial to set the `touch-action` CSS property to `none` (or specific axes like `pan-x`, `pan-y`) on the draggable element. Failing to do so can cause conflicts with native browser scrolling on touch devices, leading to unexpected behavior or glitches.
  Fix: Add `touch-action: none;` to the CSS of your draggable element, or apply it via inline style as shown in the quickstart example.
• gotcha For Vue 2 projects, `@vueuse/gesture` requires `@vue/composition-api` to be installed and correctly set up for the composables to function.
  Fix: Install `@vue/composition-api` (`npm install @vue/composition-api`) and ensure it's registered with Vue (e.g., `Vue.use(VueCompositionAPI)`).
• gotcha If you intend to use the gesture directives (e.g., `v-drag`, `v-pinch`), they must be explicitly registered either globally via `app.directive()` (Vue 3) or `Vue.directive()` (Vue 2), or locally within components.
  Fix: Import the specific directive (e.g., `DragDirective`) and register it: `import { DragDirective } from '@vueuse/gesture'; app.directive('drag', DragDirective);`.

Install

• npm install vue-use-gesture npm
• yarn add vue-use-gesture yarn
• pnpm add vue-use-gesture pnpm

Imports

• useDrag
  wrong:

  import { useDrag } from 'vue-use-gesture'

  correct:

  import { useDrag } from '@vueuse/gesture'

  Main composable for drag gestures. The package was re-homed from 'vue-use-gesture' to '@vueuse/gesture'.
• useGesture

  import { useGesture } from '@vueuse/gesture'

  A powerful composable for handling multiple gestures simultaneously with a single hook.
• v-drag (directive)
  wrong:

  import { vDrag } from '@vueuse/gesture'

  correct:

  import { DragDirective } from '@vueuse/gesture'; app.directive('drag', DragDirective);

  For directive usage (e.g., `<div v-drag>`), you must globally or component-locally register the `DragDirective`.
• usePinch

  import { usePinch } from '@vueuse/gesture'

  Composable for handling multi-touch pinch gestures.

Quickstart

Demonstrates a basic draggable element using the `useDrag` composable, integrating with `vue-use-spring` for smooth animation and including the essential `touch-action` CSS property.

<template>
  <!-- Bind it to a component -->
  <div v-bind="bind()" :style="style" class="box"></div>
</template>

<script lang="ts">
  import { useDrag } from '@vueuse/gesture'
  import { useSpring } from 'vue-use-spring'
  import { defineComponent, computed } from 'vue'

  export default defineComponent({
    setup() {
      const [{ x, y }, set] = useSpring(() => ({ x: 0, y: 0 }))

      // Set the drag hook and define component movement based on gesture data
      const bind = useDrag(({ down, movement: [mx, my] }) => {
        set({ x: down ? mx : 0, y: down ? my : 0 })
      })

      const style = computed(() => ({
        transform: `translate3d(${x.value}px,${y.value}px,0)`,
        touchAction: 'none' // Crucial for preventing browser native scrolling glitches
      }))

      return { bind, style }
    },
  })
</script>

<style scoped>
.box {
  width: 100px;
  height: 100px;
  background: #42b983;
  border-radius: 8px;
  cursor: grab;
  user-select: none;
}
.box:active {
  cursor: grabbing;
}
</style>