use-image

Preload an image and track its loading state.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { useImage } from "@vizejs/composable/use-image";

Try it

Show an avatar with a fallback

Load an image before showing it, and react to loading errors.

Open the interactive example

What to observe: The valid avatar reports Loaded 64 × 64. Choose Broken to see the fallback message.

The source can be a getter, so changing it starts a new load. status is idle, loading, loaded or error.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { ref } from "vue";
import { useImage } from "@vizejs/composable/use-image";

const avatars = {
  Valid: `data:image/svg+xml,${encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64"><rect width="64" height="64" fill="#42b883"/></svg>')}`,
  Broken: "data:image/png;base64,AAAA",
};
const choice = ref<keyof typeof avatars>("Valid");
const { status, image } = useImage(() => ({ src: avatars[choice.value] }));
</script>

<template>
  <div class="composable-example">
    <p>Show a placeholder until an avatar loads, and a fallback if it fails.</p>
    <label>
      Avatar source
      <select v-model="choice">
        <option>Valid</option>
        <option>Broken</option>
      </select>
    </label>
    <img v-if="status === 'loaded'" :src="avatars[choice]" alt="Avatar" width="64" height="64" />
    <output aria-live="polite">{{
      status === "loaded"
        ? `Loaded ${(image as HTMLImageElement | undefined)?.naturalWidth} × ${(image as HTMLImageElement | undefined)?.naturalHeight}`
        : status === "error"
          ? "Could not load the avatar; showing initials instead."
          : "Loading avatar…"
    }}</output>
  </div>
</template>

Runtime contract

API

useImage

Preload an image and track its loading state. A detached image is created for every source; the newest load wins, and superseded images have their listeners removed and their src cleared so the browser can abort the download. Use it to show a placeholder until the real image is decoded, or to validate URLs before rendering them. Server rendering: no image is created and status stays "idle". The pending load is cancelled when the owning reactive scope stops.

function useImage( source: MaybeRefOrGetter<ImageSource>, options: UseImageOptions = {}, ): ImageControls

const { ready } = useImage(() => ({ src: avatarUrl.value }));
// <img v-if="ready" :src="avatarUrl"> <Skeleton v-else />

Types

ImageSource

Image attributes accepted by useImage.

ImageLike

HTMLImageElement subset used by useImage.

UseImageOptions

Options for useImage.

ImageControls

Reactive state and actions returned by useImage.