Viewer.js

JavaScript image viewer.

HomepageViewer as jQuery plugin

Table of contents

FeaturesMainGetting startedKeyboard supportOptionsMethodsEventsNo conflictBrowser supportContributingVersioningLicense

Features

Supports optionsSupports methodsSupports eventsSupports touchSupports moveSupports zoomSupports rotationSupports scale (flip)Supports keyboardCross-browser support

Main

dist/ ├── viewer.css ( 8 KB) ├── viewer.min.css ( 7 KB) ├── viewer.js (60 KB) └── viewer.min.js (22 KB)

Getting started

Quick start

Four quick start options are available:

Download the latest release.Clone the repository: git clone https://github.com/fengyuanchen/viewerjs.git.Install with NPM: npm install viewerjs.Install with Bower: bower install fengyuanchen/viewerjs.

Installation

Include files:

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

Usage

Initialize with Viewer constructor:

Browser: window.ViewerCommonJS: var Viewer = require('viewer')NodeJS: var Viewer = require('viewerjs')(window) <!-- a block container is required --> <div> <img id="image" src="picture.jpg" alt="Picture"> </div> <div> <ul id="images"> <li><img src="picture.jpg" alt="Picture"></li> <li><img src="picture-2.jpg" alt="Picture 2"></li> <li><img src="picture-3.jpg" alt="Picture 3"></li> </ul> </div> // View one image var viewer = new Viewer(document.getElementById('image'), options); // View some images var viewer = new Viewer(document.getElementById('images'), options);

Keyboard support

Only available in modal mode.

Esc: Exit full screen 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).

inline

Type: BooleanDefault: false

Enable inline mode.

button

Type: BooleanDefault: true

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

navbar

Type: Boolean or NumberDefault: trueOptions: 0 or false: hide the navbar1 or true: show the navbar2: show the navbar only when screen width great then 768 pixels3: show the navbar only when screen width great then 992 pixels4: show the navbar only when screen width great then 1200 pixels

Specify the visibility of the navbar.

title

Type: Boolean or NumberDefault: trueOptions: 0 or false: hide the title1 or true: show the title2: show the title only when screen width great then 768 pixels3: show the title only when screen width great then 992 pixels4: show the title only when screen width great then 1200 pixels

Specify the visibility of the title (the current image's name and dimensions).

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

toolbar

Type: Boolean or NumberDefault: trueOptions: 0 or false: hide the toolbar1 or true: show the toolbar2: show the toolbar only when screen width great then 768 pixels3: show the toolbar only when screen width great then 992 pixels4: show the toolbar only when screen width great then 1200 pixels

Specify the visibility of the toolbar.

tooltip

Type: BooleanDefault: true

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

movable

Type: BooleanDefault: true

Enable to move the image.

zoomable

Type: BooleanDefault: true

Enable to zoom the image.

rotatable

Type: BooleanDefault: true

Enable to rotate the image.

scalable

Type: BooleanDefault: true

Enable to scale the image.

transition

Type: BooleanDefault: true

Enable CSS3 Transition for some special elements.

fullscreen

Type: BooleanDefault: true

Enable to request full screen when play.

Requires the browser supports Full Screen API.

keyboard

Type: BooleanDefault: true

Enable keyboard support.

interval

Type: NumberDefault: 5000

Define interval of each image when playing.

zoomRatio

Type: NumberDefault: 0.1

Define the ratio when zoom the image by wheeling mouse.

minZoomRatio

Type: NumberDefault: 0.01

Define the min ratio of the image when zoom out.

maxZoomRatio

Type: NumberDefault: 100

Define the max ratio of the image when zoom in.

zIndex

Type: NumberDefault: 2015

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

zIndexInline

Type: NumberDefault: 0

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

url

Type: String or FunctionDefault: '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 will be called on each image and should return a valid image URL.

build

Type: FunctionDefault: null

A shortcut of the "build" event.

built

Type: FunctionDefault: null

A shortcut of the "built" event.

show

Type: FunctionDefault: null

A shortcut of the "show" event.

shown

Type: FunctionDefault: null

A shortcut of the "shown" event.

hide

Type: FunctionDefault: null

A shortcut of the "hide" event.

hidden

Type: FunctionDefault: null

A shortcut of the "hidden" event.

view

Type: FunctionDefault: null

A shortcut of the "view" event.

viewed

Type: FunctionDefault: null

A shortcut of the "viewed" 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, { built: function () { // 2 methods are available here: "show" and "destroy". }, shown: function () { // 9 methods are available here: "hide", "view", "prev", "next", "play", "stop", "full", "exit" and "destroy". }, viewed: function () { // All methods are available here except "show". this.viewer.zoomTo(1).rotateTo(180); } });

show()

Show the viewer.

Only available in modal mode.

hide()

hide the viewer.

Only available in modal mode.

view([index])

index (optional): Type: NumberDefault: 0The index of the image for viewing

View one of the images with image's index.

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

prev()

View the previous image.

next()

View the next image.

move(offsetX[, offsetY])

offsetX:

Type: NumberMoving size (px) in the horizontal direction

offsetY (optional):

Type: NumberMoving 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: NumberThe left value of the image

y (optional):

Type: NumberThe top value of the imageIf not present, its default value is x.

Move the image to an absolute point.

zoom(ratio[, hasTooltip])

ratio:

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

hasTooltip (optional):

Type: BooleanDefault: falseShow tooltip

Zoom the image with a relative ratio

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

zoomTo(ratio[, hasTooltip])

ratio:

Type: NumberRequires a positive number (ratio > 0)

hasTooltip (optional):

Type: BooleanDefault: falseShow 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: NumberRotate 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: NumberDefault: 1The scaling factor to apply on the abscissa of the imageWhen equal to 1 it does nothing.

scaleY (optional):

Type: NumberThe scaling factor to apply on the ordinate of the imageIf 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: NumberDefault: 1The scaling factor to apply on the abscissa of the imageWhen equal to 1 it does nothing

Scale the abscissa of the image.

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

scaleY(scaleY)

scaleY: Type: NumberDefault: 1The scaling factor to apply on the ordinate of the imageWhen equal to 1 it does nothing

Scale the ordinate of the image.

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

play()

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.

reset()

Reset the image to its initial state.

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.

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

build

This event fires when a viewer instance starts to build.

built

This event fires when a viewer instance has built.

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

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

viewed

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

⬆ back to top

No conflict

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