Viewer.js

JavaScript image viewer.

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

Table of contents

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

Features

• Supports 39 options
• Supports 23 methods
• Supports 9 events
• Supports modal and inline modes
• Supports touch
• Supports move
• Supports zoom
• Supports rotation
• Supports scale (flip)
• Supports keyboard
• Cross-browser support

Main

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>

// 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);
  },
});

// View a list of images
const gallery = new Viewer(document.getElementById('images'));

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.
• ←: 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 a modal backdrop, specify static for a backdrop which doesn't 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 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 keys: "zoomIn", "zoomOut", "oneToOne", "reset", "prev", "play", "next", "rotateLeft", "rotateRight", "flipHorizontal" and "flipVertical".
  • Available 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,
  },
});

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

The container to put the viewer in 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).

For example:

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

fullscreen

• Type: Boolean
• Default: true

Enable to request full screen when play.

Requires the browser supports Full Screen API.

initialViewIndex

• Type: Number
• Default: 0

Define the initial index of 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.

loading

• Type: Boolean
• Default: true

Indicate if show a loading spinner when load image or not.

loop

• Type: Boolean
• Default: true

Indicate if enable 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.

zoomable

• Type: Boolean
• Default: true

Enable to zoom the image.

rotatable

• Type: Boolean
• Default: true

Enable to rotate the image.

scalable

• Type: Boolean
• Default: true

Enable to scale the image.

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 zoom in or zoom 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 viewer in modal mode.

zIndexInline

• Type: Number
• Default: 0

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

zoomRatio

• Type: Number
• Default: 0.1

Define the ratio when zoom the image by wheeling mouse.

minZoomRatio

• Type: Number
• Default: 0.01

Define the min ratio of the image when zoom out.

maxZoomRatio

• Type: Number
• Default: 100

Define the max ratio of the image when zoom 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

A shortcut of the ready event.

show

• Type: Function
• Default: null

A shortcut of the show event.

shown

• Type: Function
• Default: null

A shortcut of the shown event.

hide

• Type: Function
• Default: null

A shortcut of the hide event.

hidden

• Type: Function
• Default: null

A shortcut of the hidden event.

view

• Type: Function
• Default: null

A shortcut of the view event.

viewed

• Type: Function
• Default: null

A shortcut of the viewed event.

zoom

• Type: Function
• Default: null

A shortcut of the zoom event.

zoomed

• Type: Function
• Default: null

A shortcut of the zoomed 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 image's index. If the viewer is not shown, will show the viewer 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(offsetX[, offsetY])

• offsetX:

  • Type: Number
  • Moving size (px) in the horizontal direction

• offsetY (optional):

  • Type: Number
  • Moving size (px) in the vertical direction.
  • If not present, its default value is offsetX

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:

  • Type: Number
  • The left value of the image

• y (optional):

  • Type: Number
  • The top value of the image
  • If not present, its default value is x.

Move the image to an absolute point.

zoom(ratio[, hasTooltip])

• ratio:

  • Type: Number
  • Zoom in: requires a positive number (ratio > 0)
  • Zoom out: requires a negative number (ratio < 0)

• hasTooltip (optional):

  • Type: Boolean
  • Default: false
  • Show tooltip

Zoom the image with a relative ratio

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

zoomTo(ratio[, hasTooltip])

• ratio:

  • Type: Number
  • Requires a positive number (ratio > 0)

• hasTooltip (optional):

  • Type: Boolean
  • Default: false
  • Show tooltip

Zoom the image to an absolute ratio.

viewer.zoomTo(0); // Zoom to zero size (0%)
viewer.zoomTo(1); // Zoom to natural size (100%)

rotate(degree)

• degree:
  • Type: Number
  • Rotate right: requires a positive number (degree > 0)
  • Rotate left: requires a negative number (degree < 0)

Rotate the image with a relative degree.

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

rotateTo(degree)

• degree:
  • Type: Number

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:

  • Type: Number
  • Default: 1
  • The scaling factor to apply on the abscissa of the image
  • When equal to 1 it does nothing.

