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)
    • size: an integer (between 4 and 64) to adjust the returned placeholder size.

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: '…'
// }