Image viewer

Installation

$ npx shadcn@latest add https://goodui.dev/native/r/image-viewer.json

Then run npx expo install --fix so react-native-gesture-handler, react-native-reanimated, react-native-svg match your Expo SDK. Files land in components/goodui-native/image-viewer.

Usage

import { View } from "react-native";
import { ImageThumbnail, ImageViewer, type ViewerImage } from "@/components/goodui-native/image-viewer/image-viewer";

const photos: ViewerImage[] = [
  { source: "https://example.com/1.jpg", width: 1200, height: 800, alt: "Living room", caption: "Living room, 24 m²" },
  { source: "https://example.com/2.jpg", width: 800, height: 1200, alt: "Kitchen" },
];

export function Gallery() {
  return (
    <ImageViewer images={photos}>
      <View style={{ flexDirection: "row", gap: 4 }}>
        {photos.map((_, i) => (
          <ImageThumbnail key={i} index={i} style={{ flex: 1, aspectRatio: 1 }} />
        ))}
      </View>
    </ImageViewer>
  );
}

When to use

Examples

function FloorPlanButton() {
  const viewer = useImageViewer();
  return <Button onPress={() => viewer.open(0)}>View floor plan</Button>;
}

<ImageViewer images={[plan]}>
  <FloorPlanButton />
</ImageViewer>

<ImageViewer images={photos} onIndexChange={setIndex} onOpenChange={(open, i) => track(open ? "open" : "close", i)}>

API reference

Motion and haptics

• •Open: the frame travels from the thumbnail's box and corner radius to the image's fitted box on the smooth spring; the image covers the frame, so the thumbnail's crop opens up exactly as it lands. The backdrop fades in.
• •Pinch zooms around the fingers (resisting past 1 and maxZoom, then settling back); double-tap zooms to doubleTapZoom at the tap point or back to fit.
• •When zoomed the image pans 1:1, resists past its edges and keeps its momentum on release (decay, clamped to the edges).
• •At fit, a sideways drag moves between images 1:1 and settles on the smooth spring with the release velocity; the first and last images resist.
• •A vertical drag follows the finger, shrinks the image a little and fades the backdrop; release past 110 pt (or a fast flick) sends it back into the thumbnail of the image on screen, otherwise it springs back.
• •Tap toggles the controls. A size that arrives late (no width and height given) springs the frame to the right shape.
• •Reduced motion: opening and closing fade instead of flying, and page changes from the keyboard or buttons jump. Pinch, pan and drags still follow the finger because they are direct manipulation.

• •Haptic: tap on the close button (IconButton); zooming, paging and dismissing are direct manipulation and stay silent

• •All gestures and the open and close flight are worklets on the UI thread; React re-renders only when the image index changes or the controls toggle.
• •Only the current image and its two neighbours are mounted. Image sizes are read once per image (Image.getSize) when width and height are not given.

Accessibility

• •Each ImageThumbnail is a button labelled with the image's alt text and the hint 'Opens the image'.
• •The viewer is modal. The image is one element labelled 'alt, 2 of 5' with actions Next image, Previous image and Close; the iOS escape gesture and Android's back button close it.
• •Moving to another image announces 'Image 3 of 5'; opening announces the position too.
• •A close button sits at the top with a '2 of 5' counter; on the web there are also previous and next buttons, arrow keys move between images and Escape closes.
• •Captions show in a quiet card at the bottom and are plain text.

Notes for AI

Related