Viewer.js

JavaScript image viewer.

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

Features
Main
Getting started
Keyboard support
Options
Methods
Events
No conflict
Browser support
Contributing
Versioning
License

Features

Supports 53 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
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 browser:

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

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

Usage

Syntax

new Viewer(element[, options])

element
- Type: HTMLElement
- The target image or container of images for viewing.
options (optional)
- Type: Object
- The options for viewing. Check out the available options.

Example

<!-- a block container is required -->
<div>
  <img id="image" src="picture.jpg" alt="Picture">
</div>

<div>
  <ul id="images">
    <li><img src="picture-1.jpg" alt="Picture 1"></li>
    <li><img src="picture-2.jpg" alt="Picture 2"></li>
    <li><img src="picture-3.jpg" alt="Picture 3"></li>
  </ul>
</div>

// 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 click 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
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

Specify the visibility of the navbar.

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 indicate the visibility, the second element customize the title content

Specify the visibility and the 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 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 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.

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.

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.

rotatable

Type: Boolean
Default: true

Enable to rotate the image.

scalable

Type: Boolean
Default: true

Enable to scale the image.

zoomable

Type: Boolean
Default: true

Enable to zoom the image.

zoomOnTouch

Type: Boolean
Default: true

Enable to zoom the current image by dragging on the touch screen.

zoomOnWheel

Type: Boolean
Default: true

Enable to zoom the image by wheeling the mouse.

slideOnTouch

Type: Boolean
Default: true

Enable to slide to the next or previous image by swiping on the touch screen.

toggleOnDblclick

Type: Boolean
Default: true

Indicate if toggle the image size between its natural size and initial size when double click on the image or not.

In other words, call the toggle method automatically when double click on the image.

Requires dblclick event support.

tooltip

Type: Boolean
Default: true

Show the tooltip with image ratio (percentage) when zooming in or zooming out.

transition

Type: Boolean
Default: true

Enable CSS3 Transition for some special elements.

zIndex

Type: Number
Default: 2015

Define the CSS z-index value of the viewer in modal mode.

zIndexInline

Type: Number
Default: 0

Define the CSS z-index value of the viewer in inline mode.

zoomRatio

Type: Number
Default: 0.1

Define the ratio when zooming the image by wheeling the mouse.

minZoomRatio

Type: Number
Default: 0.01

Define the min ratio of the image when zooming out.

maxZoomRatio

Type: Number
Default: 100

Define the max ratio of the image when zooming in.

url

Type: String or Function
Default: 'src'

Define where to get the original image URL for viewing.

If it is a string, it should be one of the attributes of each image element. If it is a function, it should return a valid image URL.

For example:

<img src="picture.jpg?size=160">

new Viewer(image, {
  url(image) {
    return image.src.replace('?size=160', '');
  },
});

ready

Type: Function
Default: null

Shortcut of the ready event.

show

Type: Function
Default: null

Shortcut of the show event.

shown

Type: Function
Default: null

Shortcut of the shown event.

hide

Type: Function
Default: null

Shortcut of the hide event.

hidden

Type: Function
Default: null

Shortcut of the hidden event.

view

Type: Function
Default: null

Shortcut of the view event.

viewed

Type: Function
Default: null

Shortcut of the viewed event.

move

Type: Function
Default: null

Shortcut of the move event.

moved

Type: Function
Default: null

Shortcut of the moved event.

rotate

Type: Function
Default: null

Shortcut of the rotate event.

rotated

Type: Function
Default: null

Shortcut of the rotated event.

scale

Type: Function
Default: null

Shortcut of the scale event.

scaled

Type: Function
Default: null

Shortcut of the scaled event.

zoom

Type: Function
Default: null

Shortcut of the zoom event.

zoomed

Type: Function
Default: null

Shortcut of the zoomed event.

play

Type: Function
Default: null

Shortcut of the play event.

stop

Type: Function
Default: null

Shortcut of the stop event.

⬆ back to top

Methods

All methods allow chain composition.

As there are some asynchronous processes when start the viewer, you should call a method only when it is available, see the following lifecycle:

new Viewer(image, {
  ready() {
    // 2 methods are available here: "show" and "destroy".
  },
  shown() {
    // 9 methods are available here: "hide", "view", "prev", "next", "play", "stop", "full", "exit" and "destroy".
  },
  viewed() {
    // All methods are available here except "show".
    this.viewer.zoomTo(1).rotateTo(180);
  }
});

show([immediate])

immediate (optional):
- Type: Boolean
- Default: false
- Indicates if show the viewer immediately or not.

Show the viewer.

Only available in modal mode.

hide([immediate])

immediate (optional):
- Type: Boolean
- Default: false
- Indicates if hide the viewer immediately or not.

Hide the viewer.

Only available in modal mode.

view([index])

index (optional):
- Type: Number
- Default: 0 (inherits from the initialViewIndex option)
- The index of the image for viewing

View one of the images with the image index. If the viewer is hidden, it will be shown first.

viewer.view(1); // View the second image

prev([loop=false])

loop (optional):
- Type: Boolean
- Default: false
- Indicate if turn to view the last one when it is the first one at present.

View the previous image.

next([loop=false])

loop (optional):
- Type: Boolean
- Default: false
- Indicate if turn to view the first one when it is the last one at present.

View the next image.

move(x[, y = x])

x:
- Type: Number
- The moving distance in the horizontal direction.
y (optional):
- Type: Number
- The moving distance in the vertical direction.
- If not present, its default value is x