1.26.4 • Published 1 year ago

react-native-gallery-swiper v1.26.4

Weekly downloads
2,295
License
ISC
Repository
-
Last release
1 year ago

An easy and simple to use React Native component to render a high performant and easily customizable image gallery with common gestures like pan, pinch and double tap. Supporting both iOS and Android.

Learn more about the installation and how to use this package in the updated documentation page.

  • Supports smart rendering for large lists or small.
  • Scroll loading and supporting onEndReached.
  • Includes guestures and important event listeners for pan, pinch, single tap and double tap.
  • Includes zoom mode.
  • Easily customizable.
  • Intelligent scrolling detection to cushion rough swipe guestures.
  • Supports both iOS and Android.

Built and similar to react-native-gallery.



:open_file_folder: Index

1. Install

2. Usage Example

3. Performance Optimization List Example

4. API

5. :books: Props

6. :books: Methods

7. Example Project

9. License


:gem: Install

Type in the following to the command line to install the dependency.

$ npm install --save react-native-gallery-swiper

or

$ yarn add react-native-gallery-swiper

:tada: Usage Example

Add an import to the top of the file. At minimal, declare the GallerySwiper component in the render() method providing an array of data for the images prop.

:information_source: Local images must have a defined dimensions field with width and height or just height and width.

import GallerySwiper from "react-native-gallery-swiper";

//...
render() {
    return (
        <GallerySwiper
            images={[
                // Version *1.1.0 update (or greater versions): 
                // Can be used with different image object fieldnames.
                // Ex. source, source.uri, uri, URI, url, URL
                { uri: "https://luehangs.site/pic-chat-app-images/beautiful-blond-blonde-hair-478544.jpg" },
                { source: require("yourApp/image.png"),
                    // IMPORTANT: It is REQUIRED for LOCAL IMAGES
                    // to include a dimensions field with the
                    // actual width and height of the image or
                    // it will throw an error.
                    dimensions: { width: 1080, height: 1920 } },
                { source: require("yourApp/image.png"),
                    // Version *1.5.0 update (or greater versions):
                    // An alternative to the dimensions field.
                    // This will also be acceptable.
                    width: 1080,
                    height: 1920 },
                { source: { uri: "https://luehangs.site/pic-chat-app-images/beautiful-beautiful-women-beauty-40901.jpg" } },
                { uri: "https://luehangs.site/pic-chat-app-images/animals-avian-beach-760984.jpg" },
                { URI: "https://luehangs.site/pic-chat-app-images/beautiful-blond-fishnet-stockings-48134.jpg" },
                { url: "https://luehangs.site/pic-chat-app-images/beautiful-beautiful-woman-beauty-9763.jpg" },
                { URL: "https://luehangs.site/pic-chat-app-images/attractive-balance-beautiful-186263.jpg" },
            ]}
            // Version *1.15.0 update
            // onEndReached={() => {
            //     // add more images when scroll reaches end
            // }}
        />
    );
}
//...

:watch: Performance Optimization List Example

import GallerySwiper from "react-native-gallery-swiper";

//...
render() {
    return (
        <GallerySwiper
            images={[
                { uri: "https://luehangs.site/pic-chat-app-images/beautiful-blond-blonde-hair-478544.jpg",
                    // Optional: Adding a dimensions or height and
                    // width field with the actual width and height
                    // for REMOTE IMAGES will help improve performance.
                    dimensions: { width: 1080, height: 1920 } },
                { uri: "https://luehangs.site/pic-chat-app-images/beautiful-beautiful-women-beauty-40901.jpg",
                    dimensions: { width: 1080, height: 1920 } },
                { uri: "https://luehangs.site/pic-chat-app-images/animals-avian-beach-760984.jpg",
                    dimensions: { width: 1080, height: 1920 } },
                { uri: "https://luehangs.site/pic-chat-app-images/beautiful-blond-fishnet-stockings-48134.jpg",
                    dimensions: { width: 1080, height: 1920 } },
                { uri: "https://luehangs.site/pic-chat-app-images/beautiful-beautiful-woman-beauty-9763.jpg",
                    dimensions: { width: 1080, height: 1920 } },
                { uri: "https://luehangs.site/pic-chat-app-images/attractive-balance-beautiful-186263.jpg",
                    dimensions: { width: 1920, height: 1080 } },
                // ...
                // ...
                // ...
            ]}
            // Version *1.15.0 update
            // onEndReached={() => {
            //     // add more images when scroll reaches end
            // }}
            // Change this to render how many items before it.
            initialNumToRender={2}
            // Turning this off will make it feel faster
            // and prevent the scroller to slow down
            // on fast swipes.
            sensitiveScroll={false}
        />
    );
}
//...

