Assets

Learn about using static assets in your project, including images, videos, sounds, database files, and fonts.

A static asset is a file that is bundled with your app's binary (native binary). This file type is not part of your app's JavaScript bundle which contain your app's code. Common types of static assets include images, videos, sounds, database files for SQLite, and fonts. These assets can be served locally from your project or remotely over the network.

This guide covers different ways you can load and use static assets in your project and also provides additional information on how to optimize and minify assets.

Serve an asset locally

When an asset is stored in your project's file system, it can be embedded in your app binary at build time or loaded at runtime. You can import it like a JavaScript module using require or import statements.

For example, to render an image called example.png in App.js, you can use require to import the image from the project's assets/images directory and pass it to the <Image> component:

<Image source={require('./assets/images/example.png')} />

In the above example, the bundler reads the imported image's metadata and automatically provides the width and height. For more information, see Static Image Resources.

Libraries such as expo-image and expo-file-system work similarly to the <Image> component with local assets.

How are assets served locally

Locally stored assets are served over HTTP in development. They are automatically bundled into your app binary at the build time for production apps and served from disk on a device.

Load an asset at build time with expo-asset config plugin

Note: The expo-asset config plugin is only available for SDK 51 and above. If you are using an older SDK, you can load a using the useAssets hook.

To load an asset at build time, you can use the config plugin from the expo-asset library. This plugin will embed the asset file in your native project.

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

import { Image } from 'expo-image';
%%placeholder-start%%... %%placeholder-end%%

export default function HomeScreen() {
  return <Image source="example" />;
}

The above example is quite concise. However, when a native API expects a specific file and its resource name, this method makes it convenient to integrate with that API and use the resource name directly.

Different file formats are supported with the expo-asset config plugin. For more information on these formats, see Assets API reference. If you don't see a file format supported by the config plugin, you can use the useAssets hook to load the asset at runtime.

Load an asset at runtime with useAssets hook

The useAssets hook from expo-asset library allows loading assets asynchronously. This hook downloads and stores an asset locally and after the asset is loaded, it returns a list of that asset's instances.

import { useAssets } from 'expo-asset';

export default function HomeScreen() {
  const [assets, error] = useAssets([
    require('path/to/example-1.jpg'),
    require('path/to/example-2.png'),
  ]);

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

Serve an asset remotely

When an asset is served remotely, it is not bundled into the app binary at build time. You can use the URL of the asset resource in your project if it is hosted remotely. For example, pass the URL to the <Image> component to render a remote image:

import { Image } from 'expo-image';
%%placeholder-start%%... %%placeholder-end%%

function App() {
  return (
    <Image source={{ uri: 'https://example.com/logo.png' }} style={{ width: 50, height: 50 }} />
  );
}

There is no guarantee about the availability of images served remotely using a web URL because an internet connection may not be available, or the asset might be removed.

Additionally, loading assets remotely also requires you to provide an asset's metadata. In the above example, since the bundler cannot retrieve the image's width and height, those values are passed explicitly to the <Image> component. If you don't, the image will default to 0px by 0px.

Additional information

Manual optimization methods

Images

You can compress images using the following:

• guetzli
• pngcrush
• optipng

Some image optimizers are lossless. They re-encode your image to be smaller without any change or loss in the pixels displayed. When you need each pixel to be untouched from the original image, a lossless optimizer and a lossless image format like PNG are a good choice.

Other image optimizers are lossy. The optimized image differs from the original image. Often, lossy optimizers are more efficient because they discard visual information that reduces file size while making the image look nearly identical to humans. Tools like imagemagick can use comparison algorithms like SSIM to show how similar two images look. It's quite common for an optimized image that is over 95% similar to the original image to be far less than 95% of the original file size.

Other assets

For assets like GIFs or videos, or non-code and non-image assets, it's up to you to optimize and minify those assets.

Note: GIFs are a very inefficient format. Modern video codecs can produce significantly smaller file sizes with better quality.

Fonts

See Add a custom font for more information on how to add a custom font to your app.