nuxt-haptic

nuxt-haptic

Nuxt 4 module for mobile haptics, powered by web-haptics.

It wraps the browser Vibration API with a Nuxt-first DX:

• client and server plugins, so SSR and prerender stay safe
• useNuxtHaptics() auto-import
• v-nuxt-haptic directive for declarative interactions
• typed $nuxtHaptics injection
• persisted enabled state with touch-only behavior by default

Install

npx nuxt module add nuxt-haptic

Or install manually:

bun add nuxt-haptic

export default defineNuxtConfig({
  modules: ['nuxt-haptic'],
})

Quick Use

<script setup lang="ts">
const { success } = useNuxtHaptics()
</script>

<template>
  <button v-nuxt-haptic="'selection'" type="button">
    Tap
  </button>

  <button type="button" @click="success()">
    Save
  </button>
</template>

Options

export default defineNuxtConfig({
  modules: ['nuxt-haptic'],
  nuxtHaptic: {
    defaultPreset: 'selection',
    enabled: true,
    persistPreference: true,
    preferenceStorageKey: 'nuxt-haptic:enabled',
    touchOnly: true,
    debug: false,
    showSwitch: false,
  },
})

defaultPreset accepts any web-haptics input, including built-in preset names, numbers, arrays, and custom pattern objects.

API

useNuxtHaptics()

Returns:

• trigger(input?, options?)
• selection()
• light()
• success()
• warning()
• error()
• cancel()
• enabled
• isSupported
• setEnabled(value)
• toggleEnabled()
• config

If you need types in userland:

import type { HapticInput, PresetName, TriggerOptions } from 'nuxt-haptic'

v-nuxt-haptic

String shorthand:

<a v-nuxt-haptic="'selection'" href="/contact/">Contact</a>

Object form:

<button
  v-nuxt-haptic="{ input: 'light', on: 'pointerdown', intensity: 0.7 }"
  type="button"
>
  Press
</button>

Directive fields:

• input: any web-haptics input
• on: click, pointerdown, or pointerup
• intensity: optional intensity override
• touchOnly: override module default per element
• disabled: disable haptics for that node

Notes

• On devices without Vibration API support, web-haptics falls back cleanly and can optionally emit debug audio.
• The directive ignores non-primary mouse and pointer activation.
• The server plugin provides a no-op directive and injection so Nuxt prerender does not break.

Development

# Install dependencies
bun install

# Prepare stubs and types
bun run dev:prepare

# Run the playground
bun run dev

# Run tests
bun run test
bun run test:types

# Build the package
bun run prepack

Credits

• web-haptics by Lochie Axon for the underlying haptics runtime.

License

MIT