hpv-image-previewer

HpvImagePreviewer

A standalone, extensible JavaScript class for displaying images or galleries in a modal overlay with advanced zoom, pan, navigation, and custom action capabilities. Fully responsive, event-driven, and easily integrated into any web project.

Preview

Modal overlay with gallery navigation

Zoom and pan controls in action

Gallery carousel with thumbnails

Fully responsive on desktop and mobile

Features

• Modal Image & Gallery Display: Show single images or full galleries in a full-screen overlay.
• Zoom & Pan: Mouse wheel zoom, pinch-to-zoom, and pan when zoomed.
• Zoom Controls: Zoom in/out/reset buttons with press-and-hold for continuous zoom.
• Gallery Navigation: Cycle through images with navigation buttons, keyboard arrows, or swipe gestures.
• Custom Buttons: Flexible button system with custom handlers, keyboard shortcuts, and styling.
• Touch Support: Pinch-to-zoom, swipe navigation, and touch pan.
• Readonly Mode: Show/hide buttons based on readonly state.
• Event Driven: Emits custom events for integration and analytics.
• Intelligent Sizing: Overlay adapts to image aspect ratio and viewport.
• Reusable: Single instance can display different images or galleries.
• Customizable: Configurable button texts, callbacks, and CSS classes.
• Accessible: Keyboard navigation and ARIA-friendly markup.

Quick Start

• Include CSS and JS

<link rel="stylesheet" href="src/css/main.css">
<script src="src/js/main.js"></script>

• Instantiate and Use

const previewer = new HpvImagePreviewer({
  closeButtonText: 'Close',
  isReadOnly: false,
  buttons: [
    {
      id: 'view',
      label: 'View',
      title: 'View full size image',
      customClasses: ['btn-primary'],
      visibleReadOnly: true,
      clickHandler: (image) => window.open(image.url, '_blank')
    },
    {
      id: 'star',
      label: 'Star',
      title: 'Mark as favorite',
      customClasses: ['btn-star'],
      keyPress: { key: 's', shift: true }, // Triggers with Shift+S
      clickHandler: (image) => alert('Starred: ' + image.alt)
    }
  ]
});

const imageModel = { url: 'path/to/image.jpg', alt: 'Description' };
previewer.show(imageModel);

• Gallery Mode

const images = [
  { url: 'img1.jpg', alt: 'First' },
  { url: 'img2.jpg', alt: 'Second' }
];
previewer.showGallery(images, 0); // Start at first image

API

Constructor Options

Option	Type	Default	Description
buttons	Array	[]	Array of custom button configs
closeButtonText	string	'Close'	Text for the close button
isReadOnly	boolean	false	If true, only shows buttons with visibleReadOnly: true
minScale	number	1	Minimum zoom scale
maxScale	number	5	Maximum zoom scale
onClose	function	null	Callback for close button click
onImageSwitch	function	null	Callback for gallery navigation
isDebug	boolean	false	Enable debug logging

Button Configuration

Property	Type	Required	Description
id	string	✅	Unique identifier
label	string	✅	Button text
title	string	❌	Tooltip text
icon	string	❌	CSS class for icon
visibleReadOnly	boolean	❌	Show in readonly mode (default: true)
customClasses	Array	❌	Extra CSS classes for styling
clickHandler	function	✅	Called on click: (image, previewerInstance) => {}
keyPress	Object	❌	Keyboard shortcut: { key: 'd', ctrl: true }

Image Model

{
  url: 'string',     // Required: Image URL
  alt: 'string',     // Optional: Alt text
  file: File,        // Optional: Original file object
  // ...any custom properties
}

Methods

• show(imageModel)
• showGallery(galleryImages, activeIndex = 0)
• navigateGallery(direction)
• hide()
• updateOptions(newOptions)
• toggleReadOnly()
• setReadOnly(isReadOnly)
• destroy()

Events

Event Name	Detail Payload	Description
hpvImagePreviewer:customButtonClick	{ buttonId, image, button }	Custom button clicked
hpvImagePreviewer:close	{ image }	Overlay closed
hpvImagePreviewer:navigate	{ currentImage, currentIndex, previousImage, galleryLength, direction, cycled }	Gallery navigation occurred

File Structure

src/js/
  main.js                # HpvImagePreviewer class
src/css/
  main.css               # Overlay/modal/gallery styles
src/index.html           # Sample usage
examples/
  image-previewer-standalone.html  # Advanced example
docs/
  HpvImagePreviewer-README.md      # Full documentation

Browser Support

• Modern browsers (Chrome, Firefox, Safari, Edge)
• Touch devices (iOS Safari, Android Chrome)
• Requires ES6, CustomEvent, and modern CSS

Dependencies

• None. Pure vanilla JavaScript and CSS.

License

MIT

Contributing

Pull requests and issues are welcome! Please see docs/HpvImagePreviewer-README.md for full documentation and advanced usage.