SwImage

<!-- Local image: automatically uses pregenerated avif/webp srcset -->
<SwImage src="/images/cover.jpg" alt="Cover" ratio="16/9" />

<!-- SVG: direct output, no optimization -->
<SwImage src="/images/logo.svg" alt="Logo" fit="contain" />

<!-- External image: no srcset -->
<SwImage src="https://picsum.photos/400/300" alt="Example" ratio="4/3" />

<!-- Per-image provider override: force 'noop' for signed URLs (bypass CDN transforms) -->
<SwImage :src="signedUrl" alt="Example" ratio="4/3" provider="noop" />

<!-- ✅ A fixed-width class straight on SwImage just works; inside a flex row add flex-shrink: 0 -->
<SwImage class="avatar" src="/a.jpg" alt="" ratio="1/1" />
<style>.avatar { width: 3rem; flex-shrink: 0; }</style>

<!-- ❌ Reaching in with :deep to absolutely position the container — fragile, and `fill` already does this -->
<style>.hero :deep(.sw-image) { position: absolute; inset: 0; }</style>

<!-- ✅ The parent handles positioning/height, SwImage takes `fill` -->
<div class="hero"><SwImage src="/h.jpg" alt="" fit="cover" fill /></div>
<style>.hero { position: relative; height: 24rem; }</style>

<!-- Hero image (LCP trio): eager loading + preload injects <link rel="preload">
     + fetchpriority maxes network priority (encrypted .bnc images don't support preload, see Caveats) -->
<SwImage src="/images/hero.jpg" alt="Hero" ratio="21/9" loading="eager" preload fetchpriority="high" :placeholder="false" />

<!-- Avatar: contain to show full image, 1:1 ratio -->
<SwImage src="/images/avatar.png" alt="Avatar" ratio="1/1" fit="contain" />

<!-- Blurred cover backdrop: blur applies Gaussian blur (common detail-page background pattern) -->
<SwImage src="/images/cover.jpg" alt="" :blur="12" ratio="16/9" />

<!-- With placeholder: show brand logo while loading -->
<SwImage src="/images/product.jpg" alt="Product" ratio="1/1" placeholder="/images/logo.svg" />

<!-- Listen to load events -->
<SwImage src="/images/cover.jpg" alt="Cover" @load="onLoad" @error="onError" />

<SwImage
  src="/images/cover.jpg"
  alt="Movie cover"
  ratio="3/4"
  class="hover-zoom"
  @click="goDetail"
>
  <div class="overlay">
    <span class="play-icon">▶</span>
    <span class="title">{{ item.title }}</span>
  </div>
</SwImage>

:root {
  --sw-image-hover-zoom-scale: 1.05; /* less aggressive */
  --sw-image-hover-zoom-duration: 0.6s; /* slower */
}

::alert{type="info"}
**Under `prefers-reduced-motion: reduce` the zoom is disabled automatically** — the component ships that fallback, you don't have to add it. Scaling counts as a non-essential animation and can trigger vertigo for users with vestibular disorders (standards UX-004 / WCAG 2.3.3).

The zoom also applies **only to the real image**: placeholders never scale (magnifying a placeholder logo while the image is still loading is pointless), and images inside your slot are left alone — that animation is yours to decide.
::
vue
<!-- placeholder-class: attach a custom class to the placeholder div (e.g. skeleton pulse animation) -->
<SwImage
  src="/images/cover.jpg"
  alt="..."
  placeholder-class="skeleton-pulse"
  :placeholder="{
    dark: '/images/placeholder-dark.png',
    light: '/images/placeholder-light.png',
  }"
/>

<SwImage src="/images/cover.jpg" alt="...">
  <template #placeholder>
    <div class="my-skeleton" />
  </template>
</SwImage>

<script setup lang="ts">
const imgRef = ref()

function measure() {
  const el = imgRef.value?.getElement()
  if (el) console.log(el.naturalWidth, el.naturalHeight) // intrinsic size of the real image
}
</script>

<template>
  <SwImage ref="imgRef" src="/images/cover.jpg" alt="Cover" @load="measure" />
</template>

<!-- Custom loading / error placeholder backgrounds -->
<style>
.sw-image .placeholder { --sw-image-placeholder-bg: #16110f; }
.sw-image .placeholder.is-error { --sw-image-placeholder-error-bg: #3c0001; }
</style>