useImage API

API reference for the useImage composable.

Explore these related pages for additional context and usage patterns.

Functions

(options: UseImageOptions) => UseImageReturn

Tracks image loading state as a reactive state machine.

MaybeRefOrGetter<string | undefined>

Image source URL. Changes trigger a reload.

MaybeRefOrGetter<boolean> | 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

Readonly<ShallowRef<ImageStatus>>

Current loading state.

Readonly<Ref<boolean, boolean>>

Whether the image has not yet started loading (eager is false).

Readonly<Ref<boolean, boolean>>

Whether the image is currently loading.

Readonly<Ref<boolean, boolean>>

Whether the image has loaded successfully.

Readonly<Ref<boolean, boolean>>

Whether the image failed to load.

Readonly<Ref<string | undefined, string | undefined>>

Gated source URL. Resolves to `undefined` while idle, otherwise the current `src` value. Bind directly to the `<img>` `src` attribute.

(e?: Event) => void

Bind to the `<img>` `load` event.

(e?: Event) => void

Bind to the `<img>` `error` event.

() => void

Reset status back to `loading` so the browser re-attempts the source.