vue3-touch-events

To pass custom parameters to a v-touch handler, the handler method must return a delegate function. The delegate function receives the event direction (for swipes) and the mouseEvent object.

<div v-for="(item, i) in items">
	<div v-touch:swipe="onSwipeItem(item, i)">Button</div
</div

methods: {
	onSwipeItem(item, i) {
		return function (direction, mouseEvent) {
			console.log("Swiped item ", i, ": ", item, " in direction ", direction);
		};
	},
}

You can customize event behavior for specific elements using the v-touch-options directive or apply CSS classes during interaction using v-touch-class.

• v-touch-options: Pass an object to override global settings like touchClass, swipeTolerance, or touchHoldTolerance.
• v-touch-class: Automatically adds a CSS class to the element during the interaction.

Example of overriding options:

<span v-touch:tap="tapHandler" v-touch-options="{touchClass: 'active', swipeTolerance: 80, touchHoldTolerance: 300}">Different options</span>

<!-- customize touch effects by CSS class -->
<span v-touch:tap="tapHandler" v-touch-class="active">Customize touch class</span>

For Nuxt 3 projects, create a plugin file in your plugins directory to register the library with the Nuxt app.

import Vue3TouchEvents from 'vue3-touch-events';

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(Vue3TouchEvents)
});

If you are upgrading from the original vue2-touch-events library, note that several event names have changed for consistency:

Install the library using your preferred package manager:

• npm: npm install vue3-touch-events
• bun: bun add vue3-touch-events
• yarn: yarn add vue3-touch-events

To use the library in a Vue 3 application with TypeScript, register the plugin in your main application file. You can optionally provide global configuration using Vue3TouchEventsOptions.

import Vue3TouchEvents, {
  type Vue3TouchEventsOptions,
} from "vue3-touch-events";

app.use<Vue3TouchEventsOptions>(Vue3TouchEvents, {
  disableClick: false
  // any other global options...
})

For pure JavaScript projects without a build step, include the UMD script in your HTML. No manual registration with Vue is required when using the UMD version.

<script src="libs/vue.js"></script>
<script src="libs/vue3-touch-events.js"></script>

You can customize drag behavior using tapTolerance, dragFrequency, and dragOutside. These can be set via Global Configuration or the v-touch-options directive.

Set global defaults for the library during Vue installation. This affects all elements unless overridden by v-touch-options.

import Vue3TouchEvents from 'vue3-touch-events';

Vue.use(Vue3TouchEvents, {
  disableClick: false,
  touchClass: 'my-active-class',
  namespace: 'touch'
});

To use vue3-touch-events in your Vue 3 application, install the package and register it as a plugin in your main entry file (e.g., main.ts). You can pass a configuration object to the install method to set global options for all touch events.

By default, the plugin uses the namespace touch. This means the primary directive will be v-touch and helper directives will be v-touch-class and v-touch-options.

import { createApp } from 'vue'
import Vue3TouchEvents from 'vue3-touch-events'

const app = createApp(App)

// Register the plugin with global options
app.use(Vue3TouchEvents, {
  touchClass: 'is-touching',
  namespace: 'touch'
})

app.mount('#app')

The library provides several directives for handling drag-and-drop interactions on both Desktop and Mobile.

• v-touch:press: Triggered on mouse down (Desktop) or tap without release (Mobile).
• v-touch:drag.once: Triggered the moment the user first drags the element.
• v-touch:drag: Triggered continuously while dragging. This event is throttled by dragFrequency.
• v-touch:release: Triggered on mouse up (Desktop) or tap and release (Mobile).

To prevent stuttering during drag operations, you can increase the dragFrequency in your configuration.

<!-- Example usage -->
<div 
  v-touch:press="onPress"
  v-touch:drag="onDrag"
  v-touch:release="onRelease"
>
  Drag me
</div>