This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 51).
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.
-
npx expo install expo-asset
If you are installing this in an existing React Native app (bare workflow), start by installing expo
in your project. Then, follow the additional instructions as mentioned by library's README under "Installation in bare React Native projects" section.
You can configure expo-asset
using its built-in config plugin if you use config plugins in your project (EAS Build or npx expo run:[android|ios]
). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect.
{
"expo": {
"plugins": [
[
"expo-asset",
{
"assets": ["path/to/file.png", "path/to/directory"]
}
]
]
}
}
Name | Default | Description |
---|---|---|
assets | [] | An array of asset files or directories to link to the native project. The paths should be relative to the project root so that the file names, whether specified directly or using a directory, will become the resource names. Supported file types:
|
Learn more about how to use the expo-asset
config plugin to embed an asset file in your project in Load an asset at build time.
import { Asset } from 'expo-asset';
useAssets(moduleIds)
Name | 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 an array containing:
undefined
.undefined
.Example
const [assets, error] = useAssets([require('path/to/asset.jpg'), require('path/to/other.png')]);
return assets ? <Image source={assets[0]} /> : null;
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
Whether the asset has finished downloading from a call to downloadAsync()
.
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).
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 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 a Promise which fulfills with an Asset
instance.
fromModule(virtualAssetModule)
Name | Type | Description |
---|---|---|
virtualAssetModule | string | number | The value of |
Returns the Asset
instance representing an asset given its module or URL.
The Asset
instance for the asset.
loadAsync(moduleId)
Name | Type | Description |
---|---|---|
moduleId | string | number | number[] | string[] | An array of |
A helper that wraps Asset.fromModule(module).downloadAsync
for convenience.
Returns a Promise that fulfills with an array of Asset
s when the asset(s) has been
saved to disk.
Example
const [{ localUri }] = await Asset.loadAsync(require('./assets/snack-icon.png'));
AssetDescriptor
Name | Type | Description |
---|---|---|
hash (optional) | string | null | - |
height (optional) | number | null | - |
name | string | - |
type | string | - |
uri | string | - |
width (optional) | number | null | - |
AssetMetadata
Type: Pick<PackagerAsset, 'httpServerLocation' | 'name' | 'hash' | 'type' | 'scales' | 'width' | 'height'>
extended by:
Name | Type | Description |
---|---|---|
fileHashes (optional) | string[] | - |
fileUris (optional) | string[] | - |
uri (optional) | string | - |