flutter_vibration_manager #

A production-ready, cross-platform Flutter plugin for high-performance vibration and haptic feedback on Android and iOS.

Features #

• ⚡ Cross-Platform Haptic Feedback: Light, medium, heavy, soft, rigid, and selection haptics.
• 🔔 Notification Patterns: Native success, warning, and error haptics.
• 🎛️ Amplitude Control: Fine-grained vibration intensity on supported Android devices.
• 🌊 Waveforms & Patterns: Timed vibration sequences and repeating patterns with cancellation.
• 🎯 Usage Categorization: Semantic usage tagging (touch, notification, alarm, media, etc.).
• 🛡️ Hardware Capability Detection: Safe queries for vibrator presence, amplitude support, waveform support, and haptics support.
• 📦 Structured Results & Zero Crashes: Graceful fallback strategies; non-blocking asynchronous APIs with VibrationResult.

Platform Support Matrix #

Installation #

Add flutter_vibration_manager to your pubspec.yaml:

dependencies:
  flutter_vibration_manager: ^1.0.0

Then run:

flutter pub get

Platform Configuration #

Android #

Add the VIBRATE permission to your android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.VIBRATE" />

No runtime permission dialogs are required for normal vibration.

iOS #

No additional permissions or Info.plist entries are required for haptic feedback and system vibrations.

Usage Guide #

1. Basic Vibration #

import 'package:flutter_vibration_manager/flutter_vibration_manager.dart';

// Default vibration (500 ms)
final result = await FlutterVibrationManager.vibrate();

// Custom duration (e.g. 200 ms)
await FlutterVibrationManager.vibrate(
  duration: const Duration(milliseconds: 200),
);

// Custom duration and amplitude (1-255)
await FlutterVibrationManager.vibrate(
  duration: const Duration(milliseconds: 300),
  amplitude: 128,
  usage: VibrationUsage.touch,
);

2. Haptic Feedback #

Exposes platform-neutral haptic feedback styles:

// Light impact
await FlutterVibrationManager.haptic(HapticType.light);

// Medium impact
await FlutterVibrationManager.haptic(HapticType.medium);

// Heavy impact
await FlutterVibrationManager.haptic(HapticType.heavy);

// Soft impact
await FlutterVibrationManager.haptic(HapticType.soft);

// Rigid impact
await FlutterVibrationManager.haptic(HapticType.rigid);

// Selection feedback
await FlutterVibrationManager.haptic(HapticType.selection);

3. Notification Feedback #

Pre-configured vibration signatures for user notifications:

await FlutterVibrationManager.notification(NotificationType.success);
await FlutterVibrationManager.notification(NotificationType.warning);
await FlutterVibrationManager.notification(NotificationType.error);

4. Custom Waveforms & Repeat #

Trigger timed vibration patterns:

// Pattern: [delay, vibrate, delay, vibrate...]
await FlutterVibrationManager.waveform(
  pattern: const [
    Duration(milliseconds: 0),
    Duration(milliseconds: 100),
    Duration(milliseconds: 50),
    Duration(milliseconds: 200),
  ],
  amplitudes: const [0, 100, 0, 255], // Must match pattern length
);

// Repeating pattern (repeat: index in pattern array to loop from)
await FlutterVibrationManager.waveform(
  pattern: const [
    Duration(milliseconds: 0),
    Duration(milliseconds: 200),
    Duration(milliseconds: 300),
  ],
  repeat: 0,
);

// Stop repeating or active vibration
await FlutterVibrationManager.cancel();

5. Capability Detection #

Query device hardware before triggering haptic features:

final bool isSupported = await FlutterVibrationManager.isSupported();
final bool hasVib = await FlutterVibrationManager.hasVibrator();
final bool hasAmp = await FlutterVibrationManager.hasAmplitudeControl();

final VibrationCapabilities caps = await FlutterVibrationManager.capabilities();
print('Vibrator motor: ${caps.hasVibrator}');
print('Amplitude control: ${caps.supportsAmplitude}');
print('Haptics support: ${caps.supportsHaptics}');
print('Waveform support: ${caps.supportsWaveform}');

6. Structured Result Handling #

Every asynchronous operation returns a VibrationResult:

final result = await FlutterVibrationManager.vibrate();

if (result.isSuccess) {
  print('Vibration succeeded!');
} else {
  print('Vibration failed: ${result.status} - ${result.message}');
}

Possible VibrationStatus values:

• success
• unsupported
• unavailable
• invalidArguments
• permissionDenied
• platformError

Known Platform Differences #

1. iOS Arbitrary Waveforms: iOS does not expose arbitrary millisecond/amplitude waveform control via standard UIFeedbackGenerator or AudioServicesPlaySystemSound. When calling waveform() on iOS, it safely falls back to standard system vibration.
2. Android Amplitude Control: Amplitude control requires Android API 26+ and hardware motor support. On devices without amplitude control, default amplitude is automatically used.
3. Simulators: Simulators (Android Emulator & iOS Simulator) generally do not emulate physical vibration motors. Use capability checks (hasVibrator()) or physical test devices.

Publishing to pub.flutter-io.cn #

To publish this package to pub.flutter-io.cn:

# 1. Run dry run to check for any publication warnings
flutter pub publish --dry-run

# 2. Publish to pub.flutter-io.cn
flutter pub publish

License #

This project is licensed under the MIT License - see the LICENSE file for details.