use-image

Preload an image and track its loading state.


Package	`@vizejs/composable/use-image`
Own the source	`vize lib pull composable:use-image`
Runtime exports	`useImage`
Gzip budget	2048 B

Usage

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

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useImage`	media	experimental	deterministic-fallback	caller-managed	caller, reactive-scope	web, desktop	`window`	`tryOnScopeDispose`

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.

Member	Type	Description
`src`	`string`	Image URL.
`srcset`?	`string`	Responsive candidates.
`sizes`?	`string`	Responsive layout sizes.
`alt`?	`string`	Alternative text.
`crossOrigin`?	`"anonymous" \| "use-credentials"`	CORS mode.
`referrerPolicy`?	`ReferrerPolicy`	Referrer policy.
`loading`?	`"eager" \| "lazy"`	Loading strategy.
`decoding`?	`"sync" \| "async" \| "auto"`	Decoding hint.
`fetchPriority`?	`"high" \| "low" \| "auto"`	Fetch priority hint.
`width`?	`number`	Intrinsic width.
`height`?	`number`	Intrinsic height.

`ImageLike`

HTMLImageElement subset used by useImage.

Member	Type	Description
`src`	`string`	Image URL.
`srcset`	`string`	Responsive candidates.
`sizes`	`string`	Responsive layout sizes.
`alt`	`string`	Alternative text.
`crossOrigin`	`string \| null`	CORS mode.
`referrerPolicy`	`string`	Referrer policy.
`loading`	`string`	Loading strategy.
`decoding`	`string`	Decoding hint.
`fetchPriority`?	`string`	Fetch priority hint; absent in engines without priority hints.
`width`	`number`	Intrinsic width.
`height`	`number`	Intrinsic height.

`UseImageOptions`

Options for useImage.

Member	Type	Description
`immediate`?	`boolean`	Load when created and whenever the source changes.
`host`?	`MaybeRef<ImageHost \| null \| undefined>`	Image constructor for alternate runtimes and tests. A ref (not a getter) because the host is a constructor function.

`ImageControls`

Reactive state and actions returned by useImage.

Member	Type	Description
`status`	`Readonly<Ref<ImageStatus>>`	Loading state of the newest load.
`image`	`Readonly<ShallowRef<ImageLike \| undefined>>`	Most recently loaded image.
`error`	`Readonly<ShallowRef<Event \| undefined>>`	Error event of the newest load, cleared when a load starts.
`ready`	`ComputedRef<boolean>`	Whether the newest load succeeded.
`load`	`() => Promise<ImageLoadResult>`	Load the current source, superseding any pending load.