react-native-nitro-image-pipeline 1.2.0 → 1.2.1

package/lib/typescript/src/resizeForStyle.d.ts

@@ -0,0 +1,30 @@
+import { type StyleProp, type ViewStyle } from 'react-native';
+import type { CornerRadii, ResizeOptions } from './specs/nitro-image-toolkit.nitro';
+/**
+ * Converts a layout size in points (dp) to the pipeline's `resize` option in
+ * whole bitmap pixels using `PixelRatio.getPixelSizeForLayoutSize`. Returns
+ * `undefined` unless both values are positive numbers.
+ */
+export declare function resizeForLayout(width: unknown, height: unknown): ResizeOptions | undefined;
+/**
+ * Derives the pipeline's `resize` option from a view style whose `width` and
+ * `height` are numeric points, so the bitmap matches the display size on
+ * every screen density:
+ * ```ts
+ * useImage({ url, resize: resizeForStyle(styles.image) });
+ * ```
+ * Arrays and registered styles are flattened. Returns `undefined` when either
+ * dimension is missing or not a number (`'50%'`, `'auto'`, flex-driven) —
+ * use `<PipelineImage>` for those, which measures the view instead.
+ */
+export declare function resizeForStyle(style: StyleProp<ViewStyle>): ResizeOptions | undefined;
+/**
+ * Derives a `cornerRadius` option from a view style's `borderRadius` /
+ * `borderTopLeftRadius` / `borderTopRightRadius` / `borderBottomLeftRadius` /
+ * `borderBottomRightRadius`, in points. Per-corner properties override
+ * `borderRadius` for that corner; a corner with neither set stays square.
+ * Non-numeric values (percentages, animated values) are ignored, like
+ * {@linkcode resizeForStyle}. Returns `undefined` when none are set.
+ */
+export declare function cornerRadiusForStyle(style: StyleProp<ViewStyle>): number | CornerRadii | undefined;
+//# sourceMappingURL=resizeForStyle.d.ts.map

package/lib/typescript/src/resizeForStyle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resizeForStyle.d.ts","sourceRoot":"","sources":["../../../src/resizeForStyle.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,SAAS,EAEd,KAAK,SAAS,EACf,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EACV,WAAW,EACX,aAAa,EACd,MAAM,mCAAmC,CAAC;AAE3C;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,OAAO,GACd,aAAa,GAAG,SAAS,CAS3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,CAAC,SAAS,CAAC,GAC1B,aAAa,GAAG,SAAS,CAG3B;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,CAAC,SAAS,CAAC,GAC1B,MAAM,GAAG,WAAW,GAAG,SAAS,CAoClC"}

package/lib/typescript/src/useImage.d.ts

@@ -0,0 +1,53 @@
+import type { Image } from 'react-native-nitro-image';
+import type { CacheOption, CornerRadii, ResizeOptions } from './specs/nitro-image-toolkit.nitro';
+type Result = {
+    image: undefined;
+    error: undefined;
+} | {
+    image: Image;
+    error: undefined;
+} | {
+    image: undefined;
+    error: Error;
+};
+/**
+ * A hook to asynchronously load an image from the
+ * given {@linkcode AsyncImageSource} into memory.
+ * @example
+ * ```ts
+ * const { image, error } = useImage({ filePath: '/tmp/image.jpg' })
+ * ```
+ */
+export declare function useImage({ url, blur, cornerRadius, resize, cache, enabled, }: {
+    url: string;
+    /**
+     * Gaussian blur strength, as the standard deviation (sigma) of the blur in
+     * source-image pixels (of the resized bitmap when `resize` is set). Matches
+     * across iOS and Android; roughly half of React Native's `blurRadius`.
+     */
+    blur?: number;
+    /**
+     * Corner radius in pixels of the loaded bitmap. Pass a single number for
+     * uniform rounding, or per-corner radii (inline object literals are fine —
+     * the hook compares the radii by value, not identity). Pair with `resize`
+     * so the radii apply at the size you display instead of the source size.
+     */
+    cornerRadius?: number | CornerRadii;
+    /**
+     * Resize the bitmap to exactly this size in pixels (aspect-fill,
+     * center-crop) before blur/rounding. Typically your display size in points
+     * multiplied by `PixelRatio.get()`. Inline object literals are fine.
+     */
+    resize?: ResizeOptions;
+    cache?: CacheOption;
+    /**
+     * When `false`, no request is made and the result stays in the loading
+     * state (or keeps the current image if `url` is unchanged) until it becomes
+     * `true`. Use it to defer loading until inputs such as a layout size are
+     * known.
+     * @default true
+     */
+    enabled?: boolean;
+}): Result;
+export {};
+//# sourceMappingURL=useImage.d.ts.map

