viewerjs

Viewer.js

JavaScript image viewer.

• Website
• jquery-viewer - A jQuery plugin wrapper for Viewer.js.

Table of Contents

• Features
• Main Files
• Getting Started
• Keyboard Support
• Options
• Methods
• Static Methods
• Events
• Browser Support
• Contributing
• Versioning
• License

Features

• Supports 61 options
• Supports 23 methods
• Supports 17 events
• Supports modal and inline modes
• Supports touch
• Supports move
• Supports zoom
• Supports rotation
• Supports scale (flip)
• Supports keyboard
• Supports image magnification
• Cross-browser support

Main Files

dist/
├── viewer.css
├── viewer.min.css   (compressed)
├── viewer.js        (UMD)
├── viewer.min.js    (UMD, compressed)
├── viewer.common.js (CommonJS, default)
└── viewer.esm.js    (ES Module)

Getting Started

Installation

npm install viewerjs

In the browser:

<link href="/path/to/viewer.css" rel="stylesheet">
<script src="/path/to/viewer.js"></script>

The cdnjs project provides CDN support for Viewer.js CSS and JavaScript. You can find the links here.

Usage

Syntax

new Viewer(element[, options])

• element

  • Type: HTMLElement
  • The target image, or a container of images, to view.

• options (optional)

  • Type: Object
  • The configuration options. Check out the available options.

Alternatively, you may use Viewer.create(element[, options]).

Example

// You should import the CSS file.
// import 'viewerjs/dist/viewer.css';
import Viewer from 'viewerjs';

// View an image.
const viewer = new Viewer(document.getElementById('image'), {
  inline: true,
  viewed() {
    viewer.zoomTo(1);
  },
});
// Then show the image by clicking it, or call `viewer.show()`.

// View a list of images.
// Note: all images within the container will be found by calling `element.querySelectorAll('img')`.
const gallery = new Viewer(document.getElementById('images'));
// Then show one image by clicking it, or call `gallery.show()`.

Keyboard Support

Only available in modal mode.

• Esc: Exit full screen or close the viewer or exit modal mode or stop play.
• Space: Stop play.
• Tab: Switch the focus state on the buttons in the viewer.
• Enter: Trigger the click event handler on the button.
• ←: View the previous image.
• →: View the next image.
• ↑: Zoom in the image.
• ↓: Zoom out the image.
• Ctrl + 0: Zoom out to initial size.
• Ctrl + 1: Zoom in to natural size.

⬆ back to top

Options

You may set viewer options with new Viewer(image, options). If you want to change the global default options, you may use Viewer.setDefaults(options).

backdrop

• Type: Boolean or String
• Default: true

Enable the modal backdrop, specify static for the backdrop that will not close the modal on click.

button

• Type: Boolean
• Default: true

Show the button on the top-right of the viewer.

navbar

• Type: Boolean or Number or String or Object
• Default: true
• Options:
  • 0 or false: hide the navbar
  • 1 or true: show the navbar
  • 2: show the navbar only when the screen width is greater than 768 pixels
  • 3: show the navbar only when the screen width is greater than 992 pixels
  • 4: show the navbar only when the screen width is greater than 1200 pixels
  • small: show thumbnails at 24px tall.
  • medium: show thumbnails at 32px tall.
  • large: show thumbnails at 40px tall.
  • Object: configure the navbar with the following properties:
    • show (Boolean or Number): specify the visibility of the navbar.
    • size (String): specify the thumbnail size: small, medium, or large.
    • visibleItemCount (Number): specify the number of thumbnail items to render around the active item. The default is calculated from the container width and the width of one thumbnail item.

Specify the visibility of the navbar.

When setting a size, thumbnails use a $9 / 16$ width-to-height ratio.

navbar: {
  show: true,
  size: 'large',
}

navigation

• Type: Boolean or Number or Object

• Default: false

• Options:

  • 0 or false: hide the navigation buttons.
  • 1 or true: show the navigation buttons.
  • 2: show the navigation buttons only when the screen width is greater than 768 pixels.
  • 3: show the navigation buttons only when the screen width is greater than 992 pixels.
  • 4: show the navigation buttons only when the screen width is greater than 1200 pixels.
  • { prev: Boolean | Number | Object, next: Boolean | Number | Object }: show or hide each navigation button.
  • { prev: { show: Boolean | Number, size: String }, next: { show: Boolean | Number, size: String } }: customize each navigation button.
  • Available sizes: small (32px), medium (40px, default), and large (48px).

Show the previous and next buttons on the left and right sides of the viewer.

For example:

new Viewer(image, {
  navigation: {
    prev: {
      size: 'large',
    },
    next: {
      show: 2,
      size: 'small',
    },
  },
});

title

• Type: Boolean or Number or Function or Array
• Default: true
• Options:
  • 0 or false: hide the title
  • 1 or true or Function or Array: show the title
  • 2: show the title only when the screen width is greater than 768 pixels
  • 3: show the title only when the screen width is greater than 992 pixels
  • 4: show the title only when the screen width is greater than 1200 pixels
  • Function: customize the title content
  • [Number, Function]: the first element indicates the visibility; the second element customizes the title content

