JavaScript image viewer.
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)
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.
new Viewer(element[, options])
element
HTMLElementoptions (optional)
Object<!-- 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()`.
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.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).
Boolean or StringtrueEnable the modal backdrop, specify static for the backdrop that will not close the modal on click.
BooleantrueShow the button on the top-right of the viewer.
Boolean or Numbertrue0 or false: hide the navbar1 or true: show the navbar2: show the navbar only when the screen width is greater than 768 pixels3: show the navbar only when the screen width is greater than 992 pixels4: show the navbar only when the screen width is greater than 1200 pixelsSpecify the visibility of the navbar.
Boolean or Number or Function or Arraytrue0 or false: hide the title1 or true or Function or Array: show the title2: show the title only when the screen width is greater than 768 pixels3: show the title only when the screen width is greater than 992 pixels4: show the title only when the screen width is greater than 1200 pixelsFunction: customize the title content[Number, Function]: the first element indicate the visibility, the second element customize the title contentSpecify the visibility and the content of the title.
The name comes from the
altattribute 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})`]
});
Boolean or Number or Objecttrue0 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.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,
},
});
String''Custom class name(s) to add to the viewer's root element.
Element or String'body'Container to place the viewer in the modal mode.
Only available when the
inlineoption is set tofalse.
FunctionnullFilter 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
srcattribute set will be ignored by default.
BooleantrueEnable to request full screen when play.
Requires the browser supports Fullscreen API.
Array['crossOrigin', 'decoding', 'isMap', 'loading', 'referrerPolicy', 'sizes', 'srcset', 'useMap']Define the extra attributes to inherit from the original image.
Note that the basic attributes
srcandaltwill always inherit from the original image.
Number0Define the initial index of the image for viewing.
Also used as the default parameter value of the
viewmethod.
BooleanfalseEnable inline mode.
Number5000The amount of time to delay between automatically cycling an image when playing.
BooleantrueEnable keyboard support.
BooleantrueFocus the active item in the navbar when initialized.
Requires the
keyboardoption set totrue.
BooleantrueIndicate if showing a loading spinner when loading the image or not.
BooleantrueIndicate 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.
NumberDefine the minimum width of the viewer.
Only available in inline mode (set the
inlineoption totrue).
NumberDefine the minimum height of the viewer.
Only available in inline mode (set the
inlineoption totrue).
BooleantrueEnable to move the image.
BooleantrueEnable to rotate the image.
BooleantrueEnable to scale the image.
BooleantrueEnable to zoom the image.
BooleantrueEnable to zoom the current image by dragging on the touch screen.
BooleantrueEnable to zoom the image by wheeling the mouse.
BooleantrueEnable to slide to the next or previous image by swiping on the touch screen.
BooleantrueIndicate 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
dblclickevent support.
BooleantrueShow the tooltip with image ratio (percentage) when zooming in or zooming out.
BooleantrueEnable CSS3 Transition for some special elements.
Number2015Define the CSS z-index value of the viewer in modal mode.
Number0Define the CSS z-index value of the viewer in inline mode.
Number0.1Define the ratio when zooming the image by wheeling the mouse.
Number0.01Define the min ratio of the image when zooming out.
Number100Define the max ratio of the image when zooming in.
String or Function'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', '');
},
});
FunctionnullShortcut of the ready event.
FunctionnullShortcut of the show event.
FunctionnullShortcut of the shown event.
FunctionnullShortcut of the hide event.
FunctionnullShortcut of the hidden event.
FunctionnullShortcut of the view event.
FunctionnullShortcut of the viewed event.
FunctionnullShortcut of the move event.
FunctionnullShortcut of the moved event.
FunctionnullShortcut of the rotate event.
FunctionnullShortcut of the rotated event.
FunctionnullShortcut of the scale event.
FunctionnullShortcut of the scaled event.
FunctionnullShortcut of the zoom event.
FunctionnullShortcut of the zoomed event.
FunctionnullShortcut of the play event.
FunctionnullShortcut of the stop event.
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);
}
});
BooleanfalseShow the viewer.
Only available in modal mode.
BooleanfalseHide the viewer.
Only available in modal mode.
Number0 (inherits from the initialViewIndex option)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
BooleanfalseView the previous image.
BooleanfalseView the next image.
x:
Numbery (optional):
NumberxMove 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
x:
Numbery (optional):
Numberx.Move the image to an absolute point.
NumberRotate the image with a relative degree.
viewer.rotate(90);
viewer.rotate(-90);
NumberRotate the image to an absolute degree.
viewer.rotateTo(0); // Reset to zero degree
viewer.rotateTo(360); // Rotate a full round
scaleX:
Number11 it does nothing.scaleY (optional):
NumberscaleX.Scale the image.
viewer.scale(-1); // Flip both horizontal and vertical
viewer.scale(-1, 1); // Flip horizontal
viewer.scale(1, -1); // Flip vertical
Number11 it does nothingScale the abscissa of the image.
viewer.scaleX(-1); // Flip horizontal
Number11 it does nothingScale the ordinate of the image.
viewer.scaleY(-1); // Flip vertical
ratio:
NumberhasTooltip (optional):
BooleanfalseZoom the image with a relative ratio
viewer.zoom(0.1);
viewer.zoom(-0.1);
ratio:
NumberhasTooltip (optional):
BooleanfalseZoom the image to an absolute ratio.
viewer.zoomTo(0); // Zoom to zero size (0%)
viewer.zoomTo(1); // Zoom to natural size (100%)
BooleanfalsePlay the images.
Stop play.
Enter the modal mode.
Only available in inline mode.
Exit the modal mode.
Only available in inline mode.
Show the current ratio of the image by percentage.
Requires the
tooltipoption set totrue.
Toggle the image size between its natural size and initial size.
Used by the
toggleOnDblclickoption.
Reset the image to its initial state.
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 the viewer and remove the instance.
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);
truetruenullThis 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.
truetruenullThis event fires when the viewer modal starts to show.
Only available in modal mode.
truetruenullThis event fires when the viewer modal has shown.
Only available in modal mode.
truetruenullThis event fires when the viewer modal starts to hide.
Only available in modal mode.
truefalsenullThis event fires when the viewer modal has hidden.
Only available in modal mode.
truetrueNumberHTMLImageElementHTMLImageElementThis event fires when a viewer starts to show (view) an image.
truefalseview event.This event fires when a viewer has shown (viewed) an image.
truetrueNumberNumberNumberNumberEvent or nullpointermove, touchmove, and mousemove.This event fires when a viewer starts to move an image.
truefalsemove event.This event fires when a viewer has moved an image.
truetrueNumberNumberThis event fires when a viewer starts to rotate an image.
truefalserotate event.This event fires when a viewer has rotated an image.
truetrueNumberNumberNumberNumberThis event fires when a viewer starts to scale an image.
truefalsescale event.This event fires when a viewer has scaled an image.
truetrueNumberimageData.width / imageData.naturalWidth).NumberEvent or nullwheel, pointermove, touchmove, and mousemove.This event fires when a viewer starts to zoom (in or out) an image.
truefalsezoom event.This event fires when a viewer has zoomed (in or out) an image.
truetruenullThis event fires when the viewer starts to play.
You can abort the playing process by calling
event.preventDefault().
truetruenullThis event fires when the viewer starts to stop.
You can abort the stopping process by calling
event.preventDefault().
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>
Please read through our contributing guidelines.
Maintained under the Semantic Versioning guidelines.
FAQs
JavaScript image viewer.
We found that viewerjs demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.