haptic_feedback
A haptic feedback plugin for both iOS and Android.
While it utilizes standard iOS haptics, it aims to emulate these same haptic patterns on Android for a consistent experience across platforms.
haptic_feedback requires Flutter 3.47 or newer and Android API 24 or newer when targeting Android.
iOS builds require iOS 15 or newer.
Android builds require Java 17 or newer and AGP 9 with built-in Kotlin support. The plugin does not
apply or bundle the external Kotlin Gradle Plugin. Existing apps must migrate
their Gradle configuration and remove any android.builtInKotlin=false opt-out;
updating Flutter alone does not migrate the app. See Flutter's
AGP 9 migration guide.
For a guide on when to use each haptic type, see Missing haptic types, and which to use when by Kamran.
Getting Started
1. Add the dependency
Flutter 3.47+
dependencies:
haptic_feedback: ^0.9.0+2
Flutter 3.10–<3.47
dependencies:
haptic_feedback: ^0.6.5
For 0.6.x setup and usage, see its documentation.
2. Use the plugin
import 'package:haptic_feedback/haptic_feedback.dart';
final canVibrate = await Haptics.canVibrate();
await Haptics.vibrate(HapticsType.success);
await Haptics.vibrate(HapticsType.warning);
await Haptics.vibrate(HapticsType.error);
await Haptics.vibrate(HapticsType.light);
await Haptics.vibrate(HapticsType.medium);
await Haptics.vibrate(HapticsType.heavy);
await Haptics.vibrate(HapticsType.rigid);
await Haptics.vibrate(HapticsType.soft);
await Haptics.vibrate(HapticsType.selection);
canVibrate() reports hardware capability. A true result does not guarantee
that feedback will play: user settings, device state, and hardware support can
suppress it. On web and desktop, it returns false and vibrate() does
nothing.
Android vibration exceptions are returned as PlatformException with code
VIBRATION_ERROR. Missing plugin registration can throw MissingPluginException.
You can handle these failures when needed (exception classes are from
package:flutter/services.dart):
import 'package:flutter/services.dart';
import 'package:haptic_feedback/haptic_feedback.dart';
try {
await Haptics.vibrate(HapticsType.success);
} on PlatformException catch (e) {
// Handle or log as needed
} on MissingPluginException catch (e) {
// Handle missing plugin registration
}
3. Lower latency on iOS (optional)
vibrate() works without preparation. When a haptic must line up exactly with
an animation or sound, call prepare() with the same type a moment before it
is likely to fire, for example when a drag starts:
GestureDetector(
onPanStart: (_) => Haptics.prepare(HapticsType.success),
onPanEnd: (_) => Haptics.vibrate(HapticsType.success),
);
Calling prepare() right before vibrate() doesn't reduce latency; call it
ahead of time. The generator stays ready for only a few seconds or until the
next haptic, so calling it once at app start doesn't help either.
success, warning and error share one generator. On Android, web and
desktop, prepare() does nothing.
Android-specific options
// Use native Android haptic constants (default: false)
// When true, uses HapticFeedbackConstants like CONFIRM, REJECT, etc.
// When false, uses custom vibration primitives that are more aligned
// with iOS haptics
await Haptics.vibrate(
HapticsType.success,
useAndroidHapticConstants: false, // default
);
// On Android 13+, you can hint how the system should treat this vibration
// (alarm, communicationRequest, hardwareFeedback, media, notification, physicalEmulation, ringtone, touch, unknown)
await Haptics.vibrate(
HapticsType.success,
usage: HapticsUsage.media,
);
The optional usage parameter is a hint for the system.
It can influence how the vibration is routed and which volume / haptics
settings control it (for example, notification vs touch feedback).
Use a concrete value whenever the vibration clearly matches one of the
defined categories (for example HapticsUsage.notification for reminders
or status updates), and use HapticsUsage.touch for taps and other UI feedback.
Omitting usage keeps Android's default classification, which is not guaranteed
to behave the same as explicitly specifying HapticsUsage.unknown on every OS.
When a native haptic constant is used, Android applies its touch-feedback
settings and ignores usage. Custom patterns and fallbacks apply usage on
API 33+, including devices without amplitude control.
iOS: SwiftPM vs CocoaPods
Flutter has enabled Swift Package Manager (SwiftPM) by default since 3.44. This plugin supports both SwiftPM and CocoaPods. Both configuration commands below remain available in Flutter 3.47.
If you previously disabled SwiftPM, re-enable it globally with:
flutter config --enable-swift-package-manager
To use CocoaPods globally for the current user, run:
flutter config --no-enable-swift-package-manager
For a project-specific CocoaPods opt-out, set this in the app's pubspec.yaml:
flutter:
config:
enable-swift-package-manager: false
Disabling SwiftPM does not remove its existing Xcode integration. See Flutter's SwiftPM guide for migration and removal steps.
Platform Implementation
iOS
Uses Apple's native haptic feedback APIs:
UINotificationFeedbackGeneratorfor success, warning, and errorUIImpactFeedbackGeneratorfor light, medium, heavy, rigid, and softUISelectionFeedbackGeneratorfor selection
Android
On Android, the plugin selects a strategy based on both the API level and hardware support. These patterns approximate iOS feedback; their timing and feel can vary across devices.
Strategy 1: Native HapticFeedbackConstants (when enabled)
When useAndroidHapticConstants: true, the plugin uses Android's system-level haptic constants via View.performHapticFeedback():
| Type | Android Constant | API Level |
|---|---|---|
| success | CONFIRM |
≥ 30 |
| error | REJECT |
≥ 30 |
| light | VIRTUAL_KEY |
≥ 5 |
| medium | KEYBOARD_PRESS (≥ 27) / KEYBOARD_TAP (≥ 8) |
≥ 8 |
| heavy | CONTEXT_CLICK |
≥ 23 |
| selection | CLOCK_TICK |
≥ 21 |
warning, rigid, and soft have no mapping in this plugin and use custom
patterns. Custom patterns also apply when the mapped constant is unavailable
or no activity is attached. Once a mapped constant is dispatched, the plugin
respects Android's result and does not bypass disabled feedback with a fallback.
Strategy 2: Haptic Primitives (API 30+)
When native constants aren't available or useAndroidHapticConstants: false (default), the plugin uses VibrationEffect.Composition, which is tuned to resemble the iOS patterns:
| Type | Primitive(s) | Description |
|---|---|---|
| success | CLICK × 2 | Two clicks with increasing intensity |
| warning | CLICK × 2 | Two clicks with decreasing intensity |
| error | CLICK × 4 | Four clicks with an accented third pulse |
| light | TICK | Subtle, light feedback |
| medium | CLICK | Moderate feedback |
| heavy | THUD | Strong, deep feedback |
| rigid | CLICK | Sharp, crisp feedback |
| soft | SPIN* | Gentle, longer feedback |
| selection | TICK | Subtle selection feedback |
* SPIN requires API 31+; falls back to TICK on API 30.
Strategy 3: Waveform Vibrations (API 26+)
For devices without the required primitives, the plugin uses
VibrationEffect.createWaveform(). Devices with amplitude control use the tuned
amplitudes; others use timing-only waveforms.
Strategy 4: Legacy Vibration (API < 26)
Basic timing-only patterns for older devices.
For detailed timing specifications and implementation rationale, see HAPTIC_PATTERNS.md.
Testing
In native Flutter widget tests, defaultTargetPlatform is TargetPlatform.android by default, but the default platform implementation still calls the method channel and will throw MissingPluginException unless you register a mock. If you swap in a mock platform that returns true, Haptics.canVibrate() will return true even on a non-mobile host unless you override the target platform.
To test widgets that use haptic feedback, you can:
- Use
debugDefaultTargetPlatformOverrideto test platform-specific behavior:
import 'package:flutter/foundation.dart';
import 'package:flutter_test/flutter_test.dart';
void main() {
testWidgets('test on iOS', (tester) async {
final originalTarget = debugDefaultTargetPlatformOverride;
debugDefaultTargetPlatformOverride = TargetPlatform.iOS;
try {
// Your test code here
} finally {
debugDefaultTargetPlatformOverride = originalTarget;
}
});
}
- Mock the platform interface in your tests:
import 'package:flutter/foundation.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:haptic_feedback/haptic_feedback.dart';
import 'package:haptic_feedback/src/haptic_feedback_platform_interface.dart';
class FakeHapticFeedbackPlatform extends HapticFeedbackPlatform {
@override
Future<bool> canVibrate() async => true;
@override
Future<void> vibrate(
HapticsType type, {
HapticsUsage? usage,
bool useAndroidHapticConstants = false,
}) async {}
}
void main() {
test('haptic calls use the fake platform', () async {
final originalPlatform = HapticFeedbackPlatform.instance;
final originalTarget = debugDefaultTargetPlatformOverride;
addTearDown(() {
HapticFeedbackPlatform.instance = originalPlatform;
debugDefaultTargetPlatformOverride = originalTarget;
});
debugDefaultTargetPlatformOverride = TargetPlatform.android;
HapticFeedbackPlatform.instance = FakeHapticFeedbackPlatform();
expect(await Haptics.canVibrate(), isTrue);
await Haptics.vibrate(HapticsType.success);
});
}
- Mock the method channel to avoid
MissingPluginExceptionwhile using the real platform class:
import 'package:flutter/services.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:haptic_feedback/src/haptic_feedback_method_channel.dart';
import 'package:haptic_feedback/src/haptics_type.dart';
void main() {
const channel = MethodChannelHapticFeedback.methodChannel;
TestDefaultBinaryMessengerBinding.ensureInitialized();
setUp(() {
final binding = TestDefaultBinaryMessengerBinding.instance;
binding.defaultBinaryMessenger.setMockMethodCallHandler(
channel,
(MethodCall call) async {
if (call.method == 'canVibrate') return true;
return null; // success for vibrate calls
},
);
});
tearDown(() {
final binding = TestDefaultBinaryMessengerBinding.instance;
binding.defaultBinaryMessenger.setMockMethodCallHandler(channel, null);
});
test('canVibrate works with mocked channel', () async {
expect(await MethodChannelHapticFeedback().canVibrate(), isTrue);
});
test('vibrate forwards to mocked channel', () async {
await MethodChannelHapticFeedback().vibrate(HapticsType.success);
});
}
You can find these examples as runnable tests in example/test on GitHub.
Automatic Permissions Inclusion
Android VIBRATE Permission
When you integrate the haptic_feedback plugin into your Flutter project, it will automatically include the necessary VIBRATE permission in the final merged AndroidManifest.xml of your app. This is due to the permission being declared in the plugin's manifest.
What this means for you:
-
No Manual Action Required: You don't have to add the
<uses-permission android:name="android.permission.VIBRATE"/>permission to your app'sAndroidManifest.xmlmanually. It will be automatically merged when building the app. -
Transparency: By using the
haptic_feedbackplugin, your app will request theVIBRATEpermission. Ensure that you are aware of all permissions your app requires, especially if you publish it on app stores. Some users may be sensitive to app permissions, even if they don't require explicit consent. -
Permission Overview: To review all permissions that your app requests due to plugins and your own declarations, inspect the final merged
AndroidManifest.xmlafter a build. This will provide a comprehensive view of all permissions and other manifest entries.