:nut_and_bolt: API

<GallerySwiper /> component accepts the following props...

:books: Props

PropsDescriptionTypeDefault
imagesAn array of objects. source, source.uri, uri, URI, url or URL is a required field (if multiple similar fields in an image object, priority will go from start source to last URL). EX. [{ source: require("yourApp/image.png"), dimensions: { width: 1080, height: 1920 } }, { uri: "https://luehangs.site/pic-chat-app-images/animals-avian-beach-760984.jpg", dimensions: { width: 1080, height: 1920 } }, { uri: "https://luehangs.site/pic-chat-app-images/beautiful-blond-blonde-hair-478544.jpg"}]ArrayRequired
styleStyling the gallery.object, Array{flex: 1, backgroundColor: "#000"}
initialPageIndex of image to be displayed first.number0
resizeModeThe mechanism that should be used to resize the image when the image's dimensions differ from the image view's dimensions. Expecting one of "contain", "cover", "stretch", "repeat", "center". Version *1.12.0 update.string"contain"
imageComponentCustom function to render your images. (imageProps: { imageLoaded: boolean, source: object, image: object, style: Array<object>, resizeMode: string, capInsets: object, onLoadStart: Function, onLoad: Function, ...extras }, imageDimensions: {width: number, height: number}, index: number) => React.Element index params included in Version *1.3.1 updateFunction<Image/> component
errorComponentCustom function to render the page of an image that couldn't be displayed.FunctionA <View/> with a stylized error
initialNumToRenderHow many items to render in the initial batch. Version *1.3.0 update.number7
flatListPropsProps to be passed to the underlying FlatList.object{windowSize: 3}
pageMarginBlank margin space to show between images.number0
sensitiveScrollDetect rough and fast swiping gestures in order to "cushion" or slow down a swipe at the end. Version *1.4.0 update.booleantrue
onPageSelectedExecuted with the index of page that has been selected. (index: number) => voidFunction
onPageScrollStateChangedCalled when page scrolling state has changed, see scroll state and events. (state: string) => voidFunction
onPageScrollScroll event, see scroll state and events. (event: { position: number, offset: number, fraction: number }) => voidFunction
scrollViewStyleCustom style for the FlatList component.object{}
onDoubleTapConfirmedExecuted after a double tap. (index: number) => void Version *1.8.0 updateFunction
onSingleTapConfirmedExecuted after a single tap. (index: number) => voidFunction
onLongPressExecuted after a long press. (gestureState: object, index: number) => void index params in Version *1.10.0 update.Function
onViewTransformedExecuted while being transformed in anyway (view transformer). (transform: { scale: number, translateX: number, translateY: number }, index: number) => void Version *1.16.0 update.Function
onPinchTransformingExecuted while pinching to transform view or zoom (view transformer). (transform: { scale: number, translateX: number, translateY: number }, index: number) => void Version *1.17.0 update.Function
onPinchStartReachedExecuted after scaling out or zooming out to initial size using the pinch gesture. (transform: { scale: number, translateX: number, translateY: number }, index: number) => void Version *1.18.0 update.Function
onPinchEndReachedExecuted after scaling in or zooming in to maxScale threshold using the pinch gesture. (transform: { scale: number, translateX: number, translateY: number }, index: number) => void Version *1.18.0 update.Function
onTransformGestureReleasedExecuted after a transform guesture released (view transformer). (transform: { scale: number, translateX: number, translateY: number }, index: number) => void Version *1.16.0 update.Function
onSwipeUpReleasedExecuted after releasing an upward swipe at a specific y translate threshold while not in zoom mode. (transform: { scale: number, translateX: number, translateY: number }, index: number) => void For custom precision swiping gestures, refer to the onTransformGestureReleased. Version *1.25.0 update.Function
onSwipeDownReleasedExecuted after releasing a downward swipe at a specific y translate threshold while not in zoom mode. (transform: { scale: number, translateX: number, translateY: number }, index: number) => void For custom precision swiping gestures, refer to the onTransformGestureReleased. Version *1.25.0 update.Function
onDoubleTapStartReachedExecuted after scaling out or zooming out using double tap. (transform: { scale: number, translateX: number, translateY: number }, index: number) => void Version *1.17.0 update.Function
onDoubleTapEndReachedExecuted after scaling in or zooming in using double tap. (transform: { scale: number, translateX: number, translateY: number }, index: number) => void Version *1.17.0 update.Function
onEndReachedCalled once when the page index gets within the onEndReachedThreshold of the images content. () => void Version *1.15.0 update.Function
onEndReachedThresholdHow far from the end (in units of visible length of the list) of the list of images must be from the end of the content to trigger the onEndReached callback. Thus a value of 0.5 will trigger onEndReached when the end of the content is within half the visible length of the images. Version *1.15.0 update.number0.5
enableScaleEnable or disable zoom and double tap zoom (view transformer). Version *1.9.0 update.booleantrue
maxScaleMax zoom (view transformer). Number greater than 1 will create a zoom. Default will only zoom for large images as tiny images will be pixelated if scaling occurs. Version *1.17.0 update.numberMath.max(imageWidth / viewWidth, imageHeight / viewHeight)
enableTranslateEnable or disable moving while in zoom (view transformer). Version *1.11.0 update.booleantrue
enableResistanceEnable or disable resistance over panning (view transformer). Version *1.14.0 update.booleantrue
resistantStrHorizontalResistant value for left and right panning (view transformer). (dx: number) => number Version *1.14.0 update.Function, number or string(dx) => (dx /= 3)
resistantStrVerticalResistant value for top and bottom panning (view transformer). (dy: number) => number Version *1.14.0 update.Function, number or string(dy) => (dy /= 3)
maxOverScrollDistanceA number used to determine final scroll position triggered by fling (view transformer). Version *1.16.0 update.number20
removeClippedSubviewsTo improve scroll performance for large lists. Version *1.4.1 update.booleantrue
refPageThe ref for the inner View page. Version *1.2.0 update.Function

