Fork me on GitHub
Ignitersworld Lab

ImageViewer

A zooming and panning plugin inspired by google photos for your web images.

ImageViewer

ImageViewer is a zooming and panning plugin inspired by google photos for your web images. It provides three different modes to meet your exact need.

Why ImageViewer

  • Smooth dragging and panning images.
  • Support touch devices.
  • Double tap to zoom in/zoom out.
  • Pinch in / pinch out to zoom in/out.
  • Snap view for easier panning and zooming experience.
  • Allow quick display of loaded image then loading high resolution image asynchronously.
  • Exposed API to control zoom programmatically.
How to use?
Include jquery/zepto, imageviewer.js and imageviewer.css to your page.
    <link href="imageviewer.css"  rel="stylesheet" type="text/css" />
    <script src="jquery.js"></script> 
    <!-- or <script src="jquery.js"></script> -->
    <script src="imageviewer.js"></script>
Then you use one of the three modes to initialize ImageViewer.

Three different modes

Full-Screen Mode

Open viewer in full-screen mode. When you simply want to see the detail view of an image full-screen mode best suit you. Don’t pass the container and Image will open full-screen view.

                var viewer = ImageViewer(options); //options is optional parameter
                viewer.show('image1.png','hi-res-image1.png'); //second paramter is optional
            

Container Mode

When you want a custom layout for your viewer you should use container mode. This is most customizable way to show your viewer.

                    var viewer = ImageViewer('#container',options); //options is optional parameter
                    or
                    $('#container').ImageViewer(options);
                    var viewer = $('#container').data('ImageViewer');
                

You can define src and high-res-src attribute, so those images will be shown on the viewer by default.

                    
Or you can load image later through your instance
                    viewer.load('image1.png','hi-res-image1.png'); //second paramter is optional
                

Image Mode

If you simply want to convert images into a zoomable/pannable image you can use image mode.

                    var viewer = ImageViewer('#image',options); //options is optional parameter
                    
                    or
                    
                    $('#image').ImageViewer(options);
                    var viewer = $('#container').data('ImageViewer');
                

You can define high-res-src attribute, so that high-resolution image will be loaded for zooming.

                    
                

Full Screen Mode

Click on a image to see it on full screen.

HTML

                <div id="image-gallery-1" class="cf">
                    <img src="assets/images/image_viewer/1.jpg" data-high-res-src="assets/images/image_viewer/1_big.jpg" alt="" class="gallery-items">
                    <img src="assets/images/image_viewer/2.jpg" data-high-res-src="assets/images/image_viewer/2_big.jpg" alt="" class="gallery-items">
                    <img src="assets/images/image_viewer/3.jpg" data-high-res-src="assets/images/image_viewer/3_big.jpg" alt="" class="gallery-items">
                    <img src="assets/images/image_viewer/4.jpg" data-high-res-src="assets/images/image_viewer/4_big.jpg" alt="" class="gallery-items">
                </div>
            

JS

                $(function () {
                    var viewer = ImageViewer();
                    $('.gallery-items').click(function () {
                        var imgSrc = this.src,
                            highResolutionImage = $(this).data('high-res-img');

                        viewer.show(imgSrc, highResolutionImage);
                    });
                });
            

Container Mode

HTML

                <div id="image-gallery-2">
                    <div class="image-container"></div>
                    <img src="assets/images/left.svg" class="prev"/>
                    <img src="assets/images/right.svg"  class="next"/>
                    <div class="footer-info">
                        <span class="current"></span>/<span class="total"></span>
                    </div>
                </div>    
            

