@capacitor/haptics

@capacitor/haptics gives a Capacitor app a single JavaScript API for triggering physical touch feedback, then routes the call to whatever the platform actually supports: UIKit’s impact/notification/selection feedback generators and CoreHaptics on iOS, the Android VibratorManager/VibrationEffect APIs (with SDK-version fallbacks back to Android’s original vibrate calls), and the browser’s navigator.vibrate on the web. Developers write one impact(), notification(), vibrate(), or selectionStart/Changed/End() call and get device-appropriate feedback without branching on platform themselves.

It is maintained as an official first-party Capacitor plugin by the Ionic team, split out of the capacitor-plugins monorepo into its own repo. On devices without a Taptic Engine or vibration motor, calls resolve silently instead of throwing, which keeps calling code simple across a wide range of hardware.

What You Get

• impact() feedback with Heavy/Medium/Light styles mapped to UIImpactFeedbackGenerator on iOS and matching vibration waveforms on Android/web
• notification() feedback with Success/Warning/Error types mapped to UINotificationFeedbackGenerator on iOS and distinct vibration patterns elsewhere
• vibrate() for a raw, duration-based vibration using CoreHaptics on iOS and VibrationEffect on Android
• selectionStart()/selectionChanged()/selectionEnd() for continuous selection-change haptics (e.g. dragging through a picker or slider)
• A web fallback (HapticsWeb) built on navigator.vibrate so the same code runs in a PWA or browser preview with graceful degradation
• TypeScript types and docgen-generated API docs kept in sync with the native Swift/Kotlin implementations

Common Use Cases

• Confirming a button tap, swipe, or drag-to-reorder action with a light impact
• Signaling success/warning/error outcomes (form submit, payment result, validation) with notification feedback
• Providing tactile feedback while scrubbing through a custom picker, slider, or segmented control via selectionStart/Changed/End
• Replacing an audible alert with a vibration cue in contexts where sound is inappropriate
• Matching the tactile feel of native iOS/Android UI components inside a hybrid Capacitor app

Under The Hood

Architecture The plugin is a thin, single-purpose Capacitor bridge: src/index.ts calls registerPlugin('Haptics', ...) with a lazily-imported HapticsWeb class (src/web.ts, extending Capacitor’s WebPlugin) as the browser implementation, while the same HapticsPlugin TypeScript interface (src/definitions.ts) is fulfilled natively by android/.../HapticsPlugin.java delegating to a plain Haptics.java helper that wraps VibratorManager/Vibrator with API-level branching, and by ios/Sources/HapticsPlugin/HapticsPlugin.swift delegating to a Haptics.swift helper that wraps UIImpactFeedbackGenerator, UINotificationFeedbackGenerator, UISelectionFeedbackGenerator, and CHHapticEngine (CoreHaptics) with a fallback to AudioServicesPlayAlertSound if the haptic engine fails to start. There is no shared business logic beyond the interface contract — each platform independently implements the same six-method surface, which keeps the bridge simple but means behavioral parity across platforms is maintained by convention, not by shared code.

Tech Stack The web/TS layer builds with tsc plus Rollup into ESM and UMD (dist/plugin.js) bundles, using @capacitor/docgen to regenerate the README’s API tables from JSDoc comments, and depends on @capacitor/core 8.x as a peer dependency. The Android side is a standard Gradle library module in Java targeting the platform’s Vibrator/VibrationEffect APIs (with a documented pre-API-26 fallback path). The iOS side ships both a CocoaPods podspec and a Swift Package Manager manifest, built against UIKit, CoreHaptics, and AudioToolbox. Releases across all three targets (npm, CocoaPods trunk, Maven Central) are automated via semantic-release and its plugin ecosystem, driven by dedicated GitHub Actions workflows.

Code Quality Naming is consistent across all three implementations (impact/notification/vibrate/selectionStart/selectionChanged/selectionEnd), and the TypeScript interface is the enforced contract all platforms implement. Error handling favors graceful degradation over throwing: the web layer throws only when navigator.vibrate is entirely absent, and the iOS layer falls back from CoreHaptics to a simple system vibrate sound if the haptic engine fails to initialize. However, genuine automated test coverage is thin — the iOS and Android test directories contain only the platform’s default scaffolded example tests (an empty XCTest case, a trivial JUnit assertion), not tests exercising the plugin’s actual behavior; verification instead relies on CI build/lint workflows across iOS, Android, and web, plus manual exercise through the bundled example app. Linting is enforced via ESLint (@ionic/eslint-config), Prettier, and SwiftLint, all wired into CI.

What Makes It Unique Rather than reinventing haptics, the plugin’s value is in faithfully mapping one small API onto each platform’s idiomatic, richest feedback primitive — CoreHaptics’ custom-duration continuous haptic patterns on iOS rather than a blunt vibrate call, and Android’s newer VibratorManager/VibrationEffect.createWaveform API with a documented legacy fallback rather than a single one-size-fits-all vibration. As an official first-party Capacitor plugin (not a community wrapper), it’s the default, low-friction choice for haptic feedback in the Capacitor ecosystem and is kept version-aligned with @capacitor/core releases.