react-native-fast-image

property maxDiskAge

maxDiskAge?: number | null;

• iOS: the seconds an image is kept on disk after it was last used, or 0 to keep them until maxDiskSize removes them. Default: 1 week.

property maxDiskSize

maxDiskSize?: number | null;

• The most bytes of images kept on disk. When it's over, the least recently used are removed (on iOS, until it's half this size). Default: no limit on iOS, 250 MB on Android.

property maxMemorySize

maxMemorySize?: number | null;

• iOS: the most bytes of decoded images kept in memory. Default: no limit (they're removed when the system is low on memory).

property diskSize

diskSize?: number;

• The bytes the disk cache uses now.

property maxDiskAge

maxDiskAge?: number;

property maxDiskSize

maxDiskSize?: number;

property maxMemorySize

maxMemorySize?: number;

property children

children?: React.ReactNode;

• Content shown on top of the image.

property imageRef

imageRef?: React.Ref<any>;

• A ref to the image (the FastImage inside).

property imageStyle

imageStyle?: StyleProp<ImageStyle>;

• The image's style.

property style

style?: StyleProp<ViewStyle>;

• The container's style; the image fills it.

property blurRadius

blurRadius?: number;

• Blurs the image by this radius, in points (the same radius looks about the same on iOS and Android). 0 is no blur.

  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. - 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. - Changing it blurs the image that's showing again, without sending the load events again.

  To animate a blur, or to blur an animated image, use React Native's filter style instead, which the GPU draws: style={{ filter: [{ blur: 6 }] }}. It needs the New Architecture. React Native's docs list blur for Android 12+ only; on iOS it's behind an experimental React Native feature flag (enableSwiftUIBasedFilters, SwiftUI-based filters).

  0

property children

children?: React.ReactNode;

• Render children within the image.

  Deprecated

  In the next major version, FastImage won't render children: use FastImageBackground.

property defaultSource

defaultSource?: ImageRequireSource;

• 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.

property downsample

downsample?: boolean;

• Decodes a large image at about the size it's shown at, instead of at full size, so it takes much less memory.

  - true: an image at least twice the size its view needs is decoded at about the view's size. If the view grows, the image is decoded again for its new size (from the disk cache). - false: images are decoded at full size, e.g. for an image that's zoomed in on with a transform (a pinch-to-zoom viewer), which would otherwise show the smaller copy enlarged.

  It doesn't change onLoad's width and height (the image's own size) or the cached file. Needs SDWebImage 5.19.7 or later: before 5.19 images are decoded at full size, and 5.19.0 to 5.19.6 show photos stored sideways with an EXIF orientation (most phone photos) sideways. Photo library images are always decoded this way, and on Android images are always decoded at about the view's size (but Android 16 and later decode animated WebP at full size, and scale it as they draw it).

  If you control the images, serve them at the size they're shown (resized on your server or by an image CDN), which also saves bandwidth.

  ios true

property fallback

fallback?: boolean;

• If true, the image is shown with React Native's Image instead, styled and laid out the same way. FastImage's own features, such as its caching options, priority and transition, don't apply.

property imageRendering

imageRendering?: 'auto' | 'smooth' | 'pixelated';

• How the image is filtered when it's drawn smaller or larger than its size (like CSS's image-rendering):

  - 'auto': the platform's usual filtering. - 'smooth': iOS only. Keeps a large image drawn much smaller than its size (e.g. a big photo as a thumbnail, or fine lines and text) from looking jagged or noisy. Such an image is already decoded at about the view's size by default (see downsample), so this is for images shown at less than half their size with downsample={false}, or a little smaller than their size. **It uses more memory:** the image is also kept at smaller sizes for drawing, about a third more than the decoded image. On Android it's the same as 'auto' (images are always decoded at about the view's size there). - 'pixelated': sharp pixels, without smoothing, e.g. for pixel art drawn larger than its size. On Android, animated images are still smoothed.

  'auto'

property loop

loop?: boolean | number;

• How many times an animated image (GIF, animated WebP, APNG, or animated AVIF) plays:

  - Not set: as many times as the file says (like a browser). - true: forever. - false: once. - A number: that many times.

  Changing it restarts the animation.

property paused

paused?: boolean;

• Pauses an animated image (GIF, animated WebP, APNG, or animated AVIF) on the frame it's showing; false plays it again from there (on Android, an animated WebP or AVIF plays again from its first frame: Android can't resume one). Each image animates on its own, so pausing one doesn't pause others showing the same file.

property recyclingKey

recyclingKey?: 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.

  Example 1

  <FastImage recyclingKey={item.id} source={{ uri: item.imageUrl }} />

property resizeMode

resizeMode?: ResizeMode;

• How the image fills the view.

  - 'contain': scales it uniformly (keeping its aspect ratio) so all of it fits in the view (minus padding). - 'cover': scales it uniformly (keeping its aspect ratio) so it covers the view (minus padding), cropping what doesn't fit. - 'stretch': scales its width and height separately to fill the view, which can change its aspect ratio. - 'center': centers it at its own size, scaled down uniformly to fit if it's larger than the view. - 'repeat': repeats it to cover the view, from its top-left corner, at the image's own size in pixels (a bundled image at its size in points), scaled down to fit if it's larger than the view. An animated image repeats its first frame, and defaultSource repeats too.

  'cover'

property source

source?: Source | Source[] | ImageRequireSource;

