react-native-fast-image 10.4.0 → 10.5.0

package/README.md

@@ -26,7 +26,7 @@ React Native's `Image` component handles image caching like browsers for the mos
 - **Responsive images**: give several sizes, and the one that fits the view loads ([`source`](#source)).
 - **Animated images** (GIF, WebP, APNG and AVIF) that can [loop](#loop) and [pause](#paused).
 - **Fades** in and between images ([`transition`](#transition)).
-- **Placeholders**: a blurred preview from a [ThumbHash](#sourcethumbhash) or a [tiny image](#sourceblurdatauri) while an image loads, or a bundled image ([`placeholder`](#placeholder)).
+- **Placeholders**: a blurred preview from a [ThumbHash](#sourcethumbhash) or a [tiny image](#sourceblurdatauri) while an image loads, a bundled image, or a url, e.g. a thumbnail that's already cached ([`placeholder`](#placeholder)).
 - [**SVG**](docs/formats.md#svg-images) and [**photo library**](#photo-library-images-ios-and-tvos) images.
 - [**`FastImageBackground`**](#fastimagebackground) for content over an image.
 - **Expo and web support**, with a [config plugin](#expo-config-plugin) for Expo.
@@ -266,7 +266,7 @@ With several sources, the scale `width` and `height` are multiplied by.
 
 #### `placeholder`
 
-**Type:** `string | number | SourcePlaceholder`
+**Type:** `string | number | PlaceholderSource | SourcePlaceholder`
 
 A placeholder shown while the image loads, and if it fails to load:
 
@@ -275,13 +275,15 @@ A placeholder shown while the image loads, and if it fails to load:
 - The name of an image bundled with the app (an iOS asset catalog image or an Android drawable): `placeholder="gray"`.
 - A [ThumbHash](#sourcethumbhash), shown blurred: `placeholder={{ thumbhash }}`.
 - A tiny image as a data uri, shown blurred: `placeholder={{ blurDataUri }}`.
+- A url, loaded and cached like a source: `placeholder="https://example.com/placeholder.png"`, or a source with `headers` or a `cacheKey`: `placeholder={{ uri, headers }}`.
+- A url only shown if it's already cached, e.g. a list's thumbnail while the full-size image loads: `placeholder={{ uri, cache: 'cacheOnly' }}`.
 
-A source's own `thumbhash` or `blurDataUri` is shown instead, if it has one.
+A source's own `thumbhash` or `blurDataUri` is shown instead, if it has one; a url placeholder shows over it once it has loaded.
 
 Notes:
 
-- A url isn't loaded: it's ignored, with a warning in development.
 - On Android, a `require()`d image doesn't show in debug builds, where the dev server serves it. Release builds show it.
+- On the web, a url loads like any image, also with `'cacheOnly'`: a browser can't look only in its cache.
 
 ---
 
@@ -844,6 +846,14 @@ Where the image is in the view: see [`objectPosition`](#objectposition).
 
 ---
 
+### `PlaceholderSource`
+
+**Type:** `Pick<Source, 'uri' | 'headers' | 'cacheKey' | 'cache'>`
+
+A url as `placeholder`, loaded like a source (see `placeholder`).
+
+---
+
 ### `PositionLength`
 
 **Type:** `` number | `${number}%` ``

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

@@ -27,7 +27,7 @@ import java.util.Map;
 import javax.annotation.Nullable;
 
 class FastImageViewConverter {
-    private static final Drawable TRANSPARENT_DRAWABLE = new ColorDrawable(Color.TRANSPARENT);
+    static final Drawable TRANSPARENT_DRAWABLE = new ColorDrawable(Color.TRANSPARENT);
 
     private static final Map<String, FastImageCacheControl> FAST_IMAGE_CACHE_CONTROL_MAP =
             new HashMap<String, FastImageCacheControl>() {{

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

@@ -315,9 +315,16 @@ class FastImageViewManager extends SimpleViewManager<FastImageViewWithUrl>
         view.setSources(sources.isNull() ? null : sources.asArray());
     }
 
-    // The `placeholder` prop: the resolved asset's uri, or a data uri.
+    // The `placeholder` prop: a url to load apart from the image, as a source
+    // (a map), or the resolved asset's uri or a data uri (a string).
     @Override
     public void setPlaceholder(FastImageViewWithUrl view, Dynamic source) {
+        if (source.getType() == ReadableType.Map) {
+            view.setPlaceholder(null);
+            view.setPlaceholderSource(source.asMap());
+            return;
+        }
+        view.setPlaceholderSource(null);
         String uri = source.isNull() ? null : source.asString();
         if (uri != null && FastImageThumbHash.isDataUri(uri)) {
             Bitmap bitmap = FastImageThumbHash.dataUri(uri);

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

@@ -30,6 +30,7 @@ import androidx.annotation.RequiresApi;
 import androidx.appcompat.widget.AppCompatImageView;
 
 import com.bumptech.glide.GenericTransitionOptions;
+import com.bumptech.glide.Priority;
 import com.bumptech.glide.RequestBuilder;
 import com.bumptech.glide.RequestManager;
 import com.bumptech.glide.load.DataSource;
@@ -39,6 +40,7 @@ import com.bumptech.glide.load.resource.drawable.DrawableTransitionOptions;
 import com.bumptech.glide.load.resource.gif.GifDrawable;
 import com.bumptech.glide.request.Request;
 import com.bumptech.glide.request.RequestOptions;
+import com.bumptech.glide.request.target.CustomTarget;
 import com.bumptech.glide.request.target.DrawableImageViewTarget;
 import com.bumptech.glide.request.target.SizeReadyCallback;
 import com.bumptech.glide.request.transition.NoTransition;
@@ -309,6 +311,8 @@ class FastImageViewWithUrl extends AppCompatImageView implements ReactPointerEve
     }
 
     public void setPlaceholder(@Nullable Drawable placeholder) {
+        // None again (the placeholder prop is a url) doesn't reload.
+        if (placeholder == null && mPlaceholder == null) return;
         mNeedsReload = true;
         mPlaceholder = placeholder;
     }
@@ -338,6 +342,114 @@ class FastImageViewWithUrl extends AppCompatImageView implements ReactPointerEve
         updatePlaceholder();
     }
 
+    // `placeholder` as a url (a source): loaded apart from the image, at the
+    // most urgent priority, as it only helps if it comes before the image (or
+    // only from Glide's caches, with cache cacheOnly).
+    // Once it has, a copy shows instead of the other placeholders: FastImage's
+    // own drawable, which Glide doesn't recycle, so a fade can still draw it
+    // after its request is cleared. A failure shows nothing more.
+    @Nullable
+    private ReadableMap mPlaceholderSource = null;
+    @Nullable
+    private Drawable mUrlPlaceholder = null;
+    @Nullable
+    private CustomTarget<Drawable> mUrlPlaceholderTarget = null;
+
+    // Its load waits for the view's size (see startUrlPlaceholderLoad).
+    private boolean mUrlPlaceholderWaitsForSize = false;
+
+    public void setPlaceholderSource(@Nullable ReadableMap source) {
+        if (source == null && mPlaceholderSource == null) return;
+        mPlaceholderSource = source;
+        clearUrlPlaceholderTarget();
+        mUrlPlaceholderWaitsForSize = false;
+        mUrlPlaceholder = null;
+        updatePlaceholder();
+        scheduleUrlPlaceholderLoad();
+    }
+
+    // Starts placeholderSource's load once the current callbacks have run: an
+    // image from the memory cache has shown by then, and needs none.
+    private void scheduleUrlPlaceholderLoad() {
+        post(new Runnable() {
+            @Override
+            public void run() {
+                startUrlPlaceholderLoad();
+            }
+        });
+    }
+
+    // Loads placeholderSource's image while the image loads (or after it
+    // failed), at the view's size, once it has one: not if the image showed,
+    // or it's already loaded or loading.
+    private void startUrlPlaceholderLoad() {
+        if (requestManager == null || mDropped || mUrlPlaceholder != null || mUrlPlaceholderTarget != null
+                || !FastImageViewConverter.hasUri(mPlaceholderSource)) return;
+        if (mLoadEnded && mShownRequest != null) return;
+        if (getWidth() <= 0 || getHeight() <= 0) {
+            mUrlPlaceholderWaitsForSize = true;
+            return;
+        }
+        FastImageSource imageSource = FastImageViewConverter.getImageSource(getContext(), mPlaceholderSource);
+        if (imageSource == null) return;
+        CustomTarget<Drawable> target = new CustomTarget<Drawable>(getWidth(), getHeight()) {
+            @Override
+            public void onResourceReady(@NonNull Drawable resource, @Nullable Transition<? super Drawable> transition) {
+                if (this != mUrlPlaceholderTarget) return;
+                mUrlPlaceholder = ownCopy(resource);
+                updatePlaceholder();
+                // With the copy, Glide's can go back to its pools (a load
+                // can't be cleared from its own callback).
+                final CustomTarget<Drawable> done = this;
+                post(new Runnable() {
+                    @Override
+                    public void run() {
+                        if (requestManager != null) requestManager.clear(done);
+                    }
+                });
+            }
+
+            @Override
+            public void onLoadCleared(@Nullable Drawable placeholder) {
+            }
+        };
+        mUrlPlaceholderTarget = target;
+        requestManager
+                .load(imageSource.getSourceForLoad())
+                .apply(FastImageViewConverter.getOptions(getContext(), imageSource, mPlaceholderSource)
+                        .priority(Priority.IMMEDIATE)
+                        // Copied on a software canvas (see ownCopy).
+                        .disallowHardwareConfig())
+                .into(target);
+    }
+
+    private void clearUrlPlaceholderTarget() {
+        if (mUrlPlaceholderTarget != null && requestManager != null) requestManager.clear(mUrlPlaceholderTarget);
+        mUrlPlaceholderTarget = null;
+    }
+
+    // A bitmap of the drawable (an animated one's first frame), scaled up
+    // smoothly as the other placeholders are, or null for one with no size.
+    @Nullable
+    private Drawable ownCopy(Drawable drawable) {
+        int width = drawable.getIntrinsicWidth();
+        int height = drawable.getIntrinsicHeight();
+        if (width <= 0 || height <= 0) return null;
+        try {
+            Bitmap bitmap = Bitmap.createBitmap(width, height, Bitmap.Config.ARGB_8888);
+            Canvas canvas = new Canvas(bitmap);
+            Drawable copy = drawable.getConstantState() != null ? drawable.getConstantState().newDrawable().mutate() : drawable;
+            copy.setBounds(0, 0, width, height);
+            copy.draw(canvas);
+            BitmapDrawable own = new BitmapDrawable(getResources(), bitmap);
+            own.setFilterBitmap(true);
+            return own;
+        } catch (OutOfMemoryError | IllegalStateException e) {
+            // As startFade: out of memory, or a hardware bitmap after all.
+            return null;
+        }
+    }
+
     // The picked source's ThumbHash or blurDataUri, or null.
     @Nullable
     private String pickedSourcePlaceholder() {
@@ -372,10 +484,16 @@ class FastImageViewWithUrl extends AppCompatImageView implements ReactPointerEve
                 mInvalidPlaceholder = key;
             }
         }
+        // placeholderSource's image, once it has loaded, shows instead.
+        if (mUrlPlaceholder != null) placeholder = mUrlPlaceholder;
         if (placeholder == mShownPlaceholder) return;
         boolean showing = mShowsPlaceholder;
         mShownPlaceholder = placeholder;
-        if (showing) setImageDrawable(placeholder);
+        // Also one that arrives while the view shows nothing (no placeholder
+        // while the image loads, or after it failed): never over an image.
+        Drawable shown = getDrawable();
+        boolean showsNothing = shown == null || shown == FastImageViewConverter.TRANSPARENT_DRAWABLE;
+        if (showing || (placeholder != null && showsNothing)) setImageDrawable(placeholder);
     }
 
     // The events JS has a handler for (the handledEvents prop): the view only
@@ -449,6 +567,7 @@ class FastImageViewWithUrl extends AppCompatImageView implements ReactPointerEve
     void drop() {
         mDropped = true;
         clearView(requestManager);
+        clearUrlPlaceholderTarget();
         endProgress();
     }
 
@@ -1183,10 +1302,11 @@ class FastImageViewWithUrl extends AppCompatImageView implements ReactPointerEve
             setImageMatrix(matrix);
             return;
         }
-        // A source's placeholder (a ThumbHash or a blurDataUri) stands for an
-        // image whose size isn't known yet: with scale-down and none (which
-        // show an image at its own size), it's shown as with contain.
-        boolean hashFits = drawable == mShownPlaceholder && mPlaceholderKey != null;
+        // A source's placeholder (a ThumbHash or a blurDataUri), or
+        // placeholderSource's image, stands for an image whose size isn't
+        // known yet: with scale-down and none (which show an image at its own
+        // size), it's shown as with contain.
+        boolean hashFits = drawable == mShownPlaceholder && (mPlaceholderKey != null || drawable == mUrlPlaceholder);
         if (mLayoutScaleType == ScaleType.CENTER_CROP || mLayoutScaleType == ScaleType.FIT_CENTER || hashFits) {
             float x = viewWidth / drawableWidth;
             float y = viewHeight / drawableHeight;
@@ -1352,6 +1472,17 @@ class FastImageViewWithUrl extends AppCompatImageView implements ReactPointerEve
     // The loading image loaded (FastImageRequestListener).
     void onImageLoaded() {
         mLoadEnded = true;
+        // The image came first: its placeholder isn't needed (not from
+        // within Glide's callback).
+        if (mUrlPlaceholder == null) {
+            mUrlPlaceholderWaitsForSize = false;
+            post(new Runnable() {
+                @Override
+                public void run() {
+                    if (mUrlPlaceholder == null && mLoadEnded && mShownRequest != null) clearUrlPlaceholderTarget();
+                }
+            });
+        }
         endProgress();
         // Before the view shows it (the target does once this returns).
         applyObjectFit();
@@ -1380,6 +1511,10 @@ class FastImageViewWithUrl extends AppCompatImageView implements ReactPointerEve
             invalidate();
         }
         if (!switchSourceIfResized()) reloadIfResized();
+        if (mUrlPlaceholderWaitsForSize && w > 0 && h > 0) {
+            mUrlPlaceholderWaitsForSize = false;
+            scheduleUrlPlaceholderLoad();
+        }
     }
 
     private void reloadIfResized() {
@@ -1508,6 +1643,7 @@ class FastImageViewWithUrl extends AppCompatImageView implements ReactPointerEve
             }
         });
         builder.into(target);
+        if (!quiet) scheduleUrlPlaceholderLoad();
     }
 
     // Loading the image that's showing again (at a new size, or with another
@@ -1524,6 +1660,8 @@ class FastImageViewWithUrl extends AppCompatImageView implements ReactPointerEve
         endProgress();
         applyObjectFit();
         mShownRequest = null;
+        // Shows instead of the other placeholders once it loads.
+        scheduleUrlPlaceholderLoad();
         final int load = mLoadCount;
         // Not from within Glide's callback. Without a thumbnail Glide shows the
         // placeholder the request started with: a source placeholder that changed since
@@ -1605,6 +1743,7 @@ class FastImageViewWithUrl extends AppCompatImageView implements ReactPointerEve
 
             // Clear the image.
             setImageDrawable(null);
+            scheduleUrlPlaceholderLoad();
             return;
         }
 
@@ -1632,6 +1771,7 @@ class FastImageViewWithUrl extends AppCompatImageView implements ReactPointerEve
 
             endProgress();
             setImageDrawable(mShownPlaceholder);
+            scheduleUrlPlaceholderLoad();
             return;
         }
 

package/dist/index.cjs.js

@@ -261,8 +261,14 @@ var FastImageViewNativeComponent_default = (0, react_native.codegenNativeCompone
 var NativeFastImageModule_default = react_native.TurboModuleRegistry.get("FastImageModule");
 //#endregion
 //#region src/placeholders.ts
+const SCHEME = /^[a-z][a-z\d+.-]*:/i;
 function isImageName(value) {
-	return !/^[a-z][a-z\d+.-]*:/i.test(value) && !value.startsWith("/");
+	return !SCHEME.test(value) && !value.startsWith("/");
+}
+function placeholderSource(value) {
+	const uri = typeof value === "string" ? value : value && typeof value === "object" ? value.uri : void 0;
+	if (typeof uri !== "string" || !/^https?:/i.test(uri)) return void 0;
+	return typeof value === "string" ? { uri } : value;
 }
 function hasSourcePlaceholder(value) {
 	return !!value && typeof value === "object" && ("thumbhash" in value || "blurDataUri" in value);
@@ -270,7 +276,7 @@ function hasSourcePlaceholder(value) {
 function dataUri(value) {
 	if (typeof value !== "string" || value === "") return void 0;
 	if (/^data:/i.test(value)) return value;
-	if (typeof __DEV__ !== "undefined" && __DEV__) warnOnce("placeholder-url", `react-native-fast-image: \`placeholder\` and \`blurDataUri\` don't load urls: "${value.slice(0, 60)}" is ignored. Use a data uri (data:image/…), or for \`placeholder\`, a require()d image or the name of an image bundled with the app.`, "warn");
+	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
@@ -348,7 +354,7 @@ function builtInTransition() {
 }
 let defaultTransition;
 function FastImageBase({ source, placeholder, defaultSource, tintColor, onLoadStart, onProgress, onLoad, onError, onLoadEnd, style, children, objectFit, objectPosition, loop, transition, loading: _loading, sizes: _sizes, forwardedRef, ...viewProps }) {
-	var _props$recyclingKey, _defaultTransition;
+	var _placeholderSource, _props$recyclingKey, _defaultTransition;
 	const { fallback, resizeMode: _resizeMode, ...props } = viewProps;
 	if (__DEV__ && fallback !== void 0) warnOnce("fallback", "react-native-fast-image: `fallback` was removed in 10.0, and does nothing: images always load natively. Remove it, or use React Native's Image for those images.", "warn");
 	if (__DEV__) warnIfChildren(children);
@@ -366,7 +372,7 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, onLoadSt
 			sourcePlaceholders: placeholders.some(Boolean) ? placeholders : void 0
 		};
 	}, [source, shared]);
-	const resolvedPlaceholder = resolvePlaceholder(hasSourcePlaceholder(placeholder) ? defaultSource : placeholder !== null && placeholder !== void 0 ? placeholder : defaultSource);
+	const resolvedPlaceholder = (_placeholderSource = placeholderSource(placeholder)) !== null && _placeholderSource !== void 0 ? _placeholderSource : resolvePlaceholder(hasSourcePlaceholder(placeholder) ? defaultSource : placeholder !== null && placeholder !== void 0 ? placeholder : defaultSource);
 	return /* @__PURE__ */ react.default.createElement(FastImageViewNativeComponent_default, {
 		...props,
 		ref: forwardedRef,

package/dist/index.cjs.js.flow

@@ -110,6 +110,13 @@ export type PreloadResult = PreloadSuccess | PreloadFailure
 export type PreloadFn = (
     sources: Array<FastImageSource>,
 ) => Promise<Array<PreloadResult>>
+export type PlaceholderSource = {
+    uri?: string,
+    headers?: Object,
+    cacheKey?: string,
+    cache?: CacheControls,
+}
+
 export type SourcePlaceholder = {
     thumbhash?: string,
     blurDataUri?: string,
@@ -139,7 +146,7 @@ export type FastImageProps = $ReadOnly<{|
     onProgress?: ?(event: OnProgressEvent) => void,
 
     source?: ?(FastImageSource | Array<FastImageSource> | number),
-    placeholder?: ?(number | string | SourcePlaceholder),
+    placeholder?: ?(number | string | SourcePlaceholder | PlaceholderSource),
     // Deprecated: use placeholder, which is the same.
     defaultSource?: ?number,
 

package/dist/index.cjs.web.js

@@ -268,13 +268,18 @@ function cssPosition({ x, y }) {
 }
 //#endregion
 //#region src/placeholders.ts
+function placeholderSource(value) {
+	const uri = typeof value === "string" ? value : value && typeof value === "object" ? value.uri : void 0;
+	if (typeof uri !== "string" || !/^https?:/i.test(uri)) return void 0;
+	return typeof value === "string" ? { uri } : value;
+}
 function hasSourcePlaceholder(value) {
 	return !!value && typeof value === "object" && ("thumbhash" in value || "blurDataUri" in value);
 }
 function dataUri(value) {
 	if (typeof value !== "string" || value === "") return void 0;
 	if (/^data:/i.test(value)) return value;
-	if (typeof __DEV__ !== "undefined" && __DEV__) warnOnce("placeholder-url", `react-native-fast-image: \`placeholder\` and \`blurDataUri\` don't load urls: "${value.slice(0, 60)}" is ignored. Use a data uri (data:image/…), or for \`placeholder\`, a require()d image or the name of an image bundled with the app.`, "warn");
+	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.web.tsx
@@ -284,7 +289,7 @@ const notSupported = {
 };
 const useClientLayoutEffect = globalThis.document === void 0 ? react.useEffect : react.useLayoutEffect;
 function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadius, onLoadStart, onLoad, onError, onLoadEnd, style, children, objectFit, objectPosition, loading, sizes, dynamicRangeLimit, forwardedRef, onLayout, pointerEvents, recyclingKey: _recyclingKey, loop: _loop, imageRendering: _imageRendering, paused: _paused, transition: _transition, downsample: _downsample, onProgress: _onProgress, ...props }) {
-	var _resolveUri;
+	var _resolveUri, _placeholderSource;
 	if (typeof __DEV__ !== "undefined" && __DEV__) warnIfChildren(children);
 	const { accessibilityLabel, "aria-label": ariaLabel, resizeMode: _resizeMode, ...viewProps } = props;
 	const label = ariaLabel || accessibilityLabel || void 0;
@@ -296,7 +301,9 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadi
 	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 defaultUri = blurUri !== null && blurUri !== void 0 ? blurUri : resolveUri(preview ? defaultSource : placeholder !== null && placeholder !== void 0 ? placeholder : defaultSource);
+	const urlPlaceholder = (_placeholderSource = placeholderSource(placeholder)) === null || _placeholderSource === void 0 ? void 0 : _placeholderSource.uri;
+	const [failedPlaceholder, setFailedPlaceholder] = (0, react.useState)();
+	const defaultUri = blurUri !== null && blurUri !== void 0 ? blurUri : resolveUri(preview || urlPlaceholder ? defaultSource : placeholder !== null && placeholder !== void 0 ? placeholder : defaultSource);
 	const [result, setResult] = (0, react.useState)();
 	const ok = result && result.key === key ? result.ok : void 0;
 	const svgId = (0, react.useId)().replace(/[^\w-]/g, "");
@@ -305,7 +312,7 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadi
 	const fit = resolveObjectFit(objectFit, style);
 	const position = cssPosition(objectPositionOrCentered(objectPosition));
 	const filter = [blurRadius ? `blur(${blurRadius}px)` : "", tintColor ? `url(#${tintId})` : ""].filter(Boolean).join(" ") || void 0;
-	const showDefault = !!defaultUri && ok !== true;
+	const showDefault = ok !== true;
 	useClientLayoutEffect(() => {
 		if (key) onLoadStart === null || onLoadStart === void 0 || onLoadStart();
 	}, [key]);
@@ -326,6 +333,18 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadi
 		position,
 		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}`,
+		src: urlPlaceholder,
+		loading,
+		priority: "high",
+		dynamicRangeLimit,
+		fit: fit === "scale-down" || fit === "none" ? "contain" : fit,
+		position,
+		filter: tintColor ? `url(#${tintId})` : void 0,
+		hidden: failedPlaceholder === urlPlaceholder,
+		onError: () => setFailedPlaceholder(urlPlaceholder),
+		alt: ""
 	}) : null, key && src ? /* @__PURE__ */ react.default.createElement(Picture, {
 		key: several ? "sizes" : key,
 		src,

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

@@ -110,6 +110,13 @@ export type PreloadResult = PreloadSuccess | PreloadFailure
 export type PreloadFn = (
     sources: Array<FastImageSource>,
 ) => Promise<Array<PreloadResult>>
+export type PlaceholderSource = {
+    uri?: string,
+    headers?: Object,
+    cacheKey?: string,
+    cache?: CacheControls,
+}
+
 export type SourcePlaceholder = {
     thumbhash?: string,
     blurDataUri?: string,
@@ -139,7 +146,7 @@ export type FastImageProps = $ReadOnly<{|
     onProgress?: ?(event: OnProgressEvent) => void,
 
     source?: ?(FastImageSource | Array<FastImageSource> | number),
-    placeholder?: ?(number | string | SourcePlaceholder),
+    placeholder?: ?(number | string | SourcePlaceholder | PlaceholderSource),
     // Deprecated: use placeholder, which is the same.
     defaultSource?: ?number,
 

package/dist/index.d.ts

@@ -154,6 +154,8 @@ export type Source = {
 };
 /** A `thumbhash` or `blurDataUri` as `placeholder`. */
 export type SourcePlaceholder = Pick<Source, 'thumbhash' | 'blurDataUri'>;
+/** A url as `placeholder`, loaded like a source (see `placeholder`). */
+export type PlaceholderSource = Pick<Source, 'uri' | 'headers' | 'cacheKey' | 'cache'>;
 /** How the image fades in: see [`transition`](#transition). */
 export type Transition = {
     /**
@@ -343,17 +345,23 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
      *   `placeholder={{ thumbhash }}`.
      * - A tiny image as a data uri, shown blurred:
      *   `placeholder={{ blurDataUri }}`.
+     * - A url, loaded and cached like a source:
+     *   `placeholder="https://example.com/placeholder.png"`, or a source with
+     *   `headers` or a `cacheKey`: `placeholder={{ uri, headers }}`.
+     * - A url only shown if it's already cached, e.g. a list's thumbnail while
+     *   the full-size image loads: `placeholder={{ uri, cache: 'cacheOnly' }}`.
      *
      * A source's own `thumbhash` or `blurDataUri` is shown instead, if it has
-     * one.
+     * one; a url placeholder shows over it once it has loaded.
      *
      * Notes:
      *
-     * - A url isn't loaded: it's ignored, with a warning in development.
      * - On Android, a `require()`d image doesn't show in debug builds, where
      *   the dev server serves it. Release builds show it.
+     * - On the web, a url loads like any image, also with `'cacheOnly'`: a
+     *   browser can't look only in its cache.
      */
-    placeholder?: ImageRequireSource | string | SourcePlaceholder;
+    placeholder?: ImageRequireSource | string | SourcePlaceholder | PlaceholderSource;
     /**
      * @deprecated Use `placeholder`, which does the same.
      */

package/dist/index.js

@@ -234,8 +234,14 @@ var FastImageViewNativeComponent_default = codegenNativeComponent("FastImageView
 var NativeFastImageModule_default = TurboModuleRegistry.get("FastImageModule");
 //#endregion
 //#region src/placeholders.ts
+const SCHEME = /^[a-z][a-z\d+.-]*:/i;
 function isImageName(value) {
-	return !/^[a-z][a-z\d+.-]*:/i.test(value) && !value.startsWith("/");
+	return !SCHEME.test(value) && !value.startsWith("/");
+}
+function placeholderSource(value) {
+	const uri = typeof value === "string" ? value : value && typeof value === "object" ? value.uri : void 0;
+	if (typeof uri !== "string" || !/^https?:/i.test(uri)) return void 0;
+	return typeof value === "string" ? { uri } : value;
 }
 function hasSourcePlaceholder(value) {
 	return !!value && typeof value === "object" && ("thumbhash" in value || "blurDataUri" in value);
@@ -243,7 +249,7 @@ function hasSourcePlaceholder(value) {
 function dataUri(value) {
 	if (typeof value !== "string" || value === "") return void 0;
 	if (/^data:/i.test(value)) return value;
-	if (typeof __DEV__ !== "undefined" && __DEV__) warnOnce("placeholder-url", `react-native-fast-image: \`placeholder\` and \`blurDataUri\` don't load urls: "${value.slice(0, 60)}" is ignored. Use a data uri (data:image/…), or for \`placeholder\`, a require()d image or the name of an image bundled with the app.`, "warn");
+	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
@@ -321,7 +327,7 @@ function builtInTransition() {
 }
 let defaultTransition;
 function FastImageBase({ source, placeholder, defaultSource, tintColor, onLoadStart, onProgress, onLoad, onError, onLoadEnd, style, children, objectFit, objectPosition, loop, transition, loading: _loading, sizes: _sizes, forwardedRef, ...viewProps }) {
-	var _props$recyclingKey, _defaultTransition;
+	var _placeholderSource, _props$recyclingKey, _defaultTransition;
 	const { fallback, resizeMode: _resizeMode, ...props } = viewProps;
 	if (__DEV__ && fallback !== void 0) warnOnce("fallback", "react-native-fast-image: `fallback` was removed in 10.0, and does nothing: images always load natively. Remove it, or use React Native's Image for those images.", "warn");
 	if (__DEV__) warnIfChildren(children);
@@ -339,7 +345,7 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, onLoadSt
 			sourcePlaceholders: placeholders.some(Boolean) ? placeholders : void 0
 		};
 	}, [source, shared]);
-	const resolvedPlaceholder = resolvePlaceholder(hasSourcePlaceholder(placeholder) ? defaultSource : placeholder !== null && placeholder !== void 0 ? placeholder : defaultSource);
+	const resolvedPlaceholder = (_placeholderSource = placeholderSource(placeholder)) !== null && _placeholderSource !== void 0 ? _placeholderSource : resolvePlaceholder(hasSourcePlaceholder(placeholder) ? defaultSource : placeholder !== null && placeholder !== void 0 ? placeholder : defaultSource);
 	return /* @__PURE__ */ React.createElement(FastImageViewNativeComponent_default, {
 		...props,
 		ref: forwardedRef,

package/dist/index.js.flow

@@ -110,6 +110,13 @@ export type PreloadResult = PreloadSuccess | PreloadFailure
 export type PreloadFn = (
     sources: Array<FastImageSource>,
 ) => Promise<Array<PreloadResult>>
+export type PlaceholderSource = {
+    uri?: string,
+    headers?: Object,
+    cacheKey?: string,
+    cache?: CacheControls,
+}
+
 export type SourcePlaceholder = {
     thumbhash?: string,
     blurDataUri?: string,
@@ -139,7 +146,7 @@ export type FastImageProps = $ReadOnly<{|
     onProgress?: ?(event: OnProgressEvent) => void,
 
     source?: ?(FastImageSource | Array<FastImageSource> | number),
-    placeholder?: ?(number | string | SourcePlaceholder),
+    placeholder?: ?(number | string | SourcePlaceholder | PlaceholderSource),
     // Deprecated: use placeholder, which is the same.
     defaultSource?: ?number,
 

package/dist/index.web.js

@@ -241,13 +241,18 @@ function cssPosition({ x, y }) {
 }
 //#endregion
 //#region src/placeholders.ts
+function placeholderSource(value) {
+	const uri = typeof value === "string" ? value : value && typeof value === "object" ? value.uri : void 0;
+	if (typeof uri !== "string" || !/^https?:/i.test(uri)) return void 0;
+	return typeof value === "string" ? { uri } : value;
+}
 function hasSourcePlaceholder(value) {
 	return !!value && typeof value === "object" && ("thumbhash" in value || "blurDataUri" in value);
 }
 function dataUri(value) {
 	if (typeof value !== "string" || value === "") return void 0;
 	if (/^data:/i.test(value)) return value;
-	if (typeof __DEV__ !== "undefined" && __DEV__) warnOnce("placeholder-url", `react-native-fast-image: \`placeholder\` and \`blurDataUri\` don't load urls: "${value.slice(0, 60)}" is ignored. Use a data uri (data:image/…), or for \`placeholder\`, a require()d image or the name of an image bundled with the app.`, "warn");
+	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.web.tsx
@@ -257,7 +262,7 @@ const notSupported = {
 };
 const useClientLayoutEffect = globalThis.document === void 0 ? useEffect : useLayoutEffect;
 function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadius, onLoadStart, onLoad, onError, onLoadEnd, style, children, objectFit, objectPosition, loading, sizes, dynamicRangeLimit, forwardedRef, onLayout, pointerEvents, recyclingKey: _recyclingKey, loop: _loop, imageRendering: _imageRendering, paused: _paused, transition: _transition, downsample: _downsample, onProgress: _onProgress, ...props }) {
-	var _resolveUri;
+	var _resolveUri, _placeholderSource;
 	if (typeof __DEV__ !== "undefined" && __DEV__) warnIfChildren(children);
 	const { accessibilityLabel, "aria-label": ariaLabel, resizeMode: _resizeMode, ...viewProps } = props;
 	const label = ariaLabel || accessibilityLabel || void 0;
@@ -269,7 +274,9 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadi
 	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 defaultUri = blurUri !== null && blurUri !== void 0 ? blurUri : resolveUri(preview ? defaultSource : placeholder !== null && placeholder !== void 0 ? placeholder : defaultSource);
+	const urlPlaceholder = (_placeholderSource = placeholderSource(placeholder)) === null || _placeholderSource === void 0 ? void 0 : _placeholderSource.uri;
+	const [failedPlaceholder, setFailedPlaceholder] = useState();
+	const defaultUri = blurUri !== null && blurUri !== void 0 ? blurUri : resolveUri(preview || urlPlaceholder ? defaultSource : 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, "");
@@ -278,7 +285,7 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadi
 	const fit = resolveObjectFit(objectFit, style);
 	const position = cssPosition(objectPositionOrCentered(objectPosition));
 	const filter = [blurRadius ? `blur(${blurRadius}px)` : "", tintColor ? `url(#${tintId})` : ""].filter(Boolean).join(" ") || void 0;
-	const showDefault = !!defaultUri && ok !== true;
+	const showDefault = ok !== true;
 	useClientLayoutEffect(() => {
 		if (key) onLoadStart === null || onLoadStart === void 0 || onLoadStart();
 	}, [key]);
@@ -299,6 +306,18 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadi
 		position,
 		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}`,
+		src: urlPlaceholder,
+		loading,
+		priority: "high",
+		dynamicRangeLimit,
+		fit: fit === "scale-down" || fit === "none" ? "contain" : fit,
+		position,
+		filter: tintColor ? `url(#${tintId})` : void 0,
+		hidden: failedPlaceholder === urlPlaceholder,
+		onError: () => setFailedPlaceholder(urlPlaceholder),
+		alt: ""
 	}) : null, key && src ? /* @__PURE__ */ React.createElement(Picture, {
 		key: several ? "sizes" : key,
 		src,

package/dist/index.web.js.flow

@@ -110,6 +110,13 @@ export type PreloadResult = PreloadSuccess | PreloadFailure
 export type PreloadFn = (
     sources: Array<FastImageSource>,
 ) => Promise<Array<PreloadResult>>
+export type PlaceholderSource = {
+    uri?: string,
+    headers?: Object,
+    cacheKey?: string,
+    cache?: CacheControls,
+}
+
 export type SourcePlaceholder = {
     thumbhash?: string,
     blurDataUri?: string,
@@ -139,7 +146,7 @@ export type FastImageProps = $ReadOnly<{|
     onProgress?: ?(event: OnProgressEvent) => void,
 
     source?: ?(FastImageSource | Array<FastImageSource> | number),
-    placeholder?: ?(number | string | SourcePlaceholder),
+    placeholder?: ?(number | string | SourcePlaceholder | PlaceholderSource),
     // Deprecated: use placeholder, which is the same.
     defaultSource?: ?number,
 

package/dist/placeholders.d.ts

@@ -1,4 +1,5 @@
-import type { SourcePlaceholder } from './index';
+import type { PlaceholderSource, SourcePlaceholder } from './index';
 export declare function isImageName(value: string): boolean;
+export declare function placeholderSource(value: unknown): PlaceholderSource | undefined;
 export declare function hasSourcePlaceholder(value: unknown): value is SourcePlaceholder;
 export declare function dataUri(value: unknown): string | undefined;

package/ios/FastImage/FFFastImageView.h

@@ -34,6 +34,10 @@ typedef NS_ENUM(NSInteger, FFFObjectFit) {
 @property (nonatomic, copy) NSArray<FFFastImageSource *> *sources;
 // The `placeholder` prop.
 @property (nonatomic, strong) UIImage *placeholder;
+// `placeholder` as a url (a source): loaded apart from the
+// 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

package/ios/FastImage/FFFastImageView.m

@@ -70,8 +70,18 @@
 // shownPlaceholder).
 @property(nonatomic, strong) UIImage* hashImage;
 @property(nonatomic, copy) NSString* hashImageKey;
-// Whether the view shows its placeholder (the placeholder prop or the
-// source's), and whether that's the source's (hashImage).
+// placeholderSource's image once it has loaded, or nil: it shows instead of
+// the other placeholders (see shownPlaceholder). Its load, and which it is.
+@property(nonatomic, strong) UIImage* urlPlaceholderImage;
+@property(nonatomic, strong) id<SDWebImageOperation> urlPlaceholderOperation;
+@property(nonatomic, assign) NSUInteger urlPlaceholderLoad;
+// placeholderSource changed: its load starts with the image's, or after the
+// props if the image is still loading (see startUrlPlaceholderLoad).
+@property(nonatomic, assign) BOOL needsUrlPlaceholderLoad;
+// Whether the view shows a placeholder (the placeholder prop, the source's,
+// or placeholderSource's), and whether it stands for the image (the source's
+// or placeholderSource's): drawn as with contain for scale-down and none, as
+// the image's size isn't known yet, scaled smoothly and not blurred.
 @property(nonatomic, assign) BOOL showsPlaceholder;
 @property(nonatomic, assign) BOOL showsHash;
 // dynamicRangeLimit switched between HDR and SDR: the image is decoded again,
@@ -444,7 +454,7 @@ static UIImage* FFFBlurredImage(UIImage* image, CGFloat scale, CGFloat radius, B
 
 - (void) setImage: (UIImage*)image {
     self.imageCount++;
-    self.showsHash = image != nil && image == self.hashImage;
+    self.showsHash = image != nil && (image == self.hashImage || image == self.urlPlaceholderImage);
     self.showsPlaceholder = self.showsHash || (image != nil && image == _placeholder);
     if ([_imageRendering isEqualToString: @"pixelated"]) {
         // A source's placeholder is a blurred preview, scaled up smoothly
@@ -540,7 +550,7 @@ static UIImage* FFFBlurredImage(UIImage* image, CGFloat scale, CGFloat radius, B
 // Whether the image is blurred: a loaded image, not the placeholder prop (as
 // with React Native's Image, and on Android).
 - (BOOL) blurs: (UIImage*)image {
-    return _blurRadius > 0 && image && image != _placeholder && image != self.hashImage;
+    return _blurRadius > 0 && image && image != _placeholder && image != self.hashImage && image != self.urlPlaceholderImage;
 }
 
 // Blurs the image off the main thread, and shows it (tinted as any image) unless
@@ -849,10 +859,124 @@ NSString *FFFErrorMessage(NSError *error)
     [self updateHashImage];
 }
 
-// What shows while the image loads and if it fails: the picked source's
-// placeholder (its ThumbHash or blurDataUri), or the placeholder prop.
+// 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.
 - (UIImage*) shownPlaceholder {
-    return self.hashImage ?: _placeholder;
+    return self.urlPlaceholderImage ?: self.hashImage ?: _placeholder;
+}
+
+// Shows the placeholder that shows now (shownPlaceholder) in place of
+// `previous` if the view showed it, or if it showed nothing (one that arrived
+// while nothing showed): never over a loaded image, or the image kept while
+// a new source loads.
+- (void) showChangedPlaceholder: (UIImage*)previous showing: (BOOL)showing {
+    UIImage* placeholder = [self shownPlaceholder];
+    if (placeholder == previous) {
+        return;
+    }
+    BOOL showsNothing = super.image == nil && !self.showsLoadedImage && !self.blursOverNothing;
+    if (showing || (placeholder && showsNothing)) {
+        [self setImage: placeholder];
+    }
+}
+
+// Images that views showed, by their source's cacheKey or url, while they're
+// still in memory (held by a view or SDWebImage's memory cache), so
+// placeholderSource finds one at once whatever size it was decoded at (the
+// memory cache's key includes the size).
++ (NSMapTable<NSString*, UIImage*>*) shownImages {
+    static NSMapTable* images;
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+        images = [NSMapTable strongToWeakObjectsMapTable];
+    });
+    return images;
+}
+
+// The key a remote image (http or https) is recorded under: its cacheKey or
+// url. nil for others (data uris, files), which aren't recorded.
++ (NSString*) shownImageKey: (FFFastImageSource*)source {
+    NSString* scheme = source.url.scheme.lowercaseString;
+    if (![scheme isEqualToString: @"http"] && ![scheme isEqualToString: @"https"]) {
+        return nil;
+    }
+    return source.cacheKey.length > 0 ? source.cacheKey : source.url.absoluteString;
+}
+
++ (void) rememberShownImage: (UIImage*)image source: (FFFastImageSource*)source {
+    NSString* key = [self shownImageKey: source];
+    if (image && key) {
+        [[self shownImages] setObject: image forKey: key];
+    }
+}
+
+- (void) setPlaceholderSource: (FFFastImageSource*)placeholderSource {
+    _placeholderSource = placeholderSource;
+    [self cancelUrlPlaceholderLoad];
+    [self showUrlPlaceholderImage: nil];
+    self.needsUrlPlaceholderLoad = YES;
+}
+
+- (void) cancelUrlPlaceholderLoad {
+    self.urlPlaceholderLoad++;
+    [self.urlPlaceholderOperation cancel];
+    self.urlPlaceholderOperation = nil;
+}
+
+// Loads placeholderSource's image with the image's load (after layout, so at
+// the view's size, with the props applied), or after the image failed: not
+// if the image shows at once (from the memory cache, or a data uri), or the
+// placeholder is already loaded or loading.
+- (void) startUrlPlaceholderLoad {
+    self.needsUrlPlaceholderLoad = NO;
+    if (!_placeholderSource.url || self.urlPlaceholderImage || self.urlPlaceholderOperation) {
+        return;
+    }
+    if (_source && !self.hasErrored && [self loadsDuringLayout]) {
+        return;
+    }
+    [self loadUrlPlaceholder];
+}
+
+// Loads placeholderSource's image, as a source would load (its cache,
+// headers and cacheKey), at a high priority, as it only helps if it comes
+// before the image. One a view still shows (or that's still in memory) shows
+// at once. A failure shows nothing more.
+- (void) loadUrlPlaceholder {
+    [self cancelUrlPlaceholderLoad];
+    NSUInteger load = self.urlPlaceholderLoad;
+    FFFastImageSource* source = _placeholderSource;
+    NSString* key = [FFFastImageView shownImageKey: source];
+    UIImage* shown = key ? [[FFFastImageView shownImages] objectForKey: key] : nil;
+    if (shown) {
+        [self showUrlPlaceholderImage: shown];
+        return;
+    }
+    SDWebImageOptions options = [source cacheOptions] | SDWebImageHighPriority | SDWebImageRetryFailed | SDWebImageHandleCookies;
+    SDWebImageContext* context = [self contextForSource: source box: [self decodeBox] cover: NO];
+    __weak typeof(self) weakSelf = self;
+    self.urlPlaceholderOperation = [[SDWebImageManager sharedManager] loadImageWithURL: source.url options: options context: context progress: nil completed: ^(UIImage* _Nullable image, NSData* _Nullable data, NSError* _Nullable error, SDImageCacheType cacheType, BOOL finished, NSURL* _Nullable imageURL) {
+        if (!finished || weakSelf.urlPlaceholderLoad != load) {
+            return;
+        }
+        weakSelf.urlPlaceholderOperation = nil;
+        if (!image) {
+            return;
+        }
+        [FFFastImageView rememberShownImage: image source: source];
+        [weakSelf showUrlPlaceholderImage: image];
+    }];
+}
+
+- (void) showUrlPlaceholderImage: (UIImage*)image {
+    if (self.urlPlaceholderImage == image) {
+        return;
+    }
+    UIImage* previous = [self shownPlaceholder];
+    BOOL showing = self.showsPlaceholder;
+    self.urlPlaceholderImage = image;
+    [self showChangedPlaceholder: previous showing: showing];
 }
 
 // The picked source's ThumbHash or blurDataUri, or nil.
@@ -876,10 +1000,7 @@ NSString *FFFErrorMessage(NSError *error)
     BOOL showing = self.showsPlaceholder;
     self.hashImageKey = hash;
     self.hashImage = [FFFThumbHash imageForPlaceholder: hash];
-    UIImage* placeholder = [self shownPlaceholder];
-    if (showing && placeholder != previous) {
-        [self setImage: placeholder];
-    }
+    [self showChangedPlaceholder: previous showing: showing];
 }
 
 - (void) didSetProps {
@@ -909,6 +1030,14 @@ NSString *FFFErrorMessage(NSError *error)
     } else {
         [self reloadIfResized];
     }
+    // A new placeholderSource while the image loads, or after it failed (a
+    // load waiting for the view's size starts it with the image's).
+    if (self.needsUrlPlaceholderLoad && !_needsReload && !self.waitsForSize) {
+        if (!self.hasCompleted || self.hasErrored) {
+            [self startUrlPlaceholderLoad];
+        }
+        self.needsUrlPlaceholderLoad = NO;
+    }
 }
 
 // The same image decoded again for a dynamicRangeLimit between HDR and SDR,
@@ -1003,6 +1132,7 @@ NSString *FFFErrorMessage(NSError *error)
 - (void) reloadImage {
     _needsReload = NO;
     self.needsDynamicRangeReload = NO;
+    self.needsUrlPlaceholderLoad = NO;
     self.waitsForSize = NO;
     self.loadsSwitchedSource = self.switchesSource;
     self.switchesSource = NO;
@@ -1038,6 +1168,7 @@ NSString *FFFErrorMessage(NSError *error)
                 [self setImage: [self shownPlaceholder]];
                 self.showsLoadedImage = NO;
                 [self sendOnError: @"Failed to decode the image"];
+                [self startUrlPlaceholderLoad];
                 if (self.onFastImageLoadEnd) {
                     self.onFastImageLoadEnd([self loadEndEvent: NO]);
                 }
@@ -1080,10 +1211,15 @@ NSString *FFFErrorMessage(NSError *error)
         self.retriedAfterBackground = NO;
         [self stopWaitingForActive];
 
+        [self startUrlPlaceholderLoad];
         [self downloadImage: _source options: options context: [self loadContext] events: YES];
-    } else if ([self shownPlaceholder]) {
-        [self setImage: [self shownPlaceholder]];
-        self.showsLoadedImage = NO;
+    } else {
+        if ([self shownPlaceholder]) {
+            [self setImage: [self shownPlaceholder]];
+            self.showsLoadedImage = NO;
+        }
+        // No image: only placeholders show.
+        [self startUrlPlaceholderLoad];
     }
 }
 
@@ -1319,6 +1455,8 @@ NSString *FFFErrorMessage(NSError *error)
                         [weakSelf setImage: current];
                     }
                     weakSelf.showsLoadedImage = NO;
+                    // Shows instead of the other placeholders once it loads.
+                    [weakSelf startUrlPlaceholderLoad];
                     [weakSelf sendOnError: [source errorMessage: error]];
                     if (weakSelf.onFastImageLoadEnd) {
                         weakSelf.onFastImageLoadEnd([weakSelf loadEndEvent: NO]);
@@ -1326,6 +1464,12 @@ NSString *FFFErrorMessage(NSError *error)
                 } else {
                     weakSelf.hasCompleted = YES;
                     weakSelf.showsLoadedImage = YES;
+                    // For other views' placeholderSource.
+                    [FFFastImageView rememberShownImage: image source: source];
+                    // The image came first: its placeholder isn't needed.
+                    if (!weakSelf.urlPlaceholderImage) {
+                        [weakSelf cancelUrlPlaceholderLoad];
+                    }
                     [weakSelf sendOnLoad: image];
                     if (weakSelf.onFastImageLoadEnd) {
                         weakSelf.onFastImageLoadEnd([weakSelf loadEndEvent: YES]);
@@ -1375,11 +1519,14 @@ NSString *FFFErrorMessage(NSError *error)
     self.waitsForSize = NO;
     [self stopWaitingForActive];
     [self sd_cancelLatestImageLoad];
+    [self cancelUrlPlaceholderLoad];
 }
 
 - (void) dealloc {
     [self stopWaitingForActive];
     [self sd_cancelLatestImageLoad];
+    // Fabric frees views it doesn't recycle without stop.
+    [_urlPlaceholderOperation cancel];
 }
 
 @end

package/ios/FastImage/FFFastImageViewComponentView.mm

@@ -102,6 +102,22 @@ static id _Nullable FFFJSON(const folly::dynamic &value)
     return value.isNull() ? nil : FFFObjectFromDynamic(value);
 }
 
+// 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.
+static BOOL FFFIsUrlPlaceholder(id _Nullable placeholder)
+{
+    if (![placeholder isKindOfClass:[NSDictionary class]] || placeholder[@"__packager_asset"]) {
+        return NO;
+    }
+    id uri = placeholder[@"uri"];
+    if (![uri isKindOfClass:[NSString class]]) {
+        return NO;
+    }
+    NSString *scheme = [NSURL URLWithString:uri].scheme.lowercaseString;
+    return [scheme isEqualToString:@"http"] || [scheme isEqualToString:@"https"];
+}
+
 // The events JS has a handler for: the handledEvents prop's bits (see
 // src/specs/FastImageViewNativeComponent.ts).
 typedef NS_OPTIONS(int32_t, FFFEvent) {
@@ -234,7 +250,9 @@ typedef NS_OPTIONS(int32_t, FFFEvent) {
     }
     if (all || oldViewProps.placeholder != newViewProps.placeholder) {
         id placeholder = FFFJSON(newViewProps.placeholder);
-        view.placeholder = placeholder ? [RCTConvert UIImage:placeholder] : nil;
+        BOOL loads = FFFIsUrlPlaceholder(placeholder);
+        view.placeholder = placeholder && !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()];

package/package.json

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

package/src/index.js.flow

@@ -110,6 +110,13 @@ export type PreloadResult = PreloadSuccess | PreloadFailure
 export type PreloadFn = (
     sources: Array<FastImageSource>,
 ) => Promise<Array<PreloadResult>>
+export type PlaceholderSource = {
+    uri?: string,
+    headers?: Object,
+    cacheKey?: string,
+    cache?: CacheControls,
+}
+
 export type SourcePlaceholder = {
     thumbhash?: string,
     blurDataUri?: string,
@@ -139,7 +146,7 @@ export type FastImageProps = $ReadOnly<{|
     onProgress?: ?(event: OnProgressEvent) => void,
 
     source?: ?(FastImageSource | Array<FastImageSource> | number),
-    placeholder?: ?(number | string | SourcePlaceholder),
+    placeholder?: ?(number | string | SourcePlaceholder | PlaceholderSource),
     // Deprecated: use placeholder, which is the same.
     defaultSource?: ?number,
 

package/src/index.tsx

@@ -16,7 +16,12 @@ import { fromStyle, resolveObjectFit } from './objectFit'
 import { objectPositionOrCentered, type ObjectPosition } from './objectPosition'
 import FastImageView from './specs/FastImageViewNativeComponent'
 import NativeFastImageModule from './specs/NativeFastImageModule'
-import { dataUri, hasSourcePlaceholder, isImageName } from './placeholders'
+import {
+    dataUri,
+    hasSourcePlaceholder,
+    isImageName,
+    placeholderSource,
+} from './placeholders'
 import { warnIfChildren, warnOnce } from './warnings'
 
 /** How the image fits the view: see [`objectFit`](#objectfit). */
@@ -175,6 +180,12 @@ export type Source = {
 /** A `thumbhash` or `blurDataUri` as `placeholder`. */
 export type SourcePlaceholder = Pick<Source, 'thumbhash' | 'blurDataUri'>
 
+/** A url as `placeholder`, loaded like a source (see `placeholder`). */
+export type PlaceholderSource = Pick<
+    Source,
+    'uri' | 'headers' | 'cacheKey' | 'cache'
+>
+
 /** How the image fades in: see [`transition`](#transition). */
 export type Transition = {
     /**
@@ -365,17 +376,27 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
      *   `placeholder={{ thumbhash }}`.
      * - A tiny image as a data uri, shown blurred:
      *   `placeholder={{ blurDataUri }}`.
+     * - A url, loaded and cached like a source:
+     *   `placeholder="https://example.com/placeholder.png"`, or a source with
+     *   `headers` or a `cacheKey`: `placeholder={{ uri, headers }}`.
+     * - A url only shown if it's already cached, e.g. a list's thumbnail while
+     *   the full-size image loads: `placeholder={{ uri, cache: 'cacheOnly' }}`.
      *
      * A source's own `thumbhash` or `blurDataUri` is shown instead, if it has
-     * one.
+     * one; a url placeholder shows over it once it has loaded.
      *
      * Notes:
      *
-     * - A url isn't loaded: it's ignored, with a warning in development.
      * - On Android, a `require()`d image doesn't show in debug builds, where
      *   the dev server serves it. Release builds show it.
+     * - On the web, a url loads like any image, also with `'cacheOnly'`: a
+     *   browser can't look only in its cache.
      */
-    placeholder?: ImageRequireSource | string | SourcePlaceholder
+    placeholder?:
+        | ImageRequireSource
+        | string
+        | SourcePlaceholder
+        | PlaceholderSource
     /**
      * @deprecated Use `placeholder`, which does the same.
      */
@@ -706,7 +727,8 @@ function sourcePlaceholder(source: unknown): string {
 }
 
 const resolvePlaceholder = (
-    placeholder?: ImageRequireSource | string,
+    // A source object here has no url (e.g. { uri: name }, a bundled image).
+    placeholder?: ImageRequireSource | string | PlaceholderSource,
 ): string | object | null => {
     if (typeof placeholder === 'string') {
         // An image bundled with the app, by name, as React Native's Image
@@ -725,7 +747,9 @@ const resolvePlaceholder = (
     if (!placeholder) {
         return null
     }
-    const resolved = Image.resolveAssetSource(placeholder)
+    const resolved = Image.resolveAssetSource(
+        placeholder as ImageRequireSource | { uri: string },
+    )
     if (!resolved) {
         return null
     }
@@ -923,13 +947,17 @@ function FastImageBase({
                 : undefined,
         }
     }, [source, shared])
-    // A thumbhash or blurDataUri in `placeholder` goes in sourcePlaceholders
-    // instead: it isn't an image to show as it is, but defaultSource still is.
-    const resolvedPlaceholder = resolvePlaceholder(
-        hasSourcePlaceholder(placeholder)
-            ? defaultSource
-            : (placeholder ?? defaultSource),
-    )
+    // A url in `placeholder` goes to the native view as a source, loaded
+    // apart from the image, in place of defaultSource. A thumbhash or
+    // blurDataUri goes in sourcePlaceholders instead: it isn't an image to
+    // show as it is, but defaultSource still is.
+    const resolvedPlaceholder =
+        placeholderSource(placeholder) ??
+        resolvePlaceholder(
+            hasSourcePlaceholder(placeholder)
+                ? defaultSource
+                : (placeholder ?? defaultSource),
+        )
 
     return (
         <FastImageView

package/src/index.web.tsx

@@ -32,7 +32,11 @@ import { getAssetByID } from 'react-native-web/dist/modules/AssetRegistry'
 import { cacheControl, priority, resizeMode } from './constants'
 import { resolveObjectFit } from './objectFit'
 import { cssPosition, objectPositionOrCentered } from './objectPosition'
-import { dataUri, hasSourcePlaceholder } from './placeholders'
+import {
+    dataUri,
+    hasSourcePlaceholder,
+    placeholderSource,
+} from './placeholders'
 import { warnIfChildren, warnOnce } from './warnings'
 import type {
     CachePathResult,
@@ -132,11 +136,20 @@ function FastImageBase({
     const blurUri =
         resolveUri(dataUri(shared(source, 'blurDataUri', preview))) ??
         thumbhashUri(shared(source, 'thumbhash', preview))
+    // `placeholder` as a url (or a source with one) shows over the other
+    // 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
+    const [failedPlaceholder, setFailedPlaceholder] = useState<string>()
     // A thumbhash or blurDataUri in `placeholder` isn't an image to show as it
-    // is: defaultSource still is.
+    // is, nor is a url (above): defaultSource still is.
     const defaultUri =
         blurUri ??
-        resolveUri(preview ? defaultSource : (placeholder ?? defaultSource))
+        resolveUri(
+            preview || urlPlaceholder
+                ? defaultSource
+                : (placeholder ?? defaultSource),
+        )
     // Whether the image for `key` loaded, or failed.
     const [result, setResult] = useState<{ key: string; ok: boolean }>()
     const ok = result && result.key === key ? result.ok : undefined
@@ -156,7 +169,7 @@ function FastImageBase({
             .filter(Boolean)
             .join(' ') || undefined
     // The placeholder shows until the image has loaded, and if it fails.
-    const showDefault = !!defaultUri && ok !== true
+    const showDefault = ok !== true
 
     useClientLayoutEffect(() => {
         if (key) onLoadStart?.()
@@ -207,6 +220,28 @@ function FastImageBase({
                     alt={key ? '' : (label ?? '')}
                 />
             ) : null}
+            {urlPlaceholder && showDefault ? (
+                <Picture
+                    key={`placeholder ${urlPlaceholder}`}
+                    src={urlPlaceholder}
+                    loading={loading}
+                    // It only helps if it comes before the image, as on iOS
+                    // and Android.
+                    priority="high"
+                    dynamicRangeLimit={dynamicRangeLimit}
+                    // It stands for the image, as a source's preview does.
+                    fit={
+                        fit === 'scale-down' || fit === 'none' ? 'contain' : fit
+                    }
+                    position={position}
+                    // 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)}
+                    alt=""
+                />
+            ) : null}
             {key && src ? (
                 <Picture
                     key={several ? 'sizes' : key}

package/src/placeholders.ts

@@ -1,20 +1,37 @@
-// Placeholders given as strings (`placeholder`, and a source's `blurDataUri`)
-// are data uris, shared by the native (index.tsx) and web (index.web.tsx)
-// versions, or for `placeholder`, the name of an image bundled with the app.
-// They're decoded at once, so they show in the view's first frame; a url
-// would load like an image (and on iOS and Android, not at all), so it's
-// ignored, with a warning in development.
-import type { SourcePlaceholder } from './index'
+// Placeholders given as strings, shared by the native (index.tsx) and web
+// (index.web.tsx) versions: a source's `blurDataUri` is a data uri, decoded at
+// once, so it shows in the view's first frame (a url there is ignored, with a
+// warning in development). `placeholder` can also be the name of an image
+// bundled with the app, or a url, loaded as a source (placeholderSource).
+import type { PlaceholderSource, SourcePlaceholder } from './index'
 import { warnOnce } from './warnings'
 
 // Metro's (and React Native's Jest preset's) development flag; other web
 // bundlers may not define it.
 declare const __DEV__: boolean | undefined
 
+const SCHEME = /^[a-z][a-z\d+.-]*:/i
+
 // Whether `placeholder` is the name of an image bundled with the app (an iOS
 // asset catalog image, an Android drawable): no scheme, not a path.
 export function isImageName(value: string): boolean {
-    return !/^[a-z][a-z\d+.-]*:/i.test(value) && !value.startsWith('/')
+    return !SCHEME.test(value) && !value.startsWith('/')
+}
+
+// `placeholder` as a source to load: an http or https url, as a string or a
+// source object's uri. Undefined for anything else (a local file or a data uri
+// is decoded at once, as the native placeholder prop).
+export function placeholderSource(
+    value: unknown,
+): PlaceholderSource | undefined {
+    const uri =
+        typeof value === 'string'
+            ? value
+            : value && typeof value === 'object'
+              ? (value as PlaceholderSource).uri
+              : undefined
+    if (typeof uri !== 'string' || !/^https?:/i.test(uri)) return undefined
+    return typeof value === 'string' ? { uri } : (value as PlaceholderSource)
 }
 
 // Whether a source has a thumbhash or blurDataUri, or `placeholder` is one
@@ -37,7 +54,7 @@ export function dataUri(value: unknown): string | undefined {
     if (typeof __DEV__ !== 'undefined' && __DEV__) {
         warnOnce(
             'placeholder-url',
-            `react-native-fast-image: \`placeholder\` and \`blurDataUri\` don't load urls: "${value.slice(0, 60)}" is ignored. Use a data uri (data:image/…), or for \`placeholder\`, a require()d image or the name of an image bundled with the app.`,
+            `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',
         )
     }

package/src/specs/FastImageViewNativeComponent.ts

@@ -45,8 +45,10 @@ export interface NativeProps extends ViewProps {
     source?: CodegenTypes.UnsafeMixed
     // Several sources (sizes of one image), picked from for the view's size.
     sources?: CodegenTypes.UnsafeMixed
-    // The `placeholder` prop: a resolved asset source ({ uri, width, height,
-    // scale }) or a data uri ({ uri } on iOS; the uri on Android).
+    // The `placeholder` prop: a url to load apart from the image, as a source
+    // ({ uri, headers, cacheKey, cache }), or an image shown at once: a
+    // resolved asset source ({ uri, width, height, scale }) or a data uri
+    // ({ uri } on iOS; the uri on Android, as a string).
     placeholder?: CodegenTypes.UnsafeMixed
     // What shows in place of placeholder while a source loads: its ThumbHash,
     // or its blurDataUri (blurred natively), by the source's index ('' for