eleventy-plugin-sharp-respimg

An Eleventy shortcode that performs build-time image transformations with Sharp to resize large images into .jpeg and .webp formats with varying dimensions and generates <picture> tags for responsive images.

Installation

In your Eleventy project, install the plugin from npm:

npm install eleventy-plugin-sharp-respimg

Then add it to your Eleventy Config file:

const respimg = require("eleventy-plugin-sharp-respimg");

module.exports = (eleventyConfig) => {
    eleventyConfig.addPlugin(respimg);
}

What does it do?

It turns paired shortcodes like this:

{% respimg 
    src="car.png", 
    alt="Photo of a car", 
    inputDir="./src",
    imgDir="/images/",
    widths=[320, 640, 1024],
    sizes="(max-width: 450px) 33.3vw, 100vw",
    className="my-image",
    width=1024,
    height=768
%}

into responsive image markup using <picture> tags like this:

 <picture>
    <source 
        type="image/webp"
        srcSet="/images/car-320.webp 320w,
                /images/car-640.webp 640w,
                /images/car-1024.webp 1024w"
        sizes="(max-width: 450px) 33.3vw, 100vw"
    >
    <img 
        srcSet="/images/car-320.jpeg 320w,
                /images/car-640.jpeg 640w,
                /images/car-1024.jpeg 1024w"
        sizes="(max-width: 450px) 33.3vw, 100vw"
        src="car-320.jpeg"
        alt="Photo of a car"
        loading="lazy"
        class="my-image"
        width="1024"
        height="768"
    >
</picture>

The images are responsive by using a <picture> element which contains zero or more <source> elements and one <img> element to offer alternative versions of an image for different display/device scenarios.
Using srcset and sizes, you can deliver variable-resolution images, which respond to variable layout widths and screen densities.

Usage Options

Supply the values as name-value pairs to the shortcode like shown in the example above.

You can also use global data or front matter to supply values to the shortcode like this:

---
src: yellow-modern.png
alt: Some alt text
inputDir: ./src
imgDir: /images/
widths: 
    - 320
    - 640
    - 1024
sizes: "(max-width: 450px) 33.3vw, 100vw"
className: test-class
width: 1024
height: 768
---
{% respimg
    src=src,
    alt=alt,
    inputDir=inputDir,
    imgDir=imgDir,
    widths=widths,
    sizes=sizes,
    className=class,
    width=width,
    height=height
%}

Or in a one liner by defining an object with the required properties:

---
data:
    src: yellow-modern.png
    alt: Some alt text
    inputDir: ./src
    imgDir: /images/
    widths: 
        - 320
        - 640
        - 1024
    sizes: "(max-width: 450px) 33.3vw, 100vw"
    className: test-class
    width: 1024
    height: 768
---

{% respimg data %}

Using the paired shortcode more than once for the same image

If you have already used the utility to transform an image and you call respimg within your code again for the same file, it will generate the responsive image markup using <picture> for that image and generate new images if the shortcode parameters change.

Transform mulitple images

The real power of using this paired shortcode is the ability to use data from global data files or front matter to transform multiple images at once.

If you have global JSON data stored in data.json or in front matter which is an array of objects like this:

[
    {
        "src": "car.png",
        "alt": "Photo of a car",
        "inputDir": "./src",
        "imgDir": "/images/",
        "widths": [320, 640, 1024],
        "sizes": "(min-width: 450px) 33.3vw, 100vw",
        "class": "my-image",
        "width": 1024,
        "height": 768
    },
    {
        "src": "flower.png",
        "alt": "Photo of a flower",
        "imgDir": "./images/",
        "widths": [320, 480, 640, 1024],
        "sizes": "(max-width: 450px) 33.3vw, 100vw",
        "class": "my-image",
        "width": 1024,
        "height": 768
    }
]

you can use the paired shortcode to transform multiple images with varying dimensions into responsive image markup using a for loop like this:

{% for image in data %}
    {% respimg 
        src=image.src, 
        alt=image.alt, 
        inputDir="./src",
        imgDir=image.imgDir,
        widths=image.widths, 
        sizes=image.sizes,
        className=image.class,
        width=image.width,
        height=image.height
    %}
{% endfor %}

Paired shortcode options

Parameter	Type	Description
src	`string`	The filename for an image.
alt	`string`	A text description of the image.
inputDir	`string`	The `input` directory in your Eleventy config file.
imgDir	`string`	The directory where the image file is located. Relative to `inputDir`.
widths	`int[]` or `string[]`	The desired image widths. Supports up to 10 values. Must provide atleast 3 values in ascending order.
sizes	`string`	The `sizes` attribute which defines a set of media conditions.
id	`string`	The `id` attribute for `<img>` elements inside the generated `<picture>`. Remember `id`'s may only be used once on a page, they must be unique and cannot repeat.
className	`string`	Class name for the fallback image.
width	`int`	The fallback image `width` attribute.
height	`int`	The fallback image `height` attribute.
fallbackSrcWidth	`int`	Width of the fallback image in the `src` attribute.
quality	`int`	The quality for Sharp to generate images width. (Default: 85)
overwrite	`boolean`	Determines if Sharp generates another set of images for a given input. Make sure this is `false` when serving locally. (Default: false)
debug	`boolean`	A boolean to include console output of generated image metadata.

Notes

Use ./ when declaring the inputDir parameter as Sharp expects this.
Use .addPassthroughCopy to include the images directory in your _site output e.g. eleventyConfig.addPassthroughCopy("./src/images/");.
The <picture> and <img> tags generated by the paired shortcode don't have any styling out of the box. But they can be manipulated with a bit of CSS to apply different width or height attributes.

Recommended fallback <img> boilerplate CSS:

.my-image {
    max-width: 100%;
    object-fit: cover;
    height: auto;
    margin: 0 auto;
}

Maintainers

@tannerdolby