• Source for the remote image to load: a Source, a require()d image, or an array of the same image at different sizes.

  When source changes, the image that's showing stays until the new one has loaded. In views that get reused for other content, such as rows in FlashList or recyclerlistview, set recyclingKey so a reused row doesn't show the previous row's image.

  **Several sizes of an image.** source can also be an array of the same image at different sizes, each with its width and height in pixels (times scale, if it has one). The view loads the one whose size is closest to its own, in pixels, so a small view downloads a small image:

  <FastImage
      style={{ width: 120, height: 120 }}
      source={[
          { uri: 'https://example.com/photo-200.jpg', width: 200, height: 200 },
          { uri: 'https://example.com/photo-800.jpg', width: 800, height: 800 },
      ]}
  />

  - The view picks once it has been laid out. One that has no size (e.g. sized from onLoad) loads the largest. - When the view's size changes so that another size fits better, it loads that one (with its load events), and keeps showing the current image until then, without a transition. - Each size is cached separately. A cacheKey applies to its own entry: give each size its own key (or none), or the sizes would replace each other in the cache. - FastImage.preload, getCachePath and writeToCache take one size: pass the one a view will show. An array fails with { ok: false, error }. - An array of one is the same as that source.

property style

style?: StyleProp<ImageStyle>;

• The image's style: View's style props (borderRadius clips the image), and tintColor, as with React Native's Image (the tintColor prop wins).

property tintColor

tintColor?: ColorValue;

• If supplied, changes the color of all the non-transparent pixels to the given color.

property transition

transition?: boolean | number | Transition | null;

• Fades the image in when it loads. true uses the platform's usual fade, a number is the duration in milliseconds, or pass a Transition.

  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.

  false

  Example 1

  <FastImage source={{ uri }} transition />
  <FastImage source={{ uri }} transition={500} />
  <FastImage source={{ uri }} transition={{ betweenImages: true, skipOnCacheHit: 'none' }} />

method onError

onError: (event: OnErrorEvent) => void;

• Called on an image fetching error, with a message describing it (e.g. the HTTP status code). On iOS and Android, a download that gets nothing from the server for 15 seconds fails too (on Android, unless the app's OkHttp client has timeouts of its own).

  Example 1

  onError={e => console.log(e.nativeEvent.error)}

method onLoad

onLoad: (event: OnLoadEvent) => void;

• Called on a successful image fetch. Called with the width and height of the image itself, not of the view (on iOS, in points: an @2x asset reports half its pixel size).

  Example 1

  onLoad={e => console.log(e.nativeEvent.width, e.nativeEvent.height)}

method onLoadEnd

onLoadEnd: (result: LoadResult) => void;

• Called when the image finishes loading, whether it was successful or an error, with the result: { ok: true, width, height } (the image's size, as onLoad gets it) or { ok: false, error } (as onError gets it). TypeScript makes you check ok before reading the size or the error.

  Example 1

  <FastImage
      source={{ uri }}
      onLoadEnd={(result) => {
          if (result.ok) setAspectRatio(result.width / result.height)
          else setFailed(result.error)
      }}
  />

method onLoadStart

onLoadStart: () => void;

• Called when the image starts to load.

method onProgress

onProgress: (event: OnProgressEvent) => void;

• Called while the image downloads, with the bytes loaded so far, the total, and progress (loaded / total, from 0 to 1; the last event has 1). Not called while the total is unknown (a response without a Content-Length).

  Example 1

  onProgress={e => console.log(e.nativeEvent.progress)}

property cacheControl

cacheControl: typeof cacheControl;

property clearDiskCache

clearDiskCache: () => Promise<ClearCacheResult>;

• Removes every image from the disk cache, and the HTTP cache of cache: 'web' images. Resolves once it's done, or not ok with the error if it couldn't (Android: Glide failed to start). Never rejects.

property clearMemoryCache

clearMemoryCache: () => Promise<ClearCacheResult>;

• Removes every image from the memory cache. Resolves once it's done, or not ok with the error if it couldn't (Android: Glide failed to start). Never rejects.

property configureCache

configureCache: (limits?: CacheLimits) => Promise<CacheState>;

• Changes the cache's limits at runtime (only those given; 0 for no limit, null to go back to the app's native config) and saves them, then resolves with the limits in effect and the disk cache's size; without limits, it only resolves with them. iOS applies changes at once. Android only has maxDiskSize, applied when Glide starts: at once if it hasn't started yet in this launch, otherwise from the next launch. FastImage starts it when its first view is created (before the view has a source), and for preload, getCachePath, writeToCache, clearDiskCache and configureCache itself, even without limits (e.g. to read the disk cache's size).

property getCachePath

getCachePath: (source: Source) => Promise<CachePathResult>;

• The path of the source's downloaded file in the disk cache, downloading it first if it isn't there (without decoding it). With cache: 'cacheOnly', or a cacheKey without a uri, it doesn't download. Never rejects.

property preload

preload: (sources: Source[]) => Promise<PreloadResult[]>;

property priority

priority: typeof priority;

property resizeMode

resizeMode: typeof resizeMode;

property writeToCache

writeToCache: (source: Source, file: string) => Promise<CachePathResult>;

• Stores a local image file (a file:// uri or a path, or on Android a content:// uri) as the source's image in the disk cache, so views and preloads of the source show it without downloading it. A source with a cacheKey doesn't need a uri. Resolves with its cached file. Doesn't replace an image that's already cached, and isn't for cache: 'web' sources. Never rejects.

property overlayColor

overlayColor?: ColorValue;

property tintColor

tintColor?: ColorValue;

property nativeEvent

nativeEvent: {
    error: string;
};

property nativeEvent

nativeEvent: {
    width: number;
    height: number;
    target?: number;
};

property nativeEvent

nativeEvent: {
    loaded: number;
    total: number;
    progress: number;
};

property error

error: string;

• What went wrong.

property ok

ok: false;

property uri

uri?: string;

• The source's uri (none for a source without one, e.g. null).

property height

height: number;

• The image's height (as in onLoad).

property ok

ok: true;

property uri

uri: string;

• The source's uri.

property width

width: number;

• The image's width (as in onLoad).