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

``sh
npm install react-native-hapticlabs
`

Usage

Play haptics on Android:

`typescript
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:

`typescript
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:

`typescript
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

$3

#### playHaptics

`typescript
function playHaptics({
iosPath,
androidPath,
}: {
iosPath: string;
androidPath: string;
}): Promise;
`

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

`typescript
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 }

$3

#### playHLA

`typescript
function playHLA(path: string): Promise;
`

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 that resolves when the playback terminates

---

#### playOGG

`typescript
function playOGG(path: string): Promise;
`

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 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

`typescript
function playHAC(path: string): Promise;
`

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 that resolves when the playback terminates

---

#### playAndroidHaptics

`typescript
function playAndroidHaptics(directoryOrHACPath: string): Promise;
`

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 that resolves when the playback terminates

---

#### preloadOGG

`typescript
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

`typescript
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

`typescript
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

`typescript
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

`typescript
function unloadAllAndroidHaptics(): void;
`

Unloads all haptic patterns that have been preloaded or played.

- Platform: Android only

$3

#### playAHAP

`typescript
function playAHAP(path: string): Promise;
`

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

`typescript
function setHapticsMute(mute: boolean): void;
`

Mutes or unmutes haptic feedback.

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

---

#### isHapticsMuted

`typescript
function isHapticsMuted(): Promise;
`

Returns whether haptic feedback is muted.

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

---

#### setAudioMute

`typescript
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

`typescript
function isAudioMuted(): Promise;
`

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 | 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

$3

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

$3

`typescript
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