Image Viewer

The Image Viewer component provides an interactive way to display images with advanced gesture support. It includes pinch-to-zoom, double-tap zoom, swipe navigation between images, and slide-to-dismiss functionality. Built with React Native Reanimated for smooth 60fps animations that run on the UI thread. This is an illustration of Image Viewer component. A basic image viewer with zoom, swipe navigation, and slide-to-dismiss gestures

Installation

Run the following command:

npx gluestack-ui@alpha add image-viewer

API Reference

To use this component in your project, include the following import statement in your file.

import {
  ImageViewer,
  ImageViewerTrigger,
  ImageViewerContent,
  ImageViewerCloseButton,
  ImageViewerNavigation,
  ImageViewerCounter,
} from '@/components/ui/image-viewer';

export default () => (
  <ImageViewer images={images}>
    <ImageViewerTrigger>
      <Image source={{ uri: '...' }} />
    </ImageViewerTrigger>
    <ImageViewerContent>
      <ImageViewerCloseButton />
      <ImageViewerNavigation />
      <ImageViewerCounter />
    </ImageViewerContent>
  </ImageViewer>
);

Component Props

This section provides a comprehensive reference list for the component props, detailing descriptions, properties, types, and default behavior for easy project integration.

ImageViewer

The root component that manages the image viewer state and provides context to child components.

Prop	Type	Default	Description
images	ImageItem[]	-	Array of images to display. Each item should have url and optional alt.
defaultOpen	boolean	false	Whether the viewer is open by default (uncontrolled).
isOpen	boolean	-	Controlled open state. Use with onOpenChange for controlled mode.
onOpenChange	(isOpen: boolean) => void	-	Callback when open state changes.
initialIndex	number	0	Index of the image to show initially.

ImageViewerTrigger

The trigger element that opens the image viewer when pressed.

Prop	Type	Default	Description
children	React.ReactNode	-	Content to render as the trigger (usually an Image).
onPress	() => void	-	Additional callback when trigger is pressed.

ImageViewerContent

The modal content that displays the image with gesture support.

Prop	Type	Default	Description
children	React.ReactNode	-	Child components like CloseButton, Navigation, Counter.

ImageViewerCloseButton

A button to close the image viewer.

Prop	Type	Default	Description
className	string	-	Additional Tailwind classes for styling.

ImageViewerNavigation

Navigation buttons to move between images in the gallery.

Prop	Type	Default	Description
className	string	-	Additional Tailwind classes for styling.

ImageViewerCounter

Displays the current image index and total count (e.g., "3 / 10").

Prop	Type	Default	Description
className	string	-	Additional Tailwind classes for styling.

Gestures

The Image Viewer supports the following gestures:

Pinch to Zoom: Use two fingers to zoom in and out of images

Double Tap: Double tap to zoom in (2.5x) or reset zoom

Pan: When zoomed in, drag to pan around the image

Swipe Left/Right: Navigate between images in the gallery

Swipe Up/Down: Dismiss the viewer by swiping vertically

Accessibility

Adheres to the Dialog

WAI-ARIA design pattern

. We have outlined the various features that ensure the Image Viewer component is accessible to all users, including those with disabilities. These features help ensure that your application is inclusive and meets accessibility standards.

ARIA Labels: All interactive elements have appropriate ARIA labels

Keyboard Navigation: Full keyboard support with Tab, Enter, Escape, and Arrow keys

Focus Management: Focus is trapped within the modal when open

Screen Reader Support: Images announce their alt text to screen readers

Keyboard Interactions

Tab

- Moves focus to the next focusable element.

Shift + Tab

- Moves focus to the previous focusable element.

Enter

Space

- Activates the focused button.

Escape

- Closes the image viewer.

Left Arrow

- Navigate to previous image.

Right Arrow

- Navigate to next image.

VoiceOver: Announces image alt text and current position (e.g., "Image 3 of 10")

TalkBack: Provides similar announcements on Android

Types

interface ImageItem {
  url: string;
  alt?: string;
}

interface ImageViewerProps {
  images: ImageItem[];
  defaultOpen?: boolean;
  isOpen?: boolean;
  onOpenChange?: (isOpen: boolean) => void;
  initialIndex?: number;
}

Examples

The Examples section provides visual representations of the different variants of the component, allowing you to quickly and easily determine which one best fits your needs.

Controlled Mode

Use controlled props to programmatically control the image viewer state and track current image index

Single Image

Image viewer works great with single images too, providing zoom and pan capabilities

Edit this page on GitHub