react-native-fast-image 10.3.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.
 
 ---
 
@@ -424,6 +426,20 @@ If you control the images, serve them at the size they're shown (resized on your
 
 ---
 
+#### `dynamicRangeLimit`
+
+**Type:** `'standard' | 'constrained' | 'no-limit'` · iOS, Web only
+
+How bright HDR photos (e.g. photos taken on an iPhone) can be, on displays that support it:
+
+- `'standard'`: in standard range, like the rest of the screen.
+- `'constrained'`: in HDR, their highlights brighter than the rest of the screen but held below the display's peak, e.g. for images among other content (a feed).
+- `'no-limit'`: in full HDR, e.g. for a full-screen photo viewer.
+
+Not set, iOS shows them in standard range, and the web as the browser does by default (usually HDR). On iOS and tvOS 17 and later; Android shows them in standard range. On the web it's CSS's `dynamic-range-limit`.
+
+---
+
 #### `blurRadius`
 
 **Type:** `number` · **Default:** `0`
@@ -830,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);
@@ -389,6 +396,12 @@ class FastImageViewManager extends SimpleViewManager<FastImageViewWithUrl>
         view.setDownsample(downsample);
     }
 
+    // iOS only: Android shows an HDR photo (a gain map) in HDR only when its
+    // whole window is in HDR color mode.
+    @Override
+    public void setDynamicRangeLimit(FastImageViewWithUrl view, @Nullable String dynamicRangeLimit) {
+    }
+
     // Which events JS has a handler for (FastImageEvents); with onProgress,
     // the view gets its download's progress (see onDownloadProgress).
     @Override

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,
 
@@ -151,6 +158,7 @@ export type FastImageProps = $ReadOnly<{|
     imageRendering?: ?('auto' | 'smooth' | 'pixelated'),
     loading?: ?('lazy' | 'eager'),
     sizes?: ?string,
+    dynamicRangeLimit?: ?('standard' | 'constrained' | 'no-limit'),
     paused?: ?boolean,
     transition?: ?(boolean | number | Transition),
     downsample?: ?boolean,

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
@@ -283,8 +288,8 @@ const notSupported = {
 	error: "Not supported on the web"
 };
 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, forwardedRef, onLayout, pointerEvents, recyclingKey: _recyclingKey, loop: _loop, imageRendering: _imageRendering, paused: _paused, transition: _transition, downsample: _downsample, onProgress: _onProgress, ...props }) {
-	var _resolveUri;
+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, _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]);
@@ -321,10 +328,23 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadi
 		src: defaultUri,
 		loading,
 		priority,
+		dynamicRangeLimit,
 		fit: blurUri && (fit === "scale-down" || fit === "none") ? "contain" : fit,
 		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,
@@ -332,6 +352,7 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadi
 		sizes,
 		loading,
 		priority,
+		dynamicRangeLimit,
 		fit,
 		position,
 		filter,
@@ -438,7 +459,7 @@ const fill = {
 	width: "100%",
 	height: "100%"
 };
-function Picture({ src, srcSet, sizes, loading, priority, fit, position, filter, hidden, alt, onLoad, onError }) {
+function Picture({ src, srcSet, sizes, loading, priority, dynamicRangeLimit, fit, position, filter, hidden, alt, onLoad, onError }) {
 	const image = (0, react.useRef)(null);
 	const mounted = (0, react.useRef)(true);
 	const handled = (0, react.useRef)(void 0);
@@ -485,7 +506,8 @@ function Picture({ src, srcSet, sizes, loading, priority, fit, position, filter,
 			objectFit: fit,
 			objectPosition: position,
 			filter,
-			opacity: hidden ? 0 : void 0
+			opacity: hidden ? 0 : void 0,
+			dynamicRangeLimit
 		},
 		onLoad: (event) => loaded(event.currentTarget),
 		onError: (event) => {

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,
 
@@ -151,6 +158,7 @@ export type FastImageProps = $ReadOnly<{|
     imageRendering?: ?('auto' | 'smooth' | 'pixelated'),
     loading?: ?('lazy' | 'eager'),
     sizes?: ?string,
+    dynamicRangeLimit?: ?('standard' | 'constrained' | 'no-limit'),
     paused?: ?boolean,
     transition?: ?(boolean | number | Transition),
     downsample?: ?boolean,

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.
      */
@@ -533,6 +541,25 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
      * @default true
      */
     downsample?: boolean;
+    /**
+     * How bright HDR photos (e.g. photos taken on an iPhone) can be, on
+     * displays that support it:
+     *
+     * - `'standard'`: in standard range, like the rest of the screen.
+     * - `'constrained'`: in HDR, their highlights brighter than the rest of
+     *   the screen but held below the display's peak, e.g. for images among
+     *   other content (a feed).
+     * - `'no-limit'`: in full HDR, e.g. for a full-screen photo viewer.
+     *
+     * Not set, iOS shows them in standard range, and the web as the browser
+     * does by default (usually HDR). On iOS and tvOS 17 and later; Android
+     * shows them in standard range. On the web it's CSS's
+     * `dynamic-range-limit`.
+     *
+     * @platform ios
+     * @platform web
+     */
+    dynamicRangeLimit?: 'standard' | 'constrained' | 'no-limit';
     /**
      * Blurs the image by this radius, in points (the same radius looks about
      * the same on iOS and Android). `0` is no blur.