package/lib/typescript/src/useImage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useImage.d.ts","sourceRoot":"","sources":["../../../src/useImage.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAGtD,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,aAAa,EACd,MAAM,mCAAmC,CAAC;AAE3C,KAAK,MAAM,GAEP;IACE,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,SAAS,CAAC;CAClB,GAED;IACE,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,SAAS,CAAC;CAClB,GAED;IACE,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;CACd,CAAC;AAEN;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,EACvB,GAAG,EACH,IAAQ,EACR,YAAgB,EAChB,MAAM,EACN,KAAK,EACL,OAAc,GACf,EAAE;IACD,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IACpC;;;;OAIG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,MAAM,CA4ET"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-image-pipeline",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "High-performance image loading, caching, and processing for React Native, built with Nitro Modules",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/module/index.js",

package/src/NitroImagePipeline.ts

@@ -0,0 +1,6 @@
+import { NitroModules } from 'react-native-nitro-modules';
+
+import type { NitroImagePipeline as NitroImagePipelineSpec } from './specs/nitro-image-toolkit.nitro';
+
+export const NitroImagePipeline =
+  NitroModules.createHybridObject<NitroImagePipelineSpec>('NitroImagePipeline');

package/src/PipelineImage.tsx

@@ -0,0 +1,156 @@
+import { useEffect, useRef, useState } from 'react';
+import {
+  type HostComponent,
+  type LayoutChangeEvent,
+  PixelRatio,
+} from 'react-native';
+import { type Image, NativeNitroImage } from 'react-native-nitro-image';
+
+import {
+  cornerRadiusForStyle,
+  resizeForLayout,
+  resizeForStyle,
+} from './resizeForStyle';
+import type {
+  CacheOption,
+  CornerRadii,
+  ResizeOptions,
+} from './specs/nitro-image-toolkit.nitro';
+import { useImage } from './useImage';
+
+type ReactProps<T> = T extends HostComponent<infer P> ? P : never;
+type NativeImageProps = ReactProps<typeof NativeNitroImage>;
+
+export interface PipelineImageProps extends Omit<NativeImageProps, 'image'> {
+  /** URL of the image to load through the pipeline. */
+  url: string;
+  /**
+   * Gaussian blur sigma in **points** (density-independent). Unlike
+   * `useImage`/`loadImage`, where it is bitmap pixels, the component
+   * multiplies it by `PixelRatio.get()` so the same value looks the same on
+   * every device.
+   * @default 0
+   */
+  blur?: number;
+  /**
+   * Corner radius in **points** — a single number or per-corner radii.
+   * Converted to bitmap pixels with `PixelRatio.get()` and baked into the
+   * bitmap at the display size.
+   *
+   * When omitted, it's derived from `style`'s `borderRadius` /
+   * `borderTopLeftRadius` / `borderTopRightRadius` / `borderBottomLeftRadius`
+   * / `borderBottomRightRadius` instead — set this prop to override that.
+   * @default undefined (derived from `style`, or square corners if unset there)
+   */
+  cornerRadius?: number | CornerRadii;
+  cache?: CacheOption;
+  /** Called with the processed `Image` each time a new variant resolves. */
+  onLoad?: (image: Image) => void;
+  /** Called when loading fails. */
+  onError?: (error: Error) => void;
+}
+
+function sameSize(a?: ResizeOptions, b?: ResizeOptions): boolean {
+  return a?.width === b?.width && a?.height === b?.height;
+}
+
+function scaleRadius(
+  cornerRadius: number | CornerRadii,
+  scale: number,
+): number | CornerRadii {
+  if (typeof cornerRadius === 'number') {
+    return cornerRadius * scale;
+  }
+  return {
+    topLeft: (cornerRadius.topLeft ?? 0) * scale,
+    topRight: (cornerRadius.topRight ?? 0) * scale,
+    bottomLeft: (cornerRadius.bottomLeft ?? 0) * scale,
+    bottomRight: (cornerRadius.bottomRight ?? 0) * scale,
+  };
+}
+
+/**
+ * A `NativeNitroImage` that loads `url` through the pipeline at exactly the
+ * size it is displayed: the bitmap is resized to the view's size in points ×
+ * `PixelRatio.get()`, so `blur` and `cornerRadius` (both in points here) apply
+ * 1:1 to what is on screen and large sources are never decoded at full size.
+ *
+ * A numeric `width`/`height` in `style` starts loading immediately; otherwise
+ * (`'50%'`, `flex`, `aspectRatio`, …) loading waits for the first `onLayout`.
+ * If the layout size later changes, a new variant is loaded and swapped in
+ * without flashing. Without an explicit `cornerRadius` prop, `style`'s
+ * `borderRadius`-family properties are baked into the bitmap instead — no
+ * separate view-layer rounding needed.
+ * @example
+ * ```tsx
+ * <PipelineImage
+ *   url="https://example.com/photo.jpg"
+ *   style={{ width: 300, height: 200 }}
+ *   cornerRadius={24}
+ * />
+ * ```
+ */
+export function PipelineImage({
+  url,
+  blur = 0,
+  cornerRadius,
+  cache,
+  onLoad,
+  onError,
+  style,
+  onLayout,
+  ...viewProps
+}: PipelineImageProps) {
+  const scale = PixelRatio.get();
+  const styleSize = resizeForStyle(style);
+  const [layoutSize, setLayoutSize] = useState<ResizeOptions | undefined>(
+    undefined,
+  );
+  // A numeric style is what the caller declared, so it wins and starts the
+  // request a frame earlier; the measured layout is the fallback.
+  const resize = styleSize ?? layoutSize;
+  // Same precedence: an explicit prop wins over what style implies.
+  const effectiveCornerRadius =
+    cornerRadius ?? cornerRadiusForStyle(style) ?? 0;
+
+  const { image, error } = useImage({
+    url,
+    blur: blur * scale,
+    cornerRadius: scaleRadius(effectiveCornerRadius, scale),
+    cache,
+    resize,
+    enabled: resize !== undefined,
+  });
+
+  // Latest callbacks in refs so inline arrow props don't re-fire the effects.
+  const onLoadRef = useRef(onLoad);
+  const onErrorRef = useRef(onError);
+  useEffect(() => {
+    onLoadRef.current = onLoad;
+    onErrorRef.current = onError;
+  });
+  useEffect(() => {
+    if (image) onLoadRef.current?.(image);
+  }, [image]);
+  useEffect(() => {
+    if (error) onErrorRef.current?.(error);
+  }, [error]);
+
+  const handleLayout = (event: LayoutChangeEvent) => {
+    onLayout?.(event);
+    const { width, height } = event.nativeEvent.layout;
+    const next = resizeForLayout(width, height);
+    // Always record it (even when a numeric style is in charge) so a later
+    // switch to a non-numeric style has a size to fall back on.
+    setLayoutSize((prev) => (sameSize(prev, next) ? prev : next));
+  };
+
+  return (
+    <NativeNitroImage
+      {...viewProps}
+      style={style}
+      onLayout={handleLayout}
+      image={image}
+    />
+  );
+}

