react-native-fast-image 10.1.1 → 10.3.0

package/ios/FastImage/FFFThumbHash.m

@@ -0,0 +1,269 @@
+#import "FFFThumbHash.h"
+#import "FFFBoxBlur.h"
+#include <math.h>
+
+// FFFThumbHashToRGBA is Evan Wallace's reference decoder
+// (https://github.com/evanw/thumbhash, thumbHashToRGBA in java/ and js/) in C,
+// 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.
+
+// How many AC factors a channel of nx × ny has.
+static int FFFThumbHashCount(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;
+}
+
+static void FFFThumbHashDecodeChannel(const uint8_t* hash, int start, int* index, int nx, int ny, float scale, float* ac) {
+    int n = FFFThumbHashCount(nx, ny);
+    for (int i = 0; i < n; i++) {
+        int data = hash[start + (*index >> 1)] >> ((*index & 1) << 2);
+        ac[i] = ((float) (data & 15) / 7.5f - 1.0f) * scale;
+        (*index)++;
+    }
+}
+
+static uint8_t FFFThumbHashChannel(float value) {
+    return (uint8_t) fmaxf(0, roundf(255.0f * fminf(1, value)));
+}
+
+// The hash decoded as unpremultiplied RGBA (malloc'd, the caller frees it),
+// with its width and height, or NULL if it's too short.
+static uint8_t* FFFThumbHashToRGBA(const uint8_t* hash, NSUInteger length, int* width, int* height) {
+    if (length < 5) {
+        return NULL;
+    }
+    // Read the constants
+    int header24 = hash[0] | (hash[1] << 8) | (hash[2] << 16);
+    int header16 = hash[3] | (hash[4] << 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;
+    BOOL hasAlpha = (header24 >> 23) != 0;
+    float p_scale = (float) ((header16 >> 3) & 63) / 63.0f;
+    float q_scale = (float) ((header16 >> 9) & 63) / 63.0f;
+    BOOL isLandscape = (header16 >> 15) != 0;
+    int lx = MAX(3, isLandscape ? (hasAlpha ? 5 : 7) : header16 & 7);
+    int ly = MAX(3, isLandscape ? header16 & 7 : (hasAlpha ? 5 : 7));
+    int ac_start = hasAlpha ? 6 : 5;
+    int l_count = FFFThumbHashCount(lx, ly);
+    int pq_count = FFFThumbHashCount(3, 3);
+    int a_count = hasAlpha ? FFFThumbHashCount(5, 5) : 0;
+    if (length < (NSUInteger) (ac_start + (l_count + 2 * pq_count + a_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)
+    float l_ac[64], p_ac[16], q_ac[16], a_ac[32];
+    int ac_index = 0;
+    FFFThumbHashDecodeChannel(hash, ac_start, &ac_index, lx, ly, l_scale, l_ac);
+    FFFThumbHashDecodeChannel(hash, ac_start, &ac_index, 3, 3, p_scale * 1.25f, p_ac);
+    FFFThumbHashDecodeChannel(hash, ac_start, &ac_index, 3, 3, q_scale * 1.25f, q_ac);
+    if (hasAlpha) {
+        FFFThumbHashDecodeChannel(hash, ac_start, &ac_index, 5, 5, a_scale, a_ac);
+    }
+
+    // Decode using the DCT into RGB
+    int ratio_lx = isLandscape ? (hasAlpha ? 5 : 7) : header16 & 7;
+    int ratio_ly = isLandscape ? header16 & 7 : (hasAlpha ? 5 : 7);
+    float ratio = ratio_ly > 0 ? (float) ratio_lx / (float) ratio_ly : 1;
+    int w = MAX(1, (int) roundf(ratio > 1.0f ? 32.0f : 32.0f * ratio));
+    int h = MAX(1, (int) roundf(ratio > 1.0f ? 32.0f / ratio : 32.0f));
+    uint8_t* rgba = malloc((size_t) w * h * 4);
+    if (!rgba) {
+        return NULL;
+    }
+    int cx_stop = MAX(lx, hasAlpha ? 5 : 3);
+    int cy_stop = MAX(ly, hasAlpha ? 5 : 3);
+    float fx[8], fy[8];
+    for (int y = 0, i = 0; y < h; y++) {
+        for (int x = 0; x < w; x++, i += 4) {
+            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) cos(M_PI / w * (x + 0.5f) * cx);
+            for (int cy = 0; cy < cy_stop; cy++)
+                fy[cy] = (float) cos(M_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 (hasAlpha)
+                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;
+            rgba[i] = FFFThumbHashChannel(r);
+            rgba[i + 1] = FFFThumbHashChannel(g);
+            rgba[i + 2] = FFFThumbHashChannel(b);
+            rgba[i + 3] = FFFThumbHashChannel(a);
+        }
+    }
+    *width = w;
+    *height = h;
+    return rgba;
+}
+
+// A blurDataUri's image 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: a box blur three times each way
+// (about a Gaussian), on premultiplied colors, the edges extended outwards.
+static UIImage* FFFBlurredPreview(UIImage* image) {
+    CGImageRef source = image.CGImage;
+    if (!source) {
+        return nil;
+    }
+    size_t width = CGImageGetWidth(source), height = CGImageGetHeight(source);
+    if (width == 0 || height == 0) {
+        return nil;
+    }
+    float scale = 32.0f / MAX(width, height);
+    int w = MAX(1, (int) lroundf(width * scale)), h = MAX(1, (int) lroundf(height * scale));
+    int radius = MAX(1, (int) lroundf(scale / 2));
+    CGColorSpaceRef colorSpace = CGColorSpaceCreateWithName(kCGColorSpaceSRGB);
+    CGContextRef context = CGBitmapContextCreate(NULL, w, h, 8, w * 4, colorSpace,
+                                                 kCGImageAlphaPremultipliedLast | kCGBitmapByteOrder32Big);
+    CGColorSpaceRelease(colorSpace);
+    if (!context) {
+        return nil;
+    }
+    CGContextSetInterpolationQuality(context, kCGInterpolationHigh);
+    CGContextDrawImage(context, CGRectMake(0, 0, w, h), source);
+    FFFBoxBlur(context, 2 * radius + 1);
+    CGImageRef blurred = CGBitmapContextCreateImage(context);
+    CGContextRelease(context);
+    if (!blurred) {
+        return nil;
+    }
+    UIImage* result = [UIImage imageWithCGImage: blurred scale: 1 orientation: UIImageOrientationUp];
+    CGImageRelease(blurred);
+    return result;
+}
+
+@implementation FFFThumbHash
+
++ (NSCache<NSString*, UIImage*>*) cache {
+    static NSCache* cache;
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+        cache = [NSCache new];
+        // Recent placeholders, at most 4 KB each.
+        cache.countLimit = 256;
+    });
+    return cache;
+}
+
++ (UIImage*) imageForPlaceholder: (NSString*)placeholder {
+    if ([placeholder rangeOfString: @"data:" options: NSCaseInsensitiveSearch | NSAnchoredSearch].location == NSNotFound) {
+        return [self imageForThumbHash: placeholder];
+    }
+    UIImage* cached = [[self cache] objectForKey: placeholder];
+    if (cached) {
+        return cached;
+    }
+    NSURL* url = [NSURL URLWithString: placeholder];
+    NSData* data = url ? [NSData dataWithContentsOfURL: url] : nil;
+    UIImage* decoded = data ? [UIImage imageWithData: data scale: 1] : nil;
+    UIImage* image = decoded ? FFFBlurredPreview(decoded) : nil;
+    if (image) {
+        [[self cache] setObject: image forKey: placeholder];
+    }
+    return image;
+}
+
++ (UIImage*) imageForThumbHash: (NSString*)thumbhash {
+    if (thumbhash.length == 0) {
+        return nil;
+    }
+    UIImage* cached = [[self cache] objectForKey: thumbhash];
+    if (cached) {
+        return cached;
+    }
+    NSMutableString* base64 = [[thumbhash stringByTrimmingCharactersInSet: [NSCharacterSet whitespaceAndNewlineCharacterSet]] mutableCopy];
+    [base64 replaceOccurrencesOfString: @"-" withString: @"+" options: 0 range: NSMakeRange(0, base64.length)];
+    [base64 replaceOccurrencesOfString: @"_" withString: @"/" options: 0 range: NSMakeRange(0, base64.length)];
+    while (base64.length % 4 != 0) {
+        [base64 appendString: @"="];
+    }
+    NSData* hash = [[NSData alloc] initWithBase64EncodedString: base64 options: 0];
+    if (!hash) {
+        return nil;
+    }
+    int width = 0, height = 0;
+    uint8_t* rgba = FFFThumbHashToRGBA(hash.bytes, hash.length, &width, &height);
+    if (!rgba) {
+        return nil;
+    }
+    // Premultiplied, as Core Graphics draws it.
+    for (int i = 0; i < width * height * 4; i += 4) {
+        int alpha = rgba[i + 3];
+        rgba[i] = (uint8_t) ((rgba[i] * alpha + 127) / 255);
+        rgba[i + 1] = (uint8_t) ((rgba[i + 1] * alpha + 127) / 255);
+        rgba[i + 2] = (uint8_t) ((rgba[i + 2] * alpha + 127) / 255);
+    }
+    CGColorSpaceRef colorSpace = CGColorSpaceCreateWithName(kCGColorSpaceSRGB);
+    CGContextRef context = CGBitmapContextCreate(rgba, width, height, 8, width * 4, colorSpace,
+                                                 kCGImageAlphaPremultipliedLast | kCGBitmapByteOrder32Big);
+    CGImageRef cgImage = context ? CGBitmapContextCreateImage(context) : NULL;
+    if (context) {
+        CGContextRelease(context);
+    }
+    CGColorSpaceRelease(colorSpace);
+    free(rgba);
+    if (!cgImage) {
+        return nil;
+    }
+    UIImage* image = [UIImage imageWithCGImage: cgImage scale: 1 orientation: UIImageOrientationUp];
+    CGImageRelease(cgImage);
+    [[self cache] setObject: image forKey: thumbhash];
+    return image;
+}
+
+@end

package/ios/FastImage/FFFastImageView.h

@@ -32,7 +32,13 @@ typedef NS_ENUM(NSInteger, FFFObjectFit) {
 // Several sources (2 or more) of the same image at different sizes: the view
 // loads the one whose size is closest to its own.
 @property (nonatomic, copy) NSArray<FFFastImageSource *> *sources;
-@property (nonatomic, strong) UIImage *defaultSource;
+// The `placeholder` prop.
+@property (nonatomic, strong) UIImage *placeholder;
+// The `sourcePlaceholders` prop, by the source's index (an empty string for
+// none; one for a single source): the picked source's ThumbHash or
+// blurDataUri (a data uri) shows instead of placeholder. JS sends them apart
+// from the sources, so a new one for the same image doesn't load it again.
+@property (nonatomic, copy) NSArray<NSString *> *sourcePlaceholders;
 @property (nonatomic, strong) UIColor *imageColor;
 // When it changes, the next image doesn't replace the current one: the view
 // clears first (for views reused for other content, like list rows).

package/ios/FastImage/FFFastImageView.m

@@ -5,7 +5,8 @@
 #import <SDWebImage/SDWebImageError.h>
 #import <SDWebImage/SDImageTransformer.h>
 #import "FFFDownsampledImage.h"
-#import <Accelerate/Accelerate.h>
+#import "FFFThumbHash.h"
+#import "FFFBoxBlur.h"
 
 @interface FFFastImageView ()
 
@@ -28,15 +29,16 @@
 // The image being blurred fades in once it's blurred (transition).
 @property(nonatomic, assign) BOOL fadesBlurredImage;
 // The image being blurred is the first loaded one the view shows: until it's
-// blurred, the view shows no loaded image (nothing, or defaultSource).
+// blurred, the view shows no loaded image (nothing, or the placeholder prop).
 @property(nonatomic, assign) BOOL blursOverNothing;
 // Whether the current load was already restarted after the app came back
 // from the background (see downloadImage:).
 @property(nonatomic, assign) BOOL retriedAfterBackground;
 // Waits for the app to be active again, to restart a load.
 @property(nonatomic, strong) id activeObserver;
-// Whether the view shows an image that loaded (not defaultSource or nothing).
-// A new source then keeps it until the new image has loaded (see reloadImage).
+// Whether the view shows an image that loaded (not the placeholder prop or
+// nothing). A new source then keeps it until the new image has loaded (see
+// reloadImage).
 @property(nonatomic, assign) BOOL showsLoadedImage;
 // downsample, or several sources: a load waits for the view's size (see
 // didSetProps).
@@ -62,6 +64,15 @@
 // The view's own mask, which clips it to the box while it's moved, when React
 // Native gives it none (the view doesn't clip: overflow visible).
 @property(nonatomic, strong) CALayer* ownMask;
+// The picked source's placeholder (its ThumbHash or blurDataUri) decoded, and
+// the string, or nil: it shows instead of the placeholder prop (see
+// shownPlaceholder).
+@property(nonatomic, strong) UIImage* hashImage;
+@property(nonatomic, copy) NSString* hashImageKey;
+// Whether the view shows its placeholder (the placeholder prop or the
+// source's), and whether that's the source's (hashImage).
+@property(nonatomic, assign) BOOL showsPlaceholder;
+@property(nonatomic, assign) BOOL showsHash;
 
 @end
 
@@ -266,12 +277,14 @@ static UIImage* FFFBlurredImage(UIImage* image, CGFloat scale, CGFloat radius, B
             contentMode = UIViewContentModeScaleToFill;
             break;
         case FFFObjectFitNone:
-            contentMode = UIViewContentModeCenter;
+            // A source's placeholder stands for an image whose size isn't
+            // known yet: as with contain, here and for scale-down.
+            contentMode = self.showsHash ? UIViewContentModeScaleAspectFit : UIViewContentModeCenter;
             break;
         case FFFObjectFitScaleDown: {
             CGSize imageSize = super.image.size;
             CGSize viewSize = self.bounds.size;
-            contentMode = imageSize.width > viewSize.width || imageSize.height > viewSize.height
+            contentMode = self.showsHash || imageSize.width > viewSize.width || imageSize.height > viewSize.height
                 ? UIViewContentModeScaleAspectFit
                 : UIViewContentModeCenter;
             break;
@@ -427,6 +440,13 @@ static UIImage* FFFBlurredImage(UIImage* image, CGFloat scale, CGFloat radius, B
 
 - (void) setImage: (UIImage*)image {
     self.imageCount++;
+    self.showsHash = image != nil && image == self.hashImage;
+    self.showsPlaceholder = self.showsHash || (image != nil && image == _placeholder);
+    if ([_imageRendering isEqualToString: @"pixelated"]) {
+        // A source's placeholder is a blurred preview, scaled up smoothly
+        // (pixelated is for the image).
+        self.layer.magnificationFilter = self.showsHash ? kCAFilterLinear : kCAFilterNearest;
+    }
     if ([self blurs: image]) {
         self.originalImage = image;
         self.blurredImage = nil;
@@ -513,10 +533,10 @@ static UIImage* FFFBlurredImage(UIImage* image, CGFloat scale, CGFloat radius, B
     }
 }
 
-// Whether the image is blurred: a loaded image, not defaultSource (as with
-// React Native's Image, and on Android).
+// Whether the image is blurred: a loaded image, not the placeholder prop (as
+// with React Native's Image, and on Android).
 - (BOOL) blurs: (UIImage*)image {
-    return _blurRadius > 0 && image && image != _defaultSource;
+    return _blurRadius > 0 && image && image != _placeholder && image != self.hashImage;
 }
 
 // Blurs the image off the main thread, and shows it (tinted as any image) unless
@@ -649,27 +669,7 @@ static UIImage* FFFBlurredImage(UIImage* image, CGFloat scale, CGFloat radius, B
     [image drawInRect: CGRectMake(0, 0, width, height)];
     UIGraphicsPopContext();
 
-    if (boxSize > 1) {
-        vImage_Buffer buffer = {
-            .data = CGBitmapContextGetData(context),
-            .height = height,
-            .width = width,
-            .rowBytes = CGBitmapContextGetBytesPerRow(context),
-        };
-        vImage_Buffer other = buffer;
-        other.data = malloc(buffer.rowBytes * height);
-        vImage_Error tempSize = vImageBoxConvolve_ARGB8888(&buffer, &other, NULL, 0, 0, boxSize, boxSize, NULL,
-                                                           kvImageGetTempBufferSize | kvImageEdgeExtend);
-        void* temp = tempSize > 0 ? malloc(tempSize) : NULL;
-        if (other.data && temp) {
-            vImageBoxConvolve_ARGB8888(&buffer, &other, temp, 0, 0, boxSize, boxSize, NULL, kvImageEdgeExtend);
-            vImageBoxConvolve_ARGB8888(&other, &buffer, temp, 0, 0, boxSize, boxSize, NULL, kvImageEdgeExtend);
-            vImageBoxConvolve_ARGB8888(&buffer, &other, temp, 0, 0, boxSize, boxSize, NULL, kvImageEdgeExtend);
-            memcpy(buffer.data, other.data, buffer.rowBytes * height);
-        }
-        free(other.data);
-        free(temp);
-    }
+    FFFBoxBlur(context, boxSize);
 
     CGImageRef cgImage = CGBitmapContextCreateImage(context);
     CGContextRelease(context);
@@ -798,13 +798,51 @@ NSString *FFFErrorMessage(NSError *error)
     }
 }
 
-- (void) setDefaultSource: (UIImage*)defaultSource {
-    if (_defaultSource != defaultSource) {
-        _defaultSource = defaultSource;
+- (void) setPlaceholder: (UIImage*)placeholder {
+    if (_placeholder != placeholder) {
+        _placeholder = placeholder;
         _needsReload = YES;
     }
 }
 
+- (void) setSourcePlaceholders: (NSArray<NSString*>*)sourcePlaceholders {
+    _sourcePlaceholders = [sourcePlaceholders copy];
+    [self updateHashImage];
+}
+
+// What shows while the image loads and if it fails: the picked source's
+// placeholder (its ThumbHash or blurDataUri), or the placeholder prop.
+- (UIImage*) shownPlaceholder {
+    return self.hashImage ?: _placeholder;
+}
+
+// The picked source's ThumbHash or blurDataUri, or nil.
+- (NSString*) pickedSourcePlaceholder {
+    NSUInteger index = 0;
+    if ([self picksSource]) {
+        index = _source ? [_sources indexOfObjectIdenticalTo: _source] : NSNotFound;
+    }
+    NSString* hash = index < _sourcePlaceholders.count ? _sourcePlaceholders[index] : nil;
+    return hash.length > 0 ? hash : nil;
+}
+
+// Decodes the picked source's placeholder. A view showing the previous
+// placeholder shows the new one at once, without loading the image again.
+- (void) updateHashImage {
+    NSString* hash = [self pickedSourcePlaceholder];
+    if (hash == self.hashImageKey || [hash isEqualToString: self.hashImageKey]) {
+        return;
+    }
+    UIImage* previous = [self shownPlaceholder];
+    BOOL showing = self.showsPlaceholder;
+    self.hashImageKey = hash;
+    self.hashImage = [FFFThumbHash imageForPlaceholder: hash];
+    UIImage* placeholder = [self shownPlaceholder];
+    if (showing && placeholder != previous) {
+        [self setImage: placeholder];
+    }
+}
+
 - (void) didSetProps {
     if (_needsReload) {
         // With downsample on, the image is decoded for the view's size, and
@@ -906,6 +944,7 @@ NSString *FFFErrorMessage(NSError *error)
     if ([self picksSource]) {
         _source = [self sourceForSize];
     }
+    [self updateHashImage];
     self.decodedBox = CGSizeZero;
     // The previous load, if it's still running, is for a source the view no
     // longer shows: cancel it (a new download would, but a data uri or no
@@ -924,8 +963,9 @@ NSString *FFFErrorMessage(NSError *error)
             // Use SDWebImage API to support external format like WebP images
             UIImage* image = [UIImage sd_imageWithData: [NSData dataWithContentsOfURL: _source.url]];
             if (!image) {
-                // Not decodable: fail like a remote image, showing defaultSource.
-                [self setImage: _defaultSource];
+                // Not decodable: fail like a remote image, showing the
+                // placeholder.
+                [self setImage: [self shownPlaceholder]];
                 self.showsLoadedImage = NO;
                 [self sendOnError: @"Failed to decode the image"];
                 if (self.onFastImageLoadEnd) {
@@ -954,9 +994,10 @@ NSString *FFFErrorMessage(NSError *error)
         SDWebImageOptions options = [self loadOptions];
 
         // Keep showing the loaded image until the new one has loaded, instead
-        // of clearing it to defaultSource (or nothing) while it loads, which
-        // flashed (#747). defaultSource shows if the new image fails. As React
-        // Native's Image does; a `key` that changes starts from blank instead.
+        // of clearing it to the placeholder prop (or nothing) while it loads,
+        // which flashed (#747). The placeholder prop shows if the new image
+        // fails. As React Native's Image does; a `key` that changes starts from
+        // blank instead.
         if (self.showsLoadedImage) {
             options |= SDWebImageDelayPlaceholder;
         }
@@ -970,8 +1011,8 @@ NSString *FFFErrorMessage(NSError *error)
         [self stopWaitingForActive];
 
         [self downloadImage: _source options: options context: [self loadContext] events: YES];
-    } else if (_defaultSource) {
-        [self setImage: _defaultSource];
+    } else if ([self shownPlaceholder]) {
+        [self setImage: [self shownPlaceholder]];
         self.showsLoadedImage = NO;
     }
 }
@@ -1003,8 +1044,8 @@ NSString *FFFErrorMessage(NSError *error)
 }
 
 // Whether the view loads as it's laid out, so its image shows in this frame:
-// one in the memory cache, where SDWebImage finds it as the load starts, or
-// one that isn't downloaded (no source, which shows defaultSource, or a data
+// one in the memory cache, where SDWebImage finds it as the load starts, or one
+// that isn't downloaded (no source, which shows the placeholder prop, or a data
 // uri). Also when that can't be told (an app's own image cache), as before.
 - (BOOL) loadsDuringLayout {
     FFFastImageSource* source = [self picksSource] ? [self sourceForSize] : _source;
@@ -1143,13 +1184,13 @@ NSString *FFFErrorMessage(NSError *error)
     // class to SDAnimatedImage (loadContext sets it). Only while this is the
     // current load: SDWebImage sets the placeholder when a load it cancelled
     // completes, which could replace a newer image.
-    UIImage* placeholder = _defaultSource;
+    UIImage* placeholder = [self shownPlaceholder];
     SDSetImageBlock setImage = ^(UIImage* _Nullable image, NSData* _Nullable data, SDImageCacheType cacheType, NSURL* _Nullable imageURL) {
         if (weakSelf.loadCount != load) {
             return;
         }
-        // The loaded image, not defaultSource (shown while it loads, or if it
-        // fails).
+        // The loaded image, not the placeholder prop (shown while it loads, or
+        // if it fails).
         BOOL loaded = image && image != placeholder;
         [weakSelf showLoadedImage: image fade: loaded && [weakSelf fadesImageFromCache: cacheType]];
     };
@@ -1194,7 +1235,13 @@ NSString *FFFErrorMessage(NSError *error)
                     return;
                 }
                 if (error) {
-                    // SDWebImage shows the placeholder (defaultSource or nothing).
+                    // SDWebImage shows the placeholder the load started with
+                    // (the placeholder prop, a source's, or nothing): the
+                    // current one if the source's changed since.
+                    UIImage* current = [weakSelf shownPlaceholder];
+                    if (current != placeholder) {
+                        [weakSelf setImage: current];
+                    }
                     weakSelf.showsLoadedImage = NO;
                     [weakSelf sendOnError: [source errorMessage: error]];
                     if (weakSelf.onFastImageLoadEnd) {

package/ios/FastImage/FFFastImageViewComponentView.mm

@@ -95,7 +95,7 @@ static folly::dynamic FFFDynamicFromObject(id value)
     return nullptr;
 }
 
-// A prop of any type (a source, sources, defaultSource) as JSON: nil when
+// A prop of any type (a source, sources, placeholder) as JSON: nil when
 // it's null (not set).
 static id _Nullable FFFJSON(const folly::dynamic &value)
 {
@@ -232,9 +232,16 @@ typedef NS_OPTIONS(int32_t, FFFEvent) {
         id sources = FFFJSON(newViewProps.sources);
         view.sources = sources ? [RCTConvert FFFastImageSourceArray:sources] : nil;
     }
-    if (all || oldViewProps.defaultSource != newViewProps.defaultSource) {
-        id defaultSource = FFFJSON(newViewProps.defaultSource);
-        view.defaultSource = defaultSource ? [RCTConvert UIImage:defaultSource] : nil;
+    if (all || oldViewProps.placeholder != newViewProps.placeholder) {
+        id placeholder = FFFJSON(newViewProps.placeholder);
+        view.placeholder = placeholder ? [RCTConvert UIImage:placeholder] : nil;
+    }
+    if (all || oldViewProps.sourcePlaceholders != newViewProps.sourcePlaceholders) {
+        NSMutableArray<NSString *> *placeholders = [NSMutableArray arrayWithCapacity:newViewProps.sourcePlaceholders.size()];
+        for (const auto &placeholder : newViewProps.sourcePlaceholders) {
+            [placeholders addObject:[NSString stringWithUTF8String:placeholder.c_str()]];
+        }
+        view.sourcePlaceholders = placeholders.count > 0 ? placeholders : nil;
     }
     if (all || oldViewProps.objectFit != newViewProps.objectFit) {
         view.objectFit = [RCTConvert FFFObjectFit:FFFString(newViewProps.objectFit)];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "react-native-fast-image",
-    "version": "10.1.1",
+    "version": "10.3.0",
     "description": "FastImage, performant React Native image component.",
     "keywords": [
         "cache",
@@ -32,9 +32,11 @@
         "app.plugin.js",
         "src",
         "!src/**/*.test.tsx",
+        "!src/**/*.test.ts",
         "!src/__snapshots__",
         "dist",
-        "RNFastImage.podspec"
+        "RNFastImage.podspec",
+        "thumbhash"
     ],
     "scripts": {
         "build": "bun run build:package && bun run build:docs",

package/src/index.js.flow

@@ -110,6 +110,11 @@ export type PreloadResult = PreloadSuccess | PreloadFailure
 export type PreloadFn = (
     sources: Array<FastImageSource>,
 ) => Promise<Array<PreloadResult>>
+export type SourcePlaceholder = {
+    thumbhash?: string,
+    blurDataUri?: string,
+}
+
 export type FastImageSource = {
     uri?: string,
     headers?: Object,
@@ -118,6 +123,8 @@ export type FastImageSource = {
     cacheKey?: string,
     memoryCache?: boolean,
     diskCache?: boolean,
+    thumbhash?: string,
+    blurDataUri?: string,
     width?: number,
     height?: number,
     scale?: number,
@@ -132,6 +139,8 @@ export type FastImageProps = $ReadOnly<{|
     onProgress?: ?(event: OnProgressEvent) => void,
 
     source?: ?(FastImageSource | Array<FastImageSource> | number),
+    placeholder?: ?(number | string | SourcePlaceholder),
+    // Deprecated: use placeholder, which is the same.
     defaultSource?: ?number,
 
     tintColor?: number | string,
@@ -140,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,