@molecule/app-haptics

Haptic feedback interface for molecule.dev.

Framework-agnostic core for tactile feedback through a swappable HapticsProvider: semantic feedback (impact, notification, selection), raw vibrate, custom playPattern sequences, and ready-made patterns presets.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { impact, isSupported, notification, selection } from '@molecule/app-haptics'

async function onAddToCart(): Promise<void> {
  if (!(await isSupported())) return // safe: false when nothing is wired
  await impact('medium')
}

async function onSaveSuccess(): Promise<void> {
  if (await isSupported()) await notification('success')
}

async function onPickerTick(): Promise<void> {
  if (await isSupported()) await selection()
}

Type

native

Installation

npm install @molecule/app-haptics @molecule/app-bond @molecule/app-i18n

API

Interfaces

HapticPatternElement

Haptic pattern element for custom patterns

interface HapticPatternElement {
  /** Type of haptic event */
  type: 'impact' | 'pause'
  /** Style for impact events */
  style?: ImpactStyle
  /** Duration in milliseconds for pause events */
  duration?: number
}

HapticCapabilities

Haptic capabilities on the current device

interface HapticCapabilities {
  /** Whether haptics are supported */
  supported: boolean
  /** Whether impact feedback is available */
  impactFeedback: boolean
  /** Whether notification feedback is available */
  notificationFeedback: boolean
  /** Whether selection feedback is available */
  selectionFeedback: boolean
  /** Whether custom patterns are supported */
  customPatterns: boolean
}

HapticsProvider

Haptics provider interface

interface HapticsProvider {
  /**
   * Trigger impact feedback
   * @param style - Impact style (default: 'medium')
   */
  impact(style?: ImpactStyle): Promise<void>

  /**
   * Trigger notification feedback
   * @param type - Notification type (default: 'success')
   */
  notification(type?: NotificationType): Promise<void>

  /**
   * Trigger selection feedback (light tap for UI selections)
   */
  selection(): Promise<void>

  /**
   * Vibrate for a specified duration
   * @param duration - Duration in milliseconds (default: 300)
   */
  vibrate(duration?: number): Promise<void>

  /**
   * Play a custom haptic pattern
   * @param pattern - Array of haptic pattern elements
   */
  playPattern(pattern: HapticPatternElement[]): Promise<void>

  /**
   * Check if haptics are supported on the current device
   * @returns Whether haptic feedback is supported.
   */
  isSupported(): Promise<boolean>

  /**
   * Get haptic capabilities for the current device
   * @returns The available haptic capabilities.
   */
  getCapabilities(): Promise<HapticCapabilities>
}

Types

ImpactStyle

Impact feedback styles - for button presses, collisions, etc.

type ImpactStyle = 'light' | 'medium' | 'heavy' | 'rigid' | 'soft'

NotificationType

Notification feedback types - for success/warning/error states

type NotificationType = 'success' | 'warning' | 'error'

Functions

setProvider(provider)

Set the haptics provider

function setProvider(provider: HapticsProvider): void

• provider — HapticsProvider implementation

getProvider()

Get the current haptics provider.

function getProvider(): HapticsProvider

Returns: The active haptics provider instance.

hasProvider()

Checks if a haptics provider has been bonded.

function hasProvider(): boolean

Returns: Whether a haptics provider is currently registered.

impact(style)

Triggers impact haptic feedback.

function impact(style?: ImpactStyle): Promise<void>

• style — Impact intensity style (default: 'medium').

Returns: A promise that resolves when the haptic feedback is triggered.

notification(type)

Triggers notification haptic feedback.

function notification(type?: NotificationType): Promise<void>

• type — Notification feedback type (default: 'success').

Returns: A promise that resolves when the haptic feedback is triggered.

selection()

Triggers selection haptic feedback (light tap for UI selections).

function selection(): Promise<void>

Returns: A promise that resolves when the haptic feedback is triggered.

vibrate(duration)

Vibrates the device for a specified duration.

function vibrate(duration?: number): Promise<void>

• duration — Duration in milliseconds (default: 300).

Returns: A promise that resolves when the vibration completes.

playPattern(pattern)

Plays a custom haptic pattern sequence.

function playPattern(pattern: HapticPatternElement[]): Promise<void>

• pattern — Array of haptic pattern elements defining the sequence.

Returns: A promise that resolves when the pattern finishes playing.

isSupported()

Checks if haptics are supported on the current device.

function isSupported(): Promise<boolean>

Returns: Whether haptic feedback is supported.

getCapabilities()

Gets the haptic capabilities for the current device.

function getCapabilities(): Promise<HapticCapabilities>

Returns: The available haptic capabilities.

Constants

patterns

Preset haptic patterns for common use cases

const patterns: {
  readonly doubleTap: HapticPatternElement[]
  readonly tripleTap: HapticPatternElement[]
  readonly success: HapticPatternElement[]
  readonly error: HapticPatternElement[]
  readonly warning: HapticPatternElement[]
  readonly heartbeat: HapticPatternElement[]
}

Injection Notes

Requirements

Peer dependencies:

• @molecule/app-bond ^1.0.1
• @molecule/app-i18n ^1.0.1

Runtime Dependencies

• @molecule/app-bond

• @molecule/app-i18n

• isSupported() is the only accessor that is safe to call unbonded (returns false); everything else THROWS until setProvider() is called. No prebuilt provider package ships with molecule — supply a HapticsProvider from your native runtime, or skip wiring and let isSupported() gate the calls away on web/desktop.

• Haptics are an ENHANCEMENT, never a channel: nothing may depend on the user feeling it (iPhones with System Haptics off, most desktops, and many Android WebViews produce nothing).

• A web provider would sit on navigator.vibrate — Android-Chrome only (no iOS Safari), it needs a prior user interaction, and it cannot vary intensity, so impact('light'|'heavy') degrades to timing patterns. Check getCapabilities() rather than assuming style nuance exists.

Translations

Translation strings are provided by @molecule/app-locales-haptics.