TangentHapticFeedback

A powerful, type-safe haptic feedback library for Flutter. Create rich, customizable haptic patterns using iOS Core Haptics.

Features

• Pattern-based API - Haptics are defined as composable, reusable patterns
• Parameter curves - Intensity and sharpness can change over time (fade in, fade out, pulse, etc.)
• Built-in patterns - 20+ ready-to-use patterns for common use cases
• Fluent builder - Create complex patterns with an intuitive builder API
• Type-safe - Full compile-time type safety with sealed classes
• Silent fail - Gracefully handles unsupported devices without throwing errors

Platform Support

Platform	Status
iOS 13+	Supported
Android	Coming soon

Installation

Add to your pubspec.yaml:

dependencies:
  tangent_haptic_feedback: ^0.0.1

Quick Start

import 'package:tangent_haptic_feedback/tangent_haptic_feedback.dart';

// Play a built-in pattern
await TangentHapticFeedback.play(HapticPatterns.success);

// Prepare the engine for reduced latency (optional)
await TangentHapticFeedback.prepare();

Usage

Built-in Patterns

// Simple taps
await TangentHapticFeedback.play(HapticPatterns.lightTap);
await TangentHapticFeedback.play(HapticPatterns.mediumTap);
await TangentHapticFeedback.play(HapticPatterns.heavyTap);

// Notifications
await TangentHapticFeedback.play(HapticPatterns.success);
await TangentHapticFeedback.play(HapticPatterns.warning);
await TangentHapticFeedback.play(HapticPatterns.error);

// Expressive
await TangentHapticFeedback.play(HapticPatterns.heartbeat);
await TangentHapticFeedback.play(HapticPatterns.doubleClick);

// Curved patterns
await TangentHapticFeedback.play(HapticPatterns.explosion);
await TangentHapticFeedback.play(HapticPatterns.engineRev);
await TangentHapticFeedback.play(HapticPatterns.chargeUp);

Custom Patterns

// Create a pattern with individual events
final pattern = HapticPattern([
  TransientEvent(intensity: 0.8, sharpness: 0.6),
  TransientEvent(
    intensity: 1.0,
    sharpness: 0.8,
    delay: Duration(milliseconds: 100),
  ),
]);

await TangentHapticFeedback.play(pattern);

Pattern Builder

final pattern = HapticPatternBuilder()
  .tap(intensity: 0.6)
  .waitMs(50)
  .tap(intensity: 0.8)
  .waitMs(50)
  .tap(intensity: 1.0)
  .waitMs(100)
  .rumble(
    duration: Duration(milliseconds: 200),
    intensity: 0.5,
  )
  .build();

await TangentHapticFeedback.play(pattern);

Parameter Curves

Continuous events support intensity and sharpness curves that change over time:

// Fade out explosion
final explosion = HapticPattern([
  ContinuousEvent.curved(
    intensity: HapticParam.fadeOut,
    duration: Duration(milliseconds: 400),
  ),
]);

// Engine revving up
final engineRev = HapticPattern([
  ContinuousEvent.curved(
    intensity: HapticParam.rampUp,
    sharpness: HapticParam.linear(from: 0.3, to: 0.8),
    duration: Duration(milliseconds: 600),
  ),
]);

// Custom curve with control points
final custom = HapticPattern([
  ContinuousEvent.curved(
    intensity: HapticParam.curve([
      (0.0, 0.1),   // start soft
      (0.3, 1.0),   // spike up
      (1.0, 0.0),   // fade out
    ]),
    duration: Duration(milliseconds: 500),
  ),
]);

Available curve presets:

• HapticParam.fadeIn - 0.0 to 1.0
• HapticParam.fadeOut - 1.0 to 0.0
• HapticParam.rampUp - 0.3 to 1.0
• HapticParam.rampDown - 1.0 to 0.3
• HapticParam.pulse - 0.0 to 1.0 to 0.0
• HapticParam.spike - quick rise, slow decay

Pattern Composition

// Chain patterns sequentially
final combo = HapticPatterns.success.then(HapticPatterns.buzz);

// Repeat a pattern
final repeatedHeartbeat = HapticPatterns.heartbeat.repeat(
  3,
  gap: Duration(milliseconds: 400),
);

// Scale intensity
final gentleTap = HapticPatterns.heavyTap.scaled(0.5);

// Overlay patterns (play simultaneously)
final layered = pattern1.overlay(pattern2);

// Operators
final sequential = pattern1 + pattern2;  // same as .then()
final parallel = pattern1 | pattern2;    // same as .overlay()

API Reference

TangentHapticFeedback

Method	Description
play(HapticPattern)	Play a haptic pattern
prepare()	Warm up the haptic engine for reduced latency
stop()	Stop any currently playing pattern

HapticEvent Types

Type	Description
TransientEvent	Sharp, instantaneous tap (intensity, sharpness, delay)
ContinuousEvent	Sustained rumble with constant values
ContinuousEvent.curved	Sustained rumble with parameter curves

HapticPatterns Library

Simple taps: lightTap, mediumTap, heavyTap, soft, rigid

UI feedback: selection, doubleClick, tripleClick

Notifications: success, warning, error

Expressive: heartbeat, buzz, longBuzz

Curved: explosion, engineRev, pulseWave, impactDecay, chargeUp

Requirements

• iOS 13.0 or later
• Flutter 3.3.0 or later

Roadmap

• Android support using VibrationEffect API
• Audio-haptic synchronization
• Pattern serialization (save/load patterns)
• More built-in patterns

License

MIT License - see LICENSE for details.