expo-image

Open Beta Documentation Amazon offers this technical documentation as part of a pre-release, open beta. The features described might change as Amazon receives feedback and iterates on the features. For the most current feature information, see the Release Notes.

@amazon-devices/expo-image provides a cross-platform, performant image component for React Native and Expo. The library supports BlurHash and ThumbHash, compact representations of a placeholder for an image. It also supports transitioning between images when the source changes. @amazon-devices/expo-image implements the CSS object-fit and object-position properties.

Installation
Usage Examples
API reference
Implementation details
Supported versions
Additional resources

Installation

Add the JavaScript library dependency in the package.json file.

Copied to clipboard.

 dependencies: {
     ...
     "@amazon-devices/expo-image": "~2.0.0",
 }

Reinstall dependencies using npm install command.

Usage Examples

The example below demonstrates an image with a thumbhash placeholder and multiple sources.

Copied to clipboard.

import React from 'react';
import {StyleSheet, View} from 'react-native';
import {Image} from '@amazon-devices/expo-image';

export const App = () => {
  return (
    <View style={styles.container}>
      <Image
        source={[
          'https://images.pexels.com/photos/842711/pexels-photo-842711.jpeg',
          'https://climateforlife.pl/wp-content/uploads/2023/10/panda.png',
        ]}
        style={styles.image}
        placeholder="thumbhash:/1QcSHQRnh493V4dIh4eXh1h4kJUI"
      />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    backgroundColor: 'white',
    flex: 1,
  },
  image: {
    width: 300,
    aspectRatio: 1,
  },
});

API reference

Check out the dedicated documentation page for info about this library, API reference and more Official Expo documentation for expo-image.

Components

Component	Description
`Image`	A cross-platform React component that loads and renders images

Image props

Prop	Description
`accessibilityLabel`	The text that's read by the screen reader when the user interacts with the image. Sets the the alt tag on web which is used for web crawlers and link traversal
`accessible`	When `true`, indicates that the view is an accessibility element. When a view is an accessibility element, it groups its children into a single selectable component
`allowDownscaling`	Whether the image should be downscaled to match the size of the view container. Defaults to `true`. Setting to `false` could negatively impact the application's performance, particularly when working with large assets. However, setting to `false` could result in smoother image resizing, and end-users would always have access to the highest possible asset quality
`alt`	The text that's read by the screen reader when the user interacts with the image. Sets the the `alt` tag on web which is used for web crawlers and link traversal. Is an alias for `accessibilityLabel`
`blurRadius`	The radius of the blur in points, `0` means no blur effect. This effect is not applied to placeholders
`contentFit`	Determines how the image should be resized to fit its container. This property tells the image to fill the container in a variety of ways; such as "preserve that aspect ratio" or "stretch up and take up as much space as possible". It mirrors the CSS `object-fit` property
`contentPosition`	It is used together with `contentFit` to specify how the image should be positioned with x/y coordinates inside its own container. An equivalent of the CSS `object-position` property
`defaultSource`	A default value for the image source. WARNING: Deprecated. Provides compatibility for defaultSource from React Native Image. Use placeholder prop instead
`fadeDuration`	WARNING: Deprecated. Provides compatibility for `fadeDuration` from React Native Image. Instead use transition with the provided duration
`focusable`	Whether this View should be focusable with a non-touch input device and receive focus with a hardware keyboard
`loadingIndicatorSource`	WARNING: Deprecated. Provides compatibility for `loadingIndicatorSource` from React Native Image. Use placeholder prop instead
`onError`	Called on an image fetching error
`onLoad`	Called when the image load completes successfully
`onLoadEnd`	Called when the image load either succeeds or fails
`onLoadStart`	Called when the image starts to load
`placeholder`	An image to display while loading the proper image and no image has been displayed yet or the source is unset
`priority`	Priorities for completing loads. If more than one load is queued at a time, the load with the higher priority will be started first. Priorities are considered best effort, there are no guarantees about the order in which loads will start or finish
`recyclingKey`	Changing this prop resets the image view content to blank or a placeholder before loading and rendering the final image. This is especially useful for any kinds of recycling views like `FlashList` to prevent showing the previous source before the new one fully loads
`resizeMode`	WARNING: Deprecated. Provides compatibility for `resizeMode` from React Native Image. Note that `"repeat"` option is not supported at all. Use the more powerful `contentFit` and `contentPosition` props instead
`source`	The image source, either a remote URL, a local file resource or a number that is the result of the `require()` function. When provided as an array of sources, the source that fits best into the container size and is closest to the screen scale will be chosen. In this case it is important to provide `width`, `height` and `scale` properties
`tintColor`	A color used to tint template images (a bitmap image where only the opacity matters). The color is applied to every non-transparent pixel, causing the image’s shape to adopt that color. This effect is not applied to placeholders
`transition`	Describes how the image view should transition the contents when switching the image source. If provided as a number, it is the duration in milliseconds of the `'cross-dissolve'` effect

Methods

Method	Description
`clearDiskCache`	Asynchronously clears all images from the disk cache
`clearMemoryCache`	Asynchronously clears all images stored in memory
`prefetch`	Preloads images at the given urls that can be later used in the image view. Preloaded images are always cached on the disk, so make sure to use `disk` (default) or `memory-disk` cache policy

Implementation details

Does not support SVGs and animated sources
onProgress is not supported
onLoadEnd, onLoadStart, onLoad sometimes don't get invoked on Vega

Supported versions

Package Version	Based On	@amazon-devices/react-native-kepler version
2.0.x	1.6.0	2.0.x

Additional resources

For information on additional libraries, see Supported Third-Party Libraries and Services.

Last updated: Sep 30, 2025