# React Native Image Viewer & Lightbox

> A full-screen React Native image viewer for iOS, Android and the web with no native code: swipe between photos, pinch and double-tap to zoom, pan, swipe down to close, and arrow keys, + and − and Escape on the web. Replaces react-native-image-viewing and react-native-image-zoom-viewer.

# ImageViewer

A full-screen lightbox for photos. Swipe between images, pinch or double-tap to zoom, drag a zoomed photo around, and drag down to close. On the web, arrow keys and the arrow buttons move between images, `+` and `−` zoom, and Escape closes. It's black in light and dark mode, so photos read true.

```tsx
import { ImageViewer } from 'patine-ui';
```

```tsx live
import { useState } from 'react';
import { Image, Pressable } from 'react-native';
import { HStack, ImageViewer } from 'patine-ui';

const photos = [
  { source: { uri: 'https://picsum.photos/id/1018/1200/800' }, alt: 'Mountain valley' },
  { source: { uri: 'https://picsum.photos/id/1015/1200/800' }, alt: 'River in a canyon' },
  { source: { uri: 'https://picsum.photos/id/1039/1200/800' }, alt: 'Waterfall' },
];

export default function Example() {
  const [open, setOpen] = useState(false);
  const [index, setIndex] = useState(0);
  return (
    <>
      <HStack gap="sm">
        {photos.map((photo, i) => (
          <Pressable
            key={photo.alt}
            accessibilityRole="button"
            accessibilityLabel={`Open ${photo.alt}`}
            onPress={() => {
              setIndex(i);
              setOpen(true);
            }}
          >
            <Image source={photo.source} style={{ width: 96, height: 72, borderRadius: 8 }} />
          </Pressable>
        ))}
      </HStack>
      <ImageViewer images={photos} open={open} onOpenChange={setOpen} value={index} onValueChange={setIndex} />
    </>
  );
}
```

## Example: a listing's photos

A rental listing: one large photo and four small ones, the last with a count of the rest. Any of them opens the viewer at that photo, and it pages through all nine.

```tsx live
import { useState } from 'react';
import { Image, Pressable, StyleSheet, Text, View } from 'react-native';
import { ImageViewer } from 'patine-ui';

const IDS = [1040, 1039, 1036, 1043, 1044, 1047, 1050, 1053, 1056];
const PHOTOS = IDS.map((id, i) => ({ source: { uri: `https://picsum.photos/id/${id}/1200/800` }, alt: `Photo ${i + 1} of the cabin` }));

export default function Example() {
  const [open, setOpen] = useState(false);
  const [index, setIndex] = useState(0);
  const show = (i: number) => {
    setIndex(i);
    setOpen(true);
  };
  const Tile = ({ i, style }: { i: number; style: object }) => (
    <Pressable onPress={() => show(i)} accessibilityRole="button" accessibilityLabel={`Open ${PHOTOS[i].alt}`} style={[{ borderRadius: 10, overflow: 'hidden' }, style]}>
      <Image source={{ uri: `https://picsum.photos/id/${IDS[i]}/480/360` }} style={{ flex: 1 }} />
      {i === 4 ? (
        <View style={{ ...StyleSheet.absoluteFillObject, backgroundColor: 'rgba(0,0,0,0.45)', alignItems: 'center', justifyContent: 'center' }}>
          <Text style={{ color: '#fff', fontWeight: '600' }}>+{PHOTOS.length - 5} photos</Text>
        </View>
      ) : null}
    </Pressable>
  );
  return (
    <>
      <View style={{ width: '100%', maxWidth: 520, height: 240, flexDirection: 'row', gap: 6 }}>
        <Tile i={0} style={{ flex: 2 }} />
        <View style={{ flex: 2, gap: 6 }}>
          <View style={{ flex: 1, flexDirection: 'row', gap: 6 }}>
            <Tile i={1} style={{ flex: 1 }} />
            <Tile i={2} style={{ flex: 1 }} />
          </View>
          <View style={{ flex: 1, flexDirection: 'row', gap: 6 }}>
            <Tile i={3} style={{ flex: 1 }} />
            <Tile i={4} style={{ flex: 1 }} />
          </View>
        </View>
      </View>
      <ImageViewer images={PHOTOS} open={open} onOpenChange={setOpen} value={index} onValueChange={setIndex} />
    </>
  );
}
```

## Gestures and keys

| | Phones | Web |
| --- | --- | --- |
| Next or previous image | Swipe sideways | Arrow keys or the arrow buttons; swipe on touch screens |
| Zoom | Pinch, or double-tap where you want to look | Double-click, or `+` and `−` (`0` resets) |
| Move a zoomed image | Drag | Drag |
| Close | Swipe down, the close button, Android back | Escape or the close button |

Sideways swipes page only while the image isn't zoomed; once zoomed, a drag pans it. Leaving an image resets its zoom.

## Accessibility

- Name each image with `alt`; screen readers read it, and the counter ("2 / 5") is announced as it changes.
- The viewer is modal: focus moves into it when it opens and back to what opened it when it closes.
- On the web, the arrow buttons are named "Previous image" and "Next image"; rename them, the close button and the counter with `labels`.
- Zoom animations jump straight to their end when the OS asks to reduce motion.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `images` | `{ source, alt? }[]` | — | `source` is a `{ uri }` or a `require`d image. |
| `open` | `boolean` | — | |
| `onOpenChange` | `(open: boolean) => void` | — | Called with `false` to close. |
| `value` | `number` | — | The image shown, from 0. |
| `defaultValue` | `number` | `0` | The first image when uncontrolled. |
| `onValueChange` | `(index: number) => void` | — | The user went to another image. |
| `swipeToClose` | `boolean` | `true` | Drag down to close. |
| `labels` | `Partial<LightboxLabels>` | English | `close`, `previous`, `next`, `image` (with `{page}` and `{count}`). |
| `theme` / `design` | | provider's | The close button sits at the start on iOS and Material, at the end on the web and brand. |
