Skip to content

Commit 45b510b

Browse files
Mhp23Mhp23
committed
docs: updating the documents
1 parent 2364efe commit 45b510b

2 files changed

Lines changed: 319 additions & 4 deletions

File tree

‎README.md‎

Lines changed: 118 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,131 @@
44
</a>
55
</p>
66

7-
A high-performance React Native library for iOS haptics and Android vibration effects
7+
A high-performance React Native library for iOS haptics and Android vibration effects.
88

9-
> **Only New Architecture**: This library is currently compatible with the new architecture. If you're using React Native 0.76 or higher, it is already enabled. However, if your React Native version is between 0.68 and 0.75, you need to enable it first. [Click here if you need help enabling the new architecture](https://github.com/reactwg/react-native-new-architecture/blob/main/docs/enable-apps.md)
9+
<div align="center">
10+
<a href="./docs/USAGE.md">Documentation</a> · <a href="./example/">Example</a>
11+
</div>
12+
<br/>
13+
14+
> **Only New Architecture**: This library is only compatible with the new architecture. If you're using React Native 0.76 or higher, it is already enabled. However, if your React Native version is between 0.68 and 0.75, you need to enable it first. [Click here if you need help enabling the new architecture](https://github.com/reactwg/react-native-new-architecture/blob/main/docs/enable-apps.md)
15+
16+
## Features
17+
18+
- 🚀 &nbsp;High-performance library built with Turbo Modules for Android and iOS
19+
20+
- 🎛️ &nbsp;Provides essential methods for triggering native haptic feedback
21+
22+
- 🤖 &nbsp;Supports a wide range of Android-specific vibration effects
23+
24+
- 🛠️ &nbsp;Easy to use with simple APIs
25+
26+
- 🧵 &nbsp;Executes on the UI thread to ensure instant feedback
27+
28+
- ✅ &nbsp;Fully type-safe and written in TypeScript
1029

1130
## Installation
1231

13-
**_Developing..._**
32+
### Bare React Native
33+
34+
Install the package using either npm or Yarn:
35+
36+
```sh
37+
npm install @mhpdev/react-native-haptics
38+
```
39+
40+
Or with Yarn:
41+
42+
```sh
43+
yarn add @mhpdev/react-native-haptics
44+
```
45+
46+
For iOS, navigate to the ios directory and install the pods:
47+
48+
```sh
49+
cd ios && pod install
50+
```
51+
52+
### Expo
53+
54+
For Expo projects, follow these steps:
55+
56+
1. Install the package:
57+
58+
```sh
59+
npx expo install @mhpdev/react-native-haptics
60+
```
61+
62+
2. Since it is not supported on Expo Go, run:
63+
64+
```sh
65+
npx expo prebuild
66+
```
67+
68+
## Usage
69+
70+
To learn how to use the library, check out the [usage section](./docs/USAGE.md).
71+
72+
## Quick Start
73+
74+
```tsx
75+
import React from 'react';
76+
import Haptics from '@mhpdev/react-native-haptics';
77+
import {SafeAreaView, StyleSheet, Text, TouchableOpacity} from 'react-native';
78+
79+
const App: React.FC = () => {
80+
const onImpactPress = () => {
81+
Haptics.impact('heavy');
82+
};
83+
84+
return (
85+
<SafeAreaView style={styles.container}>
86+
<TouchableOpacity style={styles.button} onPress={onImpactPress}>
87+
<Text style={styles.buttonText}>Trigger Heavy Impact</Text>
88+
</TouchableOpacity>
89+
</SafeAreaView>
90+
);
91+
};
92+
93+
export default App;
94+
95+
const styles = StyleSheet.create({
96+
container: {
97+
flex: 1,
98+
alignItems: 'center',
99+
justifyContent: 'center',
100+
},
101+
button: {
102+
padding: 12.5,
103+
borderRadius: 5,
104+
backgroundColor: 'skyblue',
105+
},
106+
buttonText: {
107+
fontSize: 22,
108+
fontWeight: '600',
109+
},
110+
});
111+
```
112+
113+
To become more familiar with the usage of the library, check out the [example project](./example/).
114+
115+
## Testing
116+
117+
To mock the package's methods and components using the default mock configuration provided, follow these steps:
118+
119+
- Create a file named `@mhpdev/react-native-haptics.ts` inside your `__mocks__` directory.
120+
121+
- Copy the following code into that file:
122+
123+
```js
124+
jest.mock('@mhpdev/react-native-haptics', () =>
125+
require('@mhpdev/react-native-haptics/jest'),
126+
);
127+
```
14128

