react-native-fast-image 10.2.0 → 10.3.0

package/README.md

@@ -71,7 +71,7 @@ npx expo install react-native-fast-image
 
 It has native code, so it needs a [development build](https://docs.expo.dev/develop/development-builds/introduction/) (e.g. `npx expo run:ios`), not Expo Go.
 
-Needs React Native 0.83 or later with the New Architecture (Expo SDK 55 or later), iOS/tvOS 15.1 or later, and Android 7.0 (API 24) or later; on tvOS, it works with [React Native tvOS](https://github.com/react-native-tvos/react-native-tvos). Apps on the legacy architecture or older React Native can use FastImage 9 (`npm install react-native-fast-image@9`). Upgrading from FastImage 9: see [Upgrading from 9.x](docs/upgrading.md).
+Needs React Native 0.83 or later with the New Architecture (Expo SDK 55 or later) and React 19, iOS/tvOS 15.1 or later, and Android 7.0 (API 24) or later; on tvOS, it works with [React Native tvOS](https://github.com/react-native-tvos/react-native-tvos). Apps on the legacy architecture or older React Native can use FastImage 9 (`npm install react-native-fast-image@9`). Upgrading from FastImage 9: see [Upgrading from 9.x](docs/upgrading.md).
 
 To set the cache's size when the app starts, see [Native config](#native-config).
 
@@ -161,6 +161,8 @@ A hint for which images to start loading first when several are waiting: `'high'
 - `'normal'`: the default.
 - `'high'`: e.g. the image the screen is about.
 
+On the web, it's the image's `fetchpriority`.
+
 ---
 
 ##### `source.cache`
@@ -365,6 +367,22 @@ How the image is filtered when it's drawn smaller or larger than its size (like
 
 ---
 
+#### `loading`
+
+**Type:** `'lazy' | 'eager'` · **Default:** `'lazy'` · Web only
+
+Whether the image loads as it nears the screen (`'lazy'`) or at once (`'eager'`).
+
+---
+
+#### `sizes`
+
+**Type:** `string` · **Default:** `'auto, 100vw'` · Web only
+
+With several sources, the width the image is shown at, as the image's [`sizes`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img#sizes), so the browser loads the size that fits. The default is the width the image is laid out at, which needs `loading="lazy"` (otherwise, or in browsers without it, the window's width).
+
+---
+
 #### `paused`
 
 **Type:** `boolean`
@@ -932,14 +950,15 @@ The app needs access to the photo library, which it has if it got the url from t
 
 ## Web
 
-FastImage works on the web with [react-native-web](https://necolas.github.io/react-native-web/). Bundlers pick the web version through the package's `browser` field, or the `.web.js` files next to the native ones.
+FastImage works on the web with [react-native-web](https://necolas.github.io/react-native-web/) and React 19 or later. Bundlers pick the web version through the package's `browser` field, or the `.web.js` files next to the native ones.
 
 Support is minimal:
 
-- Props that work: `source` (a `uri`, a `require()`d image, or several sizes, with `thumbhash` and `blurDataUri`), `placeholder` (and `defaultSource`), `objectFit`, `objectPosition`, `tintColor`, `blurRadius`, `style`, `onLoadStart`, `onLoad`, `onError`, `onLoadEnd`, and View props such as `testID`, accessibility props, `onLayout` and `pointerEvents`.
-- Ignored: `source.headers` (a browser can't send them for an image), `source.priority`, `source.cache`, `source.cacheKey`, `source.memoryCache`, `source.diskCache`, `recyclingKey`, `loop`, `imageRendering`, `paused`, `transition`, `downsample` and `onProgress`.
+- Props that work: `source` (a `uri`, a `require()`d image, or several sizes, with `thumbhash` and `blurDataUri`), `placeholder` (and `defaultSource`), `objectFit`, `objectPosition`, `tintColor`, `blurRadius`, `style`, `source.priority`, the web-only `loading` and `sizes`, `onLoadStart`, `onLoad`, `onError`, `onLoadEnd`, and View props such as `testID`, accessibility props, `onLayout` and `pointerEvents`.
+- Ignored: `source.headers` (a browser can't send them for an image), `source.cache`, `source.cacheKey`, `source.memoryCache`, `source.diskCache`, `recyclingKey`, `loop`, `imageRendering`, `paused`, `transition`, `downsample` and `onProgress`.
 - The image is an `<img>` element that fills the view inside its borders, with `objectFit` and `objectPosition` as its CSS `object-fit` and `object-position`. `tintColor` is an SVG filter and `blurRadius` a CSS `blur()`, and the placeholder is another `<img>`, under the image until it has loaded. A new `source` gets a new `<img>`, so the previous image doesn't stay while it loads (with several sizes, the browser shows it until the new one has loaded).
-- Several sizes are shown with a lazily loaded `<img>` whose `srcset` lists them, with `sizes="auto, 100vw"`: the browser loads the one for the width the image is shown at, in device pixels (usually the smallest that's at least as wide). Browsers that don't support `sizes="auto"` use the viewport's width.
+- Images load lazily unless [`loading`](#loading) is `'eager'`, and `source.priority` `'high'` and `'low'` are the `<img>`'s `fetchpriority`.
+- Several sizes are shown with an `<img>` whose `srcset` lists them, with `sizes="auto, 100vw"` (or [`sizes`](#sizes)): the browser loads the one for the width the image is shown at, in device pixels (usually the smallest that's at least as wide). Browsers that don't support `sizes="auto"`, or an image with `loading="eager"`, use the viewport's width.
 - `FastImage.preload` loads the images into the browser's cache and resolves with a result per source. `clearMemoryCache`, `clearDiskCache` and `configureCache` resolve without doing anything (the browser manages its cache), and `getCachePath` and `writeToCache` resolve with `{ ok: false, error: 'Not supported on the web' }`.
 
 ### ThumbHashes on the web

package/dist/index.cjs.js

@@ -347,7 +347,7 @@ function builtInTransition() {
 	return resolveTransition(react_native.Platform.OS === "android", NO_TRANSITION);
 }
 let defaultTransition;
-function FastImageBase({ source, placeholder, defaultSource, tintColor, onLoadStart, onProgress, onLoad, onError, onLoadEnd, style, children, objectFit, objectPosition, loop, transition, forwardedRef, ...viewProps }) {
+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;
 	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");

package/dist/index.cjs.js.flow

@@ -149,6 +149,8 @@ export type FastImageProps = $ReadOnly<{|
     recyclingKey?: ?string,
     loop?: ?(boolean | number),
     imageRendering?: ?('auto' | 'smooth' | 'pixelated'),
+    loading?: ?('lazy' | 'eager'),
+    sizes?: ?string,
     paused?: ?boolean,
     transition?: ?(boolean | number | Transition),
     downsample?: ?boolean,

package/dist/index.cjs.web.js

@@ -278,16 +278,12 @@ function dataUri(value) {
 }
 //#endregion
 //#region src/index.web.tsx
-var _useId;
 const notSupported = {
 	ok: false,
 	error: "Not supported on the web"
 };
-let ids = 0;
-const useCounterId = () => (0, react.useState)(() => `${++ids}`)[0];
-const useSvgId = (_useId = react.default.useId) !== null && _useId !== void 0 ? _useId : useCounterId;
 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, forwardedRef, onLayout, pointerEvents, recyclingKey: _recyclingKey, loop: _loop, imageRendering: _imageRendering, paused: _paused, transition: _transition, downsample: _downsample, onProgress: _onProgress, ...props }) {
+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;
 	if (typeof __DEV__ !== "undefined" && __DEV__) warnIfChildren(children);
 	const { accessibilityLabel, "aria-label": ariaLabel, resizeMode: _resizeMode, ...viewProps } = props;
@@ -297,12 +293,13 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadi
 	const src = sized ? sized.src : resolveUri(source);
 	const srcSet = sized === null || sized === void 0 ? void 0 : sized.srcSet;
 	const key = srcSet !== null && srcSet !== void 0 ? srcSet : src;
+	const 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 [result, setResult] = (0, react.useState)();
 	const ok = result && result.key === key ? result.ok : void 0;
-	const svgId = useSvgId().replace(/[^\w-]/g, "");
+	const svgId = (0, react.useId)().replace(/[^\w-]/g, "");
 	const tintId = `fast-image-tint-${svgId}`;
 	const blurId = `fast-image-blur-${svgId}`;
 	const fit = resolveObjectFit(objectFit, style);
@@ -322,6 +319,8 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadi
 	}, defaultUri && showDefault ? /* @__PURE__ */ react.default.createElement(Picture, {
 		key: `default ${defaultUri}`,
 		src: defaultUri,
+		loading,
+		priority,
 		fit: blurUri && (fit === "scale-down" || fit === "none") ? "contain" : fit,
 		position,
 		filter: blurUri ? [`url(#${blurId})`, tintColor ? `url(#${tintId})` : ""].filter(Boolean).join(" ") : filter,
@@ -330,7 +329,9 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadi
 		key: several ? "sizes" : key,
 		src,
 		srcSet,
-		lazy: !!several,
+		sizes,
+		loading,
+		priority,
 		fit,
 		position,
 		filter,
@@ -375,6 +376,14 @@ function thumbhashUri(hash) {
 	if (decode) return decode(hash);
 	if (typeof __DEV__ !== "undefined" && __DEV__) warnOnce("thumbhash-web", "react-native-fast-image: on the web, a `thumbhash` shows only with `import 'react-native-fast-image/thumbhash'` (it decodes them). Or make it a `blurDataUri` before it reaches the browser (e.g. on your server) with that module's thumbHashToBlurDataUri, which needs no JavaScript in the browser.", "warn");
 }
+function sourcePriority(source) {
+	const values = (Array.isArray(source) ? source : [source]).map((entry) => entry && typeof entry === "object" ? entry.priority : void 0);
+	return [
+		"high",
+		"normal",
+		"low"
+	].find((priority) => values.includes(priority));
+}
 function shared(source, key, preview) {
 	const values = (Array.isArray(source) ? source : [source]).map((entry) => {
 		var _ref;
@@ -429,7 +438,7 @@ const fill = {
 	width: "100%",
 	height: "100%"
 };
-function Picture({ src, srcSet, lazy, fit, position, filter, hidden, alt, onLoad, onError }) {
+function Picture({ src, srcSet, sizes, loading, priority, 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);
@@ -466,8 +475,9 @@ function Picture({ src, srcSet, lazy, fit, position, filter, hidden, alt, onLoad
 		ref: image,
 		src,
 		srcSet,
-		sizes: srcSet ? "auto, 100vw" : void 0,
-		loading: lazy ? "lazy" : void 0,
+		sizes: srcSet ? sizes !== null && sizes !== void 0 ? sizes : "auto, 100vw" : void 0,
+		loading: loading === "eager" ? void 0 : "lazy",
+		fetchPriority: priority === "high" || priority === "low" ? priority : void 0,
 		alt,
 		draggable: false,
 		style: {

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

@@ -149,6 +149,8 @@ export type FastImageProps = $ReadOnly<{|
     recyclingKey?: ?string,
     loop?: ?(boolean | number),
     imageRendering?: ?('auto' | 'smooth' | 'pixelated'),
+    loading?: ?('lazy' | 'eager'),
+    sizes?: ?string,
     paused?: ?boolean,
     transition?: ?(boolean | number | Transition),
     downsample?: ?boolean,

package/dist/index.d.ts

@@ -35,6 +35,8 @@ export type Source = {
      * - `'normal'`: the default.
      * - `'high'`: e.g. the image the screen is about.
      *
+     * On the web, it's the image's `fetchpriority`.
+     *
      * @default 'normal'
      */
     priority?: Priority;
@@ -452,6 +454,25 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
      * @default 'auto'
      */
     imageRendering?: 'auto' | 'smooth' | 'pixelated';
+    /**
+     * Whether the image loads as it nears the screen (`'lazy'`) or at once
+     * (`'eager'`).
+     *
+     * @default 'lazy'
+     * @platform web
+     */
+    loading?: 'lazy' | 'eager';
+    /**
+     * With several sources, the width the image is shown at, as the image's
+     * [`sizes`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img#sizes),
+     * so the browser loads the size that fits. The default is the width the
+     * image is laid out at, which needs `loading="lazy"` (otherwise, or in
+     * browsers without it, the window's width).
+     *
+     * @default 'auto, 100vw'
+     * @platform web
+     */
+    sizes?: string;
     /**
      * Pauses an animated image (GIF, animated WebP, APNG, or animated AVIF) on
      * the frame it's showing; `false` plays it again from there

package/dist/index.js

@@ -320,7 +320,7 @@ function builtInTransition() {
 	return resolveTransition(Platform.OS === "android", NO_TRANSITION);
 }
 let defaultTransition;
-function FastImageBase({ source, placeholder, defaultSource, tintColor, onLoadStart, onProgress, onLoad, onError, onLoadEnd, style, children, objectFit, objectPosition, loop, transition, forwardedRef, ...viewProps }) {
+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;
 	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");

package/dist/index.js.flow

@@ -149,6 +149,8 @@ export type FastImageProps = $ReadOnly<{|
     recyclingKey?: ?string,
     loop?: ?(boolean | number),
     imageRendering?: ?('auto' | 'smooth' | 'pixelated'),
+    loading?: ?('lazy' | 'eager'),
+    sizes?: ?string,
     paused?: ?boolean,
     transition?: ?(boolean | number | Transition),
     downsample?: ?boolean,

package/dist/index.web.js

@@ -1,4 +1,4 @@
-import React, { Children, forwardRef, memo, useEffect, useLayoutEffect, useRef, useState } from "react";
+import React, { Children, forwardRef, memo, useEffect, useId, useLayoutEffect, useRef, useState } from "react";
 import { Image, PixelRatio, StyleSheet, View } from "react-native";
 import { getAssetByID } from "react-native-web/dist/modules/AssetRegistry";
 //#region src/constants.ts
@@ -251,16 +251,12 @@ function dataUri(value) {
 }
 //#endregion
 //#region src/index.web.tsx
-var _useId;
 const notSupported = {
 	ok: false,
 	error: "Not supported on the web"
 };
-let ids = 0;
-const useCounterId = () => useState(() => `${++ids}`)[0];
-const useSvgId = (_useId = React.useId) !== null && _useId !== void 0 ? _useId : useCounterId;
 const useClientLayoutEffect = globalThis.document === void 0 ? useEffect : useLayoutEffect;
-function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadius, onLoadStart, onLoad, onError, onLoadEnd, style, children, objectFit, objectPosition, forwardedRef, onLayout, pointerEvents, recyclingKey: _recyclingKey, loop: _loop, imageRendering: _imageRendering, paused: _paused, transition: _transition, downsample: _downsample, onProgress: _onProgress, ...props }) {
+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;
 	if (typeof __DEV__ !== "undefined" && __DEV__) warnIfChildren(children);
 	const { accessibilityLabel, "aria-label": ariaLabel, resizeMode: _resizeMode, ...viewProps } = props;
@@ -270,12 +266,13 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadi
 	const src = sized ? sized.src : resolveUri(source);
 	const srcSet = sized === null || sized === void 0 ? void 0 : sized.srcSet;
 	const key = srcSet !== null && srcSet !== void 0 ? srcSet : src;
+	const 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 [result, setResult] = useState();
 	const ok = result && result.key === key ? result.ok : void 0;
-	const svgId = useSvgId().replace(/[^\w-]/g, "");
+	const svgId = useId().replace(/[^\w-]/g, "");
 	const tintId = `fast-image-tint-${svgId}`;
 	const blurId = `fast-image-blur-${svgId}`;
 	const fit = resolveObjectFit(objectFit, style);
@@ -295,6 +292,8 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadi
 	}, defaultUri && showDefault ? /* @__PURE__ */ React.createElement(Picture, {
 		key: `default ${defaultUri}`,
 		src: defaultUri,
+		loading,
+		priority,
 		fit: blurUri && (fit === "scale-down" || fit === "none") ? "contain" : fit,
 		position,
 		filter: blurUri ? [`url(#${blurId})`, tintColor ? `url(#${tintId})` : ""].filter(Boolean).join(" ") : filter,
@@ -303,7 +302,9 @@ function FastImageBase({ source, placeholder, defaultSource, tintColor, blurRadi
 		key: several ? "sizes" : key,
 		src,
 		srcSet,
-		lazy: !!several,
+		sizes,
+		loading,
+		priority,
 		fit,
 		position,
 		filter,
@@ -348,6 +349,14 @@ function thumbhashUri(hash) {
 	if (decode) return decode(hash);
 	if (typeof __DEV__ !== "undefined" && __DEV__) warnOnce("thumbhash-web", "react-native-fast-image: on the web, a `thumbhash` shows only with `import 'react-native-fast-image/thumbhash'` (it decodes them). Or make it a `blurDataUri` before it reaches the browser (e.g. on your server) with that module's thumbHashToBlurDataUri, which needs no JavaScript in the browser.", "warn");
 }
+function sourcePriority(source) {
+	const values = (Array.isArray(source) ? source : [source]).map((entry) => entry && typeof entry === "object" ? entry.priority : void 0);
+	return [
+		"high",
+		"normal",
+		"low"
+	].find((priority) => values.includes(priority));
+}
 function shared(source, key, preview) {
 	const values = (Array.isArray(source) ? source : [source]).map((entry) => {
 		var _ref;
@@ -402,7 +411,7 @@ const fill = {
 	width: "100%",
 	height: "100%"
 };
-function Picture({ src, srcSet, lazy, fit, position, filter, hidden, alt, onLoad, onError }) {
+function Picture({ src, srcSet, sizes, loading, priority, fit, position, filter, hidden, alt, onLoad, onError }) {
 	const image = useRef(null);
 	const mounted = useRef(true);
 	const handled = useRef(void 0);
@@ -439,8 +448,9 @@ function Picture({ src, srcSet, lazy, fit, position, filter, hidden, alt, onLoad
 		ref: image,
 		src,
 		srcSet,
-		sizes: srcSet ? "auto, 100vw" : void 0,
-		loading: lazy ? "lazy" : void 0,
+		sizes: srcSet ? sizes !== null && sizes !== void 0 ? sizes : "auto, 100vw" : void 0,
+		loading: loading === "eager" ? void 0 : "lazy",
+		fetchPriority: priority === "high" || priority === "low" ? priority : void 0,
 		alt,
 		draggable: false,
 		style: {

package/dist/index.web.js.flow

@@ -149,6 +149,8 @@ export type FastImageProps = $ReadOnly<{|
     recyclingKey?: ?string,
     loop?: ?(boolean | number),
     imageRendering?: ?('auto' | 'smooth' | 'pixelated'),
+    loading?: ?('lazy' | 'eager'),
+    sizes?: ?string,
     paused?: ?boolean,
     transition?: ?(boolean | number | Transition),
     downsample?: ?boolean,

package/package.json

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

package/src/index.js.flow

@@ -149,6 +149,8 @@ export type FastImageProps = $ReadOnly<{|
     recyclingKey?: ?string,
     loop?: ?(boolean | number),
     imageRendering?: ?('auto' | 'smooth' | 'pixelated'),
+    loading?: ?('lazy' | 'eager'),
+    sizes?: ?string,
     paused?: ?boolean,
     transition?: ?(boolean | number | Transition),
     downsample?: ?boolean,

package/src/index.tsx

@@ -54,6 +54,8 @@ export type Source = {
      * - `'normal'`: the default.
      * - `'high'`: e.g. the image the screen is about.
      *
+     * On the web, it's the image's `fetchpriority`.
+     *
      * @default 'normal'
      */
     priority?: Priority
@@ -474,6 +476,25 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
      * @default 'auto'
      */
     imageRendering?: 'auto' | 'smooth' | 'pixelated'
+    /**
+     * Whether the image loads as it nears the screen (`'lazy'`) or at once
+     * (`'eager'`).
+     *
+     * @default 'lazy'
+     * @platform web
+     */
+    loading?: 'lazy' | 'eager'
+    /**
+     * With several sources, the width the image is shown at, as the image's
+     * [`sizes`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img#sizes),
+     * so the browser loads the size that fits. The default is the width the
+     * image is laid out at, which needs `loading="lazy"` (otherwise, or in
+     * browsers without it, the window's width).
+     *
+     * @default 'auto, 100vw'
+     * @platform web
+     */
+    sizes?: string
     /**
      * Pauses an animated image (GIF, animated WebP, APNG, or animated AVIF) on
      * the frame it's showing; `false` plays it again from there
@@ -811,6 +832,9 @@ function FastImageBase({
     objectPosition,
     loop,
     transition,
+    // Web only.
+    loading: _loading,
+    sizes: _sizes,
     forwardedRef,
     ...viewProps
 }: FastImageProps & { forwardedRef: React.Ref<any> }) {

package/src/index.web.tsx

@@ -11,15 +11,17 @@
 //
 // Works: source (uri, require(), or several sizes: see sizedSources, and
 // thumbhash and blurDataUri), placeholder (and defaultSource), objectFit,
-// objectPosition, tintColor, blurRadius, style,
-// onLoadStart, onLoad, onError, onLoadEnd, and View props (testID,
-// accessibility, onLayout, pointerEvents). The native-only props (cache,
-// priority, headers, transition, downsample, loop, paused, imageRendering,
-// recyclingKey) and onProgress are ignored.
+// objectPosition, tintColor, blurRadius, style, source.priority (as
+// fetchpriority), the web-only loading and sizes, onLoadStart, onLoad,
+// onError, onLoadEnd, and View props (testID, accessibility, onLayout,
+// pointerEvents). The native-only props (cache, headers, transition,
+// downsample, loop, paused, imageRendering, recyclingKey) and onProgress
+// are ignored.
 import React, {
     forwardRef,
     memo,
     useEffect,
+    useId,
     useLayoutEffect,
     useRef,
     useState,
@@ -40,6 +42,7 @@ import type {
     FastImageStaticProperties,
     ObjectFit,
     PreloadResult,
+    Priority,
     Source,
     SourcePlaceholder,
 } from './index'
@@ -52,15 +55,6 @@ const notSupported: CachePathResult = {
     error: 'Not supported on the web',
 }
 
-// An id that's the same on the server and in the browser: React's useId,
-// from React 18 (this package's React types are older), without the
-// characters an SVG id can't have (:r0: in React 18, «r0» in React 19). On
-// React 17, a counter's (which can differ from the server's).
-let ids = 0
-const useCounterId = () => useState(() => `${++ids}`)[0]
-const useSvgId: () => string =
-    (React as unknown as { useId?: () => string }).useId ?? useCounterId
-
 // A layout effect in the browser (it runs before the image can show), and an
 // effect when rendering on a server, where layout effects warn.
 const useClientLayoutEffect =
@@ -86,6 +80,8 @@ function FastImageBase({
     children,
     objectFit,
     objectPosition,
+    loading,
+    sizes,
     forwardedRef,
     // On the wrapper, the view the layout and touches are for here (on
     // native, FastImage's only view).
@@ -125,6 +121,7 @@ function FastImageBase({
     // one doesn't stay while it loads; with several sizes, the <img> stays,
     // and the browser shows the previous image until the new one has loaded.
     const key = srcSet ?? src
+    const priority = sourcePriority(source)
     // The source's blurDataUri, or its ThumbHash made into one (with
     // `react-native-fast-image/thumbhash`), shows blurred (see PreviewBlur)
     // in place of `placeholder` (or `placeholder`'s, for a source without its
@@ -144,7 +141,7 @@ function FastImageBase({
     const ok = result && result.key === key ? result.ok : undefined
     // The same on the server and in the browser. React's ids have characters
     // an SVG id can't (:r0: in React 18, «r0» in React 19).
-    const svgId = useSvgId().replace(/[^\w-]/g, '')
+    const svgId = useId().replace(/[^\w-]/g, '')
     const tintId = `fast-image-tint-${svgId}`
     const blurId = `fast-image-blur-${svgId}`
     // objectFit (the prop, then style's).
@@ -179,6 +176,9 @@ function FastImageBase({
                 <Picture
                     key={`default ${defaultUri}`}
                     src={defaultUri}
+                    // Loaded when the image is (a data uri needs no request).
+                    loading={loading}
+                    priority={priority}
                     // A source's placeholder stands for an image whose size
                     // isn't known yet: as contain for scale-down and none,
                     // which show an image at its own size.
@@ -210,7 +210,9 @@ function FastImageBase({
                     key={several ? 'sizes' : key}
                     src={src}
                     srcSet={srcSet}
-                    lazy={!!several}
+                    sizes={sizes}
+                    loading={loading}
+                    priority={priority}
                     fit={fit}
                     position={position}
                     filter={filter}
@@ -257,6 +259,20 @@ function thumbhashUri(hash: string | undefined): string | undefined {
     return undefined
 }
 
+// A source's priority: one source's, or the highest of several sizes'.
+function sourcePriority(
+    source: FastImageProps['source'],
+): Priority | undefined {
+    const values = (Array.isArray(source) ? source : [source]).map((entry) =>
+        entry && typeof entry === 'object'
+            ? (entry as Source).priority
+            : undefined,
+    )
+    return (['high', 'normal', 'low'] as const).find((priority) =>
+        values.includes(priority),
+    )
+}
+
 // The thumbhash or blurDataUri a source shows: its own, or `placeholder`'s
 // (preview) if it has neither. With several sources, the one they all show.
 function shared(
@@ -321,9 +337,9 @@ type PackagerAsset = {
 // Several sizes of an image, as a srcset (each size's width, times its
 // scale), from which the browser loads the one for the image's width in
 // device pixels, usually the smallest at least as wide, as expo-image does.
-// sizes="auto" has the browser use the width the image is laid out at; it
-// only applies to lazy images, and browsers without it use the next value,
-// 100vw (the viewport's width). src is the largest, for browsers without
+// sizes="auto" (the default sizes) has the browser use the width the image
+// is laid out at; it only applies to lazy images, and otherwise, or in
+// browsers without it, the next value, 100vw (the viewport's width). src is the largest, for browsers without
 // srcset.
 function sizedSources(sources: Source[]) {
     const widths = sources
@@ -395,7 +411,9 @@ const fill = {
 function Picture({
     src,
     srcSet,
-    lazy,
+    sizes,
+    loading,
+    priority,
     fit,
     position,
     filter,
@@ -406,8 +424,11 @@ function Picture({
 }: {
     src: string
     srcSet?: string
-    // Several sizes load lazily, for sizes="auto" (see sizedSources).
-    lazy?: boolean
+    // The props (see sizedSources for sizes).
+    sizes?: string
+    loading?: 'lazy' | 'eager'
+    // source.priority, as the <img>'s fetchpriority.
+    priority?: Priority
     fit: ObjectFit
     // objectPosition, as CSS.
     position: string
@@ -478,8 +499,12 @@ function Picture({
             ref={image}
             src={src}
             srcSet={srcSet}
-            sizes={srcSet ? 'auto, 100vw' : undefined}
-            loading={lazy ? 'lazy' : undefined}
+            sizes={srcSet ? (sizes ?? 'auto, 100vw') : undefined}
+            loading={loading === 'eager' ? undefined : 'lazy'}
+            // For 'high' and 'low' (the browser's own for 'normal').
+            fetchPriority={
+                priority === 'high' || priority === 'low' ? priority : undefined
+            }
             alt={alt}
             draggable={false}
             style={{