Intro

A simple Image call produces HTML that does all of the following:

1. Creates figure, figcaption, and alt text for accessibility.
2. width and height values to prevent cumulative layout shifts.
3. Default avif and webp formats and async decoding for faster image rendering.
4. Various srcset values and lazy loading to reduce bandwidth usage.

AstroOutput HTMLPreview

---
import { Image } from '@splendidlabz/astro'
---
<Image src="/src/assets/ninja-on-asteroid.png" alt="..." caption="Ninja" />

Basic Usage

Pass an src value to import an image from any folder in /src. This should be an absolute path to your image.

<Image src="/src/path/to/image.jpg" />

Alt Text

Use the alt attribute to pass alt text, just like a normal image. alt defaults to an empty string when not defined.

<Image src="..." alt="..." />

Caption

Use caption to create accessible figcaptions.

<Image src="..." alt="Accessible Figcaptions" />

<figure aria-label="Accessible Figcaption">
  <picture> <!-- ... --> </picture>
  <figcaption aria-hidden>Accessible Figcaption</figcaption>
</figure>

alt can be used with caption. When used in this way, alt should describe the image while caption should give additional context about the image.

<Image
  src="..."
  alt="describe the image"
  caption="additional context about the image"
/>

<figure aria-label="additional context about the image">
  <picture>
    <!-- ... -->
    <img
      src="..."
      alt="describe the image"
      other-properties
    >
  </picture>
  <figcaption aria-hidden>additional context about the image</figcaption>
</figure>

Image Props

You can use image properties like decoding and loading by adding them to Image. The following values are set by Astro’s Picture element by default.

<Image src="..." decoding="async" loading="lazy" />

Additional Customizations

The following additional customizations are best made by creating your own Image component on top of ours because you would likely want them to be consistent across your site.

---
import { Image } from '@splendidlabz/astro'
const formats = [/* formats */]
const widths = [/* widths */]
---

<Image {...Astro.props} {formats} {widths} />

Formats

Image creates avif and webp formats by default for better performance. You can pass in formats which takes in an array of available formats to override this default.

<Image formats={['webp']} />

Widths

Image optimizes your images and create variants at 600, 900, 1200, 1500, and 1800 pixels by default. If your image is larger than 1800px, Image will also retain the original images for screen sizes beyond 1800px.

You can customize this by providing an array of widths you’d like to create.

<Image widths={['600', '900', '1200', '1500', '1800']} />