vue-capacitor-haptics

Vue utilities for Capacitor haptics with a production-ready default strategy:

• smart cooldown to prevent haptic spam
• Android softening for less aggressive feedback
• optional web fallback using navigator.vibrate
• reduced-motion support
• Vue directive, Vue plugin, and composable API

Installation

npm install vue-capacitor-haptics @capacitor/core @capacitor/haptics

pnpm add vue-capacitor-haptics @capacitor/core @capacitor/haptics

yarn add vue-capacitor-haptics @capacitor/core @capacitor/haptics

Quick start

import { createApp } from 'vue';
import App from './App.vue';
import { VueCapacitorHaptics } from 'vue-capacitor-haptics';

const app = createApp(App);
app.use(VueCapacitorHaptics);
app.mount('#app');

This registers the v-haptic directive globally.

Plugin options

import { VueCapacitorHaptics } from 'vue-capacitor-haptics';

app.use(VueCapacitorHaptics, {
  directiveName: 'haptic',
  defaultEvent: 'pointerdown',
  defaultKind: 'tap',
  engine: {
    enabled: () => settingsStore.hapticsEnabled,
    webVibrateFallback: true,
    respectReducedMotion: true,
    globalCooldownMs: 70,
    repeatCooldownMs: 120,
    defaultThrottleMs: 70,
  },
});

Directive usage

Recommended style: use directive arguments (v-haptic:tap, v-haptic:cta, etc.) for kind selection.

Default

<ion-button v-haptic:tap>Tap</ion-button>

Kind shorthand (recommended)

<ion-button v-haptic:cta>Primary CTA</ion-button>
<ion-button v-haptic:success>Success</ion-button>
<ion-button v-haptic:error>Error</ion-button>

Object config

<div
  v-haptic="{
    kind: 'selection',
    event: 'pointermove',
    throttle: 120,
    enabled: true,
  }"
/>

Directive argument

<ion-button v-haptic:success>Save</ion-button>
<ion-button v-haptic:click="{ kind: 'tap' }">Click event</ion-button>

Composable usage

import { useHaptics } from 'vue-capacitor-haptics';

const haptics = useHaptics({
  enabled: () => settingsStore.hapticsEnabled,
  webVibrateFallback: true,
});

await haptics.trigger('selection');
await haptics.trigger('cta');
await haptics.trigger('success');

Recommended for sliders: trigger on value change

import { useHaptics } from 'vue-capacitor-haptics';

const haptics = useHaptics();
const onStepChange = haptics.createOnChangeTrigger<number>({
  kind: 'selection',
  skipInitial: true,
  throttle: 120,
});

await onStepChange(activeIndex.value);

This is usually better than using pointermove directly, because haptics only fire when the step/value actually changes.

Kind mapping

• tap, toggle -> impact light
• cta -> impact medium on iOS, softened to light on Android
• selection -> selection changed
• success, warning, error -> notification feedback

API

Main exports:

• VueCapacitorHaptics (Vue plugin)
• hapticDirective, createHapticDirective
• useHaptics, createHaptics
• ImpactStyle, NotificationType

Main types:

• HapticKind
• HapticEngineOptions
• HapticsPluginOptions
• HapticDirectiveValue, HapticDirectiveConfig
• TriggerHapticOptions, CreateOnChangeTriggerOptions<T>
• ImpactOptions, NotificationOptions, VibrateOptions

Testing

yarn type-check
yarn test
yarn test:coverage

Notes

• Native haptics require a Capacitor runtime (iOS/Android).
• On web, fallback vibration is optional and browser/device dependent.
• If prefers-reduced-motion: reduce is active and respectReducedMotion is enabled, no haptic feedback is emitted.

License

MIT.