react-native-hapticlabs

A package to play back rich, custom haptics on both Android and iOS. We recommend using Hapticlabs Studio, our no-code haptics development tool, to design and prototype custom haptic signals.

Installation

npm install react-native-hapticlabs

Usage

Play haptics on Android:

import { playAndroidHaptics, playHLA, playOGG } from 'react-native-hapticlabs';

// Automatically selects the haptic feedback based on the device's haptic support level
playAndroidHaptics('Android samples/8bit.hac').then(() => {
  console.log('Android haptics played');
});

// Plays back the HLA file and associated audio files
playHLA('Android samples/8bit/main.hla').then(() => {
  console.log('HLA played');
});

// Plays back the OGG file with haptic feedback if the device supports it
playOGG('Android samples/8bit/main.ogg').then(() => {
  console.log('OGG played');
});

Play haptics on iOS:

import { playAHAP } from 'react-native-hapticlabs';
import RNFS from 'react-native-fs';

// Plays back the AHAP files and associated other AHAP and audio files
playAHAP(RNFS.MainBundlePath + '/AHAP/Button.ahap').then(() => {
  console.log('Played ahap');
});

Play haptics on both Android and iOS:

import { playHaptics } from 'react-native-hapticlabs';
import RNFS from 'react-native-fs';

// Plays back an AHAP file on iOS and an HLA or OGG file on Android
playHaptics({
  iosPath: RNFS.MainBundlePath + '/AHAP/Button.ahap',
  androidPath: 'Android samples/Button.hac',
}).then(() => {
  console.log('Played haptics');
});

For more information on these file formats, please consult our documentation.

API Reference

Cross-Platform

playHaptics

function playHaptics({
  iosPath,
  androidPath,
}: {
  iosPath: string;
  androidPath: string;
}): Promise<void>;

Plays an AHAP file on iOS and a haptic pattern on Android. Internally calls playAHAP or playAndroidHaptics.

• Platform: iOS and Android
• Parameters:
  • iosPath: string — Path to the AHAP file for iOS
  • androidPath: string — Path to a HAC file or a directory for Android. See playAndroidHaptics for expected directory structure.
• Returns: Promise

playPredefinedHaptics

function playPredefinedHaptics(signal: {
  android?: AndroidPredefinedHaptics;
  ios?: IOSPredefinedHaptics;
}): void;

Plays a predefined (built-in) haptic signal. Only one signal per platform is used.

• Platform: iOS and Android
• Parameters:
  • signal: object — { android?: AndroidPredefinedHaptics; ios?: IOSPredefinedHaptics }

Android

playHLA

function playHLA(path: string): Promise<void>;

Plays an HLA file from the specified path, including corresponding audio files.

• Platform: Android only
• Parameters:
  • path: string — Path to the HLA file (relative to assets or fully qualified)
• Returns: A Promise<void> that resolves when the playback terminates

playOGG

function playOGG(path: string): Promise<void>;

Plays an OGG file from the specified path, including encoded haptic feedback.

• Platform: Android only
• Parameters:
  • path: string — Path to the OGG file (relative to assets or fully qualified)
• Returns: A Promise<void> that resolves when the playback terminates
• Note: If the device's haptic support level is less than 3, only audio will play. Use playAndroidHaptics for auto-selection.

playHAC

function playHAC(path: string): Promise<void>;

Plays a HAC file from the specified path, containing multiple haptic patterns for different support levels. The device will select the optimal pattern.

• Platform: Android only
• Parameters:
  • path: string — Path to the HAC file (relative to assets or fully qualified)
• Returns: A Promise<void> that resolves when the playback terminates

playAndroidHaptics

function playAndroidHaptics(directoryOrHACPath: string): Promise<void>;

Plays a haptic pattern from a directory or HAC file. If a directory is specified, the pattern is selected based on device support level. If a HAC file is specified, behaves like playHAC.

If a directory is specified, the following structure is expected:

  directoryPath
  ├── lvl1
  │   └── main.hla
  ├── lvl2
  │   └── main.hla
  └── lvl3
      └── main.ogg

The most advanced signal supported by the device is chosen and played. For example, if the device reports haptic support level 2, directoryPath/lvl2/main.hla will be played.

Note that the directory-based structure is deprecated. We recommend using HAC files.

• Platform: Android only
• Parameters:
  • directoryOrHACPath: string — Path to a HAC file or the haptic pattern directory
