imgin › Documentation

imgin.js is a javascript plugin for lazy-loading images. The plugin is extremely lightweight (1Kb minified) and is focused on performance and providing useful functionality beyond simple lazy loading.

Dependencies

updown.js requires jQuery 1.7+ to run.

Usage

While not a traditional jQuery plugin, imgin does rely on jQuery, so make sure you're calling the imgin() function within your $(document).ready() block.

HTML

To work properly, imgin requires that you add an attribute to your img tags in your HTML. By default, this attribute is data-imginsrc, but can be changed via the options object when imgin is initialized. This attribute must exist on any image you want imgin to lazy load and the value of the attribute should be the path to the image (just as you would write it in a normal image src attribute).

There are two important things to note about the HTML:

Your image tags should NOT include a normal src attribute. The src attribute will be created by imgin dynamically. Adding a src attribute is redundant and can impact performance since src attributes (even empty ones) trigger an HTTP request.
Your images should be manually assigned width and height (either in the img tag or via CSS). Without dimensions, the images will take up no space on the page until they load, meaning you'll get a lot of content jumping around as various images load.

Javascript

Once you have your HTML set up and have included the imgin JS file in your page, you can initialize the plugin by calling the imgin() function. The function takes an optional options object as its single argument. See below for more information on the options object.

1
2
3
4
5
// Sample JS
var opts = {
    // Set options here
}
imgin(opts);

CSS

There is no CSS required for imgin to run. However, adding CSS styles can make the experience much smoother. For example, using CSS transitions to fade the loaded images in can be a nice touch.

1
2
3
4
5
6
7
8
9
/* Unloaded images */
img[data-imginloaded="false"] { 
    opacity: 0; 
}
/* Loaded images */
img[data-imginloaded="true"] { 
    opacity: 1; 
    transition: opacity 1s; 
}

Data attributes

Upon initialization, all lazy-loadable images are given an attribute data-imginloaded. Initially, this attribute is set to false. When an image is loaded, the attribute is changed to true. This attribute makes for an easy way to target images via CSS or jQuery.

Return value

Calling imgin() returns an object which includes the public methods (see below).

The options object

The options object can set any of the following properties:

Property	Default	Description
offset	0	The offset in pixels outside the viewport (or inside with negative number) at which to begin lazy loading an image. E.g. a value of 100 would trigger loading on images once they got within 100px of the viewport.
lag	200	The delay (in milliseconds) to wait after the scroll event finishes before triggering a load cycle. If you find you are having performance problems (due to lots of images for example), you can increase this number to improve performance.
attr	data-imginsrc	The attribute on the image tag that will mark the image as lazy-loadable and will store the image path. Unless you have a good reason to change this, it is suggested that you leave the default. Note that, for performance reasons, once an image is loaded, this attribute is removed and that image is removed and imgin no longer recognizes that image as lazy-loadable.
onload	null	Callback function fired for each image when it finishes loading. The function passes a jQuery reference to the loaded image as its single parameter.

Public methods

imgin exposes public methods which are returned as an object to the imgin() function call. To utilize the public methods, simply capture the return in a variable and call the public methods as methods of that variable.

1
2
3
4
5
// Example of calling a public method
$(document).ready(function() {
    var myImgs = imgin();
    myImgs.force();
});

.refresh()

The refresh() method refreshes the array of lazy-loadable images that imgin stores internally. This is useful if you are dynamically adding more lazy-loadable images to the DOM. Calling refresh() will ensure that imgin is aware of these images.

.force()

The force() method forces all lazy-loadable images that have not been loaded to load immediately rather than waiting for them to enter the viewport. This only affects images that are currently recognized as lazy-loadable by imgin. If you want to add new images to the DOM and force load them, make sure you call refresh() first.