react-native-tickle

The library provides three distinct ways to trigger haptics depending on your use case:

1. Transient: Instant "click/tap" events. These have no duration and are triggered at a specific point in time.
2. Continuous (pattern): Time-based patterns defined ahead of time. You provide events (which include a duration) and optionally curves (which provide automation/modulation over time).
3. Continuous player (real-time): Used for unpredictable input like gesture positions or scroll velocity. You create a player once, then use a start → update (many times) → stop lifecycle.

Note on Events vs. Curves:

• Events define the structure (what happens and when).
• Curves define the modulation (how parameters like intensity or sharpness evolve over time).

In this library (via CoreHaptics), CHHapticParameterCurve values act as pattern-level multipliers rather than per-event modifiers. If you define an intensity or sharpness curve, it will multiply the intensity/sharpness of all events playing at that specific moment, including transient events.

The Problem: If a transient event has a base intensity of 1.0 but an active intensity curve has a value of 0.3 at that same timestamp, the resulting effective intensity will be 0.3 (1.0 × 0.3). This makes transients feel weaker than intended if they occur during a continuous event with active curves.

Install the package along with its required dependency react-native-nitro-modules using npm:

npm i @renegades/react-native-tickle react-native-nitro-modules

Before building the app, you must start the Metro JavaScript build tool. Run this command from the root of your project.

# Using npm
npm start

# OR using Yarn
yarn start

To prevent curves from affecting transient events, play the continuous and transient events in separate startHaptic() calls. This creates isolated patterns/players so that curves from one call do not multiply the intensity of events in the other.

Note: The library automatically resets control values to 1.0 at the end of each continuous event. Therefore, transients occurring after a continuous event has finished are not affected by its curves. The limitation only applies to transients occurring during a continuous event with active curves.

// Continuous with curves
startHaptic(continuousEvents, curves);

// Transients without curves (separate pattern)
startHaptic(transientEvents, []);

The recommended way to use the library is to wrap your application in the HapticProvider. This component initializes the haptic engine and automatically destroys it when the app moves to the background.

import { HapticProvider } from '@renegades/react-native-tickle';

export function App() {
  return <HapticProvider>{/* {Rest of your app} */}</HapticProvider>;
}

With Metro running, use the following command to build and launch the application on an Android emulator or connected device.

# Using npm
npm run android

# OR using Yarn
yarn android

If you need to perform a full reload to reset the app state, use the following platform-specific methods:

• Android: Press the <kbd>R</kbd> key twice, or open the Dev Menu via <kbd>Ctrl</kbd> + <kbd>M</kbd> (Windows/Linux) or <kbd>Cmd ⌘</kbd> + <kbd>M</kbd> (macOS) and select "Reload".
• iOS: Press <kbd>R</kbd> in the iOS Simulator.

For iOS, you must first install CocoaPods dependencies. If this is your first time or you have updated native dependencies, run bundle exec pod install. Then, use the following command to build and launch the application on an iOS simulator or connected device.

# Install CocoaPods dependencies
bundle exec pod install

# Using npm
npm run ios

# OR using Yarn
yarn ios

To prevent haptics from playing when a user navigates away or a component unmounts, call stopAllHaptics(). This is especially useful in navigation listeners (like beforeRemove in Expo Router) or useEffect cleanup functions.

import { stopAllHaptics } from '@renegades/react-native-tickle';
import { useEffect } from 'react';

export function SomeScreen() {
  // Stop haptics when screen unmounts
  useEffect(() => () => stopAllHaptics(), []);
  return null;
}

For haptics that respond to real-time data (like gestures), use the useContinuousPlayer hook. This provides start, stop, and update methods to control a player instance by ID.

import { useContinuousPlayer } from '@renegades/react-native-tickle';

function MyComponent() {
  // playerId, initialIntensity, initialSharpness
  const { start, stop, update } = useContinuousPlayer('my-player', 1.0, 0.5);

  const gesture = Gesture.Pan()
    .onBegin(() => {
      start();
    })
    .onUpdate((e) => {
      // Update intensity/sharpness based on gesture
      update(e.translationY / 100, 0.5);
    })
    .onEnd(() => {
      stop();
    });
}