useImage API

Tracks image loading state as a reactive state machine with idle, loading, loaded, and error states.

Explore these related pages for additional context and usage patterns.

(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.