Viewer.js Image Viewer

1.11.7 · active · verified Sun Apr 19

Viewer.js is a robust JavaScript image viewer designed for web applications, currently stable at version 1.11.7. It provides a rich set of features including modal and inline viewing modes, touch gesture support, image movement, zooming, rotation, scaling (flipping), and comprehensive keyboard navigation. The library is actively maintained with frequent minor releases focusing on bug fixes and compatibility improvements. Key differentiators include its extensive API with 53 options, 23 methods, and 17 events, offering fine-grained control over the viewing experience. It ships with TypeScript type definitions, making it suitable for modern TypeScript projects, and offers various build formats (UMD, CommonJS, ES Module) to fit different project setups. While a jQuery wrapper exists, the core library is standalone and dependency-free.

Common errors

```
ReferenceError: Viewer is not defined
```
cause The Viewer.js library was not correctly imported or loaded into the global scope before being used.

fix Ensure you have `import Viewer from 'viewerjs';` at the top of your JavaScript file, or that the `<script src="/path/to/viewer.js"></script>` tag is present and correctly placed in your HTML.
```
TypeError: Cannot read properties of null (reading 'querySelectorAll')
```
cause The HTML element passed to the `Viewer` constructor could not be found in the DOM, often due to an incorrect ID or the script running before the DOM is fully loaded.

fix Verify the element ID or selector is correct. Wrap your initialization code in a `DOMContentLoaded` listener: `document.addEventListener('DOMContentLoaded', () => { new Viewer(...); });`.
```
Images appear without any styling, controls are missing or misaligned.
```
cause The `viewer.css` stylesheet is not being loaded or applied to the page.

fix Add `import 'viewerjs/dist/viewer.css';` to your main JavaScript file (if using a bundler) or include `<link href="/path/to/viewer.css" rel="stylesheet">` in your HTML's `<head>` section, ensuring the path is correct.

Warnings

gotcha Failing to import or link the `viewer.css` stylesheet will result in an unstyled viewer, leading to a broken layout and user experience. The images will not display correctly and controls will be absent or misaligned.
Fix: Ensure `import 'viewerjs/dist/viewer.css';` is included in your application's entry point, or `<link href="/path/to/viewer.css" rel="stylesheet">` is present in your HTML `<head>`.
gotcha When using `new Viewer(element)`, if `element` is a container, Viewer.js will automatically find all `<img>` tags within that container. If you intend to view only specific images, ensure they are in a dedicated container or select them individually.
Fix: For specific images within a larger structure, create a distinct wrapper element for the target images or initialize `Viewer` on each `<img>` element directly.
gotcha Keyboard support for navigation, zoom, and rotation is only available in 'modal' mode (when `inline: false` or default). In 'inline' mode, keyboard shortcuts will not function as expected.
Fix: If keyboard control is required, use Viewer.js in its default modal display mode. For inline viewers, implement custom controls if keyboard accessibility is a strict requirement.
gotcha The `url` option dictates which image source Viewer.js uses. By default, it uses the `src` attribute. If your images have data attributes (e.g., `data-original-src`) for high-resolution versions, you must specify the `url` option.
Fix: Set the `url` option in the Viewer constructor, for example: `new Viewer(element, { url: 'data-original-src' });` or `url(image) { return image.dataset.originalSrc; }`.

Install

npm install viewerjs npm
yarn add viewerjs yarn
pnpm add viewerjs pnpm

Imports

Viewer
wrong:
```
const Viewer = require('viewerjs');
```
correct:
```
import Viewer from 'viewerjs';
```
The Viewer class is the default export for ES Modules. While a CommonJS build (`viewer.common.js`) exists, modern tooling favors the ES Module import.
CSS
wrong:
```
require('viewerjs/dist/viewer.css');
```
correct:
```
import 'viewerjs/dist/viewer.css';
```
The CSS stylesheet is crucial for proper display and must be imported in your JavaScript entry file or linked in your HTML. Using a CSS import is the recommended approach for bundlers.
Viewer.setDefaults
wrong:
```
import { setDefaults } from 'viewerjs';
```
correct:
```
import Viewer from 'viewerjs'; Viewer.setDefaults({ /* options */ });
```
`setDefaults` is a static method on the default `Viewer` export, used for global configuration of options rather than an individual instance.

Quickstart

This quickstart demonstrates how to initialize Viewer.js for both a single image and a gallery of images. It shows importing the necessary CSS and the `Viewer` class, setting up basic options like `inline` mode, and utilizing event callbacks such as `viewed`.

import 'viewerjs/dist/viewer.css';
import Viewer from 'viewerjs';

// HTML structure for demonstration
document.body.innerHTML = `
  <div>
    <img id="single-image" src="https://picsum.photos/id/1018/800/600" alt="Single Picture">
  </div>
  <div>
    <ul id="image-gallery">
      <li><img src="https://picsum.photos/id/1015/300/200" alt="Picture 1"></li>
      <li><img src="https://picsum.photos/id/1016/300/200" alt="Picture 2"></li>
      <li><img src="https://picsum.photos/id/1019/300/200" alt="Picture 3"></li>
    </ul>
  </div>
`;

// View a single image in inline mode
const singleImage = document.getElementById('single-image');
if (singleImage) {
  const viewer = new Viewer(singleImage, {
    inline: true,
    viewed() {
      console.log('Single image viewed and ready!');
      viewer.zoomTo(0.8); // Zoom to 80% after viewing
    },
    ready() {
        console.log('Viewer instance for single image is ready.');
    }
  });
  // To programmatically show the viewer in modal mode:
  // viewer.show();
}

// View a list of images (gallery)
const imageGallery = document.getElementById('image-gallery');
if (imageGallery) {
  const galleryViewer = new Viewer(imageGallery, {
    url(image) {
      return image.src; // Use image 'src' attribute for full-size image
    },
    hidden() {
        console.log('Gallery viewer is hidden.');
    },
    viewed() {
        console.log('An image in the gallery was viewed.');
    }
  });
  // To programmatically show the first image in the gallery:
  // galleryViewer.show();
}

console.log('Viewer.js examples initialized.');

view raw JSON →