React NativeActivityIndicatorIOS # | Edit on GitHub |
Props #
animating bool #
Whether to show the indicator (true, the default) or hide it (false).
color string #
The foreground color of the spinner (default is gray).
hidesWhenStopped bool #
Whether the indicator should hide when not animating (true by default).
onLayout function #
Invoked on mount and layout changes with
{nativeEvent: { layout: {x, y, width, height}}}.
size enum('small', 'large') #
Size of the indicator. Small has a height of 20, large has a height of 36.
Examples # | Edit on GitHub |
ActivityIndicatorIOS # | Edit on GitHub |
Props #
animating bool #
Whether to show the indicator (true, the default) or hide it (false).
color string #
The foreground color of the spinner (default is gray).
hidesWhenStopped bool #
Whether the indicator should hide when not animating (true by default).
onLayout function #
Invoked on mount and layout changes with
{nativeEvent: { layout: {x, y, width, height}}}.
size enum('small', 'large') #
Size of the indicator. Small has a height of 20, large has a height of 36.
Examples # | Edit on GitHub |
Android Setup # | Edit on GitHub |
This guide describes basic steps of the Android development environment setup that are required to run React Native android apps on an android emulator. We don't discuss developer tool configuration such as IDEs here.
Install Git #
On Mac, if you have installed XCode, Git is already installed, otherwise run the following:
brew install gitOn Linux, install Git via your package manager.
On Windows, download and install Git for Windows. During the setup process, choose "Run Git from Windows Command Prompt", which will add Git to your
PATHenvironment variable.
Install the Android SDK (unless you have it) #
- Install the latest JDK
- Install the Android SDK:
- On Mac:
brew install android-sdk - On Linux and Windows: Download from the Android website
- On Mac:
Define the ANDROID_HOME environment variable #
IMPORTANT: Make sure the ANDROID_HOME environment variable points to your existing Android SDK:
On Mac, add this to your
~/.bashrc,~/.bash_profileor whatever your shell uses:# If you installed the SDK via Homebrew, otherwise ~/Library/Android/sdk export ANDROID_HOME=/usr/local/opt/android-sdkOn Linux, add this to your
~/.bashrc,~/.bash_profileor whatever your shell uses:export ANDROID_HOME=<path_where_you_unpacked_android_sdk>On Windows, go to
Control Panel->System and Security->System->Change settings->Advanced->Environment variables->New
NOTE: You need to restart the Command Prompt (Windows) / Terminal Emulator (Mac OS X, Linux) to apply the new Environment variables.
Use gradle daemon #
React Native Android use gradle as a build system. We recommend to enable gradle daemon functionality which may result in up to 50% improvement in incremental build times for changes in java code. Learn here how to enable it for your platform.
Configure your SDK #
- Open the Android SDK Manager (on Mac start a new shell and run
android); in the window that appears make sure you check:- Android SDK Build-tools version 23.0.1
- Android 6.0 (API 23)
- Android Support Repository
- Click "Install Packages"
Install Genymotion #
Genymotion is much easier to set up than stock Google emulators. However, it's only free for personal use. If you want to use the stock Google emulator, see below.
- Download and install Genymotion.
- Open Genymotion. It might ask you to install VirtualBox unless you already have it.
- Create a new emulator and start it.
- To bring up the developer menu press ⌘+M
Alternative: Create a stock Google emulator #
- Start a new shell and run
android; in the window that appears make sure you check:- Intel x86 Atom System Image (for Android 5.1.1 - API 22)
- Intel x86 Emulator Accelerator (HAXM installer)
- Click "Install Packages".
- Configure hardware acceleration (HAXM), otherwise the emulator is going to be slow.
- Create an Android Virtual Device (AVD):
- Run
android avdand click on Create... -
- With the new AVD selected, click
Start...
- Run
- To bring up the developer menu press F2 (or install Frappé)
Windows Hyper-V Alternative #
The Visual Studio Emulator for Android is a free android emulator that is hardware accelerated via Hyper-V. It doesn't require you to install Visual Studio at all.
To use it with react-native you just have to add a key and value to your registry:
- Open the Run Command (Windows+R)
- Enter
regedit.exe - In the Registry Editor navigate to
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Android SDK Tools - Right Click on
Android SDK Toolsand chooseNew > String Value - Set the name to
Path - Double Click the new
PathKey and set the value toC:\Program Files\Android\sdk. The path value might be different on your machine.
You will also need to run the command adb reverse tcp:8081 tcp:8081 with this emulator.
Then restart the emulator and when it runs you can just do react-native run-android as usual.
Profiling Android UI Performance # | Edit on GitHub |
We try our best to deliver buttery-smooth UI performance by default, but sometimes that just isn't possible. Remember, Android supports 10k+ different phones and is generalized to support software rendering: the framework architecture and need to generalize across many hardware targets unfortunately means you get less for free relative to iOS. But sometimes, there are things you can improve (and many times it's not native code's fault at all!).
The first step for debugging this jank is to answer the fundamental question of where your time is being spent during each 16ms frame. For that, we'll be using a standard Android profiling tool called systrace. But first...
Make sure that JS dev mode is OFF!
You should see
__DEV__ === false, development-level warning are OFF, performance optimizations are ONin your application logs (which you can view usingadb logcat)
Profiling with Systrace #
Systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by markers start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.
Collecting a trace #
NOTE:
Systrace support was added in react-native
v0.15. You will need to build with that version to collect a trace.
First, connect a device that exhibits the stuttering you want to investigate to your computer via USB and get it to the point right before the navigation/animation you want to profile. Run systrace as follows
A quick breakdown of this command:
timeis the length of time the trace will be collected in secondssched,gfx, andvieware the android SDK tags (collections of markers) we care about:schedgives you information about what's running on each core of your phone,gfxgives you graphics info such as frame boundaries, andviewgives you information about measure, layout, and draw passes-a <your_package_name>enables app-specific markers, specifically the ones built into the React Native framework.your_package_namecan be found in theAndroidManifest.xmlof your app and looks likecom.example.app
Once the trace starts collecting, perform the animation or interaction you care about. At the end of the trace, systrace will give you a link to the trace which you can open in your browser.
Reading the trace #
After opening the trace in your browser (preferably Chrome), you should see something like this:
HINT: Use the WASD keys to strafe and zoom
Enable VSync highlighting #
The first thing you should do is highlight the 16ms frame boundaries if you haven't already done that. Check this checkbox at the top right of the screen:
You should see zebra stripes as in the screenshot above. If you don't, try profiling on a different device: Samsung has been known to have issues displaying vsyncs while the Nexus series is generally pretty reliable.
Find your process #
Scroll until you see (part of) the name of your package. In this case, I was profiling com.facebook.adsmanager, which shows up as book.adsmanager because of silly thread name limits in the kernel.
On the left side, you'll see a set of threads which correspond to the timeline rows on the right. There are three/four threads we care about for our purposes: the UI thread (which has your package name or the name UI Thread), mqt_js and mqt_native_modules. If you're running on Android 5+, we also care about the Render Thread.
UI Thread #
This is where standard android measure/layout/draw happens. The thread name on the right will be your package name (in my case book.adsmanager) or UI Thread. The events that you see on this thread should look something like this and have to do with Choreographer, traversals, and DispatchUI:
JS Thread #
This is where JS is executed. The thread name will be either mqt_js or <...> depending on how cooperative the kernel on your device is being. To identify it if it doesn't have a name, look for things like JSCall, Bridge.executeJSCall, etc:
Native Modules Thread #
This is where native module calls (e.g. the UIManager) are executed. The thread name will be either mqt_native_modules or <...>. To identify it in the latter case, look for things like NativeCall, callJavaModuleMethod, and onBatchComplete:
Bonus: Render Thread #
If you're using Android L (5.0) and up, you will also have a render thread in your application. This thread generates the actual OpenGL commands used to draw your UI. The thread name will be either RenderThread or <...>. To identify it in the latter case, look for things like DrawFrame and queueBuffer:
Identifying a culprit #
A smooth animation should look something like the following:
Each change in color is a frame -- remember that in order to display a frame, all our UI work needs to be done by the end of that 16ms period. Notice that no thread is working close to the frame boundary. An application rendering like this is rendering at 60FPS.
If you noticed chop, however, you might see something like this:
Notice that the JS thread is executing basically all the time, and across frame boundaries! This app is not rendering at 60FPS. In this case, the problem lies in JS.
You might also see something like this:
In this case, the UI and render threads are the ones that have work crossing frame boundaries. The UI that we're trying to render on each frame is requiring too much work to be done. In this case, the problem lies in the native views being rendered.
At this point, you'll have some very helpful information to inform your next steps.
JS Issues #
If you identified a JS problem, look for clues in the specific JS that you're executing. In the scenario above, we see RCTEventEmitter being called multiple times per frame. Here's a zoom-in of the JS thread from the trace above:
This doesn't seem right. Why is it being called so often? Are they actually different events? The answers to these questions will probably depend on your product code. And many times, you'll want to look into shouldComponentUpdate.
TODO: Add more tools for profiling JS
Native UI Issues #
If you identified a native UI problem, there are usually two scenarios:
- the UI you're trying to draw each frame involves to much work on the GPU, or
- You're constructing new UI during the animation/interaction (e.g. loading in new content during a scroll).
Too much GPU work #
In the first scenario, you'll see a trace that has the UI thread and/or Render Thread looking like this:
Notice the long amount of time spent in DrawFrame that crosses frame boundaries. This is time spent waiting for the GPU to drain its command buffer from the previous frame.
To mitigate this, you should:
- investigate using
renderToHardwareTextureAndroidfor complex, static content that is being animated/transformed (e.g. theNavigatorslide/alpha animations) - make sure that you are not using
needsOffscreenAlphaCompositing, which is disabled by default, as it greatly increases the per-frame load on the GPU in most cases.
If these don't help and you want to dig deeper into what the GPU is actually doing, you can check out Tracer for OpenGL ES.
Creating new views on the UI thread #
In the second scenario, you'll see something more like this:
Notice that first the JS thread thinks for a bit, then you see some work done on the native modules thread, followed by an expensive traversal on the UI thread.
There isn't an easy way to mitigate this unless you're able to postpone creating new UI until after the interaction, or you are able to simplify the UI you're creating. The react native team is working on a infrastructure level solution for this that will allow new UI to be created and configured off the main thread, allowing the interaction to continue smoothly.
Still stuck? #
If you are confused or stuck, please post ask on Stack Overflow with the react-native tag. If you are unable to get a response there, or find an issue with a core component, please File a Github issue.
Profiling Android UI Performance # | Edit on GitHub |
We try our best to deliver buttery-smooth UI performance by default, but sometimes that just isn't possible. Remember, Android supports 10k+ different phones and is generalized to support software rendering: the framework architecture and need to generalize across many hardware targets unfortunately means you get less for free relative to iOS. But sometimes, there are things you can improve (and many times it's not native code's fault at all!).
The first step for debugging this jank is to answer the fundamental question of where your time is being spent during each 16ms frame. For that, we'll be using a standard Android profiling tool called systrace. But first...
Make sure that JS dev mode is OFF!
You should see
__DEV__ === false, development-level warning are OFF, performance optimizations are ONin your application logs (which you can view usingadb logcat)
Profiling with Systrace #
Systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by markers start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.
Collecting a trace #
NOTE:
Systrace support was added in react-native
v0.15. You will need to build with that version to collect a trace.
First, connect a device that exhibits the stuttering you want to investigate to your computer via USB and get it to the point right before the navigation/animation you want to profile. Run systrace as follows
A quick breakdown of this command:
timeis the length of time the trace will be collected in secondssched,gfx, andvieware the android SDK tags (collections of markers) we care about:schedgives you information about what's running on each core of your phone,gfxgives you graphics info such as frame boundaries, andviewgives you information about measure, layout, and draw passes-a <your_package_name>enables app-specific markers, specifically the ones built into the React Native framework.your_package_namecan be found in theAndroidManifest.xmlof your app and looks likecom.example.app
Once the trace starts collecting, perform the animation or interaction you care about. At the end of the trace, systrace will give you a link to the trace which you can open in your browser.
Reading the trace #
After opening the trace in your browser (preferably Chrome), you should see something like this:
HINT: Use the WASD keys to strafe and zoom
Enable VSync highlighting #
The first thing you should do is highlight the 16ms frame boundaries if you haven't already done that. Check this checkbox at the top right of the screen:
You should see zebra stripes as in the screenshot above. If you don't, try profiling on a different device: Samsung has been known to have issues displaying vsyncs while the Nexus series is generally pretty reliable.
Find your process #
Scroll until you see (part of) the name of your package. In this case, I was profiling com.facebook.adsmanager, which shows up as book.adsmanager because of silly thread name limits in the kernel.
On the left side, you'll see a set of threads which correspond to the timeline rows on the right. There are three/four threads we care about for our purposes: the UI thread (which has your package name or the name UI Thread), mqt_js and mqt_native_modules. If you're running on Android 5+, we also care about the Render Thread.
UI Thread #
This is where standard android measure/layout/draw happens. The thread name on the right will be your package name (in my case book.adsmanager) or UI Thread. The events that you see on this thread should look something like this and have to do with Choreographer, traversals, and DispatchUI:
JS Thread #
This is where JS is executed. The thread name will be either mqt_js or <...> depending on how cooperative the kernel on your device is being. To identify it if it doesn't have a name, look for things like JSCall, Bridge.executeJSCall, etc:
Native Modules Thread #
This is where native module calls (e.g. the UIManager) are executed. The thread name will be either mqt_native_modules or <...>. To identify it in the latter case, look for things like NativeCall, callJavaModuleMethod, and onBatchComplete:
Bonus: Render Thread #
If you're using Android L (5.0) and up, you will also have a render thread in your application. This thread generates the actual OpenGL commands used to draw your UI. The thread name will be either RenderThread or <...>. To identify it in the latter case, look for things like DrawFrame and queueBuffer:
Identifying a culprit #
A smooth animation should look something like the following:
Each change in color is a frame -- remember that in order to display a frame, all our UI work needs to be done by the end of that 16ms period. Notice that no thread is working close to the frame boundary. An application rendering like this is rendering at 60FPS.
If you noticed chop, however, you might see something like this:
Notice that the JS thread is executing basically all the time, and across frame boundaries! This app is not rendering at 60FPS. In this case, the problem lies in JS.
You might also see something like this:
In this case, the UI and render threads are the ones that have work crossing frame boundaries. The UI that we're trying to render on each frame is requiring too much work to be done. In this case, the problem lies in the native views being rendered.
At this point, you'll have some very helpful information to inform your next steps.
JS Issues #
If you identified a JS problem, look for clues in the specific JS that you're executing. In the scenario above, we see RCTEventEmitter being called multiple times per frame. Here's a zoom-in of the JS thread from the trace above:
This doesn't seem right. Why is it being called so often? Are they actually different events? The answers to these questions will probably depend on your product code. And many times, you'll want to look into shouldComponentUpdate.
TODO: Add more tools for profiling JS
Native UI Issues #
If you identified a native UI problem, there are usually two scenarios:
- the UI you're trying to draw each frame involves to much work on the GPU, or
- You're constructing new UI during the animation/interaction (e.g. loading in new content during a scroll).
Too much GPU work #
In the first scenario, you'll see a trace that has the UI thread and/or Render Thread looking like this:
Notice the long amount of time spent in DrawFrame that crosses frame boundaries. This is time spent waiting for the GPU to drain its command buffer from the previous frame.
To mitigate this, you should:
- investigate using
renderToHardwareTextureAndroidfor complex, static content that is being animated/transformed (e.g. theNavigatorslide/alpha animations) - make sure that you are not using
needsOffscreenAlphaCompositing, which is disabled by default, as it greatly increases the per-frame load on the GPU in most cases.
If these don't help and you want to dig deeper into what the GPU is actually doing, you can check out Tracer for OpenGL ES.
Creating new views on the UI thread #
In the second scenario, you'll see something more like this:
Notice that first the JS thread thinks for a bit, then you see some work done on the native modules thread, followed by an expensive traversal on the UI thread.
There isn't an easy way to mitigate this unless you're able to postpone creating new UI until after the interaction, or you are able to simplify the UI you're creating. The react native team is working on a infrastructure level solution for this that will allow new UI to be created and configured off the main thread, allowing the interaction to continue smoothly.
Still stuck? #
If you are confused or stuck, please post ask on Stack Overflow with the react-native tag. If you are unable to get a response there, or find an issue with a core component, please File a Github issue.
Debugging # | Edit on GitHub |
Debugging React Native Apps #
To access the in-app developer menu:
- On iOS shake the device or press
control + ⌘ + zin the simulator. - On Android shake the device or press hardware menu button (available on older devices and in most of the emulators, e.g. in genymotion you can press
⌘ + mto simulate hardware menu button click). You can also install Frappé, a tool for OS X, which allows you to emulate shaking of devices remotely. You can use⌘ + Shift + Ras a shortcut to trigger a shake from Frappé.
Hint
To disable the developer menu for production builds:
- For iOS open your project in Xcode and select
Product→Scheme→Edit Scheme...(or press⌘ + <). Next, selectRunfrom the menu on the left and change the Build Configuration toRelease.- For Android, by default, developer menu will be disabled in release builds done by gradle (e.g with gradle
assembleReleasetask). Although this behavior can be customized by passing proper value toReactInstanceManager#setUseDeveloperSupport.
Reload #
Selecting Reload (or pressing ⌘ + r in the iOS simulator) will reload the JavaScript that powers your application. If you have added new resources (such as an image to Images.xcassets on iOS or to res/drawable folder on Android) or modified any native code (Objective-C/Swift code on iOS or Java/C++ code on Android), you will need to re-build the app for the changes to take effect.
Chrome Developer Tools #
To debug the JavaScript code in Chrome, select Debug in Chrome from the developer menu. This will open a new tab at http://localhost:8081/debugger-ui.
In Chrome, press ⌘ + option + i or select View → Developer → Developer Tools to toggle the developer tools console. Enable Pause On Caught Exceptions for a better debugging experience.
To debug on a real device:
- On iOS - open the file
RCTWebSocketExecutor.mand changelocalhostto the IP address of your computer. Shake the device to open the development menu with the option to start debugging. - On Android, if you're running Android 5.0+ device connected via USB you can use
adbcommand line tool to setup port forwarding from the device to your computer. For that run:adb reverse tcp:8081 tcp:8081(see this link for help onadbcommand). Alternatively, you can open dev menu on the device and selectDev Settings, then updateDebug server host for devicesetting to the IP address of your computer.
React Developer Tools (optional) #
Install the React Developer Tools extension for Google Chrome. This will allow you to navigate the component hierarchy via the React in the developer tools (see facebook/react-devtools for more information).
Live Reload #
This option allows for your JS changes to trigger automatic reload on the connected device/emulator. To enable this option:
- On iOS, select
Enable Live Reloadvia the developer menu to have the application automatically reload when changes are made to the JavaScript. - On Android, launch dev menu, go to
Dev Settingsand selectAuto reload on JS changeoption
FPS (Frames per Second) Monitor #
On 0.5.0-rc and higher versions, you can enable a FPS graph overlay in the developers menu in order to help you debug performance problems.
Debugging # | Edit on GitHub |
Debugging React Native Apps #
To access the in-app developer menu:
- On iOS shake the device or press
control + ⌘ + zin the simulator. - On Android shake the device or press hardware menu button (available on older devices and in most of the emulators, e.g. in genymotion you can press
⌘ + mto simulate hardware menu button click). You can also install Frappé, a tool for OS X, which allows you to emulate shaking of devices remotely. You can use⌘ + Shift + Ras a shortcut to trigger a shake from Frappé.
Hint
To disable the developer menu for production builds:
- For iOS open your project in Xcode and select
Product→Scheme→Edit Scheme...(or press⌘ + <). Next, selectRunfrom the menu on the left and change the Build Configuration toRelease.- For Android, by default, developer menu will be disabled in release builds done by gradle (e.g with gradle
assembleReleasetask). Although this behavior can be customized by passing proper value toReactInstanceManager#setUseDeveloperSupport.
Reload #
Selecting Reload (or pressing ⌘ + r in the iOS simulator) will reload the JavaScript that powers your application. If you have added new resources (such as an image to Images.xcassets on iOS or to res/drawable folder on Android) or modified any native code (Objective-C/Swift code on iOS or Java/C++ code on Android), you will need to re-build the app for the changes to take effect.
Chrome Developer Tools #
To debug the JavaScript code in Chrome, select Debug in Chrome from the developer menu. This will open a new tab at http://localhost:8081/debugger-ui.
In Chrome, press ⌘ + option + i or select View → Developer → Developer Tools to toggle the developer tools console. Enable Pause On Caught Exceptions for a better debugging experience.
To debug on a real device:
- On iOS - open the file
RCTWebSocketExecutor.mand changelocalhostto the IP address of your computer. Shake the device to open the development menu with the option to start debugging. - On Android, if you're running Android 5.0+ device connected via USB you can use
adbcommand line tool to setup port forwarding from the device to your computer. For that run:adb reverse tcp:8081 tcp:8081(see this link for help onadbcommand). Alternatively, you can open dev menu on the device and selectDev Settings, then updateDebug server host for devicesetting to the IP address of your computer.
React Developer Tools (optional) #
Install the React Developer Tools extension for Google Chrome. This will allow you to navigate the component hierarchy via the React in the developer tools (see facebook/react-devtools for more information).
Live Reload #
This option allows for your JS changes to trigger automatic reload on the connected device/emulator. To enable this option:
- On iOS, select
Enable Live Reloadvia the developer menu to have the application automatically reload when changes are made to the JavaScript. - On Android, launch dev menu, go to
Dev Settingsand selectAuto reload on JS changeoption
FPS (Frames per Second) Monitor #
On 0.5.0-rc and higher versions, you can enable a FPS graph overlay in the developers menu in order to help you debug performance problems.
Flexbox # | Edit on GitHub |
Props #
alignItems enum('flex-start', 'flex-end', 'center', 'stretch') #
alignSelf enum('auto', 'flex-start', 'flex-end', 'center', 'stretch') #
borderBottomWidth number #
borderLeftWidth number #
borderRightWidth number #
borderTopWidth number #
borderWidth number #
bottom number #
flex number #
flexDirection enum('row', 'column') #
flexWrap enum('wrap', 'nowrap') #
height number #
justifyContent enum('flex-start', 'flex-end', 'center', 'space-between', 'space-around') #
left number #
margin number #
marginBottom number #
marginHorizontal number #
marginLeft number #
marginRight number #
marginTop number #
marginVertical number #
padding number #
paddingBottom number #
paddingHorizontal number #
paddingLeft number #
paddingRight number #
paddingTop number #
paddingVertical number #
position enum('absolute', 'relative') #
right number #
top number #
width number #
Flexbox # | Edit on GitHub |
Props #
alignItems enum('flex-start', 'flex-end', 'center', 'stretch') #
alignSelf enum('auto', 'flex-start', 'flex-end', 'center', 'stretch') #
borderBottomWidth number #
borderLeftWidth number #
borderRightWidth number #
borderTopWidth number #
borderWidth number #
bottom number #
flex number #
flexDirection enum('row', 'column') #
flexWrap enum('wrap', 'nowrap') #
height number #
justifyContent enum('flex-start', 'flex-end', 'center', 'space-between', 'space-around') #
left number #
margin number #
marginBottom number #
marginHorizontal number #
marginLeft number #
marginRight number #
marginTop number #
marginVertical number #
padding number #
paddingBottom number #
paddingHorizontal number #
paddingLeft number #
paddingRight number #
paddingTop number #
paddingVertical number #
position enum('absolute', 'relative') #
right number #
top number #
width number #
Gesture Responder System # | Edit on GitHub |
Gesture recognition on mobile devices is much more complicated than web. A touch can go through several phases as the app determines what the user's intention is. For example, the app needs to determine if the touch is scrolling, sliding on a widget, or tapping. This can even change during the duration of a touch. There can also be multiple simultaneous touches.
The touch responder system is needed to allow components to negotiate these touch interactions without any additional knowledge about their parent or child components. This system is implemented in ResponderEventPlugin.js, which contains further details and documentation.
Best Practices #
Users can feel huge differences in the usability of web apps vs. native, and this is one of the big causes. Every action should have the following attributes:
- Feedback/highlighting- show the user what is handling their touch, and what will happen when they release the gesture
- Cancel-ability- when making an action, the user should be able to abort it mid-touch by dragging their finger away
These features make users more comfortable while using an app, because it allows people to experiment and interact without fear of making mistakes.
TouchableHighlight and Touchable* #
The responder system can be complicated to use. So we have provided an abstract Touchable implementation for things that should be "tappable". This uses the responder system and allows you to easily configure tap interactions declaratively. Use TouchableHighlight anywhere where you would use a button or link on web.
Responder Lifecycle #
A view can become the touch responder by implementing the correct negotiation methods. There are two methods to ask the view if it wants to become responder:
View.props.onStartShouldSetResponder: (evt) => true,- Does this view want to become responder on the start of a touch?View.props.onMoveShouldSetResponder: (evt) => true,- Called for every touch move on the View when it is not the responder: does this view want to "claim" touch responsiveness?
If the View returns true and attempts to become the responder, one of the following will happen:
View.props.onResponderGrant: (evt) => {}- The View is now responding for touch events. This is the time to highlight and show the user what is happeningView.props.onResponderReject: (evt) => {}- Something else is the responder right now and will not release it
If the view is responding, the following handlers can be called:
View.props.onResponderMove: (evt) => {}- The user is moving their fingerView.props.onResponderRelease: (evt) => {}- Fired at the end of the touch, ie "touchUp"View.props.onResponderTerminationRequest: (evt) => true- Something else wants to become responder. Should this view release the responder? Returning true allows releaseView.props.onResponderTerminate: (evt) => {}- The responder has been taken from the View. Might be taken by other views after a call toonResponderTerminationRequest, or might be taken by the OS without asking (happens with control center/ notification center on iOS)
evt is a synthetic touch event with the following form:
nativeEventchangedTouches- Array of all touch events that have changed since the last eventidentifier- The ID of the touchlocationX- The X position of the touch, relative to the elementlocationY- The Y position of the touch, relative to the elementpageX- The X position of the touch, relative to the root elementpageY- The Y position of the touch, relative to the root elementtarget- The node id of the element receiving the touch eventtimestamp- A time identifier for the touch, useful for velocity calculationtouches- Array of all current touches on the screen
Capture ShouldSet Handlers #
onStartShouldSetResponder and onMoveShouldSetResponder are called with a bubbling pattern, where the deepest node is called first. That means that the deepest component will become responder when multiple Views return true for *ShouldSetResponder handlers. This is desirable in most cases, because it makes sure all controls and buttons are usable.
However, sometimes a parent will want to make sure that it becomes responder. This can be handled by using the capture phase. Before the responder system bubbles up from the deepest component, it will do a capture phase, firing on*ShouldSetResponderCapture. So if a parent View wants to prevent the child from becoming responder on a touch start, it should have a onStartShouldSetResponderCapture handler which returns true.
View.props.onStartShouldSetResponderCapture: (evt) => true,View.props.onMoveShouldSetResponderCapture: (evt) => true,
PanResponder #
For higher-level gesture interpretation, check out PanResponder.
Gesture Responder System # | Edit on GitHub |
Gesture recognition on mobile devices is much more complicated than web. A touch can go through several phases as the app determines what the user's intention is. For example, the app needs to determine if the touch is scrolling, sliding on a widget, or tapping. This can even change during the duration of a touch. There can also be multiple simultaneous touches.
The touch responder system is needed to allow components to negotiate these touch interactions without any additional knowledge about their parent or child components. This system is implemented in ResponderEventPlugin.js, which contains further details and documentation.
Best Practices #
Users can feel huge differences in the usability of web apps vs. native, and this is one of the big causes. Every action should have the following attributes:
- Feedback/highlighting- show the user what is handling their touch, and what will happen when they release the gesture
- Cancel-ability- when making an action, the user should be able to abort it mid-touch by dragging their finger away
These features make users more comfortable while using an app, because it allows people to experiment and interact without fear of making mistakes.
TouchableHighlight and Touchable* #
The responder system can be complicated to use. So we have provided an abstract Touchable implementation for things that should be "tappable". This uses the responder system and allows you to easily configure tap interactions declaratively. Use TouchableHighlight anywhere where you would use a button or link on web.
Responder Lifecycle #
A view can become the touch responder by implementing the correct negotiation methods. There are two methods to ask the view if it wants to become responder:
View.props.onStartShouldSetResponder: (evt) => true,- Does this view want to become responder on the start of a touch?View.props.onMoveShouldSetResponder: (evt) => true,- Called for every touch move on the View when it is not the responder: does this view want to "claim" touch responsiveness?
If the View returns true and attempts to become the responder, one of the following will happen:
View.props.onResponderGrant: (evt) => {}- The View is now responding for touch events. This is the time to highlight and show the user what is happeningView.props.onResponderReject: (evt) => {}- Something else is the responder right now and will not release it
If the view is responding, the following handlers can be called:
View.props.onResponderMove: (evt) => {}- The user is moving their fingerView.props.onResponderRelease: (evt) => {}- Fired at the end of the touch, ie "touchUp"View.props.onResponderTerminationRequest: (evt) => true- Something else wants to become responder. Should this view release the responder? Returning true allows releaseView.props.onResponderTerminate: (evt) => {}- The responder has been taken from the View. Might be taken by other views after a call toonResponderTerminationRequest, or might be taken by the OS without asking (happens with control center/ notification center on iOS)
evt is a synthetic touch event with the following form:
nativeEventchangedTouches- Array of all touch events that have changed since the last eventidentifier- The ID of the touchlocationX- The X position of the touch, relative to the elementlocationY- The Y position of the touch, relative to the elementpageX- The X position of the touch, relative to the root elementpageY- The Y position of the touch, relative to the root elementtarget- The node id of the element receiving the touch eventtimestamp- A time identifier for the touch, useful for velocity calculationtouches- Array of all current touches on the screen
Capture ShouldSet Handlers #
onStartShouldSetResponder and onMoveShouldSetResponder are called with a bubbling pattern, where the deepest node is called first. That means that the deepest component will become responder when multiple Views return true for *ShouldSetResponder handlers. This is desirable in most cases, because it makes sure all controls and buttons are usable.
However, sometimes a parent will want to make sure that it becomes responder. This can be handled by using the capture phase. Before the responder system bubbles up from the deepest component, it will do a capture phase, firing on*ShouldSetResponderCapture. So if a parent View wants to prevent the child from becoming responder on a touch start, it should have a onStartShouldSetResponderCapture handler which returns true.
View.props.onStartShouldSetResponderCapture: (evt) => true,View.props.onMoveShouldSetResponderCapture: (evt) => true,
PanResponder #
For higher-level gesture interpretation, check out PanResponder.
Getting Started # | Edit on GitHub |
Requirements #
- OS X - This guide assumes OS X which is needed for iOS development.
- Homebrew is the recommended way to install Watchman and Flow.
- Install Node.js 4.0 or newer.
- Install nvm with its setup instructions here. Then run
nvm install node && nvm alias default node, which installs the latest version of Node.js and sets up your terminal so you can run it by typingnode. With nvm you can install multiple versions of Node.js and easily switch between them. - New to npm?
- Install nvm with its setup instructions here. Then run
brew install watchman. We recommend installing watchman, otherwise you might hit a node file watching bug.brew install flow, if you want to use flow.
We recommend periodically running brew update && brew upgrade to keep your programs up-to-date.
iOS Setup #
Xcode 7.0 or higher is required. It can be installed from the App Store.
Android Setup #
To write React Native apps for Android, you will need to install the Android SDK (and an Android emulator if you want to work on your app without having to use a physical device). See Android setup guide for instructions on how to set up your Android environment.
NOTE: There is experimental Windows and Linux support for Android development.
Quick start #
To run the iOS app:
$ cd AwesomeProject- Open
ios/AwesomeProject.xcodeprojand hit run in Xcode. - Open
index.ios.jsin your text editor of choice and edit some lines. - Hit ⌘-R in your iOS simulator to reload the app and see your change!
Note: If you are using an iOS device, see the Running on iOS Device page.
To run the Android app:
$ cd AwesomeProject$ react-native run-android- Open
index.android.jsin your text editor of choice and edit some lines. - Press the menu button (F2 by default, or ⌘-M in Genymotion) and select Reload JS to see your change!
- Run
adb logcat *:S ReactNative:V ReactNativeJS:Vin a terminal to see your app's logs
Note: If you are using an Android device, see the Running on Android Device page.
Congratulations! You've successfully run and modified your first React Native app.
If you run into any issues getting started, see the troubleshooting page.
Adding Android to an existing React Native project #
If you already have a (iOS-only) React Native project and want to add Android support, you need to execute the following commands in your existing project directory:
- Update the
react-nativedependency in yourpackage.jsonfile to the latest version $ npm install$ react-native android
JavaScript Environment # | Edit on GitHub |
JavaScript Runtime #
When using React Native, you're going to be running your JavaScript code in two environments:
- On iOS simulators and devices, Android emulators and devices React Native uses JavaScriptCore which is the JavaScript engine that powers Safari. On iOS JSC doesn't use JIT due to the absence of writable executable memory in iOS apps.
- When using Chrome debugging, it runs all the JavaScript code within Chrome itself and communicates with native code via WebSocket. So you are using V8.
While both environments are very similar, you may end up hitting some inconsistencies. We're likely going to experiment with other JS engines in the future, so it's best to avoid relying on specifics of any runtime.
JavaScript Syntax Transformers #
Syntax transformers make writing code more enjoyable by allowing you to use new JavaScript syntax without having to wait for support on all interpreters.
As of version 0.5.0, React Native ships with the Babel JavaScript compiler. Check Babel documentation on its supported transformations for more details.
Here's a full list of React Native's enabled transformations.
ES5
- Reserved Words:
promise.catch(function() { });
ES6
- Arrow functions:
<C onPress={() => this.setState({pressed: true})} - Block scoping:
let greeting = 'hi'; - Call spread:
Math.max(...array); - Classes:
class C extends React.Component { render() { return <View />; } } - Constants:
const answer = 42; - Destructuring:
var {isActive, style} = this.props; - Modules:
import React, { Component } from 'react-native'; - Computed Properties:
var key = 'abc'; var obj = {[key]: 10}; - Object Consise Method:
var obj = { method() { return 10; } }; - Object Short Notation:
var name = 'vjeux'; var obj = { name }; - Rest Params:
function(type, ...args) { } - Template Literals:
var who = 'world'; var str = `Hello ${who}`;
ES7
- Object Spread:
var extended = { ...obj, a: 10 }; - Function Trailing Comma:
function f(a, b, c,) { } - Async Functions:
async function doStuffAsync() { const foo = await doOtherStuffAsync(); };
JavaScript Environment # | Edit on GitHub |
JavaScript Runtime #
When using React Native, you're going to be running your JavaScript code in two environments:
- On iOS simulators and devices, Android emulators and devices React Native uses JavaScriptCore which is the JavaScript engine that powers Safari. On iOS JSC doesn't use JIT due to the absence of writable executable memory in iOS apps.
- When using Chrome debugging, it runs all the JavaScript code within Chrome itself and communicates with native code via WebSocket. So you are using V8.
While both environments are very similar, you may end up hitting some inconsistencies. We're likely going to experiment with other JS engines in the future, so it's best to avoid relying on specifics of any runtime.
JavaScript Syntax Transformers #
Syntax transformers make writing code more enjoyable by allowing you to use new JavaScript syntax without having to wait for support on all interpreters.
As of version 0.5.0, React Native ships with the Babel JavaScript compiler. Check Babel documentation on its supported transformations for more details.
Here's a full list of React Native's enabled transformations.
ES5
- Reserved Words:
promise.catch(function() { });
ES6
- Arrow functions:
<C onPress={() => this.setState({pressed: true})} - Block scoping:
let greeting = 'hi'; - Call spread:
Math.max(...array); - Classes:
class C extends React.Component { render() { return <View />; } } - Constants:
const answer = 42; - Destructuring:
var {isActive, style} = this.props; - Modules:
import React, { Component } from 'react-native'; - Computed Properties:
var key = 'abc'; var obj = {[key]: 10}; - Object Consise Method:
var obj = { method() { return 10; } }; - Object Short Notation:
var name = 'vjeux'; var obj = { name }; - Rest Params:
function(type, ...args) { } - Template Literals:
var who = 'world'; var str = `Hello ${who}`;
ES7
- Object Spread:
var extended = { ...obj, a: 10 }; - Function Trailing Comma:
function f(a, b, c,) { } - Async Functions:
async function doStuffAsync() { const foo = await doOtherStuffAsync(); };
Linux and Windows Support # | Edit on GitHub |
NOTE: This guide focuses on Android development. You'll need a Mac to build iOS apps.
As React Native on iOS requires a Mac and most of the engineers at Facebook and contributors use Macs, support for OS X is a top priority. However, we would like to support developers using Linux and Windows too. We believe we'll get the best Linux and Windows support from people using these operating systems on a daily basis.
Therefore, Linux and Windows support for the development environment is an ongoing community responsibility. This can mean filing issues and submitting PRs, and we'll help review and merge them. We are looking forward to your contributions and appreciate your patience.
As of version 0.14 Android development with React native is mostly possible on Linux and Windows. You'll need to install Node.js 4.0 or newer. On Linux we recommend installing watchman, otherwise you might hit a node file watching bug.
What's missing on Windows #
On Windows the packager won't be started automatically when you run react-native run-android. You can start it manually using:
If you hit a ERROR Watcher took too long to load on Windows, try increasing the timeout in this file (under your node_modules/react-native).
MapView # | Edit on GitHub |
Props #
onAnnotationPress function #
Deprecated. Use annotation onFocus and onBlur instead.
onRegionChange function #
Callback that is called continuously when the user is dragging the map.
onRegionChangeComplete function #
Callback that is called once, when the user is done moving the map.
pitchEnabled bool #
When this property is set to true and a valid camera is associated
+
MapView # | Edit on GitHub |
Props #
onAnnotationPress function #
Deprecated. Use annotation onFocus and onBlur instead.
onRegionChange function #
Callback that is called continuously when the user is dragging the map.
onRegionChangeComplete function #
Callback that is called once, when the user is done moving the map.
pitchEnabled bool #
When this property is set to true and a valid camera is associated
with the map, the camera’s pitch angle is used to tilt the plane
of the map. When this property is set to false, the camera’s pitch
angle is ignored and the map is always displayed as if the user
@@ -10,7 +10,7 @@ camera’s heading angle is ignored and the map is always oriented so
that true north is situated at the top of the map view
scrollEnabled bool #
If false the user won't be able to change the map region being displayed.
Default value is true.
showsUserLocation bool #
If true the app will ask for the user's location and display it on
the map. Default value is false.
NOTE: on iOS, you need to add the NSLocationWhenInUseUsageDescription
-key in Info.plist to enable geolocation, otherwise it will fail silently.
style View#style #
Used to style and layout the MapView. See StyleSheet.js and
+key in Info.plist to enable geolocation, otherwise it will fail silently.
style View#style #
Used to style and layout the MapView. See StyleSheet.js and
ViewStylePropTypes.js for more info.
zoomEnabled bool #
If false the user won't be able to pinch/zoom the map.
Default value is true.
androidactive bool #
iosannotations [{latitude: number, longitude: number, animateDrop: bool, draggable: bool, onDragStateChange: function, onFocus: function, onBlur: function, title: string, subtitle: string, leftCalloutView: element, rightCalloutView: element, detailCalloutView: element, tintColor: [object Object], image: Image.propTypes.source, view: element, id: string, hasLeftCallout: deprecatedPropType( React.PropTypes.bool, @@ -420,7 +420,7 @@ exports.examples />; } }, -];
PickerIOS # | Edit on GitHub |
Examples # | Edit on GitHub |
PickerIOS # | Edit on GitHub |
Examples # | Edit on GitHub |
ProgressViewIOS # | Edit on GitHub |
Use ProgressViewIOS to render a UIProgressView on iOS.
Props #
progress number #
The progress value (between 0 and 1).
progressImage Image.propTypes.source #
A stretchable image to display as the progress bar.
progressTintColor string #
The tint color of the progress bar itself.
progressViewStyle enum('default', 'bar') #
The progress bar style.
trackImage Image.propTypes.source #
A stretchable image to display behind the progress bar.
trackTintColor string #
The tint color of the progress bar track.
Examples # | Edit on GitHub |
ProgressViewIOS # | Edit on GitHub |
Use ProgressViewIOS to render a UIProgressView on iOS.
Props #
progress number #
The progress value (between 0 and 1).
progressImage Image.propTypes.source #
A stretchable image to display as the progress bar.
progressTintColor string #
The tint color of the progress bar itself.
progressViewStyle enum('default', 'bar') #
The progress bar style.
trackImage Image.propTypes.source #
A stretchable image to display behind the progress bar.
trackTintColor string #
The tint color of the progress bar track.
Examples # | Edit on GitHub |
PullToRefreshViewAndroid # | Edit on GitHub |
React view that supports a single scrollable child view (e.g. ScrollView). When this child
view is at scrollY: 0, swiping down triggers an onRefresh event.
The style {flex: 1} might be required to ensure the expected behavior of the child component
-(e.g. when the child is expected to scroll with ScrollView or ListView).
Props #
colors [[object Object]] #
The colors (at least one) that will be used to draw the refresh indicator
enabled bool #
Whether the pull to refresh functionality is enabled
refreshing bool #
Whether the view should be indicating an active refresh
size RefreshLayoutConsts.SIZE.DEFAULT #
Size of the refresh indicator, see PullToRefreshViewAndroid.SIZE
Examples # | Edit on GitHub |
ScrollView or ListView).Props #
colors [[object Object]] #
The colors (at least one) that will be used to draw the refresh indicator
enabled bool #
Whether the pull to refresh functionality is enabled
refreshing bool #
Whether the view should be indicating an active refresh
size RefreshLayoutConsts.SIZE.DEFAULT #
Size of the refresh indicator, see PullToRefreshViewAndroid.SIZE
Examples # | Edit on GitHub |
RefreshControl # | Edit on GitHub |
This component is used inside a ScrollView to add pull to refresh
functionality. When the ScrollView is at scrollY: 0, swiping down
-triggers an onRefresh event.
Props #
onRefresh function #
Called when the view starts refreshing.
refreshing bool #
Whether the view should be indicating an active refresh.
androidcolors [[object Object]] #
The colors (at least one) that will be used to draw the refresh indicator.
androidenabled bool #
Whether the pull to refresh functionality is enabled.
androidsize RefreshLayoutConsts.SIZE.DEFAULT #
Size of the refresh indicator, see RefreshControl.SIZE.
iostitle string #
The title displayed under the refresh indicator.
Examples # | Edit on GitHub |
onRefresh event.Props #
onRefresh function #
Called when the view starts refreshing.
refreshing bool #
Whether the view should be indicating an active refresh.
androidcolors [[object Object]] #
The colors (at least one) that will be used to draw the refresh indicator.
androidenabled bool #
Whether the pull to refresh functionality is enabled.
androidsize RefreshLayoutConsts.SIZE.DEFAULT #
Size of the refresh indicator, see RefreshControl.SIZE.
iostitle string #
The title displayed under the refresh indicator.
Examples # | Edit on GitHub |
Running On Device # | Edit on GitHub |
Prerequisite: USB Debugging #
You'll need this in order to install your app on your device. First, make sure you have USB debugging enabled on your device.
Check that your device has been successfully connected by running adb devices:
Seeing device in the right column means the device is connected. Android - go figure :) You must have only one device connected.
Now you can use react-native run-android to install and launch your app on the device.
Accessing development server from device #
You can also iterate quickly on device using the development server. Follow one of the steps described below to make your development server running on your laptop accessible for your device.
Hint
Most modern android devices don't have a hardware menu button, which we use to trigger the developer menu. In that case you can shake the device to open the dev menu (to reload, debug, etc.). Alternatively, you can run the command
adb shell input keyevent 82to open the dev menu (82 being the Menu key code).
Using adb reverse #
Note that this option is available on devices running android 5.0+ (API 21).
Have your device connected via USB with debugging enabled (see paragraph above on how to enable USB debugging on your device).
- Run
adb reverse tcp:8081 tcp:8081 - You can use
Reload JSand other development options with no extra configuration
Configure your app to connect to the local dev server via Wi-Fi #
- Make sure your laptop and your phone are on the same Wi-Fi network.
- Open your React Native app on your device. You can do this the same way you'd open any other app.
- You'll see a red screen with an error. This is OK. The following steps will fix that.
- Open the Developer menu by shaking the device or running
adb shell input keyevent 82from the command line. - Go to
Dev Settings. - Go to
Debug server host for device. - Type in your machine's IP address and the port of the local dev server (e.g. 10.0.1.1:8081). On Mac, you can find the IP address in System Preferences / Network. On Windows, open the command prompt and type
ipconfigto find your machine's IP address (more info). - Go back to the Developer menu and select
Reload JS.
Running On Device # | Edit on GitHub |
Note that running on device requires Apple Developer account and provisioning your iPhone. This guide covers only React Native specific topic.
Accessing development server from device #
You can iterate quickly on device using development server. To do that, your laptop and your phone have to be on the same wifi network.
- Open
AwesomeApp/ios/AwesomeApp/AppDelegate.m - Change the IP in the URL from
localhostto your laptop's IP. On Mac, you can find the IP address in System Preferences / Network. - In Xcode select your phone as build target and press "Build and run"
Hint
Shake the device to open development menu (reload, debug, etc.)
Using offline bundle #
When you run your app on device, we pack all the JavaScript code and the images used into the app's resources. This way you can test it without development server running and submit the app to the AppStore.
- Open
AwesomeApp/ios/AwesomeApp/AppDelegate.m - Uncomment
jsCodeLocation = [[NSBundle mainBundle] ... - The JS bundle will be built for dev or prod depending on your app's scheme (Debug = development build with warnings, Release = minified prod build with perf optimizations). To change the scheme navigate to
Product > Scheme > Edit Scheme...in xcode and changeBuild ConfigurationbetweenDebugandRelease.
Disabling in-app developer menu #
When building your app for production, your app's scheme should be set to Release as detailed in the debugging documentation in order to disable the in-app developer menu.
Troubleshooting #
If curl command fails make sure the packager is running. Also try adding --ipv4 flag to the end of it.
Note that since v0.14 JS and images are automatically packaged into the iOS app using Bundle React Native code and images Xcode build phase.
Running On Device # | Edit on GitHub |
Note that running on device requires Apple Developer account and provisioning your iPhone. This guide covers only React Native specific topic.
Accessing development server from device #
You can iterate quickly on device using development server. To do that, your laptop and your phone have to be on the same wifi network.
- Open
AwesomeApp/ios/AwesomeApp/AppDelegate.m - Change the IP in the URL from
localhostto your laptop's IP. On Mac, you can find the IP address in System Preferences / Network. - In Xcode select your phone as build target and press "Build and run"
Hint
Shake the device to open development menu (reload, debug, etc.)
Using offline bundle #
When you run your app on device, we pack all the JavaScript code and the images used into the app's resources. This way you can test it without development server running and submit the app to the AppStore.
- Open
AwesomeApp/ios/AwesomeApp/AppDelegate.m - Uncomment
jsCodeLocation = [[NSBundle mainBundle] ... - The JS bundle will be built for dev or prod depending on your app's scheme (Debug = development build with warnings, Release = minified prod build with perf optimizations). To change the scheme navigate to
Product > Scheme > Edit Scheme...in xcode and changeBuild ConfigurationbetweenDebugandRelease.
Disabling in-app developer menu #
When building your app for production, your app's scheme should be set to Release as detailed in the debugging documentation in order to disable the in-app developer menu.
Troubleshooting #
If curl command fails make sure the packager is running. Also try adding --ipv4 flag to the end of it.
Note that since v0.14 JS and images are automatically packaged into the iOS app using Bundle React Native code and images Xcode build phase.
SegmentedControlIOS # | Edit on GitHub |
Use SegmentedControlIOS to render a UISegmentedControl iOS.
Props #
enabled bool #
If false the user won't be able to interact with the control. +
SegmentedControlIOS # | Edit on GitHub |
Use SegmentedControlIOS to render a UISegmentedControl iOS.
Props #
enabled bool #
If false the user won't be able to interact with the control. Default value is true.
momentary bool #
If true, then selecting a segment won't persist visually.
The onValueChange callback will still work as expected.
onChange function #
Callback that is called when the user taps a segment; passes the event as an argument
onValueChange function #
Callback that is called when the user taps a segment; @@ -155,7 +155,7 @@ exports.examples : 'Change events can be detected', render(): ReactElement { return <EventSegmentedControlExample />; } } -];
SliderIOS # | Edit on GitHub |
Props #
disabled bool #
If true the user won't be able to move the slider. +
SliderIOS # | Edit on GitHub |
Props #
disabled bool #
If true the user won't be able to move the slider. Default value is false.
maximumTrackImage Image.propTypes.source #
Assigns a maximum track image. Only static images are supported. The leftmost pixel of the image will be stretched to fill the track.
maximumTrackTintColor string #
The color used for the track to the right of the button. Overrides the default blue gradient image.
maximumValue number #
Initial maximum value of the slider. Default value is 1.
minimumTrackImage Image.propTypes.source #
Assigns a minimum track image. Only static images are supported. The @@ -6,7 +6,7 @@ rightmost pixel of the image will be stretched to fill the track.
minimumValue number #
Initial minimum value of the slider. Default value is 0.
onSlidingComplete function #
Callback called when the user finishes changing the value (e.g. when the slider is released).
onValueChange function #
Callback continuously called while the user is dragging the slider.
step number #
Step value of the slider. The value should be between 0 and (maximumValue - minimumValue). -Default value is 0.
style View#style #
Used to style and layout the Slider. See StyleSheet.js and
+Default value is 0.
style View#style #
Used to style and layout the Slider. See StyleSheet.js and
ViewStylePropTypes.js for more info.
thumbImage Image.propTypes.source #
Sets an image for the thumb. It only supports static images.
trackImage Image.propTypes.source #
Assigns a single image for the track. Only static images are supported. The center pixel of the image will be stretched to fill the track.
value number #
Initial value of the slider. The value should be between minimumValue and maximumValue, which default to 0 and 1 respectively. @@ -116,7 +116,7 @@ exports.examples ); } }, -];
Switch # | Edit on GitHub |
Universal two-state toggle component.
Props #
disabled bool #
If true the user won't be able to toggle the switch. +
Switch # | Edit on GitHub |
Universal two-state toggle component.
Props #
disabled bool #
If true the user won't be able to toggle the switch. Default value is false.
onValueChange function #
Invoked with the new value when the value changes.
testID string #
Used to locate this view in end-to-end tests.
value bool #
The value of the switch. If true the switch will be turned on. -Default value is false.
Examples # | Edit on GitHub |
Examples # | Edit on GitHub |
< exports.title = '<Switch>'; exports.displayName = 'SwitchExample'; exports.description = 'Native boolean input'; -exports.examples = examples;
TabBarIOS.Item # | Edit on GitHub |
Props #
badge string, number #
Little red bubble that sits at the top right of the icon.
icon Image.propTypes.source #
A custom icon for the tab. It is ignored when a system icon is defined.
onPress function #
Callback when this tab is being selected, you should change the state of your +
TabBarIOS.Item # | Edit on GitHub |
Props #
badge string, number #
Little red bubble that sits at the top right of the icon.
icon Image.propTypes.source #
A custom icon for the tab. It is ignored when a system icon is defined.
onPress function #
Callback when this tab is being selected, you should change the state of your component to set selected={true}.
selected bool #
It specifies whether the children are visible or not. If you see a blank content, you probably forgot to add a selected one.
selectedIcon Image.propTypes.source #
A custom icon when the tab is selected. It is ignored when a system -icon is defined. If left empty, the icon will be tinted in blue.
style View#style #
React style object.
systemIcon enum('bookmarks', 'contacts', 'downloads', 'favorites', 'featured', 'history', 'more', 'most-recent', 'most-viewed', 'recents', 'search', 'top-rated') #
Items comes with a few predefined system icons. Note that if you are +icon is defined. If left empty, the icon will be tinted in blue.
style View#style #
React style object.
systemIcon enum('bookmarks', 'contacts', 'downloads', 'favorites', 'featured', 'history', 'more', 'most-recent', 'most-viewed', 'recents', 'search', 'top-rated') #
Items comes with a few predefined system icons. Note that if you are using them, the title and selectedIcon will be overridden with the system ones.
title string #
Text that appears under the icon. It is ignored when a system icon -is defined.
TabBarIOS # | Edit on GitHub |
Props #
style View#style #
translucent bool #
A Boolean value that indicates whether the tab bar is translucent
Examples # | Edit on GitHub |
TabBarIOS # | Edit on GitHub |
Props #
style View#style #
translucent bool #
A Boolean value that indicates whether the tab bar is translucent
Examples # | Edit on GitHub |
WebView # | Edit on GitHub |
Renders a native WebView.
Props #
automaticallyAdjustContentInsets bool #
contentInset {top: number, left: number, bottom: number, right: number} #
html string #
DeprecatedUse the source prop instead.
injectedJavaScript string #
Sets the JS to be injected when the webpage loads.
onError function #
Invoked when load fails
onLoad function #
Invoked when load finish
onLoadEnd function #
Invoked when load either succeeds or fails
onLoadStart function #
Invoked on load start
onNavigationStateChange function #
renderError function #
Function that returns a view to show if there's an error.
renderLoading function #
Function that returns a loading indicator.
source {uri: string, method: string, headers: object, body: string}, {html: string, baseUrl: string}, number #
Loads static html or a uri (with optional headers) in the WebView.
startInLoadingState bool #
style View#style #
url string #
DeprecatedUse the source prop instead.
androiddomStorageEnabled bool #
Used on Android only, controls whether DOM Storage is enabled or not
androidjavaScriptEnabled bool #
Used on Android only, JS is enabled by default for WebView on iOS
iosallowsInlineMediaPlayback bool #
Determines whether HTML5 videos play inline or use the native full-screen +
WebView # | Edit on GitHub |
Renders a native WebView.
Props #
automaticallyAdjustContentInsets bool #
contentInset {top: number, left: number, bottom: number, right: number} #
html string #
DeprecatedUse the source prop instead.
injectedJavaScript string #
Sets the JS to be injected when the webpage loads.
onError function #
Invoked when load fails
onLoad function #
Invoked when load finish
onLoadEnd function #
Invoked when load either succeeds or fails
onLoadStart function #
Invoked on load start
onNavigationStateChange function #
renderError function #
Function that returns a view to show if there's an error.
renderLoading function #
Function that returns a loading indicator.
source {uri: string, method: string, headers: object, body: string}, {html: string, baseUrl: string}, number #
Loads static html or a uri (with optional headers) in the WebView.
startInLoadingState bool #
style View#style #
url string #
DeprecatedUse the source prop instead.
androiddomStorageEnabled bool #
Used on Android only, controls whether DOM Storage is enabled or not
androidjavaScriptEnabled bool #
Used on Android only, JS is enabled by default for WebView on iOS
iosallowsInlineMediaPlayback bool #
Determines whether HTML5 videos play inline or use the native full-screen
controller.
default value false
NOTE : "In order for video to play inline, not only does this
@@ -313,7 +313,7 @@ exports.examples );
}
}
-];
ActivityIndicatorIOS # | Edit on GitHub |
Props #
animating bool #
Whether to show the indicator (true, the default) or hide it (false).
color string #
The foreground color of the spinner (default is gray).
hidesWhenStopped bool #
Whether the indicator should hide when not animating (true by default).
onLayout function #
Invoked on mount and layout changes with
{nativeEvent: { layout: {x, y, width, height}}}.
size enum('small', 'large') #
Size of the indicator. Small has a height of 20, large has a height of 36.
Examples # | Edit on GitHub |
ActivityIndicatorIOS # | Edit on GitHub |
Props #
animating bool #
Whether to show the indicator (true, the default) or hide it (false).
color string #
The foreground color of the spinner (default is gray).
hidesWhenStopped bool #
Whether the indicator should hide when not animating (true by default).
onLayout function #
Invoked on mount and layout changes with
{nativeEvent: { layout: {x, y, width, height}}}.
size enum('small', 'large') #
Size of the indicator. Small has a height of 20, large has a height of 36.
Examples # | Edit on GitHub |
Android Setup # | Edit on GitHub |
This guide describes basic steps of the Android development environment setup that are required to run React Native android apps on an android emulator. We don't discuss developer tool configuration such as IDEs here.
Install Git #
On Mac, if you have installed XCode, Git is already installed, otherwise run the following:
brew install gitOn Linux, install Git via your package manager.
On Windows, download and install Git for Windows. During the setup process, choose "Run Git from Windows Command Prompt", which will add Git to your
PATHenvironment variable.
Install the Android SDK (unless you have it) #
- Install the latest JDK
- Install the Android SDK:
- On Mac:
brew install android-sdk - On Linux and Windows: Download from the Android website
- On Mac:
Define the ANDROID_HOME environment variable #
IMPORTANT: Make sure the ANDROID_HOME environment variable points to your existing Android SDK:
On Mac, add this to your
~/.bashrc,~/.bash_profileor whatever your shell uses:# If you installed the SDK via Homebrew, otherwise ~/Library/Android/sdk export ANDROID_HOME=/usr/local/opt/android-sdkOn Linux, add this to your
~/.bashrc,~/.bash_profileor whatever your shell uses:export ANDROID_HOME=<path_where_you_unpacked_android_sdk>On Windows, go to
Control Panel->System and Security->System->Change settings->Advanced->Environment variables->New
NOTE: You need to restart the Command Prompt (Windows) / Terminal Emulator (Mac OS X, Linux) to apply the new Environment variables.
Use gradle daemon #
React Native Android use gradle as a build system. We recommend to enable gradle daemon functionality which may result in up to 50% improvement in incremental build times for changes in java code. Learn here how to enable it for your platform.
Configure your SDK #
- Open the Android SDK Manager (on Mac start a new shell and run
android); in the window that appears make sure you check:- Android SDK Build-tools version 23.0.1
- Android 6.0 (API 23)
- Android Support Repository
- Click "Install Packages"
Install Genymotion #
Genymotion is much easier to set up than stock Google emulators. However, it's only free for personal use. If you want to use the stock Google emulator, see below.
- Download and install Genymotion.
- Open Genymotion. It might ask you to install VirtualBox unless you already have it.
- Create a new emulator and start it.
- To bring up the developer menu press ⌘+M
Alternative: Create a stock Google emulator #
- Start a new shell and run
android; in the window that appears make sure you check:- Intel x86 Atom System Image (for Android 5.1.1 - API 22)
- Intel x86 Emulator Accelerator (HAXM installer)
- Click "Install Packages".
- Configure hardware acceleration (HAXM), otherwise the emulator is going to be slow.
- Create an Android Virtual Device (AVD):
- Run
android avdand click on Create... - - With the new AVD selected, click
Start...
- Run
- To bring up the developer menu press F2 (or install Frappé)
Windows Hyper-V Alternative #
The Visual Studio Emulator for Android is a free android emulator that is hardware accelerated via Hyper-V. It doesn't require you to install Visual Studio at all.
To use it with react-native you just have to add a key and value to your registry:
- Open the Run Command (Windows+R)
- Enter
regedit.exe - In the Registry Editor navigate to
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Android SDK Tools - Right Click on
Android SDK Toolsand chooseNew > String Value - Set the name to
Path - Double Click the new
PathKey and set the value toC:\Program Files\Android\sdk. The path value might be different on your machine.
You will also need to run the command adb reverse tcp:8081 tcp:8081 with this emulator.
Then restart the emulator and when it runs you can just do react-native run-android as usual.
Profiling Android UI Performance # | Edit on GitHub |
We try our best to deliver buttery-smooth UI performance by default, but sometimes that just isn't possible. Remember, Android supports 10k+ different phones and is generalized to support software rendering: the framework architecture and need to generalize across many hardware targets unfortunately means you get less for free relative to iOS. But sometimes, there are things you can improve (and many times it's not native code's fault at all!).
The first step for debugging this jank is to answer the fundamental question of where your time is being spent during each 16ms frame. For that, we'll be using a standard Android profiling tool called systrace. But first...
Make sure that JS dev mode is OFF!
You should see
__DEV__ === false, development-level warning are OFF, performance optimizations are ONin your application logs (which you can view usingadb logcat)
Profiling with Systrace #
Systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by markers start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.
Collecting a trace #
NOTE:
Systrace support was added in react-native
v0.15. You will need to build with that version to collect a trace.
First, connect a device that exhibits the stuttering you want to investigate to your computer via USB and get it to the point right before the navigation/animation you want to profile. Run systrace as follows
A quick breakdown of this command:
timeis the length of time the trace will be collected in secondssched,gfx, andvieware the android SDK tags (collections of markers) we care about:schedgives you information about what's running on each core of your phone,gfxgives you graphics info such as frame boundaries, andviewgives you information about measure, layout, and draw passes-a <your_package_name>enables app-specific markers, specifically the ones built into the React Native framework.your_package_namecan be found in theAndroidManifest.xmlof your app and looks likecom.example.app
Once the trace starts collecting, perform the animation or interaction you care about. At the end of the trace, systrace will give you a link to the trace which you can open in your browser.
Reading the trace #
After opening the trace in your browser (preferably Chrome), you should see something like this:
HINT: Use the WASD keys to strafe and zoom
Enable VSync highlighting #
The first thing you should do is highlight the 16ms frame boundaries if you haven't already done that. Check this checkbox at the top right of the screen:
You should see zebra stripes as in the screenshot above. If you don't, try profiling on a different device: Samsung has been known to have issues displaying vsyncs while the Nexus series is generally pretty reliable.
Find your process #
Scroll until you see (part of) the name of your package. In this case, I was profiling com.facebook.adsmanager, which shows up as book.adsmanager because of silly thread name limits in the kernel.
On the left side, you'll see a set of threads which correspond to the timeline rows on the right. There are three/four threads we care about for our purposes: the UI thread (which has your package name or the name UI Thread), mqt_js and mqt_native_modules. If you're running on Android 5+, we also care about the Render Thread.
UI Thread #
This is where standard android measure/layout/draw happens. The thread name on the right will be your package name (in my case book.adsmanager) or UI Thread. The events that you see on this thread should look something like this and have to do with Choreographer, traversals, and DispatchUI:
JS Thread #
This is where JS is executed. The thread name will be either mqt_js or <...> depending on how cooperative the kernel on your device is being. To identify it if it doesn't have a name, look for things like JSCall, Bridge.executeJSCall, etc:
Native Modules Thread #
This is where native module calls (e.g. the UIManager) are executed. The thread name will be either mqt_native_modules or <...>. To identify it in the latter case, look for things like NativeCall, callJavaModuleMethod, and onBatchComplete:
Bonus: Render Thread #
If you're using Android L (5.0) and up, you will also have a render thread in your application. This thread generates the actual OpenGL commands used to draw your UI. The thread name will be either RenderThread or <...>. To identify it in the latter case, look for things like DrawFrame and queueBuffer:
Identifying a culprit #
A smooth animation should look something like the following:
Each change in color is a frame -- remember that in order to display a frame, all our UI work needs to be done by the end of that 16ms period. Notice that no thread is working close to the frame boundary. An application rendering like this is rendering at 60FPS.
If you noticed chop, however, you might see something like this:
Notice that the JS thread is executing basically all the time, and across frame boundaries! This app is not rendering at 60FPS. In this case, the problem lies in JS.
You might also see something like this:
In this case, the UI and render threads are the ones that have work crossing frame boundaries. The UI that we're trying to render on each frame is requiring too much work to be done. In this case, the problem lies in the native views being rendered.
At this point, you'll have some very helpful information to inform your next steps.
JS Issues #
If you identified a JS problem, look for clues in the specific JS that you're executing. In the scenario above, we see RCTEventEmitter being called multiple times per frame. Here's a zoom-in of the JS thread from the trace above:
This doesn't seem right. Why is it being called so often? Are they actually different events? The answers to these questions will probably depend on your product code. And many times, you'll want to look into shouldComponentUpdate.
TODO: Add more tools for profiling JS
Native UI Issues #
If you identified a native UI problem, there are usually two scenarios:
- the UI you're trying to draw each frame involves to much work on the GPU, or
- You're constructing new UI during the animation/interaction (e.g. loading in new content during a scroll).
Too much GPU work #
In the first scenario, you'll see a trace that has the UI thread and/or Render Thread looking like this:
Notice the long amount of time spent in DrawFrame that crosses frame boundaries. This is time spent waiting for the GPU to drain its command buffer from the previous frame.
To mitigate this, you should:
- investigate using
renderToHardwareTextureAndroidfor complex, static content that is being animated/transformed (e.g. theNavigatorslide/alpha animations) - make sure that you are not using
needsOffscreenAlphaCompositing, which is disabled by default, as it greatly increases the per-frame load on the GPU in most cases.
If these don't help and you want to dig deeper into what the GPU is actually doing, you can check out Tracer for OpenGL ES.
Creating new views on the UI thread #
In the second scenario, you'll see something more like this:
Notice that first the JS thread thinks for a bit, then you see some work done on the native modules thread, followed by an expensive traversal on the UI thread.
There isn't an easy way to mitigate this unless you're able to postpone creating new UI until after the interaction, or you are able to simplify the UI you're creating. The react native team is working on a infrastructure level solution for this that will allow new UI to be created and configured off the main thread, allowing the interaction to continue smoothly.
Still stuck? #
If you are confused or stuck, please post ask on Stack Overflow with the react-native tag. If you are unable to get a response there, or find an issue with a core component, please File a Github issue.
Profiling Android UI Performance # | Edit on GitHub |
We try our best to deliver buttery-smooth UI performance by default, but sometimes that just isn't possible. Remember, Android supports 10k+ different phones and is generalized to support software rendering: the framework architecture and need to generalize across many hardware targets unfortunately means you get less for free relative to iOS. But sometimes, there are things you can improve (and many times it's not native code's fault at all!).
The first step for debugging this jank is to answer the fundamental question of where your time is being spent during each 16ms frame. For that, we'll be using a standard Android profiling tool called systrace. But first...
Make sure that JS dev mode is OFF!
You should see
__DEV__ === false, development-level warning are OFF, performance optimizations are ONin your application logs (which you can view usingadb logcat)
Profiling with Systrace #
Systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by markers start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.
Collecting a trace #
NOTE:
Systrace support was added in react-native
v0.15. You will need to build with that version to collect a trace.
First, connect a device that exhibits the stuttering you want to investigate to your computer via USB and get it to the point right before the navigation/animation you want to profile. Run systrace as follows
A quick breakdown of this command:
timeis the length of time the trace will be collected in secondssched,gfx, andvieware the android SDK tags (collections of markers) we care about:schedgives you information about what's running on each core of your phone,gfxgives you graphics info such as frame boundaries, andviewgives you information about measure, layout, and draw passes-a <your_package_name>enables app-specific markers, specifically the ones built into the React Native framework.your_package_namecan be found in theAndroidManifest.xmlof your app and looks likecom.example.app
Once the trace starts collecting, perform the animation or interaction you care about. At the end of the trace, systrace will give you a link to the trace which you can open in your browser.
Reading the trace #
After opening the trace in your browser (preferably Chrome), you should see something like this:
HINT: Use the WASD keys to strafe and zoom
Enable VSync highlighting #
The first thing you should do is highlight the 16ms frame boundaries if you haven't already done that. Check this checkbox at the top right of the screen:
You should see zebra stripes as in the screenshot above. If you don't, try profiling on a different device: Samsung has been known to have issues displaying vsyncs while the Nexus series is generally pretty reliable.
Find your process #
Scroll until you see (part of) the name of your package. In this case, I was profiling com.facebook.adsmanager, which shows up as book.adsmanager because of silly thread name limits in the kernel.
On the left side, you'll see a set of threads which correspond to the timeline rows on the right. There are three/four threads we care about for our purposes: the UI thread (which has your package name or the name UI Thread), mqt_js and mqt_native_modules. If you're running on Android 5+, we also care about the Render Thread.
UI Thread #
This is where standard android measure/layout/draw happens. The thread name on the right will be your package name (in my case book.adsmanager) or UI Thread. The events that you see on this thread should look something like this and have to do with Choreographer, traversals, and DispatchUI:
JS Thread #
This is where JS is executed. The thread name will be either mqt_js or <...> depending on how cooperative the kernel on your device is being. To identify it if it doesn't have a name, look for things like JSCall, Bridge.executeJSCall, etc:
Native Modules Thread #
This is where native module calls (e.g. the UIManager) are executed. The thread name will be either mqt_native_modules or <...>. To identify it in the latter case, look for things like NativeCall, callJavaModuleMethod, and onBatchComplete:
Bonus: Render Thread #
If you're using Android L (5.0) and up, you will also have a render thread in your application. This thread generates the actual OpenGL commands used to draw your UI. The thread name will be either RenderThread or <...>. To identify it in the latter case, look for things like DrawFrame and queueBuffer:
Identifying a culprit #
A smooth animation should look something like the following:
Each change in color is a frame -- remember that in order to display a frame, all our UI work needs to be done by the end of that 16ms period. Notice that no thread is working close to the frame boundary. An application rendering like this is rendering at 60FPS.
If you noticed chop, however, you might see something like this:
Notice that the JS thread is executing basically all the time, and across frame boundaries! This app is not rendering at 60FPS. In this case, the problem lies in JS.
You might also see something like this:
In this case, the UI and render threads are the ones that have work crossing frame boundaries. The UI that we're trying to render on each frame is requiring too much work to be done. In this case, the problem lies in the native views being rendered.
At this point, you'll have some very helpful information to inform your next steps.
JS Issues #
If you identified a JS problem, look for clues in the specific JS that you're executing. In the scenario above, we see RCTEventEmitter being called multiple times per frame. Here's a zoom-in of the JS thread from the trace above:
This doesn't seem right. Why is it being called so often? Are they actually different events? The answers to these questions will probably depend on your product code. And many times, you'll want to look into shouldComponentUpdate.
TODO: Add more tools for profiling JS
Native UI Issues #
If you identified a native UI problem, there are usually two scenarios:
- the UI you're trying to draw each frame involves to much work on the GPU, or
- You're constructing new UI during the animation/interaction (e.g. loading in new content during a scroll).
Too much GPU work #
In the first scenario, you'll see a trace that has the UI thread and/or Render Thread looking like this:
Notice the long amount of time spent in DrawFrame that crosses frame boundaries. This is time spent waiting for the GPU to drain its command buffer from the previous frame.
To mitigate this, you should:
- investigate using
renderToHardwareTextureAndroidfor complex, static content that is being animated/transformed (e.g. theNavigatorslide/alpha animations) - make sure that you are not using
needsOffscreenAlphaCompositing, which is disabled by default, as it greatly increases the per-frame load on the GPU in most cases.
If these don't help and you want to dig deeper into what the GPU is actually doing, you can check out Tracer for OpenGL ES.
Creating new views on the UI thread #
In the second scenario, you'll see something more like this:
Notice that first the JS thread thinks for a bit, then you see some work done on the native modules thread, followed by an expensive traversal on the UI thread.
There isn't an easy way to mitigate this unless you're able to postpone creating new UI until after the interaction, or you are able to simplify the UI you're creating. The react native team is working on a infrastructure level solution for this that will allow new UI to be created and configured off the main thread, allowing the interaction to continue smoothly.
Still stuck? #
If you are confused or stuck, please post ask on Stack Overflow with the react-native tag. If you are unable to get a response there, or find an issue with a core component, please File a Github issue.
Debugging # | Edit on GitHub |
Debugging React Native Apps #
To access the in-app developer menu:
- On iOS shake the device or press
control + ⌘ + zin the simulator. - On Android shake the device or press hardware menu button (available on older devices and in most of the emulators, e.g. in genymotion you can press
⌘ + mto simulate hardware menu button click). You can also install Frappé, a tool for OS X, which allows you to emulate shaking of devices remotely. You can use⌘ + Shift + Ras a shortcut to trigger a shake from Frappé.
Hint
To disable the developer menu for production builds:
- For iOS open your project in Xcode and select
Product→Scheme→Edit Scheme...(or press⌘ + <). Next, selectRunfrom the menu on the left and change the Build Configuration toRelease.- For Android, by default, developer menu will be disabled in release builds done by gradle (e.g with gradle
assembleReleasetask). Although this behavior can be customized by passing proper value toReactInstanceManager#setUseDeveloperSupport.
Reload #
Selecting Reload (or pressing ⌘ + r in the iOS simulator) will reload the JavaScript that powers your application. If you have added new resources (such as an image to Images.xcassets on iOS or to res/drawable folder on Android) or modified any native code (Objective-C/Swift code on iOS or Java/C++ code on Android), you will need to re-build the app for the changes to take effect.
Chrome Developer Tools #
To debug the JavaScript code in Chrome, select Debug in Chrome from the developer menu. This will open a new tab at http://localhost:8081/debugger-ui.
In Chrome, press ⌘ + option + i or select View → Developer → Developer Tools to toggle the developer tools console. Enable Pause On Caught Exceptions for a better debugging experience.
To debug on a real device:
- On iOS - open the file
RCTWebSocketExecutor.mand changelocalhostto the IP address of your computer. Shake the device to open the development menu with the option to start debugging. - On Android, if you're running Android 5.0+ device connected via USB you can use
adbcommand line tool to setup port forwarding from the device to your computer. For that run:adb reverse tcp:8081 tcp:8081(see this link for help onadbcommand). Alternatively, you can open dev menu on the device and selectDev Settings, then updateDebug server host for devicesetting to the IP address of your computer.
React Developer Tools (optional) #
Install the React Developer Tools extension for Google Chrome. This will allow you to navigate the component hierarchy via the React in the developer tools (see facebook/react-devtools for more information).
Live Reload #
This option allows for your JS changes to trigger automatic reload on the connected device/emulator. To enable this option:
- On iOS, select
Enable Live Reloadvia the developer menu to have the application automatically reload when changes are made to the JavaScript. - On Android, launch dev menu, go to
Dev Settingsand selectAuto reload on JS changeoption
FPS (Frames per Second) Monitor #
On 0.5.0-rc and higher versions, you can enable a FPS graph overlay in the developers menu in order to help you debug performance problems.
Debugging # | Edit on GitHub |
Debugging React Native Apps #
To access the in-app developer menu:
- On iOS shake the device or press
control + ⌘ + zin the simulator. - On Android shake the device or press hardware menu button (available on older devices and in most of the emulators, e.g. in genymotion you can press
⌘ + mto simulate hardware menu button click). You can also install Frappé, a tool for OS X, which allows you to emulate shaking of devices remotely. You can use⌘ + Shift + Ras a shortcut to trigger a shake from Frappé.
Hint
To disable the developer menu for production builds:
- For iOS open your project in Xcode and select
Product→Scheme→Edit Scheme...(or press⌘ + <). Next, selectRunfrom the menu on the left and change the Build Configuration toRelease.- For Android, by default, developer menu will be disabled in release builds done by gradle (e.g with gradle
assembleReleasetask). Although this behavior can be customized by passing proper value toReactInstanceManager#setUseDeveloperSupport.
Reload #
Selecting Reload (or pressing ⌘ + r in the iOS simulator) will reload the JavaScript that powers your application. If you have added new resources (such as an image to Images.xcassets on iOS or to res/drawable folder on Android) or modified any native code (Objective-C/Swift code on iOS or Java/C++ code on Android), you will need to re-build the app for the changes to take effect.
Chrome Developer Tools #
To debug the JavaScript code in Chrome, select Debug in Chrome from the developer menu. This will open a new tab at http://localhost:8081/debugger-ui.
In Chrome, press ⌘ + option + i or select View → Developer → Developer Tools to toggle the developer tools console. Enable Pause On Caught Exceptions for a better debugging experience.
To debug on a real device:
- On iOS - open the file
RCTWebSocketExecutor.mand changelocalhostto the IP address of your computer. Shake the device to open the development menu with the option to start debugging. - On Android, if you're running Android 5.0+ device connected via USB you can use
adbcommand line tool to setup port forwarding from the device to your computer. For that run:adb reverse tcp:8081 tcp:8081(see this link for help onadbcommand). Alternatively, you can open dev menu on the device and selectDev Settings, then updateDebug server host for devicesetting to the IP address of your computer.
React Developer Tools (optional) #
Install the React Developer Tools extension for Google Chrome. This will allow you to navigate the component hierarchy via the React in the developer tools (see facebook/react-devtools for more information).
Live Reload #
This option allows for your JS changes to trigger automatic reload on the connected device/emulator. To enable this option:
- On iOS, select
Enable Live Reloadvia the developer menu to have the application automatically reload when changes are made to the JavaScript. - On Android, launch dev menu, go to
Dev Settingsand selectAuto reload on JS changeoption
FPS (Frames per Second) Monitor #
On 0.5.0-rc and higher versions, you can enable a FPS graph overlay in the developers menu in order to help you debug performance problems.
Flexbox # | Edit on GitHub |
Props #
alignItems enum('flex-start', 'flex-end', 'center', 'stretch') #
alignSelf enum('auto', 'flex-start', 'flex-end', 'center', 'stretch') #
borderBottomWidth number #
borderLeftWidth number #
borderRightWidth number #
borderTopWidth number #
borderWidth number #
bottom number #
flex number #
flexDirection enum('row', 'column') #
flexWrap enum('wrap', 'nowrap') #
height number #
justifyContent enum('flex-start', 'flex-end', 'center', 'space-between', 'space-around') #
left number #
margin number #
marginBottom number #
marginHorizontal number #
marginLeft number #
marginRight number #
marginTop number #
marginVertical number #
padding number #
paddingBottom number #
paddingHorizontal number #
paddingLeft number #
paddingRight number #
paddingTop number #
paddingVertical number #
position enum('absolute', 'relative') #
right number #
top number #
width number #
Flexbox # | Edit on GitHub |
Props #
alignItems enum('flex-start', 'flex-end', 'center', 'stretch') #
alignSelf enum('auto', 'flex-start', 'flex-end', 'center', 'stretch') #
borderBottomWidth number #
borderLeftWidth number #
borderRightWidth number #
borderTopWidth number #
borderWidth number #
bottom number #
flex number #
flexDirection enum('row', 'column') #
flexWrap enum('wrap', 'nowrap') #
height number #
justifyContent enum('flex-start', 'flex-end', 'center', 'space-between', 'space-around') #
left number #
margin number #
marginBottom number #
marginHorizontal number #
marginLeft number #
marginRight number #
marginTop number #
marginVertical number #
padding number #
paddingBottom number #
paddingHorizontal number #
paddingLeft number #
paddingRight number #
paddingTop number #
paddingVertical number #
position enum('absolute', 'relative') #
right number #
top number #
width number #
Gesture Responder System # | Edit on GitHub |
Gesture recognition on mobile devices is much more complicated than web. A touch can go through several phases as the app determines what the user's intention is. For example, the app needs to determine if the touch is scrolling, sliding on a widget, or tapping. This can even change during the duration of a touch. There can also be multiple simultaneous touches.
The touch responder system is needed to allow components to negotiate these touch interactions without any additional knowledge about their parent or child components. This system is implemented in ResponderEventPlugin.js, which contains further details and documentation.
Best Practices #
Users can feel huge differences in the usability of web apps vs. native, and this is one of the big causes. Every action should have the following attributes:
- Feedback/highlighting- show the user what is handling their touch, and what will happen when they release the gesture
- Cancel-ability- when making an action, the user should be able to abort it mid-touch by dragging their finger away
These features make users more comfortable while using an app, because it allows people to experiment and interact without fear of making mistakes.
TouchableHighlight and Touchable* #
The responder system can be complicated to use. So we have provided an abstract Touchable implementation for things that should be "tappable". This uses the responder system and allows you to easily configure tap interactions declaratively. Use TouchableHighlight anywhere where you would use a button or link on web.
Responder Lifecycle #
A view can become the touch responder by implementing the correct negotiation methods. There are two methods to ask the view if it wants to become responder:
View.props.onStartShouldSetResponder: (evt) => true,- Does this view want to become responder on the start of a touch?View.props.onMoveShouldSetResponder: (evt) => true,- Called for every touch move on the View when it is not the responder: does this view want to "claim" touch responsiveness?
If the View returns true and attempts to become the responder, one of the following will happen:
View.props.onResponderGrant: (evt) => {}- The View is now responding for touch events. This is the time to highlight and show the user what is happeningView.props.onResponderReject: (evt) => {}- Something else is the responder right now and will not release it
If the view is responding, the following handlers can be called:
View.props.onResponderMove: (evt) => {}- The user is moving their fingerView.props.onResponderRelease: (evt) => {}- Fired at the end of the touch, ie "touchUp"View.props.onResponderTerminationRequest: (evt) => true- Something else wants to become responder. Should this view release the responder? Returning true allows releaseView.props.onResponderTerminate: (evt) => {}- The responder has been taken from the View. Might be taken by other views after a call toonResponderTerminationRequest, or might be taken by the OS without asking (happens with control center/ notification center on iOS)
evt is a synthetic touch event with the following form:
nativeEventchangedTouches- Array of all touch events that have changed since the last eventidentifier- The ID of the touchlocationX- The X position of the touch, relative to the elementlocationY- The Y position of the touch, relative to the elementpageX- The X position of the touch, relative to the root elementpageY- The Y position of the touch, relative to the root elementtarget- The node id of the element receiving the touch eventtimestamp- A time identifier for the touch, useful for velocity calculationtouches- Array of all current touches on the screen
Capture ShouldSet Handlers #
onStartShouldSetResponder and onMoveShouldSetResponder are called with a bubbling pattern, where the deepest node is called first. That means that the deepest component will become responder when multiple Views return true for *ShouldSetResponder handlers. This is desirable in most cases, because it makes sure all controls and buttons are usable.
However, sometimes a parent will want to make sure that it becomes responder. This can be handled by using the capture phase. Before the responder system bubbles up from the deepest component, it will do a capture phase, firing on*ShouldSetResponderCapture. So if a parent View wants to prevent the child from becoming responder on a touch start, it should have a onStartShouldSetResponderCapture handler which returns true.
View.props.onStartShouldSetResponderCapture: (evt) => true,View.props.onMoveShouldSetResponderCapture: (evt) => true,
PanResponder #
For higher-level gesture interpretation, check out PanResponder.
Gesture Responder System # | Edit on GitHub |
Gesture recognition on mobile devices is much more complicated than web. A touch can go through several phases as the app determines what the user's intention is. For example, the app needs to determine if the touch is scrolling, sliding on a widget, or tapping. This can even change during the duration of a touch. There can also be multiple simultaneous touches.
The touch responder system is needed to allow components to negotiate these touch interactions without any additional knowledge about their parent or child components. This system is implemented in ResponderEventPlugin.js, which contains further details and documentation.
Best Practices #
Users can feel huge differences in the usability of web apps vs. native, and this is one of the big causes. Every action should have the following attributes:
- Feedback/highlighting- show the user what is handling their touch, and what will happen when they release the gesture
- Cancel-ability- when making an action, the user should be able to abort it mid-touch by dragging their finger away
These features make users more comfortable while using an app, because it allows people to experiment and interact without fear of making mistakes.
TouchableHighlight and Touchable* #
The responder system can be complicated to use. So we have provided an abstract Touchable implementation for things that should be "tappable". This uses the responder system and allows you to easily configure tap interactions declaratively. Use TouchableHighlight anywhere where you would use a button or link on web.
Responder Lifecycle #
A view can become the touch responder by implementing the correct negotiation methods. There are two methods to ask the view if it wants to become responder:
View.props.onStartShouldSetResponder: (evt) => true,- Does this view want to become responder on the start of a touch?View.props.onMoveShouldSetResponder: (evt) => true,- Called for every touch move on the View when it is not the responder: does this view want to "claim" touch responsiveness?
If the View returns true and attempts to become the responder, one of the following will happen:
View.props.onResponderGrant: (evt) => {}- The View is now responding for touch events. This is the time to highlight and show the user what is happeningView.props.onResponderReject: (evt) => {}- Something else is the responder right now and will not release it
If the view is responding, the following handlers can be called:
View.props.onResponderMove: (evt) => {}- The user is moving their fingerView.props.onResponderRelease: (evt) => {}- Fired at the end of the touch, ie "touchUp"View.props.onResponderTerminationRequest: (evt) => true- Something else wants to become responder. Should this view release the responder? Returning true allows releaseView.props.onResponderTerminate: (evt) => {}- The responder has been taken from the View. Might be taken by other views after a call toonResponderTerminationRequest, or might be taken by the OS without asking (happens with control center/ notification center on iOS)
evt is a synthetic touch event with the following form:
nativeEventchangedTouches- Array of all touch events that have changed since the last eventidentifier- The ID of the touchlocationX- The X position of the touch, relative to the elementlocationY- The Y position of the touch, relative to the elementpageX- The X position of the touch, relative to the root elementpageY- The Y position of the touch, relative to the root elementtarget- The node id of the element receiving the touch eventtimestamp- A time identifier for the touch, useful for velocity calculationtouches- Array of all current touches on the screen
Capture ShouldSet Handlers #
onStartShouldSetResponder and onMoveShouldSetResponder are called with a bubbling pattern, where the deepest node is called first. That means that the deepest component will become responder when multiple Views return true for *ShouldSetResponder handlers. This is desirable in most cases, because it makes sure all controls and buttons are usable.
However, sometimes a parent will want to make sure that it becomes responder. This can be handled by using the capture phase. Before the responder system bubbles up from the deepest component, it will do a capture phase, firing on*ShouldSetResponderCapture. So if a parent View wants to prevent the child from becoming responder on a touch start, it should have a onStartShouldSetResponderCapture handler which returns true.
View.props.onStartShouldSetResponderCapture: (evt) => true,View.props.onMoveShouldSetResponderCapture: (evt) => true,
PanResponder #
For higher-level gesture interpretation, check out PanResponder.
Getting Started # | Edit on GitHub |
Requirements #
- OS X - This guide assumes OS X which is needed for iOS development.
- Homebrew is the recommended way to install Watchman and Flow.
- Install Node.js 4.0 or newer.
- Install nvm with its setup instructions here. Then run
nvm install node && nvm alias default node, which installs the latest version of Node.js and sets up your terminal so you can run it by typingnode. With nvm you can install multiple versions of Node.js and easily switch between them. - New to npm?
- Install nvm with its setup instructions here. Then run
brew install watchman. We recommend installing watchman, otherwise you might hit a node file watching bug.brew install flow, if you want to use flow.
We recommend periodically running brew update && brew upgrade to keep your programs up-to-date.
iOS Setup #
Xcode 7.0 or higher is required. It can be installed from the App Store.
Android Setup #
To write React Native apps for Android, you will need to install the Android SDK (and an Android emulator if you want to work on your app without having to use a physical device). See Android setup guide for instructions on how to set up your Android environment.
NOTE: There is experimental Windows and Linux support for Android development.
Quick start #
To run the iOS app:
$ cd AwesomeProject- Open
ios/AwesomeProject.xcodeprojand hit run in Xcode. - Open
index.ios.jsin your text editor of choice and edit some lines. - Hit ⌘-R in your iOS simulator to reload the app and see your change!
Note: If you are using an iOS device, see the Running on iOS Device page.
To run the Android app:
$ cd AwesomeProject$ react-native run-android- Open
index.android.jsin your text editor of choice and edit some lines. - Press the menu button (F2 by default, or ⌘-M in Genymotion) and select Reload JS to see your change!
- Run
adb logcat *:S ReactNative:V ReactNativeJS:Vin a terminal to see your app's logs
Note: If you are using an Android device, see the Running on Android Device page.
Congratulations! You've successfully run and modified your first React Native app.
If you run into any issues getting started, see the troubleshooting page.
Adding Android to an existing React Native project #
If you already have a (iOS-only) React Native project and want to add Android support, you need to execute the following commands in your existing project directory:
- Update the
react-nativedependency in yourpackage.jsonfile to the latest version $ npm install$ react-native android
JavaScript Environment # | Edit on GitHub |
JavaScript Runtime #
When using React Native, you're going to be running your JavaScript code in two environments:
- On iOS simulators and devices, Android emulators and devices React Native uses JavaScriptCore which is the JavaScript engine that powers Safari. On iOS JSC doesn't use JIT due to the absence of writable executable memory in iOS apps.
- When using Chrome debugging, it runs all the JavaScript code within Chrome itself and communicates with native code via WebSocket. So you are using V8.
While both environments are very similar, you may end up hitting some inconsistencies. We're likely going to experiment with other JS engines in the future, so it's best to avoid relying on specifics of any runtime.
JavaScript Syntax Transformers #
Syntax transformers make writing code more enjoyable by allowing you to use new JavaScript syntax without having to wait for support on all interpreters.
As of version 0.5.0, React Native ships with the Babel JavaScript compiler. Check Babel documentation on its supported transformations for more details.
Here's a full list of React Native's enabled transformations.
ES5
- Reserved Words:
promise.catch(function() { });
ES6
- Arrow functions:
<C onPress={() => this.setState({pressed: true})} - Block scoping:
let greeting = 'hi'; - Call spread:
Math.max(...array); - Classes:
class C extends React.Component { render() { return <View />; } } - Constants:
const answer = 42; - Destructuring:
var {isActive, style} = this.props; - Modules:
import React, { Component } from 'react-native'; - Computed Properties:
var key = 'abc'; var obj = {[key]: 10}; - Object Consise Method:
var obj = { method() { return 10; } }; - Object Short Notation:
var name = 'vjeux'; var obj = { name }; - Rest Params:
function(type, ...args) { } - Template Literals:
var who = 'world'; var str = `Hello ${who}`;
ES7
- Object Spread:
var extended = { ...obj, a: 10 }; - Function Trailing Comma:
function f(a, b, c,) { } - Async Functions:
async function doStuffAsync() { const foo = await doOtherStuffAsync(); };
JavaScript Environment # | Edit on GitHub |
JavaScript Runtime #
When using React Native, you're going to be running your JavaScript code in two environments:
- On iOS simulators and devices, Android emulators and devices React Native uses JavaScriptCore which is the JavaScript engine that powers Safari. On iOS JSC doesn't use JIT due to the absence of writable executable memory in iOS apps.
- When using Chrome debugging, it runs all the JavaScript code within Chrome itself and communicates with native code via WebSocket. So you are using V8.
While both environments are very similar, you may end up hitting some inconsistencies. We're likely going to experiment with other JS engines in the future, so it's best to avoid relying on specifics of any runtime.
JavaScript Syntax Transformers #
Syntax transformers make writing code more enjoyable by allowing you to use new JavaScript syntax without having to wait for support on all interpreters.
As of version 0.5.0, React Native ships with the Babel JavaScript compiler. Check Babel documentation on its supported transformations for more details.
Here's a full list of React Native's enabled transformations.
ES5
- Reserved Words:
promise.catch(function() { });
ES6
- Arrow functions:
<C onPress={() => this.setState({pressed: true})} - Block scoping:
let greeting = 'hi'; - Call spread:
Math.max(...array); - Classes:
class C extends React.Component { render() { return <View />; } } - Constants:
const answer = 42; - Destructuring:
var {isActive, style} = this.props; - Modules:
import React, { Component } from 'react-native'; - Computed Properties:
var key = 'abc'; var obj = {[key]: 10}; - Object Consise Method:
var obj = { method() { return 10; } }; - Object Short Notation:
var name = 'vjeux'; var obj = { name }; - Rest Params:
function(type, ...args) { } - Template Literals:
var who = 'world'; var str = `Hello ${who}`;
ES7
- Object Spread:
var extended = { ...obj, a: 10 }; - Function Trailing Comma:
function f(a, b, c,) { } - Async Functions:
async function doStuffAsync() { const foo = await doOtherStuffAsync(); };
Linux and Windows Support # | Edit on GitHub |
NOTE: This guide focuses on Android development. You'll need a Mac to build iOS apps.
As React Native on iOS requires a Mac and most of the engineers at Facebook and contributors use Macs, support for OS X is a top priority. However, we would like to support developers using Linux and Windows too. We believe we'll get the best Linux and Windows support from people using these operating systems on a daily basis.
Therefore, Linux and Windows support for the development environment is an ongoing community responsibility. This can mean filing issues and submitting PRs, and we'll help review and merge them. We are looking forward to your contributions and appreciate your patience.
As of version 0.14 Android development with React native is mostly possible on Linux and Windows. You'll need to install Node.js 4.0 or newer. On Linux we recommend installing watchman, otherwise you might hit a node file watching bug.
What's missing on Windows #
On Windows the packager won't be started automatically when you run react-native run-android. You can start it manually using:
If you hit a ERROR Watcher took too long to load on Windows, try increasing the timeout in this file (under your node_modules/react-native).
MapView # | Edit on GitHub |
Props #
onAnnotationPress function #
Deprecated. Use annotation onFocus and onBlur instead.
onRegionChange function #
Callback that is called continuously when the user is dragging the map.
onRegionChangeComplete function #
Callback that is called once, when the user is done moving the map.
pitchEnabled bool #
When this property is set to true and a valid camera is associated
+
MapView # | Edit on GitHub |
Props #
onAnnotationPress function #
Deprecated. Use annotation onFocus and onBlur instead.
onRegionChange function #
Callback that is called continuously when the user is dragging the map.
onRegionChangeComplete function #
Callback that is called once, when the user is done moving the map.
pitchEnabled bool #
When this property is set to true and a valid camera is associated
with the map, the camera’s pitch angle is used to tilt the plane
of the map. When this property is set to false, the camera’s pitch
angle is ignored and the map is always displayed as if the user
@@ -10,7 +10,7 @@ camera’s heading angle is ignored and the map is always oriented so
that true north is situated at the top of the map view
scrollEnabled bool #
If false the user won't be able to change the map region being displayed.
Default value is true.
showsUserLocation bool #
If true the app will ask for the user's location and display it on
the map. Default value is false.
NOTE: on iOS, you need to add the NSLocationWhenInUseUsageDescription
-key in Info.plist to enable geolocation, otherwise it will fail silently.
style View#style #
Used to style and layout the MapView. See StyleSheet.js and
+key in Info.plist to enable geolocation, otherwise it will fail silently.
style View#style #
Used to style and layout the MapView. See StyleSheet.js and
ViewStylePropTypes.js for more info.
zoomEnabled bool #
If false the user won't be able to pinch/zoom the map.
Default value is true.
androidactive bool #
iosannotations [{latitude: number, longitude: number, animateDrop: bool, draggable: bool, onDragStateChange: function, onFocus: function, onBlur: function, title: string, subtitle: string, leftCalloutView: element, rightCalloutView: element, detailCalloutView: element, tintColor: [object Object], image: Image.propTypes.source, view: element, id: string, hasLeftCallout: deprecatedPropType( React.PropTypes.bool, @@ -420,7 +420,7 @@ exports.examples />; } }, -];
PickerIOS # | Edit on GitHub |
Examples # | Edit on GitHub |
PickerIOS # | Edit on GitHub |
Examples # | Edit on GitHub |
ProgressViewIOS # | Edit on GitHub |
Use ProgressViewIOS to render a UIProgressView on iOS.
Props #
progress number #
The progress value (between 0 and 1).
progressImage Image.propTypes.source #
A stretchable image to display as the progress bar.
progressTintColor string #
The tint color of the progress bar itself.
progressViewStyle enum('default', 'bar') #
The progress bar style.
trackImage Image.propTypes.source #
A stretchable image to display behind the progress bar.
trackTintColor string #
The tint color of the progress bar track.
Examples # | Edit on GitHub |
ProgressViewIOS # | Edit on GitHub |
Use ProgressViewIOS to render a UIProgressView on iOS.
Props #
progress number #
The progress value (between 0 and 1).
progressImage Image.propTypes.source #
A stretchable image to display as the progress bar.
progressTintColor string #
The tint color of the progress bar itself.
progressViewStyle enum('default', 'bar') #
The progress bar style.
trackImage Image.propTypes.source #
A stretchable image to display behind the progress bar.
trackTintColor string #
The tint color of the progress bar track.
Examples # | Edit on GitHub |
PullToRefreshViewAndroid # | Edit on GitHub |
React view that supports a single scrollable child view (e.g. ScrollView). When this child
view is at scrollY: 0, swiping down triggers an onRefresh event.
The style {flex: 1} might be required to ensure the expected behavior of the child component
-(e.g. when the child is expected to scroll with ScrollView or ListView).
Props #
colors [[object Object]] #
The colors (at least one) that will be used to draw the refresh indicator
enabled bool #
Whether the pull to refresh functionality is enabled
refreshing bool #
Whether the view should be indicating an active refresh
size RefreshLayoutConsts.SIZE.DEFAULT #
Size of the refresh indicator, see PullToRefreshViewAndroid.SIZE
Examples # | Edit on GitHub |
ScrollView or ListView).Props #
colors [[object Object]] #
The colors (at least one) that will be used to draw the refresh indicator
enabled bool #
Whether the pull to refresh functionality is enabled
refreshing bool #
Whether the view should be indicating an active refresh
size RefreshLayoutConsts.SIZE.DEFAULT #
Size of the refresh indicator, see PullToRefreshViewAndroid.SIZE
Examples # | Edit on GitHub |
RefreshControl # | Edit on GitHub |
This component is used inside a ScrollView to add pull to refresh
functionality. When the ScrollView is at scrollY: 0, swiping down
-triggers an onRefresh event.
Props #
onRefresh function #
Called when the view starts refreshing.
refreshing bool #
Whether the view should be indicating an active refresh.
androidcolors [[object Object]] #
The colors (at least one) that will be used to draw the refresh indicator.
androidenabled bool #
Whether the pull to refresh functionality is enabled.
androidsize RefreshLayoutConsts.SIZE.DEFAULT #
Size of the refresh indicator, see RefreshControl.SIZE.
iostitle string #
The title displayed under the refresh indicator.
Examples # | Edit on GitHub |
onRefresh event.Props #
onRefresh function #
Called when the view starts refreshing.
refreshing bool #
Whether the view should be indicating an active refresh.
androidcolors [[object Object]] #
The colors (at least one) that will be used to draw the refresh indicator.
androidenabled bool #
Whether the pull to refresh functionality is enabled.
androidsize RefreshLayoutConsts.SIZE.DEFAULT #
Size of the refresh indicator, see RefreshControl.SIZE.
iostitle string #
The title displayed under the refresh indicator.
Examples # | Edit on GitHub |
Running On Device # | Edit on GitHub |
Prerequisite: USB Debugging #
You'll need this in order to install your app on your device. First, make sure you have USB debugging enabled on your device.
Check that your device has been successfully connected by running adb devices:
Seeing device in the right column means the device is connected. Android - go figure :) You must have only one device connected.
Now you can use react-native run-android to install and launch your app on the device.
Accessing development server from device #
You can also iterate quickly on device using the development server. Follow one of the steps described below to make your development server running on your laptop accessible for your device.
Hint
Most modern android devices don't have a hardware menu button, which we use to trigger the developer menu. In that case you can shake the device to open the dev menu (to reload, debug, etc.). Alternatively, you can run the command
adb shell input keyevent 82to open the dev menu (82 being the Menu key code).
Using adb reverse #
Note that this option is available on devices running android 5.0+ (API 21).
Have your device connected via USB with debugging enabled (see paragraph above on how to enable USB debugging on your device).
- Run
adb reverse tcp:8081 tcp:8081 - You can use
Reload JSand other development options with no extra configuration
Configure your app to connect to the local dev server via Wi-Fi #
- Make sure your laptop and your phone are on the same Wi-Fi network.
- Open your React Native app on your device. You can do this the same way you'd open any other app.
- You'll see a red screen with an error. This is OK. The following steps will fix that.
- Open the Developer menu by shaking the device or running
adb shell input keyevent 82from the command line. - Go to
Dev Settings. - Go to
Debug server host for device. - Type in your machine's IP address and the port of the local dev server (e.g. 10.0.1.1:8081). On Mac, you can find the IP address in System Preferences / Network. On Windows, open the command prompt and type
ipconfigto find your machine's IP address (more info). - Go back to the Developer menu and select
Reload JS.
Running On Device # | Edit on GitHub |
Note that running on device requires Apple Developer account and provisioning your iPhone. This guide covers only React Native specific topic.
Accessing development server from device #
You can iterate quickly on device using development server. To do that, your laptop and your phone have to be on the same wifi network.
- Open
AwesomeApp/ios/AwesomeApp/AppDelegate.m - Change the IP in the URL from
localhostto your laptop's IP. On Mac, you can find the IP address in System Preferences / Network. - In Xcode select your phone as build target and press "Build and run"
Hint
Shake the device to open development menu (reload, debug, etc.)
Using offline bundle #
When you run your app on device, we pack all the JavaScript code and the images used into the app's resources. This way you can test it without development server running and submit the app to the AppStore.
- Open
AwesomeApp/ios/AwesomeApp/AppDelegate.m - Uncomment
jsCodeLocation = [[NSBundle mainBundle] ... - The JS bundle will be built for dev or prod depending on your app's scheme (Debug = development build with warnings, Release = minified prod build with perf optimizations). To change the scheme navigate to
Product > Scheme > Edit Scheme...in xcode and changeBuild ConfigurationbetweenDebugandRelease.
Disabling in-app developer menu #
When building your app for production, your app's scheme should be set to Release as detailed in the debugging documentation in order to disable the in-app developer menu.
Troubleshooting #
If curl command fails make sure the packager is running. Also try adding --ipv4 flag to the end of it.
Note that since v0.14 JS and images are automatically packaged into the iOS app using Bundle React Native code and images Xcode build phase.
Running On Device # | Edit on GitHub |
Note that running on device requires Apple Developer account and provisioning your iPhone. This guide covers only React Native specific topic.
Accessing development server from device #
You can iterate quickly on device using development server. To do that, your laptop and your phone have to be on the same wifi network.
- Open
AwesomeApp/ios/AwesomeApp/AppDelegate.m - Change the IP in the URL from
localhostto your laptop's IP. On Mac, you can find the IP address in System Preferences / Network. - In Xcode select your phone as build target and press "Build and run"
Hint
Shake the device to open development menu (reload, debug, etc.)
Using offline bundle #
When you run your app on device, we pack all the JavaScript code and the images used into the app's resources. This way you can test it without development server running and submit the app to the AppStore.
- Open
AwesomeApp/ios/AwesomeApp/AppDelegate.m - Uncomment
jsCodeLocation = [[NSBundle mainBundle] ... - The JS bundle will be built for dev or prod depending on your app's scheme (Debug = development build with warnings, Release = minified prod build with perf optimizations). To change the scheme navigate to
Product > Scheme > Edit Scheme...in xcode and changeBuild ConfigurationbetweenDebugandRelease.
Disabling in-app developer menu #
When building your app for production, your app's scheme should be set to Release as detailed in the debugging documentation in order to disable the in-app developer menu.
Troubleshooting #
If curl command fails make sure the packager is running. Also try adding --ipv4 flag to the end of it.
Note that since v0.14 JS and images are automatically packaged into the iOS app using Bundle React Native code and images Xcode build phase.
SegmentedControlIOS # | Edit on GitHub |
Use SegmentedControlIOS to render a UISegmentedControl iOS.
Props #
enabled bool #
If false the user won't be able to interact with the control. +
SegmentedControlIOS # | Edit on GitHub |
Use SegmentedControlIOS to render a UISegmentedControl iOS.
Props #
enabled bool #
If false the user won't be able to interact with the control. Default value is true.
momentary bool #
If true, then selecting a segment won't persist visually.
The onValueChange callback will still work as expected.
onChange function #
Callback that is called when the user taps a segment; passes the event as an argument
onValueChange function #
Callback that is called when the user taps a segment; @@ -155,7 +155,7 @@ exports.examples : 'Change events can be detected', render(): ReactElement { return <EventSegmentedControlExample />; } } -];
SliderIOS # | Edit on GitHub |
Props #
disabled bool #
If true the user won't be able to move the slider. +
SliderIOS # | Edit on GitHub |
Props #
disabled bool #
If true the user won't be able to move the slider. Default value is false.
maximumTrackImage Image.propTypes.source #
Assigns a maximum track image. Only static images are supported. The leftmost pixel of the image will be stretched to fill the track.
maximumTrackTintColor string #
The color used for the track to the right of the button. Overrides the default blue gradient image.
maximumValue number #
Initial maximum value of the slider. Default value is 1.
minimumTrackImage Image.propTypes.source #
Assigns a minimum track image. Only static images are supported. The @@ -6,7 +6,7 @@ rightmost pixel of the image will be stretched to fill the track.
minimumValue number #
Initial minimum value of the slider. Default value is 0.
onSlidingComplete function #
Callback called when the user finishes changing the value (e.g. when the slider is released).
onValueChange function #
Callback continuously called while the user is dragging the slider.
step number #
Step value of the slider. The value should be between 0 and (maximumValue - minimumValue). -Default value is 0.
style View#style #
Used to style and layout the Slider. See StyleSheet.js and
+Default value is 0.
style View#style #
Used to style and layout the Slider. See StyleSheet.js and
ViewStylePropTypes.js for more info.
thumbImage Image.propTypes.source #
Sets an image for the thumb. It only supports static images.
trackImage Image.propTypes.source #
Assigns a single image for the track. Only static images are supported. The center pixel of the image will be stretched to fill the track.
value number #
Initial value of the slider. The value should be between minimumValue and maximumValue, which default to 0 and 1 respectively. @@ -116,7 +116,7 @@ exports.examples ); } }, -];
Switch # | Edit on GitHub |
Universal two-state toggle component.
Props #
disabled bool #
If true the user won't be able to toggle the switch. +
Switch # | Edit on GitHub |
Universal two-state toggle component.
Props #
disabled bool #
If true the user won't be able to toggle the switch. Default value is false.
onValueChange function #
Invoked with the new value when the value changes.
testID string #
Used to locate this view in end-to-end tests.
value bool #
The value of the switch. If true the switch will be turned on. -Default value is false.
Examples # | Edit on GitHub |
Examples # | Edit on GitHub |
< exports.title = '<Switch>'; exports.displayName = 'SwitchExample'; exports.description = 'Native boolean input'; -exports.examples = examples;
TabBarIOS.Item # | Edit on GitHub |
Props #
badge string, number #
Little red bubble that sits at the top right of the icon.
icon Image.propTypes.source #
A custom icon for the tab. It is ignored when a system icon is defined.
onPress function #
Callback when this tab is being selected, you should change the state of your +
TabBarIOS.Item # | Edit on GitHub |
Props #
badge string, number #
Little red bubble that sits at the top right of the icon.
icon Image.propTypes.source #
A custom icon for the tab. It is ignored when a system icon is defined.
onPress function #
Callback when this tab is being selected, you should change the state of your component to set selected={true}.
selected bool #
It specifies whether the children are visible or not. If you see a blank content, you probably forgot to add a selected one.
selectedIcon Image.propTypes.source #
A custom icon when the tab is selected. It is ignored when a system -icon is defined. If left empty, the icon will be tinted in blue.
style View#style #
React style object.
systemIcon enum('bookmarks', 'contacts', 'downloads', 'favorites', 'featured', 'history', 'more', 'most-recent', 'most-viewed', 'recents', 'search', 'top-rated') #
Items comes with a few predefined system icons. Note that if you are +icon is defined. If left empty, the icon will be tinted in blue.
style View#style #
React style object.
systemIcon enum('bookmarks', 'contacts', 'downloads', 'favorites', 'featured', 'history', 'more', 'most-recent', 'most-viewed', 'recents', 'search', 'top-rated') #
Items comes with a few predefined system icons. Note that if you are using them, the title and selectedIcon will be overridden with the system ones.
title string #
Text that appears under the icon. It is ignored when a system icon -is defined.
TabBarIOS # | Edit on GitHub |
Props #
style View#style #
translucent bool #
A Boolean value that indicates whether the tab bar is translucent
Examples # | Edit on GitHub |
TabBarIOS # | Edit on GitHub |
Props #
style View#style #
translucent bool #
A Boolean value that indicates whether the tab bar is translucent
Examples # | Edit on GitHub |
WebView # | Edit on GitHub |
Renders a native WebView.
Props #
automaticallyAdjustContentInsets bool #
contentInset {top: number, left: number, bottom: number, right: number} #
html string #
DeprecatedUse the source prop instead.
injectedJavaScript string #
Sets the JS to be injected when the webpage loads.
onError function #
Invoked when load fails
onLoad function #
Invoked when load finish
onLoadEnd function #
Invoked when load either succeeds or fails
onLoadStart function #
Invoked on load start
onNavigationStateChange function #
renderError function #
Function that returns a view to show if there's an error.
renderLoading function #
Function that returns a loading indicator.
source {uri: string, method: string, headers: object, body: string}, {html: string, baseUrl: string}, number #
Loads static html or a uri (with optional headers) in the WebView.
startInLoadingState bool #
style View#style #
url string #
DeprecatedUse the source prop instead.
androiddomStorageEnabled bool #
Used on Android only, controls whether DOM Storage is enabled or not
androidjavaScriptEnabled bool #
Used on Android only, JS is enabled by default for WebView on iOS
iosallowsInlineMediaPlayback bool #
Determines whether HTML5 videos play inline or use the native full-screen +
WebView # | Edit on GitHub |
Renders a native WebView.
Props #
automaticallyAdjustContentInsets bool #
contentInset {top: number, left: number, bottom: number, right: number} #
html string #
DeprecatedUse the source prop instead.
injectedJavaScript string #
Sets the JS to be injected when the webpage loads.
onError function #
Invoked when load fails
onLoad function #
Invoked when load finish
onLoadEnd function #
Invoked when load either succeeds or fails
onLoadStart function #
Invoked on load start
onNavigationStateChange function #
renderError function #
Function that returns a view to show if there's an error.
renderLoading function #
Function that returns a loading indicator.
source {uri: string, method: string, headers: object, body: string}, {html: string, baseUrl: string}, number #
Loads static html or a uri (with optional headers) in the WebView.
startInLoadingState bool #
style View#style #
url string #
DeprecatedUse the source prop instead.
androiddomStorageEnabled bool #
Used on Android only, controls whether DOM Storage is enabled or not
androidjavaScriptEnabled bool #
Used on Android only, JS is enabled by default for WebView on iOS
iosallowsInlineMediaPlayback bool #
Determines whether HTML5 videos play inline or use the native full-screen
controller.
default value false
NOTE : "In order for video to play inline, not only does this
@@ -313,7 +313,7 @@ exports.examples );
}
}
-];