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 '@splendidlabz/astro'
---

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

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

<Image src={image1} 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 format

There are lots of image formats out there, but the most performant one is are avif. We’ve built this into Image so you can optimize images without 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 400, 800, 1200, 1600 and the image’s original resolution. These let you serve appropriate images for almost every device users can use while lowering your page weight as much as possible.

These values are customizable if you wish to change them.

<!-- This is automatically generated -->
<figure>
  <picture>
    <source srcset="src1 600w, src2 1200w" type="image/avif" />
    <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 400w, src2 800w, src3 1200w, ..." type="image/avif" />
  <source srcset="src1 400w, src2 800w, src3 1200w, ..." type="image/webp" />
  <img
    src="path-to-image.jpg"
    srcset="src1 400w, src2 800w, 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 purchase a license to view this content

This content is part of our premium documentation. To access it, you'll need to have an active license for one of these products.

Get Layouts Get Basic Get Pro

If you already have a license, please login to access this content.

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 purchase a license to view this content

This content is part of our premium documentation. To access it, you'll need to have an active license for one of these products.

Get Layouts Get Basic Get Pro

If you already have a license, please login to access this content.

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 purchase a license to view this content

This content is part of our premium documentation. To access it, you'll need to have an active license for one of these products.

Get Layouts Get Basic Get Pro

If you already have a license, please login to access this content.