'use client'; import type { DependencyList } from 'react'; import { useEffect, useRef, useState } from 'react'; import { Image } from './Image'; import type { ImageLoadOptions, ImageRef, ImageSource } from './Image.types'; import { resolveSource } from './utils/resolveSources'; /** * A hook that loads an image from the given source and returns a reference * to the native image instance, or `null` until the first image is successfully loaded. * * It loads a new image every time the `uri` of the provided source changes. * To trigger reloads in some other scenarios, you can provide an additional dependency list. * * On Android, when neither `maxWidth` nor `maxHeight` is provided, large images may be * downsampled to fit the platform's bitmap size limit. The returned `ImageRef.width` and * `ImageRef.height` reflect the decoded size and may differ from the original dimensions or iOS. * * > **warning** Avoid using this hook for large images without specifying size constraints, * > as it may cause crashes due to excessive memory usage. It is recommended to use either * > `maxWidth` or `maxHeight` option to scale down the image appropriately for your use case. * * @platform android * @platform ios * @platform web * * @example * ```ts * import { useImage, Image } from 'expo-image'; * import { Text } from 'react-native'; * * export default function MyImage() { * const image = useImage('https://picsum.photos/1000/800', { * maxWidth: 800, * onError(error, retry) { * console.error('Loading failed:', error.message); * } * }); * * if (!image) { * return Image is loading...; * } * * return ; * } * ``` */ export function useImage( source: ImageSource | string | number, options: ImageLoadOptions = {}, dependencies: DependencyList = [] ): ImageRef | null { const resolvedSource = resolveSource(source) as ImageSource; const [image, setImage] = useState(null); // Since options are not dependencies of the below effect, we store them in a ref. // Once the image is asynchronously loaded, the effect will use the most recent options, // instead of the captured ones (especially important for callbacks that may change in subsequent renders). const optionsRef = useRef(options); optionsRef.current = options; useEffect(() => { // We're doing some asynchronous action in this effect, so we should keep track // if the effect was already cleaned up. In that case, the async action shouldn't change the state. let isEffectValid = true; function loadImage() { Image.loadAsync(resolvedSource, options) .then((image) => { if (isEffectValid) { setImage(image); } else { image.release(); } }) .catch((error) => { if (!isEffectValid) { return; } if (optionsRef.current.onError) { optionsRef.current.onError(error, loadImage); } else { // Print unhandled errors to the console. console.error( `Loading an image from '${resolvedSource.uri}' failed, use 'onError' option to handle errors and suppress this message` ); console.error(error); } }); } loadImage(); return () => { // Invalidate the effect. The current image stays rendered until the next one replaces it. isEffectValid = false; }; }, [resolvedSource.uri, ...dependencies]); useEffect(() => { if (!image) { return; } return () => { // Release the image once it is replaced or the component unmounts. In development, React reads // the previous props after this cleanup, so the release waits until the commit finishes. Promise.resolve().then(() => image.release()); }; }, [image]); return image; }