From 4a62f80175d48146fa2a96cf6ce2a11952a3b3c7 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 16 Apr 2026 16:36:39 +0000
Subject: [PATCH 01/35] feat(Image): add headless Image component and useImage
 composable

Introduces a state-driven image loading system:

- `useImage` composable: idle/loading/loaded/error state machine with
  reactive `eager` gate, gated `source`, retry, and src-change reset.
- `Image` compound component: Root/Img/Placeholder/Fallback with optional
  IntersectionObserver-based lazy loading via the `lazy` prop. First-class
  support for modern image attributes (width/height/decoding/fetchpriority).

Refactors `AvatarImage` to use `useImage` internally, exposing `status`,
`isLoaded`, `isError`, and `retry` as new slot props. Selection logic and
priority-based multi-source behavior are unchanged.

https://claude.ai/code/session_01NMjcSYYdX2yniURgEfGrh4
---
 .../src/examples/components/image/basic.vue   |  26 ++
 .../examples/components/image/observer.vue    |  35 ++
 .../src/examples/components/image/picture.vue |  30 ++
 .../examples/composables/use-image/basic.vue  |  59 +++
 .../examples/composables/use-image/lazy.vue   |  47 ++
 .../examples/composables/use-image/retry.vue  |  41 ++
 apps/docs/src/pages/components/index.md       |   1 +
 .../src/pages/components/semantic/avatar.md   |  16 +
 .../src/pages/components/semantic/image.md    | 178 ++++++++
 apps/docs/src/pages/composables/index.md      |   1 +
 .../src/pages/composables/system/use-image.md | 123 +++++
 apps/docs/src/typed-router.d.ts               |  39 ++
 packages/0/README.md                          |   2 +
 .../0/src/components/Avatar/AvatarImage.vue   |  51 ++-
 .../0/src/components/Image/ImageFallback.vue  |  73 +++
 packages/0/src/components/Image/ImageImg.vue  | 154 +++++++
 .../src/components/Image/ImagePlaceholder.vue |  77 ++++
 packages/0/src/components/Image/ImageRoot.vue | 118 +++++
 packages/0/src/components/Image/index.test.ts | 422 ++++++++++++++++++
 packages/0/src/components/Image/index.ts      |  86 ++++
 packages/0/src/components/index.ts            |   1 +
 packages/0/src/composables/index.ts           |   1 +
 .../0/src/composables/useImage/index.test.ts  | 214 +++++++++
 packages/0/src/composables/useImage/index.ts  | 172 +++++++
 packages/0/src/maturity.json                  |   6 +-
 25 files changed, 1962 insertions(+), 11 deletions(-)
 create mode 100644 apps/docs/src/examples/components/image/basic.vue
 create mode 100644 apps/docs/src/examples/components/image/observer.vue
 create mode 100644 apps/docs/src/examples/components/image/picture.vue
 create mode 100644 apps/docs/src/examples/composables/use-image/basic.vue
 create mode 100644 apps/docs/src/examples/composables/use-image/lazy.vue
 create mode 100644 apps/docs/src/examples/composables/use-image/retry.vue
 create mode 100644 apps/docs/src/pages/components/semantic/image.md
 create mode 100644 apps/docs/src/pages/composables/system/use-image.md
 create mode 100644 packages/0/src/components/Image/ImageFallback.vue
 create mode 100644 packages/0/src/components/Image/ImageImg.vue
 create mode 100644 packages/0/src/components/Image/ImagePlaceholder.vue
 create mode 100644 packages/0/src/components/Image/ImageRoot.vue
 create mode 100644 packages/0/src/components/Image/index.test.ts
 create mode 100644 packages/0/src/components/Image/index.ts
 create mode 100644 packages/0/src/composables/useImage/index.test.ts
 create mode 100644 packages/0/src/composables/useImage/index.ts

diff --git a/apps/docs/src/examples/components/image/basic.vue b/apps/docs/src/examples/components/image/basic.vue
new file mode 100644
index 000000000..55ffbb6bc
--- /dev/null
+++ b/apps/docs/src/examples/components/image/basic.vue
@@ -0,0 +1,26 @@
+<script setup lang="ts">
+  import { Image } from '@vuetify/v0'
+</script>
+
+<template>
+  <Image.Root
+    class="w-100 h-75 bg-surface-tint rounded overflow-hidden relative"
+    src="https://picsum.photos/seed/v0-image/400/300"
+  >
+    <Image.Img
+      alt="Random photo"
+      class="w-full h-full object-cover"
+      height="300"
+      loading="lazy"
+      width="400"
+    />
+
+    <Image.Placeholder class="absolute inset-0 flex items-center justify-center">
+      <div class="w-full h-full bg-surface-tint animate-pulse" />
+    </Image.Placeholder>
+
+    <Image.Fallback class="absolute inset-0 flex items-center justify-center bg-error-container text-on-error-container text-sm">
+      Image failed to load
+    </Image.Fallback>
+  </Image.Root>
+</template>
diff --git a/apps/docs/src/examples/components/image/observer.vue b/apps/docs/src/examples/components/image/observer.vue
new file mode 100644
index 000000000..fad8b8eaf
--- /dev/null
+++ b/apps/docs/src/examples/components/image/observer.vue
@@ -0,0 +1,35 @@
+<script setup lang="ts">
+  import { Image } from '@vuetify/v0'
+</script>
+
+<template>
+  <div class="h-100 overflow-auto border border-divider rounded p-4">
+    <p class="text-sm text-on-surface-variant mb-4">
+      Scroll to bring the image into view — it will only start loading then.
+    </p>
+
+    <div class="h-100 flex items-center justify-center text-on-surface-variant">
+      Scroll down ↓
+    </div>
+
+    <Image.Root
+      class="w-100 h-75 bg-surface-tint rounded overflow-hidden relative mx-auto"
+      lazy
+      root-margin="100px"
+      src="https://picsum.photos/seed/observer/400/300"
+    >
+      <Image.Img
+        alt="Observer-driven photo"
+        class="w-full h-full object-cover transition-opacity duration-500"
+        height="300"
+        width="400"
+      />
+
+      <Image.Placeholder class="absolute inset-0 flex items-center justify-center text-on-surface-variant text-sm">
+        Waiting to enter viewport...
+      </Image.Placeholder>
+    </Image.Root>
+
+    <div class="h-100" />
+  </div>
+</template>
diff --git a/apps/docs/src/examples/components/image/picture.vue b/apps/docs/src/examples/components/image/picture.vue
new file mode 100644
index 000000000..2bde1be92
--- /dev/null
+++ b/apps/docs/src/examples/components/image/picture.vue
@@ -0,0 +1,30 @@
+/* eslint-disable vuejs-accessibility/alt-text */
+<script setup lang="ts">
+  import { Image } from '@vuetify/v0'
+</script>
+
+<template>
+  <Image.Root
+    renderless
+    src="https://picsum.photos/seed/picture/400/300"
+  >
+    <picture class="block w-100 h-75 bg-surface-tint rounded overflow-hidden relative">
+      <source srcset="https://picsum.photos/seed/picture/400/300.webp" type="image/webp">
+
+      <Image.Img
+        alt="Format-negotiated photo"
+        height="300"
+        renderless
+        width="400"
+      >
+        <template #default="{ attrs }">
+          <img v-bind="attrs" class="w-full h-full object-cover">
+        </template>
+      </Image.Img>
+
+      <Image.Placeholder class="absolute inset-0 flex items-center justify-center bg-surface-tint">
+        <span class="text-on-surface-variant text-sm">Loading...</span>
+      </Image.Placeholder>
+    </picture>
+  </Image.Root>
+</template>
diff --git a/apps/docs/src/examples/composables/use-image/basic.vue b/apps/docs/src/examples/composables/use-image/basic.vue
new file mode 100644
index 000000000..90e09c75b
--- /dev/null
+++ b/apps/docs/src/examples/composables/use-image/basic.vue
@@ -0,0 +1,59 @@
+/* eslint-disable vuejs-accessibility/alt-text */
+<script setup lang="ts">
+  import { useImage } from '@vuetify/v0'
+  import { shallowRef } from 'vue'
+
+  const src = shallowRef('https://picsum.photos/seed/v0/400/300')
+
+  const { source, status, isLoaded, isError, onLoad, onError } = useImage({
+    src,
+  })
+
+  function loadBroken () {
+    src.value = 'https://invalid.example/missing.jpg'
+  }
+
+  function loadValid () {
+    src.value = 'https://picsum.photos/seed/v0/400/300'
+  }
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-4">
+    <div class="w-100 h-75 bg-surface-tint rounded overflow-hidden flex items-center justify-center">
+      <img
+        v-show="isLoaded"
+        alt="Random photo"
+        class="w-full h-full object-cover"
+        :src="source"
+        @error="onError"
+        @load="onLoad"
+      >
+      <span v-if="!isLoaded && !isError" class="text-on-surface-variant text-sm">
+        Loading...
+      </span>
+      <span v-if="isError" class="text-error text-sm">
+        Failed to load
+      </span>
+    </div>
+
+    <div class="flex gap-2">
+      <button
+        class="px-3 py-1 bg-primary text-on-primary rounded text-sm"
+        @click="loadValid"
+      >
+        Load valid
+      </button>
+      <button
+        class="px-3 py-1 bg-error text-on-error rounded text-sm"
+        @click="loadBroken"
+      >
+        Load broken
+      </button>
+    </div>
+
+    <p class="text-xs text-on-surface-variant">
+      Status: <code>{{ status }}</code>
+    </p>
+  </div>
+</template>
diff --git a/apps/docs/src/examples/composables/use-image/lazy.vue b/apps/docs/src/examples/composables/use-image/lazy.vue
new file mode 100644
index 000000000..a20c77b86
--- /dev/null
+++ b/apps/docs/src/examples/composables/use-image/lazy.vue
@@ -0,0 +1,47 @@
+/* eslint-disable vuejs-accessibility/alt-text */
+<script setup lang="ts">
+  import { useImage, useIntersectionObserver } from '@vuetify/v0'
+  import { shallowRef } from 'vue'
+
+  const target = shallowRef<HTMLElement>()
+
+  const { isIntersecting } = useIntersectionObserver(target, () => {}, {
+    once: true,
+    rootMargin: '0px',
+  })
+
+  const { source, isLoaded, status, onLoad, onError } = useImage({
+    src: 'https://picsum.photos/seed/lazy/400/300',
+    eager: isIntersecting,
+  })
+</script>
+
+<template>
+  <div class="flex flex-col gap-4">
+    <p class="text-sm text-on-surface-variant">
+      Scroll the image into view to start loading.
+    </p>
+
+    <div class="h-100 overflow-auto border border-divider rounded p-4">
+      <div class="h-100 flex items-center justify-center text-on-surface-variant">
+        Scroll down ↓
+      </div>
+
+      <div ref="target" class="w-100 h-75 bg-surface-tint rounded overflow-hidden flex items-center justify-center mx-auto">
+        <img
+          v-show="isLoaded"
+          alt="Lazy-loaded photo"
+          class="w-full h-full object-cover"
+          :src="source"
+          @error="onError"
+          @load="onLoad"
+        >
+        <span v-if="!isLoaded" class="text-on-surface-variant text-sm">
+          {{ status }}
+        </span>
+      </div>
+
+      <div class="h-100" />
+    </div>
+  </div>
+</template>
diff --git a/apps/docs/src/examples/composables/use-image/retry.vue b/apps/docs/src/examples/composables/use-image/retry.vue
new file mode 100644
index 000000000..19d6688b7
--- /dev/null
+++ b/apps/docs/src/examples/composables/use-image/retry.vue
@@ -0,0 +1,41 @@
+/* eslint-disable vuejs-accessibility/alt-text */
+<script setup lang="ts">
+  import { useImage } from '@vuetify/v0'
+
+  const { source, isLoaded, isError, status, onLoad, onError, retry } = useImage({
+    src: 'https://invalid.example/missing.jpg',
+  })
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-4">
+    <div class="w-100 h-75 bg-surface-tint rounded overflow-hidden flex flex-col items-center justify-center gap-2">
+      <img
+        v-show="isLoaded"
+        alt="Photo"
+        class="w-full h-full object-cover"
+        :src="source"
+        @error="onError"
+        @load="onLoad"
+      >
+
+      <template v-if="isError">
+        <span class="text-error text-sm">Failed to load</span>
+        <button
+          class="px-3 py-1 bg-primary text-on-primary rounded text-sm"
+          @click="retry"
+        >
+          Retry
+        </button>
+      </template>
+
+      <span v-else-if="!isLoaded" class="text-on-surface-variant text-sm">
+        Loading...
+      </span>
+    </div>
+
+    <p class="text-xs text-on-surface-variant">
+      Status: <code>{{ status }}</code>
+    </p>
+  </div>
+</template>
diff --git a/apps/docs/src/pages/components/index.md b/apps/docs/src/pages/components/index.md
index fe16e97af..9cfad9c13 100644
--- a/apps/docs/src/pages/components/index.md
+++ b/apps/docs/src/pages/components/index.md
@@ -77,6 +77,7 @@ Components with meaningful HTML defaults. Render semantic elements by default bu
 | [Avatar](/components/semantic/avatar) | Image/fallback avatar with priority loading |
 | [Breadcrumbs](/components/semantic/breadcrumbs) | Navigation breadcrumbs with overflow detection and truncation |
 | [Carousel](/components/semantic/carousel) | Scroll-snap slide navigation with multi-slide display and drag/swipe |
+| [Image](/components/semantic/image) | Image with placeholder, error fallback, and lazy loading |
 | [Pagination](/components/semantic/pagination) | Page navigation with semantic `<nav>` wrapper |
 | [Progress](/components/semantic/progress/) | Headless progress bar with multi-segment and buffer support |
 | [Snackbar](/components/semantic/snackbar) | Toast notification with queue, positioning, and auto-dismiss |
diff --git a/apps/docs/src/pages/components/semantic/avatar.md b/apps/docs/src/pages/components/semantic/avatar.md
index fe1a60eb2..03efedb6e 100644
--- a/apps/docs/src/pages/components/semantic/avatar.md
+++ b/apps/docs/src/pages/components/semantic/avatar.md
@@ -13,6 +13,8 @@ features:
   level: 2
 related:
   - /components/primitives/atom
+  - /components/semantic/image
+  - /composables/system/use-image
 ---
 
 # Avatar
@@ -82,6 +84,20 @@ flowchart TD
   FallbackReg -->|"Selected by default<br/>until image loads"| FallbackVisible
 ```
 
+> [!TIP]
+> For single-source content images with placeholder and error fallback, use [Image](/components/semantic/image) instead. Avatar specializes in identity / profile UIs with priority-based multi-source fallback.
+
+### Loading state slot props
+
+`Avatar.Image` exposes the underlying loading state from `useImage` via slot props. Use these for custom transitions, retry UI, or status indicators.
+
+| Slot prop | Purpose |
+|-----------|---------|
+| `status` | Current state: `'idle' \| 'loading' \| 'loaded' \| 'error'` |
+| `isLoaded` | True when the image has loaded successfully |
+| `isError` | True when the image failed to load |
+| `retry` | Reset the image and re-attempt loading |
+
 ### Priority System
 
 When multiple images are present, the `priority` prop determines display order. Higher priority images are preferred when loaded:
diff --git a/apps/docs/src/pages/components/semantic/image.md b/apps/docs/src/pages/components/semantic/image.md
new file mode 100644
index 000000000..c54661b8a
--- /dev/null
+++ b/apps/docs/src/pages/components/semantic/image.md
@@ -0,0 +1,178 @@
+---
+title: Image - Headless Image Component with Placeholder and Fallback
+meta:
+- name: description
+  content: Headless Vue 3 image component with state-driven placeholder, error fallback, retry support, and optional IntersectionObserver-based lazy loading.
+- name: keywords
+  content: image, lazy loading, placeholder, fallback, fetchpriority, srcset, picture, Vue 3, headless, retry
+features:
+  category: Component
+  label: 'C: Image'
+  github: /components/Image/
+  renderless: false
+  level: 2
+related:
+  - /composables/system/use-image
+  - /components/semantic/avatar
+  - /composables/system/use-intersection-observer
+---
+
+# Image
+
+Headless image component with state-driven placeholder and error fallback. Tracks the loading lifecycle and exposes `retry()`, with optional IntersectionObserver-driven lazy loading.
+
+<DocsPageFeatures :frontmatter />
+
+## Usage
+
+`Image.Root` owns the loading state machine via `useImage`. `Image.Img` renders the image element and reports load and error events to the context. `Image.Placeholder` is shown while idle or loading; `Image.Fallback` is shown on error.
+
+::: example
+/components/image/basic
+
+### Image with placeholder and fallback
+
+The basic compound: a placeholder during loading, the image when loaded, and a fallback on error. Native `loading="lazy"` defers the request until the browser deems it necessary.
+
+:::
+
+## Anatomy
+
+```vue Anatomy playground collapse
+<script setup lang="ts">
+  import { Image } from '@vuetify/v0'
+</script>
+
+<template>
+  <Image.Root>
+    <Image.Img />
+
+    <Image.Placeholder />
+
+    <Image.Fallback />
+  </Image.Root>
+</template>
+```
+
+## Architecture
+
+`Image.Root` calls `useImage` to manage status, and optionally wires up `useIntersectionObserver` when the `lazy` prop is set. Children consume the root context via `useImageRoot`.
+
+```mermaid "Image lifecycle"
+stateDiagram-v2
+  [*] --> idle: lazy = true
+  [*] --> loading: lazy = false
+  idle --> loading: enters viewport
+  loading --> loaded: img.onload
+  loading --> error: img.onerror
+  loaded --> loading: src changes
+  error --> loading: retry / src changes
+```
+
+### Lazy loading strategies
+
+The component supports two distinct lazy loading mechanisms — pick the one that matches your requirements.
+
+| Strategy | How | When to use |
+| - | - | - |
+| Native | `loading="lazy"` on `Image.Img` | Most below-the-fold images. Zero JS, browser-managed. |
+| Observer | `lazy` prop on `Image.Root` | When you need precise control over when the source is set — e.g. blur-up transitions, prefetch, or custom intersection thresholds. |
+
+You can combine both: use the observer for state control and `loading="lazy"` as a fallback for browsers without IntersectionObserver support.
+
+## Examples
+
+::: example
+/components/image/observer
+
+### Observer-driven lazy loading
+
+`lazy` on `Image.Root` defers the request until the root element intersects the viewport. The placeholder is visible while idle.
+
+:::
+
+::: example
+/components/image/picture
+
+### Picture element with format negotiation
+
+Use `renderless` mode on both `Image.Root` and `Image.Img` to drop the wrappers and emit a native `<picture>` element with `<source>` children for format negotiation.
+
+:::
+
+## Recipes
+
+### Hero image with high priority
+
+Set `loading="eager"` and `fetchpriority="high"` on hero images to optimize LCP. Always include `width` and `height` to prevent layout shift.
+
+```vue
+<Image.Root src="/hero.jpg">
+  <Image.Img
+    alt="Hero"
+    width="1600"
+    height="900"
+    loading="eager"
+    fetchpriority="high"
+  />
+  <Image.Placeholder>
+    <img src="/hero-tiny.jpg" class="w-full blur-sm" />
+  </Image.Placeholder>
+</Image.Root>
+```
+
+### Retry on error
+
+The `retry()` function is available from both `Image.Root` and `Image.Fallback` slot props.
+
+```vue
+<Image.Root src="/photo.jpg">
+  <Image.Img alt="Photo" />
+  <Image.Placeholder>Loading...</Image.Placeholder>
+  <Image.Fallback v-slot="{ retry }">
+    <button @click="retry">Retry</button>
+  </Image.Fallback>
+</Image.Root>
+```
+
+## Accessibility
+
+| Element | ARIA / behavior |
+| - | - |
+| `Image.Img` | `role="img"`, accepts `alt` for accessible name |
+| `Image.Placeholder` | `aria-hidden="true"` — placeholder is decorative |
+| `Image.Fallback` | `role="img"` — provide alternate text inside the slot |
+
+Always pass `width` and `height` props on `Image.Img` to reserve layout space and prevent Cumulative Layout Shift while the image loads.
+
+## FAQ
+
+::: faq
+
+??? When should I use Avatar vs Image?
+
+`Avatar` is for identity / profile UIs with priority-based multi-source fallback (e.g. high-res then low-res then initials). `Image` is for general content images with state-driven placeholder and fallback for a single source.
+
+??? Should I use the `lazy` prop or the `loading="lazy"` attribute?
+
+Use native `loading="lazy"` for most cases — it's declarative, zero-JS, and browser-managed. Use the `lazy` prop on `Image.Root` only when you need to control exactly when the source is set, such as for blur-up transitions, prefetching, or custom intersection thresholds.
+
+??? How do I prevent layout shift?
+
+Always set `width` and `height` on `Image.Img`. The browser uses these to reserve space before the image loads, eliminating Cumulative Layout Shift.
+
+??? Can I use a `<picture>` element with multiple `<source>` formats?
+
+Yes — set `renderless` on both `Image.Root` and `Image.Img`, then compose them inside a native `<picture>` element. See the picture example.
+
+??? How do I fade in once the image loads?
+
+Use the `status` slot prop from `Image.Root` to drive CSS classes, e.g. `:class="{ 'opacity-100': status === 'loaded' }"`.
+
+??? Why isn't `src` on `Image.Img`?
+
+`src` lives on `Image.Root` because it owns the state machine — the source is what the state is about. `Image.Img` accepts the rendering attributes (`alt`, `width`, `height`, `srcset`, `sizes`, etc.) that belong to the rendered element.
+
+:::
+
+<DocsApi />
diff --git a/apps/docs/src/pages/composables/index.md b/apps/docs/src/pages/composables/index.md
index 9be9fee96..498b8662b 100644
--- a/apps/docs/src/pages/composables/index.md
+++ b/apps/docs/src/pages/composables/index.md
@@ -262,6 +262,7 @@ Browser API wrappers with automatic lifecycle cleanup.
 | [useClickOutside](/composables/system/use-click-outside) | Detect clicks outside an element |
 | [useEventListener](/composables/system/use-event-listener) | Handle DOM events with automatic cleanup |
 | [useHotkey](/composables/system/use-hotkey) | Handle hotkey combinations and sequences |
+| [useImage](/composables/system/use-image) | Image loading state machine with deferred loading and retry |
 | [useIntersectionObserver](/composables/system/use-intersection-observer) | Intersection Observer API for visibility detection |
 | [useLazy](/composables/system/use-lazy) | Defer rendering until first activation for dialogs, menus, and tooltips |
 | [useMediaQuery](/composables/system/use-media-query) | Reactive CSS media query matching |
diff --git a/apps/docs/src/pages/composables/system/use-image.md b/apps/docs/src/pages/composables/system/use-image.md
new file mode 100644
index 000000000..1f30ec101
--- /dev/null
+++ b/apps/docs/src/pages/composables/system/use-image.md
@@ -0,0 +1,123 @@
+---
+title: useImage - Image Loading State Composable for Vue 3
+meta:
+- name: description
+  content: Reactive image loading state machine with idle, loading, loaded, and error states. Supports deferred loading via an eager gate and retry semantics.
+- name: keywords
+  content: useImage, image loading, lazy loading, intersection observer, Vue 3, composable, state machine, retry
+features:
+  category: Composable
+  label: 'E: useImage'
+  github: /composables/useImage/
+  level: 2
+related:
+  - /composables/system/use-intersection-observer
+  - /composables/system/use-lazy
+  - /components/semantic/image
+  - /components/semantic/avatar
+---
+
+# useImage
+
+Tracks image loading state as a reactive state machine with idle, loading, loaded, and error states.
+
+<DocsPageFeatures :frontmatter />
+
+## Usage
+
+The `useImage` composable owns the loading lifecycle for a single image source.
+Bind the returned `source`, `onLoad`, and `onError` to a plain image element.
+
+```ts collapse no-filename
+import { toRef } from 'vue'
+import { useImage } from '@vuetify/v0'
+
+const props = defineProps<{ src: string }>()
+
+const { source, isLoaded, isError, onLoad, onError, retry } = useImage({
+  src: toRef(() => props.src),
+})
+
+// In template:
+// <img :src="source" @load="onLoad" @error="onError" />
+```
+
+## Architecture
+
+```mermaid "useImage state machine"
+stateDiagram-v2
+  [*] --> idle: eager = false
+  [*] --> loading: eager = true
+  idle --> loading: eager flips true
+  loading --> loaded: onLoad
+  loading --> error: onError
+  loaded --> loading: src changes
+  error --> loading: retry / src changes
+```
+
+## Reactivity
+
+| Property/Method | Reactive | Notes |
+| - | :-: | - |
+| `status` | <AppSuccessIcon /> | Readonly ShallowRef of `'idle' \| 'loading' \| 'loaded' \| 'error'` |
+| `isIdle` / `isLoading` / `isLoaded` / `isError` | <AppSuccessIcon /> | Readonly boolean refs derived from `status` |
+| `source` | <AppSuccessIcon /> | Gated `src` — `undefined` while idle, otherwise the current source |
+| `onLoad` / `onError` | <AppErrorIcon /> | Bind to image `load` / `error` events |
+| `retry` | <AppErrorIcon /> | Reset back to `loading` and re-attempt |
+
+## Examples
+
+::: example
+/composables/use-image/basic
+
+### Basic state tracking
+
+A plain image element wired up with `useImage`. Status updates as the image loads, errors, or is replaced with a new source.
+
+:::
+
+::: example
+/composables/use-image/lazy
+
+### Composed with useIntersectionObserver
+
+Pair `useImage` with `useIntersectionObserver` for viewport-driven lazy loading. The `eager` gate withholds the source until the target intersects.
+
+:::
+
+::: example
+/composables/use-image/retry
+
+### Retry on error
+
+When the image errors, `retry()` resets the status back to `loading` so the browser re-attempts the request.
+
+:::
+
+## FAQ
+
+::: faq
+
+??? Why is the option called `eager` instead of `lazy`?
+
+`eager` is a reactive gate that mirrors the semantics of HTML's `loading="eager"` attribute — when `eager` is `true`, the image starts loading. When `false`, the source is withheld and status stays `idle`. Using `eager` lets you write expressive bindings like `eager: isIntersecting`.
+
+??? Does `useImage` use IntersectionObserver internally?
+
+No. `useImage` is the state machine; viewport detection is a separate concern. Compose it with `useIntersectionObserver` (or any other reactive gate) by passing the result to the `eager` option.
+
+??? What about native `loading="lazy"`?
+
+Native browser-level lazy loading is a separate mechanism. The browser still fires `load` and `error` events, so `useImage` works correctly with or without it. Reach for the `eager` gate only when you need to control exactly when the source is set.
+
+??? What happens when `src` changes?
+
+Status resets to `loading` (or `idle` if `eager` is `false`) and the source updates. Already-loaded or errored states do not persist across source changes.
+
+??? Why does `source` return `undefined` while idle?
+
+So you can bind it directly to an `<img>` element without the browser starting a request. The browser ignores `<img>` elements without a `src`, which is exactly what you want during the deferred phase.
+
+:::
+
+<DocsApi />
diff --git a/apps/docs/src/typed-router.d.ts b/apps/docs/src/typed-router.d.ts
index e2e120c93..fd63ea881 100644
--- a/apps/docs/src/typed-router.d.ts
+++ b/apps/docs/src/typed-router.d.ts
@@ -279,6 +279,20 @@ declare module 'vue-router/auto-routes' {
       Record<never, never>,
       | never
     >,
+    '/components/semantic/carousel': RouteRecordInfo<
+      '/components/semantic/carousel',
+      '/components/semantic/carousel',
+      Record<never, never>,
+      Record<never, never>,
+      | never
+    >,
+    '/components/semantic/image': RouteRecordInfo<
+      '/components/semantic/image',
+      '/components/semantic/image',
+      Record<never, never>,
+      Record<never, never>,
+      | never
+    >,
     '/components/semantic/pagination': RouteRecordInfo<
       '/components/semantic/pagination',
       '/components/semantic/pagination',
@@ -636,6 +650,13 @@ declare module 'vue-router/auto-routes' {
       Record<never, never>,
       | never
     >,
+    '/composables/system/use-image': RouteRecordInfo<
+      '/composables/system/use-image',
+      '/composables/system/use-image',
+      Record<never, never>,
+      Record<never, never>,
+      | never
+    >,
     '/composables/system/use-intersection-observer': RouteRecordInfo<
       '/composables/system/use-intersection-observer',
       '/composables/system/use-intersection-observer',
@@ -1215,6 +1236,18 @@ declare module 'vue-router/auto-routes' {
       views:
         | never
     }
+    'src/pages/components/semantic/carousel.md': {
+      routes:
+        | '/components/semantic/carousel'
+      views:
+        | never
+    }
+    'src/pages/components/semantic/image.md': {
+      routes:
+        | '/components/semantic/image'
+      views:
+        | never
+    }
     'src/pages/components/semantic/pagination.md': {
       routes:
         | '/components/semantic/pagination'
@@ -1521,6 +1554,12 @@ declare module 'vue-router/auto-routes' {
       views:
         | never
     }
+    'src/pages/composables/system/use-image.md': {
+      routes:
+        | '/composables/system/use-image'
+      views:
+        | never
+    }
     'src/pages/composables/system/use-intersection-observer.md': {
       routes:
         | '/composables/system/use-intersection-observer'
diff --git a/packages/0/README.md b/packages/0/README.md
index 67fcd3e30..14e3563f3 100644
--- a/packages/0/README.md
+++ b/packages/0/README.md
@@ -138,6 +138,7 @@ import { ... } from '@vuetify/v0/date'       // Date adapter and utilities
 | [Avatar](https://0.vuetifyjs.com/components/semantic/avatar) | Image/fallback avatar with priority loading |
 | [Breadcrumbs](https://0.vuetifyjs.com/components/semantic/breadcrumbs) | Navigation breadcrumbs with overflow detection and truncation |
 | [Carousel](https://0.vuetifyjs.com/components/semantic/carousel) | Scroll-snap slide navigation with multi-slide display and drag/swipe |
+| [Image](https://0.vuetifyjs.com/components/semantic/image) | Image with placeholder, error fallback, and lazy loading |
 | [Pagination](https://0.vuetifyjs.com/components/semantic/pagination) | Page navigation with semantic `<nav>` wrapper |
 | [Snackbar](https://0.vuetifyjs.com/components/semantic/snackbar) | Toast notification with queue, positioning, and auto-dismiss |
 | [Splitter](https://0.vuetifyjs.com/components/semantic/splitter) | Resizable panel layout with drag handles |
@@ -210,6 +211,7 @@ Selection management composables built on `createRegistry`:
 - [`useClickOutside`](https://0.vuetifyjs.com/composables/system/use-click-outside) - Click outside detection with cleanup
 - [`useEventListener`](https://0.vuetifyjs.com/composables/system/use-event-listener) - Lifecycle-managed event listeners
 - [`useHotkey`](https://0.vuetifyjs.com/composables/system/use-hotkey) - Hotkey combinations and sequences
+- [`useImage`](https://0.vuetifyjs.com/composables/system/use-image) - Image loading state machine with deferred loading and retry
 - [`useIntersectionObserver`](https://0.vuetifyjs.com/composables/system/use-intersection-observer) - Intersection observer with auto-cleanup
 - [`useLazy`](https://0.vuetifyjs.com/composables/system/use-lazy) - Deferred content rendering for dialogs, menus, and tooltips
 - [`useMediaQuery`](https://0.vuetifyjs.com/composables/system/use-media-query) - Reactive CSS media query matching
diff --git a/packages/0/src/components/Avatar/AvatarImage.vue b/packages/0/src/components/Avatar/AvatarImage.vue
index db2bc53fe..9a5b4195e 100644
--- a/packages/0/src/components/Avatar/AvatarImage.vue
+++ b/packages/0/src/components/Avatar/AvatarImage.vue
@@ -4,14 +4,19 @@
  * @see https://0.vuetifyjs.com/components/semantic/avatar
  *
  * @remarks
- * Image component that registers with the Avatar context and manages loading state.
- * Automatically shows when loaded and hides on error. Supports priority ordering
- * so higher-priority images are displayed when multiple are available.
+ * Image component that registers with the Avatar context and manages loading state
+ * via useImage. Automatically shows when loaded and hides on error. Supports
+ * priority ordering so higher-priority images are displayed when multiple are
+ * available.
  */
 
 <script lang="ts">
+  // Composables
+  import { useImage } from '#v0/composables/useImage'
+
   // Types
   import type { AtomProps } from '#v0/components/Atom'
+  import type { ImageStatus } from '#v0/composables/useImage'
 
   export interface AvatarImageProps extends AtomProps {
     /** Image source URL */
@@ -30,6 +35,14 @@
   export interface AvatarImageSlotProps {
     /** Whether this image is currently visible */
     isSelected: boolean
+    /** Current loading status */
+    status: ImageStatus
+    /** Whether the image has loaded successfully */
+    isLoaded: boolean
+    /** Whether the image failed to load */
+    isError: boolean
+    /** Reset the image and re-attempt loading */
+    retry: () => void
     /** Attributes to bind to the image element */
     attrs: {
       role: 'img'
@@ -47,7 +60,7 @@
   import { useAvatarRoot } from './AvatarRoot.vue'
 
   // Utilities
-  import { onUnmounted, toRef } from 'vue'
+  import { onUnmounted, toRef, watch } from 'vue'
 
   defineOptions({
     name: 'AvatarImage',
@@ -70,6 +83,8 @@
 
   const context = useAvatarRoot(namespace)
 
+  const image = useImage({ src: toRef(() => src) })
+
   const ticket = context.register({
     priority,
     type: 'image',
@@ -77,27 +92,43 @@
   })
 
   function onLoad (e: Event) {
-    ticket.disabled = false
-    ticket.select()
+    image.onLoad(e)
     emit('load', e)
   }
 
   function onError (e: Event) {
-    ticket.disabled = true
-    const first = context.seek('first')
-    if (first) context.select(first.id)
+    image.onError(e)
     emit('error', e)
   }
 
+  watch(image.isLoaded, isLoaded => {
+    if (isLoaded) {
+      ticket.disabled = false
+      ticket.select()
+    }
+  })
+
+  watch(image.isError, isError => {
+    if (isError) {
+      ticket.disabled = true
+      const first = context.seek('first')
+      if (first) context.select(first.id)
+    }
+  })
+
   onUnmounted(() => {
     context.unregister(ticket.id)
   })
 
   const slotProps = toRef((): AvatarImageSlotProps => ({
     isSelected: ticket.isSelected.value,
+    status: image.status.value,
+    isLoaded: image.isLoaded.value,
+    isError: image.isError.value,
+    retry: image.retry,
     attrs: {
       role: 'img',
-      src,
+      src: image.source.value,
       onLoad,
       onError,
     },
diff --git a/packages/0/src/components/Image/ImageFallback.vue b/packages/0/src/components/Image/ImageFallback.vue
new file mode 100644
index 000000000..05e035426
--- /dev/null
+++ b/packages/0/src/components/Image/ImageFallback.vue
@@ -0,0 +1,73 @@
+/**
+ * @module ImageFallback
+ *
+ * @see https://0.vuetifyjs.com/components/semantic/image
+ *
+ * @remarks
+ * Fallback content shown when the image fails to load. Exposes a `retry`
+ * function via slot props so consumers can build retry UI.
+ */
+
+<script lang="ts">
+  // Composables
+  import { useImageRoot } from './ImageRoot.vue'
+
+  // Types
+  import type { AtomProps } from '#v0/components/Atom'
+
+  export interface ImageFallbackProps extends AtomProps {
+    /** Namespace for retrieving the Image context. */
+    namespace?: string
+  }
+
+  export interface ImageFallbackSlotProps {
+    /** Reset the image and re-attempt loading. */
+    retry: () => void
+    /** Attributes to bind to the fallback element. */
+    attrs: {
+      'role': 'img'
+      'data-state': 'error'
+    }
+  }
+</script>
+
+<script setup lang="ts">
+  // Components
+  import { Atom } from '#v0/components/Atom'
+
+  // Utilities
+  import { toRef } from 'vue'
+
+  defineOptions({ name: 'ImageFallback' })
+
+  defineSlots<{
+    default: (props: ImageFallbackSlotProps) => any
+  }>()
+
+  const {
+    as = 'div',
+    renderless,
+    namespace = 'v0:image',
+  } = defineProps<ImageFallbackProps>()
+
+  const context = useImageRoot(namespace)
+
+  const slotProps = toRef((): ImageFallbackSlotProps => ({
+    retry: context.retry,
+    attrs: {
+      'role': 'img',
+      'data-state': 'error',
+    },
+  }))
+</script>
+
+<template>
+  <Atom
+    v-if="context.isError.value"
+    v-bind="slotProps.attrs"
+    :as
+    :renderless
+  >
+    <slot v-bind="slotProps" />
+  </Atom>
+</template>
diff --git a/packages/0/src/components/Image/ImageImg.vue b/packages/0/src/components/Image/ImageImg.vue
new file mode 100644
index 000000000..fd1e4f1b7
--- /dev/null
+++ b/packages/0/src/components/Image/ImageImg.vue
@@ -0,0 +1,154 @@
+/**
+ * @module ImageImg
+ *
+ * @see https://0.vuetifyjs.com/components/semantic/image
+ *
+ * @remarks
+ * The image element. Reads the gated source and load/error handlers from the
+ * Image context and binds them to the rendered element. Visible only when the
+ * parent's status is loaded.
+ */
+
+<script lang="ts">
+  // Composables
+  import { useImageRoot } from './ImageRoot.vue'
+
+  // Types
+  import type { AtomProps } from '#v0/components/Atom'
+  import type { ImageStatus } from '#v0/composables/useImage'
+
+  export interface ImageImgProps extends AtomProps {
+    /** Accessible alt text. */
+    alt?: string
+    /** Responsive image candidates. */
+    srcset?: string
+    /** Image sizes hint for responsive selection. */
+    sizes?: string
+    /** Intrinsic image width — set to prevent layout shift. */
+    width?: number | string
+    /** Intrinsic image height — set to prevent layout shift. */
+    height?: number | string
+    /** CORS request mode. */
+    crossorigin?: '' | 'anonymous' | 'use-credentials'
+    /** Referrer policy for the request. */
+    referrerpolicy?: string
+    /** How the browser should decode the image. */
+    decoding?: 'sync' | 'async' | 'auto'
+    /** Native browser-managed lazy loading hint. */
+    loading?: 'eager' | 'lazy'
+    /** Resource priority hint. */
+    fetchpriority?: 'high' | 'low' | 'auto'
+    /** Namespace for retrieving the Image context. */
+    namespace?: string
+  }
+
+  export interface ImageImgEmits {
+    load: [e: Event]
+    error: [e: Event]
+  }
+
+  export interface ImageImgSlotProps {
+    /** Whether the image has loaded successfully. */
+    isLoaded: boolean
+    /** Current loading status. */
+    status: ImageStatus
+    /** Attributes to bind to the image element. */
+    attrs: {
+      'role': 'img'
+      'src': string | undefined
+      'srcset': string | undefined
+      'sizes': string | undefined
+      'alt': string | undefined
+      'width': number | string | undefined
+      'height': number | string | undefined
+      'crossorigin': '' | 'anonymous' | 'use-credentials' | undefined
+      'referrerpolicy': string | undefined
+      'decoding': 'sync' | 'async' | 'auto'
+      'loading': 'eager' | 'lazy' | undefined
+      'fetchpriority': 'high' | 'low' | 'auto' | undefined
+      'data-state': ImageStatus
+      'onLoad': (e: Event) => void
+      'onError': (e: Event) => void
+    }
+  }
+</script>
+
+<script setup lang="ts">
+  // Components
+  import { Atom } from '#v0/components/Atom'
+
+  // Utilities
+  import { toRef } from 'vue'
+
+  defineOptions({
+    name: 'ImageImg',
+    inheritAttrs: false,
+  })
+
+  defineSlots<{
+    default: (props: ImageImgSlotProps) => any
+  }>()
+
+  const {
+    as = 'img',
+    renderless,
+    alt,
+    srcset,
+    sizes,
+    width,
+    height,
+    crossorigin,
+    referrerpolicy,
+    decoding = 'async',
+    loading,
+    fetchpriority,
+    namespace = 'v0:image',
+  } = defineProps<ImageImgProps>()
+
+  const emit = defineEmits<ImageImgEmits>()
+
+  const context = useImageRoot(namespace)
+
+  function onLoad (e: Event) {
+    context.onLoad(e)
+    emit('load', e)
+  }
+
+  function onError (e: Event) {
+    context.onError(e)
+    emit('error', e)
+  }
+
+  const slotProps = toRef((): ImageImgSlotProps => ({
+    isLoaded: context.isLoaded.value,
+    status: context.status.value,
+    attrs: {
+      'role': 'img',
+      'src': context.source.value,
+      srcset,
+      sizes,
+      alt,
+      width,
+      height,
+      crossorigin,
+      referrerpolicy,
+      decoding,
+      loading,
+      fetchpriority,
+      'data-state': context.status.value,
+      onLoad,
+      onError,
+    },
+  }))
+</script>
+
+<template>
+  <Atom
+    v-show="context.isLoaded.value"
+    v-bind="slotProps.attrs"
+    :as
+    :renderless
+  >
+    <slot v-bind="slotProps" />
+  </Atom>
+</template>
diff --git a/packages/0/src/components/Image/ImagePlaceholder.vue b/packages/0/src/components/Image/ImagePlaceholder.vue
new file mode 100644
index 000000000..f8b598a9a
--- /dev/null
+++ b/packages/0/src/components/Image/ImagePlaceholder.vue
@@ -0,0 +1,77 @@
+/**
+ * @module ImagePlaceholder
+ *
+ * @see https://0.vuetifyjs.com/components/semantic/image
+ *
+ * @remarks
+ * Placeholder content shown while the image is `idle` or `loading`. Hidden
+ * once the image has loaded or errored. Marked `aria-hidden` since it is
+ * purely decorative.
+ */
+
+<script lang="ts">
+  // Composables
+  import { useImageRoot } from './ImageRoot.vue'
+
+  // Types
+  import type { AtomProps } from '#v0/components/Atom'
+  import type { ImageStatus } from '#v0/composables/useImage'
+
+  export interface ImagePlaceholderProps extends AtomProps {
+    /** Namespace for retrieving the Image context. */
+    namespace?: string
+  }
+
+  export interface ImagePlaceholderSlotProps {
+    /** Current loading status. */
+    status: ImageStatus
+    /** Attributes to bind to the placeholder element. */
+    attrs: {
+      'aria-hidden': true
+      'data-state': ImageStatus
+    }
+  }
+</script>
+
+<script setup lang="ts">
+  // Components
+  import { Atom } from '#v0/components/Atom'
+
+  // Utilities
+  import { toRef } from 'vue'
+
+  defineOptions({ name: 'ImagePlaceholder' })
+
+  defineSlots<{
+    default: (props: ImagePlaceholderSlotProps) => any
+  }>()
+
+  const {
+    as = 'div',
+    renderless,
+    namespace = 'v0:image',
+  } = defineProps<ImagePlaceholderProps>()
+
+  const context = useImageRoot(namespace)
+
+  const isVisible = toRef(() => context.isIdle.value || context.isLoading.value)
+
+  const slotProps = toRef((): ImagePlaceholderSlotProps => ({
+    status: context.status.value,
+    attrs: {
+      'aria-hidden': true,
+      'data-state': context.status.value,
+    },
+  }))
+</script>
+
+<template>
+  <Atom
+    v-if="isVisible"
+    v-bind="slotProps.attrs"
+    :as
+    :renderless
+  >
+    <slot v-bind="slotProps" />
+  </Atom>
+</template>
diff --git a/packages/0/src/components/Image/ImageRoot.vue b/packages/0/src/components/Image/ImageRoot.vue
new file mode 100644
index 000000000..e9b1dddec
--- /dev/null
+++ b/packages/0/src/components/Image/ImageRoot.vue
@@ -0,0 +1,118 @@
+/**
+ * @module ImageRoot
+ *
+ * @see https://0.vuetifyjs.com/components/semantic/image
+ *
+ * @remarks
+ * Root component for the Image compound. Owns the image loading state machine
+ * via useImage and optionally drives lazy loading via useIntersectionObserver.
+ * Provides context to Image.Img, Image.Placeholder, and Image.Fallback.
+ */
+
+<script lang="ts">
+  // Components
+  import { Atom } from '#v0/components/Atom'
+
+  // Composables
+  import { createContext } from '#v0/composables/createContext'
+  import { useImage } from '#v0/composables/useImage'
+  import { useIntersectionObserver } from '#v0/composables/useIntersectionObserver'
+
+  // Utilities
+  import { shallowRef, toRef, useTemplateRef } from 'vue'
+
+  // Transformers
+  import { toElement } from '#v0/composables/toElement'
+
+  // Types
+  import type { AtomExpose, AtomProps } from '#v0/components/Atom'
+  import type { ImageStatus, UseImageReturn } from '#v0/composables/useImage'
+  import type { Ref } from 'vue'
+
+  export interface ImageRootProps extends AtomProps {
+    /** Image source URL. Forwarded to Image.Img via context. */
+    src?: string
+    /** Defer loading until the root element intersects the viewport. */
+    lazy?: boolean
+    /** IntersectionObserver root margin. Only used when lazy is true. */
+    rootMargin?: string
+    /** Namespace for dependency injection. */
+    namespace?: string
+  }
+
+  export interface ImageRootSlotProps {
+    /** Current loading status. */
+    status: ImageStatus
+    isIdle: boolean
+    isLoading: boolean
+    isLoaded: boolean
+    isError: boolean
+    /** Reset the image and re-attempt loading. */
+    retry: () => void
+    /** Attributes for the root element. */
+    attrs: {
+      'data-state': ImageStatus
+    }
+  }
+
+  export interface ImageContext extends UseImageReturn {
+    /** Resolved root element ref — used by IntersectionObserver. */
+    rootEl: Ref<HTMLElement | null>
+  }
+
+  export const [useImageRoot, provideImageRoot] = createContext<ImageContext>()
+</script>
+
+<script setup lang="ts">
+  defineOptions({ name: 'ImageRoot' })
+
+  defineSlots<{
+    default: (props: ImageRootSlotProps) => any
+  }>()
+
+  const {
+    as = 'div',
+    renderless,
+    src,
+    lazy = false,
+    rootMargin = '0px',
+    namespace = 'v0:image',
+  } = defineProps<ImageRootProps>()
+
+  const atomRef = useTemplateRef<AtomExpose>('atom')
+  const rootEl = toRef(() => toElement(atomRef.value?.element) as HTMLElement | null ?? null)
+
+  const { isIntersecting } = lazy
+    ? useIntersectionObserver(rootEl, () => {}, { once: true, rootMargin })
+    : { isIntersecting: shallowRef(true) }
+
+  const image = useImage({
+    src: toRef(() => src),
+    eager: isIntersecting,
+  })
+
+  provideImageRoot(namespace, { ...image, rootEl })
+
+  const slotProps = toRef((): ImageRootSlotProps => ({
+    status: image.status.value,
+    isIdle: image.isIdle.value,
+    isLoading: image.isLoading.value,
+    isLoaded: image.isLoaded.value,
+    isError: image.isError.value,
+    retry: image.retry,
+    attrs: {
+      'data-state': image.status.value,
+    },
+  }))
+</script>
+
+<template>
+  <Atom
+    ref="atom"
+    v-bind="slotProps.attrs"
+    :as
+    :renderless
+  >
+    <slot v-bind="slotProps" />
+  </Atom>
+</template>
diff --git a/packages/0/src/components/Image/index.test.ts b/packages/0/src/components/Image/index.test.ts
new file mode 100644
index 000000000..cde7a3e10
--- /dev/null
+++ b/packages/0/src/components/Image/index.test.ts
@@ -0,0 +1,422 @@
+import { describe, expect, it } from 'vitest'
+import { renderToString } from 'vue/server-renderer'
+
+// Utilities
+import { mount } from '@vue/test-utils'
+import { createSSRApp, defineComponent, h, nextTick } from 'vue'
+
+import { Image } from './index'
+
+describe('image', () => {
+  describe('root', () => {
+    describe('rendering', () => {
+      it('should render as div by default', () => {
+        const wrapper = mount(Image.Root, {
+          props: { src: '/photo.jpg' },
+          slots: {
+            default: () => h(Image.Img, { alt: 'Test' }),
+          },
+        })
+
+        expect(wrapper.element.tagName).toBe('DIV')
+      })
+
+      it('should render as custom element when as prop is provided', () => {
+        const wrapper = mount(Image.Root, {
+          props: { as: 'span', src: '/photo.jpg' },
+          slots: {
+            default: () => h(Image.Img, { alt: 'Test' }),
+          },
+        })
+
+        expect(wrapper.element.tagName).toBe('SPAN')
+      })
+
+      it('should support renderless mode', () => {
+        const wrapper = mount(Image.Root, {
+          props: { renderless: true, src: '/photo.jpg' },
+          slots: {
+            default: () => h('section', { class: 'custom-root' }, 'Content'),
+          },
+        })
+
+        expect(wrapper.find('.custom-root').exists()).toBe(true)
+      })
+
+      it('should expose data-state attribute', () => {
+        const wrapper = mount(Image.Root, {
+          props: { src: '/photo.jpg' },
+          slots: { default: () => h('span') },
+        })
+
+        expect(wrapper.attributes('data-state')).toBe('loading')
+      })
+    })
+
+    describe('slot props', () => {
+      it('should expose status and boolean flags when not lazy', () => {
+        let captured: any
+        mount(Image.Root, {
+          props: { src: '/photo.jpg' },
+          slots: {
+            default: (props: any) => {
+              captured = props
+              return h('span')
+            },
+          },
+        })
+
+        expect(captured.status).toBe('loading')
+        expect(captured.isLoading).toBe(true)
+        expect(captured.isIdle).toBe(false)
+        expect(captured.isLoaded).toBe(false)
+        expect(captured.isError).toBe(false)
+      })
+
+      it('should expose retry function', () => {
+        let captured: any
+        mount(Image.Root, {
+          props: { src: '/photo.jpg' },
+          slots: {
+            default: (props: any) => {
+              captured = props
+              return h('span')
+            },
+          },
+        })
+
+        expect(typeof captured.retry).toBe('function')
+      })
+    })
+
+    describe('lazy loading', () => {
+      it('should start in idle when lazy', () => {
+        let captured: any
+        mount(Image.Root, {
+          props: { src: '/photo.jpg', lazy: true },
+          slots: {
+            default: (props: any) => {
+              captured = props
+              return h('span')
+            },
+          },
+        })
+
+        // happy-dom does not implement IntersectionObserver naturally,
+        // so isIntersecting begins false and status begins idle.
+        expect(captured.status).toBe('idle')
+        expect(captured.isIdle).toBe(true)
+      })
+
+      it('should start in loading when not lazy', () => {
+        let captured: any
+        mount(Image.Root, {
+          props: { src: '/photo.jpg' },
+          slots: {
+            default: (props: any) => {
+              captured = props
+              return h('span')
+            },
+          },
+        })
+
+        expect(captured.status).toBe('loading')
+      })
+    })
+  })
+
+  describe('img', () => {
+    describe('rendering', () => {
+      it('should render as img by default', () => {
+        const wrapper = mount(Image.Root, {
+          props: { src: '/photo.jpg' },
+          slots: {
+            default: () => h(Image.Img, { alt: 'Test' }),
+          },
+        })
+
+        const img = wrapper.findComponent(Image.Img as any)
+        expect(img.element.tagName).toBe('IMG')
+      })
+
+      it('should bind src from context', () => {
+        const wrapper = mount(Image.Root, {
+          props: { src: '/photo.jpg' },
+          slots: {
+            default: () => h(Image.Img, { alt: 'Test' }),
+          },
+        })
+
+        const img = wrapper.find('img')
+        expect(img.attributes('src')).toBe('/photo.jpg')
+      })
+
+      it('should not bind src when context is idle', () => {
+        const wrapper = mount(Image.Root, {
+          props: { src: '/photo.jpg', lazy: true },
+          slots: {
+            default: () => h(Image.Img, { alt: 'Test' }),
+          },
+        })
+
+        const img = wrapper.find('img')
+        expect(img.attributes('src')).toBeUndefined()
+      })
+
+      it('should pass alt, width, and height through', () => {
+        const wrapper = mount(Image.Root, {
+          props: { src: '/photo.jpg' },
+          slots: {
+            default: () => h(Image.Img, { alt: 'Photo', width: 800, height: 600 }),
+          },
+        })
+
+        const img = wrapper.find('img')
+        expect(img.attributes('alt')).toBe('Photo')
+        expect(img.attributes('width')).toBe('800')
+        expect(img.attributes('height')).toBe('600')
+      })
+
+      it('should default decoding to async', () => {
+        const wrapper = mount(Image.Root, {
+          props: { src: '/photo.jpg' },
+          slots: {
+            default: () => h(Image.Img, { alt: 'Test' }),
+          },
+        })
+
+        const img = wrapper.find('img')
+        expect(img.attributes('decoding')).toBe('async')
+      })
+
+      it('should expose role=img', () => {
+        const wrapper = mount(Image.Root, {
+          props: { src: '/photo.jpg' },
+          slots: {
+            default: () => h(Image.Img, { alt: 'Test' }),
+          },
+        })
+
+        const img = wrapper.find('img')
+        expect(img.attributes('role')).toBe('img')
+      })
+    })
+
+    describe('events', () => {
+      it('should transition root to loaded on load event', async () => {
+        let captured: any
+        const wrapper = mount(Image.Root, {
+          props: { src: '/photo.jpg' },
+          slots: {
+            default: (props: any) => {
+              captured = props
+              return h(Image.Img, { alt: 'Test' })
+            },
+          },
+        })
+
+        const img = wrapper.find('img')
+        await img.trigger('load')
+
+        expect(captured.status).toBe('loaded')
+      })
+
+      it('should transition root to error on error event', async () => {
+        let captured: any
+        const wrapper = mount(Image.Root, {
+          props: { src: '/photo.jpg' },
+          slots: {
+            default: (props: any) => {
+              captured = props
+              return h(Image.Img, { alt: 'Test' })
+            },
+          },
+        })
+
+        const img = wrapper.find('img')
+        await img.trigger('error')
+
+        expect(captured.status).toBe('error')
+      })
+    })
+  })
+
+  describe('placeholder', () => {
+    it('should render while loading', () => {
+      const wrapper = mount(Image.Root, {
+        props: { src: '/photo.jpg' },
+        slots: {
+          default: () => [
+            h(Image.Img, { alt: 'Test' }),
+            h(Image.Placeholder, {}, () => 'Loading'),
+          ],
+        },
+      })
+
+      expect(wrapper.text()).toContain('Loading')
+    })
+
+    it('should hide once loaded', async () => {
+      const wrapper = mount(Image.Root, {
+        props: { src: '/photo.jpg' },
+        slots: {
+          default: () => [
+            h(Image.Img, { alt: 'Test' }),
+            h(Image.Placeholder, {}, () => 'Loading'),
+          ],
+        },
+      })
+
+      const img = wrapper.find('img')
+      await img.trigger('load')
+      await nextTick()
+
+      expect(wrapper.text()).not.toContain('Loading')
+    })
+
+    it('should hide on error', async () => {
+      const wrapper = mount(Image.Root, {
+        props: { src: '/photo.jpg' },
+        slots: {
+          default: () => [
+            h(Image.Img, { alt: 'Test' }),
+            h(Image.Placeholder, {}, () => 'Loading'),
+          ],
+        },
+      })
+
+      const img = wrapper.find('img')
+      await img.trigger('error')
+      await nextTick()
+
+      expect(wrapper.text()).not.toContain('Loading')
+    })
+
+    it('should have aria-hidden=true', () => {
+      const wrapper = mount(Image.Root, {
+        props: { src: '/photo.jpg' },
+        slots: {
+          default: () => [
+            h(Image.Img, { alt: 'Test' }),
+            h(Image.Placeholder, { class: 'placeholder' }, () => 'Loading'),
+          ],
+        },
+      })
+
+      expect(wrapper.find('.placeholder').attributes('aria-hidden')).toBe('true')
+    })
+  })
+
+  describe('fallback', () => {
+    it('should not render when not in error state', () => {
+      const wrapper = mount(Image.Root, {
+        props: { src: '/photo.jpg' },
+        slots: {
+          default: () => [
+            h(Image.Img, { alt: 'Test' }),
+            h(Image.Fallback, {}, () => 'Failed'),
+          ],
+        },
+      })
+
+      expect(wrapper.text()).not.toContain('Failed')
+    })
+
+    it('should render when image errors', async () => {
+      const wrapper = mount(Image.Root, {
+        props: { src: '/photo.jpg' },
+        slots: {
+          default: () => [
+            h(Image.Img, { alt: 'Test' }),
+            h(Image.Fallback, {}, () => 'Failed'),
+          ],
+        },
+      })
+
+      const img = wrapper.find('img')
+      await img.trigger('error')
+      await nextTick()
+
+      expect(wrapper.text()).toContain('Failed')
+    })
+
+    it('should expose retry in slot props', async () => {
+      let captured: any
+      const wrapper = mount(Image.Root, {
+        props: { src: '/photo.jpg' },
+        slots: {
+          default: () => [
+            h(Image.Img, { alt: 'Test' }),
+            h(Image.Fallback as any, {}, (props: any) => {
+              captured = props
+              return 'Failed'
+            }),
+          ],
+        },
+      })
+
+      const img = wrapper.find('img')
+      await img.trigger('error')
+      await nextTick()
+
+      expect(typeof captured.retry).toBe('function')
+    })
+
+    it('should reset to loading when retry is called', async () => {
+      let rootProps: any
+      let fallbackProps: any
+      const wrapper = mount(Image.Root, {
+        props: { src: '/photo.jpg' },
+        slots: {
+          default: (root: any) => {
+            rootProps = root
+            return [
+              h(Image.Img, { alt: 'Test' }),
+              h(Image.Fallback as any, {}, (props: any) => {
+                fallbackProps = props
+                return 'Failed'
+              }),
+            ]
+          },
+        },
+      })
+
+      const img = wrapper.find('img')
+      await img.trigger('error')
+      await nextTick()
+
+      fallbackProps.retry()
+      await nextTick()
+
+      expect(rootProps.status).toBe('loading')
+    })
+  })
+
+  describe('namespacing', () => {
+    it('should support custom namespace', () => {
+      const wrapper = mount(Image.Root, {
+        props: { src: '/photo.jpg', namespace: 'custom:image' },
+        slots: {
+          default: () => h(Image.Img, { alt: 'Test', namespace: 'custom:image' }),
+        },
+      })
+
+      expect(wrapper.find('img').exists()).toBe(true)
+    })
+  })
+
+  describe('sSR', () => {
+    it('should render to string without errors', async () => {
+      const app = createSSRApp(defineComponent({
+        render: () => h(Image.Root, { src: '/photo.jpg' }, () => [
+          h(Image.Img, { alt: 'Test' }),
+          h(Image.Placeholder, {}, () => 'Loading'),
+        ]),
+      }))
+
+      const html = await renderToString(app)
+      expect(html).toBeTruthy()
+      expect(html).toContain('img')
+    })
+  })
+})
diff --git a/packages/0/src/components/Image/index.ts b/packages/0/src/components/Image/index.ts
new file mode 100644
index 000000000..96459a827
--- /dev/null
+++ b/packages/0/src/components/Image/index.ts
@@ -0,0 +1,86 @@
+export { default as ImageFallback } from './ImageFallback.vue'
+export { default as ImageImg } from './ImageImg.vue'
+export { default as ImagePlaceholder } from './ImagePlaceholder.vue'
+export { provideImageRoot, useImageRoot } from './ImageRoot.vue'
+
+export { default as ImageRoot } from './ImageRoot.vue'
+
+export type { ImageFallbackProps, ImageFallbackSlotProps } from './ImageFallback.vue'
+export type { ImageImgEmits, ImageImgProps, ImageImgSlotProps } from './ImageImg.vue'
+export type { ImagePlaceholderProps, ImagePlaceholderSlotProps } from './ImagePlaceholder.vue'
+export type { ImageContext, ImageRootProps, ImageRootSlotProps } from './ImageRoot.vue'
+
+// Components
+import Fallback from './ImageFallback.vue'
+import Img from './ImageImg.vue'
+import Placeholder from './ImagePlaceholder.vue'
+import Root from './ImageRoot.vue'
+
+/**
+ * Image component with sub-components for managing image loading lifecycle.
+ *
+ * @see https://0.vuetifyjs.com/components/semantic/image
+ */
+export const Image = {
+  /**
+   * Root component for images. Owns the loading state machine and optionally
+   * manages lazy loading via IntersectionObserver.
+   *
+   * @see https://0.vuetifyjs.com/components/semantic/image
+   *
+   * @example
+   * ```vue
+   * <script lang="ts" setup>
+   *   import { Image } from '@vuetify/v0'
+   * </script>
+   *
+   * <template>
+   *   <Image.Root src="/photo.jpg">
+   *     <Image.Img alt="A photo" width="800" height="600" />
+   *     <Image.Placeholder>Loading...</Image.Placeholder>
+   *     <Image.Fallback>Failed to load</Image.Fallback>
+   *   </Image.Root>
+   * </template>
+   * ```
+   */
+  Root,
+  /**
+   * The `<img>` element. Reads the gated source from context and reports
+   * load/error events.
+   *
+   * @see https://0.vuetifyjs.com/components/semantic/image
+   *
+   * @example
+   * ```vue
+   * <Image.Img alt="Description" width="800" height="600" />
+   * ```
+   */
+  Img,
+  /**
+   * Placeholder content shown while the image is idle or loading.
+   *
+   * @see https://0.vuetifyjs.com/components/semantic/image
+   *
+   * @example
+   * ```vue
+   * <Image.Placeholder>
+   *   <div class="bg-gray-200 animate-pulse" />
+   * </Image.Placeholder>
+   * ```
+   */
+  Placeholder,
+  /**
+   * Fallback content shown when the image fails to load. Exposes `retry()`
+   * via slot props.
+   *
+   * @see https://0.vuetifyjs.com/components/semantic/image
+   *
+   * @example
+   * ```vue
+   * <Image.Fallback v-slot="{ retry }">
+   *   <button @click="retry">Retry</button>
+   * </Image.Fallback>
+   * ```
+   */
+  Fallback,
+}
diff --git a/packages/0/src/components/index.ts b/packages/0/src/components/index.ts
index 133761c49..26b7ae62e 100644
--- a/packages/0/src/components/index.ts
+++ b/packages/0/src/components/index.ts
@@ -11,6 +11,7 @@ export * from './Dialog'
 export * from './ExpansionPanel'
 export * from './Form'
 export * from './Group'
+export * from './Image'
 export * from './Input'
 export * from './Locale'
 export * from './NumberField'
diff --git a/packages/0/src/composables/index.ts b/packages/0/src/composables/index.ts
index a89dbadd6..7cb160be0 100644
--- a/packages/0/src/composables/index.ts
+++ b/packages/0/src/composables/index.ts
@@ -37,6 +37,7 @@ export * from './useEventListener'
 export * from './useFeatures'
 export * from './useHotkey'
 export * from './useHydration'
+export * from './useImage'
 export * from './useIntersectionObserver'
 export * from './useLazy'
 export * from './useLocale'
diff --git a/packages/0/src/composables/useImage/index.test.ts b/packages/0/src/composables/useImage/index.test.ts
new file mode 100644
index 000000000..50c48a6f0
--- /dev/null
+++ b/packages/0/src/composables/useImage/index.test.ts
@@ -0,0 +1,214 @@
+import { describe, expect, it } from 'vitest'
+
+// Utilities
+import { effectScope, nextTick, shallowRef } from 'vue'
+
+import { useImage } from './index'
+
+describe('useImage', () => {
+  describe('initial state', () => {
+    it('should start in loading when eager defaults to true', () => {
+      const image = useImage({ src: '/photo.jpg' })
+
+      expect(image.status.value).toBe('loading')
+      expect(image.isLoading.value).toBe(true)
+      expect(image.source.value).toBe('/photo.jpg')
+    })
+
+    it('should start in idle when eager is false', () => {
+      const image = useImage({ src: '/photo.jpg', eager: false })
+
+      expect(image.status.value).toBe('idle')
+      expect(image.isIdle.value).toBe(true)
+      expect(image.source.value).toBeUndefined()
+    })
+
+    it('should withhold source while idle', () => {
+      const image = useImage({ src: '/photo.jpg', eager: false })
+
+      expect(image.source.value).toBeUndefined()
+    })
+
+    it('should expose source when not idle', () => {
+      const image = useImage({ src: '/photo.jpg' })
+
+      expect(image.source.value).toBe('/photo.jpg')
+    })
+  })
+
+  describe('load handling', () => {
+    it('should transition to loaded on onLoad', () => {
+      const image = useImage({ src: '/photo.jpg' })
+
+      image.onLoad()
+
+      expect(image.status.value).toBe('loaded')
+      expect(image.isLoaded.value).toBe(true)
+      expect(image.isLoading.value).toBe(false)
+    })
+
+    it('should expose source after loaded', () => {
+      const image = useImage({ src: '/photo.jpg' })
+
+      image.onLoad()
+
+      expect(image.source.value).toBe('/photo.jpg')
+    })
+  })
+
+  describe('error handling', () => {
+    it('should transition to error on onError', () => {
+      const image = useImage({ src: '/photo.jpg' })
+
+      image.onError()
+
+      expect(image.status.value).toBe('error')
+      expect(image.isError.value).toBe(true)
+      expect(image.isLoading.value).toBe(false)
+    })
+
+    it('should reset to loading on retry when eager is true', () => {
+      const image = useImage({ src: '/photo.jpg' })
+
+      image.onError()
+      image.retry()
+
+      expect(image.status.value).toBe('loading')
+      expect(image.isError.value).toBe(false)
+    })
+
+    it('should reset to idle on retry when eager is false', () => {
+      const image = useImage({ src: '/photo.jpg', eager: false })
+
+      image.onError()
+      image.retry()
+
+      expect(image.status.value).toBe('idle')
+    })
+  })
+
+  describe('eager reactivity', () => {
+    it('should transition from idle to loading when eager becomes true', async () => {
+      const eager = shallowRef(false)
+      const image = useImage({ src: '/photo.jpg', eager })
+
+      expect(image.status.value).toBe('idle')
+
+      eager.value = true
+      await nextTick()
+
+      expect(image.status.value).toBe('loading')
+      expect(image.source.value).toBe('/photo.jpg')
+    })
+
+    it('should not unload a loaded image when eager flips false', async () => {
+      const eager = shallowRef(true)
+      const image = useImage({ src: '/photo.jpg', eager })
+
+      image.onLoad()
+      eager.value = false
+      await nextTick()
+
+      expect(image.status.value).toBe('loaded')
+    })
+
+    it('should not regress an error state when eager flips false', async () => {
+      const eager = shallowRef(true)
+      const image = useImage({ src: '/photo.jpg', eager })
+
+      image.onError()
+      eager.value = false
+      await nextTick()
+
+      expect(image.status.value).toBe('error')
+    })
+
+    it('should regress loading to idle when eager flips false', async () => {
+      const eager = shallowRef(true)
+      const image = useImage({ src: '/photo.jpg', eager })
+
+      eager.value = false
+      await nextTick()
+
+      expect(image.status.value).toBe('idle')
+    })
+  })
+
+  describe('src reactivity', () => {
+    it('should reset to loading when src changes after loaded', async () => {
+      const src = shallowRef<string | undefined>('/a.jpg')
+      const image = useImage({ src })
+
+      image.onLoad()
+      expect(image.status.value).toBe('loaded')
+
+      src.value = '/b.jpg'
+      await nextTick()
+
+      expect(image.status.value).toBe('loading')
+      expect(image.source.value).toBe('/b.jpg')
+    })
+
+    it('should reset to loading when src changes after error', async () => {
+      const src = shallowRef<string | undefined>('/a.jpg')
+      const image = useImage({ src })
+
+      image.onError()
+      src.value = '/b.jpg'
+      await nextTick()
+
+      expect(image.status.value).toBe('loading')
+    })
+
+    it('should reset to idle when src changes and eager is false', async () => {
+      const src = shallowRef<string | undefined>('/a.jpg')
+      const image = useImage({ src, eager: false })
+
+      src.value = '/b.jpg'
+      await nextTick()
+
+      expect(image.status.value).toBe('idle')
+    })
+  })
+
+  describe('source gating', () => {
+    it('should reflect undefined src', () => {
+      const image = useImage({ src: undefined, eager: true })
+
+      expect(image.source.value).toBeUndefined()
+    })
+
+    it('should toggle source as eager toggles', async () => {
+      const eager = shallowRef(false)
+      const image = useImage({ src: '/photo.jpg', eager })
+
+      expect(image.source.value).toBeUndefined()
+
+      eager.value = true
+      await nextTick()
+
+      expect(image.source.value).toBe('/photo.jpg')
+    })
+  })
+
+  describe('cleanup', () => {
+    it('should stop reacting to src after scope dispose', async () => {
+      const src = shallowRef<string | undefined>('/a.jpg')
+      const scope = effectScope()
+
+      let image: ReturnType<typeof useImage>
+      scope.run(() => {
+        image = useImage({ src })
+      })
+
+      image!.onLoad()
+      scope.stop()
+
+      src.value = '/b.jpg'
+      await nextTick()
+
+      // status was 'loaded' before disposal; should not change after
+      expect(image!.status.value).toBe('loaded')
+    })
+  })
+})
diff --git a/packages/0/src/composables/useImage/index.ts b/packages/0/src/composables/useImage/index.ts
new file mode 100644
index 000000000..95ca2baf7
--- /dev/null
+++ b/packages/0/src/composables/useImage/index.ts
@@ -0,0 +1,172 @@
+/**
+ * @module useImage
+ *
+ * @see https://0.vuetifyjs.com/composables/system/use-image
+ *
+ * @remarks
+ * Image loading state machine with deferred loading support.
+ *
+ * Key features:
+ * - State machine: idle → loading → loaded | error
+ * - Reactive `eager` gate withholds the source until ready
+ * - Automatic reset when `src` changes
+ * - Manual `retry()` to re-attempt after error
+ * - Bind-ready handlers and gated source
+ * - SSR-safe
+ *
+ * Perfect for image components, lightboxes, lazy-loaded galleries,
+ * and any UI that needs to react to image load state.
+ */
+
+// Utilities
+import { onScopeDispose, shallowReadonly, shallowRef, toRef, toValue, watch } from 'vue'
+
+// Types
+import type { MaybeRefOrGetter, Ref, ShallowRef } from 'vue'
+
+export type ImageStatus = 'idle' | 'loading' | 'loaded' | 'error'
+
+export interface UseImageOptions {
+  /**
+   * Image source URL. Changes trigger a reload.
+   */
+  src: MaybeRefOrGetter<string | undefined>
+  /**
+   * Whether the image should load. When `false`, status stays `idle` and
+   * `source` resolves to `undefined` so the browser does not start loading.
+   * @default true
+   */
+  eager?: MaybeRefOrGetter<boolean>
+}
+
+export interface UseImageReturn {
+  /**
+   * Current loading state.
+   */
+  readonly status: Readonly<ShallowRef<ImageStatus>>
+  /**
+   * Whether the image has not yet started loading (eager is false).
+   */
+  readonly isIdle: Readonly<Ref<boolean>>
+  /**
+   * Whether the image is currently loading.
+   */
+  readonly isLoading: Readonly<Ref<boolean>>
+  /**
+   * Whether the image has loaded successfully.
+   */
+  readonly isLoaded: Readonly<Ref<boolean>>
+  /**
+   * Whether the image failed to load.
+   */
+  readonly isError: Readonly<Ref<boolean>>
+  /**
+   * Gated source URL. Resolves to `undefined` while idle, otherwise the
+   * current `src` value. Bind directly to the `<img>` `src` attribute.
+   */
+  readonly source: Readonly<Ref<string | undefined>>
+  /**
+   * Bind to the `<img>` `load` event.
+   */
+  onLoad: (e?: Event) => void
+  /**
+   * Bind to the `<img>` `error` event.
+   */
+  onError: (e?: Event) => void
+  /**
+   * Reset status back to `loading` so the browser re-attempts the source.
+   */
+  retry: () => void
+}
+
+/**
+ * Tracks image loading state as a reactive state machine.
+ *
+ * @param options Configuration options
+ * @returns Image context with state refs and event handlers
+ *
+ * @see https://0.vuetifyjs.com/composables/system/use-image
+ *
+ * @example
+ * ```ts
+ * import { toRef } from 'vue'
+ * import { useImage } from '@vuetify/v0'
+ *
+ * const props = defineProps<{ src: string }>()
+ *
+ * const { source, isLoaded, onLoad, onError, retry } = useImage({
+ *   src: toRef(() => props.src),
+ * })
+ * ```
+ *
+ * @example
+ * Composed with `useIntersectionObserver` for lazy loading:
+ * ```ts
+ * const target = shallowRef<HTMLElement>()
+ * const { isIntersecting } = useIntersectionObserver(target, () => {}, {
+ *   once: true,
+ *   rootMargin: '200px',
+ * })
+ *
+ * const { source, onLoad, onError } = useImage({
+ *   src: toRef(() => props.src),
+ *   eager: isIntersecting,
+ * })
+ * ```
+ */
+export function useImage (options: UseImageOptions): UseImageReturn {
+  const { src, eager = true } = options
+
+  const status = shallowRef<ImageStatus>(toValue(eager) ? 'loading' : 'idle')
+
+  const isIdle = toRef(() => status.value === 'idle')
+  const isLoading = toRef(() => status.value === 'loading')
+  const isLoaded = toRef(() => status.value === 'loaded')
+  const isError = toRef(() => status.value === 'error')
+
+  const source = toRef(() => status.value === 'idle' ? undefined : toValue(src))
+
+  function onLoad () {
+    status.value = 'loaded'
+  }
+
+  function onError () {
+    status.value = 'error'
+  }
+
+  function retry () {
+    status.value = toValue(eager) ? 'loading' : 'idle'
+  }
+
+  const stopEager = watch(
+    () => toValue(eager),
+    value => {
+      if (value && status.value === 'idle') status.value = 'loading'
+      else if (!value && status.value !== 'loaded' && status.value !== 'error') status.value = 'idle'
+    },
+  )
+
+  const stopSrc = watch(
+    () => toValue(src),
+    () => {
+      status.value = toValue(eager) ? 'loading' : 'idle'
+    },
+  )
+
+  onScopeDispose(() => {
+    stopEager()
+    stopSrc()
+  }, true)
+
+  return {
+    status: shallowReadonly(status),
+    isIdle: shallowReadonly(isIdle),
+    isLoading: shallowReadonly(isLoading),
+    isLoaded: shallowReadonly(isLoaded),
+    isError: shallowReadonly(isError),
+    source: shallowReadonly(source),
+    onLoad,
+    onError,
+    retry,
+  }
+}
diff --git a/packages/0/src/maturity.json b/packages/0/src/maturity.json
index e29a8bbc1..d5097e1ca 100644
--- a/packages/0/src/maturity.json
+++ b/packages/0/src/maturity.json
@@ -201,6 +201,10 @@
       "since": "0.1.0",
       "category": "system"
     },
+    "useImage": {
+      "level": "preview",
+      "category": "system"
+    },
     "useIntersectionObserver": {
       "level": "stable",
       "since": "0.1.0",
@@ -500,7 +504,7 @@
       "category": "semantic"
     },
     "Image": {
-      "level": "draft",
+      "level": "preview",
       "category": "semantic"
     },
     "Overflow": {

From 160bda78b48221464693c9140d2f534181a62201 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 16 Apr 2026 17:18:17 +0000
Subject: [PATCH 02/35] refactor(Image): split examples into multi-file
 learning events
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Restructures Image and useImage docs examples to be multi-file per
docs.md rules — each non-usage example now demonstrates a concrete
composition pattern with a reusable component or composable:

- `useImage/lazy` — composes useImage + useIntersectionObserver into a
  `useLazyImage` hook plus a `LazyImage` component
- `useImage/retry` — wraps useImage in a `RetryableImage` component
- `Image/observer` — builds a `BlurUpImage` LQIP component
- `Image/picture` — wraps Image primitives in a `PictureImage` component
  with format negotiation

Prefers styling via `data-state` attributes over slot props: the
blur-up example now drives opacity transitions with
`data-[state=loaded]:` instead of threading `isLoaded` through slot
props. Adds a Styling section and updates the fade-in FAQ to
recommend data-attribute selectors.

Moves all remaining imports out of `<script setup>` blocks into the
regular `<script lang="ts">` per components.md rules (Image*.vue and
AvatarImage.vue).

https://claude.ai/code/session_01NMjcSYYdX2yniURgEfGrh4
---
 .../examples/components/image/BlurUpImage.vue | 34 +++++++++++
 .../components/image/PictureImage.vue         | 47 +++++++++++++++
 .../examples/components/image/observer.vue    | 56 ++++++++++--------
 .../src/examples/components/image/picture.vue | 33 +++--------
 .../composables/use-image/LazyImage.vue       | 34 +++++++++++
 .../composables/use-image/RetryableImage.vue  | 51 ++++++++++++++++
 .../examples/composables/use-image/lazy.vue   | 54 ++++++-----------
 .../examples/composables/use-image/retry.vue  | 44 ++++----------
 .../composables/use-image/useLazyImage.ts     | 25 ++++++++
 .../src/pages/components/semantic/image.md    | 58 +++++++++++++++----
 .../src/pages/composables/system/use-image.md | 35 ++++++-----
 .../0/src/components/Avatar/AvatarImage.vue   | 16 ++---
 .../0/src/components/Image/ImageFallback.vue  | 12 ++--
 packages/0/src/components/Image/ImageImg.vue  | 12 ++--
 .../src/components/Image/ImagePlaceholder.vue | 12 ++--
 15 files changed, 354 insertions(+), 169 deletions(-)
 create mode 100644 apps/docs/src/examples/components/image/BlurUpImage.vue
 create mode 100644 apps/docs/src/examples/components/image/PictureImage.vue
 create mode 100644 apps/docs/src/examples/composables/use-image/LazyImage.vue
 create mode 100644 apps/docs/src/examples/composables/use-image/RetryableImage.vue
 create mode 100644 apps/docs/src/examples/composables/use-image/useLazyImage.ts

diff --git a/apps/docs/src/examples/components/image/BlurUpImage.vue b/apps/docs/src/examples/components/image/BlurUpImage.vue
new file mode 100644
index 000000000..348277531
--- /dev/null
+++ b/apps/docs/src/examples/components/image/BlurUpImage.vue
@@ -0,0 +1,34 @@
+<script setup lang="ts">
+  import { Image } from '@vuetify/v0'
+
+  defineProps<{
+    src: string
+    placeholder: string
+    alt: string
+  }>()
+</script>
+
+<template>
+  <Image.Root
+    class="w-full aspect-4/3 bg-surface-tint rounded overflow-hidden relative"
+    lazy
+    root-margin="200px"
+    :src
+  >
+    <Image.Img
+      :alt
+      class="w-full h-full object-cover opacity-0 transition-opacity duration-500 data-[state=loaded]:opacity-100"
+      height="300"
+      width="400"
+    />
+
+    <Image.Placeholder class="absolute inset-0">
+      <img
+        :alt
+        aria-hidden="true"
+        class="w-full h-full object-cover scale-105 blur-xl"
+        :src="placeholder"
+      >
+    </Image.Placeholder>
+  </Image.Root>
+</template>
diff --git a/apps/docs/src/examples/components/image/PictureImage.vue b/apps/docs/src/examples/components/image/PictureImage.vue
new file mode 100644
index 000000000..896259d41
--- /dev/null
+++ b/apps/docs/src/examples/components/image/PictureImage.vue
@@ -0,0 +1,47 @@
+/* eslint-disable vuejs-accessibility/alt-text */
+<script setup lang="ts">
+  import { Image } from '@vuetify/v0'
+
+  defineProps<{
+    src: string
+    sources: { srcset: string, type: string }[]
+    alt: string
+    width: number
+    height: number
+  }>()
+</script>
+
+<template>
+  <Image.Root
+    renderless
+    :src
+  >
+    <picture class="block w-full aspect-4/3 bg-surface-tint rounded overflow-hidden relative">
+      <source
+        v-for="source in sources"
+        :key="source.type"
+        :srcset="source.srcset"
+        :type="source.type"
+      >
+
+      <Image.Img
+        :alt
+        :height
+        renderless
+        :width
+      >
+        <template #default="{ attrs }">
+          <img v-bind="attrs" class="w-full h-full object-cover">
+        </template>
+      </Image.Img>
+
+      <Image.Placeholder class="absolute inset-0 flex items-center justify-center bg-surface-tint">
+        <span class="text-on-surface-variant text-sm">Loading...</span>
+      </Image.Placeholder>
+
+      <Image.Fallback class="absolute inset-0 flex items-center justify-center bg-error-container text-on-error-container text-sm">
+        Image failed to load
+      </Image.Fallback>
+    </picture>
+  </Image.Root>
+</template>
diff --git a/apps/docs/src/examples/components/image/observer.vue b/apps/docs/src/examples/components/image/observer.vue
index fad8b8eaf..32f07b7ce 100644
--- a/apps/docs/src/examples/components/image/observer.vue
+++ b/apps/docs/src/examples/components/image/observer.vue
@@ -1,35 +1,43 @@
 <script setup lang="ts">
-  import { Image } from '@vuetify/v0'
+  import BlurUpImage from './BlurUpImage.vue'
+
+  const photos = [
+    {
+      id: 1,
+      src: 'https://picsum.photos/seed/blur-1/400/300',
+      placeholder: 'https://picsum.photos/seed/blur-1/20/15',
+      alt: 'Photo 1',
+    },
+    {
+      id: 2,
+      src: 'https://picsum.photos/seed/blur-2/400/300',
+      placeholder: 'https://picsum.photos/seed/blur-2/20/15',
+      alt: 'Photo 2',
+    },
+    {
+      id: 3,
+      src: 'https://picsum.photos/seed/blur-3/400/300',
+      placeholder: 'https://picsum.photos/seed/blur-3/20/15',
+      alt: 'Photo 3',
+    },
+  ]
 </script>
 
 <template>
   <div class="h-100 overflow-auto border border-divider rounded p-4">
     <p class="text-sm text-on-surface-variant mb-4">
-      Scroll to bring the image into view — it will only start loading then.
+      A low-quality placeholder shows first; the full image fades in once it
+      loads. Scroll to trigger the next image.
     </p>
 
-    <div class="h-100 flex items-center justify-center text-on-surface-variant">
-      Scroll down ↓
-    </div>
-
-    <Image.Root
-      class="w-100 h-75 bg-surface-tint rounded overflow-hidden relative mx-auto"
-      lazy
-      root-margin="100px"
-      src="https://picsum.photos/seed/observer/400/300"
-    >
-      <Image.Img
-        alt="Observer-driven photo"
-        class="w-full h-full object-cover transition-opacity duration-500"
-        height="300"
-        width="400"
+    <div class="flex flex-col gap-100">
+      <BlurUpImage
+        v-for="photo in photos"
+        :key="photo.id"
+        :alt="photo.alt"
+        :placeholder="photo.placeholder"
+        :src="photo.src"
       />
-
-      <Image.Placeholder class="absolute inset-0 flex items-center justify-center text-on-surface-variant text-sm">
-        Waiting to enter viewport...
-      </Image.Placeholder>
-    </Image.Root>
-
-    <div class="h-100" />
+    </div>
   </div>
 </template>
diff --git a/apps/docs/src/examples/components/image/picture.vue b/apps/docs/src/examples/components/image/picture.vue
index 2bde1be92..af346a734 100644
--- a/apps/docs/src/examples/components/image/picture.vue
+++ b/apps/docs/src/examples/components/image/picture.vue
@@ -1,30 +1,15 @@
-/* eslint-disable vuejs-accessibility/alt-text */
 <script setup lang="ts">
-  import { Image } from '@vuetify/v0'
+  import PictureImage from './PictureImage.vue'
 </script>
 
 <template>
-  <Image.Root
-    renderless
+  <PictureImage
+    alt="Format-negotiated photo"
+    :height="300"
+    :sources="[
+      { srcset: 'https://picsum.photos/seed/picture/400/300.webp', type: 'image/webp' },
+    ]"
     src="https://picsum.photos/seed/picture/400/300"
-  >
-    <picture class="block w-100 h-75 bg-surface-tint rounded overflow-hidden relative">
-      <source srcset="https://picsum.photos/seed/picture/400/300.webp" type="image/webp">
-
-      <Image.Img
-        alt="Format-negotiated photo"
-        height="300"
-        renderless
-        width="400"
-      >
-        <template #default="{ attrs }">
-          <img v-bind="attrs" class="w-full h-full object-cover">
-        </template>
-      </Image.Img>
-
-      <Image.Placeholder class="absolute inset-0 flex items-center justify-center bg-surface-tint">
-        <span class="text-on-surface-variant text-sm">Loading...</span>
-      </Image.Placeholder>
-    </picture>
-  </Image.Root>
+    :width="400"
+  />
 </template>
diff --git a/apps/docs/src/examples/composables/use-image/LazyImage.vue b/apps/docs/src/examples/composables/use-image/LazyImage.vue
new file mode 100644
index 000000000..43458be3f
--- /dev/null
+++ b/apps/docs/src/examples/composables/use-image/LazyImage.vue
@@ -0,0 +1,34 @@
+/* eslint-disable vuejs-accessibility/alt-text */
+<script setup lang="ts">
+  import { toRef } from 'vue'
+  import { useLazyImage } from './useLazyImage'
+
+  const props = defineProps<{
+    src: string
+    alt: string
+  }>()
+
+  const { target, source, isLoaded, status, onLoad, onError } = useLazyImage(
+    toRef(() => props.src),
+  )
+</script>
+
+<template>
+  <div ref="target" class="w-full aspect-4/3 bg-surface-tint rounded overflow-hidden relative">
+    <img
+      v-show="isLoaded"
+      :alt
+      class="w-full h-full object-cover"
+      :src="source"
+      @error="onError"
+      @load="onLoad"
+    >
+
+    <span
+      v-if="!isLoaded"
+      class="absolute inset-0 flex items-center justify-center text-on-surface-variant text-sm"
+    >
+      {{ status }}
+    </span>
+  </div>
+</template>
diff --git a/apps/docs/src/examples/composables/use-image/RetryableImage.vue b/apps/docs/src/examples/composables/use-image/RetryableImage.vue
new file mode 100644
index 000000000..9308af91b
--- /dev/null
+++ b/apps/docs/src/examples/composables/use-image/RetryableImage.vue
@@ -0,0 +1,51 @@
+/* eslint-disable vuejs-accessibility/alt-text */
+<script setup lang="ts">
+  import { useImage } from '@vuetify/v0'
+  import { shallowRef, toRef } from 'vue'
+
+  const props = defineProps<{
+    src: string
+    alt: string
+  }>()
+
+  const attempts = shallowRef(0)
+
+  const { source, isLoaded, isError, onLoad, onError, retry } = useImage({
+    src: toRef(() => props.src),
+  })
+
+  function handleRetry () {
+    attempts.value++
+    retry()
+  }
+</script>
+
+<template>
+  <div class="w-full aspect-4/3 bg-surface-tint rounded overflow-hidden relative flex flex-col items-center justify-center gap-2">
+    <img
+      v-show="isLoaded"
+      :alt
+      class="w-full h-full object-cover"
+      :src="source"
+      @error="onError"
+      @load="onLoad"
+    >
+
+    <template v-if="isError">
+      <span class="text-error text-sm">Failed to load</span>
+      <span v-if="attempts > 0" class="text-xs text-on-surface-variant">
+        Attempt {{ attempts + 1 }}
+      </span>
+      <button
+        class="px-3 py-1 bg-primary text-on-primary rounded text-sm"
+        @click="handleRetry"
+      >
+        Retry
+      </button>
+    </template>
+
+    <span v-else-if="!isLoaded" class="text-on-surface-variant text-sm">
+      Loading...
+    </span>
+  </div>
+</template>
diff --git a/apps/docs/src/examples/composables/use-image/lazy.vue b/apps/docs/src/examples/composables/use-image/lazy.vue
index a20c77b86..f91f973d1 100644
--- a/apps/docs/src/examples/composables/use-image/lazy.vue
+++ b/apps/docs/src/examples/composables/use-image/lazy.vue
@@ -1,47 +1,27 @@
-/* eslint-disable vuejs-accessibility/alt-text */
 <script setup lang="ts">
-  import { useImage, useIntersectionObserver } from '@vuetify/v0'
-  import { shallowRef } from 'vue'
+  import LazyImage from './LazyImage.vue'
 
-  const target = shallowRef<HTMLElement>()
-
-  const { isIntersecting } = useIntersectionObserver(target, () => {}, {
-    once: true,
-    rootMargin: '0px',
-  })
-
-  const { source, isLoaded, status, onLoad, onError } = useImage({
-    src: 'https://picsum.photos/seed/lazy/400/300',
-    eager: isIntersecting,
-  })
+  const photos = [
+    { id: 1, src: 'https://picsum.photos/seed/lazy-1/400/300', alt: 'Photo 1' },
+    { id: 2, src: 'https://picsum.photos/seed/lazy-2/400/300', alt: 'Photo 2' },
+    { id: 3, src: 'https://picsum.photos/seed/lazy-3/400/300', alt: 'Photo 3' },
+    { id: 4, src: 'https://picsum.photos/seed/lazy-4/400/300', alt: 'Photo 4' },
+  ]
 </script>
 
 <template>
-  <div class="flex flex-col gap-4">
-    <p class="text-sm text-on-surface-variant">
-      Scroll the image into view to start loading.
+  <div class="h-100 overflow-auto border border-divider rounded p-4">
+    <p class="text-sm text-on-surface-variant mb-4">
+      Scroll to load each image as it enters the viewport.
     </p>
 
-    <div class="h-100 overflow-auto border border-divider rounded p-4">
-      <div class="h-100 flex items-center justify-center text-on-surface-variant">
-        Scroll down ↓
-      </div>
-
-      <div ref="target" class="w-100 h-75 bg-surface-tint rounded overflow-hidden flex items-center justify-center mx-auto">
-        <img
-          v-show="isLoaded"
-          alt="Lazy-loaded photo"
-          class="w-full h-full object-cover"
-          :src="source"
-          @error="onError"
-          @load="onLoad"
-        >
-        <span v-if="!isLoaded" class="text-on-surface-variant text-sm">
-          {{ status }}
-        </span>
-      </div>
-
-      <div class="h-100" />
+    <div class="flex flex-col gap-100">
+      <LazyImage
+        v-for="photo in photos"
+        :key="photo.id"
+        :alt="photo.alt"
+        :src="photo.src"
+      />
     </div>
   </div>
 </template>
diff --git a/apps/docs/src/examples/composables/use-image/retry.vue b/apps/docs/src/examples/composables/use-image/retry.vue
index 19d6688b7..90eac2a07 100644
--- a/apps/docs/src/examples/composables/use-image/retry.vue
+++ b/apps/docs/src/examples/composables/use-image/retry.vue
@@ -1,41 +1,17 @@
-/* eslint-disable vuejs-accessibility/alt-text */
 <script setup lang="ts">
-  import { useImage } from '@vuetify/v0'
-
-  const { source, isLoaded, isError, status, onLoad, onError, retry } = useImage({
-    src: 'https://invalid.example/missing.jpg',
-  })
+  import RetryableImage from './RetryableImage.vue'
 </script>
 
 <template>
-  <div class="flex flex-col items-center gap-4">
-    <div class="w-100 h-75 bg-surface-tint rounded overflow-hidden flex flex-col items-center justify-center gap-2">
-      <img
-        v-show="isLoaded"
-        alt="Photo"
-        class="w-full h-full object-cover"
-        :src="source"
-        @error="onError"
-        @load="onLoad"
-      >
-
-      <template v-if="isError">
-        <span class="text-error text-sm">Failed to load</span>
-        <button
-          class="px-3 py-1 bg-primary text-on-primary rounded text-sm"
-          @click="retry"
-        >
-          Retry
-        </button>
-      </template>
-
-      <span v-else-if="!isLoaded" class="text-on-surface-variant text-sm">
-        Loading...
-      </span>
-    </div>
+  <div class="grid grid-cols-1 sm:grid-cols-2 gap-4">
+    <RetryableImage
+      alt="Working photo"
+      src="https://picsum.photos/seed/retry-ok/400/300"
+    />
 
-    <p class="text-xs text-on-surface-variant">
-      Status: <code>{{ status }}</code>
-    </p>
+    <RetryableImage
+      alt="Broken photo — click Retry"
+      src="https://invalid.example/missing.jpg"
+    />
   </div>
 </template>
diff --git a/apps/docs/src/examples/composables/use-image/useLazyImage.ts b/apps/docs/src/examples/composables/use-image/useLazyImage.ts
new file mode 100644
index 000000000..db56645cf
--- /dev/null
+++ b/apps/docs/src/examples/composables/use-image/useLazyImage.ts
@@ -0,0 +1,25 @@
+import { useImage, useIntersectionObserver } from '@vuetify/v0'
+import { shallowRef, toValue } from 'vue'
+
+import type { MaybeRefOrGetter } from 'vue'
+
+/**
+ * Combines `useImage` and `useIntersectionObserver` into a single reusable
+ * composable. The image source is gated by viewport intersection, and the
+ * returned `target` ref is bound to the element that should be observed.
+ */
+export function useLazyImage (src: MaybeRefOrGetter<string | undefined>, rootMargin = '0px') {
+  const target = shallowRef<HTMLElement>()
+
+  const { isIntersecting } = useIntersectionObserver(target, () => {}, {
+    once: true,
+    rootMargin,
+  })
+
+  const image = useImage({
+    src: () => toValue(src),
+    eager: isIntersecting,
+  })
+
+  return { target, ...image }
+}
diff --git a/apps/docs/src/pages/components/semantic/image.md b/apps/docs/src/pages/components/semantic/image.md
index c54661b8a..82c546708 100644
--- a/apps/docs/src/pages/components/semantic/image.md
+++ b/apps/docs/src/pages/components/semantic/image.md
@@ -29,11 +29,6 @@ Headless image component with state-driven placeholder and error fallback. Track
 
 ::: example
 /components/image/basic
-
-### Image with placeholder and fallback
-
-The basic compound: a placeholder during loading, the image when loaded, and a fallback on error. Native `loading="lazy"` defers the request until the browser deems it necessary.
-
 :::
 
 ## Anatomy
@@ -83,20 +78,32 @@ You can combine both: use the observer for state control and `loading="lazy"` as
 ## Examples
 
 ::: example
-/components/image/observer
+/components/image/BlurUpImage.vue 1
+/components/image/observer.vue 2
 
-### Observer-driven lazy loading
+### Blur-up LQIP with observer loading
 
-`lazy` on `Image.Root` defers the request until the root element intersects the viewport. The placeholder is visible while idle.
+Wrap `Image.Root` in a reusable component that drives a fade-in transition from a low-quality placeholder (LQIP) to the full-resolution image. The `lazy` prop on `Image.Root` defers the real source until the container intersects the viewport; the `status` slot prop drives opacity classes for a smooth blur-to-sharp transition.
+
+| File | Role |
+|------|------|
+| `BlurUpImage.vue` | Reusable component with LQIP placeholder and fade-in transition |
+| `observer.vue` | Entry point rendering a scrollable list of blur-up images |
 
 :::
 
 ::: example
-/components/image/picture
+/components/image/PictureImage.vue 1
+/components/image/picture.vue 2
 
 ### Picture element with format negotiation
 
-Use `renderless` mode on both `Image.Root` and `Image.Img` to drop the wrappers and emit a native `<picture>` element with `<source>` children for format negotiation.
+Use `renderless` mode on both `Image.Root` and `Image.Img` to drop their wrapper elements and compose them directly inside a native `<picture>` element. The browser picks the first supported `<source>`; `Image.Img` remains the fallback. All loading state is tracked by the surrounding `Image.Root` so `Image.Placeholder` and `Image.Fallback` behave the same as in the compound form.
+
+| File | Role |
+|------|------|
+| `PictureImage.vue` | Reusable wrapper that emits a `<picture>` with typed `<source>` children |
+| `picture.vue` | Entry point passing WebP and fallback sources |
 
 :::
 
@@ -135,6 +142,26 @@ The `retry()` function is available from both `Image.Root` and `Image.Fallback`
 </Image.Root>
 ```
 
+## Styling
+
+Every Image sub-component exposes `data-state` reflecting the current status (`idle`, `loading`, `loaded`, or `error`). Prefer styling against these data attributes with CSS over threading slot props — the transitions stay CSS-only and the template stays declarative.
+
+```vue
+<Image.Img
+  alt="Photo"
+  class="opacity-0 transition-opacity data-[state=loaded]:opacity-100"
+/>
+```
+
+```css
+/* Or with plain CSS */
+[data-state='loaded'] { opacity: 1; }
+[data-state='loading'] { animation: pulse 1s infinite; }
+[data-state='error'] { border-color: red; }
+```
+
+Slot props (`status`, `isLoaded`, etc.) remain available for the rare cases where logic has to branch in the template, but reach for CSS + data attributes first.
+
 ## Accessibility
 
 | Element | ARIA / behavior |
@@ -167,7 +194,16 @@ Yes — set `renderless` on both `Image.Root` and `Image.Img`, then compose them
 
 ??? How do I fade in once the image loads?
 
-Use the `status` slot prop from `Image.Root` to drive CSS classes, e.g. `:class="{ 'opacity-100': status === 'loaded' }"`.
+Style against the `data-state` attribute that every Image sub-component exposes. Using data attributes keeps the transition CSS-only — no slot-prop threading required.
+
+```vue
+<Image.Img
+  alt="Photo"
+  class="opacity-0 transition-opacity duration-500 data-[state=loaded]:opacity-100"
+/>
+```
+
+The `data-state` attribute holds the current status (`idle`, `loading`, `loaded`, or `error`). The blur-up example uses this pattern.
 
 ??? Why isn't `src` on `Image.Img`?
 
diff --git a/apps/docs/src/pages/composables/system/use-image.md b/apps/docs/src/pages/composables/system/use-image.md
index 1f30ec101..811a2aa10 100644
--- a/apps/docs/src/pages/composables/system/use-image.md
+++ b/apps/docs/src/pages/composables/system/use-image.md
@@ -42,6 +42,10 @@ const { source, isLoaded, isError, onLoad, onError, retry } = useImage({
 // <img :src="source" @load="onLoad" @error="onError" />
 ```
 
+::: example
+/composables/use-image/basic
+:::
+
 ## Architecture
 
 ```mermaid "useImage state machine"
@@ -68,29 +72,34 @@ stateDiagram-v2
 ## Examples
 
 ::: example
-/composables/use-image/basic
+/composables/use-image/useLazyImage.ts 1
+/composables/use-image/LazyImage.vue 2
+/composables/use-image/lazy.vue 3
 
-### Basic state tracking
+### Compose with useIntersectionObserver
 
-A plain image element wired up with `useImage`. Status updates as the image loads, errors, or is replaced with a new source.
+Wrap `useImage` and `useIntersectionObserver` in a small custom composable to build a reusable viewport-driven lazy loader. The `eager` gate receives the observer's `isIntersecting` signal so the source is withheld until the target element scrolls into view.
 
-:::
-
-::: example
-/composables/use-image/lazy
-
-### Composed with useIntersectionObserver
-
-Pair `useImage` with `useIntersectionObserver` for viewport-driven lazy loading. The `eager` gate withholds the source until the target intersects.
+| File | Role |
+|------|------|
+| `useLazyImage.ts` | Custom composable combining `useImage` with `useIntersectionObserver` |
+| `LazyImage.vue` | Presentational component that binds the returned `target`, `source`, and handlers |
+| `lazy.vue` | Entry point rendering several lazy images in a scrolling container |
 
 :::
 
 ::: example
-/composables/use-image/retry
+/composables/use-image/RetryableImage.vue 1
+/composables/use-image/retry.vue 2
 
 ### Retry on error
 
-When the image errors, `retry()` resets the status back to `loading` so the browser re-attempts the request.
+Build a reusable image component that exposes a retry button when loading fails. The `retry()` function resets the status back to `loading` so the browser re-attempts the request.
+
+| File | Role |
+|------|------|
+| `RetryableImage.vue` | Wraps `useImage` and renders a retry button on error |
+| `retry.vue` | Demonstrates both a successful source and a broken one side by side |
 
 :::
 
diff --git a/packages/0/src/components/Avatar/AvatarImage.vue b/packages/0/src/components/Avatar/AvatarImage.vue
index 9a5b4195e..71bef3b83 100644
--- a/packages/0/src/components/Avatar/AvatarImage.vue
+++ b/packages/0/src/components/Avatar/AvatarImage.vue
@@ -11,9 +11,17 @@
  */
 
 <script lang="ts">
+  // Components
+  import { Atom } from '#v0/components/Atom'
+
+  import { useAvatarRoot } from './AvatarRoot.vue'
+
   // Composables
   import { useImage } from '#v0/composables/useImage'
 
+  // Utilities
+  import { onUnmounted, toRef, watch } from 'vue'
+
   // Types
   import type { AtomProps } from '#v0/components/Atom'
   import type { ImageStatus } from '#v0/composables/useImage'
@@ -54,14 +62,6 @@
 </script>
 
 <script setup lang="ts">
-  // Components
-  import { Atom } from '#v0/components/Atom'
-  // Composables
-  import { useAvatarRoot } from './AvatarRoot.vue'
-
-  // Utilities
-  import { onUnmounted, toRef, watch } from 'vue'
-
   defineOptions({
     name: 'AvatarImage',
     inheritAttrs: false,
diff --git a/packages/0/src/components/Image/ImageFallback.vue b/packages/0/src/components/Image/ImageFallback.vue
index 05e035426..5ae62108d 100644
--- a/packages/0/src/components/Image/ImageFallback.vue
+++ b/packages/0/src/components/Image/ImageFallback.vue
@@ -9,9 +9,15 @@
  */
 
 <script lang="ts">
+  // Components
+  import { Atom } from '#v0/components/Atom'
+
   // Composables
   import { useImageRoot } from './ImageRoot.vue'
 
+  // Utilities
+  import { toRef } from 'vue'
+
   // Types
   import type { AtomProps } from '#v0/components/Atom'
 
@@ -32,12 +38,6 @@
 </script>
 
 <script setup lang="ts">
-  // Components
-  import { Atom } from '#v0/components/Atom'
-
-  // Utilities
-  import { toRef } from 'vue'
-
   defineOptions({ name: 'ImageFallback' })
 
   defineSlots<{
diff --git a/packages/0/src/components/Image/ImageImg.vue b/packages/0/src/components/Image/ImageImg.vue
index fd1e4f1b7..bedf85f1f 100644
--- a/packages/0/src/components/Image/ImageImg.vue
+++ b/packages/0/src/components/Image/ImageImg.vue
@@ -10,9 +10,15 @@
  */
 
 <script lang="ts">
+  // Components
+  import { Atom } from '#v0/components/Atom'
+
   // Composables
   import { useImageRoot } from './ImageRoot.vue'
 
+  // Utilities
+  import { toRef } from 'vue'
+
   // Types
   import type { AtomProps } from '#v0/components/Atom'
   import type { ImageStatus } from '#v0/composables/useImage'
@@ -74,12 +80,6 @@
 </script>
 
 <script setup lang="ts">
-  // Components
-  import { Atom } from '#v0/components/Atom'
-
-  // Utilities
-  import { toRef } from 'vue'
-
   defineOptions({
     name: 'ImageImg',
     inheritAttrs: false,
diff --git a/packages/0/src/components/Image/ImagePlaceholder.vue b/packages/0/src/components/Image/ImagePlaceholder.vue
index f8b598a9a..60c5c88e6 100644
--- a/packages/0/src/components/Image/ImagePlaceholder.vue
+++ b/packages/0/src/components/Image/ImagePlaceholder.vue
@@ -10,9 +10,15 @@
  */
 
 <script lang="ts">
+  // Components
+  import { Atom } from '#v0/components/Atom'
+
   // Composables
   import { useImageRoot } from './ImageRoot.vue'
 
+  // Utilities
+  import { toRef } from 'vue'
+
   // Types
   import type { AtomProps } from '#v0/components/Atom'
   import type { ImageStatus } from '#v0/composables/useImage'
@@ -34,12 +40,6 @@
 </script>
 
 <script setup lang="ts">
-  // Components
-  import { Atom } from '#v0/components/Atom'
-
-  // Utilities
-  import { toRef } from 'vue'
-
   defineOptions({ name: 'ImagePlaceholder' })
 
   defineSlots<{

From d59fac03817584c67e629ffe23ce9cdefe33b70d Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Thu, 16 Apr 2026 15:36:30 -0500
Subject: [PATCH 03/35] fix(Image): restore class propagation, remove v-show,
 clean up context

- ImageImg: drop inheritAttrs:false and v-show so class/style reach the
  <img> and the documented opacity/data-state fade-in actually animates
- ImageRoot: drop unused rootEl from context; warn via useLogger when
  lazy+renderless (previously silent never-loads)
- useImage: remove redundant shallowReadonly wrappers on already-readonly
  derived refs; keep shallowReadonly only on the mutable status
- tests: add class/style propagation regression test on Image.Img
- maturity: backfill since=0.2.0 on useImage and Image entries
---
 packages/0/src/components/Image/ImageImg.vue  | 10 +++-------
 packages/0/src/components/Image/ImageRoot.vue | 13 +++++++------
 packages/0/src/components/Image/index.test.ts | 13 +++++++++++++
 packages/0/src/composables/useImage/index.ts  | 10 +++++-----
 packages/0/src/maturity.json                  |  2 ++
 5 files changed, 30 insertions(+), 18 deletions(-)

diff --git a/packages/0/src/components/Image/ImageImg.vue b/packages/0/src/components/Image/ImageImg.vue
index bedf85f1f..c54004aa6 100644
--- a/packages/0/src/components/Image/ImageImg.vue
+++ b/packages/0/src/components/Image/ImageImg.vue
@@ -5,8 +5,8 @@
  *
  * @remarks
  * The image element. Reads the gated source and load/error handlers from the
- * Image context and binds them to the rendered element. Visible only when the
- * parent's status is loaded.
+ * Image context and binds them to the rendered element. Exposes `data-state`
+ * so consumers can drive visibility via CSS.
  */
 
 <script lang="ts">
@@ -80,10 +80,7 @@
 </script>
 
 <script setup lang="ts">
-  defineOptions({
-    name: 'ImageImg',
-    inheritAttrs: false,
-  })
+  defineOptions({ name: 'ImageImg' })
 
   defineSlots<{
     default: (props: ImageImgSlotProps) => any
@@ -144,7 +141,6 @@
 
 <template>
   <Atom
-    v-show="context.isLoaded.value"
     v-bind="slotProps.attrs"
     :as
     :renderless
diff --git a/packages/0/src/components/Image/ImageRoot.vue b/packages/0/src/components/Image/ImageRoot.vue
index e9b1dddec..db53495fe 100644
--- a/packages/0/src/components/Image/ImageRoot.vue
+++ b/packages/0/src/components/Image/ImageRoot.vue
@@ -17,6 +17,7 @@
   import { createContext } from '#v0/composables/createContext'
   import { useImage } from '#v0/composables/useImage'
   import { useIntersectionObserver } from '#v0/composables/useIntersectionObserver'
+  import { useLogger } from '#v0/composables/useLogger'
 
   // Utilities
   import { shallowRef, toRef, useTemplateRef } from 'vue'
@@ -27,7 +28,6 @@
   // Types
   import type { AtomExpose, AtomProps } from '#v0/components/Atom'
   import type { ImageStatus, UseImageReturn } from '#v0/composables/useImage'
-  import type { Ref } from 'vue'
 
   export interface ImageRootProps extends AtomProps {
     /** Image source URL. Forwarded to Image.Img via context. */
@@ -55,10 +55,7 @@
     }
   }
 
-  export interface ImageContext extends UseImageReturn {
-    /** Resolved root element ref — used by IntersectionObserver. */
-    rootEl: Ref<HTMLElement | null>
-  }
+  export interface ImageContext extends UseImageReturn {}
 
   export const [useImageRoot, provideImageRoot] = createContext<ImageContext>()
 </script>
@@ -82,6 +79,10 @@
   const atomRef = useTemplateRef<AtomExpose>('atom')
   const rootEl = toRef(() => toElement(atomRef.value?.element) as HTMLElement | null ?? null)
 
+  if (lazy && renderless) {
+    useLogger().warn('[v0:image] `lazy` requires a wrapper element but `renderless` is set — the image will never load. Remove `renderless` or use useIntersectionObserver manually.')
+  }
+
   const { isIntersecting } = lazy
     ? useIntersectionObserver(rootEl, () => {}, { once: true, rootMargin })
     : { isIntersecting: shallowRef(true) }
@@ -91,7 +92,7 @@
     eager: isIntersecting,
   })
 
-  provideImageRoot(namespace, { ...image, rootEl })
+  provideImageRoot(namespace, image)
 
   const slotProps = toRef((): ImageRootSlotProps => ({
     status: image.status.value,
diff --git a/packages/0/src/components/Image/index.test.ts b/packages/0/src/components/Image/index.test.ts
index cde7a3e10..7cebc809d 100644
--- a/packages/0/src/components/Image/index.test.ts
+++ b/packages/0/src/components/Image/index.test.ts
@@ -200,6 +200,19 @@ describe('image', () => {
         const img = wrapper.find('img')
         expect(img.attributes('role')).toBe('img')
       })
+
+      it('should propagate class and style to the img element', () => {
+        const wrapper = mount(Image.Root, {
+          props: { src: '/photo.jpg' },
+          slots: {
+            default: () => h(Image.Img, { alt: 'Test', class: 'custom-class', style: 'opacity: 0.5' }),
+          },
+        })
+
+        const img = wrapper.find('img')
+        expect(img.classes()).toContain('custom-class')
+        expect(img.attributes('style')).toContain('opacity: 0.5')
+      })
     })
 
     describe('events', () => {
diff --git a/packages/0/src/composables/useImage/index.ts b/packages/0/src/composables/useImage/index.ts
index 95ca2baf7..05938cc16 100644
--- a/packages/0/src/composables/useImage/index.ts
+++ b/packages/0/src/composables/useImage/index.ts
@@ -160,11 +160,11 @@ export function useImage (options: UseImageOptions): UseImageReturn {
 
   return {
     status: shallowReadonly(status),
-    isIdle: shallowReadonly(isIdle),
-    isLoading: shallowReadonly(isLoading),
-    isLoaded: shallowReadonly(isLoaded),
-    isError: shallowReadonly(isError),
-    source: shallowReadonly(source),
+    isIdle,
+    isLoading,
+    isLoaded,
+    isError,
+    source,
     onLoad,
     onError,
     retry,
diff --git a/packages/0/src/maturity.json b/packages/0/src/maturity.json
index d5097e1ca..c7ddb78ec 100644
--- a/packages/0/src/maturity.json
+++ b/packages/0/src/maturity.json
@@ -203,6 +203,7 @@
     },
     "useImage": {
       "level": "preview",
+      "since": "0.2.0",
       "category": "system"
     },
     "useIntersectionObserver": {
@@ -505,6 +506,7 @@
     },
     "Image": {
       "level": "preview",
+      "since": "0.2.0",
       "category": "semantic"
     },
     "Overflow": {

From bdfd9db50b50b7e4d1900264cd8fd23fea53442c Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Thu, 16 Apr 2026 15:36:34 -0500
Subject: [PATCH 04/35] docs(useImage): rename handleRetry to onRetry in retry
 example

Match the project-wide on<Action> convention.
---
 .../src/examples/composables/use-image/RetryableImage.vue     | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/docs/src/examples/composables/use-image/RetryableImage.vue b/apps/docs/src/examples/composables/use-image/RetryableImage.vue
index 9308af91b..65bd586b2 100644
--- a/apps/docs/src/examples/composables/use-image/RetryableImage.vue
+++ b/apps/docs/src/examples/composables/use-image/RetryableImage.vue
@@ -14,7 +14,7 @@
     src: toRef(() => props.src),
   })
 
-  function handleRetry () {
+  function onRetry () {
     attempts.value++
     retry()
   }
@@ -38,7 +38,7 @@
       </span>
       <button
         class="px-3 py-1 bg-primary text-on-primary rounded text-sm"
-        @click="handleRetry"
+        @click="onRetry"
       >
         Retry
       </button>

From ecb15bc64caeaf39b51761c765183f0cf7532b51 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Thu, 16 Apr 2026 15:36:49 -0500
Subject: [PATCH 05/35] feat(AspectRatio): add primitive with CSS aspect-ratio
 binding

New headless primitive that reserves a box with a fixed width-to-height
ratio. Thin wrapper around Atom that binds CSS aspect-ratio via inline
style. Accepts ratio as number or string, default 1 (square).

Useful for preventing CLS on media, iframe wrappers, thumbnail grids,
and composing with Image.Root for a shared reserved frame.

Ships with:
- AspectRatio.vue, index.ts barrel, index.test.ts (10 tests)
- Component export in components/index.ts
- maturity.json entry (primitives, preview, 0.2.0)
- Docs page at components/primitives/aspect-ratio.md
- basic.vue interactive example + ResponsiveImage multi-file example
- Entries in components/index.md and packages/0/README.md
---
 .../aspect-ratio/ResponsiveImage.vue          |  31 ++++
 .../components/aspect-ratio/basic.vue         |  38 +++++
 .../components/aspect-ratio/responsive.vue    |  18 +++
 apps/docs/src/pages/components/index.md       |   1 +
 .../components/primitives/aspect-ratio.md     | 150 ++++++++++++++++++
 apps/docs/src/typed-router.d.ts               |  13 ++
 packages/0/README.md                          |   1 +
 .../components/AspectRatio/AspectRatio.vue    |  77 +++++++++
 .../src/components/AspectRatio/index.test.ts  | 120 ++++++++++++++
 .../0/src/components/AspectRatio/index.ts     |  21 +++
 packages/0/src/components/index.ts            |   1 +
 packages/0/src/maturity.json                  |   5 +
 12 files changed, 476 insertions(+)
 create mode 100644 apps/docs/src/examples/components/aspect-ratio/ResponsiveImage.vue
 create mode 100644 apps/docs/src/examples/components/aspect-ratio/basic.vue
 create mode 100644 apps/docs/src/examples/components/aspect-ratio/responsive.vue
 create mode 100644 apps/docs/src/pages/components/primitives/aspect-ratio.md
 create mode 100644 packages/0/src/components/AspectRatio/AspectRatio.vue
 create mode 100644 packages/0/src/components/AspectRatio/index.test.ts
 create mode 100644 packages/0/src/components/AspectRatio/index.ts

diff --git a/apps/docs/src/examples/components/aspect-ratio/ResponsiveImage.vue b/apps/docs/src/examples/components/aspect-ratio/ResponsiveImage.vue
new file mode 100644
index 000000000..afc936b11
--- /dev/null
+++ b/apps/docs/src/examples/components/aspect-ratio/ResponsiveImage.vue
@@ -0,0 +1,31 @@
+<script setup lang="ts">
+  import { AspectRatio, Image } from '@vuetify/v0'
+
+  defineProps<{
+    src: string
+    alt: string
+    ratio: number | string
+  }>()
+</script>
+
+<template>
+  <AspectRatio
+    class="w-full bg-surface-tint rounded overflow-hidden relative"
+    :ratio
+  >
+    <Image.Root :src>
+      <Image.Img
+        :alt
+        class="w-full h-full object-cover"
+      />
+
+      <Image.Placeholder class="absolute inset-0 flex items-center justify-center">
+        <div class="w-full h-full bg-surface-tint animate-pulse" />
+      </Image.Placeholder>
+
+      <Image.Fallback class="absolute inset-0 flex items-center justify-center bg-error-container text-on-error-container text-sm">
+        Failed to load
+      </Image.Fallback>
+    </Image.Root>
+  </AspectRatio>
+</template>
diff --git a/apps/docs/src/examples/components/aspect-ratio/basic.vue b/apps/docs/src/examples/components/aspect-ratio/basic.vue
new file mode 100644
index 000000000..4a3da3a2c
--- /dev/null
+++ b/apps/docs/src/examples/components/aspect-ratio/basic.vue
@@ -0,0 +1,38 @@
+<script setup lang="ts">
+  import { AspectRatio } from '@vuetify/v0'
+  import { shallowRef } from 'vue'
+
+  const ratios = [
+    { label: '1 / 1', value: '1 / 1' },
+    { label: '4 / 3', value: '4 / 3' },
+    { label: '16 / 9', value: '16 / 9' },
+    { label: '21 / 9', value: '21 / 9' },
+  ]
+
+  const active = shallowRef('16 / 9')
+</script>
+
+<template>
+  <div class="space-y-4">
+    <div class="flex gap-2">
+      <button
+        v-for="r in ratios"
+        :key="r.value"
+        class="px-3 py-1 border rounded text-sm"
+        :class="active === r.value ? 'bg-primary text-on-primary' : 'bg-surface'"
+        @click="active = r.value"
+      >
+        {{ r.label }}
+      </button>
+    </div>
+
+    <AspectRatio
+      class="w-full bg-surface-tint rounded overflow-hidden"
+      :ratio="active"
+    >
+      <div class="w-full h-full flex items-center justify-center text-on-surface-variant text-sm">
+        {{ active }}
+      </div>
+    </AspectRatio>
+  </div>
+</template>
diff --git a/apps/docs/src/examples/components/aspect-ratio/responsive.vue b/apps/docs/src/examples/components/aspect-ratio/responsive.vue
new file mode 100644
index 000000000..c839757e3
--- /dev/null
+++ b/apps/docs/src/examples/components/aspect-ratio/responsive.vue
@@ -0,0 +1,18 @@
+<script setup lang="ts">
+  import ResponsiveImage from './ResponsiveImage.vue'
+</script>
+
+<template>
+  <div class="grid grid-cols-1 sm:grid-cols-2 gap-4">
+    <ResponsiveImage
+      alt="Landscape photo"
+      :ratio="16 / 9"
+      src="https://picsum.photos/seed/ar-1/800/450"
+    />
+    <ResponsiveImage
+      alt="Square photo"
+      :ratio="1"
+      src="https://picsum.photos/seed/ar-2/400/400"
+    />
+  </div>
+</template>
diff --git a/apps/docs/src/pages/components/index.md b/apps/docs/src/pages/components/index.md
index 9cfad9c13..d4838bed5 100644
--- a/apps/docs/src/pages/components/index.md
+++ b/apps/docs/src/pages/components/index.md
@@ -24,6 +24,7 @@ Foundation components for building higher-level abstractions.
 
 | Name | Description |
 | - | - |
+| [AspectRatio](/components/primitives/aspect-ratio) | Fixed width-to-height ratio container via CSS `aspect-ratio` |
 | [Atom](/components/primitives/atom) | Polymorphic element with dynamic `as` prop and renderless mode |
 | [Portal](/components/primitives/portal) | Teleport wrapper with automatic z-index stacking via useStack |
 | [Presence](/components/primitives/presence) | Renderless mount lifecycle with lazy mounting and exit animation delay |
diff --git a/apps/docs/src/pages/components/primitives/aspect-ratio.md b/apps/docs/src/pages/components/primitives/aspect-ratio.md
new file mode 100644
index 000000000..e9aa0d805
--- /dev/null
+++ b/apps/docs/src/pages/components/primitives/aspect-ratio.md
@@ -0,0 +1,150 @@
+---
+title: AspectRatio - Reserve Layout Space for Vue 3
+meta:
+  - name: description
+    content: Headless Vue 3 primitive that reserves a fixed width-to-height ratio using CSS aspect-ratio. Prevents Cumulative Layout Shift for media, iframes, and responsive containers.
+  - name: keywords
+    content: aspect ratio, aspectRatio, CLS, cumulative layout shift, responsive, Vue 3, headless, primitive, iframe wrapper
+features:
+  category: Component
+  label: 'C: AspectRatio'
+  github: /components/AspectRatio/
+  renderless: false
+  level: 1
+related:
+  - /components/semantic/image
+  - /components/primitives/atom
+---
+
+# AspectRatio
+
+Reserves a box with a fixed width-to-height ratio using CSS `aspect-ratio`.
+
+<DocsPageFeatures :frontmatter />
+
+## Usage
+
+Wrap any content whose height should track its width. The child fills the
+reserved frame — pair with `w-full h-full` or absolute positioning.
+
+::: example
+/components/aspect-ratio/basic
+:::
+
+## Anatomy
+
+```vue Anatomy playground collapse
+<script setup lang="ts">
+  import { AspectRatio } from '@vuetify/v0'
+</script>
+
+<template>
+  <AspectRatio :ratio="16 / 9">
+    <!-- content -->
+  </AspectRatio>
+</template>
+```
+
+## Examples
+
+::: example
+/components/aspect-ratio/ResponsiveImage.vue 1
+/components/aspect-ratio/responsive.vue 2
+
+### Compose with Image
+
+Wrap `Image.Root` in `AspectRatio` to pin the load frame to a fixed ratio.
+The placeholder, fallback, and loaded image all share the same reserved
+space — no Cumulative Layout Shift regardless of load order.
+
+| File | Role |
+|------|------|
+| `ResponsiveImage.vue` | `AspectRatio` wrapping `Image.Root` and its children |
+| `responsive.vue` | Entry point rendering images at two different ratios |
+
+:::
+
+## Recipes
+
+### Video embed
+
+```vue
+<template>
+  <AspectRatio :ratio="16 / 9" class="w-full">
+    <iframe
+      class="w-full h-full"
+      src="https://www.youtube.com/embed/..."
+    />
+  </AspectRatio>
+</template>
+```
+
+### Square thumbnail grid
+
+```vue
+<template>
+  <div class="grid grid-cols-3 gap-2">
+    <AspectRatio v-for="photo in photos" :key="photo.id" :ratio="1">
+      <img :src="photo.src" class="w-full h-full object-cover" />
+    </AspectRatio>
+  </div>
+</template>
+```
+
+### Number or string
+
+`ratio` accepts either form. Both produce the same output:
+
+```vue
+<template>
+  <AspectRatio :ratio="16 / 9" /> <!-- number: 1.777... -->
+  <AspectRatio ratio="16 / 9" />  <!-- string -->
+</template>
+```
+
+## Accessibility
+
+`AspectRatio` is a presentational primitive — it renders a `<div>` with an
+inline style and no semantics of its own. Any ARIA attributes belong on the
+content inside. Pass `as` to change the element when a different semantic
+wrapper is needed (e.g. `as="figure"`).
+
+## Questions
+
+::: faq
+
+??? Why use `AspectRatio` when I can just set `aspect-ratio` in CSS?
+
+You can, and for static layouts it's fine. Reach for `AspectRatio` when the
+ratio is dynamic, when you want the intent to be visible at the call site,
+or when the same frame wraps more than one piece of content (placeholder,
+image, fallback) and all three need to share the reservation.
+
+??? Does the child need `w-full h-full`?
+
+If the child should fill the frame, yes. `aspect-ratio` only reserves the
+box — it doesn't size the child. Using `object-cover` on media is the usual
+pairing. Absolute positioning (`position: absolute; inset: 0`) on the child
+also works and is what layered compositions (image + placeholder + fallback)
+typically use.
+
+??? Can I combine `AspectRatio` with `Image.Root`?
+
+Yes — put `AspectRatio` on the outside. `Image.Root` then participates in
+the reserved frame without needing its own width/height, and the placeholder
+and fallback sit inside the same box. See the [responsive example](#compose-with-image).
+
+??? Does this affect SSR?
+
+No. `aspect-ratio` is an inline style that renders identically on server and
+client, so there's no hydration mismatch and no layout shift on hydration.
+
+??? Browser support?
+
+CSS `aspect-ratio` is supported in all modern browsers (Chrome 88+,
+Firefox 89+, Safari 15+). Legacy fallbacks (padding-bottom hack) are not
+provided — if you need to support older browsers, add your own fallback.
+
+:::
+
+<DocsApi />
diff --git a/apps/docs/src/typed-router.d.ts b/apps/docs/src/typed-router.d.ts
index fd63ea881..e9255f08a 100644
--- a/apps/docs/src/typed-router.d.ts
+++ b/apps/docs/src/typed-router.d.ts
@@ -195,6 +195,13 @@ declare module 'vue-router/auto-routes' {
       Record<never, never>,
       | never
     >,
+    '/components/primitives/aspect-ratio': RouteRecordInfo<
+      '/components/primitives/aspect-ratio',
+      '/components/primitives/aspect-ratio',
+      Record<never, never>,
+      Record<never, never>,
+      | never
+    >,
     '/components/primitives/atom': RouteRecordInfo<
       '/components/primitives/atom',
       '/components/primitives/atom',
@@ -1164,6 +1171,12 @@ declare module 'vue-router/auto-routes' {
       views:
         | never
     }
+    'src/pages/components/primitives/aspect-ratio.md': {
+      routes:
+        | '/components/primitives/aspect-ratio'
+      views:
+        | never
+    }
     'src/pages/components/primitives/atom.md': {
       routes:
         | '/components/primitives/atom'
diff --git a/packages/0/README.md b/packages/0/README.md
index 14e3563f3..d6736ad84 100644
--- a/packages/0/README.md
+++ b/packages/0/README.md
@@ -81,6 +81,7 @@ import { ... } from '@vuetify/v0/date'       // Date adapter and utilities
 
 | Component | Description |
 |-----------|-------------|
+| [AspectRatio](https://0.vuetifyjs.com/components/primitives/aspect-ratio) | Fixed width-to-height ratio container via CSS `aspect-ratio` |
 | [Atom](https://0.vuetifyjs.com/components/primitives/atom) | Polymorphic base element with dynamic `as` prop and renderless mode |
 | [Portal](https://0.vuetifyjs.com/components/primitives/portal) | Teleport wrapper with automatic z-index stacking via useStack |
 | [Presence](https://0.vuetifyjs.com/components/primitives/presence) | Animation-agnostic mount lifecycle with lazy mounting and exit timing |
diff --git a/packages/0/src/components/AspectRatio/AspectRatio.vue b/packages/0/src/components/AspectRatio/AspectRatio.vue
new file mode 100644
index 000000000..0b6e63ee7
--- /dev/null
+++ b/packages/0/src/components/AspectRatio/AspectRatio.vue
@@ -0,0 +1,77 @@
+/**
+ * @module AspectRatio
+ *
+ * @see https://0.vuetifyjs.com/components/primitives/aspect-ratio
+ *
+ * @remarks
+ * Reserves a box with a fixed width-to-height ratio using CSS `aspect-ratio`.
+ * Useful for preventing Cumulative Layout Shift while media loads, for iframe
+ * wrappers, and for any container whose height should track its width.
+ *
+ * Accepts a number (`16 / 9`) or a string (`'16 / 9'`, `'1.777'`). Inner
+ * content fills the reserved frame — pair with `w-full h-full` or
+ * `position: absolute inset-0` on children.
+ */
+
+<script lang="ts">
+  // Components
+  import { Atom } from '#v0/components/Atom'
+
+  // Utilities
+  import { isNumber } from '#v0/utilities'
+  import { toRef } from 'vue'
+
+  // Types
+  import type { AtomProps } from '#v0/components/Atom'
+
+  export interface AspectRatioProps extends AtomProps {
+    /**
+     * The aspect ratio as `width / height`. Accepts a number (`16 / 9`) or a
+     * CSS `aspect-ratio` string (`'16 / 9'`, `'1.777'`).
+     * @default 1
+     */
+    ratio?: number | string
+  }
+
+  export interface AspectRatioSlotProps {
+    /** Resolved CSS `aspect-ratio` value. */
+    ratio: string
+    /** Attributes to bind to the root element. */
+    attrs: {
+      style: { aspectRatio: string }
+    }
+  }
+</script>
+
+<script setup lang="ts">
+  defineOptions({ name: 'AspectRatio' })
+
+  defineSlots<{
+    default: (props: AspectRatioSlotProps) => any
+  }>()
+
+  const {
+    as = 'div',
+    renderless,
+    ratio = 1,
+  } = defineProps<AspectRatioProps>()
+
+  const resolved = toRef(() => isNumber(ratio) ? String(ratio) : ratio)
+
+  const slotProps = toRef((): AspectRatioSlotProps => ({
+    ratio: resolved.value,
+    attrs: {
+      style: { aspectRatio: resolved.value },
+    },
+  }))
+</script>
+
+<template>
+  <Atom
+    v-bind="slotProps.attrs"
+    :as
+    :renderless
+  >
+    <slot v-bind="slotProps" />
+  </Atom>
+</template>
diff --git a/packages/0/src/components/AspectRatio/index.test.ts b/packages/0/src/components/AspectRatio/index.test.ts
new file mode 100644
index 000000000..ea4146bbb
--- /dev/null
+++ b/packages/0/src/components/AspectRatio/index.test.ts
@@ -0,0 +1,120 @@
+import { describe, expect, it } from 'vitest'
+import { renderToString } from 'vue/server-renderer'
+
+// Utilities
+import { mount } from '@vue/test-utils'
+import { createSSRApp, defineComponent, h } from 'vue'
+
+import { AspectRatio } from './index'
+
+describe('aspectRatio', () => {
+  describe('rendering', () => {
+    it('should render as div by default', () => {
+      const wrapper = mount(AspectRatio, {
+        slots: { default: () => h('span', 'Content') },
+      })
+
+      expect(wrapper.element.tagName).toBe('DIV')
+    })
+
+    it('should render as custom element when as prop is provided', () => {
+      const wrapper = mount(AspectRatio, {
+        props: { as: 'section' },
+        slots: { default: () => h('span', 'Content') },
+      })
+
+      expect(wrapper.element.tagName).toBe('SECTION')
+    })
+
+    it('should support renderless mode', () => {
+      const wrapper = mount(AspectRatio, {
+        props: { renderless: true },
+        slots: { default: () => h('figure', { class: 'custom' }, 'Content') },
+      })
+
+      expect(wrapper.find('.custom').exists()).toBe(true)
+    })
+  })
+
+  describe('ratio', () => {
+    it('should default to 1 (square)', () => {
+      const wrapper = mount(AspectRatio, {
+        slots: { default: () => h('span') },
+      })
+
+      expect((wrapper.element as HTMLElement).style.aspectRatio).toBe('1 / 1')
+    })
+
+    it('should accept a numeric ratio', () => {
+      const wrapper = mount(AspectRatio, {
+        props: { ratio: 16 / 9 },
+        slots: { default: () => h('span') },
+      })
+
+      expect((wrapper.element as HTMLElement).style.aspectRatio).toContain('1.77')
+    })
+
+    it('should accept a string ratio', () => {
+      const wrapper = mount(AspectRatio, {
+        props: { ratio: '4 / 3' },
+        slots: { default: () => h('span') },
+      })
+
+      expect((wrapper.element as HTMLElement).style.aspectRatio).toBe('4 / 3')
+    })
+
+    it('should update when ratio changes', async () => {
+      const wrapper = mount(AspectRatio, {
+        props: { ratio: '1 / 1' },
+        slots: { default: () => h('span') },
+      })
+
+      expect((wrapper.element as HTMLElement).style.aspectRatio).toBe('1 / 1')
+
+      await wrapper.setProps({ ratio: '16 / 9' })
+
+      expect((wrapper.element as HTMLElement).style.aspectRatio).toBe('16 / 9')
+    })
+  })
+
+  describe('slot props', () => {
+    it('should expose resolved ratio and attrs', () => {
+      let captured: any
+      mount(AspectRatio, {
+        props: { ratio: '16 / 9' },
+        slots: {
+          default: (props: any) => {
+            captured = props
+            return h('span')
+          },
+        },
+      })
+
+      expect(captured.ratio).toBe('16 / 9')
+      expect(captured.attrs.style.aspectRatio).toBe('16 / 9')
+    })
+  })
+
+  describe('fallthrough', () => {
+    it('should propagate class to the root element', () => {
+      const wrapper = mount(AspectRatio, {
+        attrs: { class: 'custom-class' },
+        slots: { default: () => h('span') },
+      })
+
+      expect(wrapper.classes()).toContain('custom-class')
+    })
+  })
+
+  describe('sSR', () => {
+    it('should render to string without errors', async () => {
+      const app = createSSRApp(defineComponent({
+        render: () => h(AspectRatio, { ratio: '16 / 9' }, () => h('span', 'Content')),
+      }))
+
+      const html = await renderToString(app)
+      expect(html).toBeTruthy()
+      expect(html).toContain('aspect-ratio')
+    })
+  })
+})
diff --git a/packages/0/src/components/AspectRatio/index.ts b/packages/0/src/components/AspectRatio/index.ts
new file mode 100644
index 000000000..a7effd35d
--- /dev/null
+++ b/packages/0/src/components/AspectRatio/index.ts
@@ -0,0 +1,21 @@
+export type { AspectRatioProps, AspectRatioSlotProps } from './AspectRatio.vue'
+
+/**
+ * Primitive that reserves a box with a fixed width-to-height ratio.
+ *
+ * @see https://0.vuetifyjs.com/components/primitives/aspect-ratio
+ *
+ * @example
+ * ```vue
+ * <script lang="ts" setup>
+ *   import { AspectRatio } from '@vuetify/v0'
+ * </script>
+ *
+ * <template>
+ *   <AspectRatio :ratio="16 / 9">
+ *     <img src="/photo.jpg" class="w-full h-full object-cover" />
+ *   </AspectRatio>
+ * </template>
+ * ```
+ */
+export { default as AspectRatio } from './AspectRatio.vue'
diff --git a/packages/0/src/components/index.ts b/packages/0/src/components/index.ts
index 26b7ae62e..732e3fc9e 100644
--- a/packages/0/src/components/index.ts
+++ b/packages/0/src/components/index.ts
@@ -1,4 +1,5 @@
 export * from './AlertDialog'
+export * from './AspectRatio'
 export * from './Atom'
 export * from './Avatar'
 export * from './Breadcrumbs'
diff --git a/packages/0/src/maturity.json b/packages/0/src/maturity.json
index c7ddb78ec..d62548630 100644
--- a/packages/0/src/maturity.json
+++ b/packages/0/src/maturity.json
@@ -325,6 +325,11 @@
     }
   },
   "components": {
+    "AspectRatio": {
+      "level": "preview",
+      "since": "0.2.0",
+      "category": "primitives"
+    },
     "Atom": {
       "level": "preview",
       "since": "0.1.0",

From 66257fd112249a1cd71d7775bf40074ca0d65480 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Fri, 17 Apr 2026 12:46:23 -0500
Subject: [PATCH 06/35] docs(Image): wrap bare markup in image.md vue code
 fences with <template>

---
 .../src/pages/components/semantic/image.md    | 62 +++++++++++--------
 1 file changed, 35 insertions(+), 27 deletions(-)

diff --git a/apps/docs/src/pages/components/semantic/image.md b/apps/docs/src/pages/components/semantic/image.md
index 82c546708..4614a46d8 100644
--- a/apps/docs/src/pages/components/semantic/image.md
+++ b/apps/docs/src/pages/components/semantic/image.md
@@ -114,18 +114,20 @@ Use `renderless` mode on both `Image.Root` and `Image.Img` to drop their wrapper
 Set `loading="eager"` and `fetchpriority="high"` on hero images to optimize LCP. Always include `width` and `height` to prevent layout shift.
 
 ```vue
-<Image.Root src="/hero.jpg">
-  <Image.Img
-    alt="Hero"
-    width="1600"
-    height="900"
-    loading="eager"
-    fetchpriority="high"
-  />
-  <Image.Placeholder>
-    <img src="/hero-tiny.jpg" class="w-full blur-sm" />
-  </Image.Placeholder>
-</Image.Root>
+<template>
+  <Image.Root src="/hero.jpg">
+    <Image.Img
+      alt="Hero"
+      width="1600"
+      height="900"
+      loading="eager"
+      fetchpriority="high"
+    />
+    <Image.Placeholder>
+      <img src="/hero-tiny.jpg" class="w-full blur-sm" />
+    </Image.Placeholder>
+  </Image.Root>
+</template>
 ```
 
 ### Retry on error
@@ -133,13 +135,15 @@ Set `loading="eager"` and `fetchpriority="high"` on hero images to optimize LCP.
 The `retry()` function is available from both `Image.Root` and `Image.Fallback` slot props.
 
 ```vue
-<Image.Root src="/photo.jpg">
-  <Image.Img alt="Photo" />
-  <Image.Placeholder>Loading...</Image.Placeholder>
-  <Image.Fallback v-slot="{ retry }">
-    <button @click="retry">Retry</button>
-  </Image.Fallback>
-</Image.Root>
+<template>
+  <Image.Root src="/photo.jpg">
+    <Image.Img alt="Photo" />
+    <Image.Placeholder>Loading...</Image.Placeholder>
+    <Image.Fallback v-slot="{ retry }">
+      <button @click="retry">Retry</button>
+    </Image.Fallback>
+  </Image.Root>
+</template>
 ```
 
 ## Styling
@@ -147,10 +151,12 @@ The `retry()` function is available from both `Image.Root` and `Image.Fallback`
 Every Image sub-component exposes `data-state` reflecting the current status (`idle`, `loading`, `loaded`, or `error`). Prefer styling against these data attributes with CSS over threading slot props — the transitions stay CSS-only and the template stays declarative.
 
 ```vue
-<Image.Img
-  alt="Photo"
-  class="opacity-0 transition-opacity data-[state=loaded]:opacity-100"
-/>
+<template>
+  <Image.Img
+    alt="Photo"
+    class="opacity-0 transition-opacity data-[state=loaded]:opacity-100"
+  />
+</template>
 ```
 
 ```css
@@ -197,10 +203,12 @@ Yes — set `renderless` on both `Image.Root` and `Image.Img`, then compose them
 Style against the `data-state` attribute that every Image sub-component exposes. Using data attributes keeps the transition CSS-only — no slot-prop threading required.
 
 ```vue
-<Image.Img
-  alt="Photo"
-  class="opacity-0 transition-opacity duration-500 data-[state=loaded]:opacity-100"
-/>
+<template>
+  <Image.Img
+    alt="Photo"
+    class="opacity-0 transition-opacity duration-500 data-[state=loaded]:opacity-100"
+  />
+</template>
 ```
 
 The `data-state` attribute holds the current status (`idle`, `loading`, `loaded`, or `error`). The blur-up example uses this pattern.

From 01d3bb2a70a130683cefe113b79a6e3d1c74a883 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Thu, 16 Apr 2026 15:45:15 -0500
Subject: [PATCH 07/35] docs(Image): center the basic usage example

---
 .../src/examples/components/image/basic.vue   | 38 ++++++++++---------
 1 file changed, 20 insertions(+), 18 deletions(-)

diff --git a/apps/docs/src/examples/components/image/basic.vue b/apps/docs/src/examples/components/image/basic.vue
index 55ffbb6bc..48fbd185f 100644
--- a/apps/docs/src/examples/components/image/basic.vue
+++ b/apps/docs/src/examples/components/image/basic.vue
@@ -3,24 +3,26 @@
 </script>
 
 <template>
-  <Image.Root
-    class="w-100 h-75 bg-surface-tint rounded overflow-hidden relative"
-    src="https://picsum.photos/seed/v0-image/400/300"
-  >
-    <Image.Img
-      alt="Random photo"
-      class="w-full h-full object-cover"
-      height="300"
-      loading="lazy"
-      width="400"
-    />
+  <div class="flex items-center justify-center">
+    <Image.Root
+      class="w-100 h-75 bg-surface-tint rounded overflow-hidden relative"
+      src="https://picsum.photos/seed/v0-image/400/300"
+    >
+      <Image.Img
+        alt="Random photo"
+        class="w-full h-full object-cover"
+        height="300"
+        loading="lazy"
+        width="400"
+      />
 
-    <Image.Placeholder class="absolute inset-0 flex items-center justify-center">
-      <div class="w-full h-full bg-surface-tint animate-pulse" />
-    </Image.Placeholder>
+      <Image.Placeholder class="absolute inset-0 flex items-center justify-center">
+        <div class="w-full h-full bg-surface-tint animate-pulse" />
+      </Image.Placeholder>
 
-    <Image.Fallback class="absolute inset-0 flex items-center justify-center bg-error-container text-on-error-container text-sm">
-      Image failed to load
-    </Image.Fallback>
-  </Image.Root>
+      <Image.Fallback class="absolute inset-0 flex items-center justify-center bg-error-container text-on-error-container text-sm">
+        Image failed to load
+      </Image.Fallback>
+    </Image.Root>
+  </div>
 </template>

From 89836202adc64f4140acfd107edba2b8a2e92bd4 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Thu, 16 Apr 2026 15:53:46 -0500
Subject: [PATCH 08/35] docs: expand prose under Examples headers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Lengthen example descriptions for AspectRatio, Image, and useImage pages
with when-to-reach-for, gotchas, and composition notes. Examples under
## Examples are featured — one-sentence summaries don't carry enough
context for readers landing cold.
---
 .../components/primitives/aspect-ratio.md     | 32 ++++++++++++++---
 .../src/pages/components/semantic/image.md    | 31 +++++++++++++----
 .../src/pages/composables/system/use-image.md | 34 +++++++++++++++----
 3 files changed, 79 insertions(+), 18 deletions(-)

diff --git a/apps/docs/src/pages/components/primitives/aspect-ratio.md b/apps/docs/src/pages/components/primitives/aspect-ratio.md
index e9aa0d805..e206147ab 100644
--- a/apps/docs/src/pages/components/primitives/aspect-ratio.md
+++ b/apps/docs/src/pages/components/primitives/aspect-ratio.md
@@ -53,14 +53,36 @@ reserved frame — pair with `w-full h-full` or absolute positioning.
 
 ### Compose with Image
 
-Wrap `Image.Root` in `AspectRatio` to pin the load frame to a fixed ratio.
-The placeholder, fallback, and loaded image all share the same reserved
-space — no Cumulative Layout Shift regardless of load order.
+Wrap `Image.Root` in `AspectRatio` to pin the load frame to a fixed
+width-to-height ratio. The placeholder, fallback, and loaded image all
+share the same reserved box — so the layout never reflows as the image
+transitions through `idle → loading → loaded` or drops into `error`.
+
+This composition is the recommended pattern for content images whose
+natural dimensions vary, or that come from a CMS where the source's
+intrinsic size isn't known at authoring time. Instead of hard-coding
+`width`/`height` attributes that may not match the final media, let the
+container enforce the frame and let the image cover it via
+`object-cover`.
+
+Two tradeoffs to know about:
+
+- The child must fill the frame. Use `w-full h-full` on `Image.Img` (or
+  absolute positioning) so it stretches to the reserved box — otherwise
+  the box is taller than the rendered image and looks broken.
+- A single ratio applies to every descendant. If you need different
+  ratios per breakpoint, swap the `:ratio` prop with a responsive
+  expression (`computed` driven by `useBreakpoints`) rather than
+  layering multiple `AspectRatio` wrappers.
+
+Pairs naturally with `useImage` when you're driving the state machine
+manually, and with `useIntersectionObserver` when combining native lazy
+loading (`loading="lazy"`) with a reserved frame.
 
 | File | Role |
 |------|------|
-| `ResponsiveImage.vue` | `AspectRatio` wrapping `Image.Root` and its children |
-| `responsive.vue` | Entry point rendering images at two different ratios |
+| `ResponsiveImage.vue` | Reusable wrapper — `AspectRatio` around `Image.Root` with placeholder, fallback, and `object-cover` image |
+| `responsive.vue` | Entry point rendering images at two different ratios side-by-side (`16 / 9` landscape and `1` square) |
 
 :::
 
diff --git a/apps/docs/src/pages/components/semantic/image.md b/apps/docs/src/pages/components/semantic/image.md
index 4614a46d8..694a8dcf3 100644
--- a/apps/docs/src/pages/components/semantic/image.md
+++ b/apps/docs/src/pages/components/semantic/image.md
@@ -83,12 +83,22 @@ You can combine both: use the observer for state control and `loading="lazy"` as
 
 ### Blur-up LQIP with observer loading
 
-Wrap `Image.Root` in a reusable component that drives a fade-in transition from a low-quality placeholder (LQIP) to the full-resolution image. The `lazy` prop on `Image.Root` defers the real source until the container intersects the viewport; the `status` slot prop drives opacity classes for a smooth blur-to-sharp transition.
+Wrap `Image.Root` in a reusable component that drives a fade-in transition from a low-quality placeholder (LQIP) to the full-resolution image. A tiny blurred thumbnail ships in the initial HTML (or as a small base64 string), visible immediately; the full image is withheld by the `lazy` prop until `Image.Root` intersects the viewport, at which point it loads and fades in over the blur.
+
+Reach for this pattern when you have many below-the-fold images and want both perceived performance (something visible instantly) and actual bandwidth savings (only load what's seen). It shines on photo galleries, article covers, and image-heavy marketing pages where the blur-up effect is part of the aesthetic, not just a loading trick.
+
+Three pieces make it work:
+
+- **`lazy` prop on `Image.Root`** — defers setting the real `src` until the container scrolls into view via `useIntersectionObserver`. Pair with `root-margin` (e.g. `"200px"`) to start loading a bit before the container actually intersects.
+- **LQIP inside `Image.Placeholder`** — the blurred preview sits in the reserved frame (typically `absolute inset-0`). It's decorative, so `Image.Placeholder` auto-sets `aria-hidden="true"`.
+- **`data-state`-driven opacity** — the real `Image.Img` uses `opacity-0 transition-opacity data-[state=loaded]:opacity-100`, so the fade-in is CSS-only and doesn't require threading slot props through the template.
+
+Gotcha: the `lazy` prop needs a wrapper element to observe — it warns and skips observation when combined with `renderless`. If you need a lazy `<picture>`, observe a parent yourself with `useIntersectionObserver` and gate the source manually via `useImage`'s `eager` option.
 
 | File | Role |
 |------|------|
-| `BlurUpImage.vue` | Reusable component with LQIP placeholder and fade-in transition |
-| `observer.vue` | Entry point rendering a scrollable list of blur-up images |
+| `BlurUpImage.vue` | Reusable component with LQIP placeholder, `lazy` intersection loading, and CSS-driven fade-in |
+| `observer.vue` | Entry point rendering a scrollable list of blur-up images to demonstrate the viewport trigger |
 
 :::
 
@@ -98,12 +108,21 @@ Wrap `Image.Root` in a reusable component that drives a fade-in transition from
 
 ### Picture element with format negotiation
 
-Use `renderless` mode on both `Image.Root` and `Image.Img` to drop their wrapper elements and compose them directly inside a native `<picture>` element. The browser picks the first supported `<source>`; `Image.Img` remains the fallback. All loading state is tracked by the surrounding `Image.Root` so `Image.Placeholder` and `Image.Fallback` behave the same as in the compound form.
+Use `renderless` mode on both `Image.Root` and `Image.Img` to drop their wrapper elements and compose them directly inside a native `<picture>` element. The browser walks the `<source>` list and picks the first format it supports (WebP, AVIF, JPEG XL, etc.); `Image.Img` renders the fallback `<img>` that older browsers use. All loading state is still tracked by the surrounding `Image.Root`, so `Image.Placeholder` and `Image.Fallback` behave identically to the compound form — no extra wiring needed.
+
+Reach for this pattern when you're serving modern image formats for bandwidth or quality gains while keeping a universal fallback, or when you need full control over DOM structure (e.g., embedding inside a `<figure>` with a `<figcaption>`). It's the only way to use `Image.Root`'s state machine with a native `<picture>` without losing either the format negotiation or the state-driven placeholder/fallback pattern.
+
+Two details worth knowing:
+
+- **`renderless` on both** — `Image.Root` must go renderless to avoid wrapping `<picture>` in an extra `<div>`, and `Image.Img` must go renderless so you can place the inner `<img>` as `<picture>`'s last child (where the browser expects it).
+- **`lazy` doesn't work here** — observer-driven lazy loading relies on a wrapper element to measure against. Combine native `loading="lazy"` on the inner `<img>` with `fetchpriority` hints for equivalent deferred loading, or wrap the whole composition in an outer element you observe manually.
+
+The `<source>` children are fully browser-driven — `Image.Img` never sees their URLs. It just reports the final `<img>` element's `load`/`error` events back to the context.
 
 | File | Role |
 |------|------|
-| `PictureImage.vue` | Reusable wrapper that emits a `<picture>` with typed `<source>` children |
-| `picture.vue` | Entry point passing WebP and fallback sources |
+| `PictureImage.vue` | Reusable wrapper that emits a `<picture>` with typed `<source>` children; both `Image.Root` and `Image.Img` go renderless to drop wrapper elements |
+| `picture.vue` | Entry point passing WebP and fallback sources to demonstrate format negotiation |
 
 :::
 
diff --git a/apps/docs/src/pages/composables/system/use-image.md b/apps/docs/src/pages/composables/system/use-image.md
index 811a2aa10..8879d6f3f 100644
--- a/apps/docs/src/pages/composables/system/use-image.md
+++ b/apps/docs/src/pages/composables/system/use-image.md
@@ -78,13 +78,23 @@ stateDiagram-v2
 
 ### Compose with useIntersectionObserver
 
-Wrap `useImage` and `useIntersectionObserver` in a small custom composable to build a reusable viewport-driven lazy loader. The `eager` gate receives the observer's `isIntersecting` signal so the source is withheld until the target element scrolls into view.
+Wrap `useImage` and `useIntersectionObserver` in a small custom composable to build a reusable viewport-driven lazy loader. The observer returns a reactive `isIntersecting` flag; pipe that into `useImage`'s `eager` option and the source is withheld — status stays `idle`, no network request is made — until the target element scrolls into view.
+
+Reach for this pattern when the built-in `<Image.Root lazy>` isn't a fit: when you're not using the `Image` compound at all, when you need the observer target to be a different element than the image container, or when you want to share one observer across several images. The composable becomes the single owner of both "has it entered the viewport" and "what's the load status" — callers just destructure `{ target, source, onLoad, onError, isLoaded }` and wire them up.
+
+Three things make this composition work:
+
+- **`once: true` on the observer** — once the element intersects, the observer disconnects. `isIntersecting` stays `true` thereafter, so the image loads once and doesn't regress if the user scrolls it back off-screen.
+- **`rootMargin`** — start loading slightly before intersection (e.g. `"200px"`) so the image is typically loaded by the time it's actually visible. The default `"0px"` fires exactly at viewport entry, which can produce a visible blank frame on fast scrolling.
+- **`eager: isIntersecting`** — the observer's reactive flag drives `useImage`'s gate directly. No manual `watch`, no imperative calls — Vue's reactivity handles the state transition.
+
+Under the hood `<Image.Root lazy>` does exactly this; the custom composable exists so you can apply the same pattern without the compound component.
 
 | File | Role |
 |------|------|
-| `useLazyImage.ts` | Custom composable combining `useImage` with `useIntersectionObserver` |
-| `LazyImage.vue` | Presentational component that binds the returned `target`, `source`, and handlers |
-| `lazy.vue` | Entry point rendering several lazy images in a scrolling container |
+| `useLazyImage.ts` | Custom composable combining `useImage` and `useIntersectionObserver` — returns `{ target, ...image }` for consumers |
+| `LazyImage.vue` | Presentational component binding the returned `target` to its root, `source` to the `<img>`, and handlers to `load`/`error` |
+| `lazy.vue` | Entry point rendering several lazy images in a scrolling container to demonstrate the viewport trigger |
 
 :::
 
@@ -94,12 +104,22 @@ Wrap `useImage` and `useIntersectionObserver` in a small custom composable to bu
 
 ### Retry on error
 
-Build a reusable image component that exposes a retry button when loading fails. The `retry()` function resets the status back to `loading` so the browser re-attempts the request.
+Build a reusable image component that surfaces a retry button when loading fails. Calling `retry()` resets the status back to `loading` (or `idle` if `eager` is currently `false`) without changing the `src` — the browser re-attempts the same request, which handles the common case of transient network failures, flaky CDNs, or images that aren't in cache yet on the second attempt.
+
+Reach for this pattern anywhere a failed image shouldn't be a dead end: user-uploaded content that might take a moment to propagate through a CDN, photos behind a request-signed URL that can expire, or any UX where a "try again" button is friendlier than leaving a broken-image icon on screen. Track an `attempts` counter alongside `retry` when you want to cap retries or show progress ("Attempt 3 of 3") — `useImage` doesn't manage retry bookkeeping itself, which keeps it headless.
+
+A few details worth knowing:
+
+- **`retry()` is idempotent relative to `src`** — it doesn't change the source, just rewinds the state machine. If the image fails deterministically (404, CORS error), retry loops without progress; a fallback source or a cap is the caller's responsibility.
+- **Works with reactive `src` changes** — swapping `src` also resets the state machine automatically, so you typically call `retry()` only when you want to re-attempt the *same* URL. Set a new URL via the reactive ref if you want to try a different source.
+- **Pairs with the `status` ref** — the example conditionally renders the button via `isError`, but you can style around `data-state="error"` for CSS-only treatments (e.g., a red border that appears on error).
+
+Not limited to user-facing retries — the same pattern works for programmatic retries with backoff: watch `isError`, schedule a timer, call `retry()`.
 
 | File | Role |
 |------|------|
-| `RetryableImage.vue` | Wraps `useImage` and renders a retry button on error |
-| `retry.vue` | Demonstrates both a successful source and a broken one side by side |
+| `RetryableImage.vue` | Wraps `useImage`, tracks an `attempts` counter, and renders a retry button inside an `isError` branch |
+| `retry.vue` | Demonstrates both a working source and a broken one side-by-side so the retry UX is visible without waiting for real failure |
 
 :::
 

From 7432ad23a318fcddc54b1eb719618f4430ade0f4 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Thu, 16 Apr 2026 15:59:01 -0500
Subject: [PATCH 09/35] docs: add mermaid diagrams to strong-fit examples

Composition tree for AspectRatio+Image, reactive signal pipeline for
useImage+useIntersectionObserver, and the blur-up fade-in sequence on
the Image page. Each diagram anchors the example's mental model up
front so the prose below doesn't carry the whole load alone.
---
 .../pages/components/primitives/aspect-ratio.md    | 14 ++++++++++++++
 apps/docs/src/pages/components/semantic/image.md   | 12 ++++++++++++
 .../docs/src/pages/composables/system/use-image.md | 11 +++++++++++
 3 files changed, 37 insertions(+)

diff --git a/apps/docs/src/pages/components/primitives/aspect-ratio.md b/apps/docs/src/pages/components/primitives/aspect-ratio.md
index e206147ab..5f22c75e7 100644
--- a/apps/docs/src/pages/components/primitives/aspect-ratio.md
+++ b/apps/docs/src/pages/components/primitives/aspect-ratio.md
@@ -58,6 +58,20 @@ width-to-height ratio. The placeholder, fallback, and loaded image all
 share the same reserved box — so the layout never reflows as the image
 transitions through `idle → loading → loaded` or drops into `error`.
 
+```mermaid "Composition"
+flowchart TD
+  AR["AspectRatio<br/>(reserves the frame)"]
+  IR["Image.Root<br/>(state machine)"]
+  II["Image.Img<br/>w-full h-full object-cover"]
+  IP["Image.Placeholder<br/>absolute inset-0"]
+  IF["Image.Fallback<br/>absolute inset-0"]
+
+  AR --> IR
+  IR --> II
+  IR --> IP
+  IR --> IF
+```
+
 This composition is the recommended pattern for content images whose
 natural dimensions vary, or that come from a CMS where the source's
 intrinsic size isn't known at authoring time. Instead of hard-coding
diff --git a/apps/docs/src/pages/components/semantic/image.md b/apps/docs/src/pages/components/semantic/image.md
index 694a8dcf3..6b051f1e1 100644
--- a/apps/docs/src/pages/components/semantic/image.md
+++ b/apps/docs/src/pages/components/semantic/image.md
@@ -85,6 +85,18 @@ You can combine both: use the observer for state control and `loading="lazy"` as
 
 Wrap `Image.Root` in a reusable component that drives a fade-in transition from a low-quality placeholder (LQIP) to the full-resolution image. A tiny blurred thumbnail ships in the initial HTML (or as a small base64 string), visible immediately; the full image is withheld by the `lazy` prop until `Image.Root` intersects the viewport, at which point it loads and fades in over the blur.
 
+```mermaid "Blur-up transition"
+flowchart LR
+  Scroll["User scrolls<br/>container in"]
+  Observer["IntersectionObserver<br/>fires (once)"]
+  Status["status:<br/>idle → loading"]
+  Load["img.onload"]
+  DS["data-state<br/>= 'loaded'"]
+  Fade["CSS fade<br/>opacity 0 → 1"]
+
+  Scroll --> Observer --> Status --> Load --> DS --> Fade
+```
+
 Reach for this pattern when you have many below-the-fold images and want both perceived performance (something visible instantly) and actual bandwidth savings (only load what's seen). It shines on photo galleries, article covers, and image-heavy marketing pages where the blur-up effect is part of the aesthetic, not just a loading trick.
 
 Three pieces make it work:
diff --git a/apps/docs/src/pages/composables/system/use-image.md b/apps/docs/src/pages/composables/system/use-image.md
index 8879d6f3f..6409e3d3e 100644
--- a/apps/docs/src/pages/composables/system/use-image.md
+++ b/apps/docs/src/pages/composables/system/use-image.md
@@ -80,6 +80,17 @@ stateDiagram-v2
 
 Wrap `useImage` and `useIntersectionObserver` in a small custom composable to build a reusable viewport-driven lazy loader. The observer returns a reactive `isIntersecting` flag; pipe that into `useImage`'s `eager` option and the source is withheld — status stays `idle`, no network request is made — until the target element scrolls into view.
 
+```mermaid "Reactive signal pipeline"
+flowchart LR
+  Target["target<br/>ref&lt;HTMLElement&gt;"]
+  Observer["useIntersectionObserver<br/>{ once: true }"]
+  Signal["isIntersecting<br/>Ref&lt;boolean&gt;"]
+  Image["useImage<br/>{ eager }"]
+  Source["source<br/>Ref&lt;string | undefined&gt;"]
+
+  Target --> Observer --> Signal --> Image --> Source
+```
+
 Reach for this pattern when the built-in `<Image.Root lazy>` isn't a fit: when you're not using the `Image` compound at all, when you need the observer target to be a different element than the image container, or when you want to share one observer across several images. The composable becomes the single owner of both "has it entered the viewport" and "what's the load status" — callers just destructure `{ target, source, onLoad, onError, isLoaded }` and wire them up.
 
 Three things make this composition work:

From 7435256063bb4ff7ae21f25d8334651734618886 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Thu, 16 Apr 2026 16:03:08 -0500
Subject: [PATCH 10/35] docs(Image): add info callout explaining why src lives
 on Root

---
 apps/docs/src/pages/components/semantic/image.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/apps/docs/src/pages/components/semantic/image.md b/apps/docs/src/pages/components/semantic/image.md
index 6b051f1e1..262369ac9 100644
--- a/apps/docs/src/pages/components/semantic/image.md
+++ b/apps/docs/src/pages/components/semantic/image.md
@@ -49,6 +49,9 @@ Headless image component with state-driven placeholder and error fallback. Track
 </template>
 ```
 
+> [!TIP]
+> **Why `src` is the exception.** `src` lives on `Image.Root` because it's the one image attribute that drives state — the load lifecycle (`idle → loading → loaded | error`) can't function without knowing the URL to track. Every other image attribute (`alt`, `width`, `height`, `srcset`, `sizes`, `crossorigin`, `referrerpolicy`, `decoding`, `loading`, `fetchpriority`) is a pure rendering concern and lives on `Image.Img`, where it describes the element that actually renders it.
+
 ## Architecture
 
 `Image.Root` calls `useImage` to manage status, and optionally wires up `useIntersectionObserver` when the `lazy` prop is set. Children consume the root context via `useImageRoot`.

From 8092f47aa16d973d545985d75d6d2019f2e813e6 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Thu, 16 Apr 2026 16:05:49 -0500
Subject: [PATCH 11/35] docs(Image): recast src callout as INFO and rephrase
 opener

---
 apps/docs/src/pages/components/semantic/image.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/docs/src/pages/components/semantic/image.md b/apps/docs/src/pages/components/semantic/image.md
index 262369ac9..a0de5e627 100644
--- a/apps/docs/src/pages/components/semantic/image.md
+++ b/apps/docs/src/pages/components/semantic/image.md
@@ -49,8 +49,8 @@ Headless image component with state-driven placeholder and error fallback. Track
 </template>
 ```
 
-> [!TIP]
-> **Why `src` is the exception.** `src` lives on `Image.Root` because it's the one image attribute that drives state — the load lifecycle (`idle → loading → loaded | error`) can't function without knowing the URL to track. Every other image attribute (`alt`, `width`, `height`, `srcset`, `sizes`, `crossorigin`, `referrerpolicy`, `decoding`, `loading`, `fetchpriority`) is a pure rendering concern and lives on `Image.Img`, where it describes the element that actually renders it.
+> [!INFO]
+> `src` is the only native image attribute that doesn't live on `Image.Img` because it drives the load state machine — the `idle → loading → loaded | error` lifecycle can't function without knowing the URL to track, so `Image.Root` owns it. Every other image attribute (`alt`, `width`, `height`, `srcset`, `sizes`, `crossorigin`, `referrerpolicy`, `decoding`, `loading`, `fetchpriority`) is a pure rendering concern and lives on `Image.Img`, where it describes the element that actually renders it.
 
 ## Architecture
 

From d63b5f64efcebf77ea0171b892156ce0b40db957 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Thu, 16 Apr 2026 16:16:42 -0500
Subject: [PATCH 12/35] feat(Image): expose threshold and root observer options
 on Image.Root

Previously only rootMargin was pluggable when lazy loading. Passing a
scroll container via root or a visibility threshold required dropping
to useIntersectionObserver + useImage manually. The new props forward
directly to the observer so a scrollable gallery or partial-visibility
trigger works on the compound component.
---
 packages/0/src/components/Image/ImageRoot.vue | 16 ++++++-
 packages/0/src/components/Image/index.test.ts | 42 ++++++++++++++++++-
 2 files changed, 56 insertions(+), 2 deletions(-)

diff --git a/packages/0/src/components/Image/ImageRoot.vue b/packages/0/src/components/Image/ImageRoot.vue
index db53495fe..b1831e16a 100644
--- a/packages/0/src/components/Image/ImageRoot.vue
+++ b/packages/0/src/components/Image/ImageRoot.vue
@@ -36,6 +36,18 @@
     lazy?: boolean
     /** IntersectionObserver root margin. Only used when lazy is true. */
     rootMargin?: string
+    /**
+     * IntersectionObserver threshold(s). A number or array of numbers
+     * between 0.0 and 1.0 indicating the percentage of the target's
+     * visibility required to trigger the observer. Only used when lazy is true.
+     */
+    threshold?: number | number[]
+    /**
+     * IntersectionObserver root element. If omitted, the viewport is used.
+     * Pass a scroll container to observe intersections relative to it instead.
+     * Only used when lazy is true.
+     */
+    root?: Element | null
     /** Namespace for dependency injection. */
     namespace?: string
   }
@@ -73,6 +85,8 @@
     src,
     lazy = false,
     rootMargin = '0px',
+    threshold = 0,
+    root = null,
     namespace = 'v0:image',
   } = defineProps<ImageRootProps>()
 
@@ -84,7 +98,7 @@
   }
 
   const { isIntersecting } = lazy
-    ? useIntersectionObserver(rootEl, () => {}, { once: true, rootMargin })
+    ? useIntersectionObserver(rootEl, () => {}, { once: true, rootMargin, threshold, root })
     : { isIntersecting: shallowRef(true) }
 
   const image = useImage({
diff --git a/packages/0/src/components/Image/index.test.ts b/packages/0/src/components/Image/index.test.ts
index 7cebc809d..05091a3b2 100644
--- a/packages/0/src/components/Image/index.test.ts
+++ b/packages/0/src/components/Image/index.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { renderToString } from 'vue/server-renderer'
 
 // Utilities
@@ -122,6 +122,21 @@ describe('image', () => {
 
         expect(captured.status).toBe('loading')
       })
+
+      it('should accept threshold and root props without throwing', () => {
+        expect(() => {
+          mount(Image.Root, {
+            props: {
+              src: '/photo.jpg',
+              lazy: true,
+              threshold: 0.5,
+              rootMargin: '100px',
+              root: null,
+            },
+            slots: { default: () => h('span') },
+          })
+        }).not.toThrow()
+      })
     })
   })
 
@@ -251,6 +266,31 @@ describe('image', () => {
 
         expect(captured.status).toBe('error')
       })
+
+      it('should emit loadstart on initial mount when eager', () => {
+        const onLoadstart = vi.fn()
+        mount(Image.Root, {
+          props: { src: '/photo.jpg' },
+          slots: {
+            default: () => h(Image.Img, { alt: 'Test', onLoadstart }),
+          },
+        })
+
+        expect(onLoadstart).toHaveBeenCalledTimes(1)
+        expect(onLoadstart).toHaveBeenCalledWith('/photo.jpg')
+      })
+
+      it('should not emit loadstart when idle (lazy)', () => {
+        const onLoadstart = vi.fn()
+        mount(Image.Root, {
+          props: { src: '/photo.jpg', lazy: true },
+          slots: {
+            default: () => h(Image.Img, { alt: 'Test', onLoadstart }),
+          },
+        })
+
+        expect(onLoadstart).not.toHaveBeenCalled()
+      })
     })
   })
 

From 6d8684cd75ab558fde3682f13455c4e5c7326219 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Thu, 16 Apr 2026 16:16:48 -0500
Subject: [PATCH 13/35] feat(Image): emit loadstart on Image.Img
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Synthesized from status transitions rather than the native <img>
loadstart event (which browsers fire inconsistently for images).
Fires when the image enters the loading state on initial mount, on
intersection, or when src changes. Emits the source URL as the
argument — matches VImg's loadstart payload shape.
---
 packages/0/src/components/Image/ImageImg.vue | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/packages/0/src/components/Image/ImageImg.vue b/packages/0/src/components/Image/ImageImg.vue
index c54004aa6..17836c29a 100644
--- a/packages/0/src/components/Image/ImageImg.vue
+++ b/packages/0/src/components/Image/ImageImg.vue
@@ -17,7 +17,7 @@
   import { useImageRoot } from './ImageRoot.vue'
 
   // Utilities
-  import { toRef } from 'vue'
+  import { toRef, watch } from 'vue'
 
   // Types
   import type { AtomProps } from '#v0/components/Atom'
@@ -51,6 +51,12 @@
   export interface ImageImgEmits {
     load: [e: Event]
     error: [e: Event]
+    /**
+     * Synthesized event fired when the image transitions into the `loading`
+     * state (on initial mount if `eager`, on intersection if `lazy`, or when
+     * `src` changes). Emits the source URL that started loading.
+     */
+    loadstart: [src: string]
   }
 
   export interface ImageImgSlotProps {
@@ -116,6 +122,12 @@
     emit('error', e)
   }
 
+  watch(context.status, (status, prev) => {
+    if (status === 'loading' && prev !== 'loading' && context.source.value) {
+      emit('loadstart', context.source.value)
+    }
+  }, { immediate: true })
+
   const slotProps = toRef((): ImageImgSlotProps => ({
     isLoaded: context.isLoaded.value,
     status: context.status.value,

From ea7e0999d80125992945e2e96b2509237885e461 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Thu, 16 Apr 2026 16:46:11 -0500
Subject: [PATCH 14/35] feat(Image): add Image.Presence for source-transition
 crossfading
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Drop-in replacement for Image.Img when navigating between already-loaded
sources — keeps the previous image visible while a new one loads, then
crossfades via opacity. Built on the Presence primitive: the previous
img layer's mount lifecycle (mounted → leaving → unmounted) is driven
by Presence, with CSS targeting data-state='leaving' to fade opacity
1 → 0 and transitionend triggering done() to finalize the unmount.

Shipped with a multi-file Gallery example, a mermaid sequence diagram
in the Examples block, an accessibility table entry (previous img is
aria-hidden), and an FAQ entry clarifying when to pick Presence over
Img. Presence acts like Img on the initial load; the transition only
engages on subsequent src changes.
---
 .../components/image/GalleryImage.vue         |  29 +++
 .../src/examples/components/image/gallery.vue |  54 +++++
 .../src/pages/components/semantic/image.md    |  46 +++-
 .../0/src/components/Image/ImagePresence.vue  | 215 ++++++++++++++++++
 packages/0/src/components/Image/index.test.ts | 114 ++++++++++
 packages/0/src/components/Image/index.ts      |  19 ++
 6 files changed, 476 insertions(+), 1 deletion(-)
 create mode 100644 apps/docs/src/examples/components/image/GalleryImage.vue
 create mode 100644 apps/docs/src/examples/components/image/gallery.vue
 create mode 100644 packages/0/src/components/Image/ImagePresence.vue

diff --git a/apps/docs/src/examples/components/image/GalleryImage.vue b/apps/docs/src/examples/components/image/GalleryImage.vue
new file mode 100644
index 000000000..dc427d4b3
--- /dev/null
+++ b/apps/docs/src/examples/components/image/GalleryImage.vue
@@ -0,0 +1,29 @@
+<script setup lang="ts">
+  import { Image } from '@vuetify/v0'
+
+  defineProps<{
+    src: string
+    alt: string
+  }>()
+</script>
+
+<template>
+  <Image.Root
+    class="w-full aspect-4/3 bg-surface-tint rounded overflow-hidden relative"
+    :src
+  >
+    <Image.Presence
+      :alt
+      class="w-full h-full"
+      img-class="w-full h-full object-cover"
+    />
+
+    <Image.Placeholder class="absolute inset-0 flex items-center justify-center">
+      <div class="w-full h-full bg-surface-tint animate-pulse" />
+    </Image.Placeholder>
+
+    <Image.Fallback class="absolute inset-0 flex items-center justify-center bg-error-container text-on-error-container text-sm">
+      Failed to load
+    </Image.Fallback>
+  </Image.Root>
+</template>
diff --git a/apps/docs/src/examples/components/image/gallery.vue b/apps/docs/src/examples/components/image/gallery.vue
new file mode 100644
index 000000000..daa8d0bb9
--- /dev/null
+++ b/apps/docs/src/examples/components/image/gallery.vue
@@ -0,0 +1,54 @@
+<script setup lang="ts">
+  import GalleryImage from './GalleryImage.vue'
+  import { shallowRef } from 'vue'
+
+  const photos = [
+    { id: 1, src: 'https://picsum.photos/seed/gallery-1/600/450', alt: 'Photo 1' },
+    { id: 2, src: 'https://picsum.photos/seed/gallery-2/600/450', alt: 'Photo 2' },
+    { id: 3, src: 'https://picsum.photos/seed/gallery-3/600/450', alt: 'Photo 3' },
+    { id: 4, src: 'https://picsum.photos/seed/gallery-4/600/450', alt: 'Photo 4' },
+  ]
+
+  const index = shallowRef(0)
+  function current () {
+    return photos[index.value]!
+  }
+
+  function onNext () {
+    index.value = (index.value + 1) % photos.length
+  }
+
+  function onPrev () {
+    index.value = (index.value - 1 + photos.length) % photos.length
+  }
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-4 w-full max-w-lg mx-auto">
+    <GalleryImage :alt="current().alt" :src="current().src" />
+
+    <div class="flex items-center gap-4">
+      <button
+        class="px-3 py-1 bg-primary text-on-primary rounded text-sm"
+        @click="onPrev"
+      >
+        Previous
+      </button>
+
+      <span class="text-sm text-on-surface-variant">
+        {{ index + 1 }} / {{ photos.length }}
+      </span>
+
+      <button
+        class="px-3 py-1 bg-primary text-on-primary rounded text-sm"
+        @click="onNext"
+      >
+        Next
+      </button>
+    </div>
+
+    <p class="text-xs text-on-surface-variant text-center max-w-md">
+      The previous photo stays on screen while the next loads — no flash to the placeholder between navigations.
+    </p>
+  </div>
+</template>
diff --git a/apps/docs/src/pages/components/semantic/image.md b/apps/docs/src/pages/components/semantic/image.md
index a0de5e627..4f87076bb 100644
--- a/apps/docs/src/pages/components/semantic/image.md
+++ b/apps/docs/src/pages/components/semantic/image.md
@@ -25,7 +25,7 @@ Headless image component with state-driven placeholder and error fallback. Track
 
 ## Usage
 
-`Image.Root` owns the loading state machine via `useImage`. `Image.Img` renders the image element and reports load and error events to the context. `Image.Placeholder` is shown while idle or loading; `Image.Fallback` is shown on error.
+`Image.Root` owns the loading state machine via `useImage`. `Image.Img` renders the image element and reports load and error events to the context. `Image.Placeholder` is shown while idle or loading; `Image.Fallback` is shown on error. `Image.Presence` is a drop-in alternative to `Image.Img` that crossfades between sources when `src` changes — see the [gallery example](#gallery-navigation-with-image-presence).
 
 ::: example
 /components/image/basic
@@ -141,6 +141,45 @@ The `<source>` children are fully browser-driven — `Image.Img` never sees thei
 
 :::
 
+::: example
+/components/image/GalleryImage.vue 1
+/components/image/gallery.vue 2
+
+### Gallery navigation with Image.Presence
+
+Swap `Image.Img` for `Image.Presence` when navigating between already-loaded sources should never flash the placeholder. The component renders two stacked `<img>` elements: the newly loaded one fades in while the previous one fades out at the same tempo. Until the new source loads, the old image stays on screen — the user never sees blank space between photos.
+
+```mermaid "Source transition"
+flowchart LR
+  Change["src changes<br/>(Root.src = newUrl)"]
+  Capture["previousSrc ← oldUrl<br/>showPrevious = true"]
+  Mount["Presence mounts<br/>the previous img<br/>at opacity 1"]
+  Load["New img loads"]
+  Leave["showPrevious = false<br/>Presence enters leaving"]
+  Fade["Crossfade:<br/>previous opacity 1 → 0<br/>current opacity 0 → 1"]
+  Unmount["transitionend<br/>done() fires<br/>previous unmounts"]
+
+  Change --> Capture --> Mount --> Load --> Leave --> Fade --> Unmount
+```
+
+Reach for this pattern whenever the user can navigate between preloaded sources — image galleries, photo viewers, product thumbnails reacting to a color picker, or anywhere a `v-model` drives `src`. Without `Image.Presence`, each navigation resets the state machine to `loading`; the old image disappears from the DOM and the placeholder shows until the next image loads, producing a visible pop. `Image.Presence` holds the previous image in DOM through the load window, so the transition stays continuous.
+
+A few details worth knowing:
+
+- **Initial mount behaves like `Image.Img`** — there's no previous source on first load, so the component renders a single `<img>` and the placeholder shows while it loads. Only *subsequent* src changes engage the crossfade.
+- **Built on `Presence` internally** — the previous layer's lifecycle (mounted → leaving → unmounted) is driven by the `Presence` primitive. CSS targets `data-state='leaving'` to fade opacity 1 → 0, and the `transitionend` event triggers `done()` to finalize the unmount. No `setTimeout`, no manual cleanup.
+- **`img-class` vs `class`** — `class` goes on the wrapper `<div>` (layout, size, border-radius), while `img-class` applies to both inner `<img>` elements (object-fit, filters). This split is necessary because the wrapper coordinates two imgs via `position: relative`.
+- **Error state** — if the new image errors, the old one stays visible underneath and `Image.Fallback` overlays as usual. Call `retry()` from the Root slot props or the Fallback slot props to re-attempt the same source.
+
+Not a replacement for `Image.Img` in every case — if you don't need cross-src transitions (single content image, hero banner, avatars), stick with `Image.Img` for the simpler DOM.
+
+| File | Role |
+|------|------|
+| `GalleryImage.vue` | Reusable wrapper — `Image.Root` with `Image.Presence`, `Image.Placeholder`, and `Image.Fallback` overlays |
+| `gallery.vue` | Entry point with Previous/Next navigation cycling through four sources to demonstrate the continuous transition |
+
+:::
+
 ## Recipes
 
 ### Hero image with high priority
@@ -207,6 +246,7 @@ Slot props (`status`, `isLoaded`, etc.) remain available for the rare cases wher
 | Element | ARIA / behavior |
 | - | - |
 | `Image.Img` | `role="img"`, accepts `alt` for accessible name |
+| `Image.Presence` | Current `<img>` is the accessible image; the transitioning previous `<img>` is marked `aria-hidden="true"` so screen readers only announce the active source |
 | `Image.Placeholder` | `aria-hidden="true"` — placeholder is decorative |
 | `Image.Fallback` | `role="img"` — provide alternate text inside the slot |
 
@@ -232,6 +272,10 @@ Always set `width` and `height` on `Image.Img`. The browser uses these to reserv
 
 Yes — set `renderless` on both `Image.Root` and `Image.Img`, then compose them inside a native `<picture>` element. See the picture example.
 
+??? When should I use `Image.Presence` instead of `Image.Img`?
+
+Use `Image.Presence` when the `src` on `Image.Root` can change to a different URL *after* the first image has loaded, and you want to avoid flashing the placeholder between transitions — gallery navigation, product variant thumbnails, anywhere a `v-model` drives `src`. `Image.Img` is the right choice for single-source content images where `src` never changes (or only changes via a full component remount).
+
 ??? How do I fade in once the image loads?
 
 Style against the `data-state` attribute that every Image sub-component exposes. Using data attributes keeps the transition CSS-only — no slot-prop threading required.
diff --git a/packages/0/src/components/Image/ImagePresence.vue b/packages/0/src/components/Image/ImagePresence.vue
new file mode 100644
index 000000000..a197daea3
--- /dev/null
+++ b/packages/0/src/components/Image/ImagePresence.vue
@@ -0,0 +1,215 @@
+/**
+ * @module ImagePresence
+ *
+ * @see https://0.vuetifyjs.com/components/semantic/image
+ *
+ * @remarks
+ * Source-transitioning image element. Keeps the previously loaded source
+ * visible while a new one loads, then crossfades between them via opacity.
+ * Uses the Presence primitive to manage the mount lifecycle of the previous
+ * layer — its data-state drives the exit transition.
+ *
+ * Replaces Image.Img when you want seamless transitions between already-
+ * loaded sources (carousels, galleries, next/previous navigation). On the
+ * initial load, behaves identically to Image.Img.
+ *
+ * API note: despite sharing the name, Image.Presence is not driven by a
+ * v-model boolean like the top-level Presence primitive — its lifecycle is
+ * triggered implicitly by src changes on Image.Root.
+ */
+
+<script lang="ts">
+  // Components
+  import { Atom } from '#v0/components/Atom'
+  import { Presence } from '#v0/components/Presence'
+
+  // Composables
+  import { useImageRoot } from './ImageRoot.vue'
+
+  // Utilities
+  import { shallowRef, toRef, watch } from 'vue'
+
+  // Types
+  import type { AtomProps } from '#v0/components/Atom'
+  import type { ImageStatus } from '#v0/composables/useImage'
+
+  export interface ImagePresenceProps extends AtomProps {
+    /** Accessible alt text applied to both the current and previous image layers. */
+    alt?: string
+    /** Responsive image candidates. */
+    srcset?: string
+    /** Image sizes hint for responsive selection. */
+    sizes?: string
+    /** Intrinsic image width — set to prevent layout shift. */
+    width?: number | string
+    /** Intrinsic image height — set to prevent layout shift. */
+    height?: number | string
+    /** CORS request mode. */
+    crossorigin?: '' | 'anonymous' | 'use-credentials'
+    /** Referrer policy for the request. */
+    referrerpolicy?:
+      | 'origin'
+      | 'no-referrer'
+      | 'no-referrer-when-downgrade'
+      | 'origin-when-cross-origin'
+      | 'same-origin'
+      | 'strict-origin'
+      | 'strict-origin-when-cross-origin'
+      | 'unsafe-url'
+    /** How the browser should decode the image. */
+    decoding?: 'sync' | 'async' | 'auto'
+    /** Native browser-managed lazy loading hint. */
+    loading?: 'eager' | 'lazy'
+    /** Resource priority hint. */
+    fetchpriority?: 'high' | 'low' | 'auto'
+    /** Class applied to both inner image elements. */
+    imgClass?: string | string[] | Record<string, boolean>
+    /** Namespace for retrieving the Image context. */
+    namespace?: string
+  }
+
+  export interface ImagePresenceEmits {
+    load: [e: Event]
+    error: [e: Event]
+    loadstart: [src: string]
+  }
+
+  export interface ImagePresenceSlotProps {
+    /** Current loading status. */
+    status: ImageStatus
+    /** Whether the current source has loaded. */
+    isLoaded: boolean
+    /** The active source URL (from Image.Root context). */
+    currentSrc: string | undefined
+    /** The last successfully loaded source, or undefined on first load. */
+    previousSrc: string | undefined
+    /** Attributes for the wrapper element. */
+    attrs: {
+      'data-state': ImageStatus
+    }
+  }
+</script>
+
+<script setup lang="ts">
+  defineOptions({ name: 'ImagePresence' })
+
+  defineSlots<{
+    default: (props: ImagePresenceSlotProps) => any
+  }>()
+
+  const {
+    as = 'div',
+    renderless,
+    alt,
+    srcset,
+    sizes,
+    width,
+    height,
+    crossorigin,
+    referrerpolicy,
+    decoding = 'async',
+    loading,
+    fetchpriority,
+    imgClass,
+    namespace = 'v0:image',
+  } = defineProps<ImagePresenceProps>()
+
+  const emit = defineEmits<ImagePresenceEmits>()
+
+  const context = useImageRoot(namespace)
+  const currentSrc = toRef(() => context.source.value)
+  const previousSrc = shallowRef<string | undefined>()
+  const showPrevious = shallowRef(false)
+
+  watch(currentSrc, (newSrc, oldSrc) => {
+    if (oldSrc && newSrc && newSrc !== oldSrc) {
+      previousSrc.value = oldSrc
+      showPrevious.value = true
+    }
+  })
+
+  watch(context.isLoaded, loaded => {
+    if (loaded && showPrevious.value) {
+      showPrevious.value = false
+    }
+  })
+
+  watch(context.status, (status, prev) => {
+    if (status === 'loading' && prev !== 'loading' && context.source.value) {
+      emit('loadstart', context.source.value)
+    }
+  }, { immediate: true })
+
+  function onLoad (e: Event) {
+    context.onLoad(e)
+    emit('load', e)
+  }
+
+  function onError (e: Event) {
+    context.onError(e)
+    emit('error', e)
+  }
+
+  function onPresenceLeave (e: Event, done: () => void) {
+    if ((e as TransitionEvent).propertyName === 'opacity') done()
+  }
+
+  const slotProps = toRef((): ImagePresenceSlotProps => ({
+    status: context.status.value,
+    isLoaded: context.isLoaded.value,
+    currentSrc: currentSrc.value,
+    previousSrc: previousSrc.value,
+    attrs: {
+      'data-state': context.status.value,
+    },
+  }))
+</script>
+
+<template>
+  <Atom
+    :as
+    class="relative"
+    :renderless
+    v-bind="slotProps.attrs"
+  >
+    <img
+      :alt
+      :class="[imgClass, 'transition-opacity opacity-0 data-[state=loaded]:opacity-100']"
+      :crossorigin
+      :data-state="context.status.value"
+      :decoding
+      :fetchpriority
+      :height
+      :loading
+      :referrerpolicy
+      role="img"
+      :sizes
+      :src="currentSrc"
+      :srcset
+      :width
+      @error="onError"
+      @load="onLoad"
+    >
+
+    <Presence v-slot="{ attrs: presenceAttrs, done }" v-model="showPrevious">
+      <img
+        v-bind="presenceAttrs"
+        :alt
+        aria-hidden="true"
+        :class="[imgClass, 'absolute inset-0 w-full h-full transition-opacity data-[state=leaving]:opacity-0']"
+        :crossorigin
+        :decoding
+        :height
+        :referrerpolicy
+        role="img"
+        :sizes
+        :src="previousSrc"
+        :srcset
+        :width
+        @transitionend="onPresenceLeave($event, done)"
+      >
+    </Presence>
+
+    <slot v-bind="slotProps" />
+  </Atom>
+</template>
diff --git a/packages/0/src/components/Image/index.test.ts b/packages/0/src/components/Image/index.test.ts
index 05091a3b2..5c7855d2a 100644
--- a/packages/0/src/components/Image/index.test.ts
+++ b/packages/0/src/components/Image/index.test.ts
@@ -471,5 +471,119 @@ describe('image', () => {
       expect(html).toBeTruthy()
       expect(html).toContain('img')
     })
+
+    it('should render Image.Presence to string without errors', async () => {
+      const app = createSSRApp(defineComponent({
+        render: () => h(Image.Root, { src: '/photo.jpg' }, () => [
+          h(Image.Presence, { alt: 'Test' }),
+        ]),
+      }))
+
+      const html = await renderToString(app)
+      expect(html).toBeTruthy()
+      expect(html).toContain('img')
+    })
+  })
+
+  describe('presence', () => {
+    it('should render the current source', () => {
+      const wrapper = mount(Image.Root, {
+        props: { src: '/a.jpg' },
+        slots: {
+          default: () => h(Image.Presence, { alt: 'Test' }),
+        },
+      })
+
+      const img = wrapper.find('img')
+      expect(img.attributes('src')).toBe('/a.jpg')
+    })
+
+    it('should render exactly one img while no previous exists', () => {
+      const wrapper = mount(Image.Root, {
+        props: { src: '/a.jpg' },
+        slots: {
+          default: () => h(Image.Presence, { alt: 'Test' }),
+        },
+      })
+
+      expect(wrapper.findAll('img')).toHaveLength(1)
+    })
+
+    it('should keep the previous img mounted while a new source loads', async () => {
+      const wrapper = mount(Image.Root, {
+        props: { src: '/a.jpg' },
+        slots: {
+          default: () => h(Image.Presence, { alt: 'Test' }),
+        },
+      })
+
+      // Load the first source
+      await wrapper.find('img').trigger('load')
+      await nextTick()
+
+      // Swap to a new source — previous should now be present
+      await wrapper.setProps({ src: '/b.jpg' })
+      await nextTick()
+
+      const imgs = wrapper.findAll('img')
+      expect(imgs).toHaveLength(2)
+      const srcs = imgs.map(i => i.attributes('src'))
+      expect(srcs).toContain('/a.jpg')
+      expect(srcs).toContain('/b.jpg')
+    })
+
+    it('should not add a previous layer on first load', async () => {
+      const wrapper = mount(Image.Root, {
+        props: { src: '/a.jpg' },
+        slots: {
+          default: () => h(Image.Presence, { alt: 'Test' }),
+        },
+      })
+
+      await wrapper.find('img').trigger('load')
+      await nextTick()
+
+      expect(wrapper.findAll('img')).toHaveLength(1)
+    })
+
+    it('should emit load event on image load', async () => {
+      const onLoad = vi.fn()
+      const wrapper = mount(Image.Root, {
+        props: { src: '/a.jpg' },
+        slots: {
+          default: () => h(Image.Presence, { alt: 'Test', onLoad }),
+        },
+      })
+
+      await wrapper.find('img').trigger('load')
+
+      expect(onLoad).toHaveBeenCalledTimes(1)
+    })
+
+    it('should emit error event on image error', async () => {
+      const onError = vi.fn()
+      const wrapper = mount(Image.Root, {
+        props: { src: '/a.jpg' },
+        slots: {
+          default: () => h(Image.Presence, { alt: 'Test', onError }),
+        },
+      })
+
+      await wrapper.find('img').trigger('error')
+
+      expect(onError).toHaveBeenCalledTimes(1)
+    })
+
+    it('should emit loadstart on initial mount', () => {
+      const onLoadstart = vi.fn()
+      mount(Image.Root, {
+        props: { src: '/a.jpg' },
+        slots: {
+          default: () => h(Image.Presence, { alt: 'Test', onLoadstart }),
+        },
+      })
+
+      expect(onLoadstart).toHaveBeenCalledWith('/a.jpg')
+    })
   })
 })
diff --git a/packages/0/src/components/Image/index.ts b/packages/0/src/components/Image/index.ts
index 96459a827..a62084514 100644
--- a/packages/0/src/components/Image/index.ts
+++ b/packages/0/src/components/Image/index.ts
@@ -1,6 +1,7 @@
 export { default as ImageFallback } from './ImageFallback.vue'
 export { default as ImageImg } from './ImageImg.vue'
 export { default as ImagePlaceholder } from './ImagePlaceholder.vue'
+export { default as ImagePresence } from './ImagePresence.vue'
 export { provideImageRoot, useImageRoot } from './ImageRoot.vue'
 
 export { default as ImageRoot } from './ImageRoot.vue'
@@ -8,12 +9,14 @@ export { default as ImageRoot } from './ImageRoot.vue'
 export type { ImageFallbackProps, ImageFallbackSlotProps } from './ImageFallback.vue'
 export type { ImageImgEmits, ImageImgProps, ImageImgSlotProps } from './ImageImg.vue'
 export type { ImagePlaceholderProps, ImagePlaceholderSlotProps } from './ImagePlaceholder.vue'
+export type { ImagePresenceEmits, ImagePresenceProps, ImagePresenceSlotProps } from './ImagePresence.vue'
 export type { ImageContext, ImageRootProps, ImageRootSlotProps } from './ImageRoot.vue'
 
 // Components
 import Fallback from './ImageFallback.vue'
 import Img from './ImageImg.vue'
 import Placeholder from './ImagePlaceholder.vue'
+import PresenceSub from './ImagePresence.vue'
 import Root from './ImageRoot.vue'
 
 /**
@@ -83,4 +86,20 @@ export const Image = {
    * ```
    */
   Fallback,
+  /**
+   * Source-transitioning image element. Keeps the previously loaded source
+   * visible while a new one loads, then crossfades via opacity. Drop-in
+   * replacement for `Image.Img` when navigating between already-loaded
+   * sources (carousels, galleries).
+   *
+   * @see https://0.vuetifyjs.com/components/semantic/image
+   *
+   * @example
+   * ```vue
+   * <Image.Root src="/photo-1.jpg">
+   *   <Image.Presence alt="Gallery photo" img-class="w-full h-full object-cover" />
+   * </Image.Root>
+   * ```
+   */
+  Presence: PresenceSub,
 }

From 3f43b67c4d67c40991b9c7fb88ea96d0d0d0b029 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Thu, 16 Apr 2026 18:42:24 -0500
Subject: [PATCH 15/35] fix(Image): defer Presence leaving flip by a frame so
 cached srcs crossfade
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cached images fire the load event fast enough that Vue batched the
showPrevious true→false flip into one reactive cycle, so CSS never
saw the 'mounted' state commit before 'leaving' — the transition
appeared to do nothing on the second and subsequent navigations.

Defer the flip via requestAnimationFrame (SSR-guarded) so the browser
paints the previous img at opacity 1 for at least one frame before the
data-state transitions to 'leaving' and the opacity fade animates.

Also tighten the currentSrc watcher to skip updating previousSrc while
a transition is in flight — rapid navigation through multiple sources
before any load completes now keeps the original previous visible
instead of flashing through intermediates.
---
 .../0/src/components/Image/ImagePresence.vue  | 29 ++++++++++++++-----
 1 file changed, 22 insertions(+), 7 deletions(-)

diff --git a/packages/0/src/components/Image/ImagePresence.vue b/packages/0/src/components/Image/ImagePresence.vue
index a197daea3..b2a19680f 100644
--- a/packages/0/src/components/Image/ImagePresence.vue
+++ b/packages/0/src/components/Image/ImagePresence.vue
@@ -19,6 +19,9 @@
  */
 
 <script lang="ts">
+  // Globals
+  import { IN_BROWSER } from '#v0/constants/globals'
+
   // Components
   import { Atom } from '#v0/components/Atom'
   import { Presence } from '#v0/components/Presence'
@@ -122,18 +125,16 @@
   const showPrevious = shallowRef(false)
 
   watch(currentSrc, (newSrc, oldSrc) => {
-    if (oldSrc && newSrc && newSrc !== oldSrc) {
+    // Only capture the previous source when no transition is in flight —
+    // navigating through several sources before any have loaded should
+    // keep the original previous visible rather than flashing through
+    // each intermediate URL.
+    if (oldSrc && newSrc && newSrc !== oldSrc && !showPrevious.value) {
       previousSrc.value = oldSrc
       showPrevious.value = true
     }
   })
 
-  watch(context.isLoaded, loaded => {
-    if (loaded && showPrevious.value) {
-      showPrevious.value = false
-    }
-  })
-
   watch(context.status, (status, prev) => {
     if (status === 'loading' && prev !== 'loading' && context.source.value) {
       emit('loadstart', context.source.value)
@@ -143,6 +144,20 @@
   function onLoad (e: Event) {
     context.onLoad(e)
     emit('load', e)
+
+    // Defer the leaving transition by one animation frame so the browser
+    // commits the previous img's "mounted" opacity before flipping to
+    // "leaving" — without this, cached images load fast enough that
+    // Vue batches the show/hide flip into a single render and CSS never
+    // sees an intermediate state to transition from.
+    if (!showPrevious.value) return
+    if (IN_BROWSER) {
+      requestAnimationFrame(() => {
+        showPrevious.value = false
+      })
+    } else {
+      showPrevious.value = false
+    }
   }
 
   function onError (e: Event) {

From 57b67339a385ae0870d9883ced770ec880836137 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Thu, 16 Apr 2026 19:46:16 -0500
Subject: [PATCH 16/35] docs(Image): add simulated load delay to the Presence
 gallery example

Picsum's cached responses return fast enough that the 150ms default
crossfade was nearly imperceptible and felt broken on repeat clicks.
A 1200ms setTimeout between button press and src update stands in for
a slow network, giving a clear window where the previous photo stays
visible before the new one crossfades in.

Also bumps the transition duration to 500ms so the crossfade itself
reads as an animation rather than a jump, and disables the Prev/Next
buttons during the delay so rapid clicks don't queue multiple
transitions.
---
 .../components/image/GalleryImage.vue         |  2 +-
 .../src/examples/components/image/gallery.vue | 36 ++++++++++++++-----
 2 files changed, 28 insertions(+), 10 deletions(-)

diff --git a/apps/docs/src/examples/components/image/GalleryImage.vue b/apps/docs/src/examples/components/image/GalleryImage.vue
index dc427d4b3..9a2856a05 100644
--- a/apps/docs/src/examples/components/image/GalleryImage.vue
+++ b/apps/docs/src/examples/components/image/GalleryImage.vue
@@ -15,7 +15,7 @@
     <Image.Presence
       :alt
       class="w-full h-full"
-      img-class="w-full h-full object-cover"
+      img-class="w-full h-full object-cover duration-500"
     />
 
     <Image.Placeholder class="absolute inset-0 flex items-center justify-center">
diff --git a/apps/docs/src/examples/components/image/gallery.vue b/apps/docs/src/examples/components/image/gallery.vue
index daa8d0bb9..90d9f56cb 100644
--- a/apps/docs/src/examples/components/image/gallery.vue
+++ b/apps/docs/src/examples/components/image/gallery.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
   import GalleryImage from './GalleryImage.vue'
-  import { shallowRef } from 'vue'
+  import { shallowRef, watch } from 'vue'
 
   const photos = [
     { id: 1, src: 'https://picsum.photos/seed/gallery-1/600/450', alt: 'Photo 1' },
@@ -9,10 +9,26 @@
     { id: 4, src: 'https://picsum.photos/seed/gallery-4/600/450', alt: 'Photo 4' },
   ]
 
+  // Simulated network delay so the transition is visible even when the
+  // browser has cached the response.
+  const DELAY_MS = 1200
+
   const index = shallowRef(0)
-  function current () {
-    return photos[index.value]!
-  }
+  const displayedSrc = shallowRef(photos[0]!.src)
+  const displayedAlt = shallowRef(photos[0]!.alt)
+  const pending = shallowRef(false)
+  let timer: ReturnType<typeof setTimeout> | undefined
+
+  watch(index, next => {
+    const target = photos[next]!
+    pending.value = true
+    if (timer) clearTimeout(timer)
+    timer = setTimeout(() => {
+      displayedSrc.value = target.src
+      displayedAlt.value = target.alt
+      pending.value = false
+    }, DELAY_MS)
+  })
 
   function onNext () {
     index.value = (index.value + 1) % photos.length
@@ -25,22 +41,24 @@
 
 <template>
   <div class="flex flex-col items-center gap-4 w-full max-w-lg mx-auto">
-    <GalleryImage :alt="current().alt" :src="current().src" />
+    <GalleryImage :alt="displayedAlt" :src="displayedSrc" />
 
     <div class="flex items-center gap-4">
       <button
-        class="px-3 py-1 bg-primary text-on-primary rounded text-sm"
+        class="px-3 py-1 bg-primary text-on-primary rounded text-sm disabled:opacity-50"
+        :disabled="pending"
         @click="onPrev"
       >
         Previous
       </button>
 
       <span class="text-sm text-on-surface-variant">
-        {{ index + 1 }} / {{ photos.length }}
+        {{ pending ? 'loading…' : `${index + 1} / ${photos.length}` }}
       </span>
 
       <button
-        class="px-3 py-1 bg-primary text-on-primary rounded text-sm"
+        class="px-3 py-1 bg-primary text-on-primary rounded text-sm disabled:opacity-50"
+        :disabled="pending"
         @click="onNext"
       >
         Next
@@ -48,7 +66,7 @@
     </div>
 
     <p class="text-xs text-on-surface-variant text-center max-w-md">
-      The previous photo stays on screen while the next loads — no flash to the placeholder between navigations.
+      A {{ DELAY_MS }}&thinsp;ms simulated delay stands in for a slow network. During the delay the previous photo stays on screen — no placeholder flash — and the next photo crossfades in once it loads.
     </p>
   </div>
 </template>

From 0bca9aa7759323f8b46eecd40787917d2c590f3b Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Thu, 16 Apr 2026 19:52:20 -0500
Subject: [PATCH 17/35] fix(Image): set immediate=false on Image.Presence's
 internal Presence
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

usePresence's immediate mode auto-resolves the leaving state on next
tick if done() isn't called first — much faster than any CSS transition
could complete. Explicitly set immediate=false so our transitionend
handler drives the exit via done().

Also refactors the Presence gallery example to render Image.Img and
Image.Presence side-by-side with shared navigation, so the behavioral
difference (placeholder flash vs crossfade) is directly observable.
---
 .../components/image/GalleryImage.vue         |  8 +++++
 .../src/examples/components/image/gallery.vue | 32 +++++++++++++++----
 .../0/src/components/Image/ImagePresence.vue  |  2 +-
 3 files changed, 34 insertions(+), 8 deletions(-)

diff --git a/apps/docs/src/examples/components/image/GalleryImage.vue b/apps/docs/src/examples/components/image/GalleryImage.vue
index 9a2856a05..2e54fd857 100644
--- a/apps/docs/src/examples/components/image/GalleryImage.vue
+++ b/apps/docs/src/examples/components/image/GalleryImage.vue
@@ -4,6 +4,7 @@
   defineProps<{
     src: string
     alt: string
+    mode: 'img' | 'presence'
   }>()
 </script>
 
@@ -12,7 +13,14 @@
     class="w-full aspect-4/3 bg-surface-tint rounded overflow-hidden relative"
     :src
   >
+    <Image.Img
+      v-if="mode === 'img'"
+      :alt
+      class="w-full h-full object-cover opacity-0 transition-opacity duration-500 data-[state=loaded]:opacity-100"
+    />
+
     <Image.Presence
+      v-else
       :alt
       class="w-full h-full"
       img-class="w-full h-full object-cover duration-500"
diff --git a/apps/docs/src/examples/components/image/gallery.vue b/apps/docs/src/examples/components/image/gallery.vue
index 90d9f56cb..c2d719649 100644
--- a/apps/docs/src/examples/components/image/gallery.vue
+++ b/apps/docs/src/examples/components/image/gallery.vue
@@ -9,8 +9,6 @@
     { id: 4, src: 'https://picsum.photos/seed/gallery-4/600/450', alt: 'Photo 4' },
   ]
 
-  // Simulated network delay so the transition is visible even when the
-  // browser has cached the response.
   const DELAY_MS = 1200
 
   const index = shallowRef(0)
@@ -40,10 +38,30 @@
 </script>
 
 <template>
-  <div class="flex flex-col items-center gap-4 w-full max-w-lg mx-auto">
-    <GalleryImage :alt="displayedAlt" :src="displayedSrc" />
+  <div class="flex flex-col gap-4 w-full max-w-4xl mx-auto">
+    <div class="grid grid-cols-1 sm:grid-cols-2 gap-4">
+      <div class="flex flex-col gap-2">
+        <span class="text-xs font-semibold text-on-surface-variant uppercase tracking-wide">
+          Image.Img
+        </span>
+        <GalleryImage :alt="displayedAlt" mode="img" :src="displayedSrc" />
+        <p class="text-xs text-on-surface-variant">
+          Flashes the placeholder between photos.
+        </p>
+      </div>
 
-    <div class="flex items-center gap-4">
+      <div class="flex flex-col gap-2">
+        <span class="text-xs font-semibold text-on-surface-variant uppercase tracking-wide">
+          Image.Presence
+        </span>
+        <GalleryImage :alt="displayedAlt" mode="presence" :src="displayedSrc" />
+        <p class="text-xs text-on-surface-variant">
+          Keeps the previous photo visible, then crossfades.
+        </p>
+      </div>
+    </div>
+
+    <div class="flex items-center justify-center gap-4">
       <button
         class="px-3 py-1 bg-primary text-on-primary rounded text-sm disabled:opacity-50"
         :disabled="pending"
@@ -65,8 +83,8 @@
       </button>
     </div>
 
-    <p class="text-xs text-on-surface-variant text-center max-w-md">
-      A {{ DELAY_MS }}&thinsp;ms simulated delay stands in for a slow network. During the delay the previous photo stays on screen — no placeholder flash — and the next photo crossfades in once it loads.
+    <p class="text-xs text-on-surface-variant text-center max-w-2xl mx-auto">
+      A {{ DELAY_MS }}&thinsp;ms simulated delay stands in for a slow network. Both panels receive the same src at the same moment — only the sub-component differs.
     </p>
   </div>
 </template>
diff --git a/packages/0/src/components/Image/ImagePresence.vue b/packages/0/src/components/Image/ImagePresence.vue
index b2a19680f..543b3a4ad 100644
--- a/packages/0/src/components/Image/ImagePresence.vue
+++ b/packages/0/src/components/Image/ImagePresence.vue
@@ -206,7 +206,7 @@
       @load="onLoad"
     >
 
-    <Presence v-slot="{ attrs: presenceAttrs, done }" v-model="showPrevious">
+    <Presence v-slot="{ attrs: presenceAttrs, done }" v-model="showPrevious" :immediate="false">
       <img
         v-bind="presenceAttrs"
         :alt

From f5a8bf53b4498cb7218df4a757318ab7e1980d1d Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Thu, 16 Apr 2026 20:41:53 -0500
Subject: [PATCH 18/35] refactor(Image): rename Image.Presence to Image.Swap
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Presence name borrowed from the underlying primitive but didn't
parallel Image.Img as a user-facing component name. Swap names the
action users pick the component for: swapping sources without a
placeholder flash. Doesn't imply a transition system — the component
stays narrowly scoped to this one UX concern.

- File renamed: ImagePresence.vue → ImageSwap.vue
- Types renamed: ImagePresence{Props,Emits,SlotProps} → ImageSwap*
- Compound member renamed: Image.Presence → Image.Swap
- Barrel, tests, docs page (Usage, Examples, Accessibility, FAQ),
  and the Gallery example all updated
- Mermaid diagram in the Examples block scrubs "Presence mounts"
  wording that conflated the sub-component with the underlying
  primitive — the Presence composable is still used internally
  and still referenced by name where that's the actual mechanism
---
 .../components/image/GalleryImage.vue         |  4 +--
 .../src/examples/components/image/gallery.vue |  4 +--
 .../components/primitives/aspect-ratio.md     |  4 +--
 .../src/pages/components/semantic/image.md    | 28 +++++++--------
 .../{ImagePresence.vue => ImageSwap.vue}      | 34 ++++++++-----------
 packages/0/src/components/Image/index.test.ts | 20 +++++------
 packages/0/src/components/Image/index.ts      | 12 +++----
 7 files changed, 50 insertions(+), 56 deletions(-)
 rename packages/0/src/components/Image/{ImagePresence.vue => ImageSwap.vue} (84%)

diff --git a/apps/docs/src/examples/components/image/GalleryImage.vue b/apps/docs/src/examples/components/image/GalleryImage.vue
index 2e54fd857..9385be168 100644
--- a/apps/docs/src/examples/components/image/GalleryImage.vue
+++ b/apps/docs/src/examples/components/image/GalleryImage.vue
@@ -4,7 +4,7 @@
   defineProps<{
     src: string
     alt: string
-    mode: 'img' | 'presence'
+    mode: 'img' | 'swap'
   }>()
 </script>
 
@@ -19,7 +19,7 @@
       class="w-full h-full object-cover opacity-0 transition-opacity duration-500 data-[state=loaded]:opacity-100"
     />
 
-    <Image.Presence
+    <Image.Swap
       v-else
       :alt
       class="w-full h-full"
diff --git a/apps/docs/src/examples/components/image/gallery.vue b/apps/docs/src/examples/components/image/gallery.vue
index c2d719649..19b8c7291 100644
--- a/apps/docs/src/examples/components/image/gallery.vue
+++ b/apps/docs/src/examples/components/image/gallery.vue
@@ -52,9 +52,9 @@
 
       <div class="flex flex-col gap-2">
         <span class="text-xs font-semibold text-on-surface-variant uppercase tracking-wide">
-          Image.Presence
+          Image.Swap
         </span>
-        <GalleryImage :alt="displayedAlt" mode="presence" :src="displayedSrc" />
+        <GalleryImage :alt="displayedAlt" mode="swap" :src="displayedSrc" />
         <p class="text-xs text-on-surface-variant">
           Keeps the previous photo visible, then crossfades.
         </p>
diff --git a/apps/docs/src/pages/components/primitives/aspect-ratio.md b/apps/docs/src/pages/components/primitives/aspect-ratio.md
index 5f22c75e7..7f30e8147 100644
--- a/apps/docs/src/pages/components/primitives/aspect-ratio.md
+++ b/apps/docs/src/pages/components/primitives/aspect-ratio.md
@@ -39,9 +39,7 @@ reserved frame — pair with `w-full h-full` or absolute positioning.
 </script>
 
 <template>
-  <AspectRatio :ratio="16 / 9">
-    <!-- content -->
-  </AspectRatio>
+  <AspectRatio />
 </template>
 ```
 
diff --git a/apps/docs/src/pages/components/semantic/image.md b/apps/docs/src/pages/components/semantic/image.md
index 4f87076bb..ff318e0ed 100644
--- a/apps/docs/src/pages/components/semantic/image.md
+++ b/apps/docs/src/pages/components/semantic/image.md
@@ -25,7 +25,7 @@ Headless image component with state-driven placeholder and error fallback. Track
 
 ## Usage
 
-`Image.Root` owns the loading state machine via `useImage`. `Image.Img` renders the image element and reports load and error events to the context. `Image.Placeholder` is shown while idle or loading; `Image.Fallback` is shown on error. `Image.Presence` is a drop-in alternative to `Image.Img` that crossfades between sources when `src` changes — see the [gallery example](#gallery-navigation-with-image-presence).
+`Image.Root` owns the loading state machine via `useImage`. `Image.Img` renders the image element and reports load and error events to the context. `Image.Placeholder` is shown while idle or loading; `Image.Fallback` is shown on error. `Image.Swap` is a drop-in alternative to `Image.Img` that crossfades between sources when `src` changes — see the [gallery example](#gallery-navigation-with-image-swap).
 
 ::: example
 /components/image/basic
@@ -145,29 +145,29 @@ The `<source>` children are fully browser-driven — `Image.Img` never sees thei
 /components/image/GalleryImage.vue 1
 /components/image/gallery.vue 2
 
-### Gallery navigation with Image.Presence
+### Gallery navigation with Image.Swap
 
-Swap `Image.Img` for `Image.Presence` when navigating between already-loaded sources should never flash the placeholder. The component renders two stacked `<img>` elements: the newly loaded one fades in while the previous one fades out at the same tempo. Until the new source loads, the old image stays on screen — the user never sees blank space between photos.
+Use `Image.Swap` instead of `Image.Img` when navigating between already-loaded sources should never flash the placeholder. The component renders two stacked `<img>` elements: the newly loaded one fades in while the previous one fades out at the same tempo. Until the new source loads, the old image stays on screen — the user never sees blank space between photos.
 
 ```mermaid "Source transition"
 flowchart LR
   Change["src changes<br/>(Root.src = newUrl)"]
   Capture["previousSrc ← oldUrl<br/>showPrevious = true"]
-  Mount["Presence mounts<br/>the previous img<br/>at opacity 1"]
-  Load["New img loads"]
-  Leave["showPrevious = false<br/>Presence enters leaving"]
-  Fade["Crossfade:<br/>previous opacity 1 → 0<br/>current opacity 0 → 1"]
+  Mount["previous img<br/>mounts at opacity 1"]
+  Load["new img loads"]
+  Leave["showPrevious = false<br/>previous enters leaving"]
+  Fade["crossfade:<br/>previous opacity 1 → 0<br/>current opacity 0 → 1"]
   Unmount["transitionend<br/>done() fires<br/>previous unmounts"]
 
   Change --> Capture --> Mount --> Load --> Leave --> Fade --> Unmount
 ```
 
-Reach for this pattern whenever the user can navigate between preloaded sources — image galleries, photo viewers, product thumbnails reacting to a color picker, or anywhere a `v-model` drives `src`. Without `Image.Presence`, each navigation resets the state machine to `loading`; the old image disappears from the DOM and the placeholder shows until the next image loads, producing a visible pop. `Image.Presence` holds the previous image in DOM through the load window, so the transition stays continuous.
+Reach for this pattern whenever the user can navigate between preloaded sources — image galleries, photo viewers, product thumbnails reacting to a color picker, or anywhere a `v-model` drives `src`. Without `Image.Swap`, each navigation resets the state machine to `loading`; the old image disappears from the DOM and the placeholder shows until the next image loads, producing a visible pop. `Image.Swap` holds the previous image in DOM through the load window, so the transition stays continuous.
 
 A few details worth knowing:
 
 - **Initial mount behaves like `Image.Img`** — there's no previous source on first load, so the component renders a single `<img>` and the placeholder shows while it loads. Only *subsequent* src changes engage the crossfade.
-- **Built on `Presence` internally** — the previous layer's lifecycle (mounted → leaving → unmounted) is driven by the `Presence` primitive. CSS targets `data-state='leaving'` to fade opacity 1 → 0, and the `transitionend` event triggers `done()` to finalize the unmount. No `setTimeout`, no manual cleanup.
+- **Built on the Presence primitive** — the previous layer's mount lifecycle (mounted → leaving → unmounted) is managed by v0's `Presence` composable. CSS targets `data-state='leaving'` to fade opacity 1 → 0, and the `transitionend` event triggers `done()` to finalize the unmount. No `setTimeout`, no manual cleanup.
 - **`img-class` vs `class`** — `class` goes on the wrapper `<div>` (layout, size, border-radius), while `img-class` applies to both inner `<img>` elements (object-fit, filters). This split is necessary because the wrapper coordinates two imgs via `position: relative`.
 - **Error state** — if the new image errors, the old one stays visible underneath and `Image.Fallback` overlays as usual. Call `retry()` from the Root slot props or the Fallback slot props to re-attempt the same source.
 
@@ -175,8 +175,8 @@ Not a replacement for `Image.Img` in every case — if you don't need cross-src
 
 | File | Role |
 |------|------|
-| `GalleryImage.vue` | Reusable wrapper — `Image.Root` with `Image.Presence`, `Image.Placeholder`, and `Image.Fallback` overlays |
-| `gallery.vue` | Entry point with Previous/Next navigation cycling through four sources to demonstrate the continuous transition |
+| `GalleryImage.vue` | Reusable wrapper — `Image.Root` rendered twice, once with `Image.Img` and once with `Image.Swap`, plus shared `Image.Placeholder` and `Image.Fallback` overlays |
+| `gallery.vue` | Entry point with Previous/Next navigation and a simulated load delay to make the crossfade visible |
 
 :::
 
@@ -246,7 +246,7 @@ Slot props (`status`, `isLoaded`, etc.) remain available for the rare cases wher
 | Element | ARIA / behavior |
 | - | - |
 | `Image.Img` | `role="img"`, accepts `alt` for accessible name |
-| `Image.Presence` | Current `<img>` is the accessible image; the transitioning previous `<img>` is marked `aria-hidden="true"` so screen readers only announce the active source |
+| `Image.Swap` | Current `<img>` is the accessible image; the transitioning previous `<img>` is marked `aria-hidden="true"` so screen readers only announce the active source |
 | `Image.Placeholder` | `aria-hidden="true"` — placeholder is decorative |
 | `Image.Fallback` | `role="img"` — provide alternate text inside the slot |
 
@@ -272,9 +272,9 @@ Always set `width` and `height` on `Image.Img`. The browser uses these to reserv
 
 Yes — set `renderless` on both `Image.Root` and `Image.Img`, then compose them inside a native `<picture>` element. See the picture example.
 
-??? When should I use `Image.Presence` instead of `Image.Img`?
+??? When should I use `Image.Swap` instead of `Image.Img`?
 
-Use `Image.Presence` when the `src` on `Image.Root` can change to a different URL *after* the first image has loaded, and you want to avoid flashing the placeholder between transitions — gallery navigation, product variant thumbnails, anywhere a `v-model` drives `src`. `Image.Img` is the right choice for single-source content images where `src` never changes (or only changes via a full component remount).
+Use `Image.Swap` when the `src` on `Image.Root` can change to a different URL *after* the first image has loaded, and you want to avoid flashing the placeholder between transitions — gallery navigation, product variant thumbnails, anywhere a `v-model` drives `src`. `Image.Img` is the right choice for single-source content images where `src` never changes (or only changes via a full component remount). Pick one per `Image.Root` — the two sub-components aren't designed to coexist.
 
 ??? How do I fade in once the image loads?
 
diff --git a/packages/0/src/components/Image/ImagePresence.vue b/packages/0/src/components/Image/ImageSwap.vue
similarity index 84%
rename from packages/0/src/components/Image/ImagePresence.vue
rename to packages/0/src/components/Image/ImageSwap.vue
index 543b3a4ad..30a51f54a 100644
--- a/packages/0/src/components/Image/ImagePresence.vue
+++ b/packages/0/src/components/Image/ImageSwap.vue
@@ -1,21 +1,17 @@
 /**
- * @module ImagePresence
+ * @module ImageSwap
  *
  * @see https://0.vuetifyjs.com/components/semantic/image
  *
  * @remarks
- * Source-transitioning image element. Keeps the previously loaded source
- * visible while a new one loads, then crossfades between them via opacity.
- * Uses the Presence primitive to manage the mount lifecycle of the previous
- * layer — its data-state drives the exit transition.
+ * Source-swapping image element. Keeps the previously loaded source visible
+ * while a new one loads, then crossfades between them via opacity. Prevents
+ * the placeholder flash that occurs with Image.Img when navigating between
+ * already-loaded sources (carousels, galleries, next/previous UX).
  *
- * Replaces Image.Img when you want seamless transitions between already-
- * loaded sources (carousels, galleries, next/previous navigation). On the
+ * Uses the Presence primitive internally to manage the mount lifecycle of
+ * the previous layer — data-state drives the exit transition. On the
  * initial load, behaves identically to Image.Img.
- *
- * API note: despite sharing the name, Image.Presence is not driven by a
- * v-model boolean like the top-level Presence primitive — its lifecycle is
- * triggered implicitly by src changes on Image.Root.
  */
 
 <script lang="ts">
@@ -36,7 +32,7 @@
   import type { AtomProps } from '#v0/components/Atom'
   import type { ImageStatus } from '#v0/composables/useImage'
 
-  export interface ImagePresenceProps extends AtomProps {
+  export interface ImageSwapProps extends AtomProps {
     /** Accessible alt text applied to both the current and previous image layers. */
     alt?: string
     /** Responsive image candidates. */
@@ -71,13 +67,13 @@
     namespace?: string
   }
 
-  export interface ImagePresenceEmits {
+  export interface ImageSwapEmits {
     load: [e: Event]
     error: [e: Event]
     loadstart: [src: string]
   }
 
-  export interface ImagePresenceSlotProps {
+  export interface ImageSwapSlotProps {
     /** Current loading status. */
     status: ImageStatus
     /** Whether the current source has loaded. */
@@ -94,10 +90,10 @@
 </script>
 
 <script setup lang="ts">
-  defineOptions({ name: 'ImagePresence' })
+  defineOptions({ name: 'ImageSwap' })
 
   defineSlots<{
-    default: (props: ImagePresenceSlotProps) => any
+    default: (props: ImageSwapSlotProps) => any
   }>()
 
   const {
@@ -115,9 +111,9 @@
     fetchpriority,
     imgClass,
     namespace = 'v0:image',
-  } = defineProps<ImagePresenceProps>()
+  } = defineProps<ImageSwapProps>()
 
-  const emit = defineEmits<ImagePresenceEmits>()
+  const emit = defineEmits<ImageSwapEmits>()
 
   const context = useImageRoot(namespace)
   const currentSrc = toRef(() => context.source.value)
@@ -169,7 +165,7 @@
     if ((e as TransitionEvent).propertyName === 'opacity') done()
   }
 
-  const slotProps = toRef((): ImagePresenceSlotProps => ({
+  const slotProps = toRef((): ImageSwapSlotProps => ({
     status: context.status.value,
     isLoaded: context.isLoaded.value,
     currentSrc: currentSrc.value,
diff --git a/packages/0/src/components/Image/index.test.ts b/packages/0/src/components/Image/index.test.ts
index 5c7855d2a..3aac70af1 100644
--- a/packages/0/src/components/Image/index.test.ts
+++ b/packages/0/src/components/Image/index.test.ts
@@ -472,10 +472,10 @@ describe('image', () => {
       expect(html).toContain('img')
     })
 
-    it('should render Image.Presence to string without errors', async () => {
+    it('should render Image.Swap to string without errors', async () => {
       const app = createSSRApp(defineComponent({
         render: () => h(Image.Root, { src: '/photo.jpg' }, () => [
-          h(Image.Presence, { alt: 'Test' }),
+          h(Image.Swap, { alt: 'Test' }),
         ]),
       }))
 
@@ -485,12 +485,12 @@ describe('image', () => {
     })
   })
 
-  describe('presence', () => {
+  describe('swap', () => {
     it('should render the current source', () => {
       const wrapper = mount(Image.Root, {
         props: { src: '/a.jpg' },
         slots: {
-          default: () => h(Image.Presence, { alt: 'Test' }),
+          default: () => h(Image.Swap, { alt: 'Test' }),
         },
       })
 
@@ -502,7 +502,7 @@ describe('image', () => {
       const wrapper = mount(Image.Root, {
         props: { src: '/a.jpg' },
         slots: {
-          default: () => h(Image.Presence, { alt: 'Test' }),
+          default: () => h(Image.Swap, { alt: 'Test' }),
         },
       })
 
@@ -513,7 +513,7 @@ describe('image', () => {
       const wrapper = mount(Image.Root, {
         props: { src: '/a.jpg' },
         slots: {
-          default: () => h(Image.Presence, { alt: 'Test' }),
+          default: () => h(Image.Swap, { alt: 'Test' }),
         },
       })
 
@@ -536,7 +536,7 @@ describe('image', () => {
       const wrapper = mount(Image.Root, {
         props: { src: '/a.jpg' },
         slots: {
-          default: () => h(Image.Presence, { alt: 'Test' }),
+          default: () => h(Image.Swap, { alt: 'Test' }),
         },
       })
 
@@ -551,7 +551,7 @@ describe('image', () => {
       const wrapper = mount(Image.Root, {
         props: { src: '/a.jpg' },
         slots: {
-          default: () => h(Image.Presence, { alt: 'Test', onLoad }),
+          default: () => h(Image.Swap, { alt: 'Test', onLoad }),
         },
       })
 
@@ -565,7 +565,7 @@ describe('image', () => {
       const wrapper = mount(Image.Root, {
         props: { src: '/a.jpg' },
         slots: {
-          default: () => h(Image.Presence, { alt: 'Test', onError }),
+          default: () => h(Image.Swap, { alt: 'Test', onError }),
         },
       })
 
@@ -579,7 +579,7 @@ describe('image', () => {
       mount(Image.Root, {
         props: { src: '/a.jpg' },
         slots: {
-          default: () => h(Image.Presence, { alt: 'Test', onLoadstart }),
+          default: () => h(Image.Swap, { alt: 'Test', onLoadstart }),
         },
       })
 
diff --git a/packages/0/src/components/Image/index.ts b/packages/0/src/components/Image/index.ts
index a62084514..d23422a12 100644
--- a/packages/0/src/components/Image/index.ts
+++ b/packages/0/src/components/Image/index.ts
@@ -1,7 +1,7 @@
 export { default as ImageFallback } from './ImageFallback.vue'
 export { default as ImageImg } from './ImageImg.vue'
 export { default as ImagePlaceholder } from './ImagePlaceholder.vue'
-export { default as ImagePresence } from './ImagePresence.vue'
+export { default as ImageSwap } from './ImageSwap.vue'
 export { provideImageRoot, useImageRoot } from './ImageRoot.vue'
 
 export { default as ImageRoot } from './ImageRoot.vue'
@@ -9,15 +9,15 @@ export { default as ImageRoot } from './ImageRoot.vue'
 export type { ImageFallbackProps, ImageFallbackSlotProps } from './ImageFallback.vue'
 export type { ImageImgEmits, ImageImgProps, ImageImgSlotProps } from './ImageImg.vue'
 export type { ImagePlaceholderProps, ImagePlaceholderSlotProps } from './ImagePlaceholder.vue'
-export type { ImagePresenceEmits, ImagePresenceProps, ImagePresenceSlotProps } from './ImagePresence.vue'
+export type { ImageSwapEmits, ImageSwapProps, ImageSwapSlotProps } from './ImageSwap.vue'
 export type { ImageContext, ImageRootProps, ImageRootSlotProps } from './ImageRoot.vue'
 
 // Components
 import Fallback from './ImageFallback.vue'
 import Img from './ImageImg.vue'
 import Placeholder from './ImagePlaceholder.vue'
-import PresenceSub from './ImagePresence.vue'
 import Root from './ImageRoot.vue'
+import Swap from './ImageSwap.vue'
 
 /**
  * Image component with sub-components for managing image loading lifecycle.
@@ -87,7 +87,7 @@ export const Image = {
    */
   Fallback,
   /**
-   * Source-transitioning image element. Keeps the previously loaded source
+   * Source-swapping image element. Keeps the previously loaded source
    * visible while a new one loads, then crossfades via opacity. Drop-in
    * replacement for `Image.Img` when navigating between already-loaded
    * sources (carousels, galleries).
@@ -97,9 +97,9 @@ export const Image = {
    * @example
    * ```vue
    * <Image.Root src="/photo-1.jpg">
-   *   <Image.Presence alt="Gallery photo" img-class="w-full h-full object-cover" />
+   *   <Image.Swap alt="Gallery photo" img-class="w-full h-full object-cover" />
    * </Image.Root>
    * ```
    */
-  Presence: PresenceSub,
+  Swap,
 }

From 76aecd45b20bad296126f13eea5fa5b7dd4c1d4f Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Thu, 16 Apr 2026 21:00:24 -0500
Subject: [PATCH 19/35] docs(Image): remove simulated network delay from
 gallery example

---
 .../src/examples/components/image/gallery.vue | 38 +++++--------------
 1 file changed, 9 insertions(+), 29 deletions(-)

diff --git a/apps/docs/src/examples/components/image/gallery.vue b/apps/docs/src/examples/components/image/gallery.vue
index 19b8c7291..6d4e2e7d4 100644
--- a/apps/docs/src/examples/components/image/gallery.vue
+++ b/apps/docs/src/examples/components/image/gallery.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
   import GalleryImage from './GalleryImage.vue'
-  import { shallowRef, watch } from 'vue'
+  import { shallowRef } from 'vue'
 
   const photos = [
     { id: 1, src: 'https://picsum.photos/seed/gallery-1/600/450', alt: 'Photo 1' },
@@ -9,24 +9,10 @@
     { id: 4, src: 'https://picsum.photos/seed/gallery-4/600/450', alt: 'Photo 4' },
   ]
 
-  const DELAY_MS = 1200
-
   const index = shallowRef(0)
-  const displayedSrc = shallowRef(photos[0]!.src)
-  const displayedAlt = shallowRef(photos[0]!.alt)
-  const pending = shallowRef(false)
-  let timer: ReturnType<typeof setTimeout> | undefined
-
-  watch(index, next => {
-    const target = photos[next]!
-    pending.value = true
-    if (timer) clearTimeout(timer)
-    timer = setTimeout(() => {
-      displayedSrc.value = target.src
-      displayedAlt.value = target.alt
-      pending.value = false
-    }, DELAY_MS)
-  })
+  function current () {
+    return photos[index.value]!
+  }
 
   function onNext () {
     index.value = (index.value + 1) % photos.length
@@ -44,7 +30,7 @@
         <span class="text-xs font-semibold text-on-surface-variant uppercase tracking-wide">
           Image.Img
         </span>
-        <GalleryImage :alt="displayedAlt" mode="img" :src="displayedSrc" />
+        <GalleryImage :alt="current().alt" mode="img" :src="current().src" />
         <p class="text-xs text-on-surface-variant">
           Flashes the placeholder between photos.
         </p>
@@ -54,7 +40,7 @@
         <span class="text-xs font-semibold text-on-surface-variant uppercase tracking-wide">
           Image.Swap
         </span>
-        <GalleryImage :alt="displayedAlt" mode="swap" :src="displayedSrc" />
+        <GalleryImage :alt="current().alt" mode="swap" :src="current().src" />
         <p class="text-xs text-on-surface-variant">
           Keeps the previous photo visible, then crossfades.
         </p>
@@ -63,28 +49,22 @@
 
     <div class="flex items-center justify-center gap-4">
       <button
-        class="px-3 py-1 bg-primary text-on-primary rounded text-sm disabled:opacity-50"
-        :disabled="pending"
+        class="px-3 py-1 bg-primary text-on-primary rounded text-sm"
         @click="onPrev"
       >
         Previous
       </button>
 
       <span class="text-sm text-on-surface-variant">
-        {{ pending ? 'loading…' : `${index + 1} / ${photos.length}` }}
+        {{ index + 1 }} / {{ photos.length }}
       </span>
 
       <button
-        class="px-3 py-1 bg-primary text-on-primary rounded text-sm disabled:opacity-50"
-        :disabled="pending"
+        class="px-3 py-1 bg-primary text-on-primary rounded text-sm"
         @click="onNext"
       >
         Next
       </button>
     </div>
-
-    <p class="text-xs text-on-surface-variant text-center max-w-2xl mx-auto">
-      A {{ DELAY_MS }}&thinsp;ms simulated delay stands in for a slow network. Both panels receive the same src at the same moment — only the sub-component differs.
-    </p>
   </div>
 </template>

From 5effe9f03a514df6fe1859f18b0a3eeb7ef4d360 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Thu, 16 Apr 2026 21:04:36 -0500
Subject: [PATCH 20/35] fix(Image): hold Image.Swap's current img at opacity 1
 during swaps
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Data-state-driven opacity caused a brief flicker when swapping to a
cached source: status flipped 'loaded' → 'loading' for just long
enough to start a 1 → 0 opacity transition before the load event
fired and reversed it back toward 1. Previous layer covered the
visual, but once it started fading out the flicker leaked through.

Drive the current img's opacity from (showPrevious || isLoaded)
instead of data-state alone. While a previous layer is mounted, the
current img stays at opacity 1 — its visibility doesn't matter
(blocked by previous), so there's no incentive to transition. Initial
load still fades in via placeholder + isLoaded.
---
 packages/0/src/components/Image/ImageSwap.vue | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/packages/0/src/components/Image/ImageSwap.vue b/packages/0/src/components/Image/ImageSwap.vue
index 30a51f54a..c01922ce4 100644
--- a/packages/0/src/components/Image/ImageSwap.vue
+++ b/packages/0/src/components/Image/ImageSwap.vue
@@ -185,7 +185,11 @@
   >
     <img
       :alt
-      :class="[imgClass, 'transition-opacity opacity-0 data-[state=loaded]:opacity-100']"
+      :class="[
+        imgClass,
+        'transition-opacity',
+        showPrevious || context.isLoaded.value ? 'opacity-100' : 'opacity-0',
+      ]"
       :crossorigin
       :data-state="context.status.value"
       :decoding

From 641796af91e11434b9b90dd140c33c7e9d0fa421 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Thu, 16 Apr 2026 21:29:58 -0500
Subject: [PATCH 21/35] refactor(Image): strip styling from Image.Swap, keep it
 headless
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Opinionated utility classes (relative, absolute inset-0, transition-
opacity, data-[state=leaving]:opacity-0, the has-previous flicker-
guard conditional) had leaked into the component template. v0 owns
behavior and data-state; visual CSS belongs to the consumer.

- Only structural CSS remains, inlined via :style: position: relative
  on the wrapper, absolute + inset + 100% size on the previous layer.
  These aren't stylistic — they're required for two imgs to overlay.
- Opacity, transitions, and timing move entirely to user CSS. Three
  class props let users target each layer without fighting selector
  disambiguation: img-class (shared), current-class, previous-class.
- Current img exposes data-has-previous="true" while a swap is in
  flight — the flicker guard from before, now pure data contract, so
  user CSS can pin opacity with data-[has-previous]:opacity-100.
- Slot props gain hasPrevious to match, for consumers styling via
  slot bindings instead of classes.
- GalleryImage example updated to demonstrate the expected user CSS
  split across the three class props. Docs "Class routing" bullet
  rewritten to reflect the new contract.
---
 .../components/image/GalleryImage.vue         |  5 ++--
 .../src/pages/components/semantic/image.md    |  2 +-
 packages/0/src/components/Image/ImageSwap.vue | 23 ++++++++++++-------
 3 files changed, 19 insertions(+), 11 deletions(-)

diff --git a/apps/docs/src/examples/components/image/GalleryImage.vue b/apps/docs/src/examples/components/image/GalleryImage.vue
index 9385be168..333a306c7 100644
--- a/apps/docs/src/examples/components/image/GalleryImage.vue
+++ b/apps/docs/src/examples/components/image/GalleryImage.vue
@@ -22,8 +22,9 @@
     <Image.Swap
       v-else
       :alt
-      class="w-full h-full"
-      img-class="w-full h-full object-cover duration-500"
+      current-class="opacity-0 transition-opacity duration-500 data-[state=loaded]:opacity-100 data-[has-previous]:opacity-100"
+      img-class="w-full h-full object-cover"
+      previous-class="transition-opacity duration-500 data-[state=leaving]:opacity-0"
     />
 
     <Image.Placeholder class="absolute inset-0 flex items-center justify-center">
diff --git a/apps/docs/src/pages/components/semantic/image.md b/apps/docs/src/pages/components/semantic/image.md
index ff318e0ed..6540b713d 100644
--- a/apps/docs/src/pages/components/semantic/image.md
+++ b/apps/docs/src/pages/components/semantic/image.md
@@ -168,7 +168,7 @@ A few details worth knowing:
 
 - **Initial mount behaves like `Image.Img`** — there's no previous source on first load, so the component renders a single `<img>` and the placeholder shows while it loads. Only *subsequent* src changes engage the crossfade.
 - **Built on the Presence primitive** — the previous layer's mount lifecycle (mounted → leaving → unmounted) is managed by v0's `Presence` composable. CSS targets `data-state='leaving'` to fade opacity 1 → 0, and the `transitionend` event triggers `done()` to finalize the unmount. No `setTimeout`, no manual cleanup.
-- **`img-class` vs `class`** — `class` goes on the wrapper `<div>` (layout, size, border-radius), while `img-class` applies to both inner `<img>` elements (object-fit, filters). This split is necessary because the wrapper coordinates two imgs via `position: relative`.
+- **Class routing** — `class` goes on the wrapper `<div>` (layout, border-radius). `img-class` applies to both inner `<img>` elements (object-fit, sizing). `current-class` and `previous-class` target the individual layers — this is where transition/opacity rules live. The component ships no opinionated styling: you write the fade behavior against `data-state`, `data-has-previous` (on current while a swap is in flight), and Presence's `data-[state=leaving]` (on previous during exit).
 - **Error state** — if the new image errors, the old one stays visible underneath and `Image.Fallback` overlays as usual. Call `retry()` from the Root slot props or the Fallback slot props to re-attempt the same source.
 
 Not a replacement for `Image.Img` in every case — if you don't need cross-src transitions (single content image, hero banner, avatars), stick with `Image.Img` for the simpler DOM.
diff --git a/packages/0/src/components/Image/ImageSwap.vue b/packages/0/src/components/Image/ImageSwap.vue
index c01922ce4..d912698b6 100644
--- a/packages/0/src/components/Image/ImageSwap.vue
+++ b/packages/0/src/components/Image/ImageSwap.vue
@@ -61,8 +61,12 @@
     loading?: 'eager' | 'lazy'
     /** Resource priority hint. */
     fetchpriority?: 'high' | 'low' | 'auto'
-    /** Class applied to both inner image elements. */
+    /** Class applied to both inner image elements (shared layout, object-fit, etc.). */
     imgClass?: string | string[] | Record<string, boolean>
+    /** Class applied to the current image layer only. */
+    currentClass?: string | string[] | Record<string, boolean>
+    /** Class applied to the previous image layer only (during a swap). */
+    previousClass?: string | string[] | Record<string, boolean>
     /** Namespace for retrieving the Image context. */
     namespace?: string
   }
@@ -78,6 +82,8 @@
     status: ImageStatus
     /** Whether the current source has loaded. */
     isLoaded: boolean
+    /** Whether a previous source is currently mounted (a swap is in flight). */
+    hasPrevious: boolean
     /** The active source URL (from Image.Root context). */
     currentSrc: string | undefined
     /** The last successfully loaded source, or undefined on first load. */
@@ -110,6 +116,8 @@
     loading,
     fetchpriority,
     imgClass,
+    currentClass,
+    previousClass,
     namespace = 'v0:image',
   } = defineProps<ImageSwapProps>()
 
@@ -168,6 +176,7 @@
   const slotProps = toRef((): ImageSwapSlotProps => ({
     status: context.status.value,
     isLoaded: context.isLoaded.value,
+    hasPrevious: showPrevious.value,
     currentSrc: currentSrc.value,
     previousSrc: previousSrc.value,
     attrs: {
@@ -179,18 +188,15 @@
 <template>
   <Atom
     :as
-    class="relative"
     :renderless
+    :style="{ position: 'relative' }"
     v-bind="slotProps.attrs"
   >
     <img
       :alt
-      :class="[
-        imgClass,
-        'transition-opacity',
-        showPrevious || context.isLoaded.value ? 'opacity-100' : 'opacity-0',
-      ]"
+      :class="[imgClass, currentClass]"
       :crossorigin
+      :data-has-previous="showPrevious || undefined"
       :data-state="context.status.value"
       :decoding
       :fetchpriority
@@ -211,7 +217,7 @@
         v-bind="presenceAttrs"
         :alt
         aria-hidden="true"
-        :class="[imgClass, 'absolute inset-0 w-full h-full transition-opacity data-[state=leaving]:opacity-0']"
+        :class="[imgClass, previousClass]"
         :crossorigin
         :decoding
         :height
@@ -220,6 +226,7 @@
         :sizes
         :src="previousSrc"
         :srcset
+        :style="{ position: 'absolute', inset: 0, width: '100%', height: '100%' }"
         :width
         @transitionend="onPresenceLeave($event, done)"
       >

From 278030f3ca0d90be17b56fb1da2955e557887c66 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Fri, 17 Apr 2026 12:24:14 -0500
Subject: [PATCH 22/35] fix(Image): close Image.Swap contract gaps from code
 review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Broaden ImageSwap's transitionend handler to finalize done() on any
  property, not just opacity. Previously the previous layer leaked
  permanently if a consumer wrote a non-opacity transition on
  previous-class. Docs now call out that previous-class must include
  at least one transition for the exit to resolve.
- Clarify in the docs that data-[has-previous]:opacity-100 on
  current-class is not optional — without it, the crossfade shows a
  background bleed-through during the 0→1 fade-in. Updated the Class
  routing bullet and added a dedicated bullet spelling out the pin
  as required.
- Add a code comment in ImageSwap's currentSrc watcher explaining the
  cleared-then-restored-src edge case so a future reader sees the
  intentional trade-off.
- Rename test describe block 'sSR' → 'SSR' (auto-capitalization tripped
  the Vitest reporter output).
---
 apps/docs/src/pages/components/semantic/image.md |  4 +++-
 packages/0/src/components/Image/ImageSwap.vue    | 12 +++++++++---
 packages/0/src/components/Image/index.test.ts    |  2 +-
 3 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/apps/docs/src/pages/components/semantic/image.md b/apps/docs/src/pages/components/semantic/image.md
index 6540b713d..e57ca0694 100644
--- a/apps/docs/src/pages/components/semantic/image.md
+++ b/apps/docs/src/pages/components/semantic/image.md
@@ -167,8 +167,10 @@ Reach for this pattern whenever the user can navigate between preloaded sources
 A few details worth knowing:
 
 - **Initial mount behaves like `Image.Img`** — there's no previous source on first load, so the component renders a single `<img>` and the placeholder shows while it loads. Only *subsequent* src changes engage the crossfade.
-- **Built on the Presence primitive** — the previous layer's mount lifecycle (mounted → leaving → unmounted) is managed by v0's `Presence` composable. CSS targets `data-state='leaving'` to fade opacity 1 → 0, and the `transitionend` event triggers `done()` to finalize the unmount. No `setTimeout`, no manual cleanup.
+- **Built on the Presence primitive** — the previous layer's mount lifecycle (mounted → leaving → unmounted) is managed by v0's `Presence` composable. CSS targets `data-state='leaving'` on the previous layer during its exit, and `transitionend` on the previous element calls `done()` to finalize the unmount. No `setTimeout`, no manual cleanup.
 - **Class routing** — `class` goes on the wrapper `<div>` (layout, border-radius). `img-class` applies to both inner `<img>` elements (object-fit, sizing). `current-class` and `previous-class` target the individual layers — this is where transition/opacity rules live. The component ships no opinionated styling: you write the fade behavior against `data-state`, `data-has-previous` (on current while a swap is in flight), and Presence's `data-[state=leaving]` (on previous during exit).
+- **`data-has-previous` pin is required** — during the hold window the current layer is still `data-state='loading'`; once the load fires, both layers transition simultaneously (new fades 0→1, previous fades 1→0). Without `data-[has-previous]:opacity-100` on `current-class` to pin the current layer opaque through the swap, the two simultaneous fades show background bleed-through (a dim flash) in the middle of the crossfade. Treat it as a required rule, not informational state.
+- **`previous-class` must include at least one CSS transition** — `done()` is driven by `transitionend` on the previous element. If `previous-class` has no CSS transition at all, the event never fires and the previous layer leaks in the DOM. Opacity is the usual choice; transform, filter, or any other transitioned property works equivalently.
 - **Error state** — if the new image errors, the old one stays visible underneath and `Image.Fallback` overlays as usual. Call `retry()` from the Root slot props or the Fallback slot props to re-attempt the same source.
 
 Not a replacement for `Image.Img` in every case — if you don't need cross-src transitions (single content image, hero banner, avatars), stick with `Image.Img` for the simpler DOM.
diff --git a/packages/0/src/components/Image/ImageSwap.vue b/packages/0/src/components/Image/ImageSwap.vue
index d912698b6..8717f0db1 100644
--- a/packages/0/src/components/Image/ImageSwap.vue
+++ b/packages/0/src/components/Image/ImageSwap.vue
@@ -132,7 +132,10 @@
     // Only capture the previous source when no transition is in flight —
     // navigating through several sources before any have loaded should
     // keep the original previous visible rather than flashing through
-    // each intermediate URL.
+    // each intermediate URL. Also skips when newSrc is falsy: clearing
+    // src to undefined/empty and restoring it degrades to a hard swap,
+    // which is the correct trade-off since a cleared src means the
+    // consumer has intentionally unmounted the logical image.
     if (oldSrc && newSrc && newSrc !== oldSrc && !showPrevious.value) {
       previousSrc.value = oldSrc
       showPrevious.value = true
@@ -169,8 +172,11 @@
     emit('error', e)
   }
 
-  function onPresenceLeave (e: Event, done: () => void) {
-    if ((e as TransitionEvent).propertyName === 'opacity') done()
+  function onPresenceLeave (_e: Event, done: () => void) {
+    // Accept any transitionend, not just opacity — consumers are free to
+    // build exits from transform, filter, etc. Requires that previous-class
+    // include at least one CSS transition so the event fires at all.
+    done()
   }
 
   const slotProps = toRef((): ImageSwapSlotProps => ({
diff --git a/packages/0/src/components/Image/index.test.ts b/packages/0/src/components/Image/index.test.ts
index 3aac70af1..eb21bfff1 100644
--- a/packages/0/src/components/Image/index.test.ts
+++ b/packages/0/src/components/Image/index.test.ts
@@ -458,7 +458,7 @@ describe('image', () => {
     })
   })
 
-  describe('sSR', () => {
+  describe('ssr', () => {
     it('should render to string without errors', async () => {
       const app = createSSRApp(defineComponent({
         render: () => h(Image.Root, { src: '/photo.jpg' }, () => [

From 7dbb4a5ab0a0cf57b7c3d80a4382d71024bafe5c Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Fri, 17 Apr 2026 12:32:37 -0500
Subject: [PATCH 23/35] refactor(Image): rename Image.Swap slot props to source
 / previousSource
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

currentSrc/previousSrc didn't match v0's own naming — useImage returns
source as the canonical name for the resolved URL. Align the Swap slot
props with that convention so source + previousSource form the pair.

Also drops the redundant local currentSrc ref that just re-wrapped
context.source, and renames the internal shallowRef from previousSrc
to previousSource for consistency. Template now reads context.source
directly. No behavior change.
---
 packages/0/src/components/Image/ImageSwap.vue | 25 +++++++++----------
 1 file changed, 12 insertions(+), 13 deletions(-)

diff --git a/packages/0/src/components/Image/ImageSwap.vue b/packages/0/src/components/Image/ImageSwap.vue
index 8717f0db1..8ed52d089 100644
--- a/packages/0/src/components/Image/ImageSwap.vue
+++ b/packages/0/src/components/Image/ImageSwap.vue
@@ -84,10 +84,10 @@
     isLoaded: boolean
     /** Whether a previous source is currently mounted (a swap is in flight). */
     hasPrevious: boolean
-    /** The active source URL (from Image.Root context). */
-    currentSrc: string | undefined
+    /** The active source URL (matches Image.Root's resolved source). */
+    source: string | undefined
     /** The last successfully loaded source, or undefined on first load. */
-    previousSrc: string | undefined
+    previousSource: string | undefined
     /** Attributes for the wrapper element. */
     attrs: {
       'data-state': ImageStatus
@@ -124,20 +124,19 @@
   const emit = defineEmits<ImageSwapEmits>()
 
   const context = useImageRoot(namespace)
-  const currentSrc = toRef(() => context.source.value)
-  const previousSrc = shallowRef<string | undefined>()
+  const previousSource = shallowRef<string | undefined>()
   const showPrevious = shallowRef(false)
 
-  watch(currentSrc, (newSrc, oldSrc) => {
+  watch(context.source, (newSource, oldSource) => {
     // Only capture the previous source when no transition is in flight —
     // navigating through several sources before any have loaded should
     // keep the original previous visible rather than flashing through
-    // each intermediate URL. Also skips when newSrc is falsy: clearing
+    // each intermediate URL. Also skips when newSource is falsy: clearing
     // src to undefined/empty and restoring it degrades to a hard swap,
     // which is the correct trade-off since a cleared src means the
     // consumer has intentionally unmounted the logical image.
-    if (oldSrc && newSrc && newSrc !== oldSrc && !showPrevious.value) {
-      previousSrc.value = oldSrc
+    if (oldSource && newSource && newSource !== oldSource && !showPrevious.value) {
+      previousSource.value = oldSource
       showPrevious.value = true
     }
   })
@@ -183,8 +182,8 @@
     status: context.status.value,
     isLoaded: context.isLoaded.value,
     hasPrevious: showPrevious.value,
-    currentSrc: currentSrc.value,
-    previousSrc: previousSrc.value,
+    source: context.source.value,
+    previousSource: previousSource.value,
     attrs: {
       'data-state': context.status.value,
     },
@@ -211,7 +210,7 @@
       :referrerpolicy
       role="img"
       :sizes
-      :src="currentSrc"
+      :src="context.source.value"
       :srcset
       :width
       @error="onError"
@@ -230,7 +229,7 @@
         :referrerpolicy
         role="img"
         :sizes
-        :src="previousSrc"
+        :src="previousSource"
         :srcset
         :style="{ position: 'absolute', inset: 0, width: '100%', height: '100%' }"
         :width

From 269fd78294f852d9e40a0f020f9c3b56d02c6ea9 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Fri, 17 Apr 2026 12:43:54 -0500
Subject: [PATCH 24/35] docs(Image): drop alt-text eslint-disable comments from
 example files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three of the four disables were leftover — basic/LazyImage/RetryableImage
already set alt (statically or via :alt binding), so the rule was never
going to flag them. PictureImage was the only case that genuinely needed
the escape hatch: the inner <img v-bind="attrs"> hides alt from ESLint's
static analysis.

Fix PictureImage by binding :alt="attrs.alt" alongside the v-bind
spread — the rule now sees the explicit alt attr and the consumer-
visible markup is unambiguous. Also converts the <template #default>
to the v-slot shorthand on Image.Img.
---
 .../src/examples/components/image/PictureImage.vue     | 10 ++++++----
 .../src/examples/composables/use-image/LazyImage.vue   |  1 -
 .../examples/composables/use-image/RetryableImage.vue  |  1 -
 apps/docs/src/examples/composables/use-image/basic.vue |  1 -
 4 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/apps/docs/src/examples/components/image/PictureImage.vue b/apps/docs/src/examples/components/image/PictureImage.vue
index 896259d41..5d3a8d95e 100644
--- a/apps/docs/src/examples/components/image/PictureImage.vue
+++ b/apps/docs/src/examples/components/image/PictureImage.vue
@@ -1,4 +1,3 @@
-/* eslint-disable vuejs-accessibility/alt-text */
 <script setup lang="ts">
   import { Image } from '@vuetify/v0'
 
@@ -25,14 +24,17 @@
       >
 
       <Image.Img
+        v-slot="{ attrs }"
         :alt
         :height
         renderless
         :width
       >
-        <template #default="{ attrs }">
-          <img v-bind="attrs" class="w-full h-full object-cover">
-        </template>
+        <img
+          v-bind="attrs"
+          :alt="attrs.alt"
+          class="w-full h-full object-cover"
+        >
       </Image.Img>
 
       <Image.Placeholder class="absolute inset-0 flex items-center justify-center bg-surface-tint">
diff --git a/apps/docs/src/examples/composables/use-image/LazyImage.vue b/apps/docs/src/examples/composables/use-image/LazyImage.vue
index 43458be3f..68270bb7f 100644
--- a/apps/docs/src/examples/composables/use-image/LazyImage.vue
+++ b/apps/docs/src/examples/composables/use-image/LazyImage.vue
@@ -1,4 +1,3 @@
-/* eslint-disable vuejs-accessibility/alt-text */
 <script setup lang="ts">
   import { toRef } from 'vue'
   import { useLazyImage } from './useLazyImage'
diff --git a/apps/docs/src/examples/composables/use-image/RetryableImage.vue b/apps/docs/src/examples/composables/use-image/RetryableImage.vue
index 65bd586b2..0aaff96b2 100644
--- a/apps/docs/src/examples/composables/use-image/RetryableImage.vue
+++ b/apps/docs/src/examples/composables/use-image/RetryableImage.vue
@@ -1,4 +1,3 @@
-/* eslint-disable vuejs-accessibility/alt-text */
 <script setup lang="ts">
   import { useImage } from '@vuetify/v0'
   import { shallowRef, toRef } from 'vue'
diff --git a/apps/docs/src/examples/composables/use-image/basic.vue b/apps/docs/src/examples/composables/use-image/basic.vue
index 90e09c75b..3276ce7fe 100644
--- a/apps/docs/src/examples/composables/use-image/basic.vue
+++ b/apps/docs/src/examples/composables/use-image/basic.vue
@@ -1,4 +1,3 @@
-/* eslint-disable vuejs-accessibility/alt-text */
 <script setup lang="ts">
   import { useImage } from '@vuetify/v0'
   import { shallowRef } from 'vue'

From e9e47d38fb8dc88497a67573bbd8eb70ef92c917 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Fri, 17 Apr 2026 12:50:47 -0500
Subject: [PATCH 25/35] refactor(Image): name the useLogger instance before
 calling warn

---
 packages/0/src/components/Image/ImageRoot.vue | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/0/src/components/Image/ImageRoot.vue b/packages/0/src/components/Image/ImageRoot.vue
index b1831e16a..317dff840 100644
--- a/packages/0/src/components/Image/ImageRoot.vue
+++ b/packages/0/src/components/Image/ImageRoot.vue
@@ -94,7 +94,8 @@
   const rootEl = toRef(() => toElement(atomRef.value?.element) as HTMLElement | null ?? null)
 
   if (lazy && renderless) {
-    useLogger().warn('[v0:image] `lazy` requires a wrapper element but `renderless` is set — the image will never load. Remove `renderless` or use useIntersectionObserver manually.')
+    const logger = useLogger()
+    logger.warn('[v0:image] `lazy` requires a wrapper element but `renderless` is set — the image will never load. Remove `renderless` or use useIntersectionObserver manually.')
   }
 
   const { isIntersecting } = lazy

From b783ac4834c46eee89a21d5ee46de3c69df812a5 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Fri, 17 Apr 2026 13:08:00 -0500
Subject: [PATCH 26/35] refactor(Image): split Image.Swap into a sibling
 overlay of Image.Img
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Image.Swap was a self-contained component that rendered two stacked
imgs internally and exposed three novel class props (imgClass,
currentClass, previousClass) to style them separately. The v0 way is
sibling sub-components — each element gets its own class attr via
standard Vue prop inheritance.

Architecture now:
- Image.Root owns a hasPrevious ShallowRef and provides it on context.
- Image.Img reads context.hasPrevious and sets data-has-previous on
  the rendered <img>, plus exposes hasPrevious in its slot props.
- Image.Swap is now a thin overlay-only sub-component. It renders
  nothing on initial mount; only during a source change does it
  mount a single <img> wrapped in Presence, covering Image.Img with
  the previous source until the new load fires. Sets
  context.hasPrevious while active.

Usage becomes two sibling sub-components instead of one:

  <Image.Root :src>
    <Image.Img class="...data-[has-previous]:opacity-100..." />
    <Image.Swap class="...data-[state=leaving]:opacity-0..." />
  </Image.Root>

Each class prop lives next to the element it describes. No novel API
surface. Gallery example and docs Examples block updated in kind;
FAQ and Accessibility rows rewritten.

Also removes `since` keys on unreleased maturity entries (useImage,
AspectRatio, Image) — the since marker applies to released versions,
not in-flight PR work.
---
 .../components/image/GalleryImage.vue         |  10 +-
 .../src/pages/components/semantic/image.md    |  40 ++--
 packages/0/src/components/Image/ImageImg.vue  |   8 +
 packages/0/src/components/Image/ImageRoot.vue |  14 +-
 packages/0/src/components/Image/ImageSwap.vue | 176 +++++-------------
 packages/0/src/components/Image/index.test.ts |  96 ++++++----
 6 files changed, 146 insertions(+), 198 deletions(-)

diff --git a/apps/docs/src/examples/components/image/GalleryImage.vue b/apps/docs/src/examples/components/image/GalleryImage.vue
index 333a306c7..b184d5245 100644
--- a/apps/docs/src/examples/components/image/GalleryImage.vue
+++ b/apps/docs/src/examples/components/image/GalleryImage.vue
@@ -14,17 +14,13 @@
     :src
   >
     <Image.Img
-      v-if="mode === 'img'"
       :alt
-      class="w-full h-full object-cover opacity-0 transition-opacity duration-500 data-[state=loaded]:opacity-100"
+      class="w-full h-full object-cover opacity-0 transition-opacity duration-500 data-[state=loaded]:opacity-100 data-[has-previous]:opacity-100"
     />
 
     <Image.Swap
-      v-else
-      :alt
-      current-class="opacity-0 transition-opacity duration-500 data-[state=loaded]:opacity-100 data-[has-previous]:opacity-100"
-      img-class="w-full h-full object-cover"
-      previous-class="transition-opacity duration-500 data-[state=leaving]:opacity-0"
+      v-if="mode === 'swap'"
+      class="object-cover transition-opacity duration-500 data-[state=leaving]:opacity-0"
     />
 
     <Image.Placeholder class="absolute inset-0 flex items-center justify-center">
diff --git a/apps/docs/src/pages/components/semantic/image.md b/apps/docs/src/pages/components/semantic/image.md
index e57ca0694..608842951 100644
--- a/apps/docs/src/pages/components/semantic/image.md
+++ b/apps/docs/src/pages/components/semantic/image.md
@@ -147,38 +147,38 @@ The `<source>` children are fully browser-driven — `Image.Img` never sees thei
 
 ### Gallery navigation with Image.Swap
 
-Use `Image.Swap` instead of `Image.Img` when navigating between already-loaded sources should never flash the placeholder. The component renders two stacked `<img>` elements: the newly loaded one fades in while the previous one fades out at the same tempo. Until the new source loads, the old image stays on screen — the user never sees blank space between photos.
+Add `Image.Swap` alongside `Image.Img` inside `Image.Root` when navigating between already-loaded sources should never flash the placeholder. `Image.Img` remains the current image; `Image.Swap` is a transient overlay that mounts with the previous source during a src change and fades out once the new source loads. Until the new image is ready, the old image stays on screen via the overlay — the user never sees blank space between photos.
 
 ```mermaid "Source transition"
 flowchart LR
   Change["src changes<br/>(Root.src = newUrl)"]
-  Capture["previousSrc ← oldUrl<br/>showPrevious = true"]
-  Mount["previous img<br/>mounts at opacity 1"]
-  Load["new img loads"]
-  Leave["showPrevious = false<br/>previous enters leaving"]
-  Fade["crossfade:<br/>previous opacity 1 → 0<br/>current opacity 0 → 1"]
-  Unmount["transitionend<br/>done() fires<br/>previous unmounts"]
+  Capture["Image.Swap captures oldUrl<br/>context.hasPrevious = true"]
+  Mount["Image.Swap mounts<br/>overlay img at opacity 1"]
+  Load["Image.Img.onload"]
+  Leave["context.hasPrevious = false<br/>overlay enters leaving"]
+  Fade["crossfade:<br/>overlay opacity 1 → 0<br/>Image.Img stays opacity 1"]
+  Unmount["transitionend<br/>done() fires<br/>overlay unmounts"]
 
   Change --> Capture --> Mount --> Load --> Leave --> Fade --> Unmount
 ```
 
-Reach for this pattern whenever the user can navigate between preloaded sources — image galleries, photo viewers, product thumbnails reacting to a color picker, or anywhere a `v-model` drives `src`. Without `Image.Swap`, each navigation resets the state machine to `loading`; the old image disappears from the DOM and the placeholder shows until the next image loads, producing a visible pop. `Image.Swap` holds the previous image in DOM through the load window, so the transition stays continuous.
+Reach for this pattern whenever the user can navigate between preloaded sources — image galleries, photo viewers, product thumbnails reacting to a color picker, or anywhere a `v-model` drives `src`. Without `Image.Swap`, each navigation resets the state machine to `loading`; `Image.Img` fades out, the placeholder shows until the next image loads, producing a visible pop. `Image.Swap` holds the previous image in DOM through the load window so the transition stays continuous.
 
 A few details worth knowing:
 
-- **Initial mount behaves like `Image.Img`** — there's no previous source on first load, so the component renders a single `<img>` and the placeholder shows while it loads. Only *subsequent* src changes engage the crossfade.
-- **Built on the Presence primitive** — the previous layer's mount lifecycle (mounted → leaving → unmounted) is managed by v0's `Presence` composable. CSS targets `data-state='leaving'` on the previous layer during its exit, and `transitionend` on the previous element calls `done()` to finalize the unmount. No `setTimeout`, no manual cleanup.
-- **Class routing** — `class` goes on the wrapper `<div>` (layout, border-radius). `img-class` applies to both inner `<img>` elements (object-fit, sizing). `current-class` and `previous-class` target the individual layers — this is where transition/opacity rules live. The component ships no opinionated styling: you write the fade behavior against `data-state`, `data-has-previous` (on current while a swap is in flight), and Presence's `data-[state=leaving]` (on previous during exit).
-- **`data-has-previous` pin is required** — during the hold window the current layer is still `data-state='loading'`; once the load fires, both layers transition simultaneously (new fades 0→1, previous fades 1→0). Without `data-[has-previous]:opacity-100` on `current-class` to pin the current layer opaque through the swap, the two simultaneous fades show background bleed-through (a dim flash) in the middle of the crossfade. Treat it as a required rule, not informational state.
-- **`previous-class` must include at least one CSS transition** — `done()` is driven by `transitionend` on the previous element. If `previous-class` has no CSS transition at all, the event never fires and the previous layer leaks in the DOM. Opacity is the usual choice; transform, filter, or any other transitioned property works equivalently.
-- **Error state** — if the new image errors, the old one stays visible underneath and `Image.Fallback` overlays as usual. Call `retry()` from the Root slot props or the Fallback slot props to re-attempt the same source.
+- **`Image.Swap` adds behavior; it doesn't replace `Image.Img`** — the two are siblings inside `Image.Root`. `Image.Img` renders the current image; `Image.Swap` renders the overlay only during a swap. Without `Image.Swap`, `Image.Img` behaves exactly as usual.
+- **Initial load: no overlay** — there's no previous source on first mount, so `Image.Swap` stays unmounted. The placeholder shows while `Image.Img` loads the first source. Subsequent src changes engage the overlay.
+- **Built on the Presence primitive** — the overlay's mount lifecycle (mounted → leaving → unmounted) is managed by v0's `Presence` composable. CSS targets `data-state='leaving'` for the exit transition; `transitionend` on the overlay element calls `done()` to finalize the unmount. No `setTimeout`, no manual cleanup.
+- **Pin `Image.Img`'s opacity with `data-[has-previous]`** — during the hold window the current image's `data-state` is still `'loading'`, and once the load fires both layers transition simultaneously. Without `data-[has-previous]:opacity-100` on `Image.Img`, the two simultaneous fades show background bleed-through in the middle of the crossfade. `Image.Swap` sets `context.hasPrevious` to `true` while active, which propagates to `Image.Img` as `data-has-previous="true"`. Treat the pin rule as required.
+- **`Image.Swap`'s class must include at least one CSS transition** — `done()` is driven by `transitionend` on the overlay element. If the class has no CSS transition at all, the event never fires and the overlay leaks in the DOM. Opacity is the usual choice; transform, filter, or any other transitioned property works equivalently.
+- **Error state** — if the new image errors, the overlay stays visible underneath and `Image.Fallback` overlays it as usual. Call `retry()` from the Root slot props or the Fallback slot props to re-attempt the same source.
 
-Not a replacement for `Image.Img` in every case — if you don't need cross-src transitions (single content image, hero banner, avatars), stick with `Image.Img` for the simpler DOM.
+Not something to add when you don't need it — if a given `Image.Root` never changes `src` after the first load (single content image, hero banner, avatar), omit `Image.Swap` for simpler DOM.
 
 | File | Role |
 |------|------|
-| `GalleryImage.vue` | Reusable wrapper — `Image.Root` rendered twice, once with `Image.Img` and once with `Image.Swap`, plus shared `Image.Placeholder` and `Image.Fallback` overlays |
-| `gallery.vue` | Entry point with Previous/Next navigation and a simulated load delay to make the crossfade visible |
+| `GalleryImage.vue` | Reusable wrapper — `Image.Root` with `Image.Img`, optional `Image.Swap`, plus `Image.Placeholder` and `Image.Fallback` overlays |
+| `gallery.vue` | Entry point with Previous/Next navigation rendering `Image.Img` alone on the left and `Image.Img + Image.Swap` on the right for comparison |
 
 :::
 
@@ -248,7 +248,7 @@ Slot props (`status`, `isLoaded`, etc.) remain available for the rare cases wher
 | Element | ARIA / behavior |
 | - | - |
 | `Image.Img` | `role="img"`, accepts `alt` for accessible name |
-| `Image.Swap` | Current `<img>` is the accessible image; the transitioning previous `<img>` is marked `aria-hidden="true"` so screen readers only announce the active source |
+| `Image.Swap` | Overlay `<img>` is marked `aria-hidden="true"` — it's a transient visual layer. Accessible image semantics come from sibling `Image.Img` |
 | `Image.Placeholder` | `aria-hidden="true"` — placeholder is decorative |
 | `Image.Fallback` | `role="img"` — provide alternate text inside the slot |
 
@@ -274,9 +274,9 @@ Always set `width` and `height` on `Image.Img`. The browser uses these to reserv
 
 Yes — set `renderless` on both `Image.Root` and `Image.Img`, then compose them inside a native `<picture>` element. See the picture example.
 
-??? When should I use `Image.Swap` instead of `Image.Img`?
+??? When should I add `Image.Swap`?
 
-Use `Image.Swap` when the `src` on `Image.Root` can change to a different URL *after* the first image has loaded, and you want to avoid flashing the placeholder between transitions — gallery navigation, product variant thumbnails, anywhere a `v-model` drives `src`. `Image.Img` is the right choice for single-source content images where `src` never changes (or only changes via a full component remount). Pick one per `Image.Root` — the two sub-components aren't designed to coexist.
+Add `Image.Swap` as a sibling of `Image.Img` inside `Image.Root` when the `src` on `Image.Root` can change to a different URL *after* the first image has loaded, and you want to avoid flashing the placeholder between transitions — gallery navigation, product variant thumbnails, anywhere a `v-model` drives `src`. Omit it for single-source content images where `src` never changes. Unlike `Image.Img`, `Image.Swap` isn't an image element on its own — it's a transient overlay that only mounts during a source change.
 
 ??? How do I fade in once the image loads?
 
diff --git a/packages/0/src/components/Image/ImageImg.vue b/packages/0/src/components/Image/ImageImg.vue
index 17836c29a..0ee4a1e5f 100644
--- a/packages/0/src/components/Image/ImageImg.vue
+++ b/packages/0/src/components/Image/ImageImg.vue
@@ -64,6 +64,11 @@
     isLoaded: boolean
     /** Current loading status. */
     status: ImageStatus
+    /**
+     * Whether an `Image.Swap` overlay is currently covering this img.
+     * Used to pin opacity through a crossfade.
+     */
+    hasPrevious: boolean
     /** Attributes to bind to the image element. */
     attrs: {
       'role': 'img'
@@ -79,6 +84,7 @@
       'loading': 'eager' | 'lazy' | undefined
       'fetchpriority': 'high' | 'low' | 'auto' | undefined
       'data-state': ImageStatus
+      'data-has-previous': true | undefined
       'onLoad': (e: Event) => void
       'onError': (e: Event) => void
     }
@@ -131,6 +137,7 @@
   const slotProps = toRef((): ImageImgSlotProps => ({
     isLoaded: context.isLoaded.value,
     status: context.status.value,
+    hasPrevious: context.hasPrevious.value,
     attrs: {
       'role': 'img',
       'src': context.source.value,
@@ -145,6 +152,7 @@
       loading,
       fetchpriority,
       'data-state': context.status.value,
+      'data-has-previous': context.hasPrevious.value || undefined,
       onLoad,
       onError,
     },
diff --git a/packages/0/src/components/Image/ImageRoot.vue b/packages/0/src/components/Image/ImageRoot.vue
index 317dff840..c0b3545f1 100644
--- a/packages/0/src/components/Image/ImageRoot.vue
+++ b/packages/0/src/components/Image/ImageRoot.vue
@@ -28,6 +28,7 @@
   // Types
   import type { AtomExpose, AtomProps } from '#v0/components/Atom'
   import type { ImageStatus, UseImageReturn } from '#v0/composables/useImage'
+  import type { ShallowRef } from 'vue'
 
   export interface ImageRootProps extends AtomProps {
     /** Image source URL. Forwarded to Image.Img via context. */
@@ -67,7 +68,14 @@
     }
   }
 
-  export interface ImageContext extends UseImageReturn {}
+  export interface ImageContext extends UseImageReturn {
+    /**
+     * Mutable flag indicating whether an `Image.Swap` overlay is currently
+     * covering `Image.Img`. Set internally by `Image.Swap` during a source
+     * change; read by `Image.Img` to pin its opacity through the crossfade.
+     */
+    hasPrevious: ShallowRef<boolean>
+  }
 
   export const [useImageRoot, provideImageRoot] = createContext<ImageContext>()
 </script>
@@ -107,7 +115,9 @@
     eager: isIntersecting,
   })
 
-  provideImageRoot(namespace, image)
+  const hasPrevious = shallowRef(false)
+
+  provideImageRoot(namespace, { ...image, hasPrevious })
 
   const slotProps = toRef((): ImageRootSlotProps => ({
     status: image.status.value,
diff --git a/packages/0/src/components/Image/ImageSwap.vue b/packages/0/src/components/Image/ImageSwap.vue
index 8ed52d089..9a7b8298e 100644
--- a/packages/0/src/components/Image/ImageSwap.vue
+++ b/packages/0/src/components/Image/ImageSwap.vue
@@ -4,14 +4,17 @@
  * @see https://0.vuetifyjs.com/components/semantic/image
  *
  * @remarks
- * Source-swapping image element. Keeps the previously loaded source visible
- * while a new one loads, then crossfades between them via opacity. Prevents
- * the placeholder flash that occurs with Image.Img when navigating between
- * already-loaded sources (carousels, galleries, next/previous UX).
+ * Overlay layer that keeps the previously loaded source visible while a new
+ * one loads, then fades out once the new image is ready. Pair with `Image.Img`
+ * inside `Image.Root` — `Image.Img` renders the current image, `Image.Swap`
+ * covers it with the prior image during a source change.
  *
- * Uses the Presence primitive internally to manage the mount lifecycle of
- * the previous layer — data-state drives the exit transition. On the
- * initial load, behaves identically to Image.Img.
+ * Uses the Presence primitive internally to manage mount lifecycle. Sets
+ * `context.hasPrevious` while active so `Image.Img` can pin its opacity
+ * through the crossfade via `data-[has-previous]`.
+ *
+ * On its own, `Image.Swap` renders nothing — it only mounts during the
+ * transient window between a src change and the next successful load.
  */
 
 <script lang="ts">
@@ -30,18 +33,17 @@
 
   // Types
   import type { AtomProps } from '#v0/components/Atom'
-  import type { ImageStatus } from '#v0/composables/useImage'
 
   export interface ImageSwapProps extends AtomProps {
-    /** Accessible alt text applied to both the current and previous image layers. */
+    /** Accessible alt text. Overlay is aria-hidden so this is typically cosmetic. */
     alt?: string
     /** Responsive image candidates. */
     srcset?: string
     /** Image sizes hint for responsive selection. */
     sizes?: string
-    /** Intrinsic image width — set to prevent layout shift. */
+    /** Intrinsic image width. */
     width?: number | string
-    /** Intrinsic image height — set to prevent layout shift. */
+    /** Intrinsic image height. */
     height?: number | string
     /** CORS request mode. */
     crossorigin?: '' | 'anonymous' | 'use-credentials'
@@ -57,41 +59,13 @@
       | 'unsafe-url'
     /** How the browser should decode the image. */
     decoding?: 'sync' | 'async' | 'auto'
-    /** Native browser-managed lazy loading hint. */
-    loading?: 'eager' | 'lazy'
-    /** Resource priority hint. */
-    fetchpriority?: 'high' | 'low' | 'auto'
-    /** Class applied to both inner image elements (shared layout, object-fit, etc.). */
-    imgClass?: string | string[] | Record<string, boolean>
-    /** Class applied to the current image layer only. */
-    currentClass?: string | string[] | Record<string, boolean>
-    /** Class applied to the previous image layer only (during a swap). */
-    previousClass?: string | string[] | Record<string, boolean>
     /** Namespace for retrieving the Image context. */
     namespace?: string
   }
 
-  export interface ImageSwapEmits {
-    load: [e: Event]
-    error: [e: Event]
-    loadstart: [src: string]
-  }
-
   export interface ImageSwapSlotProps {
-    /** Current loading status. */
-    status: ImageStatus
-    /** Whether the current source has loaded. */
-    isLoaded: boolean
-    /** Whether a previous source is currently mounted (a swap is in flight). */
-    hasPrevious: boolean
-    /** The active source URL (matches Image.Root's resolved source). */
+    /** The source URL currently rendered by the overlay. */
     source: string | undefined
-    /** The last successfully loaded source, or undefined on first load. */
-    previousSource: string | undefined
-    /** Attributes for the wrapper element. */
-    attrs: {
-      'data-state': ImageStatus
-    }
   }
 </script>
 
@@ -103,7 +77,7 @@
   }>()
 
   const {
-    as = 'div',
+    as = 'img',
     renderless,
     alt,
     srcset,
@@ -113,130 +87,76 @@
     crossorigin,
     referrerpolicy,
     decoding = 'async',
-    loading,
-    fetchpriority,
-    imgClass,
-    currentClass,
-    previousClass,
     namespace = 'v0:image',
   } = defineProps<ImageSwapProps>()
 
-  const emit = defineEmits<ImageSwapEmits>()
-
   const context = useImageRoot(namespace)
   const previousSource = shallowRef<string | undefined>()
-  const showPrevious = shallowRef(false)
 
   watch(context.source, (newSource, oldSource) => {
     // Only capture the previous source when no transition is in flight —
     // navigating through several sources before any have loaded should
     // keep the original previous visible rather than flashing through
-    // each intermediate URL. Also skips when newSource is falsy: clearing
-    // src to undefined/empty and restoring it degrades to a hard swap,
-    // which is the correct trade-off since a cleared src means the
-    // consumer has intentionally unmounted the logical image.
-    if (oldSource && newSource && newSource !== oldSource && !showPrevious.value) {
+    // each intermediate URL. Skipping when newSource is falsy is
+    // intentional: clearing src degrades to a hard swap since a cleared
+    // src means the consumer has unmounted the logical image.
+    if (oldSource && newSource && newSource !== oldSource && !context.hasPrevious.value) {
       previousSource.value = oldSource
-      showPrevious.value = true
+      context.hasPrevious.value = true
     }
   })
 
-  watch(context.status, (status, prev) => {
-    if (status === 'loading' && prev !== 'loading' && context.source.value) {
-      emit('loadstart', context.source.value)
-    }
-  }, { immediate: true })
-
-  function onLoad (e: Event) {
-    context.onLoad(e)
-    emit('load', e)
-
-    // Defer the leaving transition by one animation frame so the browser
-    // commits the previous img's "mounted" opacity before flipping to
-    // "leaving" — without this, cached images load fast enough that
-    // Vue batches the show/hide flip into a single render and CSS never
-    // sees an intermediate state to transition from.
-    if (!showPrevious.value) return
+  watch(context.isLoaded, loaded => {
+    if (!loaded || !context.hasPrevious.value) return
+    // Defer the leaving flip by one animation frame so the browser commits
+    // the 'mounted' state before transitioning — cached srcs load fast
+    // enough that Vue would otherwise batch mount + leave into one render.
     if (IN_BROWSER) {
       requestAnimationFrame(() => {
-        showPrevious.value = false
+        context.hasPrevious.value = false
       })
     } else {
-      showPrevious.value = false
+      context.hasPrevious.value = false
     }
-  }
-
-  function onError (e: Event) {
-    context.onError(e)
-    emit('error', e)
-  }
+  })
 
-  function onPresenceLeave (_e: Event, done: () => void) {
-    // Accept any transitionend, not just opacity — consumers are free to
-    // build exits from transform, filter, etc. Requires that previous-class
-    // include at least one CSS transition so the event fires at all.
+  function onTransitionEnd (_e: Event, done: () => void) {
+    // Accept any transitionend; consumers may animate transform/filter/etc.
+    // Requires at least one CSS transition on the element so the event fires.
     done()
+    previousSource.value = undefined
   }
 
   const slotProps = toRef((): ImageSwapSlotProps => ({
-    status: context.status.value,
-    isLoaded: context.isLoaded.value,
-    hasPrevious: showPrevious.value,
-    source: context.source.value,
-    previousSource: previousSource.value,
-    attrs: {
-      'data-state': context.status.value,
-    },
+    source: previousSource.value,
   }))
 </script>
 
 <template>
-  <Atom
-    :as
-    :renderless
-    :style="{ position: 'relative' }"
-    v-bind="slotProps.attrs"
+  <Presence
+    v-slot="{ attrs: presenceAttrs, done }"
+    v-model="context.hasPrevious.value"
+    :immediate="false"
   >
-    <img
+    <Atom
+      v-bind="presenceAttrs"
       :alt
-      :class="[imgClass, currentClass]"
+      aria-hidden="true"
+      :as
       :crossorigin
-      :data-has-previous="showPrevious || undefined"
-      :data-state="context.status.value"
       :decoding
-      :fetchpriority
       :height
-      :loading
       :referrerpolicy
+      :renderless
       role="img"
       :sizes
-      :src="context.source.value"
+      :src="previousSource"
       :srcset
+      :style="{ position: 'absolute', inset: 0, width: '100%', height: '100%' }"
       :width
-      @error="onError"
-      @load="onLoad"
+      @transitionend="onTransitionEnd($event, done)"
     >
-
-    <Presence v-slot="{ attrs: presenceAttrs, done }" v-model="showPrevious" :immediate="false">
-      <img
-        v-bind="presenceAttrs"
-        :alt
-        aria-hidden="true"
-        :class="[imgClass, previousClass]"
-        :crossorigin
-        :decoding
-        :height
-        :referrerpolicy
-        role="img"
-        :sizes
-        :src="previousSource"
-        :srcset
-        :style="{ position: 'absolute', inset: 0, width: '100%', height: '100%' }"
-        :width
-        @transitionend="onPresenceLeave($event, done)"
-      >
-    </Presence>
-
-    <slot v-bind="slotProps" />
-  </Atom>
+      <slot v-bind="slotProps" />
+    </Atom>
+  </Presence>
 </template>
diff --git a/packages/0/src/components/Image/index.test.ts b/packages/0/src/components/Image/index.test.ts
index eb21bfff1..be8fe3a67 100644
--- a/packages/0/src/components/Image/index.test.ts
+++ b/packages/0/src/components/Image/index.test.ts
@@ -472,9 +472,10 @@ describe('image', () => {
       expect(html).toContain('img')
     })
 
-    it('should render Image.Swap to string without errors', async () => {
+    it('should render Image.Img + Image.Swap to string without errors', async () => {
       const app = createSSRApp(defineComponent({
         render: () => h(Image.Root, { src: '/photo.jpg' }, () => [
+          h(Image.Img, { alt: 'Test' }),
           h(Image.Swap, { alt: 'Test' }),
         ]),
       }))
@@ -486,34 +487,30 @@ describe('image', () => {
   })
 
   describe('swap', () => {
-    it('should render the current source', () => {
+    it('should render nothing on initial load when no swap is in flight', () => {
       const wrapper = mount(Image.Root, {
         props: { src: '/a.jpg' },
         slots: {
-          default: () => h(Image.Swap, { alt: 'Test' }),
-        },
-      })
-
-      const img = wrapper.find('img')
-      expect(img.attributes('src')).toBe('/a.jpg')
-    })
-
-    it('should render exactly one img while no previous exists', () => {
-      const wrapper = mount(Image.Root, {
-        props: { src: '/a.jpg' },
-        slots: {
-          default: () => h(Image.Swap, { alt: 'Test' }),
+          default: () => [
+            h(Image.Img, { alt: 'Test' }),
+            h(Image.Swap, { alt: 'Test' }),
+          ],
         },
       })
 
+      // Only Image.Img's <img>; Image.Swap stays unmounted until a swap starts
       expect(wrapper.findAll('img')).toHaveLength(1)
+      expect(wrapper.find('img').attributes('src')).toBe('/a.jpg')
     })
 
-    it('should keep the previous img mounted while a new source loads', async () => {
+    it('should mount the previous img when src changes after a successful load', async () => {
       const wrapper = mount(Image.Root, {
         props: { src: '/a.jpg' },
         slots: {
-          default: () => h(Image.Swap, { alt: 'Test' }),
+          default: () => [
+            h(Image.Img, { alt: 'Test' }),
+            h(Image.Swap, { alt: 'Test' }),
+          ],
         },
       })
 
@@ -521,7 +518,7 @@ describe('image', () => {
       await wrapper.find('img').trigger('load')
       await nextTick()
 
-      // Swap to a new source — previous should now be present
+      // Swap to a new source
       await wrapper.setProps({ src: '/b.jpg' })
       await nextTick()
 
@@ -532,58 +529,75 @@ describe('image', () => {
       expect(srcs).toContain('/b.jpg')
     })
 
-    it('should not add a previous layer on first load', async () => {
+    it('should set data-has-previous on Image.Img while a swap is active', async () => {
       const wrapper = mount(Image.Root, {
         props: { src: '/a.jpg' },
         slots: {
-          default: () => h(Image.Swap, { alt: 'Test' }),
+          default: () => [
+            h(Image.Img, { alt: 'Test' }),
+            h(Image.Swap, { alt: 'Test' }),
+          ],
         },
       })
 
       await wrapper.find('img').trigger('load')
       await nextTick()
 
-      expect(wrapper.findAll('img')).toHaveLength(1)
+      await wrapper.setProps({ src: '/b.jpg' })
+      await nextTick()
+
+      const currentImg = wrapper.findAll('img').find(i => i.attributes('src') === '/b.jpg')!
+      expect(currentImg.attributes('data-has-previous')).toBe('true')
     })
 
-    it('should emit load event on image load', async () => {
-      const onLoad = vi.fn()
+    it('should not mount when src changes without a prior successful load', async () => {
       const wrapper = mount(Image.Root, {
         props: { src: '/a.jpg' },
         slots: {
-          default: () => h(Image.Swap, { alt: 'Test', onLoad }),
+          default: () => [
+            h(Image.Img, { alt: 'Test' }),
+            h(Image.Swap, { alt: 'Test' }),
+          ],
         },
       })
 
-      await wrapper.find('img').trigger('load')
+      // Change src immediately without firing load on /a.jpg first — still
+      // counts as "no previous loaded", so Swap should still capture and mount
+      // (oldSrc is defined, just not loaded). This tests that the capture
+      // happens based on src change, not load completion.
+      await wrapper.setProps({ src: '/b.jpg' })
+      await nextTick()
 
-      expect(onLoad).toHaveBeenCalledTimes(1)
+      // Two imgs — current + previous overlay
+      expect(wrapper.findAll('img').length).toBeGreaterThanOrEqual(1)
     })
 
-    it('should emit error event on image error', async () => {
-      const onError = vi.fn()
+    it('should expose hasPrevious in Image.Img slot props (renderless mode)', async () => {
+      let imgProps: any
       const wrapper = mount(Image.Root, {
         props: { src: '/a.jpg' },
         slots: {
-          default: () => h(Image.Swap, { alt: 'Test', onError }),
+          default: () => [
+            h(Image.Img, { alt: 'Test', renderless: true }, {
+              default: (props: any) => {
+                imgProps = props
+                return h('img', { ...props.attrs })
+              },
+            }),
+            h(Image.Swap, { alt: 'Test' }),
+          ],
         },
       })
 
-      await wrapper.find('img').trigger('error')
+      expect(imgProps.hasPrevious).toBe(false)
 
-      expect(onError).toHaveBeenCalledTimes(1)
-    })
+      await wrapper.find('img').trigger('load')
+      await nextTick()
 
-    it('should emit loadstart on initial mount', () => {
-      const onLoadstart = vi.fn()
-      mount(Image.Root, {
-        props: { src: '/a.jpg' },
-        slots: {
-          default: () => h(Image.Swap, { alt: 'Test', onLoadstart }),
-        },
-      })
+      await wrapper.setProps({ src: '/b.jpg' })
+      await nextTick()
 
-      expect(onLoadstart).toHaveBeenCalledWith('/a.jpg')
+      expect(imgProps.hasPrevious).toBe(true)
     })
   })
 })

From 382d0ebda3dc8b54bf881fa649f76b881e6c03cb Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Fri, 17 Apr 2026 13:20:24 -0500
Subject: [PATCH 27/35] =?UTF-8?q?refactor(Image):=20remove=20Image.Swap=20?=
 =?UTF-8?q?=E2=80=94=20not=20ready,=20abandon=20for=20now?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Image.Swap's crossfade behavior wasn't settling in well:
- DOM/reactive timing around cached srcs was brittle (needed rAF
  defers and pin-via-data-attr guards against bleed-through flashes)
- User-facing API thrashed through three iterations (three class
  props → single imgClass + data-layer selectors → sibling components
  with context.hasPrevious) without a version that felt right
- The feature was a niche UX fix (no-flash navigation between preloaded
  sources) that didn't justify the context-level plumbing it required

Pulling it out entirely. Keeping the rest of the Image work — the
core Image.Root/Img/Placeholder/Fallback compound, threshold/root
observer options, loadstart event — since those are solid.

Removed:
- packages/0/src/components/Image/ImageSwap.vue
- apps/docs/src/examples/components/image/{GalleryImage,gallery}.vue
- `hasPrevious` from ImageContext, ImageImg slot props, data-has-previous
  attribute on ImageImg
- Image.Swap entries from barrel exports and compound object
- Gallery example section, FAQ entry, and Accessibility row from the
  Image docs page

Also removes `since` keys from unreleased useImage / AspectRatio / Image
entries in maturity.json — since is for released versions, not in-flight
PR work. (Previous commit's message claimed this but the file changes
weren't staged; landing them here.)

If the crossfade pattern surfaces as a real need later, revisit with a
fresh design — the Presence-primitive mechanism still works; the
question is whether to package it at the component layer at all or leave
it as a recipe.
---
 .../components/image/GalleryImage.vue         |  34 ----
 .../src/examples/components/image/gallery.vue |  70 --------
 .../src/pages/components/semantic/image.md    |  48 +-----
 packages/0/src/components/Image/ImageImg.vue  |   8 -
 packages/0/src/components/Image/ImageRoot.vue |  14 +-
 packages/0/src/components/Image/ImageSwap.vue | 162 ------------------
 packages/0/src/components/Image/index.test.ts | 128 --------------
 packages/0/src/components/Image/index.ts      |  19 --
 packages/0/src/maturity.json                  |   3 -
 9 files changed, 3 insertions(+), 483 deletions(-)
 delete mode 100644 apps/docs/src/examples/components/image/GalleryImage.vue
 delete mode 100644 apps/docs/src/examples/components/image/gallery.vue
 delete mode 100644 packages/0/src/components/Image/ImageSwap.vue

diff --git a/apps/docs/src/examples/components/image/GalleryImage.vue b/apps/docs/src/examples/components/image/GalleryImage.vue
deleted file mode 100644
index b184d5245..000000000
--- a/apps/docs/src/examples/components/image/GalleryImage.vue
+++ /dev/null
@@ -1,34 +0,0 @@
-<script setup lang="ts">
-  import { Image } from '@vuetify/v0'
-
-  defineProps<{
-    src: string
-    alt: string
-    mode: 'img' | 'swap'
-  }>()
-</script>
-
-<template>
-  <Image.Root
-    class="w-full aspect-4/3 bg-surface-tint rounded overflow-hidden relative"
-    :src
-  >
-    <Image.Img
-      :alt
-      class="w-full h-full object-cover opacity-0 transition-opacity duration-500 data-[state=loaded]:opacity-100 data-[has-previous]:opacity-100"
-    />
-
-    <Image.Swap
-      v-if="mode === 'swap'"
-      class="object-cover transition-opacity duration-500 data-[state=leaving]:opacity-0"
-    />
-
-    <Image.Placeholder class="absolute inset-0 flex items-center justify-center">
-      <div class="w-full h-full bg-surface-tint animate-pulse" />
-    </Image.Placeholder>
-
-    <Image.Fallback class="absolute inset-0 flex items-center justify-center bg-error-container text-on-error-container text-sm">
-      Failed to load
-    </Image.Fallback>
-  </Image.Root>
-</template>
diff --git a/apps/docs/src/examples/components/image/gallery.vue b/apps/docs/src/examples/components/image/gallery.vue
deleted file mode 100644
index 6d4e2e7d4..000000000
--- a/apps/docs/src/examples/components/image/gallery.vue
+++ /dev/null
@@ -1,70 +0,0 @@
-<script setup lang="ts">
-  import GalleryImage from './GalleryImage.vue'
-  import { shallowRef } from 'vue'
-
-  const photos = [
-    { id: 1, src: 'https://picsum.photos/seed/gallery-1/600/450', alt: 'Photo 1' },
-    { id: 2, src: 'https://picsum.photos/seed/gallery-2/600/450', alt: 'Photo 2' },
-    { id: 3, src: 'https://picsum.photos/seed/gallery-3/600/450', alt: 'Photo 3' },
-    { id: 4, src: 'https://picsum.photos/seed/gallery-4/600/450', alt: 'Photo 4' },
-  ]
-
-  const index = shallowRef(0)
-  function current () {
-    return photos[index.value]!
-  }
-
-  function onNext () {
-    index.value = (index.value + 1) % photos.length
-  }
-
-  function onPrev () {
-    index.value = (index.value - 1 + photos.length) % photos.length
-  }
-</script>
-
-<template>
-  <div class="flex flex-col gap-4 w-full max-w-4xl mx-auto">
-    <div class="grid grid-cols-1 sm:grid-cols-2 gap-4">
-      <div class="flex flex-col gap-2">
-        <span class="text-xs font-semibold text-on-surface-variant uppercase tracking-wide">
-          Image.Img
-        </span>
-        <GalleryImage :alt="current().alt" mode="img" :src="current().src" />
-        <p class="text-xs text-on-surface-variant">
-          Flashes the placeholder between photos.
-        </p>
-      </div>
-
-      <div class="flex flex-col gap-2">
-        <span class="text-xs font-semibold text-on-surface-variant uppercase tracking-wide">
-          Image.Swap
-        </span>
-        <GalleryImage :alt="current().alt" mode="swap" :src="current().src" />
-        <p class="text-xs text-on-surface-variant">
-          Keeps the previous photo visible, then crossfades.
-        </p>
-      </div>
-    </div>
-
-    <div class="flex items-center justify-center gap-4">
-      <button
-        class="px-3 py-1 bg-primary text-on-primary rounded text-sm"
-        @click="onPrev"
-      >
-        Previous
-      </button>
-
-      <span class="text-sm text-on-surface-variant">
-        {{ index + 1 }} / {{ photos.length }}
-      </span>
-
-      <button
-        class="px-3 py-1 bg-primary text-on-primary rounded text-sm"
-        @click="onNext"
-      >
-        Next
-      </button>
-    </div>
-  </div>
-</template>
diff --git a/apps/docs/src/pages/components/semantic/image.md b/apps/docs/src/pages/components/semantic/image.md
index 608842951..a0de5e627 100644
--- a/apps/docs/src/pages/components/semantic/image.md
+++ b/apps/docs/src/pages/components/semantic/image.md
@@ -25,7 +25,7 @@ Headless image component with state-driven placeholder and error fallback. Track
 
 ## Usage
 
-`Image.Root` owns the loading state machine via `useImage`. `Image.Img` renders the image element and reports load and error events to the context. `Image.Placeholder` is shown while idle or loading; `Image.Fallback` is shown on error. `Image.Swap` is a drop-in alternative to `Image.Img` that crossfades between sources when `src` changes — see the [gallery example](#gallery-navigation-with-image-swap).
+`Image.Root` owns the loading state machine via `useImage`. `Image.Img` renders the image element and reports load and error events to the context. `Image.Placeholder` is shown while idle or loading; `Image.Fallback` is shown on error.
 
 ::: example
 /components/image/basic
@@ -141,47 +141,6 @@ The `<source>` children are fully browser-driven — `Image.Img` never sees thei
 
 :::
 
-::: example
-/components/image/GalleryImage.vue 1
-/components/image/gallery.vue 2
-
-### Gallery navigation with Image.Swap
-
-Add `Image.Swap` alongside `Image.Img` inside `Image.Root` when navigating between already-loaded sources should never flash the placeholder. `Image.Img` remains the current image; `Image.Swap` is a transient overlay that mounts with the previous source during a src change and fades out once the new source loads. Until the new image is ready, the old image stays on screen via the overlay — the user never sees blank space between photos.
-
-```mermaid "Source transition"
-flowchart LR
-  Change["src changes<br/>(Root.src = newUrl)"]
-  Capture["Image.Swap captures oldUrl<br/>context.hasPrevious = true"]
-  Mount["Image.Swap mounts<br/>overlay img at opacity 1"]
-  Load["Image.Img.onload"]
-  Leave["context.hasPrevious = false<br/>overlay enters leaving"]
-  Fade["crossfade:<br/>overlay opacity 1 → 0<br/>Image.Img stays opacity 1"]
-  Unmount["transitionend<br/>done() fires<br/>overlay unmounts"]
-
-  Change --> Capture --> Mount --> Load --> Leave --> Fade --> Unmount
-```
-
-Reach for this pattern whenever the user can navigate between preloaded sources — image galleries, photo viewers, product thumbnails reacting to a color picker, or anywhere a `v-model` drives `src`. Without `Image.Swap`, each navigation resets the state machine to `loading`; `Image.Img` fades out, the placeholder shows until the next image loads, producing a visible pop. `Image.Swap` holds the previous image in DOM through the load window so the transition stays continuous.
-
-A few details worth knowing:
-
-- **`Image.Swap` adds behavior; it doesn't replace `Image.Img`** — the two are siblings inside `Image.Root`. `Image.Img` renders the current image; `Image.Swap` renders the overlay only during a swap. Without `Image.Swap`, `Image.Img` behaves exactly as usual.
-- **Initial load: no overlay** — there's no previous source on first mount, so `Image.Swap` stays unmounted. The placeholder shows while `Image.Img` loads the first source. Subsequent src changes engage the overlay.
-- **Built on the Presence primitive** — the overlay's mount lifecycle (mounted → leaving → unmounted) is managed by v0's `Presence` composable. CSS targets `data-state='leaving'` for the exit transition; `transitionend` on the overlay element calls `done()` to finalize the unmount. No `setTimeout`, no manual cleanup.
-- **Pin `Image.Img`'s opacity with `data-[has-previous]`** — during the hold window the current image's `data-state` is still `'loading'`, and once the load fires both layers transition simultaneously. Without `data-[has-previous]:opacity-100` on `Image.Img`, the two simultaneous fades show background bleed-through in the middle of the crossfade. `Image.Swap` sets `context.hasPrevious` to `true` while active, which propagates to `Image.Img` as `data-has-previous="true"`. Treat the pin rule as required.
-- **`Image.Swap`'s class must include at least one CSS transition** — `done()` is driven by `transitionend` on the overlay element. If the class has no CSS transition at all, the event never fires and the overlay leaks in the DOM. Opacity is the usual choice; transform, filter, or any other transitioned property works equivalently.
-- **Error state** — if the new image errors, the overlay stays visible underneath and `Image.Fallback` overlays it as usual. Call `retry()` from the Root slot props or the Fallback slot props to re-attempt the same source.
-
-Not something to add when you don't need it — if a given `Image.Root` never changes `src` after the first load (single content image, hero banner, avatar), omit `Image.Swap` for simpler DOM.
-
-| File | Role |
-|------|------|
-| `GalleryImage.vue` | Reusable wrapper — `Image.Root` with `Image.Img`, optional `Image.Swap`, plus `Image.Placeholder` and `Image.Fallback` overlays |
-| `gallery.vue` | Entry point with Previous/Next navigation rendering `Image.Img` alone on the left and `Image.Img + Image.Swap` on the right for comparison |
-
-:::
-
 ## Recipes
 
 ### Hero image with high priority
@@ -248,7 +207,6 @@ Slot props (`status`, `isLoaded`, etc.) remain available for the rare cases wher
 | Element | ARIA / behavior |
 | - | - |
 | `Image.Img` | `role="img"`, accepts `alt` for accessible name |
-| `Image.Swap` | Overlay `<img>` is marked `aria-hidden="true"` — it's a transient visual layer. Accessible image semantics come from sibling `Image.Img` |
 | `Image.Placeholder` | `aria-hidden="true"` — placeholder is decorative |
 | `Image.Fallback` | `role="img"` — provide alternate text inside the slot |
 
@@ -274,10 +232,6 @@ Always set `width` and `height` on `Image.Img`. The browser uses these to reserv
 
 Yes — set `renderless` on both `Image.Root` and `Image.Img`, then compose them inside a native `<picture>` element. See the picture example.
 
-??? When should I add `Image.Swap`?
-
-Add `Image.Swap` as a sibling of `Image.Img` inside `Image.Root` when the `src` on `Image.Root` can change to a different URL *after* the first image has loaded, and you want to avoid flashing the placeholder between transitions — gallery navigation, product variant thumbnails, anywhere a `v-model` drives `src`. Omit it for single-source content images where `src` never changes. Unlike `Image.Img`, `Image.Swap` isn't an image element on its own — it's a transient overlay that only mounts during a source change.
-
 ??? How do I fade in once the image loads?
 
 Style against the `data-state` attribute that every Image sub-component exposes. Using data attributes keeps the transition CSS-only — no slot-prop threading required.
diff --git a/packages/0/src/components/Image/ImageImg.vue b/packages/0/src/components/Image/ImageImg.vue
index 0ee4a1e5f..17836c29a 100644
--- a/packages/0/src/components/Image/ImageImg.vue
+++ b/packages/0/src/components/Image/ImageImg.vue
@@ -64,11 +64,6 @@
     isLoaded: boolean
     /** Current loading status. */
     status: ImageStatus
-    /**
-     * Whether an `Image.Swap` overlay is currently covering this img.
-     * Used to pin opacity through a crossfade.
-     */
-    hasPrevious: boolean
     /** Attributes to bind to the image element. */
     attrs: {
       'role': 'img'
@@ -84,7 +79,6 @@
       'loading': 'eager' | 'lazy' | undefined
       'fetchpriority': 'high' | 'low' | 'auto' | undefined
       'data-state': ImageStatus
-      'data-has-previous': true | undefined
       'onLoad': (e: Event) => void
       'onError': (e: Event) => void
     }
@@ -137,7 +131,6 @@
   const slotProps = toRef((): ImageImgSlotProps => ({
     isLoaded: context.isLoaded.value,
     status: context.status.value,
-    hasPrevious: context.hasPrevious.value,
     attrs: {
       'role': 'img',
       'src': context.source.value,
@@ -152,7 +145,6 @@
       loading,
       fetchpriority,
       'data-state': context.status.value,
-      'data-has-previous': context.hasPrevious.value || undefined,
       onLoad,
       onError,
     },
diff --git a/packages/0/src/components/Image/ImageRoot.vue b/packages/0/src/components/Image/ImageRoot.vue
index c0b3545f1..317dff840 100644
--- a/packages/0/src/components/Image/ImageRoot.vue
+++ b/packages/0/src/components/Image/ImageRoot.vue
@@ -28,7 +28,6 @@
   // Types
   import type { AtomExpose, AtomProps } from '#v0/components/Atom'
   import type { ImageStatus, UseImageReturn } from '#v0/composables/useImage'
-  import type { ShallowRef } from 'vue'
 
   export interface ImageRootProps extends AtomProps {
     /** Image source URL. Forwarded to Image.Img via context. */
@@ -68,14 +67,7 @@
     }
   }
 
-  export interface ImageContext extends UseImageReturn {
-    /**
-     * Mutable flag indicating whether an `Image.Swap` overlay is currently
-     * covering `Image.Img`. Set internally by `Image.Swap` during a source
-     * change; read by `Image.Img` to pin its opacity through the crossfade.
-     */
-    hasPrevious: ShallowRef<boolean>
-  }
+  export interface ImageContext extends UseImageReturn {}
 
   export const [useImageRoot, provideImageRoot] = createContext<ImageContext>()
 </script>
@@ -115,9 +107,7 @@
     eager: isIntersecting,
   })
 
-  const hasPrevious = shallowRef(false)
-
-  provideImageRoot(namespace, { ...image, hasPrevious })
+  provideImageRoot(namespace, image)
 
   const slotProps = toRef((): ImageRootSlotProps => ({
     status: image.status.value,
diff --git a/packages/0/src/components/Image/ImageSwap.vue b/packages/0/src/components/Image/ImageSwap.vue
deleted file mode 100644
index 9a7b8298e..000000000
--- a/packages/0/src/components/Image/ImageSwap.vue
+++ /dev/null
@@ -1,162 +0,0 @@
-/**
- * @module ImageSwap
- *
- * @see https://0.vuetifyjs.com/components/semantic/image
- *
- * @remarks
- * Overlay layer that keeps the previously loaded source visible while a new
- * one loads, then fades out once the new image is ready. Pair with `Image.Img`
- * inside `Image.Root` — `Image.Img` renders the current image, `Image.Swap`
- * covers it with the prior image during a source change.
- *
- * Uses the Presence primitive internally to manage mount lifecycle. Sets
- * `context.hasPrevious` while active so `Image.Img` can pin its opacity
- * through the crossfade via `data-[has-previous]`.
- *
- * On its own, `Image.Swap` renders nothing — it only mounts during the
- * transient window between a src change and the next successful load.
- */
-
-<script lang="ts">
-  // Globals
-  import { IN_BROWSER } from '#v0/constants/globals'
-
-  // Components
-  import { Atom } from '#v0/components/Atom'
-  import { Presence } from '#v0/components/Presence'
-
-  // Composables
-  import { useImageRoot } from './ImageRoot.vue'
-
-  // Utilities
-  import { shallowRef, toRef, watch } from 'vue'
-
-  // Types
-  import type { AtomProps } from '#v0/components/Atom'
-
-  export interface ImageSwapProps extends AtomProps {
-    /** Accessible alt text. Overlay is aria-hidden so this is typically cosmetic. */
-    alt?: string
-    /** Responsive image candidates. */
-    srcset?: string
-    /** Image sizes hint for responsive selection. */
-    sizes?: string
-    /** Intrinsic image width. */
-    width?: number | string
-    /** Intrinsic image height. */
-    height?: number | string
-    /** CORS request mode. */
-    crossorigin?: '' | 'anonymous' | 'use-credentials'
-    /** Referrer policy for the request. */
-    referrerpolicy?:
-      | 'origin'
-      | 'no-referrer'
-      | 'no-referrer-when-downgrade'
-      | 'origin-when-cross-origin'
-      | 'same-origin'
-      | 'strict-origin'
-      | 'strict-origin-when-cross-origin'
-      | 'unsafe-url'
-    /** How the browser should decode the image. */
-    decoding?: 'sync' | 'async' | 'auto'
-    /** Namespace for retrieving the Image context. */
-    namespace?: string
-  }
-
-  export interface ImageSwapSlotProps {
-    /** The source URL currently rendered by the overlay. */
-    source: string | undefined
-  }
-</script>
-
-<script setup lang="ts">
-  defineOptions({ name: 'ImageSwap' })
-
-  defineSlots<{
-    default: (props: ImageSwapSlotProps) => any
-  }>()
-
-  const {
-    as = 'img',
-    renderless,
-    alt,
-    srcset,
-    sizes,
-    width,
-    height,
-    crossorigin,
-    referrerpolicy,
-    decoding = 'async',
-    namespace = 'v0:image',
-  } = defineProps<ImageSwapProps>()
-
-  const context = useImageRoot(namespace)
-  const previousSource = shallowRef<string | undefined>()
-
-  watch(context.source, (newSource, oldSource) => {
-    // Only capture the previous source when no transition is in flight —
-    // navigating through several sources before any have loaded should
-    // keep the original previous visible rather than flashing through
-    // each intermediate URL. Skipping when newSource is falsy is
-    // intentional: clearing src degrades to a hard swap since a cleared
-    // src means the consumer has unmounted the logical image.
-    if (oldSource && newSource && newSource !== oldSource && !context.hasPrevious.value) {
-      previousSource.value = oldSource
-      context.hasPrevious.value = true
-    }
-  })
-
-  watch(context.isLoaded, loaded => {
-    if (!loaded || !context.hasPrevious.value) return
-    // Defer the leaving flip by one animation frame so the browser commits
-    // the 'mounted' state before transitioning — cached srcs load fast
-    // enough that Vue would otherwise batch mount + leave into one render.
-    if (IN_BROWSER) {
-      requestAnimationFrame(() => {
-        context.hasPrevious.value = false
-      })
-    } else {
-      context.hasPrevious.value = false
-    }
-  })
-
-  function onTransitionEnd (_e: Event, done: () => void) {
-    // Accept any transitionend; consumers may animate transform/filter/etc.
-    // Requires at least one CSS transition on the element so the event fires.
-    done()
-    previousSource.value = undefined
-  }
-
-  const slotProps = toRef((): ImageSwapSlotProps => ({
-    source: previousSource.value,
-  }))
-</script>
-
-<template>
-  <Presence
-    v-slot="{ attrs: presenceAttrs, done }"
-    v-model="context.hasPrevious.value"
-    :immediate="false"
-  >
-    <Atom
-      v-bind="presenceAttrs"
-      :alt
-      aria-hidden="true"
-      :as
-      :crossorigin
-      :decoding
-      :height
-      :referrerpolicy
-      :renderless
-      role="img"
-      :sizes
-      :src="previousSource"
-      :srcset
-      :style="{ position: 'absolute', inset: 0, width: '100%', height: '100%' }"
-      :width
-      @transitionend="onTransitionEnd($event, done)"
-    >
-      <slot v-bind="slotProps" />
-    </Atom>
-  </Presence>
-</template>
diff --git a/packages/0/src/components/Image/index.test.ts b/packages/0/src/components/Image/index.test.ts
index be8fe3a67..d4e5d0b3b 100644
--- a/packages/0/src/components/Image/index.test.ts
+++ b/packages/0/src/components/Image/index.test.ts
@@ -471,133 +471,5 @@ describe('image', () => {
       expect(html).toBeTruthy()
       expect(html).toContain('img')
     })
-
-    it('should render Image.Img + Image.Swap to string without errors', async () => {
-      const app = createSSRApp(defineComponent({
-        render: () => h(Image.Root, { src: '/photo.jpg' }, () => [
-          h(Image.Img, { alt: 'Test' }),
-          h(Image.Swap, { alt: 'Test' }),
-        ]),
-      }))
-
-      const html = await renderToString(app)
-      expect(html).toBeTruthy()
-      expect(html).toContain('img')
-    })
-  })
-
-  describe('swap', () => {
-    it('should render nothing on initial load when no swap is in flight', () => {
-      const wrapper = mount(Image.Root, {
-        props: { src: '/a.jpg' },
-        slots: {
-          default: () => [
-            h(Image.Img, { alt: 'Test' }),
-            h(Image.Swap, { alt: 'Test' }),
-          ],
-        },
-      })
-
-      // Only Image.Img's <img>; Image.Swap stays unmounted until a swap starts
-      expect(wrapper.findAll('img')).toHaveLength(1)
-      expect(wrapper.find('img').attributes('src')).toBe('/a.jpg')
-    })
-
-    it('should mount the previous img when src changes after a successful load', async () => {
-      const wrapper = mount(Image.Root, {
-        props: { src: '/a.jpg' },
-        slots: {
-          default: () => [
-            h(Image.Img, { alt: 'Test' }),
-            h(Image.Swap, { alt: 'Test' }),
-          ],
-        },
-      })
-
-      // Load the first source
-      await wrapper.find('img').trigger('load')
-      await nextTick()
-
-      // Swap to a new source
-      await wrapper.setProps({ src: '/b.jpg' })
-      await nextTick()
-
-      const imgs = wrapper.findAll('img')
-      expect(imgs).toHaveLength(2)
-      const srcs = imgs.map(i => i.attributes('src'))
-      expect(srcs).toContain('/a.jpg')
-      expect(srcs).toContain('/b.jpg')
-    })
-
-    it('should set data-has-previous on Image.Img while a swap is active', async () => {
-      const wrapper = mount(Image.Root, {
-        props: { src: '/a.jpg' },
-        slots: {
-          default: () => [
-            h(Image.Img, { alt: 'Test' }),
-            h(Image.Swap, { alt: 'Test' }),
-          ],
-        },
-      })
-
-      await wrapper.find('img').trigger('load')
-      await nextTick()
-
-      await wrapper.setProps({ src: '/b.jpg' })
-      await nextTick()
-
-      const currentImg = wrapper.findAll('img').find(i => i.attributes('src') === '/b.jpg')!
-      expect(currentImg.attributes('data-has-previous')).toBe('true')
-    })
-
-    it('should not mount when src changes without a prior successful load', async () => {
-      const wrapper = mount(Image.Root, {
-        props: { src: '/a.jpg' },
-        slots: {
-          default: () => [
-            h(Image.Img, { alt: 'Test' }),
-            h(Image.Swap, { alt: 'Test' }),
-          ],
-        },
-      })
-
-      // Change src immediately without firing load on /a.jpg first — still
-      // counts as "no previous loaded", so Swap should still capture and mount
-      // (oldSrc is defined, just not loaded). This tests that the capture
-      // happens based on src change, not load completion.
-      await wrapper.setProps({ src: '/b.jpg' })
-      await nextTick()
-
-      // Two imgs — current + previous overlay
-      expect(wrapper.findAll('img').length).toBeGreaterThanOrEqual(1)
-    })
-
-    it('should expose hasPrevious in Image.Img slot props (renderless mode)', async () => {
-      let imgProps: any
-      const wrapper = mount(Image.Root, {
-        props: { src: '/a.jpg' },
-        slots: {
-          default: () => [
-            h(Image.Img, { alt: 'Test', renderless: true }, {
-              default: (props: any) => {
-                imgProps = props
-                return h('img', { ...props.attrs })
-              },
-            }),
-            h(Image.Swap, { alt: 'Test' }),
-          ],
-        },
-      })
-
-      expect(imgProps.hasPrevious).toBe(false)
-
-      await wrapper.find('img').trigger('load')
-      await nextTick()
-
-      await wrapper.setProps({ src: '/b.jpg' })
-      await nextTick()
-
-      expect(imgProps.hasPrevious).toBe(true)
-    })
   })
 })
diff --git a/packages/0/src/components/Image/index.ts b/packages/0/src/components/Image/index.ts
index d23422a12..96459a827 100644
--- a/packages/0/src/components/Image/index.ts
+++ b/packages/0/src/components/Image/index.ts
@@ -1,7 +1,6 @@
 export { default as ImageFallback } from './ImageFallback.vue'
 export { default as ImageImg } from './ImageImg.vue'
 export { default as ImagePlaceholder } from './ImagePlaceholder.vue'
-export { default as ImageSwap } from './ImageSwap.vue'
 export { provideImageRoot, useImageRoot } from './ImageRoot.vue'
 
 export { default as ImageRoot } from './ImageRoot.vue'
@@ -9,7 +8,6 @@ export { default as ImageRoot } from './ImageRoot.vue'
 export type { ImageFallbackProps, ImageFallbackSlotProps } from './ImageFallback.vue'
 export type { ImageImgEmits, ImageImgProps, ImageImgSlotProps } from './ImageImg.vue'
 export type { ImagePlaceholderProps, ImagePlaceholderSlotProps } from './ImagePlaceholder.vue'
-export type { ImageSwapEmits, ImageSwapProps, ImageSwapSlotProps } from './ImageSwap.vue'
 export type { ImageContext, ImageRootProps, ImageRootSlotProps } from './ImageRoot.vue'
 
 // Components
@@ -17,7 +15,6 @@ import Fallback from './ImageFallback.vue'
 import Img from './ImageImg.vue'
 import Placeholder from './ImagePlaceholder.vue'
 import Root from './ImageRoot.vue'
-import Swap from './ImageSwap.vue'
 
 /**
  * Image component with sub-components for managing image loading lifecycle.
@@ -86,20 +83,4 @@ export const Image = {
    * ```
    */
   Fallback,
-  /**
-   * Source-swapping image element. Keeps the previously loaded source
-   * visible while a new one loads, then crossfades via opacity. Drop-in
-   * replacement for `Image.Img` when navigating between already-loaded
-   * sources (carousels, galleries).
-   *
-   * @see https://0.vuetifyjs.com/components/semantic/image
-   *
-   * @example
-   * ```vue
-   * <Image.Root src="/photo-1.jpg">
-   *   <Image.Swap alt="Gallery photo" img-class="w-full h-full object-cover" />
-   * </Image.Root>
-   * ```
-   */
-  Swap,
 }
diff --git a/packages/0/src/maturity.json b/packages/0/src/maturity.json
index d62548630..605d2456a 100644
--- a/packages/0/src/maturity.json
+++ b/packages/0/src/maturity.json
@@ -203,7 +203,6 @@
     },
     "useImage": {
       "level": "preview",
-      "since": "0.2.0",
       "category": "system"
     },
     "useIntersectionObserver": {
@@ -327,7 +326,6 @@
   "components": {
     "AspectRatio": {
       "level": "preview",
-      "since": "0.2.0",
       "category": "primitives"
     },
     "Atom": {
@@ -511,7 +509,6 @@
     },
     "Image": {
       "level": "preview",
-      "since": "0.2.0",
       "category": "semantic"
     },
     "Overflow": {

From 278c4380f5cbd52506c4cb82c63b15224d986131 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Fri, 17 Apr 2026 13:28:30 -0500
Subject: [PATCH 28/35] test(Image): close remaining coverage gaps on Root and
 Img
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- ImageRoot: warn-when-lazy-and-renderless guard (lines 97-98 were
  previously untested — covered with a console.warn spy that asserts
  the expected message)
- ImageImg: default-slot rendering in renderless mode (line 160 — the
  slot only renders when Atom is non-self-closing or renderless)

Brings Image + AspectRatio + useImage to 100% statements / branches /
lines across the board. Remaining gap is an intentional no-op callback
passed to useIntersectionObserver that happy-dom cannot exercise.
---
 packages/0/src/components/Image/index.test.ts | 34 +++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/packages/0/src/components/Image/index.test.ts b/packages/0/src/components/Image/index.test.ts
index d4e5d0b3b..0c53b6a2b 100644
--- a/packages/0/src/components/Image/index.test.ts
+++ b/packages/0/src/components/Image/index.test.ts
@@ -137,6 +137,20 @@ describe('image', () => {
           })
         }).not.toThrow()
       })
+
+      it('should warn when lazy is combined with renderless', () => {
+        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+        mount(Image.Root, {
+          props: { src: '/photo.jpg', lazy: true, renderless: true },
+          slots: { default: () => h('span') },
+        })
+
+        expect(warnSpy).toHaveBeenCalledTimes(1)
+        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('`lazy` requires a wrapper element'))
+
+        warnSpy.mockRestore()
+      })
     })
   })
 
@@ -216,6 +230,26 @@ describe('image', () => {
         expect(img.attributes('role')).toBe('img')
       })
 
+      it('should render default slot when in renderless mode', () => {
+        let captured: any
+        const wrapper = mount(Image.Root, {
+          props: { src: '/photo.jpg' },
+          slots: {
+            default: () => h(Image.Img, { alt: 'Test', renderless: true }, {
+              default: (props: any) => {
+                captured = props
+                return h('img', { ...props.attrs, class: 'consumer-img' })
+              },
+            }),
+          },
+        })
+
+        expect(captured).toBeDefined()
+        expect(captured.attrs.src).toBe('/photo.jpg')
+        expect(captured.attrs.role).toBe('img')
+        expect(wrapper.find('img.consumer-img').exists()).toBe(true)
+      })
+
       it('should propagate class and style to the img element', () => {
         const wrapper = mount(Image.Root, {
           props: { src: '/photo.jpg' },

From 6c763d0e58bd0114318e048e2062122d9bbd2853 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Fri, 17 Apr 2026 13:30:39 -0500
Subject: [PATCH 29/35] docs(useImage): show Usage as a full .vue SFC instead
 of a ts fence

---
 .../src/pages/composables/system/use-image.md | 32 ++++++++++++-------
 1 file changed, 20 insertions(+), 12 deletions(-)

diff --git a/apps/docs/src/pages/composables/system/use-image.md b/apps/docs/src/pages/composables/system/use-image.md
index 6409e3d3e..d7420bf7f 100644
--- a/apps/docs/src/pages/composables/system/use-image.md
+++ b/apps/docs/src/pages/composables/system/use-image.md
@@ -28,18 +28,26 @@ Tracks image loading state as a reactive state machine with idle, loading, loade
 The `useImage` composable owns the loading lifecycle for a single image source.
 Bind the returned `source`, `onLoad`, and `onError` to a plain image element.
 
-```ts collapse no-filename
-import { toRef } from 'vue'
-import { useImage } from '@vuetify/v0'
-
-const props = defineProps<{ src: string }>()
-
-const { source, isLoaded, isError, onLoad, onError, retry } = useImage({
-  src: toRef(() => props.src),
-})
-
-// In template:
-// <img :src="source" @load="onLoad" @error="onError" />
+```vue collapse
+<script setup lang="ts">
+  import { toRef } from 'vue'
+  import { useImage } from '@vuetify/v0'
+
+  const props = defineProps<{ src: string, alt: string }>()
+
+  const { source, isLoaded, isError, onLoad, onError, retry } = useImage({
+    src: toRef(() => props.src),
+  })
+</script>
+
+<template>
+  <img
+    :alt
+    :src="source"
+    @load="onLoad"
+    @error="onError"
+  >
+</template>
 ```
 
 ::: example

From fca806b9bd840b76e8e68b4147550566141c64f9 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Fri, 17 Apr 2026 13:39:31 -0500
Subject: [PATCH 30/35] fix(useImage): force browser to refetch on retry by
 cycling through idle
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Setting status directly from 'error' to 'loading' kept source pinned
to the same URL, and browsers skip the re-request when an <img>'s src
attribute is assigned its existing value. Retries visibly hung in the
loading state: no new network request, no error/load event, forever.

Cycle status through 'idle' on the next tick so source briefly returns
undefined, clearing the <img>'s src attribute. When status flips back
to 'loading' the following tick, source resolves to the URL again and
the browser treats it as a fresh request.

Updated tests to reflect the new two-tick transition — retry() is
still fire-and-forget from the caller's perspective, but observed
state now transitions error → idle → loading across one nextTick.
Verified in the docs dev preview: the retry button on the broken
photo now completes the cycle and returns to error state as expected.
---
 packages/0/src/components/Image/index.test.ts |  2 ++
 .../0/src/composables/useImage/index.test.ts  | 24 +++++++++++++++++--
 packages/0/src/composables/useImage/index.ts  | 13 ++++++++--
 3 files changed, 35 insertions(+), 4 deletions(-)

diff --git a/packages/0/src/components/Image/index.test.ts b/packages/0/src/components/Image/index.test.ts
index 0c53b6a2b..55b202120 100644
--- a/packages/0/src/components/Image/index.test.ts
+++ b/packages/0/src/components/Image/index.test.ts
@@ -473,6 +473,8 @@ describe('image', () => {
       await nextTick()
 
       fallbackProps.retry()
+      // retry cycles through 'idle' briefly to force the browser refetch
+      await nextTick()
       await nextTick()
 
       expect(rootProps.status).toBe('loading')
diff --git a/packages/0/src/composables/useImage/index.test.ts b/packages/0/src/composables/useImage/index.test.ts
index 50c48a6f0..ba7900ccc 100644
--- a/packages/0/src/composables/useImage/index.test.ts
+++ b/packages/0/src/composables/useImage/index.test.ts
@@ -67,22 +67,42 @@ describe('useImage', () => {
       expect(image.isLoading.value).toBe(false)
     })
 
-    it('should reset to loading on retry when eager is true', () => {
+    it('should reset to loading on retry when eager is true', async () => {
       const image = useImage({ src: '/photo.jpg' })
 
       image.onError()
       image.retry()
 
+      // Cycles through 'idle' for one tick to force the browser to refetch
+      expect(image.status.value).toBe('idle')
+      await nextTick()
+
       expect(image.status.value).toBe('loading')
       expect(image.isError.value).toBe(false)
     })
 
-    it('should reset to idle on retry when eager is false', () => {
+    it('should briefly clear source during retry so the browser refetches the same URL', async () => {
+      const image = useImage({ src: '/photo.jpg' })
+
+      image.onError()
+      expect(image.source.value).toBe('/photo.jpg')
+
+      image.retry()
+      expect(image.source.value).toBeUndefined()
+
+      await nextTick()
+      expect(image.source.value).toBe('/photo.jpg')
+    })
+
+    it('should reset to idle on retry when eager is false', async () => {
       const image = useImage({ src: '/photo.jpg', eager: false })
 
       image.onError()
       image.retry()
 
+      expect(image.status.value).toBe('idle')
+      await nextTick()
+
       expect(image.status.value).toBe('idle')
     })
   })
diff --git a/packages/0/src/composables/useImage/index.ts b/packages/0/src/composables/useImage/index.ts
index 05938cc16..3080a78f9 100644
--- a/packages/0/src/composables/useImage/index.ts
+++ b/packages/0/src/composables/useImage/index.ts
@@ -19,7 +19,7 @@
  */
 
 // Utilities
-import { onScopeDispose, shallowReadonly, shallowRef, toRef, toValue, watch } from 'vue'
+import { nextTick, onScopeDispose, shallowReadonly, shallowRef, toRef, toValue, watch } from 'vue'
 
 // Types
 import type { MaybeRefOrGetter, Ref, ShallowRef } from 'vue'
@@ -135,7 +135,16 @@ export function useImage (options: UseImageOptions): UseImageReturn {
   }
 
   function retry () {
-    status.value = toValue(eager) ? 'loading' : 'idle'
+    // Cycle through 'idle' on the next tick so `source` briefly returns
+    // undefined, forcing the <img> to clear its src attribute. Without
+    // this, browsers skip the re-request when the new src equals the old
+    // src — the retry would appear to "hang" in the loading state because
+    // no load/error event ever fires for the same cached URL.
+    const resumeAs = toValue(eager) ? 'loading' : 'idle'
+    status.value = 'idle'
+    nextTick(() => {
+      status.value = resumeAs
+    })
   }
 
   const stopEager = watch(

From 2ee196930dccb90e90d2a3c7e9f33abb21a629c6 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Fri, 17 Apr 2026 13:39:31 -0500
Subject: [PATCH 31/35] docs(useImage): move basic example under Examples with
 substantive prose

---
 .../src/pages/composables/system/use-image.md   | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/apps/docs/src/pages/composables/system/use-image.md b/apps/docs/src/pages/composables/system/use-image.md
index d7420bf7f..b920f3962 100644
--- a/apps/docs/src/pages/composables/system/use-image.md
+++ b/apps/docs/src/pages/composables/system/use-image.md
@@ -50,10 +50,6 @@ Bind the returned `source`, `onLoad`, and `onError` to a plain image element.
 </template>
 ```
 
-::: example
-/composables/use-image/basic
-:::
-
 ## Architecture
 
 ```mermaid "useImage state machine"
@@ -79,6 +75,19 @@ stateDiagram-v2
 
 ## Examples
 
+::: example
+/composables/use-image/basic
+
+### Basic usage
+
+Wire `useImage` directly to a plain `<img>` element. The composable returns `source`, `onLoad`, `onError`, and four state refs — bind them to the element and you have the full load lifecycle for ~10 lines of setup.
+
+Reach for raw `useImage` when the image lives in markup the `Image` compound can't produce — hand-rolled `<picture>`, a canvas-adjacent element, third-party wrappers, or anywhere you want the state machine without v0's DOM. For typical content images, prefer `Image.Root` + `Image.Img` which packages the same composable with built-in placeholder and fallback slots.
+
+The example surfaces the `status` ref as a live label and includes buttons that swap between a working URL and a known-broken URL, so the transitions `idle → loading → loaded | error` play out on click.
+
+:::
+
 ::: example
 /composables/use-image/useLazyImage.ts 1
 /composables/use-image/LazyImage.vue 2

From 2bedadbb51b89f44a6c79307bbece8d35b9accaa Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Fri, 17 Apr 2026 14:00:22 -0500
Subject: [PATCH 32/35] docs(useImage): simulate flaky network in the retry
 example
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Each click on Retry now has a 25% chance of swapping in the real src
(success) and a 75% chance of re-requesting the broken URL (another
failure). When a retry lands on success, the image is loaded and the
retry UI disappears — matching real-world behavior where a transient
failure eventually resolves after one or more attempts.

Simplified retry.vue to a single RetryableImage card — with the flaky
behavior baked into the component, the previous side-by-side layout
(one working, one broken) no longer illustrated distinct stories.
---
 .../composables/use-image/RetryableImage.vue       | 14 ++++++++++++--
 .../src/examples/composables/use-image/retry.vue   |  9 ++-------
 .../docs/src/pages/composables/system/use-image.md |  4 ++--
 3 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/apps/docs/src/examples/composables/use-image/RetryableImage.vue b/apps/docs/src/examples/composables/use-image/RetryableImage.vue
index 0aaff96b2..e9227b1f4 100644
--- a/apps/docs/src/examples/composables/use-image/RetryableImage.vue
+++ b/apps/docs/src/examples/composables/use-image/RetryableImage.vue
@@ -7,15 +7,25 @@
     alt: string
   }>()
 
+  const BROKEN = 'https://invalid.example/missing.jpg'
   const attempts = shallowRef(0)
+  const currentSrc = shallowRef(BROKEN)
 
   const { source, isLoaded, isError, onLoad, onError, retry } = useImage({
-    src: toRef(() => props.src),
+    src: toRef(() => currentSrc.value),
   })
 
   function onRetry () {
     attempts.value++
-    retry()
+    // Simulate a flaky network: each retry has a 25% chance of succeeding.
+    // On success, swap the broken URL for the real one — the src change
+    // triggers a fresh fetch. Otherwise call retry() to re-attempt the
+    // existing (broken) URL.
+    if (Math.random() < 0.25) {
+      currentSrc.value = props.src
+    } else {
+      retry()
+    }
   }
 </script>
 
diff --git a/apps/docs/src/examples/composables/use-image/retry.vue b/apps/docs/src/examples/composables/use-image/retry.vue
index 90eac2a07..83b2d5741 100644
--- a/apps/docs/src/examples/composables/use-image/retry.vue
+++ b/apps/docs/src/examples/composables/use-image/retry.vue
@@ -3,15 +3,10 @@
 </script>
 
 <template>
-  <div class="grid grid-cols-1 sm:grid-cols-2 gap-4">
+  <div class="max-w-md mx-auto">
     <RetryableImage
-      alt="Working photo"
+      alt="Photo that sometimes loads"
       src="https://picsum.photos/seed/retry-ok/400/300"
     />
-
-    <RetryableImage
-      alt="Broken photo — click Retry"
-      src="https://invalid.example/missing.jpg"
-    />
   </div>
 </template>
diff --git a/apps/docs/src/pages/composables/system/use-image.md b/apps/docs/src/pages/composables/system/use-image.md
index b920f3962..5951c0f63 100644
--- a/apps/docs/src/pages/composables/system/use-image.md
+++ b/apps/docs/src/pages/composables/system/use-image.md
@@ -146,8 +146,8 @@ Not limited to user-facing retries — the same pattern works for programmatic r
 
 | File | Role |
 |------|------|
-| `RetryableImage.vue` | Wraps `useImage`, tracks an `attempts` counter, and renders a retry button inside an `isError` branch |
-| `retry.vue` | Demonstrates both a working source and a broken one side-by-side so the retry UX is visible without waiting for real failure |
+| `RetryableImage.vue` | Wraps `useImage`, tracks an `attempts` counter, and renders a retry button inside an `isError` branch. Simulates a flaky network: each click has a 25% chance of swapping in the real source (success) or re-requesting the broken one (another failure) |
+| `retry.vue` | Entry point rendering a single `RetryableImage` — click Retry repeatedly to watch the state cycle between `loading` and `error` until a retry happens to land on success |
 
 :::
 

From 86e917611f3fd1913356bde8fe3e5d31ca2cf236 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Fri, 17 Apr 2026 14:07:02 -0500
Subject: [PATCH 33/35] docs(Image): note retry in loadstart JSDoc and cover
 with a test
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ImageImgEmits.loadstart JSDoc omitted retry as a trigger, but retry
has always emitted it: retry() transitions status into 'loading'
(via 'idle' now, directly before) and the watcher fires on that
transition with context.source as the URL. Semantically correct —
a retry is a new network request and analytics should count it —
just under-documented. Add retry to the trigger list and back it
with a test so the contract is explicit.
---
 packages/0/src/components/Image/ImageImg.vue  |  5 +--
 packages/0/src/components/Image/index.test.ts | 32 +++++++++++++++++++
 2 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/packages/0/src/components/Image/ImageImg.vue b/packages/0/src/components/Image/ImageImg.vue
index 17836c29a..d72fbc37b 100644
--- a/packages/0/src/components/Image/ImageImg.vue
+++ b/packages/0/src/components/Image/ImageImg.vue
@@ -53,8 +53,9 @@
     error: [e: Event]
     /**
      * Synthesized event fired when the image transitions into the `loading`
-     * state (on initial mount if `eager`, on intersection if `lazy`, or when
-     * `src` changes). Emits the source URL that started loading.
+     * state: on initial mount if `eager`, on intersection if `lazy`, when
+     * `src` changes, or when `retry()` is called. Emits the source URL that
+     * started loading — analytics can treat every emit as one network request.
      */
     loadstart: [src: string]
   }
diff --git a/packages/0/src/components/Image/index.test.ts b/packages/0/src/components/Image/index.test.ts
index 55b202120..18a2674af 100644
--- a/packages/0/src/components/Image/index.test.ts
+++ b/packages/0/src/components/Image/index.test.ts
@@ -325,6 +325,38 @@ describe('image', () => {
 
         expect(onLoadstart).not.toHaveBeenCalled()
       })
+
+      it('should emit loadstart again when retry is called from Fallback', async () => {
+        const onLoadstart = vi.fn()
+        let fallbackProps: any
+        const wrapper = mount(Image.Root, {
+          props: { src: '/photo.jpg' },
+          slots: {
+            default: () => [
+              h(Image.Img, { alt: 'Test', onLoadstart }),
+              h(Image.Fallback as any, {}, (props: any) => {
+                fallbackProps = props
+                return 'Failed'
+              }),
+            ],
+          },
+        })
+
+        // Initial mount: one loadstart for the first fetch
+        expect(onLoadstart).toHaveBeenCalledTimes(1)
+
+        await wrapper.find('img').trigger('error')
+        await nextTick()
+
+        fallbackProps.retry()
+        // retry cycles through 'idle' briefly to force the browser refetch
+        await nextTick()
+        await nextTick()
+
+        // retry counts as a new network request — loadstart fires again
+        expect(onLoadstart).toHaveBeenCalledTimes(2)
+        expect(onLoadstart).toHaveBeenLastCalledWith('/photo.jpg')
+      })
     })
   })
 

From 06a3dd113aed7cfd4776908b952f2309528f42b5 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Fri, 17 Apr 2026 14:11:02 -0500
Subject: [PATCH 34/35] docs(useImage): replace 'Failed to load' text with a
 broken-image icon

---
 .../examples/composables/use-image/RetryableImage.vue  | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/apps/docs/src/examples/composables/use-image/RetryableImage.vue b/apps/docs/src/examples/composables/use-image/RetryableImage.vue
index e9227b1f4..980f693ee 100644
--- a/apps/docs/src/examples/composables/use-image/RetryableImage.vue
+++ b/apps/docs/src/examples/composables/use-image/RetryableImage.vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
   import { useImage } from '@vuetify/v0'
+  import { mdiImageBrokenVariant } from '@mdi/js'
   import { shallowRef, toRef } from 'vue'
 
   const props = defineProps<{
@@ -41,7 +42,14 @@
     >
 
     <template v-if="isError">
-      <span class="text-error text-sm">Failed to load</span>
+      <svg
+        aria-label="Image failed to load"
+        class="size-16 text-error"
+        role="img"
+        viewBox="0 0 24 24"
+      >
+        <path :d="mdiImageBrokenVariant" fill="currentColor" />
+      </svg>
       <span v-if="attempts > 0" class="text-xs text-on-surface-variant">
         Attempt {{ attempts + 1 }}
       </span>

From 3696932510b69910e4156a24fbf82c4b478be866 Mon Sep 17 00:00:00 2001
From: John Leider <john@vuetifyjs.com>
Date: Fri, 17 Apr 2026 14:47:14 -0500
Subject: [PATCH 35/35] docs(useImage): use a neutral broken-image icon in both
 error states

---
 .../composables/use-image/RetryableImage.vue        |  2 +-
 .../src/examples/composables/use-image/basic.vue    | 13 ++++++++++---
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/apps/docs/src/examples/composables/use-image/RetryableImage.vue b/apps/docs/src/examples/composables/use-image/RetryableImage.vue
index 980f693ee..a3eb48a8e 100644
--- a/apps/docs/src/examples/composables/use-image/RetryableImage.vue
+++ b/apps/docs/src/examples/composables/use-image/RetryableImage.vue
@@ -44,7 +44,7 @@
     <template v-if="isError">
       <svg
         aria-label="Image failed to load"
-        class="size-16 text-error"
+        class="size-24 text-on-surface-variant"
         role="img"
         viewBox="0 0 24 24"
       >
diff --git a/apps/docs/src/examples/composables/use-image/basic.vue b/apps/docs/src/examples/composables/use-image/basic.vue
index 3276ce7fe..5bf054530 100644
--- a/apps/docs/src/examples/composables/use-image/basic.vue
+++ b/apps/docs/src/examples/composables/use-image/basic.vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
   import { useImage } from '@vuetify/v0'
+  import { mdiImageBrokenVariant } from '@mdi/js'
   import { shallowRef } from 'vue'
 
   const src = shallowRef('https://picsum.photos/seed/v0/400/300')
@@ -31,9 +32,15 @@
       <span v-if="!isLoaded && !isError" class="text-on-surface-variant text-sm">
         Loading...
       </span>
-      <span v-if="isError" class="text-error text-sm">
-        Failed to load
-      </span>
+      <svg
+        v-if="isError"
+        aria-label="Image failed to load"
+        class="size-24 text-on-surface-variant"
+        role="img"
+        viewBox="0 0 24 24"
+      >
+        <path :d="mdiImageBrokenVariant" fill="currentColor" />
+      </svg>
     </div>
 
     <div class="flex gap-2">