React NativeAccessibility #
Native App Accessibility (iOS and Android) #
Both iOS and Android provide APIs for making apps accessible to people with disabilities. In addition, both platforms provide bundled assistive technologies, like the screen readers VoiceOver (iOS) and TalkBack (Android) for the visually impaired. Similarly, in React Native we have included APIs designed to provide developers with support for making apps more accessible. Take note, iOS and Android differ slightly in their approaches, and thus the React Native implementations may vary by platform.
In addition to this documentation, you might find this blog post about React Native accessibility to be useful.
Making Apps Accessible #
Accessibility properties #
accessible (iOS, Android) #
When true, indicates that the view is an accessibility element. When a view is an accessibility element, it groups its children into a single selectable component. By default, all touchable elements are accessible.
On Android, ‘accessible={true}’ property for a react-native View will be translated into native ‘focusable={true}’.
Accessibility #
Native App Accessibility (iOS and Android) #
Both iOS and Android provide APIs for making apps accessible to people with disabilities. In addition, both platforms provide bundled assistive technologies, like the screen readers VoiceOver (iOS) and TalkBack (Android) for the visually impaired. Similarly, in React Native we have included APIs designed to provide developers with support for making apps more accessible. Take note, iOS and Android differ slightly in their approaches, and thus the React Native implementations may vary by platform.
In addition to this documentation, you might find this blog post about React Native accessibility to be useful.
Making Apps Accessible #
Accessibility properties #
accessible (iOS, Android) #
When true, indicates that the view is an accessibility element. When a view is an accessibility element, it groups its children into a single selectable component. By default, all touchable elements are accessible.
On Android, ‘accessible={true}’ property for a react-native View will be translated into native ‘focusable={true}’.
In the above example, we can't get accessibility focus separately on 'text one' and 'text two'. Instead we get focus on a parent view with 'accessible' property.
accessibilityLabel (iOS, Android) #
When a view is marked as accessible, it is a good practice to set an accessibilityLabel on the view, so that people who use VoiceOver know what element they have selected. VoiceOver will read this string when a user selects the associated element.
To use, set the accessibilityLabel property to a custom string on your View:
B contains a child view C a
<CustomRadioButton
accessibleComponentType={this.state.radioButton}
- onPress={this._onPress}/>In the above example we've created a custom radio button that now behaves like a native one. More specifically, TalkBack now correctly announces changes to the radio button selection.
Testing VoiceOver Support (iOS) #
To enable VoiceOver, go to the Settings app on your iOS device. Tap General, then Accessibility. There you will find many tools that people use to make their devices more usable, such as bolder text, increased contrast, and VoiceOver.
To enable VoiceOver, tap on VoiceOver under "Vision" and toggle the switch that appears at the top.
At the very bottom of the Accessibility settings, there is an "Accessibility Shortcut". You can use this to toggle VoiceOver by triple clicking the Home button.
You can edit the content above on GitHub and send us a pull request!
AccessibilityInfo #
Sometimes it's useful to know whether or not the device has a screen reader that is currently active. The +
AccessibilityInfo #
Sometimes it's useful to know whether or not the device has a screen reader that is currently active. The
AccessibilityInfo API is designed for this purpose. You can use it to query the current state of the
screen reader as well as to register to be notified when the state of the screen reader changes.
Here's a small example illustrating how to use AccessibilityInfo:
false otherwise.static setAccessibilityFocus(reactTag) #
iOS-Only. Set accessibility focus to a react component.
iOS-Only. Set accessibility focus to a react component.
static announceForAccessibility(announcement) #
iOS-Only. Post a string to be announced by the screen reader.
static removeEventListener(eventName, handler) #
Remove an event handler.
You can edit the content above on GitHub and send us a pull request!
ActionSheetIOS #
Methods #
static showActionSheetWithOptions(options, callback) #
Display an iOS action sheet. The options object must contain one or more
+
ActionSheetIOS #
Methods #
static showActionSheetWithOptions(options, callback) #
Display an iOS action sheet. The options object must contain one or more
of:
options(array of strings) - a list of button titles (required)cancelButtonIndex(int) - index of cancel button inoptionsdestructiveButtonIndex(int) - index of destructive button inoptionstitle(string) - a title to show above the action sheetmessage(string) - a message to show below the title
static showShareActionSheetWithOptions(options, failureCallback, successCallback) #
Display the iOS share sheet. The options object should contain
one or both of message and url and can additionally have
a subject or excludedActivityTypes:
url(string) - a URL to sharemessage(string) - a message to sharesubject(string) - a subject for the messageexcludedActivityTypes(array) - the activities to exclude from the ActionSheet
NOTE: if url points to a local file, or is a base64-encoded
uri, the file it points to will be loaded and shared directly.
-In this way, you can share images, videos, PDF files, etc.
You can edit the content above on GitHub and send us a pull request!
ActivityIndicator #
Displays a circular loading indicator.
Props #
animating?: bool #
Whether to show the indicator (true, the default) or hide it (false).
size?: enum('small', 'large'), number #
Size of the indicator (default is 'small'). -Passing a number to the size prop is only supported on Android.
ioshidesWhenStopped?: bool #
Whether the indicator should hide when not animating (true by default).
You can edit the content above on GitHub and send us a pull request!
ActivityIndicator #
Displays a circular loading indicator.
Props #
animating?: bool #
Whether to show the indicator (true, the default) or hide it (false).
size?: enum('small', 'large'), number #
Size of the indicator (default is 'small'). +Passing a number to the size prop is only supported on Android.
ioshidesWhenStopped?: bool #
Whether the indicator should hide when not animating (true by default).
Improve this page by sending a pull request!
AdSupportIOS #
AdSupport provides access to the "advertising identifier". If you link this library
+
AdSupportIOS #
AdSupport provides access to the "advertising identifier". If you link this library
in your project, you may need to justify your use for this identifier when submitting
your application to the App Store.
In order to use AdSupport in your project, you must link the RCTAdSupport library.
In Xcode, you can manually add the RCTAdSupport.m and RCTAdSupport.h files from
node_modules/react-native/Libraries/AdSupport/ to the Libraries/React/Base/ folder
-of your current project.
You can refer to Linking for help.
Methods #
You can edit the content above on GitHub and send us a pull request!
Alert #
Launches an alert dialog with the specified title and message.
Optionally provide a list of buttons. Tapping any button will fire the +
Alert #
Launches an alert dialog with the specified title and message.
Optionally provide a list of buttons. Tapping any button will fire the respective onPress callback and dismiss the alert. By default, the only button will be an 'OK' button.
This is an API that works both on iOS and Android and can show static
alerts. To show an alert that prompts the user to enter some information,
@@ -18,7 +18,7 @@ i.e. { cancelable: false }
Example usage:
Methods #
static alert(title, message?, buttons?, options?, type?) #
You can edit the content above on GitHub and send us a pull request!
AlertIOS #
AlertIOS provides functionality to create an iOS alert dialog with a
+
AlertIOS #
AlertIOS provides functionality to create an iOS alert dialog with a
message or create a prompt for user input.
Creating an iOS alert:
Type Definitions #
AlertType #
An Alert button type
$Enum
Constants:
| Value | Description |
|---|---|
| default | Default alert with no inputs |
| plain-text | Plain text input alert |
| secure-text | Secure text input alert |
| login-password | Login and password alert |
AlertButtonStyle #
An Alert button style
$Enum
Constants:
| Value | Description |
|---|---|
| default | Default button style |
| cancel | Cancel button style |
| destructive | Destructive button style |
ButtonsArray #
Array or buttons
Array
Properties:
| Name and Type | Description |
|---|---|
| [text] string | Button label |
| [onPress] function | Callback function when button pressed |
| [style] | Button style |
Constants:
| Value | Description |
|---|---|
| text | Button label |
| onPress | Callback function when button pressed |
| style | Button style |
You can edit the content above on GitHub and send us a pull request!
Building React Native from source #
You will need to build React Native from source if you want to work on a new feature/bug fix, try out the latest features which are not released yet, or maintain your own fork with patches that cannot be merged to the core.
Prerequisites #
Assuming you have the Android SDK installed, run android to open the Android SDK Manager.
Make sure you have the following installed:
- Android SDK version 23 (compileSdkVersion in
build.gradle) - SDK build tools version 23.0.1 (buildToolsVersion in
build.gradle) - Android Support Repository >= 17 (for Android Support Library)
- Android NDK (download links and installation instructions below)
Point Gradle to your Android SDK: #
Step 1: Set environment variables through your local shell.
Note: Files may vary based on shell flavor. See below for examples from common shells.
- bash:
.bash_profileor.bashrc - zsh:
.zprofileor.zshrc - ksh:
.profileor$ENV
Example:
Building React Native from source #
You will need to build React Native from source if you want to work on a new feature/bug fix, try out the latest features which are not released yet, or maintain your own fork with patches that cannot be merged to the core.
Prerequisites #
Assuming you have the Android SDK installed, run android to open the Android SDK Manager.
Make sure you have the following installed:
- Android SDK version 23 (compileSdkVersion in
build.gradle) - SDK build tools version 23.0.1 (buildToolsVersion in
build.gradle) - Android Support Repository >= 17 (for Android Support Library)
- Android NDK (download links and installation instructions below)
Point Gradle to your Android SDK: #
Step 1: Set environment variables through your local shell.
Note: Files may vary based on shell flavor. See below for examples from common shells.
- bash:
.bash_profileor.bashrc - zsh:
.zprofileor.zshrc - ksh:
.profileor$ENV
Example:
Step 2: Create a local.properties file in the android directory of your react-native app with the following contents:
Example:
Download links for Android NDK #
- Mac OS (64-bit) - http://dl.google.com/android/repository/android-ndk-r10e-darwin-x86_64.zip
- Linux (64-bit) - http://dl.google.com/android/repository/android-ndk-r10e-linux-x86_64.zip
- Windows (64-bit) - http://dl.google.com/android/repository/android-ndk-r10e-windows-x86_64.zip
- Windows (32-bit) - http://dl.google.com/android/repository/android-ndk-r10e-windows-x86.zip
You can find further instructions on the official page.
Building the source #
1. Installing the fork #
First, you need to install react-native from your fork. For example, to install the master branch from the official repo, run the following:
Alternatively, you can clone the repo to your node_modules directory and run npm install inside the cloned repo.
2. Adding gradle dependencies #
Add gradle-download-task as dependency in android/build.gradle:
Building for Maven/Nexus deployment #
If you find that you need to push up a locally compiled React Native .aar and related files to a remote Nexus repository, you can.
Start by following the Point Gradle to your Android SDK section of this page. Once you do this, assuming you have Gradle configured properly, you can then run the following command from the root of your React Native checkout to build and package all required files:
This will package everything that would typically be included in the android directory of your node_modules/react-native/ installation in the root directory of your React Native checkout.
Testing #
If you made changes to React Native and submit a pull request, all tests will run on your pull request automatically. To run the tests locally, see Running Tests.
Troubleshooting #
Gradle build fails in ndk-build. See the section about local.properties file above.
You can edit the content above on GitHub and send us a pull request!
Animated #
The Animated library is designed to make animations fluid, powerful, and
+
Animated #
The Animated library is designed to make animations fluid, powerful, and
easy to build and maintain. Animated focuses on declarative relationships
between inputs and outputs, with configurable transforms in between, and
simple start/stop methods to control time-based animation execution.
The simplest workflow for creating an animation is to to create an
@@ -145,7 +145,7 @@ API to normal Animated.Value, but multiplexed. Contains two regula
}
}
Methods #
constructor(valueIn?) #
setValue(value) #
setOffset(offset) #
flattenOffset() #
extractOffset() #
resetAnimation(callback?) #
stopAnimation(callback?) #
addListener(callback) #
removeListener(id) #
removeAllListeners() #
getLayout() #
Converts {x, y} into {left, top} for use in style, e.g.
getTranslateTransform() #
Converts {x, y} into a useable translation transform, e.g.
class AnimatedInterpolation #
Methods #
You can edit the content above on GitHub and send us a pull request!
Animations #
Animations are very important to create a great user experience. +
Animations #
Animations are very important to create a great user experience. Stationary objects must overcome inertia as they start moving. Objects in motion have momentum and rarely come to a stop immediately. Animations allow you to convey physically believable motion in your interface.
React Native provides two complementary animation systems: @@ -285,7 +285,7 @@ option. You may also want to defer any computationally intensive work until after animations are complete, using the InteractionManager. You can monitor the -frame rate by using the In-App Developer Menu "FPS Monitor" tool.
You can edit the content above on GitHub and send us a pull request!
AppRegistry #
AppRegistry #
static startHeadlessTask(taskId, taskKey, data) #
Only called from native code. Starts a headless task.
@param taskId the native id for this task instance to keep track of its execution @param taskKey the key for the task to start -@param data the data to pass to the task
You can edit the content above on GitHub and send us a pull request!
AppState #
AppState can tell you if the app is in the foreground or background,
+
AppState #
AppState can tell you if the app is in the foreground or background,
and notify you when the state changes.
AppState is frequently used to determine the intent and proper behavior when handling push notifications.
App States #
active- The app is running in the foregroundbackground- The app is running in the background. The user is either in another app or on the home screeninactive- This is a state that occurs when transitioning between @@ -43,7 +43,7 @@ and providing the handlerTODO: now that AppState is a subclass of NativeE
addEventListenerandremoveEventListenerand just useaddListenerandlistener.remove()directly. That will be a breaking change though, as both the method and event names are different (addListener events are currently -required to be globally unique).
removeEventListener(type, handler) #
Remove a handler by passing the change event type and the handler
You can edit the content above on GitHub and send us a pull request!
AsyncStorage #
AsyncStorage is a simple, unencrypted, asynchronous, persistent, key-value storage
+
AsyncStorage #
AsyncStorage is a simple, unencrypted, asynchronous, persistent, key-value storage
system that is global to the app. It should be used instead of LocalStorage.
It is recommended that you use an abstraction on top of AsyncStorage
instead of AsyncStorage directly for anything more than light usage since
it operates globally.
On iOS, AsyncStorage is backed by native code that stores small values in a
@@ -115,7 +115,7 @@ AsyncStorage.
// Console log results:
// => UID234 {"name":"Chris","age":31,"traits":{"shoe_size":10,"hair":"brown","eyes":"blue"}}
-// => UID345 {"name":"Marge","age":26,"traits":{"shoe_size":6,"hair":"blonde","eyes":"green"}}
You can edit the content above on GitHub and send us a pull request!
BackHandler #
Detect hardware button presses for back navigation.
Android: Detect hardware back button presses, and programmatically invoke the default back button +
BackHandler #
Detect hardware button presses for back navigation.
Android: Detect hardware back button presses, and programmatically invoke the default back button functionality to exit the app if there are no listeners or if none of the listeners return true.
tvOS: Detect presses of the menu button on the TV remote. (Still to be implemented: programmatically disable menu button handling functionality to exit the app if there are no listeners or if none of the listeners return true.)
iOS: Not applicable.
The event subscriptions are called in reverse order (i.e. last registered subscription first), @@ -11,7 +11,7 @@ and if one subscription returns true then subscriptions registered earlier will return true; } return false; -});
Methods #
You can edit the content above on GitHub and send us a pull request!
Building For Apple TV #
Apple TV support has been implemented with the intention of making existing React Native iOS applications "just work" on tvOS, with few or no changes needed in the JavaScript code for the applications.
The RNTester app supports Apple TV; use the RNTester-tvOS build target to build for tvOS.
Build changes #
Native layer: React Native Xcode projects all now have Apple TV build targets, with names ending in the string '-tvOS'.
react-native init: New React Native projects created with
react-native initwill have Apple TV target automatically created in their XCode projects.JavaScript layer: Support for Apple TV has been added to
Platform.ios.js. You can check whether code is running on AppleTV by doing
Building For Apple TV #
Apple TV support has been implemented with the intention of making existing React Native iOS applications "just work" on tvOS, with few or no changes needed in the JavaScript code for the applications.
The RNTester app supports Apple TV; use the RNTester-tvOS build target to build for tvOS.
Build changes #
Native layer: React Native Xcode projects all now have Apple TV build targets, with names ending in the string '-tvOS'.
react-native init: New React Native projects created with
react-native initwill have Apple TV target automatically created in their XCode projects.JavaScript layer: Support for Apple TV has been added to
Platform.ios.js. You can check whether code is running on AppleTV by doing
Code changes #
General support for tvOS: Apple TV specific changes in native code are all wrapped by the TARGET_OS_TV define. These include changes to suppress APIs that are not supported on tvOS (e.g. web views, sliders, switches, status bar, etc.), and changes to support user input from the TV remote or keyboard.
Common codebase: Since tvOS and iOS share most Objective-C and JavaScript code in common, most documentation for iOS applies equally to tvOS.
Access to touchable controls: When running on Apple TV, the native view class is
RCTTVView, which has additional methods to make use of the tvOS focus engine. TheTouchablemixin has code added to detect focus changes and use existing methods to style the components properly and initiate the proper actions when the view is selected using the TV remote, soTouchableHighlightandTouchableOpacitywill "just work". In particular:touchableHandleActivePressInwill be executed when the touchable view goes into focustouchableHandleActivePressOutwill be executed when the touchable view goes out of focustouchableHandlePresswill be executed when the touchable view is actually selected by pressing the "select" button on the TV remote.
TV remote/keyboard input: A new native class,
RCTTVRemoteHandler, sets up gesture recognizers for TV remote events. When TV remote events occur, this class fires notifications that are picked up byRCTTVNavigationEventEmitter(a subclass ofRCTEventEmitter), that fires a JS event. This event will be picked up by instances of theTVEventHandlerJavaScript object. Application code that needs to implement custom handling of TV remote events can create an instance ofTVEventHandlerand listen for these events, as in the following code:
TV remote animations:
RCTTVViewnative code implements Apple-recommended parallax animations to help guide the eye as the user navigates through views. The animations can be disabled or adjusted with new optional view properties.Back navigation with the TV remote menu button: The
BackHandlercomponent, originally written to support the Android back button, now also supports back navigation on the Apple TV using the menu button on the TV remote.Known issues:
- ListView scrolling. The issue can be easily worked around by setting
removeClippedSubviewsto false in ListView and similar components. For more discussion of this issue, see this PR.
- ListView scrolling. The issue can be easily worked around by setting
You can edit the content above on GitHub and send us a pull request!
Button #
A basic button component that should render nicely on any platform. Supports +
Button #
A basic button component that should render nicely on any platform. Supports a minimal level of customization.
If this button doesn't look right for your app, you can build your own @@ -10,7 +10,7 @@ Or, take a look at the ="Learn More" color="#841584" accessibilityLabel="Learn more about this purple button" -/>
Props #
accessibilityLabel?: ?string #
Text to display for blindness accessibility features
color?: ?string #
Color of the text (iOS), or background color of the button (Android)
disabled?: ?boolean #
If true, disable all interactions for this component.
onPress: () => any #
Handler to be called when the user taps the button
testID?: ?string #
Used to locate this view in end-to-end tests.
title: string #
Text to display inside the button
You can edit the content above on GitHub and send us a pull request!
CameraRoll #
CameraRoll provides access to the local camera roll / gallery.
+
CameraRoll #
CameraRoll provides access to the local camera roll / gallery.
Before using this you must link the RCTCameraRoll library.
You can refer to Linking for help.
Permissions #
The user's permission is required in order to access the Camera Roll on devices running iOS 10 or later.
Add the NSPhotoLibraryUsageDescription key in your Info.plist with a string that describes how your
@@ -6,7 +6,7 @@ app will use this data. This key will appear as Privacy - Photo Library Us
or a local video file URI (remote or data URIs are not supported for saving video at this time).
If the tag has a file extension of .mov or .mp4, it will be inferred as a video. Otherwise
it will be treated as a photo. To override the automatic choice, you can pass an optional
type parameter that must be one of 'photo' or 'video'.
Returns a Promise which will resolve with the new URI.
static getPhotos(params) #
Returns a Promise with photo identifier objects from the local camera
-roll of the device matching shape defined by getPhotosReturnChecker.
Expects a params object of the following shape:
first: {number} : The number of photos wanted in reverse order of the photo application (i.e. most recent first for SavedPhotos).after: {string} : A cursor that matchespage_info { end_cursor }returned from a previous call togetPhotos.groupTypes: {string} : Specifies which group types to filter the results to. Valid values are:AlbumAllEventFacesLibraryPhotoStreamSavedPhotos// default
groupName: {string} : Specifies filter on group names, like 'Recent Photos' or custom album titles.assetType: {string} : Specifies filter on asset type. Valid values are:AllVideosPhotos// default
mimeTypes: {string} : Filter by mimetype (e.g. image/jpeg).
Returns a Promise which when resolved will be of the following shape:
edges: {Array<node>} An array of node objectsnode: {object} An object with the following shape:type: {string}group_name: {string}image: {object} : An object with the following shape:uri: {string}height: {number}width: {number}isStored: {boolean}
timestamp: {number}location: {object} : An object with the following shape:latitude: {number}longitude: {number}altitude: {number}heading: {number}speed: {number}
page_info: {object} : An object with the following shape:has_next_page: {boolean}start_cursor: {boolean}end_cursor: {boolean}
You can edit the content above on GitHub and send us a pull request!
Clipboard #
Clipboard gives you an interface for setting and getting content from Clipboard on both iOS and Android
Methods #
static getString() #
Get content of string type, this method returns a Promise, so you can use following code to get clipboard content
Clipboard #
Clipboard gives you an interface for setting and getting content from Clipboard on both iOS and Android
Methods #
static getString() #
Get content of string type, this method returns a Promise, so you can use following code to get clipboard content
static setString(content) #
Set content of string type. You can use following code to set clipboard content
@param the content to be stored in the clipboard.
You can edit the content above on GitHub and send us a pull request!
Color Reference #
Components in React Native are styled using JavaScript. Color properties usually match how CSS works on the web.
Red-green-blue #
React Native supports rgb() and rgba() in both hexadecimal and functional notation:
'#f0f'(#rgb)'#ff00ff'(#rrggbb)'rgb(255, 0, 255)''rgba(255, 255, 255, 1.0)''#f0ff'(#rgba)'#ff00ff00'(#rrggbbaa)
Hue-saturation-lightness #
hsl() and hsla() is supported in functional notation:
'hsl(360, 100%, 100%)''hsla(360, 100%, 100%, 1.0)'
transparent #
This is a shortcut for rgba(0,0,0,0):
'transparent'
Named colors #
You can also use color names as values. React Native follows the CSS3 specification:
- aliceblue (#f0f8ff)
- antiquewhite (#faebd7)
- aqua (#00ffff)
- aquamarine (#7fffd4)
- azure (#f0ffff)
- beige (#f5f5dc)
- bisque (#ffe4c4)
- black (#000000)
- blanchedalmond (#ffebcd)
- blue (#0000ff)
- blueviolet (#8a2be2)
- brown (#a52a2a)
- burlywood (#deb887)
- cadetblue (#5f9ea0)
- chartreuse (#7fff00)
- chocolate (#d2691e)
- coral (#ff7f50)
- cornflowerblue (#6495ed)
- cornsilk (#fff8dc)
- crimson (#dc143c)
- cyan (#00ffff)
- darkblue (#00008b)
- darkcyan (#008b8b)
- darkgoldenrod (#b8860b)
- darkgray (#a9a9a9)
- darkgreen (#006400)
- darkgrey (#a9a9a9)
- darkkhaki (#bdb76b)
- darkmagenta (#8b008b)
- darkolivegreen (#556b2f)
- darkorange (#ff8c00)
- darkorchid (#9932cc)
- darkred (#8b0000)
- darksalmon (#e9967a)
- darkseagreen (#8fbc8f)
- darkslateblue (#483d8b)
- darkslategrey (#2f4f4f)
- darkturquoise (#00ced1)
- darkviolet (#9400d3)
- deeppink (#ff1493)
- deepskyblue (#00bfff)
- dimgray (#696969)
- dimgrey (#696969)
- dodgerblue (#1e90ff)
- firebrick (#b22222)
- floralwhite (#fffaf0)
- forestgreen (#228b22)
- fuchsia (#ff00ff)
- gainsboro (#dcdcdc)
- ghostwhite (#f8f8ff)
- gold (#ffd700)
- goldenrod (#daa520)
- gray (#808080)
- green (#008000)
- greenyellow (#adff2f)
- grey (#808080)
- honeydew (#f0fff0)
- hotpink (#ff69b4)
- indianred (#cd5c5c)
- indigo (#4b0082)
- ivory (#fffff0)
- khaki (#f0e68c)
- lavender (#e6e6fa)
- lavenderblush (#fff0f5)
- lawngreen (#7cfc00)
- lemonchiffon (#fffacd)
- lightblue (#add8e6)
- lightcoral (#f08080)
- lightcyan (#e0ffff)
- lightgoldenrodyellow (#fafad2)
- lightgray (#d3d3d3)
- lightgreen (#90ee90)
- lightgrey (#d3d3d3)
- lightpink (#ffb6c1)
- lightsalmon (#ffa07a)
- lightseagreen (#20b2aa)
- lightskyblue (#87cefa)
- lightslategrey (#778899)
- lightsteelblue (#b0c4de)
- lightyellow (#ffffe0)
- lime (#00ff00)
- limegreen (#32cd32)
- linen (#faf0e6)
- magenta (#ff00ff)
- maroon (#800000)
- mediumaquamarine (#66cdaa)
- mediumblue (#0000cd)
- mediumorchid (#ba55d3)
- mediumpurple (#9370db)
- mediumseagreen (#3cb371)
- mediumslateblue (#7b68ee)
- mediumspringgreen (#00fa9a)
- mediumturquoise (#48d1cc)
- mediumvioletred (#c71585)
- midnightblue (#191970)
- mintcream (#f5fffa)
- mistyrose (#ffe4e1)
- moccasin (#ffe4b5)
- navajowhite (#ffdead)
- navy (#000080)
- oldlace (#fdf5e6)
- olive (#808000)
- olivedrab (#6b8e23)
- orange (#ffa500)
- orangered (#ff4500)
- orchid (#da70d6)
- palegoldenrod (#eee8aa)
- palegreen (#98fb98)
- paleturquoise (#afeeee)
- palevioletred (#db7093)
- papayawhip (#ffefd5)
- peachpuff (#ffdab9)
- peru (#cd853f)
- pink (#ffc0cb)
- plum (#dda0dd)
- powderblue (#b0e0e6)
- purple (#800080)
- rebeccapurple (#663399)
- red (#ff0000)
- rosybrown (#bc8f8f)
- royalblue (#4169e1)
- saddlebrown (#8b4513)
- salmon (#fa8072)
- sandybrown (#f4a460)
- seagreen (#2e8b57)
- seashell (#fff5ee)
- sienna (#a0522d)
- silver (#c0c0c0)
- skyblue (#87ceeb)
- slateblue (#6a5acd)
- slategray (#708090)
- snow (#fffafa)
- springgreen (#00ff7f)
- steelblue (#4682b4)
- tan (#d2b48c)
- teal (#008080)
- thistle (#d8bfd8)
- tomato (#ff6347)
- turquoise (#40e0d0)
- violet (#ee82ee)
- wheat (#f5deb3)
- white (#ffffff)
- whitesmoke (#f5f5f5)
- yellow (#ffff00)
- yellowgreen (#9acd32)
You can edit the content above on GitHub and send us a pull request!
Color Reference #
Components in React Native are styled using JavaScript. Color properties usually match how CSS works on the web.
Red-green-blue #
React Native supports rgb() and rgba() in both hexadecimal and functional notation:
'#f0f'(#rgb)'#ff00ff'(#rrggbb)'rgb(255, 0, 255)''rgba(255, 255, 255, 1.0)''#f0ff'(#rgba)'#ff00ff00'(#rrggbbaa)
Hue-saturation-lightness #
hsl() and hsla() is supported in functional notation:
'hsl(360, 100%, 100%)''hsla(360, 100%, 100%, 1.0)'
transparent #
This is a shortcut for rgba(0,0,0,0):
'transparent'
Named colors #
You can also use color names as values. React Native follows the CSS3 specification:
- aliceblue (#f0f8ff)
- antiquewhite (#faebd7)
- aqua (#00ffff)
- aquamarine (#7fffd4)
- azure (#f0ffff)
- beige (#f5f5dc)
- bisque (#ffe4c4)
- black (#000000)
- blanchedalmond (#ffebcd)
- blue (#0000ff)
- blueviolet (#8a2be2)
- brown (#a52a2a)
- burlywood (#deb887)
- cadetblue (#5f9ea0)
- chartreuse (#7fff00)
- chocolate (#d2691e)
- coral (#ff7f50)
- cornflowerblue (#6495ed)
- cornsilk (#fff8dc)
- crimson (#dc143c)
- cyan (#00ffff)
- darkblue (#00008b)
- darkcyan (#008b8b)
- darkgoldenrod (#b8860b)
- darkgray (#a9a9a9)
- darkgreen (#006400)
- darkgrey (#a9a9a9)
- darkkhaki (#bdb76b)
- darkmagenta (#8b008b)
- darkolivegreen (#556b2f)
- darkorange (#ff8c00)
- darkorchid (#9932cc)
- darkred (#8b0000)
- darksalmon (#e9967a)
- darkseagreen (#8fbc8f)
- darkslateblue (#483d8b)
- darkslategrey (#2f4f4f)
- darkturquoise (#00ced1)
- darkviolet (#9400d3)
- deeppink (#ff1493)
- deepskyblue (#00bfff)
- dimgray (#696969)
- dimgrey (#696969)
- dodgerblue (#1e90ff)
- firebrick (#b22222)
- floralwhite (#fffaf0)
- forestgreen (#228b22)
- fuchsia (#ff00ff)
- gainsboro (#dcdcdc)
- ghostwhite (#f8f8ff)
- gold (#ffd700)
- goldenrod (#daa520)
- gray (#808080)
- green (#008000)
- greenyellow (#adff2f)
- grey (#808080)
- honeydew (#f0fff0)
- hotpink (#ff69b4)
- indianred (#cd5c5c)
- indigo (#4b0082)
- ivory (#fffff0)
- khaki (#f0e68c)
- lavender (#e6e6fa)
- lavenderblush (#fff0f5)
- lawngreen (#7cfc00)
- lemonchiffon (#fffacd)
- lightblue (#add8e6)
- lightcoral (#f08080)
- lightcyan (#e0ffff)
- lightgoldenrodyellow (#fafad2)
- lightgray (#d3d3d3)
- lightgreen (#90ee90)
- lightgrey (#d3d3d3)
- lightpink (#ffb6c1)
- lightsalmon (#ffa07a)
- lightseagreen (#20b2aa)
- lightskyblue (#87cefa)
- lightslategrey (#778899)
- lightsteelblue (#b0c4de)
- lightyellow (#ffffe0)
- lime (#00ff00)
- limegreen (#32cd32)
- linen (#faf0e6)
- magenta (#ff00ff)
- maroon (#800000)
- mediumaquamarine (#66cdaa)
- mediumblue (#0000cd)
- mediumorchid (#ba55d3)
- mediumpurple (#9370db)
- mediumseagreen (#3cb371)
- mediumslateblue (#7b68ee)
- mediumspringgreen (#00fa9a)
- mediumturquoise (#48d1cc)
- mediumvioletred (#c71585)
- midnightblue (#191970)
- mintcream (#f5fffa)
- mistyrose (#ffe4e1)
- moccasin (#ffe4b5)
- navajowhite (#ffdead)
- navy (#000080)
- oldlace (#fdf5e6)
- olive (#808000)
- olivedrab (#6b8e23)
- orange (#ffa500)
- orangered (#ff4500)
- orchid (#da70d6)
- palegoldenrod (#eee8aa)
- palegreen (#98fb98)
- paleturquoise (#afeeee)
- palevioletred (#db7093)
- papayawhip (#ffefd5)
- peachpuff (#ffdab9)
- peru (#cd853f)
- pink (#ffc0cb)
- plum (#dda0dd)
- powderblue (#b0e0e6)
- purple (#800080)
- rebeccapurple (#663399)
- red (#ff0000)
- rosybrown (#bc8f8f)
- royalblue (#4169e1)
- saddlebrown (#8b4513)
- salmon (#fa8072)
- sandybrown (#f4a460)
- seagreen (#2e8b57)
- seashell (#fff5ee)
- sienna (#a0522d)
- silver (#c0c0c0)
- skyblue (#87ceeb)
- slateblue (#6a5acd)
- slategray (#708090)
- snow (#fffafa)
- springgreen (#00ff7f)
- steelblue (#4682b4)
- tan (#d2b48c)
- teal (#008080)
- thistle (#d8bfd8)
- tomato (#ff6347)
- turquoise (#40e0d0)
- violet (#ee82ee)
- wheat (#f5deb3)
- white (#ffffff)
- whitesmoke (#f5f5f5)
- yellow (#ffff00)
- yellowgreen (#9acd32)
Improve this page by sending a pull request!
Communication between native and React Native #
In Integrating with Existing Apps guide and Native UI Components guide we learn how to embed React Native in a native component and vice versa. When we mix native and React Native components, we'll eventually find a need to communicate between these two worlds. Some ways to achieve that have been already mentioned in other guides. This article summarizes available techniques.
Introduction #
React Native is inspired by React, so the basic idea of the information flow is similar. The flow in React is one-directional. We maintain a hierarchy of components, in which each component depends only on its parent and its own internal state. We do this with properties: data is passed from a parent to its children in a top-down manner. If an ancestor component relies on the state of its descendant, one should pass down a callback to be used by the descendant to update the ancestor.
The same concept applies to React Native. As long as we are building our application purely within the framework, we can drive our app with properties and callbacks. But, when we mix React Native and native components, we need some special, cross-language mechanisms that would allow us to pass information between them.
Properties #
Properties are the simplest way of cross-component communication. So we need a way to pass properties both from native to React Native, and from React Native to native.
Passing properties from native to React Native #
In order to embed a React Native view in a native component, we use RCTRootView. RCTRootView is a UIView that holds a React Native app. It also provides an interface between native side and the hosted app.
RCTRootView has an initializer that allows you to pass arbitrary properties down to the React Native app. The initialProperties parameter has to be an instance of NSDictionary. The dictionary is internally converted into a JSON object that the top-level JS component can reference.
Communication between native and React Native #
In Integrating with Existing Apps guide and Native UI Components guide we learn how to embed React Native in a native component and vice versa. When we mix native and React Native components, we'll eventually find a need to communicate between these two worlds. Some ways to achieve that have been already mentioned in other guides. This article summarizes available techniques.
Introduction #
React Native is inspired by React, so the basic idea of the information flow is similar. The flow in React is one-directional. We maintain a hierarchy of components, in which each component depends only on its parent and its own internal state. We do this with properties: data is passed from a parent to its children in a top-down manner. If an ancestor component relies on the state of its descendant, one should pass down a callback to be used by the descendant to update the ancestor.
The same concept applies to React Native. As long as we are building our application purely within the framework, we can drive our app with properties and callbacks. But, when we mix React Native and native components, we need some special, cross-language mechanisms that would allow us to pass information between them.
Properties #
Properties are the simplest way of cross-component communication. So we need a way to pass properties both from native to React Native, and from React Native to native.
Passing properties from native to React Native #
In order to embed a React Native view in a native component, we use RCTRootView. RCTRootView is a UIView that holds a React Native app. It also provides an interface between native side and the hosted app.
RCTRootView has an initializer that allows you to pass arbitrary properties down to the React Native app. The initialProperties parameter has to be an instance of NSDictionary. The dictionary is internally converted into a JSON object that the top-level JS component can reference.
In the example we have a FlexibleSizeExampleView view that holds a root view. We create the root view, initialize it and set the delegate. The delegate will handle size updates. Then, we set the root view's size flexibility to RCTRootViewSizeFlexibilityHeight, which means that rootViewDidChangeIntrinsicSize: method will be called every time the React Native content changes its height. Finally, we set the root view's width and position. Note that we set there height as well, but it has no effect as we made the height RN-dependent.
You can checkout full source code of the exmaple here.
It's fine to change root view's size flexibility mode dynamically. Changing flexibility mode of a root view will schedule a layout recalculation and the delegate rootViewDidChangeIntrinsicSize: method will be called once the content size is known.
Note: React Native layout calculation is performed on a special thread, while native UI view updates are done on the main thread. This may cause temporary UI inconsistencies between native and React Native. This is a known problem and our team is working on synchronizing UI updates coming from different sources.
Note: React Native does not perform any layout calculations until the root view becomes a subview of some other views. If you want to hide React Native view until its dimensions are known, add the root view as a subview and make it initially hidden (use
UIView'shiddenproperty). Then change its visibility in the delegate method.
You can edit the content above on GitHub and send us a pull request!
Components and APIs #
React Native provides a number of built-in components. You will find a full list of components and APIs on the sidebar to the left. If you're not sure where to get started, take a look at the following categories:
You're not limited to the components and APIs bundled with React Native. React Native is a community of thousands of developers. If you're looking for a library that does something specific, search the npm registry for packages mentioning react-native, or check out Awesome React Native for a curated list.
Basic Components #
Most apps will end up using one of these basic components. You'll want to get yourself familiarized with all of these if you're new to React Native.
Components and APIs #
React Native provides a number of built-in components. You will find a full list of components and APIs on the sidebar to the left. If you're not sure where to get started, take a look at the following categories:
You're not limited to the components and APIs bundled with React Native. React Native is a community of thousands of developers. If you're looking for a library that does something specific, search the npm registry for packages mentioning react-native, or check out Awesome React Native for a curated list.
Basic Components #
Most apps will end up using one of these basic components. You'll want to get yourself familiarized with all of these if you're new to React Native.
View
The most fundamental component for building a UI.
@@ -188,7 +188,7 @@A component that renders web content in a native view.
You can edit the content above on GitHub and send us a pull request!
How to Contribute #
React Native is one of Facebook's first open source projects that is both under very active development and is also being used to ship code to everybody using Facebook's mobile apps. We're still working out the kinks to make contributing to this project as easy and transparent as possible, but we're not quite there yet. Hopefully this document makes the process for contributing clear and preempts some questions you may have.
- Code of Conduct
- Development Process
- Branch Organization
- How to Get in Touch
- Bugs
- Pull Requests
- Triaging Issues and Pull Requests
- Style Guide
- License
Code of Conduct #
Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.
Our Development Process #
Some of the core team will be working directly on GitHub. These changes will be public from the beginning. Other changesets will come via a bridge with Facebook's internal source control. This is a necessity as it allows engineers at Facebook outside of the core team to move fast and contribute from an environment they are comfortable in.
Branch Organization #
We will do our best to keep master in good shape, with tests passing at all times. But in order to move fast, we will make API changes that your application might not be compatible with. We will do our best to communicate these changes and version appropriately so you can lock into a specific version if need be.
To see what changes are coming and provide better feedback to React Native contributors, use the latest release candidate when possible. By the time a release candidate is released, the changes it contains will have been shipped in production Facebook apps for over two weeks.
How to Get in Touch #
Many React Native users are active on Stack Overflow. If you want to get a general sense of what React Native folks talk about, check out the React Native Community Facebook group. There is also an active community of React and React Native users on the Discord chat platform in case you need help.
The React Native team sends out periodical updates through the following channels:
Core contributors to React Native meet monthly and post their meeting notes on the React Native blog. You can also find ad hoc discussions in the React Native Core Contributors Facebook group.
Bugs #
Where to Find Known Issues #
We are using GitHub Issues for our public bugs. Before filing a new task, try to make sure your problem doesn't already exist.
Questions and feature requests are tracked elsewhere:
- Have a question? Ask on Stack Overflow.
- If you have a question regarding future plans, check out the roadmap.
- Have a feature request that is not covered in the roadmap? Add it here.
Reporting New Issues #
When opening a new issue, always make sure to fill out the issue template. This step is very important! Not doing so may result in your issue getting closed. Don't take this personally if this happens, and feel free to open a new issue once you've gathered all the information required by the template.
- One issue, one bug: Please report a single bug per issue.
- Provide a Snack: The best way to get attention on your issue is to provide a reduced test case. You can use Snack to demonstrate the issue.
- Provide reproduction steps: List all the steps necessary to reproduce the issue. Provide a Snack or upload a sample project to GitHub. The person reading your bug report should be able to follow these steps to reproduce your issue with minimal effort.
- Try out the latest version: Verify that the issue can be reproduced locally by updating your project to use React Native from
master. The bug may have already been fixed!
We're not able to provide support through GitHub Issues. If you're looking for help with your code, consider asking on Stack Overflow or reaching out to the community through other channels.
Security Bugs #
Facebook has a bounty program for the safe disclosure of security bugs. With that in mind, please do not file public issues; go through the process outlined on that page.
Pull Requests #
Your First Pull Request #
Working on your first Pull Request? You can learn how from this free video series:
How to Contribute to an Open Source Project on GitHub
We have a list of beginner friendly issues to help you get your feet wet in the React Native codebase and familiar with our contribution process. This is a great place to get started.
If you decide to fix an issue, please be sure to check the comment thread in case somebody is already working on a fix. If nobody is working on it at the moment, please leave a comment stating that you intend to work on it so other people don't accidentally duplicate your effort.
If somebody claims an issue but doesn't follow up for more than two weeks, it's fine to take over it but you should still leave a comment.
Sending a Pull Request #
If you send a pull request, please do it against the master branch. We maintain stable branches for stable releases separately but we don't accept pull requests to them directly. Instead, we cherry-pick non-breaking changes from master to the latest stable version.
The core team will be monitoring for pull requests. When we get one, we'll run some Facebook-specific integration tests on it first. From here, we'll need to get another person to sign off on the changes and then merge the pull request. For API changes we may need to fix internal uses, which could cause some delay. We'll do our best to provide updates and feedback throughout the process.
Small pull requests are much easier to review and more likely to get merged. Make sure the PR does only one thing, otherwise please split it.
Before submitting a pull request, please make sure the following is done…
- Fork the repository and create your branch from
master. - Add the copyright notice to the top of any new files you've added.
- Describe your test plan in your commit.
- Ensure tests pass on both Travis and Circle CI.
- Make sure your code lints (
npm run lint). - If you haven't already, sign the CLA.
Note: It is not necessary to keep clicking
Merge master to your branchon the PR page. You would want to merge master if there are conflicts or tests are failing. The Facebook-GitHub-Bot ultimately squashes all commits to a single one before merging your PR.
Test plan #
A good test plan has the exact commands you ran and their output, provides screenshots or videos if the pull request changes UI or updates the website.
- If you've added code that should be tested, add tests!
- If you've changed APIs, update the documentation.
- If you've updated the docs, verify the website locally and submit screenshots if applicable (see website/README.md)
See What is a Test Plan? to learn more.
Continuous integration tests #
Make sure all tests pass on both Travis and Circle CI. PRs that break tests are unlikely to be merged.
You can learn more about running tests and contributing to React Native next.
Breaking changes #
When adding a new breaking change, follow this template in your pull request:
How to Contribute #
React Native is one of Facebook's first open source projects that is both under very active development and is also being used to ship code to everybody using Facebook's mobile apps. If you're interested in contributing to React Native, hopefully this document makes the process for contributing clear.
Core contributors to React Native meet monthly and post their meeting notes on the React Native blog. You can also find ad hoc discussions in the React Native Core Contributors Facebook group.
Code of Conduct #
Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.
How to contribute #
There are many ways to contribute to React Native, and many of them do not involve writing any code. Here's a few ideas to get started:
- Simply start using React Native. Go through the Getting Started guide. Does everything work as expected? If not, we're always looking for improvements. Let us know by opening an issue.
- Look through the open issues. Provide workarounds, ask for clarification, or suggest labels. Help triage issues.
- If you find an issue you would like to fix, open a pull request. Issues tagged as
Good First Taskare a good place to get started. - Read through the React Native docs. If you find anything that is confusing or can be improved, you can make edits by clicking "Improve this page" at the bottom of most docs.
- Browse Stack Overflow and answer questions. This will help you get familiarized with common pitfalls or misunderstandings, which can be useful when contributing updates to the documentation.
- Take a look at the features requested by others in the community and consider opening a pull request if you see something you want to work on.
Contributions are very welcome. If you think you need help planning your contribution, please hop into #react-native and let people know you're looking for a mentor.
Triaging issues and pull requests #
One great way you can contribute to the project without writing any code is to help triage issues and pull requests as they come in.
- Ask for more information if the issue does not provide all the details required by the template.
- Suggest labels that can help categorize issues.
- Flag issues that are stale or that should be closed.
- Ask for test plans and review code.
Adding labels, closing and reopening issues, and merging pull requests is, as you may expect, limited to a subset of contributors. Simply commenting on the issue or pull request can still go a long way towards helping us keep the number of outstanding issues under control.
Once you have become an active contributor in the community, you may gain access to the Facebook GitHub Bot, allowing you to perform some of these operations yourself. You can learn more about the bot in the maintainer's guide.
Our development process #
Some of the core team will be working directly on GitHub. These changes will be public from the beginning. Other changesets will come via a bridge with Facebook's internal source control. This is a necessity as it allows engineers at Facebook outside of the core team to move fast and contribute from an environment they are comfortable in.
When a change made on GitHub is approved, it will first be imported into Facebook's internal source control. The change will eventually sync back to GitHub as a single commit once it has passed all internal tests.
Branch organization #
We will do our best to keep master in good shape, with tests passing at all times. But in order to move fast, we will make API changes that your application might not be compatible with. We will do our best to communicate these changes and version appropriately so you can lock into a specific version if need be.
To see what changes are coming and provide better feedback to React Native contributors, use the latest release candidate when possible. By the time a release candidate is released, the changes it contains will have been shipped in production Facebook apps for over two weeks.
Bugs #
We use GitHub Issues for our public bugs. If you would like to report a problem, take a look around and see if someone already opened an issue about it. If you a are certain this is a new, unreported bug, you can submit a bug report.
If you have questions about using React Native, the help page list various resources that should help you get started.
We also have a place where you can request features or enhancements. If you see anything you'd like to be implemented, vote it up and explain your use case.
Reporting new issues #
When opening a new issue, always make sure to fill out the issue template. This step is very important! Not doing so may result in your issue getting closed. Don't take this personally if this happens, and feel free to open a new issue once you've gathered all the information required by the template.
- One issue, one bug: Please report a single bug per issue.
- Provide a Snack: The best way to get attention on your issue is to provide a reduced test case. You can use Snack to demonstrate the issue.
- Provide reproduction steps: List all the steps necessary to reproduce the issue. Provide a Snack or upload a sample project to GitHub. The person reading your bug report should be able to follow these steps to reproduce your issue with minimal effort.
- Try out the latest version: Verify that the issue can be reproduced locally by updating your project to use React Native from
master. The bug may have already been fixed!
We're not able to provide support through GitHub Issues. If you're looking for help with your code, consider asking on Stack Overflow or reaching out to the community through other channels.
Security bugs #
Facebook has a bounty program for the safe disclosure of security bugs. With that in mind, please do not file public issues; go through the process outlined on that page.
Pull requests #
Your first pull request #
So you have decided to contribute code back to upstream by opening a pull request. You've invested a good chunk of time, and we appreciate it. We will do our best to work with you and get the PR looked at.
Working on your first Pull Request? You can learn how from this free video series:
How to Contribute to an Open Source Project on GitHub
We have a list of beginner friendly issues to help you get your feet wet in the React Native codebase and familiar with our contribution process. This is a great place to get started.
Proposing a change #
If you would like to request a new feature or enhancement but are not yet thinking about opening a pull request, we have a place to track feature requests.
If you intend to change the public API, or make any non-trivial changes to the implementation, we recommend filing an issue. This lets us reach an agreement on your proposal before you put significant effort into it.
If you're only fixing a bug, it's fine to submit a pull request right away but we still recommend to file an issue detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue.
Sending a pull request #
Small pull requests are much easier to review and more likely to get merged. Make sure the PR does only one thing, otherwise please split it.
Before submitting a pull request, please make sure the following is done:
- Fork the repository and create your branch from
master. - Add the copyright notice to the top of any new files you've added.
- Describe your test plan in your commit.
- Ensure tests pass on both Travis and Circle CI.
- Make sure your code lints (
npm run lint). - If you haven't already, sign the CLA.
All pull requests should be opened against the master branch.
Note: It is not necessary to keep clicking
Merge master to your branchon the PR page. You would want to merge master if there are conflicts or tests are failing. The Facebook-GitHub-Bot ultimately squashes all commits to a single one before merging your PR.
Test plan #
A good test plan has the exact commands you ran and their output, provides screenshots or videos if the pull request changes UI or updates the website.
- If you've added code that should be tested, add tests!
- If you've changed APIs, update the documentation.
- If you've updated the docs, verify the website locally and submit screenshots if applicable (see website/README.md)
See What is a Test Plan? to learn more.
Continuous integration tests #
Make sure all tests pass on both Travis and Circle CI. PRs that break tests are unlikely to be merged. Learn more about testing your changes here.
Breaking changes #
When adding a new breaking change, follow this template in your pull request:
If your pull request is merged, a core contributor will update the list of breaking changes which is then used to populate the release notes.
Copyright Notice for files #
Copy and paste this to the top of your new file(s):
If your pull request is merged, a core contributor will update the list of breaking changes which is then used to populate the release notes.
Copyright Notice for files #
Copy and paste this to the top of your new file(s):
If you've added a new module, add a @providesModule <moduleName> at the end of the comment. This will allow the haste package manager to find it.
Contributor License Agreement (CLA) #
In order to accept your pull request, we need you to submit a CLA. You only need to do this once, so if you've done this for another Facebook open source project, you're good to go. If you are submitting a pull request for the first time, just let us know that you have completed the CLA and we can cross-check with your GitHub username.
Complete your CLA here: https://code.facebook.com/cla
Proposing a change #
If you intend to change the public API, or make any non-trivial changes to the implementation, we recommend filing an issue. This lets us reach an agreement on your proposal before you put significant effort into it.
If you're only fixing a bug, it's fine to submit a pull request right away but we still recommend to file an issue detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue.
Triaging Issues and Pull Requests #
One great way you can contribute to the project without writing any code is to help triage issues and pull requests as they come in. Ask for more information if the issue does not provide all the details required by the template. Suggest labels. Flag issues that are stale or that should be closed. Ask for test plans and review code.
Adding labels, closing and reopening issues, and merging pull requests is, as you may expect, limited to a subset of contributors. Simply commenting on the issue or pull request can still go a long way towards helping us keep the number of outstanding issues under control.
Using the Facebook GitHub Bot #
The Facebook GitHub Bot allows certain active members of the community to perform administrative actions such as labeling and closing issues. The list of community members with this kind of access can be found at the top of IssueCommands.txt. The bot can be triggered by adding any of the following commands as a standalone comment on an issue:
- @facebook-github-bot no-template -
-- Use this when more information is needed, especially if the issue does not adhere to the issue template. The bot will close the issue after adding the "Needs more information" label. -
- @facebook-github-bot stack-overflow -
-- Mark issues that do not belong in the bug tracker, and redirect to Stack Overflow. The bot will close the issue after adding the "For Stack Overflow" label. -
- @facebook-github-bot needs-repro -
-- Prompts the author to provide a reproducible example or Snack. The bot will apply the "Needs more information" label. -
- @facebook-github-bot cannot-repro -
-- Use this when the issue cannot be reproduced, either because it affects a particular app but no minimal repro was provided, or the issue describes something sporadic that is unlikely to be reproduced by a community member. The bot will close the issue. -
- @facebook-github-bot duplicate (#[0-9]+) -
-- Marks an issue as a duplicate. Requires a issue number to be provided. The bot will close the issue. -
- @facebook-github-bot label (.*) -
-- Use this command to add a label, such as "iOS" or "Android", to an issue. -
- @facebook-github-bot feature -
-- Use this when an issue describes a feature request, as opposed to a reproducible bug. The bot will point the author to the feature request tracker, add the "Feature Request" label, then close the issue. -
- @facebook-github-bot expected -
-- Use this when an issue describes a type of expected behavior. The bot will close the issue. -
- @facebook-github-bot answered -
-- Use this when an issue appears to be a question that has already been answered by someone on the thread. The bot will close the issue. -
- @facebook-github-bot close -
-- Closes an issue without providing a particular explanation. -
- @facebook-github-bot reopen -
-- Re-opens a previously closed issue. -
- @facebook-github-bot bugfix -
-- Mark issues that describe a reproducible bug and encourage the author to send a pull request. The bot will add the "Help Wanted" label. -
- @facebook-github-bot no-reply -
-- Use this when an issue requires more information from the author but they have not added a comment in a while. The bot will close the issue. -
- @facebook-github-bot icebox -
-- Use this when an issue has been open for over 30 days with no activity and no community member has volunteered to work on a fix. The bot will close the issue after adding the "Icebox" label. -
Additionally, the following commands can be used on a pull request:
- @facebook-github-bot cla -
-- Remind the author that the CLA needs to be signed. -
- @facebook-github-bot shipit -
-- Flag the PR for merging. If used by a core contributor, the bot will attempt to import the pull request. In general, core contributors are those who have consistently submitted high quality contributions to the project. -
Style Guide #
Our linter will catch most styling issues that may exist in your code. You can check the status of your code styling by simply running npm run lint.
However, there are still some styles that the linter cannot pick up.
Code Conventions #
General #
- Most important: Look around. Match the style you see used in the rest of the project. This includes formatting, naming things in code, naming things in documentation.
- Add trailing commas,
- 2 spaces for indentation (no tabs)
- "Attractive"
JavaScript #
- Use semicolons;
'use strict';- Prefer
'over" - Do not use the optional parameters of
setTimeoutandsetInterval - 80 character line length
JSX #
- Prefer
"over'for string literal props - When wrapping opening tags over multiple lines, place one prop per line
{}of props should hug their values (no spaces)- Place the closing
>of opening tags on the same line as the last prop - Place the closing
/>of self-closing tags on their own line and left-align them with the opening<
Objective-C #
- Space after
@propertydeclarations - Brackets on every
if, on the same line - method,@interface, and@implementationbrackets on the following line- Try to keep it around 80 characters line length (sometimes it's just not possible...)
*operator goes with the variable name (e.g.NSObject *variableName;)
Java #
- If a method call spans multiple lines closing bracket is on the same line as the last argument.
- If a method header doesn't fit on one line each argument goes on a separate line.
- 100 character line length
Documentation #
- Do not wrap lines at 80 characters - configure your editor to soft-wrap when editing documentation.
License #
By contributing to React Native, you agree that your contributions will be licensed under its BSD license.
What Next? #
Read the next section to learn how to test your changes.
You can edit the content above on GitHub and send us a pull request!
DatePickerAndroid #
Opens the standard Android date picker dialog.
Example #
DatePickerAndroid #
Opens the standard Android date picker dialog.
Example #
day if the user picked a date. If the user dismissed the dialog, the Promise will
still be resolved with action being DatePickerAndroid.dismissedAction and all the other keys
being undefined. Always check whether the action before reading the values.Note the native date picker dialog has some UI glitches on Android 4 and lower
-when using the minDate and maxDate options.
static dateSetAction() #
A date has been selected.
static dismissedAction() #
The dialog has been dismissed.
You can edit the content above on GitHub and send us a pull request!
DatePickerIOS #
Use DatePickerIOS to render a date/time picker (selector) on iOS. This is
+
DatePickerIOS #
Use DatePickerIOS to render a date/time picker (selector) on iOS. This is
a controlled component, so you must hook in to the onDateChange callback
and update the date prop in order for the component to update, otherwise
the user's change will be reverted immediately to reflect props.date as the
@@ -6,7 +6,7 @@ source of truth.
Props
timeZoneOffsetInMinutes?: number #
Timezone offset in minutes.
By default, the date picker will use the device's timezone. With this parameter, it is possible to force a certain timezone offset. For -instance, to show times in Pacific Standard Time, pass -7 * 60.
You can edit the content above on GitHub and send us a pull request!
Debugging #
Enabling Keyboard Shortcuts #
React Native supports a few keyboard shortcuts in the iOS Simulator. They are described below. To enable them, open the Hardware menu, select Keyboard, and make sure that "Connect Hardware Keyboard" is checked.
Accessing the In-App Developer Menu #
You can access the developer menu by shaking your device or by selecting "Shake Gesture" inside the Hardware menu in the iOS Simulator. You can also use the ⌘D keyboard shortcut when your app is running in the iOS Simulator, or ⌘M when running in an Android emulator.
The Developer Menu is disabled in release (production) builds.
Reloading JavaScript #
Instead of recompiling your app every time you make a change, you can reload your app's JavaScript code instantly. To do so, select "Reload" from the Developer Menu. You can also press ⌘R in the iOS Simulator, or tap R twice on Android emulators.
Automatic reloading #
You can speed up your development times by having your app reload automatically any time your code changes. Automatic reloading can be enabled by selecting "Enable Live Reload" from the Developer Menu.
You may even go a step further and keep your app running as new versions of your files are injected into the JavaScript bundle automatically by enabling Hot Reloading from the Developer Menu. This will allow you to persist the app's state through reloads.
There are some instances where hot reloading cannot be implemented perfectly. If you run into any issues, use a full reload to reset your app.
You will need to rebuild your app for changes to take effect in certain situations:
- You have added new resources to your native app's bundle, such as an image in
Images.xcassetson iOS or theres/drawablefolder on Android. - You have modified native code (Objective-C/Swift on iOS or Java/C++ on Android).
In-app Errors and Warnings #
Errors and warnings are displayed inside your app in development builds.
Errors #
In-app errors are displayed in a full screen alert with a red background inside your app. This screen is known as a RedBox. You can use console.error() to manually trigger one.
Warnings #
Warnings will be displayed on screen with a yellow background. These alerts are known as YellowBoxes. Click on the alerts to show more information or to dismiss them.
As with a RedBox, you can use console.warn() to trigger a YellowBox.
YellowBoxes can be disabled during development by using console.disableYellowBox = true;. Specific warnings can be ignored programmatically by setting an array of prefixes that should be ignored: console.ignoredYellowBox = ['Warning: ...'];.
In CI/Xcode, YellowBoxes can also be disabled by setting the IS_TESTING environment variable.
RedBoxes and YellowBoxes are automatically disabled in release (production) builds.
Chrome Developer Tools #
To debug the JavaScript code in Chrome, select "Debug JS Remotely" from the Developer Menu. This will open a new tab at http://localhost:8081/debugger-ui.
Select Tools → Developer Tools from the Chrome Menu to open the Developer Tools. You may also access the DevTools using keyboard shortcuts (⌘⌥I on macOS, Ctrl Shift I on Windows). You may also want to enable Pause On Caught Exceptions for a better debugging experience.
Note: the React Developer Tools Chrome extension does not work with React Native, but you can use its standalone version instead. Read this section to learn how.
Debugging using a custom JavaScript debugger #
To use a custom JavaScript debugger in place of Chrome Developer Tools, set the REACT_DEBUGGER environment variable to a command that will start your custom debugger. You can then select "Debug JS Remotely" from the Developer Menu to start debugging.
The debugger will receive a list of all project roots, separated by a space. For example, if you set REACT_DEBUGGER="node /path/to/launchDebugger.js --port 2345 --type ReactNative", then the command node /path/to/launchDebugger.js --port 2345 --type ReactNative /path/to/reactNative/app will be used to start your debugger.
Custom debugger commands executed this way should be short-lived processes, and they shouldn't produce more than 200 kilobytes of output.
React Developer Tools #
You can use the standalone version of React Developer Tools to debug the React component hierarchy. To use it, install the react-devtools package globally:
Now run react-devtools from the terminal to launch the standalone DevTools app:
It should connect to your simulator within a few seconds.
Note: if you prefer to avoid global installations, you can add
react-devtoolsas a project dependency. Add thereact-devtoolspackage to your project usingnpm install --save-dev react-devtools, then add"react-devtools": "react-devtools"to thescriptssection in yourpackage.json, and then runnpm run react-devtoolsfrom your project folder to open the DevTools.
Integration with React Native Inspector #
Open the in-app developer menu and choose "Show Inspector". It will bring up an overlay that lets you tap on any UI element and see information about it:
However, when react-devtools is running, Inspector will enter a special collapsed mode, and instead use the DevTools as primary UI. In this mode, clicking on something in the simulator will bring up the relevant components in the DevTools:
You can choose "Hide Inspector" in the same menu to exit this mode.
Inspecting Component Instances #
When debugging JavaScript in Chrome, you can inspect the props and state of the React components in the browser console.
First, follow the instructions for debugging in Chrome to open the Chrome console.
Make sure that the dropdown in the top left corner of the Chrome console says debuggerWorker.js. This step is essential.
Then select a React component in React DevTools. There is a search box at the top that helps you find one by name. As soon as you select it, it will be available as $r in the Chrome console, letting you inspect its props, state, and instance properties.
Performance Monitor #
You can enable a performance overlay to help you debug performance problems by selecting "Perf Monitor" in the Developer Menu.
+
Debugging #
Enabling Keyboard Shortcuts #
React Native supports a few keyboard shortcuts in the iOS Simulator. They are described below. To enable them, open the Hardware menu, select Keyboard, and make sure that "Connect Hardware Keyboard" is checked.
Accessing the In-App Developer Menu #
You can access the developer menu by shaking your device or by selecting "Shake Gesture" inside the Hardware menu in the iOS Simulator. You can also use the ⌘D keyboard shortcut when your app is running in the iOS Simulator, or ⌘M when running in an Android emulator.
The Developer Menu is disabled in release (production) builds.
Reloading JavaScript #
Instead of recompiling your app every time you make a change, you can reload your app's JavaScript code instantly. To do so, select "Reload" from the Developer Menu. You can also press ⌘R in the iOS Simulator, or tap R twice on Android emulators.
Automatic reloading #
You can speed up your development times by having your app reload automatically any time your code changes. Automatic reloading can be enabled by selecting "Enable Live Reload" from the Developer Menu.
You may even go a step further and keep your app running as new versions of your files are injected into the JavaScript bundle automatically by enabling Hot Reloading from the Developer Menu. This will allow you to persist the app's state through reloads.
There are some instances where hot reloading cannot be implemented perfectly. If you run into any issues, use a full reload to reset your app.
You will need to rebuild your app for changes to take effect in certain situations:
- You have added new resources to your native app's bundle, such as an image in
Images.xcassetson iOS or theres/drawablefolder on Android. - You have modified native code (Objective-C/Swift on iOS or Java/C++ on Android).
In-app Errors and Warnings #
Errors and warnings are displayed inside your app in development builds.
Errors #
In-app errors are displayed in a full screen alert with a red background inside your app. This screen is known as a RedBox. You can use console.error() to manually trigger one.
Warnings #
Warnings will be displayed on screen with a yellow background. These alerts are known as YellowBoxes. Click on the alerts to show more information or to dismiss them.
As with a RedBox, you can use console.warn() to trigger a YellowBox.
YellowBoxes can be disabled during development by using console.disableYellowBox = true;. Specific warnings can be ignored programmatically by setting an array of prefixes that should be ignored: console.ignoredYellowBox = ['Warning: ...'];.
In CI/Xcode, YellowBoxes can also be disabled by setting the IS_TESTING environment variable.
RedBoxes and YellowBoxes are automatically disabled in release (production) builds.
Chrome Developer Tools #
To debug the JavaScript code in Chrome, select "Debug JS Remotely" from the Developer Menu. This will open a new tab at http://localhost:8081/debugger-ui.
Select Tools → Developer Tools from the Chrome Menu to open the Developer Tools. You may also access the DevTools using keyboard shortcuts (⌘⌥I on macOS, Ctrl Shift I on Windows). You may also want to enable Pause On Caught Exceptions for a better debugging experience.
Note: the React Developer Tools Chrome extension does not work with React Native, but you can use its standalone version instead. Read this section to learn how.
Debugging using a custom JavaScript debugger #
To use a custom JavaScript debugger in place of Chrome Developer Tools, set the REACT_DEBUGGER environment variable to a command that will start your custom debugger. You can then select "Debug JS Remotely" from the Developer Menu to start debugging.
The debugger will receive a list of all project roots, separated by a space. For example, if you set REACT_DEBUGGER="node /path/to/launchDebugger.js --port 2345 --type ReactNative", then the command node /path/to/launchDebugger.js --port 2345 --type ReactNative /path/to/reactNative/app will be used to start your debugger.
Custom debugger commands executed this way should be short-lived processes, and they shouldn't produce more than 200 kilobytes of output.
React Developer Tools #
You can use the standalone version of React Developer Tools to debug the React component hierarchy. To use it, install the react-devtools package globally:
Now run react-devtools from the terminal to launch the standalone DevTools app:
It should connect to your simulator within a few seconds.
Note: if you prefer to avoid global installations, you can add
react-devtoolsas a project dependency. Add thereact-devtoolspackage to your project usingnpm install --save-dev react-devtools, then add"react-devtools": "react-devtools"to thescriptssection in yourpackage.json, and then runnpm run react-devtoolsfrom your project folder to open the DevTools.
Integration with React Native Inspector #
Open the in-app developer menu and choose "Show Inspector". It will bring up an overlay that lets you tap on any UI element and see information about it:
However, when react-devtools is running, Inspector will enter a special collapsed mode, and instead use the DevTools as primary UI. In this mode, clicking on something in the simulator will bring up the relevant components in the DevTools:
You can choose "Hide Inspector" in the same menu to exit this mode.
Inspecting Component Instances #
When debugging JavaScript in Chrome, you can inspect the props and state of the React components in the browser console.
First, follow the instructions for debugging in Chrome to open the Chrome console.
Make sure that the dropdown in the top left corner of the Chrome console says debuggerWorker.js. This step is essential.
Then select a React component in React DevTools. There is a search box at the top that helps you find one by name. As soon as you select it, it will be available as $r in the Chrome console, letting you inspect its props, state, and instance properties.
Performance Monitor #
You can enable a performance overlay to help you debug performance problems by selecting "Perf Monitor" in the Developer Menu.
Debugging in Ejected Apps #
Run react-native run-android
In a new Chrome tab, open: chrome://inspect, then click on 'Inspect device' (the one followed by "Powered by Stetho").
Debugging native code #
When working with native code, such as when writing native modules, you can launch the app from Android Studio or Xcode and take advantage of the native debugging features (setting up breakpoints, etc.) as you would in case of building a standard native app.
You can edit the content above on GitHub and send us a pull request!
Dimensions #
Methods #
static set(dims) #
This should only be called from native code by sending the +
Dimensions #
Methods #
static set(dims) #
This should only be called from native code by sending the didUpdateDimensions event.
@param {object} dims Simple string-keyed object of dimensions to set
static get(dim) #
Initial dimensions are set before runApplication is called so they should
be available before any other require's are run, but may be updated later.
Note: Although dimensions are available immediately, they may change (e.g
due to device rotation) so any rendering logic or styles that depend on
@@ -8,7 +8,7 @@ setting a value in a StyleSheet).
Example: var {height,
@returns {Object?} Value for the dimension.
static addEventListener(type, handler) #
Add an event handler. Supported events:
change: Fires when a property within theDimensionsobject changes. The argument to the event handler is an object withwindowandscreenproperties whose values are the same as the return values ofDimensions.get('window')and -Dimensions.get('screen'), respectively.
static removeEventListener(type, handler) #
Remove an event handler.
You can edit the content above on GitHub and send us a pull request!
Direct Manipulation #
It is sometimes necessary to make changes directly to a component +
Direct Manipulation #
It is sometimes necessary to make changes directly to a component without using state/props to trigger a re-render of the entire subtree. When using React in the browser for example, you sometimes need to directly modify a DOM node, and the same is true for views in mobile @@ -150,7 +150,7 @@ ignored and overridden.
Other native methods #
The methods described here are available on most of the default components provided by React Native. Note, however, that they are not available on composite components that aren't directly backed by a native view. This will generally include most components that you define in your own app.
measure(callback) #
Determines the location on screen, width, and height of the given view and returns the values via an async callback. If successful, the callback will be called with the following arguments:
- x
- y
- width
- height
- pageX
- pageY
Note that these measurements are not available until after the rendering has been completed in native. If you need the measurements as soon as possible, consider using the onLayout prop instead.
measureInWindow(callback) #
Determines the location of the given view in the window and returns the values via an async callback. If the React root view is embedded in another native view, this will give you the absolute coordinates. If successful, the callback will be called with the following arguments:
- x
- y
- width
- height
measureLayout(relativeToNativeNode, onSuccess, onFail) #
Like measure(), but measures the view relative an ancestor, specified as relativeToNativeNode. This means that the returned x, y are relative to the origin x, y of the ancestor view.
As always, to obtain a native node handle for a component, you can use ReactNative.findNodeHandle(component).
focus() #
Requests focus for the given input or view. The exact behavior triggered will depend on the platform and type of view.
blur() #
Removes focus from an input or view. This is the opposite of focus().
You can edit the content above on GitHub and send us a pull request!
DrawerLayoutAndroid #
React component that wraps the platform DrawerLayout (Android only). The
+
DrawerLayoutAndroid #
React component that wraps the platform DrawerLayout (Android only). The
Drawer (typically used for navigation) is rendered with renderNavigationView
and direct children are the main view (where your content goes). The navigation
view is initially not visible on the screen, but can be pulled in from the
@@ -37,7 +37,7 @@ from the edge of the window.
renderNavigationView: function #
The navigation view that will be rendered to the side of the screen and can be pulled in.
The navigation view that will be rendered to the side of the screen and can be pulled in.
Methods #
You can edit the content above on GitHub and send us a pull request!
Easing #
The Easing module implements common easing functions. This module is used
+
Easing #
The Easing module implements common easing functions. This module is used
by Animate.timing() to convey physically
believable motion in animations.
You can find a visualization of some common easing functions at http://easings.net/
Predefined animations #
The Easing module provides several predefined animations through the
@@ -17,7 +17,7 @@ animates back slightly as the animation starts.
Wolfram Plot:
- <
transition-timing-function.A useful tool to visualize cubic bezier curves can be found at http://cubic-bezier.com/
static in(easing) #
Runs an easing function forwards.
static out(easing) #
Runs an easing function backwards.
static inOut(easing) #
Makes any easing function symmetrical. The easing function will run forwards for half of the duration, then backwards for the rest of the -duration.
You can edit the content above on GitHub and send us a pull request!
FlatList #
A performant interface for rendering simple, flat lists, supporting the most handy features:
- Fully cross-platform.
- Optional horizontal mode.
- Configurable viewability callbacks.
- Header support.
- Footer support.
- Separator support.
- Pull to Refresh.
- Scroll loading.
- ScrollToIndex support.
If you need section support, use <SectionList>.
Minimal Example:
FlatList #
A performant interface for rendering simple, flat lists, supporting the most handy features:
- Fully cross-platform.
- Optional horizontal mode.
- Configurable viewability callbacks.
- Header support.
- Footer support.
- Separator support.
- Pull to Refresh.
- Scroll loading.
- ScrollToIndex support.
If you need section support, use <SectionList>.
Minimal Example:
More complex example demonstrating PureComponent usage for perf optimization and avoiding bugs.
- By binding the
onPressItemhandler, the props will remain===andPureComponentwill @@ -129,7 +129,7 @@ middle.viewOffsetis a fixed number of pixels to offset the finalgetItemLayoutprop.
scrollToItem(params: object) #
Requires linear scan through data - use scrollToIndex instead if possible.
Note: cannot scroll to locations outside the render window without specifying the
getItemLayout prop.
scrollToOffset(params: object) #
Scroll to a specific content pixel offset in the list.
Check out scrollToOffset of VirtualizedList
recordInteraction() #
Tells the list an interaction has occured, which should trigger viewability calculations, e.g.
if waitForInteractions is true and the user has not scrolled. This is typically called by
-taps on items or by navigation actions.
flashScrollIndicators() #
Displays the scroll indicators momentarily.
You can edit the content above on GitHub and send us a pull request!
Layout with Flexbox #
A component can specify the layout of its children using the flexbox algorithm. Flexbox is designed to provide a consistent layout on different screen sizes.
You will normally use a combination of flexDirection, alignItems, and justifyContent to achieve the right layout.
Flexbox works the same way in React Native as it does in CSS on the web, with a few exceptions. The defaults are different, with
flexDirectiondefaulting tocolumninstead ofrow, and theflexparameter only supporting a single number.
Flex Direction #
Adding flexDirection to a component's style determines the primary axis of its layout. Should the children be organized horizontally (row) or vertically (column)? The default is column.
Layout with Flexbox #
A component can specify the layout of its children using the flexbox algorithm. Flexbox is designed to provide a consistent layout on different screen sizes.
You will normally use a combination of flexDirection, alignItems, and justifyContent to achieve the right layout.
Flexbox works the same way in React Native as it does in CSS on the web, with a few exceptions. The defaults are different, with
flexDirectiondefaulting tocolumninstead ofrow, and theflexparameter only supporting a single number.
Flex Direction #
Adding flexDirection to a component's style determines the primary axis of its layout. Should the children be organized horizontally (row) or vertically (column)? The default is column.
Going Deeper #
We've covered the basics, but there are many other styles you may need for layouts. The full list of props that control layout is documented here.
We're getting close to being able to build a real application. One thing we are still missing is a way to take user input, so let's move on to learn how to handle text input with the TextInput component.
You can edit the content above on GitHub and send us a pull request!
Geolocation #
The Geolocation API extends the web spec: +
Geolocation #
The Geolocation API extends the web spec: https://developer.mozilla.org/en-US/docs/Web/API/Geolocation
As a browser polyfill, this API is available through the navigator.geolocation
global - you do not need to import it.
Configuration and Permissions #
static watchPosition(success, error?, options?) #
Invokes the success callback whenever the location changes. Supported -options: timeout (ms), maximumAge (ms), enableHighAccuracy (bool), distanceFilter(m)
static clearWatch(watchID) #
static stopObserving() #
You can edit the content above on GitHub and send us a pull request!
Gesture Responder System #
The gesture responder system manages the lifecycle of gestures in your app. 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 #
To make your app feel great, 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.
You can edit the content above on GitHub and send us a pull request!
Gesture Responder System #
The gesture responder system manages the lifecycle of gestures in your app. 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 #
To make your app feel great, 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.
Improve this page by sending a pull request!