JS Plugins JavaScript
On branch current
Latest: ???/cur
Running: 6f9b46a (v1.9.12)
??? commits behind


Activate image-viewer.js like this:



Pass in options like this:

  optionName: optionValue

Or put them on the element as data attributes:


At minimum you need image with a string or images with an array.

controlsObjectSee below.
controls.zoomToActualSize.iconStringfa fa-expandContains the controls (their names and icons) that will display on the image viewer. Leave out controls to exclude them from displaying.
controls.zoomToActualSize.nameStringActual SizeName to use for the zoom to actual size button.
controls.fitToContainer.iconStringfa fa-compressClass for the icon to use for the fit to container button.
controls.fitToContainer.nameStringFitName to use for the fit to container button
controls.pan.iconUpStringfa fa-angle-upClass for the icon to use for the pan up button.
controls.pan.iconDownStringfa fa-angle-downClass for the icon to use for the pan down button.
controls.pan.iconLeftStringfa fa-angle-leftClass for the icon to use for the pan left button.
controls.pan.iconRightStringfa fa-angle-rightClass for the icon to use for the pan right button.
controls.zoomFactor.nameStringZoom FactorName to use for the zoom factor text box.
controls.zoomIn.iconStringfa fa-search-plusClass for the icon to use for the zoom in button.
controls.zoomIn.nameStringZoom InName to use for the zoom in button.
controls.zoomIn.repeatBooleantrueWhether to keep zooming in as long as the user holds down the button.
controls.zoomOut.iconStringfa fa-search-minusClass for the icon to use for the zoom out button.
controls.zoomOut.nameStringZoom OutName to use for the zoom out button.
controls.zoomOut.repeatBooleantrueWhether to keep zooming out as long as the user holds down the button.
controls.rotateFactor.nameStringRotate FactorName to use for the rotate factor text box.
controls.rotateLeft.iconStringfa fa-rotate-leftClass for the icon to use for the rotate left button.
controls.rotateLeft.nameStringRotate LeftName to use for the rotate left button.
controls.rotateLeft.repeatBooleanundefinedWhether to keep rotating left as long as the user holds down the button.
controls.rotateRight.iconStringfa fa-rotate-rightClass for the icon to use for the rotate right button.
controls.rotateRight.nameStringRotate RightName to use for the rotate right button.
controls.rotateRight.repeatBooleanundefinedWhether to keep rotating right as long as the user holds down the button.
controls.focus.iconStringfa fa-searchClass for the icon to use for the focus button.
controls.focus.onNameStringFocus: OnName to use for the focus button when it's on.
controls.focus.offNameStringFocus: OffName to use for the focus button when it's off.
showControlsBooleantrueWhether to start with the controls hidden.
imagesArray.<String>[]Images to load into the viewer.
imageStringundefinedThe image to load into the viewer. This is used only if images is not included.
currentImageNumber0Index of the current image. Setting this allows you to decide which image first displays.
spinnerClassStringfa fa-spin fa-spinnerClass to use for the spinner icon.
missingMessageStringImage does not exist!What to display if the image does not exist.
noneMessageStringNo images to displayWhat to display if no images are passed in.
focusBoxesArray.<Object>[]Focus boxes to display after the image loads. The coordinates should be in relation to the image, not the canvas.
focusCloseIconStringfa fa-closeClose icon for focus boxes.
focusMinSizeNumber20Minimum allowed size of a focus box (only applies while dragging).
focusOpacityNumber0.5Opacity of the overlay when focusing.
absoluteFocusBoxesBooleanfalseSuppose you had a focus box at (10, 10). If this is set to true, the focus box will always be at (10,10) in relation to the image no matter how it is rotated.
allowFocusDragBooleantrueWhether you can drag and create focus boxes.
focusMaxNumber1Maximum number of focus boxes you can have.
panFactorNumber10How much to pan with each step.
rotationFactorNumber90How much to rotate with each step. Valid values are 1 through 359.
zoomFactorNumber0.1How much to zoom with each step. Valid values are 0.1 through 1.
capMaximumZoomBooleantrueWhether to cap the maximum zoom to the image size.
capMinimumZoomBooleantrueWhether to cap the minimum zoom to the canvas size.
loadZoomNumber0At what size the image should load. This is a percentage of the original image size. Valid values are 0 through 1.
loadPositionStringcenterWhere to put the image on load. Only takes effect if the image does not fit on the canvas. Valid values are top or center.
rotationsArray.<Number>[]Holds rotation values for images.
loadRotationNumberundefinedWhat rotation the images should load with. This is used only if rotations is not included.
keyCodesObjectContains key codes for controlling the image viewer via the keyboard. When in a text field, you must also press CTRL or ALT for these keys to work (so that they don't override your typing). Leave out controls to disable them.
keycodes.closeFocusBoxArray.<Number>[27]The escape key closes focus boxes by default.
keycodes.panLeftArray.<Number>[37]The left arrow key pans left by default.
keycodes.panUpArray.<Number>[38]The up arrow key pans up by default.
keycodes.panRightArray.<Number>[39]The right arrow key pans right by default.
keycodes.panDownArray.<Number>[40]The down arrow key pans down by default.
keycodes.zoomOutArray.<Number>[189, 173]The minus key zooms out by default. Firefox uses 173 for the minus key.
keycodes.zoomInArray.<Number>[187, 61]The equals/plus key zooms in by default. Firefox uses 61 for the equals/plus key.
keycodes.rotateLeftArray.<Number>[76]The l key rotates left by default.
keycodes.rotateRightArray.<Number>[82]The r key rotates right by default
keycodes.zoomToActualSizeArray.<Number>[65]The a key zooms to actual size by default.
keycodes.fitToContainerArray.<Number>[70]The f key fits to container by default.
keycodes.previousImageArray.<Number>[81]The q key goes to the previous image by default.
keycodes.nextImageArray.<Number>[87]The w key goes to the nextimage by default.
keycodes.toggleControlBarArray.<Number>[72]The h key shows and hides the control bar by default.
preloadBooleanfalseWhether to preload images.


Use events like this:

$viewer.on('viewer:rotated', function (event, data) {
  // Do something.

Events are "debounced", so they won't fire until the user has finished the action.

viewer:readyeventFires when the image viewer has finished loading.
viewer:zoomedevent, imageDataFires when the image zooms in or out.
viewer:movedevent, imageDataFires when the image pans in any direction.
viewer:rotatedevent, imageDataFires when the image rotates left or right.
viewer:resizedeventFires when the viewer is resized due to the window resizing.
viewer:changedevent, currentImageFires when the image changes.
focus:movedevent, focusDataFires when a focus box is moved.
focus:createdevent, focusDataFires when a focus box is created.
focus:deletedeventFires when a focus box is deleted.
controls:toggledevent, showingFires when the control bar is toggled.

These are the parameter descriptions:

imageDataObjectContains width, height, left, top, and rotation.
currentImageNumberIndex of the current image in the array of images.
focusDataObjectContains left, top, width, and height.
showingBooleanWhether the control bar is now showing or hiding.


Methods can be called like this:

$viewer.imageViewer('methodName', 'argument1', 'argument2');

You can also call reInit with new or changed options and it will intelligently do what it needs to do. Or grab the plugin instance from $.data and run with that.

The most useful methods are probably:


Switches to the image you specify.

positionNumberPosition of the image to show.

addNewFocusBox(left, top, width, height, center)

Creates a new focus box at the coordinates you specify.

leftNumberLeft of the focus box.
topNumberTop of the focus box.
widthNumberWidth of the focus box.
heightNumberHeight of the focus box.
centerNumberWhether to move the viewer to center on the new focus box.


Closes the focus box you specify (leave empty to close the current focus box).

indexNumberIndex of the focus box to close.