Specify the visibility and content of the title.

The name comes from the alt attribute of an image element or the image name parsed from its URL.

For example, title: 4 equals to:

new Viewer(image, {
  title: [4, (image, imageData) => `${image.alt} (${imageData.naturalWidth} × ${imageData.naturalHeight})`]
});

toolbar

• Type: Boolean or Number or Object
• Default: true
• Options:
  • 0 or false: hide the toolbar.
  • 1 or true: show the toolbar.
  • 2: show the toolbar only when the screen width is greater than 768 pixels.
  • 3: show the toolbar only when the screen width is greater than 992 pixels.
  • 4: show the toolbar only when the screen width is greater than 1200 pixels.
  • { key: Boolean | Number }: show or hide the toolbar.
  • { key: String }: customize the size of the button.
  • { key: Function }: customize the click handler of the button.
  • { key: { show: Boolean | Number, size: String, click: Function }: customize each property of the button.
  • Available built-in keys: "zoomIn", "zoomOut", "oneToOne", "reset", "prev", "play", "next", "rotateLeft", "rotateRight", "flipHorizontal", "flipVertical".
  • Available built-in sizes: "small", "medium" (default) and "large".

Specify the visibility and layout of the toolbar and its buttons.

For example, toolbar: 4 equals to:

new Viewer(image, {
  toolbar: {
    zoomIn: 4,
    zoomOut: 4,
    oneToOne: 4,
    reset: 4,
    prev: 4,
    play: {
      show: 4,
      size: 'large',
    },
    next: 4,
    rotateLeft: 4,
    rotateRight: 4,
    flipHorizontal: 4,
    flipVertical: 4,
  },
});

see more for custom toolbar.

className

• Type: String
• Default: ''

Custom class name(s) to add to the viewer's root element.

container

• Type: Element or String
• Default: 'body'
• An element or a valid selector for Document.querySelector

Container to place the viewer in the modal mode.

Only available when the inline option is set to false.

filter

• Type: Function
• Default: null

Filter the images for viewing (should return true if the image is viewable, return false to ignore the image).

For example:

new Viewer(image, {
  filter(image) {
    return image.complete;
  },
});

Note that images without the src attribute set will be ignored by default.

fullscreen

• Type: Boolean or FullscreenOptions
• Default: true

Enable to request full screen when play.

Requires the browser supports Fullscreen API.

inheritedAttributes

• Type: Array
• Default: ['crossOrigin', 'decoding', 'isMap', 'loading', 'referrerPolicy', 'sizes', 'srcset', 'useMap']

Define the extra attributes to inherit from the original image.

Note that the basic attributes src and alt will always inherit from the original image.

initialCoverage

• Type: Number
• Default: 0.9

Define the initial coverage of the viewing image. It must be a positive number between 0 (0%) and 1 (100%).

initialViewIndex

• Type: Number
• Default: 0

Define the initial index of the image for viewing.

Also used as the default parameter value of the view method.

inline

• Type: Boolean
• Default: false

Enable inline mode.

autoplay

• Type: Boolean
• Default: true

Enable to automatically cycle the images when playing.

interval

• Type: Number
• Default: 5000

The amount of time to delay between automatically cycling an image when playing.

keyboard

• Type: Boolean
• Default: true

Enable keyboard support.

focus

• Type: Boolean
• Default: true

Focus the active item in the navbar when initialized.

Requires the keyboard option set to true.

loading

• Type: Boolean
• Default: true

Indicate if showing a loading spinner when loading the image or not.

loop

• Type: Boolean
• Default: true

Indicate if enabling loop viewing or not.

If the current image is the last one, then the next one to view is the first one, and vice versa.

preload

• Type: Boolean
• Default: true

Enable to preload the next or previous image before viewing it.

minWidth

• Type: Number
• Default: 200

Define the minimum width of the viewer.

Only available in inline mode (set the inline option to true).

minHeight

• Type: Number
• Default: 100

Define the minimum height of the viewer.

Only available in inline mode (set the inline option to true).

movable

• Type: Boolean
• Default: true

Enable to move the image.

magnifier

• Type: Boolean or Object
• Default: false
• Options:
  • size (Number): the size of the magnifier in pixels. Defaults to 100.
  • zoomRatio (Number): the magnification ratio. Defaults to 2.
  • opacity (Number): the opacity of the magnifier, from 0 to 1. Defaults to 1.

Show a magnifier over the image when hovering in fullscreen mode. The magnifier is disabled on touch screens.

For example:

new Viewer(image, {
  magnifier: {
    size: 120,
    zoomRatio: 3,
    opacity: 0.8,
  },
});

rotatable

• Type: Boolean
• Default: true

Enable to rotate the image.

rotateOnGesture

• Type: Boolean
• Default: true

Enable to rotate the current image with gesture events, such as a two-finger gesture on Mac Safari.

rotateOnTouch

• Type: Boolean
• Default: true

Enable to rotate the current image with a two-finger gesture on a touch screen.

scalable

• Type: Boolean
• Default: true

En