• Returns: A Promise<void> that resolves when the playback terminates

preloadOGG

function preloadOGG(path: string): void;

Preloads an OGG file to reduce latency. Only OGG files <1MB (uncompressed) can be preloaded.

• Platform: Android only
• Parameters:
  • path: string — Path to the OGG file

preloadAndroidHaptics

function preloadAndroidHaptics(directoryOrHACPath: string): void;

Preloads haptic patterns from a directory or HAC file to reduce playback latency. Note that referenced OGG files >= 1MB (uncompressed) can not be preloaded.

• Platform: Android only
• Parameters:
  • directoryOrHACPath: string — Path to a HAC file or a directory for Android. See playAndroidHaptics for expected directory structure.

unloadOGG

function unloadOGG(path: string): void;

Unloads a preloaded OGG file to free memory.

• Platform: Android only
• Parameters:
  • path: string — Path to the OGG file

unloadAndroidHaptics

function unloadAndroidHaptics(directoryOrHACPath: string): void;

Unloads haptic patterns loaded from a directory or HAC file.

• Platform: Android only
• Parameters:
  • directoryOrHACPath: string — Path to a HAC file or a directory for Android. See playAndroidHaptics for expected directory structure.

unloadAllAndroidHaptics

function unloadAllAndroidHaptics(): void;

Unloads all haptic patterns that have been preloaded or played.

• Platform: Android only

iOS

playAHAP

function playAHAP(path: string): Promise<void>;

Plays an AHAP file from the specified path, including corresponding AHAP and audio files.

• Platform: iOS only
• Parameters:
  • path: string — Path to the AHAP file
• Returns: Promise

setHapticsMute

function setHapticsMute(mute: boolean): void;

Mutes or unmutes haptic feedback.

• Platform: iOS only
• Parameters:
  • mute: boolean
• Note: This only applies to AHAP files

isHapticsMuted

function isHapticsMuted(): Promise<boolean>;

Returns whether haptic feedback is muted.

• Platform: iOS only
• Note: This only applies to AHAP files

setAudioMute

function setAudioMute(mute: boolean): void;

Mutes or unmutes audio playback.

• Platform: iOS only
• Parameters:
  • mute: boolean
• Note: This only applies to audio referenced in AHAP files

isAudioMuted

function isAudioMuted(): Promise<boolean>;

Returns whether audio playback is muted.

• Platform: iOS only
• Note: This only applies to audio referenced in AHAP files

Constants

• androidHapticSupportLevel: 0 | 1 | 2 | 3 | 4 — Device haptic support level (Android only)
• areOnOffHapticsSupported: boolean — On/off haptic support (Android only)
• areAmplitudeControlHapticsSupported: boolean — Amplitude control support (Android only)
• areAudioCoupledHapticsSupported: boolean — Audio-coupled haptic support (Android only)
• areEnvelopeHapticsSupported: boolean — Envelope-controlled haptic support (Android only)
• resonanceFrequency: number | null — Resonance frequency (Android only)
• qFactor: number | null — Q factor (Android only)
• minFrequency: number | null — Minimum frequency (Android only)
• maxFrequency: number | null — Maximum frequency (Android only)
• maxAcceleration: number | null — Maximum acceleration (Android only)
• frequencyResponse: Map<number, number> | null — Frequency response (Android only)
• envelopeControlPointMinDurationMillis: number | null — Envelope control point min duration (Android only)
• envelopeControlPointMaxDurationMillis: number | null — Envelope control point max duration (Android only)
• envelopeMaxDurationMillis: number | null — Envelope max duration (Android only)
• envelopeMaxControlPointCount: number | null — Envelope max control points (Android only)

Enums

AndroidPredefinedHaptics

enum AndroidPredefinedHaptics {
  CLICK = 'Click',
  DOUBLE_CLICK = 'Double Click',
  HEAVY_CLICK = 'Heavy Click',
  TICK = 'Tick',
}

IOSPredefinedHaptics

enum IOSPredefinedHaptics {
  LIGHT = 'light',
  MEDIUM = 'medium',
  HEAVY = 'heavy',
  RIGID = 'rigid',
  SOFT = 'soft',
  SUCCESS = 'success',
  WARNING = 'warning',
  ERROR = 'error',
  SELECTION = 'selection',
}

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

Made with create-react-native-library