Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    viewerjspublic

    Viewer.js

    Build Status Downloads Version

    JavaScript image viewer.

    Table of contents

    Features

    • Supports 34 options
    • Supports 23 methods
    • Supports 7 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

    Include files:

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

    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>
    var viewer = new Viewer(document.getElementById('image'), {
      inline: true,
      viewed: function() {
        viewer.zoomTo(1);
      }
    });
     
    // View a list of images
    var viewer = 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).

    inline

    • Type: Boolean
    • Default: false

    Enable inline mode.

    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
    • Default: true
    • Options:
      • 0 or false: hide the title
      • 1 or true: 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

    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 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:

    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,
    }

    tooltip

    • Type: Boolean
    • Default: true

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

    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.

    transition

    • Type: Boolean
    • Default: true

    Enable CSS3 Transition for some special elements.

    fullscreen

    • Type: Boolean
    • Default: true

    Enable to request full screen when play.

    Requires the browser supports Full Screen API.

    keyboard

    • Type: Boolean
    • Default: true

    Enable keyboard support.

    backdrop

    • Type: Boolean or String
    • Default: true

    Enable a modal backdrop, specify static for a backdrop which doesn't close the modal on click.

    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.

    interval

    • Type: Number
    • Default: 5000

    The amount of time to delay between automatically cycling an image when playing.

    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).

    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.

    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.

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

    container

    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(images, {
      filter(image) {
        return image.complete;
      },
    });

    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.

    ⬆ 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: 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([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
      • 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.

    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.

    var viewer;
     
    image.addEventListener('viewed', function () {
      console.log(this.viewer === viewer);
      // -> true
    }, false);
     
    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.

    ⬆ 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

    install

    npm i viewerjs

    Downloadslast 7 days

    1,783

    version

    1.0.0

    license

    MIT

    repository

    github.com

    last publish

    collaborators

    • avatar