• scaleY (optional):

  • Type: Number
  • The scaling factor to apply on the ordinate of the image
  • If not present, its default value is scaleX.

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:
  • Type: Number
  • Default: 1
  • The scaling factor to apply on the abscissa of the image
  • When equal to 1 it does nothing

Scale the abscissa of the image.

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

scaleY(scaleY)

• scaleY:
  • Type: Number
  • Default: 1
  • The scaling factor to apply on the ordinate of the image
  • When equal to 1 it does nothing

Scale the ordinate of the image.

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

play([fullscreen])

• fullscreen (optional):
  • Type: Boolean
  • Default: false
  • Indicate if request fullscreen or not.

Play the images.

stop()

Stop play.

full()

Enter modal mode.

Only available in inline mode.

exit()

Exit modal mode.

Only available in inline mode.

tooltip()

Show the current ratio of the image with percentage.

Requires the tooltip option set to true.

toggle()

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

Used by the toggleOnDblclick option.

reset()

Reset the image to its initial state.

update()

Update the viewer instance when the source images changed (added, removed or sorted).

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

destroy()

Destroy the viewer and remove the instance.

⬆ back to top

Events

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

Be careful to use these events in other component which has 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

This event fires when a viewer instance is ready for viewing.

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

show

This event fires when the viewer modal starts to show.

Only available in modal mode.

shown

This event fires when the viewer modal has shown.

Only available in modal mode.

hide

This event fires when the viewer modal starts to hide.

Only available in modal mode.

hidden

This event fires when the viewer modal has hidden.

Only available in modal mode.

view

• event.detail.originalImage:

  • Type: HTMLImageElement
  • The original image.

• event.detail.index:

  • Type: Number
  • The index of the original image.

• event.detail.image:

  • Type: HTMLImageElement
  • The current image (a clone of the original image).

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

viewed

• event.detail: the same as the view event.

This event fires when a viewer has shown (viewed) an image.

zoom

• event.detail.originalEvent:

  • Type: Event
  • Options: wheel, touchmove.

• event.detail.oldRatio:

  • Type: Number
  • The old (current) ratio of the image.

• event.detail.ratio:

  • Type: Number
  • The new (next) ratio of the image (imageData.width / imageData.naturalWidth).

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

zoomed

• event.detail: the same as the zoom event.

This event fires when a viewer has zoomed (in or out) an image.

⬆ back to top

No conflict

If you have to use other viewer with the same namespace, just 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>

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

Changelog

next

