Skip to main content

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.

import { ImageViewer } from 'patine-ui';
Behaves like
Loading…
<>
  <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} />
</>

Try the props​

Behaves like
Props
<ImageViewer
images={photos}
open={open}
onOpenChange={setOpen}
/>

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.

Behaves like
Loading…
<>
  <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​

PhonesWeb
Next or previous imageSwipe sidewaysArrow keys or the arrow buttons; swipe on touch screens
ZoomPinch, or double-tap where you want to lookDouble-click, or + and − (0 resets)
Move a zoomed imageDragDrag
CloseSwipe down, the close button, Android backEscape 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​

PropTypeDefaultDescription
images{ source, alt? }[]—source is a { uri } or a required image.
openboolean—
onOpenChange(open: boolean) => void—Called with false to close.
valuenumber—The image shown, from 0.
defaultValuenumber0The first image when uncontrolled.
onValueChange(index: number) => void—The user went to another image.
swipeToClosebooleantrueDrag down to close.
labelsPartial<LightboxLabels>Englishclose, previous, next, image (with {page} and {count}).
theme / designprovider'sThe close button sits at the start on iOS and Material, at the end on the web and brand.