Image

Image creates optimized images with accessible figcaptions and prevents cumulative layout shift. It uses Astro’s Picture component under the hood.

Prevent cumulative layout shift without additional work

Google has been extremely vocal about the importance of Cumulative Layout Shift (CLS), so much that it has became part of Google’s Lighthouse audit.

Thankfully, Astro’s built-in Image and Picture components handles CLS without us having to lift a finger.

---
import { Image } from 'astro:assets'
import image1 from '../image1.jpg'
---

<Image src={image1} alt="..." />

Super easy Dynamic Image Import

Unfortunately, Astro’s built in Image and Picture elements require you to manually import your image, which leaves more to be desired.

We’ve built Image so you can import images dynamically just like how you’ve been using images all along.

---
import { Image } from 'astro:assets'
import image1 from '../image1.jpg'
---

<Image src={image1} alt="..." />

---
import { Image } from '@splendidlabz/astro'
---

<Image src='/src/assets/image1.jpg' alt="..." />

Include accessible Figcaptions with a single property

It’s strange, but <figcaption> elements aren’t accessible. You gotta work out a few quirks to make them accessible. We’ve done this for you so you can just add caption and call it a day.

---
import { Image } from '@splendidlabz/astro'
---

<Image
  src='...'
  alt="image alt"
  caption="image caption"
/>

<figure aria-label="image caption">
  <picture>
    <!-- ... -->
    <img ... alt="image alt" />
  </picture>
  <figcaption aria-hidden>image caption</figcaption>
</figure>

Automatic AVIF and Webp formats

There are lots of image formats out there, but the most performant ones are avif and webp. We’ve built these two formats into Image so you can optimize your images without any extra work.

---
import { Image } from '@splendidlabz/astro'
---

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

<figure>
  <picture>
    <source ... type="image/avif" />
    <source ... type="image/webp" />
    <img ... alt="image alt" />
  </picture>
</figure>

Automatic srcset for improved responsive image performance

Image includes srcset sizes at 600, 900, 1200, 1500 and 1800 pixels to serve appropriate images for almost every device users can use. This lowers your page weight as much as possible.

These values are customizable if you wish to change them.

---
import { Image } from '@splendidlabz/astro'
---

<Image ... widths={['600', '1200']} />

<figure>
  <picture>
    <source srcset="src1 600w, src2 1200w" type="image/avif" />
    <source srcset="src1 600w, src2 1200w" type="image/webp" />
    <img ... srcset="src1 600w, src2 1200w" />
  </picture>
</figure>

Intro

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

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

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

<figure aria-label="Figcaption content">
  <picture>
    <source srcset="src1 600w, src2 900w, src3 1200w, ..." type="image/avif" />
    <source srcset="src1 600w, src2 900w, src3 1200w, ..." type="image/webp" />
    <img
      src="path-to-image.jpg"
      srcset="src1 600w, src2 900w, src3 1200w, ..."
      alt="Alt Text"
      width="1200"
      height="1200"
      loading="lazy"
      decoding="async"
    />
  </picture>
  <figcaption aria-hidden>Figcaption content</figcaption>
</figure>

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

Please login to view this content

Splendid Labz is free because we love developers and we want to contribute back to the ecosystem.

We only charge for access to the documentation to keep the project going. If you don't wish to pay, feel free to use the content from the features tab, our blogs or our videos as your guide.

HTML Output

Image produces the following HTML when caption is not used.

<figure>
  <picture>
    <source srcset="..." type="image/avif" />
    <source srcset="..." type="image/webp" />
    <img
      src="..."
      srcset="..."
      alt="Alt Text"
      width="..."
      height="..."
      loading="lazy"
      decoding="async"
    />
  </picture>
</figure>

It produces the following HTML when caption is used.

<figure aria-label="Figcaption content">
  <picture>
    <source srcset="..." type="image/avif" />
    <source srcset="..." type="image/webp" />
    <img
      src="..."
      srcset="..."
      alt="Alt Text"
      width="..."
      height="..."
      loading="lazy"
      decoding="async"
    />
  </picture>
  <figcaption aria-hidden>Figcaption content</figcaption>
</figure>

Styling with CSS

We don’t provide basic styles for Image so you can use your own styles.

figure { /* ... your styles here ... */ }
figcaption { /* ... your styles here ... */ }
img { /* ... your styles here ... */ }

That said, we recommend adding the following to your reset.css file to ensure images are responsive. This, plus other reset styles, are provided in Splendid Styles

img {
  display: block;
  max-width: 100%;
  height: auto;
}

Styling with Tailwind

You can use the following properties to style Image with Tailwind:

Property	Description
`class`	Class for the `<figure>` element
`imageClass`	Class for the `<img>` element
`captionClass`	Class for the `<figcaption>` element

<Image
  class="..."
  imageClass="..."
  captionClass="..."
> ... </Image>

Please login to view this content

Splendid Labz is free because we love developers and we want to contribute back to the ecosystem.

We only charge for access to the documentation to keep the project going. If you don't wish to pay, feel free to use the content from the features tab, our blogs or our videos as your guide.

Styling API

You can use the following properties to style Image with Tailwind:

Property	Description
`class`	Class for the `<figure>` element
`imageClass`	Class for the `<img>` element
`captionClass`	Class for the `<figcaption>` element

Functionality API

You can use these properties to adjust the Image’s output.

Property	Type	Description
`src`	`string`	Source of the image. This should be an absolute url from your project root.
`alt`	`string`	Alt text
`caption`	`string`	Caption text
`formats`	`array`	Image formats to create and optimize for.
`widths`	`array`	`srcset` sizes to create and optimize for.

Please login to view this content

Splendid Labz is free because we love developers and we want to contribute back to the ecosystem.

We only charge for access to the documentation to keep the project going. If you don't wish to pay, feel free to use the content from the features tab, our blogs or our videos as your guide.