:books: Methods

:small_blue_diamond: flingToPage(params)

Scrolls to the following index with input velocity.

Parameters:

NameTypeRequiredDescription
paramsobjectYESSee below.

Valid params keys are:

  • "index" (number) - Index of desired page. Required.
  • "velocityX" (boolean) - Speed intensity > 0.00. Required.

:small_blue_diamond: scrollToPage(params)

Scrolls to the following index with or without animation.

Parameters:

NameTypeRequiredDescription
paramsobjectYESSee below.

Valid params keys are:

  • "index" (number) - Index of desired page. Required.
  • "immediate" (boolean) - Animated transition or not. Defaults to false.

:clapper: Example Project

Perform steps 1-2 to run locally:

  1. Clone the Repo
  2. Install and Run

:small_blue_diamond: 1. Clone the Repo

Clone react-native-gallery-swiper locally. In a terminal, run:

$ git clone https://github.com/Luehang/react-native-gallery-swiper.git react-native-gallery-swiper

:small_blue_diamond: 2. Install and Run

$ cd react-native-gallery-swiper/example/

iOS - Mac - Install & Run

1. check out the code
2. npm install
3. npm run ios

Android - Mac - Install & Run

1. check out the code
2. npm install
3. emulator running in separate terminal
4. npm run android

:page_facing_up: License

ISC, as found in the LICENSE file.

1.26.4

1 year ago

1.26.3

1 year ago

1.26.2

1 year ago

1.26.1

1 year ago

1.26.0

1 year ago

1.25.3

2 years ago

1.25.2

2 years ago

1.25.1

2 years ago

1.25.0

2 years ago

1.24.4

2 years ago

1.24.3

2 years ago

1.24.2

2 years ago

1.24.1

2 years ago

1.24.0

2 years ago

1.23.1

2 years ago

1.23.0

2 years ago

1.22.2

2 years ago

1.22.1

2 years ago

1.22.0

2 years ago

1.21.0

2 years ago

1.20.3

2 years ago

1.20.2

2 years ago

1.20.1

3 years ago

1.20.0

3 years ago

1.19.0

3 years ago

1.18.0

3 years ago

1.17.0

3 years ago

1.16.0

3 years ago

1.15.0

3 years ago

1.14.0

3 years ago

1.13.0

3 years ago

1.12.0

3 years ago

1.11.0

3 years ago

1.10.0

3 years ago

1.9.0

3 years ago

1.8.0

3 years ago

1.7.1

3 years ago

1.7.0

3 years ago

1.6.2

3 years ago

1.6.1

3 years ago

1.6.0

3 years ago

1.5.2

3 years ago

1.5.1

3 years ago

1.5.0

3 years ago

1.4.2

3 years ago

1.4.0

3 years ago

1.3.2

3 years ago

1.3.1

3 years ago

1.3.0

3 years ago

1.2.0

3 years ago

1.1.15

3 years ago

1.1.14

3 years ago

1.1.13

3 years ago

1.1.11

3 years ago

1.1.10

3 years ago

1.1.7

3 years ago

1.1.6

3 years ago

1.1.5

3 years ago

1.1.4

3 years ago

1.1.3

3 years ago

1.1.2

3 years ago

1.1.1

3 years ago

1.1.0

3 years ago

1.0.5

3 years ago

1.0.4

3 years ago

1.0.3

3 years ago

1.0.2

3 years ago

1.0.1

3 years ago

1.0.0

3 years ago