• Escape all strings that use in HTML for better security (#269).

1.3.3 (Apr 6, 2019)

• Fix unexpected modal exiting behavior when the mouse is pressed (#255).
• Abort image downloading when cancel viewing for better performance.

1.3.2 (Jan 24, 2019)

• Fix Document not active error when calling the exit method.
• Improve wheel event listening for better performance (#102).

1.3.1 (Dec 9, 2018)

• Emulate click (single tap) and double click (double tap) in touch devices to support backdrop and image zooming (#210).
• Ignore pointer events when not the primary button was pressed (#221).

1.3.0 (Oct 25, 2018)

• Add a new option: className (#209).
• Fix wrong click action when the target image is ignored by the filter option (#211)

1.2.1 (Oct 20, 2018)

• Improve viewer instance storage to avoid side effect.
• Fix parameter error of Object.assign in iOS devices.

1.2.0 (Jul 15, 2018)

• Add 2 new options: toggleOnDblclick (#173) and initialViewIndex (#183).
• Enhance the title option to support to customize title content (#54, #185).

1.1.0 (May 27, 2018)

• Add 2 new events: zoom and zoomed (#144).
• Make the touch zooming more smoother (#162).

1.0.1 (May 20, 2018)

• Add namespace to data attribute names (from data-* to data-viewer-*) to avoid side effect.
• Make sure the image data is a non-null object to avoid unexpected errors.
• Fix broken zoom feature in iOS browsers (#167).

1.0.0 (Apr 1, 2018)

• Add in browser checking to support to import in Node.js.
• Cancel update when there are no images when call the update method.

1.0.0-rc.1 (Mar 13, 2018)

• Fix the wrong image switching behavior in iOS browsers.
• Fix a TypeError in strict mode (#149).
• Fix type definitions issue of the show and hide methods.

1.0.0-rc (Mar 10, 2018)

• Add a new option: loading.
• Add type definitions file for TypeScript.
• Enhance the show, hide and play methods.
• Change the default value of loop option from false to true.

1.0.0-beta.2 (Feb 13, 2018)

• Add a new option: container.
• Recover the missing default value of the interval option (#133).

1.0.0-beta.1 (Dec 23, 2017)

• Add a new option: backdrop.

1.0.0-beta (Dec 12, 2017)

• Add style field to package.json.
• Fix the issue of NodeList deconstructing (#118).
• Fall back to document.documentElement if document.body is not existing (#120).

0.10.0 (Nov 5, 2017)

• Add a new option: loop.
• Enhance toolbar customization.

0.9.0 (Nov 4, 2017)

• Add a new option: filter.
• Enhance the prev and next methods (#47).
• Support to customize the layout of toolbar (#79).
• Disallow to show again if it had shown.

0.8.0 (Oct 8, 2017)

• Refactor - separate constants, simplify utilities, and so on.
• Stop play after exited fullscreen.
• Improve JSDoc.

0.7.2 (Aug 19, 2017)

• Ignore mouse down event when the viewer is hiding (#70).
• Fixed multiple active items in navbar (#75).

0.7.1 (May 14, 2017)

• Support to use Viewer in a modal (#39).

0.7.0 (Apr 30, 2017)

• Changed the main field value from dist/viewer.js (UMD) to dist/viewer.common.js (CommonJS).
• Added module and browser fields to package.json.
• Fixed an issue of touch zoom.

0.6.2 (Mar 4, 2017)

• Fixed the issue of touch and move problem (#63).

0.6.1 (Feb 18, 2017)

• Prevented the default behaviour of drag action (#63).

0.6.0 (Jan 24, 2017)

• Ported JavaScript code to ECMAScript 6.
• Ported CSS code to CSSNext.

0.5.1 (Jan 2, 2017)

• Improved event handler for Pointer Events.

0.5.0 (July 22, 2016)

• Improve modal opening and closing.
• Remove build event.
• Rename built event to ready.
• Fixed a bug of data-* attributes setting and getting (#33).

0.4.0 (Mar 20, 2016)

• Added some properties to "event.detail" of the "view" and "viewed" events.

0.3.3 (Mar 19, 2016)

• Fix the issue of hiding wrong element in the "view" method (#19).

0.3.2 (Mar 11, 2016)

• Fix the parameters error on the "url" option when it is a function.

0.3.1 (Feb 2, 2016)

• Added tests.
• Ignored invalid class name.
• Re-render image only when viewed.

0.3.0 (Jan 21, 2016)

• Add more available values to the "title", "toolbar" and "navbar" options.
• Support to toggle the visibility of title, toolbar and navbar between different screen widths.
• Exit fullscreen when stop playing.
• Fixed title not generated bug.

0.2.0 (Jan 1, 2016)

• Added "update" method for update image dynamically.
• Hides title and toolbar on small screen (width < 768px).

0.1.1 (Dec 28, 2015)

• Supports to zoom from event triggering point.
• Optimized "toggle" method.
• Fixed a bug of the index of viewing image.

0.1.0 (Dec 24, 2015)

• Supports 2 modes: "modal" (default), "inline"
• Supports 30 options: "inline", "button", "navbar", "title", "toolbar", "tooltip", "movable", "zoomable", "rotatable", "scalable", "transition", "fullscreen", "keyboard", "interval", "minWidth", "minHeight", "zoomRatio", "minZoomRatio", "maxZoomRatio", "zIndex", "zIndexInline", "url", "build", "built", "show", "shown", "hide", "hidden", "view", "viewed"
• Supports 22 methods: "show", "hide", "view", "prev", "next", "move", "moveTo", "zoom", "zoomTo", "rotate", "rotateTo", "scale", "scaleX", "scaleY", "play", "stop", "full", "exit", "tooltip", "toggle", "reset", "destroy"
• Supports 8 events: "build", "built", "show", "shown", "hide", "hidden", "view", "viewed"