react-native-fast-image 10.6.0 → 10.8.0

package/README.md

@@ -101,7 +101,7 @@ const YourImage = () => (
 
 ### `FastImage`
 
-It's a single native view, which also takes React Native's View props, such as accessibility props, `testID`, `nativeID`, `onLayout`, `pointerEvents` and `hitSlop`. A ref to it is that view (e.g. for `measure`). It doesn't take children: use [`FastImageBackground`](#fastimagebackground) for content over an image.
+It's a single native view, which also takes React Native's View props, such as accessibility props, `testID`, `nativeID`, `onLayout`, `pointerEvents` and `hitSlop`. A ref to it is that view (e.g. for `measure`), with [`reload()`](#refreload). It doesn't take children: use [`FastImageBackground`](#fastimagebackground) for content over an image.
 
 <!-- api:props start (generated from src/ by website/scripts/generate.mts) -->
 
@@ -537,6 +537,27 @@ If supplied, changes the color of all the non-transparent pixels to the given co
 
 <!-- api:props end -->
 
+---
+
+#### `ref.reload()`
+
+Loads the image again, e.g. to try again after `onError`. The image showing stays until the new one has loaded (or the placeholder, if it failed), and the events are sent as for a new source. An image in the cache loads from it. In TypeScript, the ref's type is `FastImageRef`.
+
+```tsx
+const image = useRef<FastImageRef>(null)
+
+<FastImage ref={image} source={{ uri }} onError={() => setFailed(true)} />
+{failed && (
+    <Button
+        title="Try again"
+        onPress={() => {
+            setFailed(false)
+            image.current?.reload()
+        }}
+    />
+)}
+```
+
 ### `FastImageBackground`
 
 An image with content on top of it: a view that the image fills, with the children on top.
@@ -577,7 +598,7 @@ The image's style.
 
 #### `imageRef`
 
-**Type:** `Ref<any>`
+**Type:** `Ref<FastImageRef>`
 
 A ref to the image (the FastImage inside).
 

package/android/src/main/java/com/fastimage/FastImageViewConverter.java

@@ -16,7 +16,6 @@ import com.bumptech.glide.load.model.LazyHeaders;
 import com.bumptech.glide.request.RequestOptions;
 import com.bumptech.glide.signature.ApplicationVersionSignature;
 import com.facebook.react.bridge.JSApplicationIllegalArgumentException;
-import com.facebook.react.bridge.NoSuchKeyException;
 import com.facebook.react.bridge.ReadableMap;
 import com.facebook.react.bridge.ReadableMapKeySetIterator;
 import com.facebook.react.bridge.ReadableType;
@@ -34,6 +33,10 @@ class FastImageViewConverter {
                 put("immutable", FastImageCacheControl.IMMUTABLE);
                 put("web", FastImageCacheControl.WEB);
                 put("cacheOnly", FastImageCacheControl.CACHE_ONLY);
+                // React Native's ImageURISource value, which views take. Its
+                // others (e.g. 'reload') are immutable, as any value this map
+                // doesn't have (see getValueFromSource).
+                put("only-if-cached", FastImageCacheControl.CACHE_ONLY);
             }};
 
     private static final Map<String, Priority> FAST_IMAGE_PRIORITY_MAP =
@@ -189,13 +192,12 @@ class FastImageViewConverter {
         return value;
     }
 
+    // A value the map doesn't have (e.g. React Native's `cache: 'reload'`, or
+    // one that isn't a string) gets the default, as on iOS.
     private static <T> T getValueFromSource(String propName, String defaultProp, Map<String, T> map, ReadableMap source) {
-        String propValue;
-        try {
-            propValue = source != null ? source.getString(propName) : null;
-        } catch (NoSuchKeyException e) {
-            propValue = null;
-        }
-        return getValue(propName, defaultProp, map, propValue);
+        T value = source != null && source.hasKey(propName) && source.getType(propName) == ReadableType.String
+                ? map.get(source.getString(propName))
+                : null;
+        return value != null ? value : map.get(defaultProp);
     }
 }

package/android/src/main/java/com/fastimage/FastImageViewManager.java

@@ -435,6 +435,12 @@ class FastImageViewManager extends SimpleViewManager<FastImageViewWithUrl>
         view.setObjectFit(FastImageViewConverter.getScaleType(objectFit));
     }
 
+    // The ref's reload() (a command).
+    @Override
+    public void reload(FastImageViewWithUrl view) {
+        view.reload();
+    }
+
     @Override
     public void onDropViewInstance(@NonNull FastImageViewWithUrl view) {
         // Cancels its request, and nothing loads or tracks progress for it

package/android/src/main/java/com/fastimage/FastImageViewWithUrl.java

@@ -364,6 +364,15 @@ class FastImageViewWithUrl extends AppCompatImageView implements ReactPointerEve
         return true;
     }
 
