@zackrypaul/media-viewer

A plug-and-play React Native package for displaying tappable media thumbnails and opening them in a fullscreen viewer. Designed for minimal integration friction and easy data conformity.

Installation

yarn add @zackrypaul/media-viewer

Minimal Usage

import { TapToOpenMediaViewer } from "@zackrypaul/media-viewer";

const items = [
  { url: "https://example.com/image.jpg" }, // Minimal MediaItem
];

<TapToOpenMediaViewer items={items} />;

Minimal Required Props

• items: Array of objects with at least a url property (string).
  Example:

  [{ url: "https://example.com/image.jpg" }]

• For videos, add type: "video" and a valid video URL.

MediaItem Shape

export interface MediaItem {
  url: string; // REQUIRED
  id?: string;
  type?: "image" | "video";
  thumbnailUri?: string;
  posterUri?: string;
  width?: number;
  height?: number;
  accessibilityLabel?: string;
}

Components

• TapToOpenMediaViewer: Thumbnails + fullscreen modal.
  Minimal required prop: items
• MediaViewer: Fullscreen modal only.
  Minimal required props: items, visible, onRequestClose
• MediaGrid: Optional grid layout for thumbnails.
• SmartMediaLayout: Social-style arrangement.

Example

<TapToOpenMediaViewer
  items={[
    { url: "https://example.com/image.jpg" },
    { url: "https://example.com/video.mp4", type: "video" },
  ]}
/>

Customization

All props are optional except for items. You can provide custom header, footer, or render hooks if needed, but the package works out-of-the-box with just the minimal shape.

Data Conformity

If your app’s data doesn’t match the required shape, map it before passing:

const items = myMedia.map(media => ({
  url: media.src,
  type: media.isVideo ? "video" : "image",
}));

Peer Dependencies

• expo
• react
• react-native

License

MIT