{"id":12362,"library":"viewerjs","title":"Viewer.js Image Viewer","description":"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.","status":"active","version":"1.11.7","language":"javascript","source_language":"en","source_url":"https://github.com/fengyuanchen/viewerjs","tags":["javascript","image","viewer","viewerjs","viewer.js","html","css","front-end","typescript"],"install":[{"cmd":"npm install viewerjs","lang":"bash","label":"npm"},{"cmd":"yarn add viewerjs","lang":"bash","label":"yarn"},{"cmd":"pnpm add viewerjs","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const Viewer = require('viewerjs');","symbol":"Viewer","correct":"import Viewer from 'viewerjs';"},{"note":"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.","wrong":"require('viewerjs/dist/viewer.css');","symbol":"CSS","correct":"import 'viewerjs/dist/viewer.css';"},{"note":"`setDefaults` is a static method on the default `Viewer` export, used for global configuration of options rather than an individual instance.","wrong":"import { setDefaults } from 'viewerjs';","symbol":"Viewer.setDefaults","correct":"import Viewer from 'viewerjs'; Viewer.setDefaults({ /* options */ });"}],"quickstart":{"code":"import 'viewerjs/dist/viewer.css';\nimport Viewer from 'viewerjs';\n\n// HTML structure for demonstration\ndocument.body.innerHTML = `\n  <div>\n    <img id=\"single-image\" src=\"https://picsum.photos/id/1018/800/600\" alt=\"Single Picture\">\n  </div>\n  <div>\n    <ul id=\"image-gallery\">\n      <li><img src=\"https://picsum.photos/id/1015/300/200\" alt=\"Picture 1\"></li>\n      <li><img src=\"https://picsum.photos/id/1016/300/200\" alt=\"Picture 2\"></li>\n      <li><img src=\"https://picsum.photos/id/1019/300/200\" alt=\"Picture 3\"></li>\n    </ul>\n  </div>\n`;\n\n// View a single image in inline mode\nconst singleImage = document.getElementById('single-image');\nif (singleImage) {\n  const viewer = new Viewer(singleImage, {\n    inline: true,\n    viewed() {\n      console.log('Single image viewed and ready!');\n      viewer.zoomTo(0.8); // Zoom to 80% after viewing\n    },\n    ready() {\n        console.log('Viewer instance for single image is ready.');\n    }\n  });\n  // To programmatically show the viewer in modal mode:\n  // viewer.show();\n}\n\n// View a list of images (gallery)\nconst imageGallery = document.getElementById('image-gallery');\nif (imageGallery) {\n  const galleryViewer = new Viewer(imageGallery, {\n    url(image) {\n      return image.src; // Use image 'src' attribute for full-size image\n    },\n    hidden() {\n        console.log('Gallery viewer is hidden.');\n    },\n    viewed() {\n        console.log('An image in the gallery was viewed.');\n    }\n  });\n  // To programmatically show the first image in the gallery:\n  // galleryViewer.show();\n}\n\nconsole.log('Viewer.js examples initialized.');\n","lang":"typescript","description":"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`."},"warnings":[{"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>`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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; }`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The Viewer.js library was not correctly imported or loaded into the global scope before being used.","error":"ReferenceError: Viewer is not defined"},{"fix":"Verify the element ID or selector is correct. Wrap your initialization code in a `DOMContentLoaded` listener: `document.addEventListener('DOMContentLoaded', () => { new Viewer(...); });`.","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.","error":"TypeError: Cannot read properties of null (reading 'querySelectorAll')"},{"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.","cause":"The `viewer.css` stylesheet is not being loaded or applied to the page.","error":"Images appear without any styling, controls are missing or misaligned."}],"ecosystem":"npm"}