react-native-fast-image 10.1.1 → 10.3.0

package/README.md

@@ -26,6 +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)).
 - [**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.
@@ -70,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).
 
@@ -160,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`
@@ -211,6 +214,32 @@ Whether the image is kept on disk. With `false` it isn't kept in the disk cache
 
 ---
 
+##### `source.thumbhash`
+
+**Type:** `string`
+
+A [ThumbHash](https://evanw.github.io/thumbhash/) of the image, shown blurred while the image loads, and if it fails to load. It's a short string you make when the image is uploaded (e.g. with the `thumbhash` package) and send with the image's url.
+
+On the web, it needs `import 'react-native-fast-image/thumbhash'` (see [ThumbHashes on the web](#thumbhashes-on-the-web)).
+
+```jsx
+<FastImage source={{ uri: photo.url, thumbhash: photo.thumbhash }} />
+```
+
+---
+
+##### `source.blurDataUri`
+
+**Type:** `string`
+
+A tiny version of the image (e.g. 8 to 20 px) as a data uri, shown blurred while the image loads, and if it fails to load. On the web it shows without any JavaScript, e.g. in a server-rendered page.
+
+```jsx
+<FastImage source={{ uri: photo.url, blurDataUri: photo.lqip }} />
+```
+
+---
+
 ##### `source.width`
 
 **Type:** `number`
@@ -235,13 +264,32 @@ With several sources, the scale `width` and `height` are multiplied by.
 
 ---
 
+#### `placeholder`
+
+**Type:** `string | number | SourcePlaceholder`
+
+A placeholder shown while the image loads, and if it fails to load:
+
+- An image loaded with `require()`: `placeholder={require('./gray.png')}`.
+- A data uri: `placeholder="data:image/png;base64,…"`.
+- 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 source's own `thumbhash` or `blurDataUri` is shown instead, if it has one.
+
+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.
+
+---
+
 #### `defaultSource`
 
 **Type:** `number`
 
-An asset loaded with `require(...)`, shown while the first image loads, and if an image fails to load. When `source` changes, the previous image shows while the new one loads instead (see `source` and `recyclingKey`).
-
-On Android, `defaultSource` doesn't show in debug builds: there the dev server serves `require()`d images, and `defaultSource` is only loaded from the app's resources.
+**Deprecated:** Use `placeholder`, which does the same.
 
 ---
 
@@ -272,7 +320,7 @@ Where the image is in the view, as CSS's `object-position` places it: where its
 - A string in CSS's syntax: one or two keywords (`'top'`, `'left bottom'`), lengths in points (`'10px 20px'`, with `px`) or percentages (`'25% 75%'`), or offsets from an edge (`'right 10px bottom 20%'`). A percentage puts that point of the image at that point of the view: `'0% 0%'` is the top-left corner, `'100% 100%'` the bottom-right.
 - An object with one of `top` and `bottom` and one of `left` and `right`, each in points (a number) or a percentage (`'25%'`), e.g. `{ right: 10, bottom: '20%' }`. A missing axis is centered.
 
-Points are dp on Android. An invalid value is ignored (the image is centered), with a warning in development. `defaultSource` is placed the same way.
+Points are dp on Android. An invalid value is ignored (the image is centered), with a warning in development. Placeholders are placed the same way.
 
 ```jsx
 <FastImage source={{ uri }} objectFit="cover" objectPosition="top" />
@@ -284,7 +332,7 @@ Points are dp on Android. An invalid value is ignored (the image is centered), w
 
 **Type:** `string | null`
 
