### react-native-nitro-haptic

Lightweight, fast haptics for React Native powered by Nitro Modules. Supports simple presets and fully custom haptic patterns on iOS and Android.

### Disclaimer

This library was primarily generated by ChatGPT. The author does not know C++, Kotlin, or Swift. Use at your own risk; reviews and contributions are welcome.

### Installation

Install the library and Nitro Modules:

```bash
npm i react-native-nitro-haptic react-native-nitro-modules
# or
bun add react-native-nitro-haptic react-native-nitro-modules
# or
yarn add react-native-nitro-haptic react-native-nitro-modules
```

iOS pods:

```bash
npx pod-install
```

Then rebuild your app.

Notes
- Android vibrate permission is included by the library manifest
- iOS Core Haptics custom patterns require iOS 13+; presets work on older iOS via UIKit feedback generators

### Quick start

Trigger a preset or play a custom pattern

```ts
import { notify, play } from 'react-native-nitro-haptic'

notify('selection')

play({
  events: [
    { eventType: 'hapticTransient', time: 0, parameters: { intensity: 1, sharpness: 0.6 } },
    { eventType: 'hapticTransient', time: 0.2, parameters: { intensity: 0.8, sharpness: 0.3 } }
  ]
})
```

Check availability

```ts
import { NitroHaptic } from 'react-native-nitro-haptic'

if (NitroHaptic.isAvailable()) {
  notify('impactMedium')
}
```

### Presets

Available `HapticPreset` values

```
'selection' | 'impactLight' | 'impactMedium' | 'impactHeavy' | 'impactSoft' | 'impactRigid' | 'notificationSuccess' | 'notificationWarning' | 'notificationError'
```

### API

| Name | Type | Description |
| --- | --- | --- |
| notify | (preset: HapticPreset) => void | Triggers a one-shot preset. Cross‑platform. |
| play | (pattern: HapticPattern) => Promise<void> | Plays a custom haptic pattern. On iOS uses Core Haptics; on Android approximates with waveform. |
| NitroHaptic | Haptic | The underlying Nitro hybrid object exposing `isAvailable`, `notify`, `play`. |
| HapticPreset | union | See Presets list above. |
| HapticPattern | { events: HapticEvent[] } | Pattern container. |
| HapticEvent | { eventType, time, eventDuration?, parameters? } | Single event within a pattern. |
| HapticEventType | 'hapticTransient' \| 'hapticContinuous' | Event kind: transient tap or continuous buzz. |
| HapticParameters | { intensity?: number; sharpness?: number } | Both in [0..1]. |

Event fields
- **eventType**: 'hapticTransient' or 'hapticContinuous'
- **time**: seconds from pattern start (number)
- **eventDuration**: duration in seconds for continuous events
- **parameters.intensity**: 0..1 amplitude
- **parameters.sharpness**: 0..1 brightness (iOS); used to shape transient length on Android

### Custom pattern examples

Heartbeat

```ts
import { play } from 'react-native-nitro-haptic'

play({
  events: [
    { eventType: 'hapticTransient', time: 0, parameters: { intensity: 0.8, sharpness: 0.2 } },
    { eventType: 'hapticTransient', time: 0.2, parameters: { intensity: 1, sharpness: 0.3 } }
  ]
})
```

Crescendo

```ts
play({
  events: Array.from({ length: 8 }).map((_, i) => ({
    eventType: 'hapticTransient' as const,
    time: i * 0.06,
    parameters: { intensity: Math.min(0.2 + i * 0.1, 1), sharpness: 0.3 + i * 0.05 }
  }))
})
```

### Migrating from react-native-haptic-feedback

Use the helper map to keep familiar names

```ts
import { RNHFPresetToNitro, notify } from 'react-native-nitro-haptic'

notify(RNHFPresetToNitro.rigid)
notify(RNHFPresetToNitro.notificationSuccess)
```

### Platform notes

- **iOS**: Presets are backed by `UI*FeedbackGenerator`. Custom patterns use Core Haptics and require a device with haptics (iOS 13+). On devices without Core Haptics, `play` resolves without producing haptics.
- **Android**: Presets and patterns use `Vibrator`/`VibrationEffect`. On API < 26, patterns degrade to a single vibration; on API 26+, waveforms with custom amplitudes are used.

### Example app

See `example` for a runnable showcase with multiple presets and patterns.

### Contributing

- [Development workflow](CONTRIBUTING.md#development-workflow)
- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
- [Code of conduct](CODE_OF_CONDUCT.md)

### License

MIT

—

Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)