Viewer.js

• 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

• options (optional)

Alternatively, you may use Viewer.create(element[, 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 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.

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

button

• Type: Boolean
• Default: true

navbar

• Type: Boolean or Number or String or Object
• Default: true
• Options:

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:

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:

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:

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

container

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

Only available when the inline option is set to false.

filter

• Type: Function
• Default: null

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

Requires the browser supports Fullscreen API.

inheritedAttributes

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

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

initialCoverage

• Type: Number
• Default: 0.9

initialViewIndex

• Type: Number
• Default: 0

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

inline

• Type: Boolean
• Default: false

autoplay

• Type: Boolean
• Default: true

interval

• Type: Number
• Default: 5000

keyboard

• Type: Boolean
• Default: true

focus

• Type: Boolean
• Default: true

Requires the keyboard option set to true.

loading

• Type: Boolean
• Default: true

loop

• Type: Boolean
• Default: true

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

minWidth

• Type: Number
• Default: 200

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

minHeight

• Type: Number
• Default: 100

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

movable

• Type: Boolean
• Default: true

magnifier

• Type: Boolean or Object
• Default: false
• Options:

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

rotateOnGesture

• Type: Boolean
• Default: true

rotateOnTouch

• Type: Boolean
• Default: true

scalable

• Type: Boolean
• Default: true

zoomable

• Type: Boolean
• Default: true

zoomOnGesture

• Type: Boolean
• Default: true

zoomOnTouch

• Type: Boolean
• Default: true

zoomOnWheel

• Type: Boolean | String
• Default: true

Set to a modifier key name (ctrl, shift, alt, meta), or a combination joined with + (e.g. ctrl+shift), to only zoom when the given modifier key(s) are held down while wheeling. Otherwise, wheeling falls back to sliding when slideOnWheel is enabled.

slideOnTouch

• Type: Boolean
• Default: true

slideOnWheel

• Type: Boolean | String
• Default: true

Set to a modifier key name (ctrl, shift, alt, meta), or a combination joined with + (e.g. ctrl+shift), to only slide when the given modifier key(s) are held down while wheeling.

Takes effect over the navbar, and also over the rest of the viewer when zoomOnWheel doesn't take effect for that wheel event.

toggleOnDblclick

• Type: Boolean
• Default: true

In other words, call the toggle method automatically when the image is double-clicked.

Requires dblclick event support.

tooltip

• Type: Boolean
• Default: true

transition

• Type: Boolean or Object
• Default: true

When passing an object, set a supported action to false to disable only its transition. The supported actions are show, hide, view, move, zoom, rotate, scale, play, and tooltip.

new Viewer(image, {
  transition: {
    hide: false,
    view: false,
    zoom: false,
  },
});

zIndex

• Type: Number
• Default: 2015

zIndexInline

• Type: Number
• Default: 0

zoomRatio

• Type: Number
• Default: 0.1

minZoomRatio

• Type: Number or Function
• Default: 0.01

If it is a function, it receives the current image and image data, and should return the minimum ratio:

new Viewer(image, {
  minZoomRatio(image, imageData) {
    return imageData.naturalWidth > 2000 ? 0.1 : 0.01;
  },
});

maxZoomRatio

• Type: Number or Function
• Default: 100

If it is a function, it receives the current image and image data, and should return the maximum ratio:

new Viewer(image, {
  maxZoomRatio(image, imageData) {
    return imageData.naturalWidth > 2000 ? 2 : 10;
  },
});

url

• Type: String or Function
• Default: 'src'

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

show

• Type: Function
• Default: null

shown

• Type: Function
• Default: null

hide

• Type: Function
• Default: null

hidden

• Type: Function
• Default: null

view

• Type: Function
• Default: null

viewed

• Type: Function
• Default: null

move

• Type: Function
• Default: null

moved

• Type: Function
• Default: null

rotate

• Type: Function
• Default: null

rotated

• Type: Function
• Default: null

scale

• Type: Function
• Default: null

scaled

• Type: Function
• Default: null

zoom

• Type: Function
• Default: null

zoomed

• Type: Function
• Default: null

play

• Type: Function
• Default: null

playing

• Type: Function
• Default: null

stop

• Type: Function
• Default: null

⬆ back to top

Methods

All methods support chain composition.

As there are some asynchronous processes when starting 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):

Show the viewer.

Only available in modal mode.

hide([immediate])

• immediate (optional):

Hide the viewer.

Only available in modal mode.

view([index])

• index (optional):

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

View the previous image.

next([loop=false])

• loop (optional):

View the next image.

move(x[, y = x])

• x:

• y (optional):

Move the image with relative offsets.

viewer.move(1);
viewer.move(-1, 0); // Move left
viewer.move(1, 0);  // Move right
viewer.move(0, -1); // Move up
viewer.move(0, 1);  // Move down

moveTo(x[, y = x])

• x:

• y (optional):

Move the image to an absolute point.

rotate(degree)

• degree:

Rotate the image with a relative degree.

viewer.rotate(90);
viewer.rotate(-90);

rotateTo(degree)

• degree:

Rotate the image to an absolute degree.

viewer.rotateTo(0); // Reset to zero degree
viewer.rotateTo(360); // Rotate a full round

scale(scaleX[, scaleY])

• scaleX:

• scaleY (optional):

Scale the image.

viewer.scale(-1); // Flip both horizontal and vertical
viewer.scale(-1, 1); // Flip horizontal
viewer.scale(1, -1); // Flip vertical

scaleX(scaleX)

• scaleX:

Scale the abscissa of the image.

viewer.scaleX(-1); // Flip horizontal

scaleY(scaleY)

• scaleY:

Scale the ordinate of the image.

viewer.scaleY(-1); // Flip vertical

zoom(ratio[, showTooltip[, pivot]])

• ratio:

• showTooltip (optional):

• pivot (optional):

Zoom the image with a relative ratio

viewer.zoom(0.1);
viewer.zoom(-0.1);

zoomTo(ratio[, showTooltip[, pivot]])

• ratio:

• showTooltip (optional):

• pivot (optional):

Zoom the image to an absolute ratio.

viewer.zoomTo(0); // Zoom to zero size (0%)
viewer.zoomTo(1); // Zoom to natural size (100%)
// Zoom to 50% from the center of the window.
viewer.zoomTo(0.5, false, {
  x: window.innerWidth / 2,
  y: window.innerHeight / 2,
});

play([fullscreen])

• fullscreen (optional):

Play the images.

stop()

Stop play.

full()

Enter the modal mode.

Only available in inline mode.

exit()

Exit the modal mode.

Only available in inline mode.

tooltip()

Show the current ratio of the image by percentage.

Requires the tooltip option set to true.

toggle()

Toggle the image size between its current size and natural size.

Used by the toggleOnDblclick option.

reset()

Reset the image to its initial state.

update([options])

Update the viewer instance when the source images changed (added, removed, or sorted), or update the options while the viewer is open.

If you load images dynamically (with XMLHTTPRequest), you can use this method to add the new images to the viewer instance.

viewer.update({
  slideOnTouch: false,
});

destroy()

Destroy the viewer and remove the instance.

⬆ back to top

Static Methods

create(element[, options])

Create a new Viewer instance without using the new operator.

const viewer = Viewer.create(image, {
  inline: true,
});

setDefaults(options)

Change the global default options for subsequently created Viewer instances. Instance options override these defaults.

Viewer.setDefaults({
  inline: true,
});

noConflict

If you have to use another viewer with the same namespace, call the Viewer.noConflict static method to revert to it.

<script src="other-viewer.js"></script>
<script src="viewer.js"></script>
<script>
  Viewer.noConflict();
  // Code that uses other Viewer can follow here.
</script>

⬆ back to top

Events

All events can access the viewer instance with this.viewer in its handler.

Be careful to use these events with other components which have the same event names, e.g.: Bootstrap's modal.

let viewer;
image.addEventListener('viewed', function () {
  console.log(this.viewer === viewer);
  // > true
});
viewer = new Viewer(image);

ready

• event.bubbles: true
• event.cancelable: true
• event.detail: null

In modal mode, this event will not be triggered until you click on one of the images.

show

• event.bubbles: true
• event.cancelable: true
• event.detail.originalEvent:

This event fires when the viewer modal starts to show.

Only available in modal mode.

shown

• event.bubbles: true
• event.cancelable: true
• event.detail: the same as the show event.

Only available in modal mode.

hide

• event.bubbles: true
• event.cancelable: true
• event.detail.originalEvent:

This event fires when the viewer modal starts to hide.

Only available in modal mode.

hidden

• event.bubbles: true
• event.cancelable: false
• event.detail: the same as the hide event.

Only available in modal mode.

view

• event.bubbles: true
• event.cancelable: true
• event.detail.index:

• event.detail.image:

• event.detail.originalImage:

• event.detail.originalEvent:

This event fires when a viewer starts to show (view) an image.

viewed

• event.bubbles: true
• event.cancelable: false
• event.detail: the same as the view event.

move

• event.bubbles: true
• event.cancelable: true
• event.detail.x:

• event.detail.y:

• event.detail.oldX:

• event.detail.oldY:

• event.detail.originalEvent:

This event fires when a viewer starts to move an image.

moved

• event.bubbles: true
• event.cancelable: false
• event.detail: the same as the move event.

rotate

• event.bubbles: true
• event.cancelable: true
• event.detail.degree:

• event.detail.oldDegree:

• event.detail.originalEvent:

This event fires when a viewer starts to rotate an image.

rotated

• event.bubbles: true
• event.cancelable: false
• event.detail: the same as the rotate event.

scale

• event.bubbles: true
• event.cancelable: true
• event.detail.scaleX:

• event.detail.scaleY:

• event.detail.oldScaleX:

• event.detail.oldScaleY:

• event.detail.originalEvent:

This event fires when a viewer starts to scale an image.

scaled

• event.bubbles: true
• event.cancelable: false
• event.detail: the same as the scale event.

zoom

• event.bubbles: true
• event.cancelable: true
• event.detail.ratio:

• event.detail.oldRatio:

• event.detail.originalEvent:

This event fires when a viewer starts to zoom (in or out) an image.

zoomed

• event.bubbles: true
• event.cancelable: false
• event.detail: the same as the zoom event.

play

• event.bubbles: true
• event.cancelable: true
• event.detail.originalEvent:

This event fires when the viewer starts to play.

You can abort the playing process by calling event.preventDefault().

playing

• event.bubbles: true
• event.cancelable: true
• event.detail.index:

• event.detail.image:

• event.detail.originalImage:

• event.detail.originalEvent:

This event fires when a viewer starts to play (cycle) an image.

You can abort the cycling process by calling event.preventDefault().

stop

• event.bubbles: true
• event.cancelable: true
• event.detail.originalEvent:

This event fires when the viewer starts to stop.

You can abort the stopping process by calling event.preventDefault().

⬆ back to top

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Opera (latest)
• Edge (latest)
• Internet Explorer 9+

Contributing

Please read through our contributing guidelines.

Versioning

Maintained under the Semantic Versioning guidelines.

License

MIT © Chen Fengyuan

⬆ back to top