-For views that get reused for other content, such as rows in FlashList or recyclerlistview. Set it to something that identifies the content, e.g. the item's id. When it changes, the image is cleared right away (to `defaultSource`, or blank) instead of staying until the new one has loaded. Unlike changing `key`, this keeps the view, which is what list recycling is for.
+For views that get reused for other content, such as rows in FlashList or recyclerlistview. Set it to something that identifies the content, e.g. the item's id. When it changes, the image is cleared right away (to `placeholder`, or blank) instead of staying until the new one has loaded. Unlike changing `key`, this keeps the view, which is what list recycling is for.
 
 ```jsx
 <FastImage recyclingKey={item.id} source={{ uri: item.imageUrl }} />
@@ -319,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`
@@ -368,7 +432,7 @@ Blurs the image by this radius, in points (the same radius looks about the same
 
 It's for still images, or a radius that changes now and then (e.g. blurring a photo behind a sheet). Each change blurs the image again on the CPU, so don't animate it.
 
-- Only the loaded image is blurred, not `defaultSource`.
+- Only the loaded image is blurred, not a placeholder.
 - An animated image (GIF, animated WebP, APNG or AVIF) shows its first frame, blurred, and doesn't animate.
 - With `tintColor`, the blurred image is tinted.
 - The image is blurred at about the size it's shown at, off the main thread. The cached file stays the original image, so `getCachePath` and other views of it aren't affected.
@@ -452,7 +516,7 @@ The image's style: View's style props (`borderRadius` clips the image, and borde
 
 **Type:** `ColorValue`
 
-If supplied, changes the color of all the non-transparent pixels to the given color.
+If supplied, changes the color of all the non-transparent pixels to the given color, including the placeholder.
 
 <!-- api:props end -->
 
@@ -811,12 +875,20 @@ An image's load priority: see [`source.priority`](#sourcepriority).
 
 ---
 
+### `SourcePlaceholder`
+
+**Type:** `Pick<Source, 'thumbhash' | 'blurDataUri'>`
+
+A `thumbhash` or `blurDataUri` as `placeholder`.
+
+---
+
 ### `Transition`
 
 How the image fades in: see [`transition`](#transition).
 
 - `duration?` (`number`): How long the fade takes, in milliseconds; 0 means no fade. Defaults to the default transition's (see `FastImage.setDefaults`) if it fades, otherwise the platform's usual length: 300 ms on Android, 250 ms on iOS.
-- `betweenImages?` (`boolean`, default `false`): Also fades between images: a new `source` replacing an image that's showing cross-dissolves from it. Otherwise only an image that appears over nothing (or over `defaultSource`) fades in, and a new source replaces the image showing at once, once it has loaded.
+- `betweenImages?` (`boolean`, default `false`): Also fades between images: a new `source` replacing an image that's showing cross-dissolves from it. Otherwise only an image that appears over nothing (or over a placeholder) fades in, and a new source replaces the image showing at once, once it has loaded.
 - `skipOnCacheHit?` (`'none' | 'memory' | 'all' | null`, default `'memory'`): Skips the fade for an image from a cache, so images already loaded show at once, e.g. in a list scrolled back up or a reused row.
 
     - `'memory'`: skips it for images from the memory cache.
@@ -878,16 +950,37 @@ 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), `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`.
-- 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 `defaultSource` 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.
+- 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).
+- 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
+
+On the web, a [`thumbhash`](#sourcethumbhash) needs a decoder, which isn't included by default. Import it once:
+
+```js
+import 'react-native-fast-image/thumbhash'
+```
+
+Or, to show the preview without any JavaScript (e.g. in a server-rendered page), make the hash a [`blurDataUri`](#sourceblurdatauri) on your server:
+
+```js
+import { thumbHashToBlurDataUri } from 'react-native-fast-image/thumbhash'
+
+const source = {
+    uri: photo.url,
+    thumbhash: photo.thumbhash, // iOS and Android
+    blurDataUri: thumbHashToBlurDataUri(photo.thumbhash), // the web
+}
+```
+
 ## Jest
 
 With React Native's Jest preset, FastImage renders without any setup, as its native view (`FastImageView`, in snapshots). Its functions need the native module, which Jest doesn't have, so they throw: mock the ones a test calls, e.g.

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

@@ -136,8 +136,9 @@ final class FastImageBlur extends BitmapTransformation {
         pool.put(copy);
     }
 
-    // Three box blurs, each across then down, with the edges extended.
-    private static void blur(int[] pixels, int width, int height, int boxSize) {
+    // Three box blurs, each across then down, with the edges extended. Also
+    // for a source's blurDataUri (FastImageThumbHash).
+    static void blur(int[] pixels, int width, int height, int boxSize) {
         int[] other = new int[width * height];
         int radius = boxSize / 2;
         for (int i = 0; i < 3; i++) {

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

@@ -0,0 +1,246 @@
+package com.fastimage;
+
+import android.graphics.Bitmap;
+import android.graphics.BitmapFactory;
+import android.util.Base64;
+import android.util.LruCache;
+
+import androidx.annotation.Nullable;
+
+import java.nio.IntBuffer;
+import java.util.Locale;
+
+// A source's `thumbhash` (https://evanw.github.io/thumbhash/) decoded into the
+// placeholder it shows while its image loads: at most 32 × 32 pixels, which
+// the view scales up smoothly. Decoding takes well under a millisecond, so it
+// happens as the view picks its source; recent ones are cached by their hash,
+// for list rows that show the same images again. Also a source's
+// `blurDataUri`: a data uri's few pixels, scaled up to the same size and
+// blurred (blurDataUri).
+//
+// thumbHashToRGBA is Evan Wallace's reference decoder
+// (https://github.com/evanw/thumbhash, java/com/madebyevan/thumbhash), with a
+// check that the hash is long enough for what its header says it holds:
+//
+// Copyright (c) 2023 Evan Wallace
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to
+// deal in the Software without restriction, including without limitation the
+// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+// sell copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+// IN THE SOFTWARE.
+final class FastImageThumbHash {
+    private FastImageThumbHash() {
+    }
+
+    // Recently decoded placeholders, by their hash or blurDataUri: at most
+    // 4 KB each.
+    private static final LruCache<String, Bitmap> cache = new LruCache<>(256);
+
+    // A source's placeholder: its blurDataUri's, or its ThumbHash's.
+    @Nullable
+    static Bitmap placeholder(@Nullable String value) {
+        return value != null && isDataUri(value) ? blurDataUri(value) : bitmap(value);
+    }
+
+    // A source's blurDataUri, decoded, scaled so its longer side is 32 px
+    // (a ThumbHash's size), and blurred by about half of one of its pixels, so
+    // that a few pixels scale up smoothly instead of in steps.
+    @Nullable
+    static Bitmap blurDataUri(String uri) {
+        Bitmap cached = cache.get(uri);
+        if (cached != null) return cached;
+        Bitmap decoded = dataUri(uri);
+        if (decoded == null) return null;
+        int width = decoded.getWidth();
+        int height = decoded.getHeight();
+        float scale = 32f / Math.max(width, height);
+        int w = Math.max(1, Math.round(width * scale));
+        int h = Math.max(1, Math.round(height * scale));
+        // Blurred on its premultiplied pixels (as stored), so transparent
+        // pixels don't darken their neighbors.
+        Bitmap bitmap = Bitmap.createScaledBitmap(decoded, w, h, true).copy(Bitmap.Config.ARGB_8888, true);
+        if (bitmap == null) return null;
+        int[] pixels = new int[w * h];
+        IntBuffer buffer = IntBuffer.wrap(pixels);
+        bitmap.copyPixelsToBuffer(buffer);
+        FastImageBlur.blur(pixels, w, h, 2 * Math.max(1, Math.round(scale / 2)) + 1);
+        buffer.rewind();
+        bitmap.copyPixelsFromBuffer(buffer);
+        cache.put(uri, bitmap);
+        return bitmap;
+    }
+
+    static boolean isDataUri(String value) {
+        return value.regionMatches(true, 0, "data:", 0, 5);
+    }
+
+    // A base64 data uri's image (PNG, JPEG, WebP, a GIF's first frame), or
+    // null if it isn't one Android decodes (e.g. an SVG).
+    @Nullable
+    static Bitmap dataUri(String uri) {
+        int comma = uri.indexOf(',');
+        if (comma < 0 || !uri.substring(0, comma).toLowerCase(Locale.ROOT).endsWith(";base64")) return null;
+        byte[] data;
+        try {
+            data = Base64.decode(uri.substring(comma + 1), Base64.DEFAULT);
+        } catch (IllegalArgumentException e) {
+            return null;
+        }
+        return BitmapFactory.decodeByteArray(data, 0, data.length);
+    }
+
+    // The placeholder for a base64 ThumbHash (standard or url-safe, with or
+    // without padding), or null for an empty or invalid one.
+    @Nullable
+    static Bitmap bitmap(@Nullable String thumbhash) {
+        if (thumbhash == null || thumbhash.isEmpty()) return null;
+        Bitmap cached = cache.get(thumbhash);
+        if (cached != null) return cached;
+        StringBuilder base64 = new StringBuilder(thumbhash.trim().replace('-', '+').replace('_', '/'));
+        while (base64.length() % 4 != 0) base64.append('=');
+        byte[] hash;
+        try {
+            hash = Base64.decode(base64.toString(), Base64.NO_WRAP);
+        } catch (IllegalArgumentException e) {
+            return null;
+        }
+        int[] size = new int[2];
+        int[] colors = thumbHashToColors(hash, size);
+        if (colors == null) return null;
+        Bitmap bitmap = Bitmap.createBitmap(colors, size[0], size[1], Bitmap.Config.ARGB_8888);
+        cache.put(thumbhash, bitmap);
+        return bitmap;
+    }
+
+    // The hash decoded as unpremultiplied ARGB colors (Bitmap.createBitmap's),
+    // its width and height in size, or null if it's too short.
+    @Nullable
+    private static int[] thumbHashToColors(byte[] hash, int[] size) {
+        if (hash.length < 5) return null;
+        // Read the constants
+        int header24 = (hash[0] & 255) | ((hash[1] & 255) << 8) | ((hash[2] & 255) << 16);
+        int header16 = (hash[3] & 255) | ((hash[4] & 255) << 8);
+        float l_dc = (float) (header24 & 63) / 63.0f;
+        float p_dc = (float) ((header24 >> 6) & 63) / 31.5f - 1.0f;
+        float q_dc = (float) ((header24 >> 12) & 63) / 31.5f - 1.0f;
+        float l_scale = (float) ((header24 >> 18) & 31) / 31.0f;
+        boolean hasAlpha = (header24 >> 23) != 0;
+        float p_scale = (float) ((header16 >> 3) & 63) / 63.0f;
+        float q_scale = (float) ((header16 >> 9) & 63) / 63.0f;
+        boolean isLandscape = (header16 >> 15) != 0;
+        int lx = Math.max(3, isLandscape ? hasAlpha ? 5 : 7 : header16 & 7);
+        int ly = Math.max(3, isLandscape ? header16 & 7 : hasAlpha ? 5 : 7);
+        int ac_start = hasAlpha ? 6 : 5;
+        int ac_count = count(lx, ly) + 2 * count(3, 3) + (hasAlpha ? count(5, 5) : 0);
+        if (hash.length < ac_start + (ac_count + 1) / 2) return null;
+        float a_dc = hasAlpha ? (float) (hash[5] & 15) / 15.0f : 1.0f;
+        float a_scale = hasAlpha ? (float) ((hash[5] >> 4) & 15) / 15.0f : 0;
+
+        // Read the varying factors (boost saturation by 1.25x to compensate for quantization)
+        int[] ac_index = {0};
+        float[] l_ac = decode(hash, ac_start, ac_index, lx, ly, l_scale);
+        float[] p_ac = decode(hash, ac_start, ac_index, 3, 3, p_scale * 1.25f);
+        float[] q_ac = decode(hash, ac_start, ac_index, 3, 3, q_scale * 1.25f);
+        float[] a_ac = hasAlpha ? decode(hash, ac_start, ac_index, 5, 5, a_scale) : null;
+
+        // Decode using the DCT into RGB
+        float ratio = approximateAspectRatio(hash);
+        int w = Math.max(1, Math.round(ratio > 1.0f ? 32.0f : 32.0f * ratio));
+        int h = Math.max(1, Math.round(ratio > 1.0f ? 32.0f / ratio : 32.0f));
+        int[] colors = new int[w * h];
+        int cx_stop = Math.max(lx, hasAlpha ? 5 : 3);
+        int cy_stop = Math.max(ly, hasAlpha ? 5 : 3);
+        float[] fx = new float[cx_stop];
+        float[] fy = new float[cy_stop];
+        for (int y = 0, i = 0; y < h; y++) {
+            for (int x = 0; x < w; x++, i++) {
+                float l = l_dc, p = p_dc, q = q_dc, a = a_dc;
+
+                // Precompute the coefficients
+                for (int cx = 0; cx < cx_stop; cx++)
+                    fx[cx] = (float) Math.cos(Math.PI / w * (x + 0.5f) * cx);
+                for (int cy = 0; cy < cy_stop; cy++)
+                    fy[cy] = (float) Math.cos(Math.PI / h * (y + 0.5f) * cy);
+
+                // Decode L
+                for (int cy = 0, j = 0; cy < ly; cy++) {
+                    float fy2 = fy[cy] * 2.0f;
+                    for (int cx = cy > 0 ? 0 : 1; cx * ly < lx * (ly - cy); cx++, j++)
+                        l += l_ac[j] * fx[cx] * fy2;
+                }
+
+                // Decode P and Q
+                for (int cy = 0, j = 0; cy < 3; cy++) {
+                    float fy2 = fy[cy] * 2.0f;
+                    for (int cx = cy > 0 ? 0 : 1; cx < 3 - cy; cx++, j++) {
+                        float f = fx[cx] * fy2;
+                        p += p_ac[j] * f;
+                        q += q_ac[j] * f;
+                    }
+                }
+
+                // Decode A
+                if (a_ac != null)
+                    for (int cy = 0, j = 0; cy < 5; cy++) {
+                        float fy2 = fy[cy] * 2.0f;
+                        for (int cx = cy > 0 ? 0 : 1; cx < 5 - cy; cx++, j++)
+                            a += a_ac[j] * fx[cx] * fy2;
+                    }
+
+                // Convert to RGB
+                float b = l - 2.0f / 3.0f * p;
+                float r = (3.0f * l - b + q) / 2.0f;
+                float g = r - q;
+                colors[i] = (channel(a) << 24) | (channel(r) << 16) | (channel(g) << 8) | channel(b);
+            }
+        }
+        size[0] = w;
+        size[1] = h;
+        return colors;
+    }
+
+    private static int channel(float value) {
+        return Math.max(0, Math.round(255.0f * Math.min(1, value)));
+    }
+
+    // How many AC factors a channel of nx × ny has.
+    private static int count(int nx, int ny) {
+        int n = 0;
+        for (int cy = 0; cy < ny; cy++)
+            for (int cx = cy > 0 ? 0 : 1; cx * ny < nx * (ny - cy); cx++)
+                n++;
+        return n;
+    }
+
+    private static float[] decode(byte[] hash, int start, int[] index, int nx, int ny, float scale) {
+        float[] ac = new float[count(nx, ny)];
+        for (int i = 0; i < ac.length; i++) {
+            int data = hash[start + (index[0] >> 1)] >> ((index[0] & 1) << 2);
+            ac[i] = ((float) (data & 15) / 7.5f - 1.0f) * scale;
+            index[0]++;
+        }
+        return ac;
+    }
+
+    private static float approximateAspectRatio(byte[] hash) {
+        byte header = hash[3];
+        boolean hasAlpha = (hash[2] & 0x80) != 0;
+        boolean isLandscape = (hash[4] & 0x80) != 0;
+        int lx = isLandscape ? hasAlpha ? 5 : 7 : header & 7;
+        int ly = isLandscape ? header & 7 : hasAlpha ? 5 : 7;
+        return ly == 0 ? 1 : (float) lx / (float) ly;
+    }
+}

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

@@ -145,7 +145,7 @@ class FastImageViewConverter {
                 .set(FastImageGlide.REQUEST, true)
                 .set(FastImageGlide.NO_STORE, noStore);
 
-        // imageSource is null when only a defaultSource is shown.
+        // imageSource is null when only the placeholder prop is shown.
         if (imageSource != null && imageSource.isResource()) {
             // Every local resource (drawable) in Android has its own unique numeric id, which are
             // generated at build time. Although these ids are unique, they are not guaranteed unique

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

@@ -7,9 +7,12 @@ import static com.fastimage.FastImageRequestListener.REACT_ON_LOAD_EVENT;
 import android.app.Activity;
 import android.content.Context;
 import android.content.ContextWrapper;
+import android.graphics.Bitmap;
 import android.graphics.PorterDuff;
 import android.util.Log;
 import android.graphics.Rect;
+import android.graphics.drawable.BitmapDrawable;
+import android.util.DisplayMetrics;
 
 import androidx.annotation.NonNull;
 
@@ -312,12 +315,19 @@ class FastImageViewManager extends SimpleViewManager<FastImageViewWithUrl>
         view.setSources(sources.isNull() ? null : sources.asArray());
     }
 
-    // The resolved asset's uri.
+    // The `placeholder` prop: the resolved asset's uri, or a data uri.
     @Override
-    public void setDefaultSource(FastImageViewWithUrl view, Dynamic source) {
-        view.setDefaultSource(
-                ResourceDrawableIdHelper.getResourceDrawable(
-                        view.getContext(), source.isNull() ? null : source.asString()));
+    public void setPlaceholder(FastImageViewWithUrl view, Dynamic source) {
+        String uri = source.isNull() ? null : source.asString();
+        if (uri != null && FastImageThumbHash.isDataUri(uri)) {
+            Bitmap bitmap = FastImageThumbHash.dataUri(uri);
+            // One pixel per dp, as on iOS and the web (decoded, it's at the
+            // screen's density: one pixel per pixel).
+            if (bitmap != null) bitmap.setDensity(DisplayMetrics.DENSITY_DEFAULT);
+            view.setPlaceholder(bitmap == null ? null : new BitmapDrawable(view.getResources(), bitmap));
+        } else {
+            view.setPlaceholder(ResourceDrawableIdHelper.getResourceDrawable(view.getContext(), uri));
+        }
     }
 
     @Override
@@ -334,6 +344,11 @@ class FastImageViewManager extends SimpleViewManager<FastImageViewWithUrl>
         view.setRecyclingKey(recyclingKey);
     }
 
+    @Override
+    public void setSourcePlaceholders(FastImageViewWithUrl view, @Nullable ReadableArray placeholders) {
+        view.setSourcePlaceholders(placeholders);
+    }
+
     @Override
     public void setLoopCount(FastImageViewWithUrl view, int loopCount) {
         view.setLoopCount(loopCount);