Get new jQuery plugins just once a week

×

Smarter-Images

FavoriteLoadingAdd to favorites

September 13, 2015

Smarter-Images | jQuery plugin for simple responsive images

Smarter-Images is an extremely easy to use jQuery plugin for responsive images using an external service.

Created by Mike Zarandona

Download

Example

Smarter-Images plugin

responsive images

SmarterImages

Images are dumb - make them smarter with flexible dynamic image replacement

Demo on CodePen.io

About

SmarterImages aims to be the most flexible dynamic image replacement jQuery plugin. Think CDN, but without the server.

The plugin watches the browser viewport width on load() and resize(), and when the zone changes the plugin rebuilds a new src URL. If the object in question is an <img/> element, it gets a new src; if the object in question is anything else (such as a <div/>) it will get an updated background-image style property.

Features

Inline Images and Placeholder.gif

To fire SmarterImages on inline <img/> elements, they are required to have both an src attribute and a data-si-src attribute. Even though the "real" src is stored inside data-si-src, without a "true" src the image won't load correctly. To get around this, the fastest-known solution named placeholder.gif is included - a 43byte 1px x 1px transparent GIF, more on that here. Please note that in some cases it's more appropriate for user experience to implement a "loading" graphic, like a nice FontAwesome animated icon.

Definitions: Breakpoints vs. Zones

This document will refer to terms such as "breakpoint" and "zone" - here's what they mean:

breakpoint
A pixel integer value at which the script will initiate an image swap. These markers encapsulate the zones. They're defined by passing in an array of integers to options.breakpoints.

zone
The range in which a breakpoint-specific sized image is visible. These are the areas between the breakpoints, and are automatically calculated.

breakpoints
|--------|-----------|-----------|-----------|-----------|-----------|---------->
0       360         480         768         1050        1300        1600

        0 (min)            1           2           3           4        5 (max)
|--------------------|-----------|-----------|-----------|-----------|---------->
zones


Processors

Processors are any services, CDNs, APIs, or custom functions which handle image sizing and/or serving. Additional options for processors are always welcome and appreciated, please open an issue with suggestions!

CloudImage.io

<cloudimage.io/> is the easiest way to resize, store, and deliver your images to your customers.     — http://cloudimage.io

To use CloudImage.io (paid service) set options.useCloudImageIO to true, and pass in your CloudImage.io URL prefix to options.cloudImageIO. That's it!

Custom Processor

To use any other custom setup, set options.useCustomURL to true and pass in a custom URL to options.customURL. Two replacement variables are available to help build the correct URL - check out the code examples section later in this document.

Custom Processor URL Replacement Variables

%%size%% This string will be replaced with the current breakpoint size dynamically.

Example: http://fakecdn.com/resize/%%size%%/http://example.com/path/to/myimage.png Output: http://fakecdn.com/resize/768/http://example.com/path/to/myimage.png

%%source%% This string will be replaced with the current image's source attribute (data-si-src).

Example: http://fakecdn.com/resize/768/%%source%% Output: http://fakecdn.com/resize/768/http://example.com/path/to/myimage.png

Placeholders

To use placeholders for mock-ups or testing purposes (for science), set options.usePlaceholders to true. Note that this will ignore the data-si-src option completely and will populate the targeted object(s) with placeholder images served from Placehold.it.


Options

Option Type Default Description
breakpoints array [360, 480, 768, 1050, 1300, 1600] Defines the breakpoints at which targeted images will be replaced.
upsizeOnly boolean false If true, images will only load larger sizes to reduce server calls; if false, images with load larger and smaller sizes.
maintainAspect boolean false If true, images will maintain their original width / height aspect ratio.
useCloudImageIO boolean false Switch to turn on / off the CloudImage.io image processor.
cloudImageIO string N/A CloudImage.io URL account prefix.
useCustomURL boolean false Switch to turn on / off the custom URL image processor.
customURL string N/A Custom image processor URL pattern.
usePlaceholders boolean false Turn on placeholder images for testing.
protocol string http:// Defines the protocol for the target image URLs (http://, https://, //).
logging boolean false Turns on / off console messages for debugging / testing.
onImgSwap function false Callback function which fires after each replacement.


Examples

Basic Examples

Inline Image

<!-- HTML -->
<img src="/path/to/placeholder.gif" data-si-src="http://example.com/image.png"></div>
// jQuery
// when the document is ready
$(document).ready(function() {

    // call SmarterImages
    $('img[data-si-src]').smarterImages();
});

Background Image

<!-- HTML -->
<div class="smarter-image" data-si-src="http://example.com/image.png"></div>
// jQuery
$('.smarter-image').smarterImages();

CloudImage.io Example

// jQuery
$('.smarter-image').smarterImages({
    useCloudImageIO: true,
    cloudImageIO: 'abcdef'
});

Custom URL Example

// jQuery
$('.resize-images').smarterImages({
    useCustomURL: true,
    customURL: 'http://fakecdn.com/resize/%%size%%/%%source%%'

Callback Function Example

$this is exposed so that each <img/> can be targeted individually.

thisBreakpoint holds the current zone's size, in pixels.

// jQuery
$('.fadein-imgs').smarterImages({
    useCloudImageIO: true,
    cloudImageIO: 'abcdef',

    onImgSwap: function($this, thisBreakpoint) {
        // your callback function code here
        // ...
    }
});

Kitchen Sink Example

    $('img[data-si-src]').smarterImages({
        // basic things
        breakpoints: [360, 480, 768, 1050, 1300, 1600],
        upsizeOnly: true,
        maintainAspect: false,

        // cloudimage.io setup
        useCloudImageIO: false,
        cloudImageIO: '',

        // custom url setup
        useCustomURL: false,
        customURL: '',

        // placeholders (for science)
        usePlaceholders: false,

        // nuts + bolts
        protocol: 'http://',
        logging: false,

        // callback function
        onImgSwap: function($this, thisBreakpoint) {
            // ...
        }
    });


Changelog

v1.0.0

Initial release.


Author

Mike Zarandona | mike.zarandona.com

Smarter-Images

Related posts:

Dynamic Carousel
Freetile-js
okayNav
Smarter-Images plugin

http://jquer.in/wp-content/uploads/2015/09/Smarter-Images.jpg

jQuery plugin

Sign up for our weekly newsletter.

* We won't spam you ever