zimme-zoom

A collection of image-related React components packaged as an npm package. The main component is PhotoViewer, a lightweight React photo viewer with zoom, navigation, blurred background, and SVG overlay support.

Components

zimme-zoom provides the following React components:

• PhotoViewer - The main component: A lightweight photo viewer with zoom, navigation, blurred background, and SVG overlay support
• Gallery - A grid-based image gallery component that displays images and integrates with PhotoViewer
• ImageCarousel - A swipeable image carousel with lazy loading and touch/mouse gesture support
• Image - A reusable image component for displaying images with click handlers, built-in loading states (pulsing placeholder), and smooth fade-in transitions

All components are exported from the main package:

import { PhotoViewer, Gallery, Image } from 'zimme-zoom';
import type { ZZImage, PhotoViewerProps } from 'zimme-zoom';

Demo

📖 Examples and interactive demos on Storybook.

Click here to view the video demo on YouTube

Prerequisites

• Node.js >= 14.0.0
• React >= 16.8.0
• React DOM >= 16.8.0
• Yarn >= 1.22.0 (or npm)

Installation

yarn add zimme-zoom

PhotoViewer Usage

Basic Example

import { PhotoViewer } from 'zimme-zoom';
import type { ZZImage } from 'zimme-zoom';

const images: ZZImage[] = [
  {
    id: '1',
    src: 'https://example.com/image1.jpg',
    alt: 'Image 1',
    title: 'My Photo',
  },
];

function App() {
  const [selectedImage, setSelectedImage] = useState<ZZImage | null>(null);

  return (
    <>
      <button onClick={() => setSelectedImage(images[0])}>View Photo</button>
      <PhotoViewer images={images} selectedImage={selectedImage} onClose={() => setSelectedImage(null)} />
    </>
  );
}

With SVG Overlay

const imageWithOverlay: ZZImage = {
  id: '2',
  src: 'https://example.com/image2.jpg',
  alt: 'Image with overlay',
  svgOverlay: <YourSVGComponent />,
  overlayPosition: 'bottom-right',
  overlaySize: { maxWidth: 200, maxHeight: 200 },
};

Custom Settings

The settings prop allows you to customize the PhotoViewer behavior. All settings are optional and will use default values if not provided.

<PhotoViewer
  images={images}
  selectedImage={selectedImage}
  onClose={() => setSelectedImage(null)}
  settings={{
    allowZoom: true,
    allowRotate: true,
    maxZoom: 5,
    zoomStep: 0.3,
  }}
/>

PhotoViewer Props

Prop	Type	Required	Description
images	ZZImage[]	Yes	Array of images to display
selectedImage	ZZImage | null	Yes	Currently selected image to display
onClose	() => void	Yes	Callback function called when PhotoViewer is closed
onImageChange	(image: ZZImage) => void	No	Callback function called when the displayed image changes
settings	Partial<PhotoViewerSettings>	No	Configuration object for PhotoViewer behavior (see Settings)

Available Settings

All settings are configured through the settings prop:

Setting	Type	Default	Description
allowZoom	boolean	true	Enable/disable zoom functionality (mouse wheel, zoom buttons)
allowRotate	boolean	true	Enable/disable image rotation
allowReset	boolean	true	Enable/disable reset button (resets zoom and rotation)
allowDownload	boolean	false	Enable/disable download button
doubleClickZoom	number	4	Zoom level when double-clicking the image
clickOutsideToExit	boolean	true	Close PhotoViewer when clicking outside the image
keyboardInteraction	boolean	true	Enable/disable keyboard shortcuts (Arrow keys, +/-, r, 0, Escape)
maxZoom	number	4	Maximum zoom level (multiplier)
minZoom	number	0.5	Minimum zoom level (multiplier)
zoomStep	number	0.3	Zoom increment/decrement step size
showOverlayByDefault	boolean	false	Show SVG overlay by default when PhotoViewer opens (only applies if image has svgOverlay)
showOverlayButton	boolean	false	Show overlay toggle button in navigation bar (only applies if image has svgOverlay)

Settings Example

<PhotoViewer
  images={images}
  selectedImage={selectedImage}
  onClose={() => setSelectedImage(null)}
  settings={{
    allowZoom: true,
    allowRotate: true,
    allowReset: true,
    allowDownload: true,
    doubleClickZoom: 3,
    clickOutsideToExit: true,
    keyboardInteraction: true,
    maxZoom: 5,
    minZoom: 0.3,
    zoomStep: 0.5,
    showOverlayByDefault: true,
    showOverlayButton: true,
  }}
/>

Image Component Usage

The Image component is a reusable image component that provides built-in loading states and smooth transitions.

Basic Example

import { Image } from 'zimme-zoom';
import type { ZZImage } from 'zimme-zoom';

const image: ZZImage = {
  id: '1',
  src: 'https://example.com/image1.jpg',
  alt: 'Image 1',
};

function App() {
  return <Image image={image} onClick={() => console.log('Image clicked')} />;
}

Image Props

Prop	Type	Required	Description
image	ZZImage	Yes	Image object containing id, src, and alt
onClick	() => void	No	Callback function called when image is clicked

The component is designed to work seamlessly within the Gallery component, but can also be used standalone in your own layouts.

License

MIT