webpack-image-placeholder-loader

webpack-image-placeholder-loader

This loader generates a color or solid color image or blurred 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.

Examples

Blurred Placeholder	Solid Color Placeholder

React

Vue

React example with other related loaders

Vue example with other related loaders

Install

Install with npm:

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

Install with yarn:

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

Usage

Step 1

webpack.config.js

module.exports = {
  // ...
  module: {
    rules: [
      // ...
      {
        test: /\.(png|jpe?g|svg|gif|webp|tiff?)$/i,
        oneOf: [
          {
            // if the import url looks like "some.png?placeholder..."
            resourceQuery: /placeholder/,
            use: {
              loader: "webpack-image-placeholder-loader",
              options: {
                format: "hex",
              },
            },
          },
          {
            // if no previous resourceQuery match
            use: "file-loader",
          },
        ],
      },
    ],
  },
};

Step 2

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

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";

Options

Name	Type	Default	Description
format	"base64", "blurred-svg", "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.
blurQuality	number	1	The quality of blur image if format is "blurred-svg", no effect if the format is anything else. Possible values from 0 (not including 0) to 100 (including 100).
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: "blurred-svg": placeholderUrl === "data:image/svg+xml;charset=utf-8,%3Csvg xmlns=..."
• 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.

blurQuality

When used with "blurred-svg", the image is first shunk by this percentage, stretched, then blurred.

1 is 1/100 of the original quality. 100 is the original quality (DO NOT recommand using 100). Can be decimal numbers too, 0.1 would be 1/1000 of the original quality. The lower the value, the more blurry the image will be, and the smaller the size.

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.