React Native's Image Component

Why it exists

Mobile apps need a performant way to display images from different sources, like the network or local files. React Native abstracts the platform-specific image views (like UIImageView on iOS and Fresco on Android) into a single, cross-platform component, simplifying development.

The mental model

Think of the Image component as a specialized View designed for one job: rendering a picture. It handles the underlying complexity of fetching remote images, decoding them, and displaying them, while giving you hooks to manage loading states and presentation.

How it works

You provide a source prop to tell the component where to find the image. For static assets bundled with your app, you use require('./path/to/image.png'). For network images, you provide an object: { uri: 'https://...' }. Because React Native can't know the dimensions of a remote image before downloading it, you must provide an explicit width and height in the style prop for network images. The component then uses the native platform's image-loading library to fetch, cache, and display the image.

When to use it

Use this component whenever you need to display a raster image (like a PNG or JPG). This includes user avatars from an API, icons bundled with your app, photos from the camera roll, or background images (using the related ImageBackground component). It's also useful for showing placeholders or loading indicators while the main image downloads, using props like defaultSource or loadingIndicatorSource.

When not to use it

For simple vector graphics or icons, a library like react-native-vector-icons might be a better choice. It uses font files or SVG, which can be scaled and colored more easily than static images. For complex background effects that involve more than a single image, a custom View with other child elements might be more flexible.

One canonical example

A classic use case is displaying a logo from a URL. You pass an object to the source prop with a uri key pointing to the image's web address. Crucially, you must also provide a style prop with explicit width and height values. Without these styles, the image will have zero dimensions and be invisible on the screen.