grunt-responsive-images-extender

Extend HTML image tags with srcset and sizes attributes to leverage native responsive images.

Getting Started

This plugin requires Grunt ~0.4.0

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-responsive-images-extender --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-responsive-images-extender');

The "responsive_images_extender" task

Overview

The responsive_images_extender task will scan your source files for HTML <img> tags and extend them with srcset and optional sizes attributes to leverage native responsive images as described in Yoav Weiss' article.

It is therefore the perfect complement to the responsive_images task that generates images with different resolutions. Used in combination you enable the browser to make an informed decision which image to download and render.

This plugin uses Cheerio to traverse/modify the DOM and image-size to read the image sizes straight from the image files. You don't have to configure the srcset or srcsetRetina option anymore, since they get built automatically based on the present image files.

In your project's Gruntfile, add a section named responsive_images_extender to the data object passed into grunt.initConfig().

grunt.initConfig({
  responsive_images_extender: {
    options: {
      // Task-specific options go here.
    },
    your_target: {
      // Target-specific file lists and/or options go here.
    },
  },
});

Options

• options.separator Type: String Default: '-'

  The separator used for naming your resized images.

• options.baseDir Type: String Default: ''

  The base directory of the site you are serving. This enables Grunt to access your image files when you use absolute paths to reference them in your HTML code. Ignore this option if you are using relative paths only.

• options.sizes Type: Array Default: none

  An array of objects containing the selectors (standard CSS selectors, like .some-class, #an-id or img[src^="http://"]) and their respective size tableau. An example could look like this:

  sizes: [{
    selector: '#post-header',
    sizeList: [{
      cond: 'max-width: 30em',
      size: '100vw'
    },{
      cond: 'max-width: 50em',
      size: '50vw'
    },{
      cond: 'default',
      size: 'calc(33vw - 100px)'
    }]
  },{
    selector: '.hero img',
    sizeList: [{
      cond: 'max-width: 20em',
      size: '80vw'
    },{
      cond: 'default',
      size: '90vw'
    }]
  }]

  If you want to set a default size value, make sure to set the condition to default and add the object at the end of the array. Otherwise the default value renders the following media conditions obsolete, since the browser walks through the list specified in sizes and looks for the first matching one.

  This array is optional and without specifying one the browser assumes the size 100vw for all images.

  You can use the placeholder %size% which gets replaced by the actual width of the current image (this can come in handy to specify a maximum width with a breakpoint, e.g. (min-width: 400px) 400px).

• options.ignore Type: Array Default: []

  An array of standard CSS selectors of image tags you want to ignore.

• options.srcsetAttributeName Type: String Default: 'srcset'

  Overwrite the name of the srcset attribute with something else, for example some lazy loaders require data-srcset.

• options.srcAttribute Type: String Default: none

  Set the src attribute to:

  • 'none': Delete the src attribute which is necessary to avoid duplicate downloads when you are using a polyfill. Please note that this is not valid HTML, though.
  • 'smallest': Set the src fallback to the smallest image.
  • Do not use this option to leave src untouched.

Usage Examples

Default Options

grunt.initConfig({
  responsive_images_extender: {
    target: {
      options: {},
      files: [{
        expand: true,
        src: ['**/*.{html,htm,php}'],
        cwd: 'src/',
        dest: 'build/'
      }]
    }
  }
});

This configuration will turn this HTML code

<img alt="A simple image" src="simple.jpg" title="A simple image">

into this (the image sizes are arbitrarily chosen and read directly from the files):

<img alt="A simple image" src="simple.jpg"
     srcset="simple-small.jpg 320w,
             simple-medium.jpg 640w,
             simple-large.jpg 1024w,
             simple.jpg 2000w"
     title="A simple image">

Custom Options

Use the options to refine your tasks, e.g. to add a sizes attribute, a different separator, or a different src value. <img> tags with a width attribute automatically trigger the use of x descriptors.

grunt.initConfig({
  responsive_images_extender: {
    complete: {
      options: {
        separator: '@',
        baseDir: 'build',
        srcAttribute: 'smallest',
        sizes: [{
          selector: '.article-img',
          sizeList: [{
            cond: 'max-width: 30em',
            size: '100vw'
          },{
            cond: 'max-width: 50em',
            size: '50vw'
          },{
            cond: 'default',
            size: 'calc(33vw - 100px)'
          }]
        }]
      },
      files: [{
        expand: true,
        src: ['**/*.{html,htm,php}'],
        cwd: 'src/',
        dest: 'build/'
      }]
    }
  }
});

Above configuration would turn the following HTML chunk

<img alt="A simple image" src="simple.jpg" class="article-img">

<img src="simple.jpg" width="200">

into this:

<img alt="A simple image" src="[email protected]" class=".article-img"
     srcset="[email protected] 200w,
             [email protected] 400w,
             [email protected] 800w,
             simple.jpg 1600w"
     sizes="(max-width: 30em) 100vw,
            (max-width: 50em) 50vw,
            calc(33vw - 100px)">

<img src="[email protected]" width="200"
     srcset="[email protected] 1x,
             [email protected] 2x,
             [email protected] 4x,
             simple.jpg 8x">

Ignoring images

Sometimes you want to exclude certain images from the algorithm. You can achieve this with the ignore option:

grunt.initConfig({
  responsive_images_extender: {
    ignoring: {
      options: {
        ignore: ['.icons', '#logo', 'figure img']
      },
      files: [{
        expand: true,
        src: ['**/*.{html,htm,php}'],
        cwd: 'src/',
        dest: 'build/'
      }]
    }
  }
});

Please see this task's Gruntfile for more usage examples.

Related Work

• grunt-responsive-images

  Use this task to generate images with different sizes.

• grunt-responsive-images-converter

  This task can be used to convert images in markdown files into a <picture> tag. Unfortunately, it is limited to markdown files. Also, read here why <picture> is not the smartest thing in most cases.

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

3.0.0

• Fixed file path to be a string rather than an array (as requested by path module since Node 6)
• Allow for multiple source files per destination file
• Adjusted files config in Gruntfile (see the Grunt docs)

2.0.1

• Switched to POSIX-compatible paths (thanks to sprrw)

2.0.0

• srcset is built automatically based on the image sizes read directly from the files. x descriptors are triggered for images with width attribute.
• Removed srcset and srcsetRetina option.
• Added the srcAttribute option to delete src for polyfills or set the smallest image as a fallback.
• Added the srcsetAttributeName option to use for example data-srcset for lazy loaders.
• Added the %size% placeholder to use the image size inside the sizes rules

1.0.0

• The sizes option allows users to specify multiple sizes for different selectors, for example for hero images, article images or icons.
• Added the ignore option.

0.1.0

• Initial commit and first version