Package Exports

webpack-image-placeholder-loader

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (webpack-image-placeholder-loader) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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 --save-dev webpack-image-placeholder-loader

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 --save-dev webpack-query-loader

Install with yarn:

yarn add webpack-query-loader --dev

Step 2

Configure webpack-query-loader

module.exports = {
  ...
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|svg|gif|webp|tiff?)/i,
        use: [
          {
            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.