Working with Images and Media
1. Loading Local Images
| Property | Description | Example |
|---|---|---|
| source | Specifies the image to load. Can be a local file path or URI. | source={require('./assets/image.png')} |
| resizeMode | Determines how the image should be resized to fit its container. | resizeMode="cover" |
Example: Loading a Local Image
import React from 'react';
import { Image } from 'react-native';
const MyImage = () => {
return (
<Image
source={require('./assets/logo.png')}
style={{ width: 200, height: 100 }}
/>
);
};
export default MyImage;
Note: Local images must be imported using
require() at compile time. Dynamic image paths are not supported.
2. Loading Remote Images
| Property | Description | Default | Notes |
|---|---|---|---|
| source | Image source, can be a remote URL or local asset | None | Required field |
| resizeMode | How to resize the image within its bounds | cover |
Options: cover, contain, stretch, repeat, center |
| loadingIndicatorSource | Image to show while loading remote image | None | Can be a local or remote image |
Example: Loading a Remote Image
import React from 'react';
import { Image } from 'react-native';
const RemoteImage = () => (
<Image
source={{ uri: 'https://example.com/image.jpg' }}
style={{ width: 200, height: 200 }}
/>
);
export default RemoteImage;
Note: Remote images must be loaded over HTTPS to comply with security policies on iOS and Android.
Warning: Avoid using
resizeMode: stretch for remote images as it can cause distortion.
3. Handling Image Caching
| Property | Description | Default |
|---|---|---|
| cache | Controls caching behavior for images. Can be 'default', 'reload', or 'force-cache'. |
'default' |
| resizeMode | How to resize the image if it doesn't fit the container. Options: 'cover', 'contain', 'stretch', 'repeat', 'center'. |
'cover' |
Example: Using cache property
<Image
source={{ uri: 'https://example.com/image.jpg', cache: 'force-cache' }}
style={{ width: 200, height: 200 }}
/>
Note: The
cache property is particularly useful for images that are frequently reused, such as app icons or user avatars.
4. Using Image Resize Modes
| Mode | Description | Usage |
|---|---|---|
| cover | Image is scaled to maintain aspect ratio and fill the container, potentially cropping the image. | resizeMode="cover" |
| contain | Image is scaled to maintain aspect ratio and fit within the container, potentially leaving empty space. | resizeMode="contain" |
| stretch | Image is stretched to fill the container, potentially distorting the image. | resizeMode="stretch" |
| repeat | Image is repeated to fill the container, useful for patterns or backgrounds. | resizeMode="repeat" |
| center | Image is centered within the container without scaling. | resizeMode="center" |
Example: Image Resize Mode Usage
<Image
source={{ uri: 'https://example.com/image.jpg' }}
style={{ width: 200, height: 200 }}
resizeMode="cover"
/>5. Implementing Image Placeholders
Example: Basic Image Placeholder
<Image
source={{ uri: 'https://example.com/image.jpg' }}
style={{ width: 200, height: 200 }}
placeholder={{ uri: 'https://example.com/placeholder.jpg' }}
/>| Property | Values | Description |
|---|---|---|
| placeholder | string | object |
URI or image object to use as placeholder |
| placeholderStyle | object |
Styles to apply to the placeholder image |
Note: The
placeholder property supports both URI strings and image objects for more complex placeholder configurations.
Example: Placeholder with Style
<Image
source={{ uri: 'https://example.com/image.jpg' }}
style={{ width: 200, height: 200 }}
placeholder={{
uri: 'https://example.com/placeholder.jpg',
}}
placeholderStyle={{
resizeMode: 'cover',
opacity: 0.7,
}}
/>6. Handling Image Loading States
| State | Description | Usage |
|---|---|---|
| loading | Indicates that the image is currently loading. | Use to show a spinner or placeholder while image loads. |
| error | Indicates that the image failed to load. | Use to display an error message or fallback image. |
| success | Indicates that the image loaded successfully. | Use to display the actual image content. |
Example: Image Loading State Handling
import React, { useState } from 'react';
import { Image } from 'react-native';
const ImageWithLoading = ({ source }) => {
const [loading, setLoading] = useState(true);
const [error, setError] = useState(false);
const handleLoad = () => {
setLoading(false);
};
const handleError = () => {
setLoading(false);
setError(true);
};
return (
<Image
source={source}
onLoad={handleLoad}
onError={handleError}
style={{ width: 200, height: 200 }}
>
{loading && <View style={{ flex: 1, justifyContent: 'center' }}><ActivityIndicator /></View>}
{error && <View style={{ flex: 1, justifyContent: 'center' }}><Text>Failed to load image</Text></View>}
</Image>
);
};
Note: The
onLoad and onError props are essential for handling image loading states effectively.
7. Using ImageBackground Component
| Property | Values | Description |
|---|---|---|
| source | number | { uri: string } | Array<{ uri: string }> |
Image to display. Can be a local image or remote URL. |
| resizeMode | cover | contain | stretch | repeat | center |
How to resize the image if it doesn't fit the container. |
| imageStyle | style object |
Additional style to apply to the image. |
| children | ReactNode |
Content to overlay on top of the image. |
Example: Basic ImageBackground Usage
import React from 'react';
import { ImageBackground, Text, View } from 'react-native';
const BackgroundImageExample = () => {
return (
<ImageBackground
source={{ uri: 'https://example.com/image.jpg' }}
style={{ width: 300, height: 200 }}
>
<View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
<Text style={{ color: 'white', fontSize: 20 }}>Overlay Text</Text>
</View>
</ImageBackground>
);
};
export default BackgroundImageExample;
Note: The
ImageBackground component is a wrapper around the Image component and supports all of its properties, in addition to the specific background-related ones.
8. Optimizing Image Performance
Example: Using Image Resize Mode
import { Image } from 'react-native';
<Image
source={{ uri: 'https://example.com/image.jpg' }}
style={{ width: 200, height: 200 }}
resizeMode="cover"
/>| Property | Values | Description |
|---|---|---|
| resizeMode | cover, contain, stretch, repeat, center |
How to resize the image to fit the view |
Note: Using
resizeMode can prevent unnecessary image scaling and improve rendering performance.
Example: Preloading Images
import { Image } from 'react-native';
Image.prefetch('https://example.com/image.jpg')
.then(() => console.log("Image preloaded"))
.catch(err => console.error("Error preloading image:", err));Example: Using Local Images for Better Performance
import { Image } from 'react-native';
<Image
source={require("./assets/image.png")}
style={{ width: 100, height: 100 }}
/>Image Performance Tips
- Use local image assets for faster loading
- Preload images when possible to reduce load times
- Choose appropriate
resizeModeto avoid unnecessary scaling - Optimize image sizes and formats for mobile devices
9. Supporting Multiple Image Densities
| Resolution | Scale Factor | File Suffix | Usage |
|---|---|---|---|
| 1x | 1 |
@1x |
Base resolution for standard displays |
| 2x | 2 |
@2x |
High-DPI displays (e.g., Retina) |
| 3x | 3 |
@3x |
Ultra-high DPI displays (e.g., iPhone X) |
Example: Using Multiple Image Densities
import { Image } from 'react-native';
<Image
source={require('./assets/images/logo@1x.png')}
style={{ width: 100, height: 100 }}
/>
Note: React Native automatically selects the appropriate image based on device pixel density.
Warning: If an image is not provided for a specific density, React Native will scale the base image, potentially causing pixelation or blurriness.
10. Implementing Progressive Image Loading
Progressive image loading improves perceived performance by displaying a low-quality version of an image first, followed by the full-resolution image once it's loaded.
| Property | Description | Values |
|---|---|---|
| blurRadius | Applies a blur effect to the placeholder image | number |
| resizeMode | How the image should be resized to fit its container | cover | contain | stretch | repeat | center |
| progressiveRenderingEnabled | Enables progressive loading for images | true | false |
Example: Using blurRadius for progressive loading
<Image
source={{ uri: 'https://example.com/image.jpg' }}
blurRadius={10}
style={{ width: 300, height: 200 }}
/>Example: Enabling progressive rendering
<Image
source={{ uri: 'https://example.com/large-image.jpg' }}
progressiveRenderingEnabled={true}
style={{ width: 400, height: 300 }}
/>
Note: Progressive rendering is supported on iOS and Android, but may not work as expected on web platforms.
11. Using FastImage for Performance
Example: Basic FastImage Usage
<FastImage
style={styles.image}
source={{
uri: 'https://example.com/image.jpg',
}}
/>| Property | Description | Values | Notes |
|---|---|---|---|
| source | Image source configuration | object |
Required. Supports local and remote URIs |
| style | Styling for the image | object |
Accepts standard React Native style properties |
| cache | Cache policy for image loading | 'default' | 'force-cache' | 'no-cache' |
Improves performance by caching images |
| resizeMode | How image scales to fit container | 'cover' | 'contain' | 'stretch' | 'repeat' | 'center' |
Defaults to 'cover' |
Note: FastImage is a drop-in replacement for
Image that provides better performance, especially for remote images.
Warning: FastImage does not support SVGs natively. For SVG support, consider using
react-native-svg.