expo-image - Amazon Vega Docs

@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

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

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

Reinstall dependencies using the npm install command.

Examples

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

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

See the documentation page for information about this library and API reference: Official Expo documentation for expo-image.

Components

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

Image props

Prop	Description	Supported
`accessibilityLabel`	The text that’s read by the screen reader when the user interacts with the image. Sets the the alt tag on the web which is used for web crawlers and link traversals.	✅ Yes
`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.	✅ Yes
`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.	✅ Yes
`alt`	The text that’s read by the screen reader when the user interacts with the image. Sets the `alt` tag on the web which is used for web crawlers and link traversals. Is an alias for `accessibilityLabel`.	✅ Yes
`blurRadius`	The radius of the blur in points, for example `0` means no blur effect. This effect isn’t applied to placeholders.	✅ Yes
`contentFit`	Determines how the image should be resized to fit its container. The image can fill the container in a variety of ways, such as “preserve that aspect ratio” or “stretch up to the maximum amount of space”. Similar to the CSS `object-fit` property.	✅ Yes
`contentPosition`	Can be used 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.	✅ Yes
`defaultSource`	WARNING: Deprecated. A default value for the image source. Provides compatibility for `defaultSource` from React Native Image. Use the `placeholder` prop instead.	✅ Yes
`fadeDuration`	WARNING: Deprecated. Provides compatibility for `fadeDuration` from React Native Image. Instead use `transition` with the provided duration.	✅ Yes
`focusable`	Whether this View should be focusable with a non-touch input device and receive focus with a hardware keyboard.	✅ Yes
`loadingIndicatorSource`	WARNING: Deprecated. Provides compatibility for `loadingIndicatorSource` from React Native Image. Use the `placeholder` prop instead.	✅ Yes
`onError`	Called on an image fetching error.	✅ Yes
`onLoad`	Called when the image load completes successfully.	✅ Yes
`onLoadEnd`	Called when the image load either succeeds or fails.	✅ Yes
`onLoadStart`	Called when the image starts to load.	✅ Yes
`placeholder`	An image to display while loading the proper image and no image has been displayed yet or the source is unset.	✅ Yes
`priority`	Priorities for completing loads. If more than one load is queued at a time, the load with the higher priority is started first. Priorities are considered best effort, there are no guarantees about the order in which loads start or finish.	✅ Yes
`recyclingKey`	Resets the image view content to blank or to a placeholder before loading and rendering the final image. Useful for recycling views like `FlashList` to prevent showing the previous source before the new one fully loads.	✅ Yes
`resizeMode`	WARNING: Deprecated. Provides compatibility for `resizeMode` from React Native Image. The `"repeat"` option isn’t supported. Use the more powerful `contentFit` and `contentPosition` props instead.	✅ Yes
`source`	The image source, either a remote URL, a local file resource, or a number that’s 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 is chosen. In this case, you must provide the `width`, `height`, and `scale` properties.	✅ Yes
`tintColor`	A color used to tint template images, for example 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.	✅ Yes
`transition`	Describes how the image view should transition the contents when switching the image source. If provided as a number, you get the duration in milliseconds of the `'cross-dissolve'` effect.	✅ Yes
`onProgress`	Used for video playback or file uploads. React Native documentation: https://reactnative.dev/docs/image#onprogress	❌ No

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 later can be used in the image view. Preloaded images are always cached on the disk, so make sure to use the `disk` (default) or `memory-disk` cache policy.

Known issues and limitations

This library doesn’t support SVGs and animated sources.
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

Supported Third-Party Libraries and Services.

​Installation

​Examples

​API reference

​Components

​Image props

​Methods

​Known issues and limitations

​Supported versions

​Related topics