react-native-fast-image 10.5.0 → 10.7.0

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,17 +253,28 @@ 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/index.tsx
-function withoutPlaceholders(source) {
-	if (!hasSourcePlaceholder(source)) return source;
-	const { thumbhash: _thumbhash, blurDataUri: _blurDataUri, ...rest } = source;
-	return rest;
-}
-function sourcePlaceholder(source) {
-	if (!source || typeof source !== "object") return "";
-	const { thumbhash, blurDataUri } = source;
-	return thumbhash || dataUri(blurDataUri) || "";
+//#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.tsx
 const resolvePlaceholder = (placeholder) => {
 	if (typeof placeholder === "string") {
 		if (isImageName(placeholder)) return Platform.OS === "android" ? placeholder : { uri: placeholder };
@@ -334,28 +346,21 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, onLoadSt
 	const resolvedTintColor = tintColor != null ? tintColor : fromStyle(style, "tintColor");
 	const fit = resolveObjectFit(objectFit, style);
 	const position = objectPositionOrCentered(objectPosition);
-	const shared = hasSourcePlaceholder(placeholder) ? sourcePlaceholder(placeholder) : "";
-	const { resolvedSource, sources, sourcePlaceholders } = useMemo(() => {
-		const sources = Array.isArray(source) ? source.length === 1 ? void 0 : source : void 0;
-		const single = Array.isArray(source) ? source[0] : source;
-		const placeholders = (sources !== null && sources !== void 0 ? sources : [single]).map((entry) => sourcePlaceholder(entry) || shared);
-		return {
-			resolvedSource: sources ? void 0 : Image.resolveAssetSource(withoutPlaceholders(single)),
-			sources: (sources === null || sources === void 0 ? void 0 : sources.some(hasSourcePlaceholder)) ? sources.map(withoutPlaceholders) : sources,
-			sourcePlaceholders: placeholders.some(Boolean) ? placeholders : void 0
-		};
-	}, [source, shared]);
-	const resolvedPlaceholder = (_placeholderSource = placeholderSource(placeholder)) !== null && _placeholderSource !== void 0 ? _placeholderSource : resolvePlaceholder(hasSourcePlaceholder(placeholder) ? defaultSource : placeholder !== null && placeholder !== void 0 ? placeholder : defaultSource);
+	const resolvedSource = useMemo(() => {
+		for (const entry of [source].flat()) dataUri(entry === null || entry === void 0 ? void 0 : entry.blurDataUri);
+		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),
 		...resolveTransition(transition, (_defaultTransition = defaultTransition) !== null && _defaultTransition !== void 0 ? _defaultTransition : builtInTransition()),
 		source: resolvedSource,
-		sources,
-		sourcePlaceholders,
 		placeholder: resolvedPlaceholder,
 		onFastImageLoadStart: onLoadStart,
 		onFastImageProgress: onProgress,
@@ -377,6 +382,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

@@ -145,7 +145,7 @@ export type FastImageProps = $ReadOnly<{|
     onLoadStart?: ?() => void,
     onProgress?: ?(event: OnProgressEvent) => void,
 
-    source?: ?(FastImageSource | Array<FastImageSource> | number),
+    source?: ?(FastImageSource | Array<FastImageSource | number> | number),
     placeholder?: ?(number | string | SourcePlaceholder | PlaceholderSource),
     // Deprecated: use placeholder, which is the same.
     defaultSource?: ?number,
@@ -196,4 +196,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,12 +292,17 @@ 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 || urlPlaceholder ? defaultSource : placeholder !== null && placeholder !== void 0 ? placeholder : defaultSource);
+	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();
 	const ok = result && result.key === key ? result.ok : void 0;
 	const svgId = useId().replace(/[^\w-]/g, "");
@@ -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,
@@ -389,10 +415,9 @@ function shared(source, key, preview) {
 function resolveUri(source) {
 	let uri;
 	if (typeof source === "number") {
-		var _asset$scales$;
 		const asset = getAssetByID(source);
 		if (!asset) return void 0;
-		const scale = asset.scales.reduce((best, scale) => Math.abs(scale - PixelRatio.get()) < Math.abs(best - PixelRatio.get()) ? scale : best, (_asset$scales$ = asset.scales[0]) !== null && _asset$scales$ !== void 0 ? _asset$scales$ : 1);
+		const scale = assetScale(asset);
 		const suffix = scale !== 1 ? `@${scale}x` : "";
 		uri = `${asset.httpServerLocation}/${asset.name}${suffix}.${asset.type}`;
 	} else if (typeof source === "string") uri = source;
@@ -401,9 +426,24 @@ function resolveUri(source) {
 	const svg = uri === null || uri === void 0 ? void 0 : uri.match(/^(data:image\/svg\+xml;utf8,)(.*)/);
 	return svg ? svg[1] + encodeURIComponent(svg[2]) : uri || void 0;
 }
-function sizedSources(sources) {
+function assetScale(asset) {
+	var _asset$scales$;
+	return asset.scales.reduce((best, scale) => Math.abs(scale - PixelRatio.get()) < Math.abs(best - PixelRatio.get()) ? scale : best, (_asset$scales$ = asset.scales[0]) !== null && _asset$scales$ !== void 0 ? _asset$scales$ : 1);
+}
+function sizedSource(source) {
+	if (typeof source !== "number") return source;
+	const asset = getAssetByID(source);
+	return asset ? {
+		uri: resolveUri(source),
+		width: asset.width,
+		height: asset.height,
+		scale: assetScale(asset)
+	} : void 0;
+}
+function sizedSources(entries) {
 	var _largest$uri, _sources$find;
-	const widths = sources.filter((source) => (source === null || source === void 0 ? void 0 : source.uri) && source.width).map((source) => {
+	const sources = entries.map(sizedSource);
+	const widths = sources.filter((source) => !!(source === null || source === void 0 ? void 0 : source.uri) && !!source.width).map((source) => {
 		var _source$width, _source$scale;
 		return {
 			uri: source.uri,
@@ -563,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

@@ -145,7 +145,7 @@ export type FastImageProps = $ReadOnly<{|
     onLoadStart?: ?() => void,
     onProgress?: ?(event: OnProgressEvent) => void,
 
-    source?: ?(FastImageSource | Array<FastImageSource> | number),
+    source?: ?(FastImageSource | Array<FastImageSource | number> | number),
     placeholder?: ?(number | string | SourcePlaceholder | PlaceholderSource),
     // Deprecated: use placeholder, which is the same.
     defaultSource?: ?number,
@@ -196,4 +196,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/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<{
@@ -20,9 +21,7 @@ type LoadEndEvent = Readonly<{
 }>;
 export interface NativeProps extends ViewProps {
     source?: CodegenTypes.UnsafeMixed;
-    sources?: CodegenTypes.UnsafeMixed;
     placeholder?: CodegenTypes.UnsafeMixed;
-    sourcePlaceholders?: ReadonlyArray<string>;
     objectFit?: CodegenTypes.WithDefault<string, 'cover'>;
     objectPositionX?: CodegenTypes.WithDefault<CodegenTypes.Float, 0.5>;
     objectPositionXOffset?: CodegenTypes.Float;
@@ -46,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/FFFThumbHash.h

@@ -15,6 +15,9 @@ NS_ASSUME_NONNULL_BEGIN
 // Main thread.
 + (nullable UIImage*) imageForPlaceholder: (nullable NSString*)placeholder;
 
+// Whether a placeholder is a data uri (a blurDataUri) rather than a ThumbHash.
++ (BOOL) isDataUri: (nullable NSString*)placeholder;
+
 // The placeholder for a base64 ThumbHash (standard or url-safe, with or
 // without padding), or nil for an empty or invalid one. Main thread.
 + (nullable UIImage*) imageForThumbHash: (nullable NSString*)thumbhash;

package/ios/FastImage/FFFThumbHash.m

@@ -200,8 +200,12 @@ static UIImage* FFFBlurredPreview(UIImage* image) {
     return cache;
 }
 
++ (BOOL) isDataUri: (NSString*)placeholder {
+    return placeholder && [placeholder rangeOfString: @"data:" options: NSCaseInsensitiveSearch | NSAnchoredSearch].location != NSNotFound;
+}
+
 + (UIImage*) imageForPlaceholder: (NSString*)placeholder {
-    if ([placeholder rangeOfString: @"data:" options: NSCaseInsensitiveSearch | NSAnchoredSearch].location == NSNotFound) {
+    if (![self isDataUri: placeholder]) {
         return [self imageForThumbHash: placeholder];
     }
     UIImage* cached = [[self cache] objectForKey: placeholder];

package/ios/FastImage/FFFastImageView.h

@@ -28,9 +28,8 @@ typedef NS_ENUM(NSInteger, FFFObjectFit) {
 @property (nonatomic, copy) RCTDirectEventBlock onFastImageLoad;
 @property (nonatomic, copy) RCTDirectEventBlock onFastImageLoadEnd;
 @property (nonatomic, assign) FFFObjectFit objectFit;
-@property (nonatomic, strong) FFFastImageSource *source;
-// Several sources (2 or more) of the same image at different sizes: the view
-// loads the one whose size is closest to its own.
+// The `source` prop: one source, or several (sizes of one image), of which
+// the view loads the one whose size is closest to its own.
 @property (nonatomic, copy) NSArray<FFFastImageSource *> *sources;
 // The `placeholder` prop.
 @property (nonatomic, strong) UIImage *placeholder;
@@ -38,11 +37,14 @@ typedef NS_ENUM(NSInteger, FFFObjectFit) {
 // image, at a high priority (or only from the cache, with cache cacheOnly),
 // it shows over the other placeholders once it has.
 @property (nonatomic, strong) FFFastImageSource *placeholderSource;
-// The `sourcePlaceholders` prop, by the source's index (an empty string for
-// none; one for a single source): the picked source's ThumbHash or
-// blurDataUri (a data uri) shows instead of placeholder. JS sends them apart
-// from the sources, so a new one for the same image doesn't load it again.
+// The sources' ThumbHashes or blurDataUris (data uris), by the source's index
+// (an empty string for none): the picked source's shows instead of
+// placeholder. Set apart from the sources, so a new one for the same image
+// doesn't load it again.
 @property (nonatomic, copy) NSArray<NSString *> *sourcePlaceholders;
+// `placeholder` as a thumbhash or blurDataUri: shows for the sources without
+// their own.
+@property (nonatomic, copy) NSString *placeholderHash;
 @property (nonatomic, strong) UIColor *imageColor;
 // When it changes, the next image doesn't replace the current one: the view
 // clears first (for views reused for other content, like list rows).
@@ -80,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

@@ -44,9 +44,9 @@
 // downsample, or several sources: a load waits for the view's size (see
 // didSetProps).
 @property(nonatomic, assign) BOOL waitsForSize;
-// The `source` prop. With several `sources`, _source is the one picked for
-// the view's size instead.
-@property(nonatomic, strong) FFFastImageSource* propSource;
+// The source that loads: the `source` prop's, or with several the one
+// picked for the view's size.
+@property(nonatomic, strong) FFFastImageSource* source;
 // Several sources: the next load switches to another one for a new view
 // size, and the one after it is loading. It's the same picture at another
 // size, so it doesn't fade in.
@@ -749,21 +749,11 @@ NSString *FFFErrorMessage(NSError *error)
     return event;
 }
 
-- (void) setSource: (FFFastImageSource*)source {
-    if (self.propSource != source) {
-        self.propSource = source;
-        if (![self picksSource]) {
-            _source = source;
-        }
-        _needsReload = YES;
-    }
-}
-
 - (void) setSources: (NSArray<FFFastImageSource*>*)sources {
     if (_sources != sources) {
         _sources = [sources copy];
         if (![self picksSource]) {
-            _source = self.propSource;
+            _source = _sources.firstObject;
         }
         _needsReload = YES;
     }
@@ -847,11 +837,16 @@ NSString *FFFErrorMessage(NSError *error)
     return [_dynamicRangeLimit isEqualToString: @"constrained"] || [_dynamicRangeLimit isEqualToString: @"no-limit"];
 }
 
+// Shows at once, as a new source placeholder does (see updateHashImage),
+// without loading the image again.
 - (void) setPlaceholder: (UIImage*)placeholder {
-    if (_placeholder != placeholder) {
-        _placeholder = placeholder;
-        _needsReload = YES;
+    if (_placeholder == placeholder) {
+        return;
     }
+    UIImage* previous = [self shownPlaceholder];
+    BOOL showing = self.showsPlaceholder;
+    _placeholder = placeholder;
+    [self showChangedPlaceholder: previous showing: showing];
 }
 
 - (void) setSourcePlaceholders: (NSArray<NSString*>*)sourcePlaceholders {
@@ -859,6 +854,11 @@ NSString *FFFErrorMessage(NSError *error)
     [self updateHashImage];
 }
 
+- (void) setPlaceholderHash: (NSString*)placeholderHash {
+    _placeholderHash = [placeholderHash copy];
+    [self updateHashImage];
+}
+
 // What shows while the image loads and if it fails: placeholderSource's
 // image once it has loaded, the picked source's placeholder (its ThumbHash or
 // blurDataUri), or the placeholder prop.
@@ -912,6 +912,9 @@ NSString *FFFErrorMessage(NSError *error)
 }
 
 - (void) setPlaceholderSource: (FFFastImageSource*)placeholderSource {
+    if (!placeholderSource && !_placeholderSource) {
+        return;
+    }
     _placeholderSource = placeholderSource;
     [self cancelUrlPlaceholderLoad];
     [self showUrlPlaceholderImage: nil];
@@ -979,14 +982,18 @@ NSString *FFFErrorMessage(NSError *error)
     [self showChangedPlaceholder: previous showing: showing];
 }
 
-// The picked source's ThumbHash or blurDataUri, or nil.
+// The picked source's ThumbHash or blurDataUri, or placeholderHash, or nil.
 - (NSString*) pickedSourcePlaceholder {
     NSUInteger index = 0;
     if ([self picksSource]) {
         index = _source ? [_sources indexOfObjectIdenticalTo: _source] : NSNotFound;
+        // None until one is picked.
+        if (index == NSNotFound) {
+            return nil;
+        }
     }
     NSString* hash = index < _sourcePlaceholders.count ? _sourcePlaceholders[index] : nil;
-    return hash.length > 0 ? hash : nil;
+    return hash.length > 0 ? hash : _placeholderHash.length > 0 ? _placeholderHash : nil;
 }
 
 // Decodes the picked source's placeholder. A view showing the previous
@@ -1040,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

@@ -8,6 +8,7 @@
 #import <react/renderer/components/RNFastImageSpec/RCTComponentViewHelpers.h>
 
 #import "FFFastImageView.h"
+#import "FFFThumbHash.h"
 #import "RCTConvert+FFFastImage.h"
 
 using namespace facebook::react;
@@ -102,6 +103,41 @@ static id _Nullable FFFJSON(const folly::dynamic &value)
     return value.isNull() ? nil : FFFObjectFromDynamic(value);
 }
 
+// A source (or `placeholder`) without its thumbhash and blurDataUri, to
+// compare: one source, or each of several.
+static folly::dynamic FFFWithoutPlaceholders(const folly::dynamic &value)
+{
+    if (value.isArray()) {
+        folly::dynamic result = folly::dynamic::array;
+        for (const auto &entry : value) {
+            result.push_back(FFFWithoutPlaceholders(entry));
+        }
+        return result;
+    }
+    if (!value.isObject()) {
+        return value;
+    }
+    folly::dynamic result = value;
+    result.erase("thumbhash");
+    result.erase("blurDataUri");
+    return result;
+}
+
+// A source's (or `placeholder`'s) ThumbHash, or its blurDataUri if it's a data
+// uri (JS warns about another), or nil.
+static NSString *_Nullable FFFSourcePlaceholder(NSDictionary *source)
+{
+    id thumbhash = source[@"thumbhash"];
+    if ([thumbhash isKindOfClass:[NSString class]] && [thumbhash length] > 0) {
+        return thumbhash;
+    }
+    id blurDataUri = source[@"blurDataUri"];
+    if ([blurDataUri isKindOfClass:[NSString class]] && [FFFThumbHash isDataUri:blurDataUri]) {
+        return blurDataUri;
+    }
+    return nil;
+}
+
 // Whether the placeholder prop is a url to load apart from the image (a
 // source with an http or https uri), rather than an image to show at once: a
 // bundled image (served by the packager in development), a file or a data uri.
@@ -242,25 +278,36 @@ typedef NS_OPTIONS(int32_t, FFFEvent) {
     FFFastImageView *view = _imageView;
 
     if (all || oldViewProps.source != newViewProps.source) {
-        view.source = [RCTConvert FFFastImageSource:FFFJSON(newViewProps.source)];
-    }
-    if (all || oldViewProps.sources != newViewProps.sources) {
-        id sources = FFFJSON(newViewProps.sources);
-        view.sources = sources ? [RCTConvert FFFastImageSourceArray:sources] : nil;
+        // One source, or several (an array). Only a change besides their
+        // thumbhashes and blurDataUris loads again: a new one for the same
+        // image (e.g. one that arrives later) shows at once.
+        BOOL loads = all || FFFWithoutPlaceholders(oldViewProps.source) != FFFWithoutPlaceholders(newViewProps.source);
+        id json = FFFJSON(newViewProps.source);
+        NSArray *entries = [json isKindOfClass:[NSArray class]] ? json : json ? @[ json ] : @[];
+        NSMutableArray<FFFastImageSource *> *sources = [NSMutableArray arrayWithCapacity:entries.count];
+        NSMutableArray<NSString *> *placeholders = [NSMutableArray arrayWithCapacity:entries.count];
+        for (id entry in entries) {
+            if ([entry isKindOfClass:[NSDictionary class]]) {
+                if (loads) {
+                    [sources addObject:[RCTConvert FFFastImageSource:entry]];
+                }
+                [placeholders addObject:FFFSourcePlaceholder(entry) ?: @""];
+            }
+        }
+        if (loads) {
+            view.sources = sources.count > 0 ? sources : nil;
+        }
+        view.sourcePlaceholders = placeholders;
     }
     if (all || oldViewProps.placeholder != newViewProps.placeholder) {
+        // A thumbhash or blurDataUri, a url to load, or an image to show.
         id placeholder = FFFJSON(newViewProps.placeholder);
-        BOOL loads = FFFIsUrlPlaceholder(placeholder);
-        view.placeholder = placeholder && !loads ? [RCTConvert UIImage:placeholder] : nil;
+        BOOL hash = [placeholder isKindOfClass:[NSDictionary class]] && (placeholder[@"thumbhash"] || placeholder[@"blurDataUri"]);
+        BOOL loads = !hash && FFFIsUrlPlaceholder(placeholder);
+        view.placeholderHash = hash ? FFFSourcePlaceholder(placeholder) : nil;
+        view.placeholder = placeholder && !hash && !loads ? [RCTConvert UIImage:placeholder] : nil;
         view.placeholderSource = loads ? [RCTConvert FFFastImageSource:placeholder] : nil;
     }
-    if (all || oldViewProps.sourcePlaceholders != newViewProps.sourcePlaceholders) {
-        NSMutableArray<NSString *> *placeholders = [NSMutableArray arrayWithCapacity:newViewProps.sourcePlaceholders.size()];
-        for (const auto &placeholder : newViewProps.sourcePlaceholders) {
-            [placeholders addObject:[NSString stringWithUTF8String:placeholder.c_str()]];
-        }
-        view.sourcePlaceholders = placeholders.count > 0 ? placeholders : nil;
-    }
     if (all || oldViewProps.objectFit != newViewProps.objectFit) {
         view.objectFit = [RCTConvert FFFObjectFit:FFFString(newViewProps.objectFit)];
     }
@@ -341,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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "react-native-fast-image",
-    "version": "10.5.0",
+    "version": "10.7.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?.())
+    }
+}