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
Include files:
<link href="/path/to/viewer.css" rel="stylesheet">
<script src="/path/to/viewer.js"></script>
Initialize with Viewer constructor:
window.Viewervar Viewer = require('viewerjs')import Viewer from 'viewerjs'<!-- 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);
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.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).
BooleanfalseEnable inline mode.
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 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 pixelsSpecify the visibility of the navbar.
Boolean or Numbertrue0 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 pixelsSpecify the visibility of the title (the current image's name and dimensions).
The name comes from the
altattribute of an image element or the image name parsed from URL.
Boolean or Number or Objecttrue0 or false: hide the toolbar.1 or true: show the toolbar.2: show the toolbar only when screen width great then 768 pixels.3: show the toolbar only when screen width great then 992 pixels.4: show the toolbar only when screen width great then 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:
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,
}
BooleantrueShow the tooltip with image ratio (percentage) when zoom in or zoom out.
BooleantrueEnable to move the image.
BooleantrueEnable to zoom the image.
BooleantrueEnable to rotate the image.
BooleantrueEnable to scale the image.
BooleantrueEnable CSS3 Transition for some special elements.
BooleantrueEnable to request full screen when play.
Requires the browser supports Full Screen API.
BooleantrueEnable keyboard support.
BooleanfalseEnable loop viewing.
If the current image is the last one, then the next one to view is the first one, and vice versa.
Number5000Define interval of each image when playing.
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).
Number0.1Define the ratio when zoom the image by wheeling mouse.
Number0.01Define the min ratio of the image when zoom out.
Number100Define the max ratio of the image when zoom in.
Number2015Define the CSS z-index value of viewer in modal mode.
Number0Define the CSS z-index value of viewer in inline mode.
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 will be called on each image and should return a valid image URL.
FunctionnullFilter the images for viewing (should return true if the image is viewable).
For example:
new Viewer(images, {
filter(image) {
return image.complete;
},
});
FunctionnullA shortcut of the ready event.
FunctionnullA shortcut of the show event.
FunctionnullA shortcut of the shown event.
FunctionnullA shortcut of the hide event.
FunctionnullA shortcut of the hidden event.
FunctionnullA shortcut of the view event.
FunctionnullA shortcut of the viewed 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: 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 the viewer.
Only available in modal mode.
hide the viewer.
Only available in modal mode.
Number0View one of the images with image's index.
viewer.view(1); // View the second image
BooleanfalseView the previous image.
BooleanfalseView the next image.
offsetX:
NumberoffsetY (optional):
NumberoffsetXMove 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:
Numberleft value of the imagey (optional):
Numbertop value of the imagex.Move the image to an absolute point.
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%)
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
Play the images.
Stop play.
Enter modal mode.
Only available in inline mode.
Exit modal mode.
Only available in inline mode.
Show the current ratio of the image with percentage.
Requires the
tooltipoption set totrue.
Toggle the image size between its natural size and initial size.
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 in other component which has the same event names, e.g.: Bootstrap's modal.
var viewer;
image.addEventListener('viewed', function () {
console.log(this.viewer === viewer);
// -> true
}, false);
viewer = new Viewer(image);
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.
This event fires when the viewer modal starts to show.
Only available in modal mode.
This event fires when the viewer modal has shown.
Only available in modal mode.
This event fires when the viewer modal starts to hide.
Only available in modal mode.
This event fires when the viewer modal has hidden.
Only available in modal mode.
event.detail.originalImage:
HTMLImageElementevent.detail.index:
Numberevent.detail.image:
HTMLImageElementThis event fires when a viewer starts to show (view) an image.
view event.This event fires when a viewer has shown (viewed) an image.
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>
Please read through our contributing guidelines.
Maintained under the Semantic Versioning guidelines.
1.0.0-beta (Dec 12, 2017)
style field to package.json.document.documentElement if document.body is not existing (#120).FAQs
JavaScript image viewer.
The npm package viewerjs receives a total of 24,920 weekly downloads. As such, viewerjs popularity was classified as popular.
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
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
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.