Astro LQIP

Features

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

Usage

In your current Astro project, just replace the import of the native Astro<Image>or<Picture>component byastro-lqip or import the<Background> component for CSS background images.

Image

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

Picture

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

Background

+ import { Background } from 'astro-lqip/components';

Example:

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

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

<Image src={image} alt="Cover Image" width={220} height={220} />
<Picture src={otherImage} alt="Other cover Image" width={220} height={220} />
<Background src={backgroundImage}>
  <section>
    <p>Optimized background</p>
  </section>
</Background>

<style>
  section {
    background-image: var(--background);
    background-size: cover;
    background-position: center;
  }
</style>

Example with absolute path:

---
import { Image, Picture, Background } 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} />
<Background src="/src/assets/images/background-image.png">
  <section>
    <p>Optimized background</p>
  </section>
</Background>

<style>
  section {
    background-image: var(--background);
    background-size: cover;
    background-position: center;
  }
</style>

Example with relative path:

---
import { Image, Picture, Background } 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} />
<Background src="../assets/images/background-image.png">
  <section>
    <p>Optimized background</p>
  </section>
</Background>

<style>
  section {
    background-image: var(--background);
    background-size: cover;
    background-position: center;
  }
</style>

Example with alias:

---
import { Image, Picture, Background } 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} />
<Background src="@/assets/images/background-image.png">
  <section>
    <p>Optimized background</p>
  </section>
</Background>

<style>
  section {
    background-image: var(--background);
    background-size: cover;
    background-position: center;
  }
</style>

Props

Image and Picture

Both<Image>and<Picture>components support all the props of thenative Astro componentsbut 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 withlqipSize.
  • 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 from4to64. (default is 4)

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 cover Image" width={220} height={220} lqip="css" lqipSize={7} />

Background

The<Background> component supports the following props:

• src (required): The source of the background image located in src folder. It can be a static import, absolute path, relative path, alias path or remote URL.
• 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.
• cssVariable: A string that represents the name of the CSS variable to store the background data.
  • By default, the background data is stored in a CSS variable named--background.
  • For responsive backgrounds, the CSS variable names are generated based on the provided widths, following the pattern--background-small (lower than 768px),--background-medium (768px to 1199px),--background-large (1200px to 1919px) and--background-xlarge (1920px and above).--background is also generated for the largest image for backward compatibility.
  • If thecssVariable prop is provided, the generated CSS variable names will follow the pattern--{cssVariable}-small,--{cssVariable}-medium,--{cssVariable}-large and--{cssVariable}-xlarge.
• format: The image format to use for the background. It can be one of the following in string or an array of strings. If an array is provided, this generates multiple background images with the native image-set() CSS function, which allows the browser to choose the best format to use based on its support:
  • avif
  • webp (default option)
  • jpeg
  • png
• widths: An array of numbers that represents the widths to use for responsive background images.
• width: The width to use for the background image. This prop is ignored if the widths prop is provided.
• height: The height to use for the background image. This prop is ignored if the widths prop is provided.
• quality: The quality to use for the background image. It can be a number from 1 to 100.
• fit: The fit to use for the background image. It can be one of the following:
  • cover
  • contain
  • fill
  • inside
  • outside

Example:

---
import { Background } from 'astro-lqip/components';
import backgroundImage from '/src/assets/images/background-image.png';
---

<Background src={backgroundImage} lqip="color" cssVariable="--bg-lqip" format={["avif", "webp"]} width={500} height={300} quality={80} fit="cover">
  <section>
    <p>Optimized background</p>
  </section>
</Background>

<style>
  section {
    background-image: var(--bg-lqip);
    background-size: cover;
    background-position: center;
  }
</style>

Example with responsive background:

---
import { Background } from 'astro-lqip/components';
import backgroundImage from '/src/assets/images/background-image.png';
---

<Background src={backgroundImage} format="avif" widths={[475, 1000, 1536, 2100]}>
  <section>
    <p>Optimized background</p>
  </section>
</Background>

<style>
  section {
    background-image: var(--background-small); /* 475px */
    background-size: cover;
    background-position: center;
  }

  @media (width >= 768px) {
    section {
      background-image: var(--background-medium); /* 1000px */
    }
  }

  @media (width >= 1200px) {
    section {
      background-image: var(--background-large); /* 1536px */
    }
  }

  @media (width >= 1920px) {
    section {
      /* or var(--background), since it's the default variable for the largest image */
      background-image: var(--background-xlarge); /* 2100px */
    }
  }
</style>