viewerjs

library1.11.7jsnpmunverified

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.

web-framework

npm install viewerjs

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VIEWERJS

viewerjs

web-frameworkjavascriptv1.11.7

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Viewer

✓ import Viewer from 'viewerjs';

✗ const Viewer = require('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

✓ import 'viewerjs/dist/viewer.css';

✗ require('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

✓ import Viewer from 'viewerjs'; Viewer.setDefaults({ /* options */ });

✗ import { setDefaults } from 'viewerjs';

`setDefaults` is a static method on the default `Viewer` export, used for global configuration of options rather than an individual instance.

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.');

Debug

Known issues

gotchaFailing 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>`.

affects: >=1.0.0

gotchaWhen 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.

affects: >=1.0.0

gotchaKeyboard 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.

affects: >=1.0.0

gotchaThe `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; }`.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: Viewer is not defined

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')

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.

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.

Upgrade

Version history

1.11.7latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/fengyuanchen/viewerjs ↗

packagehttps://www.npmjs.com/package/viewerjs ↗

homepagehttps://fengyuanchen.github.io/viewerjs ↗