Skip to content

Commit c8ea44b

Browse files
saseungminsaseungmin
authored
docs: create usage documentation (#59)
1 parent 373dac7 commit c8ea44b

23 files changed

+1368
-2
lines changed

‎docs/docs/en/guide/_meta.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,10 @@
33
"type": "dir",
44
"name": "getting-started",
55
"label": "Getting Started"
6+
},
7+
{
8+
"type": "dir",
9+
"name": "usage",
10+
"label": "Usage"
611
}
712
]

‎docs/docs/en/guide/getting-started/quick-start.mdx‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
import { PackageManagerTabs } from '@theme';
2+
13
# Quick Start
24

35
## Examples & Demo
@@ -8,6 +10,15 @@
810
<img src="https://raw.githubusercontent.com/saseungmin/react-native-gesture-image-viewer/main/assets/example.gif" width="600" alt="Demo of react-native-gesture-image-viewer gestures" />
911
</div>
1012

13+
## Installation
14+
15+
:::warning Important
16+
`react-native-gesture-image-viewer` is a high-performance viewer library built on [`react-native-reanimated`](https://www.npmjs.com/package/react-native-reanimated) and [`react-native-gesture-handler`](https://www.npmjs.com/package/react-native-gesture-handler).
17+
Therefore, you **must install** React Native Reanimated and Gesture Handler before using this library. **If you haven't set it up yet, please refer to the [installation guide](/guide/getting-started/installation.html).**
18+
:::
19+
20+
<PackageManagerTabs command="install react-native-gesture-image-viewer" />
21+
1122
## Basic Usage
1223

1324
`react-native-gesture-image-viewer` is a library focused purely on gesture interactions for complete customization.

‎docs/docs/en/guide/usage/_meta.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
[
2+
"basic-usage",
3+
"gesture-features",
4+
"custom-components",
5+
"programmatic-control",
6+
"handling-viewer-events",
7+
"style-customization",
8+
"multi-instance-management",
9+
"gesture-viewer-props"
10+
]

‎docs/docs/en/guide/usage/basic-usage.mdx‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Basic Usage
2+
3+
## GestureViewer
4+
5+
```tsx
6+
import { FlatList, Image, Modal } from 'react-native';
7+
import { GestureViewer } from 'react-native-gesture-image-viewer';
8+
9+
function App() {
10+
const images = [...];
11+
const [visible, setVisible] = useState(false);
12+
13+
const renderImage = useCallback((imageUrl: string) => {
14+
return <Image source={{ uri: imageUrl }} style={{ width: '100%', height: '100%' }} resizeMode="contain" />;
15+
}, []);
16+
17+
return (
18+
<Modal visible={visible} onRequestClose={() => setVisible(false)}>
19+
<GestureViewer
20+
data={images}
21+
renderItem={renderImage}
22+
ListComponent={FlatList}
23+
onDismiss={() => setVisible(false)}
24+
/>
25+
</Modal>
26+
);
27+
}
28+
```
29+
30+
## [useGestureViewerController](/guide/usage/programmatic-control.html)
31+
32+
You can programmatically control the `GestureViewer` using the `useGestureViewerController` hook.
33+
34+
```tsx
35+
import { GestureViewer, useGestureViewerController } from 'react-native-gesture-image-viewer';
36+
37+
function App() {
38+
const {
39+
goToIndex,
40+
goToPrevious,
41+
goToNext,
42+
currentIndex,
43+
totalCount,
44+
zoomIn,
45+
zoomOut,
46+
resetZoom,
47+
rotate
48+
} = useGestureViewerController();
49+
50+
return (
51+
<View>
52+
<GestureViewer
53+
data={images}
54+
renderItem={renderImage}
55+
/>
56+
{/* Navigation Controls */}
57+
<View>
58+
<Feather.Button name="chevron-left" onPress={goToPrevious} />
59+
<Button title="Jump to index 2" onPress={() => goToIndex(2)} />
60+
<Feather.Button name="chevron-right" onPress={goToNext} />
61+
<Text>{`${currentIndex + 1} / ${totalCount}`}</Text>
62+
</View>
63+
</View>
64+
);
65+
}
66+
```
67+
68+
## [useGestureViewerEvent](/guide/usage/handling-viewer-events.html)
69+
70+
You can subscribe to specific events from `GestureViewer` using the `useGestureViewerEvent` hook. This allows you to respond to real-time gesture changes like zoom and rotation.
71+
72+
```tsx
73+
import { GestureViewer, useGestureViewerEvent } from 'react-native-gesture-image-viewer';
74+
75+
function App() {
76+
useGestureViewerEvent('zoomChange', (data) => {
77+
console.log(`Zoom changed from ${data.previousScale} to ${data.scale}`);
78+
});
79+
80+
useGestureViewerEvent('rotationChange', (data) => {
81+
console.log(`Rotation changed from ${data.previousRotation}° to ${data.rotation}°`);
82+
});
83+
84+
return (
85+
<GestureViewer
86+
data={images}
87+
renderItem={renderImage}
88+
/>
89+
);
90+
}
91+
```

‎docs/docs/en/guide/usage/custom-components.mdx‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
import { Tab, Tabs } from '@rspress/core/theme';
2+
3+
# Custom Components
4+
5+
`react-native-gesture-image-viewer` offers powerful complete component customization. You can create gesture-supported items with not only images but any component you want.
6+
7+
## Modal Components
8+
9+
You can create a viewer using any `Modal` of your choice as shown below:
10+
11+
<Tabs>
12+
<Tab label="Use Modal">
13+
```tsx
14+
import { FlatList, Image, Modal } from 'react-native';
15+
import { GestureViewer } from 'react-native-gesture-image-viewer';
16+
17+
function App() {
18+
const images = [...];
19+
const [visible, setVisible] = useState(false);
20+
21+
return (
22+
<Modal visible={visible} onRequestClose={() => setVisible(false)}>
23+
<GestureViewer
24+
data={images}
25+
renderItem={renderImage}
26+
ListComponent={FlatList}
27+
onDismiss={() => setVisible(false)}
28+
/>
29+
</Modal>
30+
);
31+
}
32+
```
33+
</Tab>
34+
<Tab label="Use React Native Modal">
35+
```tsx
36+
import { FlatList, Image } from 'react-native';
37+
import Modal from 'react-native-modal';
38+
import { GestureViewer } from 'react-native-gesture-image-viewer';
39+
40+
function App() {
41+
const images = [...];
42+
const [visible, setVisible] = useState(false);
43+
44+
return (
45+
<Modal
46+
isVisible={visible}
47+
onBackButtonPress={() => setVisible(false)}
48+
onBackdropPress={() => setVisible(false)}
49+
hasBackdrop={false}
50+
style={styles.modal}
51+
useNativeDriver={true}
52+
hideModalContentWhileAnimating={true}
53+
animationInTiming={300}
54+
animationOutTiming={300}
55+
>
56+
<GestureViewer
57+
data={images}
58+
renderItem={renderImage}
59+
ListComponent={FlatList}
60+
onDismiss={() => setVisible(false)}
61+
/>
62+
</Modal>
63+
);
64+
}
65+
```
66+
</Tab>
67+
</Tabs>
68+
69+
## List Components
70+
71+
Support for any list component like `ScrollView`, `FlatList`, [`FlashList`](https://shopify.github.io/flash-list/) through the `ListComponent` prop.
72+
The `listProps` provides **type inference based on the selected list component**, ensuring accurate autocompletion and type safety in your IDE.
73+
74+
```tsx
75+
import { FlashList } from '@shopify/flash-list';
76+
77+
function App() {
78+
return (
79+
<GestureViewer
80+
data={images}
81+
ListComponent={FlashList}
82+
listProps={{
83+
// ✅ FlashList props autocompletion
84+
}}
85+
/>
86+
);
87+
}
88+
```
89+
90+
## Content Components
91+
92+
You can inject various types of content components like [`expo-image`](https://docs.expo.dev/versions/latest/sdk/image/), [`FastImage`](https://github.com/DylanVann/react-native-fast-image), etc., through the `renderItem` prop to use gestures.
93+
94+
```tsx
95+
import { GestureViewer } from 'react-native-gesture-image-viewer';
96+
import { Image } from 'expo-image';
97+
98+
function App() {
99+
const renderImage = useCallback((imageUrl: string) => {
100+
return <Image source={{ uri: imageUrl }} style={{ width: '100%', height: '100%' }} contentFit="contain" />;
101+
}, []);
102+
103+
return (
104+
<GestureViewer
105+
data={images}
106+
renderItem={renderImage}
107+
/>
108+
);
109+
}
110+
```

‎docs/docs/en/guide/usage/gesture-features.mdx‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Gesture Features
2+
3+
`react-native-gesture-image-viewer` supports various gestures essential for viewers. Please refer to the examples below for default gesture actions.
4+
5+
```tsx
6+
import { GestureViewer } from 'react-native-gesture-image-viewer';
7+
8+
function App() {
9+
return (
10+
<GestureViewer
11+
data={images}
12+
renderItem={renderImage}
13+
enableDismissGesture={true}
14+
enableSwipeGesture={true}
15+
enableZoomGesture={true}
16+
enableDoubleTapGesture={true}
17+
enableZoomPanGesture={true}
18+
/>
19+
)
20+
}
21+
```
22+
23+
## Props
24+
25+
### `enableDismissGesture` (default: `true`)
26+
27+
Calls `onDismiss` function when swiping down. Useful for closing modals with downward swipe gestures.
28+
29+
### `enableSwipeGesture` (default: `true`)
30+
31+
Controls left/right swipe gestures. When `false`, horizontal gestures are disabled.
32+
33+
### `enableZoomGesture` (default: `true`)
34+
35+
Controls two-finger pinch gestures with focal point zooming. When `false`, pinch zoom is disabled. Zoom centers on the point between your two fingers for intuitive scaling.
36+
37+
### `enableDoubleTapGesture` (default: `true`)
38+
39+
Controls double-tap zoom gestures with precision targeting. When `false`, double-tap zoom is disabled. Zoom centers exactly on the tapped location.
40+
41+
### `enableZoomPanGesture` (default: `true`)
42+
43+
Enables panning when zoomed in with automatic boundary detection. When `false`, movement is disabled during zoom. Prevents content from moving outside visible screen area.

0 commit comments

Comments
 (0)