Library · Media & Buttons

Img

Section-imagery workhorse — lazy + async by default, arbitrary aspect-ratio, object-fit/position art direction, radius control. Pass imageComponent (astro:assets) for optimised local images or src for plain/CMS URLs. Complements Media (ratio presets, baked radius).

Live preview — edit theme bottom-right 
---
import Img from "../components/primitives/media/Img.astro";
---
<figure>
  <Img src="https://fakeimg.pl/720x405" alt="" aspectRatio="16/9" />
  <figcaption class="type-caption">aspectRatio="16/9" (defaults: cover, lazy)</figcaption>
</figure>
<figure>
  <Img
    src="https://fakeimg.pl/720x726"
    alt=""
    aspectRatio="360/363"
    position="top center"
    radius="20px 20px 0 0"
  />
  <figcaption class="type-caption">Team-card treatment — ratio + position + split radius</figcaption>
</figure>
<figure>
  <Img src="https://fakeimg.pl/720x720" alt="" aspectRatio="1/1" radius="50%" />
  <figcaption class="type-caption">aspectRatio="1/1" · radius="50%"</figcaption>
</figure>

Props

NameTypeRequiredDescription
src string — Image URL (plain <img>; use imageComponent for optimised local assets)
imageComponent ImageMetadata | Promise<{ default: ImageMetadata }> — Astro Image source — ImageMetadata or a Promise from import()
alt string Yes Alt text (required — pass "" only for decorative images)
aspectRatio string — CSS aspect-ratio, e.g. "16/9" or "360/363"
fit 'cover' | 'contain' | 'fill' | 'none' — object-fit (default: 'cover')
position string — object-position, e.g. 'top center' (default: 'center')
radius string — border-radius CSS value, e.g. '20px 20px 0 0'
loading 'lazy' | 'eager' — Loading strategy (default: 'lazy')
fetchpriority 'high' | 'low' | 'auto' — Fetch priority (default: 'auto')
width number — Intrinsic width (required for remote images via imageComponent)
height number — Intrinsic height (required for remote images via imageComponent)
class string — Additional classes
[key: string] any — HTML attributes

Example with all props

<Img
  src="/images/team-portrait.jpg"
  alt="Founding directors"
  aspectRatio="360/363"
  fit="cover"
  position="top center"
  radius="20px 20px 0 0"
  loading="lazy"
  fetchpriority="auto"
  width={720}
  height={726}
  class="card-img"
/>

<!-- Optimised local asset via astro:assets -->
<Img imageComponent={import("../assets/portrait.jpg")} alt="…" aspectRatio="4/3" />