https://github.com/pavelbabenko/react-native-awesome-gallery
Performant, native-like, and well-customizable gallery for React Native.
https://github.com/pavelbabenko/react-native-awesome-gallery
List: react-native-awesome-gallery
android expo expo-sdk-40 gallery image-gallery image-viewer ios lightbox pinch-to-zoom react react-native reanimated2
Last synced: about 2 months ago
JSON representation
Performant, native-like, and well-customizable gallery for React Native.
- Host: GitHub
- URL: https://github.com/pavelbabenko/react-native-awesome-gallery
- Owner: pavelbabenko
- License: mit
- Created: 2021-03-04T12:14:53.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2024-09-28T11:54:39.000Z (over 1 year ago)
- Last Synced: 2025-05-12T00:01:49.887Z (about 1 year ago)
- Topics: android, expo, expo-sdk-40, gallery, image-gallery, image-viewer, ios, lightbox, pinch-to-zoom, react, react-native, reanimated2
- Language: TypeScript
- Homepage:
- Size: 64 MB
- Stars: 553
- Watchers: 5
- Forks: 59
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://badge.fury.io/js/react-native-awesome-gallery)
## Support
If you love using React Native Awesome Gallery and would like to show your appreciation, you can support the project by buying me a coffee. Your support helps me keep the project alive and continuously improving. Every little bit counts!
[](https://www.buymeacoffee.com/pavelbabenko)
React Native Awesome Gallery
Photos gallery powered by Reanimated v3 and react-native-gesture-handler
Basic usage
With toolbar
Loop
## Supported features
- Zoom to scale
- Double tap to scale
- Native iOS feeling (rubber effect, decay animation on pan gesture)
- RTL support
- Fully customizable
- Both orientations (portrait + landscape)
- Infinite list
- Supports both iOS and Android.
## Installation
> **_Note:_** Starting from v0.3.6 using Reanimated v3 is required
First you have to follow installation instructions of [Reanimated v3](https://docs.swmansion.com/react-native-reanimated/) and [react-native-gesture-handler](https://docs.swmansion.com/react-native-gesture-handler/)
```sh
yarn add react-native-awesome-gallery
```
Expo is supported since SDK 40. More information [here](https://docs.expo.io/versions/latest/sdk/reanimated/)
## Usage
Check out an [example folder](./example) for example with Expo Image
```js
import Gallery from 'react-native-awesome-gallery';
// ...
const images = ['https://image1', 'https://image2'];
return (
{
console.log(newIndex);
}}
/>
);
```
## Props
| Prop | Description | Type | Default |
|----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
| data | Array of items to render | `T[]` | `undefined` |
| renderItem? | Callback func which can be used to render custom image component, e.g `FastImage`. NOTE: You have to call `setImageDimensions({width, height})` parameter after image is loaded | `(renderItemInfo: {item: T, index: number, setImageDimensions: Function}) => React.ReactElement` | `undefined` |
| keyExtractor? | Callback func which provides unique keys for items | `(item: T, index: number) => string or number` | Takes `id` or `key` or `_id` from `Item`, otherwise puts `Item` as key |
| initialIndex? | The initial image index | `number` | `0` |
| onIndexChange? | Is called when index of active item is changed | `(newIndex: number) => void` | `undefined` |
| numToRender? | Amount of items rendered in gallery simultaneously | `number` | `5` |
| emptySpaceWidth? | Width of empty space between items | `number` | `30` |
| doubleTapScale? | Image scale when double tap is fired | `number` | `3` |
| doubleTapInterval? | Time in milliseconds between single and double tap events | `number` | `500` |
| maxScale? | Maximum scale user can set with gesture | `number` | `6` |
| pinchEnabled? | Is pinch gesture enabled | `boolean` | `true` |
| swipeEnabled? | Is pan gesture enabled | `boolean` | `true` |
| doubleTapEnabled? | Is double tap enabled | `boolean` | `true` |
| disableTransitionOnScaledImage? | Disables transition to next/previous image when scale > 1 | `boolean` | `false` |
| hideAdjacentImagesOnScaledImage? | Hides next and previous images when scale > 1 | `boolean` | `false` |
| disableVerticalSwipe? | Disables vertical swipe when scale == 1 | `boolean` | `false` |
| disableSwipeUp? | Disables swipe up when scale == 1 | `boolean` | `false` |
| loop? | Allows user to swipe infinitely. Works when `data.length > 1` | `boolean` | `false` |
| onScaleChange? | Is called when scale is changed | `(scale: number) => void` | `undefined` |
| onScaleChangeRange? | Shows range of scale in which `onScaleChange` is called | `{start: number, end: number}` | `undefined` |
| containerDimensions? | Dimensions object for the View that wraps gallery. | `{width: number, height: number}` | value returned from `useWindowDimensions()` hook. |
| style? | Style of container | `ViewStyle` | `undefined` |
## Events
| Prop | Description | Type |
|------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|------------|
| onSwipeToClose() | Fired when user swiped to top/bottom | `Function` |
| onTranslationYChange(translationY: number, shouldClose: boolean) | `'worklet';` Fired when user is swiping vertically to close the gallery | `Worklet` |
| onTap() | Fired when user tap on image | `Function` |
| onDoubleTap(toScale: number) | Fired when user double tap on image | `Function` |
| onLongPress() | Fired when long press is detected | `Function` |
| onScaleStart(scale: number) | Fired when pinch gesture starts | `Function` |
| onScaleEnd(scale: number) | Fired when pinch gesture ends. Use case: add haptic feedback when user finished gesture with `scale > maxScale` or `scale < 1` | `Function` |
| onPanStart() | Fired when pan gesture starts | `Function` |
## Methods
```js
import Gallery, { GalleryRef } from 'react-native-awesome-gallery';
// ...
const ref = useRef(null);
```
| Prop | Description | Type |
|----------|---------------------------|--------------------------------------------------|
| setIndex | Sets active index | `(newIndex: number, animated?: boolean) => void` |
| reset | Resets scale, translation | `(animated?: boolean) => void` |
## License
MIT