Tailwind

note

Due to limitations with Tailwind's JIT engine:

1. @plaiceholder/tailwindcss only supports Local images.
2. Images must not have an _ in their name (Tailwind treats this as a space)

Installation

1. Install the package alongside your existing tailwindcss and plaiceholder installation:

   npm

   npm install @plaiceholder/tailwindcss

   Yarn

   yarn add @plaiceholder/tailwindcss

2. Add the plugin to your tailwind.config.js:

   tailwind.config.js

   module.exports = {
     content: [],
     theme: {
       extend: {},
     },
     variants: {},
     plugins: [require("@plaiceholder/tailwindcss")],
   };

Usage

Once installed, pure CSS image LQIPs can be created with the following JIT class format:

HTML

<!-- 
   returns a pure CSS LQIP for 
   `./public/path-to-your-image.jpg`
-->
<div class="plaiceholder-[/path-to-your-image.jpg]" />

React.js

const Example = () => (
  // returns a pure CSS LQIP for
  // `./public/path-to-your-image.jpg`
  <div className="plaiceholder-[/path-to-your-image.jpg]" />
);

The class only returns the "pixels" (linear-gradient values), allowing you to configure your preferred "blur" effect:

HTML

<!-- 
   returns a pure CSS LQIP for 
   `./public/path-to-your-image.jpg`
-->
<div
  class="plaiceholder-[/path-to-your-image.jpg] transform scale-150 filter blur-2xl"
/>

React.js

const Example = () => (
  // returns a pure CSS LQIP for
  // `./public/path-to-your-image.jpg`
  <div className="plaiceholder-[/path-to-your-image.jpg] transform scale-150 filter blur-2xl" />
);

Utils

Dynamic values aren't supported by JIT mode, meaning arbitrary LQIPs can't be computed.

The values must exist at build-time.

// ❌ NOT POSSIBLE
const Example = ({ src }) => (
  <div
    className={`plaiceholder-[{src}] transform scale-150 filter blur-2xl`}
  />;
);

To circumvent this, @plaiceholder/tailwindcss offers an additional utils entry point to extract image paths from the JIT classes on the server-side.

For example, in a Next.js setup.

Node.js

import { getPlaiceholder } from "plaiceholder";
import { extractImgSrc } from "@plaiceholder/tailwindcss/utils";

try {
  const plaiceholder = "plaiceholder-[/path-to-your-image.jpg]";

  getPlaiceholder(extractImgSrc(plaiceholder)).then(({ img }) =>
    console.log(img)
  );
} catch (err) {
  err;
}

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

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 { extractImgSrc } from "@plaiceholder/tailwindcss/utils";

export const getStaticProps = async () => {
  const plaiceholder = "plaiceholder-[/path-to-your-image.jpg]";
  const { img } = await getPlaiceholder(extractImgSrc(plaiceholder));

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

const Page: React.FC<InferGetStaticPropsType<typeof getStaticProps>> = ({
  img,
  plaiceholder,
}) => (
  <div className="relative block overflow-hidden">
    <div
      className={`absolute inset-0 w-full h-full ${plaiceholder} transform scale-150 filter blur-2xl`}
    />
    <Image {...img} />
  </div>
);

export default Page;