package/src/index.ts

@@ -1,144 +1,14 @@
-import { useEffect, useRef, useState } from 'react';
-import type { Image } from 'react-native-nitro-image';
-import { NitroModules } from 'react-native-nitro-modules';
-
-import type {
+export { NitroImagePipeline } from './NitroImagePipeline';
+export { PipelineImage, type PipelineImageProps } from './PipelineImage';
+export {
+  cornerRadiusForStyle,
+  resizeForLayout,
+  resizeForStyle,
+} from './resizeForStyle';
+export type {
   CacheOption,
   CornerRadii,
-  NitroImagePipeline as NitroImagePipelineSpec,
   Options,
   ResizeOptions,
 } from './specs/nitro-image-toolkit.nitro';
-
-export type { CacheOption, CornerRadii, Options, ResizeOptions };
-
-export const NitroImagePipeline =
-  NitroModules.createHybridObject<NitroImagePipelineSpec>('NitroImagePipeline');
-
-type Result =
-  // Loading State
-  | {
-      image: undefined;
-      error: undefined;
-    }
-  // Loaded state
-  | {
-      image: Image;
-      error: undefined;
-    }
-  // Error state
-  | {
-      image: undefined;
-      error: Error;
-    };
-
-/**
- * A hook to asynchronously load an image from the
- * given {@linkcode AsyncImageSource} into memory.
- * @example
- * ```ts
- * const { image, error } = useImage({ filePath: '/tmp/image.jpg' })
- * ```
- */
-export function useImage({
-  url,
-  blur = 0,
-  cornerRadius = 0,
-  resize,
-  cache,
-}: {
-  url: string;
-  /**
-   * Gaussian blur strength, as the standard deviation (sigma) of the blur in
-   * source-image pixels (of the resized bitmap when `resize` is set). Matches
-   * across iOS and Android; roughly half of React Native's `blurRadius`.
-   */
-  blur?: number;
-  /**
-   * Corner radius in pixels of the loaded bitmap. Pass a single number for
-   * uniform rounding, or per-corner radii (inline object literals are fine —
-   * the hook compares the radii by value, not identity). Pair with `resize`
-   * so the radii apply at the size you display instead of the source size.
-   */
-  cornerRadius?: number | CornerRadii;
-  /**
-   * Resize the bitmap to exactly this size in pixels (aspect-fill,
-   * center-crop) before blur/rounding. Typically your display size in points
-   * multiplied by `PixelRatio.get()`. Inline object literals are fine.
-   */
-  resize?: ResizeOptions;
-  cache?: CacheOption;
-}): Result {
-  const [image, setImage] = useState<Result>({
-    image: undefined,
-    error: undefined,
-  });
-  const loadedUrlRef = useRef(url);
-
-  // Split the option into primitives so an inline `{ topLeft: 24, ... }`
-  // literal (new identity every render) doesn't re-trigger the effect.
-  const isUniformRadius = typeof cornerRadius === 'number';
-  const uniformRadius = isUniformRadius ? cornerRadius : 0;
-  const {
-    topLeft = 0,
-    topRight = 0,
-    bottomLeft = 0,
-    bottomRight = 0,
-  } = isUniformRadius ? {} : cornerRadius;
-  const resizeWidth = resize?.width ?? 0;
-  const resizeHeight = resize?.height ?? 0;
-
-  useEffect(() => {
-    let cancelled = false;
-    // Only reset to the loading state when the URL changes; for same-URL
-    // param tweaks (blur/cornerRadius/cache) keep showing the current image
-    // until the new variant resolves, to avoid flashing empty.
-    if (loadedUrlRef.current !== url) {
-      loadedUrlRef.current = url;
-      setImage({ image: undefined, error: undefined });
-    }
-
-    (async () => {
-      try {
-        const result = await NitroImagePipeline.loadImage(url, {
-          blur,
-          cornerRadius: isUniformRadius
-            ? uniformRadius
-            : { topLeft, topRight, bottomLeft, bottomRight },
-          resize:
-            resizeWidth > 0 && resizeHeight > 0
-              ? { width: resizeWidth, height: resizeHeight }
-              : undefined,
-          cache,
-        });
-
-        if (!cancelled) {
-          setImage({ image: result, error: undefined });
-        }
-      } catch (e) {
-        const error = e instanceof Error ? e : new Error(`${e}`);
-        if (!cancelled) {
-          setImage({ image: undefined, error: error });
-        }
-      }
-    })();
-
-    return () => {
-      cancelled = true;
-    };
-  }, [
-    url,
-    blur,
-    isUniformRadius,
-    uniformRadius,
-    topLeft,
-    topRight,
-    bottomLeft,
-    bottomRight,
-    resizeWidth,
-    resizeHeight,
-    cache,
-  ]);
-
-  return image;
-}
+export { useImage } from './useImage';

package/src/resizeForStyle.ts

@@ -0,0 +1,96 @@
+import {
+  PixelRatio,
+  type StyleProp,
+  StyleSheet,
+  type ViewStyle,
+} from 'react-native';
+
+import type {
+  CornerRadii,
+  ResizeOptions,
+} from './specs/nitro-image-toolkit.nitro';
+
+/**
+ * Converts a layout size in points (dp) to the pipeline's `resize` option in
+ * whole bitmap pixels using `PixelRatio.getPixelSizeForLayoutSize`. Returns
+ * `undefined` unless both values are positive numbers.
+ */
+export function resizeForLayout(
+  width: unknown,
+  height: unknown,
+): ResizeOptions | undefined {
+  if (typeof width !== 'number' || typeof height !== 'number') {
+    return undefined;
+  }
+  const pixelWidth = PixelRatio.getPixelSizeForLayoutSize(width);
+  const pixelHeight = PixelRatio.getPixelSizeForLayoutSize(height);
+  return pixelWidth > 0 && pixelHeight > 0
+    ? { width: pixelWidth, height: pixelHeight }
+    : undefined;
+}
+
+/**
+ * Derives the pipeline's `resize` option from a view style whose `width` and
+ * `height` are numeric points, so the bitmap matches the display size on
+ * every screen density:
+ * ```ts
+ * useImage({ url, resize: resizeForStyle(styles.image) });
+ * ```
+ * Arrays and registered styles are flattened. Returns `undefined` when either
+ * dimension is missing or not a number (`'50%'`, `'auto'`, flex-driven) —
+ * use `<PipelineImage>` for those, which measures the view instead.
+ */
+export function resizeForStyle(
+  style: StyleProp<ViewStyle>,
+): ResizeOptions | undefined {
+  const flat = StyleSheet.flatten(style);
+  return resizeForLayout(flat?.width, flat?.height);
+}
+
+/**
+ * Derives a `cornerRadius` option from a view style's `borderRadius` /
+ * `borderTopLeftRadius` / `borderTopRightRadius` / `borderBottomLeftRadius` /
+ * `borderBottomRightRadius`, in points. Per-corner properties override
+ * `borderRadius` for that corner; a corner with neither set stays square.
+ * Non-numeric values (percentages, animated values) are ignored, like
+ * {@linkcode resizeForStyle}. Returns `undefined` when none are set.
+ */
+export function cornerRadiusForStyle(
+  style: StyleProp<ViewStyle>,
+): number | CornerRadii | undefined {
+  const flat = StyleSheet.flatten(style);
+  const base =
+    typeof flat?.borderRadius === 'number' ? flat.borderRadius : undefined;
+  const topLeft =
+    typeof flat?.borderTopLeftRadius === 'number'
+      ? flat.borderTopLeftRadius
+      : undefined;
+  const topRight =
+    typeof flat?.borderTopRightRadius === 'number'
+      ? flat.borderTopRightRadius
+      : undefined;
+  const bottomLeft =
+    typeof flat?.borderBottomLeftRadius === 'number'
+      ? flat.borderBottomLeftRadius
+      : undefined;
+  const bottomRight =
+    typeof flat?.borderBottomRightRadius === 'number'
+      ? flat.borderBottomRightRadius
+      : undefined;
+
+  if (
+    topLeft === undefined &&
+    topRight === undefined &&
+    bottomLeft === undefined &&
+    bottomRight === undefined
+  ) {
+    return base;
+  }
+
+  return {
+    topLeft: topLeft ?? base,
+    topRight: topRight ?? base,
+    bottomLeft: bottomLeft ?? base,
+    bottomRight: bottomRight ?? base,
+  };
+}

package/src/useImage.ts

@@ -0,0 +1,149 @@
+import { useEffect, useRef, useState } from 'react';
+import type { Image } from 'react-native-nitro-image';
+
+import { NitroImagePipeline } from './NitroImagePipeline';
+import type {
+  CacheOption,
+  CornerRadii,
+  ResizeOptions,
+} from './specs/nitro-image-toolkit.nitro';
+
+type Result =
+  // Loading State
+  | {
+      image: undefined;
+      error: undefined;
+    }
+  // Loaded state
+  | {
+      image: Image;
+      error: undefined;
+    }
+  // Error state
+  | {
+      image: undefined;
+      error: Error;
+    };
+
+/**
+ * A hook to asynchronously load an image from the
+ * given {@linkcode AsyncImageSource} into memory.
+ * @example
+ * ```ts
+ * const { image, error } = useImage({ filePath: '/tmp/image.jpg' })
+ * ```
+ */
+export function useImage({
+  url,
+  blur = 0,
+  cornerRadius = 0,
+  resize,
+  cache,
+  enabled = true,
+}: {
+  url: string;
+  /**
+   * Gaussian blur strength, as the standard deviation (sigma) of the blur in
+   * source-image pixels (of the resized bitmap when `resize` is set). Matches
+   * across iOS and Android; roughly half of React Native's `blurRadius`.
+   */
+  blur?: number;
+  /**
+   * Corner radius in pixels of the loaded bitmap. Pass a single number for
+   * uniform rounding, or per-corner radii (inline object literals are fine —
+   * the hook compares the radii by value, not identity). Pair with `resize`
+   * so the radii apply at the size you display instead of the source size.
+   */
+  cornerRadius?: number | CornerRadii;
+  /**
+   * Resize the bitmap to exactly this size in pixels (aspect-fill,
+   * center-crop) before blur/rounding. Typically your display size in points
+   * multiplied by `PixelRatio.get()`. Inline object literals are fine.
+   */
+  resize?: ResizeOptions;
+  cache?: CacheOption;
+  /**
+   * When `false`, no request is made and the result stays in the loading
+   * state (or keeps the current image if `url` is unchanged) until it becomes
+   * `true`. Use it to defer loading until inputs such as a layout size are
+   * known.
+   * @default true
+   */
+  enabled?: boolean;
+}): Result {
+  const [image, setImage] = useState<Result>({
+    image: undefined,
+    error: undefined,
+  });
+  const loadedUrlRef = useRef(url);
+
+  // Split the option into primitives so an inline `{ topLeft: 24, ... }`
+  // literal (new identity every render) doesn't re-trigger the effect.
+  const isUniformRadius = typeof cornerRadius === 'number';
+  const uniformRadius = isUniformRadius ? cornerRadius : 0;
+  const {
+    topLeft = 0,
+    topRight = 0,
+    bottomLeft = 0,
+    bottomRight = 0,
+  } = isUniformRadius ? {} : cornerRadius;
+  const resizeWidth = resize?.width ?? 0;
+  const resizeHeight = resize?.height ?? 0;
+
+  useEffect(() => {
+    let cancelled = false;
+    // Only reset to the loading state when the URL changes; for same-URL
+    // param tweaks (blur/cornerRadius/cache) keep showing the current image
+    // until the new variant resolves, to avoid flashing empty.
+    if (loadedUrlRef.current !== url) {
+      loadedUrlRef.current = url;
+      setImage({ image: undefined, error: undefined });
+    }
+
+    if (enabled) {
+      (async () => {
+        try {
+          const result = await NitroImagePipeline.loadImage(url, {
+            blur,
+            cornerRadius: isUniformRadius
+              ? uniformRadius
+              : { topLeft, topRight, bottomLeft, bottomRight },
+            resize:
+              resizeWidth > 0 && resizeHeight > 0
+                ? { width: resizeWidth, height: resizeHeight }
+                : undefined,
+            cache,
+          });
+
+          if (!cancelled) {
+            setImage({ image: result, error: undefined });
+          }
+        } catch (e) {
+          const error = e instanceof Error ? e : new Error(`${e}`);
+          if (!cancelled) {
+            setImage({ image: undefined, error: error });
+          }
+        }
+      })();
+    }
+
+    return () => {
+      cancelled = true;
+    };
+  }, [
+    url,
+    blur,
+    isUniformRadius,
+    uniformRadius,
+    topLeft,
+    topRight,
+    bottomLeft,
+    bottomRight,
+    resizeWidth,
+    resizeHeight,
+    cache,
+    enabled,
+  ]);
+
+  return image;
+}