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: your preferred static directory (default: ./public)
  • size: an integer (between 4 and 64) to adjust the returned placeholder size (default: 4)

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

Node.js

import { getPlaiceholder } from "plaiceholder";

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

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

Next.js

pages/example.tsx

import * as React from "react";
import type { InferGetStaticPropsType } from "next";
import Image from "next/image";
import { getPlaiceholder } from "plaiceholder";

export const getStaticProps = async () => {
  const { css, img } = await getPlaiceholder("/path-to-your-image.jpg");

  return {
    props: {
      img,
      css,
    },
  };
};

const Page: React.FC<InferGetStaticPropsType<typeof getStaticProps>> = ({
  img,
  css,
}) => (
  <div style={{ position: "relative", display: "block", overflow: "hidden" }}>
    <div
      style={{
        position: "absolute",
        top: 0,
        right: 0,
        bottom: 0,
        left: 0,
        width: "100%",
        height: "100%",
        transform: "scale(1.5)",
        filter: "blur(40px)",
        ...css,
      }}
    />

    <Image {...img} />
  </div>
);

export default Page;

11ty

See the 11ty example

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

Node.js

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
//   ]
// ]

Next.js

pages/example.tsx

import * as React from "react";
import type { InferGetStaticPropsType } from "next";
import Image from "next/image";
import { getPlaiceholder } from "plaiceholder";

export const getStaticProps = async () => {
  const { svg, img } = await getPlaiceholder("/path-to-your-image.jpg");

  return {
    props: {
      img,
      svg,
    },
  };
};

const Page: React.FC<InferGetStaticPropsType<typeof getStaticProps>> = ({
  img,
  svg,
}) => (
  <div style={{ position: "relative", display: "block", overflow: "hidden" }}>
    {React.createElement(
      svg[0],
      {
        ...svg[1],
        style: {
          ...svg[1].style,
          transform: ["scale(1.5)", svg[1].style.transform].join(" "),
          filter: "blur(40px)",
        },
      },
      svg[2].map((child) =>
        React.createElement(child[0], {
          key: [child[1].x, child[1].y].join(),
          ...child[1],
        })
      )
    )}

    <Image {...img} />
  </div>
);

export default Page;

11ty

See the 11ty example

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

Node.js

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…

Next.js

pages/example.tsx

import * as React from "react";
import type { InferGetStaticPropsType } from "next";
import Image from "next/image";
import { getPlaiceholder } from "plaiceholder";

export const getStaticProps = async () => {
  const { base64, img } = await getPlaiceholder("/path-to-your-image.jpg");

  return {
    props: {
      imageProps: {
        ...img,
        blurDataURL: base64,
      },
    },
  };
};

const Page: React.FC<InferGetStaticPropsType<typeof getStaticProps>> = ({
  imageProps,
}) => (
  <div>
    <Image {...imageProps} placeholder="blur" />
  </div>
);

export default Page;

11ty

See the 11ty example

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

Node.js

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
//  }

Next.js

pages/example.tsx

import * as React from "react";
import type { InferGetStaticPropsType } from "next";
import Image from "next/image";
import { getPlaiceholder } from "plaiceholder";
import { BlurhashCanvas } from "react-blurhash";

export const getStaticProps = async () => {
  const { blurhash, img } = await getPlaiceholder("/path-to-your-image.jpg");

  return {
    props: {
      img,
      blurhash,
    },
  };
};

const Page: React.FC<InferGetStaticPropsType<typeof getStaticProps>> = ({
  img,
  blurhash,
}) => (
  <div style={{ position: "relative", display: "block", overflow: "hidden" }}>
    <BlurhashCanvas
      {...blurhash}
      punch={1}
      style={{
        position: "absolute",
        top: 0,
        right: 0,
        bottom: 0,
        left: 0,
        width: "100%",
        height: "100%",
      }}
    />

    <Image {...img} />
  </div>
);

export default Page;

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