webpack-image-placeholder-loader

webpack-image-placeholder-loader

This loader generates a color or solid color image from a given image for use as a placeholder.

Under the hood this package uses fast-average-color. See fast-average-color for examples of colors derived from images.

Supports JPEG, PNG, WebP, TIFF, GIF and SVG images.

Install

Install with npm:

npm install webpack-image-placeholder-loader --save-dev

Install with yarn:

yarn add webpack-image-placeholder-loader --dev

Usage

Recommanded usage for Webpack v4

Step 1

Install webpack-query-loader

Install with npm:

npm install webpack-query-loader --save-dev

Install with yarn:

yarn add webpack-query-loader --dev

Step 2

Configure webpack-query-loader

webpack.config.js

module.exports = {
  ...
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|svg|gif|webp|tiff?)/i,
        use: [
          // if import has query "?placeholder"
          {
            loader: "webpack-query-loader",
            options: {
              resourceQuery: "placeholder",
              use: {
                loader: "webpack-image-placeholder-loader",
                options: {
                  format: "base64",
                  size: 1,
                  color: "sqrt",
                  backgroundColor: "#FFF"
                }
              }
            },
          },
          {
            loader: "webpack-query-loader",
            options: {
              resourceQuery: "!placeholder",
              use: {
                loader: "file-loader", // or whatever loaders you want to use
              }
            },
          },
        ],
      },
    ],
  },
};

Step 3

Use in code

import placeholderUrl from "./some_pic.png?placeholder";

To override options for one import, you can use queries

import placeholderUrl from "./some_pic.png?placeholder&size=original";

Other usage for Webpack v4

With default options:

import placeholderUrl from "!!webpack-image-placeholder-loader!./some_pic.png";

With specified options:

import placeholderUrl from "!!webpack-image-placeholder-loader!./some_pic.png?format=base64&size=1&color=sqrt&backgroundColor=white";

Recommanded usage for Webpack v5

Same as Webpack v4 but use resourceQuery instead of webpack-query-loader

Options

Name	Type	Default	Description
format	"base64", "hex", "rgb", or "array"	"base64"	The format of the output
size	number or "original"	1	The size of the output image if format is "base64", no effect if the format is anything else
color	string|object	"sqrt"	An algorithm ("simple", "sqrt" or "dominant") to generate a color from a given image, or a color string or color object to use in generating the output image
backgroundColor	string|object	"#FFF"	The background color to use if the given image has transparency
esModule	boolean	true	Whether the export is in ES modules syntax or CommonJS modules syntax

format

With

import placeholderUrl from "./some_pic.png?placeholder";

• format: "base64": placeholderUrl === "data:image/png;base64,iVBORw0KG..."
• format: "hex": placeholderUrl === "#6b7548"
• format: "rgb": placeholderUrl === "rgb(107, 117, 72)"
• format: "array": placeholderUrl === [107, 117, 72]"

size

size will only take effect if format: "base64". When size is a number, the output image will be a square of the given number of pixels. When size: "original", the output image will be the size of the original image.

color

color can be an algorithm ("simple", "sqrt" or "dominant") to generate a color from a given image (see examples in algorithm), or a color string or color object to use in generating the output image.

A color string or color object is any valid colors accepted by TinyColor.

For example:

{
  color: "white",
  format: "base64"
}

will output a white pixel.

{
  color: "white",
  format: "hex"
}

will output #FFFFFF

backgroundColor

If an image has transparency, backgroundColor will be used as the background color. By default backgroundColor is white.

esModule

Whether the export is in ES modules syntax or CommonJS modules syntax. If you don't know what it is or whether or not you need it, leave is as default.

Changelog

1.1.18 (2020-11-17)

Bug Fixes

• import with query where the value is a number not working (cebacb4)