React NativeImages #
Static Image Resources #
As of 0.14 release, React Native provides a unified way of managing images in your iOS and Android apps. To add a static image to your app, place it somewhere in your source code tree and reference it like this:
The image name is resolved the same way JS modules are resolved. In the example above the packager will look for my-icon.png in the same folder as the component that requires it. Also if you have my-icon.ios.png and my-icon.android.png, the packager will pick the file depending on the platform you are running on.
You can also use @2x, @3x, etc. suffix in the file name to provide images for different screen densities. For example, if you have the following file structure:
Images #
Static Image Resources #
React Native provides a unified way of managing images in your iOS and Android apps. To add a static image to your app, place it somewhere in your source code tree and reference it like this:
The image name is resolved the same way JS modules are resolved. In the example above, the packager will look for my-icon.png in the same folder as the component that requires it. Also, if you have my-icon.ios.png and my-icon.android.png, the packager will pick the correct file for the platform.
You can also use the @2x and @3x suffixes to provide images for different screen densities. If you have the following file structure:
And button.js code contains
Packager will bundle and serve the image corresponding to the device's screen density, e.g. on iPhone 5s check@2x.png will be used, on Nexus 5 – check@3x.png. If there is no image matching the screen density, the closest best option will be selected.
On Windows, you might need to restart the packager if you add new images to your project.
Here are some benefits that you get:
- Same system on iOS and Android.
- Images live in the same folder as your JS code. Components are self-contained.
- No global namespace, i.e. you don't have to worry about name collisions.
- Only the images that are actually used will be packaged into your app.
- Adding and changing images doesn't require app recompilation, just refresh the simulator as you normally do.
- The packager knows the image dimensions, no need to duplicate it in the code.
- Images can be distributed via npm packages.
Note that in order for this to work, the image name in require has to be known statically.
...and button.js code contains:
...the packager will bundle and serve the image corresponding to device's screen density. For example, check@2x.png, will be used on an iPhone 7, whilecheck@3x.png will be used on an iPhone 7 Plus or a Nexus 5. If there is no image matching the screen density, the closest best option will be selected.
On Windows, you might need to restart the packager if you add new images to your project.
Here are some benefits that you get:
- Same system on iOS and Android.
- Images live in the same folder as your JavaScript code. Components are self-contained.
- No global namespace, i.e. you don't have to worry about name collisions.
- Only the images that are actually used will be packaged into your app.
- Adding and changing images doesn't require app recompilation, just refresh the simulator as you normally do.
- The packager knows the image dimensions, no need to duplicate it in the code.
- Images can be distributed via npm packages.
In order for this to work, the image name in require has to be known statically.
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.
Available React Native 0.14+. If you've generated your project with 0.13 or earlier, read this. The new asset system relies on build hooks for Xcode and Gradle that are included in new projects generated with react-native init. If you generated your projects before that, you'll have to manually add them to your projects to use the new images asset system. See Upgrading for instructions on how to do this.
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 (via Xcode asset catalogs or Android drawable folder):
Note that this approach provides 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.
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.
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 (via Xcode asset catalogs or Android drawable folder):
This approach provides 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.