Reference version

Archive Expo Snack Discord and Forums Newsletter

Expo Asset

GitHub

npm

A universal library that allows downloading assets and using them with other libraries.

expo-asset provides an interface to Expo's asset system. An asset is any file that lives alongside the source code of your app that the app needs at runtime. Examples include images, fonts, and sounds. Expo's asset system integrates with React Native's, so that you can refer to files with require('path/to/file'). This is how you refer to static image files in React Native for use in an Image component, for example. Check out React Native's documentation on static image resources for more information. This method of referring to static image resources works out of the box with Expo.

Platform Compatibility

Android Device	Android Emulator	iOS Device	iOS Simulator	Web

Installation

Terminal

- npx expo install expo-asset

If you are installing this in an existing React Native app, start by installing expo in your project. Then, follow the additional instructions as mentioned by the library's README under "Installation in bare React Native projects" section.

API

import { Asset } from 'expo-asset';

Hooks

`useAssets(moduleIds)`

Parameter	Type
moduleIds	`number \| number[]`

Downloads and stores one or more assets locally. After the assets are loaded, this hook returns a list of asset instances. If something went wrong when loading the assets, an error is returned.

Note, the assets are not "reloaded" when you dynamically change the asset list.

Returns:

[Asset[] | undefined, Error | undefined]

Returns an array containing:

on the first position, a list of all loaded assets. If they aren't loaded yet, this value is undefined.
on the second position, an error which encountered when loading the assets. If there was no error, this value is undefined.

Example

const [assets, error] = useAssets([require('path/to/asset.jpg'), require('path/to/other.png')]);

return assets ? <Image source={assets[0]} /> : null;

Classes

`Asset`

The Asset class represents an asset in your app. It gives metadata about the asset (such as its name and type) and provides facilities to load the asset data.

Asset Properties

`downloaded`

Type: boolean • Default: false

`downloading`

Type: boolean • Default: false

`hash`

Type: null | string • Default: null

The MD5 hash of the asset's data.

`height`

Type: null | number • Default: null

If the asset is an image, the height of the image data divided by the scale factor. The scale factor is the number after @ in the filename, or 1 if not present.

`localUri`

Type: null | string • Default: null

If the asset has been downloaded (by calling downloadAsync()), the file:// URI pointing to the local file on the device that contains the asset data.

`name`

Type: string

The name of the asset file without the extension. Also without the part from @ onward in the filename (used to specify scale factor for images).

`type`

Type: string

The extension of the asset filename.

`uri`

Type: string

A URI that points to the asset's data on the remote server. When running the published version of your app, this refers to the location on Expo's asset server where Expo has stored your asset. When running the app from Expo CLI during development, this URI points to Expo CLI's server running on your computer and the asset is served directly from your computer. If you are not using Classic Updates (legacy), this field should be ignored as we ensure your assets are on device before before running your application logic.

`width`

Type: null | number • Default: null

If the asset is an image, the width of the image data divided by the scale factor. The scale factor is the number after @ in the filename, or 1 if not present.

Asset Methods

`downloadAsync()`

Downloads the asset data to a local file in the device's cache directory. Once the returned promise is fulfilled without error, the localUri field of this asset points to a local file containing the asset data. The asset is only downloaded if an up-to-date local file for the asset isn't already present due to an earlier download. The downloaded Asset will be returned when the promise is resolved.

Returns:

Promise<Asset>

Returns a Promise which fulfills with an Asset instance.

`fromMetadata(meta)`

Parameter	Type
meta	`AssetMetadata`

Returns:

Asset

`fromModule(virtualAssetModule)`

Parameter	Type	Description
virtualAssetModule	`string \| number`	The value of `require('path/to/file')` for the asset or external network URL

Returns the Asset instance representing an asset given its module or URL.

Returns:

Asset

The Asset instance for the asset.

`fromURI(uri)`

Parameter	Type
uri	`string`

Returns:

Asset

`loadAsync(moduleId)`

Parameter	Type	Description
moduleId	`string \| number \| number[] \| string[]`	An array of `require('path/to/file')` or external network URLs. Can also be just one module or URL without an Array.

A helper that wraps Asset.fromModule(module).downloadAsync for convenience.

Returns:

Promise<Asset[]>

Returns a Promise that fulfills with an array of Assets when the asset(s) has been saved to disk.

Example

const [{ localUri }] = await Asset.loadAsync(require('./assets/snack-icon.png'));

Types

`AssetDescriptor`

Name	Type	Description
hash (optional)	`string \| null`	-
height (optional)	`number \| null`	-
name	`string`	-
type	`string`	-
uri	`string`	-
width (optional)	`number \| null`	-

`AssetMetadata`

Name	Type	Description
fileHashes (optional)	`string[]`	-
fileUris (optional)	`string[]`	-
uri (optional)	`string`	-