react-native-custom-haptics

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

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

fgrgic / react-native-custom-haptics

readme