react-native-custom-haptics

Custom haptic patterns for React Native. Built on top of expo-haptics package.

Updating from previous versions

Installation

This module uses expo-haptics as a peer dependency

npm

npm i -s expo expo-haptics
npm i -s react-native-custom-haptics

yarn

yarn add expo expo-haptics
yarn add react-native-custom-haptics

If you're using managed workflow, this is enough. For bare workflow you should also follow these additional installation instructions.

Usage

Similar to React Native's Vibrate, react-native-custom-haptics uses an array that describes the pattern.

const SUCCESS_PATTERN = ['light', 300, 'light', 300, 'heavy'];

Every even index will be evaluated as a description of the impact, and every odd inded as a pause between the vibrations.

// App.tsx
import { HapticsProvider } from 'react-native-custom-haptics';

// ...

const App = () => {
  return (
    <HapticsProvider>
      // <RestOfTheApp />
    </HapticsProvider>
  );
};

// Screen.tsx
import { useHaptics } from 'react-native-custom-haptics';

const Screen = () => {
  const { trigger, stop } = useHaptics();

  React.useEffect(() => {
    // stops the haptic pattern on cleanup
    return () => stop();
  }, []);

  return (
    <View>
      <Button title="Press Me" onPress={() => trigger(SUCCESS_PATTERN)} />
    </View>
  );
};

export default App;

Advanced Usage

Define a set of constants for the haptic feedbacks inside the application:

// haptics.config.ts
export const SUCCESS = ['light', 300, 'light', 400, 'heavy'];
export const WARNING = ['light', 300, 'heavy', 300, 'light'];
export const ERROR = ['heavy', 300, 400];

// CustomButton.tsx
// ...
import { useHaptics } from 'react-native-custom-haptics';

import * as patterns from '.../haptics.config'

const PrimaryButton = () => {
  const {trigger, stop} => useHaptics();

  React.useEffect(() => () => stop(), [])

  return (
    <Pressable style={...} onPress={() => trigger(patterns.SUCCESS)}>
      <Text>Press</Text>
    </Pressable>
  )
}

// ...

export default PrimaryButton;

Package Exports

| name | description | | ------------------ | ----------------------------------------------------------------- | | HapticsProvider | wrapper for the app | | useHaptics | set of functions to trigger haptic patterns | | HapticImpactType | type of haptic impact. Read more here. | | HapticsOptions | type of additional, optional options. Read more here. |

useHaptics

| exported value | description | | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | | trigger(pattern: Impact[], options?: HapticsOptions) | triggers a haptics pattern passed as an argument. Impact Type, options | | stop() | stops running the pattern if any exists | | isRunning | boolean that is true if any haptic pattern is currently running, false otherwise |

Haptic Impact Type

Impact can be:

• "light": light impact
• "medium": medium impact
• "heavy": heavy impact
• "vibrate": vibrate for 400ms (default value for Android and the only possible valuse for iOS)
• "select": select impact (softer)
• number: set the length of vibration in ms on Android, iOS will always vibrate for 400ms.

type HapticImpactType =
  | 'light'
  | 'medium'
  | 'heavy'
  | 'vibrate'
  | 'select'
  | number;

Options

options is an optional parameter in trigger function. It's an object of HapticsOptions type. | option | description | values |default | | --- | --- | --- | --- | |platforms|array containing platforms where the pattern should run|'ios' \| 'android'[]| undefined (runs on ios and android) |

Updating

1.0.0

If you were using the pre-release 0.1.0, update introduces one breaking change to the trigger function:

trigger(...pattern: HapticImpactType[]) → trigger(pattern: HapticImpactType[], options?: HapticsOptions)

License

MIT