'data:
/>
<Image
style={{width: 50, height: 50}}
- source={{uri: 'https://facebook.github.io/react/img/logo_og.png'}}
+ source={{uri: 'https://facebook.github.io/react/logo-og.png'}}
/>
<Image
style={{width: 66, height: 58}}
@@ -25,7 +25,7 @@ as well as one from network and even from data provided in the 'data:
}
// skip this line if using Create React Native App
-AppRegistry.registerComponent('DisplayAnImage', () => DisplayAnImage);You can also add style to an image:
import React, { Component } from 'react';
+AppRegistry.registerComponent('DisplayAnImage', () => DisplayAnImage);You can also add style to an image:
import React, { Component } from 'react';
import { AppRegistry, View, Image, StyleSheet } from 'react-native';
const styles = StyleSheet.create({
diff --git a/releases/next/docs/images.html b/releases/next/docs/images.html
index f5d56da54f7..0e0d0b451e5 100644
--- a/releases/next/docs/images.html
+++ b/releases/next/docs/images.html
@@ -12,12 +12,12 @@
// GOOD
var icon = this.props.active ? require('./my-icon-active.png') : require('./my-icon-inactive.png');
<Image source={icon} />Note that image sources required this way include size (width, height) info for the Image. If you need to scale the image dynamically (i.e. via flex), you may need to manually set { width: undefined, height: undefined } on the style attribute.
Static Non-Image Resources #
The require syntax described above can be used to statically include audio, video or document files in your project as well. Most common file types are supported including .mp3, .wav, .mp4, .mov, .html and .pdf. See packager defaults for the full list.
You can add support for other types by creating a packager config file (see the packager config file for the full list of configuration options).
A caveat is that videos must use absolute positioning instead of flexGrow, since size info is not currently passed for non-image assets. This limitation doesn't occur for videos that are linked directly into Xcode or the Assets folder for Android.
Images From Hybrid App's Resources #
If you are building a hybrid app (some UIs in React Native, some UIs in platform code) you can still use images that are already bundled into the app.
For images included via Xcode asset catalogs or in the Android drawable folder, use the image name without the extension:
<Image source={{uri: 'app_icon'}} style={{width: 40, height: 40}} />For images in the Android assets folder, use the asset:/ scheme:
<Image source={{uri: 'asset:/app_icon.png'}} style={{width: 40, height: 40}} />These approaches provide no safety checks. It's up to you to guarantee that those images are available in the application. Also you have to specify image dimensions manually.
Network Images #
Many of the images you will display in your app will not be available at compile time, or you will want to load some dynamically to keep the binary size down. Unlike with static resources, you will need to manually specify the dimensions of your image. It's highly recommended that you use https as well in order to satisfy App Transport Security requirements on iOS.
// GOOD
-<Image source={{uri: 'https://facebook.github.io/react/img/logo_og.png'}}
+<Image source={{uri: 'https://facebook.github.io/react/logo-og.png'}}
style={{width: 400, height: 400}} />
// BAD
-<Image source={{uri: 'https://facebook.github.io/react/img/logo_og.png'}} />Network Requests for Images #
If you would like to set such things as the HTTP-Verb, Headers or a Body along with the image request, you may do this by defining these properties on the source object:
<Image source={{
- uri: 'https://facebook.github.io/react/img/logo_og.png',
+<Image source={{uri: 'https://facebook.github.io/react/logo-og.png'}} />Network Requests for Images #
If you would like to set such things as the HTTP-Verb, Headers or a Body along with the image request, you may do this by defining these properties on the source object:
<Image source={{
+ uri: 'https://facebook.github.io/react/logo-og.png',
method: 'POST',
headers: {
Pragma: 'no-cache'
@@ -31,7 +31,7 @@ regardless of its age or expiration date. If there is no existing data in the ca
corresponding the request, the data is loaded from the originating source.only-if-cached: The existing cache data will be used to satisfy a request, regardless of
its age or expiration date. If there is no existing data in the cache corresponding
to a URL load request, no attempt is made to load the data from the originating source,
-and the load is considered to have failed.Local Filesystem Images #
See CameraRoll for an example of
using local resources that are outside of Images.xcassets.
Best Camera Roll Image #
iOS saves multiple sizes for the same image in your Camera Roll, it is very important to pick the one that's as close as possible for performance reasons. You wouldn't want to use the full quality 3264x2448 image as source when displaying a 200x200 thumbnail. If there's an exact match, React Native will pick it, otherwise it's going to use the first one that's at least 50% bigger in order to avoid blur when resizing from a close size. All of this is done by default so you don't have to worry about writing the tedious (and error prone) code to do it yourself.
Why Not Automatically Size Everything? #
In the browser if you don't give a size to an image, the browser is going to render a 0x0 element, download the image, and then render the image based with the correct size. The big issue with this behavior is that your UI is going to jump all around as images load, this makes for a very bad user experience.
In React Native this behavior is intentionally not implemented. It is more work for the developer to know the dimensions (or aspect ratio) of the remote image in advance, but we believe that it leads to a better user experience. Static images loaded from the app bundle via the require('./my-icon.png') syntax can be automatically sized because their dimensions are available immediately at the time of mounting.
For example, the result of require('./my-icon.png') might be:
{"__packager_asset":true,"uri":"my-icon.png","width":591,"height":573}Source as an object #
In React Native, one interesting decision is that the src attribute is named source and doesn't take a string but an object with a uri attribute.
<Image source={{uri: 'something.jpg'}} />On the infrastructure side, the reason is that it allows us to attach metadata to this object. For example if you are using require('./my-icon.png'), then we add information about its actual location and size (don't rely on this fact, it might change in the future!). This is also future proofing, for example we may want to support sprites at some point, instead of outputting {uri: ...}, we can output {uri: ..., crop: {left: 10, top: 50, width: 20, height: 40}} and transparently support spriting on all the existing call sites.
On the user side, this lets you annotate the object with useful attributes such as the dimension of the image in order to compute the size it's going to be displayed in. Feel free to use it as your data structure to store more information about your image.
Background Image via Nesting #
A common feature request from developers familiar with the web is background-image. To handle this use case, you can use the <ImageBackground> component, which has the same props as <Image>, and add whatever children to it you would like to layer on top of it.
You might not want to use <ImageBackground> in some cases, since the implementation is very simple. Refer to <ImageBackground>'s source code for more insight, and create your own custom component when needed.
return (
<ImageBackground source={...}>