react-native-fast-image 8.21.0 → 8.22.0

package/README.md

@@ -212,6 +212,27 @@ Pauses an animated image (GIF, and animated WebP on iOS) on the frame it's showi
 
 ---
 
+### `transition?: boolean | number | Transition`
+
+Fades the image in when it loads. Off by default. `true` uses the platform's usual fade, a number is the duration in milliseconds, or pass an object:
+
+- `duration`: milliseconds; 0 is no fade. Defaults to the platform's usual length: 300 ms on Android, 250 ms on iOS.
+- `betweenImages` (default `false`): also fade between images. By default an image fades in when it appears over nothing (or over `defaultSource`), and a new `source` replaces the image that's showing at once, once it has loaded. With `true`, the new image cross-dissolves from the one showing (for a gallery or an avatar that changes, say).
+- `skipOnCacheHit`: which images show at once, without the fade:
+    - `'memory'` (default): images from the memory cache, so a list scrolled back up shows images it already loaded at once. Images from the disk cache fade in.
+    - `'all'`: images from the memory or disk cache: images that download fade in, and local files and bundled images usually only the first time they load (the disk cache usually keeps them too).
+    - `'none'`: every image fades in.
+
+Downloads, local files (`file://`, `content://`) and bundled images (`require()`) fade in. In lists that reuse views (e.g. FlashList), set `recyclingKey`, so a reused view starts empty and its image fades in, instead of showing the previous item's image until it loads.
+
+```jsx
+<FastImage source={{ uri }} transition />
+<FastImage source={{ uri }} transition={500} />
+<FastImage source={{ uri }} transition={{ betweenImages: true, skipOnCacheHit: 'none' }} />
+```
+
+---
+
 ### `downsample?: boolean`
 
 iOS only. Decodes a large image at about the size it's shown at, instead of at full size, so it takes much less memory.

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

@@ -105,6 +105,21 @@ class FastImageViewManager extends SimpleViewManager<FastImageViewWithUrl> imple
         view.setBlurRadius(PixelUtil.toPixelFromDIP(blurRadius));
     }
 