+    // Loads the image again, as a new source would, keeping the image showing
+    // until then (the ref's reload()). Before the first props there's nothing
+    // to load yet.
+    void reload() {
+        if (mManager == null) return;
+        mNeedsReload = true;
+        onAfterUpdate(mManager, requestManager);
+    }
+
     // Shows at once, as a new source placeholder does (see updatePlaceholder),
     // without loading the image again.
     public void setPlaceholder(@Nullable Drawable placeholder) {

package/dist/composeRefs.d.ts

@@ -0,0 +1,2 @@
+import type React from 'react';
+export declare function composeRefs<T>(...refs: (React.Ref<T> | undefined)[]): React.RefCallback<T>;

package/dist/index.cjs.js

@@ -255,6 +255,7 @@ function objectPositionOrCentered(position) {
 }
 //#endregion
 //#region src/specs/FastImageViewNativeComponent.ts
+const Commands = (0, react_native.codegenNativeCommands)({ supportedCommands: ["reload"] });
 var FastImageViewNativeComponent_default = (0, react_native.codegenNativeComponent)("FastImageView");
 //#endregion
 //#region src/specs/NativeFastImageModule.ts
@@ -279,6 +280,32 @@ function dataUri(value) {
 	if (typeof __DEV__ !== "undefined" && __DEV__) warnOnce("placeholder-url", `react-native-fast-image: \`blurDataUri\` takes a data uri (data:image/…): "${value.slice(0, 60)}" is ignored. For a placeholder loaded from a url, use \`placeholder\`.`, "warn");
 }
 //#endregion
+//#region src/composeRefs.ts
+function composeRefs(...refs) {
+	return (value) => {
+		const cleanups = refs.map((ref) => {
+			if (typeof ref === "function") {
+				const cleanup = ref(value);
+				return typeof cleanup === "function" ? cleanup : () => {
+					ref(null);
+				};
+			}
+			if (ref) {
+				ref.current = value;
+				return () => {
+					ref.current = null;
+				};
+			}
+		});
+		return () => cleanups.forEach((cleanup) => cleanup === null || cleanup === void 0 ? void 0 : cleanup());
+	};
+}
+//#endregion
+//#region src/reactNativeCache.ts
+function warnIfReload(source) {
+	if (typeof __DEV__ !== "undefined" && __DEV__ && (source === null || source === void 0 ? void 0 : source.cache) === "reload") warnOnce("cache-reload", "react-native-fast-image: `cache: 'reload'` loads the image as the default, `'immutable'`: it isn't loaded again each time. For an image that changes at the same url, use `cache: 'web'` (it follows the server's cache headers), or change its `cacheKey`.", "warn");
+}
+//#endregion
 //#region src/index.tsx
 const resolvePlaceholder = (placeholder) => {
 	if (typeof placeholder === "string") {
@@ -352,14 +379,18 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, onLoadSt
 	const fit = resolveObjectFit(objectFit, style);
 	const position = objectPositionOrCentered(objectPosition);
 	const resolvedSource = (0, react.useMemo)(() => {
-		for (const entry of [source].flat()) dataUri(entry === null || entry === void 0 ? void 0 : entry.blurDataUri);
+		for (const entry of [source].flat()) {
+			dataUri(entry === null || entry === void 0 ? void 0 : entry.blurDataUri);
+			warnIfReload(entry);
+		}
 		const single = Array.isArray(source) && source.length === 1 ? source[0] : source;
 		return Array.isArray(single) ? single.map((entry) => react_native.Image.resolveAssetSource(entry)) : react_native.Image.resolveAssetSource(single);
 	}, [source]);
 	const resolvedPlaceholder = hasSourcePlaceholder(placeholder) ? placeholder.thumbhash || dataUri(placeholder.blurDataUri) ? placeholder : resolvePlaceholder(defaultSource) : (_placeholderSource = placeholderSource(placeholder)) !== null && _placeholderSource !== void 0 ? _placeholderSource : resolvePlaceholder(placeholder !== null && placeholder !== void 0 ? placeholder : defaultSource);
+	const ref = (0, react.useMemo)(() => composeRefs(addReload, forwardedRef), [forwardedRef]);
 	return /* @__PURE__ */ react.default.createElement(FastImageViewNativeComponent_default, {
 		...props,
-		ref: forwardedRef,
+		ref,
 		style: [styles.image, style],
 		recyclingKey: (_props$recyclingKey = props.recyclingKey) !== null && _props$recyclingKey !== void 0 ? _props$recyclingKey : void 0,
 		loopCount: loopCount(loop),
@@ -386,6 +417,9 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, onLoadSt
 		objectPositionYOffset: position.y.offset
 	});
 }
+function addReload(view) {
+	if (view) view.reload = () => Commands.reload(view);
+}
 const FastImageMemo = (0, react.memo)(FastImageBase);
 const FastImageComponent = (0, react.forwardRef)((props, ref) => /* @__PURE__ */ react.default.createElement(FastImageMemo, {
 	forwardedRef: ref,

package/dist/index.cjs.js.flow

@@ -137,6 +137,15 @@ export type FastImageSource = {
     scale?: number,
 }
 
+// React Native's ImageURISource cache values, which the views' `source` takes
+// so a React Native source works as it is: native reads 'only-if-cached' as
+// 'cacheOnly', and the others as the default, 'immutable'.
+type ReactNativeCache = 'default' | 'reload' | 'force-cache' | 'only-if-cached'
+type ViewSource = {
+    ...FastImageSource,
+    cache?: CacheControls | ReactNativeCache,
+}
+
 export type FastImageProps = $ReadOnly<{|
     ...ViewProps,
     onError?: ?(event: OnErrorEvent) => void,
@@ -145,7 +154,7 @@ export type FastImageProps = $ReadOnly<{|
     onLoadStart?: ?() => void,
     onProgress?: ?(event: OnProgressEvent) => void,
 
-    source?: ?(FastImageSource | Array<FastImageSource | number> | number),
+    source?: ?(ViewSource | Array<ViewSource | number> | number),
     placeholder?: ?(number | string | SourcePlaceholder | PlaceholderSource),
     // Deprecated: use placeholder, which is the same.
     defaultSource?: ?number,
@@ -196,4 +205,6 @@ declare export default class FastImage extends React$Component<FastImageProps> {
         source: FastImageSource,
         file: string,
     ) => Promise<CachePathResult>;
+    // On a ref: loads the image again, e.g. to try again after onError.
+    reload(): void;
 }

package/dist/index.cjs.web.js

@@ -282,6 +282,27 @@ function dataUri(value) {
 	if (typeof __DEV__ !== "undefined" && __DEV__) warnOnce("placeholder-url", `react-native-fast-image: \`blurDataUri\` takes a data uri (data:image/…): "${value.slice(0, 60)}" is ignored. For a placeholder loaded from a url, use \`placeholder\`.`, "warn");
 }
 //#endregion
+//#region src/composeRefs.ts
+function composeRefs(...refs) {
+	return (value) => {
+		const cleanups = refs.map((ref) => {
+			if (typeof ref === "function") {
+				const cleanup = ref(value);
+				return typeof cleanup === "function" ? cleanup : () => {
+					ref(null);
+				};
+			}
+			if (ref) {
+				ref.current = value;
+				return () => {
+					ref.current = null;
+				};
+			}
+		});
+		return () => cleanups.forEach((cleanup) => cleanup === null || cleanup === void 0 ? void 0 : cleanup());
+	};
+}
+//#endregion
 //#region src/index.web.tsx
 const notSupported = {
 	ok: false,
@@ -298,10 +319,15 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadi
 	const src = sized ? sized.src : resolveUri(source);
 	const srcSet = sized === null || sized === void 0 ? void 0 : sized.srcSet;
 	const key = srcSet !== null && srcSet !== void 0 ? srcSet : src;
+	const [reloads, setReloads] = (0, react.useState)(0);
+	const ref = (0, react.useMemo)(() => composeRefs((view) => {
+		if (view) view.reload = () => setReloads((count) => count + 1);
+	}, forwardedRef), [forwardedRef]);
 	const priority = sourcePriority(source);
 	const preview = hasSourcePlaceholder(placeholder) ? placeholder : void 0;
 	const blurUri = (_resolveUri = resolveUri(dataUri(shared(source, "blurDataUri", preview)))) !== null && _resolveUri !== void 0 ? _resolveUri : thumbhashUri(shared(source, "thumbhash", preview));
 	const urlPlaceholder = (_placeholderSource = placeholderSource(placeholder)) === null || _placeholderSource === void 0 ? void 0 : _placeholderSource.uri;
+	const placeholderKey = `${urlPlaceholder} ${reloads}`;
 	const [failedPlaceholder, setFailedPlaceholder] = (0, react.useState)();
 	const defaultUri = blurUri !== null && blurUri !== void 0 ? blurUri : resolveUri(preview ? defaultSource : urlPlaceholder ? void 0 : placeholder !== null && placeholder !== void 0 ? placeholder : defaultSource);
 	const [result, setResult] = (0, react.useState)();
@@ -315,14 +341,14 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadi
 	const showDefault = ok !== true;
 	useClientLayoutEffect(() => {
 		if (key) onLoadStart === null || onLoadStart === void 0 || onLoadStart();
-	}, [key]);
+	}, [key, reloads]);
 	return /* @__PURE__ */ react.default.createElement(react_native.View, {
 		...viewProps,
 		"aria-label": label,
 		style: [styles.container, style],
 		onLayout,
 		pointerEvents,
-		ref: forwardedRef
+		ref
 	}, defaultUri && showDefault ? /* @__PURE__ */ react.default.createElement(Picture, {
 		key: `default ${defaultUri}`,
 		src: defaultUri,
@@ -334,7 +360,7 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadi
 		filter: blurUri ? [`url(#${blurId})`, tintColor ? `url(#${tintId})` : ""].filter(Boolean).join(" ") : filter,
 		alt: key ? "" : label !== null && label !== void 0 ? label : ""
 	}) : null, urlPlaceholder && showDefault ? /* @__PURE__ */ react.default.createElement(Picture, {
-		key: `placeholder ${urlPlaceholder}`,
+		key: `placeholder ${placeholderKey}`,
 		src: urlPlaceholder,
 		loading,
 		priority: "high",
@@ -342,11 +368,11 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadi
 		fit: fit === "scale-down" || fit === "none" ? "contain" : fit,
 		position,
 		filter: tintColor ? `url(#${tintId})` : void 0,
-		hidden: failedPlaceholder === urlPlaceholder,
-		onError: () => setFailedPlaceholder(urlPlaceholder),
+		hidden: failedPlaceholder === placeholderKey,
+		onError: () => setFailedPlaceholder(placeholderKey),
 		alt: ""
 	}) : null, key && src ? /* @__PURE__ */ react.default.createElement(Picture, {
-		key: several ? "sizes" : key,
+		key: `${several ? "sizes" : key} ${reloads}`,
 		src,
 		srcSet,
 		sizes,
@@ -604,11 +630,10 @@ FastImage.setDefaults = () => {};
 FastImage.writeToCache = () => Promise.resolve(notSupported);
 FastImage.getCachePath = () => Promise.resolve(notSupported);
 const styles = react_native.StyleSheet.create({ container: { overflow: "hidden" } });
-const FastImageWithRef = FastImageComponent;
 const FastImageBackground = (0, react.forwardRef)(({ style, imageStyle, imageRef, children, ...props }, ref) => /* @__PURE__ */ react.default.createElement(react_native.View, {
 	style,
 	ref
-}, /* @__PURE__ */ react.default.createElement(FastImageWithRef, {
+}, /* @__PURE__ */ react.default.createElement(FastImageComponent, {
 	...props,
 	style: [react_native.StyleSheet.absoluteFill, imageStyle],
 	ref: imageRef

package/dist/index.cjs.web.js.flow

@@ -137,6 +137,15 @@ export type FastImageSource = {
     scale?: number,
 }
 
+// React Native's ImageURISource cache values, which the views' `source` takes
+// so a React Native source works as it is: native reads 'only-if-cached' as
+// 'cacheOnly', and the others as the default, 'immutable'.
+type ReactNativeCache = 'default' | 'reload' | 'force-cache' | 'only-if-cached'
+type ViewSource = {
+    ...FastImageSource,
+    cache?: CacheControls | ReactNativeCache,
+}
+
 export type FastImageProps = $ReadOnly<{|
     ...ViewProps,
     onError?: ?(event: OnErrorEvent) => void,
@@ -145,7 +154,7 @@ export type FastImageProps = $ReadOnly<{|
     onLoadStart?: ?() => void,
     onProgress?: ?(event: OnProgressEvent) => void,
 
-    source?: ?(FastImageSource | Array<FastImageSource | number> | number),
+    source?: ?(ViewSource | Array<ViewSource | number> | number),
     placeholder?: ?(number | string | SourcePlaceholder | PlaceholderSource),
     // Deprecated: use placeholder, which is the same.
     defaultSource?: ?number,
@@ -196,4 +205,6 @@ declare export default class FastImage extends React$Component<FastImageProps> {
         source: FastImageSource,
         file: string,
     ) => Promise<CachePathResult>;
+    // On a ref: loads the image again, e.g. to try again after onError.
+    reload(): void;
 }

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import React from 'react';
 import { ColorValue, View, StyleProp, ViewStyle, ImageRequireSource, AccessibilityProps, ViewProps } from 'react-native';
 import { cacheControl, priority, resizeMode } from './constants';
 import { type ObjectPosition } from './objectPosition';
+import { type ReactNativeCache } from './reactNativeCache';
 /** How the image fits the view: see [`objectFit`](#objectfit). */
 export type ObjectFit = 'fill' | 'contain' | 'cover' | 'none' | 'scale-down';
 export type { ObjectPosition, PositionLength } from './objectPosition';
@@ -152,6 +153,9 @@ export type Source = {
     /** With several sources, the scale `width` and `height` are multiplied by. */
     scale?: number;
 };
+type ViewSource = Source | (Omit<Source, 'cache'> & {
+    cache?: ReactNativeCache;
+});
 /** A `thumbhash` or `blurDataUri` as `placeholder`. */
 export type SourcePlaceholder = Pick<Source, 'thumbhash' | 'blurDataUri'>;
 /** A url as `placeholder`, loaded like a source (see `placeholder`). */
@@ -334,7 +338,7 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
      * - A `require()`d image can be one of the sizes: its size is the file's.
      * - An array of one is the same as that source.
      */
-    source?: Source | Array<Source | ImageRequireSource> | ImageRequireSource;
+    source?: ViewSource | Array<ViewSource | ImageRequireSource> | ImageRequireSource;
     /**
      * A placeholder shown while the image loads, and if it fails to load:
      *
@@ -664,6 +668,18 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
     children?: "FastImage doesn't take children: use FastImageBackground for content over an image";
 }
 type ViewRef = React.ComponentRef<typeof View>;
+/**
+ * What a ref to `FastImage` gets: its native view, with a View's methods
+ * (e.g. `measure`), and `reload()`. E.g. `useRef<FastImageRef>(null)`.
+ */
+export type FastImageRef = ViewRef & {
+    /**
+     * Loads the image again, e.g. to try again after `onError`. The image
+     * showing stays until the new one has loaded, and the events are sent as
+     * for a new source. An image in the cache loads from it.
+     */
+    reload(): void;
+};
 /** A preloaded source that loaded (and is now cached). */
 export interface PreloadSuccess {
     /** The source's uri. */
@@ -762,14 +778,14 @@ export interface FastImageDefaults {
      */
     transition?: boolean | number | Transition | null;
 }
-declare const FastImage: React.ForwardRefExoticComponent<FastImageProps & React.RefAttributes<ViewRef>> & FastImageStaticProperties;
+declare const FastImage: React.ForwardRefExoticComponent<FastImageProps & React.RefAttributes<FastImageRef>> & FastImageStaticProperties;
 export interface FastImageBackgroundProps extends Omit<FastImageProps, 'style' | 'children'> {
     /** The container's style; the image fills it. */
     style?: StyleProp<ViewStyle>;
     /** The image's style. */
     imageStyle?: StyleProp<ImageStyle>;
     /** A ref to the image (the FastImage inside). */
-    imageRef?: React.Ref<any>;
+    imageRef?: React.Ref<FastImageRef>;
     /** Content shown on top of the image. */
     children?: React.ReactNode;
 }

package/dist/index.js

@@ -1,5 +1,5 @@
 import React, { Children, forwardRef, memo, useMemo } from "react";
-import { Image, Platform, StyleSheet, TurboModuleRegistry, View, codegenNativeComponent } from "react-native";
+import { Image, Platform, StyleSheet, TurboModuleRegistry, View, codegenNativeCommands, codegenNativeComponent } from "react-native";
 //#region src/constants.ts
 const resizeMode = {
 	contain: "contain",
@@ -228,6 +228,7 @@ function objectPositionOrCentered(position) {
 }
 //#endregion
 //#region src/specs/FastImageViewNativeComponent.ts
+const Commands = codegenNativeCommands({ supportedCommands: ["reload"] });
 var FastImageViewNativeComponent_default = codegenNativeComponent("FastImageView");
 //#endregion
 //#region src/specs/NativeFastImageModule.ts
@@ -252,6 +253,32 @@ function dataUri(value) {
 	if (typeof __DEV__ !== "undefined" && __DEV__) warnOnce("placeholder-url", `react-native-fast-image: \`blurDataUri\` takes a data uri (data:image/…): "${value.slice(0, 60)}" is ignored. For a placeholder loaded from a url, use \`placeholder\`.`, "warn");
 }
 //#endregion
+//#region src/composeRefs.ts
+function composeRefs(...refs) {
+	return (value) => {
+		const cleanups = refs.map((ref) => {
+			if (typeof ref === "function") {
+				const cleanup = ref(value);
+				return typeof cleanup === "function" ? cleanup : () => {
+					ref(null);
+				};
+			}
+			if (ref) {
+				ref.current = value;
+				return () => {
+					ref.current = null;
+				};
+			}
+		});
+		return () => cleanups.forEach((cleanup) => cleanup === null || cleanup === void 0 ? void 0 : cleanup());
+	};
+}
+//#endregion
+//#region src/reactNativeCache.ts
+function warnIfReload(source) {
+	if (typeof __DEV__ !== "undefined" && __DEV__ && (source === null || source === void 0 ? void 0 : source.cache) === "reload") warnOnce("cache-reload", "react-native-fast-image: `cache: 'reload'` loads the image as the default, `'immutable'`: it isn't loaded again each time. For an image that changes at the same url, use `cache: 'web'` (it follows the server's cache headers), or change its `cacheKey`.", "warn");
+}
+//#endregion
 //#region src/index.tsx
 const resolvePlaceholder = (placeholder) => {
 	if (typeof placeholder === "string") {
@@ -325,14 +352,18 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, onLoadSt
 	const fit = resolveObjectFit(objectFit, style);
 	const position = objectPositionOrCentered(objectPosition);
 	const resolvedSource = useMemo(() => {
-		for (const entry of [source].flat()) dataUri(entry === null || entry === void 0 ? void 0 : entry.blurDataUri);
+		for (const entry of [source].flat()) {
+			dataUri(entry === null || entry === void 0 ? void 0 : entry.blurDataUri);
+			warnIfReload(entry);
+		}
 		const single = Array.isArray(source) && source.length === 1 ? source[0] : source;
 		return Array.isArray(single) ? single.map((entry) => Image.resolveAssetSource(entry)) : Image.resolveAssetSource(single);
 	}, [source]);
 	const resolvedPlaceholder = hasSourcePlaceholder(placeholder) ? placeholder.thumbhash || dataUri(placeholder.blurDataUri) ? placeholder : resolvePlaceholder(defaultSource) : (_placeholderSource = placeholderSource(placeholder)) !== null && _placeholderSource !== void 0 ? _placeholderSource : resolvePlaceholder(placeholder !== null && placeholder !== void 0 ? placeholder : defaultSource);
+	const ref = useMemo(() => composeRefs(addReload, forwardedRef), [forwardedRef]);
 	return /* @__PURE__ */ React.createElement(FastImageViewNativeComponent_default, {
 		...props,
-		ref: forwardedRef,
+		ref,
 		style: [styles.image, style],
 		recyclingKey: (_props$recyclingKey = props.recyclingKey) !== null && _props$recyclingKey !== void 0 ? _props$recyclingKey : void 0,
 		loopCount: loopCount(loop),
@@ -359,6 +390,9 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, onLoadSt
 		objectPositionYOffset: position.y.offset
 	});
 }
+function addReload(view) {
+	if (view) view.reload = () => Commands.reload(view);
+}
 const FastImageMemo = memo(FastImageBase);
 const FastImageComponent = forwardRef((props, ref) => /* @__PURE__ */ React.createElement(FastImageMemo, {
 	forwardedRef: ref,

package/dist/index.js.flow

@@ -137,6 +137,15 @@ export type FastImageSource = {
     scale?: number,
 }
 
+// React Native's ImageURISource cache values, which the views' `source` takes
+// so a React Native source works as it is: native reads 'only-if-cached' as
+// 'cacheOnly', and the others as the default, 'immutable'.
+type ReactNativeCache = 'default' | 'reload' | 'force-cache' | 'only-if-cached'
+type ViewSource = {
+    ...FastImageSource,
+    cache?: CacheControls | ReactNativeCache,
+}
+
 export type FastImageProps = $ReadOnly<{|
     ...ViewProps,
     onError?: ?(event: OnErrorEvent) => void,
@@ -145,7 +154,7 @@ export type FastImageProps = $ReadOnly<{|
     onLoadStart?: ?() => void,
     onProgress?: ?(event: OnProgressEvent) => void,
 
-    source?: ?(FastImageSource | Array<FastImageSource | number> | number),
+    source?: ?(ViewSource | Array<ViewSource | number> | number),
     placeholder?: ?(number | string | SourcePlaceholder | PlaceholderSource),
     // Deprecated: use placeholder, which is the same.
     defaultSource?: ?number,
@@ -196,4 +205,6 @@ declare export default class FastImage extends React$Component<FastImageProps> {
         source: FastImageSource,
         file: string,
     ) => Promise<CachePathResult>;
+    // On a ref: loads the image again, e.g. to try again after onError.
+    reload(): void;
 }

package/dist/index.web.d.ts

@@ -1,6 +1,8 @@
 import React from 'react';
-import type { FastImageBackgroundProps, FastImageProps, FastImageStaticProperties } from './index';
+import { View } from 'react-native';
+import type { FastImageBackgroundProps, FastImageProps, FastImageRef, FastImageStaticProperties } from './index';
 export type * from './index';
-declare const FastImage: React.ComponentType<FastImageProps> & FastImageStaticProperties;
-export declare const FastImageBackground: React.ComponentType<FastImageBackgroundProps>;
+type ViewRef = React.ComponentRef<typeof View>;
+declare const FastImage: React.ForwardRefExoticComponent<FastImageProps & React.RefAttributes<FastImageRef>> & FastImageStaticProperties;
+export declare const FastImageBackground: React.ForwardRefExoticComponent<FastImageBackgroundProps & React.RefAttributes<ViewRef>>;
 export default FastImage;

package/dist/index.web.js

@@ -1,4 +1,4 @@
-import React, { Children, forwardRef, memo, useEffect, useId, useLayoutEffect, useRef, useState } from "react";
+import React, { Children, forwardRef, memo, useEffect, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { Image, PixelRatio, StyleSheet, View } from "react-native";
 import { getAssetByID } from "react-native-web/dist/modules/AssetRegistry";
 //#region src/constants.ts
@@ -255,6 +255,27 @@ function dataUri(value) {
 	if (typeof __DEV__ !== "undefined" && __DEV__) warnOnce("placeholder-url", `react-native-fast-image: \`blurDataUri\` takes a data uri (data:image/…): "${value.slice(0, 60)}" is ignored. For a placeholder loaded from a url, use \`placeholder\`.`, "warn");
 }
 //#endregion
+//#region src/composeRefs.ts
+function composeRefs(...refs) {
+	return (value) => {
+		const cleanups = refs.map((ref) => {
+			if (typeof ref === "function") {
+				const cleanup = ref(value);
+				return typeof cleanup === "function" ? cleanup : () => {
+					ref(null);
+				};
+			}
+			if (ref) {
+				ref.current = value;
+				return () => {
+					ref.current = null;
+				};
+			}
+		});
+		return () => cleanups.forEach((cleanup) => cleanup === null || cleanup === void 0 ? void 0 : cleanup());
+	};
+}
+//#endregion
 //#region src/index.web.tsx
 const notSupported = {
 	ok: false,
@@ -271,10 +292,15 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadi
 	const src = sized ? sized.src : resolveUri(source);
 	const srcSet = sized === null || sized === void 0 ? void 0 : sized.srcSet;
 	const key = srcSet !== null && srcSet !== void 0 ? srcSet : src;
+	const [reloads, setReloads] = useState(0);
+	const ref = useMemo(() => composeRefs((view) => {
+		if (view) view.reload = () => setReloads((count) => count + 1);
+	}, forwardedRef), [forwardedRef]);
 	const priority = sourcePriority(source);
 	const preview = hasSourcePlaceholder(placeholder) ? placeholder : void 0;
 	const blurUri = (_resolveUri = resolveUri(dataUri(shared(source, "blurDataUri", preview)))) !== null && _resolveUri !== void 0 ? _resolveUri : thumbhashUri(shared(source, "thumbhash", preview));
 	const urlPlaceholder = (_placeholderSource = placeholderSource(placeholder)) === null || _placeholderSource === void 0 ? void 0 : _placeholderSource.uri;
+	const placeholderKey = `${urlPlaceholder} ${reloads}`;
 	const [failedPlaceholder, setFailedPlaceholder] = useState();
 	const defaultUri = blurUri !== null && blurUri !== void 0 ? blurUri : resolveUri(preview ? defaultSource : urlPlaceholder ? void 0 : placeholder !== null && placeholder !== void 0 ? placeholder : defaultSource);
 	const [result, setResult] = useState();
@@ -288,14 +314,14 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadi
 	const showDefault = ok !== true;
 	useClientLayoutEffect(() => {
 		if (key) onLoadStart === null || onLoadStart === void 0 || onLoadStart();
-	}, [key]);
+	}, [key, reloads]);
 	return /* @__PURE__ */ React.createElement(View, {
 		...viewProps,
 		"aria-label": label,
 		style: [styles.container, style],
 		onLayout,
 		pointerEvents,
-		ref: forwardedRef
+		ref
 	}, defaultUri && showDefault ? /* @__PURE__ */ React.createElement(Picture, {
 		key: `default ${defaultUri}`,
 		src: defaultUri,
@@ -307,7 +333,7 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadi
 		filter: blurUri ? [`url(#${blurId})`, tintColor ? `url(#${tintId})` : ""].filter(Boolean).join(" ") : filter,
 		alt: key ? "" : label !== null && label !== void 0 ? label : ""
 	}) : null, urlPlaceholder && showDefault ? /* @__PURE__ */ React.createElement(Picture, {
-		key: `placeholder ${urlPlaceholder}`,
+		key: `placeholder ${placeholderKey}`,
 		src: urlPlaceholder,
 		loading,
 		priority: "high",
@@ -315,11 +341,11 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadi
 		fit: fit === "scale-down" || fit === "none" ? "contain" : fit,
 		position,
 		filter: tintColor ? `url(#${tintId})` : void 0,
-		hidden: failedPlaceholder === urlPlaceholder,
-		onError: () => setFailedPlaceholder(urlPlaceholder),
+		hidden: failedPlaceholder === placeholderKey,
+		onError: () => setFailedPlaceholder(placeholderKey),
 		alt: ""
 	}) : null, key && src ? /* @__PURE__ */ React.createElement(Picture, {
-		key: several ? "sizes" : key,
+		key: `${several ? "sizes" : key} ${reloads}`,
 		src,
 		srcSet,
 		sizes,
@@ -577,11 +603,10 @@ FastImage.setDefaults = () => {};
 FastImage.writeToCache = () => Promise.resolve(notSupported);
 FastImage.getCachePath = () => Promise.resolve(notSupported);
 const styles = StyleSheet.create({ container: { overflow: "hidden" } });
-const FastImageWithRef = FastImageComponent;
 const FastImageBackground = forwardRef(({ style, imageStyle, imageRef, children, ...props }, ref) => /* @__PURE__ */ React.createElement(View, {
 	style,
 	ref
-}, /* @__PURE__ */ React.createElement(FastImageWithRef, {
+}, /* @__PURE__ */ React.createElement(FastImageComponent, {
 	...props,
 	style: [StyleSheet.absoluteFill, imageStyle],
 	ref: imageRef

package/dist/index.web.js.flow

@@ -137,6 +137,15 @@ export type FastImageSource = {
     scale?: number,
 }
 
+// React Native's ImageURISource cache values, which the views' `source` takes
+// so a React Native source works as it is: native reads 'only-if-cached' as
+// 'cacheOnly', and the others as the default, 'immutable'.
+type ReactNativeCache = 'default' | 'reload' | 'force-cache' | 'only-if-cached'
+type ViewSource = {
+    ...FastImageSource,
+    cache?: CacheControls | ReactNativeCache,
+}
+
 export type FastImageProps = $ReadOnly<{|
     ...ViewProps,
     onError?: ?(event: OnErrorEvent) => void,
@@ -145,7 +154,7 @@ export type FastImageProps = $ReadOnly<{|
     onLoadStart?: ?() => void,
     onProgress?: ?(event: OnProgressEvent) => void,
 
-    source?: ?(FastImageSource | Array<FastImageSource | number> | number),
+    source?: ?(ViewSource | Array<ViewSource | number> | number),
     placeholder?: ?(number | string | SourcePlaceholder | PlaceholderSource),
     // Deprecated: use placeholder, which is the same.
     defaultSource?: ?number,
@@ -196,4 +205,6 @@ declare export default class FastImage extends React$Component<FastImageProps> {
         source: FastImageSource,
         file: string,
     ) => Promise<CachePathResult>;
+    // On a ref: loads the image again, e.g. to try again after onError.
+    reload(): void;
 }

package/dist/reactNativeCache.d.ts

@@ -0,0 +1,2 @@
+export type ReactNativeCache = 'default' | 'reload' | 'force-cache' | 'only-if-cached';
+export declare function warnIfReload(source: unknown): void;

package/dist/specs/FastImageViewNativeComponent.d.ts

@@ -1,3 +1,4 @@
+import type * as React from 'react';
 import type { CodegenTypes, ColorValue, HostComponent, ViewProps } from 'react-native';
 type LoadStartEvent = Readonly<{}>;
 type ProgressEvent = Readonly<{
@@ -44,5 +45,9 @@ export interface NativeProps extends ViewProps {
     onFastImageError?: CodegenTypes.DirectEventHandler<ErrorEvent>;
     onFastImageLoadEnd?: CodegenTypes.DirectEventHandler<LoadEndEvent>;
 }
+interface NativeCommands {
+    reload: (viewRef: React.ElementRef<HostComponent<NativeProps>>) => void;
+}
+export declare const Commands: NativeCommands;
 declare const _default: HostComponent<NativeProps>;
 export default _default;

package/ios/FastImage/FFFastImageView.h

@@ -82,6 +82,10 @@ typedef NS_ENUM(NSInteger, FFFObjectFit) {
 // the view has a size, when it needs one).
 - (void) didSetProps;
 
+// Loads the image again, as a new source would (once the view has a size,
+// when it needs one): the ref's reload().
+- (void) reload;
+
 // Keeps the view's mask (React Native's, for its rounded corners) on the box
 // the view was laid out at, while objectPosition moves the view: after React
 // Native sets or removes it.

package/ios/FastImage/FFFastImageView.m

@@ -1047,6 +1047,11 @@ NSString *FFFErrorMessage(NSError *error)
     }
 }
 
+- (void) reload {
+    _needsReload = YES;
+    [self didSetProps];
+}
+
 // The same image decoded again for a dynamicRangeLimit between HDR and SDR,
 // as a resize is (reloadIfResized): without events once it has loaded, and
 // the image showing stays if the load fails. A display setting shouldn't

package/ios/FastImage/FFFastImageViewComponentView.mm

@@ -388,6 +388,17 @@ typedef NS_OPTIONS(int32_t, FFFEvent) {
     }
 }
 
+// The view's commands (reload), from the ref's methods.
+- (void)handleCommand:(const NSString *)commandName args:(const NSArray *)args
+{
+    RCTFastImageViewHandleCommand(self, commandName, args);
+}
+
+- (void)reload
+{
+    [_imageView reload];
+}
+
 // React Native makes the image view's mask again when the appearance changes
 // (as after an update): where objectPosition moved the view, it moves back.
 - (void)traitCollectionDidChange:(UITraitCollection *)previousTraitCollection

package/ios/FastImage/RCTConvert+FFFastImage.m

@@ -21,6 +21,9 @@ RCT_ENUM_CONVERTER(FFFCacheControl, (@{
                                        @"immutable": @(FFFCacheControlImmutable),
                                        @"web": @(FFFCacheControlWeb),
                                        @"cacheOnly": @(FFFCacheControlCacheOnly),
+                                       // React Native's ImageURISource value, which views
+                                       // take. Its others (e.g. 'reload') are the default.
+                                       @"only-if-cached": @(FFFCacheControlCacheOnly),
                                        }), FFFCacheControlImmutable, integerValue);
 
 + (FFFastImageSource *)FFFastImageSource:(id)json {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "react-native-fast-image",
-    "version": "10.6.0",
+    "version": "10.8.0",
     "description": "FastImage, performant React Native image component.",
     "keywords": [
         "cache",

package/src/composeRefs.ts

@@ -0,0 +1,29 @@
+// Shared by the native (index.tsx) and web (index.web.tsx) versions.
+import type React from 'react'
+
+// One ref that sets each of these refs (as React Native's useMergeRefs does),
+// and clears them when it's cleared.
+export function composeRefs<T>(
+    ...refs: (React.Ref<T> | undefined)[]
+): React.RefCallback<T> {
+    return (value) => {
+        const cleanups = refs.map((ref) => {
+            if (typeof ref === 'function') {
+                const cleanup = ref(value)
+                return typeof cleanup === 'function'
+                    ? cleanup
+                    : () => {
+                          ref(null)
+                      }
+            }
+            if (ref) {
+                ref.current = value
+                return () => {
+                    ref.current = null
+                }
+            }
+            return undefined
+        })
+        return () => cleanups.forEach((cleanup) => cleanup?.())
+    }
+}

package/src/index.js.flow

@@ -137,6 +137,15 @@ export type FastImageSource = {
     scale?: number,
 }
 
+// React Native's ImageURISource cache values, which the views' `source` takes
+// so a React Native source works as it is: native reads 'only-if-cached' as
+// 'cacheOnly', and the others as the default, 'immutable'.
+type ReactNativeCache = 'default' | 'reload' | 'force-cache' | 'only-if-cached'
+type ViewSource = {
+    ...FastImageSource,
+    cache?: CacheControls | ReactNativeCache,
+}
+
 export type FastImageProps = $ReadOnly<{|
     ...ViewProps,
     onError?: ?(event: OnErrorEvent) => void,
@@ -145,7 +154,7 @@ export type FastImageProps = $ReadOnly<{|
     onLoadStart?: ?() => void,
     onProgress?: ?(event: OnProgressEvent) => void,
 
-    source?: ?(FastImageSource | Array<FastImageSource | number> | number),
+    source?: ?(ViewSource | Array<ViewSource | number> | number),
     placeholder?: ?(number | string | SourcePlaceholder | PlaceholderSource),
     // Deprecated: use placeholder, which is the same.
     defaultSource?: ?number,
@@ -196,4 +205,6 @@ declare export default class FastImage extends React$Component<FastImageProps> {
         source: FastImageSource,
         file: string,
     ) => Promise<CachePathResult>;
+    // On a ref: loads the image again, e.g. to try again after onError.
+    reload(): void;
 }

package/src/index.tsx

@@ -14,7 +14,7 @@ import {
 import { cacheControl, priority, resizeMode } from './constants'
 import { fromStyle, resolveObjectFit } from './objectFit'
 import { objectPositionOrCentered, type ObjectPosition } from './objectPosition'
-import FastImageView from './specs/FastImageViewNativeComponent'
+import FastImageView, { Commands } from './specs/FastImageViewNativeComponent'
 import NativeFastImageModule from './specs/NativeFastImageModule'
 import {
     dataUri,
@@ -22,6 +22,8 @@ import {
     isImageName,
     placeholderSource,
 } from './placeholders'
+import { composeRefs } from './composeRefs'
+import { type ReactNativeCache, warnIfReload } from './reactNativeCache'
 import { warnIfChildren, warnOnce } from './warnings'
 
 /** How the image fits the view: see [`objectFit`](#objectfit). */
@@ -177,6 +179,14 @@ export type Source = {
     scale?: number
 }
 
+// What the views' `source` takes: a Source, or one with React Native's cache
+// values (see reactNativeCache.ts), so a React Native `ImageURISource` works as
+// it is. Only the views: preload, getCachePath, writeToCache and placeholder
+// take Fast Image's values.
+type ViewSource =
+    | Source
+    | (Omit<Source, 'cache'> & { cache?: ReactNativeCache })
+
 /** A `thumbhash` or `blurDataUri` as `placeholder`. */
 export type SourcePlaceholder = Pick<Source, 'thumbhash' | 'blurDataUri'>
 
@@ -365,7 +375,10 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
      * - A `require()`d image can be one of the sizes: its size is the file's.
      * - An array of one is the same as that source.
      */
-    source?: Source | Array<Source | ImageRequireSource> | ImageRequireSource
+    source?:
+        | ViewSource
+        | Array<ViewSource | ImageRequireSource>
+        | ImageRequireSource
     /**
      * A placeholder shown while the image loads, and if it fails to load:
      *
@@ -900,9 +913,11 @@ function FastImageBase({
     // only those change. Memoized on source, so an unchanged source reaches
     // the native view as the same object, and React's prop diff stops at it.
     const resolvedSource = useMemo(() => {
-        // A blurDataUri that isn't a data uri is ignored, with a warning.
+        // A blurDataUri that isn't a data uri is ignored, with a warning, and
+        // React Native's cache: 'reload' warns (native reads its cache values).
         for (const entry of [source].flat()) {
             dataUri((entry as Source | undefined)?.blurDataUri)
+            warnIfReload(entry)
         }
         const single =
             Array.isArray(source) && source.length === 1 ? source[0] : source
@@ -920,11 +935,15 @@ function FastImageBase({
             : resolvePlaceholder(defaultSource)
         : (placeholderSource(placeholder) ??
           resolvePlaceholder(placeholder ?? defaultSource))
+    const ref = useMemo(
+        () => composeRefs<FastImageRef>(addReload, forwardedRef),
+        [forwardedRef],
+    )
 
     return (
         <FastImageView
             {...props}
-            ref={forwardedRef}
+            ref={ref}
             // Clips the image to borderRadius by default, as React Native's
             // Image does.
             style={[styles.image, style]}
@@ -967,19 +986,37 @@ function FastImageBase({
     )
 }
 
+// The ref is the native view, with reload() added, as React Native's
+// TextInput adds its methods to its native view.
+function addReload(view: FastImageRef | null) {
+    if (view) view.reload = () => Commands.reload(view as any)
+}
+
 const FastImageMemo = memo(FastImageBase)
 
-// What a ref to FastImage or FastImageBackground gets: FastImage's native
-// view, or FastImageBackground's view. Typed as a View's (they have the same
-// methods, e.g. measure). ComponentRef, as
-// React Native's types declare View as a class, and its Strict TypeScript API
-// (opt-in from 0.80, the default from 0.87) as a function component that takes
-// a ref.
+// What a ref to FastImageBackground gets (its view), and, with reload(), one
+// to FastImage (its native view, which has the same methods, e.g. measure).
+// ComponentRef, as React Native's types declare View as a class, and its
+// Strict TypeScript API (opt-in from 0.80, the default from 0.87) as a
+// function component that takes a ref.
 type ViewRef = React.ComponentRef<typeof View>
 
+/**
+ * What a ref to `FastImage` gets: its native view, with a View's methods
+ * (e.g. `measure`), and `reload()`. E.g. `useRef<FastImageRef>(null)`.
+ */
+export type FastImageRef = ViewRef & {
+    /**
+     * Loads the image again, e.g. to try again after `onError`. The image
+     * showing stays until the new one has loaded, and the events are sent as
+     * for a new source. An image in the cache loads from it.
+     */
+    reload(): void
+}
+
 const FastImageComponent: React.ForwardRefExoticComponent<
-    FastImageProps & React.RefAttributes<ViewRef>
-> = forwardRef((props: FastImageProps, ref: React.Ref<ViewRef>) => (
+    FastImageProps & React.RefAttributes<FastImageRef>
+> = forwardRef((props: FastImageProps, ref: React.Ref<FastImageRef>) => (
     <FastImageMemo forwardedRef={ref} {...props} />
 ))
 
@@ -1112,7 +1149,7 @@ export interface FastImageDefaults {
 }
 
 const FastImage: React.ForwardRefExoticComponent<
-    FastImageProps & React.RefAttributes<ViewRef>
+    FastImageProps & React.RefAttributes<FastImageRef>
 > &
     FastImageStaticProperties = FastImageComponent as any
 
@@ -1223,7 +1260,7 @@ export interface FastImageBackgroundProps extends Omit<
     /** The image's style. */
     imageStyle?: StyleProp<ImageStyle>
     /** A ref to the image (the FastImage inside). */
-    imageRef?: React.Ref<any>
+    imageRef?: React.Ref<FastImageRef>
     /** Content shown on top of the image. */
     children?: React.ReactNode
 }

package/src/index.web.tsx

@@ -23,6 +23,7 @@ import React, {
     useEffect,
     useId,
     useLayoutEffect,
+    useMemo,
     useRef,
     useState,
 } from 'react'
@@ -37,12 +38,14 @@ import {
     hasSourcePlaceholder,
     placeholderSource,
 } from './placeholders'
+import { composeRefs } from './composeRefs'
 import { warnIfChildren, warnOnce } from './warnings'
 import type {
     CachePathResult,
     CacheState,
     FastImageBackgroundProps,
     FastImageProps,
+    FastImageRef,
     FastImageStaticProperties,
     ObjectFit,
     PreloadResult,
@@ -126,6 +129,17 @@ function FastImageBase({
     // one doesn't stay while it loads; with several sizes, the <img> stays,
     // and the browser shows the previous image until the new one has loaded.
     const key = srcSet ?? src
+    // Counts the ref's reload() calls: each gives the image a new <img>, which
+    // the browser loads again (as a new view would). The image showing stays
+    // (it has loaded), or stays hidden (it failed), until then.
+    const [reloads, setReloads] = useState(0)
+    const ref = useMemo(
+        () =>
+            composeRefs((view: FastImageRef | null) => {
+                if (view) view.reload = () => setReloads((count) => count + 1)
+            }, forwardedRef),
+        [forwardedRef],
+    )
     const priority = sourcePriority(source)
     // The source's blurDataUri, or its ThumbHash made into one (with
     // `react-native-fast-image/thumbhash`), shows blurred (see PreviewBlur)
@@ -140,6 +154,8 @@ function FastImageBase({
     // placeholders as it loads, as on iOS and Android. The browser loads it
     // like any image: it can't look in its cache only (cache: 'cacheOnly').
     const urlPlaceholder = placeholderSource(placeholder)?.uri
+    // reload() gives it a new <img> too, so one that failed is asked for again.
+    const placeholderKey = `${urlPlaceholder} ${reloads}`
     const [failedPlaceholder, setFailedPlaceholder] = useState<string>()
     // defaultSource only shows without `placeholder`, as on iOS and Android,
     // or in place of a thumbhash or blurDataUri the web can't show (one of
@@ -179,7 +195,7 @@ function FastImageBase({
         if (key) onLoadStart?.()
         // Once per image the browser is asked for.
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [key])
+    }, [key, reloads])
 
     return (
         <View
@@ -188,7 +204,7 @@ function FastImageBase({
             style={[styles.container, style]}
             onLayout={onLayout}
             pointerEvents={pointerEvents}
-            ref={forwardedRef}
+            ref={ref}
         >
             {defaultUri && showDefault ? (
                 <Picture
@@ -226,7 +242,7 @@ function FastImageBase({
             ) : null}
             {urlPlaceholder && showDefault ? (
                 <Picture
-                    key={`placeholder ${urlPlaceholder}`}
+                    key={`placeholder ${placeholderKey}`}
                     src={urlPlaceholder}
                     loading={loading}
                     // It only helps if it comes before the image, as on iOS
@@ -241,14 +257,14 @@ function FastImageBase({
                     // Tinted, not blurred, as on iOS and Android.
                     filter={tintColor ? `url(#${tintId})` : undefined}
                     // Nothing (no broken image icon) if it fails.
-                    hidden={failedPlaceholder === urlPlaceholder}
-                    onError={() => setFailedPlaceholder(urlPlaceholder)}
+                    hidden={failedPlaceholder === placeholderKey}
+                    onError={() => setFailedPlaceholder(placeholderKey)}
                     alt=""
                 />
             ) : null}
             {key && src ? (
                 <Picture
-                    key={several ? 'sizes' : key}
+                    key={`${several ? 'sizes' : key} ${reloads}`}
                     src={src}
                     srcSet={srcSet}
                     sizes={sizes}
@@ -383,10 +399,13 @@ function assetScale(asset: PackagerAsset): number {
     )
 }
 
+// What sizedSources reads of a source.
+type SizedSource = Pick<Source, 'uri' | 'width' | 'height' | 'scale'>
+
 // One of several sizes: a require()d image in react-native-web's asset
 // registry as a source with its file's size (Expo's web builds make it a
 // { uri, width, height } object already).
-function sizedSource(source: Source | number): Source | undefined {
+function sizedSource(source: SizedSource | number): SizedSource | undefined {
     if (typeof source !== 'number') return source
     const asset: PackagerAsset | undefined = getAssetByID(source)
     return asset
@@ -406,10 +425,12 @@ function sizedSource(source: Source | number): Source | undefined {
 // is laid out at; it only applies to lazy images, and otherwise, or in
 // browsers without it, the next value, 100vw (the viewport's width). src is the largest, for browsers without
 // srcset.
-function sizedSources(entries: (Source | number)[]) {
+function sizedSources(entries: (SizedSource | number)[]) {
     const sources = entries.map(sizedSource)
     const widths = sources
-        .filter((source): source is Source => !!source?.uri && !!source.width)
+        .filter(
+            (source): source is SizedSource => !!source?.uri && !!source.width,
+        )
         .map((source) => ({
             uri: source.uri as string,
             width: Math.round((source.width ?? 0) * (source.scale ?? 1)),
@@ -653,11 +674,15 @@ const tintStyle = {
 
 const FastImageMemo = memo(FastImageBase)
 
-const FastImageComponent: React.ComponentType<FastImageProps> = forwardRef(
-    (props: FastImageProps, ref: React.Ref<any>) => (
-        <FastImageMemo forwardedRef={ref} {...props} />
-    ),
-)
+// What a ref to FastImageBackground gets, as in index.tsx: a View's
+// (react-native-web's element). FastImage's has reload() too (FastImageRef).
+type ViewRef = React.ComponentRef<typeof View>
+
+const FastImageComponent: React.ForwardRefExoticComponent<
+    FastImageProps & React.RefAttributes<FastImageRef>
+> = forwardRef((props: FastImageProps, ref: React.Ref<FastImageRef>) => (
+    <FastImageMemo forwardedRef={ref} {...props} />
+))
 
 FastImageComponent.displayName = 'FastImage'
 
@@ -672,7 +697,9 @@ function getSize(uri: string) {
     })
 }
 
-const FastImage: React.ComponentType<FastImageProps> &
+const FastImage: React.ForwardRefExoticComponent<
+    FastImageProps & React.RefAttributes<FastImageRef>
+> &
     FastImageStaticProperties = FastImageComponent as any
 
 FastImage.cacheControl = cacheControl
@@ -720,33 +747,29 @@ const styles = StyleSheet.create({
     },
 })
 
-// FastImage forwards its ref, which its type doesn't say.
-const FastImageWithRef = FastImageComponent as React.ComponentType<
-    FastImageProps & { ref?: React.Ref<any> }
->
-
-export const FastImageBackground: React.ComponentType<FastImageBackgroundProps> =
-    forwardRef(
-        (
-            {
-                style,
-                imageStyle,
-                imageRef,
-                children,
-                ...props
-            }: FastImageBackgroundProps,
-            ref: React.Ref<any>,
-        ) => (
-            <View style={style} ref={ref}>
-                <FastImageWithRef
-                    {...props}
-                    style={[StyleSheet.absoluteFill, imageStyle]}
-                    ref={imageRef}
-                />
-                {children}
-            </View>
-        ),
-    )
+export const FastImageBackground: React.ForwardRefExoticComponent<
+    FastImageBackgroundProps & React.RefAttributes<ViewRef>
+> = forwardRef(
+    (
+        {
+            style,
+            imageStyle,
+            imageRef,
+            children,
+            ...props
+        }: FastImageBackgroundProps,
+        ref: React.Ref<ViewRef>,
+    ) => (
+        <View style={style} ref={ref}>
+            <FastImageComponent
+                {...props}
+                style={[StyleSheet.absoluteFill, imageStyle]}
+                ref={imageRef}
+            />
+            {children}
+        </View>
+    ),
+)
 
 FastImageBackground.displayName = 'FastImageBackground'
 

package/src/reactNativeCache.ts

@@ -0,0 +1,28 @@
+// React Native's `ImageURISource` cache values, which the views' `source`
+// takes so a source typed for React Native's Image works as it is. Not
+// documented: Fast Image's own values are the ones to use. Native reads
+// 'only-if-cached' as 'cacheOnly', and the others as the default, 'immutable'.
+import { warnOnce } from './warnings'
+
+declare const __DEV__: boolean | undefined
+
+export type ReactNativeCache =
+    | 'default'
+    | 'reload'
+    | 'force-cache'
+    | 'only-if-cached'
+
+// Warns for a source with 'reload', as the image isn't loaded again each time.
+export function warnIfReload(source: unknown) {
+    if (
+        typeof __DEV__ !== 'undefined' &&
+        __DEV__ &&
+        (source as { cache?: unknown } | null | undefined)?.cache === 'reload'
+    ) {
+        warnOnce(
+            'cache-reload',
+            "react-native-fast-image: `cache: 'reload'` loads the image as the default, `'immutable'`: it isn't loaded again each time. For an image that changes at the same url, use `cache: 'web'` (it follows the server's cache headers), or change its `cacheKey`.",
+            'warn',
+        )
+    }
+}

package/src/specs/FastImageViewNativeComponent.ts

@@ -1,15 +1,16 @@
 // The native image view, from React Native's Codegen (the New Architecture's
 // component). FastImage (index.tsx) renders it as its only view, and turns
 // its props into these.
+import type * as React from 'react'
 import type {
     CodegenTypes,
     ColorValue,
     HostComponent,
     ViewProps,
 } from 'react-native'
-// React Native's Babel plugin replaces the call below with the component's
-// view config, so the import isn't used when the app runs.
-import { codegenNativeComponent } from 'react-native'
+// React Native's Babel plugin replaces the calls below with the component's
+// view config and commands, so the imports aren't used when the app runs.
+import { codegenNativeCommands, codegenNativeComponent } from 'react-native'
 
 type LoadStartEvent = Readonly<{}>
 
@@ -86,6 +87,17 @@ export interface NativeProps extends ViewProps {
     onFastImageLoadEnd?: CodegenTypes.DirectEventHandler<LoadEndEvent>
 }
 
+interface NativeCommands {
+    // Loads the image again, as a new source would (with its events), keeping
+    // the image showing until then. ElementRef, which React Native 0.83's
+    // Codegen needs (later ones also take ComponentRef).
+    reload: (viewRef: React.ElementRef<HostComponent<NativeProps>>) => void
+}
+
+export const Commands: NativeCommands = codegenNativeCommands<NativeCommands>({
+    supportedCommands: ['reload'],
+})
+
 export default codegenNativeComponent<NativeProps>(
     'FastImageView',
 ) as HostComponent<NativeProps>