JS

                //Example 2
                $(function () {
                    var images = [{
                        small : 'assets/images/image_viewer/1.jpg',
                        big : 'assets/images/image_viewer/1_big.jpg'
                    },{
                        small : 'assets/images/image_viewer/2.jpg',
                        big : 'assets/images/image_viewer/2_big.jpg'
                    },{
                        small : 'assets/images/image_viewer/3.jpg',
                        big : 'assets/images/image_viewer/3_big.jpg'
                    },{
                        small : 'assets/images/image_viewer/4.jpg',
                        big : 'assets/images/image_viewer/4_big.jpg'
                    }];

                    var curImageIdx = 1,
                        total = images.length;
                    var wrapper = $('#image-gallery-2'),
                        curSpan = wrapper.find('.current');
                    var viewer = ImageViewer(wrapper.find('.image-container'));

                    //display total count
                    wrapper.find('.total').html(total);

                    function showImage(){
                        var imgObj = images[curImageIdx - 1];
                        viewer.load(imgObj.small, imgObj.big);
                        curSpan.html(curImageIdx);
                    }

                    wrapper.find('.next').click(function(){
                         curImageIdx++;
                        if(curImageIdx > total) curImageIdx = 1;
                        showImage();
                    });

                    wrapper.find('.prev').click(function(){
                         curImageIdx--;
                        if(curImageIdx < 0) curImageIdx = total;
                        showImage();
                    });

                    //initially show image
                    showImage();
                });
            

Image Mode

HTML

                <div id="image-gallery-3" class="cf">
                    <img src="assets/images/image_viewer/1.jpg" data-high-res-src="assets/images/image_viewer/1_big.jpg" alt="" class="pannable-image">
                    <img src="assets/images/image_viewer/2.jpg" data-high-res-src="assets/images/image_viewer/2_big.jpg" alt="" class="pannable-image">
                </div>
            

JS

                //Example 3
                $(function () {
                    $('.pannable-image').ImageViewer();
                });
            

ImageViewer function

                var viewer = ImageViewer(container, options); //container and options both are options
            

Container is an optional parameter and can be selector string, jQuery object, DOM object. Options is the configuration for the plugin. ImageViewer returns a viewer instance through which you can call its methods.

Options

Syntax :
                var viewer = ImageViewer('#container',{
                    maxZoom : 400
                });
            
Option Allowed Value Default Description
zoomValue number in percentage 100 It defines the initial zoom value of an image.
maxZoom number in percentage 500 It defines maximum percentage you can zoom an image.
snapView boolean true Configuration to show/hide snap view.
refreshOnResize boolean true Defines wether to refresh the viewer on resize of window.
zoomOnMouseWheel boolean true Defines weather to allow zoom with mouse scroll or not.

Methods

zoom(zoomValue,point)

To zoom viewer through code.
percentageValue : zoom value in percentage.
point (optional): Point {x, y} which would act as center of zoom. If not defined, it will take center of container as the zooming point.

                viewer.zoom(300, {x:500, y: 500});
            

resetZoom()

Reset zoom to provided zoomValue through option

                viewer.resetZoom();
            

refresh()

Refresh the viewer

                viewer.refresh();
            

show(imgSrc, highResImg)

Show the full screen viewer(Note: only available when plugin is initialized in full screen mode).
imgSrc : image source to display in viewer.
highResImg (optional) : A high resoultion image source of the same image. Its good when you have a lower quality image already loaded and you to quickly show image on viewer and simultaneously load better quality image.

                viewer.show('image1.png','hi-res-image1.png');
            

hide()

Hide the full-screen viewer (Note: only available when plugin is initialized in full screen mode)

                viewer.hide();
            

load(imgSrc, highResImg)

Load an image or new image in viewer. Available on Full screen and Container mode.
imgSrc : image source to display in viewer.
highResImg (optional) : A high resoultion image source of the same image. Its good when you have a lower quality image already loaded and you to quickly show image on viewer and simultaneously load better quality image.

                viewer.load('image1.png','hi-res-image1.png');
            

destroy()

Destroy the plugin instance and unbind events. It returns null which should be assigned to viewer variable to completly free the memory.

                viewer = viewer.destroy();
            

Want to support and contribute to ImageViewer?

ImageViewer needs your contribution to become best of its kind. There are lot of things you can do to contribute and support plugin.

Author

This plugin is developed and maintained by me ( Sudhanshu Yadav ignitersworld.com/me ) . If you have any query you can contact me at sudhanshuyadav2@gmail.com.

You can also follow me on twitter and github Follow @s-yadav .

Check out my other open source work