Essential CSS
JavaScript Roadmap
Learn JavaScript
Mastering Web Typography
Practical Astro
Understanding Async JS
Unorthodox Tailwind
API Masterclass
Build and Deploy
The Beginner Freelancer
Real World Node
Profile Billing Logout
Practical Astro
Lesson Plan
  1. Content Systems
    1. Introduction
    2. An import alias
    3. Using Markdown
    4. Markdown extended
    5. Markdown component
    6. Markdown component in frameworks
    7. Content collections made easy
    8. Basic blogs
    9. Blogs made easy
    10. Prev/Next navigation
    11. Pagination made easy
    12. Better tag pages
    13. Paginated tag pages
    14. Markdown layouts
    15. Partials
    16. JS over JSON Data
    17. Dynamic 404 pages
    18. Putting everything together
    19. Other useful systems
  2. Image Systems
    1. Introduction
    2. Images are complicated because of this
    3. Astro's Image component
    4. Astro's Picture component
    5. Improvements over Astro's Image and Picture Components
    6. Images in Markdown and MDX
    7. Images in framework components
    8. Background images
    9. Art Direction with Astro
    10. Videos without layout shifts
    11. GIF Replacements and background video
    12. SVGs and icons
    13. SVG backgrounds
    14. Adding noise to images
    15. Asset caching on GitHub Actions
    16. Putting everything together
    17. Other useful systems

Putting everything together

2m:10s

You can now handle all the different image situations that may have slowed you down before.

Here are the 7 kinds of visual assets again:

  1. Standard images
  2. Background images
  3. Art direction
  4. Videos
  5. Background videos
  6. SVG icons and inline SVGs
  7. Background SVGs

I’ve put together a repository that gives you the code for each one of these image situations.

The Image Systems demo app — a grid of cards, each demonstrating one image-system technique

This gives you a different way to explore the patterns and copy the parts you want instead of reading through the lessons again.

You now have a pattern for every image situation Astro throws at you. The whole point of this module is that you stop deciding from scratch each time — you reach for the right tool. Here’s the decision map.

The decision map

A normal image on a page → Image. Import straight from /src/assets, get a responsive, optimized <picture> with a figure wrapper.

<Image src="/src/assets/photo.jpg" alt="..." />

An image that needs a caption → Image with caption.

A content image in Markdown/MDX → the Markdown image syntax for the common case; the Image component when you need control.

![Description](@/assets/photo.jpg)

A different crop per breakpoint → Picture with artDirection. Not just smaller — a genuinely different image.

An image behind content → a regular Image with object-background by default; BackgroundImage when you specifically need CSS background behavior like tiling.

An image inside a React/Svelte/Vue component → a slot first; the img utility when you need it as an optimized prop.

An icon or logo → Icon for icon-pack icons, SVG for your own SVGs — both inlined so you can style them. SVGBackground for decorative full-size patterns.

Motion that used to be a GIF → Video with gifReplacement.

A slow CI build → cache Astro’s image output between runs.

The two CSS lines that make it all work

None of this matters if your images stretch. Keep this in your global stylesheet:

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

The mindset

The hard part of images in Astro was never the code — it was knowing which approach fits which situation, and not relearning that on every project. You’ve now made those decisions once. Reuse them.

When a new image problem shows up, run it through the map above. The right pattern is almost always one you’ve already seen here.