Smart Cross-platform Image Delivery Plugin - smart_images

Smart Cross-platform Image Delivery Plugin - smart_images
File Size: 6.56 MB
Views Total: 757
Last Update:
Publish Date:
Official Website: Go to website
License: MIT

Yet another smart Image Delivery plugin for jQuery that automatically updates the src of an img tag and pulls in the image appropriate to the current window width.


  • jQuery.
  • BreakpointX: Define responsive breakpoints, register callbacks when crossing, with optional css class handling.


# Yarn
$ yarn add @aklump/smart-images

$ npm install @aklump/smart-images --save

How to use it:

1. Include the needed JavaScript file as noticed above in your html document.

<script src="/path/to/jquery.min.js"></script>
<script src="/path/to/BreakpointX.js"></script>

2. Download and include the jQuery smart_images plugin after jQuery.

<script src="jquery.smart_images.js"></script>

3. The markup.

  • You MUST have at least two image paths defined based on a media query regarding a screen width.
  • You MUST have only one min-width declaration and it needs to be 1px greater than your highest max-width declaration.
  • You MAY have as many max-width declarations as you want breakpoints.
  • Each max-width tag MUST define a path to an image the SHOULD be the same width as the max-width value.
  • The single min-width tag MUST define a path to the largest image you want to load and it SHOULD be larger than the min-width value, e.g., if min-width=769 the image may be 1080px wide.
<div class="smart-image">
  <span data-si-srcset="small.jpg" data-si-media="(max-width: 319px)"></span>
  <span data-si-srcset="medium.jpg" data-si-media="(max-width: 479px)"></span>
  <span data-si-srcset="large.jpg" data-si-media="(max-width: 767px)"></span>
  <span data-si-srcset="full.jpg" data-si-media="(min-width: 768px)"></span>

4. Initialize the plugin on document ready and we're done.


5. To get the SmartImages object after it's attached you can do this:

var smartImages = $('.smart-image').data('smartImages');

6. Possible plugin settings with default values.

 * Namespace for all data tags, e.g. 'si-'.
dataPrefix     : 'si-',
dataSrcSuffix  : 'srcset',
dataMediaSuffix: 'media',

 * Used with $el.find() to locate the img tag that gets replaced with src.
imgSelector: 'img',

 * Used with $el.find() to locate the tags that contain the srcsets. By default this is null because it uses the
 * data suffixes above, but setting it here will override that behavior.  This would allow you to use an alternate
 * structure if necessary.
srcSelector: null,

 * How many milliseconds to wait to read the window width after a resize event.
resizeThrottle: 300,

 * This setting answers the question of loading smaller images when the window downsizes.
 * 'never' means the largest image that gets loaded first will always show.  Use this method to reduce bandwidth,
 * and if aspect ratios are the same across breakpoints.  THIS IS THE FASTEST AND USES THE LEAST BANDWIDTH.
 * Setting this to 'always' will mean that the images are swapped BOTH when the window grows larger and grows
 * smaller and results in more data transfer when the window starts out larger because the smaller images need to
 * be downloaded.  One reason to choose this setting is if the aspect ratios are different for different
 * breakpoints--to ensure images don't distort.  USE THIS OPTION IF ASPECT RATIOS ARE DIFFERENT ACROSS BREAKPOINTS.
 * 'loaded' means smaller images will be shown if they were previously loaded.  This happens when the window starts
 * out small, grows larger, then shrinks back.  This option may give better visual appearance because the browser
 * is not resizing the image.  Compared to 'never' this results in a slight delay as the window grows larger, and
 * the image needs to be swapped out for the larger. USE THIS OPTION IF YOU NOTICE SMALLER IMAGES ARE NOT AS CLEAR
 * One of:
 * - never
 * - always
 * - loaded
downsize: 'never',

 * Callback fired on initializing before loading the first images.
onInit: null,

 * Callback before a src change is to occur.  Only the first time this is called will `this.firstRun` be true.
 * Return false to prevent the image src swap.
 * @param string breakpoint name
 * @param string image src
onBeforeChange: null,

 * Callback just after a src change has occurred.
 * @param string breakpoint name
 * @param string image src
onAfterChange: null


v0.4.4 (2019-02-03)

  • Update

v0.4.3 (2018-12-17)

  • Update

v0.4.2 (2018-12-15)

  • Update

v0.4.0 (2018-12-13)

  • Changed name back to to be standards compliant.

v0.3.2 (2018-12-11)

  • onBeforeChange now receives a segment object as the first argument.
  • onAfterChange now receives a segment object as the first argument.

v0.2.4 (2018-12-05)

  • JS update

v0.2.1 (2018-11-30)

  • JS update

v0.1.7 (2017-05-19)

  • JS update

v0.1.5 (2017-03-31)

  • added new setting srcSelector

This awesome jQuery plugin is developed by aklump. For more Advanced Usages, please check the demo page or visit the official website.