🖼️ astro-lqip

Native extended Astro components for generating low quality image placeholders (LQIP).

✨ Features

• 🖼️ Supports both <Image> and <Picture> components.
• 🎨 Multiple LQIP techniques: base64, solid color, CSS via gradients and SVG.
• 🚀 Easy to use, just replace the native Astro components with the ones from astro-lqip.
• ⚡️ Support images as static imports or using string paths.
• 🔧 Fully compatible with Astro's image optimization features.
• 🌍 Supports both local and remote images.
• ⚙️ Supports SSR mode with Node Adapter.

⬇️ Installation

NPM:

npm install astro-lqip

PNPM:

pnpm add astro-lqip

Yarn:

yarn add astro-lqip

🚀 Usage

In your current Astro project, just replace the import of the native Astro <Image> or <Picture> components with the ones provided by astro-lqip.

Image

- import { Image } from 'astro:assets';
+ import { Image } from 'astro-lqip/components';

Picture

- import { Picture } from 'astro:assets';
+ import { Picture } from 'astro-lqip/components';

Example:

---
import { Image, Picture } from 'astro-lqip/components';

import image from '/src/assets/images/image.png';
import otherImage from '/src/assets/images/other-image.png';
---

<Image src={image} alt="Cover Image" width={220} height={220} />
<Picture src={otherImage} alt="Other Image" width={220} height={220} />

Tip

Since version 1.6.0, you can also put the image path as string directly in the src prop. Support absolute paths in src, relative paths and alias.

Example with absolute path:

---
import { Image, Picture } from 'astro-lqip/components';
---

<Image src="/src/assets/images/image.png" alt="Cover Image" width={220} height={220} />
<Picture src="/src/assets/images/other-image.png" alt="Other Image" width={220} height={220} />

Example with relative path:

---
import { Image, Picture } from 'astro-lqip/components';
---

<!-- assuming you are on the path `/src/pages/index.astro` -->
<Image src="../assets/images/image.png" alt="Cover Image" width={220} height={220} />
<Picture src="../assets/images/other-image.png" alt="Other Image" width={220} height={220} />

Example with alias:

---
import { Image, Picture } from 'astro-lqip/components';
---

<Image src="@/assets/images/image.png" alt="Cover Image" width={220} height={220} />
<Picture src="@/assets/images/other-image.png" alt="Other Image" width={220} height={220} />

Learn how to configure path aliasing in the Astro documentation. If you want more examples of uses you can see the Usage Tips page.

⚙️ Props

Both <Image> and <Picture> components support all the props of the native Astro components, but adds a couple of props for LQIP management:

• lqip: The LQIP type to use. It can be one of the following:
  • base64: Generates a Base64-encoded LQIP image. (default option)
  • color: Generates a solid color placeholder. Not compatible with lqipSize.
  • css: Generates a CSS-based LQIP image.
  • svg: Generates an SVG-based LQIP image.
• lqipSize: The size of the LQIP image, which can be any number from 4 to 64. (default is 4)

Warning

A high value for lqipSize can significantly increase the total size of your website.

Example:

---
import { Image, Picture } from 'astro-lqip/components';

import image from '/src/assets/images/image.png';
import otherImage from '/src/assets/images/other-image.png';
---

<Image src={image} alt="Cover Image" width={220} height={220} lqip="svg" lqipSize={10} />
<Picture src={otherImage} alt="Other Image" width={220} height={220} lqip="css" lqipSize={7} />

Tip

For the <Image> component, a parentAttributes prop similar to pictureAttributes has been added.

💡 Knowledge

Since this integration is built on top of Astro native <Image> and <Picture> components, you can refer to the Astro documentation for more information on how to use it.

For some simple tips, visit the Usage Tips page.

🤝 Contributing

If you wish to contribute to this project, you can do so by reading the contribution guide.

📄 License

This project is licensed under the MIT License. See the license file for more details.