expo-image-viewer

Expo Image Viewer

‼️ Do not use in production yet. See prerequisites below. ‼️

This is a simple image viewer built with React Native Reanimated and React Native Gesture Handler. Images use Expo Image, which is highly performant and allows for the prefetching of images to display in the image viewer.

This package is fully compatible with Expo Go.

Prerequisites

• Expo SDK 49
• Expo Image - Currently this package uses an unreleased version of Expo Image while waiting for Expo to publish changes fixing a memory leak while scaling images.
• Expo Haptics
• Reanimated 3.3.0+
• React Native Gesture Handler 2.12.0+

Installation

yarn add expo-image-viewer

Usage

First, you will want to wrap your app inside a <GestureHandlerRootView> component. You should place this somewhere near the root of your app, such as in your App.tsx file.

import { GestureHandlerRootView } from 'react-native-gesture-handler';

export default function App() {
    return (
        <GestureHandlerRootView>
          <App />
        </GestureHandlerRootView>
    );
}

Next, you should additionally wrap your app inside of ImageViewerProvider.

import { ImageViewerProvider } from 'expo-image-viewer';

export default function App() {
    return (
        <GestureHandlerRootView>
          <ImageViewerProvider>
            <App />
          </ImageViewerProvider>
        </GestureHandlerRootView>
    );
}

Finally, you can use the ViewerImage component to display images in the image viewer.

import { ViewerImage } from 'expo-image-viewer';

export default function MyScreen() {
    return (
        <View style={{flex: 1}}>
            <ViewerImage
              source="https://images.unsplash.com/photo-1634179127707-4b8b9b5b2b0b?ixid=MnwxMjA3fDB8MHxlZGl0b3JpYWwtZmVlZHwzNnx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=500&q=60"
              initialDimensions={{
                height: 500,
                width: 500
              }}
              heightModifier={0.6}
              title="My Image"
            />
        </View>
    );
}

Whenever the ViewerImage component is pressed, the image viewer will open and display the image.

Props

ImageViewerProvider

Prop	Type	Description
children	React.ReactNode	The children to render inside of the provider.
options	ImageViewerOptions	The options to use for the image viewer.

ImageViewerOptions

Option	Required	Default	Type	Description
showHeader	No	true	boolean	Show the header.
showFooter	No	true	boolean	Show the footer.
showCloseButton	No	true	boolean	Show the close button.
preloadImages	No	true	boolean	When supplying an array of images, the each of the images will be preloaded. See more below.
heightModifier	No	1	number	A number between 0 and 1 that defines the modifier for the height. Useful if displaying images in a feed and want to maintain aspect ratio without having images disappear off the screen
swipeToDismiss	No	true	boolean	Whether to allow the user to swipe to dismiss the viewer.
FooterComponent	No	null	() => React.JSX.Element	A footer component to render. Background color should be transparent. The animated displaying/hideing of this will be handled for you.
ActivityIndicatorComponent	No	null	() => React.JSX.Element	A component to render for an activity indicator. It will automatically be positioned in the center of your initial dimensions.

ViewerImage

Prop	Required	Default	Type	Description
source	Yes	NA	string string[]	The source of the image.
contentFit	No	contain	ImageContentFit (see Expo Image)	How the image should be displayed within its bounds.
title	No	NA	string	The title of the image. Will be shown in the image viewer if the header is enabled.
heightModifier	No	NA	number	Overrides the heightModifier provided to the ImageViewerProvider.
blurRadius	No	NA	number	A blur radius to apply to the image (see Expo Image)
recyclingKey	No	NA	string	A recycling key to be used with a recycler view such as FlashList (see Expo Image)
initialDimensions	Yes	{height: 300, width: 300}`	`{height: number, width: number}	A height and width that should be the default for the image.
onLoad	No	NA	(e: ImageLoadEventData) => void	A function to run when the onLoad event is called.
onPress	No	NA	() => unknown	A function to run when the image is pressed
useInitialDimensions	No	false	boolean	Whether to keep the initial dimensions of the image even after the load.
showActivityIndicator	No	true	boolean	Whether to show the activity indicator while the image is loading. You can supply your own component to display, otherwise will use the React Native ActivityIndicator component.
activityIndicatorSize	No	large	small | large	Size of the activity indicator
activityIndicatorColor	No	white	ColorValue	Color of the activity indicator

useImageViewer()

If you need to get any of the current values (such as the current index of the displayed image or the image source) or if you wish to create your own implementation of ViewerImage, you can use the useImageViewer hook.

Property	Type	Description
options	ImageViewerOptions	The options passed to the ImageViewerProvider. These are only provided for reference. They should be changed in the ImageViewerProvider.
props	IImageViewerState	The current state of the image viewer. See below.
dispatch	(action: React.Dispatch<IAction>) => void	A dispatch function to dispatch actions to the image viewer. See below.

IImageViewerState

Property	Type	Description
params	IImageViewerParams	The params passed to the image viewer. See below.
visible	boolean	Whether the image viewer is visible.
viewerOpacity	Animated.SharedValue<number>	The opacity of the image viewer. Do not change this unless you are creating your own implementation.
viewerRef	React.RefObject<View> | null	The ref of the image's container. For example, the pressable that you are wrapping your <Image>in. Used to perform a measurement of the view when opening. Do not change this value unless you are creating your own implementation.

IImageViewerParams

Property	Type	Description
source	string string[]	The source of the image.
title	string	The title of the image.
index	number	The index of the image being displayed in the viewer.

IAction

IAction is an object that takes a type and a payload. These are the possible actions.

Action	Payload Type	Description
setState	IImageViewerState	Sets the state of the image viewer.
setVisible	boolean	Sets the visibility of the image viewer.
setIndex	number	Sets the index of the image to display in the viewer.