15129
## Contributing
16130

17-
See the [contributing guide](./docs/CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.
131+
See the [contributing guide](./CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.
18132

19133
## License
20134

‎docs/USAGE.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# React Native Haptics Usage Guide
2+
3+
- [React Native Haptics Usage Guide](#react-native-haptics-usage-guide)
4+
- [Installation](#installation)
5+
- [Bare React Native](#bare-react-native)
6+
- [Expo](#expo)
7+
- [API Overview](#api-overview)
8+
- [**impact**](#impact)
9+
- [**notification**](#notification)
10+
- [**selection**](#selection)
11+
- [**androidHaptics**](#androidhaptics)
12+
- [Example Application](#example-application)
13+
14+
---
15+
16+
## Installation
17+
18+
### Bare React Native
19+
20+
Install the package using either npm or Yarn:
21+
22+
```sh
23+
npm install @mhpdev/react-native-haptics
24+
```
25+
26+
Or with Yarn:
27+
28+
```sh
29+
yarn add @mhpdev/react-native-haptics
30+
```
31+
32+
For iOS, navigate to the ios directory and install the pods:
33+
34+
```sh
35+
cd ios && pod install
36+
```
37+
38+
### Expo
39+
40+
For Expo projects, follow these steps:
41+
42+
1. Install the package:
43+
44+
```sh
45+
npx expo install @mhpdev/react-native-haptics
46+
```
47+
48+
2. Since it is not supported on Expo Go, run:
49+
50+
```sh
51+
npx expo prebuild
52+
```
53+
54+
---
55+
56+
## API Overview
57+
58+
The library exports a default `Haptics` object that provides methods for triggering haptic feedback.
59+
60+
```tsx
61+
import Haptics from '@mhpdev/react-native-haptics';
62+
```
63+
64+
---
65+
66+
### **impact**
67+
68+
Triggers an impact haptic feedback. This corresponds to `UIImpactFeedbackGenerator` on iOS. On Android, it simulates the equivalent vibration effect.
69+
70+
**API Definition:**
71+
72+
```ts
73+
Haptics.impact(style: ImpactFeedback): Promise<void>
74+
```
75+
76+
**ImpactFeedback Type:**
77+
78+
- `light`: A collision between small, light user interface elements.
79+
- `medium`: A collision between moderately sized user interface elements.
80+
- `heavy`: A collision between large, heavy user interface elements.
81+
- `soft`: A collision between user interface elements that are soft, with a large amount of compression or elasticity. (iOS 13.0+)
82+
- `rigid`: A collision between user interface elements that are rigid, with a small amount of compression or elasticity. (iOS 13.0+)
83+
84+
**Example Usage:**
85+
86+
```ts
87+
import {ImpactFeedback} from '@mhpdev/react-native-haptics';
88+
89+
// Trigger a heavy impact
90+
Haptics.impact('heavy');
91+
92+
// Trigger a light impact
93+
Haptics.impact('light');
94+
```
95+
96+
---
97+
98+
### **notification**
99+
100+
Triggers a notification haptic feedback to communicate success, warning, or error. This corresponds to `UINotificationFeedbackGenerator` on iOS. On Android, it simulates the equivalent vibration effect.
101+
102+
**API Definition:**
103+
104+
```ts
105+
Haptics.notification(type: NotificationFeedback): Promise<void>
106+
```
107+
108+
**NotificationFeedback Type:**
109+
110+
- `success`: Indicates that a task or action has completed successfully.
111+
- `warning`: Indicates that a task or action has produced a warning.
112+
- `error`: Indicates that a task or action has failed.
113+
114+
**Example Usage:**
115+
116+
```ts
117+
import {NotificationFeedback} from '@mhpdev/react-native-haptics';
118+
119+
// Trigger a success notification
120+
Haptics.notification('success');
121+
122+
// Trigger an error notification
123+
Haptics.notification('error');
124+
```
125+
126+
---
127+
128+
### **selection**
129+
130+
Triggers a haptic feedback to indicate a selection change. This corresponds to `UISelectionFeedbackGenerator` on iOS. On Android, it uses `HapticFeedbackConstants.VIRTUAL_KEY`.
131+
132+
**API Definition:**
133+
134+
```ts
135+
Haptics.selection(): Promise<void>
136+
```
137+
138+
**Example Usage:**
139+
140+
```ts
141+
// Trigger a selection change haptic
142+
Haptics.selection();
143+
```
144+
145+
---
146+
147+
### **androidHaptics**
148+
149+
Triggers a platform-specific haptic feedback on Android. This method is a no-op on iOS.
150+
151+
> **Note:** Availability of each feedback type varies by Android SDK version. If a requested type is unsupported on the device, it safely falls back to `virtual-key`.
152+
153+
**API Definition:**
154+
155+
```ts
156+
Haptics.androidHaptics(type: AndroidHapticsFeedback): Promise<void>
157+
```
158+
159+
**AndroidHapticsFeedback Type:**
160+
161+
| Type | Description | Required API |
162+
| :----------------------------- | :--------------------------------------------------------------- | :----------- |
163+
| `clock-tick` | Feedback for a clock tick, e.g., while setting the time. | - |
164+
| `confirm` | Confirms a user's action. | 30+ |
165+
| `context-click` | Feedback for a context-click or right-click. | 23+ |
166+
| `drag-start` | Indicates the start of a drag action. | 34+ |
167+
| `gesture-end` | Indicates the end of a gesture. | 30+ |
168+
| `gesture-start` | Indicates the start of a gesture. | 30+ |
169+
| `gesture-threshold-activate` | Indicates the activation of a gesture threshold. | 34+ |
170+
| `gesture-threshold-deactivate` | Indicates the deactivation of a gesture threshold. | 34+ |
171+
| `keyboard-press` | Feedback for pressing a key on a soft keyboard. | 27+ |
172+
| `keyboard-release` | Feedback for releasing a key on a soft keyboard. | 27+ |
173+
| `keyboard-tap` | Feedback for a tap on a soft keyboard key. | - |
174+
| `long-press` | Feedback for a long press on an object. | - |
175+
| `no-haptics` | Explicitly specifies that no haptic feedback should be provided. | 34+ |
176+
| `reject` | Rejects a user's action. | 30+ |
177+
| `segment-frequent-tick` | A frequent tick in a segmented control. | 34+ |
178+
| `segment-tick` | A tick in a segmented control. | 34+ |
179+
| `text-handle-move` | Feedback for moving a text selection handle. | 27+ |
180+
| `toggle-off` | Indicates a toggle has been turned off. | 34+ |
181+
| `toggle-on` | Indicates a toggle has been turned on. | 34+ |
182+
| `virtual-key` | Feedback for a virtual key press. | - |
183+
| `virtual-key-release` | Feedback for a virtual key release. | 27+ |
184+
185+
**Example Usage:**
186+
187+
```ts
188+
import {AndroidHapticsFeedback} from '@mhpdev/react-native-haptics';
189+
190+
// Trigger a long press haptic on Android
191+
Haptics.androidHaptics('long-press');
192+
193+
// Trigger a confirm haptic on Android
194+
Haptics.androidHaptics('confirm');
195+
```
196+
197+
---
198+
199+
## Example Application
200+
201+
Check out the [example project](../example/).

0 commit comments

Comments
 (0)