expo-asset

Download and manage app assets efficiently across all platforms

expo-asset

Version: 55.0.5

A universal module to download assets and pass them into other APIs. Simplifies asset management by providing automatic caching, downloading, and local URI access for bundled and remote assets.

Installation

npx expo install expo-asset

Usage

import { Asset } from 'expo-asset';

// Load a bundled asset
const asset = Asset.fromModule(require('./assets/image.png'));
await asset.downloadAsync();

// Use the local URI
console.log(asset.localUri);

API Reference

Asset Class

name · string

The name of the asset file

type · string

The file extension/type (e.g., ‘png’, ‘jpg’, ‘mp4’)

hash · string | null

The MD5 hash of the asset’s content

uri · string

The URI that points to the asset’s location (local or remote)

localUri · string | null

The local filesystem URI after the asset is downloaded. null if not yet downloaded.

width · number | null

Width in pixels for image assets

height · number | null

Height in pixels for image assets

downloaded · boolean

Whether the asset has been downloaded to the local filesystem

Methods

Asset.fromModule(module) · (module: number) => Asset

Creates an Asset instance from a require() statement

const asset = Asset.fromModule(require('./logo.png'));

Asset.fromURI(uri) · (uri: string) => Asset

Creates an Asset instance from a URI string

const asset = Asset.fromURI('https://example.com/image.png');

Asset.loadAsync(modules) · (modules: number | number[]) => Promise<void>

Loads and caches assets by require() module IDs

await Asset.loadAsync([
  require('./image1.png'),
  require('./image2.png')
]);

asset.downloadAsync() · () => Promise<void>

Downloads the asset to the local filesystem if not already downloaded

const asset = Asset.fromModule(require('./video.mp4'));
await asset.downloadAsync();
console.log(asset.localUri); // file:/// path

Examples

Preload Assets on App Start

import { Asset } from 'expo-asset';
import * as SplashScreen from 'expo-splash-screen';
import { useEffect, useState } from 'react';

// Prevent splash screen from auto-hiding
SplashScreen.preventAutoHideAsync();

function App() {
  const [isReady, setIsReady] = useState(false);
  
  useEffect(() => {
    async function prepare() {
      try {
        // Preload assets
        await Asset.loadAsync([
          require('./assets/images/logo.png'),
          require('./assets/images/background.jpg'),
          require('./assets/videos/intro.mp4')
        ]);
      } catch (error) {
        console.warn(error);
      } finally {
        setIsReady(true);
        await SplashScreen.hideAsync();
      }
    }
    
    prepare();
  }, []);
  
  if (!isReady) {
    return null;
  }
  
  return <YourApp />;
}

Use with Image Component

import { Asset } from 'expo-asset';
import { Image } from 'react-native';
import { useEffect, useState } from 'react';

function ImageWithAsset() {
  const [asset, setAsset] = useState<Asset | null>(null);
  
  useEffect(() => {
    async function loadAsset() {
      const img = Asset.fromModule(require('./image.png'));
      await img.downloadAsync();
      setAsset(img);
    }
    loadAsset();
  }, []);
  
  if (!asset?.localUri) {
    return null;
  }
  
  return (
    <Image
      source={{ uri: asset.localUri }}
      style={{ width: asset.width, height: asset.height }}
    />
  );
}

Load Remote Asset

import { Asset } from 'expo-asset';

async function downloadRemoteImage() {
  const asset = Asset.fromURI('https://example.com/image.jpg');
  
  // Download to cache
  await asset.downloadAsync();
  
  // Now available locally
  console.log('Downloaded to:', asset.localUri);
  
  return asset;
}

Pass to Video Player

import { Asset } from 'expo-asset';
import { Video } from 'expo-av';
import { useEffect, useState } from 'react';

function VideoPlayer() {
  const [videoUri, setVideoUri] = useState<string | null>(null);
  
  useEffect(() => {
    async function prepareVideo() {
      const asset = Asset.fromModule(require('./video.mp4'));
      await asset.downloadAsync();
      setVideoUri(asset.localUri);
    }
    prepareVideo();
  }, []);
  
  if (!videoUri) {
    return null;
  }
  
  return (
    <Video
      source={{ uri: videoUri }}
      style={{ width: 300, height: 200 }}
      useNativeControls
    />
  );
}

Batch Asset Loading

import { Asset } from 'expo-asset';

const imageAssets = [
  require('./assets/1.png'),
  require('./assets/2.png'),
  require('./assets/3.png')
];

const soundAssets = [
  require('./assets/sound1.mp3'),
  require('./assets/sound2.mp3')
];

async function cacheAssets() {
  const images = Asset.loadAsync(imageAssets);
  const sounds = Asset.loadAsync(soundAssets);
  
  await Promise.all([images, sounds]);
  console.log('All assets loaded!');
}

Asset with Dimensions

import { Asset } from 'expo-asset';

async function getImageDimensions() {
  const asset = Asset.fromModule(require('./photo.jpg'));
  await asset.downloadAsync();
  
  return {
    uri: asset.localUri,
    width: asset.width,
    height: asset.height,
    aspectRatio: asset.width! / asset.height!
  };
}

Custom Asset Hook

import { Asset } from 'expo-asset';
import { useEffect, useState } from 'react';

function useAsset(moduleId: number) {
  const [asset, setAsset] = useState<Asset | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);
  
  useEffect(() => {
    async function loadAsset() {
      try {
        const loaded = Asset.fromModule(moduleId);
        await loaded.downloadAsync();
        setAsset(loaded);
      } catch (err) {
        setError(err as Error);
      } finally {
        setLoading(false);
      }
    }
    loadAsset();
  }, [moduleId]);
  
  return { asset, loading, error };
}

// Usage
function MyComponent() {
  const { asset, loading, error } = useAsset(require('./image.png'));
  
  if (loading) return <Text>Loading...</Text>;
  if (error) return <Text>Error: {error.message}</Text>;
  
  return <Image source={{ uri: asset!.localUri! }} />;
}

App Plugin Configuration

For asset optimization during build:

app.json:

{
  "expo": {
    "plugins": [
      [
        "expo-asset",
        {
          "assets": ["./assets/images", "./assets/fonts"]
        }
      ]
    ]
  }
}

TypeScript

import { Asset } from 'expo-asset';

const asset: Asset = Asset.fromModule(require('./image.png'));

await asset.downloadAsync();

const uri: string | null = asset.localUri;
const width: number | null = asset.width;
const downloaded: boolean = asset.downloaded;

Platform Support

Platform	Supported
iOS	✅
Android	✅
Web	✅

On web, assets are loaded via HTTP and “downloading” is essentially ensuring they’re loaded in the browser cache.

Best Practices

1. Preload Critical Assets: Load essential assets during app initialization
2. Use Asset Caching: Assets are automatically cached after first download
3. Handle Errors: Wrap downloadAsync() in try/catch blocks
4. Batch Loading: Use Asset.loadAsync() for multiple assets
5. Check Downloaded State: Verify asset.downloaded before using localUri

Resources

• Official Documentation
• GitHub Repository