+    @ReactProp(name = "transitionDuration")
+    public void setTransitionDuration(FastImageViewWithUrl view, int transitionDuration) {
+        view.setTransitionDuration(transitionDuration);
+    }
+
+    @ReactProp(name = "transitionBetweenImages")
+    public void setTransitionBetweenImages(FastImageViewWithUrl view, boolean betweenImages) {
+        view.setTransitionBetweenImages(betweenImages);
+    }
+
+    @ReactProp(name = "transitionSkipOnCacheHit")
+    public void setTransitionSkipOnCacheHit(FastImageViewWithUrl view, @Nullable String skipOnCacheHit) {
+        view.setTransitionSkipOnCacheHit(skipOnCacheHit);
+    }
+
     @ReactProp(name = "paused")
     public void setPaused(FastImageViewWithUrl view, boolean paused) {
         view.setPaused(paused);

package/android/src/main/java/com/dylanvann/fastimage/FastImageViewWithUrl.java

@@ -2,9 +2,16 @@ package com.dylanvann.fastimage;
 
 import static com.dylanvann.fastimage.FastImageRequestListener.REACT_ON_ERROR_EVENT;
 
+import android.animation.Animator;
+import android.animation.AnimatorListenerAdapter;
+import android.animation.ValueAnimator;
 import android.annotation.SuppressLint;
 import android.content.Context;
 import android.graphics.Bitmap;
+import android.graphics.Canvas;
+import android.graphics.Paint;
+import android.graphics.PorterDuff;
+import android.graphics.PorterDuffXfermode;
 import android.graphics.drawable.BitmapDrawable;
 import android.graphics.drawable.Drawable;
 
@@ -13,15 +20,20 @@ import androidx.annotation.Nullable;
 import androidx.appcompat.widget.AppCompatImageView;
 import androidx.core.view.ViewCompat;
 
+import com.bumptech.glide.GenericTransitionOptions;
 import com.bumptech.glide.RequestBuilder;
 import com.bumptech.glide.RequestManager;
+import com.bumptech.glide.load.DataSource;
 import com.bumptech.glide.load.model.GlideUrl;
 import com.bumptech.glide.load.resource.bitmap.DownsampleStrategy;
+import com.bumptech.glide.load.resource.drawable.DrawableTransitionOptions;
 import com.bumptech.glide.load.resource.gif.GifDrawable;
 import com.bumptech.glide.request.RequestOptions;
 import com.bumptech.glide.request.target.DrawableImageViewTarget;
 import com.bumptech.glide.request.target.SizeReadyCallback;
+import com.bumptech.glide.request.transition.NoTransition;
 import com.bumptech.glide.request.transition.Transition;
+import com.bumptech.glide.request.transition.TransitionFactory;
 import com.facebook.react.bridge.ReadableMap;
 import com.facebook.react.bridge.WritableMap;
 import com.facebook.react.bridge.WritableNativeMap;
@@ -88,6 +100,168 @@ class FastImageViewWithUrl extends AppCompatImageView {
     // Pauses GIFs on the frame they're showing (the view's own animation).
     private boolean mPaused = false;
 
+    // The `transition` prop (from the next load): how long a loaded image
+    // takes to fade in, in milliseconds (0 for no fade), whether it also fades
+    // over a loaded image (a new source), and which cache hits show at once
+    // (none, memory or all).
+    private int mTransitionDuration = 0;
+    private boolean mTransitionBetweenImages = false;
+    private String mTransitionSkipOnCacheHit = "memory";
+
+    public void setTransitionDuration(int transitionDuration) {
+        mTransitionDuration = Math.max(0, transitionDuration);
+    }
+
+    public void setTransitionBetweenImages(boolean betweenImages) {
+        mTransitionBetweenImages = betweenImages;
+    }
+
+    public void setTransitionSkipOnCacheHit(@Nullable String skipOnCacheHit) {
+        mTransitionSkipOnCacheHit = skipOnCacheHit == null ? "memory" : skipOnCacheHit;
+    }
+
+    // Fades a loaded image in, unless it's from a cache that skipOnCacheHit
+    // skips, as Glide's and Coil's cross-fades and Fresco decide: from the
+    // memory cache it shows at once (by default), and from the disk cache
+    // too with 'all'. Downloads, local files and bundled images fade.
+    private final class FadeFactory implements TransitionFactory<Drawable> {
+        private final int duration;
+        private final String skipOnCacheHit;
+
+        FadeFactory(int duration, String skipOnCacheHit) {
+            this.duration = duration;
+            this.skipOnCacheHit = skipOnCacheHit;
+        }
+
+        @Override
+        public Transition<Drawable> build(DataSource dataSource, boolean isFirstResource) {
+            if (skips(dataSource)) return NoTransition.get();
+            return new Transition<Drawable>() {
+                @Override
+                public boolean transition(Drawable current, ViewAdapter adapter) {
+                    startFade(duration);
+                    // The target shows the image as usual.
+                    return false;
+                }
+            };
+        }
+
+        private boolean skips(DataSource dataSource) {
+            if (skipOnCacheHit.equals("none")) return false;
+            if (dataSource == DataSource.MEMORY_CACHE) return true;
+            // Glide also keeps a local file's or bundled image's decoded
+            // image in its disk cache (at the size it was decoded at, and not
+            // for GIFs), so with 'all' they usually only fade the first time.
+            boolean disk = dataSource == DataSource.DATA_DISK_CACHE || dataSource == DataSource.RESOURCE_DISK_CACHE;
+            return disk && skipOnCacheHit.equals("all");
+        }
+    }
+
+    // A fade in progress: what the view showed (null if nothing), drawn
+    // fading out while the view's image fades in, as a cross-dissolve on iOS.
+    // Drawn here rather than with Glide's DrawableCrossFadeTransition, whose
+    // TransitionDrawable stretches both images to one size and stays in the
+    // view after the fade, still drawing (and animating) the previous image.
+    @Nullable
+    private ValueAnimator mFade;
+    @Nullable
+    private Bitmap mFadeFrom;
+    private float mFadeProgress = 1f;
+    private final Paint mFadeFromPaint = new Paint(Paint.FILTER_BITMAP_FLAG);
+    private final Paint mFadeInPaint = new Paint();
+
+    {
+        // The two add up to a cross-dissolve: from * (1 - t) + image * t.
+        mFadeInPaint.setXfermode(new PorterDuffXfermode(PorterDuff.Mode.ADD));
+    }
+
+    private void startFade(int duration) {
+        int width = getWidth();
+        int height = getHeight();
+        if (width <= 0 || height <= 0) return;
+        // What the view shows now, including a fade in progress.
+        Bitmap from = null;
+        if (getDrawable() != null) {
+            try {
+                from = Bitmap.createBitmap(width, height, Bitmap.Config.ARGB_8888);
+                onDraw(new Canvas(from));
+            } catch (OutOfMemoryError | RuntimeException e) {
+                // Out of memory, or a hardware bitmap (Android 8+; an app's
+                // Glide module can enable them), which a software canvas
+                // can't draw: fade in over nothing instead.
+                if (from != null) from.recycle();
+                from = null;
+            }
+        }
+        endFade();
+        mFadeFrom = from;
+        mFadeProgress = 0f;
+        final ValueAnimator fade = ValueAnimator.ofFloat(0f, 1f);
+        fade.setDuration(duration);
+        fade.addUpdateListener(new ValueAnimator.AnimatorUpdateListener() {
+            @Override
+            public void onAnimationUpdate(ValueAnimator animation) {
+                mFadeProgress = (float) animation.getAnimatedValue();
+                invalidate();
+            }
+        });
+        fade.addListener(new AnimatorListenerAdapter() {
+            @Override
+            public void onAnimationEnd(Animator animation) {
+                if (mFade == fade) endFade();
+            }
+        });
+        mFade = fade;
+        fade.start();
+    }
+
+    // Shows the image on its own (the fade ends, another starts, or the view
+    // is detached).
+    private void endFade() {
+        ValueAnimator fade = mFade;
+        mFade = null;
+        if (fade != null) fade.cancel();
+        if (mFadeFrom != null) {
+            mFadeFrom.recycle();
+            mFadeFrom = null;
+        }
+        mFadeProgress = 1f;
+        invalidate();
+    }
+
+    @SuppressWarnings("deprecation")
+    @Override
+    protected void onDraw(Canvas canvas) {
+        if (mFade == null) {
+            super.onDraw(canvas);
+            return;
+        }
+        int width = getWidth();
+        int height = getHeight();
+        int alpha = Math.round(255 * mFadeProgress);
+        if (mFadeFrom == null) {
+            // Fading in over nothing: one layer.
+            int count = canvas.saveLayerAlpha(0, 0, width, height, alpha, Canvas.ALL_SAVE_FLAG);
+            super.onDraw(canvas);
+            canvas.restoreToCount(count);
+            return;
+        }
+        // Canvas.ALL_SAVE_FLAG: the saveLayer without flags is API 21+.
+        int count = canvas.saveLayer(0, 0, width, height, null, Canvas.ALL_SAVE_FLAG);
+        mFadeFromPaint.setAlpha(255 - alpha);
+        canvas.drawBitmap(mFadeFrom, 0, 0, mFadeFromPaint);
+        mFadeInPaint.setAlpha(alpha);
+        canvas.saveLayer(0, 0, width, height, mFadeInPaint, Canvas.ALL_SAVE_FLAG);
+        super.onDraw(canvas);
+        canvas.restoreToCount(count);
+    }
+
+    @Override
+    protected void onDetachedFromWindow() {
+        endFade();
+        super.onDetachedFromWindow();
+    }
+
     public void setPaused(boolean paused) {
         if (paused == mPaused) return;
         mPaused = paused;
@@ -277,9 +451,10 @@ class FastImageViewWithUrl extends AppCompatImageView {
         mRecyclingKey = recyclingKey;
         if (changed) {
             // No thumbnail of the current image, so Glide clears the view to
-            // defaultSource (or nothing) while the next one loads. Reload even
-            // if the source is the same.
+            // defaultSource (or nothing) while the next one loads, nor a fade
+            // from it. Reload even if the source is the same.
             mShownRequest = null;
+            endFade();
             mNeedsReload = true;
         }
     }
@@ -299,6 +474,13 @@ class FastImageViewWithUrl extends AppCompatImageView {
     @Override
     protected void onSizeChanged(int w, int h, int oldw, int oldh) {
         super.onSizeChanged(w, h, oldw, oldh);
+        // During a fade, what the view showed was drawn at the old size: the
+        // image fades in over nothing instead.
+        if (mFadeFrom != null && (w != mFadeFrom.getWidth() || h != mFadeFrom.getHeight())) {
+            mFadeFrom.recycle();
+            mFadeFrom = null;
+            invalidate();
+        }
         reloadIfResized();
     }
 
@@ -395,7 +577,9 @@ class FastImageViewWithUrl extends AppCompatImageView {
     // it was loaded at: the key it's in Glide's memory cache under.
     @SuppressLint("CheckResult")
     private RequestBuilder<Drawable> fromCache(RequestBuilder<Drawable> shown) {
-        RequestBuilder<Drawable> request = shown.clone().onlyRetrieveFromCache(true);
+        // Never fades: it's the image the view showed.
+        RequestBuilder<Drawable> request = shown.clone().onlyRetrieveFromCache(true)
+                .transition(GenericTransitionOptions.<Drawable>withNoTransition());
         if (mShownWidth > 0 && mShownHeight > 0) request = request.override(mShownWidth, mShownHeight);
         return request;
     }
@@ -461,6 +645,8 @@ class FastImageViewWithUrl extends AppCompatImageView {
         boolean restarting = mRestarting;
         mRestarting = false;
         mLoadCount++;
+        // A fade in progress carries on, as on iOS: into the next image if it
+        // shows at once, and a next image that fades starts from it.
         RequestBuilder<Drawable> shownRequest = mShownRequest;
         mShownRequest = null;
         mLoadingRequest = null;
@@ -560,6 +746,16 @@ class FastImageViewWithUrl extends AppCompatImageView {
 
             if (model == null) meanwhile = null;
             boolean thumbnail = shownRequest != null && model != null && meanwhile == null;
+            // After the clone: loading the image that's showing again (at a
+            // new size, or with another blur) doesn't fade it in again. Over a
+            // loaded image (a new source) only with betweenImages: otherwise it
+            // replaces it at once, as Glide, Coil and Fresco fade an image in
+            // from nothing and never between images.
+            boolean replacing = shownRequest != null && model != null;
+            if (mTransitionDuration > 0 && (!replacing || mTransitionBetweenImages)) {
+                builder = builder.transition(DrawableTransitionOptions.with(
+                        new FadeFactory(mTransitionDuration, mTransitionSkipOnCacheHit)));
+            }
             if (thumbnail) {
                 builder = builder.thumbnail(fromCache(shownRequest));
             }

package/dist/index.cjs.js

@@ -91,11 +91,24 @@ function withProgress(onProgress) {
 		onProgress(event);
 	});
 }
+const DEFAULT_FADE_MS = react_native.Platform.OS === "ios" ? 250 : 300;
+function transitionProps(transition) {
+	var _transition$duration;
+	const { duration, betweenImages, skipOnCacheHit } = typeof transition === "number" ? { duration: transition } : typeof transition === "object" && transition ? {
+		...transition,
+		duration: (_transition$duration = transition.duration) !== null && _transition$duration !== void 0 ? _transition$duration : DEFAULT_FADE_MS
+	} : { duration: transition ? DEFAULT_FADE_MS : 0 };
+	return {
+		transitionDuration: typeof duration === "number" && duration > 0 ? duration : 0,
+		transitionBetweenImages: !!betweenImages,
+		transitionSkipOnCacheHit: skipOnCacheHit || "memory"
+	};
+}
 function withoutCache(source) {
 	const { cache: _cache, ...rest } = source || {};
 	return rest;
 }
-function FastImageBase({ source, defaultSource, tintColor, onLoadStart, onProgress, onLoad, onError, onLoadEnd, style, fallback, children, resizeMode = "cover", loop, forwardedRef, onLayout, pointerEvents, ...viewProps }) {
+function FastImageBase({ source, defaultSource, tintColor, onLoadStart, onProgress, onLoad, onError, onLoadEnd, style, fallback, children, resizeMode = "cover", loop, transition, forwardedRef, onLayout, pointerEvents, ...viewProps }) {
 	const { onClick, ...props } = viewProps;
 	const fallbackResult = (0, react.useRef)(void 0);
 	const wrapperProps = {
@@ -158,6 +171,7 @@ function FastImageBase({ source, defaultSource, tintColor, onLoadStart, onProgre
 		...imageProps,
 		tintColor: resolvedTintColor,
 		loopCount: loopCount(loop),
+		...transitionProps(transition),
 		style: react_native.StyleSheet.absoluteFill,
 		source: resolvedSource,
 		defaultSource: resolvedDefaultSource,

package/dist/index.cjs.js.flow

@@ -72,6 +72,12 @@ export type CachePathResult =
     | {| ok: true, path: string |}
     | {| ok: false, error: string |}
 
+export type Transition = $ReadOnly<{|
+    duration?: ?number,
+    betweenImages?: ?boolean,
+    skipOnCacheHit?: ?('none' | 'memory' | 'all'),
+|}>
+
 export type PreloadSuccess = {|
     uri: string,
     ok: true,
@@ -117,6 +123,7 @@ export type FastImageProps = $ReadOnly<{|
     loop?: ?(boolean | number),
     imageRendering?: ?('auto' | 'smooth' | 'pixelated'),
     paused?: ?boolean,
+    transition?: ?(boolean | number | Transition),
     downsample?: ?boolean,
     blurRadius?: ?number,
     testID?: ?string,

package/dist/index.d.ts

@@ -42,6 +42,35 @@ export type Source = {
      */
     memoryCache?: boolean;
 };
+export type Transition = {
+    /**
+     * How long the fade takes, in milliseconds; 0 means no fade. Defaults to
+     * the platform's usual length: 300 ms on Android, 250 ms on iOS.
+     */
+    duration?: number;
+    /**
+     * 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.
+     * @default false
+     */
+    betweenImages?: boolean;
+    /**
+     * 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.
+     * - `'all'`: skips it for images from the memory or disk cache too, so
+     *   images that download fade in, and local files and bundled images
+     *   usually only the first time (the disk cache usually keeps them too).
+     * - `'none'`: always fades.
+     *
+     * Downloads, local files and bundled images (`require()`) fade in.
+     * @default 'memory'
+     */
+    skipOnCacheHit?: 'none' | 'memory' | 'all' | null;
+};
 export interface OnLoadEvent {
     nativeEvent: {
         width: number;
@@ -135,6 +164,13 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
      * its own, so pausing one doesn't pause others showing the same file.
      */
     paused?: boolean;
+    /**
+     * Fades the image in when it loads: `true` for the platform's usual fade,
+     * a duration in milliseconds, or a `Transition` (default: no fade). An
+     * image fades in when it appears over nothing (see `betweenImages`),
+     * unless it's from the memory cache (see `skipOnCacheHit`).
+     */
+    transition?: boolean | number | Transition | null;
     /**
      * iOS only. Decodes a large image at about the size it's shown at, so it
      * takes much less memory. For images much larger than their views that

package/dist/index.js

@@ -64,11 +64,24 @@ function withProgress(onProgress) {
 		onProgress(event);
 	});
 }
+const DEFAULT_FADE_MS = Platform.OS === "ios" ? 250 : 300;
+function transitionProps(transition) {
+	var _transition$duration;
+	const { duration, betweenImages, skipOnCacheHit } = typeof transition === "number" ? { duration: transition } : typeof transition === "object" && transition ? {
+		...transition,
+		duration: (_transition$duration = transition.duration) !== null && _transition$duration !== void 0 ? _transition$duration : DEFAULT_FADE_MS
+	} : { duration: transition ? DEFAULT_FADE_MS : 0 };
+	return {
+		transitionDuration: typeof duration === "number" && duration > 0 ? duration : 0,
+		transitionBetweenImages: !!betweenImages,
+		transitionSkipOnCacheHit: skipOnCacheHit || "memory"
+	};
+}
 function withoutCache(source) {
 	const { cache: _cache, ...rest } = source || {};
 	return rest;
 }
-function FastImageBase({ source, defaultSource, tintColor, onLoadStart, onProgress, onLoad, onError, onLoadEnd, style, fallback, children, resizeMode = "cover", loop, forwardedRef, onLayout, pointerEvents, ...viewProps }) {
+function FastImageBase({ source, defaultSource, tintColor, onLoadStart, onProgress, onLoad, onError, onLoadEnd, style, fallback, children, resizeMode = "cover", loop, transition, forwardedRef, onLayout, pointerEvents, ...viewProps }) {
 	const { onClick, ...props } = viewProps;
 	const fallbackResult = useRef(void 0);
 	const wrapperProps = {
@@ -131,6 +144,7 @@ function FastImageBase({ source, defaultSource, tintColor, onLoadStart, onProgre
 		...imageProps,
 		tintColor: resolvedTintColor,
 		loopCount: loopCount(loop),
+		...transitionProps(transition),
 		style: StyleSheet.absoluteFill,
 		source: resolvedSource,
 		defaultSource: resolvedDefaultSource,

package/dist/index.js.flow

@@ -72,6 +72,12 @@ export type CachePathResult =
     | {| ok: true, path: string |}
     | {| ok: false, error: string |}
 
+export type Transition = $ReadOnly<{|
+    duration?: ?number,
+    betweenImages?: ?boolean,
+    skipOnCacheHit?: ?('none' | 'memory' | 'all'),
+|}>
+
 export type PreloadSuccess = {|
     uri: string,
     ok: true,
@@ -117,6 +123,7 @@ export type FastImageProps = $ReadOnly<{|
     loop?: ?(boolean | number),
     imageRendering?: ?('auto' | 'smooth' | 'pixelated'),
     paused?: ?boolean,
+    transition?: ?(boolean | number | Transition),
     downsample?: ?boolean,
     blurRadius?: ?number,
     testID?: ?string,

package/ios/FastImage/FFFastImageView.h

@@ -30,6 +30,12 @@
 @property (nonatomic, copy) NSString *imageRendering;
 // Pauses animated images on the frame they're showing.
 @property (nonatomic, assign) BOOL paused;
+// The `transition` prop: how long a loaded image takes to fade in, in
+// milliseconds (0 for no fade), whether it also fades over a loaded image
+// (a new source), and which cache hits show at once (none, memory or all).
+@property (nonatomic, assign) double transitionDuration;
+@property (nonatomic, assign) BOOL transitionBetweenImages;
+@property (nonatomic, copy) NSString *transitionSkipOnCacheHit;
 // Decodes images at about the view's size instead of at full size.
 @property (nonatomic, assign) BOOL downsample;
 // Blurs the loaded image by this radius, in points (0 is no blur).

package/ios/FastImage/FFFastImageView.m

@@ -26,6 +26,11 @@
 @property(nonatomic, assign) CGSize blurredForSize;
 // The blurred image showing (untinted), so a tint change can re-show it.
 @property(nonatomic, strong) UIImage* blurredImage;
+// 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).
+@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;
@@ -117,6 +122,77 @@ static UIImage* FFFBlurredImage(UIImage* image, CGFloat scale, CGFloat radius, B
     }
 }
 
+// Whether a loaded image fades in (the `transition` prop). Over a loaded
+// image (a new source) only with betweenImages: otherwise it replaces it at
+// once, as Android's image libraries fade an image in from nothing and never
+// between images. Then as SDWebImage's transitions and those libraries
+// decide: from the memory cache it shows at once (skipOnCacheHit 'memory',
+// the default), and from the disk cache too with 'all'. Downloads, local
+// files and bundled images fade.
+- (BOOL) fadesImageFromCache: (SDImageCacheType)cacheType {
+    if (self.transitionDuration <= 0 || ([self displaysLoadedImage] && !self.transitionBetweenImages)) {
+        return NO;
+    }
+    NSString* skip = self.transitionSkipOnCacheHit;
+    if ([skip isEqualToString: @"none"]) {
+        return YES;
+    }
+    if (cacheType == SDImageCacheTypeMemory) {
+        return NO;
+    }
+    // SDWebImage also keeps local files and bundled images in its disk cache,
+    // so with 'all' they usually only fade the first time.
+    return !(cacheType == SDImageCacheTypeDisk && [skip isEqualToString: @"all"]);
+}
+
+// Whether the view shows a loaded image now: a loaded image that's still
+// being blurred isn't showing yet.
+- (BOOL) displaysLoadedImage {
+    return self.showsLoadedImage && !self.blursOverNothing;
+}
+
+// Shows a loaded image, fading it in over what the view shows if `fade`. A
+// blurred image shows, and fades in, once it's blurred.
+- (void) showLoadedImage: (UIImage*)image fade: (BOOL)fade {
+    if ([self blurs: image]) {
+        self.blursOverNothing = ![self displaysLoadedImage];
+        self.fadesBlurredImage = fade;
+        self.image = image;
+        return;
+    }
+    self.blursOverNothing = NO;
+    self.fadesBlurredImage = NO;
+    if (fade) {
+        [self fadeIn: ^{
+            self.image = image;
+        }];
+    } else {
+        self.image = image;
+    }
+}
+
+// Makes the change (showing another image), fading it in over what the view
+// showed.
+- (void) fadeIn: (void (^)(void))change {
+    if (!super.image || !self.layer.presentationLayer) {
+        // Nothing to cross-dissolve from: the view shows no image, or isn't
+        // on screen yet (e.g. a new view whose image loads as it mounts),
+        // where a cross-dissolve has nothing drawn to start from and shows
+        // the image at once. Fade the view in instead.
+        change();
+        CABasicAnimation* fadeIn = [CABasicAnimation animationWithKeyPath: @"opacity"];
+        fadeIn.fromValue = @0;
+        fadeIn.duration = self.transitionDuration / 1000;
+        [self.layer addAnimation: fadeIn forKey: @"FFFFadeIn"];
+        return;
+    }
+    [UIView transitionWithView: self
+                      duration: self.transitionDuration / 1000
+                       options: UIViewAnimationOptionTransitionCrossDissolve | UIViewAnimationOptionAllowUserInteraction
+                    animations: change
+                    completion: nil];
+}
+
 - (void) setPaused: (BOOL)paused {
     if (_paused == paused) {
         return;
@@ -246,7 +322,17 @@ static UIImage* FFFBlurredImage(UIImage* image, CGFloat scale, CGFloat radius, B
     }
     self.originalImage = image && self.imageColor ? image : nil;
     self.blurredImage = nil;
-    [self showImage: image];
+    self.blursOverNothing = NO;
+    // The blur was removed before it was ready: the fade it was waiting for
+    // happens now.
+    if (self.fadesBlurredImage) {
+        self.fadesBlurredImage = NO;
+        [self fadeIn: ^{
+            [self showImage: image];
+        }];
+    } else {
+        [self showImage: image];
+    }
 }
 
 // Shows the image, tinted as React Native's Image does it: UIKit draws a
@@ -336,7 +422,15 @@ static UIImage* FFFBlurredImage(UIImage* image, CGFloat scale, CGFloat radius, B
 - (void) showBlurredImage: (UIImage*)image count: (NSUInteger)count {
     if (self.imageCount == count) {
         self.blurredImage = image;
-        [self showImage: image];
+        self.blursOverNothing = NO;
+        if (self.fadesBlurredImage) {
+            self.fadesBlurredImage = NO;
+            [self fadeIn: ^{
+                [self showImage: image];
+            }];
+        } else {
+            [self showImage: image];
+        }
     }
 }
 
@@ -513,8 +607,9 @@ NSString *FFFErrorMessage(NSError *error)
     if (changed) {
         // The view shows other content now: don't keep the current image
         // while the next one loads (reloadImage clears it), even if the
-        // source is the same.
+        // source is the same, nor a fade from it.
         self.showsLoadedImage = NO;
+        [self.layer removeAllAnimations];
         _needsReload = YES;
     }
 }
@@ -646,7 +741,7 @@ NSString *FFFErrorMessage(NSError *error)
                 }
                 return;
             }
-            [self setImage: image];
+            [self showLoadedImage: image fade: [self fadesImageFromCache: SDImageCacheTypeNone]];
             if (self.onFastImageProgress) {
                 self.onFastImageProgress(@{
                         @"loaded": @(1),
@@ -799,13 +894,18 @@ 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;
     SDSetImageBlock setImage = ^(UIImage* _Nullable image, NSData* _Nullable data, SDImageCacheType cacheType, NSURL* _Nullable imageURL) {
-        if (weakSelf.loadCount == load) {
-            weakSelf.image = image;
+        if (weakSelf.loadCount != load) {
+            return;
         }
+        // The loaded image, not defaultSource (shown while it loads, or if it
+        // fails).
+        BOOL loaded = image && image != placeholder;
+        [weakSelf showLoadedImage: image fade: loaded && [weakSelf fadesImageFromCache: cacheType]];
     };
     [self sd_internalSetImageWithURL: url
-                    placeholderImage: _defaultSource
+                    placeholderImage: placeholder
                              options: options
                              context: context
                        setImageBlock: setImage

package/ios/FastImage/FFFastImageViewManager.m

@@ -107,6 +107,9 @@ RCT_EXPORT_VIEW_PROPERTY(recyclingKey, NSString)
 RCT_EXPORT_VIEW_PROPERTY(loopCount, NSInteger)
 RCT_EXPORT_VIEW_PROPERTY(imageRendering, NSString)
 RCT_EXPORT_VIEW_PROPERTY(paused, BOOL)
+RCT_EXPORT_VIEW_PROPERTY(transitionDuration, double)
+RCT_EXPORT_VIEW_PROPERTY(transitionBetweenImages, BOOL)
+RCT_EXPORT_VIEW_PROPERTY(transitionSkipOnCacheHit, NSString)
 RCT_EXPORT_VIEW_PROPERTY(downsample, BOOL)
 RCT_EXPORT_VIEW_PROPERTY(blurRadius, CGFloat)
 RCT_EXPORT_VIEW_PROPERTY(onFastImageLoadStart, RCTDirectEventBlock)

package/package.json

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