Fix: Image Missing Required "alt" Property in Astro

What Causes This Error?

This error occurs when you use Astro’s <Image /> component without providing the required alt attribute. Alt text is essential for accessibility and is required by web standards.

The Problem

---
import { Image } from 'astro:assets';
import heroImage from '../assets/hero.jpg';
---

<!-- ❌ Missing alt attribute -->
<Image src={heroImage} />

The Fix

Add Alt Text

---
import { Image } from 'astro:assets';
import heroImage from '../assets/hero.jpg';
---

<!-- ✅ Descriptive alt text -->
<Image src={heroImage} alt="Mountain landscape at sunset" />

Empty Alt for Decorative Images

---
import { Image } from 'astro:assets';
import decorativeImage from '../assets/divider.png';
---

<!-- ✅ Empty alt for purely decorative images -->
<Image src={decorativeImage} alt="" />

Common Scenarios

Dynamic Alt Text

---
import { Image } from 'astro:assets';

const { image, title } = Astro.props;
---

<Image src={image} alt={`Photo of ${title}`} />

Content Collections

---
import { Image } from 'astro:assets';
import { getCollection } from 'astro:content';

const posts = await getCollection('blog');
---

{posts.map((post) => (
  <Image
    src={post.data.coverImage}
    alt={post.data.coverImageAlt || `Cover image for ${post.data.title}`}
  />
))}

Remote Images

---
import { Image } from 'astro:assets';
---

<Image
  src="https://example.com/image.jpg"
  alt="Description of the remote image"
  width={800}
  height={600}
/>

Picture Component

---
import { Picture } from 'astro:assets';
import photo from '../assets/photo.jpg';
---

<!-- Picture also requires alt -->
<Picture
  src={photo}
  alt="Portrait photo"
  formats={['avif', 'webp']}
/>

Writing Good Alt Text

<!-- ❌ Bad alt text -->
<Image src={photo} alt="image" />
<Image src={photo} alt="photo.jpg" />
<Image src={photo} alt="click here" />

<!-- ✅ Good alt text -->
<Image src={photo} alt="Golden retriever playing fetch in the park" />
<Image src={chart} alt="Bar chart showing sales growth from 2020 to 2024" />
<Image src={logo} alt="Acme Company logo" />

Conditional Alt Based on Context

---
import { Image } from 'astro:assets';

interface Props {
  image: ImageMetadata;
  isDecorative?: boolean;
  description?: string;
}

const { image, isDecorative = false, description } = Astro.props;
---

<Image
  src={image}
  alt={isDecorative ? '' : description || 'Image'}
/>

getImage Function

---
import { getImage } from 'astro:assets';
import rawImage from '../assets/photo.jpg';

const optimized = await getImage({
  src: rawImage,
  width: 800,
});
---

<!-- When using getImage, you handle the img tag yourself -->
<img src={optimized.src} alt="Your alt text here" {...optimized.attributes} />

Quick Checklist

• Every <Image /> needs an alt attribute
• Use descriptive text for informative images
• Use alt="" for purely decorative images
• Don’t start with “Image of” or “Picture of”
• Keep alt text concise but meaningful