Skip to main content

Usage

getPlaiceholder(src, options);

Parameters​

  • src: string reference to an image. Can be either;

    1. a file path to an image inside the root public directory, referenced from the base URL (/).
    2. a remote image URL.
  • options: (optional)

    • dir: a file path to your preferred static assets directory; where local images are resolved from (default: ./public)

    • size: an integer (between 4 and 64) to adjust the returned placeholder size (default: 4)

    • Sharp Configuration

      Under-the-hood, plaiceholder uses Sharp to transform images; a small selection of options have been exposed for further customization:

      note

      Plaiceholder has no plans to expand these options. If you need more control on the ouput, we recommend rolling your own Sharp-based LQIP solution.

      • brightness: brightness multiplier (default: 1)

      • format: force output to a specified output (default: ["png"])

      • hue: degrees for hue rotation (no default)

      • lightness: lightness addend (no default)

      • removeAlpha: remove alpha channel for transparent images (default: true)

        Note: this option is a no-op for Blurhash.

      • saturation: saturation multiplier (default: 1.2)

Return Values​

css​

Converts a specified image into a low-res placeholder, outputted as a set of linear-gradients (in the form of a JavaScript style object).

For a "blurred" effect, extend the returned styles with filter: blur(<value>) and transform: scale(<value>).

Example​

import { getPlaiceholder } from "plaiceholder";

try {
getPlaiceholder("/path-to-your-image.jpg").then(({ css }) =>
console.log(css)
);
} catch (err) {
err;
}

// Logs
// {
// backgroundImage: "…"
// backgroundPosition: "…"
// backgroundSize: "…"
// backgroundRepeat: "…"
// }

svg​

Converts a specified image into a low-res placeholder, outputted as an SVG.

For a "blurred" effect, extend the returned SVG's styles with filter: blur(<value>) and transform: scale(<value>).

note

Although it returns the SVG in the format of React.createElement() arguments, you are not constrained to using React.js.

e.g. See the 11ty example.

Example​

import { getPlaiceholder } from "plaiceholder";

try {
getPlaiceholder("/path-to-your-image.jpg").then(({ svg }) =>
console.log(svg)
);
} catch (err) {
err;
}

// Logs
// [
// "svg",
// { ...svgProps }
// [
// [
// "rect",
// { ...rectProps }
// ],
// ...etc
// ]
// ]

base64​

Converts a specified image into a low-res image, encoded as Base64 string.

For a "blurred" effect, add filter: blur(<value>) and transform: scale(<value>) styles to the image.

Example​

import { getPlaiceholder } from "plaiceholder";

try {
getPlaiceholder("/path-to-your-image.jpg").then(({ base64 }) =>
console.log(base64)
);
} catch (err) {
err;
}

// Logs
// data:image/jpeg;base64,/9j/2wBDAAYEBQY…

blurhash​

Converts a specified image into a low-res image, encoded as Blurhash string accompanied by its width and height

This can be passed into a library such as react-blurhash.

Example​

import { getPlaiceholder } from "plaiceholder";

try {
getPlaiceholder("/path-to-your-image.jpg").then(({ blurhash }) =>
console.log(blurhash)
);
} catch (err) {
err;
}

// Logs
// {
// hash: "U.QSL{%1bdxtR...",
// height: 32,
// width: 32
// }

img​

Returns all essential <img /> attributes via the img object.

import { getPlaiceholder } from "plaiceholder";

try {
getPlaiceholder("/path-to-your-image.jpg").then(({ img }) =>
console.log(img)
);
} catch (err) {
err;
}

// Logs
// {
// src: '…',
// width: …,
// height: …,
// type: '…'
// }