diff --git a/404.html b/404.html index 0a674afb7da..aaec5aec8dc 100644 --- a/404.html +++ b/404.html @@ -19,13 +19,13 @@ - +

Page Not Found

We could not find what you were looking for.

Please contact the owner of the site that linked you to the original URL and let them know their link is broken.

- + \ No newline at end of file diff --git a/blog.html b/blog.html index cdaa33e76df..e4580aaf11d 100644 --- a/blog.html +++ b/blog.html @@ -19,7 +19,7 @@ - + @@ -56,7 +56,7 @@
const MyComponent = () => {
const colorScheme = useColorScheme();
return <Text>useColorScheme(): {colorScheme}</Text>;
};

See the docs for Appearance and useColorScheme for more information.

Moving Apple TV to react-native-tvos

As part of our Lean Core effort and to bring Apple TV in line with other platforms like React Native Windows and React Native macOS, we’ve started to remove Apple TV specific code from core.

Going forward, Apple TV support for React Native will be maintained in react-native-community/react-native-tvos along with the corresponding react-native-tvos NPM package. This is a full fork of the main repository, with only the changes needed to support Apple TV.

Releases of react-native-tvos will be based on the public release of React Native. For this 0.62 release of react-native please upgrade Apple TV projects to use react-native-tvos 0.62.

More upgrade support

When 0.61 was released, the community introduced a new upgrade helper tool to support developers upgrading to new versions of React Native. The upgrade helper provides a diff of changes from the version you're on to the version you're targeting, allowing you to see the changes that need to be made for your specific upgrade.

Even with this tool, issues come up when upgrading. Today we're introducing more dedicated upgrading support by announcing Upgrade-Support. Upgrade Support is a GitHub issue tracker where users can submit issues specific to upgrading their projects to receive help from the community.

We're always working to improve the upgrade experience, and we hope that these tools give users the support they need in the edge cases we haven't covered yet.

Other improvements

Breaking changes

Deprecations

Thanks

Thank you to the hundreds of contributors that helped make 0.62 possible!

To see all the updates, take a look at the 0.62 changelog.

Meet Doctor, a new React Native command

Lucas Bento

Lucas Bento

React Native Community

After over 20 pull requests from 6 contributors in the React Native Community, we're excited to launch react-native doctor, a new command to help you out with getting started, troubleshooting and automatically fixing errors with your development environment. The doctor command is heavily inspired by Expo and Homebrew's own doctor command with a pinch of UI inspired by Jest.

Announcing React Native 0.61 with Fast Refresh

Dan Abramov

Dan Abramov

React Core at Facebook

We’re excited to announce React Native 0.61, which includes a new reloading experience we’re calling Fast Refresh.

Fast Refresh

When we asked the React Native community about common pain points, one of the top answers was that the “hot reloading” feature was broken. It didn’t work reliably for function components, often failed to update the screen, and wasn’t resilient to typos and mistakes. We heard that most people turned it off because it was too unreliable.

In React Native 0.61, we’re unifying the existing “live reloading” (reload on save) and “hot reloading” features into a single new feature called “Fast Refresh”. Fast Refresh was implemented from scratch with the following principles:

To see Fast Refresh in action, check out this video:

Give it a try, and let us know what you think! If you prefer, you can turn it off in the Dev Menu (Cmd+D on iOS, Cmd+M or Ctrl+M on Android). Turning it on and off is instant so you can do it any time.

Here are a few Fast Refresh tips:

Please report any issues with Fast Refresh on GitHub, and we’ll look into them.

Other Improvements

Breaking Changes

Thanks

Thanks to all of the contributors that helped make 0.61 possible!

To see all the updates, take a look at the 0.61 changelog.

Meet Hermes, a new JavaScript Engine optimized for React Native

Rachel Nabors

Rachel Nabors

Documentation Engineer at Facebook

Last week at Chain React we announced Hermes, an open source JavaScript engine we’ve been working on at Facebook. It’s a small and lightweight JavaScript engine optimized for running React Native on Android. Check it out!

Hermes improves React Native performance by decreasing memory utilization, reducing download size, and decreasing the time it takes for the app to become usable or “time to interactive” (TTI).

“As we analyzed performance data, we noticed that the JavaScript engine itself was a significant factor in startup performance and download size. With this data in hand, we knew we had to optimize JavaScript performance in the more constrained environments of a mobile phone compared with a desktop or laptop. After exploring other options, we built a new JavaScript engine we call Hermes. It is designed to improve app performance, focusing on our React Native apps, even on mass-market devices with limited memory, slow storage, and reduced computing power.” —Hermes: An open source JavaScript engine optimized for mobile apps, starting with React Native

Want to get started right away? Be sure to check out our new guide to enabling Hermes in your existing React Native app in the docs!

Illustration of the Hermes and React Native logos joined into a winged fury, rising in a crashing electrical storm from a lone, glowing, presumably Android phone. Illustration by Rachel Nabors

Announcing React Native 0.60

Ryan Turner

Ryan Turner

Core Maintainer & React Native Developer

After months of hard work from hundreds of contributors, the React Native Core team is proud to announce the release of version 0.60. This release handles significant migrations for both Android and iOS platforms, and many issues are resolved too. This blog post covers the highlights of the release. As always though, refer to the changelog for more detailed information. Finally, thank you contributors for helping us to make this milestone!

Focus on Accessibility

There have been many improvements to the accessibility APIs, like announceForAccessibility, plus improvements to roles, action support, flags, and more. Accessibility is a complex science, but we hope these improvements make it a bit easier to be an A11Y. Be sure to check React Native Open Source Update June 2019 for more details of these changes.

A Fresh Start

React Native's start screen has been updated! Thank you to the many contributors who helped create the new UI. This new "Hello World" will welcome users to the ecosystem in a more friendly, engaging way.

The new init screen helps developers get started from the get-go with resources and a good example

AndroidX Support

AndroidX is a major step forward in the Android ecosystem, and the old support library artifacts are being deprecated. For 0.60, React Native has been migrated over to AndroidX. This is a breaking change, and your native code and dependencies will need to be migrated as well.

With this change, React Native apps will need to begin using AndroidX themselves. They cannot be used side-by-side in one app, so all of the app code and dependency code needs to be using one or the other.

matt-oakes on discussions-and-proposals

While your own native code will need to be migrated by you, @mikehardy, @cawfree, and @m4tt72 built a clever tool named "jetifier" to patch your node_modules. Library maintainers will need to upgrade, but this tool provide you with a temporary solution while giving them time to release an AndroidX version. So if you find errors related to AndroidX migration, give this a shot.

CocoaPods by Default

CocoaPods are now part of React Native's iOS project. If you weren't already, be sure to open iOS platform code using the xcworkspace file from now on (protip: try xed ios from the root project directory). Also, the podspecs for the internal packages have changed to make them compatible with the Xcode projects, which will help with troubleshooting and debugging. Expect to make some straightforward changes to your Podfile as part of the upgrade to 0.60 to bring this exciting support. Note that we are aware of a compatibility issue with use_frameworks!, and we're tracking an issue with workarounds and a future patch.

Lean Core Removals

WebView and NetInfo were previously extracted into separate repositories, and in 0.60 we’ve finished migrating them out of the React Native repository. Additionally, in response to community feedback about new App Store policy, Geolocation has been extracted. If you haven’t already, complete your migration by adding dependencies to react-native-webview, @react-native-community/netinfo, and @react-native-community/geolocation. If you'd like an automated solution, consider using rn-upgrade-deprecated-modules. Maintainers have made more than 100 commits to these repositories since extraction and we’re excited to see the community’s support!

Native Modules are now Autolinked

The team working on the React Native CLI has introduced major improvements to native module linking called autolinking! Most scenarios will not require the use of react-native link anymore. At the same time, the team overhauled the linking process in general. Be sure to react-native unlink any preexisting dependencies as mentioned in the docs above.

Upgrade Helper

@lucasbento, @pvinis, @kelset, and @watadarkstar have built a great tool called Upgrade Helper to make the upgrade process simpler. It helps React Native users with brownfield apps or complex customizations to see what's changed between versions. Take a look at the updated upgrading docs and try it out today for your upgrade path!

Upgrade Helper cleanly and easily shows the changes needed to migrate to a different version of React Native

A Note to Library Maintainers

Changes for AndroidX will almost certainly require updates to your library, so be sure to include support soon. If you're not able to upgrade yet, consider checking your library against the jetifier to confirm that users are able to patch your library at build time.

Review the autolinking docs to update your configs and readme. Depending on how your library was previously integrated, you may also need to make some additional changes. Check the dependencies guide from the CLI for information on how to define your dependency interface.

Thanks

While these are the highlights that we noted, there are many others to be excited about. To see all the updates, take a look at the changelog. As always, stay tuned for more news. Enjoy 0.60 in the meantime!

React Native Open Source Update June 2019

Christoph Nakazawa

Christoph Nakazawa

Engineer at Facebook

Code & Community Health

In the past six months, a total of 2800 commits were made to React Native by more than 550 contributors. 400 contributors from the community created more than 1,150 Pull Requests, of which 820 Pull Requests were merged.

The average number of Pull Requests per day throughout the past six months has increased from three to about six, even though we split the website, CLI and many modules out of React Native via the Lean Core effort. The average amount of open pull requests is now below 25 and we usually reply with suggestions and reviews within hours or days.

Meaningful Community Contributions

We’d like to highlight a number of recent contributions which we thought were awesome:

Lean Core

The primary motivation of Lean Core has been to split modules out of React Native into separate repositories so they can receive better maintenance. In just a six months repositories like WebView, NetInfo, AsyncStorage, the website and the CLI received more than 800 Pull Requests combined. Besides better maintenance, these projects can also be independently released more often than React Native itself.

We have also taken the opportunity to remove obsolete polyfills and legacy components from React Native itself. Polyfills were necessary in the past to support language features like Map and Set in older versions of JavaScriptCore (JSC). Now that React Native ships with a new version, these polyfills were removed.

This work is still in progress and many more things still need to be split out or removed both on the native and JavaScript side but there are early signs that we managed to reverse the trend of increasing the surface area and app size: When looking at the JavaScript bundle for example, about a year ago in version 0.54 the React Native JavaScript bundle size was 530kb and grew to 607kb (+77kb) by version 0.57 in just 6 months. Now we are seeing a bundle size reduction of 28kb down to 579kb on master, a delta of more than 100kb!

As we conclude the first iteration of the Lean Core effort, we will make an effort to be more intentional about new APIs added to React Native and we will continuously evaluate ways to make React Native smaller and faster, as well as finding ways to empower the community to take ownership of various components.

User Feedback

Six months ago we asked the community “What do you dislike about React Native?” which gave a good overview of problems people are facing. We replied to the post a few months ago and it's time to summarize the progress that was made on top issues:

Unfortunately we weren’t able to improve everything just yet:

Given the large amount of changes in the past six months, we'd like to ask you the same question again. If you are using the latest version of React Native and you have things you'd like to give feedback on, please comment on our new edition of “What do you dislike about React Native?”

Continuous Integration

Facebook merges all Pull Requests and internal changes directly into Facebook’s repository first and then syncs all commits back to GitHub. Facebook’s infrastructure is different from common continuous integration services and not all open source tests were run inside of Facebook. This means that commits that sync out to GitHub frequently break tests in open source which take a lot of time to fix.

Héctor Ramos from the React Native team spent the past two months improving React Native's continuous integration systems both at Facebook and on GitHub. Most of the open source tests are now run before changes are committed to React Native at Facebook which will keep CI stable on GitHub when commits are being synchronized.

Next

Make sure to check out our talks about the future of React Native! In the next couple of months, members of the React Native team at Facebook will speak at Chain React and at React Native EU. Also, watch out for our next release, 0.60, which is right around the corner. It's going to be exciting ✨

React Native at F8 and Open Source Podcast

Christoph Nakazawa

Christoph Nakazawa

Engineer at Facebook

This week, Eli White gave a talk at F8 2019 about React Native in Facebook's Android and iOS applications. We are excited to share what we've been up to for the past two years and what we're doing next.

Check out the video on Facebook's developer website:

F8 Talk about React Native

Highlights from the talk:

React Radio Podcast about Open Source

Eli's talk concludes by talking about our recent open source work. We gave an update on our progress in March and recently Nader Dabit and Gant Laborde invited Christoph for a chat on their podcast, React Native Radio, to chat about React Native in open source.

Highlights from the podcast:

You'll find the episode in your favorite podcasting app soon or you can listen to the recording right here:

- + diff --git a/blog/2015/03/26/react-native-bringing-modern-web-techniques-to-mobile.html b/blog/2015/03/26/react-native-bringing-modern-web-techniques-to-mobile.html index 5aa4fa44519..84613d6dcce 100644 --- a/blog/2015/03/26/react-native-bringing-modern-web-techniques-to-mobile.html +++ b/blog/2015/03/26/react-native-bringing-modern-web-techniques-to-mobile.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native: Bringing modern web techniques to mobile

Tom Occhino

Tom Occhino

Engineering Manager at Facebook

We introduced React to the world two years ago, and since then it's seen impressive growth, both inside and outside of Facebook. Today, even though no one is forced to use it, new web projects at Facebook are commonly built using React in one form or another, and it's being broadly adopted across the industry. Engineers are choosing to use React every day because it enables them to spend more time focusing on their products and less time fighting with their framework. It wasn't until we'd been building with React for a while, though, that we started to understand what makes it so powerful.

React forces us to break our applications down into discrete components, each representing a single view. These components make it easier to iterate on our products, since we don't need to keep the entire system in our head in order to make changes to one part of it. More important, though, React wraps the DOM's mutative, imperative API with a declarative one, which raises the level of abstraction and simplifies the programming model. What we've found is that when we build with React, our code is a lot more predictable. This predictability makes it so we can iterate more quickly with confidence, and our applications are a lot more reliable as a result. Additionally, it's not only easier to scale our applications when they're built with React, but we've found it's also easier to scale the size of our teams themselves.

Together with the rapid iteration cycle of the web, we've been able to build some awesome products with React, including many components of Facebook.com. Additionally, we've built amazing frameworks in JavaScript on top of React, like Relay, which allows us to greatly simplify our data fetching at scale. Of course, web is only part of the story. Facebook also has widely used Android and iOS apps, which are built on top of disjointed, proprietary technology stacks. Having to build our apps on top of multiple platforms has bifurcated our engineering organization, but that's only one of the things that makes native mobile application development hard.

This is an excerpt. Read the rest of the post on Facebook Code.

- + diff --git a/blog/2015/03/26/react-native-bringing-modern-web-techniques-to-mobile/index.html b/blog/2015/03/26/react-native-bringing-modern-web-techniques-to-mobile/index.html index 5aa4fa44519..84613d6dcce 100644 --- a/blog/2015/03/26/react-native-bringing-modern-web-techniques-to-mobile/index.html +++ b/blog/2015/03/26/react-native-bringing-modern-web-techniques-to-mobile/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native: Bringing modern web techniques to mobile

Tom Occhino

Tom Occhino

Engineering Manager at Facebook

We introduced React to the world two years ago, and since then it's seen impressive growth, both inside and outside of Facebook. Today, even though no one is forced to use it, new web projects at Facebook are commonly built using React in one form or another, and it's being broadly adopted across the industry. Engineers are choosing to use React every day because it enables them to spend more time focusing on their products and less time fighting with their framework. It wasn't until we'd been building with React for a while, though, that we started to understand what makes it so powerful.

React forces us to break our applications down into discrete components, each representing a single view. These components make it easier to iterate on our products, since we don't need to keep the entire system in our head in order to make changes to one part of it. More important, though, React wraps the DOM's mutative, imperative API with a declarative one, which raises the level of abstraction and simplifies the programming model. What we've found is that when we build with React, our code is a lot more predictable. This predictability makes it so we can iterate more quickly with confidence, and our applications are a lot more reliable as a result. Additionally, it's not only easier to scale our applications when they're built with React, but we've found it's also easier to scale the size of our teams themselves.

Together with the rapid iteration cycle of the web, we've been able to build some awesome products with React, including many components of Facebook.com. Additionally, we've built amazing frameworks in JavaScript on top of React, like Relay, which allows us to greatly simplify our data fetching at scale. Of course, web is only part of the story. Facebook also has widely used Android and iOS apps, which are built on top of disjointed, proprietary technology stacks. Having to build our apps on top of multiple platforms has bifurcated our engineering organization, but that's only one of the things that makes native mobile application development hard.

This is an excerpt. Read the rest of the post on Facebook Code.

- + diff --git a/blog/2015/09/14/react-native-for-android.html b/blog/2015/09/14/react-native-for-android.html index 56c1dfa3628..d06ae76f45f 100644 --- a/blog/2015/09/14/react-native-for-android.html +++ b/blog/2015/09/14/react-native-for-android.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native for Android: How we built the first cross-platform React Native app

Daniel Witte

Software Engineer at Facebook

Earlier this year, we introduced React Native for iOS. React Native brings what developers are used to from React on the web — declarative self-contained UI components and fast development cycles — to the mobile platform, while retaining the speed, fidelity, and feel of native applications. Today, we're happy to release React Native for Android.

At Facebook we've been using React Native in production for over a year now. Almost exactly a year ago, our team set out to develop the Ads Manager app. Our goal was to create a new app to let the millions of people who advertise on Facebook manage their accounts and create new ads on the go. It ended up being not only Facebook's first fully React Native app but also the first cross-platform one. In this post, we'd like to share with you how we built this app, how React Native enabled us to move faster, and the lessons we learned.

This is an excerpt. Read the rest of the post on Facebook Code.

- + diff --git a/blog/2015/09/14/react-native-for-android/index.html b/blog/2015/09/14/react-native-for-android/index.html index 56c1dfa3628..d06ae76f45f 100644 --- a/blog/2015/09/14/react-native-for-android/index.html +++ b/blog/2015/09/14/react-native-for-android/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native for Android: How we built the first cross-platform React Native app

Daniel Witte

Software Engineer at Facebook

Earlier this year, we introduced React Native for iOS. React Native brings what developers are used to from React on the web — declarative self-contained UI components and fast development cycles — to the mobile platform, while retaining the speed, fidelity, and feel of native applications. Today, we're happy to release React Native for Android.

At Facebook we've been using React Native in production for over a year now. Almost exactly a year ago, our team set out to develop the Ads Manager app. Our goal was to create a new app to let the millions of people who advertise on Facebook manage their accounts and create new ads on the go. It ended up being not only Facebook's first fully React Native app but also the first cross-platform one. In this post, we'd like to share with you how we built this app, how React Native enabled us to move faster, and the lessons we learned.

This is an excerpt. Read the rest of the post on Facebook Code.

- + diff --git a/blog/2015/11/23/making-react-native-apps-accessible.html b/blog/2015/11/23/making-react-native-apps-accessible.html index da8282ea1d3..e73696db693 100644 --- a/blog/2015/11/23/making-react-native-apps-accessible.html +++ b/blog/2015/11/23/making-react-native-apps-accessible.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Making React Native apps accessible

Georgiy Kassabli

Georgiy Kassabli

Software Engineer at Facebook

With the recent launch of React on web and React Native on mobile, we've provided a new front-end framework for developers to build products. One key aspect of building a robust product is ensuring that anyone can use it, including people who have vision loss or other disabilities. The Accessibility API for React and React Native enables you to make any React-powered experience usable by someone who may use assistive technology, like a screen reader for the blind and visually impaired.

For this post, we're going to focus on React Native apps. We've designed the React Accessibility API to look and feel similar to the Android and iOS APIs. If you've developed accessible applications for Android, iOS, or the web before, you should feel comfortable with the framework and nomenclature of the React AX API. For instance, you can make a UI element accessible (therefore exposed to assistive technology) and use accessibilityLabel to provide a string description for the element:

<View accessible={true} accessibilityLabel=”This is simple view”>

Let's walk through a slightly more involved application of the React AX API by looking at one of Facebook's own React-powered products: the Ads Manager app.

This is an excerpt. Read the rest of the post on Facebook Code.

- + diff --git a/blog/2015/11/23/making-react-native-apps-accessible/index.html b/blog/2015/11/23/making-react-native-apps-accessible/index.html index da8282ea1d3..e73696db693 100644 --- a/blog/2015/11/23/making-react-native-apps-accessible/index.html +++ b/blog/2015/11/23/making-react-native-apps-accessible/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Making React Native apps accessible

Georgiy Kassabli

Georgiy Kassabli

Software Engineer at Facebook

With the recent launch of React on web and React Native on mobile, we've provided a new front-end framework for developers to build products. One key aspect of building a robust product is ensuring that anyone can use it, including people who have vision loss or other disabilities. The Accessibility API for React and React Native enables you to make any React-powered experience usable by someone who may use assistive technology, like a screen reader for the blind and visually impaired.

For this post, we're going to focus on React Native apps. We've designed the React Accessibility API to look and feel similar to the Android and iOS APIs. If you've developed accessible applications for Android, iOS, or the web before, you should feel comfortable with the framework and nomenclature of the React AX API. For instance, you can make a UI element accessible (therefore exposed to assistive technology) and use accessibilityLabel to provide a string description for the element:

<View accessible={true} accessibilityLabel=”This is simple view”>

Let's walk through a slightly more involved application of the React AX API by looking at one of Facebook's own React-powered products: the Ads Manager app.

This is an excerpt. Read the rest of the post on Facebook Code.

- + diff --git a/blog/2016/03/24/introducing-hot-reloading.html b/blog/2016/03/24/introducing-hot-reloading.html index 1f693225c41..05dce962f08 100644 --- a/blog/2016/03/24/introducing-hot-reloading.html +++ b/blog/2016/03/24/introducing-hot-reloading.html @@ -19,7 +19,7 @@ - + @@ -50,7 +50,7 @@
return store;
};

When you change a reducer, the code to accept that reducer will be sent to the client. Then the client will realize that the reducer doesn't know how to accept itself, so it will look for all the modules that refer it and try to accept them. Eventually, the flow will get to the single store, the configureStore module, which will accept the HMR update.

Conclusion

If you are interested in helping making hot reloading better, I encourage you to read Dan Abramov's post around the future of hot reloading and to contribute. For example, Johny Days is going to make it work with multiple connected clients. We're relying on you all to maintain and improve this feature.

With React Native, we have the opportunity to rethink the way we build apps in order to make it a great developer experience. Hot reloading is only one piece of the puzzle, what other crazy hacks can we do to make it better?

- + diff --git a/blog/2016/03/24/introducing-hot-reloading/index.html b/blog/2016/03/24/introducing-hot-reloading/index.html index 1f693225c41..05dce962f08 100644 --- a/blog/2016/03/24/introducing-hot-reloading/index.html +++ b/blog/2016/03/24/introducing-hot-reloading/index.html @@ -19,7 +19,7 @@ - + @@ -50,7 +50,7 @@
return store;
};

When you change a reducer, the code to accept that reducer will be sent to the client. Then the client will realize that the reducer doesn't know how to accept itself, so it will look for all the modules that refer it and try to accept them. Eventually, the flow will get to the single store, the configureStore module, which will accept the HMR update.

Conclusion

If you are interested in helping making hot reloading better, I encourage you to read Dan Abramov's post around the future of hot reloading and to contribute. For example, Johny Days is going to make it work with multiple connected clients. We're relying on you all to maintain and improve this feature.

With React Native, we have the opportunity to rethink the way we build apps in order to make it a great developer experience. Hot reloading is only one piece of the puzzle, what other crazy hacks can we do to make it better?

- + diff --git a/blog/2016/03/28/dive-into-react-native-performance.html b/blog/2016/03/28/dive-into-react-native-performance.html index d5ee61f76c8..a5edb47841b 100644 --- a/blog/2016/03/28/dive-into-react-native-performance.html +++ b/blog/2016/03/28/dive-into-react-native-performance.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Dive into React Native Performance

Pieter De Baets

Pieter De Baets

Software Engineer at Facebook

React Native allows you to build Android and iOS apps in JavaScript using React and Relay's declarative programming model. This leads to more concise, easier-to-understand code; fast iteration without a compile cycle; and easy sharing of code across multiple platforms. You can ship faster and focus on details that really matter, making your app look and feel fantastic. Optimizing performance is a big part of this. Here is the story of how we made React Native app startup twice as fast.

Why the hurry?

With an app that runs faster, content loads quickly, which means people get more time to interact with it, and smooth animations make the app enjoyable to use. In emerging markets, where 2011 class phones on 2G networks are the majority, a focus on performance can make the difference between an app that is usable and one that isn't.

Since releasing React Native on iOS and on Android, we have been improving list view scrolling performance, memory efficiency, UI responsiveness, and app startup time. Startup sets the first impression of an app and stresses all parts of the framework, so it is the most rewarding and challenging problem to tackle.

This is an excerpt. Read the rest of the post on Facebook Code.

- + diff --git a/blog/2016/03/28/dive-into-react-native-performance/index.html b/blog/2016/03/28/dive-into-react-native-performance/index.html index d5ee61f76c8..a5edb47841b 100644 --- a/blog/2016/03/28/dive-into-react-native-performance/index.html +++ b/blog/2016/03/28/dive-into-react-native-performance/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Dive into React Native Performance

Pieter De Baets

Pieter De Baets

Software Engineer at Facebook

React Native allows you to build Android and iOS apps in JavaScript using React and Relay's declarative programming model. This leads to more concise, easier-to-understand code; fast iteration without a compile cycle; and easy sharing of code across multiple platforms. You can ship faster and focus on details that really matter, making your app look and feel fantastic. Optimizing performance is a big part of this. Here is the story of how we made React Native app startup twice as fast.

Why the hurry?

With an app that runs faster, content loads quickly, which means people get more time to interact with it, and smooth animations make the app enjoyable to use. In emerging markets, where 2011 class phones on 2G networks are the majority, a focus on performance can make the difference between an app that is usable and one that isn't.

Since releasing React Native on iOS and on Android, we have been improving list view scrolling performance, memory efficiency, UI responsiveness, and app startup time. Startup sets the first impression of an app and stresses all parts of the framework, so it is the most rewarding and challenging problem to tackle.

This is an excerpt. Read the rest of the post on Facebook Code.

- + diff --git a/blog/2016/04/13/react-native-a-year-in-review.html b/blog/2016/04/13/react-native-a-year-in-review.html index 0f2d9b2f5e2..10a629c9d45 100644 --- a/blog/2016/04/13/react-native-a-year-in-review.html +++ b/blog/2016/04/13/react-native-a-year-in-review.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native: A year in review

Martin Konicek

Martin Konicek

Software Engineer at Facebook

It's been one year since we open-sourced React Native. What started as an idea with a handful of engineers is now a framework being used by product teams across Facebook and beyond. Today at F8 we announced that Microsoft is bringing React Native to the Windows ecosystem, giving developers the potential to build React Native on Windows PC, Phone, and Xbox. It will also provide open source tools and services such as a React Native extension for Visual Studio Code and CodePush to help developers create React Native apps on the Windows platform. In addition, Samsung is building React Native for its hybrid platform, which will empower developers to build apps for millions of SmartTVs and mobile and wearable devices. We also released the Facebook SDK for React Native, which makes it easier for developers to incorporate Facebook social features like Login, Sharing, App Analytics, and Graph APIs into their apps. In one year, React Native has changed the way developers build on every major platform.

It's been an epic ride — but we are only getting started. Here is a look back at how React Native has grown and evolved since we open-sourced it a year ago, some challenges we faced along the way, and what we expect as we look ahead to the future.

This is an excerpt. Read the rest of the post on Facebook Code.

- + diff --git a/blog/2016/04/13/react-native-a-year-in-review/index.html b/blog/2016/04/13/react-native-a-year-in-review/index.html index 0f2d9b2f5e2..10a629c9d45 100644 --- a/blog/2016/04/13/react-native-a-year-in-review/index.html +++ b/blog/2016/04/13/react-native-a-year-in-review/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native: A year in review

Martin Konicek

Martin Konicek

Software Engineer at Facebook

It's been one year since we open-sourced React Native. What started as an idea with a handful of engineers is now a framework being used by product teams across Facebook and beyond. Today at F8 we announced that Microsoft is bringing React Native to the Windows ecosystem, giving developers the potential to build React Native on Windows PC, Phone, and Xbox. It will also provide open source tools and services such as a React Native extension for Visual Studio Code and CodePush to help developers create React Native apps on the Windows platform. In addition, Samsung is building React Native for its hybrid platform, which will empower developers to build apps for millions of SmartTVs and mobile and wearable devices. We also released the Facebook SDK for React Native, which makes it easier for developers to incorporate Facebook social features like Login, Sharing, App Analytics, and Graph APIs into their apps. In one year, React Native has changed the way developers build on every major platform.

It's been an epic ride — but we are only getting started. Here is a look back at how React Native has grown and evolved since we open-sourced it a year ago, some challenges we faced along the way, and what we expect as we look ahead to the future.

This is an excerpt. Read the rest of the post on Facebook Code.

- + diff --git a/blog/2016/07/06/toward-better-documentation.html b/blog/2016/07/06/toward-better-documentation.html index 003103c8107..b5f2e31e4dc 100644 --- a/blog/2016/07/06/toward-better-documentation.html +++ b/blog/2016/07/06/toward-better-documentation.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
AppRegistry.registerComponent('ScratchPad', () => ScratchPad);

We think these inline examples, using the react-native-web-player module with help from Devin Abbott, are a great way to learn the basics of React Native, and we have updated our tutorial for new React Native developers to use these wherever possible. Check it out - if you have ever been curious to see what would happen if you modified just one little bit of sample code, this is a really nice way to poke around. Also, if you're building developer tools and you want to show a live React Native sample on your own site, react-native-web-player can make that straightforward.

The core simulation engine is provided by Nicolas Gallagher's react-native-web project, which provides a way to display React Native components like Text and View on the web. Check out react-native-web if you're interested in building mobile and web experiences that share a large chunk of the codebase.

Better Guides

In some parts of React Native, there are multiple ways to do things, and we've heard feedback that we could provide better guidance.

We have a new guide to Navigation that compares the different approaches and advises on what you should use - Navigator, NavigatorIOS, NavigationExperimental. In the medium term, we're working towards improving and consolidating those interfaces. In the short term, we hope that a better guide will make your life easier.

We also have a new guide to handling touches that explains some of the basics of making button-like interfaces, and a brief summary of the different ways to handle touch events.

Another area we worked on is Flexbox. This includes tutorials on how to handle layout with Flexbox and how to control the size of components. It also includes an unsexy but hopefully-useful list of all the props that control layout in React Native.

Getting Started

When you start getting a React Native development environment set up on your machine, you do have to do a bunch of installing and configuring things. It's hard to make installation a really fun and exciting experience, but we can at least make it as quick and painless as possible.

We built a new Getting Started workflow that lets you select your development operating system and your mobile operating system up front, to provide one concise place with all the setup instructions. We also went through the installation process to make sure everything worked and to make sure that every decision point had a clear recommendation. After testing it out on our innocent coworkers, we're pretty sure this is an improvement.

We also worked on the guide to integrating React Native into an existing app. Many of the largest apps that use React Native, like the Facebook app itself, actually build part of the app in React Native, and part of it using regular development tools. We hope this guide makes it easier for more people to build apps this way.

We Need Your Help

Your feedback lets us know what we should prioritize. I know some people will read this blog post and think "Better docs? Pffft. The documentation for X is still garbage!". That's great - we need that energy. The best way to give us feedback depends on the sort of feedback.

If you find a mistake in the documentation, like inaccurate descriptions or code that doesn't actually work, file an issue. Tag it with "Documentation", so that it's easier to route it to the right people.

If there isn't a specific mistake, but something in the documentation is fundamentally confusing, it's not a great fit for a GitHub issue. Instead, post on Canny about the area of the docs that could use help. This helps us prioritize when we are doing more general work like guide-writing.

Thanks for reading this far, and thanks for using React Native!

- + diff --git a/blog/2016/07/06/toward-better-documentation/index.html b/blog/2016/07/06/toward-better-documentation/index.html index 003103c8107..b5f2e31e4dc 100644 --- a/blog/2016/07/06/toward-better-documentation/index.html +++ b/blog/2016/07/06/toward-better-documentation/index.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
AppRegistry.registerComponent('ScratchPad', () => ScratchPad);

We think these inline examples, using the react-native-web-player module with help from Devin Abbott, are a great way to learn the basics of React Native, and we have updated our tutorial for new React Native developers to use these wherever possible. Check it out - if you have ever been curious to see what would happen if you modified just one little bit of sample code, this is a really nice way to poke around. Also, if you're building developer tools and you want to show a live React Native sample on your own site, react-native-web-player can make that straightforward.

The core simulation engine is provided by Nicolas Gallagher's react-native-web project, which provides a way to display React Native components like Text and View on the web. Check out react-native-web if you're interested in building mobile and web experiences that share a large chunk of the codebase.

Better Guides

In some parts of React Native, there are multiple ways to do things, and we've heard feedback that we could provide better guidance.

We have a new guide to Navigation that compares the different approaches and advises on what you should use - Navigator, NavigatorIOS, NavigationExperimental. In the medium term, we're working towards improving and consolidating those interfaces. In the short term, we hope that a better guide will make your life easier.

We also have a new guide to handling touches that explains some of the basics of making button-like interfaces, and a brief summary of the different ways to handle touch events.

Another area we worked on is Flexbox. This includes tutorials on how to handle layout with Flexbox and how to control the size of components. It also includes an unsexy but hopefully-useful list of all the props that control layout in React Native.

Getting Started

When you start getting a React Native development environment set up on your machine, you do have to do a bunch of installing and configuring things. It's hard to make installation a really fun and exciting experience, but we can at least make it as quick and painless as possible.

We built a new Getting Started workflow that lets you select your development operating system and your mobile operating system up front, to provide one concise place with all the setup instructions. We also went through the installation process to make sure everything worked and to make sure that every decision point had a clear recommendation. After testing it out on our innocent coworkers, we're pretty sure this is an improvement.

We also worked on the guide to integrating React Native into an existing app. Many of the largest apps that use React Native, like the Facebook app itself, actually build part of the app in React Native, and part of it using regular development tools. We hope this guide makes it easier for more people to build apps this way.

We Need Your Help

Your feedback lets us know what we should prioritize. I know some people will read this blog post and think "Better docs? Pffft. The documentation for X is still garbage!". That's great - we need that energy. The best way to give us feedback depends on the sort of feedback.

If you find a mistake in the documentation, like inaccurate descriptions or code that doesn't actually work, file an issue. Tag it with "Documentation", so that it's easier to route it to the right people.

If there isn't a specific mistake, but something in the documentation is fundamentally confusing, it's not a great fit for a GitHub issue. Instead, post on Canny about the area of the docs that could use help. This helps us prioritize when we are doing more general work like guide-writing.

Thanks for reading this far, and thanks for using React Native!

- + diff --git a/blog/2016/08/12/react-native-meetup-san-francisco.html b/blog/2016/08/12/react-native-meetup-san-francisco.html index 4d0941863f2..50981fdfecc 100644 --- a/blog/2016/08/12/react-native-meetup-san-francisco.html +++ b/blog/2016/08/12/react-native-meetup-san-francisco.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

San Francisco Meetup Recap

Héctor Ramos

Héctor Ramos

Developer Advocate at Facebook

Last week I had the opportunity to attend the React Native Meetup at Zynga’s San Francisco office. With around 200 people in attendance, it served as a great place to meet other developers near me that are also interested in React Native.

I was particularly interested in learning more about how React and React Native are used at companies like Zynga, Netflix, and Airbnb. The agenda for the night would be as follows:

  • Rapid Prototyping in React
  • Designing APIs for React Native
  • Bridging the Gap: Using React Native in Existing Codebases

But first, the event started off with a quick introduction and a brief recap of recent news:

If one of these meetups is held near you, I highly recommend attending!

Rapid Prototyping in React at Zynga

The first round of news was followed by a quick introduction by Zynga, our hosts for the evening. Abhishek Chadha talked about how they use React to quickly prototype new experiences on mobile, demoing a quick prototype of a Draw Something-like app. They use a similar approach as React Native, providing access to native APIs via a bridge. This was demonstrated when Abhishek used the device's camera to snap a photo of the audience and then drew a hat on someone's head.

Designing APIs for React Native at Netflix

Up next, the first featured talk of the evening. Clarence Leung, Senior Software Engineer at Netflix, presented his talk on Designing APIs for React Native. First he noted the two main types of libraries one may work on: components such as tab bars and date pickers, and libraries that provide access to native services such as the camera roll or in-app payments. There are two ways one may approach when building a library for use in React Native:

  • Provide platform-specific components
  • A cross-platform library with a similar API for both Android and iOS

Each approach has its own considerations, and it’s up to you to determine what works best for your needs.

Approach #1

As an example of platform-specific components, Clarence talked about the DatePickerIOS and DatePickerAndroid from core React Native. On iOS, date pickers are rendered as part of the UI and can be easily embedded in an existing view, while date pickers on Android are presented modally. It makes sense to provide separate components in this case.

Approach #2

Photo pickers, on the other hand, are treated similarly on Android and iOS. There are some slight differences — Android does not group photos into folders like iOS does with Selfies, for example — but those are easily handled using if statements and the Platform component.

Regardless of which approach you settle on, it’s a good idea to minimize the API surface and build app-specific libraries. For example, iOS’s In-App Purchase framework supports one-time, consumable purchases, as well as renewable subscriptions. If your app will only need to support consumable purchases, you may get away with dropping support for subscriptions in your cross-platform library.

There was a brief Q&A session at the end of Clarence’s talk. One of the interesting tid bits that came out of it was that around 80% of the React Native code written for these libraries at Netflix is shared across both Android and iOS.

Bridging the Gap, Using React Native in Existing Codebases

The final talk of the night was by Leland Richardson from Airbnb. The talk was focused on the use of React Native in existing codebases. I already know how easy it is to write a new app from scratch using React Native, so I was very interested to hear about Airbnb’s experience adopting React Native in their existing native apps.

Leland started off by talking about greenfield apps versus brownfield apps. Greenfield means to start a project without the need to consider any prior work. This is in contrast to brownfield projects where you need to take into account the existing project’s requirements, development processes, and all of the teams various needs.

When you’re working on a greenfield app, the React Native CLI sets up a single repository for both Android and iOS and everything just works. The first challenge against using React Native at Airbnb was the fact that the Android and iOS app each had their own repository. Multi-repo companies have some hurdles to get past before they can adopt React Native.

To get around this, Airbnb first set up a new repo for the React Native codebase. They used their continuous integration servers to mirror the Android and iOS repos into this new repo. After tests are run and the bundle is built, the build artifacts are synced back to the Android and iOS repos. This allows the mobile engineers to work on native code without altering their development environment. Mobile engineers don't need to install npm, run the packager, or remember to build the JavaScript bundle. The engineers writing actual React Native code do not have to worry about syncing their code across Android and iOS, as they work on the React Native repository directly.

This does come with some drawbacks, mainly they could not ship atomic updates. Changes that require a combination of native and JavaScript code would require three separate pull requests, all of which had to be carefully landed. In order to avoid conflicts, CI will fail to land changes back to the Android and iOS repos if master has changed since the build started. This would cause long delays during high commit frequency days (such as when new releases are cut).

Airbnb has since moved to a mono repo approach. Fortunately this was already under consideration, and once the Android and iOS teams became comfortable with using React Native they were happy to accelerate the move towards the mono repo.

This has solved most of the issues they had with the split repo approach. Leland did note that this does cause a higher strain on the version control servers, which may be an issue for smaller companies.

The Navigation Problem

The second half of Leland's talk focused on a topic that is dear to me: the Navigation problem in React Native. He talked about the abundance of navigation libraries in React Native, both first party and third party. NavigationExperimental was mentioned as something that seemed promising, but ended up not being well suited for their use case.

In fact, none of the existing navigation libraries seem to work well for brownfield apps. A brownfield app requires that the navigation state be fully owned by the native app. For example, if a user’s session expires while a React Native view is being presented, the native app should be able to take over and present a login screen as needed.

Airbnb also wanted to avoid replacing native navigation bars with JavaScript versions as part of a transition, as the effect could be jarring. Initially they limited themselves to modally presented views, but this obviously presented a problem when it came to adopting React Native more widely within their apps.

They decided that they needed their own library. The library is called airbnb-navigation. The library has not yet being open sourced as it is strongly tied to Airbnb’s codebase, but it is something they’d like to release by the end of the year.

I won’t go into much detail into the library’s API, but here are some of the key takeaways:

  • One must preregister scenes ahead of time
  • Each scene is displayed within its own RCTRootView. They are presented natively on each platform (e.g. UINavigationControllers are used on iOS).
  • The main ScrollView in a scene should be wrapped in a ScrollScene component. Doing so allows you to take advantage of native behaviors such as tapping on the status bar to scroll to the top on iOS.
  • Transitions between scenes are handled natively, no need to worry about performance.
  • The Android back button is automatically supported.
  • They can take advantage of View Controller based navigation bar styling via a Navigator.Config UI-less component.

There’s also some considerations to keep in mind:

  • The navigation bar is not easily customized in JavaScript, as it is a native component. This is intentional, as using native navigation bars is a hard requirement for this type of library.
  • ScreenProps must be serialized/de-serialized whenever they're sent through the bridge, so care must be taken if sending too much data here.
  • Navigation state is owned by the native app (also a hard requirement for the library), so things like Redux cannot manipulate navigation state.

Leland's talk was also followed by a Q&A session. Overall, Airbnb is satisfied with React Native. They’re interested in using Code Push to fix any issues without going through the App Store, and their engineers love Live Reload, as they don't have to wait for the native app to be rebuilt after every minor change.

Closing Remarks

The event ended with some additional React Native news:

Meetups provide a good opportunity to meet and learn from other developers in the community. I'm looking forward to attending more React Native meetups in the future. If you make it up to one of these, please look out for me and let me know how we can make React Native work better for you!

- + diff --git a/blog/2016/08/12/react-native-meetup-san-francisco/index.html b/blog/2016/08/12/react-native-meetup-san-francisco/index.html index 4d0941863f2..50981fdfecc 100644 --- a/blog/2016/08/12/react-native-meetup-san-francisco/index.html +++ b/blog/2016/08/12/react-native-meetup-san-francisco/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

San Francisco Meetup Recap

Héctor Ramos

Héctor Ramos

Developer Advocate at Facebook

Last week I had the opportunity to attend the React Native Meetup at Zynga’s San Francisco office. With around 200 people in attendance, it served as a great place to meet other developers near me that are also interested in React Native.

I was particularly interested in learning more about how React and React Native are used at companies like Zynga, Netflix, and Airbnb. The agenda for the night would be as follows:

  • Rapid Prototyping in React
  • Designing APIs for React Native
  • Bridging the Gap: Using React Native in Existing Codebases

But first, the event started off with a quick introduction and a brief recap of recent news:

If one of these meetups is held near you, I highly recommend attending!

Rapid Prototyping in React at Zynga

The first round of news was followed by a quick introduction by Zynga, our hosts for the evening. Abhishek Chadha talked about how they use React to quickly prototype new experiences on mobile, demoing a quick prototype of a Draw Something-like app. They use a similar approach as React Native, providing access to native APIs via a bridge. This was demonstrated when Abhishek used the device's camera to snap a photo of the audience and then drew a hat on someone's head.

Designing APIs for React Native at Netflix

Up next, the first featured talk of the evening. Clarence Leung, Senior Software Engineer at Netflix, presented his talk on Designing APIs for React Native. First he noted the two main types of libraries one may work on: components such as tab bars and date pickers, and libraries that provide access to native services such as the camera roll or in-app payments. There are two ways one may approach when building a library for use in React Native:

  • Provide platform-specific components
  • A cross-platform library with a similar API for both Android and iOS

Each approach has its own considerations, and it’s up to you to determine what works best for your needs.

Approach #1

As an example of platform-specific components, Clarence talked about the DatePickerIOS and DatePickerAndroid from core React Native. On iOS, date pickers are rendered as part of the UI and can be easily embedded in an existing view, while date pickers on Android are presented modally. It makes sense to provide separate components in this case.

Approach #2

Photo pickers, on the other hand, are treated similarly on Android and iOS. There are some slight differences — Android does not group photos into folders like iOS does with Selfies, for example — but those are easily handled using if statements and the Platform component.

Regardless of which approach you settle on, it’s a good idea to minimize the API surface and build app-specific libraries. For example, iOS’s In-App Purchase framework supports one-time, consumable purchases, as well as renewable subscriptions. If your app will only need to support consumable purchases, you may get away with dropping support for subscriptions in your cross-platform library.

There was a brief Q&A session at the end of Clarence’s talk. One of the interesting tid bits that came out of it was that around 80% of the React Native code written for these libraries at Netflix is shared across both Android and iOS.

Bridging the Gap, Using React Native in Existing Codebases

The final talk of the night was by Leland Richardson from Airbnb. The talk was focused on the use of React Native in existing codebases. I already know how easy it is to write a new app from scratch using React Native, so I was very interested to hear about Airbnb’s experience adopting React Native in their existing native apps.

Leland started off by talking about greenfield apps versus brownfield apps. Greenfield means to start a project without the need to consider any prior work. This is in contrast to brownfield projects where you need to take into account the existing project’s requirements, development processes, and all of the teams various needs.

When you’re working on a greenfield app, the React Native CLI sets up a single repository for both Android and iOS and everything just works. The first challenge against using React Native at Airbnb was the fact that the Android and iOS app each had their own repository. Multi-repo companies have some hurdles to get past before they can adopt React Native.

To get around this, Airbnb first set up a new repo for the React Native codebase. They used their continuous integration servers to mirror the Android and iOS repos into this new repo. After tests are run and the bundle is built, the build artifacts are synced back to the Android and iOS repos. This allows the mobile engineers to work on native code without altering their development environment. Mobile engineers don't need to install npm, run the packager, or remember to build the JavaScript bundle. The engineers writing actual React Native code do not have to worry about syncing their code across Android and iOS, as they work on the React Native repository directly.

This does come with some drawbacks, mainly they could not ship atomic updates. Changes that require a combination of native and JavaScript code would require three separate pull requests, all of which had to be carefully landed. In order to avoid conflicts, CI will fail to land changes back to the Android and iOS repos if master has changed since the build started. This would cause long delays during high commit frequency days (such as when new releases are cut).

Airbnb has since moved to a mono repo approach. Fortunately this was already under consideration, and once the Android and iOS teams became comfortable with using React Native they were happy to accelerate the move towards the mono repo.

This has solved most of the issues they had with the split repo approach. Leland did note that this does cause a higher strain on the version control servers, which may be an issue for smaller companies.

The Navigation Problem

The second half of Leland's talk focused on a topic that is dear to me: the Navigation problem in React Native. He talked about the abundance of navigation libraries in React Native, both first party and third party. NavigationExperimental was mentioned as something that seemed promising, but ended up not being well suited for their use case.

In fact, none of the existing navigation libraries seem to work well for brownfield apps. A brownfield app requires that the navigation state be fully owned by the native app. For example, if a user’s session expires while a React Native view is being presented, the native app should be able to take over and present a login screen as needed.

Airbnb also wanted to avoid replacing native navigation bars with JavaScript versions as part of a transition, as the effect could be jarring. Initially they limited themselves to modally presented views, but this obviously presented a problem when it came to adopting React Native more widely within their apps.

They decided that they needed their own library. The library is called airbnb-navigation. The library has not yet being open sourced as it is strongly tied to Airbnb’s codebase, but it is something they’d like to release by the end of the year.

I won’t go into much detail into the library’s API, but here are some of the key takeaways:

  • One must preregister scenes ahead of time
  • Each scene is displayed within its own RCTRootView. They are presented natively on each platform (e.g. UINavigationControllers are used on iOS).
  • The main ScrollView in a scene should be wrapped in a ScrollScene component. Doing so allows you to take advantage of native behaviors such as tapping on the status bar to scroll to the top on iOS.
  • Transitions between scenes are handled natively, no need to worry about performance.
  • The Android back button is automatically supported.
  • They can take advantage of View Controller based navigation bar styling via a Navigator.Config UI-less component.

There’s also some considerations to keep in mind:

  • The navigation bar is not easily customized in JavaScript, as it is a native component. This is intentional, as using native navigation bars is a hard requirement for this type of library.
  • ScreenProps must be serialized/de-serialized whenever they're sent through the bridge, so care must be taken if sending too much data here.
  • Navigation state is owned by the native app (also a hard requirement for the library), so things like Redux cannot manipulate navigation state.

Leland's talk was also followed by a Q&A session. Overall, Airbnb is satisfied with React Native. They’re interested in using Code Push to fix any issues without going through the App Store, and their engineers love Live Reload, as they don't have to wait for the native app to be rebuilt after every minor change.

Closing Remarks

The event ended with some additional React Native news:

Meetups provide a good opportunity to meet and learn from other developers in the community. I'm looking forward to attending more React Native meetups in the future. If you make it up to one of these, please look out for me and let me know how we can make React Native work better for you!

- + diff --git a/blog/2016/08/19/right-to-left-support-for-react-native-apps.html b/blog/2016/08/19/right-to-left-support-for-react-native-apps.html index a87db435433..79c83a8151c 100644 --- a/blog/2016/08/19/right-to-left-support-for-react-native-apps.html +++ b/blog/2016/08/19/right-to-left-support-for-react-native-apps.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@
_onDirectionChange = () => {
I18nManager.forceRTL(!this.state.isRTL);
this.setState({ isRTL: !this.state.isRTL });
Alert.alert(
'Reload this page',
'Please reload this page to change the UI direction! ' +
'All examples in this app will be affected. ' +
'Check them out to see what they look like in RTL layout.'
);
};

When working on a new feature, you can easily toggle this button and reload the app to see RTL layout. The benefit is you won't need to change the language setting to test, however some text alignment won't change, as explained in the next section. Therefore, it's always a good idea to test your app in the RTL language before launching.

Limitations and Future Plan

The RTL support should cover most of the UX in your app; however, there are some limitations for now:

Try it Out!

Check out the RTLExample in the RNTester to understand more about RTL support, and let us know how it works for you!

Finally, thank you for reading! We hope that the RTL support for React Native helps you grow your apps for international audience!

- + diff --git a/blog/2016/08/19/right-to-left-support-for-react-native-apps/index.html b/blog/2016/08/19/right-to-left-support-for-react-native-apps/index.html index a87db435433..79c83a8151c 100644 --- a/blog/2016/08/19/right-to-left-support-for-react-native-apps/index.html +++ b/blog/2016/08/19/right-to-left-support-for-react-native-apps/index.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@
_onDirectionChange = () => {
I18nManager.forceRTL(!this.state.isRTL);
this.setState({ isRTL: !this.state.isRTL });
Alert.alert(
'Reload this page',
'Please reload this page to change the UI direction! ' +
'All examples in this app will be affected. ' +
'Check them out to see what they look like in RTL layout.'
);
};

When working on a new feature, you can easily toggle this button and reload the app to see RTL layout. The benefit is you won't need to change the language setting to test, however some text alignment won't change, as explained in the next section. Therefore, it's always a good idea to test your app in the RTL language before launching.

Limitations and Future Plan

The RTL support should cover most of the UX in your app; however, there are some limitations for now:

Try it Out!

Check out the RTLExample in the RNTester to understand more about RTL support, and let us know how it works for you!

Finally, thank you for reading! We hope that the RTL support for React Native helps you grow your apps for international audience!

- + diff --git a/blog/2016/09/08/exponent-talks-unraveling-navigation.html b/blog/2016/09/08/exponent-talks-unraveling-navigation.html index 791622bf677..5bb8762fc00 100644 --- a/blog/2016/09/08/exponent-talks-unraveling-navigation.html +++ b/blog/2016/09/08/exponent-talks-unraveling-navigation.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Expo Talks: Adam on Unraveling Navigation

Héctor Ramos

Héctor Ramos

Developer Advocate at Facebook

Adam Miskiewicz from Expo talks about mobile navigation and the ex-navigation React Native library at Expo's office hours last week.

- + diff --git a/blog/2016/09/08/exponent-talks-unraveling-navigation/index.html b/blog/2016/09/08/exponent-talks-unraveling-navigation/index.html index 791622bf677..5bb8762fc00 100644 --- a/blog/2016/09/08/exponent-talks-unraveling-navigation/index.html +++ b/blog/2016/09/08/exponent-talks-unraveling-navigation/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Expo Talks: Adam on Unraveling Navigation

Héctor Ramos

Héctor Ramos

Developer Advocate at Facebook

Adam Miskiewicz from Expo talks about mobile navigation and the ex-navigation React Native library at Expo's office hours last week.

- + diff --git a/blog/2016/10/25/0.36-headless-js-the-keyboard-api-and-more.html b/blog/2016/10/25/0.36-headless-js-the-keyboard-api-and-more.html index c06027e2633..f22bba2888d 100644 --- a/blog/2016/10/25/0.36-headless-js-the-keyboard-api-and-more.html +++ b/blog/2016/10/25/0.36-headless-js-the-keyboard-api-and-more.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
Animated.spring(a, {
toValue: 2,
}).start();

b will then follow a's spring animation and produce the value of 1 / a.

The basic usage is like this:

<Animated.View style={{transform: [{scale: a}]}}>
<Animated.Image style={{transform: [{scale: b}]}} />
<Animated.View>

In this example, the inner image won't get stretched at all because the parent's scaling gets cancelled out. If you'd like to learn more, check out the Animations guide.

Dark Status Bars

A new barStyle value has been added to StatusBar: dark-content. With this addition, you can now use barStyle on both Android and iOS. The behavior will now be the following:

...and more

The above is just a sample of what has changed in 0.36. Check out the release notes on GitHub to see the full list of new features, bug fixes, and breaking changes.

You can upgrade to 0.36 by running the following commands in a terminal:

$ npm install --save react-native@0.36
$ react-native upgrade
- + diff --git a/blog/2016/10/25/0.36-headless-js-the-keyboard-api-and-more/index.html b/blog/2016/10/25/0.36-headless-js-the-keyboard-api-and-more/index.html index c06027e2633..f22bba2888d 100644 --- a/blog/2016/10/25/0.36-headless-js-the-keyboard-api-and-more/index.html +++ b/blog/2016/10/25/0.36-headless-js-the-keyboard-api-and-more/index.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
Animated.spring(a, {
toValue: 2,
}).start();

b will then follow a's spring animation and produce the value of 1 / a.

The basic usage is like this:

<Animated.View style={{transform: [{scale: a}]}}>
<Animated.Image style={{transform: [{scale: b}]}} />
<Animated.View>

In this example, the inner image won't get stretched at all because the parent's scaling gets cancelled out. If you'd like to learn more, check out the Animations guide.

Dark Status Bars

A new barStyle value has been added to StatusBar: dark-content. With this addition, you can now use barStyle on both Android and iOS. The behavior will now be the following:

...and more

The above is just a sample of what has changed in 0.36. Check out the release notes on GitHub to see the full list of new features, bug fixes, and breaking changes.

You can upgrade to 0.36 by running the following commands in a terminal:

$ npm install --save react-native@0.36
$ react-native upgrade
- + diff --git a/blog/2016/11/08/introducing-button-yarn-and-a-public-roadmap.html b/blog/2016/11/08/introducing-button-yarn-and-a-public-roadmap.html index 0fa960b9339..2d14091ad0b 100644 --- a/blog/2016/11/08/introducing-button-yarn-and-a-public-roadmap.html +++ b/blog/2016/11/08/introducing-button-yarn-and-a-public-roadmap.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Introducing Button, Faster Installs with Yarn, and a Public Roadmap

Héctor Ramos

Héctor Ramos

Developer Advocate at Facebook

We have heard from many people that there is so much work happening with React Native, it can be tough to keep track of what's going on. To help communicate what work is in progress, we are now publishing a roadmap for React Native. At a high level, this work can be broken down into three priorities:

  • Core Libraries. Adding more functionality to the most useful components and APIs.
  • Stability. Improve the underlying infrastructure to reduce bugs and improve code quality.
  • Developer Experience. Help React Native developers move faster

If you have suggestions for features that you think would be valuable on the roadmap, check out Canny, where you can suggest new features and discuss existing proposals.

What's new in React Native

Version 0.37 of React Native, released today, introduces a new core component to make it really easy to add a touchable Button to any app. We're also introducing support for the new Yarn package manager, which should speed up the whole process of updating your app's dependencies.

Introducing Button

Today we're introducing a basic <Button /> component that looks great on every platform. This addresses one of the most common pieces of feedback we get: React Native is one of the only mobile development toolkits without a button ready to use out of the box.

Simple Button on Android, iOS

<Button
onPress={onPressMe}
title="Press Me"
accessibilityLabel="Learn more about this Simple Button"
/>

Experienced React Native developers know how to make a button: use TouchableOpacity for the default look on iOS, TouchableNativeFeedback for the ripple effect on Android, then apply a few styles. Custom buttons aren't particularly hard to build or install, but we aim to make React Native radically easy to learn. With the addition of a basic button into core, newcomers will be able to develop something awesome in their first day, rather than spending that time formatting a Button and learning about Touchable nuances.

Button is meant to work great and look native on every platform, so it won't support all the bells and whistles that custom buttons do. It is a great starting point, but is not meant to replace all your existing buttons. To learn more, check out the new Button documentation, complete with a runnable example!

Speed up react-native init using Yarn

You can now use Yarn, the new package manager for JavaScript, to speed up react-native init significantly. To see the speedup please install yarn and upgrade your react-native-cli to 1.2.0:

$ npm install -g react-native-cli

You should now see “Using yarn” when setting up new apps:

Using yarn

In simple local testing react-native init finished in about 1 minute on a good network (vs around 3 minutes when using npm 3.10.8). Installing yarn is optional but highly recommended.

Thank you!

We'd like to thank everyone who contributed to this release. The full release notes are now available on GitHub. With over two dozen bug fixes and new features, React Native just keeps getting better thanks to you.

- + diff --git a/blog/2016/11/08/introducing-button-yarn-and-a-public-roadmap/index.html b/blog/2016/11/08/introducing-button-yarn-and-a-public-roadmap/index.html index 0fa960b9339..2d14091ad0b 100644 --- a/blog/2016/11/08/introducing-button-yarn-and-a-public-roadmap/index.html +++ b/blog/2016/11/08/introducing-button-yarn-and-a-public-roadmap/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Introducing Button, Faster Installs with Yarn, and a Public Roadmap

Héctor Ramos

Héctor Ramos

Developer Advocate at Facebook

We have heard from many people that there is so much work happening with React Native, it can be tough to keep track of what's going on. To help communicate what work is in progress, we are now publishing a roadmap for React Native. At a high level, this work can be broken down into three priorities:

  • Core Libraries. Adding more functionality to the most useful components and APIs.
  • Stability. Improve the underlying infrastructure to reduce bugs and improve code quality.
  • Developer Experience. Help React Native developers move faster

If you have suggestions for features that you think would be valuable on the roadmap, check out Canny, where you can suggest new features and discuss existing proposals.

What's new in React Native

Version 0.37 of React Native, released today, introduces a new core component to make it really easy to add a touchable Button to any app. We're also introducing support for the new Yarn package manager, which should speed up the whole process of updating your app's dependencies.

Introducing Button

Today we're introducing a basic <Button /> component that looks great on every platform. This addresses one of the most common pieces of feedback we get: React Native is one of the only mobile development toolkits without a button ready to use out of the box.

Simple Button on Android, iOS

<Button
onPress={onPressMe}
title="Press Me"
accessibilityLabel="Learn more about this Simple Button"
/>

Experienced React Native developers know how to make a button: use TouchableOpacity for the default look on iOS, TouchableNativeFeedback for the ripple effect on Android, then apply a few styles. Custom buttons aren't particularly hard to build or install, but we aim to make React Native radically easy to learn. With the addition of a basic button into core, newcomers will be able to develop something awesome in their first day, rather than spending that time formatting a Button and learning about Touchable nuances.

Button is meant to work great and look native on every platform, so it won't support all the bells and whistles that custom buttons do. It is a great starting point, but is not meant to replace all your existing buttons. To learn more, check out the new Button documentation, complete with a runnable example!

Speed up react-native init using Yarn

You can now use Yarn, the new package manager for JavaScript, to speed up react-native init significantly. To see the speedup please install yarn and upgrade your react-native-cli to 1.2.0:

$ npm install -g react-native-cli

You should now see “Using yarn” when setting up new apps:

Using yarn

In simple local testing react-native init finished in about 1 minute on a good network (vs around 3 minutes when using npm 3.10.8). Installing yarn is optional but highly recommended.

Thank you!

We'd like to thank everyone who contributed to this release. The full release notes are now available on GitHub. With over two dozen bug fixes and new features, React Native just keeps getting better thanks to you.

- + diff --git a/blog/2016/12/05/easier-upgrades.html b/blog/2016/12/05/easier-upgrades.html index 5a18216047d..ae29043e870 100644 --- a/blog/2016/12/05/easier-upgrades.html +++ b/blog/2016/12/05/easier-upgrades.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@
diff --git a/ios/MyAwesomeApp/Info.plist b/ios/MyAwesomeApp/Info.plist
index e98ebb0..2fb6a11 100644
--- a/ios/MyAwesomeApp/Info.plist
+++ b/ios/MyAwesomeApp/Info.plist
@@ -45,7 +45,7 @@
<dict>
<key>localhost</key>
<dict>
- <key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
+ <key>NSExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
[...]

All we need now is to apply this patch to your source files. While the old react-native upgrade process would have prompted you for any small difference, Git is able to merge most of the changes automatically using its 3-way merge algorithm and eventually leave us with familiar conflict delimiters:

13B07F951A680F5B00A75B9A /* Release */ = {
isa = XCBuildConfiguration;
buildSettings = {
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
<<<<<<< ours
CODE_SIGN_IDENTITY = "iPhone Developer";
FRAMEWORK_SEARCH_PATHS = (
"$(inherited)",
"$(PROJECT_DIR)/HockeySDK.embeddedframework",
"$(PROJECT_DIR)/HockeySDK-iOS/HockeySDK.embeddedframework",
);
=======
CURRENT_PROJECT_VERSION = 1;
>>>>>>> theirs
HEADER_SEARCH_PATHS = (
"$(inherited)",
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include,
"$(SRCROOT)/../node_modules/react-native/React/**",
"$(SRCROOT)/../node_modules/react-native-code-push/ios/CodePush/**",
);

These conflicts are generally easy to reason about. The delimiter ours stands for "your team" whereas theirs could be seen as "the React Native team".

Why introduce a new global package?

React Native comes with a global CLI (the react-native-cli package) which delegates commands to the local CLI embedded in the node_modules/react-native/local-cli directory.

As we mentioned above, the process has to be started from your current React Native version. If we had embedded the implementation in the local-cli, you wouldn't be able to enjoy this feature when using old versions of React Native. For example, you wouldn't be able to upgrade from 0.29.2 to 0.38.0 if this new upgrade code was only released in 0.38.0.

Upgrading based on Git is a big improvement in developer experience and it is important to make it available to everyone. By using a separate package react-native-git-upgrade installed globally you can use this new code today no matter what version of React Native your project is using.

One more reason is the recent Yeoman wipeout by Martin Konicek. We didn't want to get these Yeoman dependencies back into the react-native package to be able to evaluate the old template in order to create the patch.

Try it out and provide feedback

As a conclusion, I would say, enjoy the feature and feel free to suggest improvements, report issues and especially send pull requests. Each environment is a bit different and each React Native project is different, and we need your feedback to make this work well for everyone.

Thank you!

I would like to thank the awesome companies Zenika and M6 Web without whom none of this would have been possible!

- + diff --git a/blog/2016/12/05/easier-upgrades/index.html b/blog/2016/12/05/easier-upgrades/index.html index 5a18216047d..ae29043e870 100644 --- a/blog/2016/12/05/easier-upgrades/index.html +++ b/blog/2016/12/05/easier-upgrades/index.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@
diff --git a/ios/MyAwesomeApp/Info.plist b/ios/MyAwesomeApp/Info.plist
index e98ebb0..2fb6a11 100644
--- a/ios/MyAwesomeApp/Info.plist
+++ b/ios/MyAwesomeApp/Info.plist
@@ -45,7 +45,7 @@
<dict>
<key>localhost</key>
<dict>
- <key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
+ <key>NSExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
[...]

All we need now is to apply this patch to your source files. While the old react-native upgrade process would have prompted you for any small difference, Git is able to merge most of the changes automatically using its 3-way merge algorithm and eventually leave us with familiar conflict delimiters:

13B07F951A680F5B00A75B9A /* Release */ = {
isa = XCBuildConfiguration;
buildSettings = {
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
<<<<<<< ours
CODE_SIGN_IDENTITY = "iPhone Developer";
FRAMEWORK_SEARCH_PATHS = (
"$(inherited)",
"$(PROJECT_DIR)/HockeySDK.embeddedframework",
"$(PROJECT_DIR)/HockeySDK-iOS/HockeySDK.embeddedframework",
);
=======
CURRENT_PROJECT_VERSION = 1;
>>>>>>> theirs
HEADER_SEARCH_PATHS = (
"$(inherited)",
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include,
"$(SRCROOT)/../node_modules/react-native/React/**",
"$(SRCROOT)/../node_modules/react-native-code-push/ios/CodePush/**",
);

These conflicts are generally easy to reason about. The delimiter ours stands for "your team" whereas theirs could be seen as "the React Native team".

Why introduce a new global package?

React Native comes with a global CLI (the react-native-cli package) which delegates commands to the local CLI embedded in the node_modules/react-native/local-cli directory.

As we mentioned above, the process has to be started from your current React Native version. If we had embedded the implementation in the local-cli, you wouldn't be able to enjoy this feature when using old versions of React Native. For example, you wouldn't be able to upgrade from 0.29.2 to 0.38.0 if this new upgrade code was only released in 0.38.0.

Upgrading based on Git is a big improvement in developer experience and it is important to make it available to everyone. By using a separate package react-native-git-upgrade installed globally you can use this new code today no matter what version of React Native your project is using.

One more reason is the recent Yeoman wipeout by Martin Konicek. We didn't want to get these Yeoman dependencies back into the react-native package to be able to evaluate the old template in order to create the patch.

Try it out and provide feedback

As a conclusion, I would say, enjoy the feature and feel free to suggest improvements, report issues and especially send pull requests. Each environment is a bit different and each React Native project is different, and we need your feedback to make this work well for everyone.

Thank you!

I would like to thank the awesome companies Zenika and M6 Web without whom none of this would have been possible!

- + diff --git a/blog/2017/01/07/monthly-release-cadence.html b/blog/2017/01/07/monthly-release-cadence.html index 3a757d3e32f..c0b84805358 100644 --- a/blog/2017/01/07/monthly-release-cadence.html +++ b/blog/2017/01/07/monthly-release-cadence.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

A Monthly Release Cadence: Releasing December and January RC

Eric Vicenti

Eric Vicenti

Engineer at Facebook

Shortly after React Native was introduced, we started releasing every two weeks to help the community adopt new features, while keeping versions stable for production use. At Facebook we had to stabilize the codebase every two weeks for the release of our production iOS apps, so we decided to release the open source versions at the same pace. Now, many of the Facebook apps ship once per week, especially on Android. Because we ship from master weekly, we need to keep it quite stable. So the bi-weekly release cadence doesn't even benefit internal contributors anymore.

We frequently hear feedback from the community that the release rate is hard to keep up with. Tools like Expo had to skip every other release in order to manage the rapid change in version. So it seems clear that the bi-weekly releases did not serve the community well.

Now releasing monthly

We're happy to announce the new monthly release cadence, and the December 2016 release, v0.40, which has been stabilizing for all last month and is ready to adopt. (Just make sure to update headers in your native modules on iOS).

Although it may vary a few days to avoid weekends or handle unforeseen issues, you can now expect a given release to be available on the first day of the month, and released on the last.

Use the current month for the best support

The January release candidate is ready to try, and you can see what's new here.

To see what changes are coming and provide better feedback to React Native contributors, always use the current month's release candidate when possible. By the time each version is released at the end of the month, the changes it contains will have been shipped in production Facebook apps for over two weeks.

You can easily upgrade your app with the new react-native-git-upgrade command:

npm install -g react-native-git-upgrade
react-native-git-upgrade 0.41.0-rc.0

We hope this simpler approach will make it easier for the community to keep track of changes in React Native, and to adopt new versions as quickly as possible!

(Thanks go to Martin Konicek for coming up with this plan and Mike Grabowski for making it happen)

- + diff --git a/blog/2017/01/07/monthly-release-cadence/index.html b/blog/2017/01/07/monthly-release-cadence/index.html index 3a757d3e32f..c0b84805358 100644 --- a/blog/2017/01/07/monthly-release-cadence/index.html +++ b/blog/2017/01/07/monthly-release-cadence/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

A Monthly Release Cadence: Releasing December and January RC

Eric Vicenti

Eric Vicenti

Engineer at Facebook

Shortly after React Native was introduced, we started releasing every two weeks to help the community adopt new features, while keeping versions stable for production use. At Facebook we had to stabilize the codebase every two weeks for the release of our production iOS apps, so we decided to release the open source versions at the same pace. Now, many of the Facebook apps ship once per week, especially on Android. Because we ship from master weekly, we need to keep it quite stable. So the bi-weekly release cadence doesn't even benefit internal contributors anymore.

We frequently hear feedback from the community that the release rate is hard to keep up with. Tools like Expo had to skip every other release in order to manage the rapid change in version. So it seems clear that the bi-weekly releases did not serve the community well.

Now releasing monthly

We're happy to announce the new monthly release cadence, and the December 2016 release, v0.40, which has been stabilizing for all last month and is ready to adopt. (Just make sure to update headers in your native modules on iOS).

Although it may vary a few days to avoid weekends or handle unforeseen issues, you can now expect a given release to be available on the first day of the month, and released on the last.

Use the current month for the best support

The January release candidate is ready to try, and you can see what's new here.

To see what changes are coming and provide better feedback to React Native contributors, always use the current month's release candidate when possible. By the time each version is released at the end of the month, the changes it contains will have been shipped in production Facebook apps for over two weeks.

You can easily upgrade your app with the new react-native-git-upgrade command:

npm install -g react-native-git-upgrade
react-native-git-upgrade 0.41.0-rc.0

We hope this simpler approach will make it easier for the community to keep track of changes in React Native, and to adopt new versions as quickly as possible!

(Thanks go to Martin Konicek for coming up with this plan and Mike Grabowski for making it happen)

- + diff --git a/blog/2017/02/14/using-native-driver-for-animated.html b/blog/2017/02/14/using-native-driver-for-animated.html index 148564d6daf..3883a56308b 100644 --- a/blog/2017/02/14/using-native-driver-for-animated.html +++ b/blog/2017/02/14/using-native-driver-for-animated.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Using Native Driver for Animated

Janic Duplessis

Janic Duplessis

Software Engineer at App & Flow

For the past year, we've been working on improving performance of animations that use the Animated library. Animations are very important to create a beautiful user experience but can also be hard to do right. We want to make it easy for developers to create performant animations without having to worry about some of their code causing it to lag.

What is this?

The Animated API was designed with a very important constraint in mind, it is serializable. This means we can send everything about the animation to native before it has even started and allows native code to perform the animation on the UI thread without having to go through the bridge on every frame. It is very useful because once the animation has started, the JS thread can be blocked and the animation will still run smoothly. In practice this can happen a lot because user code runs on the JS thread and React renders can also lock JS for a long time.

A bit of history...

This project started about a year ago, when Expo built the li.st app on Android. Krzysztof Magiera was contracted to build the initial implementation on Android. It ended up working well and li.st was the first app to ship with native driven animations using Animated. A few months later, Brandon Withrow built the initial implementation on iOS. After that, Ryan Gomba and myself worked on adding missing features like support for Animated.event as well as squash bugs we found when using it in production apps. This was truly a community effort and I would like to thanks everyone that was involved as well as Expo for sponsoring a large part of the development. It is now used by Touchable components in React Native as well as for navigation animations in the newly released React Navigation library.

How does it work?

First, let's check out how animations currently work using Animated with the JS driver. When using Animated, you declare a graph of nodes that represent the animations that you want to perform, and then use a driver to update an Animated value using a predefined curve. You may also update an Animated value by connecting it to an event of a View using Animated.event.

Here's a breakdown of the steps for an animation and where it happens:

  • JS: The animation driver uses requestAnimationFrame to execute on every frame and update the value it drives using the new value it calculates based on the animation curve.
  • JS: Intermediate values are calculated and passed to a props node that is attached to a View.
  • JS: The View is updated using setNativeProps.
  • JS to Native bridge.
  • Native: The UIView or android.View is updated.

As you can see, most of the work happens on the JS thread. If it is blocked the animation will skip frames. It also needs to go through the JS to Native bridge on every frame to update native views.

What the native driver does is move all of these steps to native. Since Animated produces a graph of animated nodes, it can be serialized and sent to native only once when the animation starts, eliminating the need to callback into the JS thread; the native code can take care of updating the views directly on the UI thread on every frame.

Here's an example of how we can serialize an animated value and an interpolation node (not the exact implementation, just an example).

Create the native value node, this is the value that will be animated:

NativeAnimatedModule.createNode({
id: 1,
type: 'value',
initialValue: 0,
});

Create the native interpolation node, this tells the native driver how to interpolate a value:

NativeAnimatedModule.createNode({
id: 2,
type: 'interpolation',
inputRange: [0, 10],
outputRange: [10, 0],
extrapolate: 'clamp',
});

Create the native props node, this tells the native driver which prop on the view it is attached to:

NativeAnimatedModule.createNode({
id: 3,
type: 'props',
properties: ['style.opacity'],
});

Connect nodes together:

NativeAnimatedModule.connectNodes(1, 2);
NativeAnimatedModule.connectNodes(2, 3);

Connect the props node to a view:

NativeAnimatedModule.connectToView(3, ReactNative.findNodeHandle(viewRef));

With that, the native animated module has all the info it needs to update the native views directly without having to go to JS to calculate any value.

All there is left to do is actually start the animation by specifying what type of animation curve we want and what animated value to update. Timing animations can also be simplified by calculating every frame of the animation in advance in JS to make the native implementation smaller.

NativeAnimatedModule.startAnimation({
type: 'timing',
frames: [0, 0.1, 0.2, 0.4, 0.65, ...],
animatedValueId: 1,
});

And now here's the breakdown of what happens when the animation runs:

  • Native: The native animation driver uses CADisplayLink or android.view.Choreographer to execute on every frame and update the value it drives using the new value it calculates based on the animation curve.
  • Native: Intermediate values are calculated and passed to a props node that is attached to a native view.
  • Native: The UIView or android.View is updated.

As you can see, no more JS thread and no more bridge which means faster animations! 🎉🎉

How do I use this in my app?

For normal animations the answer is simple, just add useNativeDriver: true to the animation config when starting it.

Before:

Animated.timing(this.state.animatedValue, {
toValue: 1,
duration: 500,
}).start();

After:

Animated.timing(this.state.animatedValue, {
toValue: 1,
duration: 500,
useNativeDriver: true, // <-- Add this
}).start();

Animated values are only compatible with one driver so if you use native driver when starting an animation on a value, make sure every animation on that value also uses the native driver.

It also works with Animated.event, this is very useful if you have an animation that must follow the scroll position because without the native driver it will always run a frame behind of the gesture because of the async nature of React Native.

Before:

<ScrollView
scrollEventThrottle={16}
onScroll={Animated.event(
[{ nativeEvent: { contentOffset: { y: this.state.animatedValue } } }]
)}
>
{content}
</ScrollView>

After:

<Animated.ScrollView // <-- Use the Animated ScrollView wrapper
scrollEventThrottle={1} // <-- Use 1 here to make sure no events are ever missed
onScroll={Animated.event(
[{ nativeEvent: { contentOffset: { y: this.state.animatedValue } } }],
{ useNativeDriver: true } // <-- Add this
)}
>
{content}
</Animated.ScrollView>

Caveats

Not everything you can do with Animated is currently supported in Native Animated. The main limitation is that you can only animate non-layout properties, things like transform and opacity will work but Flexbox and position properties won't. Another one is with Animated.event, it will only work with direct events and not bubbling events. This means it does not work with PanResponder but does work with things like ScrollView#onScroll.

Native Animated has also been part of React Native for quite a while but has never been documented because it was considered experimental. Because of that make sure you are using a recent version (0.40+) of React Native if you want to use this feature.

Resources

For more information about animated I recommend watching this talk by Christopher Chedeau.

If you want a deep dive into animations and how offloading them to native can improve user experience there is also this talk by Krzysztof Magiera.

- + diff --git a/blog/2017/02/14/using-native-driver-for-animated/index.html b/blog/2017/02/14/using-native-driver-for-animated/index.html index 148564d6daf..3883a56308b 100644 --- a/blog/2017/02/14/using-native-driver-for-animated/index.html +++ b/blog/2017/02/14/using-native-driver-for-animated/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Using Native Driver for Animated

Janic Duplessis

Janic Duplessis

Software Engineer at App & Flow

For the past year, we've been working on improving performance of animations that use the Animated library. Animations are very important to create a beautiful user experience but can also be hard to do right. We want to make it easy for developers to create performant animations without having to worry about some of their code causing it to lag.

What is this?

The Animated API was designed with a very important constraint in mind, it is serializable. This means we can send everything about the animation to native before it has even started and allows native code to perform the animation on the UI thread without having to go through the bridge on every frame. It is very useful because once the animation has started, the JS thread can be blocked and the animation will still run smoothly. In practice this can happen a lot because user code runs on the JS thread and React renders can also lock JS for a long time.

A bit of history...

This project started about a year ago, when Expo built the li.st app on Android. Krzysztof Magiera was contracted to build the initial implementation on Android. It ended up working well and li.st was the first app to ship with native driven animations using Animated. A few months later, Brandon Withrow built the initial implementation on iOS. After that, Ryan Gomba and myself worked on adding missing features like support for Animated.event as well as squash bugs we found when using it in production apps. This was truly a community effort and I would like to thanks everyone that was involved as well as Expo for sponsoring a large part of the development. It is now used by Touchable components in React Native as well as for navigation animations in the newly released React Navigation library.

How does it work?

First, let's check out how animations currently work using Animated with the JS driver. When using Animated, you declare a graph of nodes that represent the animations that you want to perform, and then use a driver to update an Animated value using a predefined curve. You may also update an Animated value by connecting it to an event of a View using Animated.event.

Here's a breakdown of the steps for an animation and where it happens:

  • JS: The animation driver uses requestAnimationFrame to execute on every frame and update the value it drives using the new value it calculates based on the animation curve.
  • JS: Intermediate values are calculated and passed to a props node that is attached to a View.
  • JS: The View is updated using setNativeProps.
  • JS to Native bridge.
  • Native: The UIView or android.View is updated.

As you can see, most of the work happens on the JS thread. If it is blocked the animation will skip frames. It also needs to go through the JS to Native bridge on every frame to update native views.

What the native driver does is move all of these steps to native. Since Animated produces a graph of animated nodes, it can be serialized and sent to native only once when the animation starts, eliminating the need to callback into the JS thread; the native code can take care of updating the views directly on the UI thread on every frame.

Here's an example of how we can serialize an animated value and an interpolation node (not the exact implementation, just an example).

Create the native value node, this is the value that will be animated:

NativeAnimatedModule.createNode({
id: 1,
type: 'value',
initialValue: 0,
});

Create the native interpolation node, this tells the native driver how to interpolate a value:

NativeAnimatedModule.createNode({
id: 2,
type: 'interpolation',
inputRange: [0, 10],
outputRange: [10, 0],
extrapolate: 'clamp',
});

Create the native props node, this tells the native driver which prop on the view it is attached to:

NativeAnimatedModule.createNode({
id: 3,
type: 'props',
properties: ['style.opacity'],
});

Connect nodes together:

NativeAnimatedModule.connectNodes(1, 2);
NativeAnimatedModule.connectNodes(2, 3);

Connect the props node to a view:

NativeAnimatedModule.connectToView(3, ReactNative.findNodeHandle(viewRef));

With that, the native animated module has all the info it needs to update the native views directly without having to go to JS to calculate any value.

All there is left to do is actually start the animation by specifying what type of animation curve we want and what animated value to update. Timing animations can also be simplified by calculating every frame of the animation in advance in JS to make the native implementation smaller.

NativeAnimatedModule.startAnimation({
type: 'timing',
frames: [0, 0.1, 0.2, 0.4, 0.65, ...],
animatedValueId: 1,
});

And now here's the breakdown of what happens when the animation runs:

  • Native: The native animation driver uses CADisplayLink or android.view.Choreographer to execute on every frame and update the value it drives using the new value it calculates based on the animation curve.
  • Native: Intermediate values are calculated and passed to a props node that is attached to a native view.
  • Native: The UIView or android.View is updated.

As you can see, no more JS thread and no more bridge which means faster animations! 🎉🎉

How do I use this in my app?

For normal animations the answer is simple, just add useNativeDriver: true to the animation config when starting it.

Before:

Animated.timing(this.state.animatedValue, {
toValue: 1,
duration: 500,
}).start();

After:

Animated.timing(this.state.animatedValue, {
toValue: 1,
duration: 500,
useNativeDriver: true, // <-- Add this
}).start();

Animated values are only compatible with one driver so if you use native driver when starting an animation on a value, make sure every animation on that value also uses the native driver.

It also works with Animated.event, this is very useful if you have an animation that must follow the scroll position because without the native driver it will always run a frame behind of the gesture because of the async nature of React Native.

Before:

<ScrollView
scrollEventThrottle={16}
onScroll={Animated.event(
[{ nativeEvent: { contentOffset: { y: this.state.animatedValue } } }]
)}
>
{content}
</ScrollView>

After:

<Animated.ScrollView // <-- Use the Animated ScrollView wrapper
scrollEventThrottle={1} // <-- Use 1 here to make sure no events are ever missed
onScroll={Animated.event(
[{ nativeEvent: { contentOffset: { y: this.state.animatedValue } } }],
{ useNativeDriver: true } // <-- Add this
)}
>
{content}
</Animated.ScrollView>

Caveats

Not everything you can do with Animated is currently supported in Native Animated. The main limitation is that you can only animate non-layout properties, things like transform and opacity will work but Flexbox and position properties won't. Another one is with Animated.event, it will only work with direct events and not bubbling events. This means it does not work with PanResponder but does work with things like ScrollView#onScroll.

Native Animated has also been part of React Native for quite a while but has never been documented because it was considered experimental. Because of that make sure you are using a recent version (0.40+) of React Native if you want to use this feature.

Resources

For more information about animated I recommend watching this talk by Christopher Chedeau.

If you want a deep dive into animations and how offloading them to native can improve user experience there is also this talk by Krzysztof Magiera.

- + diff --git a/blog/2017/03/13/better-list-views.html b/blog/2017/03/13/better-list-views.html index 494af9bf2db..f2ae0540119 100644 --- a/blog/2017/03/13/better-list-views.html +++ b/blog/2017/03/13/better-list-views.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@
<SectionList
sections={[ // heterogeneous rendering between sections
{data: [...], key: ..., renderItem: ...},
{data: [...], key: ..., renderItem: ...},
{data: [...], key: ..., renderItem: ...},
]}
/>

<VirtualizedList>

The implementation behind the scenes with a more flexible API. Especially handy if your data is not in a plain array (e.g. an immutable list).

Features

Lists are used in many contexts, so we packed the new components full of features to handle the majority of use cases out of the box:

Some Caveats

Performance

Besides simplifying the API, the new list components also have significant performance enhancements, the main one being nearly constant memory usage for any number of rows. This is done by 'virtualizing' elements that are outside of the render window by completely unmounting them from the component hierarchy and reclaiming the JS memory from the react components, along with the native memory from the shadow tree and the UI views. This has a catch which is that internal component state will not be preserved, so make sure you track any important state outside of the components themselves, e.g. in Relay or Redux or Flux store.

Limiting the render window also reduces the amount of work that needs to be done by React and the native platform, e.g from view traversals. Even if you are rendering the last of a million elements, with these new lists there is no need to iterate through all those elements in order to render. You can even jump to the middle with scrollToIndex without excessive rendering.

We've also made some improvements with scheduling which should help with application responsiveness. Items at the edge of the render window are rendered infrequently and at a lower priority after any active gestures or animations or other interactions have completed.

Advanced Usage

Unlike ListView, all items in the render window are re-rendered any time any props change. Often this is fine because the windowing reduces the number of items to a constant number, but if your items are on the complex side, you should make sure to follow React best practices for performance and use React.PureComponent and/or shouldComponentUpdate as appropriate within your components to limit re-renders of the recursive subtree.

If you can calculate the height of your rows without rendering them, you can improve the user experience by providing the getItemLayout prop. This makes it much smoother to scroll to specific items with e.g. scrollToIndex, and will improve the scroll indicator UI because the height of the content can be determined without rendering it.

If you have an alternative data type, like an immutable list, <VirtualizedList> is the way to go. It takes a getItem prop that lets you return the item data for any given index and has looser flow typing.

There are also a bunch of parameters you can tweak if you have an unusual use case. For example, you can use windowSize to trade off memory usage vs. user experience, maxToRenderPerBatch to adjust fill rate vs. responsiveness, onEndReachedThreshold to control when scroll loading happens, and more.

Future Work

- + diff --git a/blog/2017/03/13/better-list-views/index.html b/blog/2017/03/13/better-list-views/index.html index 494af9bf2db..f2ae0540119 100644 --- a/blog/2017/03/13/better-list-views/index.html +++ b/blog/2017/03/13/better-list-views/index.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@
<SectionList
sections={[ // heterogeneous rendering between sections
{data: [...], key: ..., renderItem: ...},
{data: [...], key: ..., renderItem: ...},
{data: [...], key: ..., renderItem: ...},
]}
/>

<VirtualizedList>

The implementation behind the scenes with a more flexible API. Especially handy if your data is not in a plain array (e.g. an immutable list).

Features

Lists are used in many contexts, so we packed the new components full of features to handle the majority of use cases out of the box:

Some Caveats

Performance

Besides simplifying the API, the new list components also have significant performance enhancements, the main one being nearly constant memory usage for any number of rows. This is done by 'virtualizing' elements that are outside of the render window by completely unmounting them from the component hierarchy and reclaiming the JS memory from the react components, along with the native memory from the shadow tree and the UI views. This has a catch which is that internal component state will not be preserved, so make sure you track any important state outside of the components themselves, e.g. in Relay or Redux or Flux store.

Limiting the render window also reduces the amount of work that needs to be done by React and the native platform, e.g from view traversals. Even if you are rendering the last of a million elements, with these new lists there is no need to iterate through all those elements in order to render. You can even jump to the middle with scrollToIndex without excessive rendering.

We've also made some improvements with scheduling which should help with application responsiveness. Items at the edge of the render window are rendered infrequently and at a lower priority after any active gestures or animations or other interactions have completed.

Advanced Usage

Unlike ListView, all items in the render window are re-rendered any time any props change. Often this is fine because the windowing reduces the number of items to a constant number, but if your items are on the complex side, you should make sure to follow React best practices for performance and use React.PureComponent and/or shouldComponentUpdate as appropriate within your components to limit re-renders of the recursive subtree.

If you can calculate the height of your rows without rendering them, you can improve the user experience by providing the getItemLayout prop. This makes it much smoother to scroll to specific items with e.g. scrollToIndex, and will improve the scroll indicator UI because the height of the content can be determined without rendering it.

If you have an alternative data type, like an immutable list, <VirtualizedList> is the way to go. It takes a getItem prop that lets you return the item data for any given index and has looser flow typing.

There are also a bunch of parameters you can tweak if you have an unusual use case. For example, you can use windowSize to trade off memory usage vs. user experience, maxToRenderPerBatch to adjust fill rate vs. responsiveness, onEndReachedThreshold to control when scroll loading happens, and more.

Future Work

- + diff --git a/blog/2017/03/13/idx-the-existential-function.html b/blog/2017/03/13/idx-the-existential-function.html index eef78fd8656..ad9eeceb903 100644 --- a/blog/2017/03/13/idx-the-existential-function.html +++ b/blog/2017/03/13/idx-the-existential-function.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

idx: The Existential Function

Timothy Yung

Timothy Yung

Engineering Manager at Facebook

At Facebook, we often need to access deeply nested values in data structures fetched with GraphQL. On the way to accessing these deeply nested values, it is common for one or more intermediate fields to be nullable. These intermediate fields may be null for a variety of reasons, from failed privacy checks to the mere fact that null happens to be the most flexible way to represent non-fatal errors.

Unfortunately, accessing these deeply nested values is currently tedious and verbose.

props.user &&
props.user.friends &&
props.user.friends[0] &&
props.user.friends[0].friends;

There is an ECMAScript proposal to introduce the existential operator which will make this much more convenient. But until a time when that proposal is finalized, we want a solution that improves our quality of life, maintains existing language semantics, and encourages type safety with Flow.

We came up with an existential function we call idx.

idx(props, (_) => _.user.friends[0].friends);

The invocation in this code snippet behaves similarly to the boolean expression in the code snippet above, except with significantly less repetition. The idx function takes exactly two arguments:

  • Any value, typically an object or array into which you want to access a nested value.
  • A function that receives the first argument and accesses a nested value on it.

In theory, the idx function will try-catch errors that are the result of accessing properties on null or undefined. If such an error is caught, it will return either null or undefined. (And you can see how this might be implemented in idx.js.)

In practice, try-catching every nested property access is slow, and differentiating between specific kinds of TypeErrors is fragile. To deal with these shortcomings, we created a Babel plugin that transforms the above idx invocation into the following expression:

props.user == null
? props.user
: props.user.friends == null
? props.user.friends
: props.user.friends[0] == null
? props.user.friends[0]
: props.user.friends[0].friends;

Finally, we added a custom Flow type declaration for idx that allows the traversal in the second argument to be properly type-checked while permitting nested access on nullable properties.

The function, Babel plugin, and Flow declaration are now available on GitHub. They are used by installing the idx and babel-plugin-idx npm packages, and adding “idx” to the list of plugins in your .babelrc file.

- + diff --git a/blog/2017/03/13/idx-the-existential-function/index.html b/blog/2017/03/13/idx-the-existential-function/index.html index eef78fd8656..ad9eeceb903 100644 --- a/blog/2017/03/13/idx-the-existential-function/index.html +++ b/blog/2017/03/13/idx-the-existential-function/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

idx: The Existential Function

Timothy Yung

Timothy Yung

Engineering Manager at Facebook

At Facebook, we often need to access deeply nested values in data structures fetched with GraphQL. On the way to accessing these deeply nested values, it is common for one or more intermediate fields to be nullable. These intermediate fields may be null for a variety of reasons, from failed privacy checks to the mere fact that null happens to be the most flexible way to represent non-fatal errors.

Unfortunately, accessing these deeply nested values is currently tedious and verbose.

props.user &&
props.user.friends &&
props.user.friends[0] &&
props.user.friends[0].friends;

There is an ECMAScript proposal to introduce the existential operator which will make this much more convenient. But until a time when that proposal is finalized, we want a solution that improves our quality of life, maintains existing language semantics, and encourages type safety with Flow.

We came up with an existential function we call idx.

idx(props, (_) => _.user.friends[0].friends);

The invocation in this code snippet behaves similarly to the boolean expression in the code snippet above, except with significantly less repetition. The idx function takes exactly two arguments:

  • Any value, typically an object or array into which you want to access a nested value.
  • A function that receives the first argument and accesses a nested value on it.

In theory, the idx function will try-catch errors that are the result of accessing properties on null or undefined. If such an error is caught, it will return either null or undefined. (And you can see how this might be implemented in idx.js.)

In practice, try-catching every nested property access is slow, and differentiating between specific kinds of TypeErrors is fragile. To deal with these shortcomings, we created a Babel plugin that transforms the above idx invocation into the following expression:

props.user == null
? props.user
: props.user.friends == null
? props.user.friends
: props.user.friends[0] == null
? props.user.friends[0]
: props.user.friends[0].friends;

Finally, we added a custom Flow type declaration for idx that allows the traversal in the second argument to be properly type-checked while permitting nested access on nullable properties.

The function, Babel plugin, and Flow declaration are now available on GitHub. They are used by installing the idx and babel-plugin-idx npm packages, and adding “idx” to the list of plugins in your .babelrc file.

- + diff --git a/blog/2017/03/13/introducing-create-react-native-app.html b/blog/2017/03/13/introducing-create-react-native-app.html index aa28da98e26..54433cdcf0a 100644 --- a/blog/2017/03/13/introducing-create-react-native-app.html +++ b/blog/2017/03/13/introducing-create-react-native-app.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Introducing Create React Native App

Adam Perry

Adam Perry

Software Engineer at Expo

Today we’re announcing Create React Native App: a new tool that makes it significantly easier to get started with a React Native project! It’s heavily inspired by the design of Create React App and is the product of a collaboration between Facebook and Expo (formerly Exponent).

Many developers struggle with installing and configuring React Native’s current native build dependencies, especially for Android. With Create React Native App, there’s no need to use Xcode or Android Studio, and you can develop for your iOS device using Linux or Windows. This is accomplished using the Expo app, which loads and runs CRNA projects written in pure JavaScript without compiling any native code.

Try creating a new project (replace with suitable yarn commands if you have it installed):

$ npm i -g create-react-native-app
$ create-react-native-app my-project
$ cd my-project
$ npm start

This will start the React Native packager and print a QR code. Open it in the Expo app to load your JavaScript. Calls to console.log are forwarded to your terminal. You can make use of any standard React Native APIs as well as the Expo SDK.

What about native code?

Many React Native projects have Java or Objective-C/Swift dependencies that need to be compiled. The Expo app does include APIs for camera, video, contacts, and more, and bundles popular libraries like Airbnb’s react-native-maps, or Facebook authentication. However if you need a native code dependency that Expo doesn’t bundle then you’ll probably need to have your own build configuration for it. Just like Create React App, “ejecting” is supported by CRNA.

You can run npm run eject to get a project very similar to what react-native init would generate. At that point you’ll need Xcode and/or Android Studio just as you would if you started with react-native init , adding libraries with react-native link will work, and you’ll have full control over the native code compilation process.

Questions? Feedback?

Create React Native App is now stable enough for general use, which means we’re very eager to hear about your experience using it! You can find me on Twitter or open an issue on the GitHub repository. Pull requests are very welcome!

- + diff --git a/blog/2017/03/13/introducing-create-react-native-app/index.html b/blog/2017/03/13/introducing-create-react-native-app/index.html index aa28da98e26..54433cdcf0a 100644 --- a/blog/2017/03/13/introducing-create-react-native-app/index.html +++ b/blog/2017/03/13/introducing-create-react-native-app/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Introducing Create React Native App

Adam Perry

Adam Perry

Software Engineer at Expo

Today we’re announcing Create React Native App: a new tool that makes it significantly easier to get started with a React Native project! It’s heavily inspired by the design of Create React App and is the product of a collaboration between Facebook and Expo (formerly Exponent).

Many developers struggle with installing and configuring React Native’s current native build dependencies, especially for Android. With Create React Native App, there’s no need to use Xcode or Android Studio, and you can develop for your iOS device using Linux or Windows. This is accomplished using the Expo app, which loads and runs CRNA projects written in pure JavaScript without compiling any native code.

Try creating a new project (replace with suitable yarn commands if you have it installed):

$ npm i -g create-react-native-app
$ create-react-native-app my-project
$ cd my-project
$ npm start

This will start the React Native packager and print a QR code. Open it in the Expo app to load your JavaScript. Calls to console.log are forwarded to your terminal. You can make use of any standard React Native APIs as well as the Expo SDK.

What about native code?

Many React Native projects have Java or Objective-C/Swift dependencies that need to be compiled. The Expo app does include APIs for camera, video, contacts, and more, and bundles popular libraries like Airbnb’s react-native-maps, or Facebook authentication. However if you need a native code dependency that Expo doesn’t bundle then you’ll probably need to have your own build configuration for it. Just like Create React App, “ejecting” is supported by CRNA.

You can run npm run eject to get a project very similar to what react-native init would generate. At that point you’ll need Xcode and/or Android Studio just as you would if you started with react-native init , adding libraries with react-native link will work, and you’ll have full control over the native code compilation process.

Questions? Feedback?

Create React Native App is now stable enough for general use, which means we’re very eager to hear about your experience using it! You can find me on Twitter or open an issue on the GitHub repository. Pull requests are very welcome!

- + diff --git a/blog/2017/06/21/react-native-monthly-1.html b/blog/2017/06/21/react-native-monthly-1.html index 52776905bdf..a2cb813be26 100644 --- a/blog/2017/06/21/react-native-monthly-1.html +++ b/blog/2017/06/21/react-native-monthly-1.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native Monthly #1

Tomislav Tenodi

Tomislav Tenodi

Product Manager at Shoutem

At Shoutem, we've been fortunate enough to work with React Native from its very beginnings. We decided we wanted to be part of the amazing community from day one. Soon enough, we realized it's almost impossible to keep up with the pace the community was growing and improving. That's why we decided to organize a monthly meeting where all major React Native contributors can briefly present what their efforts and plans are.

Monthly meetings

We had our first session of the monthly meeting on June 14, 2017. The mission for React Native Monthly is simple and straightforward: improve the React Native community. Presenting teams' efforts eases collaboration between teams done offline.

Teams

On the first meeting, we had 8 teams join us:

We hope to have more core contributors join the upcoming sessions!

Notes

As teams' plans might be of interest to a broader audience, we'll be sharing them here, on the React Native blog. So, here they are:

Airbnb

  • Plans to add some A11y (accessibility) APIs to View and the AccessibilityInfo native module.
  • Will be investigating adding some APIs to native modules on Android to allow for specifying threads for them to run on.
  • Have been investigating potential initialization performance improvements.
  • Have been investigating some more sophisticated bundling strategies to use on top of "unbundle".

Callstack

  • Looking into improving the release process by using Detox for E2E testing. Pull request should land soon.
  • Blob pull request they have been working on has been merged, subsequent pull requests coming up.
  • Increasing Haul adoption across internal projects to see how it performs compared to Metro Bundler. Working on better multi-threaded performance with the Webpack team.
  • Internally, they have implemented a better infrastructure to manage open source projects. Plans to be getting more stuff out in upcoming weeks.
  • The React Native Europe conference is coming along, nothing interesting yet, but y'all invited!
  • Stepped back from react-navigation for a while to investigate alternatives (especially native navigations).

Expo

Facebook

  • React Native's packager is now Metro Bundler, in an independent repo. The Metro Bundler team in London is excited to address the needs of the community, improve modularity for additional use-cases beyond React Native, and increase responsiveness on issues and PRs.
  • In the coming months, the React Native team will work on refining the APIs of primitive components. Expect improvements in layout quirks, accessibility, and flow typing.
  • The React Native team also plans on improving core modularity this year, by refactoring to fully support 3rd party platforms such as Windows and macOS.

GeekyAnts

  • The team is working on a UI/UX design app (codename: Builder) which directly works with .js files. Right now, it supports only React Native. It’s similar to Adobe XD and Sketch.
  • The team is working hard so that you can load up an existing React Native app in the editor, make changes (visually, as a designer) and save the changes directly to the JS file.
  • Folks are trying to bridge the gap between Designers and Developers and bring them on the same repo.
  • Also, NativeBase recently reached 5,000 GitHub stars.

Microsoft

  • CodePush has now been integrated into Mobile Center. This is the first step in providing a much more integrated experience with distribution, analytics and other services. See their announcement here.
  • VSCode has a bug with debugging, they are working on fixing that right now and will have a new build.
  • Investigating Detox for Integration testing, looking at JSC Context to get variables alongside crash reports.

Shoutem

  • Making it easier to work on Shoutem apps with tools from the React Native community. You will be able to use all the React Native commands to run the apps created on Shoutem.
  • Investigating profiling tools for React Native. They had a lot of problems setting it up and they will write some of the insights they discovered along the way.
  • Shoutem is working on making it easier to integrate React Native with existing native apps. They will document the concept that they developed internally in the company, in order to get the feedback from the community.

Wix

  • Working internally to adopt Detox to move significant parts of the Wix app to "zero manual QA". As a result, Detox is being used heavily in a production setting by dozens of developers and maturing rapidly.
  • Working to add support to the Metro Bundler for overriding any file extension during the build. Instead of just "ios" and "android", it would support any custom extension like "e2e" or "detox". Plans to use this for E2E mocking. There's already a library out called react-native-repackager, now working on a PR.
  • Investigating automation of performance tests. This is a new repo called DetoxInstruments. You can take a look, it's being developed open source.
  • Working with a contributor from KPN on Detox for Android and supporting real devices.
  • Thinking about "Detox as a platform" to allow building other tools that need to automate the simulator/device. An example is Storybook for React Native or Ram's idea for integration testing.

Next session

Meetings will be held every four weeks. The next session is scheduled for July 12, 2017. As we just started with this meeting, we'd like to know how do these notes benefit the React Native community. Feel free to ping me on Twitter if you have any suggestion on what we should cover in the following sessions, or how we should improve the output of the meeting.

- + diff --git a/blog/2017/06/21/react-native-monthly-1/index.html b/blog/2017/06/21/react-native-monthly-1/index.html index 52776905bdf..a2cb813be26 100644 --- a/blog/2017/06/21/react-native-monthly-1/index.html +++ b/blog/2017/06/21/react-native-monthly-1/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native Monthly #1

Tomislav Tenodi

Tomislav Tenodi

Product Manager at Shoutem

At Shoutem, we've been fortunate enough to work with React Native from its very beginnings. We decided we wanted to be part of the amazing community from day one. Soon enough, we realized it's almost impossible to keep up with the pace the community was growing and improving. That's why we decided to organize a monthly meeting where all major React Native contributors can briefly present what their efforts and plans are.

Monthly meetings

We had our first session of the monthly meeting on June 14, 2017. The mission for React Native Monthly is simple and straightforward: improve the React Native community. Presenting teams' efforts eases collaboration between teams done offline.

Teams

On the first meeting, we had 8 teams join us:

We hope to have more core contributors join the upcoming sessions!

Notes

As teams' plans might be of interest to a broader audience, we'll be sharing them here, on the React Native blog. So, here they are:

Airbnb

  • Plans to add some A11y (accessibility) APIs to View and the AccessibilityInfo native module.
  • Will be investigating adding some APIs to native modules on Android to allow for specifying threads for them to run on.
  • Have been investigating potential initialization performance improvements.
  • Have been investigating some more sophisticated bundling strategies to use on top of "unbundle".

Callstack

  • Looking into improving the release process by using Detox for E2E testing. Pull request should land soon.
  • Blob pull request they have been working on has been merged, subsequent pull requests coming up.
  • Increasing Haul adoption across internal projects to see how it performs compared to Metro Bundler. Working on better multi-threaded performance with the Webpack team.
  • Internally, they have implemented a better infrastructure to manage open source projects. Plans to be getting more stuff out in upcoming weeks.
  • The React Native Europe conference is coming along, nothing interesting yet, but y'all invited!
  • Stepped back from react-navigation for a while to investigate alternatives (especially native navigations).

Expo

Facebook

  • React Native's packager is now Metro Bundler, in an independent repo. The Metro Bundler team in London is excited to address the needs of the community, improve modularity for additional use-cases beyond React Native, and increase responsiveness on issues and PRs.
  • In the coming months, the React Native team will work on refining the APIs of primitive components. Expect improvements in layout quirks, accessibility, and flow typing.
  • The React Native team also plans on improving core modularity this year, by refactoring to fully support 3rd party platforms such as Windows and macOS.

GeekyAnts

  • The team is working on a UI/UX design app (codename: Builder) which directly works with .js files. Right now, it supports only React Native. It’s similar to Adobe XD and Sketch.
  • The team is working hard so that you can load up an existing React Native app in the editor, make changes (visually, as a designer) and save the changes directly to the JS file.
  • Folks are trying to bridge the gap between Designers and Developers and bring them on the same repo.
  • Also, NativeBase recently reached 5,000 GitHub stars.

Microsoft

  • CodePush has now been integrated into Mobile Center. This is the first step in providing a much more integrated experience with distribution, analytics and other services. See their announcement here.
  • VSCode has a bug with debugging, they are working on fixing that right now and will have a new build.
  • Investigating Detox for Integration testing, looking at JSC Context to get variables alongside crash reports.

Shoutem

  • Making it easier to work on Shoutem apps with tools from the React Native community. You will be able to use all the React Native commands to run the apps created on Shoutem.
  • Investigating profiling tools for React Native. They had a lot of problems setting it up and they will write some of the insights they discovered along the way.
  • Shoutem is working on making it easier to integrate React Native with existing native apps. They will document the concept that they developed internally in the company, in order to get the feedback from the community.

Wix

  • Working internally to adopt Detox to move significant parts of the Wix app to "zero manual QA". As a result, Detox is being used heavily in a production setting by dozens of developers and maturing rapidly.
  • Working to add support to the Metro Bundler for overriding any file extension during the build. Instead of just "ios" and "android", it would support any custom extension like "e2e" or "detox". Plans to use this for E2E mocking. There's already a library out called react-native-repackager, now working on a PR.
  • Investigating automation of performance tests. This is a new repo called DetoxInstruments. You can take a look, it's being developed open source.
  • Working with a contributor from KPN on Detox for Android and supporting real devices.
  • Thinking about "Detox as a platform" to allow building other tools that need to automate the simulator/device. An example is Storybook for React Native or Ram's idea for integration testing.

Next session

Meetings will be held every four weeks. The next session is scheduled for July 12, 2017. As we just started with this meeting, we'd like to know how do these notes benefit the React Native community. Feel free to ping me on Twitter if you have any suggestion on what we should cover in the following sessions, or how we should improve the output of the meeting.

- + diff --git a/blog/2017/07/28/react-native-monthly-2.html b/blog/2017/07/28/react-native-monthly-2.html index 86bea6883aa..77ca9341022 100644 --- a/blog/2017/07/28/react-native-monthly-2.html +++ b/blog/2017/07/28/react-native-monthly-2.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native Monthly #2

Tomislav Tenodi

Tomislav Tenodi

Product Manager at Shoutem

The React Native monthly meeting continues! On this session, we were joined by Infinite Red, great minds behind Chain React, the React Native Conference. As most of the people here were presenting talks at Chain React, we pushed the meeting to a week later. Talks from the conference have been posted online and I encourage you to check them out. So, let's see what our teams are up to.

Teams

On this second meeting, we had 9 teams join us:

Notes

Here are the notes from each team:

Airbnb

Callstack

  • Mike Grabowski has been managing React Native's monthly releases as always, including a few betas that were pushed out. In particular, working on getting a v0.43.5 build published to npm since it unblocks Windows users!
  • Slow but consistent work is happening on Haul. There is a pull request that adds HMR, and other improvements have shipped. Recently got a few industry leaders to adopt it. Possibly planning to start a full-time paid work in that area.
  • Michał Pierzchała from the Jest team has joined us at Callstack this month. He will help maintain Haul and possibly work on Metro Bundler and Jest.
  • Satyajit Sahoo is now with us, yay!
  • Got a bunch of cool stuff coming up from our OSS department. In particular, working on bringing Material Palette API to React Native. Planning to finally release our native iOS kit which is aimed to provide 1:1 look & feel of native components.

Expo

  • Recently launched Native Directory to help with discoverability and evaluation of libraries in React Native ecosystem. The problem: lots of libraries, hard to test, need to manually apply heuristics and not immediately obvious which ones are just the best ones that you should use. It's also hard to know if something is compatible with CRNA/Expo. So Native Directory tries to solve these problems. Check it out and add your library to it. The list of libraries is in here. This is just our first pass of it, and we want this to be owned and run by the community, not just Expo folks. So please pitch in if you think this is valuable and want to make it better!
  • Added initial support for installing npm packages in Snack with Expo SDK 19. Let us know if you run into any issues with it, we are still working through some bugs. Along with Native Directory, this should make it easy to test libraries that have only JS dependencies, or dependencies included in Expo SDK. Try it out:
  • Released Expo SDK19 with a bunch of improvements across the board, and we're now using the updated Android JSC.
  • Working on a guide in docs with Alexander Kotliarskyi with a list of tips on how to improve the user experience of your app. Please join in and add to the list or help write some of it!
  • Continuing to work on: audio/video, camera, gestures (with Software Mansion, react-native-gesture-handler), GL camera integration and hoping to land some of these for the first time in SDK20 (August), and significant improvements to others by then as well. We're just getting started on building infrastructure into the Expo client for background work (geolocation, audio, handling notifications, etc.).
  • Adam Miskiewicz has made some nice progress on imitating the transitions from UINavigationController in react-navigation. Check out an earlier version of it in his tweet - release coming with it soon. Also check out MaskedViewIOS which he upstreamed. If you have the skills and desire to implement MaskedView for Android that would be awesome!

Facebook

  • Facebook is internally exploring being able to embed native ComponentKit and Litho components inside of React Native.
  • Contributions to React Native are very welcome! If you are wondering how you can contribute, the "How to Contribute" guide describes our development process and lays out the steps to send your first pull request. There are other ways to contribute that do not require writing code, such as by triaging issues or updating the docs.
    • At the time of writing, React Native has 635 open issues and 249 open pull requests. This is overwhelming for our maintainers, and when things get fixed internally, it is difficult to ensure the relevant tasks are updated.
    • We are unsure what the best approach is to handle this while keeping the community satisfied. Some (but not all!) options include closing stale issues, giving significantly more people permissions to manage issues, and automatically closing issues that do not follow the issue template. We wrote a "What to Expect from Maintainers" guide to set expectations and avoid surprises. If you have ideas on how we can make this experience better for maintainers as well as ensuring people opening issues and pull requests feel heard and valued, please let us know!

GeekyAnts

  • We demoed the Designer Tool which works with React Native files on Chain React. Many attendees signed up for the waiting list.
  • We are also looking at other cross-platform solutions like Google Flutter (a major comparison coming along), Kotlin Native, and Apache Weex to understand the architectural differences and what we can learn from them to improve the overall performance of React Native.
  • Switched to react-navigation for most of our apps, which has improved the overall performance.
  • Also, announced NativeBase Market - A marketplace for React Native components and apps (for and by the developers).

Infinite Red

Microsoft

  • CodePush has now been integrated into Mobile Center. Existing users will have no change in their workflow.
    • Some people have reported an issue with duplicate apps - they already had an app on Mobile Center. We are working on resolving them, but if you have two apps, let us know, and we can merge them for you.
  • Mobile Center now supports Push Notifications for CodePush. We also showed how a combination of Notifications and CodePush could be used for A/B testing apps - something unique to the ReactNative architecture.
  • VSCode has a known debugging issue with ReactNative - the next release of the extension in a couple of days will be fixing the issue.
  • Since there are many other teams also working on React Native inside Microsoft, we will work on getting better representation from all the groups for the next meeting.

Shoutem

  • Finished the process of making the React Native development easier on Shoutem. You can use all the standard react-native commands when developing apps on Shoutem.
  • We did a lot of work trying to figure out how to best approach the profiling on React Native. A big chunk of documentation is outdated, and we'll do our best to create a pull request on the official docs or at least write some of our conclusions in a blog post.
  • Switching our navigation solution to react-navigation, so we might have some feedback soon.
  • We released a new HTML component in our toolkit which transforms the raw HTML to the React Native components tree.

Wix

  • We started working on a pull request to Metro Bundler with react-native-repackager capabilities. We updated react-native-repackager to support RN 44 (which we use in production). We are using it for our mocking infrastructure for detox.
  • We have been covering the Wix app in detox tests for the last three weeks. It's an amazing learning experience of how to reduce manual QA in an app of this scale (over 40 engineers). We have resolved several issues with detox as a result, a new version was just published. I am happy to report that we are living up to the "zero flakiness policy" and the tests are passing consistently so far.
  • Detox for Android is moving forward nicely. We are getting significant help from the community. We are expecting an initial version in about two weeks.
  • DetoxInstruments, our performance testing tool, is getting a little bigger than we originally intended. We are now planning to turn it into a standalone tool that will not be tightly coupled to detox. It will allow investigating the performance of iOS apps in general. It will also be integrated with detox so we can run automated tests on performance metrics.

Next session

The next session is scheduled for August 16, 2017. As this was only our second meeting, we'd like to know how do these notes benefit the React Native community. Feel free to ping me on Twitter if you have any suggestion on how we should improve the output of the meeting.

- + diff --git a/blog/2017/07/28/react-native-monthly-2/index.html b/blog/2017/07/28/react-native-monthly-2/index.html index 86bea6883aa..77ca9341022 100644 --- a/blog/2017/07/28/react-native-monthly-2/index.html +++ b/blog/2017/07/28/react-native-monthly-2/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native Monthly #2

Tomislav Tenodi

Tomislav Tenodi

Product Manager at Shoutem

The React Native monthly meeting continues! On this session, we were joined by Infinite Red, great minds behind Chain React, the React Native Conference. As most of the people here were presenting talks at Chain React, we pushed the meeting to a week later. Talks from the conference have been posted online and I encourage you to check them out. So, let's see what our teams are up to.

Teams

On this second meeting, we had 9 teams join us:

Notes

Here are the notes from each team:

Airbnb

Callstack

  • Mike Grabowski has been managing React Native's monthly releases as always, including a few betas that were pushed out. In particular, working on getting a v0.43.5 build published to npm since it unblocks Windows users!
  • Slow but consistent work is happening on Haul. There is a pull request that adds HMR, and other improvements have shipped. Recently got a few industry leaders to adopt it. Possibly planning to start a full-time paid work in that area.
  • Michał Pierzchała from the Jest team has joined us at Callstack this month. He will help maintain Haul and possibly work on Metro Bundler and Jest.
  • Satyajit Sahoo is now with us, yay!
  • Got a bunch of cool stuff coming up from our OSS department. In particular, working on bringing Material Palette API to React Native. Planning to finally release our native iOS kit which is aimed to provide 1:1 look & feel of native components.

Expo

  • Recently launched Native Directory to help with discoverability and evaluation of libraries in React Native ecosystem. The problem: lots of libraries, hard to test, need to manually apply heuristics and not immediately obvious which ones are just the best ones that you should use. It's also hard to know if something is compatible with CRNA/Expo. So Native Directory tries to solve these problems. Check it out and add your library to it. The list of libraries is in here. This is just our first pass of it, and we want this to be owned and run by the community, not just Expo folks. So please pitch in if you think this is valuable and want to make it better!
  • Added initial support for installing npm packages in Snack with Expo SDK 19. Let us know if you run into any issues with it, we are still working through some bugs. Along with Native Directory, this should make it easy to test libraries that have only JS dependencies, or dependencies included in Expo SDK. Try it out:
  • Released Expo SDK19 with a bunch of improvements across the board, and we're now using the updated Android JSC.
  • Working on a guide in docs with Alexander Kotliarskyi with a list of tips on how to improve the user experience of your app. Please join in and add to the list or help write some of it!
  • Continuing to work on: audio/video, camera, gestures (with Software Mansion, react-native-gesture-handler), GL camera integration and hoping to land some of these for the first time in SDK20 (August), and significant improvements to others by then as well. We're just getting started on building infrastructure into the Expo client for background work (geolocation, audio, handling notifications, etc.).
  • Adam Miskiewicz has made some nice progress on imitating the transitions from UINavigationController in react-navigation. Check out an earlier version of it in his tweet - release coming with it soon. Also check out MaskedViewIOS which he upstreamed. If you have the skills and desire to implement MaskedView for Android that would be awesome!

Facebook

  • Facebook is internally exploring being able to embed native ComponentKit and Litho components inside of React Native.
  • Contributions to React Native are very welcome! If you are wondering how you can contribute, the "How to Contribute" guide describes our development process and lays out the steps to send your first pull request. There are other ways to contribute that do not require writing code, such as by triaging issues or updating the docs.
    • At the time of writing, React Native has 635 open issues and 249 open pull requests. This is overwhelming for our maintainers, and when things get fixed internally, it is difficult to ensure the relevant tasks are updated.
    • We are unsure what the best approach is to handle this while keeping the community satisfied. Some (but not all!) options include closing stale issues, giving significantly more people permissions to manage issues, and automatically closing issues that do not follow the issue template. We wrote a "What to Expect from Maintainers" guide to set expectations and avoid surprises. If you have ideas on how we can make this experience better for maintainers as well as ensuring people opening issues and pull requests feel heard and valued, please let us know!

GeekyAnts

  • We demoed the Designer Tool which works with React Native files on Chain React. Many attendees signed up for the waiting list.
  • We are also looking at other cross-platform solutions like Google Flutter (a major comparison coming along), Kotlin Native, and Apache Weex to understand the architectural differences and what we can learn from them to improve the overall performance of React Native.
  • Switched to react-navigation for most of our apps, which has improved the overall performance.
  • Also, announced NativeBase Market - A marketplace for React Native components and apps (for and by the developers).

Infinite Red

Microsoft

  • CodePush has now been integrated into Mobile Center. Existing users will have no change in their workflow.
    • Some people have reported an issue with duplicate apps - they already had an app on Mobile Center. We are working on resolving them, but if you have two apps, let us know, and we can merge them for you.
  • Mobile Center now supports Push Notifications for CodePush. We also showed how a combination of Notifications and CodePush could be used for A/B testing apps - something unique to the ReactNative architecture.
  • VSCode has a known debugging issue with ReactNative - the next release of the extension in a couple of days will be fixing the issue.
  • Since there are many other teams also working on React Native inside Microsoft, we will work on getting better representation from all the groups for the next meeting.

Shoutem

  • Finished the process of making the React Native development easier on Shoutem. You can use all the standard react-native commands when developing apps on Shoutem.
  • We did a lot of work trying to figure out how to best approach the profiling on React Native. A big chunk of documentation is outdated, and we'll do our best to create a pull request on the official docs or at least write some of our conclusions in a blog post.
  • Switching our navigation solution to react-navigation, so we might have some feedback soon.
  • We released a new HTML component in our toolkit which transforms the raw HTML to the React Native components tree.

Wix

  • We started working on a pull request to Metro Bundler with react-native-repackager capabilities. We updated react-native-repackager to support RN 44 (which we use in production). We are using it for our mocking infrastructure for detox.
  • We have been covering the Wix app in detox tests for the last three weeks. It's an amazing learning experience of how to reduce manual QA in an app of this scale (over 40 engineers). We have resolved several issues with detox as a result, a new version was just published. I am happy to report that we are living up to the "zero flakiness policy" and the tests are passing consistently so far.
  • Detox for Android is moving forward nicely. We are getting significant help from the community. We are expecting an initial version in about two weeks.
  • DetoxInstruments, our performance testing tool, is getting a little bigger than we originally intended. We are now planning to turn it into a standalone tool that will not be tightly coupled to detox. It will allow investigating the performance of iOS apps in general. It will also be integrated with detox so we can run automated tests on performance metrics.

Next session

The next session is scheduled for August 16, 2017. As this was only our second meeting, we'd like to know how do these notes benefit the React Native community. Feel free to ping me on Twitter if you have any suggestion on how we should improve the output of the meeting.

- + diff --git a/blog/2017/08/07/react-native-performance-in-marketplace.html b/blog/2017/08/07/react-native-performance-in-marketplace.html index 939dc9e60a9..40a5a650eb7 100644 --- a/blog/2017/08/07/react-native-performance-in-marketplace.html +++ b/blog/2017/08/07/react-native-performance-in-marketplace.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native Performance in Marketplace

Aaron Chiu

Software Engineer at Facebook

React Native is used in multiple places across multiple apps in the Facebook family including a top level tab in the main Facebook apps. Our focus for this post is a highly visible product, Marketplace. It is available in a dozen or so countries and enables users to discover products and services provided by other users.

In the first half of 2017, through the joint effort of the Relay Team, the Marketplace team, the Mobile JS Platform team, and the React Native team, we cut Marketplace Time to Interaction (TTI) in half for Android Year Class 2010-11 devices. Facebook has historically considered these devices as low-end Android devices, and they have the slowest TTIs on any platform or device type.

A typical React Native startup looks something like this:

Disclaimer: ratios aren't representative and will vary depending on how React Native is configured and used.

We first initialize the React Native core (aka the “Bridge”) before running the product specific JavaScript which determines what native views React Native will render in the Native Processing Time.

A different approach

One of the earlier mistakes that we made was to let Systrace and CTScan drive our performance efforts. These tools helped us find a lot of low-hanging fruit in 2016, but we discovered that both Systrace and CTScan are not representative of production scenarios and cannot emulate what happens in the wild. Ratios of time spent in the breakdowns are often incorrect and, wildly off-base at times. At the extreme, some things that we expected to take a few milliseconds actually take hundreds or thousands of milliseconds. That said, CTScan is useful and we've found it catches a third of regressions before they hit production.

On Android, we attribute the shortcomings of these tools to the fact that 1) React Native is a multithreaded framework, 2) Marketplace is co-located with a multitude of complex views such as Newsfeed and other top-level tabs, and 3) computation times vary wildly. Thus, this half, we let production measurements and breakdowns drive almost all of our decision making and prioritization.

Down the path of production instrumentation

Instrumenting production may sound simple on the surface, but it turned out to be quite a complex process. It took multiple iteration cycles of 2-3 weeks each; due to the latency of landing a commit in master, to pushing the app to the Play Store, to gathering sufficient production samples to have confidence in our work. Each iteration cycle involved discovering if our breakdowns were accurate, if they had the right level of granularity, and if they properly added up to the whole time span. We could not rely on alpha and beta releases because they are not representative of the general population. In essence, we very tediously built a very accurate production trace based on the aggregate of millions of samples.

One of the reasons we meticulously verified that every millisecond in breakdowns properly added up to their parent metrics was that we realized early on there were gaps in our instrumentation. It turned out that our initial breakdowns did not account for stalls caused by thread jumps. Thread jumps themselves aren't expensive, but thread jumps to busy threads already doing work are very expensive. We eventually reproduced these blockages locally by sprinkling Thread.sleep() calls at the right moments, and we managed to fix them by:

  1. removing our dependency on AsyncTask,
  2. undoing the forced initialization of ReactContext and NativeModules on the UI thread, and
  3. removing the dependency on measuring the ReactRootView at initialization time.

Together, removing these thread blockage issues reduced the startup time by over 25%.

Production metrics also challenged some of our prior assumptions. For example, we used to pre-load many JavaScript modules on the startup path under the assumption that co-locating modules in one bundle would reduce their initialization cost. However, the cost of pre-loading and co-locating these modules far outweighed the benefits. By re-configuring our inline require blacklists and removing JavaScript modules from the startup path, we were able to avoid loading unnecessary modules such as Relay Classic (when only Relay Modern was necessary). Today, our RUN_JS_BUNDLE breakdown is over 75% faster.

We also found wins by investigating product-specific native modules. For example, by lazily injecting a native module's dependencies, we reduced that native module's cost by 98%. By removing the contention of Marketplace startup with other products, we reduced startup by an equivalent interval.

The best part is that many of these improvements are broadly applicable to all screens built with React Native.

Conclusion

People assume that React Native startup performance problems are caused by JavaScript being slow or exceedingly high network times. While speeding up things like JavaScript would bring down TTI by a non-trivial sum, each of these contribute a much smaller percentage of TTI than was previously believed.

The lesson so far has been to measure, measure, measure! Some wins come from moving run-time costs to build time, such as Relay Modern and Lazy NativeModules. Other wins come from avoiding work by being smarter about parallelizing code or removing dead code. And some wins come from large architectural changes to React Native, such as cleaning up thread blockages. There is no grand solution to performance, and longer-term performance wins will come from incremental instrumentation and improvements. Do not let cognitive bias influence your decisions. Instead, carefully gather and interpret production data to guide future work.

Future plans

In the long term, we want Marketplace TTI to be comparable to similar products built with Native, and, in general, have React Native performance on par with native performance. Further more, although this half we drastically reduced the bridge startup cost by about 80%, we plan to bring the cost of the React Native bridge close to zero via projects like Prepack and more build time processing.

- + diff --git a/blog/2017/08/07/react-native-performance-in-marketplace/index.html b/blog/2017/08/07/react-native-performance-in-marketplace/index.html index 939dc9e60a9..40a5a650eb7 100644 --- a/blog/2017/08/07/react-native-performance-in-marketplace/index.html +++ b/blog/2017/08/07/react-native-performance-in-marketplace/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native Performance in Marketplace

Aaron Chiu

Software Engineer at Facebook

React Native is used in multiple places across multiple apps in the Facebook family including a top level tab in the main Facebook apps. Our focus for this post is a highly visible product, Marketplace. It is available in a dozen or so countries and enables users to discover products and services provided by other users.

In the first half of 2017, through the joint effort of the Relay Team, the Marketplace team, the Mobile JS Platform team, and the React Native team, we cut Marketplace Time to Interaction (TTI) in half for Android Year Class 2010-11 devices. Facebook has historically considered these devices as low-end Android devices, and they have the slowest TTIs on any platform or device type.

A typical React Native startup looks something like this:

Disclaimer: ratios aren't representative and will vary depending on how React Native is configured and used.

We first initialize the React Native core (aka the “Bridge”) before running the product specific JavaScript which determines what native views React Native will render in the Native Processing Time.

A different approach

One of the earlier mistakes that we made was to let Systrace and CTScan drive our performance efforts. These tools helped us find a lot of low-hanging fruit in 2016, but we discovered that both Systrace and CTScan are not representative of production scenarios and cannot emulate what happens in the wild. Ratios of time spent in the breakdowns are often incorrect and, wildly off-base at times. At the extreme, some things that we expected to take a few milliseconds actually take hundreds or thousands of milliseconds. That said, CTScan is useful and we've found it catches a third of regressions before they hit production.

On Android, we attribute the shortcomings of these tools to the fact that 1) React Native is a multithreaded framework, 2) Marketplace is co-located with a multitude of complex views such as Newsfeed and other top-level tabs, and 3) computation times vary wildly. Thus, this half, we let production measurements and breakdowns drive almost all of our decision making and prioritization.

Down the path of production instrumentation

Instrumenting production may sound simple on the surface, but it turned out to be quite a complex process. It took multiple iteration cycles of 2-3 weeks each; due to the latency of landing a commit in master, to pushing the app to the Play Store, to gathering sufficient production samples to have confidence in our work. Each iteration cycle involved discovering if our breakdowns were accurate, if they had the right level of granularity, and if they properly added up to the whole time span. We could not rely on alpha and beta releases because they are not representative of the general population. In essence, we very tediously built a very accurate production trace based on the aggregate of millions of samples.

One of the reasons we meticulously verified that every millisecond in breakdowns properly added up to their parent metrics was that we realized early on there were gaps in our instrumentation. It turned out that our initial breakdowns did not account for stalls caused by thread jumps. Thread jumps themselves aren't expensive, but thread jumps to busy threads already doing work are very expensive. We eventually reproduced these blockages locally by sprinkling Thread.sleep() calls at the right moments, and we managed to fix them by:

  1. removing our dependency on AsyncTask,
  2. undoing the forced initialization of ReactContext and NativeModules on the UI thread, and
  3. removing the dependency on measuring the ReactRootView at initialization time.

Together, removing these thread blockage issues reduced the startup time by over 25%.

Production metrics also challenged some of our prior assumptions. For example, we used to pre-load many JavaScript modules on the startup path under the assumption that co-locating modules in one bundle would reduce their initialization cost. However, the cost of pre-loading and co-locating these modules far outweighed the benefits. By re-configuring our inline require blacklists and removing JavaScript modules from the startup path, we were able to avoid loading unnecessary modules such as Relay Classic (when only Relay Modern was necessary). Today, our RUN_JS_BUNDLE breakdown is over 75% faster.

We also found wins by investigating product-specific native modules. For example, by lazily injecting a native module's dependencies, we reduced that native module's cost by 98%. By removing the contention of Marketplace startup with other products, we reduced startup by an equivalent interval.

The best part is that many of these improvements are broadly applicable to all screens built with React Native.

Conclusion

People assume that React Native startup performance problems are caused by JavaScript being slow or exceedingly high network times. While speeding up things like JavaScript would bring down TTI by a non-trivial sum, each of these contribute a much smaller percentage of TTI than was previously believed.

The lesson so far has been to measure, measure, measure! Some wins come from moving run-time costs to build time, such as Relay Modern and Lazy NativeModules. Other wins come from avoiding work by being smarter about parallelizing code or removing dead code. And some wins come from large architectural changes to React Native, such as cleaning up thread blockages. There is no grand solution to performance, and longer-term performance wins will come from incremental instrumentation and improvements. Do not let cognitive bias influence your decisions. Instead, carefully gather and interpret production data to guide future work.

Future plans

In the long term, we want Marketplace TTI to be comparable to similar products built with Native, and, in general, have React Native performance on par with native performance. Further more, although this half we drastically reduced the bridge startup cost by about 80%, we plan to bring the cost of the React Native bridge close to zero via projects like Prepack and more build time processing.

- + diff --git a/blog/2017/08/30/react-native-monthly-3.html b/blog/2017/08/30/react-native-monthly-3.html index bb6b8e1f52e..2b8562b2ada 100644 --- a/blog/2017/08/30/react-native-monthly-3.html +++ b/blog/2017/08/30/react-native-monthly-3.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native Monthly #3

Mike Grabowski

Mike Grabowski

CTO at Callstack

The React Native monthly meeting continues! This month's meeting was a bit shorter as most of our teams were busy shipping. Next month, we are at React Native EU conference in Wroclaw, Poland. Make sure to grab a ticket and see you there in person! Meanwhile, let's see what our teams are up to.

Teams

On this third meeting, we had 5 teams join us:

Notes

Here are the notes from each team:

Callstack

  • Recently open sourced react-native-material-palette. It extracts prominent colors from images to help you create visually engaging apps. It's Android only at the moment, but we are looking into adding support for iOS in the future.
  • We have landed HMR support into haul and a bunch of other, cool stuff! Check out latest releases.
  • React Native EU 2017 is coming! Next month is all about React Native and Poland! Make sure to grab last tickets available here.

Expo

  • Released support for installing npm packages on Snack. Usual Expo restrictions apply -- packages can't depend on custom native APIs that aren't already included in Expo. We are also working on supporting multiple files and uploading assets in Snack. Satyajit will talk about Snack at React Native Europe.
  • Released SDK20 with camera, payments, secure storage, magnetometer, pause/resume fs downloads, and improved splash/loading screen.
  • Continuing to work with Krzysztof on react-native-gesture-handler. Please give it a try, rebuild some gesture that you have previously built using PanResponder or native gesture recognizers and let us know what issues you encounter.
  • Experimenting with JSC debugging protocol, working on a bunch of feature requests on Canny.

Facebook

  • Last month we discussed management of the GitHub issue tracker and that we would try to make improvements to address the maintainability of the project.
  • Currently, the number of open issues is holding steady at around 600, and it seems like it may stay that way for a while. In the past month, we have closed 690 issues due to lack of activity (defined as no comments in the last 60 days). Out of those 690 issues, 58 were re-opened for a variety of reasons (a maintainer committed to providing a fix, or a contributor made a great case for keeping the issue open).
  • We plan to continue with the automated closing of stale issues for the foreseeable future. We’d like to be in a state where every impactful issue opened in the tracker is acted upon, but we’re not there yet. We need all the help we can from maintainers to triage issues and make sure we don't miss issues that introduce regressions or introduce breaking changes, especially those that affect newly created projects. People interested in helping out can use the Facebook GitHub Bot to triage issues and pull requests. The new Maintainers Guide contains more information on triage and use of the GitHub Bot. Please add yourself to the issue task force and encourage other active community members to do the same!

Microsoft

  • The new Skype app is built on top of React Native in order to facilitate sharing as much code between platforms as possible. The React Native-based Skype app is currently available in the Android and iOS app stores.
  • While building the Skype app on React Native, we send pull requests to React Native in order to address bugs and missing features that we come across. So far, we've gotten about 70 pull requests merged.
  • React Native enabled us to power both the Android and iOS Skype apps from the same codebase. We also want to use that codebase to power the Skype web app. To help us achieve that goal, we built and open sourced a thin layer on top of React/React Native called ReactXP. ReactXP provides a set of cross platform components that get mapped to React Native when targeting iOS/Android and to react-dom when targeting the web. ReactXP's goals are similar to another open source library called React Native for Web. There's a brief description of how the approaches of these libraries differ in the ReactXP FAQ.

Shoutem

  • We are continuing our efforts on improving and simplifying the developer experience when building apps using Shoutem.
  • Started migrating all our apps to react-navigation, but we ended postponing this until a more stable version is released, or one of the native navigation solutions becomes stable.
  • Updating all our extensions and most of our open source libraries (animation, theme, ui) to React Native 0.47.1.

Next session

The next session is scheduled for Wednesday 13, September 2017. As this was only our third meeting, we'd like to know how do these notes benefit the React Native community. Feel free to ping me on Twitter if you have any suggestion on how we should improve the output of the meeting.

- + diff --git a/blog/2017/08/30/react-native-monthly-3/index.html b/blog/2017/08/30/react-native-monthly-3/index.html index bb6b8e1f52e..2b8562b2ada 100644 --- a/blog/2017/08/30/react-native-monthly-3/index.html +++ b/blog/2017/08/30/react-native-monthly-3/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native Monthly #3

Mike Grabowski

Mike Grabowski

CTO at Callstack

The React Native monthly meeting continues! This month's meeting was a bit shorter as most of our teams were busy shipping. Next month, we are at React Native EU conference in Wroclaw, Poland. Make sure to grab a ticket and see you there in person! Meanwhile, let's see what our teams are up to.

Teams

On this third meeting, we had 5 teams join us:

Notes

Here are the notes from each team:

Callstack

  • Recently open sourced react-native-material-palette. It extracts prominent colors from images to help you create visually engaging apps. It's Android only at the moment, but we are looking into adding support for iOS in the future.
  • We have landed HMR support into haul and a bunch of other, cool stuff! Check out latest releases.
  • React Native EU 2017 is coming! Next month is all about React Native and Poland! Make sure to grab last tickets available here.

Expo

  • Released support for installing npm packages on Snack. Usual Expo restrictions apply -- packages can't depend on custom native APIs that aren't already included in Expo. We are also working on supporting multiple files and uploading assets in Snack. Satyajit will talk about Snack at React Native Europe.
  • Released SDK20 with camera, payments, secure storage, magnetometer, pause/resume fs downloads, and improved splash/loading screen.
  • Continuing to work with Krzysztof on react-native-gesture-handler. Please give it a try, rebuild some gesture that you have previously built using PanResponder or native gesture recognizers and let us know what issues you encounter.
  • Experimenting with JSC debugging protocol, working on a bunch of feature requests on Canny.

Facebook

  • Last month we discussed management of the GitHub issue tracker and that we would try to make improvements to address the maintainability of the project.
  • Currently, the number of open issues is holding steady at around 600, and it seems like it may stay that way for a while. In the past month, we have closed 690 issues due to lack of activity (defined as no comments in the last 60 days). Out of those 690 issues, 58 were re-opened for a variety of reasons (a maintainer committed to providing a fix, or a contributor made a great case for keeping the issue open).
  • We plan to continue with the automated closing of stale issues for the foreseeable future. We’d like to be in a state where every impactful issue opened in the tracker is acted upon, but we’re not there yet. We need all the help we can from maintainers to triage issues and make sure we don't miss issues that introduce regressions or introduce breaking changes, especially those that affect newly created projects. People interested in helping out can use the Facebook GitHub Bot to triage issues and pull requests. The new Maintainers Guide contains more information on triage and use of the GitHub Bot. Please add yourself to the issue task force and encourage other active community members to do the same!

Microsoft

  • The new Skype app is built on top of React Native in order to facilitate sharing as much code between platforms as possible. The React Native-based Skype app is currently available in the Android and iOS app stores.
  • While building the Skype app on React Native, we send pull requests to React Native in order to address bugs and missing features that we come across. So far, we've gotten about 70 pull requests merged.
  • React Native enabled us to power both the Android and iOS Skype apps from the same codebase. We also want to use that codebase to power the Skype web app. To help us achieve that goal, we built and open sourced a thin layer on top of React/React Native called ReactXP. ReactXP provides a set of cross platform components that get mapped to React Native when targeting iOS/Android and to react-dom when targeting the web. ReactXP's goals are similar to another open source library called React Native for Web. There's a brief description of how the approaches of these libraries differ in the ReactXP FAQ.

Shoutem

  • We are continuing our efforts on improving and simplifying the developer experience when building apps using Shoutem.
  • Started migrating all our apps to react-navigation, but we ended postponing this until a more stable version is released, or one of the native navigation solutions becomes stable.
  • Updating all our extensions and most of our open source libraries (animation, theme, ui) to React Native 0.47.1.

Next session

The next session is scheduled for Wednesday 13, September 2017. As this was only our third meeting, we'd like to know how do these notes benefit the React Native community. Feel free to ping me on Twitter if you have any suggestion on how we should improve the output of the meeting.

- + diff --git a/blog/2017/09/21/react-native-monthly-4.html b/blog/2017/09/21/react-native-monthly-4.html index 5806ddb9328..393e4846c9d 100644 --- a/blog/2017/09/21/react-native-monthly-4.html +++ b/blog/2017/09/21/react-native-monthly-4.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native Monthly #4

Mike Grabowski

Mike Grabowski

CTO at Callstack

The React Native monthly meeting continues! Here are the notes from each team:

Callstack

  • React Native EU is over. More than 300 participants from 33 countries have visited Wroclaw. Talks can be found on Youtube.
  • We are slowly getting back to our open source schedule after the conference. One thing worth mentioning is that we are working on a next release of react-native-opentok that fixes most of the existing issues.

GeekyAnts

Trying to lower the entry barrier for the developers embracing React Native with the following things:

  • Announced BuilderX.io at React Native EU. BuilderX is a design tool that directly works with JavaScript files (only React Native is supported at the moment) to generate beautiful, readable, and editable code.
  • Launched ReactNativeSeed.com which provides a set of boilerplates for your next React Native project. It comes with a variety of options that include TypeScript & Flow for data-types, MobX, Redux, and mobx-state-tree for state-management with CRNA and plain React-Native as the stack.

Expo

  • Will release SDK 21 shortly, which adds support for react-native 0.48.3 and a bunch of bugfixes/reliability improvements/new features in the Expo SDK, including video recording, a new splash screen API, support for react-native-gesture-handler, and improved error handling.
  • Re: react-native-gesture-handler, Krzysztof Magiera of Software Mansion continues pushing this forward and we've been helping him with testing it and funding part of his development time. Having this integrated in Expo in SDK21 will allow people to play with it easily in Snack, so we're excited to see what people come up with.
  • Re: improved error logging / handling - see this gist of an internal Expo PR for details on logging, (in particular, "Problem 2"), and this commit for a change that handles failed attempts to import npm standard library modules. There is plenty of opportunity to improve error messages upstream in React Native in this way and we will work on follow up upstream PRs. It would be great for the community to get involved too.
  • native.directory continues to grow, you can add your projects from the Github repo.
  • Visit hackathons around North America, including PennApps, Hack The North, HackMIT, and soon MHacks.

Facebook

  • Working on improving <Text> and <TextInput> components on Android. (Native auto-growing for <TextInput>; deeply nested <Text> components layout issues; better code structure; performance optimizations).
  • We're still looking for additional contributors who would like to help triage issues and pull requests.

Microsoft

  • Released Code Signing feature for CodePush. React Native developers are now able to sign their application bundles in CodePush. The announcement can be found here
  • Working on completing integration of CodePush to Mobile Center. Considering test/crash integration as well.

Next session

The next session is scheduled for Wednesday 10, October 2017. As this was only our fourth meeting, we'd like to know how do these notes benefit the React Native community. Feel free to ping me on Twitter if you have any suggestion on how we should improve the output of the meeting.

- + diff --git a/blog/2017/09/21/react-native-monthly-4/index.html b/blog/2017/09/21/react-native-monthly-4/index.html index 5806ddb9328..393e4846c9d 100644 --- a/blog/2017/09/21/react-native-monthly-4/index.html +++ b/blog/2017/09/21/react-native-monthly-4/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native Monthly #4

Mike Grabowski

Mike Grabowski

CTO at Callstack

The React Native monthly meeting continues! Here are the notes from each team:

Callstack

  • React Native EU is over. More than 300 participants from 33 countries have visited Wroclaw. Talks can be found on Youtube.
  • We are slowly getting back to our open source schedule after the conference. One thing worth mentioning is that we are working on a next release of react-native-opentok that fixes most of the existing issues.

GeekyAnts

Trying to lower the entry barrier for the developers embracing React Native with the following things:

  • Announced BuilderX.io at React Native EU. BuilderX is a design tool that directly works with JavaScript files (only React Native is supported at the moment) to generate beautiful, readable, and editable code.
  • Launched ReactNativeSeed.com which provides a set of boilerplates for your next React Native project. It comes with a variety of options that include TypeScript & Flow for data-types, MobX, Redux, and mobx-state-tree for state-management with CRNA and plain React-Native as the stack.

Expo

  • Will release SDK 21 shortly, which adds support for react-native 0.48.3 and a bunch of bugfixes/reliability improvements/new features in the Expo SDK, including video recording, a new splash screen API, support for react-native-gesture-handler, and improved error handling.
  • Re: react-native-gesture-handler, Krzysztof Magiera of Software Mansion continues pushing this forward and we've been helping him with testing it and funding part of his development time. Having this integrated in Expo in SDK21 will allow people to play with it easily in Snack, so we're excited to see what people come up with.
  • Re: improved error logging / handling - see this gist of an internal Expo PR for details on logging, (in particular, "Problem 2"), and this commit for a change that handles failed attempts to import npm standard library modules. There is plenty of opportunity to improve error messages upstream in React Native in this way and we will work on follow up upstream PRs. It would be great for the community to get involved too.
  • native.directory continues to grow, you can add your projects from the Github repo.
  • Visit hackathons around North America, including PennApps, Hack The North, HackMIT, and soon MHacks.

Facebook

  • Working on improving <Text> and <TextInput> components on Android. (Native auto-growing for <TextInput>; deeply nested <Text> components layout issues; better code structure; performance optimizations).
  • We're still looking for additional contributors who would like to help triage issues and pull requests.

Microsoft

  • Released Code Signing feature for CodePush. React Native developers are now able to sign their application bundles in CodePush. The announcement can be found here
  • Working on completing integration of CodePush to Mobile Center. Considering test/crash integration as well.

Next session

The next session is scheduled for Wednesday 10, October 2017. As this was only our fourth meeting, we'd like to know how do these notes benefit the React Native community. Feel free to ping me on Twitter if you have any suggestion on how we should improve the output of the meeting.

- + diff --git a/blog/2017/11/06/react-native-monthly-5.html b/blog/2017/11/06/react-native-monthly-5.html index b68ec3958a6..487cf34ead2 100644 --- a/blog/2017/11/06/react-native-monthly-5.html +++ b/blog/2017/11/06/react-native-monthly-5.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native Monthly #5

Tomislav Tenodi

Tomislav Tenodi

Founder at Speck

The React Native monthly meeting continues! Let's see what our teams are up to.

Callstack

  • We’ve been working on React Native CI. Most importantly, we have migrated from Travis to Circle, leaving React Native with a single, unified CI pipeline.
  • We’ve organised Hacktoberfest - React Native edition where, together with attendees, we tried to submit many pull requests to open source projects.
  • We keep working on Haul. Last month, we have submitted two new releases, including Webpack 3 support. We plan to add CRNA and Expo support as well as work on better HMR. Our roadmap is public on the issue tracker. If you would like to suggest improvements or give feedback, let us know!

Expo

  • Released Expo SDK 22 (using React Native 0.49) and updated CRNA for it.
    • Includes improved splash screen API, basic ARKit support, “DeviceMotion” API, SFAuthenticationSession support on iOS11, and more.
  • Your snacks can now have multiple JavaScript files and you can upload images and other assets by just dragging them into the editor.
  • Contribute to react-navigation to add support for iPhone X.
  • Focus our attention on rough edges when building large applications with Expo. For example:
    • First-class support for deploying to multiple environments: staging, production, and arbitrary channels. Channels will support rolling back and setting the active release for a given channel. Let us know if you want to be an early tester, @expo_io.
    • We are also working on improving our standalone app building infrastructure and adding support for bundling images and other non-code assets in standalone app builds while keeping the ability to update assets over the air.

Facebook

  • Better RTL support:
    • We’re introducing a number of direction-aware styles.
      • Position:
        • (left|right) → (start|end)
      • Margin:
        • margin(Left|Right) → margin(Start|End)
      • Padding:
        • padding(Left|Right) → padding(Start|End)
      • Border:
        • borderTop(Left|Right)Radius → borderTop(Start|End)Radius
        • borderBottom(Left|Right)Radius → borderBottom(Start|End)Radius
        • border(Left|Right)Width → border(Start|End)Width
        • border(Left|Right)Color → border(Start|End)Color
    • The meaning of “left” and “right” were swapped in RTL for position, margin, padding, and border styles. Within a few months, we’re going to remove this behaviour and make “left” always mean “left,” and “right” always mean “right”. The breaking changes are hidden under a flag. Use I18nManager.swapLeftAndRightInRTL(false) in your React Native components to opt into them.
  • Working on Flow typing our internal native modules and using those to generate interfaces in Java and protocols in ObjC that the native implementations must implement. We hope this codegen becomes open source next year, at the earliest.

Infinite Red

  • New OSS tool for helping React Native and other projects. More here.
  • Revamping Ignite for a new boilerplate release (Code name: Bowser)

Shoutem

  • Improving the development flow on Shoutem. We want to streamline the process from creating an app to first custom screen and make it really easy, thus lowering the barrier for new React Native developers. Prepared a few workshops to test out new features. We also improved Shoutem CLI to support new flows.
  • Shoutem UI received a few component improvements and bugfixes. We also checked compatibility with latest React Native versions.
  • Shoutem platform received a few notable updates, new integrations are available as part of the open-source extensions project. We are really excited to see active development on Shoutem extensions from other developers. We actively contact and offer advice and guidance about their extensions.

Next session

The next session is scheduled for Wednesday 6, December 2017. Feel free to ping me on Twitter if you have any suggestion on how we should improve the output of the meeting.

- + diff --git a/blog/2017/11/06/react-native-monthly-5/index.html b/blog/2017/11/06/react-native-monthly-5/index.html index b68ec3958a6..487cf34ead2 100644 --- a/blog/2017/11/06/react-native-monthly-5/index.html +++ b/blog/2017/11/06/react-native-monthly-5/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native Monthly #5

Tomislav Tenodi

Tomislav Tenodi

Founder at Speck

The React Native monthly meeting continues! Let's see what our teams are up to.

Callstack

  • We’ve been working on React Native CI. Most importantly, we have migrated from Travis to Circle, leaving React Native with a single, unified CI pipeline.
  • We’ve organised Hacktoberfest - React Native edition where, together with attendees, we tried to submit many pull requests to open source projects.
  • We keep working on Haul. Last month, we have submitted two new releases, including Webpack 3 support. We plan to add CRNA and Expo support as well as work on better HMR. Our roadmap is public on the issue tracker. If you would like to suggest improvements or give feedback, let us know!

Expo

  • Released Expo SDK 22 (using React Native 0.49) and updated CRNA for it.
    • Includes improved splash screen API, basic ARKit support, “DeviceMotion” API, SFAuthenticationSession support on iOS11, and more.
  • Your snacks can now have multiple JavaScript files and you can upload images and other assets by just dragging them into the editor.
  • Contribute to react-navigation to add support for iPhone X.
  • Focus our attention on rough edges when building large applications with Expo. For example:
    • First-class support for deploying to multiple environments: staging, production, and arbitrary channels. Channels will support rolling back and setting the active release for a given channel. Let us know if you want to be an early tester, @expo_io.
    • We are also working on improving our standalone app building infrastructure and adding support for bundling images and other non-code assets in standalone app builds while keeping the ability to update assets over the air.

Facebook

  • Better RTL support:
    • We’re introducing a number of direction-aware styles.
      • Position:
        • (left|right) → (start|end)
      • Margin:
        • margin(Left|Right) → margin(Start|End)
      • Padding:
        • padding(Left|Right) → padding(Start|End)
      • Border:
        • borderTop(Left|Right)Radius → borderTop(Start|End)Radius
        • borderBottom(Left|Right)Radius → borderBottom(Start|End)Radius
        • border(Left|Right)Width → border(Start|End)Width
        • border(Left|Right)Color → border(Start|End)Color
    • The meaning of “left” and “right” were swapped in RTL for position, margin, padding, and border styles. Within a few months, we’re going to remove this behaviour and make “left” always mean “left,” and “right” always mean “right”. The breaking changes are hidden under a flag. Use I18nManager.swapLeftAndRightInRTL(false) in your React Native components to opt into them.
  • Working on Flow typing our internal native modules and using those to generate interfaces in Java and protocols in ObjC that the native implementations must implement. We hope this codegen becomes open source next year, at the earliest.

Infinite Red

  • New OSS tool for helping React Native and other projects. More here.
  • Revamping Ignite for a new boilerplate release (Code name: Bowser)

Shoutem

  • Improving the development flow on Shoutem. We want to streamline the process from creating an app to first custom screen and make it really easy, thus lowering the barrier for new React Native developers. Prepared a few workshops to test out new features. We also improved Shoutem CLI to support new flows.
  • Shoutem UI received a few component improvements and bugfixes. We also checked compatibility with latest React Native versions.
  • Shoutem platform received a few notable updates, new integrations are available as part of the open-source extensions project. We are really excited to see active development on Shoutem extensions from other developers. We actively contact and offer advice and guidance about their extensions.

Next session

The next session is scheduled for Wednesday 6, December 2017. Feel free to ping me on Twitter if you have any suggestion on how we should improve the output of the meeting.

- + diff --git a/blog/2018/01/09/react-native-monthly-6.html b/blog/2018/01/09/react-native-monthly-6.html index 181916aad4c..e1d1ece921e 100644 --- a/blog/2018/01/09/react-native-monthly-6.html +++ b/blog/2018/01/09/react-native-monthly-6.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native Monthly #6

Tomislav Tenodi

Tomislav Tenodi

Founder at Speck

The React Native monthly meeting is still going strong! Make sure to check a note on the bottom of this post for the next sessions.

Expo

  • Congratulations to Devin Abbott and Houssein Djirdeh on their pre-release of the "Full Stack React Native" book! It walks you through learning React Native by building several small apps. You can try those apps out on https://www.fullstackreact.com/react-native/ before buying the book.
  • Released a first (experimental) version of reason-react-native-scripts to help people to easily try out ReasonML.
  • Expo SDK 24 is released! It uses React Native 0.51 and includes a bunch of new features and improvements: bundling images in standalone apps (no need to cache on first load!), image manipulation API (crop, resize, rotate, flip), face detection API, new release channel features (set the active release for a given channel and rollback), web dashboard to track standalone app builds, and a fix longstanding bug with OpenGL Android implementation and the Android multi-tasker, just to name a few things.
  • We are allocating more resources to React Navigation starting this January. We strongly believe that it is both possible and desirable to build React Native navigation with just React components and primitives like Animated and react-native-gesture-handler and we’re really excited about some of the improvements we have planned. If you're looking to contribute to the community, check out react-native-maps and react-native-svg, which could both use some help!

Infinite Red

Microsoft

  • A pull request has been started to migrate the core React Native Windows bridge to .NET Standard, making it effectively OS-agnostic. The hope is that many other .NET Core platforms can extend the bridge with their own threading models, JavaScript runtimes, and UIManagers (think JavaScriptCore, Xamarin.Mac, Linux Gtk#, and Samsung Tizen options).

Wix

  • Detox
    • In order for us to scale with E2E tests, we want to minimize time spent on CI, we are working on parallelization support for Detox.
    • Submitted a pull request to enable support for custom flavor builds, to better support mocking on E2E.
  • DetoxInstruments
    • Working on the killer feature of DetoxInstruments proves to be a very challenging task, taking JavaScript backtrace at any given time requires a custom JSCore implementation to support JS thread suspension. Testing the profiler internally on Wix’s app revealed interesting insights about the JS thread.
    • The project is still not stable enough for general use but is actively worked on, and we hope to announce it soon.
  • React Native Navigation
    • V2 development pace has been increased substantially, up until now, we only had 1 developer working on it 20% of his time, we now have 3 developers working on it full time!
  • Android Performance
    • Replacing the old JSCore bundled in RN with its newest version (tip of webkitGTK project, with custom JIT configuration) produced 40% performance increase on the JS thread. Next up is compiling a 64bit version of it. This effort is based on JSC build scripts for Android. Follow its current status here.

Next sessions

There's been some discussion on re-purposing this meeting to discuss a single and specific topic (e.g. navigation, moving React Native modules into separate repos, documentation, ...). That way we feel we can contribute the best to React Native community. It might take place in the next meeting session. Feel free to tweet what you'd like to see covered as a topic.

- + diff --git a/blog/2018/01/09/react-native-monthly-6/index.html b/blog/2018/01/09/react-native-monthly-6/index.html index 181916aad4c..e1d1ece921e 100644 --- a/blog/2018/01/09/react-native-monthly-6/index.html +++ b/blog/2018/01/09/react-native-monthly-6/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native Monthly #6

Tomislav Tenodi

Tomislav Tenodi

Founder at Speck

The React Native monthly meeting is still going strong! Make sure to check a note on the bottom of this post for the next sessions.

Expo

  • Congratulations to Devin Abbott and Houssein Djirdeh on their pre-release of the "Full Stack React Native" book! It walks you through learning React Native by building several small apps. You can try those apps out on https://www.fullstackreact.com/react-native/ before buying the book.
  • Released a first (experimental) version of reason-react-native-scripts to help people to easily try out ReasonML.
  • Expo SDK 24 is released! It uses React Native 0.51 and includes a bunch of new features and improvements: bundling images in standalone apps (no need to cache on first load!), image manipulation API (crop, resize, rotate, flip), face detection API, new release channel features (set the active release for a given channel and rollback), web dashboard to track standalone app builds, and a fix longstanding bug with OpenGL Android implementation and the Android multi-tasker, just to name a few things.
  • We are allocating more resources to React Navigation starting this January. We strongly believe that it is both possible and desirable to build React Native navigation with just React components and primitives like Animated and react-native-gesture-handler and we’re really excited about some of the improvements we have planned. If you're looking to contribute to the community, check out react-native-maps and react-native-svg, which could both use some help!

Infinite Red

Microsoft

  • A pull request has been started to migrate the core React Native Windows bridge to .NET Standard, making it effectively OS-agnostic. The hope is that many other .NET Core platforms can extend the bridge with their own threading models, JavaScript runtimes, and UIManagers (think JavaScriptCore, Xamarin.Mac, Linux Gtk#, and Samsung Tizen options).

Wix

  • Detox
    • In order for us to scale with E2E tests, we want to minimize time spent on CI, we are working on parallelization support for Detox.
    • Submitted a pull request to enable support for custom flavor builds, to better support mocking on E2E.
  • DetoxInstruments
    • Working on the killer feature of DetoxInstruments proves to be a very challenging task, taking JavaScript backtrace at any given time requires a custom JSCore implementation to support JS thread suspension. Testing the profiler internally on Wix’s app revealed interesting insights about the JS thread.
    • The project is still not stable enough for general use but is actively worked on, and we hope to announce it soon.
  • React Native Navigation
    • V2 development pace has been increased substantially, up until now, we only had 1 developer working on it 20% of his time, we now have 3 developers working on it full time!
  • Android Performance
    • Replacing the old JSCore bundled in RN with its newest version (tip of webkitGTK project, with custom JIT configuration) produced 40% performance increase on the JS thread. Next up is compiling a 64bit version of it. This effort is based on JSC build scripts for Android. Follow its current status here.

Next sessions

There's been some discussion on re-purposing this meeting to discuss a single and specific topic (e.g. navigation, moving React Native modules into separate repos, documentation, ...). That way we feel we can contribute the best to React Native community. It might take place in the next meeting session. Feel free to tweet what you'd like to see covered as a topic.

- + diff --git a/blog/2018/01/18/implementing-twitters-app-loading-animation-in-react-native.html b/blog/2018/01/18/implementing-twitters-app-loading-animation-in-react-native.html index 152da5ce9c1..af16283507c 100644 --- a/blog/2018/01/18/implementing-twitters-app-loading-animation-in-react-native.html +++ b/blog/2018/01/18/implementing-twitters-app-loading-animation-in-react-native.html @@ -19,7 +19,7 @@ - + @@ -45,7 +45,7 @@
return (
<View style={styles.fullScreen}>
{fullScreenBlueLayer}
<MaskedViewIOS
style={{ flex: 1 }}
maskElement={
<View style={styles.centeredFullScreen}>
<Animated.Image
style={[styles.maskImageStyle, imageScale]}
source={twitterLogo}
/>
</View>
}>
{fullScreenWhiteLayer}
<Animated.View
style={[opacityClearToVisible, appScale, { flex: 1 }]}>
{this.props.children}
</Animated.View>
</MaskedViewIOS>
</View>
);

Yay! We now have the animation pieces looking like we want. Now we just have to clean up our blue and white layers which will never be seen again.

To know when we can clean them up, we need to know when the animation is complete. Luckily where we call, Animated.timing ,.start takes an optional callback that runs when the animation is complete.

Animated.timing(this.state.loadingProgress, {
toValue: 100,
duration: 1000,
useNativeDriver: true
}).start(() => {
this.setState({
animationDone: true
});
});

Now that we have a value in state to know whether we are done with the animation, we can modify our blue and white layers to use that.

const fullScreenBlueLayer = this.state.animationDone ? null : (
<View style={[styles.fullScreenBlueLayer]} />
);
const fullScreenWhiteLayer = this.state.animationDone ? null : (
<View style={[styles.fullScreenWhiteLayer]} />
);

Voila! Our animation now works and we clean up our unused layers once the animation is done. We have built the Twitter app loading animation!

But wait, mine doesn’t work!

Don’t fret, dear reader. I too hate when guides only give you chunks of the code and don’t give you the completed source.

This component has been published to npm and is on GitHub as react-native-mask-loader. To try this out on your phone, it is available on Expo here:

More Reading / Extra Credit

  1. This gitbook is a great resource to learn more about Animated after you have read the React Native docs.
  2. The actual Twitter animation seems to speed up the mask reveal towards the end. Try modifying the loader to use a different easing function (or a spring!) to better match that behavior.
  3. The current end-scale of the mask is hard coded and likely won’t reveal the entire app on a tablet. Calculating the end scale based on screen size and image size would be an awesome PR.
- + diff --git a/blog/2018/01/18/implementing-twitters-app-loading-animation-in-react-native/index.html b/blog/2018/01/18/implementing-twitters-app-loading-animation-in-react-native/index.html index 152da5ce9c1..af16283507c 100644 --- a/blog/2018/01/18/implementing-twitters-app-loading-animation-in-react-native/index.html +++ b/blog/2018/01/18/implementing-twitters-app-loading-animation-in-react-native/index.html @@ -19,7 +19,7 @@ - + @@ -45,7 +45,7 @@
return (
<View style={styles.fullScreen}>
{fullScreenBlueLayer}
<MaskedViewIOS
style={{ flex: 1 }}
maskElement={
<View style={styles.centeredFullScreen}>
<Animated.Image
style={[styles.maskImageStyle, imageScale]}
source={twitterLogo}
/>
</View>
}>
{fullScreenWhiteLayer}
<Animated.View
style={[opacityClearToVisible, appScale, { flex: 1 }]}>
{this.props.children}
</Animated.View>
</MaskedViewIOS>
</View>
);

Yay! We now have the animation pieces looking like we want. Now we just have to clean up our blue and white layers which will never be seen again.

To know when we can clean them up, we need to know when the animation is complete. Luckily where we call, Animated.timing ,.start takes an optional callback that runs when the animation is complete.

Animated.timing(this.state.loadingProgress, {
toValue: 100,
duration: 1000,
useNativeDriver: true
}).start(() => {
this.setState({
animationDone: true
});
});

Now that we have a value in state to know whether we are done with the animation, we can modify our blue and white layers to use that.

const fullScreenBlueLayer = this.state.animationDone ? null : (
<View style={[styles.fullScreenBlueLayer]} />
);
const fullScreenWhiteLayer = this.state.animationDone ? null : (
<View style={[styles.fullScreenWhiteLayer]} />
);

Voila! Our animation now works and we clean up our unused layers once the animation is done. We have built the Twitter app loading animation!

But wait, mine doesn’t work!

Don’t fret, dear reader. I too hate when guides only give you chunks of the code and don’t give you the completed source.

This component has been published to npm and is on GitHub as react-native-mask-loader. To try this out on your phone, it is available on Expo here:

More Reading / Extra Credit

  1. This gitbook is a great resource to learn more about Animated after you have read the React Native docs.
  2. The actual Twitter animation seems to speed up the mask reveal towards the end. Try modifying the loader to use a different easing function (or a spring!) to better match that behavior.
  3. The current end-scale of the mask is hard coded and likely won’t reveal the entire app on a tablet. Calculating the end scale based on screen size and image size would be an awesome PR.
- + diff --git a/blog/2018/03/05/AWS-app-sync.html b/blog/2018/03/05/AWS-app-sync.html index 3f0062e5977..e690fcb3db8 100644 --- a/blog/2018/03/05/AWS-app-sync.html +++ b/blog/2018/03/05/AWS-app-sync.html @@ -19,7 +19,7 @@ - + @@ -46,7 +46,7 @@
const client = new AWSAppSyncClient({
url: awsconfig.graphqlEndpoint,
region: awsconfig.region,
auth: {type: AUTH_TYPE.API_KEY, apiKey: awsconfig.apiKey}
});

The AppSync console provides a configuration file for download, which contains your GraphQL endpoint, AWS Region, and API key. You can then use the client with React Apollo:

const WithProvider = () => (
<ApolloProvider client={client}>
<Rehydrated>
<App />
</Rehydrated>
</ApolloProvider>
);

At this point, you can use standard GraphQL queries:

query ListEvents {
listEvents{
items{
__typename
id
name
where
when
description
comments{
__typename
items{
__typename
eventId
commentId
content
createdAt
}
nextToken
}
}
}
}

The example above shows a query with the sample app schema provisioned by AppSync. It not only showcases interaction with DynamoDB, but also includes pagination of data (including encrypted tokens) and type relations between Events and Comments. Because the app is configured with the AWSAppSyncClient, data is automatically persisted offline and will synchronize when devices reconnect.

You can see a deep dive of the client technology behind this and a React Native demo in this video.

Feedback

The team behind the libraries is eager to hear how these libraries and services work for you. They also want to hear what else we can do to make React and React Native development with cloud services easier for you. Reach out to the AWS Mobile team on GitHub for AWS Amplify or AWS AppSync.

- + diff --git a/blog/2018/03/05/AWS-app-sync/index.html b/blog/2018/03/05/AWS-app-sync/index.html index 3f0062e5977..e690fcb3db8 100644 --- a/blog/2018/03/05/AWS-app-sync/index.html +++ b/blog/2018/03/05/AWS-app-sync/index.html @@ -19,7 +19,7 @@ - + @@ -46,7 +46,7 @@
const client = new AWSAppSyncClient({
url: awsconfig.graphqlEndpoint,
region: awsconfig.region,
auth: {type: AUTH_TYPE.API_KEY, apiKey: awsconfig.apiKey}
});

The AppSync console provides a configuration file for download, which contains your GraphQL endpoint, AWS Region, and API key. You can then use the client with React Apollo:

const WithProvider = () => (
<ApolloProvider client={client}>
<Rehydrated>
<App />
</Rehydrated>
</ApolloProvider>
);

At this point, you can use standard GraphQL queries:

query ListEvents {
listEvents{
items{
__typename
id
name
where
when
description
comments{
__typename
items{
__typename
eventId
commentId
content
createdAt
}
nextToken
}
}
}
}

The example above shows a query with the sample app schema provisioned by AppSync. It not only showcases interaction with DynamoDB, but also includes pagination of data (including encrypted tokens) and type relations between Events and Comments. Because the app is configured with the AWSAppSyncClient, data is automatically persisted offline and will synchronize when devices reconnect.

You can see a deep dive of the client technology behind this and a React Native demo in this video.

Feedback

The team behind the libraries is eager to hear how these libraries and services work for you. They also want to hear what else we can do to make React and React Native development with cloud services easier for you. Reach out to the AWS Mobile team on GitHub for AWS Amplify or AWS AppSync.

- + diff --git a/blog/2018/03/22/building-input-accessory-view-for-react-native.html b/blog/2018/03/22/building-input-accessory-view-for-react-native.html index b4bde0955ce..a034a466826 100644 --- a/blog/2018/03/22/building-input-accessory-view-for-react-native.html +++ b/blog/2018/03/22/building-input-accessory-view-for-react-native.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@
render() {
const inputAccessoryViewID = 'inputAccessoryView1';
return (
<View>
<TextInput
style={styles.default}
inputAccessoryViewID={inputAccessoryViewID}
onChangeText={(text) => this.setState({ text })}
value={this.state.text}
/>
<InputAccessoryView nativeID={inputAccessoryViewID}>
<View style={{ backgroundColor: 'white' }}>
<Button
onPress={() =>
this.setState({ text: 'Placeholder Text' })
}
title="Reset Text"
/>
</View>
</InputAccessoryView>
</View>
);
}
}

Another example for Sticky Text Inputs can be found in the repository.

When will I be able to use this?

The full commit for this feature implementation is here. <InputAccessoryView> will be available in the upcoming v0.55.0 release.

Happy keyboarding :)

- + diff --git a/blog/2018/03/22/building-input-accessory-view-for-react-native/index.html b/blog/2018/03/22/building-input-accessory-view-for-react-native/index.html index b4bde0955ce..a034a466826 100644 --- a/blog/2018/03/22/building-input-accessory-view-for-react-native/index.html +++ b/blog/2018/03/22/building-input-accessory-view-for-react-native/index.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@
render() {
const inputAccessoryViewID = 'inputAccessoryView1';
return (
<View>
<TextInput
style={styles.default}
inputAccessoryViewID={inputAccessoryViewID}
onChangeText={(text) => this.setState({ text })}
value={this.state.text}
/>
<InputAccessoryView nativeID={inputAccessoryViewID}>
<View style={{ backgroundColor: 'white' }}>
<Button
onPress={() =>
this.setState({ text: 'Placeholder Text' })
}
title="Reset Text"
/>
</View>
</InputAccessoryView>
</View>
);
}
}

Another example for Sticky Text Inputs can be found in the repository.

When will I be able to use this?

The full commit for this feature implementation is here. <InputAccessoryView> will be available in the upcoming v0.55.0 release.

Happy keyboarding :)

- + diff --git a/blog/2018/04/09/build-com-app.html b/blog/2018/04/09/build-com-app.html index bb2af4fbae0..d3d47c2ad31 100644 --- a/blog/2018/04/09/build-com-app.html +++ b/blog/2018/04/09/build-com-app.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Built with React Native - The Build.com app

Garrett McCullough

Garrett McCullough

Senior Mobile Engineer

Build.com, headquartered in Chico, California, is one of the largest online retailers for home improvement items. The team has had a strong web-centric business for 18 years and began thinking about a mobile App in 2015. Building unique Android and iOS apps wasn’t practical due to our small team and limited native experience. Instead, we decided to take a risk on the very new React Native framework. Our initial commit was on August 12, 2015 using React Native v0.8.0! We were live in both App Stores on October 15, 2016. Over the last two years, we’ve continued to upgrade and expand the app. We are currently on React Native version 0.53.0.

You can check out the app at https://www.build.com/app.

Features

Our app is full featured and includes everything that you’d expect from an e-commerce app: product listings, search and sorting, the ability to configure complex products, favorites, etc. We accept standard credit card payment methods as well as PayPal, and Apple Pay for our iOS users.

A few standout features you might not expect include:

  1. 3D models available for around 40 products with 90 finishes
  2. Augmented Reality (AR) to allow the user to see how lights and faucets will look in their home at 98% size accuracy. The Build.com React Native App is featured in the Apple App store for AR Shopping! AR is now available for Android and iOS!
  3. Collaborative project management features that allow people to put together shopping lists for the different phases of their project and collaborate around selection

We’re working on many new and exciting features that will continue to improve our app experience including the next phase of Immersive Shopping with AR.

Our Development Workflow

Build.com allows each dev to choose the tools that best suit them.

  • IDEs include Atom, IntelliJ, VS Code, Sublime, Eclipse, etc.
  • For Unit testing, developers are responsible for creating Jest unit tests for any new components and we’re working to increase the coverage of older parts of the app using jest-coverage-ratchet.
  • We use Jenkins to build out our beta and release candidates. This process works well for us but still requires significant work to create the release notes and other artifacts.
  • Integration Testing include a shared pool of testers that work across desktop, mobile and web. Our automation engineer is building out our suite of automated integration tests using Java and Appium.
  • Other parts of the workflow include a detailed eslint configuration, custom rules that enforce properties needed for testing, and pre-push hooks that block offending changes.

Libraries Used in the App

The Build.com app relies on a number of common open source libraries including: Redux, Moment, Numeral, Enzyme and a bunch of React Native bridge modules. We also use a number of forked open source libraries; forked either because they were abandoned or because we needed custom features. A quick count shows around 115 JavaScript and native dependencies. We would like to explore tools that remove unused libraries.

We're in the process of adding static typing via TypeScript and looking into optional chaining. These features could help us with solving a couple classes of bugs that we still see:

  • Data that is the wrong type
  • Data that is undefined because an object didn’t contain what we expected

Open Source Contributions

Since we rely so heavily on open source, our team is committed to contributing back to the community. Build.com allows the team to open source libraries that we've built and encourages us contribute back to the libraries that we use.

We’ve released and maintained a number of React Native libraries:

  • react-native-polyfill
  • react-native-simple-store
  • react-native-contact-picker

We have also contributed to a long list of libraries including: React and React Native, react-native-schemes-manager, react-native-swipeable, react-native-gallery, react-native-view-transformer, react-native-navigation.

Our Journey

We’ve seen a lot of growth in React Native and the ecosystem in the past couple years. Early on, it seemed that every version of React Native would fix some bugs but introduce several more. For example, Remote JS Debugging was broken on Android for several months. Thankfully, things became much more stable in 2017.

Navigation Libraries

One of our big recurring challenges has been with navigation libraries. For a long time, we were using Expo’s ex-nav library. It worked well for us but it was eventually deprecated. However, we were in heavy feature development at the time so taking time to change out a navigation library wasn’t feasible. That meant we had to fork the library and patch it to support React 16 and the iPhone X. Eventually, we were able to migrate to react-native-navigation and hopefully that will see continued support.

Bridge Modules

Another big challenge has been with bridge modules. When we first started, a lot of critical bridges were missing. One of my teammates wrote react-native-contact-picker because we needed access to the Android contact picker in our app. We’ve also seen a lot of bridges that were broken by changes within React Native. For example, there was a breaking change within React Native v40 and when we upgraded our app, I had to submit PRs to fix 3 or 4 libraries that had not yet been updated.

Looking Forward

As React Native continues to grow, our wishlist to our community include:

  • Stabilize and improve the navigation libraries
  • Maintain support for libraries in the React Native ecosystem
  • Improve the experience for adding native libraries and bridge modules to a project

Companies and individuals in the React Native community have been great about volunteering their time and effort to improve the tools that we all use. If you haven’t gotten involved in open source, I hope you’ll take a look at improving the code or documentation for some of the libraries that you use. There are a lot of articles to help you get started and it may be a lot easier than you think!

- + diff --git a/blog/2018/04/09/build-com-app/index.html b/blog/2018/04/09/build-com-app/index.html index bb2af4fbae0..d3d47c2ad31 100644 --- a/blog/2018/04/09/build-com-app/index.html +++ b/blog/2018/04/09/build-com-app/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Built with React Native - The Build.com app

Garrett McCullough

Garrett McCullough

Senior Mobile Engineer

Build.com, headquartered in Chico, California, is one of the largest online retailers for home improvement items. The team has had a strong web-centric business for 18 years and began thinking about a mobile App in 2015. Building unique Android and iOS apps wasn’t practical due to our small team and limited native experience. Instead, we decided to take a risk on the very new React Native framework. Our initial commit was on August 12, 2015 using React Native v0.8.0! We were live in both App Stores on October 15, 2016. Over the last two years, we’ve continued to upgrade and expand the app. We are currently on React Native version 0.53.0.

You can check out the app at https://www.build.com/app.

Features

Our app is full featured and includes everything that you’d expect from an e-commerce app: product listings, search and sorting, the ability to configure complex products, favorites, etc. We accept standard credit card payment methods as well as PayPal, and Apple Pay for our iOS users.

A few standout features you might not expect include:

  1. 3D models available for around 40 products with 90 finishes
  2. Augmented Reality (AR) to allow the user to see how lights and faucets will look in their home at 98% size accuracy. The Build.com React Native App is featured in the Apple App store for AR Shopping! AR is now available for Android and iOS!
  3. Collaborative project management features that allow people to put together shopping lists for the different phases of their project and collaborate around selection

We’re working on many new and exciting features that will continue to improve our app experience including the next phase of Immersive Shopping with AR.

Our Development Workflow

Build.com allows each dev to choose the tools that best suit them.

  • IDEs include Atom, IntelliJ, VS Code, Sublime, Eclipse, etc.
  • For Unit testing, developers are responsible for creating Jest unit tests for any new components and we’re working to increase the coverage of older parts of the app using jest-coverage-ratchet.
  • We use Jenkins to build out our beta and release candidates. This process works well for us but still requires significant work to create the release notes and other artifacts.
  • Integration Testing include a shared pool of testers that work across desktop, mobile and web. Our automation engineer is building out our suite of automated integration tests using Java and Appium.
  • Other parts of the workflow include a detailed eslint configuration, custom rules that enforce properties needed for testing, and pre-push hooks that block offending changes.

Libraries Used in the App

The Build.com app relies on a number of common open source libraries including: Redux, Moment, Numeral, Enzyme and a bunch of React Native bridge modules. We also use a number of forked open source libraries; forked either because they were abandoned or because we needed custom features. A quick count shows around 115 JavaScript and native dependencies. We would like to explore tools that remove unused libraries.

We're in the process of adding static typing via TypeScript and looking into optional chaining. These features could help us with solving a couple classes of bugs that we still see:

  • Data that is the wrong type
  • Data that is undefined because an object didn’t contain what we expected

Open Source Contributions

Since we rely so heavily on open source, our team is committed to contributing back to the community. Build.com allows the team to open source libraries that we've built and encourages us contribute back to the libraries that we use.

We’ve released and maintained a number of React Native libraries:

  • react-native-polyfill
  • react-native-simple-store
  • react-native-contact-picker

We have also contributed to a long list of libraries including: React and React Native, react-native-schemes-manager, react-native-swipeable, react-native-gallery, react-native-view-transformer, react-native-navigation.

Our Journey

We’ve seen a lot of growth in React Native and the ecosystem in the past couple years. Early on, it seemed that every version of React Native would fix some bugs but introduce several more. For example, Remote JS Debugging was broken on Android for several months. Thankfully, things became much more stable in 2017.

Navigation Libraries

One of our big recurring challenges has been with navigation libraries. For a long time, we were using Expo’s ex-nav library. It worked well for us but it was eventually deprecated. However, we were in heavy feature development at the time so taking time to change out a navigation library wasn’t feasible. That meant we had to fork the library and patch it to support React 16 and the iPhone X. Eventually, we were able to migrate to react-native-navigation and hopefully that will see continued support.

Bridge Modules

Another big challenge has been with bridge modules. When we first started, a lot of critical bridges were missing. One of my teammates wrote react-native-contact-picker because we needed access to the Android contact picker in our app. We’ve also seen a lot of bridges that were broken by changes within React Native. For example, there was a breaking change within React Native v40 and when we upgraded our app, I had to submit PRs to fix 3 or 4 libraries that had not yet been updated.

Looking Forward

As React Native continues to grow, our wishlist to our community include:

  • Stabilize and improve the navigation libraries
  • Maintain support for libraries in the React Native ecosystem
  • Improve the experience for adding native libraries and bridge modules to a project

Companies and individuals in the React Native community have been great about volunteering their time and effort to improve the tools that we all use. If you haven’t gotten involved in open source, I hope you’ll take a look at improving the code or documentation for some of the libraries that you use. There are a lot of articles to help you get started and it may be a lot easier than you think!

- + diff --git a/blog/2018/05/07/using-typescript-with-react-native.html b/blog/2018/05/07/using-typescript-with-react-native.html index 96c164804f5..514b52aa684 100644 --- a/blog/2018/05/07/using-typescript-with-react-native.html +++ b/blog/2018/05/07/using-typescript-with-react-native.html @@ -19,7 +19,7 @@ - + @@ -52,7 +52,7 @@
it('renders correctly with defaults', () => {
const button = renderer
.create(<Hello name="World" enthusiasmLevel={1} />)
.toJSON();
expect(button).toMatchSnapshot();
});

The first time the test is run, it will create a snapshot of the rendered component and store it in the components/__tests__/__snapshots__/Hello.tsx.snap file. When you modify your component, you'll need to update the snapshots and review the update for inadvertent changes. You can read more about testing React Native components here.

Next Steps

Check out the official React tutorial and state-management library Redux. These resources can be helpful when writing React Native apps. Additionally, you may want to look at ReactXP, a component library written entirely in TypeScript that supports both React on the web as well as React Native.

Have fun in a more type-safe React Native development environment!

- + diff --git a/blog/2018/05/07/using-typescript-with-react-native/index.html b/blog/2018/05/07/using-typescript-with-react-native/index.html index 96c164804f5..514b52aa684 100644 --- a/blog/2018/05/07/using-typescript-with-react-native/index.html +++ b/blog/2018/05/07/using-typescript-with-react-native/index.html @@ -19,7 +19,7 @@ - + @@ -52,7 +52,7 @@
it('renders correctly with defaults', () => {
const button = renderer
.create(<Hello name="World" enthusiasmLevel={1} />)
.toJSON();
expect(button).toMatchSnapshot();
});

The first time the test is run, it will create a snapshot of the rendered component and store it in the components/__tests__/__snapshots__/Hello.tsx.snap file. When you modify your component, you'll need to update the snapshots and review the update for inadvertent changes. You can read more about testing React Native components here.

Next Steps

Check out the official React tutorial and state-management library Redux. These resources can be helpful when writing React Native apps. Additionally, you may want to look at ReactXP, a component library written entirely in TypeScript that supports both React on the web as well as React Native.

Have fun in a more type-safe React Native development environment!

- + diff --git a/blog/2018/06/14/state-of-react-native-2018.html b/blog/2018/06/14/state-of-react-native-2018.html index 65510ae5cea..4e2dafdbc8f 100644 --- a/blog/2018/06/14/state-of-react-native-2018.html +++ b/blog/2018/06/14/state-of-react-native-2018.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

State of React Native 2018

Sophie Alpert

Sophie Alpert

Engineering Manager on React at Facebook

It's been a while since we last published a status update about React Native.

At Facebook, we're using React Native more than ever and for many important projects. One of our most popular products is Marketplace, one of the top-level tabs in our app which is used by 800 million people each month. Since its creation in 2015, all of Marketplace has been built with React Native, including over a hundred full-screen views throughout different parts of the app.

We're also using React Native for many new parts of the app. If you watched the F8 keynote last month, you'll recognize Blood Donations, Crisis Response, Privacy Shortcuts, and Wellness Checks – all recent features built with React Native. And projects outside the main Facebook app are using React Native too. The new Oculus Go VR headset includes a companion mobile app that is fully built with React Native, not to mention React VR powering many experiences in the headset itself.

Naturally, we also use many other technologies to build our apps. Litho and ComponentKit are two libraries we use extensively in our apps; both provide a React-like component API for building native screens. It's never been a goal for React Native to replace all other technologies – we are focused on making React Native itself better, but we love seeing other teams borrow ideas from React Native, like bringing instant reload to non-JavaScript code too.

Architecture

When we started the React Native project in 2013, we designed it to have a single “bridge” between JavaScript and native that is asynchronous, serializable, and batched. Just as React DOM turns React state updates into imperative, mutative calls to DOM APIs like document.createElement(attrs) and .appendChild(), React Native was designed to return a single JSON message that lists mutations to perform, like [["createView", attrs], ["manageChildren", ...]]. We designed the entire system to never rely on getting a synchronous response back and to ensure everything in that list could be fully serialized to JSON and back. We did this for the flexibility it gave us: on top of this architecture, we were able to build tools like Chrome debugging, which runs all the JavaScript code asynchronously over a WebSocket connection.

Over the last 5 years, we found that these initial principles have made building some features harder. An asynchronous bridge means you can't integrate JavaScript logic directly with many native APIs expecting synchronous answers. A batched bridge that queues native calls means it's harder to have React Native apps call into functions that are implemented natively. And a serializable bridge means unnecessary copying instead of directly sharing memory between the two worlds. For apps that are entirely built in React Native, these restrictions are usually bearable. But for apps with complex integration between React Native and existing app code, they are frustrating.

We're working on a large-scale rearchitecture of React Native to make the framework more flexible and integrate better with native infrastructure in hybrid JavaScript/native apps. With this project, we'll apply what we've learned over the last 5 years and incrementally bring our architecture to a more modern one. We're rewriting many of React Native's internals, but most of the changes are under the hood: existing React Native apps will continue to work with few or no changes.

To make React Native more lightweight and fit better into existing native apps, this rearchitecture has three major internal changes. First, we are changing the threading model. Instead of each UI update needing to perform work on three different threads, it will be possible to call synchronously into JavaScript on any thread for high-priority updates while still keeping low-priority work off the main thread to maintain responsiveness. Second, we are incorporating async rendering capabilities into React Native to allow multiple rendering priorities and to simplify asynchronous data handling. Finally, we are simplifying our bridge to make it faster and more lightweight; direct calls between native and JavaScript are more efficient and will make it easier to build debugging tools like cross-language stack traces.

Once these changes are completed, closer integrations will be possible. Today, it's not possible to incorporate native navigation and gesture handling or native components like UICollectionView and RecyclerView without complex hacks. After our changes to the threading model, building features like this will be straightforward.

We'll release more details about this work later this year as it approaches completion.

Community

Alongside the community inside Facebook, we're happy to have a thriving population of React Native users and collaborators outside Facebook. We'd like to support the React Native community more, both by serving React Native users better and by making the project easier to contribute to.

Just as our architecture changes will help React Native interoperate more cleanly with other native infrastructure, React Native should be slimmer on the JavaScript side to fit better with the JavaScript ecosystem, which includes making the VM and bundler swappable. We know the pace of breaking changes can be hard to keep up with, so we'd like to find ways to have fewer major releases. Finally, we know that some teams are looking for more thorough documentation in topics like startup optimization, where our expertise hasn't yet been written down. Expect to see some of these changes over the coming year.

If you're using React Native, you're part of our community; keep letting us know how we can make React Native better for you.

React Native is just one tool in a mobile developer's toolbox, but it's one that we strongly believe in – and we're making it better every day, with over 2500 commits in the last year from 500+ contributors.

- + diff --git a/blog/2018/06/14/state-of-react-native-2018/index.html b/blog/2018/06/14/state-of-react-native-2018/index.html index 65510ae5cea..4e2dafdbc8f 100644 --- a/blog/2018/06/14/state-of-react-native-2018/index.html +++ b/blog/2018/06/14/state-of-react-native-2018/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

State of React Native 2018

Sophie Alpert

Sophie Alpert

Engineering Manager on React at Facebook

It's been a while since we last published a status update about React Native.

At Facebook, we're using React Native more than ever and for many important projects. One of our most popular products is Marketplace, one of the top-level tabs in our app which is used by 800 million people each month. Since its creation in 2015, all of Marketplace has been built with React Native, including over a hundred full-screen views throughout different parts of the app.

We're also using React Native for many new parts of the app. If you watched the F8 keynote last month, you'll recognize Blood Donations, Crisis Response, Privacy Shortcuts, and Wellness Checks – all recent features built with React Native. And projects outside the main Facebook app are using React Native too. The new Oculus Go VR headset includes a companion mobile app that is fully built with React Native, not to mention React VR powering many experiences in the headset itself.

Naturally, we also use many other technologies to build our apps. Litho and ComponentKit are two libraries we use extensively in our apps; both provide a React-like component API for building native screens. It's never been a goal for React Native to replace all other technologies – we are focused on making React Native itself better, but we love seeing other teams borrow ideas from React Native, like bringing instant reload to non-JavaScript code too.

Architecture

When we started the React Native project in 2013, we designed it to have a single “bridge” between JavaScript and native that is asynchronous, serializable, and batched. Just as React DOM turns React state updates into imperative, mutative calls to DOM APIs like document.createElement(attrs) and .appendChild(), React Native was designed to return a single JSON message that lists mutations to perform, like [["createView", attrs], ["manageChildren", ...]]. We designed the entire system to never rely on getting a synchronous response back and to ensure everything in that list could be fully serialized to JSON and back. We did this for the flexibility it gave us: on top of this architecture, we were able to build tools like Chrome debugging, which runs all the JavaScript code asynchronously over a WebSocket connection.

Over the last 5 years, we found that these initial principles have made building some features harder. An asynchronous bridge means you can't integrate JavaScript logic directly with many native APIs expecting synchronous answers. A batched bridge that queues native calls means it's harder to have React Native apps call into functions that are implemented natively. And a serializable bridge means unnecessary copying instead of directly sharing memory between the two worlds. For apps that are entirely built in React Native, these restrictions are usually bearable. But for apps with complex integration between React Native and existing app code, they are frustrating.

We're working on a large-scale rearchitecture of React Native to make the framework more flexible and integrate better with native infrastructure in hybrid JavaScript/native apps. With this project, we'll apply what we've learned over the last 5 years and incrementally bring our architecture to a more modern one. We're rewriting many of React Native's internals, but most of the changes are under the hood: existing React Native apps will continue to work with few or no changes.

To make React Native more lightweight and fit better into existing native apps, this rearchitecture has three major internal changes. First, we are changing the threading model. Instead of each UI update needing to perform work on three different threads, it will be possible to call synchronously into JavaScript on any thread for high-priority updates while still keeping low-priority work off the main thread to maintain responsiveness. Second, we are incorporating async rendering capabilities into React Native to allow multiple rendering priorities and to simplify asynchronous data handling. Finally, we are simplifying our bridge to make it faster and more lightweight; direct calls between native and JavaScript are more efficient and will make it easier to build debugging tools like cross-language stack traces.

Once these changes are completed, closer integrations will be possible. Today, it's not possible to incorporate native navigation and gesture handling or native components like UICollectionView and RecyclerView without complex hacks. After our changes to the threading model, building features like this will be straightforward.

We'll release more details about this work later this year as it approaches completion.

Community

Alongside the community inside Facebook, we're happy to have a thriving population of React Native users and collaborators outside Facebook. We'd like to support the React Native community more, both by serving React Native users better and by making the project easier to contribute to.

Just as our architecture changes will help React Native interoperate more cleanly with other native infrastructure, React Native should be slimmer on the JavaScript side to fit better with the JavaScript ecosystem, which includes making the VM and bundler swappable. We know the pace of breaking changes can be hard to keep up with, so we'd like to find ways to have fewer major releases. Finally, we know that some teams are looking for more thorough documentation in topics like startup optimization, where our expertise hasn't yet been written down. Expect to see some of these changes over the coming year.

If you're using React Native, you're part of our community; keep letting us know how we can make React Native better for you.

React Native is just one tool in a mobile developer's toolbox, but it's one that we strongly believe in – and we're making it better every day, with over 2500 commits in the last year from 500+ contributors.

- + diff --git a/blog/2018/07/04/releasing-react-native-056.html b/blog/2018/07/04/releasing-react-native-056.html index 31860ecbda7..8d529b87b87 100644 --- a/blog/2018/07/04/releasing-react-native-056.html +++ b/blog/2018/07/04/releasing-react-native-056.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Releasing 0.56

Lorenzo Sciandra

Lorenzo Sciandra

Core Maintainer & React Native Developer at Drivetribe

The long-awaited 0.56 version of React Native is now available 🎉. This blog post highlights some of the changes introduced in this new release. We also want to take the opportunity to explain what has kept us busy since March.

The breaking changes dilemma, or, "when to release?"

The Contributor's Guide explains the integration process that all changes to React Native go through. The project has is composed by many different tools, requiring coordination and constant support to keep everything working properly. Add to this the vibrant open source community that contributes back to the project, and you will get a sense of the mind-bending scale of it all.

With React Native's impressive adoption, breaking changes must be made with great care, and the process is not as smooth as we'd like. A decision was made to skip the April and May releases to allow the core team to integrate and test a new set of breaking changes. Dedicated community communication channels were used along the way to ensure that the June 2018 (0.56.0) release is as hassle-free as possible to adopt by those who patiently waited for the stable release.

Is 0.56.0 perfect? No, as every piece of software out there: but we reached a point where the tradeoff between "waiting for more stability" versus "testing led to successful results so we can push forward" that we feel ready to release it. Moreover, we are aware of a few issues that are not solved in the final 0.56.0 release. Most developers should have no issues upgrading to 0.56.0. For those that are blocked by the aforementioned issues, we hope to see you around in our discussions and we are looking forward to working with you on a solution to these issues.

You might consider 0.56.0 as a fundamental building block towards a more stable framework: it will take probably a week or two of widespread adoption before all the edge cases will be sanded off, but this will lead to an even better July 2018 (0.57.0) release.

We'd like to conclude this section by thanking all the 67 contributors who worked on a total of 818 commits (!) that will help make your apps even better 👏.

And now, without further ado...

The Big Changes

Babel 7

As you may know, the transpiler tool that allows us all to use the latest and greatest features of JavaScript, Babel, is moving to v7 soon. Since this new version brings along some important changes, we felt that now it would be a good time to upgrade, allowing Metro to leverage on its improvements.

If you find yourself in trouble with upgrading, please refer to the documentation section related to it.

Modernizing Android support

On Android, much of the surrounding tooling has changed. We've updated to Gradle 3.5, Android SDK 26, Fresco to 1.9.0, and OkHttp to 3.10.0 and even the NDK API target to API 16. These changes should go without issue and result in faster builds. More importantly, it will help developers comply with the new Play Store requirements coming into effect next month.

Related to this, we'd like to particularly thank Dulmandakh for the many PRs submitted in order to make it possible 👏.

There are some more steps that need to be taken in this direction, and you can follow along with the future planning and discussion of updating the Android support in the dedicated issue (and a side one for the JSC).

New Node, Xcode, React, and Flow – oh my!

Node 8 is now the standard for React Native. It was actually already being tested already, but we've put both feet forward as Node 6 entered maintenance mode. React was also updated to 16.4, which brings a ton of fixes with it.

We're dropping support for iOS 8, making iOS 9 the oldest iOS version that can be targeted. We do not foresee this being a problem, as any device that can run iOS 8, can be upgraded to iOS 9. This change allowed us to remove rarely-used code that implemented workarounds for older devices running iOS 8.

The continuous integration toolchain has been updated to use Xcode 9.4, ensuring that all iOS tests are run on the latest developer tools provided by Apple.

We have upgraded to Flow 0.75 to use the new error format that many devs appreciate. We've also created types for many more components. If you're not yet enforcing static typing in your project, please consider using Flow to identify problems as you code instead of at runtime.

And a lot of other things...

For instance, YellowBox was replaced with a new implementation that makes debugging a lot better.

For the complete release notes, please reference the full changelog here. And remember to keep an eye on the upgrading guide to avoid issues moving to this new version.

A final note: starting this week, the React Native core team will resume holding monthly meetings. We'll make sure to keep everyone up-to-date with what's covered, and ensure to keep your feedback at hand for future meetings.

Happy coding everyone!

Lorenzo, Ryan, and the whole React Native core team

PS: as always, we'd like to remind everyone that React Native is still in 0.x versioning because of the many changes still undergoing - so remember when upgrading that yes, probably, something may still crash or be broken. Be helpful towards each other in the issues and when submitting PRs - and remember to follow the CoC enforced: there's always a human on the other side of the screen.

- + diff --git a/blog/2018/07/04/releasing-react-native-056/index.html b/blog/2018/07/04/releasing-react-native-056/index.html index 31860ecbda7..8d529b87b87 100644 --- a/blog/2018/07/04/releasing-react-native-056/index.html +++ b/blog/2018/07/04/releasing-react-native-056/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Releasing 0.56

Lorenzo Sciandra

Lorenzo Sciandra

Core Maintainer & React Native Developer at Drivetribe

The long-awaited 0.56 version of React Native is now available 🎉. This blog post highlights some of the changes introduced in this new release. We also want to take the opportunity to explain what has kept us busy since March.

The breaking changes dilemma, or, "when to release?"

The Contributor's Guide explains the integration process that all changes to React Native go through. The project has is composed by many different tools, requiring coordination and constant support to keep everything working properly. Add to this the vibrant open source community that contributes back to the project, and you will get a sense of the mind-bending scale of it all.

With React Native's impressive adoption, breaking changes must be made with great care, and the process is not as smooth as we'd like. A decision was made to skip the April and May releases to allow the core team to integrate and test a new set of breaking changes. Dedicated community communication channels were used along the way to ensure that the June 2018 (0.56.0) release is as hassle-free as possible to adopt by those who patiently waited for the stable release.

Is 0.56.0 perfect? No, as every piece of software out there: but we reached a point where the tradeoff between "waiting for more stability" versus "testing led to successful results so we can push forward" that we feel ready to release it. Moreover, we are aware of a few issues that are not solved in the final 0.56.0 release. Most developers should have no issues upgrading to 0.56.0. For those that are blocked by the aforementioned issues, we hope to see you around in our discussions and we are looking forward to working with you on a solution to these issues.

You might consider 0.56.0 as a fundamental building block towards a more stable framework: it will take probably a week or two of widespread adoption before all the edge cases will be sanded off, but this will lead to an even better July 2018 (0.57.0) release.

We'd like to conclude this section by thanking all the 67 contributors who worked on a total of 818 commits (!) that will help make your apps even better 👏.

And now, without further ado...

The Big Changes

Babel 7

As you may know, the transpiler tool that allows us all to use the latest and greatest features of JavaScript, Babel, is moving to v7 soon. Since this new version brings along some important changes, we felt that now it would be a good time to upgrade, allowing Metro to leverage on its improvements.

If you find yourself in trouble with upgrading, please refer to the documentation section related to it.

Modernizing Android support

On Android, much of the surrounding tooling has changed. We've updated to Gradle 3.5, Android SDK 26, Fresco to 1.9.0, and OkHttp to 3.10.0 and even the NDK API target to API 16. These changes should go without issue and result in faster builds. More importantly, it will help developers comply with the new Play Store requirements coming into effect next month.

Related to this, we'd like to particularly thank Dulmandakh for the many PRs submitted in order to make it possible 👏.

There are some more steps that need to be taken in this direction, and you can follow along with the future planning and discussion of updating the Android support in the dedicated issue (and a side one for the JSC).

New Node, Xcode, React, and Flow – oh my!

Node 8 is now the standard for React Native. It was actually already being tested already, but we've put both feet forward as Node 6 entered maintenance mode. React was also updated to 16.4, which brings a ton of fixes with it.

We're dropping support for iOS 8, making iOS 9 the oldest iOS version that can be targeted. We do not foresee this being a problem, as any device that can run iOS 8, can be upgraded to iOS 9. This change allowed us to remove rarely-used code that implemented workarounds for older devices running iOS 8.

The continuous integration toolchain has been updated to use Xcode 9.4, ensuring that all iOS tests are run on the latest developer tools provided by Apple.

We have upgraded to Flow 0.75 to use the new error format that many devs appreciate. We've also created types for many more components. If you're not yet enforcing static typing in your project, please consider using Flow to identify problems as you code instead of at runtime.

And a lot of other things...

For instance, YellowBox was replaced with a new implementation that makes debugging a lot better.

For the complete release notes, please reference the full changelog here. And remember to keep an eye on the upgrading guide to avoid issues moving to this new version.

A final note: starting this week, the React Native core team will resume holding monthly meetings. We'll make sure to keep everyone up-to-date with what's covered, and ensure to keep your feedback at hand for future meetings.

Happy coding everyone!

Lorenzo, Ryan, and the whole React Native core team

PS: as always, we'd like to remind everyone that React Native is still in 0.x versioning because of the many changes still undergoing - so remember when upgrading that yes, probably, something may still crash or be broken. Be helpful towards each other in the issues and when submitting PRs - and remember to follow the CoC enforced: there's always a human on the other side of the screen.

- + diff --git a/blog/2018/08/13/react-native-accessibility-updates.html b/blog/2018/08/13/react-native-accessibility-updates.html index a9d1746c3ed..f63eb25cb04 100644 --- a/blog/2018/08/13/react-native-accessibility-updates.html +++ b/blog/2018/08/13/react-native-accessibility-updates.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Accessibility API Updates

Ziqi Chen

Ziqi Chen

Student at UC Berkeley

Motivation

As technology advances and mobile apps become increasingly important to everyday life, the necessity of creating accessible applications has likewise grown in importance.

React Native's limited Accessibility API has always been a huge pain point for developers, so we've made a few updates to the Accessibility API to make it easier to create inclusive mobile applications.

Problems With the Existing API

Problem One: Two Completely Different Yet Similar Props - accessibilityComponentType (Android) and accessibilityTraits (iOS)

accessibilityComponentType and accessibilityTraits are two properties that are used to tell TalkBack on Android and VoiceOver on iOS what kind of UI element the user is interacting with. The two biggest problems with these properties are that:

  1. They are two different properties with different usage methods, yet have the same purpose. In the previous API, these are two separate properties (one for each platform), which was not only inconvenient, but also confusing to many developers. accessibilityTraits on iOS allows 17 different values while accessibilityComponentType on Android allows only 4 values. Furthermore, the values for the most part had no overlap. Even the input types for these two properties are different. accessibilityTraits allows either an array of traits to be passed in or a single trait, while accessibilityComponentType allows only a single value.
  2. There is very limited functionality on Android. With the old property, the only UI elements that Talkback were able to recognize were “button,” “radiobutton_checked,” and “radiobutton_unchecked.”

Problem Two: Non-existent Accessibility Hints:

Accessibility Hints help users using TalkBack or VoiceOver understand what will happen when they perform an action on an accessibility element that is not apparent by only the accessibility label. These hints can be turned on and off in the settings panel. Previously, React Native's API did not support accessibility hints at all.

Problem Three: Ignoring Inverted Colors:

Some users with vision loss use inverted colors on their mobile phones to have greater screen contrast. Apple provided an API for iOS which allows developers to ignore certain views. This way, images and videos aren't distorted when a user has the inverted colors setting on. This API is currently unsupported by React Native.

Design of the New API

Solution One: Combining accessibilityComponentType (Android) and accessibilityTraits (iOS)

In order to solve the confusion between accessibilityComponentType and accessibilityTraits, we decided to merge them into a single property. This made sense because they technically had the same intended functionality and by merging them, developers no longer had to worry about platform specific intricacies when building accessibility features.

Background

On iOS, UIAccessibilityTraits is a property that can be set on any NSObject. Each of the 17 traits passed in through the javascript property to native is mapped to a UIAccessibilityTraits element in Objective-C. Traits are each represented by a long int, and every trait that is set is ORed together.

On Android however, AccessibilityComponentType is a concept that was made up by React Native, and doesn't directly map to any properties in Android. Accessibility is handled by an accessibility delegate. Each view has a default accessibility delegate. If you want to customize any accessibility actions, you have to create a new accessibility delegate, override specific methods you want to customize, and then set the accessibility delegate of the view you are handling to be associated with the new delegate. When a developer set AccessibilityComponentType, the native code created a new delegate based off of the component that was passed in, and set the view to have that accessibility delegate.

Changes Made

For our new property, we wanted to create a superset of the two properties. We decided to keep the new property modeled mostly after the existing property accessibilityTraits, since accessibilityTraits has significantly more values. The functionality of Android for these traits would be polyfilled in by modifying the Accessibility Delegate.

There are 17 values of UIAccessibilityTraits that accessibilityTraits on iOS can be set to. However, we didn't include all of them as possible values to our new property. This is because the effect of setting some of these traits is actually not very well known, and many of these values are virtually never used.

The values UIAccessibilityTraits were set to generally took on one of two purposes. They either described a role that UI element had, or they described the state a UI element was in. Most uses of the previous properties we observed usually used one value that represented a role and combined it with either “state selected,” “state disabled,” or both. Therefore, we decided to create two new accessibility properties: accessibilityRole and accessibilityState.

accessibilityRole

The new property, accessibilityRole, is used to tell Talkback or Voiceover the role of a UI Element. This new property can take on one of the following values:

  • none
  • button
  • link
  • search
  • image
  • keyboardkey
  • text
  • adjustable
  • header
  • summary
  • imagebutton

This property only allows one value to be passed in because UI elements generally don't logically take on more than one of these. The exception is image and button, so we've added a role imagebutton that is a combination of both.

accessibilityStates

The new property, accessibilityStates, is used to tell Talkback or Voiceover the state a UI Element is in. This property takes on an Array containing one or both of the following values:

  • selected
  • disabled

Solution Two: Adding Accessibility Hints

For this, we added a new property, accessibilityHint. Setting this property will allow Talkback or Voiceover to recite the hint to users.

accessibilityHint

This property takes in the accessibility hint to be read in the form of a String.

On iOS, setting this property will set the corresponding native property AccessibilityHint on the view. The hint will then be read by Voiceover if Accessibility Hints are turned on in the iPhone.

On Android, setting this property appends the value of the hint to the end of the accessibility label. The upside to this implementation is that it mimics the behavior of hints on iOS, but the downside to this implementation is that these hints cannot be turned off in the settings on Android the way they can be on iOS.

The reason we made this decision on Android is because normally, accessibility hints correspond with a specific action (e.g. click), and we wanted to keep behaviors consistent across platforms.

Solution to Problem Three

accessibilityIgnoresInvertColors

We exposed Apple's api AccessibilityIgnoresInvertColors to JavaScript, so now when you have a view where you don't want colors to be inverted (e.g image), you can set this property to true, and it won't be inverted.

New Usage

These new properties will become available in the React Native 0.57 release.

How to Upgrade

If you are currently using accessibilityComponentType and accessibilityTraits, here are the steps you can take to upgrade to the new properties.

1. Using jscodeshift

The most simple use cases can be replaced by running a jscodeshift script.

This script replaces the following instances:

accessibilityTraits=“trait”
accessibilityTraits={[“trait”]}

With

accessibilityRole= “trait”

This script also removes instances of AccessibilityComponentType (assuming everywhere you set AccessibilityComponentType, you would also set AccessibilityTraits).

2. Using a manual codemod

For the cases that used AccessibilityTraits that don't have a corresponding value for AccessibilityRole, and the cases where multiple traits were passed into AccessibilityTraits, a manual codemod would have to be done.

In general,

accessibilityTraits= {[“button”, “selected”]}

would be manually replaced with

accessibilityRole=“button”
accessibilityStates={[“selected”]}

These properties are already being used in Facebook's codebase. The codemod for Facebook was surprisingly simple. The jscodeshift script fixed about half of our instances, and the other half was fixed manually. Overall, the entire process took less than a few hours.

Hopefully you will find the updated API useful! And please continue making apps accessible! #inclusion

- + diff --git a/blog/2018/08/13/react-native-accessibility-updates/index.html b/blog/2018/08/13/react-native-accessibility-updates/index.html index a9d1746c3ed..f63eb25cb04 100644 --- a/blog/2018/08/13/react-native-accessibility-updates/index.html +++ b/blog/2018/08/13/react-native-accessibility-updates/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Accessibility API Updates

Ziqi Chen

Ziqi Chen

Student at UC Berkeley

Motivation

As technology advances and mobile apps become increasingly important to everyday life, the necessity of creating accessible applications has likewise grown in importance.

React Native's limited Accessibility API has always been a huge pain point for developers, so we've made a few updates to the Accessibility API to make it easier to create inclusive mobile applications.

Problems With the Existing API

Problem One: Two Completely Different Yet Similar Props - accessibilityComponentType (Android) and accessibilityTraits (iOS)

accessibilityComponentType and accessibilityTraits are two properties that are used to tell TalkBack on Android and VoiceOver on iOS what kind of UI element the user is interacting with. The two biggest problems with these properties are that:

  1. They are two different properties with different usage methods, yet have the same purpose. In the previous API, these are two separate properties (one for each platform), which was not only inconvenient, but also confusing to many developers. accessibilityTraits on iOS allows 17 different values while accessibilityComponentType on Android allows only 4 values. Furthermore, the values for the most part had no overlap. Even the input types for these two properties are different. accessibilityTraits allows either an array of traits to be passed in or a single trait, while accessibilityComponentType allows only a single value.
  2. There is very limited functionality on Android. With the old property, the only UI elements that Talkback were able to recognize were “button,” “radiobutton_checked,” and “radiobutton_unchecked.”

Problem Two: Non-existent Accessibility Hints:

Accessibility Hints help users using TalkBack or VoiceOver understand what will happen when they perform an action on an accessibility element that is not apparent by only the accessibility label. These hints can be turned on and off in the settings panel. Previously, React Native's API did not support accessibility hints at all.

Problem Three: Ignoring Inverted Colors:

Some users with vision loss use inverted colors on their mobile phones to have greater screen contrast. Apple provided an API for iOS which allows developers to ignore certain views. This way, images and videos aren't distorted when a user has the inverted colors setting on. This API is currently unsupported by React Native.

Design of the New API

Solution One: Combining accessibilityComponentType (Android) and accessibilityTraits (iOS)

In order to solve the confusion between accessibilityComponentType and accessibilityTraits, we decided to merge them into a single property. This made sense because they technically had the same intended functionality and by merging them, developers no longer had to worry about platform specific intricacies when building accessibility features.

Background

On iOS, UIAccessibilityTraits is a property that can be set on any NSObject. Each of the 17 traits passed in through the javascript property to native is mapped to a UIAccessibilityTraits element in Objective-C. Traits are each represented by a long int, and every trait that is set is ORed together.

On Android however, AccessibilityComponentType is a concept that was made up by React Native, and doesn't directly map to any properties in Android. Accessibility is handled by an accessibility delegate. Each view has a default accessibility delegate. If you want to customize any accessibility actions, you have to create a new accessibility delegate, override specific methods you want to customize, and then set the accessibility delegate of the view you are handling to be associated with the new delegate. When a developer set AccessibilityComponentType, the native code created a new delegate based off of the component that was passed in, and set the view to have that accessibility delegate.

Changes Made

For our new property, we wanted to create a superset of the two properties. We decided to keep the new property modeled mostly after the existing property accessibilityTraits, since accessibilityTraits has significantly more values. The functionality of Android for these traits would be polyfilled in by modifying the Accessibility Delegate.

There are 17 values of UIAccessibilityTraits that accessibilityTraits on iOS can be set to. However, we didn't include all of them as possible values to our new property. This is because the effect of setting some of these traits is actually not very well known, and many of these values are virtually never used.

The values UIAccessibilityTraits were set to generally took on one of two purposes. They either described a role that UI element had, or they described the state a UI element was in. Most uses of the previous properties we observed usually used one value that represented a role and combined it with either “state selected,” “state disabled,” or both. Therefore, we decided to create two new accessibility properties: accessibilityRole and accessibilityState.

accessibilityRole

The new property, accessibilityRole, is used to tell Talkback or Voiceover the role of a UI Element. This new property can take on one of the following values:

  • none
  • button
  • link
  • search
  • image
  • keyboardkey
  • text
  • adjustable
  • header
  • summary
  • imagebutton

This property only allows one value to be passed in because UI elements generally don't logically take on more than one of these. The exception is image and button, so we've added a role imagebutton that is a combination of both.

accessibilityStates

The new property, accessibilityStates, is used to tell Talkback or Voiceover the state a UI Element is in. This property takes on an Array containing one or both of the following values:

  • selected
  • disabled

Solution Two: Adding Accessibility Hints

For this, we added a new property, accessibilityHint. Setting this property will allow Talkback or Voiceover to recite the hint to users.

accessibilityHint

This property takes in the accessibility hint to be read in the form of a String.

On iOS, setting this property will set the corresponding native property AccessibilityHint on the view. The hint will then be read by Voiceover if Accessibility Hints are turned on in the iPhone.

On Android, setting this property appends the value of the hint to the end of the accessibility label. The upside to this implementation is that it mimics the behavior of hints on iOS, but the downside to this implementation is that these hints cannot be turned off in the settings on Android the way they can be on iOS.

The reason we made this decision on Android is because normally, accessibility hints correspond with a specific action (e.g. click), and we wanted to keep behaviors consistent across platforms.

Solution to Problem Three

accessibilityIgnoresInvertColors

We exposed Apple's api AccessibilityIgnoresInvertColors to JavaScript, so now when you have a view where you don't want colors to be inverted (e.g image), you can set this property to true, and it won't be inverted.

New Usage

These new properties will become available in the React Native 0.57 release.

How to Upgrade

If you are currently using accessibilityComponentType and accessibilityTraits, here are the steps you can take to upgrade to the new properties.

1. Using jscodeshift

The most simple use cases can be replaced by running a jscodeshift script.

This script replaces the following instances:

accessibilityTraits=“trait”
accessibilityTraits={[“trait”]}

With

accessibilityRole= “trait”

This script also removes instances of AccessibilityComponentType (assuming everywhere you set AccessibilityComponentType, you would also set AccessibilityTraits).

2. Using a manual codemod

For the cases that used AccessibilityTraits that don't have a corresponding value for AccessibilityRole, and the cases where multiple traits were passed into AccessibilityTraits, a manual codemod would have to be done.

In general,

accessibilityTraits= {[“button”, “selected”]}

would be manually replaced with

accessibilityRole=“button”
accessibilityStates={[“selected”]}

These properties are already being used in Facebook's codebase. The codemod for Facebook was surprisingly simple. The jscodeshift script fixed about half of our instances, and the other half was fixed manually. Overall, the entire process took less than a few hours.

Hopefully you will find the updated API useful! And please continue making apps accessible! #inclusion

- + diff --git a/blog/2018/08/27/wkwebview.html b/blog/2018/08/27/wkwebview.html index 8f170d68c4a..345b8dcb878 100644 --- a/blog/2018/08/27/wkwebview.html +++ b/blog/2018/08/27/wkwebview.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Introducing new iOS WebViews

Ramanpreet Nara

Software Engineer at Facebook

For a long time now, Apple has discouraged using UIWebViews in favor of WKWebView. In iOS 12, which will be released in the upcoming months, UIWebViews will be formally deprecated. React Native's iOS WebView implementation relies heavily on the UIWebView class. Therefore, in light of these developments, we've built a new native iOS backend to the WebView React Native component that uses WKWebView.

The tail end of these changes were landed in this commit, and will become available in the 0.57 release.

To opt into this new implementation, please use the useWebKit prop:

<WebView
useWebKit={true}
source={{ url: 'https://www.google.com' }}
/>

Improvements

UIWebView had no legitimate way to facilitate communication between the JavaScript running in the WebView, and React Native. When messages were sent from the WebView, we relied on a hack to deliver them to React Native. Succinctly, we encoded the message data into a url with a special scheme, and navigated the WebView to it. On the native side, we intercepted and cancelled this navigation, parsed the data from the url, and finally called into React Native. This implementation was error prone and insecure. I'm glad to announce that we've leveraged WKWebView features to completely replace it.

Other benefits of WKWebView over UIWebView include faster JavaScript execution, and a multi-process architecture. Please see this 2014 WWDC for more details.

Caveats

If your components use the following props, then you may experience problems when switching to WKWebView. For the time being, we suggest that you avoid using these props:

Inconsistent behavior:

automaticallyAdjustContentInsets and contentInsets (commit)

When you add contentInsets to a WKWebView, it doesn't change the WKWebView's viewport. The viewport remains the same size as the frame. With UIWebView, the viewport size actually changes (gets smaller, if the content insets are positive).

backgroundColor (commit)

With the new iOS implementation of WebView, there's a chance that your background color will flicker into view if you use this property. Furthermore, WKWebView renders transparent backgrounds differently from UIWebview. Please look at the commit description for more details.

Not supported:

scalesPageToFit (commit)

WKWebView didn't support the scalesPageToFit prop, so we couldn't implement this on the WebView React Native component.

- + diff --git a/blog/2018/08/27/wkwebview/index.html b/blog/2018/08/27/wkwebview/index.html index 8f170d68c4a..345b8dcb878 100644 --- a/blog/2018/08/27/wkwebview/index.html +++ b/blog/2018/08/27/wkwebview/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Introducing new iOS WebViews

Ramanpreet Nara

Software Engineer at Facebook

For a long time now, Apple has discouraged using UIWebViews in favor of WKWebView. In iOS 12, which will be released in the upcoming months, UIWebViews will be formally deprecated. React Native's iOS WebView implementation relies heavily on the UIWebView class. Therefore, in light of these developments, we've built a new native iOS backend to the WebView React Native component that uses WKWebView.

The tail end of these changes were landed in this commit, and will become available in the 0.57 release.

To opt into this new implementation, please use the useWebKit prop:

<WebView
useWebKit={true}
source={{ url: 'https://www.google.com' }}
/>

Improvements

UIWebView had no legitimate way to facilitate communication between the JavaScript running in the WebView, and React Native. When messages were sent from the WebView, we relied on a hack to deliver them to React Native. Succinctly, we encoded the message data into a url with a special scheme, and navigated the WebView to it. On the native side, we intercepted and cancelled this navigation, parsed the data from the url, and finally called into React Native. This implementation was error prone and insecure. I'm glad to announce that we've leveraged WKWebView features to completely replace it.

Other benefits of WKWebView over UIWebView include faster JavaScript execution, and a multi-process architecture. Please see this 2014 WWDC for more details.

Caveats

If your components use the following props, then you may experience problems when switching to WKWebView. For the time being, we suggest that you avoid using these props:

Inconsistent behavior:

automaticallyAdjustContentInsets and contentInsets (commit)

When you add contentInsets to a WKWebView, it doesn't change the WKWebView's viewport. The viewport remains the same size as the frame. With UIWebView, the viewport size actually changes (gets smaller, if the content insets are positive).

backgroundColor (commit)

With the new iOS implementation of WebView, there's a chance that your background color will flicker into view if you use this property. Furthermore, WKWebView renders transparent backgrounds differently from UIWebview. Please look at the commit description for more details.

Not supported:

scalesPageToFit (commit)

WKWebView didn't support the scalesPageToFit prop, so we couldn't implement this on the WebView React Native component.

- + diff --git a/blog/2018/11/01/oss-roadmap.html b/blog/2018/11/01/oss-roadmap.html index 5ff55fa7fde..885422093c7 100644 --- a/blog/2018/11/01/oss-roadmap.html +++ b/blog/2018/11/01/oss-roadmap.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Open Source Roadmap

Héctor Ramos

Héctor Ramos

Engineer at Facebook

This year, the React Native team has focused on a large scale re-architecture of React Native. As Sophie mentioned in her State of React Native post, we've sketched out a plan to better support the thriving population of React Native users and collaborators outside of Facebook. It's now time to share more details about what we've been working on. Before I do so, I'd like to lay out our long-term vision for React Native in open source.

Our vision for React Native is...

  • A healthy GitHub repository. Issues and pull requests get handled within a reasonable period of time.
    • Increased test coverage.
    • Commits that sync out from the Facebook code repository should not break open source tests.
    • A higher scale of meaningful community contributions.
  • Stable APIs, making it easier to interface with open source dependencies.
    • Facebook uses the same public API as open source
    • React Native releases that follow semantic versioning.
  • A vibrant eco-system. High quality ViewManagers, native modules, and multiple platform support maintained by the community.
  • Excellent documentation. Focus on helping users create high quality experiences, and up-to-date API reference docs.

We have identified the following focus areas to help us achieve this vision.

✂️ Lean Core

Our goal is to reduce the surface area of React Native by removing non-core and unused components. We'll transfer non-core components to the community to allow it to move faster. The reduced surface area will make it easier to manage contributions to React Native.

WebView is an example of a component that we transferred to the community. We are working on a workflow that will allow internal teams to continue using these components after we remove them from the repository. We have identified dozens more components that we'll give ownership of to the community.

🎁 Open Sourcing Internals and 🛠Updated Tooling

The React Native development experience for product teams at Facebook can be quite different from open source. Tools that may be popular in the open source community are not used at Facebook. There may be an internal tool that achieves the same purpose. In some cases, Facebook teams have become used to tools that do not exist outside of Facebook. These disparities can pose challenges when we open source our upcoming architecture work.

We'll work on releasing some of these internal tools. We'll also improve support for tools popular with the open source community. Here's a non-exhaustive list of projects we'll tackle:

  • Open source JSI and enable the community to bring their own JavaScript VMs, replacing the existing JavaScriptCore from RN's initial release. We'll be covering what JSI is in a future post, in the meantime you can learn more about JSI from Parashuram's talk at React Conf.
  • Support 64-bit libraries on Android.
  • Enable debugging under the new architecture.
  • Improve support for CocoaPods, Gradle, Maven, and new Xcode build system.

✅ Testing Infrastructure

When Facebook engineers publish code, it's considered safe to land if it passes all tests. These tests identify whether a change might break one of our own React Native surfaces. Yet, there are differences in how Facebook uses React Native. This has allowed us to unknowingly break React Native in open source.

We'll shore up our internal tests to ensure they run in an environment that is as close as possible to open source. This will help prevent code that breaks these tests from making it to open source. We will also work on infrastructure to enable better testing of the core repo on GitHub, enabling future pull requests to easily include tests.

Combined with the reduced surface area, this will allow contributors to merge pull requests quicker, with confidence.

📜 Public API

Facebook will consume React Native via the public API, the same way open source does, to reduce unintentional breaking changes. We have started converting internal call sites to address this. Our goal is to converge on a stable, public API, leading to the adoption of semantic versioning in version 1.0.

📣 Communication

React Native is one of the top open source projects on GitHub by contributor count. That makes us really happy, and we'd like to keep it going. We'll continue working on initiatives that lead to involved contributors, such as increased transparency and open discussion. The documentation is one of the first things someone new to React Native will encounter, yet it has not been a priority. We'd like to fix that, starting with bringing back auto-generated API reference docs, creating additional content focused on creating quality user experiences, and improving our release notes.

Timeline

We're planning to land these projects throughout the next year or so. Some of these efforts are already ongoing, such as JSI which has already landed in open source. Others will take a bit longer to complete, such as reducing the surface area. We'll do our best to keep the community up to date with our progress. Please join us in the Discussions and Proposals repository, a initiative from the React Native community that has led to the creation of several of the initiatives discussed in this roadmap.

- + diff --git a/blog/2018/11/01/oss-roadmap/index.html b/blog/2018/11/01/oss-roadmap/index.html index 5ff55fa7fde..885422093c7 100644 --- a/blog/2018/11/01/oss-roadmap/index.html +++ b/blog/2018/11/01/oss-roadmap/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Open Source Roadmap

Héctor Ramos

Héctor Ramos

Engineer at Facebook

This year, the React Native team has focused on a large scale re-architecture of React Native. As Sophie mentioned in her State of React Native post, we've sketched out a plan to better support the thriving population of React Native users and collaborators outside of Facebook. It's now time to share more details about what we've been working on. Before I do so, I'd like to lay out our long-term vision for React Native in open source.

Our vision for React Native is...

  • A healthy GitHub repository. Issues and pull requests get handled within a reasonable period of time.
    • Increased test coverage.
    • Commits that sync out from the Facebook code repository should not break open source tests.
    • A higher scale of meaningful community contributions.
  • Stable APIs, making it easier to interface with open source dependencies.
    • Facebook uses the same public API as open source
    • React Native releases that follow semantic versioning.
  • A vibrant eco-system. High quality ViewManagers, native modules, and multiple platform support maintained by the community.
  • Excellent documentation. Focus on helping users create high quality experiences, and up-to-date API reference docs.

We have identified the following focus areas to help us achieve this vision.

✂️ Lean Core

Our goal is to reduce the surface area of React Native by removing non-core and unused components. We'll transfer non-core components to the community to allow it to move faster. The reduced surface area will make it easier to manage contributions to React Native.

WebView is an example of a component that we transferred to the community. We are working on a workflow that will allow internal teams to continue using these components after we remove them from the repository. We have identified dozens more components that we'll give ownership of to the community.

🎁 Open Sourcing Internals and 🛠Updated Tooling

The React Native development experience for product teams at Facebook can be quite different from open source. Tools that may be popular in the open source community are not used at Facebook. There may be an internal tool that achieves the same purpose. In some cases, Facebook teams have become used to tools that do not exist outside of Facebook. These disparities can pose challenges when we open source our upcoming architecture work.

We'll work on releasing some of these internal tools. We'll also improve support for tools popular with the open source community. Here's a non-exhaustive list of projects we'll tackle:

  • Open source JSI and enable the community to bring their own JavaScript VMs, replacing the existing JavaScriptCore from RN's initial release. We'll be covering what JSI is in a future post, in the meantime you can learn more about JSI from Parashuram's talk at React Conf.
  • Support 64-bit libraries on Android.
  • Enable debugging under the new architecture.
  • Improve support for CocoaPods, Gradle, Maven, and new Xcode build system.

✅ Testing Infrastructure

When Facebook engineers publish code, it's considered safe to land if it passes all tests. These tests identify whether a change might break one of our own React Native surfaces. Yet, there are differences in how Facebook uses React Native. This has allowed us to unknowingly break React Native in open source.

We'll shore up our internal tests to ensure they run in an environment that is as close as possible to open source. This will help prevent code that breaks these tests from making it to open source. We will also work on infrastructure to enable better testing of the core repo on GitHub, enabling future pull requests to easily include tests.

Combined with the reduced surface area, this will allow contributors to merge pull requests quicker, with confidence.

📜 Public API

Facebook will consume React Native via the public API, the same way open source does, to reduce unintentional breaking changes. We have started converting internal call sites to address this. Our goal is to converge on a stable, public API, leading to the adoption of semantic versioning in version 1.0.

📣 Communication

React Native is one of the top open source projects on GitHub by contributor count. That makes us really happy, and we'd like to keep it going. We'll continue working on initiatives that lead to involved contributors, such as increased transparency and open discussion. The documentation is one of the first things someone new to React Native will encounter, yet it has not been a priority. We'd like to fix that, starting with bringing back auto-generated API reference docs, creating additional content focused on creating quality user experiences, and improving our release notes.

Timeline

We're planning to land these projects throughout the next year or so. Some of these efforts are already ongoing, such as JSI which has already landed in open source. Others will take a bit longer to complete, such as reducing the surface area. We'll do our best to keep the community up to date with our progress. Please join us in the Discussions and Proposals repository, a initiative from the React Native community that has led to the creation of several of the initiatives discussed in this roadmap.

- + diff --git a/blog/2019/01/07/state-of-react-native-community.html b/blog/2019/01/07/state-of-react-native-community.html index 0c6b26544d6..a0661a67e7c 100644 --- a/blog/2019/01/07/state-of-react-native-community.html +++ b/blog/2019/01/07/state-of-react-native-community.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

The State of the React Native Community in 2018

Lorenzo Sciandra

Lorenzo Sciandra

Core Maintainer & React Native Developer

In 2018 the React Native Community made a number of changes to the way we develop and communicate about React Native. We believe that a few years from now we will look back and see that this shift was a turning point for React Native.

A lot of people are excited about the rewrite of React Native's architecture, widely known as Fabric. Among other things, this will fix fundamental limitations in React Native's architecture and will set up React Native for success in the future together with JSI and TurboModules.

The biggest shift in 2018 was to empower the React Native Community. From the beginning, Facebook encouraged developers from all around the world to participate in React Native's open source project. Since then, a number of core contributors emerged to handle, among other things, the release process.

These members took a few substantial steps towards making the whole community more empowered to shape the future of this project with the following resources:

react-native-releases 📬

This repository, created in January, serves the dual purpose of allowing everyone to keep up the new releases in a more collaborative manner and opened the conversation of what would be part of a certain release to whomever wanted to suggest a cherry-pick (like for 0.57.8 and all its previous versions).

This has been the driving force behind moving away from a monthly release cycle, and the "long term support" approach currently used for version 0.57.x.

Half of the credit for reaching these decisions goes to the other repository created this year:

discussions-and-proposals 🗣

This repository, created in July, expanded on the idea of a more open environment for conversations on React Native. Previously, this need was handled by issues labelled For Discussion in the main repository, but we wanted to expand this strategy to an RFC approach that other libraries have (e.g. React).

This experiment immediately found its role in the React Native lifecycle. The Facebook team is now using the community RFC process to discuss what could be improved in React Native, and coordinate the efforts around the Lean Core project - among other interesting discussions.

@ReactNativeComm 🐣

We are aware that our approach to communicate these efforts has not been as effective as we would have liked, and in an attempt to give you all an easier time keeping up with everything going on in the React Native Community (from releases to active discussions) we created a new twitter account that you can rely on @ReactNativeComm.

If you are not on that social network, remember that you can always watch repositories via GitHub; this feature improved these past few months with the possibility of being notified only for releases, so you should consider using it anyway.

What awaits ahead 🎓

Over the past 7-8 months, core contributors enhanced the React Native Community GitHub organization to take more ownership over the development of React Native, and enhance collaboration with Facebook. But this always lacked the formal structure that similar projects may have in place.

This organization can set the example for everyone in the larger developer community by enforcing a set of standards for all the packages/repos hosted in it, providing a single place for maintainers to help each other and contribute quality code that conforms to community-agreed standards.

In early 2019, we will have this new set of guidelines in place. Let us know what you think in the dedicated discussion.

We are confident that with these changes, the community will become more collaborative so that when we reach 1.0, we will all continue to write (even more) awesome apps by leveraging this joint effort 🤗

I hope you are as excited as we are about the future of this community. We're excited to see all of you involved either in the conversations happening in the repositories listed above or via the awesome code you’ll produce.

Happy coding!

- + diff --git a/blog/2019/01/07/state-of-react-native-community/index.html b/blog/2019/01/07/state-of-react-native-community/index.html index 0c6b26544d6..a0661a67e7c 100644 --- a/blog/2019/01/07/state-of-react-native-community/index.html +++ b/blog/2019/01/07/state-of-react-native-community/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

The State of the React Native Community in 2018

Lorenzo Sciandra

Lorenzo Sciandra

Core Maintainer & React Native Developer

In 2018 the React Native Community made a number of changes to the way we develop and communicate about React Native. We believe that a few years from now we will look back and see that this shift was a turning point for React Native.

A lot of people are excited about the rewrite of React Native's architecture, widely known as Fabric. Among other things, this will fix fundamental limitations in React Native's architecture and will set up React Native for success in the future together with JSI and TurboModules.

The biggest shift in 2018 was to empower the React Native Community. From the beginning, Facebook encouraged developers from all around the world to participate in React Native's open source project. Since then, a number of core contributors emerged to handle, among other things, the release process.

These members took a few substantial steps towards making the whole community more empowered to shape the future of this project with the following resources:

react-native-releases 📬

This repository, created in January, serves the dual purpose of allowing everyone to keep up the new releases in a more collaborative manner and opened the conversation of what would be part of a certain release to whomever wanted to suggest a cherry-pick (like for 0.57.8 and all its previous versions).

This has been the driving force behind moving away from a monthly release cycle, and the "long term support" approach currently used for version 0.57.x.

Half of the credit for reaching these decisions goes to the other repository created this year:

discussions-and-proposals 🗣

This repository, created in July, expanded on the idea of a more open environment for conversations on React Native. Previously, this need was handled by issues labelled For Discussion in the main repository, but we wanted to expand this strategy to an RFC approach that other libraries have (e.g. React).

This experiment immediately found its role in the React Native lifecycle. The Facebook team is now using the community RFC process to discuss what could be improved in React Native, and coordinate the efforts around the Lean Core project - among other interesting discussions.

@ReactNativeComm 🐣

We are aware that our approach to communicate these efforts has not been as effective as we would have liked, and in an attempt to give you all an easier time keeping up with everything going on in the React Native Community (from releases to active discussions) we created a new twitter account that you can rely on @ReactNativeComm.

If you are not on that social network, remember that you can always watch repositories via GitHub; this feature improved these past few months with the possibility of being notified only for releases, so you should consider using it anyway.

What awaits ahead 🎓

Over the past 7-8 months, core contributors enhanced the React Native Community GitHub organization to take more ownership over the development of React Native, and enhance collaboration with Facebook. But this always lacked the formal structure that similar projects may have in place.

This organization can set the example for everyone in the larger developer community by enforcing a set of standards for all the packages/repos hosted in it, providing a single place for maintainers to help each other and contribute quality code that conforms to community-agreed standards.

In early 2019, we will have this new set of guidelines in place. Let us know what you think in the dedicated discussion.

We are confident that with these changes, the community will become more collaborative so that when we reach 1.0, we will all continue to write (even more) awesome apps by leveraging this joint effort 🤗

I hope you are as excited as we are about the future of this community. We're excited to see all of you involved either in the conversations happening in the repositories listed above or via the awesome code you’ll produce.

Happy coding!

- + diff --git a/blog/2019/03/01/react-native-open-source-update.html b/blog/2019/03/01/react-native-open-source-update.html index 368ee580489..6f6f3d3560a 100644 --- a/blog/2019/03/01/react-native-open-source-update.html +++ b/blog/2019/03/01/react-native-open-source-update.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native Open Source Update March 2019

Christoph Nakazawa

Christoph Nakazawa

Engineer at Facebook

We announced our React Native Open Source roadmap in Q4 2018 after deciding to invest more in the React Native open source community.

For our first milestone, we focused on identifying and improving the most visible aspects of our community. Our goals were to reduce outstanding pull requests, reduce the project's surface area, identify leading user problems, and establish guidelines for community management.

In the past two months, we made more progress than we expected. Read on for more details:

Pull Requests

In order to build a healthy community, we must respond quickly to code contributions. In past years, we de-prioritized reviewing community contributions and accumulated 280 pull requests (December 2018). In the first milestone, we reduced the number of open pull requests to ~65. Simultaneously, the average number of pull requests opened per day increased from 3.5 to 7 which means we have handled about 600 pull requests in the last three months.

We merged almost two-thirds and closed one-third of the pull requests. They were closed without being merged if they are obsolete or low quality, or if they unnecessarily increase the project's surface area. Most of the merged pull requests fixed bugs, improved cross-platform parity, or introduced new features. Notable contributions include improving type safety and the ongoing work to support AndroidX.

At Facebook, we run React Native from master, so we test all changes first before they make it into a React Native Release. Out of all the merged pull requests, only six caused issues: four only affected internal development and two were caught in the release candidate state.

One of the more visible community contributions was the updated “RedBox” screen. It's a good example of how the community is making the developer experience friendlier.

Lean Core

React Native currently has a very wide surface area with many unmaintained abstractions that we do not use a lot at Facebook. We are working on reducing the surface area in order to make React Native smaller and allow the community to take better care of abstractions that are mostly unused at Facebook.

In the first milestone, we asked the community for help on the Lean Core project. The response was overwhelming and we could barely keep up with all the progress. Check out all the work completed in less than a month!

What we are most excited about is that maintainers have jumped in fixing long standing issues, adding tests, and supporting long requested features. These modules are getting more support than they ever did within React Native, showing that this is a great step for the community. Examples of such projects are WebView that has received many pull requests since their extraction and the CLI that is now maintained by members of the community and received much needed improvements and fixes.

Leading User Problems

In December, we asked the community what they disliked about React Native. We aggregated the responses and replied to each and every problem. Fortunately, many of the issues that our community faces are also problems at Facebook. In our next milestone, we plan to address some of the main problems.

One of the highest voted problems was the developer experience of upgrading to newer versions of React Native. Unfortunately, this is not something that we experience ourselves because we run React Native from master. Thankfully, members from the community already stepped up to address this problem:

0.59 Release

Without the help of the React Native community, especially Mike Grabowski and Lorenzo Sciandra, we would not be able to ship releases. We want to improve the release management process and plan to be more involved from now on:

  • We will work with community members to create a blog post for each major release.
  • We will show breaking changes directly in the CLI when people upgrade to new versions.
  • We will reduce the time it takes to make a release. We are exploring ways to increase automated testing and also creating an improved manual test plan.

Many of these plans will be incorporated in the upcoming React Native 0.59 release. 0.59 will ship with React Hooks, a new 64-bit version of JavaScriptCore for Android, and many performance and functionality improvements. It is currently published as a release candidate and is expected to be stable within the next two weeks.

Next Steps

For the next two months, we will continue managing pull requests to stay on track while also starting to reduce the number of outstanding GitHub issues. We will continue reducing the surface area of React Native through the Lean Core project. We plan to address 5 of the top community problems. As we finalize the community guidelines, we will turn attention to our website and documentation.

We are very excited to host over ten contributors from our community at Facebook London in March to help drive several of these efforts. We are glad that you are using React Native and hope that you'll see and feel the improvements we are working on in 2019. We'll be back with another update in a few months and will be merging your pull requests in the meantime! ⚛️✌️

- + diff --git a/blog/2019/03/01/react-native-open-source-update/index.html b/blog/2019/03/01/react-native-open-source-update/index.html index 368ee580489..6f6f3d3560a 100644 --- a/blog/2019/03/01/react-native-open-source-update/index.html +++ b/blog/2019/03/01/react-native-open-source-update/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native Open Source Update March 2019

Christoph Nakazawa

Christoph Nakazawa

Engineer at Facebook

We announced our React Native Open Source roadmap in Q4 2018 after deciding to invest more in the React Native open source community.

For our first milestone, we focused on identifying and improving the most visible aspects of our community. Our goals were to reduce outstanding pull requests, reduce the project's surface area, identify leading user problems, and establish guidelines for community management.

In the past two months, we made more progress than we expected. Read on for more details:

Pull Requests

In order to build a healthy community, we must respond quickly to code contributions. In past years, we de-prioritized reviewing community contributions and accumulated 280 pull requests (December 2018). In the first milestone, we reduced the number of open pull requests to ~65. Simultaneously, the average number of pull requests opened per day increased from 3.5 to 7 which means we have handled about 600 pull requests in the last three months.

We merged almost two-thirds and closed one-third of the pull requests. They were closed without being merged if they are obsolete or low quality, or if they unnecessarily increase the project's surface area. Most of the merged pull requests fixed bugs, improved cross-platform parity, or introduced new features. Notable contributions include improving type safety and the ongoing work to support AndroidX.

At Facebook, we run React Native from master, so we test all changes first before they make it into a React Native Release. Out of all the merged pull requests, only six caused issues: four only affected internal development and two were caught in the release candidate state.

One of the more visible community contributions was the updated “RedBox” screen. It's a good example of how the community is making the developer experience friendlier.

Lean Core

React Native currently has a very wide surface area with many unmaintained abstractions that we do not use a lot at Facebook. We are working on reducing the surface area in order to make React Native smaller and allow the community to take better care of abstractions that are mostly unused at Facebook.

In the first milestone, we asked the community for help on the Lean Core project. The response was overwhelming and we could barely keep up with all the progress. Check out all the work completed in less than a month!

What we are most excited about is that maintainers have jumped in fixing long standing issues, adding tests, and supporting long requested features. These modules are getting more support than they ever did within React Native, showing that this is a great step for the community. Examples of such projects are WebView that has received many pull requests since their extraction and the CLI that is now maintained by members of the community and received much needed improvements and fixes.

Leading User Problems

In December, we asked the community what they disliked about React Native. We aggregated the responses and replied to each and every problem. Fortunately, many of the issues that our community faces are also problems at Facebook. In our next milestone, we plan to address some of the main problems.

One of the highest voted problems was the developer experience of upgrading to newer versions of React Native. Unfortunately, this is not something that we experience ourselves because we run React Native from master. Thankfully, members from the community already stepped up to address this problem:

0.59 Release

Without the help of the React Native community, especially Mike Grabowski and Lorenzo Sciandra, we would not be able to ship releases. We want to improve the release management process and plan to be more involved from now on:

  • We will work with community members to create a blog post for each major release.
  • We will show breaking changes directly in the CLI when people upgrade to new versions.
  • We will reduce the time it takes to make a release. We are exploring ways to increase automated testing and also creating an improved manual test plan.

Many of these plans will be incorporated in the upcoming React Native 0.59 release. 0.59 will ship with React Hooks, a new 64-bit version of JavaScriptCore for Android, and many performance and functionality improvements. It is currently published as a release candidate and is expected to be stable within the next two weeks.

Next Steps

For the next two months, we will continue managing pull requests to stay on track while also starting to reduce the number of outstanding GitHub issues. We will continue reducing the surface area of React Native through the Lean Core project. We plan to address 5 of the top community problems. As we finalize the community guidelines, we will turn attention to our website and documentation.

We are very excited to host over ten contributors from our community at Facebook London in March to help drive several of these efforts. We are glad that you are using React Native and hope that you'll see and feel the improvements we are working on in 2019. We'll be back with another update in a few months and will be merging your pull requests in the meantime! ⚛️✌️

- + diff --git a/blog/2019/03/12/releasing-react-native-059.html b/blog/2019/03/12/releasing-react-native-059.html index 4e7f30db3cc..2c80ed53388 100644 --- a/blog/2019/03/12/releasing-react-native-059.html +++ b/blog/2019/03/12/releasing-react-native-059.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Releasing React Native 0.59

Ryan Turner

Ryan Turner

Core Maintainer & React Native Developer

Welcome to the 0.59 release of React Native! This is another big release with 644 commits by 88 contributors. Contributions also come in other forms, so thank you for maintaining issues, fostering communities, and teaching people about React Native. This month brings a number of highly anticipated changes, and we hope you enjoy them.

🎣 Hooks are here

React Hooks are part of this release, which let you reuse stateful logic across components. There is a lot of buzz about hooks, but if you haven't heard, take a look at some of the wonderful resources below:

Be sure to give this a try in your apps. We hope that you find the reuse as exciting as we do.

📱 Updated JSC means performance gains and 64-bit support on Android

React Native uses JSC (JavaScriptCore) to power your application. JSC on Android was a few years old, which meant that a lot of modern JavaScript features weren't supported. Even worse, it performed poorly compared iOS's modern JSC. With this release, that all changes.

Thanks to some awesome work by @DanielZlotin, @dulmandakh, @gengjiawen, @kmagiera, and @kudo JSC has caught up with the past few years. This brings with it 64-bit support, modern JavaScript support, and big performance improvements. Kudos for also making this a maintainable process now so that we can take advantage of future WebKit improvements without so much legwork, and thank you Software Mansion and Expo for making this work possible.

💨 Faster app launches with inline requires

We want to help people have performant React Native apps by default and are working to bring Facebook's optimizations to the community. Applications load resources as needed rather than slowing down launch. This feature is called "inline requires", as it lets Metro identify components to be lazy loaded. Apps with a deep and varied component architecture will see the most improvement.

source of the `metro.config.js` file in the 0.59 template, demonstrating where to enable `inlineRequires`

We need the community to let us know how it works before we turn it on by default. When you upgrade to 0.59, there will be a new metro.config.js file; flip the options to true and give us your feedback! Read more about inline requires in the performance docs to benchmark your app.

🚅 Lean core is underway

React Native is a large and complex project with a complicated repository. This makes the codebase less approachable to contributors, difficult to test, and bloated as a dev dependency. Lean Core is our effort to address these issues by migrating code to separate libraries for better management. The past few releases have seen the first steps of this, but let's get serious.

You may notice that additional components are now officially deprecated. This is great news, as there are now owners for these features actively maintaining them. Heed the warning messages and migrate to the new libraries for these features, because they will be removed in a future release. Below is a table indicating the component, its status, and where you may migrate your use to.

ComponentDeprecated?New home
AsyncStorage0.59@react-native-community/react-native-async-storage
ImageStore0.59expo-file-system or react-native-fs
MaskedViewIOS0.59@react-native-community/react-native-masked-view
NetInfo0.59@react-native-community/react-native-netinfo
Slider0.59@react-native-community/react-native-slider
ViewPagerAndroid0.59@react-native-community/react-native-viewpager

Over the coming months, there will be many more components following this path to a leaner core. We're looking for help with this — head over to the lean core umbrella to pitch in.

👩🏽‍💻 CLI improvements

React Native's command line tools are developer's entry point to the ecosystem, but they had long-standing issues and lacked official support. The CLI tools have been moved to a new repository, and a dedicated group of maintainers have already made some exciting improvements.

Logs are formatted much better now. Commands now run nearly instantly — you'll immediately notice a difference:

0.58's CLI is slow to start0.58's CLI is nearly instantaneous

🚀 Upgrading to 0.59

We heard your feedback regarding the React Native upgrade process and we are taking steps to improve the experience in future releases. To upgrade to 0.59, we recommend using rn-diff-purge to determine what has changed between your current React Native version and 0.59, then applying those changes manually. Once you've upgraded your project to 0.59, you will be able to use the newly improved react-native upgrade command (based on rn-diff-purge!) to upgrade to 0.60 and beyond as newer releases become available.

🔨 Breaking Changes

Android support in 0.59 has been cleaned up following Google's latest recommendations, which may result in potential breakage of existing apps. This issue might present as a runtime crash and a message, "You need to use a Theme.AppCompat theme (or descendant) with this activity". We recommend updating your project's AndroidManifest.xml file, making sure that the android:theme value is an AppCompat theme (such as @style/Theme.AppCompat.Light.NoActionBar).

The react-native-git-upgrade command has been removed in 0.59, in favor of the newly improved react-native upgrade command.

🤗 Thanks

Lots of new contributors helped with enabling generation of native code from flow types and resolving Xcode warnings - these are a great way to learn how React Native works and contributing to the greater good. Thank you! Look out for similar issues in the future.

While these are the highlights that we noted, there are many others to be excited about. To see all of the updates, take a look at the changelog. 0.59 is a huge release – we can't wait for you to try it out.

We have even more improvements coming throughout the rest of the year. Stay tuned!

Ryan and the whole React Native core team

- + diff --git a/blog/2019/03/12/releasing-react-native-059/index.html b/blog/2019/03/12/releasing-react-native-059/index.html index 4e7f30db3cc..2c80ed53388 100644 --- a/blog/2019/03/12/releasing-react-native-059/index.html +++ b/blog/2019/03/12/releasing-react-native-059/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Releasing React Native 0.59

Ryan Turner

Ryan Turner

Core Maintainer & React Native Developer

Welcome to the 0.59 release of React Native! This is another big release with 644 commits by 88 contributors. Contributions also come in other forms, so thank you for maintaining issues, fostering communities, and teaching people about React Native. This month brings a number of highly anticipated changes, and we hope you enjoy them.

🎣 Hooks are here

React Hooks are part of this release, which let you reuse stateful logic across components. There is a lot of buzz about hooks, but if you haven't heard, take a look at some of the wonderful resources below:

Be sure to give this a try in your apps. We hope that you find the reuse as exciting as we do.

📱 Updated JSC means performance gains and 64-bit support on Android

React Native uses JSC (JavaScriptCore) to power your application. JSC on Android was a few years old, which meant that a lot of modern JavaScript features weren't supported. Even worse, it performed poorly compared iOS's modern JSC. With this release, that all changes.

Thanks to some awesome work by @DanielZlotin, @dulmandakh, @gengjiawen, @kmagiera, and @kudo JSC has caught up with the past few years. This brings with it 64-bit support, modern JavaScript support, and big performance improvements. Kudos for also making this a maintainable process now so that we can take advantage of future WebKit improvements without so much legwork, and thank you Software Mansion and Expo for making this work possible.

💨 Faster app launches with inline requires

We want to help people have performant React Native apps by default and are working to bring Facebook's optimizations to the community. Applications load resources as needed rather than slowing down launch. This feature is called "inline requires", as it lets Metro identify components to be lazy loaded. Apps with a deep and varied component architecture will see the most improvement.

source of the `metro.config.js` file in the 0.59 template, demonstrating where to enable `inlineRequires`

We need the community to let us know how it works before we turn it on by default. When you upgrade to 0.59, there will be a new metro.config.js file; flip the options to true and give us your feedback! Read more about inline requires in the performance docs to benchmark your app.

🚅 Lean core is underway

React Native is a large and complex project with a complicated repository. This makes the codebase less approachable to contributors, difficult to test, and bloated as a dev dependency. Lean Core is our effort to address these issues by migrating code to separate libraries for better management. The past few releases have seen the first steps of this, but let's get serious.

You may notice that additional components are now officially deprecated. This is great news, as there are now owners for these features actively maintaining them. Heed the warning messages and migrate to the new libraries for these features, because they will be removed in a future release. Below is a table indicating the component, its status, and where you may migrate your use to.

ComponentDeprecated?New home
AsyncStorage0.59@react-native-community/react-native-async-storage
ImageStore0.59expo-file-system or react-native-fs
MaskedViewIOS0.59@react-native-community/react-native-masked-view
NetInfo0.59@react-native-community/react-native-netinfo
Slider0.59@react-native-community/react-native-slider
ViewPagerAndroid0.59@react-native-community/react-native-viewpager

Over the coming months, there will be many more components following this path to a leaner core. We're looking for help with this — head over to the lean core umbrella to pitch in.

👩🏽‍💻 CLI improvements

React Native's command line tools are developer's entry point to the ecosystem, but they had long-standing issues and lacked official support. The CLI tools have been moved to a new repository, and a dedicated group of maintainers have already made some exciting improvements.

Logs are formatted much better now. Commands now run nearly instantly — you'll immediately notice a difference:

0.58's CLI is slow to start0.58's CLI is nearly instantaneous

🚀 Upgrading to 0.59

We heard your feedback regarding the React Native upgrade process and we are taking steps to improve the experience in future releases. To upgrade to 0.59, we recommend using rn-diff-purge to determine what has changed between your current React Native version and 0.59, then applying those changes manually. Once you've upgraded your project to 0.59, you will be able to use the newly improved react-native upgrade command (based on rn-diff-purge!) to upgrade to 0.60 and beyond as newer releases become available.

🔨 Breaking Changes

Android support in 0.59 has been cleaned up following Google's latest recommendations, which may result in potential breakage of existing apps. This issue might present as a runtime crash and a message, "You need to use a Theme.AppCompat theme (or descendant) with this activity". We recommend updating your project's AndroidManifest.xml file, making sure that the android:theme value is an AppCompat theme (such as @style/Theme.AppCompat.Light.NoActionBar).

The react-native-git-upgrade command has been removed in 0.59, in favor of the newly improved react-native upgrade command.

🤗 Thanks

Lots of new contributors helped with enabling generation of native code from flow types and resolving Xcode warnings - these are a great way to learn how React Native works and contributing to the greater good. Thank you! Look out for similar issues in the future.

While these are the highlights that we noted, there are many others to be excited about. To see all of the updates, take a look at the changelog. 0.59 is a huge release – we can't wait for you to try it out.

We have even more improvements coming throughout the rest of the year. Stay tuned!

Ryan and the whole React Native core team

- + diff --git a/blog/2019/05/01/react-native-at-f8-and-podcast.html b/blog/2019/05/01/react-native-at-f8-and-podcast.html index 6fc4ba62432..ceba8b13537 100644 --- a/blog/2019/05/01/react-native-at-f8-and-podcast.html +++ b/blog/2019/05/01/react-native-at-f8-and-podcast.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native at F8 and Open Source Podcast

Christoph Nakazawa

Christoph Nakazawa

Engineer at Facebook

This week, Eli White gave a talk at F8 2019 about React Native in Facebook's Android and iOS applications. We are excited to share what we've been up to for the past two years and what we're doing next.

Check out the video on Facebook's developer website:

F8 Talk about React Native

Highlights from the talk:

  • We spent 2017 and 2018 focused on React Native's largest product, Facebook's Marketplace. We collaborated with the Marketplace team to improve quality and add delight to the product. At this point, Marketplace is one of the highest quality products in the Facebook app both on Android and iOS.
  • Marketplace's performance was a big challenge as well, especially on mid-end Android devices. We cut startup time by more than 50% over the last year with more improvements on the way! The biggest improvements are being built into React Native and will be coming to the community later this year.
  • We have the confidence that we can build the high quality and performant apps that Facebook needs with React Native. This confidence has let us invest in bigger bets, like rethinking the core of React Native.
  • Microsoft supports and uses React Native for Windows, enabling people to use their expertise and codebase to render to Microsofts's Universal Windows Platform. Check out Microsoft Build next week to hear them talk about that more.

React Radio Podcast about Open Source

Eli's talk concludes by talking about our recent open source work. We gave an update on our progress in March and recently Nader Dabit and Gant Laborde invited Christoph for a chat on their podcast, React Native Radio, to chat about React Native in open source.

Highlights from the podcast:

  • We talked about how the React Native team at Facebook thinks about open source and how we are building a sustainable community that scales for a project of React Native's size.
  • We are on track to remove multiple modules as part of the Lean Core effort. Many modules like WebView and the React Native CLI have received more than 100 Pull Requests since they were extracted.
  • Next, we'll be focusing on overhauling the React Native website and documentation. Stay tuned!

You'll find the episode in your favorite podcasting app soon or you can listen to the recording right here:

- + diff --git a/blog/2019/05/01/react-native-at-f8-and-podcast/index.html b/blog/2019/05/01/react-native-at-f8-and-podcast/index.html index 6fc4ba62432..ceba8b13537 100644 --- a/blog/2019/05/01/react-native-at-f8-and-podcast/index.html +++ b/blog/2019/05/01/react-native-at-f8-and-podcast/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native at F8 and Open Source Podcast

Christoph Nakazawa

Christoph Nakazawa

Engineer at Facebook

This week, Eli White gave a talk at F8 2019 about React Native in Facebook's Android and iOS applications. We are excited to share what we've been up to for the past two years and what we're doing next.

Check out the video on Facebook's developer website:

F8 Talk about React Native

Highlights from the talk:

  • We spent 2017 and 2018 focused on React Native's largest product, Facebook's Marketplace. We collaborated with the Marketplace team to improve quality and add delight to the product. At this point, Marketplace is one of the highest quality products in the Facebook app both on Android and iOS.
  • Marketplace's performance was a big challenge as well, especially on mid-end Android devices. We cut startup time by more than 50% over the last year with more improvements on the way! The biggest improvements are being built into React Native and will be coming to the community later this year.
  • We have the confidence that we can build the high quality and performant apps that Facebook needs with React Native. This confidence has let us invest in bigger bets, like rethinking the core of React Native.
  • Microsoft supports and uses React Native for Windows, enabling people to use their expertise and codebase to render to Microsofts's Universal Windows Platform. Check out Microsoft Build next week to hear them talk about that more.

React Radio Podcast about Open Source

Eli's talk concludes by talking about our recent open source work. We gave an update on our progress in March and recently Nader Dabit and Gant Laborde invited Christoph for a chat on their podcast, React Native Radio, to chat about React Native in open source.

Highlights from the podcast:

  • We talked about how the React Native team at Facebook thinks about open source and how we are building a sustainable community that scales for a project of React Native's size.
  • We are on track to remove multiple modules as part of the Lean Core effort. Many modules like WebView and the React Native CLI have received more than 100 Pull Requests since they were extracted.
  • Next, we'll be focusing on overhauling the React Native website and documentation. Stay tuned!

You'll find the episode in your favorite podcasting app soon or you can listen to the recording right here:

- + diff --git a/blog/2019/06/12/react-native-open-source-update.html b/blog/2019/06/12/react-native-open-source-update.html index a7f13968df0..ebfa6de2abc 100644 --- a/blog/2019/06/12/react-native-open-source-update.html +++ b/blog/2019/06/12/react-native-open-source-update.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native Open Source Update June 2019

Christoph Nakazawa

Christoph Nakazawa

Engineer at Facebook

Code & Community Health

In the past six months, a total of 2800 commits were made to React Native by more than 550 contributors. 400 contributors from the community created more than 1,150 Pull Requests, of which 820 Pull Requests were merged.

The average number of Pull Requests per day throughout the past six months has increased from three to about six, even though we split the website, CLI and many modules out of React Native via the Lean Core effort. The average amount of open pull requests is now below 25 and we usually reply with suggestions and reviews within hours or days.

Meaningful Community Contributions

We’d like to highlight a number of recent contributions which we thought were awesome:

Lean Core

The primary motivation of Lean Core has been to split modules out of React Native into separate repositories so they can receive better maintenance. In just a six months repositories like WebView, NetInfo, AsyncStorage, the website and the CLI received more than 800 Pull Requests combined. Besides better maintenance, these projects can also be independently released more often than React Native itself.

We have also taken the opportunity to remove obsolete polyfills and legacy components from React Native itself. Polyfills were necessary in the past to support language features like Map and Set in older versions of JavaScriptCore (JSC). Now that React Native ships with a new version, these polyfills were removed.

This work is still in progress and many more things still need to be split out or removed both on the native and JavaScript side but there are early signs that we managed to reverse the trend of increasing the surface area and app size: When looking at the JavaScript bundle for example, about a year ago in version 0.54 the React Native JavaScript bundle size was 530kb and grew to 607kb (+77kb) by version 0.57 in just 6 months. Now we are seeing a bundle size reduction of 28kb down to 579kb on master, a delta of more than 100kb!

As we conclude the first iteration of the Lean Core effort, we will make an effort to be more intentional about new APIs added to React Native and we will continuously evaluate ways to make React Native smaller and faster, as well as finding ways to empower the community to take ownership of various components.

User Feedback

Six months ago we asked the community “What do you dislike about React Native?” which gave a good overview of problems people are facing. We replied to the post a few months ago and it's time to summarize the progress that was made on top issues:

  • Upgrading: The React Native community rallied around with multiple improvements to the upgrading experience: autolinking, a better upgrading command via rn-diff-purge, an upgrade helper website (coming soon). We’ll also make sure to communicate breaking changes and exciting new features by publishing blog posts for each major release. Many of these improvements will make future upgrades beyond the 0.60 release significantly easier.
  • Support / Uncertainty: Many people were frustrated with the lack of activity on Pull Requests and general uncertainty about Facebook's investment in React Native. As we've shown above, we can confidently say that we are ready for many more Pull Requests and we are eagerly looking forward to your proposals and contributions!
  • Performance: React Native 0.59 shipped with a new and much faster version of JavaScriptCore (JSC). Separately, we have been working on making it easier to enable inline-requires by default and we have more exciting updates for you in the next couple of months.
  • Documentation: We recently started an effort to overhaul and rewrite all of React Native's documentation. If you are looking to contribute, we’d love to get your help!
  • Warnings in Xcode: We got rid of all the existing warnings and are making an effort not to introduce new warnings.
  • Hot Reloading: The React team is building a new hot reloading system that will soon be integrated into React Native.

Unfortunately we weren’t able to improve everything just yet:

  • Debugging: We fixed many inconvenient bugs and issues people that we have been running into every day, but unfortunately we haven't made as much progress on this as we would like. We recognize that debugging with React Native isn't great and we'll prioritize improving this in the future.
  • Metro symlinks: Unfortunately we haven't been able to implement a simple and straightforward solution for this yet. However, React Native users shared various workarounds that may work for you.

Given the large amount of changes in the past six months, we'd like to ask you the same question again. If you are using the latest version of React Native and you have things you'd like to give feedback on, please comment on our new edition of “What do you dislike about React Native?”

Continuous Integration

Facebook merges all Pull Requests and internal changes directly into Facebook’s repository first and then syncs all commits back to GitHub. Facebook’s infrastructure is different from common continuous integration services and not all open source tests were run inside of Facebook. This means that commits that sync out to GitHub frequently break tests in open source which take a lot of time to fix.

Héctor Ramos from the React Native team spent the past two months improving React Native's continuous integration systems both at Facebook and on GitHub. Most of the open source tests are now run before changes are committed to React Native at Facebook which will keep CI stable on GitHub when commits are being synchronized.

Next

Make sure to check out our talks about the future of React Native! In the next couple of months, members of the React Native team at Facebook will speak at Chain React and at React Native EU. Also, watch out for our next release, 0.60, which is right around the corner. It's going to be exciting ✨

- + diff --git a/blog/2019/06/12/react-native-open-source-update/index.html b/blog/2019/06/12/react-native-open-source-update/index.html index a7f13968df0..ebfa6de2abc 100644 --- a/blog/2019/06/12/react-native-open-source-update/index.html +++ b/blog/2019/06/12/react-native-open-source-update/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native Open Source Update June 2019

Christoph Nakazawa

Christoph Nakazawa

Engineer at Facebook

Code & Community Health

In the past six months, a total of 2800 commits were made to React Native by more than 550 contributors. 400 contributors from the community created more than 1,150 Pull Requests, of which 820 Pull Requests were merged.

The average number of Pull Requests per day throughout the past six months has increased from three to about six, even though we split the website, CLI and many modules out of React Native via the Lean Core effort. The average amount of open pull requests is now below 25 and we usually reply with suggestions and reviews within hours or days.

Meaningful Community Contributions

We’d like to highlight a number of recent contributions which we thought were awesome:

Lean Core

The primary motivation of Lean Core has been to split modules out of React Native into separate repositories so they can receive better maintenance. In just a six months repositories like WebView, NetInfo, AsyncStorage, the website and the CLI received more than 800 Pull Requests combined. Besides better maintenance, these projects can also be independently released more often than React Native itself.

We have also taken the opportunity to remove obsolete polyfills and legacy components from React Native itself. Polyfills were necessary in the past to support language features like Map and Set in older versions of JavaScriptCore (JSC). Now that React Native ships with a new version, these polyfills were removed.

This work is still in progress and many more things still need to be split out or removed both on the native and JavaScript side but there are early signs that we managed to reverse the trend of increasing the surface area and app size: When looking at the JavaScript bundle for example, about a year ago in version 0.54 the React Native JavaScript bundle size was 530kb and grew to 607kb (+77kb) by version 0.57 in just 6 months. Now we are seeing a bundle size reduction of 28kb down to 579kb on master, a delta of more than 100kb!

As we conclude the first iteration of the Lean Core effort, we will make an effort to be more intentional about new APIs added to React Native and we will continuously evaluate ways to make React Native smaller and faster, as well as finding ways to empower the community to take ownership of various components.

User Feedback

Six months ago we asked the community “What do you dislike about React Native?” which gave a good overview of problems people are facing. We replied to the post a few months ago and it's time to summarize the progress that was made on top issues:

  • Upgrading: The React Native community rallied around with multiple improvements to the upgrading experience: autolinking, a better upgrading command via rn-diff-purge, an upgrade helper website (coming soon). We’ll also make sure to communicate breaking changes and exciting new features by publishing blog posts for each major release. Many of these improvements will make future upgrades beyond the 0.60 release significantly easier.
  • Support / Uncertainty: Many people were frustrated with the lack of activity on Pull Requests and general uncertainty about Facebook's investment in React Native. As we've shown above, we can confidently say that we are ready for many more Pull Requests and we are eagerly looking forward to your proposals and contributions!
  • Performance: React Native 0.59 shipped with a new and much faster version of JavaScriptCore (JSC). Separately, we have been working on making it easier to enable inline-requires by default and we have more exciting updates for you in the next couple of months.
  • Documentation: We recently started an effort to overhaul and rewrite all of React Native's documentation. If you are looking to contribute, we’d love to get your help!
  • Warnings in Xcode: We got rid of all the existing warnings and are making an effort not to introduce new warnings.
  • Hot Reloading: The React team is building a new hot reloading system that will soon be integrated into React Native.

Unfortunately we weren’t able to improve everything just yet:

  • Debugging: We fixed many inconvenient bugs and issues people that we have been running into every day, but unfortunately we haven't made as much progress on this as we would like. We recognize that debugging with React Native isn't great and we'll prioritize improving this in the future.
  • Metro symlinks: Unfortunately we haven't been able to implement a simple and straightforward solution for this yet. However, React Native users shared various workarounds that may work for you.

Given the large amount of changes in the past six months, we'd like to ask you the same question again. If you are using the latest version of React Native and you have things you'd like to give feedback on, please comment on our new edition of “What do you dislike about React Native?”

Continuous Integration

Facebook merges all Pull Requests and internal changes directly into Facebook’s repository first and then syncs all commits back to GitHub. Facebook’s infrastructure is different from common continuous integration services and not all open source tests were run inside of Facebook. This means that commits that sync out to GitHub frequently break tests in open source which take a lot of time to fix.

Héctor Ramos from the React Native team spent the past two months improving React Native's continuous integration systems both at Facebook and on GitHub. Most of the open source tests are now run before changes are committed to React Native at Facebook which will keep CI stable on GitHub when commits are being synchronized.

Next

Make sure to check out our talks about the future of React Native! In the next couple of months, members of the React Native team at Facebook will speak at Chain React and at React Native EU. Also, watch out for our next release, 0.60, which is right around the corner. It's going to be exciting ✨

- + diff --git a/blog/2019/07/03/version-60.html b/blog/2019/07/03/version-60.html index af7946f2255..3b6e318527e 100644 --- a/blog/2019/07/03/version-60.html +++ b/blog/2019/07/03/version-60.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Announcing React Native 0.60

Ryan Turner

Ryan Turner

Core Maintainer & React Native Developer

After months of hard work from hundreds of contributors, the React Native Core team is proud to announce the release of version 0.60. This release handles significant migrations for both Android and iOS platforms, and many issues are resolved too. This blog post covers the highlights of the release. As always though, refer to the changelog for more detailed information. Finally, thank you contributors for helping us to make this milestone!

Focus on Accessibility

There have been many improvements to the accessibility APIs, like announceForAccessibility, plus improvements to roles, action support, flags, and more. Accessibility is a complex science, but we hope these improvements make it a bit easier to be an A11Y. Be sure to check React Native Open Source Update June 2019 for more details of these changes.

A Fresh Start

React Native's start screen has been updated! Thank you to the many contributors who helped create the new UI. This new "Hello World" will welcome users to the ecosystem in a more friendly, engaging way.

The new init screen helps developers get started from the get-go with resources and a good example

AndroidX Support

AndroidX is a major step forward in the Android ecosystem, and the old support library artifacts are being deprecated. For 0.60, React Native has been migrated over to AndroidX. This is a breaking change, and your native code and dependencies will need to be migrated as well.

With this change, React Native apps will need to begin using AndroidX themselves. They cannot be used side-by-side in one app, so all of the app code and dependency code needs to be using one or the other.

matt-oakes on discussions-and-proposals

While your own native code will need to be migrated by you, @mikehardy, @cawfree, and @m4tt72 built a clever tool named "jetifier" to patch your node_modules. Library maintainers will need to upgrade, but this tool provide you with a temporary solution while giving them time to release an AndroidX version. So if you find errors related to AndroidX migration, give this a shot.

CocoaPods by Default

CocoaPods are now part of React Native's iOS project. If you weren't already, be sure to open iOS platform code using the xcworkspace file from now on (protip: try xed ios from the root project directory). Also, the podspecs for the internal packages have changed to make them compatible with the Xcode projects, which will help with troubleshooting and debugging. Expect to make some straightforward changes to your Podfile as part of the upgrade to 0.60 to bring this exciting support. Note that we are aware of a compatibility issue with use_frameworks!, and we're tracking an issue with workarounds and a future patch.

Lean Core Removals

WebView and NetInfo were previously extracted into separate repositories, and in 0.60 we’ve finished migrating them out of the React Native repository. Additionally, in response to community feedback about new App Store policy, Geolocation has been extracted. If you haven’t already, complete your migration by adding dependencies to react-native-webview, @react-native-community/netinfo, and @react-native-community/geolocation. If you'd like an automated solution, consider using rn-upgrade-deprecated-modules. Maintainers have made more than 100 commits to these repositories since extraction and we’re excited to see the community’s support!

Native Modules are now Autolinked

The team working on the React Native CLI has introduced major improvements to native module linking called autolinking! Most scenarios will not require the use of react-native link anymore. At the same time, the team overhauled the linking process in general. Be sure to react-native unlink any preexisting dependencies as mentioned in the docs above.

Upgrade Helper

@lucasbento, @pvinis, @kelset, and @watadarkstar have built a great tool called Upgrade Helper to make the upgrade process simpler. It helps React Native users with brownfield apps or complex customizations to see what's changed between versions. Take a look at the updated upgrading docs and try it out today for your upgrade path!

Upgrade Helper cleanly and easily shows the changes needed to migrate to a different version of React Native

A Note to Library Maintainers

Changes for AndroidX will almost certainly require updates to your library, so be sure to include support soon. If you're not able to upgrade yet, consider checking your library against the jetifier to confirm that users are able to patch your library at build time.

Review the autolinking docs to update your configs and readme. Depending on how your library was previously integrated, you may also need to make some additional changes. Check the dependencies guide from the CLI for information on how to define your dependency interface.

Thanks

While these are the highlights that we noted, there are many others to be excited about. To see all the updates, take a look at the changelog. As always, stay tuned for more news. Enjoy 0.60 in the meantime!

- + diff --git a/blog/2019/07/03/version-60/index.html b/blog/2019/07/03/version-60/index.html index af7946f2255..3b6e318527e 100644 --- a/blog/2019/07/03/version-60/index.html +++ b/blog/2019/07/03/version-60/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Announcing React Native 0.60

Ryan Turner

Ryan Turner

Core Maintainer & React Native Developer

After months of hard work from hundreds of contributors, the React Native Core team is proud to announce the release of version 0.60. This release handles significant migrations for both Android and iOS platforms, and many issues are resolved too. This blog post covers the highlights of the release. As always though, refer to the changelog for more detailed information. Finally, thank you contributors for helping us to make this milestone!

Focus on Accessibility

There have been many improvements to the accessibility APIs, like announceForAccessibility, plus improvements to roles, action support, flags, and more. Accessibility is a complex science, but we hope these improvements make it a bit easier to be an A11Y. Be sure to check React Native Open Source Update June 2019 for more details of these changes.

A Fresh Start

React Native's start screen has been updated! Thank you to the many contributors who helped create the new UI. This new "Hello World" will welcome users to the ecosystem in a more friendly, engaging way.

The new init screen helps developers get started from the get-go with resources and a good example

AndroidX Support

AndroidX is a major step forward in the Android ecosystem, and the old support library artifacts are being deprecated. For 0.60, React Native has been migrated over to AndroidX. This is a breaking change, and your native code and dependencies will need to be migrated as well.

With this change, React Native apps will need to begin using AndroidX themselves. They cannot be used side-by-side in one app, so all of the app code and dependency code needs to be using one or the other.

matt-oakes on discussions-and-proposals

While your own native code will need to be migrated by you, @mikehardy, @cawfree, and @m4tt72 built a clever tool named "jetifier" to patch your node_modules. Library maintainers will need to upgrade, but this tool provide you with a temporary solution while giving them time to release an AndroidX version. So if you find errors related to AndroidX migration, give this a shot.

CocoaPods by Default

CocoaPods are now part of React Native's iOS project. If you weren't already, be sure to open iOS platform code using the xcworkspace file from now on (protip: try xed ios from the root project directory). Also, the podspecs for the internal packages have changed to make them compatible with the Xcode projects, which will help with troubleshooting and debugging. Expect to make some straightforward changes to your Podfile as part of the upgrade to 0.60 to bring this exciting support. Note that we are aware of a compatibility issue with use_frameworks!, and we're tracking an issue with workarounds and a future patch.

Lean Core Removals

WebView and NetInfo were previously extracted into separate repositories, and in 0.60 we’ve finished migrating them out of the React Native repository. Additionally, in response to community feedback about new App Store policy, Geolocation has been extracted. If you haven’t already, complete your migration by adding dependencies to react-native-webview, @react-native-community/netinfo, and @react-native-community/geolocation. If you'd like an automated solution, consider using rn-upgrade-deprecated-modules. Maintainers have made more than 100 commits to these repositories since extraction and we’re excited to see the community’s support!

Native Modules are now Autolinked

The team working on the React Native CLI has introduced major improvements to native module linking called autolinking! Most scenarios will not require the use of react-native link anymore. At the same time, the team overhauled the linking process in general. Be sure to react-native unlink any preexisting dependencies as mentioned in the docs above.

Upgrade Helper

@lucasbento, @pvinis, @kelset, and @watadarkstar have built a great tool called Upgrade Helper to make the upgrade process simpler. It helps React Native users with brownfield apps or complex customizations to see what's changed between versions. Take a look at the updated upgrading docs and try it out today for your upgrade path!

Upgrade Helper cleanly and easily shows the changes needed to migrate to a different version of React Native

A Note to Library Maintainers

Changes for AndroidX will almost certainly require updates to your library, so be sure to include support soon. If you're not able to upgrade yet, consider checking your library against the jetifier to confirm that users are able to patch your library at build time.

Review the autolinking docs to update your configs and readme. Depending on how your library was previously integrated, you may also need to make some additional changes. Check the dependencies guide from the CLI for information on how to define your dependency interface.

Thanks

While these are the highlights that we noted, there are many others to be excited about. To see all the updates, take a look at the changelog. As always, stay tuned for more news. Enjoy 0.60 in the meantime!

- + diff --git a/blog/2019/07/17/hermes.html b/blog/2019/07/17/hermes.html index ac0e539e525..c34df04b3ed 100644 --- a/blog/2019/07/17/hermes.html +++ b/blog/2019/07/17/hermes.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Meet Hermes, a new JavaScript Engine optimized for React Native

Rachel Nabors

Rachel Nabors

Documentation Engineer at Facebook

Last week at Chain React we announced Hermes, an open source JavaScript engine we’ve been working on at Facebook. It’s a small and lightweight JavaScript engine optimized for running React Native on Android. Check it out!

Hermes improves React Native performance by decreasing memory utilization, reducing download size, and decreasing the time it takes for the app to become usable or “time to interactive” (TTI).

“As we analyzed performance data, we noticed that the JavaScript engine itself was a significant factor in startup performance and download size. With this data in hand, we knew we had to optimize JavaScript performance in the more constrained environments of a mobile phone compared with a desktop or laptop. After exploring other options, we built a new JavaScript engine we call Hermes. It is designed to improve app performance, focusing on our React Native apps, even on mass-market devices with limited memory, slow storage, and reduced computing power.” —Hermes: An open source JavaScript engine optimized for mobile apps, starting with React Native

Want to get started right away? Be sure to check out our new guide to enabling Hermes in your existing React Native app in the docs!

Illustration of the Hermes and React Native logos joined into a winged fury, rising in a crashing electrical storm from a lone, glowing, presumably Android phone. Illustration by Rachel Nabors

- + diff --git a/blog/2019/07/17/hermes/index.html b/blog/2019/07/17/hermes/index.html index ac0e539e525..c34df04b3ed 100644 --- a/blog/2019/07/17/hermes/index.html +++ b/blog/2019/07/17/hermes/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Meet Hermes, a new JavaScript Engine optimized for React Native

Rachel Nabors

Rachel Nabors

Documentation Engineer at Facebook

Last week at Chain React we announced Hermes, an open source JavaScript engine we’ve been working on at Facebook. It’s a small and lightweight JavaScript engine optimized for running React Native on Android. Check it out!

Hermes improves React Native performance by decreasing memory utilization, reducing download size, and decreasing the time it takes for the app to become usable or “time to interactive” (TTI).

“As we analyzed performance data, we noticed that the JavaScript engine itself was a significant factor in startup performance and download size. With this data in hand, we knew we had to optimize JavaScript performance in the more constrained environments of a mobile phone compared with a desktop or laptop. After exploring other options, we built a new JavaScript engine we call Hermes. It is designed to improve app performance, focusing on our React Native apps, even on mass-market devices with limited memory, slow storage, and reduced computing power.” —Hermes: An open source JavaScript engine optimized for mobile apps, starting with React Native

Want to get started right away? Be sure to check out our new guide to enabling Hermes in your existing React Native app in the docs!

Illustration of the Hermes and React Native logos joined into a winged fury, rising in a crashing electrical storm from a lone, glowing, presumably Android phone. Illustration by Rachel Nabors

- + diff --git a/blog/2019/09/18/version-0.61.html b/blog/2019/09/18/version-0.61.html index 3b26ee75e5c..c72e4d17806 100644 --- a/blog/2019/09/18/version-0.61.html +++ b/blog/2019/09/18/version-0.61.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Announcing React Native 0.61 with Fast Refresh

Dan Abramov

Dan Abramov

React Core at Facebook

We’re excited to announce React Native 0.61, which includes a new reloading experience we’re calling Fast Refresh.

Fast Refresh

When we asked the React Native community about common pain points, one of the top answers was that the “hot reloading” feature was broken. It didn’t work reliably for function components, often failed to update the screen, and wasn’t resilient to typos and mistakes. We heard that most people turned it off because it was too unreliable.

In React Native 0.61, we’re unifying the existing “live reloading” (reload on save) and “hot reloading” features into a single new feature called “Fast Refresh”. Fast Refresh was implemented from scratch with the following principles:

  • Fast Refresh fully supports modern React, including function components and Hooks.
  • Fast Refresh gracefully recovers after typos and other mistakes, and falls back to a full reload when needed.
  • Fast Refresh doesn’t perform invasive code transformations so it’s reliable enough to be on by default.

To see Fast Refresh in action, check out this video:

Give it a try, and let us know what you think! If you prefer, you can turn it off in the Dev Menu (Cmd+D on iOS, Cmd+M or Ctrl+M on Android). Turning it on and off is instant so you can do it any time.

Here are a few Fast Refresh tips:

  • Fast Refresh preserves React local state in function components (and Hooks!) by default.
  • If you need to reset the React state on every edit, you can add a special // @refresh reset comment to the file with that component.
  • Fast Refresh always remounts class components without preserving state. This ensures it works reliably.
  • We all make mistakes in the code! Fast Refresh automatically retries rendering after you save a file. You don't need to reload the app manually after fixing a syntax or a runtime error.
  • Adding a console.log or a debugger statement during edits is a neat debugging technique.

Please report any issues with Fast Refresh on GitHub, and we’ll look into them.

Other Improvements

  • Fixed use_frameworks! CocoaPods support. In 0.60 we made some updates to integrate CocoaPods by default. Unfortunately, this broke builds using use_frameworks!. This is fixed in 0.61, making it easier to integrate React Native into your iOS projects that require building with dynamic frameworks.
  • Add useWindowDimensions Hook. This new Hook automatically provides and subscribes to dimension updates, and can be used instead of the Dimensions API in most cases.
  • React was upgraded to 16.9. This version deprecates old names for the UNSAFE_ lifecycle methods, contains improvements to act, and more. See the React 16.9 blog post for an automated migration script and more information.

Breaking Changes

  • Remove React .xcodeproj. In 0.60, we introduced auto-linking support via CocoaPods. We have also integrated CocoaPods into the e2e tests runs, so that from now on, we have a unified standard way of integrating RN into iOS apps. This effectively deprecates the React .xcodeproj support, and the file has been removed starting 0.61. Note: if you use 0.60 auto-linking already, you shouldn't be affected.

Thanks

Thanks to all of the contributors that helped make 0.61 possible!

To see all the updates, take a look at the 0.61 changelog.

- + diff --git a/blog/2019/09/18/version-0.61/index.html b/blog/2019/09/18/version-0.61/index.html index 3b26ee75e5c..c72e4d17806 100644 --- a/blog/2019/09/18/version-0.61/index.html +++ b/blog/2019/09/18/version-0.61/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Announcing React Native 0.61 with Fast Refresh

Dan Abramov

Dan Abramov

React Core at Facebook

We’re excited to announce React Native 0.61, which includes a new reloading experience we’re calling Fast Refresh.

Fast Refresh

When we asked the React Native community about common pain points, one of the top answers was that the “hot reloading” feature was broken. It didn’t work reliably for function components, often failed to update the screen, and wasn’t resilient to typos and mistakes. We heard that most people turned it off because it was too unreliable.

In React Native 0.61, we’re unifying the existing “live reloading” (reload on save) and “hot reloading” features into a single new feature called “Fast Refresh”. Fast Refresh was implemented from scratch with the following principles:

  • Fast Refresh fully supports modern React, including function components and Hooks.
  • Fast Refresh gracefully recovers after typos and other mistakes, and falls back to a full reload when needed.
  • Fast Refresh doesn’t perform invasive code transformations so it’s reliable enough to be on by default.

To see Fast Refresh in action, check out this video:

Give it a try, and let us know what you think! If you prefer, you can turn it off in the Dev Menu (Cmd+D on iOS, Cmd+M or Ctrl+M on Android). Turning it on and off is instant so you can do it any time.

Here are a few Fast Refresh tips:

  • Fast Refresh preserves React local state in function components (and Hooks!) by default.
  • If you need to reset the React state on every edit, you can add a special // @refresh reset comment to the file with that component.
  • Fast Refresh always remounts class components without preserving state. This ensures it works reliably.
  • We all make mistakes in the code! Fast Refresh automatically retries rendering after you save a file. You don't need to reload the app manually after fixing a syntax or a runtime error.
  • Adding a console.log or a debugger statement during edits is a neat debugging technique.

Please report any issues with Fast Refresh on GitHub, and we’ll look into them.

Other Improvements

  • Fixed use_frameworks! CocoaPods support. In 0.60 we made some updates to integrate CocoaPods by default. Unfortunately, this broke builds using use_frameworks!. This is fixed in 0.61, making it easier to integrate React Native into your iOS projects that require building with dynamic frameworks.
  • Add useWindowDimensions Hook. This new Hook automatically provides and subscribes to dimension updates, and can be used instead of the Dimensions API in most cases.
  • React was upgraded to 16.9. This version deprecates old names for the UNSAFE_ lifecycle methods, contains improvements to act, and more. See the React 16.9 blog post for an automated migration script and more information.

Breaking Changes

  • Remove React .xcodeproj. In 0.60, we introduced auto-linking support via CocoaPods. We have also integrated CocoaPods into the e2e tests runs, so that from now on, we have a unified standard way of integrating RN into iOS apps. This effectively deprecates the React .xcodeproj support, and the file has been removed starting 0.61. Note: if you use 0.60 auto-linking already, you shouldn't be affected.

Thanks

Thanks to all of the contributors that helped make 0.61 possible!

To see all the updates, take a look at the 0.61 changelog.

- + diff --git a/blog/2019/11/18/react-native-doctor.html b/blog/2019/11/18/react-native-doctor.html index 8e4c9810f32..7a98c1f8250 100644 --- a/blog/2019/11/18/react-native-doctor.html +++ b/blog/2019/11/18/react-native-doctor.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Meet Doctor, a new React Native command

Lucas Bento

Lucas Bento

React Native Community

After over 20 pull requests from 6 contributors in the React Native Community, we're excited to launch react-native doctor, a new command to help you out with getting started, troubleshooting and automatically fixing errors with your development environment. The doctor command is heavily inspired by Expo and Homebrew's own doctor command with a pinch of UI inspired by Jest.

Here it is in action:

How it works

The doctor command currently supports most of the software and libraries that React Native relies on, such as CocoaPods, Xcode and Android SDK. With doctor we'll find issues with your development environment and give you the option to automatically fix them. If doctor is not able to fix an issue, it will display a message and a helpful link explaining how to fix it manually as the following:

Doctor command with a link to help on Android SDK's installation

Try it now

The doctor command is available as a part of React Native 0.62. However, you can try it without upgrading yet:

npx @react-native-community/cli doctor

What checks are currently supported

doctor currently supports the following checks:

  • Node.js (>= 8.3)
  • yarn (>= 1.10)
  • npm (>= 4)
  • Watchman (>= 4), used for watching changes in the filesystem when in development mode.

Specific to the Android environment:

  • Android SDK (>= 26), the software runtime for Android.
  • Android NDK (>= 19), the native development toolkit for Android.
  • ANDROID_HOME, environment variable required by the Android SDK setup.

And to the iOS environment:

  • Xcode (>= 10), IDE for developing, building and shipping iOS applications.
  • CocoaPods, library dependency management tool for iOS applications.
  • ios-deploy (optional), library used internally by the CLI to install applications on a physical iOS device.

Thanks

Huge thanks for the React Native Community for working on this, in particular @thymikee, @thib92, @jmeistrich, @tido64 and @rickhanlonii.

- + diff --git a/blog/2019/11/18/react-native-doctor/index.html b/blog/2019/11/18/react-native-doctor/index.html index 8e4c9810f32..7a98c1f8250 100644 --- a/blog/2019/11/18/react-native-doctor/index.html +++ b/blog/2019/11/18/react-native-doctor/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

Meet Doctor, a new React Native command

Lucas Bento

Lucas Bento

React Native Community

After over 20 pull requests from 6 contributors in the React Native Community, we're excited to launch react-native doctor, a new command to help you out with getting started, troubleshooting and automatically fixing errors with your development environment. The doctor command is heavily inspired by Expo and Homebrew's own doctor command with a pinch of UI inspired by Jest.

Here it is in action:

How it works

The doctor command currently supports most of the software and libraries that React Native relies on, such as CocoaPods, Xcode and Android SDK. With doctor we'll find issues with your development environment and give you the option to automatically fix them. If doctor is not able to fix an issue, it will display a message and a helpful link explaining how to fix it manually as the following:

Doctor command with a link to help on Android SDK's installation

Try it now

The doctor command is available as a part of React Native 0.62. However, you can try it without upgrading yet:

npx @react-native-community/cli doctor

What checks are currently supported

doctor currently supports the following checks:

  • Node.js (>= 8.3)
  • yarn (>= 1.10)
  • npm (>= 4)
  • Watchman (>= 4), used for watching changes in the filesystem when in development mode.

Specific to the Android environment:

  • Android SDK (>= 26), the software runtime for Android.
  • Android NDK (>= 19), the native development toolkit for Android.
  • ANDROID_HOME, environment variable required by the Android SDK setup.

And to the iOS environment:

  • Xcode (>= 10), IDE for developing, building and shipping iOS applications.
  • CocoaPods, library dependency management tool for iOS applications.
  • ios-deploy (optional), library used internally by the CLI to install applications on a physical iOS device.

Thanks

Huge thanks for the React Native Community for working on this, in particular @thymikee, @thib92, @jmeistrich, @tido64 and @rickhanlonii.

- + diff --git a/blog/2020/03/26/version-0.62.html b/blog/2020/03/26/version-0.62.html index 36d99e3f7b7..495da627295 100644 --- a/blog/2020/03/26/version-0.62.html +++ b/blog/2020/03/26/version-0.62.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@
const MyComponent = () => {
const colorScheme = useColorScheme();
return <Text>useColorScheme(): {colorScheme}</Text>;
};

See the docs for Appearance and useColorScheme for more information.

Moving Apple TV to react-native-tvos

As part of our Lean Core effort and to bring Apple TV in line with other platforms like React Native Windows and React Native macOS, we’ve started to remove Apple TV specific code from core.

Going forward, Apple TV support for React Native will be maintained in react-native-community/react-native-tvos along with the corresponding react-native-tvos NPM package. This is a full fork of the main repository, with only the changes needed to support Apple TV.

Releases of react-native-tvos will be based on the public release of React Native. For this 0.62 release of react-native please upgrade Apple TV projects to use react-native-tvos 0.62.

More upgrade support

When 0.61 was released, the community introduced a new upgrade helper tool to support developers upgrading to new versions of React Native. The upgrade helper provides a diff of changes from the version you're on to the version you're targeting, allowing you to see the changes that need to be made for your specific upgrade.

Even with this tool, issues come up when upgrading. Today we're introducing more dedicated upgrading support by announcing Upgrade-Support. Upgrade Support is a GitHub issue tracker where users can submit issues specific to upgrading their projects to receive help from the community.

We're always working to improve the upgrade experience, and we hope that these tools give users the support they need in the edge cases we haven't covered yet.

Other improvements

Breaking changes

Deprecations

Thanks

Thank you to the hundreds of contributors that helped make 0.62 possible!

To see all the updates, take a look at the 0.62 changelog.

- + diff --git a/blog/2020/03/26/version-0.62/index.html b/blog/2020/03/26/version-0.62/index.html index 36d99e3f7b7..495da627295 100644 --- a/blog/2020/03/26/version-0.62/index.html +++ b/blog/2020/03/26/version-0.62/index.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@
const MyComponent = () => {
const colorScheme = useColorScheme();
return <Text>useColorScheme(): {colorScheme}</Text>;
};

See the docs for Appearance and useColorScheme for more information.

Moving Apple TV to react-native-tvos

As part of our Lean Core effort and to bring Apple TV in line with other platforms like React Native Windows and React Native macOS, we’ve started to remove Apple TV specific code from core.

Going forward, Apple TV support for React Native will be maintained in react-native-community/react-native-tvos along with the corresponding react-native-tvos NPM package. This is a full fork of the main repository, with only the changes needed to support Apple TV.

Releases of react-native-tvos will be based on the public release of React Native. For this 0.62 release of react-native please upgrade Apple TV projects to use react-native-tvos 0.62.

More upgrade support

When 0.61 was released, the community introduced a new upgrade helper tool to support developers upgrading to new versions of React Native. The upgrade helper provides a diff of changes from the version you're on to the version you're targeting, allowing you to see the changes that need to be made for your specific upgrade.

Even with this tool, issues come up when upgrading. Today we're introducing more dedicated upgrading support by announcing Upgrade-Support. Upgrade Support is a GitHub issue tracker where users can submit issues specific to upgrading their projects to receive help from the community.

We're always working to improve the upgrade experience, and we hope that these tools give users the support they need in the edge cases we haven't covered yet.

Other improvements

Breaking changes

Deprecations

Thanks

Thank you to the hundreds of contributors that helped make 0.62 possible!

To see all the updates, take a look at the 0.62 changelog.

- + diff --git a/blog/2020/07/06/version-0.63.html b/blog/2020/07/06/version-0.63.html index 0a8de3c1c74..f8e295349b3 100644 --- a/blog/2020/07/06/version-0.63.html +++ b/blog/2020/07/06/version-0.63.html @@ -19,7 +19,7 @@ - + @@ -45,7 +45,7 @@
<Text style={{ color: customDynamicTextColor }}>
This color changes automatically based on the system theme!
</Text>;

Changes the text color based on the system theme

You can learn more about DynamicColorIOS from the documentation.

Dropping iOS 9 and Node.js 8 support

After over four years from its release, we are dropping support for iOS 9. This change will allow us to move faster by being able to reduce the number of compatibility checks that need to be placed in the native code to detect whether a given feature was supported on a certain iOS version. With its market share of 1%, it shouldn’t have much negative impact on your customers.

At the same time, we are dropping support for Node 8. Its LTS maintenance cycle expired in December 2019. The current LTS is Node 10 and it is now the version that we are targeting. If you are still using Node 8 for the development of React Native applications, we encourage you to upgrade in order to receive all the latest security fixes and updates.

Other notable improvements

Thanks

Thank you to the hundreds of contributors that helped make 0.63 possible!

Special thanks to Rick Hanlon for authoring the section on LogBox and Eli White for authoring the Pressable part of this article.

To see all the updates, take a look at the 0.63 changelog.

- + diff --git a/blog/2020/07/06/version-0.63/index.html b/blog/2020/07/06/version-0.63/index.html index 0a8de3c1c74..f8e295349b3 100644 --- a/blog/2020/07/06/version-0.63/index.html +++ b/blog/2020/07/06/version-0.63/index.html @@ -19,7 +19,7 @@ - + @@ -45,7 +45,7 @@
<Text style={{ color: customDynamicTextColor }}>
This color changes automatically based on the system theme!
</Text>;

Changes the text color based on the system theme

You can learn more about DynamicColorIOS from the documentation.

Dropping iOS 9 and Node.js 8 support

After over four years from its release, we are dropping support for iOS 9. This change will allow us to move faster by being able to reduce the number of compatibility checks that need to be placed in the native code to detect whether a given feature was supported on a certain iOS version. With its market share of 1%, it shouldn’t have much negative impact on your customers.

At the same time, we are dropping support for Node 8. Its LTS maintenance cycle expired in December 2019. The current LTS is Node 10 and it is now the version that we are targeting. If you are still using Node 8 for the development of React Native applications, we encourage you to upgrade in order to receive all the latest security fixes and updates.

Other notable improvements

Thanks

Thank you to the hundreds of contributors that helped make 0.63 possible!

Special thanks to Rick Hanlon for authoring the section on LogBox and Eli White for authoring the Pressable part of this article.

To see all the updates, take a look at the 0.63 changelog.

- + diff --git a/blog/2020/07/17/react-native-principles.html b/blog/2020/07/17/react-native-principles.html index f9fbc117bab..c4042e048a8 100644 --- a/blog/2020/07/17/react-native-principles.html +++ b/blog/2020/07/17/react-native-principles.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native Team Principles

Eli White

Eli White

Engineering Manager on React Native

The React Native team at Facebook is guided by principles that help determine how we prioritize our work on React Native. These principles represent our team specifically and do not necessarily represent every stakeholder in the React Native community. We are sharing these principles here to be more transparent about what drives us, how we make decisions, and how we focus our efforts.

Native Experience

Our top priority for React Native is to match the expectations people have for each platform. This is why React Native renders to platform primitives. We value native look-and-feel over cross-platform consistency.

For example, the TextInput in React Native renders to a UITextField on iOS. This ensures that integration with password managers and keyboard controls work out of the box. By using platform primitives, React Native apps are also able to stay up-to-date with design and behavior changes from new releases of Android and iOS.

In order to match the look-and-feel of native apps, we must also match their performance. This is where we focus our most ambitious efforts. For example, Facebook created Hermes, a new JavaScript Engine built from scratch for React Native on Android. Hermes significantly improves the start time of React Native apps. We are also working on major architectural changes that optimize the threading model and make React Native easier to interoperate with native code.

Massive Scale

Hundreds of screens in the Facebook app are implemented with React Native. The Facebook app is used by billions of people on a huge range of devices. This is why we invest in the most challenging problems at scale.

Deploying React Native in our apps lets us identify problems that we wouldn’t see at a smaller scale. For example, Facebook focuses on improving performance across a broad spectrum of devices from the newest iPhone to many older generations of Android devices. This focus informs our architecture projects such as Hermes, Fabric, and TurboModules.

We have proven that React Native can scale to massive organizations too. When hundreds of developers are working on the same app, gradual adoption is a must. This is why we made sure that React Native can be adopted one screen at a time. Soon, we will be taking this one step further and enable migrating individual native views of an existing native screen to React Native.

A focus on massive scale means there are many things our team isn’t currently working on. For example, our team doesn’t drive the adoption of React Native in the industry. We also do not actively build solutions for problems that we don’t see at scale. We are proud that we have many partners and core contributors that are able to focus on those important areas for the community.

Developer Velocity

Great user experiences are created iteratively. It should only take a few seconds to seeing the result of code changes in a running app. React Native's architecture enables it to provide near-instant feedback during development.

We often hear from teams that adopting React Native significantly improved their development velocity. These teams find that the instant feedback during development makes it much easier to try different ideas and add extra polish when they don’t have to interrupt their coding session for every little change. When we make changes to React Native, we make sure to preserve this quality of the developer experience.

Instant feedback is not the only way that React Native improves developer velocity. Teams can easily leverage the fast-growing ecosystem of high quality open source packages. Teams can also share business logic between Android, iOS, and the web. This helps them ship updates faster and reduce organizational silos between platform teams.

Every Platform

When we introduced React Native in 2014, we presented it with our motto “Learn once, write anywhere” — and we mean anywhere. Developers should be able to reach as many people as possible without being limited by device model or operating system.

React Native targets very different platforms including mobile, desktop, web, TV, VR, game consoles, and more. We want to enable rich experiences on each platform instead of requiring developers to build for the lowest common denominator. To accomplish this, we focus on supporting the unique features of each platform. This ranges from varying input mechanisms (e.g. touch, pen, mouse) to fundamentally different consumption experiences like 3D environments in VR.

This principle informed our decision to implement React Native’s new core architecture in cross-platform C++ to promote parity across platforms. We are also refining the public interface targeted at other platform maintainers like Microsoft with Windows and macOS. We strive to enable any platforms to support React Native.

Declarative UI

We don’t believe in deploying the exact same user interface on every platform, we believe in exposing each platform’s unique capabilities with the same declarative programming model. Our declarative programming model is React.

In our experience, the unidirectional data flow popularized by React makes applications easier to understand. We prefer to express a screen as a composition of declarative components rather than imperatively managed views. React’s success on the web and the direction of the new native Android and iOS frameworks show that the industry has also embraced declarative UI.

React popularized declarative user interfaces. However, there remain many unsolved problems that React is uniquely positioned to solve. React Native will continue to build on top of the innovations of React and remain at the forefront of the declarative user interface movement.

- + diff --git a/blog/2020/07/17/react-native-principles/index.html b/blog/2020/07/17/react-native-principles/index.html index f9fbc117bab..c4042e048a8 100644 --- a/blog/2020/07/17/react-native-principles/index.html +++ b/blog/2020/07/17/react-native-principles/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native Team Principles

Eli White

Eli White

Engineering Manager on React Native

The React Native team at Facebook is guided by principles that help determine how we prioritize our work on React Native. These principles represent our team specifically and do not necessarily represent every stakeholder in the React Native community. We are sharing these principles here to be more transparent about what drives us, how we make decisions, and how we focus our efforts.

Native Experience

Our top priority for React Native is to match the expectations people have for each platform. This is why React Native renders to platform primitives. We value native look-and-feel over cross-platform consistency.

For example, the TextInput in React Native renders to a UITextField on iOS. This ensures that integration with password managers and keyboard controls work out of the box. By using platform primitives, React Native apps are also able to stay up-to-date with design and behavior changes from new releases of Android and iOS.

In order to match the look-and-feel of native apps, we must also match their performance. This is where we focus our most ambitious efforts. For example, Facebook created Hermes, a new JavaScript Engine built from scratch for React Native on Android. Hermes significantly improves the start time of React Native apps. We are also working on major architectural changes that optimize the threading model and make React Native easier to interoperate with native code.

Massive Scale

Hundreds of screens in the Facebook app are implemented with React Native. The Facebook app is used by billions of people on a huge range of devices. This is why we invest in the most challenging problems at scale.

Deploying React Native in our apps lets us identify problems that we wouldn’t see at a smaller scale. For example, Facebook focuses on improving performance across a broad spectrum of devices from the newest iPhone to many older generations of Android devices. This focus informs our architecture projects such as Hermes, Fabric, and TurboModules.

We have proven that React Native can scale to massive organizations too. When hundreds of developers are working on the same app, gradual adoption is a must. This is why we made sure that React Native can be adopted one screen at a time. Soon, we will be taking this one step further and enable migrating individual native views of an existing native screen to React Native.

A focus on massive scale means there are many things our team isn’t currently working on. For example, our team doesn’t drive the adoption of React Native in the industry. We also do not actively build solutions for problems that we don’t see at scale. We are proud that we have many partners and core contributors that are able to focus on those important areas for the community.

Developer Velocity

Great user experiences are created iteratively. It should only take a few seconds to seeing the result of code changes in a running app. React Native's architecture enables it to provide near-instant feedback during development.

We often hear from teams that adopting React Native significantly improved their development velocity. These teams find that the instant feedback during development makes it much easier to try different ideas and add extra polish when they don’t have to interrupt their coding session for every little change. When we make changes to React Native, we make sure to preserve this quality of the developer experience.

Instant feedback is not the only way that React Native improves developer velocity. Teams can easily leverage the fast-growing ecosystem of high quality open source packages. Teams can also share business logic between Android, iOS, and the web. This helps them ship updates faster and reduce organizational silos between platform teams.

Every Platform

When we introduced React Native in 2014, we presented it with our motto “Learn once, write anywhere” — and we mean anywhere. Developers should be able to reach as many people as possible without being limited by device model or operating system.

React Native targets very different platforms including mobile, desktop, web, TV, VR, game consoles, and more. We want to enable rich experiences on each platform instead of requiring developers to build for the lowest common denominator. To accomplish this, we focus on supporting the unique features of each platform. This ranges from varying input mechanisms (e.g. touch, pen, mouse) to fundamentally different consumption experiences like 3D environments in VR.

This principle informed our decision to implement React Native’s new core architecture in cross-platform C++ to promote parity across platforms. We are also refining the public interface targeted at other platform maintainers like Microsoft with Windows and macOS. We strive to enable any platforms to support React Native.

Declarative UI

We don’t believe in deploying the exact same user interface on every platform, we believe in exposing each platform’s unique capabilities with the same declarative programming model. Our declarative programming model is React.

In our experience, the unidirectional data flow popularized by React makes applications easier to understand. We prefer to express a screen as a composition of declarative components rather than imperatively managed views. React’s success on the web and the direction of the new native Android and iOS frameworks show that the industry has also embraced declarative UI.

React popularized declarative user interfaces. However, there remain many unsolved problems that React is uniquely positioned to solve. React Native will continue to build on top of the innovations of React and remain at the forefront of the declarative user interface movement.

- + diff --git a/blog/2020/07/23/docs-update.html b/blog/2020/07/23/docs-update.html index c52cace5e40..42b083aff5e 100644 --- a/blog/2020/07/23/docs-update.html +++ b/blog/2020/07/23/docs-update.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native Documentation Update

Rachel Nabors

Rachel Nabors

Documentation Engineer at Facebook

Last year we conducted user interviews and sent out a survey to learn more about how and when people use the React Native docs. With the data and guidance gleaned from 24 interviews and over 3000 survey responses, we've been able to work to improve React Native's documentation, and we're excited to share that progress today:

Thank you so much to everyone who participated in the interviews, the survey, and our documentation efforts! Your collaboration makes this possible.

What’s next?

The global COVID-19 pandemic has impacted many community members’ jobs.

We are responding with additional content including:

  • New and improved Native Modules guides
  • Introductory content for people coming in to React Native for the first time

You can help!

There are many ways you can help us write even better docs!

  1. If you see a typo, run into an issue with a guide, or something otherwise isn’t quite right, click that “Edit” button and submit a PR.
  2. Participate in our survey—this helps us understand how you use React Native and its documentation
  3. Write for us! We’re working on a tutorial section as well as guides for topics like offline apps, navigation, accessibility, debugging, animations, internationalization, and performance. If you or someone you admire or know is a perfect fit for any of these, please reach out to me!
- + diff --git a/blog/2020/07/23/docs-update/index.html b/blog/2020/07/23/docs-update/index.html index c52cace5e40..42b083aff5e 100644 --- a/blog/2020/07/23/docs-update/index.html +++ b/blog/2020/07/23/docs-update/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@

All Blog Posts

React Native Documentation Update

Rachel Nabors

Rachel Nabors

Documentation Engineer at Facebook

Last year we conducted user interviews and sent out a survey to learn more about how and when people use the React Native docs. With the data and guidance gleaned from 24 interviews and over 3000 survey responses, we've been able to work to improve React Native's documentation, and we're excited to share that progress today:

Thank you so much to everyone who participated in the interviews, the survey, and our documentation efforts! Your collaboration makes this possible.

What’s next?

The global COVID-19 pandemic has impacted many community members’ jobs.

We are responding with additional content including:

  • New and improved Native Modules guides
  • Introductory content for people coming in to React Native for the first time

You can help!

There are many ways you can help us write even better docs!

  1. If you see a typo, run into an issue with a guide, or something otherwise isn’t quite right, click that “Edit” button and submit a PR.
  2. Participate in our survey—this helps us understand how you use React Native and its documentation
  3. Write for us! We’re working on a tutorial section as well as guides for topics like offline apps, navigation, accessibility, debugging, animations, internationalization, and performance. If you or someone you admire or know is a perfect fit for any of these, please reach out to me!
- + diff --git a/blog/atom.xml b/blog/atom.xml index 158d8008a93..c11f8f0053f 100644 --- a/blog/atom.xml +++ b/blog/atom.xml @@ -218,13 +218,6 @@ 2017-06-21T00:00:00.000Z - - <![CDATA[Better List Views in React Native]]> - Better List Views in React Native - - 2017-03-13T00:00:00.000Z - - <![CDATA[idx: The Existential Function]]> idx: The Existential Function @@ -239,6 +232,13 @@ 2017-03-13T00:00:00.000Z + + <![CDATA[Better List Views in React Native]]> + Better List Views in React Native + + 2017-03-13T00:00:00.000Z + + <![CDATA[Using Native Driver for Animated]]> Using Native Driver for Animated diff --git a/blog/index.html b/blog/index.html index cdaa33e76df..e4580aaf11d 100644 --- a/blog/index.html +++ b/blog/index.html @@ -19,7 +19,7 @@ - + @@ -56,7 +56,7 @@
const MyComponent = () => {
const colorScheme = useColorScheme();
return <Text>useColorScheme(): {colorScheme}</Text>;
};

See the docs for Appearance and useColorScheme for more information.

Moving Apple TV to react-native-tvos

As part of our Lean Core effort and to bring Apple TV in line with other platforms like React Native Windows and React Native macOS, we’ve started to remove Apple TV specific code from core.

Going forward, Apple TV support for React Native will be maintained in react-native-community/react-native-tvos along with the corresponding react-native-tvos NPM package. This is a full fork of the main repository, with only the changes needed to support Apple TV.

Releases of react-native-tvos will be based on the public release of React Native. For this 0.62 release of react-native please upgrade Apple TV projects to use react-native-tvos 0.62.

More upgrade support

When 0.61 was released, the community introduced a new upgrade helper tool to support developers upgrading to new versions of React Native. The upgrade helper provides a diff of changes from the version you're on to the version you're targeting, allowing you to see the changes that need to be made for your specific upgrade.

Even with this tool, issues come up when upgrading. Today we're introducing more dedicated upgrading support by announcing Upgrade-Support. Upgrade Support is a GitHub issue tracker where users can submit issues specific to upgrading their projects to receive help from the community.

We're always working to improve the upgrade experience, and we hope that these tools give users the support they need in the edge cases we haven't covered yet.

Other improvements

Breaking changes

Deprecations

Thanks

Thank you to the hundreds of contributors that helped make 0.62 possible!

To see all the updates, take a look at the 0.62 changelog.

Meet Doctor, a new React Native command

Lucas Bento

Lucas Bento

React Native Community

After over 20 pull requests from 6 contributors in the React Native Community, we're excited to launch react-native doctor, a new command to help you out with getting started, troubleshooting and automatically fixing errors with your development environment. The doctor command is heavily inspired by Expo and Homebrew's own doctor command with a pinch of UI inspired by Jest.

Announcing React Native 0.61 with Fast Refresh

Dan Abramov

Dan Abramov

React Core at Facebook

We’re excited to announce React Native 0.61, which includes a new reloading experience we’re calling Fast Refresh.

Fast Refresh

When we asked the React Native community about common pain points, one of the top answers was that the “hot reloading” feature was broken. It didn’t work reliably for function components, often failed to update the screen, and wasn’t resilient to typos and mistakes. We heard that most people turned it off because it was too unreliable.

In React Native 0.61, we’re unifying the existing “live reloading” (reload on save) and “hot reloading” features into a single new feature called “Fast Refresh”. Fast Refresh was implemented from scratch with the following principles:

  • Fast Refresh fully supports modern React, including function components and Hooks.
  • Fast Refresh gracefully recovers after typos and other mistakes, and falls back to a full reload when needed.
  • Fast Refresh doesn’t perform invasive code transformations so it’s reliable enough to be on by default.

To see Fast Refresh in action, check out this video:

Give it a try, and let us know what you think! If you prefer, you can turn it off in the Dev Menu (Cmd+D on iOS, Cmd+M or Ctrl+M on Android). Turning it on and off is instant so you can do it any time.

Here are a few Fast Refresh tips:

  • Fast Refresh preserves React local state in function components (and Hooks!) by default.
  • If you need to reset the React state on every edit, you can add a special // @refresh reset comment to the file with that component.
  • Fast Refresh always remounts class components without preserving state. This ensures it works reliably.
  • We all make mistakes in the code! Fast Refresh automatically retries rendering after you save a file. You don't need to reload the app manually after fixing a syntax or a runtime error.
  • Adding a console.log or a debugger statement during edits is a neat debugging technique.

Please report any issues with Fast Refresh on GitHub, and we’ll look into them.

Other Improvements

  • Fixed use_frameworks! CocoaPods support. In 0.60 we made some updates to integrate CocoaPods by default. Unfortunately, this broke builds using use_frameworks!. This is fixed in 0.61, making it easier to integrate React Native into your iOS projects that require building with dynamic frameworks.
  • Add useWindowDimensions Hook. This new Hook automatically provides and subscribes to dimension updates, and can be used instead of the Dimensions API in most cases.
  • React was upgraded to 16.9. This version deprecates old names for the UNSAFE_ lifecycle methods, contains improvements to act, and more. See the React 16.9 blog post for an automated migration script and more information.

Breaking Changes

  • Remove React .xcodeproj. In 0.60, we introduced auto-linking support via CocoaPods. We have also integrated CocoaPods into the e2e tests runs, so that from now on, we have a unified standard way of integrating RN into iOS apps. This effectively deprecates the React .xcodeproj support, and the file has been removed starting 0.61. Note: if you use 0.60 auto-linking already, you shouldn't be affected.

Thanks

Thanks to all of the contributors that helped make 0.61 possible!

To see all the updates, take a look at the 0.61 changelog.

Meet Hermes, a new JavaScript Engine optimized for React Native

Rachel Nabors

Rachel Nabors

Documentation Engineer at Facebook

Last week at Chain React we announced Hermes, an open source JavaScript engine we’ve been working on at Facebook. It’s a small and lightweight JavaScript engine optimized for running React Native on Android. Check it out!

Hermes improves React Native performance by decreasing memory utilization, reducing download size, and decreasing the time it takes for the app to become usable or “time to interactive” (TTI).

“As we analyzed performance data, we noticed that the JavaScript engine itself was a significant factor in startup performance and download size. With this data in hand, we knew we had to optimize JavaScript performance in the more constrained environments of a mobile phone compared with a desktop or laptop. After exploring other options, we built a new JavaScript engine we call Hermes. It is designed to improve app performance, focusing on our React Native apps, even on mass-market devices with limited memory, slow storage, and reduced computing power.” —Hermes: An open source JavaScript engine optimized for mobile apps, starting with React Native

Want to get started right away? Be sure to check out our new guide to enabling Hermes in your existing React Native app in the docs!

Illustration of the Hermes and React Native logos joined into a winged fury, rising in a crashing electrical storm from a lone, glowing, presumably Android phone. Illustration by Rachel Nabors

Announcing React Native 0.60

Ryan Turner

Ryan Turner

Core Maintainer & React Native Developer

After months of hard work from hundreds of contributors, the React Native Core team is proud to announce the release of version 0.60. This release handles significant migrations for both Android and iOS platforms, and many issues are resolved too. This blog post covers the highlights of the release. As always though, refer to the changelog for more detailed information. Finally, thank you contributors for helping us to make this milestone!

Focus on Accessibility

There have been many improvements to the accessibility APIs, like announceForAccessibility, plus improvements to roles, action support, flags, and more. Accessibility is a complex science, but we hope these improvements make it a bit easier to be an A11Y. Be sure to check React Native Open Source Update June 2019 for more details of these changes.

A Fresh Start

React Native's start screen has been updated! Thank you to the many contributors who helped create the new UI. This new "Hello World" will welcome users to the ecosystem in a more friendly, engaging way.

The new init screen helps developers get started from the get-go with resources and a good example

AndroidX Support

AndroidX is a major step forward in the Android ecosystem, and the old support library artifacts are being deprecated. For 0.60, React Native has been migrated over to AndroidX. This is a breaking change, and your native code and dependencies will need to be migrated as well.

With this change, React Native apps will need to begin using AndroidX themselves. They cannot be used side-by-side in one app, so all of the app code and dependency code needs to be using one or the other.

matt-oakes on discussions-and-proposals

While your own native code will need to be migrated by you, @mikehardy, @cawfree, and @m4tt72 built a clever tool named "jetifier" to patch your node_modules. Library maintainers will need to upgrade, but this tool provide you with a temporary solution while giving them time to release an AndroidX version. So if you find errors related to AndroidX migration, give this a shot.

CocoaPods by Default

CocoaPods are now part of React Native's iOS project. If you weren't already, be sure to open iOS platform code using the xcworkspace file from now on (protip: try xed ios from the root project directory). Also, the podspecs for the internal packages have changed to make them compatible with the Xcode projects, which will help with troubleshooting and debugging. Expect to make some straightforward changes to your Podfile as part of the upgrade to 0.60 to bring this exciting support. Note that we are aware of a compatibility issue with use_frameworks!, and we're tracking an issue with workarounds and a future patch.

Lean Core Removals

WebView and NetInfo were previously extracted into separate repositories, and in 0.60 we’ve finished migrating them out of the React Native repository. Additionally, in response to community feedback about new App Store policy, Geolocation has been extracted. If you haven’t already, complete your migration by adding dependencies to react-native-webview, @react-native-community/netinfo, and @react-native-community/geolocation. If you'd like an automated solution, consider using rn-upgrade-deprecated-modules. Maintainers have made more than 100 commits to these repositories since extraction and we’re excited to see the community’s support!

Native Modules are now Autolinked

The team working on the React Native CLI has introduced major improvements to native module linking called autolinking! Most scenarios will not require the use of react-native link anymore. At the same time, the team overhauled the linking process in general. Be sure to react-native unlink any preexisting dependencies as mentioned in the docs above.

Upgrade Helper

@lucasbento, @pvinis, @kelset, and @watadarkstar have built a great tool called Upgrade Helper to make the upgrade process simpler. It helps React Native users with brownfield apps or complex customizations to see what's changed between versions. Take a look at the updated upgrading docs and try it out today for your upgrade path!

Upgrade Helper cleanly and easily shows the changes needed to migrate to a different version of React Native

A Note to Library Maintainers

Changes for AndroidX will almost certainly require updates to your library, so be sure to include support soon. If you're not able to upgrade yet, consider checking your library against the jetifier to confirm that users are able to patch your library at build time.

Review the autolinking docs to update your configs and readme. Depending on how your library was previously integrated, you may also need to make some additional changes. Check the dependencies guide from the CLI for information on how to define your dependency interface.

Thanks

While these are the highlights that we noted, there are many others to be excited about. To see all the updates, take a look at the changelog. As always, stay tuned for more news. Enjoy 0.60 in the meantime!

React Native Open Source Update June 2019

Christoph Nakazawa

Christoph Nakazawa

Engineer at Facebook

Code & Community Health

In the past six months, a total of 2800 commits were made to React Native by more than 550 contributors. 400 contributors from the community created more than 1,150 Pull Requests, of which 820 Pull Requests were merged.

The average number of Pull Requests per day throughout the past six months has increased from three to about six, even though we split the website, CLI and many modules out of React Native via the Lean Core effort. The average amount of open pull requests is now below 25 and we usually reply with suggestions and reviews within hours or days.

Meaningful Community Contributions

We’d like to highlight a number of recent contributions which we thought were awesome:

Lean Core

The primary motivation of Lean Core has been to split modules out of React Native into separate repositories so they can receive better maintenance. In just a six months repositories like WebView, NetInfo, AsyncStorage, the website and the CLI received more than 800 Pull Requests combined. Besides better maintenance, these projects can also be independently released more often than React Native itself.

We have also taken the opportunity to remove obsolete polyfills and legacy components from React Native itself. Polyfills were necessary in the past to support language features like Map and Set in older versions of JavaScriptCore (JSC). Now that React Native ships with a new version, these polyfills were removed.

This work is still in progress and many more things still need to be split out or removed both on the native and JavaScript side but there are early signs that we managed to reverse the trend of increasing the surface area and app size: When looking at the JavaScript bundle for example, about a year ago in version 0.54 the React Native JavaScript bundle size was 530kb and grew to 607kb (+77kb) by version 0.57 in just 6 months. Now we are seeing a bundle size reduction of 28kb down to 579kb on master, a delta of more than 100kb!

As we conclude the first iteration of the Lean Core effort, we will make an effort to be more intentional about new APIs added to React Native and we will continuously evaluate ways to make React Native smaller and faster, as well as finding ways to empower the community to take ownership of various components.

User Feedback

Six months ago we asked the community “What do you dislike about React Native?” which gave a good overview of problems people are facing. We replied to the post a few months ago and it's time to summarize the progress that was made on top issues:

  • Upgrading: The React Native community rallied around with multiple improvements to the upgrading experience: autolinking, a better upgrading command via rn-diff-purge, an upgrade helper website (coming soon). We’ll also make sure to communicate breaking changes and exciting new features by publishing blog posts for each major release. Many of these improvements will make future upgrades beyond the 0.60 release significantly easier.
  • Support / Uncertainty: Many people were frustrated with the lack of activity on Pull Requests and general uncertainty about Facebook's investment in React Native. As we've shown above, we can confidently say that we are ready for many more Pull Requests and we are eagerly looking forward to your proposals and contributions!
  • Performance: React Native 0.59 shipped with a new and much faster version of JavaScriptCore (JSC). Separately, we have been working on making it easier to enable inline-requires by default and we have more exciting updates for you in the next couple of months.
  • Documentation: We recently started an effort to overhaul and rewrite all of React Native's documentation. If you are looking to contribute, we’d love to get your help!
  • Warnings in Xcode: We got rid of all the existing warnings and are making an effort not to introduce new warnings.
  • Hot Reloading: The React team is building a new hot reloading system that will soon be integrated into React Native.

Unfortunately we weren’t able to improve everything just yet:

  • Debugging: We fixed many inconvenient bugs and issues people that we have been running into every day, but unfortunately we haven't made as much progress on this as we would like. We recognize that debugging with React Native isn't great and we'll prioritize improving this in the future.
  • Metro symlinks: Unfortunately we haven't been able to implement a simple and straightforward solution for this yet. However, React Native users shared various workarounds that may work for you.

Given the large amount of changes in the past six months, we'd like to ask you the same question again. If you are using the latest version of React Native and you have things you'd like to give feedback on, please comment on our new edition of “What do you dislike about React Native?”

Continuous Integration

Facebook merges all Pull Requests and internal changes directly into Facebook’s repository first and then syncs all commits back to GitHub. Facebook’s infrastructure is different from common continuous integration services and not all open source tests were run inside of Facebook. This means that commits that sync out to GitHub frequently break tests in open source which take a lot of time to fix.

Héctor Ramos from the React Native team spent the past two months improving React Native's continuous integration systems both at Facebook and on GitHub. Most of the open source tests are now run before changes are committed to React Native at Facebook which will keep CI stable on GitHub when commits are being synchronized.

Next

Make sure to check out our talks about the future of React Native! In the next couple of months, members of the React Native team at Facebook will speak at Chain React and at React Native EU. Also, watch out for our next release, 0.60, which is right around the corner. It's going to be exciting ✨

React Native at F8 and Open Source Podcast

Christoph Nakazawa

Christoph Nakazawa

Engineer at Facebook

This week, Eli White gave a talk at F8 2019 about React Native in Facebook's Android and iOS applications. We are excited to share what we've been up to for the past two years and what we're doing next.

Check out the video on Facebook's developer website:

F8 Talk about React Native

Highlights from the talk:

  • We spent 2017 and 2018 focused on React Native's largest product, Facebook's Marketplace. We collaborated with the Marketplace team to improve quality and add delight to the product. At this point, Marketplace is one of the highest quality products in the Facebook app both on Android and iOS.
  • Marketplace's performance was a big challenge as well, especially on mid-end Android devices. We cut startup time by more than 50% over the last year with more improvements on the way! The biggest improvements are being built into React Native and will be coming to the community later this year.
  • We have the confidence that we can build the high quality and performant apps that Facebook needs with React Native. This confidence has let us invest in bigger bets, like rethinking the core of React Native.
  • Microsoft supports and uses React Native for Windows, enabling people to use their expertise and codebase to render to Microsofts's Universal Windows Platform. Check out Microsoft Build next week to hear them talk about that more.

React Radio Podcast about Open Source

Eli's talk concludes by talking about our recent open source work. We gave an update on our progress in March and recently Nader Dabit and Gant Laborde invited Christoph for a chat on their podcast, React Native Radio, to chat about React Native in open source.

Highlights from the podcast:

  • We talked about how the React Native team at Facebook thinks about open source and how we are building a sustainable community that scales for a project of React Native's size.
  • We are on track to remove multiple modules as part of the Lean Core effort. Many modules like WebView and the React Native CLI have received more than 100 Pull Requests since they were extracted.
  • Next, we'll be focusing on overhauling the React Native website and documentation. Stay tuned!

You'll find the episode in your favorite podcasting app soon or you can listen to the recording right here:

- + diff --git a/blog/page/2.html b/blog/page/2.html index c97266ca861..517da6420d2 100644 --- a/blog/page/2.html +++ b/blog/page/2.html @@ -19,7 +19,7 @@ - + @@ -62,7 +62,7 @@
it('renders correctly with defaults', () => {
const button = renderer
.create(<Hello name="World" enthusiasmLevel={1} />)
.toJSON();
expect(button).toMatchSnapshot();
});

The first time the test is run, it will create a snapshot of the rendered component and store it in the components/__tests__/__snapshots__/Hello.tsx.snap file. When you modify your component, you'll need to update the snapshots and review the update for inadvertent changes. You can read more about testing React Native components here.

Next Steps

Check out the official React tutorial and state-management library Redux. These resources can be helpful when writing React Native apps. Additionally, you may want to look at ReactXP, a component library written entirely in TypeScript that supports both React on the web as well as React Native.

Have fun in a more type-safe React Native development environment!

Built with React Native - The Build.com app

Garrett McCullough

Garrett McCullough

Senior Mobile Engineer

Build.com, headquartered in Chico, California, is one of the largest online retailers for home improvement items. The team has had a strong web-centric business for 18 years and began thinking about a mobile App in 2015. Building unique Android and iOS apps wasn’t practical due to our small team and limited native experience. Instead, we decided to take a risk on the very new React Native framework. Our initial commit was on August 12, 2015 using React Native v0.8.0! We were live in both App Stores on October 15, 2016. Over the last two years, we’ve continued to upgrade and expand the app. We are currently on React Native version 0.53.0.

You can check out the app at https://www.build.com/app.

Features

Our app is full featured and includes everything that you’d expect from an e-commerce app: product listings, search and sorting, the ability to configure complex products, favorites, etc. We accept standard credit card payment methods as well as PayPal, and Apple Pay for our iOS users.

A few standout features you might not expect include:

  1. 3D models available for around 40 products with 90 finishes
  2. Augmented Reality (AR) to allow the user to see how lights and faucets will look in their home at 98% size accuracy. The Build.com React Native App is featured in the Apple App store for AR Shopping! AR is now available for Android and iOS!
  3. Collaborative project management features that allow people to put together shopping lists for the different phases of their project and collaborate around selection

We’re working on many new and exciting features that will continue to improve our app experience including the next phase of Immersive Shopping with AR.

Our Development Workflow

Build.com allows each dev to choose the tools that best suit them.

  • IDEs include Atom, IntelliJ, VS Code, Sublime, Eclipse, etc.
  • For Unit testing, developers are responsible for creating Jest unit tests for any new components and we’re working to increase the coverage of older parts of the app using jest-coverage-ratchet.
  • We use Jenkins to build out our beta and release candidates. This process works well for us but still requires significant work to create the release notes and other artifacts.
  • Integration Testing include a shared pool of testers that work across desktop, mobile and web. Our automation engineer is building out our suite of automated integration tests using Java and Appium.
  • Other parts of the workflow include a detailed eslint configuration, custom rules that enforce properties needed for testing, and pre-push hooks that block offending changes.

Libraries Used in the App

The Build.com app relies on a number of common open source libraries including: Redux, Moment, Numeral, Enzyme and a bunch of React Native bridge modules. We also use a number of forked open source libraries; forked either because they were abandoned or because we needed custom features. A quick count shows around 115 JavaScript and native dependencies. We would like to explore tools that remove unused libraries.

We're in the process of adding static typing via TypeScript and looking into optional chaining. These features could help us with solving a couple classes of bugs that we still see:

  • Data that is the wrong type
  • Data that is undefined because an object didn’t contain what we expected

Open Source Contributions

Since we rely so heavily on open source, our team is committed to contributing back to the community. Build.com allows the team to open source libraries that we've built and encourages us contribute back to the libraries that we use.

We’ve released and maintained a number of React Native libraries:

  • react-native-polyfill
  • react-native-simple-store
  • react-native-contact-picker

We have also contributed to a long list of libraries including: React and React Native, react-native-schemes-manager, react-native-swipeable, react-native-gallery, react-native-view-transformer, react-native-navigation.

Our Journey

We’ve seen a lot of growth in React Native and the ecosystem in the past couple years. Early on, it seemed that every version of React Native would fix some bugs but introduce several more. For example, Remote JS Debugging was broken on Android for several months. Thankfully, things became much more stable in 2017.

Navigation Libraries

One of our big recurring challenges has been with navigation libraries. For a long time, we were using Expo’s ex-nav library. It worked well for us but it was eventually deprecated. However, we were in heavy feature development at the time so taking time to change out a navigation library wasn’t feasible. That meant we had to fork the library and patch it to support React 16 and the iPhone X. Eventually, we were able to migrate to react-native-navigation and hopefully that will see continued support.

Bridge Modules

Another big challenge has been with bridge modules. When we first started, a lot of critical bridges were missing. One of my teammates wrote react-native-contact-picker because we needed access to the Android contact picker in our app. We’ve also seen a lot of bridges that were broken by changes within React Native. For example, there was a breaking change within React Native v40 and when we upgraded our app, I had to submit PRs to fix 3 or 4 libraries that had not yet been updated.

Looking Forward

As React Native continues to grow, our wishlist to our community include:

  • Stabilize and improve the navigation libraries
  • Maintain support for libraries in the React Native ecosystem
  • Improve the experience for adding native libraries and bridge modules to a project

Companies and individuals in the React Native community have been great about volunteering their time and effort to improve the tools that we all use. If you haven’t gotten involved in open source, I hope you’ll take a look at improving the code or documentation for some of the libraries that you use. There are a lot of articles to help you get started and it may be a lot easier than you think!

- + diff --git a/blog/page/2/index.html b/blog/page/2/index.html index c97266ca861..517da6420d2 100644 --- a/blog/page/2/index.html +++ b/blog/page/2/index.html @@ -19,7 +19,7 @@ - + @@ -62,7 +62,7 @@
it('renders correctly with defaults', () => {
const button = renderer
.create(<Hello name="World" enthusiasmLevel={1} />)
.toJSON();
expect(button).toMatchSnapshot();
});

The first time the test is run, it will create a snapshot of the rendered component and store it in the components/__tests__/__snapshots__/Hello.tsx.snap file. When you modify your component, you'll need to update the snapshots and review the update for inadvertent changes. You can read more about testing React Native components here.

Next Steps

Check out the official React tutorial and state-management library Redux. These resources can be helpful when writing React Native apps. Additionally, you may want to look at ReactXP, a component library written entirely in TypeScript that supports both React on the web as well as React Native.

Have fun in a more type-safe React Native development environment!

Built with React Native - The Build.com app

Garrett McCullough

Garrett McCullough

Senior Mobile Engineer

Build.com, headquartered in Chico, California, is one of the largest online retailers for home improvement items. The team has had a strong web-centric business for 18 years and began thinking about a mobile App in 2015. Building unique Android and iOS apps wasn’t practical due to our small team and limited native experience. Instead, we decided to take a risk on the very new React Native framework. Our initial commit was on August 12, 2015 using React Native v0.8.0! We were live in both App Stores on October 15, 2016. Over the last two years, we’ve continued to upgrade and expand the app. We are currently on React Native version 0.53.0.

You can check out the app at https://www.build.com/app.

Features

Our app is full featured and includes everything that you’d expect from an e-commerce app: product listings, search and sorting, the ability to configure complex products, favorites, etc. We accept standard credit card payment methods as well as PayPal, and Apple Pay for our iOS users.

A few standout features you might not expect include:

  1. 3D models available for around 40 products with 90 finishes
  2. Augmented Reality (AR) to allow the user to see how lights and faucets will look in their home at 98% size accuracy. The Build.com React Native App is featured in the Apple App store for AR Shopping! AR is now available for Android and iOS!
  3. Collaborative project management features that allow people to put together shopping lists for the different phases of their project and collaborate around selection

We’re working on many new and exciting features that will continue to improve our app experience including the next phase of Immersive Shopping with AR.

Our Development Workflow

Build.com allows each dev to choose the tools that best suit them.

  • IDEs include Atom, IntelliJ, VS Code, Sublime, Eclipse, etc.
  • For Unit testing, developers are responsible for creating Jest unit tests for any new components and we’re working to increase the coverage of older parts of the app using jest-coverage-ratchet.
  • We use Jenkins to build out our beta and release candidates. This process works well for us but still requires significant work to create the release notes and other artifacts.
  • Integration Testing include a shared pool of testers that work across desktop, mobile and web. Our automation engineer is building out our suite of automated integration tests using Java and Appium.
  • Other parts of the workflow include a detailed eslint configuration, custom rules that enforce properties needed for testing, and pre-push hooks that block offending changes.

Libraries Used in the App

The Build.com app relies on a number of common open source libraries including: Redux, Moment, Numeral, Enzyme and a bunch of React Native bridge modules. We also use a number of forked open source libraries; forked either because they were abandoned or because we needed custom features. A quick count shows around 115 JavaScript and native dependencies. We would like to explore tools that remove unused libraries.

We're in the process of adding static typing via TypeScript and looking into optional chaining. These features could help us with solving a couple classes of bugs that we still see:

  • Data that is the wrong type
  • Data that is undefined because an object didn’t contain what we expected

Open Source Contributions

Since we rely so heavily on open source, our team is committed to contributing back to the community. Build.com allows the team to open source libraries that we've built and encourages us contribute back to the libraries that we use.

We’ve released and maintained a number of React Native libraries:

  • react-native-polyfill
  • react-native-simple-store
  • react-native-contact-picker

We have also contributed to a long list of libraries including: React and React Native, react-native-schemes-manager, react-native-swipeable, react-native-gallery, react-native-view-transformer, react-native-navigation.

Our Journey

We’ve seen a lot of growth in React Native and the ecosystem in the past couple years. Early on, it seemed that every version of React Native would fix some bugs but introduce several more. For example, Remote JS Debugging was broken on Android for several months. Thankfully, things became much more stable in 2017.

Navigation Libraries

One of our big recurring challenges has been with navigation libraries. For a long time, we were using Expo’s ex-nav library. It worked well for us but it was eventually deprecated. However, we were in heavy feature development at the time so taking time to change out a navigation library wasn’t feasible. That meant we had to fork the library and patch it to support React 16 and the iPhone X. Eventually, we were able to migrate to react-native-navigation and hopefully that will see continued support.

Bridge Modules

Another big challenge has been with bridge modules. When we first started, a lot of critical bridges were missing. One of my teammates wrote react-native-contact-picker because we needed access to the Android contact picker in our app. We’ve also seen a lot of bridges that were broken by changes within React Native. For example, there was a breaking change within React Native v40 and when we upgraded our app, I had to submit PRs to fix 3 or 4 libraries that had not yet been updated.

Looking Forward

As React Native continues to grow, our wishlist to our community include:

  • Stabilize and improve the navigation libraries
  • Maintain support for libraries in the React Native ecosystem
  • Improve the experience for adding native libraries and bridge modules to a project

Companies and individuals in the React Native community have been great about volunteering their time and effort to improve the tools that we all use. If you haven’t gotten involved in open source, I hope you’ll take a look at improving the code or documentation for some of the libraries that you use. There are a lot of articles to help you get started and it may be a lot easier than you think!

- + diff --git a/blog/page/3.html b/blog/page/3.html index bfc13a6a3aa..44849667460 100644 --- a/blog/page/3.html +++ b/blog/page/3.html @@ -19,7 +19,7 @@ - + @@ -62,7 +62,7 @@
return (
<View style={styles.fullScreen}>
{fullScreenBlueLayer}
<MaskedViewIOS
style={{ flex: 1 }}
maskElement={
<View style={styles.centeredFullScreen}>
<Animated.Image
style={[styles.maskImageStyle, imageScale]}
source={twitterLogo}
/>
</View>
}>
{fullScreenWhiteLayer}
<Animated.View
style={[opacityClearToVisible, appScale, { flex: 1 }]}>
{this.props.children}
</Animated.View>
</MaskedViewIOS>
</View>
);

Yay! We now have the animation pieces looking like we want. Now we just have to clean up our blue and white layers which will never be seen again.

To know when we can clean them up, we need to know when the animation is complete. Luckily where we call, Animated.timing ,.start takes an optional callback that runs when the animation is complete.

Animated.timing(this.state.loadingProgress, {
toValue: 100,
duration: 1000,
useNativeDriver: true
}).start(() => {
this.setState({
animationDone: true
});
});

Now that we have a value in state to know whether we are done with the animation, we can modify our blue and white layers to use that.

const fullScreenBlueLayer = this.state.animationDone ? null : (
<View style={[styles.fullScreenBlueLayer]} />
);
const fullScreenWhiteLayer = this.state.animationDone ? null : (
<View style={[styles.fullScreenWhiteLayer]} />
);

Voila! Our animation now works and we clean up our unused layers once the animation is done. We have built the Twitter app loading animation!

But wait, mine doesn’t work!

Don’t fret, dear reader. I too hate when guides only give you chunks of the code and don’t give you the completed source.

This component has been published to npm and is on GitHub as react-native-mask-loader. To try this out on your phone, it is available on Expo here:

More Reading / Extra Credit

  1. This gitbook is a great resource to learn more about Animated after you have read the React Native docs.
  2. The actual Twitter animation seems to speed up the mask reveal towards the end. Try modifying the loader to use a different easing function (or a spring!) to better match that behavior.
  3. The current end-scale of the mask is hard coded and likely won’t reveal the entire app on a tablet. Calculating the end scale based on screen size and image size would be an awesome PR.

React Native Monthly #6

Tomislav Tenodi

Tomislav Tenodi

Founder at Speck

The React Native monthly meeting is still going strong! Make sure to check a note on the bottom of this post for the next sessions.

Expo

  • Congratulations to Devin Abbott and Houssein Djirdeh on their pre-release of the "Full Stack React Native" book! It walks you through learning React Native by building several small apps. You can try those apps out on https://www.fullstackreact.com/react-native/ before buying the book.
  • Released a first (experimental) version of reason-react-native-scripts to help people to easily try out ReasonML.
  • Expo SDK 24 is released! It uses React Native 0.51 and includes a bunch of new features and improvements: bundling images in standalone apps (no need to cache on first load!), image manipulation API (crop, resize, rotate, flip), face detection API, new release channel features (set the active release for a given channel and rollback), web dashboard to track standalone app builds, and a fix longstanding bug with OpenGL Android implementation and the Android multi-tasker, just to name a few things.
  • We are allocating more resources to React Navigation starting this January. We strongly believe that it is both possible and desirable to build React Native navigation with just React components and primitives like Animated and react-native-gesture-handler and we’re really excited about some of the improvements we have planned. If you're looking to contribute to the community, check out react-native-maps and react-native-svg, which could both use some help!

Infinite Red

Microsoft

  • A pull request has been started to migrate the core React Native Windows bridge to .NET Standard, making it effectively OS-agnostic. The hope is that many other .NET Core platforms can extend the bridge with their own threading models, JavaScript runtimes, and UIManagers (think JavaScriptCore, Xamarin.Mac, Linux Gtk#, and Samsung Tizen options).

Wix

  • Detox
    • In order for us to scale with E2E tests, we want to minimize time spent on CI, we are working on parallelization support for Detox.
    • Submitted a pull request to enable support for custom flavor builds, to better support mocking on E2E.
  • DetoxInstruments
    • Working on the killer feature of DetoxInstruments proves to be a very challenging task, taking JavaScript backtrace at any given time requires a custom JSCore implementation to support JS thread suspension. Testing the profiler internally on Wix’s app revealed interesting insights about the JS thread.
    • The project is still not stable enough for general use but is actively worked on, and we hope to announce it soon.
  • React Native Navigation
    • V2 development pace has been increased substantially, up until now, we only had 1 developer working on it 20% of his time, we now have 3 developers working on it full time!
  • Android Performance
    • Replacing the old JSCore bundled in RN with its newest version (tip of webkitGTK project, with custom JIT configuration) produced 40% performance increase on the JS thread. Next up is compiling a 64bit version of it. This effort is based on JSC build scripts for Android. Follow its current status here.

Next sessions

There's been some discussion on re-purposing this meeting to discuss a single and specific topic (e.g. navigation, moving React Native modules into separate repos, documentation, ...). That way we feel we can contribute the best to React Native community. It might take place in the next meeting session. Feel free to tweet what you'd like to see covered as a topic.

React Native Monthly #5

Tomislav Tenodi

Tomislav Tenodi

Founder at Speck

The React Native monthly meeting continues! Let's see what our teams are up to.

Callstack

  • We’ve been working on React Native CI. Most importantly, we have migrated from Travis to Circle, leaving React Native with a single, unified CI pipeline.
  • We’ve organised Hacktoberfest - React Native edition where, together with attendees, we tried to submit many pull requests to open source projects.
  • We keep working on Haul. Last month, we have submitted two new releases, including Webpack 3 support. We plan to add CRNA and Expo support as well as work on better HMR. Our roadmap is public on the issue tracker. If you would like to suggest improvements or give feedback, let us know!

Expo

  • Released Expo SDK 22 (using React Native 0.49) and updated CRNA for it.
    • Includes improved splash screen API, basic ARKit support, “DeviceMotion” API, SFAuthenticationSession support on iOS11, and more.
  • Your snacks can now have multiple JavaScript files and you can upload images and other assets by just dragging them into the editor.
  • Contribute to react-navigation to add support for iPhone X.
  • Focus our attention on rough edges when building large applications with Expo. For example:
    • First-class support for deploying to multiple environments: staging, production, and arbitrary channels. Channels will support rolling back and setting the active release for a given channel. Let us know if you want to be an early tester, @expo_io.
    • We are also working on improving our standalone app building infrastructure and adding support for bundling images and other non-code assets in standalone app builds while keeping the ability to update assets over the air.

Facebook

  • Better RTL support:
    • We’re introducing a number of direction-aware styles.
      • Position:
        • (left|right) → (start|end)
      • Margin:
        • margin(Left|Right) → margin(Start|End)
      • Padding:
        • padding(Left|Right) → padding(Start|End)
      • Border:
        • borderTop(Left|Right)Radius → borderTop(Start|End)Radius
        • borderBottom(Left|Right)Radius → borderBottom(Start|End)Radius
        • border(Left|Right)Width → border(Start|End)Width
        • border(Left|Right)Color → border(Start|End)Color
    • The meaning of “left” and “right” were swapped in RTL for position, margin, padding, and border styles. Within a few months, we’re going to remove this behaviour and make “left” always mean “left,” and “right” always mean “right”. The breaking changes are hidden under a flag. Use I18nManager.swapLeftAndRightInRTL(false) in your React Native components to opt into them.
  • Working on Flow typing our internal native modules and using those to generate interfaces in Java and protocols in ObjC that the native implementations must implement. We hope this codegen becomes open source next year, at the earliest.

Infinite Red

  • New OSS tool for helping React Native and other projects. More here.
  • Revamping Ignite for a new boilerplate release (Code name: Bowser)

Shoutem

  • Improving the development flow on Shoutem. We want to streamline the process from creating an app to first custom screen and make it really easy, thus lowering the barrier for new React Native developers. Prepared a few workshops to test out new features. We also improved Shoutem CLI to support new flows.
  • Shoutem UI received a few component improvements and bugfixes. We also checked compatibility with latest React Native versions.
  • Shoutem platform received a few notable updates, new integrations are available as part of the open-source extensions project. We are really excited to see active development on Shoutem extensions from other developers. We actively contact and offer advice and guidance about their extensions.

Next session

The next session is scheduled for Wednesday 6, December 2017. Feel free to ping me on Twitter if you have any suggestion on how we should improve the output of the meeting.

React Native Monthly #4

Mike Grabowski

Mike Grabowski

CTO at Callstack

The React Native monthly meeting continues! Here are the notes from each team:

Callstack

  • React Native EU is over. More than 300 participants from 33 countries have visited Wroclaw. Talks can be found on Youtube.
  • We are slowly getting back to our open source schedule after the conference. One thing worth mentioning is that we are working on a next release of react-native-opentok that fixes most of the existing issues.

GeekyAnts

Trying to lower the entry barrier for the developers embracing React Native with the following things:

  • Announced BuilderX.io at React Native EU. BuilderX is a design tool that directly works with JavaScript files (only React Native is supported at the moment) to generate beautiful, readable, and editable code.
  • Launched ReactNativeSeed.com which provides a set of boilerplates for your next React Native project. It comes with a variety of options that include TypeScript & Flow for data-types, MobX, Redux, and mobx-state-tree for state-management with CRNA and plain React-Native as the stack.

Expo

  • Will release SDK 21 shortly, which adds support for react-native 0.48.3 and a bunch of bugfixes/reliability improvements/new features in the Expo SDK, including video recording, a new splash screen API, support for react-native-gesture-handler, and improved error handling.
  • Re: react-native-gesture-handler, Krzysztof Magiera of Software Mansion continues pushing this forward and we've been helping him with testing it and funding part of his development time. Having this integrated in Expo in SDK21 will allow people to play with it easily in Snack, so we're excited to see what people come up with.
  • Re: improved error logging / handling - see this gist of an internal Expo PR for details on logging, (in particular, "Problem 2"), and this commit for a change that handles failed attempts to import npm standard library modules. There is plenty of opportunity to improve error messages upstream in React Native in this way and we will work on follow up upstream PRs. It would be great for the community to get involved too.
  • native.directory continues to grow, you can add your projects from the Github repo.
  • Visit hackathons around North America, including PennApps, Hack The North, HackMIT, and soon MHacks.

Facebook

  • Working on improving <Text> and <TextInput> components on Android. (Native auto-growing for <TextInput>; deeply nested <Text> components layout issues; better code structure; performance optimizations).
  • We're still looking for additional contributors who would like to help triage issues and pull requests.

Microsoft

  • Released Code Signing feature for CodePush. React Native developers are now able to sign their application bundles in CodePush. The announcement can be found here
  • Working on completing integration of CodePush to Mobile Center. Considering test/crash integration as well.

Next session

The next session is scheduled for Wednesday 10, October 2017. As this was only our fourth meeting, we'd like to know how do these notes benefit the React Native community. Feel free to ping me on Twitter if you have any suggestion on how we should improve the output of the meeting.

React Native Monthly #3

Mike Grabowski

Mike Grabowski

CTO at Callstack

The React Native monthly meeting continues! This month's meeting was a bit shorter as most of our teams were busy shipping. Next month, we are at React Native EU conference in Wroclaw, Poland. Make sure to grab a ticket and see you there in person! Meanwhile, let's see what our teams are up to.

Teams

On this third meeting, we had 5 teams join us:

Notes

Here are the notes from each team:

Callstack

  • Recently open sourced react-native-material-palette. It extracts prominent colors from images to help you create visually engaging apps. It's Android only at the moment, but we are looking into adding support for iOS in the future.
  • We have landed HMR support into haul and a bunch of other, cool stuff! Check out latest releases.
  • React Native EU 2017 is coming! Next month is all about React Native and Poland! Make sure to grab last tickets available here.

Expo

  • Released support for installing npm packages on Snack. Usual Expo restrictions apply -- packages can't depend on custom native APIs that aren't already included in Expo. We are also working on supporting multiple files and uploading assets in Snack. Satyajit will talk about Snack at React Native Europe.
  • Released SDK20 with camera, payments, secure storage, magnetometer, pause/resume fs downloads, and improved splash/loading screen.
  • Continuing to work with Krzysztof on react-native-gesture-handler. Please give it a try, rebuild some gesture that you have previously built using PanResponder or native gesture recognizers and let us know what issues you encounter.
  • Experimenting with JSC debugging protocol, working on a bunch of feature requests on Canny.

Facebook

  • Last month we discussed management of the GitHub issue tracker and that we would try to make improvements to address the maintainability of the project.
  • Currently, the number of open issues is holding steady at around 600, and it seems like it may stay that way for a while. In the past month, we have closed 690 issues due to lack of activity (defined as no comments in the last 60 days). Out of those 690 issues, 58 were re-opened for a variety of reasons (a maintainer committed to providing a fix, or a contributor made a great case for keeping the issue open).
  • We plan to continue with the automated closing of stale issues for the foreseeable future. We’d like to be in a state where every impactful issue opened in the tracker is acted upon, but we’re not there yet. We need all the help we can from maintainers to triage issues and make sure we don't miss issues that introduce regressions or introduce breaking changes, especially those that affect newly created projects. People interested in helping out can use the Facebook GitHub Bot to triage issues and pull requests. The new Maintainers Guide contains more information on triage and use of the GitHub Bot. Please add yourself to the issue task force and encourage other active community members to do the same!

Microsoft

  • The new Skype app is built on top of React Native in order to facilitate sharing as much code between platforms as possible. The React Native-based Skype app is currently available in the Android and iOS app stores.
  • While building the Skype app on React Native, we send pull requests to React Native in order to address bugs and missing features that we come across. So far, we've gotten about 70 pull requests merged.
  • React Native enabled us to power both the Android and iOS Skype apps from the same codebase. We also want to use that codebase to power the Skype web app. To help us achieve that goal, we built and open sourced a thin layer on top of React/React Native called ReactXP. ReactXP provides a set of cross platform components that get mapped to React Native when targeting iOS/Android and to react-dom when targeting the web. ReactXP's goals are similar to another open source library called React Native for Web. There's a brief description of how the approaches of these libraries differ in the ReactXP FAQ.

Shoutem

  • We are continuing our efforts on improving and simplifying the developer experience when building apps using Shoutem.
  • Started migrating all our apps to react-navigation, but we ended postponing this until a more stable version is released, or one of the native navigation solutions becomes stable.
  • Updating all our extensions and most of our open source libraries (animation, theme, ui) to React Native 0.47.1.

Next session

The next session is scheduled for Wednesday 13, September 2017. As this was only our third meeting, we'd like to know how do these notes benefit the React Native community. Feel free to ping me on Twitter if you have any suggestion on how we should improve the output of the meeting.

React Native Performance in Marketplace

Aaron Chiu

Software Engineer at Facebook

React Native is used in multiple places across multiple apps in the Facebook family including a top level tab in the main Facebook apps. Our focus for this post is a highly visible product, Marketplace. It is available in a dozen or so countries and enables users to discover products and services provided by other users.

In the first half of 2017, through the joint effort of the Relay Team, the Marketplace team, the Mobile JS Platform team, and the React Native team, we cut Marketplace Time to Interaction (TTI) in half for Android Year Class 2010-11 devices. Facebook has historically considered these devices as low-end Android devices, and they have the slowest TTIs on any platform or device type.

A typical React Native startup looks something like this:

Disclaimer: ratios aren't representative and will vary depending on how React Native is configured and used.

We first initialize the React Native core (aka the “Bridge”) before running the product specific JavaScript which determines what native views React Native will render in the Native Processing Time.

A different approach

One of the earlier mistakes that we made was to let Systrace and CTScan drive our performance efforts. These tools helped us find a lot of low-hanging fruit in 2016, but we discovered that both Systrace and CTScan are not representative of production scenarios and cannot emulate what happens in the wild. Ratios of time spent in the breakdowns are often incorrect and, wildly off-base at times. At the extreme, some things that we expected to take a few milliseconds actually take hundreds or thousands of milliseconds. That said, CTScan is useful and we've found it catches a third of regressions before they hit production.

On Android, we attribute the shortcomings of these tools to the fact that 1) React Native is a multithreaded framework, 2) Marketplace is co-located with a multitude of complex views such as Newsfeed and other top-level tabs, and 3) computation times vary wildly. Thus, this half, we let production measurements and breakdowns drive almost all of our decision making and prioritization.

Down the path of production instrumentation

Instrumenting production may sound simple on the surface, but it turned out to be quite a complex process. It took multiple iteration cycles of 2-3 weeks each; due to the latency of landing a commit in master, to pushing the app to the Play Store, to gathering sufficient production samples to have confidence in our work. Each iteration cycle involved discovering if our breakdowns were accurate, if they had the right level of granularity, and if they properly added up to the whole time span. We could not rely on alpha and beta releases because they are not representative of the general population. In essence, we very tediously built a very accurate production trace based on the aggregate of millions of samples.

One of the reasons we meticulously verified that every millisecond in breakdowns properly added up to their parent metrics was that we realized early on there were gaps in our instrumentation. It turned out that our initial breakdowns did not account for stalls caused by thread jumps. Thread jumps themselves aren't expensive, but thread jumps to busy threads already doing work are very expensive. We eventually reproduced these blockages locally by sprinkling Thread.sleep() calls at the right moments, and we managed to fix them by:

  1. removing our dependency on AsyncTask,
  2. undoing the forced initialization of ReactContext and NativeModules on the UI thread, and
  3. removing the dependency on measuring the ReactRootView at initialization time.

Together, removing these thread blockage issues reduced the startup time by over 25%.

Production metrics also challenged some of our prior assumptions. For example, we used to pre-load many JavaScript modules on the startup path under the assumption that co-locating modules in one bundle would reduce their initialization cost. However, the cost of pre-loading and co-locating these modules far outweighed the benefits. By re-configuring our inline require blacklists and removing JavaScript modules from the startup path, we were able to avoid loading unnecessary modules such as Relay Classic (when only Relay Modern was necessary). Today, our RUN_JS_BUNDLE breakdown is over 75% faster.

We also found wins by investigating product-specific native modules. For example, by lazily injecting a native module's dependencies, we reduced that native module's cost by 98%. By removing the contention of Marketplace startup with other products, we reduced startup by an equivalent interval.

The best part is that many of these improvements are broadly applicable to all screens built with React Native.

Conclusion

People assume that React Native startup performance problems are caused by JavaScript being slow or exceedingly high network times. While speeding up things like JavaScript would bring down TTI by a non-trivial sum, each of these contribute a much smaller percentage of TTI than was previously believed.

The lesson so far has been to measure, measure, measure! Some wins come from moving run-time costs to build time, such as Relay Modern and Lazy NativeModules. Other wins come from avoiding work by being smarter about parallelizing code or removing dead code. And some wins come from large architectural changes to React Native, such as cleaning up thread blockages. There is no grand solution to performance, and longer-term performance wins will come from incremental instrumentation and improvements. Do not let cognitive bias influence your decisions. Instead, carefully gather and interpret production data to guide future work.

Future plans

In the long term, we want Marketplace TTI to be comparable to similar products built with Native, and, in general, have React Native performance on par with native performance. Further more, although this half we drastically reduced the bridge startup cost by about 80%, we plan to bring the cost of the React Native bridge close to zero via projects like Prepack and more build time processing.

React Native Monthly #2

Tomislav Tenodi

Tomislav Tenodi

Product Manager at Shoutem

The React Native monthly meeting continues! On this session, we were joined by Infinite Red, great minds behind Chain React, the React Native Conference. As most of the people here were presenting talks at Chain React, we pushed the meeting to a week later. Talks from the conference have been posted online and I encourage you to check them out. So, let's see what our teams are up to.

Teams

On this second meeting, we had 9 teams join us:

Notes

Here are the notes from each team:

Airbnb

Callstack

  • Mike Grabowski has been managing React Native's monthly releases as always, including a few betas that were pushed out. In particular, working on getting a v0.43.5 build published to npm since it unblocks Windows users!
  • Slow but consistent work is happening on Haul. There is a pull request that adds HMR, and other improvements have shipped. Recently got a few industry leaders to adopt it. Possibly planning to start a full-time paid work in that area.
  • Michał Pierzchała from the Jest team has joined us at Callstack this month. He will help maintain Haul and possibly work on Metro Bundler and Jest.
  • Satyajit Sahoo is now with us, yay!
  • Got a bunch of cool stuff coming up from our OSS department. In particular, working on bringing Material Palette API to React Native. Planning to finally release our native iOS kit which is aimed to provide 1:1 look & feel of native components.

Expo

  • Recently launched Native Directory to help with discoverability and evaluation of libraries in React Native ecosystem. The problem: lots of libraries, hard to test, need to manually apply heuristics and not immediately obvious which ones are just the best ones that you should use. It's also hard to know if something is compatible with CRNA/Expo. So Native Directory tries to solve these problems. Check it out and add your library to it. The list of libraries is in here. This is just our first pass of it, and we want this to be owned and run by the community, not just Expo folks. So please pitch in if you think this is valuable and want to make it better!
  • Added initial support for installing npm packages in Snack with Expo SDK 19. Let us know if you run into any issues with it, we are still working through some bugs. Along with Native Directory, this should make it easy to test libraries that have only JS dependencies, or dependencies included in Expo SDK. Try it out:
  • Released Expo SDK19 with a bunch of improvements across the board, and we're now using the updated Android JSC.
  • Working on a guide in docs with Alexander Kotliarskyi with a list of tips on how to improve the user experience of your app. Please join in and add to the list or help write some of it!
  • Continuing to work on: audio/video, camera, gestures (with Software Mansion, react-native-gesture-handler), GL camera integration and hoping to land some of these for the first time in SDK20 (August), and significant improvements to others by then as well. We're just getting started on building infrastructure into the Expo client for background work (geolocation, audio, handling notifications, etc.).
  • Adam Miskiewicz has made some nice progress on imitating the transitions from UINavigationController in react-navigation. Check out an earlier version of it in his tweet - release coming with it soon. Also check out MaskedViewIOS which he upstreamed. If you have the skills and desire to implement MaskedView for Android that would be awesome!

Facebook

  • Facebook is internally exploring being able to embed native ComponentKit and Litho components inside of React Native.
  • Contributions to React Native are very welcome! If you are wondering how you can contribute, the "How to Contribute" guide describes our development process and lays out the steps to send your first pull request. There are other ways to contribute that do not require writing code, such as by triaging issues or updating the docs.
    • At the time of writing, React Native has 635 open issues and 249 open pull requests. This is overwhelming for our maintainers, and when things get fixed internally, it is difficult to ensure the relevant tasks are updated.
    • We are unsure what the best approach is to handle this while keeping the community satisfied. Some (but not all!) options include closing stale issues, giving significantly more people permissions to manage issues, and automatically closing issues that do not follow the issue template. We wrote a "What to Expect from Maintainers" guide to set expectations and avoid surprises. If you have ideas on how we can make this experience better for maintainers as well as ensuring people opening issues and pull requests feel heard and valued, please let us know!

GeekyAnts

  • We demoed the Designer Tool which works with React Native files on Chain React. Many attendees signed up for the waiting list.
  • We are also looking at other cross-platform solutions like Google Flutter (a major comparison coming along), Kotlin Native, and Apache Weex to understand the architectural differences and what we can learn from them to improve the overall performance of React Native.
  • Switched to react-navigation for most of our apps, which has improved the overall performance.
  • Also, announced NativeBase Market - A marketplace for React Native components and apps (for and by the developers).

Infinite Red

Microsoft

  • CodePush has now been integrated into Mobile Center. Existing users will have no change in their workflow.
    • Some people have reported an issue with duplicate apps - they already had an app on Mobile Center. We are working on resolving them, but if you have two apps, let us know, and we can merge them for you.
  • Mobile Center now supports Push Notifications for CodePush. We also showed how a combination of Notifications and CodePush could be used for A/B testing apps - something unique to the ReactNative architecture.
  • VSCode has a known debugging issue with ReactNative - the next release of the extension in a couple of days will be fixing the issue.
  • Since there are many other teams also working on React Native inside Microsoft, we will work on getting better representation from all the groups for the next meeting.

Shoutem

  • Finished the process of making the React Native development easier on Shoutem. You can use all the standard react-native commands when developing apps on Shoutem.
  • We did a lot of work trying to figure out how to best approach the profiling on React Native. A big chunk of documentation is outdated, and we'll do our best to create a pull request on the official docs or at least write some of our conclusions in a blog post.
  • Switching our navigation solution to react-navigation, so we might have some feedback soon.
  • We released a new HTML component in our toolkit which transforms the raw HTML to the React Native components tree.

Wix

  • We started working on a pull request to Metro Bundler with react-native-repackager capabilities. We updated react-native-repackager to support RN 44 (which we use in production). We are using it for our mocking infrastructure for detox.
  • We have been covering the Wix app in detox tests for the last three weeks. It's an amazing learning experience of how to reduce manual QA in an app of this scale (over 40 engineers). We have resolved several issues with detox as a result, a new version was just published. I am happy to report that we are living up to the "zero flakiness policy" and the tests are passing consistently so far.
  • Detox for Android is moving forward nicely. We are getting significant help from the community. We are expecting an initial version in about two weeks.
  • DetoxInstruments, our performance testing tool, is getting a little bigger than we originally intended. We are now planning to turn it into a standalone tool that will not be tightly coupled to detox. It will allow investigating the performance of iOS apps in general. It will also be integrated with detox so we can run automated tests on performance metrics.

Next session

The next session is scheduled for August 16, 2017. As this was only our second meeting, we'd like to know how do these notes benefit the React Native community. Feel free to ping me on Twitter if you have any suggestion on how we should improve the output of the meeting.

React Native Monthly #1

Tomislav Tenodi

Tomislav Tenodi

Product Manager at Shoutem

At Shoutem, we've been fortunate enough to work with React Native from its very beginnings. We decided we wanted to be part of the amazing community from day one. Soon enough, we realized it's almost impossible to keep up with the pace the community was growing and improving. That's why we decided to organize a monthly meeting where all major React Native contributors can briefly present what their efforts and plans are.

Monthly meetings

We had our first session of the monthly meeting on June 14, 2017. The mission for React Native Monthly is simple and straightforward: improve the React Native community. Presenting teams' efforts eases collaboration between teams done offline.

Teams

On the first meeting, we had 8 teams join us:

We hope to have more core contributors join the upcoming sessions!

Notes

As teams' plans might be of interest to a broader audience, we'll be sharing them here, on the React Native blog. So, here they are:

Airbnb

  • Plans to add some A11y (accessibility) APIs to View and the AccessibilityInfo native module.
  • Will be investigating adding some APIs to native modules on Android to allow for specifying threads for them to run on.
  • Have been investigating potential initialization performance improvements.
  • Have been investigating some more sophisticated bundling strategies to use on top of "unbundle".

Callstack

  • Looking into improving the release process by using Detox for E2E testing. Pull request should land soon.
  • Blob pull request they have been working on has been merged, subsequent pull requests coming up.
  • Increasing Haul adoption across internal projects to see how it performs compared to Metro Bundler. Working on better multi-threaded performance with the Webpack team.
  • Internally, they have implemented a better infrastructure to manage open source projects. Plans to be getting more stuff out in upcoming weeks.
  • The React Native Europe conference is coming along, nothing interesting yet, but y'all invited!
  • Stepped back from react-navigation for a while to investigate alternatives (especially native navigations).

Expo

Facebook

  • React Native's packager is now Metro Bundler, in an independent repo. The Metro Bundler team in London is excited to address the needs of the community, improve modularity for additional use-cases beyond React Native, and increase responsiveness on issues and PRs.
  • In the coming months, the React Native team will work on refining the APIs of primitive components. Expect improvements in layout quirks, accessibility, and flow typing.
  • The React Native team also plans on improving core modularity this year, by refactoring to fully support 3rd party platforms such as Windows and macOS.

GeekyAnts

  • The team is working on a UI/UX design app (codename: Builder) which directly works with .js files. Right now, it supports only React Native. It’s similar to Adobe XD and Sketch.
  • The team is working hard so that you can load up an existing React Native app in the editor, make changes (visually, as a designer) and save the changes directly to the JS file.
  • Folks are trying to bridge the gap between Designers and Developers and bring them on the same repo.
  • Also, NativeBase recently reached 5,000 GitHub stars.

Microsoft

  • CodePush has now been integrated into Mobile Center. This is the first step in providing a much more integrated experience with distribution, analytics and other services. See their announcement here.
  • VSCode has a bug with debugging, they are working on fixing that right now and will have a new build.
  • Investigating Detox for Integration testing, looking at JSC Context to get variables alongside crash reports.

Shoutem

  • Making it easier to work on Shoutem apps with tools from the React Native community. You will be able to use all the React Native commands to run the apps created on Shoutem.
  • Investigating profiling tools for React Native. They had a lot of problems setting it up and they will write some of the insights they discovered along the way.
  • Shoutem is working on making it easier to integrate React Native with existing native apps. They will document the concept that they developed internally in the company, in order to get the feedback from the community.

Wix

  • Working internally to adopt Detox to move significant parts of the Wix app to "zero manual QA". As a result, Detox is being used heavily in a production setting by dozens of developers and maturing rapidly.
  • Working to add support to the Metro Bundler for overriding any file extension during the build. Instead of just "ios" and "android", it would support any custom extension like "e2e" or "detox". Plans to use this for E2E mocking. There's already a library out called react-native-repackager, now working on a PR.
  • Investigating automation of performance tests. This is a new repo called DetoxInstruments. You can take a look, it's being developed open source.
  • Working with a contributor from KPN on Detox for Android and supporting real devices.
  • Thinking about "Detox as a platform" to allow building other tools that need to automate the simulator/device. An example is Storybook for React Native or Ram's idea for integration testing.

Next session

Meetings will be held every four weeks. The next session is scheduled for July 12, 2017. As we just started with this meeting, we'd like to know how do these notes benefit the React Native community. Feel free to ping me on Twitter if you have any suggestion on what we should cover in the following sessions, or how we should improve the output of the meeting.

- + diff --git a/blog/page/3/index.html b/blog/page/3/index.html index bfc13a6a3aa..44849667460 100644 --- a/blog/page/3/index.html +++ b/blog/page/3/index.html @@ -19,7 +19,7 @@ - + @@ -62,7 +62,7 @@
return (
<View style={styles.fullScreen}>
{fullScreenBlueLayer}
<MaskedViewIOS
style={{ flex: 1 }}
maskElement={
<View style={styles.centeredFullScreen}>
<Animated.Image
style={[styles.maskImageStyle, imageScale]}
source={twitterLogo}
/>
</View>
}>
{fullScreenWhiteLayer}
<Animated.View
style={[opacityClearToVisible, appScale, { flex: 1 }]}>
{this.props.children}
</Animated.View>
</MaskedViewIOS>
</View>
);

Yay! We now have the animation pieces looking like we want. Now we just have to clean up our blue and white layers which will never be seen again.

To know when we can clean them up, we need to know when the animation is complete. Luckily where we call, Animated.timing ,.start takes an optional callback that runs when the animation is complete.

Animated.timing(this.state.loadingProgress, {
toValue: 100,
duration: 1000,
useNativeDriver: true
}).start(() => {
this.setState({
animationDone: true
});
});

Now that we have a value in state to know whether we are done with the animation, we can modify our blue and white layers to use that.

const fullScreenBlueLayer = this.state.animationDone ? null : (
<View style={[styles.fullScreenBlueLayer]} />
);
const fullScreenWhiteLayer = this.state.animationDone ? null : (
<View style={[styles.fullScreenWhiteLayer]} />
);

Voila! Our animation now works and we clean up our unused layers once the animation is done. We have built the Twitter app loading animation!

But wait, mine doesn’t work!

Don’t fret, dear reader. I too hate when guides only give you chunks of the code and don’t give you the completed source.

This component has been published to npm and is on GitHub as react-native-mask-loader. To try this out on your phone, it is available on Expo here:

More Reading / Extra Credit

  1. This gitbook is a great resource to learn more about Animated after you have read the React Native docs.
  2. The actual Twitter animation seems to speed up the mask reveal towards the end. Try modifying the loader to use a different easing function (or a spring!) to better match that behavior.
  3. The current end-scale of the mask is hard coded and likely won’t reveal the entire app on a tablet. Calculating the end scale based on screen size and image size would be an awesome PR.

React Native Monthly #6

Tomislav Tenodi

Tomislav Tenodi

Founder at Speck

The React Native monthly meeting is still going strong! Make sure to check a note on the bottom of this post for the next sessions.

Expo

  • Congratulations to Devin Abbott and Houssein Djirdeh on their pre-release of the "Full Stack React Native" book! It walks you through learning React Native by building several small apps. You can try those apps out on https://www.fullstackreact.com/react-native/ before buying the book.
  • Released a first (experimental) version of reason-react-native-scripts to help people to easily try out ReasonML.
  • Expo SDK 24 is released! It uses React Native 0.51 and includes a bunch of new features and improvements: bundling images in standalone apps (no need to cache on first load!), image manipulation API (crop, resize, rotate, flip), face detection API, new release channel features (set the active release for a given channel and rollback), web dashboard to track standalone app builds, and a fix longstanding bug with OpenGL Android implementation and the Android multi-tasker, just to name a few things.
  • We are allocating more resources to React Navigation starting this January. We strongly believe that it is both possible and desirable to build React Native navigation with just React components and primitives like Animated and react-native-gesture-handler and we’re really excited about some of the improvements we have planned. If you're looking to contribute to the community, check out react-native-maps and react-native-svg, which could both use some help!

Infinite Red

Microsoft

  • A pull request has been started to migrate the core React Native Windows bridge to .NET Standard, making it effectively OS-agnostic. The hope is that many other .NET Core platforms can extend the bridge with their own threading models, JavaScript runtimes, and UIManagers (think JavaScriptCore, Xamarin.Mac, Linux Gtk#, and Samsung Tizen options).

Wix

  • Detox
    • In order for us to scale with E2E tests, we want to minimize time spent on CI, we are working on parallelization support for Detox.
    • Submitted a pull request to enable support for custom flavor builds, to better support mocking on E2E.
  • DetoxInstruments
    • Working on the killer feature of DetoxInstruments proves to be a very challenging task, taking JavaScript backtrace at any given time requires a custom JSCore implementation to support JS thread suspension. Testing the profiler internally on Wix’s app revealed interesting insights about the JS thread.
    • The project is still not stable enough for general use but is actively worked on, and we hope to announce it soon.
  • React Native Navigation
    • V2 development pace has been increased substantially, up until now, we only had 1 developer working on it 20% of his time, we now have 3 developers working on it full time!
  • Android Performance
    • Replacing the old JSCore bundled in RN with its newest version (tip of webkitGTK project, with custom JIT configuration) produced 40% performance increase on the JS thread. Next up is compiling a 64bit version of it. This effort is based on JSC build scripts for Android. Follow its current status here.

Next sessions

There's been some discussion on re-purposing this meeting to discuss a single and specific topic (e.g. navigation, moving React Native modules into separate repos, documentation, ...). That way we feel we can contribute the best to React Native community. It might take place in the next meeting session. Feel free to tweet what you'd like to see covered as a topic.

React Native Monthly #5

Tomislav Tenodi

Tomislav Tenodi

Founder at Speck

The React Native monthly meeting continues! Let's see what our teams are up to.

Callstack

  • We’ve been working on React Native CI. Most importantly, we have migrated from Travis to Circle, leaving React Native with a single, unified CI pipeline.
  • We’ve organised Hacktoberfest - React Native edition where, together with attendees, we tried to submit many pull requests to open source projects.
  • We keep working on Haul. Last month, we have submitted two new releases, including Webpack 3 support. We plan to add CRNA and Expo support as well as work on better HMR. Our roadmap is public on the issue tracker. If you would like to suggest improvements or give feedback, let us know!

Expo

  • Released Expo SDK 22 (using React Native 0.49) and updated CRNA for it.
    • Includes improved splash screen API, basic ARKit support, “DeviceMotion” API, SFAuthenticationSession support on iOS11, and more.
  • Your snacks can now have multiple JavaScript files and you can upload images and other assets by just dragging them into the editor.
  • Contribute to react-navigation to add support for iPhone X.
  • Focus our attention on rough edges when building large applications with Expo. For example:
    • First-class support for deploying to multiple environments: staging, production, and arbitrary channels. Channels will support rolling back and setting the active release for a given channel. Let us know if you want to be an early tester, @expo_io.
    • We are also working on improving our standalone app building infrastructure and adding support for bundling images and other non-code assets in standalone app builds while keeping the ability to update assets over the air.

Facebook

  • Better RTL support:
    • We’re introducing a number of direction-aware styles.
      • Position:
        • (left|right) → (start|end)
      • Margin:
        • margin(Left|Right) → margin(Start|End)
      • Padding:
        • padding(Left|Right) → padding(Start|End)
      • Border:
        • borderTop(Left|Right)Radius → borderTop(Start|End)Radius
        • borderBottom(Left|Right)Radius → borderBottom(Start|End)Radius
        • border(Left|Right)Width → border(Start|End)Width
        • border(Left|Right)Color → border(Start|End)Color
    • The meaning of “left” and “right” were swapped in RTL for position, margin, padding, and border styles. Within a few months, we’re going to remove this behaviour and make “left” always mean “left,” and “right” always mean “right”. The breaking changes are hidden under a flag. Use I18nManager.swapLeftAndRightInRTL(false) in your React Native components to opt into them.
  • Working on Flow typing our internal native modules and using those to generate interfaces in Java and protocols in ObjC that the native implementations must implement. We hope this codegen becomes open source next year, at the earliest.

Infinite Red

  • New OSS tool for helping React Native and other projects. More here.
  • Revamping Ignite for a new boilerplate release (Code name: Bowser)

Shoutem

  • Improving the development flow on Shoutem. We want to streamline the process from creating an app to first custom screen and make it really easy, thus lowering the barrier for new React Native developers. Prepared a few workshops to test out new features. We also improved Shoutem CLI to support new flows.
  • Shoutem UI received a few component improvements and bugfixes. We also checked compatibility with latest React Native versions.
  • Shoutem platform received a few notable updates, new integrations are available as part of the open-source extensions project. We are really excited to see active development on Shoutem extensions from other developers. We actively contact and offer advice and guidance about their extensions.

Next session

The next session is scheduled for Wednesday 6, December 2017. Feel free to ping me on Twitter if you have any suggestion on how we should improve the output of the meeting.

React Native Monthly #4

Mike Grabowski

Mike Grabowski

CTO at Callstack

The React Native monthly meeting continues! Here are the notes from each team:

Callstack

  • React Native EU is over. More than 300 participants from 33 countries have visited Wroclaw. Talks can be found on Youtube.
  • We are slowly getting back to our open source schedule after the conference. One thing worth mentioning is that we are working on a next release of react-native-opentok that fixes most of the existing issues.

GeekyAnts

Trying to lower the entry barrier for the developers embracing React Native with the following things:

  • Announced BuilderX.io at React Native EU. BuilderX is a design tool that directly works with JavaScript files (only React Native is supported at the moment) to generate beautiful, readable, and editable code.
  • Launched ReactNativeSeed.com which provides a set of boilerplates for your next React Native project. It comes with a variety of options that include TypeScript & Flow for data-types, MobX, Redux, and mobx-state-tree for state-management with CRNA and plain React-Native as the stack.

Expo

  • Will release SDK 21 shortly, which adds support for react-native 0.48.3 and a bunch of bugfixes/reliability improvements/new features in the Expo SDK, including video recording, a new splash screen API, support for react-native-gesture-handler, and improved error handling.
  • Re: react-native-gesture-handler, Krzysztof Magiera of Software Mansion continues pushing this forward and we've been helping him with testing it and funding part of his development time. Having this integrated in Expo in SDK21 will allow people to play with it easily in Snack, so we're excited to see what people come up with.
  • Re: improved error logging / handling - see this gist of an internal Expo PR for details on logging, (in particular, "Problem 2"), and this commit for a change that handles failed attempts to import npm standard library modules. There is plenty of opportunity to improve error messages upstream in React Native in this way and we will work on follow up upstream PRs. It would be great for the community to get involved too.
  • native.directory continues to grow, you can add your projects from the Github repo.
  • Visit hackathons around North America, including PennApps, Hack The North, HackMIT, and soon MHacks.

Facebook

  • Working on improving <Text> and <TextInput> components on Android. (Native auto-growing for <TextInput>; deeply nested <Text> components layout issues; better code structure; performance optimizations).
  • We're still looking for additional contributors who would like to help triage issues and pull requests.

Microsoft

  • Released Code Signing feature for CodePush. React Native developers are now able to sign their application bundles in CodePush. The announcement can be found here
  • Working on completing integration of CodePush to Mobile Center. Considering test/crash integration as well.

Next session

The next session is scheduled for Wednesday 10, October 2017. As this was only our fourth meeting, we'd like to know how do these notes benefit the React Native community. Feel free to ping me on Twitter if you have any suggestion on how we should improve the output of the meeting.

React Native Monthly #3

Mike Grabowski

Mike Grabowski

CTO at Callstack

The React Native monthly meeting continues! This month's meeting was a bit shorter as most of our teams were busy shipping. Next month, we are at React Native EU conference in Wroclaw, Poland. Make sure to grab a ticket and see you there in person! Meanwhile, let's see what our teams are up to.

Teams

On this third meeting, we had 5 teams join us:

Notes

Here are the notes from each team:

Callstack

  • Recently open sourced react-native-material-palette. It extracts prominent colors from images to help you create visually engaging apps. It's Android only at the moment, but we are looking into adding support for iOS in the future.
  • We have landed HMR support into haul and a bunch of other, cool stuff! Check out latest releases.
  • React Native EU 2017 is coming! Next month is all about React Native and Poland! Make sure to grab last tickets available here.

Expo

  • Released support for installing npm packages on Snack. Usual Expo restrictions apply -- packages can't depend on custom native APIs that aren't already included in Expo. We are also working on supporting multiple files and uploading assets in Snack. Satyajit will talk about Snack at React Native Europe.
  • Released SDK20 with camera, payments, secure storage, magnetometer, pause/resume fs downloads, and improved splash/loading screen.
  • Continuing to work with Krzysztof on react-native-gesture-handler. Please give it a try, rebuild some gesture that you have previously built using PanResponder or native gesture recognizers and let us know what issues you encounter.
  • Experimenting with JSC debugging protocol, working on a bunch of feature requests on Canny.

Facebook

  • Last month we discussed management of the GitHub issue tracker and that we would try to make improvements to address the maintainability of the project.
  • Currently, the number of open issues is holding steady at around 600, and it seems like it may stay that way for a while. In the past month, we have closed 690 issues due to lack of activity (defined as no comments in the last 60 days). Out of those 690 issues, 58 were re-opened for a variety of reasons (a maintainer committed to providing a fix, or a contributor made a great case for keeping the issue open).
  • We plan to continue with the automated closing of stale issues for the foreseeable future. We’d like to be in a state where every impactful issue opened in the tracker is acted upon, but we’re not there yet. We need all the help we can from maintainers to triage issues and make sure we don't miss issues that introduce regressions or introduce breaking changes, especially those that affect newly created projects. People interested in helping out can use the Facebook GitHub Bot to triage issues and pull requests. The new Maintainers Guide contains more information on triage and use of the GitHub Bot. Please add yourself to the issue task force and encourage other active community members to do the same!

Microsoft

  • The new Skype app is built on top of React Native in order to facilitate sharing as much code between platforms as possible. The React Native-based Skype app is currently available in the Android and iOS app stores.
  • While building the Skype app on React Native, we send pull requests to React Native in order to address bugs and missing features that we come across. So far, we've gotten about 70 pull requests merged.
  • React Native enabled us to power both the Android and iOS Skype apps from the same codebase. We also want to use that codebase to power the Skype web app. To help us achieve that goal, we built and open sourced a thin layer on top of React/React Native called ReactXP. ReactXP provides a set of cross platform components that get mapped to React Native when targeting iOS/Android and to react-dom when targeting the web. ReactXP's goals are similar to another open source library called React Native for Web. There's a brief description of how the approaches of these libraries differ in the ReactXP FAQ.

Shoutem

  • We are continuing our efforts on improving and simplifying the developer experience when building apps using Shoutem.
  • Started migrating all our apps to react-navigation, but we ended postponing this until a more stable version is released, or one of the native navigation solutions becomes stable.
  • Updating all our extensions and most of our open source libraries (animation, theme, ui) to React Native 0.47.1.

Next session

The next session is scheduled for Wednesday 13, September 2017. As this was only our third meeting, we'd like to know how do these notes benefit the React Native community. Feel free to ping me on Twitter if you have any suggestion on how we should improve the output of the meeting.

React Native Performance in Marketplace

Aaron Chiu

Software Engineer at Facebook

React Native is used in multiple places across multiple apps in the Facebook family including a top level tab in the main Facebook apps. Our focus for this post is a highly visible product, Marketplace. It is available in a dozen or so countries and enables users to discover products and services provided by other users.

In the first half of 2017, through the joint effort of the Relay Team, the Marketplace team, the Mobile JS Platform team, and the React Native team, we cut Marketplace Time to Interaction (TTI) in half for Android Year Class 2010-11 devices. Facebook has historically considered these devices as low-end Android devices, and they have the slowest TTIs on any platform or device type.

A typical React Native startup looks something like this:

Disclaimer: ratios aren't representative and will vary depending on how React Native is configured and used.

We first initialize the React Native core (aka the “Bridge”) before running the product specific JavaScript which determines what native views React Native will render in the Native Processing Time.

A different approach

One of the earlier mistakes that we made was to let Systrace and CTScan drive our performance efforts. These tools helped us find a lot of low-hanging fruit in 2016, but we discovered that both Systrace and CTScan are not representative of production scenarios and cannot emulate what happens in the wild. Ratios of time spent in the breakdowns are often incorrect and, wildly off-base at times. At the extreme, some things that we expected to take a few milliseconds actually take hundreds or thousands of milliseconds. That said, CTScan is useful and we've found it catches a third of regressions before they hit production.

On Android, we attribute the shortcomings of these tools to the fact that 1) React Native is a multithreaded framework, 2) Marketplace is co-located with a multitude of complex views such as Newsfeed and other top-level tabs, and 3) computation times vary wildly. Thus, this half, we let production measurements and breakdowns drive almost all of our decision making and prioritization.

Down the path of production instrumentation

Instrumenting production may sound simple on the surface, but it turned out to be quite a complex process. It took multiple iteration cycles of 2-3 weeks each; due to the latency of landing a commit in master, to pushing the app to the Play Store, to gathering sufficient production samples to have confidence in our work. Each iteration cycle involved discovering if our breakdowns were accurate, if they had the right level of granularity, and if they properly added up to the whole time span. We could not rely on alpha and beta releases because they are not representative of the general population. In essence, we very tediously built a very accurate production trace based on the aggregate of millions of samples.

One of the reasons we meticulously verified that every millisecond in breakdowns properly added up to their parent metrics was that we realized early on there were gaps in our instrumentation. It turned out that our initial breakdowns did not account for stalls caused by thread jumps. Thread jumps themselves aren't expensive, but thread jumps to busy threads already doing work are very expensive. We eventually reproduced these blockages locally by sprinkling Thread.sleep() calls at the right moments, and we managed to fix them by:

  1. removing our dependency on AsyncTask,
  2. undoing the forced initialization of ReactContext and NativeModules on the UI thread, and
  3. removing the dependency on measuring the ReactRootView at initialization time.

Together, removing these thread blockage issues reduced the startup time by over 25%.

Production metrics also challenged some of our prior assumptions. For example, we used to pre-load many JavaScript modules on the startup path under the assumption that co-locating modules in one bundle would reduce their initialization cost. However, the cost of pre-loading and co-locating these modules far outweighed the benefits. By re-configuring our inline require blacklists and removing JavaScript modules from the startup path, we were able to avoid loading unnecessary modules such as Relay Classic (when only Relay Modern was necessary). Today, our RUN_JS_BUNDLE breakdown is over 75% faster.

We also found wins by investigating product-specific native modules. For example, by lazily injecting a native module's dependencies, we reduced that native module's cost by 98%. By removing the contention of Marketplace startup with other products, we reduced startup by an equivalent interval.

The best part is that many of these improvements are broadly applicable to all screens built with React Native.

Conclusion

People assume that React Native startup performance problems are caused by JavaScript being slow or exceedingly high network times. While speeding up things like JavaScript would bring down TTI by a non-trivial sum, each of these contribute a much smaller percentage of TTI than was previously believed.

The lesson so far has been to measure, measure, measure! Some wins come from moving run-time costs to build time, such as Relay Modern and Lazy NativeModules. Other wins come from avoiding work by being smarter about parallelizing code or removing dead code. And some wins come from large architectural changes to React Native, such as cleaning up thread blockages. There is no grand solution to performance, and longer-term performance wins will come from incremental instrumentation and improvements. Do not let cognitive bias influence your decisions. Instead, carefully gather and interpret production data to guide future work.

Future plans

In the long term, we want Marketplace TTI to be comparable to similar products built with Native, and, in general, have React Native performance on par with native performance. Further more, although this half we drastically reduced the bridge startup cost by about 80%, we plan to bring the cost of the React Native bridge close to zero via projects like Prepack and more build time processing.

React Native Monthly #2

Tomislav Tenodi

Tomislav Tenodi

Product Manager at Shoutem

The React Native monthly meeting continues! On this session, we were joined by Infinite Red, great minds behind Chain React, the React Native Conference. As most of the people here were presenting talks at Chain React, we pushed the meeting to a week later. Talks from the conference have been posted online and I encourage you to check them out. So, let's see what our teams are up to.

Teams

On this second meeting, we had 9 teams join us:

Notes

Here are the notes from each team:

Airbnb

Callstack

  • Mike Grabowski has been managing React Native's monthly releases as always, including a few betas that were pushed out. In particular, working on getting a v0.43.5 build published to npm since it unblocks Windows users!
  • Slow but consistent work is happening on Haul. There is a pull request that adds HMR, and other improvements have shipped. Recently got a few industry leaders to adopt it. Possibly planning to start a full-time paid work in that area.
  • Michał Pierzchała from the Jest team has joined us at Callstack this month. He will help maintain Haul and possibly work on Metro Bundler and Jest.
  • Satyajit Sahoo is now with us, yay!
  • Got a bunch of cool stuff coming up from our OSS department. In particular, working on bringing Material Palette API to React Native. Planning to finally release our native iOS kit which is aimed to provide 1:1 look & feel of native components.

Expo

  • Recently launched Native Directory to help with discoverability and evaluation of libraries in React Native ecosystem. The problem: lots of libraries, hard to test, need to manually apply heuristics and not immediately obvious which ones are just the best ones that you should use. It's also hard to know if something is compatible with CRNA/Expo. So Native Directory tries to solve these problems. Check it out and add your library to it. The list of libraries is in here. This is just our first pass of it, and we want this to be owned and run by the community, not just Expo folks. So please pitch in if you think this is valuable and want to make it better!
  • Added initial support for installing npm packages in Snack with Expo SDK 19. Let us know if you run into any issues with it, we are still working through some bugs. Along with Native Directory, this should make it easy to test libraries that have only JS dependencies, or dependencies included in Expo SDK. Try it out:
  • Released Expo SDK19 with a bunch of improvements across the board, and we're now using the updated Android JSC.
  • Working on a guide in docs with Alexander Kotliarskyi with a list of tips on how to improve the user experience of your app. Please join in and add to the list or help write some of it!
  • Continuing to work on: audio/video, camera, gestures (with Software Mansion, react-native-gesture-handler), GL camera integration and hoping to land some of these for the first time in SDK20 (August), and significant improvements to others by then as well. We're just getting started on building infrastructure into the Expo client for background work (geolocation, audio, handling notifications, etc.).
  • Adam Miskiewicz has made some nice progress on imitating the transitions from UINavigationController in react-navigation. Check out an earlier version of it in his tweet - release coming with it soon. Also check out MaskedViewIOS which he upstreamed. If you have the skills and desire to implement MaskedView for Android that would be awesome!

Facebook

  • Facebook is internally exploring being able to embed native ComponentKit and Litho components inside of React Native.
  • Contributions to React Native are very welcome! If you are wondering how you can contribute, the "How to Contribute" guide describes our development process and lays out the steps to send your first pull request. There are other ways to contribute that do not require writing code, such as by triaging issues or updating the docs.
    • At the time of writing, React Native has 635 open issues and 249 open pull requests. This is overwhelming for our maintainers, and when things get fixed internally, it is difficult to ensure the relevant tasks are updated.
    • We are unsure what the best approach is to handle this while keeping the community satisfied. Some (but not all!) options include closing stale issues, giving significantly more people permissions to manage issues, and automatically closing issues that do not follow the issue template. We wrote a "What to Expect from Maintainers" guide to set expectations and avoid surprises. If you have ideas on how we can make this experience better for maintainers as well as ensuring people opening issues and pull requests feel heard and valued, please let us know!

GeekyAnts

  • We demoed the Designer Tool which works with React Native files on Chain React. Many attendees signed up for the waiting list.
  • We are also looking at other cross-platform solutions like Google Flutter (a major comparison coming along), Kotlin Native, and Apache Weex to understand the architectural differences and what we can learn from them to improve the overall performance of React Native.
  • Switched to react-navigation for most of our apps, which has improved the overall performance.
  • Also, announced NativeBase Market - A marketplace for React Native components and apps (for and by the developers).

Infinite Red

Microsoft

  • CodePush has now been integrated into Mobile Center. Existing users will have no change in their workflow.
    • Some people have reported an issue with duplicate apps - they already had an app on Mobile Center. We are working on resolving them, but if you have two apps, let us know, and we can merge them for you.
  • Mobile Center now supports Push Notifications for CodePush. We also showed how a combination of Notifications and CodePush could be used for A/B testing apps - something unique to the ReactNative architecture.
  • VSCode has a known debugging issue with ReactNative - the next release of the extension in a couple of days will be fixing the issue.
  • Since there are many other teams also working on React Native inside Microsoft, we will work on getting better representation from all the groups for the next meeting.

Shoutem

  • Finished the process of making the React Native development easier on Shoutem. You can use all the standard react-native commands when developing apps on Shoutem.
  • We did a lot of work trying to figure out how to best approach the profiling on React Native. A big chunk of documentation is outdated, and we'll do our best to create a pull request on the official docs or at least write some of our conclusions in a blog post.
  • Switching our navigation solution to react-navigation, so we might have some feedback soon.
  • We released a new HTML component in our toolkit which transforms the raw HTML to the React Native components tree.

Wix

  • We started working on a pull request to Metro Bundler with react-native-repackager capabilities. We updated react-native-repackager to support RN 44 (which we use in production). We are using it for our mocking infrastructure for detox.
  • We have been covering the Wix app in detox tests for the last three weeks. It's an amazing learning experience of how to reduce manual QA in an app of this scale (over 40 engineers). We have resolved several issues with detox as a result, a new version was just published. I am happy to report that we are living up to the "zero flakiness policy" and the tests are passing consistently so far.
  • Detox for Android is moving forward nicely. We are getting significant help from the community. We are expecting an initial version in about two weeks.
  • DetoxInstruments, our performance testing tool, is getting a little bigger than we originally intended. We are now planning to turn it into a standalone tool that will not be tightly coupled to detox. It will allow investigating the performance of iOS apps in general. It will also be integrated with detox so we can run automated tests on performance metrics.

Next session

The next session is scheduled for August 16, 2017. As this was only our second meeting, we'd like to know how do these notes benefit the React Native community. Feel free to ping me on Twitter if you have any suggestion on how we should improve the output of the meeting.

React Native Monthly #1

Tomislav Tenodi

Tomislav Tenodi

Product Manager at Shoutem

At Shoutem, we've been fortunate enough to work with React Native from its very beginnings. We decided we wanted to be part of the amazing community from day one. Soon enough, we realized it's almost impossible to keep up with the pace the community was growing and improving. That's why we decided to organize a monthly meeting where all major React Native contributors can briefly present what their efforts and plans are.

Monthly meetings

We had our first session of the monthly meeting on June 14, 2017. The mission for React Native Monthly is simple and straightforward: improve the React Native community. Presenting teams' efforts eases collaboration between teams done offline.

Teams

On the first meeting, we had 8 teams join us:

We hope to have more core contributors join the upcoming sessions!

Notes

As teams' plans might be of interest to a broader audience, we'll be sharing them here, on the React Native blog. So, here they are:

Airbnb

  • Plans to add some A11y (accessibility) APIs to View and the AccessibilityInfo native module.
  • Will be investigating adding some APIs to native modules on Android to allow for specifying threads for them to run on.
  • Have been investigating potential initialization performance improvements.
  • Have been investigating some more sophisticated bundling strategies to use on top of "unbundle".

Callstack

  • Looking into improving the release process by using Detox for E2E testing. Pull request should land soon.
  • Blob pull request they have been working on has been merged, subsequent pull requests coming up.
  • Increasing Haul adoption across internal projects to see how it performs compared to Metro Bundler. Working on better multi-threaded performance with the Webpack team.
  • Internally, they have implemented a better infrastructure to manage open source projects. Plans to be getting more stuff out in upcoming weeks.
  • The React Native Europe conference is coming along, nothing interesting yet, but y'all invited!
  • Stepped back from react-navigation for a while to investigate alternatives (especially native navigations).

Expo

Facebook

  • React Native's packager is now Metro Bundler, in an independent repo. The Metro Bundler team in London is excited to address the needs of the community, improve modularity for additional use-cases beyond React Native, and increase responsiveness on issues and PRs.
  • In the coming months, the React Native team will work on refining the APIs of primitive components. Expect improvements in layout quirks, accessibility, and flow typing.
  • The React Native team also plans on improving core modularity this year, by refactoring to fully support 3rd party platforms such as Windows and macOS.

GeekyAnts

  • The team is working on a UI/UX design app (codename: Builder) which directly works with .js files. Right now, it supports only React Native. It’s similar to Adobe XD and Sketch.
  • The team is working hard so that you can load up an existing React Native app in the editor, make changes (visually, as a designer) and save the changes directly to the JS file.
  • Folks are trying to bridge the gap between Designers and Developers and bring them on the same repo.
  • Also, NativeBase recently reached 5,000 GitHub stars.

Microsoft

  • CodePush has now been integrated into Mobile Center. This is the first step in providing a much more integrated experience with distribution, analytics and other services. See their announcement here.
  • VSCode has a bug with debugging, they are working on fixing that right now and will have a new build.
  • Investigating Detox for Integration testing, looking at JSC Context to get variables alongside crash reports.

Shoutem

  • Making it easier to work on Shoutem apps with tools from the React Native community. You will be able to use all the React Native commands to run the apps created on Shoutem.
  • Investigating profiling tools for React Native. They had a lot of problems setting it up and they will write some of the insights they discovered along the way.
  • Shoutem is working on making it easier to integrate React Native with existing native apps. They will document the concept that they developed internally in the company, in order to get the feedback from the community.

Wix

  • Working internally to adopt Detox to move significant parts of the Wix app to "zero manual QA". As a result, Detox is being used heavily in a production setting by dozens of developers and maturing rapidly.
  • Working to add support to the Metro Bundler for overriding any file extension during the build. Instead of just "ios" and "android", it would support any custom extension like "e2e" or "detox". Plans to use this for E2E mocking. There's already a library out called react-native-repackager, now working on a PR.
  • Investigating automation of performance tests. This is a new repo called DetoxInstruments. You can take a look, it's being developed open source.
  • Working with a contributor from KPN on Detox for Android and supporting real devices.
  • Thinking about "Detox as a platform" to allow building other tools that need to automate the simulator/device. An example is Storybook for React Native or Ram's idea for integration testing.

Next session

Meetings will be held every four weeks. The next session is scheduled for July 12, 2017. As we just started with this meeting, we'd like to know how do these notes benefit the React Native community. Feel free to ping me on Twitter if you have any suggestion on what we should cover in the following sessions, or how we should improve the output of the meeting.

- + diff --git a/blog/page/4.html b/blog/page/4.html index 649f393aeb8..5d00515f9eb 100644 --- a/blog/page/4.html +++ b/blog/page/4.html @@ -19,7 +19,7 @@ - + @@ -55,7 +55,7 @@
_onDirectionChange = () => {
I18nManager.forceRTL(!this.state.isRTL);
this.setState({ isRTL: !this.state.isRTL });
Alert.alert(
'Reload this page',
'Please reload this page to change the UI direction! ' +
'All examples in this app will be affected. ' +
'Check them out to see what they look like in RTL layout.'
);
};

When working on a new feature, you can easily toggle this button and reload the app to see RTL layout. The benefit is you won't need to change the language setting to test, however some text alignment won't change, as explained in the next section. Therefore, it's always a good idea to test your app in the RTL language before launching.

Limitations and Future Plan

The RTL support should cover most of the UX in your app; however, there are some limitations for now:

Try it Out!

Check out the RTLExample in the RNTester to understand more about RTL support, and let us know how it works for you!

Finally, thank you for reading! We hope that the RTL support for React Native helps you grow your apps for international audience!

- + diff --git a/blog/page/4/index.html b/blog/page/4/index.html index 649f393aeb8..5d00515f9eb 100644 --- a/blog/page/4/index.html +++ b/blog/page/4/index.html @@ -19,7 +19,7 @@ - + @@ -55,7 +55,7 @@
_onDirectionChange = () => {
I18nManager.forceRTL(!this.state.isRTL);
this.setState({ isRTL: !this.state.isRTL });
Alert.alert(
'Reload this page',
'Please reload this page to change the UI direction! ' +
'All examples in this app will be affected. ' +
'Check them out to see what they look like in RTL layout.'
);
};

When working on a new feature, you can easily toggle this button and reload the app to see RTL layout. The benefit is you won't need to change the language setting to test, however some text alignment won't change, as explained in the next section. Therefore, it's always a good idea to test your app in the RTL language before launching.

Limitations and Future Plan

The RTL support should cover most of the UX in your app; however, there are some limitations for now:

Try it Out!

Check out the RTLExample in the RNTester to understand more about RTL support, and let us know how it works for you!

Finally, thank you for reading! We hope that the RTL support for React Native helps you grow your apps for international audience!

- + diff --git a/blog/page/5.html b/blog/page/5.html index f418317fbe3..1517699f32d 100644 --- a/blog/page/5.html +++ b/blog/page/5.html @@ -19,7 +19,7 @@ - + @@ -60,7 +60,7 @@
return store;
};

When you change a reducer, the code to accept that reducer will be sent to the client. Then the client will realize that the reducer doesn't know how to accept itself, so it will look for all the modules that refer it and try to accept them. Eventually, the flow will get to the single store, the configureStore module, which will accept the HMR update.

Conclusion

If you are interested in helping making hot reloading better, I encourage you to read Dan Abramov's post around the future of hot reloading and to contribute. For example, Johny Days is going to make it work with multiple connected clients. We're relying on you all to maintain and improve this feature.

With React Native, we have the opportunity to rethink the way we build apps in order to make it a great developer experience. Hot reloading is only one piece of the puzzle, what other crazy hacks can we do to make it better?

Making React Native apps accessible

Georgiy Kassabli

Georgiy Kassabli

Software Engineer at Facebook

With the recent launch of React on web and React Native on mobile, we've provided a new front-end framework for developers to build products. One key aspect of building a robust product is ensuring that anyone can use it, including people who have vision loss or other disabilities. The Accessibility API for React and React Native enables you to make any React-powered experience usable by someone who may use assistive technology, like a screen reader for the blind and visually impaired.

For this post, we're going to focus on React Native apps. We've designed the React Accessibility API to look and feel similar to the Android and iOS APIs. If you've developed accessible applications for Android, iOS, or the web before, you should feel comfortable with the framework and nomenclature of the React AX API. For instance, you can make a UI element accessible (therefore exposed to assistive technology) and use accessibilityLabel to provide a string description for the element:

<View accessible={true} accessibilityLabel=”This is simple view”>

Let's walk through a slightly more involved application of the React AX API by looking at one of Facebook's own React-powered products: the Ads Manager app.

This is an excerpt. Read the rest of the post on Facebook Code.

React Native for Android: How we built the first cross-platform React Native app

Daniel Witte

Software Engineer at Facebook

Earlier this year, we introduced React Native for iOS. React Native brings what developers are used to from React on the web — declarative self-contained UI components and fast development cycles — to the mobile platform, while retaining the speed, fidelity, and feel of native applications. Today, we're happy to release React Native for Android.

At Facebook we've been using React Native in production for over a year now. Almost exactly a year ago, our team set out to develop the Ads Manager app. Our goal was to create a new app to let the millions of people who advertise on Facebook manage their accounts and create new ads on the go. It ended up being not only Facebook's first fully React Native app but also the first cross-platform one. In this post, we'd like to share with you how we built this app, how React Native enabled us to move faster, and the lessons we learned.

This is an excerpt. Read the rest of the post on Facebook Code.

React Native: Bringing modern web techniques to mobile

Tom Occhino

Tom Occhino

Engineering Manager at Facebook

We introduced React to the world two years ago, and since then it's seen impressive growth, both inside and outside of Facebook. Today, even though no one is forced to use it, new web projects at Facebook are commonly built using React in one form or another, and it's being broadly adopted across the industry. Engineers are choosing to use React every day because it enables them to spend more time focusing on their products and less time fighting with their framework. It wasn't until we'd been building with React for a while, though, that we started to understand what makes it so powerful.

React forces us to break our applications down into discrete components, each representing a single view. These components make it easier to iterate on our products, since we don't need to keep the entire system in our head in order to make changes to one part of it. More important, though, React wraps the DOM's mutative, imperative API with a declarative one, which raises the level of abstraction and simplifies the programming model. What we've found is that when we build with React, our code is a lot more predictable. This predictability makes it so we can iterate more quickly with confidence, and our applications are a lot more reliable as a result. Additionally, it's not only easier to scale our applications when they're built with React, but we've found it's also easier to scale the size of our teams themselves.

Together with the rapid iteration cycle of the web, we've been able to build some awesome products with React, including many components of Facebook.com. Additionally, we've built amazing frameworks in JavaScript on top of React, like Relay, which allows us to greatly simplify our data fetching at scale. Of course, web is only part of the story. Facebook also has widely used Android and iOS apps, which are built on top of disjointed, proprietary technology stacks. Having to build our apps on top of multiple platforms has bifurcated our engineering organization, but that's only one of the things that makes native mobile application development hard.

This is an excerpt. Read the rest of the post on Facebook Code.

- + diff --git a/blog/page/5/index.html b/blog/page/5/index.html index f418317fbe3..1517699f32d 100644 --- a/blog/page/5/index.html +++ b/blog/page/5/index.html @@ -19,7 +19,7 @@ - + @@ -60,7 +60,7 @@
return store;
};

When you change a reducer, the code to accept that reducer will be sent to the client. Then the client will realize that the reducer doesn't know how to accept itself, so it will look for all the modules that refer it and try to accept them. Eventually, the flow will get to the single store, the configureStore module, which will accept the HMR update.

Conclusion

If you are interested in helping making hot reloading better, I encourage you to read Dan Abramov's post around the future of hot reloading and to contribute. For example, Johny Days is going to make it work with multiple connected clients. We're relying on you all to maintain and improve this feature.

With React Native, we have the opportunity to rethink the way we build apps in order to make it a great developer experience. Hot reloading is only one piece of the puzzle, what other crazy hacks can we do to make it better?

Making React Native apps accessible

Georgiy Kassabli

Georgiy Kassabli

Software Engineer at Facebook

With the recent launch of React on web and React Native on mobile, we've provided a new front-end framework for developers to build products. One key aspect of building a robust product is ensuring that anyone can use it, including people who have vision loss or other disabilities. The Accessibility API for React and React Native enables you to make any React-powered experience usable by someone who may use assistive technology, like a screen reader for the blind and visually impaired.

For this post, we're going to focus on React Native apps. We've designed the React Accessibility API to look and feel similar to the Android and iOS APIs. If you've developed accessible applications for Android, iOS, or the web before, you should feel comfortable with the framework and nomenclature of the React AX API. For instance, you can make a UI element accessible (therefore exposed to assistive technology) and use accessibilityLabel to provide a string description for the element:

<View accessible={true} accessibilityLabel=”This is simple view”>

Let's walk through a slightly more involved application of the React AX API by looking at one of Facebook's own React-powered products: the Ads Manager app.

This is an excerpt. Read the rest of the post on Facebook Code.

React Native for Android: How we built the first cross-platform React Native app

Daniel Witte

Software Engineer at Facebook

Earlier this year, we introduced React Native for iOS. React Native brings what developers are used to from React on the web — declarative self-contained UI components and fast development cycles — to the mobile platform, while retaining the speed, fidelity, and feel of native applications. Today, we're happy to release React Native for Android.

At Facebook we've been using React Native in production for over a year now. Almost exactly a year ago, our team set out to develop the Ads Manager app. Our goal was to create a new app to let the millions of people who advertise on Facebook manage their accounts and create new ads on the go. It ended up being not only Facebook's first fully React Native app but also the first cross-platform one. In this post, we'd like to share with you how we built this app, how React Native enabled us to move faster, and the lessons we learned.

This is an excerpt. Read the rest of the post on Facebook Code.

React Native: Bringing modern web techniques to mobile

Tom Occhino

Tom Occhino

Engineering Manager at Facebook

We introduced React to the world two years ago, and since then it's seen impressive growth, both inside and outside of Facebook. Today, even though no one is forced to use it, new web projects at Facebook are commonly built using React in one form or another, and it's being broadly adopted across the industry. Engineers are choosing to use React every day because it enables them to spend more time focusing on their products and less time fighting with their framework. It wasn't until we'd been building with React for a while, though, that we started to understand what makes it so powerful.

React forces us to break our applications down into discrete components, each representing a single view. These components make it easier to iterate on our products, since we don't need to keep the entire system in our head in order to make changes to one part of it. More important, though, React wraps the DOM's mutative, imperative API with a declarative one, which raises the level of abstraction and simplifies the programming model. What we've found is that when we build with React, our code is a lot more predictable. This predictability makes it so we can iterate more quickly with confidence, and our applications are a lot more reliable as a result. Additionally, it's not only easier to scale our applications when they're built with React, but we've found it's also easier to scale the size of our teams themselves.

Together with the rapid iteration cycle of the web, we've been able to build some awesome products with React, including many components of Facebook.com. Additionally, we've built amazing frameworks in JavaScript on top of React, like Relay, which allows us to greatly simplify our data fetching at scale. Of course, web is only part of the story. Facebook also has widely used Android and iOS apps, which are built on top of disjointed, proprietary technology stacks. Having to build our apps on top of multiple platforms has bifurcated our engineering organization, but that's only one of the things that makes native mobile application development hard.

This is an excerpt. Read the rest of the post on Facebook Code.

- + diff --git a/blog/rss.xml b/blog/rss.xml index b18c24891d5..c7d4e26a3a3 100644 --- a/blog/rss.xml +++ b/blog/rss.xml @@ -218,13 +218,6 @@ Wed, 21 Jun 2017 00:00:00 GMT - - <![CDATA[Better List Views in React Native]]> - https://reactnative.dev/blog/2017/03/13/better-list-views - Better List Views in React Native - Mon, 13 Mar 2017 00:00:00 GMT - - <![CDATA[idx: The Existential Function]]> https://reactnative.dev/blog/2017/03/13/idx-the-existential-function @@ -239,6 +232,13 @@ Mon, 13 Mar 2017 00:00:00 GMT + + <![CDATA[Better List Views in React Native]]> + https://reactnative.dev/blog/2017/03/13/better-list-views + Better List Views in React Native + Mon, 13 Mar 2017 00:00:00 GMT + + <![CDATA[Using Native Driver for Animated]]> https://reactnative.dev/blog/2017/02/14/using-native-driver-for-animated diff --git a/blog/tags.html b/blog/tags.html index f7d4cde3069..854f04ab078 100644 --- a/blog/tags.html +++ b/blog/tags.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@

All Blog Posts

Tags

- + diff --git a/blog/tags/announcement.html b/blog/tags/announcement.html index ebc52ee33b6..b8c4aa6db02 100644 --- a/blog/tags/announcement.html +++ b/blog/tags/announcement.html @@ -19,7 +19,7 @@ - + @@ -74,7 +74,7 @@
AppRegistry.registerComponent('ScratchPad', () => ScratchPad);

We think these inline examples, using the react-native-web-player module with help from Devin Abbott, are a great way to learn the basics of React Native, and we have updated our tutorial for new React Native developers to use these wherever possible. Check it out - if you have ever been curious to see what would happen if you modified just one little bit of sample code, this is a really nice way to poke around. Also, if you're building developer tools and you want to show a live React Native sample on your own site, react-native-web-player can make that straightforward.

The core simulation engine is provided by Nicolas Gallagher's react-native-web project, which provides a way to display React Native components like Text and View on the web. Check out react-native-web if you're interested in building mobile and web experiences that share a large chunk of the codebase.

Better Guides

In some parts of React Native, there are multiple ways to do things, and we've heard feedback that we could provide better guidance.

We have a new guide to Navigation that compares the different approaches and advises on what you should use - Navigator, NavigatorIOS, NavigationExperimental. In the medium term, we're working towards improving and consolidating those interfaces. In the short term, we hope that a better guide will make your life easier.

We also have a new guide to handling touches that explains some of the basics of making button-like interfaces, and a brief summary of the different ways to handle touch events.

Another area we worked on is Flexbox. This includes tutorials on how to handle layout with Flexbox and how to control the size of components. It also includes an unsexy but hopefully-useful list of all the props that control layout in React Native.

Getting Started

When you start getting a React Native development environment set up on your machine, you do have to do a bunch of installing and configuring things. It's hard to make installation a really fun and exciting experience, but we can at least make it as quick and painless as possible.

We built a new Getting Started workflow that lets you select your development operating system and your mobile operating system up front, to provide one concise place with all the setup instructions. We also went through the installation process to make sure everything worked and to make sure that every decision point had a clear recommendation. After testing it out on our innocent coworkers, we're pretty sure this is an improvement.

We also worked on the guide to integrating React Native into an existing app. Many of the largest apps that use React Native, like the Facebook app itself, actually build part of the app in React Native, and part of it using regular development tools. We hope this guide makes it easier for more people to build apps this way.

We Need Your Help

Your feedback lets us know what we should prioritize. I know some people will read this blog post and think "Better docs? Pffft. The documentation for X is still garbage!". That's great - we need that energy. The best way to give us feedback depends on the sort of feedback.

If you find a mistake in the documentation, like inaccurate descriptions or code that doesn't actually work, file an issue. Tag it with "Documentation", so that it's easier to route it to the right people.

If there isn't a specific mistake, but something in the documentation is fundamentally confusing, it's not a great fit for a GitHub issue. Instead, post on Canny about the area of the docs that could use help. This helps us prioritize when we are doing more general work like guide-writing.

Thanks for reading this far, and thanks for using React Native!

React Native: A year in review

Martin Konicek

Martin Konicek

Software Engineer at Facebook

It's been one year since we open-sourced React Native. What started as an idea with a handful of engineers is now a framework being used by product teams across Facebook and beyond. Today at F8 we announced that Microsoft is bringing React Native to the Windows ecosystem, giving developers the potential to build React Native on Windows PC, Phone, and Xbox. It will also provide open source tools and services such as a React Native extension for Visual Studio Code and CodePush to help developers create React Native apps on the Windows platform. In addition, Samsung is building React Native for its hybrid platform, which will empower developers to build apps for millions of SmartTVs and mobile and wearable devices. We also released the Facebook SDK for React Native, which makes it easier for developers to incorporate Facebook social features like Login, Sharing, App Analytics, and Graph APIs into their apps. In one year, React Native has changed the way developers build on every major platform.

It's been an epic ride — but we are only getting started. Here is a look back at how React Native has grown and evolved since we open-sourced it a year ago, some challenges we faced along the way, and what we expect as we look ahead to the future.

This is an excerpt. Read the rest of the post on Facebook Code.

React Native for Android: How we built the first cross-platform React Native app

Daniel Witte

Software Engineer at Facebook

Earlier this year, we introduced React Native for iOS. React Native brings what developers are used to from React on the web — declarative self-contained UI components and fast development cycles — to the mobile platform, while retaining the speed, fidelity, and feel of native applications. Today, we're happy to release React Native for Android.

At Facebook we've been using React Native in production for over a year now. Almost exactly a year ago, our team set out to develop the Ads Manager app. Our goal was to create a new app to let the millions of people who advertise on Facebook manage their accounts and create new ads on the go. It ended up being not only Facebook's first fully React Native app but also the first cross-platform one. In this post, we'd like to share with you how we built this app, how React Native enabled us to move faster, and the lessons we learned.

This is an excerpt. Read the rest of the post on Facebook Code.

React Native: Bringing modern web techniques to mobile

Tom Occhino

Tom Occhino

Engineering Manager at Facebook

We introduced React to the world two years ago, and since then it's seen impressive growth, both inside and outside of Facebook. Today, even though no one is forced to use it, new web projects at Facebook are commonly built using React in one form or another, and it's being broadly adopted across the industry. Engineers are choosing to use React every day because it enables them to spend more time focusing on their products and less time fighting with their framework. It wasn't until we'd been building with React for a while, though, that we started to understand what makes it so powerful.

React forces us to break our applications down into discrete components, each representing a single view. These components make it easier to iterate on our products, since we don't need to keep the entire system in our head in order to make changes to one part of it. More important, though, React wraps the DOM's mutative, imperative API with a declarative one, which raises the level of abstraction and simplifies the programming model. What we've found is that when we build with React, our code is a lot more predictable. This predictability makes it so we can iterate more quickly with confidence, and our applications are a lot more reliable as a result. Additionally, it's not only easier to scale our applications when they're built with React, but we've found it's also easier to scale the size of our teams themselves.

Together with the rapid iteration cycle of the web, we've been able to build some awesome products with React, including many components of Facebook.com. Additionally, we've built amazing frameworks in JavaScript on top of React, like Relay, which allows us to greatly simplify our data fetching at scale. Of course, web is only part of the story. Facebook also has widely used Android and iOS apps, which are built on top of disjointed, proprietary technology stacks. Having to build our apps on top of multiple platforms has bifurcated our engineering organization, but that's only one of the things that makes native mobile application development hard.

This is an excerpt. Read the rest of the post on Facebook Code.

- + diff --git a/blog/tags/announcement/index.html b/blog/tags/announcement/index.html index ebc52ee33b6..b8c4aa6db02 100644 --- a/blog/tags/announcement/index.html +++ b/blog/tags/announcement/index.html @@ -19,7 +19,7 @@ - + @@ -74,7 +74,7 @@
AppRegistry.registerComponent('ScratchPad', () => ScratchPad);

We think these inline examples, using the react-native-web-player module with help from Devin Abbott, are a great way to learn the basics of React Native, and we have updated our tutorial for new React Native developers to use these wherever possible. Check it out - if you have ever been curious to see what would happen if you modified just one little bit of sample code, this is a really nice way to poke around. Also, if you're building developer tools and you want to show a live React Native sample on your own site, react-native-web-player can make that straightforward.

The core simulation engine is provided by Nicolas Gallagher's react-native-web project, which provides a way to display React Native components like Text and View on the web. Check out react-native-web if you're interested in building mobile and web experiences that share a large chunk of the codebase.

Better Guides

In some parts of React Native, there are multiple ways to do things, and we've heard feedback that we could provide better guidance.

We have a new guide to Navigation that compares the different approaches and advises on what you should use - Navigator, NavigatorIOS, NavigationExperimental. In the medium term, we're working towards improving and consolidating those interfaces. In the short term, we hope that a better guide will make your life easier.

We also have a new guide to handling touches that explains some of the basics of making button-like interfaces, and a brief summary of the different ways to handle touch events.

Another area we worked on is Flexbox. This includes tutorials on how to handle layout with Flexbox and how to control the size of components. It also includes an unsexy but hopefully-useful list of all the props that control layout in React Native.

Getting Started

When you start getting a React Native development environment set up on your machine, you do have to do a bunch of installing and configuring things. It's hard to make installation a really fun and exciting experience, but we can at least make it as quick and painless as possible.

We built a new Getting Started workflow that lets you select your development operating system and your mobile operating system up front, to provide one concise place with all the setup instructions. We also went through the installation process to make sure everything worked and to make sure that every decision point had a clear recommendation. After testing it out on our innocent coworkers, we're pretty sure this is an improvement.

We also worked on the guide to integrating React Native into an existing app. Many of the largest apps that use React Native, like the Facebook app itself, actually build part of the app in React Native, and part of it using regular development tools. We hope this guide makes it easier for more people to build apps this way.

We Need Your Help

Your feedback lets us know what we should prioritize. I know some people will read this blog post and think "Better docs? Pffft. The documentation for X is still garbage!". That's great - we need that energy. The best way to give us feedback depends on the sort of feedback.

If you find a mistake in the documentation, like inaccurate descriptions or code that doesn't actually work, file an issue. Tag it with "Documentation", so that it's easier to route it to the right people.

If there isn't a specific mistake, but something in the documentation is fundamentally confusing, it's not a great fit for a GitHub issue. Instead, post on Canny about the area of the docs that could use help. This helps us prioritize when we are doing more general work like guide-writing.

Thanks for reading this far, and thanks for using React Native!

React Native: A year in review

Martin Konicek

Martin Konicek

Software Engineer at Facebook

It's been one year since we open-sourced React Native. What started as an idea with a handful of engineers is now a framework being used by product teams across Facebook and beyond. Today at F8 we announced that Microsoft is bringing React Native to the Windows ecosystem, giving developers the potential to build React Native on Windows PC, Phone, and Xbox. It will also provide open source tools and services such as a React Native extension for Visual Studio Code and CodePush to help developers create React Native apps on the Windows platform. In addition, Samsung is building React Native for its hybrid platform, which will empower developers to build apps for millions of SmartTVs and mobile and wearable devices. We also released the Facebook SDK for React Native, which makes it easier for developers to incorporate Facebook social features like Login, Sharing, App Analytics, and Graph APIs into their apps. In one year, React Native has changed the way developers build on every major platform.

It's been an epic ride — but we are only getting started. Here is a look back at how React Native has grown and evolved since we open-sourced it a year ago, some challenges we faced along the way, and what we expect as we look ahead to the future.

This is an excerpt. Read the rest of the post on Facebook Code.

React Native for Android: How we built the first cross-platform React Native app

Daniel Witte

Software Engineer at Facebook

Earlier this year, we introduced React Native for iOS. React Native brings what developers are used to from React on the web — declarative self-contained UI components and fast development cycles — to the mobile platform, while retaining the speed, fidelity, and feel of native applications. Today, we're happy to release React Native for Android.

At Facebook we've been using React Native in production for over a year now. Almost exactly a year ago, our team set out to develop the Ads Manager app. Our goal was to create a new app to let the millions of people who advertise on Facebook manage their accounts and create new ads on the go. It ended up being not only Facebook's first fully React Native app but also the first cross-platform one. In this post, we'd like to share with you how we built this app, how React Native enabled us to move faster, and the lessons we learned.

This is an excerpt. Read the rest of the post on Facebook Code.

React Native: Bringing modern web techniques to mobile

Tom Occhino

Tom Occhino

Engineering Manager at Facebook

We introduced React to the world two years ago, and since then it's seen impressive growth, both inside and outside of Facebook. Today, even though no one is forced to use it, new web projects at Facebook are commonly built using React in one form or another, and it's being broadly adopted across the industry. Engineers are choosing to use React every day because it enables them to spend more time focusing on their products and less time fighting with their framework. It wasn't until we'd been building with React for a while, though, that we started to understand what makes it so powerful.

React forces us to break our applications down into discrete components, each representing a single view. These components make it easier to iterate on our products, since we don't need to keep the entire system in our head in order to make changes to one part of it. More important, though, React wraps the DOM's mutative, imperative API with a declarative one, which raises the level of abstraction and simplifies the programming model. What we've found is that when we build with React, our code is a lot more predictable. This predictability makes it so we can iterate more quickly with confidence, and our applications are a lot more reliable as a result. Additionally, it's not only easier to scale our applications when they're built with React, but we've found it's also easier to scale the size of our teams themselves.

Together with the rapid iteration cycle of the web, we've been able to build some awesome products with React, including many components of Facebook.com. Additionally, we've built amazing frameworks in JavaScript on top of React, like Relay, which allows us to greatly simplify our data fetching at scale. Of course, web is only part of the story. Facebook also has widely used Android and iOS apps, which are built on top of disjointed, proprietary technology stacks. Having to build our apps on top of multiple platforms has bifurcated our engineering organization, but that's only one of the things that makes native mobile application development hard.

This is an excerpt. Read the rest of the post on Facebook Code.

- + diff --git a/blog/tags/engineering.html b/blog/tags/engineering.html index c66067b4f28..97416d25084 100644 --- a/blog/tags/engineering.html +++ b/blog/tags/engineering.html @@ -19,7 +19,7 @@ - + @@ -98,7 +98,7 @@
return store;
};

When you change a reducer, the code to accept that reducer will be sent to the client. Then the client will realize that the reducer doesn't know how to accept itself, so it will look for all the modules that refer it and try to accept them. Eventually, the flow will get to the single store, the configureStore module, which will accept the HMR update.

Conclusion

If you are interested in helping making hot reloading better, I encourage you to read Dan Abramov's post around the future of hot reloading and to contribute. For example, Johny Days is going to make it work with multiple connected clients. We're relying on you all to maintain and improve this feature.

With React Native, we have the opportunity to rethink the way we build apps in order to make it a great developer experience. Hot reloading is only one piece of the puzzle, what other crazy hacks can we do to make it better?

Making React Native apps accessible

Georgiy Kassabli

Georgiy Kassabli

Software Engineer at Facebook

With the recent launch of React on web and React Native on mobile, we've provided a new front-end framework for developers to build products. One key aspect of building a robust product is ensuring that anyone can use it, including people who have vision loss or other disabilities. The Accessibility API for React and React Native enables you to make any React-powered experience usable by someone who may use assistive technology, like a screen reader for the blind and visually impaired.

For this post, we're going to focus on React Native apps. We've designed the React Accessibility API to look and feel similar to the Android and iOS APIs. If you've developed accessible applications for Android, iOS, or the web before, you should feel comfortable with the framework and nomenclature of the React AX API. For instance, you can make a UI element accessible (therefore exposed to assistive technology) and use accessibilityLabel to provide a string description for the element:

<View accessible={true} accessibilityLabel=”This is simple view”>

Let's walk through a slightly more involved application of the React AX API by looking at one of Facebook's own React-powered products: the Ads Manager app.

This is an excerpt. Read the rest of the post on Facebook Code.

- + diff --git a/blog/tags/engineering/index.html b/blog/tags/engineering/index.html index c66067b4f28..97416d25084 100644 --- a/blog/tags/engineering/index.html +++ b/blog/tags/engineering/index.html @@ -19,7 +19,7 @@ - + @@ -98,7 +98,7 @@
return store;
};

When you change a reducer, the code to accept that reducer will be sent to the client. Then the client will realize that the reducer doesn't know how to accept itself, so it will look for all the modules that refer it and try to accept them. Eventually, the flow will get to the single store, the configureStore module, which will accept the HMR update.

Conclusion

If you are interested in helping making hot reloading better, I encourage you to read Dan Abramov's post around the future of hot reloading and to contribute. For example, Johny Days is going to make it work with multiple connected clients. We're relying on you all to maintain and improve this feature.

With React Native, we have the opportunity to rethink the way we build apps in order to make it a great developer experience. Hot reloading is only one piece of the puzzle, what other crazy hacks can we do to make it better?

Making React Native apps accessible

Georgiy Kassabli

Georgiy Kassabli

Software Engineer at Facebook

With the recent launch of React on web and React Native on mobile, we've provided a new front-end framework for developers to build products. One key aspect of building a robust product is ensuring that anyone can use it, including people who have vision loss or other disabilities. The Accessibility API for React and React Native enables you to make any React-powered experience usable by someone who may use assistive technology, like a screen reader for the blind and visually impaired.

For this post, we're going to focus on React Native apps. We've designed the React Accessibility API to look and feel similar to the Android and iOS APIs. If you've developed accessible applications for Android, iOS, or the web before, you should feel comfortable with the framework and nomenclature of the React AX API. For instance, you can make a UI element accessible (therefore exposed to assistive technology) and use accessibilityLabel to provide a string description for the element:

<View accessible={true} accessibilityLabel=”This is simple view”>

Let's walk through a slightly more involved application of the React AX API by looking at one of Facebook's own React-powered products: the Ads Manager app.

This is an excerpt. Read the rest of the post on Facebook Code.

- + diff --git a/blog/tags/events.html b/blog/tags/events.html index 9978838d3db..1fc5f754a89 100644 --- a/blog/tags/events.html +++ b/blog/tags/events.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@

All Blog Posts

1 post tagged with "events"

View All Tags

San Francisco Meetup Recap

Héctor Ramos

Héctor Ramos

Developer Advocate at Facebook

Last week I had the opportunity to attend the React Native Meetup at Zynga’s San Francisco office. With around 200 people in attendance, it served as a great place to meet other developers near me that are also interested in React Native.

I was particularly interested in learning more about how React and React Native are used at companies like Zynga, Netflix, and Airbnb. The agenda for the night would be as follows:

  • Rapid Prototyping in React
  • Designing APIs for React Native
  • Bridging the Gap: Using React Native in Existing Codebases

But first, the event started off with a quick introduction and a brief recap of recent news:

If one of these meetups is held near you, I highly recommend attending!

Rapid Prototyping in React at Zynga

The first round of news was followed by a quick introduction by Zynga, our hosts for the evening. Abhishek Chadha talked about how they use React to quickly prototype new experiences on mobile, demoing a quick prototype of a Draw Something-like app. They use a similar approach as React Native, providing access to native APIs via a bridge. This was demonstrated when Abhishek used the device's camera to snap a photo of the audience and then drew a hat on someone's head.

Designing APIs for React Native at Netflix

Up next, the first featured talk of the evening. Clarence Leung, Senior Software Engineer at Netflix, presented his talk on Designing APIs for React Native. First he noted the two main types of libraries one may work on: components such as tab bars and date pickers, and libraries that provide access to native services such as the camera roll or in-app payments. There are two ways one may approach when building a library for use in React Native:

  • Provide platform-specific components
  • A cross-platform library with a similar API for both Android and iOS

Each approach has its own considerations, and it’s up to you to determine what works best for your needs.

Approach #1

As an example of platform-specific components, Clarence talked about the DatePickerIOS and DatePickerAndroid from core React Native. On iOS, date pickers are rendered as part of the UI and can be easily embedded in an existing view, while date pickers on Android are presented modally. It makes sense to provide separate components in this case.

Approach #2

Photo pickers, on the other hand, are treated similarly on Android and iOS. There are some slight differences — Android does not group photos into folders like iOS does with Selfies, for example — but those are easily handled using if statements and the Platform component.

Regardless of which approach you settle on, it’s a good idea to minimize the API surface and build app-specific libraries. For example, iOS’s In-App Purchase framework supports one-time, consumable purchases, as well as renewable subscriptions. If your app will only need to support consumable purchases, you may get away with dropping support for subscriptions in your cross-platform library.

There was a brief Q&A session at the end of Clarence’s talk. One of the interesting tid bits that came out of it was that around 80% of the React Native code written for these libraries at Netflix is shared across both Android and iOS.

Bridging the Gap, Using React Native in Existing Codebases

The final talk of the night was by Leland Richardson from Airbnb. The talk was focused on the use of React Native in existing codebases. I already know how easy it is to write a new app from scratch using React Native, so I was very interested to hear about Airbnb’s experience adopting React Native in their existing native apps.

Leland started off by talking about greenfield apps versus brownfield apps. Greenfield means to start a project without the need to consider any prior work. This is in contrast to brownfield projects where you need to take into account the existing project’s requirements, development processes, and all of the teams various needs.

When you’re working on a greenfield app, the React Native CLI sets up a single repository for both Android and iOS and everything just works. The first challenge against using React Native at Airbnb was the fact that the Android and iOS app each had their own repository. Multi-repo companies have some hurdles to get past before they can adopt React Native.

To get around this, Airbnb first set up a new repo for the React Native codebase. They used their continuous integration servers to mirror the Android and iOS repos into this new repo. After tests are run and the bundle is built, the build artifacts are synced back to the Android and iOS repos. This allows the mobile engineers to work on native code without altering their development environment. Mobile engineers don't need to install npm, run the packager, or remember to build the JavaScript bundle. The engineers writing actual React Native code do not have to worry about syncing their code across Android and iOS, as they work on the React Native repository directly.

This does come with some drawbacks, mainly they could not ship atomic updates. Changes that require a combination of native and JavaScript code would require three separate pull requests, all of which had to be carefully landed. In order to avoid conflicts, CI will fail to land changes back to the Android and iOS repos if master has changed since the build started. This would cause long delays during high commit frequency days (such as when new releases are cut).

Airbnb has since moved to a mono repo approach. Fortunately this was already under consideration, and once the Android and iOS teams became comfortable with using React Native they were happy to accelerate the move towards the mono repo.

This has solved most of the issues they had with the split repo approach. Leland did note that this does cause a higher strain on the version control servers, which may be an issue for smaller companies.

The Navigation Problem

The second half of Leland's talk focused on a topic that is dear to me: the Navigation problem in React Native. He talked about the abundance of navigation libraries in React Native, both first party and third party. NavigationExperimental was mentioned as something that seemed promising, but ended up not being well suited for their use case.

In fact, none of the existing navigation libraries seem to work well for brownfield apps. A brownfield app requires that the navigation state be fully owned by the native app. For example, if a user’s session expires while a React Native view is being presented, the native app should be able to take over and present a login screen as needed.

Airbnb also wanted to avoid replacing native navigation bars with JavaScript versions as part of a transition, as the effect could be jarring. Initially they limited themselves to modally presented views, but this obviously presented a problem when it came to adopting React Native more widely within their apps.

They decided that they needed their own library. The library is called airbnb-navigation. The library has not yet being open sourced as it is strongly tied to Airbnb’s codebase, but it is something they’d like to release by the end of the year.

I won’t go into much detail into the library’s API, but here are some of the key takeaways:

  • One must preregister scenes ahead of time
  • Each scene is displayed within its own RCTRootView. They are presented natively on each platform (e.g. UINavigationControllers are used on iOS).
  • The main ScrollView in a scene should be wrapped in a ScrollScene component. Doing so allows you to take advantage of native behaviors such as tapping on the status bar to scroll to the top on iOS.
  • Transitions between scenes are handled natively, no need to worry about performance.
  • The Android back button is automatically supported.
  • They can take advantage of View Controller based navigation bar styling via a Navigator.Config UI-less component.

There’s also some considerations to keep in mind:

  • The navigation bar is not easily customized in JavaScript, as it is a native component. This is intentional, as using native navigation bars is a hard requirement for this type of library.
  • ScreenProps must be serialized/de-serialized whenever they're sent through the bridge, so care must be taken if sending too much data here.
  • Navigation state is owned by the native app (also a hard requirement for the library), so things like Redux cannot manipulate navigation state.

Leland's talk was also followed by a Q&A session. Overall, Airbnb is satisfied with React Native. They’re interested in using Code Push to fix any issues without going through the App Store, and their engineers love Live Reload, as they don't have to wait for the native app to be rebuilt after every minor change.

Closing Remarks

The event ended with some additional React Native news:

Meetups provide a good opportunity to meet and learn from other developers in the community. I'm looking forward to attending more React Native meetups in the future. If you make it up to one of these, please look out for me and let me know how we can make React Native work better for you!

- + diff --git a/blog/tags/events/index.html b/blog/tags/events/index.html index 9978838d3db..1fc5f754a89 100644 --- a/blog/tags/events/index.html +++ b/blog/tags/events/index.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@

All Blog Posts

1 post tagged with "events"

View All Tags

San Francisco Meetup Recap

Héctor Ramos

Héctor Ramos

Developer Advocate at Facebook

Last week I had the opportunity to attend the React Native Meetup at Zynga’s San Francisco office. With around 200 people in attendance, it served as a great place to meet other developers near me that are also interested in React Native.

I was particularly interested in learning more about how React and React Native are used at companies like Zynga, Netflix, and Airbnb. The agenda for the night would be as follows:

  • Rapid Prototyping in React
  • Designing APIs for React Native
  • Bridging the Gap: Using React Native in Existing Codebases

But first, the event started off with a quick introduction and a brief recap of recent news:

If one of these meetups is held near you, I highly recommend attending!

Rapid Prototyping in React at Zynga

The first round of news was followed by a quick introduction by Zynga, our hosts for the evening. Abhishek Chadha talked about how they use React to quickly prototype new experiences on mobile, demoing a quick prototype of a Draw Something-like app. They use a similar approach as React Native, providing access to native APIs via a bridge. This was demonstrated when Abhishek used the device's camera to snap a photo of the audience and then drew a hat on someone's head.

Designing APIs for React Native at Netflix

Up next, the first featured talk of the evening. Clarence Leung, Senior Software Engineer at Netflix, presented his talk on Designing APIs for React Native. First he noted the two main types of libraries one may work on: components such as tab bars and date pickers, and libraries that provide access to native services such as the camera roll or in-app payments. There are two ways one may approach when building a library for use in React Native:

  • Provide platform-specific components
  • A cross-platform library with a similar API for both Android and iOS

Each approach has its own considerations, and it’s up to you to determine what works best for your needs.

Approach #1

As an example of platform-specific components, Clarence talked about the DatePickerIOS and DatePickerAndroid from core React Native. On iOS, date pickers are rendered as part of the UI and can be easily embedded in an existing view, while date pickers on Android are presented modally. It makes sense to provide separate components in this case.

Approach #2

Photo pickers, on the other hand, are treated similarly on Android and iOS. There are some slight differences — Android does not group photos into folders like iOS does with Selfies, for example — but those are easily handled using if statements and the Platform component.

Regardless of which approach you settle on, it’s a good idea to minimize the API surface and build app-specific libraries. For example, iOS’s In-App Purchase framework supports one-time, consumable purchases, as well as renewable subscriptions. If your app will only need to support consumable purchases, you may get away with dropping support for subscriptions in your cross-platform library.

There was a brief Q&A session at the end of Clarence’s talk. One of the interesting tid bits that came out of it was that around 80% of the React Native code written for these libraries at Netflix is shared across both Android and iOS.

Bridging the Gap, Using React Native in Existing Codebases

The final talk of the night was by Leland Richardson from Airbnb. The talk was focused on the use of React Native in existing codebases. I already know how easy it is to write a new app from scratch using React Native, so I was very interested to hear about Airbnb’s experience adopting React Native in their existing native apps.

Leland started off by talking about greenfield apps versus brownfield apps. Greenfield means to start a project without the need to consider any prior work. This is in contrast to brownfield projects where you need to take into account the existing project’s requirements, development processes, and all of the teams various needs.

When you’re working on a greenfield app, the React Native CLI sets up a single repository for both Android and iOS and everything just works. The first challenge against using React Native at Airbnb was the fact that the Android and iOS app each had their own repository. Multi-repo companies have some hurdles to get past before they can adopt React Native.

To get around this, Airbnb first set up a new repo for the React Native codebase. They used their continuous integration servers to mirror the Android and iOS repos into this new repo. After tests are run and the bundle is built, the build artifacts are synced back to the Android and iOS repos. This allows the mobile engineers to work on native code without altering their development environment. Mobile engineers don't need to install npm, run the packager, or remember to build the JavaScript bundle. The engineers writing actual React Native code do not have to worry about syncing their code across Android and iOS, as they work on the React Native repository directly.

This does come with some drawbacks, mainly they could not ship atomic updates. Changes that require a combination of native and JavaScript code would require three separate pull requests, all of which had to be carefully landed. In order to avoid conflicts, CI will fail to land changes back to the Android and iOS repos if master has changed since the build started. This would cause long delays during high commit frequency days (such as when new releases are cut).

Airbnb has since moved to a mono repo approach. Fortunately this was already under consideration, and once the Android and iOS teams became comfortable with using React Native they were happy to accelerate the move towards the mono repo.

This has solved most of the issues they had with the split repo approach. Leland did note that this does cause a higher strain on the version control servers, which may be an issue for smaller companies.

The Navigation Problem

The second half of Leland's talk focused on a topic that is dear to me: the Navigation problem in React Native. He talked about the abundance of navigation libraries in React Native, both first party and third party. NavigationExperimental was mentioned as something that seemed promising, but ended up not being well suited for their use case.

In fact, none of the existing navigation libraries seem to work well for brownfield apps. A brownfield app requires that the navigation state be fully owned by the native app. For example, if a user’s session expires while a React Native view is being presented, the native app should be able to take over and present a login screen as needed.

Airbnb also wanted to avoid replacing native navigation bars with JavaScript versions as part of a transition, as the effect could be jarring. Initially they limited themselves to modally presented views, but this obviously presented a problem when it came to adopting React Native more widely within their apps.

They decided that they needed their own library. The library is called airbnb-navigation. The library has not yet being open sourced as it is strongly tied to Airbnb’s codebase, but it is something they’d like to release by the end of the year.

I won’t go into much detail into the library’s API, but here are some of the key takeaways:

  • One must preregister scenes ahead of time
  • Each scene is displayed within its own RCTRootView. They are presented natively on each platform (e.g. UINavigationControllers are used on iOS).
  • The main ScrollView in a scene should be wrapped in a ScrollScene component. Doing so allows you to take advantage of native behaviors such as tapping on the status bar to scroll to the top on iOS.
  • Transitions between scenes are handled natively, no need to worry about performance.
  • The Android back button is automatically supported.
  • They can take advantage of View Controller based navigation bar styling via a Navigator.Config UI-less component.

There’s also some considerations to keep in mind:

  • The navigation bar is not easily customized in JavaScript, as it is a native component. This is intentional, as using native navigation bars is a hard requirement for this type of library.
  • ScreenProps must be serialized/de-serialized whenever they're sent through the bridge, so care must be taken if sending too much data here.
  • Navigation state is owned by the native app (also a hard requirement for the library), so things like Redux cannot manipulate navigation state.

Leland's talk was also followed by a Q&A session. Overall, Airbnb is satisfied with React Native. They’re interested in using Code Push to fix any issues without going through the App Store, and their engineers love Live Reload, as they don't have to wait for the native app to be rebuilt after every minor change.

Closing Remarks

The event ended with some additional React Native news:

Meetups provide a good opportunity to meet and learn from other developers in the community. I'm looking forward to attending more React Native meetups in the future. If you make it up to one of these, please look out for me and let me know how we can make React Native work better for you!

- + diff --git a/blog/tags/index.html b/blog/tags/index.html index f7d4cde3069..854f04ab078 100644 --- a/blog/tags/index.html +++ b/blog/tags/index.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@

All Blog Posts

Tags

- + diff --git a/blog/tags/release.html b/blog/tags/release.html index ab69cd0bc5c..8d822b20c80 100644 --- a/blog/tags/release.html +++ b/blog/tags/release.html @@ -19,7 +19,7 @@ - + @@ -52,7 +52,7 @@
const MyComponent = () => {
const colorScheme = useColorScheme();
return <Text>useColorScheme(): {colorScheme}</Text>;
};

See the docs for Appearance and useColorScheme for more information.

Moving Apple TV to react-native-tvos

As part of our Lean Core effort and to bring Apple TV in line with other platforms like React Native Windows and React Native macOS, we’ve started to remove Apple TV specific code from core.

Going forward, Apple TV support for React Native will be maintained in react-native-community/react-native-tvos along with the corresponding react-native-tvos NPM package. This is a full fork of the main repository, with only the changes needed to support Apple TV.

Releases of react-native-tvos will be based on the public release of React Native. For this 0.62 release of react-native please upgrade Apple TV projects to use react-native-tvos 0.62.

More upgrade support

When 0.61 was released, the community introduced a new upgrade helper tool to support developers upgrading to new versions of React Native. The upgrade helper provides a diff of changes from the version you're on to the version you're targeting, allowing you to see the changes that need to be made for your specific upgrade.

Even with this tool, issues come up when upgrading. Today we're introducing more dedicated upgrading support by announcing Upgrade-Support. Upgrade Support is a GitHub issue tracker where users can submit issues specific to upgrading their projects to receive help from the community.

We're always working to improve the upgrade experience, and we hope that these tools give users the support they need in the edge cases we haven't covered yet.

Other improvements

Breaking changes

Deprecations

Thanks

Thank you to the hundreds of contributors that helped make 0.62 possible!

To see all the updates, take a look at the 0.62 changelog.

Announcing React Native 0.61 with Fast Refresh

Dan Abramov

Dan Abramov

React Core at Facebook

We’re excited to announce React Native 0.61, which includes a new reloading experience we’re calling Fast Refresh.

Fast Refresh

When we asked the React Native community about common pain points, one of the top answers was that the “hot reloading” feature was broken. It didn’t work reliably for function components, often failed to update the screen, and wasn’t resilient to typos and mistakes. We heard that most people turned it off because it was too unreliable.

In React Native 0.61, we’re unifying the existing “live reloading” (reload on save) and “hot reloading” features into a single new feature called “Fast Refresh”. Fast Refresh was implemented from scratch with the following principles:

  • Fast Refresh fully supports modern React, including function components and Hooks.
  • Fast Refresh gracefully recovers after typos and other mistakes, and falls back to a full reload when needed.
  • Fast Refresh doesn’t perform invasive code transformations so it’s reliable enough to be on by default.

To see Fast Refresh in action, check out this video:

Give it a try, and let us know what you think! If you prefer, you can turn it off in the Dev Menu (Cmd+D on iOS, Cmd+M or Ctrl+M on Android). Turning it on and off is instant so you can do it any time.

Here are a few Fast Refresh tips:

  • Fast Refresh preserves React local state in function components (and Hooks!) by default.
  • If you need to reset the React state on every edit, you can add a special // @refresh reset comment to the file with that component.
  • Fast Refresh always remounts class components without preserving state. This ensures it works reliably.
  • We all make mistakes in the code! Fast Refresh automatically retries rendering after you save a file. You don't need to reload the app manually after fixing a syntax or a runtime error.
  • Adding a console.log or a debugger statement during edits is a neat debugging technique.

Please report any issues with Fast Refresh on GitHub, and we’ll look into them.

Other Improvements

  • Fixed use_frameworks! CocoaPods support. In 0.60 we made some updates to integrate CocoaPods by default. Unfortunately, this broke builds using use_frameworks!. This is fixed in 0.61, making it easier to integrate React Native into your iOS projects that require building with dynamic frameworks.
  • Add useWindowDimensions Hook. This new Hook automatically provides and subscribes to dimension updates, and can be used instead of the Dimensions API in most cases.
  • React was upgraded to 16.9. This version deprecates old names for the UNSAFE_ lifecycle methods, contains improvements to act, and more. See the React 16.9 blog post for an automated migration script and more information.

Breaking Changes

  • Remove React .xcodeproj. In 0.60, we introduced auto-linking support via CocoaPods. We have also integrated CocoaPods into the e2e tests runs, so that from now on, we have a unified standard way of integrating RN into iOS apps. This effectively deprecates the React .xcodeproj support, and the file has been removed starting 0.61. Note: if you use 0.60 auto-linking already, you shouldn't be affected.

Thanks

Thanks to all of the contributors that helped make 0.61 possible!

To see all the updates, take a look at the 0.61 changelog.

Announcing React Native 0.60

Ryan Turner

Ryan Turner

Core Maintainer & React Native Developer

After months of hard work from hundreds of contributors, the React Native Core team is proud to announce the release of version 0.60. This release handles significant migrations for both Android and iOS platforms, and many issues are resolved too. This blog post covers the highlights of the release. As always though, refer to the changelog for more detailed information. Finally, thank you contributors for helping us to make this milestone!

Focus on Accessibility

There have been many improvements to the accessibility APIs, like announceForAccessibility, plus improvements to roles, action support, flags, and more. Accessibility is a complex science, but we hope these improvements make it a bit easier to be an A11Y. Be sure to check React Native Open Source Update June 2019 for more details of these changes.

A Fresh Start

React Native's start screen has been updated! Thank you to the many contributors who helped create the new UI. This new "Hello World" will welcome users to the ecosystem in a more friendly, engaging way.

The new init screen helps developers get started from the get-go with resources and a good example

AndroidX Support

AndroidX is a major step forward in the Android ecosystem, and the old support library artifacts are being deprecated. For 0.60, React Native has been migrated over to AndroidX. This is a breaking change, and your native code and dependencies will need to be migrated as well.

With this change, React Native apps will need to begin using AndroidX themselves. They cannot be used side-by-side in one app, so all of the app code and dependency code needs to be using one or the other.

matt-oakes on discussions-and-proposals

While your own native code will need to be migrated by you, @mikehardy, @cawfree, and @m4tt72 built a clever tool named "jetifier" to patch your node_modules. Library maintainers will need to upgrade, but this tool provide you with a temporary solution while giving them time to release an AndroidX version. So if you find errors related to AndroidX migration, give this a shot.

CocoaPods by Default

CocoaPods are now part of React Native's iOS project. If you weren't already, be sure to open iOS platform code using the xcworkspace file from now on (protip: try xed ios from the root project directory). Also, the podspecs for the internal packages have changed to make them compatible with the Xcode projects, which will help with troubleshooting and debugging. Expect to make some straightforward changes to your Podfile as part of the upgrade to 0.60 to bring this exciting support. Note that we are aware of a compatibility issue with use_frameworks!, and we're tracking an issue with workarounds and a future patch.

Lean Core Removals

WebView and NetInfo were previously extracted into separate repositories, and in 0.60 we’ve finished migrating them out of the React Native repository. Additionally, in response to community feedback about new App Store policy, Geolocation has been extracted. If you haven’t already, complete your migration by adding dependencies to react-native-webview, @react-native-community/netinfo, and @react-native-community/geolocation. If you'd like an automated solution, consider using rn-upgrade-deprecated-modules. Maintainers have made more than 100 commits to these repositories since extraction and we’re excited to see the community’s support!

Native Modules are now Autolinked

The team working on the React Native CLI has introduced major improvements to native module linking called autolinking! Most scenarios will not require the use of react-native link anymore. At the same time, the team overhauled the linking process in general. Be sure to react-native unlink any preexisting dependencies as mentioned in the docs above.

Upgrade Helper

@lucasbento, @pvinis, @kelset, and @watadarkstar have built a great tool called Upgrade Helper to make the upgrade process simpler. It helps React Native users with brownfield apps or complex customizations to see what's changed between versions. Take a look at the updated upgrading docs and try it out today for your upgrade path!

Upgrade Helper cleanly and easily shows the changes needed to migrate to a different version of React Native

A Note to Library Maintainers

Changes for AndroidX will almost certainly require updates to your library, so be sure to include support soon. If you're not able to upgrade yet, consider checking your library against the jetifier to confirm that users are able to patch your library at build time.

Review the autolinking docs to update your configs and readme. Depending on how your library was previously integrated, you may also need to make some additional changes. Check the dependencies guide from the CLI for information on how to define your dependency interface.

Thanks

While these are the highlights that we noted, there are many others to be excited about. To see all the updates, take a look at the changelog. As always, stay tuned for more news. Enjoy 0.60 in the meantime!

Releasing React Native 0.59

Ryan Turner

Ryan Turner

Core Maintainer & React Native Developer

Welcome to the 0.59 release of React Native! This is another big release with 644 commits by 88 contributors. Contributions also come in other forms, so thank you for maintaining issues, fostering communities, and teaching people about React Native. This month brings a number of highly anticipated changes, and we hope you enjoy them.

🎣 Hooks are here

React Hooks are part of this release, which let you reuse stateful logic across components. There is a lot of buzz about hooks, but if you haven't heard, take a look at some of the wonderful resources below:

Be sure to give this a try in your apps. We hope that you find the reuse as exciting as we do.

📱 Updated JSC means performance gains and 64-bit support on Android

React Native uses JSC (JavaScriptCore) to power your application. JSC on Android was a few years old, which meant that a lot of modern JavaScript features weren't supported. Even worse, it performed poorly compared iOS's modern JSC. With this release, that all changes.

Thanks to some awesome work by @DanielZlotin, @dulmandakh, @gengjiawen, @kmagiera, and @kudo JSC has caught up with the past few years. This brings with it 64-bit support, modern JavaScript support, and big performance improvements. Kudos for also making this a maintainable process now so that we can take advantage of future WebKit improvements without so much legwork, and thank you Software Mansion and Expo for making this work possible.

💨 Faster app launches with inline requires

We want to help people have performant React Native apps by default and are working to bring Facebook's optimizations to the community. Applications load resources as needed rather than slowing down launch. This feature is called "inline requires", as it lets Metro identify components to be lazy loaded. Apps with a deep and varied component architecture will see the most improvement.

source of the `metro.config.js` file in the 0.59 template, demonstrating where to enable `inlineRequires`

We need the community to let us know how it works before we turn it on by default. When you upgrade to 0.59, there will be a new metro.config.js file; flip the options to true and give us your feedback! Read more about inline requires in the performance docs to benchmark your app.

🚅 Lean core is underway

React Native is a large and complex project with a complicated repository. This makes the codebase less approachable to contributors, difficult to test, and bloated as a dev dependency. Lean Core is our effort to address these issues by migrating code to separate libraries for better management. The past few releases have seen the first steps of this, but let's get serious.

You may notice that additional components are now officially deprecated. This is great news, as there are now owners for these features actively maintaining them. Heed the warning messages and migrate to the new libraries for these features, because they will be removed in a future release. Below is a table indicating the component, its status, and where you may migrate your use to.

ComponentDeprecated?New home
AsyncStorage0.59@react-native-community/react-native-async-storage
ImageStore0.59expo-file-system or react-native-fs
MaskedViewIOS0.59@react-native-community/react-native-masked-view
NetInfo0.59@react-native-community/react-native-netinfo
Slider0.59@react-native-community/react-native-slider
ViewPagerAndroid0.59@react-native-community/react-native-viewpager

Over the coming months, there will be many more components following this path to a leaner core. We're looking for help with this — head over to the lean core umbrella to pitch in.

👩🏽‍💻 CLI improvements

React Native's command line tools are developer's entry point to the ecosystem, but they had long-standing issues and lacked official support. The CLI tools have been moved to a new repository, and a dedicated group of maintainers have already made some exciting improvements.

Logs are formatted much better now. Commands now run nearly instantly — you'll immediately notice a difference:

0.58's CLI is slow to start0.58's CLI is nearly instantaneous

🚀 Upgrading to 0.59

We heard your feedback regarding the React Native upgrade process and we are taking steps to improve the experience in future releases. To upgrade to 0.59, we recommend using rn-diff-purge to determine what has changed between your current React Native version and 0.59, then applying those changes manually. Once you've upgraded your project to 0.59, you will be able to use the newly improved react-native upgrade command (based on rn-diff-purge!) to upgrade to 0.60 and beyond as newer releases become available.

🔨 Breaking Changes

Android support in 0.59 has been cleaned up following Google's latest recommendations, which may result in potential breakage of existing apps. This issue might present as a runtime crash and a message, "You need to use a Theme.AppCompat theme (or descendant) with this activity". We recommend updating your project's AndroidManifest.xml file, making sure that the android:theme value is an AppCompat theme (such as @style/Theme.AppCompat.Light.NoActionBar).

The react-native-git-upgrade command has been removed in 0.59, in favor of the newly improved react-native upgrade command.

🤗 Thanks

Lots of new contributors helped with enabling generation of native code from flow types and resolving Xcode warnings - these are a great way to learn how React Native works and contributing to the greater good. Thank you! Look out for similar issues in the future.

While these are the highlights that we noted, there are many others to be excited about. To see all of the updates, take a look at the changelog. 0.59 is a huge release – we can't wait for you to try it out.

We have even more improvements coming throughout the rest of the year. Stay tuned!

Ryan and the whole React Native core team

Releasing 0.56

Lorenzo Sciandra

Lorenzo Sciandra

Core Maintainer & React Native Developer at Drivetribe

The long-awaited 0.56 version of React Native is now available 🎉. This blog post highlights some of the changes introduced in this new release. We also want to take the opportunity to explain what has kept us busy since March.

The breaking changes dilemma, or, "when to release?"

The Contributor's Guide explains the integration process that all changes to React Native go through. The project has is composed by many different tools, requiring coordination and constant support to keep everything working properly. Add to this the vibrant open source community that contributes back to the project, and you will get a sense of the mind-bending scale of it all.

With React Native's impressive adoption, breaking changes must be made with great care, and the process is not as smooth as we'd like. A decision was made to skip the April and May releases to allow the core team to integrate and test a new set of breaking changes. Dedicated community communication channels were used along the way to ensure that the June 2018 (0.56.0) release is as hassle-free as possible to adopt by those who patiently waited for the stable release.

Is 0.56.0 perfect? No, as every piece of software out there: but we reached a point where the tradeoff between "waiting for more stability" versus "testing led to successful results so we can push forward" that we feel ready to release it. Moreover, we are aware of a few issues that are not solved in the final 0.56.0 release. Most developers should have no issues upgrading to 0.56.0. For those that are blocked by the aforementioned issues, we hope to see you around in our discussions and we are looking forward to working with you on a solution to these issues.

You might consider 0.56.0 as a fundamental building block towards a more stable framework: it will take probably a week or two of widespread adoption before all the edge cases will be sanded off, but this will lead to an even better July 2018 (0.57.0) release.

We'd like to conclude this section by thanking all the 67 contributors who worked on a total of 818 commits (!) that will help make your apps even better 👏.

And now, without further ado...

The Big Changes

Babel 7

As you may know, the transpiler tool that allows us all to use the latest and greatest features of JavaScript, Babel, is moving to v7 soon. Since this new version brings along some important changes, we felt that now it would be a good time to upgrade, allowing Metro to leverage on its improvements.

If you find yourself in trouble with upgrading, please refer to the documentation section related to it.

Modernizing Android support

On Android, much of the surrounding tooling has changed. We've updated to Gradle 3.5, Android SDK 26, Fresco to 1.9.0, and OkHttp to 3.10.0 and even the NDK API target to API 16. These changes should go without issue and result in faster builds. More importantly, it will help developers comply with the new Play Store requirements coming into effect next month.

Related to this, we'd like to particularly thank Dulmandakh for the many PRs submitted in order to make it possible 👏.

There are some more steps that need to be taken in this direction, and you can follow along with the future planning and discussion of updating the Android support in the dedicated issue (and a side one for the JSC).

New Node, Xcode, React, and Flow – oh my!

Node 8 is now the standard for React Native. It was actually already being tested already, but we've put both feet forward as Node 6 entered maintenance mode. React was also updated to 16.4, which brings a ton of fixes with it.

We're dropping support for iOS 8, making iOS 9 the oldest iOS version that can be targeted. We do not foresee this being a problem, as any device that can run iOS 8, can be upgraded to iOS 9. This change allowed us to remove rarely-used code that implemented workarounds for older devices running iOS 8.

The continuous integration toolchain has been updated to use Xcode 9.4, ensuring that all iOS tests are run on the latest developer tools provided by Apple.

We have upgraded to Flow 0.75 to use the new error format that many devs appreciate. We've also created types for many more components. If you're not yet enforcing static typing in your project, please consider using Flow to identify problems as you code instead of at runtime.

And a lot of other things...

For instance, YellowBox was replaced with a new implementation that makes debugging a lot better.

For the complete release notes, please reference the full changelog here. And remember to keep an eye on the upgrading guide to avoid issues moving to this new version.

A final note: starting this week, the React Native core team will resume holding monthly meetings. We'll make sure to keep everyone up-to-date with what's covered, and ensure to keep your feedback at hand for future meetings.

Happy coding everyone!

Lorenzo, Ryan, and the whole React Native core team

PS: as always, we'd like to remind everyone that React Native is still in 0.x versioning because of the many changes still undergoing - so remember when upgrading that yes, probably, something may still crash or be broken. Be helpful towards each other in the issues and when submitting PRs - and remember to follow the CoC enforced: there's always a human on the other side of the screen.

- + diff --git a/blog/tags/release/index.html b/blog/tags/release/index.html index ab69cd0bc5c..8d822b20c80 100644 --- a/blog/tags/release/index.html +++ b/blog/tags/release/index.html @@ -19,7 +19,7 @@ - + @@ -52,7 +52,7 @@
const MyComponent = () => {
const colorScheme = useColorScheme();
return <Text>useColorScheme(): {colorScheme}</Text>;
};

See the docs for Appearance and useColorScheme for more information.

Moving Apple TV to react-native-tvos

As part of our Lean Core effort and to bring Apple TV in line with other platforms like React Native Windows and React Native macOS, we’ve started to remove Apple TV specific code from core.

Going forward, Apple TV support for React Native will be maintained in react-native-community/react-native-tvos along with the corresponding react-native-tvos NPM package. This is a full fork of the main repository, with only the changes needed to support Apple TV.

Releases of react-native-tvos will be based on the public release of React Native. For this 0.62 release of react-native please upgrade Apple TV projects to use react-native-tvos 0.62.

More upgrade support

When 0.61 was released, the community introduced a new upgrade helper tool to support developers upgrading to new versions of React Native. The upgrade helper provides a diff of changes from the version you're on to the version you're targeting, allowing you to see the changes that need to be made for your specific upgrade.

Even with this tool, issues come up when upgrading. Today we're introducing more dedicated upgrading support by announcing Upgrade-Support. Upgrade Support is a GitHub issue tracker where users can submit issues specific to upgrading their projects to receive help from the community.

We're always working to improve the upgrade experience, and we hope that these tools give users the support they need in the edge cases we haven't covered yet.

Other improvements

Breaking changes

Deprecations

Thanks

Thank you to the hundreds of contributors that helped make 0.62 possible!

To see all the updates, take a look at the 0.62 changelog.

Announcing React Native 0.61 with Fast Refresh

Dan Abramov

Dan Abramov

React Core at Facebook

We’re excited to announce React Native 0.61, which includes a new reloading experience we’re calling Fast Refresh.

Fast Refresh

When we asked the React Native community about common pain points, one of the top answers was that the “hot reloading” feature was broken. It didn’t work reliably for function components, often failed to update the screen, and wasn’t resilient to typos and mistakes. We heard that most people turned it off because it was too unreliable.

In React Native 0.61, we’re unifying the existing “live reloading” (reload on save) and “hot reloading” features into a single new feature called “Fast Refresh”. Fast Refresh was implemented from scratch with the following principles:

  • Fast Refresh fully supports modern React, including function components and Hooks.
  • Fast Refresh gracefully recovers after typos and other mistakes, and falls back to a full reload when needed.
  • Fast Refresh doesn’t perform invasive code transformations so it’s reliable enough to be on by default.

To see Fast Refresh in action, check out this video:

Give it a try, and let us know what you think! If you prefer, you can turn it off in the Dev Menu (Cmd+D on iOS, Cmd+M or Ctrl+M on Android). Turning it on and off is instant so you can do it any time.

Here are a few Fast Refresh tips:

  • Fast Refresh preserves React local state in function components (and Hooks!) by default.
  • If you need to reset the React state on every edit, you can add a special // @refresh reset comment to the file with that component.
  • Fast Refresh always remounts class components without preserving state. This ensures it works reliably.
  • We all make mistakes in the code! Fast Refresh automatically retries rendering after you save a file. You don't need to reload the app manually after fixing a syntax or a runtime error.
  • Adding a console.log or a debugger statement during edits is a neat debugging technique.

Please report any issues with Fast Refresh on GitHub, and we’ll look into them.

Other Improvements

  • Fixed use_frameworks! CocoaPods support. In 0.60 we made some updates to integrate CocoaPods by default. Unfortunately, this broke builds using use_frameworks!. This is fixed in 0.61, making it easier to integrate React Native into your iOS projects that require building with dynamic frameworks.
  • Add useWindowDimensions Hook. This new Hook automatically provides and subscribes to dimension updates, and can be used instead of the Dimensions API in most cases.
  • React was upgraded to 16.9. This version deprecates old names for the UNSAFE_ lifecycle methods, contains improvements to act, and more. See the React 16.9 blog post for an automated migration script and more information.

Breaking Changes

  • Remove React .xcodeproj. In 0.60, we introduced auto-linking support via CocoaPods. We have also integrated CocoaPods into the e2e tests runs, so that from now on, we have a unified standard way of integrating RN into iOS apps. This effectively deprecates the React .xcodeproj support, and the file has been removed starting 0.61. Note: if you use 0.60 auto-linking already, you shouldn't be affected.

Thanks

Thanks to all of the contributors that helped make 0.61 possible!

To see all the updates, take a look at the 0.61 changelog.

Announcing React Native 0.60

Ryan Turner

Ryan Turner

Core Maintainer & React Native Developer

After months of hard work from hundreds of contributors, the React Native Core team is proud to announce the release of version 0.60. This release handles significant migrations for both Android and iOS platforms, and many issues are resolved too. This blog post covers the highlights of the release. As always though, refer to the changelog for more detailed information. Finally, thank you contributors for helping us to make this milestone!

Focus on Accessibility

There have been many improvements to the accessibility APIs, like announceForAccessibility, plus improvements to roles, action support, flags, and more. Accessibility is a complex science, but we hope these improvements make it a bit easier to be an A11Y. Be sure to check React Native Open Source Update June 2019 for more details of these changes.

A Fresh Start

React Native's start screen has been updated! Thank you to the many contributors who helped create the new UI. This new "Hello World" will welcome users to the ecosystem in a more friendly, engaging way.

The new init screen helps developers get started from the get-go with resources and a good example

AndroidX Support

AndroidX is a major step forward in the Android ecosystem, and the old support library artifacts are being deprecated. For 0.60, React Native has been migrated over to AndroidX. This is a breaking change, and your native code and dependencies will need to be migrated as well.

With this change, React Native apps will need to begin using AndroidX themselves. They cannot be used side-by-side in one app, so all of the app code and dependency code needs to be using one or the other.

matt-oakes on discussions-and-proposals

While your own native code will need to be migrated by you, @mikehardy, @cawfree, and @m4tt72 built a clever tool named "jetifier" to patch your node_modules. Library maintainers will need to upgrade, but this tool provide you with a temporary solution while giving them time to release an AndroidX version. So if you find errors related to AndroidX migration, give this a shot.

CocoaPods by Default

CocoaPods are now part of React Native's iOS project. If you weren't already, be sure to open iOS platform code using the xcworkspace file from now on (protip: try xed ios from the root project directory). Also, the podspecs for the internal packages have changed to make them compatible with the Xcode projects, which will help with troubleshooting and debugging. Expect to make some straightforward changes to your Podfile as part of the upgrade to 0.60 to bring this exciting support. Note that we are aware of a compatibility issue with use_frameworks!, and we're tracking an issue with workarounds and a future patch.

Lean Core Removals

WebView and NetInfo were previously extracted into separate repositories, and in 0.60 we’ve finished migrating them out of the React Native repository. Additionally, in response to community feedback about new App Store policy, Geolocation has been extracted. If you haven’t already, complete your migration by adding dependencies to react-native-webview, @react-native-community/netinfo, and @react-native-community/geolocation. If you'd like an automated solution, consider using rn-upgrade-deprecated-modules. Maintainers have made more than 100 commits to these repositories since extraction and we’re excited to see the community’s support!

Native Modules are now Autolinked

The team working on the React Native CLI has introduced major improvements to native module linking called autolinking! Most scenarios will not require the use of react-native link anymore. At the same time, the team overhauled the linking process in general. Be sure to react-native unlink any preexisting dependencies as mentioned in the docs above.

Upgrade Helper

@lucasbento, @pvinis, @kelset, and @watadarkstar have built a great tool called Upgrade Helper to make the upgrade process simpler. It helps React Native users with brownfield apps or complex customizations to see what's changed between versions. Take a look at the updated upgrading docs and try it out today for your upgrade path!

Upgrade Helper cleanly and easily shows the changes needed to migrate to a different version of React Native

A Note to Library Maintainers

Changes for AndroidX will almost certainly require updates to your library, so be sure to include support soon. If you're not able to upgrade yet, consider checking your library against the jetifier to confirm that users are able to patch your library at build time.

Review the autolinking docs to update your configs and readme. Depending on how your library was previously integrated, you may also need to make some additional changes. Check the dependencies guide from the CLI for information on how to define your dependency interface.

Thanks

While these are the highlights that we noted, there are many others to be excited about. To see all the updates, take a look at the changelog. As always, stay tuned for more news. Enjoy 0.60 in the meantime!

Releasing React Native 0.59

Ryan Turner

Ryan Turner

Core Maintainer & React Native Developer

Welcome to the 0.59 release of React Native! This is another big release with 644 commits by 88 contributors. Contributions also come in other forms, so thank you for maintaining issues, fostering communities, and teaching people about React Native. This month brings a number of highly anticipated changes, and we hope you enjoy them.

🎣 Hooks are here

React Hooks are part of this release, which let you reuse stateful logic across components. There is a lot of buzz about hooks, but if you haven't heard, take a look at some of the wonderful resources below:

Be sure to give this a try in your apps. We hope that you find the reuse as exciting as we do.

📱 Updated JSC means performance gains and 64-bit support on Android

React Native uses JSC (JavaScriptCore) to power your application. JSC on Android was a few years old, which meant that a lot of modern JavaScript features weren't supported. Even worse, it performed poorly compared iOS's modern JSC. With this release, that all changes.

Thanks to some awesome work by @DanielZlotin, @dulmandakh, @gengjiawen, @kmagiera, and @kudo JSC has caught up with the past few years. This brings with it 64-bit support, modern JavaScript support, and big performance improvements. Kudos for also making this a maintainable process now so that we can take advantage of future WebKit improvements without so much legwork, and thank you Software Mansion and Expo for making this work possible.

💨 Faster app launches with inline requires

We want to help people have performant React Native apps by default and are working to bring Facebook's optimizations to the community. Applications load resources as needed rather than slowing down launch. This feature is called "inline requires", as it lets Metro identify components to be lazy loaded. Apps with a deep and varied component architecture will see the most improvement.

source of the `metro.config.js` file in the 0.59 template, demonstrating where to enable `inlineRequires`

We need the community to let us know how it works before we turn it on by default. When you upgrade to 0.59, there will be a new metro.config.js file; flip the options to true and give us your feedback! Read more about inline requires in the performance docs to benchmark your app.

🚅 Lean core is underway

React Native is a large and complex project with a complicated repository. This makes the codebase less approachable to contributors, difficult to test, and bloated as a dev dependency. Lean Core is our effort to address these issues by migrating code to separate libraries for better management. The past few releases have seen the first steps of this, but let's get serious.

You may notice that additional components are now officially deprecated. This is great news, as there are now owners for these features actively maintaining them. Heed the warning messages and migrate to the new libraries for these features, because they will be removed in a future release. Below is a table indicating the component, its status, and where you may migrate your use to.

ComponentDeprecated?New home
AsyncStorage0.59@react-native-community/react-native-async-storage
ImageStore0.59expo-file-system or react-native-fs
MaskedViewIOS0.59@react-native-community/react-native-masked-view
NetInfo0.59@react-native-community/react-native-netinfo
Slider0.59@react-native-community/react-native-slider
ViewPagerAndroid0.59@react-native-community/react-native-viewpager

Over the coming months, there will be many more components following this path to a leaner core. We're looking for help with this — head over to the lean core umbrella to pitch in.

👩🏽‍💻 CLI improvements

React Native's command line tools are developer's entry point to the ecosystem, but they had long-standing issues and lacked official support. The CLI tools have been moved to a new repository, and a dedicated group of maintainers have already made some exciting improvements.

Logs are formatted much better now. Commands now run nearly instantly — you'll immediately notice a difference:

0.58's CLI is slow to start0.58's CLI is nearly instantaneous

🚀 Upgrading to 0.59

We heard your feedback regarding the React Native upgrade process and we are taking steps to improve the experience in future releases. To upgrade to 0.59, we recommend using rn-diff-purge to determine what has changed between your current React Native version and 0.59, then applying those changes manually. Once you've upgraded your project to 0.59, you will be able to use the newly improved react-native upgrade command (based on rn-diff-purge!) to upgrade to 0.60 and beyond as newer releases become available.

🔨 Breaking Changes

Android support in 0.59 has been cleaned up following Google's latest recommendations, which may result in potential breakage of existing apps. This issue might present as a runtime crash and a message, "You need to use a Theme.AppCompat theme (or descendant) with this activity". We recommend updating your project's AndroidManifest.xml file, making sure that the android:theme value is an AppCompat theme (such as @style/Theme.AppCompat.Light.NoActionBar).

The react-native-git-upgrade command has been removed in 0.59, in favor of the newly improved react-native upgrade command.

🤗 Thanks

Lots of new contributors helped with enabling generation of native code from flow types and resolving Xcode warnings - these are a great way to learn how React Native works and contributing to the greater good. Thank you! Look out for similar issues in the future.

While these are the highlights that we noted, there are many others to be excited about. To see all of the updates, take a look at the changelog. 0.59 is a huge release – we can't wait for you to try it out.

We have even more improvements coming throughout the rest of the year. Stay tuned!

Ryan and the whole React Native core team

Releasing 0.56

Lorenzo Sciandra

Lorenzo Sciandra

Core Maintainer & React Native Developer at Drivetribe

The long-awaited 0.56 version of React Native is now available 🎉. This blog post highlights some of the changes introduced in this new release. We also want to take the opportunity to explain what has kept us busy since March.

The breaking changes dilemma, or, "when to release?"

The Contributor's Guide explains the integration process that all changes to React Native go through. The project has is composed by many different tools, requiring coordination and constant support to keep everything working properly. Add to this the vibrant open source community that contributes back to the project, and you will get a sense of the mind-bending scale of it all.

With React Native's impressive adoption, breaking changes must be made with great care, and the process is not as smooth as we'd like. A decision was made to skip the April and May releases to allow the core team to integrate and test a new set of breaking changes. Dedicated community communication channels were used along the way to ensure that the June 2018 (0.56.0) release is as hassle-free as possible to adopt by those who patiently waited for the stable release.

Is 0.56.0 perfect? No, as every piece of software out there: but we reached a point where the tradeoff between "waiting for more stability" versus "testing led to successful results so we can push forward" that we feel ready to release it. Moreover, we are aware of a few issues that are not solved in the final 0.56.0 release. Most developers should have no issues upgrading to 0.56.0. For those that are blocked by the aforementioned issues, we hope to see you around in our discussions and we are looking forward to working with you on a solution to these issues.

You might consider 0.56.0 as a fundamental building block towards a more stable framework: it will take probably a week or two of widespread adoption before all the edge cases will be sanded off, but this will lead to an even better July 2018 (0.57.0) release.

We'd like to conclude this section by thanking all the 67 contributors who worked on a total of 818 commits (!) that will help make your apps even better 👏.

And now, without further ado...

The Big Changes

Babel 7

As you may know, the transpiler tool that allows us all to use the latest and greatest features of JavaScript, Babel, is moving to v7 soon. Since this new version brings along some important changes, we felt that now it would be a good time to upgrade, allowing Metro to leverage on its improvements.

If you find yourself in trouble with upgrading, please refer to the documentation section related to it.

Modernizing Android support

On Android, much of the surrounding tooling has changed. We've updated to Gradle 3.5, Android SDK 26, Fresco to 1.9.0, and OkHttp to 3.10.0 and even the NDK API target to API 16. These changes should go without issue and result in faster builds. More importantly, it will help developers comply with the new Play Store requirements coming into effect next month.

Related to this, we'd like to particularly thank Dulmandakh for the many PRs submitted in order to make it possible 👏.

There are some more steps that need to be taken in this direction, and you can follow along with the future planning and discussion of updating the Android support in the dedicated issue (and a side one for the JSC).

New Node, Xcode, React, and Flow – oh my!

Node 8 is now the standard for React Native. It was actually already being tested already, but we've put both feet forward as Node 6 entered maintenance mode. React was also updated to 16.4, which brings a ton of fixes with it.

We're dropping support for iOS 8, making iOS 9 the oldest iOS version that can be targeted. We do not foresee this being a problem, as any device that can run iOS 8, can be upgraded to iOS 9. This change allowed us to remove rarely-used code that implemented workarounds for older devices running iOS 8.

The continuous integration toolchain has been updated to use Xcode 9.4, ensuring that all iOS tests are run on the latest developer tools provided by Apple.

We have upgraded to Flow 0.75 to use the new error format that many devs appreciate. We've also created types for many more components. If you're not yet enforcing static typing in your project, please consider using Flow to identify problems as you code instead of at runtime.

And a lot of other things...

For instance, YellowBox was replaced with a new implementation that makes debugging a lot better.

For the complete release notes, please reference the full changelog here. And remember to keep an eye on the upgrading guide to avoid issues moving to this new version.

A final note: starting this week, the React Native core team will resume holding monthly meetings. We'll make sure to keep everyone up-to-date with what's covered, and ensure to keep your feedback at hand for future meetings.

Happy coding everyone!

Lorenzo, Ryan, and the whole React Native core team

PS: as always, we'd like to remind everyone that React Native is still in 0.x versioning because of the many changes still undergoing - so remember when upgrading that yes, probably, something may still crash or be broken. Be helpful towards each other in the issues and when submitting PRs - and remember to follow the CoC enforced: there's always a human on the other side of the screen.

- + diff --git a/blog/tags/showcase.html b/blog/tags/showcase.html index a671359233d..a5a4a00f95e 100644 --- a/blog/tags/showcase.html +++ b/blog/tags/showcase.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@

All Blog Posts

1 post tagged with "showcase"

View All Tags

Built with React Native - The Build.com app

Garrett McCullough

Garrett McCullough

Senior Mobile Engineer

Build.com, headquartered in Chico, California, is one of the largest online retailers for home improvement items. The team has had a strong web-centric business for 18 years and began thinking about a mobile App in 2015. Building unique Android and iOS apps wasn’t practical due to our small team and limited native experience. Instead, we decided to take a risk on the very new React Native framework. Our initial commit was on August 12, 2015 using React Native v0.8.0! We were live in both App Stores on October 15, 2016. Over the last two years, we’ve continued to upgrade and expand the app. We are currently on React Native version 0.53.0.

You can check out the app at https://www.build.com/app.

Features

Our app is full featured and includes everything that you’d expect from an e-commerce app: product listings, search and sorting, the ability to configure complex products, favorites, etc. We accept standard credit card payment methods as well as PayPal, and Apple Pay for our iOS users.

A few standout features you might not expect include:

  1. 3D models available for around 40 products with 90 finishes
  2. Augmented Reality (AR) to allow the user to see how lights and faucets will look in their home at 98% size accuracy. The Build.com React Native App is featured in the Apple App store for AR Shopping! AR is now available for Android and iOS!
  3. Collaborative project management features that allow people to put together shopping lists for the different phases of their project and collaborate around selection

We’re working on many new and exciting features that will continue to improve our app experience including the next phase of Immersive Shopping with AR.

Our Development Workflow

Build.com allows each dev to choose the tools that best suit them.

  • IDEs include Atom, IntelliJ, VS Code, Sublime, Eclipse, etc.
  • For Unit testing, developers are responsible for creating Jest unit tests for any new components and we’re working to increase the coverage of older parts of the app using jest-coverage-ratchet.
  • We use Jenkins to build out our beta and release candidates. This process works well for us but still requires significant work to create the release notes and other artifacts.
  • Integration Testing include a shared pool of testers that work across desktop, mobile and web. Our automation engineer is building out our suite of automated integration tests using Java and Appium.
  • Other parts of the workflow include a detailed eslint configuration, custom rules that enforce properties needed for testing, and pre-push hooks that block offending changes.

Libraries Used in the App

The Build.com app relies on a number of common open source libraries including: Redux, Moment, Numeral, Enzyme and a bunch of React Native bridge modules. We also use a number of forked open source libraries; forked either because they were abandoned or because we needed custom features. A quick count shows around 115 JavaScript and native dependencies. We would like to explore tools that remove unused libraries.

We're in the process of adding static typing via TypeScript and looking into optional chaining. These features could help us with solving a couple classes of bugs that we still see:

  • Data that is the wrong type
  • Data that is undefined because an object didn’t contain what we expected

Open Source Contributions

Since we rely so heavily on open source, our team is committed to contributing back to the community. Build.com allows the team to open source libraries that we've built and encourages us contribute back to the libraries that we use.

We’ve released and maintained a number of React Native libraries:

  • react-native-polyfill
  • react-native-simple-store
  • react-native-contact-picker

We have also contributed to a long list of libraries including: React and React Native, react-native-schemes-manager, react-native-swipeable, react-native-gallery, react-native-view-transformer, react-native-navigation.

Our Journey

We’ve seen a lot of growth in React Native and the ecosystem in the past couple years. Early on, it seemed that every version of React Native would fix some bugs but introduce several more. For example, Remote JS Debugging was broken on Android for several months. Thankfully, things became much more stable in 2017.

Navigation Libraries

One of our big recurring challenges has been with navigation libraries. For a long time, we were using Expo’s ex-nav library. It worked well for us but it was eventually deprecated. However, we were in heavy feature development at the time so taking time to change out a navigation library wasn’t feasible. That meant we had to fork the library and patch it to support React 16 and the iPhone X. Eventually, we were able to migrate to react-native-navigation and hopefully that will see continued support.

Bridge Modules

Another big challenge has been with bridge modules. When we first started, a lot of critical bridges were missing. One of my teammates wrote react-native-contact-picker because we needed access to the Android contact picker in our app. We’ve also seen a lot of bridges that were broken by changes within React Native. For example, there was a breaking change within React Native v40 and when we upgraded our app, I had to submit PRs to fix 3 or 4 libraries that had not yet been updated.

Looking Forward

As React Native continues to grow, our wishlist to our community include:

  • Stabilize and improve the navigation libraries
  • Maintain support for libraries in the React Native ecosystem
  • Improve the experience for adding native libraries and bridge modules to a project

Companies and individuals in the React Native community have been great about volunteering their time and effort to improve the tools that we all use. If you haven’t gotten involved in open source, I hope you’ll take a look at improving the code or documentation for some of the libraries that you use. There are a lot of articles to help you get started and it may be a lot easier than you think!

- + diff --git a/blog/tags/showcase/index.html b/blog/tags/showcase/index.html index a671359233d..a5a4a00f95e 100644 --- a/blog/tags/showcase/index.html +++ b/blog/tags/showcase/index.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@

All Blog Posts

1 post tagged with "showcase"

View All Tags

Built with React Native - The Build.com app

Garrett McCullough

Garrett McCullough

Senior Mobile Engineer

Build.com, headquartered in Chico, California, is one of the largest online retailers for home improvement items. The team has had a strong web-centric business for 18 years and began thinking about a mobile App in 2015. Building unique Android and iOS apps wasn’t practical due to our small team and limited native experience. Instead, we decided to take a risk on the very new React Native framework. Our initial commit was on August 12, 2015 using React Native v0.8.0! We were live in both App Stores on October 15, 2016. Over the last two years, we’ve continued to upgrade and expand the app. We are currently on React Native version 0.53.0.

You can check out the app at https://www.build.com/app.

Features

Our app is full featured and includes everything that you’d expect from an e-commerce app: product listings, search and sorting, the ability to configure complex products, favorites, etc. We accept standard credit card payment methods as well as PayPal, and Apple Pay for our iOS users.

A few standout features you might not expect include:

  1. 3D models available for around 40 products with 90 finishes
  2. Augmented Reality (AR) to allow the user to see how lights and faucets will look in their home at 98% size accuracy. The Build.com React Native App is featured in the Apple App store for AR Shopping! AR is now available for Android and iOS!
  3. Collaborative project management features that allow people to put together shopping lists for the different phases of their project and collaborate around selection

We’re working on many new and exciting features that will continue to improve our app experience including the next phase of Immersive Shopping with AR.

Our Development Workflow

Build.com allows each dev to choose the tools that best suit them.

  • IDEs include Atom, IntelliJ, VS Code, Sublime, Eclipse, etc.
  • For Unit testing, developers are responsible for creating Jest unit tests for any new components and we’re working to increase the coverage of older parts of the app using jest-coverage-ratchet.
  • We use Jenkins to build out our beta and release candidates. This process works well for us but still requires significant work to create the release notes and other artifacts.
  • Integration Testing include a shared pool of testers that work across desktop, mobile and web. Our automation engineer is building out our suite of automated integration tests using Java and Appium.
  • Other parts of the workflow include a detailed eslint configuration, custom rules that enforce properties needed for testing, and pre-push hooks that block offending changes.

Libraries Used in the App

The Build.com app relies on a number of common open source libraries including: Redux, Moment, Numeral, Enzyme and a bunch of React Native bridge modules. We also use a number of forked open source libraries; forked either because they were abandoned or because we needed custom features. A quick count shows around 115 JavaScript and native dependencies. We would like to explore tools that remove unused libraries.

We're in the process of adding static typing via TypeScript and looking into optional chaining. These features could help us with solving a couple classes of bugs that we still see:

  • Data that is the wrong type
  • Data that is undefined because an object didn’t contain what we expected

Open Source Contributions

Since we rely so heavily on open source, our team is committed to contributing back to the community. Build.com allows the team to open source libraries that we've built and encourages us contribute back to the libraries that we use.

We’ve released and maintained a number of React Native libraries:

  • react-native-polyfill
  • react-native-simple-store
  • react-native-contact-picker

We have also contributed to a long list of libraries including: React and React Native, react-native-schemes-manager, react-native-swipeable, react-native-gallery, react-native-view-transformer, react-native-navigation.

Our Journey

We’ve seen a lot of growth in React Native and the ecosystem in the past couple years. Early on, it seemed that every version of React Native would fix some bugs but introduce several more. For example, Remote JS Debugging was broken on Android for several months. Thankfully, things became much more stable in 2017.

Navigation Libraries

One of our big recurring challenges has been with navigation libraries. For a long time, we were using Expo’s ex-nav library. It worked well for us but it was eventually deprecated. However, we were in heavy feature development at the time so taking time to change out a navigation library wasn’t feasible. That meant we had to fork the library and patch it to support React 16 and the iPhone X. Eventually, we were able to migrate to react-native-navigation and hopefully that will see continued support.

Bridge Modules

Another big challenge has been with bridge modules. When we first started, a lot of critical bridges were missing. One of my teammates wrote react-native-contact-picker because we needed access to the Android contact picker in our app. We’ve also seen a lot of bridges that were broken by changes within React Native. For example, there was a breaking change within React Native v40 and when we upgraded our app, I had to submit PRs to fix 3 or 4 libraries that had not yet been updated.

Looking Forward

As React Native continues to grow, our wishlist to our community include:

  • Stabilize and improve the navigation libraries
  • Maintain support for libraries in the React Native ecosystem
  • Improve the experience for adding native libraries and bridge modules to a project

Companies and individuals in the React Native community have been great about volunteering their time and effort to improve the tools that we all use. If you haven’t gotten involved in open source, I hope you’ll take a look at improving the code or documentation for some of the libraries that you use. There are a lot of articles to help you get started and it may be a lot easier than you think!

- + diff --git a/blog/tags/videos.html b/blog/tags/videos.html index f594624d378..0e4e83c6c48 100644 --- a/blog/tags/videos.html +++ b/blog/tags/videos.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@

All Blog Posts

1 post tagged with "videos"

View All Tags
- + diff --git a/blog/tags/videos/index.html b/blog/tags/videos/index.html index f594624d378..0e4e83c6c48 100644 --- a/blog/tags/videos/index.html +++ b/blog/tags/videos/index.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@

All Blog Posts

1 post tagged with "videos"

View All Tags
- + diff --git a/docs/0.60/_getting-started-linux-android.html b/docs/0.60/_getting-started-linux-android.html index bc9f41f664e..0cfdd5ed1bb 100644 --- a/docs/0.60/_getting-started-linux-android.html +++ b/docs/0.60/_getting-started-linux-android.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: 0.60

_getting-started-linux-android

Installing dependencies

You will need Node, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node

Follow the installation instructions for your Linux distribution to install Node 10 or newer.

Java Development Kit

React Native requires at least the version 8 of the Java SE Development Kit (JDK). You may download and install OpenJDK from AdoptOpenJDK or your system packager. You may also Download and install Oracle JDK 14 if desired.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

Add the following lines to your $HOME/.bash_profile or $HOME/.bashrc (if you are using zsh then ~/.zprofile or ~/.zshrc) config file:

export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

.bash_profile is specific to bash. If you're using another shell, you will need to edit the appropriate shell-specific config file.

Type source $HOME/.bash_profile for bash or source $HOME/.zprofile to load the config into your current shell. Verify that ANDROID_HOME has been set by running echo $ANDROID_HOME and the appropriate directories have been added to your path by running echo $PATH.

Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Watchman

Follow the Watchman installation guide to compile and install Watchman from source.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance and increased compatibility in certain edge cases (translation: you may be able to get by without installing this, but your mileage may vary; installing this now may save you from a headache later).

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

We recommend configuring VM acceleration on your system to improve performance. Once you've followed those instructions, go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (Ctrl + M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.60/_getting-started-linux-android/index.html b/docs/0.60/_getting-started-linux-android/index.html index bc9f41f664e..0cfdd5ed1bb 100644 --- a/docs/0.60/_getting-started-linux-android/index.html +++ b/docs/0.60/_getting-started-linux-android/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: 0.60

_getting-started-linux-android

Installing dependencies

You will need Node, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node

Follow the installation instructions for your Linux distribution to install Node 10 or newer.

Java Development Kit

React Native requires at least the version 8 of the Java SE Development Kit (JDK). You may download and install OpenJDK from AdoptOpenJDK or your system packager. You may also Download and install Oracle JDK 14 if desired.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

Add the following lines to your $HOME/.bash_profile or $HOME/.bashrc (if you are using zsh then ~/.zprofile or ~/.zshrc) config file:

export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

.bash_profile is specific to bash. If you're using another shell, you will need to edit the appropriate shell-specific config file.

Type source $HOME/.bash_profile for bash or source $HOME/.zprofile to load the config into your current shell. Verify that ANDROID_HOME has been set by running echo $ANDROID_HOME and the appropriate directories have been added to your path by running echo $PATH.

Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Watchman

Follow the Watchman installation guide to compile and install Watchman from source.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance and increased compatibility in certain edge cases (translation: you may be able to get by without installing this, but your mileage may vary; installing this now may save you from a headache later).

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

We recommend configuring VM acceleration on your system to improve performance. Once you've followed those instructions, go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (Ctrl + M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.60/_getting-started-macos-android.html b/docs/0.60/_getting-started-macos-android.html index 445c394e7b8..9aa0a6fff7e 100644 --- a/docs/0.60/_getting-started-macos-android.html +++ b/docs/0.60/_getting-started-macos-android.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: 0.60

_getting-started-macos-android

Installing dependencies

You will need Node, Watchman, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node & Watchman

We recommend installing Node and Watchman using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install node
brew install watchman

If you have already installed Node on your system, make sure it is Node 10 or newer.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

Java Development Kit

We recommend installing JDK using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install --cask adoptopenjdk/openjdk/adoptopenjdk8

If you have already installed JDK on your system, make sure it is JDK 8 or newer.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device
  • If you are not already using Hyper-V: Performance (Intel ® HAXM) (See here for AMD or Hyper-V)

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

Android Studio Welcome

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

Add the following lines to your $HOME/.bash_profile or $HOME/.bashrc (if you are using zsh then ~/.zprofile or ~/.zshrc) config file:

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

.bash_profile is specific to bash. If you're using another shell, you will need to edit the appropriate shell-specific config file.

Type source $HOME/.bash_profile for bash or source $HOME/.zprofile to load the config into your current shell. Verify that ANDROID_HOME has been set by running echo $ANDROID_HOME and the appropriate directories have been added to your path by running echo $PATH.

Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

If you don't have HAXM installed, follow these instructions to set it up, then go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

AwesomeProject on Android

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (⌘M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.60/_getting-started-macos-android/index.html b/docs/0.60/_getting-started-macos-android/index.html index 445c394e7b8..9aa0a6fff7e 100644 --- a/docs/0.60/_getting-started-macos-android/index.html +++ b/docs/0.60/_getting-started-macos-android/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: 0.60

_getting-started-macos-android

Installing dependencies

You will need Node, Watchman, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node & Watchman

We recommend installing Node and Watchman using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install node
brew install watchman

If you have already installed Node on your system, make sure it is Node 10 or newer.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

Java Development Kit

We recommend installing JDK using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install --cask adoptopenjdk/openjdk/adoptopenjdk8

If you have already installed JDK on your system, make sure it is JDK 8 or newer.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device
  • If you are not already using Hyper-V: Performance (Intel ® HAXM) (See here for AMD or Hyper-V)

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

Android Studio Welcome

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

Add the following lines to your $HOME/.bash_profile or $HOME/.bashrc (if you are using zsh then ~/.zprofile or ~/.zshrc) config file:

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

.bash_profile is specific to bash. If you're using another shell, you will need to edit the appropriate shell-specific config file.

Type source $HOME/.bash_profile for bash or source $HOME/.zprofile to load the config into your current shell. Verify that ANDROID_HOME has been set by running echo $ANDROID_HOME and the appropriate directories have been added to your path by running echo $PATH.

Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

If you don't have HAXM installed, follow these instructions to set it up, then go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

AwesomeProject on Android

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (⌘M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.60/_getting-started-macos-ios.html b/docs/0.60/_getting-started-macos-ios.html index 392ece5d899..5b813676376 100644 --- a/docs/0.60/_getting-started-macos-ios.html +++ b/docs/0.60/_getting-started-macos-ios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

_getting-started-macos-ios

Installing dependencies

You will need Node, Watchman, the React Native command line interface, and Xcode.

While you can use any editor of your choice to develop your app, you will need to install Xcode in order to set up the necessary tooling to build your React Native app for iOS.

Node & Watchman

We recommend installing Node and Watchman using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install node
brew install watchman

If you have already installed Node on your system, make sure it is Node 10 or newer.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

Xcode & CocoaPods

The easiest way to install Xcode is via the Mac App Store. Installing Xcode will also install the iOS Simulator and all the necessary tools to build your iOS app.

If you have already installed Xcode on your system, make sure it is version 9.4 or newer.

Command Line Tools

You will also need to install the Xcode Command Line Tools. Open Xcode, then choose "Preferences..." from the Xcode menu. Go to the Locations panel and install the tools by selecting the most recent version in the Command Line Tools dropdown.

Xcode Command Line Tools

Installing an iOS Simulator in Xcode

To install a simulator, open Xcode > Preferences... and select the Components tab. Select a simulator with the corresponding version of iOS you wish to use.

CocoaPods

CocoaPods is built with Ruby and it will be installable with the default Ruby available on macOS. You can use a Ruby Version manager, however we recommend that you use the standard Ruby available on macOS unless you know what you're doing.

Using the default Ruby install will require you to use sudo when installing gems. (This is only an issue for the duration of the gem installation, though.)

sudo gem install cocoapods

For more information, please visit CocoaPods Getting Started guide.

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

You can use React Native's built-in command line interface to generate a new project. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding iOS support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Note If the above command is failing, you may have old version of react-native or react-native-cli installed globally on your pc. Try uninstalling the cli and run the cli using npx.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-ios

You should see your new app running in the iOS Simulator shortly.

AwesomeProject on iOS

npx react-native run-ios is one way to run your app. You can also run it directly from within Xcode.

If you can't get this to work, see the Troubleshooting page.

Running on a device

The above command will automatically run your app on the iOS Simulator by default. If you want to run the app on an actual physical iOS device, please follow the instructions here.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Hit ⌘R in your iOS Simulator to reload the app and see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.60/_getting-started-macos-ios/index.html b/docs/0.60/_getting-started-macos-ios/index.html index 392ece5d899..5b813676376 100644 --- a/docs/0.60/_getting-started-macos-ios/index.html +++ b/docs/0.60/_getting-started-macos-ios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

_getting-started-macos-ios

Installing dependencies

You will need Node, Watchman, the React Native command line interface, and Xcode.

While you can use any editor of your choice to develop your app, you will need to install Xcode in order to set up the necessary tooling to build your React Native app for iOS.

Node & Watchman

We recommend installing Node and Watchman using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install node
brew install watchman

If you have already installed Node on your system, make sure it is Node 10 or newer.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

Xcode & CocoaPods

The easiest way to install Xcode is via the Mac App Store. Installing Xcode will also install the iOS Simulator and all the necessary tools to build your iOS app.

If you have already installed Xcode on your system, make sure it is version 9.4 or newer.

Command Line Tools

You will also need to install the Xcode Command Line Tools. Open Xcode, then choose "Preferences..." from the Xcode menu. Go to the Locations panel and install the tools by selecting the most recent version in the Command Line Tools dropdown.

Xcode Command Line Tools

Installing an iOS Simulator in Xcode

To install a simulator, open Xcode > Preferences... and select the Components tab. Select a simulator with the corresponding version of iOS you wish to use.

CocoaPods

CocoaPods is built with Ruby and it will be installable with the default Ruby available on macOS. You can use a Ruby Version manager, however we recommend that you use the standard Ruby available on macOS unless you know what you're doing.

Using the default Ruby install will require you to use sudo when installing gems. (This is only an issue for the duration of the gem installation, though.)

sudo gem install cocoapods

For more information, please visit CocoaPods Getting Started guide.

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

You can use React Native's built-in command line interface to generate a new project. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding iOS support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Note If the above command is failing, you may have old version of react-native or react-native-cli installed globally on your pc. Try uninstalling the cli and run the cli using npx.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-ios

You should see your new app running in the iOS Simulator shortly.

AwesomeProject on iOS

npx react-native run-ios is one way to run your app. You can also run it directly from within Xcode.

If you can't get this to work, see the Troubleshooting page.

Running on a device

The above command will automatically run your app on the iOS Simulator by default. If you want to run the app on an actual physical iOS device, please follow the instructions here.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Hit ⌘R in your iOS Simulator to reload the app and see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.60/_getting-started-windows-android.html b/docs/0.60/_getting-started-windows-android.html index 2b0961f5869..ccfeaad3002 100644 --- a/docs/0.60/_getting-started-windows-android.html +++ b/docs/0.60/_getting-started-windows-android.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: 0.60

_getting-started-windows-android

Installing dependencies

You will need Node, the React Native command line interface, Python2, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node, Python2, JDK

We recommend installing Node and Python2 via Chocolatey, a popular package manager for Windows.

React Native also requires Java SE Development Kit (JDK), as well as Python2. Both can be installed using Chocolatey.

Open an Administrator Command Prompt (right click Command Prompt and select "Run as Administrator"), then run the following command:

choco install -y nodejs.install python2 openjdk8

If you have already installed Node on your system, make sure it is Node 10 or newer. If you already have a JDK on your system, make sure it is version 8 or newer.

You can find additional installation options on Node's Downloads page.

If you're using the latest version of Java Development Kit, you'll need to change the Gradle version of your project so it can recognize the JDK. You can do that by going to {project root folder}\android\gradle\wrapper\gradle-wrapper.properties and changing the distributionUrl value to upgrade the Gradle version. You can check out here the lastest releases of Gradle.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device
  • If you are not already using Hyper-V: Performance (Intel ® HAXM) (See here for AMD or Hyper-V)

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

Android Studio Welcome

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

  1. Open the Windows Control Panel.
  2. Click on User Accounts, then click User Accounts again
  3. Click on Change my environment variables
  4. Click on New... to create a new ANDROID_HOME user variable that points to the path to your Android SDK:

ANDROID_HOME Environment Variable

The SDK is installed, by default, at the following location:

%LOCALAPPDATA%\Android\Sdk

You can find the actual location of the SDK in the Android Studio "Settings" dialog, under Appearance & Behavior → System Settings → Android SDK.

Open a new Command Prompt window to ensure the new environment variable is loaded before proceeding to the next step.

  1. Open powershell
  2. Copy and paste Get-ChildItem -Path Env:\ into powershell
  3. Verify ANDROID_HOME has been added

4. Add platform-tools to Path

  1. Open the Windows Control Panel.
  2. Click on User Accounts, then click User Accounts again
  3. Click on Change my environment variables
  4. Select the Path variable.
  5. Click Edit.
  6. Click New and add the path to platform-tools to the list.

The default location for this folder is:

%LOCALAPPDATA%\Android\Sdk\platform-tools

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

If you don't have HAXM installed, click on "Install HAXM" or follow these instructions to set it up, then go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

AwesomeProject on Android

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (Ctrl + M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.60/_getting-started-windows-android/index.html b/docs/0.60/_getting-started-windows-android/index.html index 2b0961f5869..ccfeaad3002 100644 --- a/docs/0.60/_getting-started-windows-android/index.html +++ b/docs/0.60/_getting-started-windows-android/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: 0.60

_getting-started-windows-android

Installing dependencies

You will need Node, the React Native command line interface, Python2, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node, Python2, JDK

We recommend installing Node and Python2 via Chocolatey, a popular package manager for Windows.

React Native also requires Java SE Development Kit (JDK), as well as Python2. Both can be installed using Chocolatey.

Open an Administrator Command Prompt (right click Command Prompt and select "Run as Administrator"), then run the following command:

choco install -y nodejs.install python2 openjdk8

If you have already installed Node on your system, make sure it is Node 10 or newer. If you already have a JDK on your system, make sure it is version 8 or newer.

You can find additional installation options on Node's Downloads page.

If you're using the latest version of Java Development Kit, you'll need to change the Gradle version of your project so it can recognize the JDK. You can do that by going to {project root folder}\android\gradle\wrapper\gradle-wrapper.properties and changing the distributionUrl value to upgrade the Gradle version. You can check out here the lastest releases of Gradle.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device
  • If you are not already using Hyper-V: Performance (Intel ® HAXM) (See here for AMD or Hyper-V)

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

Android Studio Welcome

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

  1. Open the Windows Control Panel.
  2. Click on User Accounts, then click User Accounts again
  3. Click on Change my environment variables
  4. Click on New... to create a new ANDROID_HOME user variable that points to the path to your Android SDK:

ANDROID_HOME Environment Variable

The SDK is installed, by default, at the following location:

%LOCALAPPDATA%\Android\Sdk

You can find the actual location of the SDK in the Android Studio "Settings" dialog, under Appearance & Behavior → System Settings → Android SDK.

Open a new Command Prompt window to ensure the new environment variable is loaded before proceeding to the next step.

  1. Open powershell
  2. Copy and paste Get-ChildItem -Path Env:\ into powershell
  3. Verify ANDROID_HOME has been added

4. Add platform-tools to Path

  1. Open the Windows Control Panel.
  2. Click on User Accounts, then click User Accounts again
  3. Click on Change my environment variables
  4. Select the Path variable.
  5. Click Edit.
  6. Click New and add the path to platform-tools to the list.

The default location for this folder is:

%LOCALAPPDATA%\Android\Sdk\platform-tools

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

If you don't have HAXM installed, click on "Install HAXM" or follow these instructions to set it up, then go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

AwesomeProject on Android

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (Ctrl + M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.60/_integration-with-exisiting-apps-java.html b/docs/0.60/_integration-with-exisiting-apps-java.html index 84f51095b13..e60457272fe 100644 --- a/docs/0.60/_integration-with-exisiting-apps-java.html +++ b/docs/0.60/_integration-with-exisiting-apps-java.html @@ -19,7 +19,7 @@ - + @@ -48,7 +48,7 @@
if (mReactInstanceManager != null) {
mReactInstanceManager.onHostDestroy(this);
}
if (mReactRootView != null) {
mReactRootView.unmountReactApplication();
}
}

We also need to pass back button events to React Native:

@Override
public void onBackPressed() {
if (mReactInstanceManager != null) {
mReactInstanceManager.onBackPressed();
} else {
super.onBackPressed();
}
}

This allows JavaScript to control what happens when the user presses the hardware back button (e.g. to implement navigation). When JavaScript doesn't handle the back button press, your invokeDefaultOnBackPressed method will be called. By default this finishes your Activity.

Finally, we need to hook up the dev menu. By default, this is activated by (rage) shaking the device, but this is not very useful in emulators. So we make it show when you press the hardware menu button (use Ctrl + M if you're using Android Studio emulator):

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
if (keyCode == KeyEvent.KEYCODE_MENU && mReactInstanceManager != null) {
mReactInstanceManager.showDevOptionsDialog();
return true;
}
return super.onKeyUp(keyCode, event);
}

Now your activity is ready to run some JavaScript code.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ yarn start
2. Run the app

Now build and run your Android app as normal.

Once you reach your React-powered activity inside the app, it should load the JavaScript code from the development server and display:

Screenshot

Creating a release build in Android Studio

You can use Android Studio to create your release builds too! It’s as quick as creating release builds of your previously-existing native Android app. There’s one additional step, which you’ll have to do before every release build. You need to execute the following to create a React Native bundle, which will be included with your native Android app:

$ npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/com/your-company-name/app-package-name/src/main/assets/index.android.bundle --assets-dest android/com/your-company-name/app-package-name/src/main/res/

Don’t forget to replace the paths with correct ones and create the assets folder if it doesn’t exist.

Now, create a release build of your native app from within Android Studio as usual and you should be good to go!

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.60/_integration-with-exisiting-apps-java/index.html b/docs/0.60/_integration-with-exisiting-apps-java/index.html index 84f51095b13..e60457272fe 100644 --- a/docs/0.60/_integration-with-exisiting-apps-java/index.html +++ b/docs/0.60/_integration-with-exisiting-apps-java/index.html @@ -19,7 +19,7 @@ - + @@ -48,7 +48,7 @@
if (mReactInstanceManager != null) {
mReactInstanceManager.onHostDestroy(this);
}
if (mReactRootView != null) {
mReactRootView.unmountReactApplication();
}
}

We also need to pass back button events to React Native:

@Override
public void onBackPressed() {
if (mReactInstanceManager != null) {
mReactInstanceManager.onBackPressed();
} else {
super.onBackPressed();
}
}

This allows JavaScript to control what happens when the user presses the hardware back button (e.g. to implement navigation). When JavaScript doesn't handle the back button press, your invokeDefaultOnBackPressed method will be called. By default this finishes your Activity.

Finally, we need to hook up the dev menu. By default, this is activated by (rage) shaking the device, but this is not very useful in emulators. So we make it show when you press the hardware menu button (use Ctrl + M if you're using Android Studio emulator):

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
if (keyCode == KeyEvent.KEYCODE_MENU && mReactInstanceManager != null) {
mReactInstanceManager.showDevOptionsDialog();
return true;
}
return super.onKeyUp(keyCode, event);
}

Now your activity is ready to run some JavaScript code.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ yarn start
2. Run the app

Now build and run your Android app as normal.

Once you reach your React-powered activity inside the app, it should load the JavaScript code from the development server and display:

Screenshot

Creating a release build in Android Studio

You can use Android Studio to create your release builds too! It’s as quick as creating release builds of your previously-existing native Android app. There’s one additional step, which you’ll have to do before every release build. You need to execute the following to create a React Native bundle, which will be included with your native Android app:

$ npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/com/your-company-name/app-package-name/src/main/assets/index.android.bundle --assets-dest android/com/your-company-name/app-package-name/src/main/res/

Don’t forget to replace the paths with correct ones and create the assets folder if it doesn’t exist.

Now, create a release build of your native app from within Android Studio as usual and you should be good to go!

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.60/_integration-with-exisiting-apps-objc.html b/docs/0.60/_integration-with-exisiting-apps-objc.html index f51f9abab05..1c8bde84eba 100644 --- a/docs/0.60/_integration-with-exisiting-apps-objc.html +++ b/docs/0.60/_integration-with-exisiting-apps-objc.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
RCTRootView *rootView =
[[RCTRootView alloc] initWithBundleURL: jsCodeLocation
moduleName: @"RNHighScores"
initialProperties:
@{
@"scores" : @[
@{
@"name" : @"Alex",
@"value": @"42"
},
@{
@"name" : @"Joel",
@"value": @"10"
}
]
}
launchOptions: nil];
UIViewController *vc = [[UIViewController alloc] init];
vc.view = rootView;
[self presentViewController:vc animated:YES completion:nil];
}

Note that RCTRootView initWithURL starts up a new JSC VM. To save resources and simplify the communication between RN views in different parts of your native app, you can have multiple views powered by React Native that are associated with a single JS runtime. To do that, instead of using [RCTRootView alloc] initWithURL, use RCTBridge initWithBundleURL to create a bridge and then use RCTRootView initWithBridge.

When moving your app to production, the NSURL can point to a pre-bundled file on disk via something like [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];. You can use the react-native-xcode.sh script in node_modules/react-native/scripts/ to generate that pre-bundled file.

3. Wire Up

Wire up the new link in the main menu to the newly added event handler method.

Event Path

One of the easier ways to do this is to open the view in the storyboard and right click on the new link. Select something such as the Touch Up Inside event, drag that to the storyboard and then select the created method from the list provided.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Add App Transport Security exception

Apple has blocked implicit cleartext HTTP resource loading. So we need to add the following our project's Info.plist (or equivalent) file.

<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>localhost</key>
<dict>
<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
</dict>

App Transport Security is good for your users. Make sure to re-enable it prior to releasing your app for production.

2. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ npm start
3. Run the app

If you are using Xcode or your favorite editor, build and run your native iOS application as normal. Alternatively, you can run the app from the command line using:

# From the root of your project
$ npx react-native run-ios

In our sample application, you should see the link to the "High Scores" and then when you click on that you will see the rendering of your React Native component.

Here is the native application home screen:

Home Screen

Here is the React Native high score screen:

High Scores

If you are getting module resolution issues when running your application please see this GitHub issue for information and possible resolution. This comment seemed to be the latest possible resolution.

See the Code

You can examine the code that added the React Native screen to our sample app on GitHub.

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.60/_integration-with-exisiting-apps-objc/index.html b/docs/0.60/_integration-with-exisiting-apps-objc/index.html index f51f9abab05..1c8bde84eba 100644 --- a/docs/0.60/_integration-with-exisiting-apps-objc/index.html +++ b/docs/0.60/_integration-with-exisiting-apps-objc/index.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
RCTRootView *rootView =
[[RCTRootView alloc] initWithBundleURL: jsCodeLocation
moduleName: @"RNHighScores"
initialProperties:
@{
@"scores" : @[
@{
@"name" : @"Alex",
@"value": @"42"
},
@{
@"name" : @"Joel",
@"value": @"10"
}
]
}
launchOptions: nil];
UIViewController *vc = [[UIViewController alloc] init];
vc.view = rootView;
[self presentViewController:vc animated:YES completion:nil];
}

Note that RCTRootView initWithURL starts up a new JSC VM. To save resources and simplify the communication between RN views in different parts of your native app, you can have multiple views powered by React Native that are associated with a single JS runtime. To do that, instead of using [RCTRootView alloc] initWithURL, use RCTBridge initWithBundleURL to create a bridge and then use RCTRootView initWithBridge.

When moving your app to production, the NSURL can point to a pre-bundled file on disk via something like [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];. You can use the react-native-xcode.sh script in node_modules/react-native/scripts/ to generate that pre-bundled file.

3. Wire Up

Wire up the new link in the main menu to the newly added event handler method.

Event Path

One of the easier ways to do this is to open the view in the storyboard and right click on the new link. Select something such as the Touch Up Inside event, drag that to the storyboard and then select the created method from the list provided.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Add App Transport Security exception

Apple has blocked implicit cleartext HTTP resource loading. So we need to add the following our project's Info.plist (or equivalent) file.

<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>localhost</key>
<dict>
<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
</dict>

App Transport Security is good for your users. Make sure to re-enable it prior to releasing your app for production.

2. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ npm start
3. Run the app

If you are using Xcode or your favorite editor, build and run your native iOS application as normal. Alternatively, you can run the app from the command line using:

# From the root of your project
$ npx react-native run-ios

In our sample application, you should see the link to the "High Scores" and then when you click on that you will see the rendering of your React Native component.

Here is the native application home screen:

Home Screen

Here is the React Native high score screen:

High Scores

If you are getting module resolution issues when running your application please see this GitHub issue for information and possible resolution. This comment seemed to be the latest possible resolution.

See the Code

You can examine the code that added the React Native screen to our sample app on GitHub.

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.60/_integration-with-exisiting-apps-swift.html b/docs/0.60/_integration-with-exisiting-apps-swift.html index 76421bf351b..078416d18c9 100644 --- a/docs/0.60/_integration-with-exisiting-apps-swift.html +++ b/docs/0.60/_integration-with-exisiting-apps-swift.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
let rootView = RCTRootView(
bundleURL: jsCodeLocation,
moduleName: "RNHighScores",
initialProperties: mockData as [NSObject : AnyObject],
launchOptions: nil
)
let vc = UIViewController()
vc.view = rootView
self.present(vc, animated: true, completion: nil)
}

Note that RCTRootView bundleURL starts up a new JSC VM. To save resources and simplify the communication between RN views in different parts of your native app, you can have multiple views powered by React Native that are associated with a single JS runtime. To do that, instead of using RCTRootView bundleURL, use RCTBridge initWithBundleURL to create a bridge and then use RCTRootView initWithBridge.

When moving your app to production, the NSURL can point to a pre-bundled file on disk via something like let mainBundle = NSBundle(URLForResource: "main" withExtension:"jsbundle"). You can use the react-native-xcode.sh script in node_modules/react-native/scripts/ to generate that pre-bundled file.

3. Wire Up

Wire up the new link in the main menu to the newly added event handler method.

Event Path

One of the easier ways to do this is to open the view in the storyboard and right click on the new link. Select something such as the Touch Up Inside event, drag that to the storyboard and then select the created method from the list provided.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Add App Transport Security exception

Apple has blocked implicit cleartext HTTP resource loading. So we need to add the following our project's Info.plist (or equivalent) file.

<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>localhost</key>
<dict>
<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
</dict>

App Transport Security is good for your users. Make sure to re-enable it prior to releasing your app for production.

2. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ npm start
3. Run the app

If you are using Xcode or your favorite editor, build and run your native iOS application as normal. Alternatively, you can run the app from the command line using:

# From the root of your project
$ npx react-native run-ios

In our sample application, you should see the link to the "High Scores" and then when you click on that you will see the rendering of your React Native component.

Here is the native application home screen:

Home Screen

Here is the React Native high score screen:

High Scores

If you are getting module resolution issues when running your application please see this GitHub issue for information and possible resolution. This comment seemed to be the latest possible resolution.

See the Code

You can examine the code that added the React Native screen to our sample app on GitHub.

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.60/_integration-with-exisiting-apps-swift/index.html b/docs/0.60/_integration-with-exisiting-apps-swift/index.html index 76421bf351b..078416d18c9 100644 --- a/docs/0.60/_integration-with-exisiting-apps-swift/index.html +++ b/docs/0.60/_integration-with-exisiting-apps-swift/index.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
let rootView = RCTRootView(
bundleURL: jsCodeLocation,
moduleName: "RNHighScores",
initialProperties: mockData as [NSObject : AnyObject],
launchOptions: nil
)
let vc = UIViewController()
vc.view = rootView
self.present(vc, animated: true, completion: nil)
}

Note that RCTRootView bundleURL starts up a new JSC VM. To save resources and simplify the communication between RN views in different parts of your native app, you can have multiple views powered by React Native that are associated with a single JS runtime. To do that, instead of using RCTRootView bundleURL, use RCTBridge initWithBundleURL to create a bridge and then use RCTRootView initWithBridge.

When moving your app to production, the NSURL can point to a pre-bundled file on disk via something like let mainBundle = NSBundle(URLForResource: "main" withExtension:"jsbundle"). You can use the react-native-xcode.sh script in node_modules/react-native/scripts/ to generate that pre-bundled file.

3. Wire Up

Wire up the new link in the main menu to the newly added event handler method.

Event Path

One of the easier ways to do this is to open the view in the storyboard and right click on the new link. Select something such as the Touch Up Inside event, drag that to the storyboard and then select the created method from the list provided.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Add App Transport Security exception

Apple has blocked implicit cleartext HTTP resource loading. So we need to add the following our project's Info.plist (or equivalent) file.

<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>localhost</key>
<dict>
<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
</dict>

App Transport Security is good for your users. Make sure to re-enable it prior to releasing your app for production.

2. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ npm start
3. Run the app

If you are using Xcode or your favorite editor, build and run your native iOS application as normal. Alternatively, you can run the app from the command line using:

# From the root of your project
$ npx react-native run-ios

In our sample application, you should see the link to the "High Scores" and then when you click on that you will see the rendering of your React Native component.

Here is the native application home screen:

Home Screen

Here is the React Native high score screen:

High Scores

If you are getting module resolution issues when running your application please see this GitHub issue for information and possible resolution. This comment seemed to be the latest possible resolution.

See the Code

You can examine the code that added the React Native screen to our sample app on GitHub.

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.60/accessibility.html b/docs/0.60/accessibility.html index afde0279091..e90503e283a 100644 --- a/docs/0.60/accessibility.html +++ b/docs/0.60/accessibility.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
# enable
adb shell settings put secure enabled_accessibility_services com.google.android.marvin.talkback/com.google.android.marvin.talkback.TalkBackService

Additional Resources

Edit this page
Last updated on
- + diff --git a/docs/0.60/accessibility/index.html b/docs/0.60/accessibility/index.html index afde0279091..e90503e283a 100644 --- a/docs/0.60/accessibility/index.html +++ b/docs/0.60/accessibility/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
# enable
adb shell settings put secure enabled_accessibility_services com.google.android.marvin.talkback/com.google.android.marvin.talkback.TalkBackService

Additional Resources

Edit this page
Last updated on
- + diff --git a/docs/0.60/accessibilityinfo.html b/docs/0.60/accessibilityinfo.html index d3bc1c00071..4de96fb2748 100644 --- a/docs/0.60/accessibilityinfo.html +++ b/docs/0.60/accessibilityinfo.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@
render() {
return (
<View>
<Text>
The reduce motion is{' '}
{this.state.reduceMotionEnabled
? 'enabled'
: 'disabled'}
.
</Text>
<Text>
The screen reader is{' '}
{this.state.screenReaderEnabled
? 'enabled'
: 'disabled'}
.
</Text>
</View>
);
}
}

Reference

Methods

isBoldTextEnabled()

static isBoldTextEnabled()

iOS-Only. Query whether a bold text is currently enabled. Returns a promise which resolves to a boolean. The result is true when bold text is enabled and false otherwise.

isGrayscaleEnabled()

static isGrayscaleEnabled()

iOS-Only. Query whether grayscale is currently enabled. Returns a promise which resolves to a boolean. The result is true when grayscale is enabled and false otherwise.

isInvertColorsEnabled()

static isInvertColorsEnabled()

iOS-Only. Query whether invert colors is currently enabled. Returns a promise which resolves to a boolean. The result is true when invert colors is enabled and false otherwise.

isReduceMotionEnabled()

static isReduceMotionEnabled()

Query whether reduce motion is currently enabled. Returns a promise which resolves to a boolean. The result is true when reduce motion is enabled and false otherwise.

isReduceTransparencyEnabled()

static isReduceTransparencyEnabled()

iOS-Only. Query whether reduce transparency is currently enabled. Returns a promise which resolves to a boolean. The result is true when a reduce transparency is enabled and false otherwise.

isScreenReaderEnabled()

static isScreenReaderEnabled()

Query whether a screen reader is currently enabled. Returns a promise which resolves to a boolean. The result is true when a screen reader is enabled and false otherwise.

addEventListener()

static addEventListener(eventName, handler)

Add an event handler. Supported events:

setAccessibilityFocus()

static setAccessibilityFocus(reactTag)

Set accessibility focus to a React component. On Android, this is equivalent to UIManager.sendAccessibilityEvent(reactTag, UIManager.AccessibilityEventTypes.typeViewFocused);.

announceForAccessibility()

static announceForAccessibility(announcement)

Post a string to be announced by the screen reader.

removeEventListener()

static removeEventListener(eventName, handler)

Remove an event handler.

Edit this page
Last updated on
- + diff --git a/docs/0.60/accessibilityinfo/index.html b/docs/0.60/accessibilityinfo/index.html index d3bc1c00071..4de96fb2748 100644 --- a/docs/0.60/accessibilityinfo/index.html +++ b/docs/0.60/accessibilityinfo/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@
render() {
return (
<View>
<Text>
The reduce motion is{' '}
{this.state.reduceMotionEnabled
? 'enabled'
: 'disabled'}
.
</Text>
<Text>
The screen reader is{' '}
{this.state.screenReaderEnabled
? 'enabled'
: 'disabled'}
.
</Text>
</View>
);
}
}

Reference

Methods

isBoldTextEnabled()

static isBoldTextEnabled()

iOS-Only. Query whether a bold text is currently enabled. Returns a promise which resolves to a boolean. The result is true when bold text is enabled and false otherwise.

isGrayscaleEnabled()

static isGrayscaleEnabled()

iOS-Only. Query whether grayscale is currently enabled. Returns a promise which resolves to a boolean. The result is true when grayscale is enabled and false otherwise.

isInvertColorsEnabled()

static isInvertColorsEnabled()

iOS-Only. Query whether invert colors is currently enabled. Returns a promise which resolves to a boolean. The result is true when invert colors is enabled and false otherwise.

isReduceMotionEnabled()

static isReduceMotionEnabled()

Query whether reduce motion is currently enabled. Returns a promise which resolves to a boolean. The result is true when reduce motion is enabled and false otherwise.

isReduceTransparencyEnabled()

static isReduceTransparencyEnabled()

iOS-Only. Query whether reduce transparency is currently enabled. Returns a promise which resolves to a boolean. The result is true when a reduce transparency is enabled and false otherwise.

isScreenReaderEnabled()

static isScreenReaderEnabled()

Query whether a screen reader is currently enabled. Returns a promise which resolves to a boolean. The result is true when a screen reader is enabled and false otherwise.

addEventListener()

static addEventListener(eventName, handler)

Add an event handler. Supported events:

setAccessibilityFocus()

static setAccessibilityFocus(reactTag)

Set accessibility focus to a React component. On Android, this is equivalent to UIManager.sendAccessibilityEvent(reactTag, UIManager.AccessibilityEventTypes.typeViewFocused);.

announceForAccessibility()

static announceForAccessibility(announcement)

Post a string to be announced by the screen reader.

removeEventListener()

static removeEventListener(eventName, handler)

Remove an event handler.

Edit this page
Last updated on
- + diff --git a/docs/0.60/actionsheetios.html b/docs/0.60/actionsheetios.html index 01483aa693b..fc1a48afd82 100644 --- a/docs/0.60/actionsheetios.html +++ b/docs/0.60/actionsheetios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

ActionSheetIOS

Reference

Methods

showActionSheetWithOptions()

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 in options
  • destructiveButtonIndex (int) - index of destructive button in options
  • title (string) - a title to show above the action sheet
  • message (string) - a message to show below the title
  • anchor (number) - the node to which the action sheet should be anchored (used for iPad)
  • tintColor (string) - the color used for non-destructive button titles

The 'callback' function takes one parameter, the zero-based index of the selected item.

Minimal example:

ActionSheetIOS.showActionSheetWithOptions(
{
options: ['Cancel', 'Remove'],
destructiveButtonIndex: 1,
cancelButtonIndex: 0
},
(buttonIndex) => {
if (buttonIndex === 1) {
/* destructive action */
}
}
);

showShareActionSheetWithOptions()

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 share
  • message (string) - a message to share
  • subject (string) - a subject for the message
  • excludedActivityTypes (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.

The 'failureCallback' function takes one parameter, an error object. The only property defined on this object is an optional stack property of type string.

The 'successCallback' function takes two parameters:

  • a boolean value signifying success or failure
  • a string that, in the case of success, indicates the method of sharing
Edit this page
Last updated on
- + diff --git a/docs/0.60/actionsheetios/index.html b/docs/0.60/actionsheetios/index.html index 01483aa693b..fc1a48afd82 100644 --- a/docs/0.60/actionsheetios/index.html +++ b/docs/0.60/actionsheetios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

ActionSheetIOS

Reference

Methods

showActionSheetWithOptions()

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 in options
  • destructiveButtonIndex (int) - index of destructive button in options
  • title (string) - a title to show above the action sheet
  • message (string) - a message to show below the title
  • anchor (number) - the node to which the action sheet should be anchored (used for iPad)
  • tintColor (string) - the color used for non-destructive button titles

The 'callback' function takes one parameter, the zero-based index of the selected item.

Minimal example:

ActionSheetIOS.showActionSheetWithOptions(
{
options: ['Cancel', 'Remove'],
destructiveButtonIndex: 1,
cancelButtonIndex: 0
},
(buttonIndex) => {
if (buttonIndex === 1) {
/* destructive action */
}
}
);

showShareActionSheetWithOptions()

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 share
  • message (string) - a message to share
  • subject (string) - a subject for the message
  • excludedActivityTypes (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.

The 'failureCallback' function takes one parameter, an error object. The only property defined on this object is an optional stack property of type string.

The 'successCallback' function takes two parameters:

  • a boolean value signifying success or failure
  • a string that, in the case of success, indicates the method of sharing
Edit this page
Last updated on
- + diff --git a/docs/0.60/activityindicator.html b/docs/0.60/activityindicator.html index dcf081a43f7..c26453a3c33 100644 --- a/docs/0.60/activityindicator.html +++ b/docs/0.60/activityindicator.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

ActivityIndicator

Displays a circular loading indicator.

Example

Reference

Props

Inherits View Props.

animating

Whether to show the indicator (true, the default) or hide it (false).

TypeRequired
boolNo

color

The foreground color of the spinner (default is gray on iOS and dark cyan on Android).

TypeRequired
colorNo

hidesWhenStopped

Whether the indicator should hide when not animating (true by default).

TypeRequiredPlatform
boolNoiOS

size

Size of the indicator (default is 'small'). Passing a number to the size prop is only supported on Android.

TypeRequired
enum('small', 'large'), numberNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/activityindicator/index.html b/docs/0.60/activityindicator/index.html index dcf081a43f7..c26453a3c33 100644 --- a/docs/0.60/activityindicator/index.html +++ b/docs/0.60/activityindicator/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

ActivityIndicator

Displays a circular loading indicator.

Example

Reference

Props

Inherits View Props.

animating

Whether to show the indicator (true, the default) or hide it (false).

TypeRequired
boolNo

color

The foreground color of the spinner (default is gray on iOS and dark cyan on Android).

TypeRequired
colorNo

hidesWhenStopped

Whether the indicator should hide when not animating (true by default).

TypeRequiredPlatform
boolNoiOS

size

Size of the indicator (default is 'small'). Passing a number to the size prop is only supported on Android.

TypeRequired
enum('small', 'large'), numberNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/alert.html b/docs/0.60/alert.html index 83478a52ee2..4cf07b40a89 100644 --- a/docs/0.60/alert.html +++ b/docs/0.60/alert.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

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 Android and iOS and can show static alerts. To show an alert that prompts the user to enter some information, see AlertIOS; entering text in an alert is common on iOS only.

Example

iOSAndroid

iOS

On iOS you can specify any number of buttons. Each button can optionally specify a style, which is one of 'default', 'cancel' or 'destructive'.

Android

On Android at most three buttons can be specified. Android has a concept of a neutral, negative and a positive button:

  • If you specify one button, it will be the 'positive' one (such as 'OK')
  • Two buttons mean 'negative', 'positive' (such as 'Cancel', 'OK')
  • Three buttons mean 'neutral', 'negative', 'positive' (such as 'Later', 'Cancel', 'OK')

By default alerts on Android can be dismissed by tapping outside of the alert box. This event can be handled by providing an optional options parameter, with an onDismiss callback property { onDismiss: () => {} }.

Alternatively, the dismissing behavior can be disabled altogether by providing an optional options parameter with the cancelable property set to false i.e. { cancelable: false }

Example usage:

// Works on both Android and iOS
Alert.alert(
'Alert Title',
'My Alert Msg',
[
{
text: 'Ask me later',
onPress: () => console.log('Ask me later pressed')
},
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{ text: 'OK', onPress: () => console.log('OK Pressed') }
],
{ cancelable: false }
);

Reference

Methods

alert()

static alert(title, message?, buttons?, options? type?)
Edit this page
Last updated on
- + diff --git a/docs/0.60/alert/index.html b/docs/0.60/alert/index.html index 83478a52ee2..4cf07b40a89 100644 --- a/docs/0.60/alert/index.html +++ b/docs/0.60/alert/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

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 Android and iOS and can show static alerts. To show an alert that prompts the user to enter some information, see AlertIOS; entering text in an alert is common on iOS only.

Example

iOSAndroid

iOS

On iOS you can specify any number of buttons. Each button can optionally specify a style, which is one of 'default', 'cancel' or 'destructive'.

Android

On Android at most three buttons can be specified. Android has a concept of a neutral, negative and a positive button:

  • If you specify one button, it will be the 'positive' one (such as 'OK')
  • Two buttons mean 'negative', 'positive' (such as 'Cancel', 'OK')
  • Three buttons mean 'neutral', 'negative', 'positive' (such as 'Later', 'Cancel', 'OK')

By default alerts on Android can be dismissed by tapping outside of the alert box. This event can be handled by providing an optional options parameter, with an onDismiss callback property { onDismiss: () => {} }.

Alternatively, the dismissing behavior can be disabled altogether by providing an optional options parameter with the cancelable property set to false i.e. { cancelable: false }

Example usage:

// Works on both Android and iOS
Alert.alert(
'Alert Title',
'My Alert Msg',
[
{
text: 'Ask me later',
onPress: () => console.log('Ask me later pressed')
},
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{ text: 'OK', onPress: () => console.log('OK Pressed') }
],
{ cancelable: false }
);

Reference

Methods

alert()

static alert(title, message?, buttons?, options? type?)
Edit this page
Last updated on
- + diff --git a/docs/0.60/alertios.html b/docs/0.60/alertios.html index 45538bef4f5..a9bd1027670 100644 --- a/docs/0.60/alertios.html +++ b/docs/0.60/alertios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

AlertIOS

Deprecated. AlertIOS has been moved to Alert

AlertIOS provides functionality to create an iOS alert dialog with a message or create a prompt for user input.

Creating an iOS alert:

AlertIOS.alert(
'Sync Complete',
'All your data are belong to us.'
);

Creating an iOS prompt:

AlertIOS.prompt('Enter a value', null, (text) =>
console.log('You entered ' + text)
);

We recommend using the Alert.alert method for cross-platform support if you don't need to create iOS-only prompts.

Reference

Methods

alert()

static alert(title: string, [message]: string, [callbackOrButtons]: ?(() => void), ButtonsArray, [type]: AlertType): [object Object]

Create and display a popup alert.

Parameters:

NameTypeRequiredDescription
titlestringYesThe dialog's title. Passing null or '' will hide the title.
messagestringNoAn optional message that appears below the dialog's title.
callbackOrButtons?(() => void),ButtonsArrayNoThis optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called when the user taps 'OK'. If passed an array of button configurations, each button should include a text key, as well as optional onPress and style keys. style should be one of 'default', 'cancel' or 'destructive'.
typeAlertTypeNoDeprecated, do not use.

Example with custom buttons:

AlertIOS.alert(
'Update available',
'Keep your app up to date to enjoy the latest features',
[
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{
text: 'Install',
onPress: () => console.log('Install Pressed')
}
]
);

prompt()

static prompt(title: string, [message]: string, [callbackOrButtons]: ?((text: string) => void), ButtonsArray, [type]: AlertType, [defaultValue]: string, [keyboardType]: string): [object Object]

Create and display a prompt to enter some text.

Parameters:

NameTypeRequiredDescription
titlestringYesThe dialog's title.
messagestringNoAn optional message that appears above the text input.
callbackOrButtons?((text: string) => void),ButtonsArrayNoThis optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called with the prompt's value when the user taps 'OK'. If passed an array of button configurations, each button should include a text key, as well as optional onPress and style keys (see example). style should be one of 'default', 'cancel' or 'destructive'.
typeAlertTypeNoThis configures the text input. One of 'plain-text', 'secure-text' or 'login-password'.
defaultValuestringNoThe default text in text input.
keyboardTypestringNoThe keyboard type of first text field(if exists). One of 'default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter' or 'web-search'.

Example with custom buttons:

AlertIOS.prompt(
'Enter password',
'Enter your password to claim your $1.5B in lottery winnings',
[
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{
text: 'OK',
onPress: (password) =>
console.log('OK Pressed, password: ' + password)
}
],
'secure-text'
);

,

Example with the default button and a custom callback:

AlertIOS.prompt(
'Update username',
null,
(text) => console.log('Your username is ' + text),
null,
'default'
);

Type Definitions

AlertType

An Alert button type

Type
\$Enum

Constants:

ValueDescription
defaultDefault alert with no inputs
plain-textPlain text input alert
secure-textSecure text input alert
login-passwordLogin and password alert

AlertButtonStyle

An Alert button style

Type
\$Enum

Constants:

ValueDescription
defaultDefault button style
cancelCancel button style
destructiveDestructive button style

ButtonsArray

Array or buttons

Type
Array

Properties:

NameTypeDescription
[text]stringButton label
[onPress]functionCallback function when button pressed
[style]AlertButtonStyleButton style

Constants:

ValueDescription
textButton label
onPressCallback function when button pressed
styleButton style
Edit this page
Last updated on
- + diff --git a/docs/0.60/alertios/index.html b/docs/0.60/alertios/index.html index 45538bef4f5..a9bd1027670 100644 --- a/docs/0.60/alertios/index.html +++ b/docs/0.60/alertios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

AlertIOS

Deprecated. AlertIOS has been moved to Alert

AlertIOS provides functionality to create an iOS alert dialog with a message or create a prompt for user input.

Creating an iOS alert:

AlertIOS.alert(
'Sync Complete',
'All your data are belong to us.'
);

Creating an iOS prompt:

AlertIOS.prompt('Enter a value', null, (text) =>
console.log('You entered ' + text)
);

We recommend using the Alert.alert method for cross-platform support if you don't need to create iOS-only prompts.

Reference

Methods

alert()

static alert(title: string, [message]: string, [callbackOrButtons]: ?(() => void), ButtonsArray, [type]: AlertType): [object Object]

Create and display a popup alert.

Parameters:

NameTypeRequiredDescription
titlestringYesThe dialog's title. Passing null or '' will hide the title.
messagestringNoAn optional message that appears below the dialog's title.
callbackOrButtons?(() => void),ButtonsArrayNoThis optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called when the user taps 'OK'. If passed an array of button configurations, each button should include a text key, as well as optional onPress and style keys. style should be one of 'default', 'cancel' or 'destructive'.
typeAlertTypeNoDeprecated, do not use.

Example with custom buttons:

AlertIOS.alert(
'Update available',
'Keep your app up to date to enjoy the latest features',
[
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{
text: 'Install',
onPress: () => console.log('Install Pressed')
}
]
);

prompt()

static prompt(title: string, [message]: string, [callbackOrButtons]: ?((text: string) => void), ButtonsArray, [type]: AlertType, [defaultValue]: string, [keyboardType]: string): [object Object]

Create and display a prompt to enter some text.

Parameters:

NameTypeRequiredDescription
titlestringYesThe dialog's title.
messagestringNoAn optional message that appears above the text input.
callbackOrButtons?((text: string) => void),ButtonsArrayNoThis optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called with the prompt's value when the user taps 'OK'. If passed an array of button configurations, each button should include a text key, as well as optional onPress and style keys (see example). style should be one of 'default', 'cancel' or 'destructive'.
typeAlertTypeNoThis configures the text input. One of 'plain-text', 'secure-text' or 'login-password'.
defaultValuestringNoThe default text in text input.
keyboardTypestringNoThe keyboard type of first text field(if exists). One of 'default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter' or 'web-search'.

Example with custom buttons:

AlertIOS.prompt(
'Enter password',
'Enter your password to claim your $1.5B in lottery winnings',
[
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{
text: 'OK',
onPress: (password) =>
console.log('OK Pressed, password: ' + password)
}
],
'secure-text'
);

,

Example with the default button and a custom callback:

AlertIOS.prompt(
'Update username',
null,
(text) => console.log('Your username is ' + text),
null,
'default'
);

Type Definitions

AlertType

An Alert button type

Type
\$Enum

Constants:

ValueDescription
defaultDefault alert with no inputs
plain-textPlain text input alert
secure-textSecure text input alert
login-passwordLogin and password alert

AlertButtonStyle

An Alert button style

Type
\$Enum

Constants:

ValueDescription
defaultDefault button style
cancelCancel button style
destructiveDestructive button style

ButtonsArray

Array or buttons

Type
Array

Properties:

NameTypeDescription
[text]stringButton label
[onPress]functionCallback function when button pressed
[style]AlertButtonStyleButton style

Constants:

ValueDescription
textButton label
onPressCallback function when button pressed
styleButton style
Edit this page
Last updated on
- + diff --git a/docs/0.60/animated.html b/docs/0.60/animated.html index 06ebea4063d..638587084e1 100644 --- a/docs/0.60/animated.html +++ b/docs/0.60/animated.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Animated

The Animated library is designed to make animations fluid, powerful, and painless to build and maintain. Animated focuses on declarative relationships between inputs and outputs, with configurable transforms in between, and start/stop methods to control time-based animation execution.

The most basic workflow for creating an animation is to create an Animated.Value, hook it up to one or more style attributes of an animated component, and then drive updates via animations using Animated.timing():

Animated.timing(
// Animate value over time
this.state.fadeAnim, // The value to drive
{
toValue: 1 // Animate to final value of 1
}
).start(); // Start the animation

Refer to the Animations guide to see additional examples of Animated in action.

Overview

There are two value types you can use with Animated:

Animated.Value can bind to style properties or other props, and can be interpolated as well. A single Animated.Value can drive any number of properties.

Configuring animations

Animated provides three types of animation types. Each animation type provides a particular animation curve that controls how your values animate from their initial value to the final value:

In most cases, you will be using timing(). By default, it uses a symmetric easeInOut curve that conveys the gradual acceleration of an object to full speed and concludes by gradually decelerating to a stop.

Working with animations

Animations are started by calling start() on your animation. start() takes a completion callback that will be called when the animation is done. If the animation finished running normally, the completion callback will be invoked with {finished: true}. If the animation is done because stop() was called on it before it could finish (e.g. because it was interrupted by a gesture or another animation), then it will receive {finished: false}.

Using the native driver

By using the native driver, we send everything about the animation to native before starting the animation, allowing native code to perform the animation on the UI thread without having to go through the bridge on every frame. Once the animation has started, the JS thread can be blocked without affecting the animation.

You can use the native driver by specifying useNativeDriver: true in your animation configuration. See the Animations guide to learn more.

Animatable components

Only animatable components can be animated. These unique components do the magic of binding the animated values to the properties, and do targeted native updates to avoid the cost of the react render and reconciliation process on every frame. They also handle cleanup on unmount so they are safe by default.

Animated exports the following animatable components using the above wrapper:

  • Animated.Image
  • Animated.ScrollView
  • Animated.Text
  • Animated.View
  • Animated.FlatList
  • Animated.SectionList

Composing animations

Animations can also be combined in complex ways using composition functions:

Animations can also be chained together by setting the toValue of one animation to be another Animated.Value. See Tracking dynamic values in the Animations guide.

By default, if one animation is stopped or interrupted, then all other animations in the group are also stopped.

Combining animated values

You can combine two animated values via addition, subtraction, multiplication, division, or modulo to make a new animated value:

Interpolation

The interpolate() function allows input ranges to map to different output ranges. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value. It uses linear interpolation by default but also supports easing functions.

Read more about interpolation in the Animation guide.

Handling gestures and other events

Gestures, like panning or scrolling, and other events can map directly to animated values using Animated.event(). This is done with a structured map syntax so that values can be extracted from complex event objects. The first level is an array to allow mapping across multiple args, and that array contains nested objects.

For example, when working with horizontal scrolling gestures, you would do the following in order to map event.nativeEvent.contentOffset.x to scrollX (an Animated.Value):

onScroll={Animated.event(
// scrollX = e.nativeEvent.contentOffset.x
[{ nativeEvent: {
contentOffset: {
x: scrollX
}
}
}]
)}

Reference

Methods

When the given value is a ValueXY instead of a Value, each config option may be a vector of the form {x: ..., y: ...} instead of a scalar.

decay()

static decay(value, config)

Animates a value from an initial velocity to zero based on a decay coefficient.

Config is an object that may have the following options:

  • velocity: Initial velocity. Required.
  • deceleration: Rate of decay. Default 0.997.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

timing()

static timing(value, config)

Animates a value along a timed easing curve. The Easing module has tons of predefined curves, or you can use your own function.

Config is an object that may have the following options:

  • duration: Length of animation (milliseconds). Default 500.
  • easing: Easing function to define curve. Default is Easing.inOut(Easing.ease).
  • delay: Start the animation after delay (milliseconds). Default 0.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

spring()

static spring(value, config)

Animates a value according to an analytical spring model based on damped harmonic oscillation. Tracks velocity state to create fluid motions as the toValue updates, and can be chained together.

Config is an object that may have the following options.

Note that you can only define one of bounciness/speed, tension/friction, or stiffness/damping/mass, but not more than one:

The friction/tension or bounciness/speed options match the spring model in Facebook Pop, Rebound, and Origami.

  • friction: Controls "bounciness"/overshoot. Default 7.
  • tension: Controls speed. Default 40.
  • speed: Controls speed of the animation. Default 12.
  • bounciness: Controls bounciness. Default 8.

Specifying stiffness/damping/mass as parameters makes Animated.spring use an analytical spring model based on the motion equations of a damped harmonic oscillator. This behavior is slightly more precise and faithful to the physics behind spring dynamics, and closely mimics the implementation in iOS's CASpringAnimation.

  • stiffness: The spring stiffness coefficient. Default 100.
  • damping: Defines how the spring’s motion should be damped due to the forces of friction. Default 10.
  • mass: The mass of the object attached to the end of the spring. Default 1.

Other configuration options are as follows:

  • velocity: The initial velocity of the object attached to the spring. Default 0 (object is at rest).
  • overshootClamping: Boolean indicating whether the spring should be clamped and not bounce. Default false.
  • restDisplacementThreshold: The threshold of displacement from rest below which the spring should be considered at rest. Default 0.001.
  • restSpeedThreshold: The speed at which the spring should be considered at rest in pixels per second. Default 0.001.
  • delay: Start the animation after delay (milliseconds). Default 0.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

add()

static add(a, b)

Creates a new Animated value composed from two Animated values added together.

subtract()

static subtract(a, b)

Creates a new Animated value composed by subtracting the second Animated value from the first Animated value.

divide()

static divide(a, b)

Creates a new Animated value composed by dividing the first Animated value by the second Animated value.

multiply()

static multiply(a, b)

Creates a new Animated value composed from two Animated values multiplied together.

modulo()

static modulo(a, modulus)

Creates a new Animated value that is the (non-negative) modulo of the provided Animated value

diffClamp()

static diffClamp(a, min, max)

Create a new Animated value that is limited between 2 values. It uses the difference between the last value so even if the value is far from the bounds it will start changing when the value starts getting closer again. (value = clamp(value + diff, min, max)).

This is useful with scroll events, for example, to show the navbar when scrolling up and to hide it when scrolling down.

delay()

static delay(time)

Starts an animation after the given delay.

sequence()

static sequence(animations)

Starts an array of animations in order, waiting for each to complete before starting the next. If the current running animation is stopped, no following animations will be started.

parallel()

static parallel(animations, config?)

Starts an array of animations all at the same time. By default, if one of the animations is stopped, they will all be stopped. You can override this with the stopTogether flag.

stagger()

static stagger(time, animations)

Array of animations may run in parallel (overlap), but are started in sequence with successive delays. Nice for doing trailing effects.

loop()

static loop(animation, config?)

Loops a given animation continuously, so that each time it reaches the end, it resets and begins again from the start. Will loop without blocking the UI thread if the child animation is set to useNativeDriver: true. In addition, loops can prevent VirtualizedList-based components from rendering more rows while the animation is running. You can pass isInteraction: false in the child animation config to fix this.

Config is an object that may have the following options:

  • iterations: Number of times the animation should loop. Default -1 (infinite).

event()

static event(argMapping, config?)

Takes an array of mappings and extracts values from each arg accordingly, then calls setValue on the mapped outputs. e.g.

onScroll={Animated.event(
[{nativeEvent: {contentOffset: {x: this._scrollX}}}],
{listener: (event) => console.log(event)}, // Optional async listener
)}
...
onPanResponderMove: Animated.event([
null, // raw event arg ignored
{dx: this._panX}], // gestureState arg
{listener: (event, gestureState) => console.log(event, gestureState)}, // Optional async listener
),

Config is an object that may have the following options:

  • listener: Optional async listener.
  • useNativeDriver: Uses the native driver when true. Default false.

forkEvent()

static forkEvent(event, listener)

Advanced imperative API for snooping on animated events that are passed in through props. It permits to add a new javascript listener to an existing AnimatedEvent. If animatedEvent is a javascript listener, it will merge the 2 listeners into a single one, and if animatedEvent is null/undefined, it will assign the javascript listener directly. Use values directly where possible.

unforkEvent()

static unforkEvent(event, listener)

Properties

Value

Standard value class for driving animations. Typically initialized with new Animated.Value(0);

ValueXY

2D value class for driving 2D animations, such as pan gestures.

Interpolation

Exported to use the Interpolation type in flow.

Node

Exported for ease of type checking. All animated values derive from this class.

createAnimatedComponent

Make any React component Animatable. Used to create Animated.View, etc.

attachNativeEvent

Imperative API to attach an animated value to an event on a view. Prefer using Animated.event with useNativeDrive: true if possible.

Edit this page
Last updated on
- + diff --git a/docs/0.60/animated/index.html b/docs/0.60/animated/index.html index 06ebea4063d..638587084e1 100644 --- a/docs/0.60/animated/index.html +++ b/docs/0.60/animated/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Animated

The Animated library is designed to make animations fluid, powerful, and painless to build and maintain. Animated focuses on declarative relationships between inputs and outputs, with configurable transforms in between, and start/stop methods to control time-based animation execution.

The most basic workflow for creating an animation is to create an Animated.Value, hook it up to one or more style attributes of an animated component, and then drive updates via animations using Animated.timing():

Animated.timing(
// Animate value over time
this.state.fadeAnim, // The value to drive
{
toValue: 1 // Animate to final value of 1
}
).start(); // Start the animation

Refer to the Animations guide to see additional examples of Animated in action.

Overview

There are two value types you can use with Animated:

Animated.Value can bind to style properties or other props, and can be interpolated as well. A single Animated.Value can drive any number of properties.

Configuring animations

Animated provides three types of animation types. Each animation type provides a particular animation curve that controls how your values animate from their initial value to the final value:

In most cases, you will be using timing(). By default, it uses a symmetric easeInOut curve that conveys the gradual acceleration of an object to full speed and concludes by gradually decelerating to a stop.

Working with animations

Animations are started by calling start() on your animation. start() takes a completion callback that will be called when the animation is done. If the animation finished running normally, the completion callback will be invoked with {finished: true}. If the animation is done because stop() was called on it before it could finish (e.g. because it was interrupted by a gesture or another animation), then it will receive {finished: false}.

Using the native driver

By using the native driver, we send everything about the animation to native before starting the animation, allowing native code to perform the animation on the UI thread without having to go through the bridge on every frame. Once the animation has started, the JS thread can be blocked without affecting the animation.

You can use the native driver by specifying useNativeDriver: true in your animation configuration. See the Animations guide to learn more.

Animatable components

Only animatable components can be animated. These unique components do the magic of binding the animated values to the properties, and do targeted native updates to avoid the cost of the react render and reconciliation process on every frame. They also handle cleanup on unmount so they are safe by default.

Animated exports the following animatable components using the above wrapper:

  • Animated.Image
  • Animated.ScrollView
  • Animated.Text
  • Animated.View
  • Animated.FlatList
  • Animated.SectionList

Composing animations

Animations can also be combined in complex ways using composition functions:

Animations can also be chained together by setting the toValue of one animation to be another Animated.Value. See Tracking dynamic values in the Animations guide.

By default, if one animation is stopped or interrupted, then all other animations in the group are also stopped.

Combining animated values

You can combine two animated values via addition, subtraction, multiplication, division, or modulo to make a new animated value:

Interpolation

The interpolate() function allows input ranges to map to different output ranges. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value. It uses linear interpolation by default but also supports easing functions.

Read more about interpolation in the Animation guide.

Handling gestures and other events

Gestures, like panning or scrolling, and other events can map directly to animated values using Animated.event(). This is done with a structured map syntax so that values can be extracted from complex event objects. The first level is an array to allow mapping across multiple args, and that array contains nested objects.

For example, when working with horizontal scrolling gestures, you would do the following in order to map event.nativeEvent.contentOffset.x to scrollX (an Animated.Value):

onScroll={Animated.event(
// scrollX = e.nativeEvent.contentOffset.x
[{ nativeEvent: {
contentOffset: {
x: scrollX
}
}
}]
)}

Reference

Methods

When the given value is a ValueXY instead of a Value, each config option may be a vector of the form {x: ..., y: ...} instead of a scalar.

decay()

static decay(value, config)

Animates a value from an initial velocity to zero based on a decay coefficient.

Config is an object that may have the following options:

  • velocity: Initial velocity. Required.
  • deceleration: Rate of decay. Default 0.997.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

timing()

static timing(value, config)

Animates a value along a timed easing curve. The Easing module has tons of predefined curves, or you can use your own function.

Config is an object that may have the following options:

  • duration: Length of animation (milliseconds). Default 500.
  • easing: Easing function to define curve. Default is Easing.inOut(Easing.ease).
  • delay: Start the animation after delay (milliseconds). Default 0.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

spring()

static spring(value, config)

Animates a value according to an analytical spring model based on damped harmonic oscillation. Tracks velocity state to create fluid motions as the toValue updates, and can be chained together.

Config is an object that may have the following options.

Note that you can only define one of bounciness/speed, tension/friction, or stiffness/damping/mass, but not more than one:

The friction/tension or bounciness/speed options match the spring model in Facebook Pop, Rebound, and Origami.

  • friction: Controls "bounciness"/overshoot. Default 7.
  • tension: Controls speed. Default 40.
  • speed: Controls speed of the animation. Default 12.
  • bounciness: Controls bounciness. Default 8.

Specifying stiffness/damping/mass as parameters makes Animated.spring use an analytical spring model based on the motion equations of a damped harmonic oscillator. This behavior is slightly more precise and faithful to the physics behind spring dynamics, and closely mimics the implementation in iOS's CASpringAnimation.

  • stiffness: The spring stiffness coefficient. Default 100.
  • damping: Defines how the spring’s motion should be damped due to the forces of friction. Default 10.
  • mass: The mass of the object attached to the end of the spring. Default 1.

Other configuration options are as follows:

  • velocity: The initial velocity of the object attached to the spring. Default 0 (object is at rest).
  • overshootClamping: Boolean indicating whether the spring should be clamped and not bounce. Default false.
  • restDisplacementThreshold: The threshold of displacement from rest below which the spring should be considered at rest. Default 0.001.
  • restSpeedThreshold: The speed at which the spring should be considered at rest in pixels per second. Default 0.001.
  • delay: Start the animation after delay (milliseconds). Default 0.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

add()

static add(a, b)

Creates a new Animated value composed from two Animated values added together.

subtract()

static subtract(a, b)

Creates a new Animated value composed by subtracting the second Animated value from the first Animated value.

divide()

static divide(a, b)

Creates a new Animated value composed by dividing the first Animated value by the second Animated value.

multiply()

static multiply(a, b)

Creates a new Animated value composed from two Animated values multiplied together.

modulo()

static modulo(a, modulus)

Creates a new Animated value that is the (non-negative) modulo of the provided Animated value

diffClamp()

static diffClamp(a, min, max)

Create a new Animated value that is limited between 2 values. It uses the difference between the last value so even if the value is far from the bounds it will start changing when the value starts getting closer again. (value = clamp(value + diff, min, max)).

This is useful with scroll events, for example, to show the navbar when scrolling up and to hide it when scrolling down.

delay()

static delay(time)

Starts an animation after the given delay.

sequence()

static sequence(animations)

Starts an array of animations in order, waiting for each to complete before starting the next. If the current running animation is stopped, no following animations will be started.

parallel()

static parallel(animations, config?)

Starts an array of animations all at the same time. By default, if one of the animations is stopped, they will all be stopped. You can override this with the stopTogether flag.

stagger()

static stagger(time, animations)

Array of animations may run in parallel (overlap), but are started in sequence with successive delays. Nice for doing trailing effects.

loop()

static loop(animation, config?)

Loops a given animation continuously, so that each time it reaches the end, it resets and begins again from the start. Will loop without blocking the UI thread if the child animation is set to useNativeDriver: true. In addition, loops can prevent VirtualizedList-based components from rendering more rows while the animation is running. You can pass isInteraction: false in the child animation config to fix this.

Config is an object that may have the following options:

  • iterations: Number of times the animation should loop. Default -1 (infinite).

event()

static event(argMapping, config?)

Takes an array of mappings and extracts values from each arg accordingly, then calls setValue on the mapped outputs. e.g.

onScroll={Animated.event(
[{nativeEvent: {contentOffset: {x: this._scrollX}}}],
{listener: (event) => console.log(event)}, // Optional async listener
)}
...
onPanResponderMove: Animated.event([
null, // raw event arg ignored
{dx: this._panX}], // gestureState arg
{listener: (event, gestureState) => console.log(event, gestureState)}, // Optional async listener
),

Config is an object that may have the following options:

  • listener: Optional async listener.
  • useNativeDriver: Uses the native driver when true. Default false.

forkEvent()

static forkEvent(event, listener)

Advanced imperative API for snooping on animated events that are passed in through props. It permits to add a new javascript listener to an existing AnimatedEvent. If animatedEvent is a javascript listener, it will merge the 2 listeners into a single one, and if animatedEvent is null/undefined, it will assign the javascript listener directly. Use values directly where possible.

unforkEvent()

static unforkEvent(event, listener)

Properties

Value

Standard value class for driving animations. Typically initialized with new Animated.Value(0);

ValueXY

2D value class for driving 2D animations, such as pan gestures.

Interpolation

Exported to use the Interpolation type in flow.

Node

Exported for ease of type checking. All animated values derive from this class.

createAnimatedComponent

Make any React component Animatable. Used to create Animated.View, etc.

attachNativeEvent

Imperative API to attach an animated value to an event on a view. Prefer using Animated.event with useNativeDrive: true if possible.

Edit this page
Last updated on
- + diff --git a/docs/0.60/animatedvalue.html b/docs/0.60/animatedvalue.html index 8d6389a54ee..c0aa1e19613 100644 --- a/docs/0.60/animatedvalue.html +++ b/docs/0.60/animatedvalue.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

AnimatedValue

Standard value for driving animations. One Animated.Value can drive multiple properties in a synchronized fashion, but can only be driven by one mechanism at a time. Using a new mechanism (e.g. starting a new animation, or calling setValue) will stop any previous ones.

Typically initialized with new Animated.Value(0);

See also Animated.

Methods

Reference

Methods

setValue()

setValue(value);

Directly set the value. This will stop any animations running on the value and update all the bound properties.

Parameters:

NameTypeRequiredDescription
valuenumberYesValue

setOffset()

setOffset(offset);

Sets an offset that is applied on top of whatever value is set, whether via setValue, an animation, or Animated.event. Useful for compensating things like the start of a pan gesture.

Parameters:

NameTypeRequiredDescription
offsetnumberYesOffset value

flattenOffset()

flattenOffset();

Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.

extractOffset()

extractOffset();

Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.

addListener()

addListener(callback);

Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.

Returns a string that serves as an identifier for the listener.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesThe callback function which will receive an object with a value key set to the new value.

removeListener()

removeListener(id);

Unregister a listener. The id param shall match the identifier previously returned by addListener().

Parameters:

NameTypeRequiredDescription
idstringYesId for the listener being removed.

removeAllListeners()

removeAllListeners();

Remove all registered listeners.

stopAnimation()

stopAnimation([callback]);

Stops any running animation or tracking. callback is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the final value.

resetAnimation()

resetAnimation([callback]);

Stops any animation and resets the value to its original.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the original value.

interpolate()

interpolate(config);

Interpolates the value before updating the property, e.g. mapping 0-1 to 0-10.

See AnimatedInterpolation.js

Parameters:

NameTypeRequiredDescription
configobjectYesSee below.

The config object is composed of the following keys:

  • inputRange: an array of numbers
  • outputRange: an array of numbers or strings
  • easing (optional): a function that returns a number, given an input number
  • extrapolate (optional): a string such as 'extend', 'identity', or 'clamp'
  • extrapolateLeft (optional): a string such as 'extend', 'identity', or 'clamp'
  • extrapolateRight (optional): a string such as 'extend', 'identity', or 'clamp'

animate()

animate(animation, callback);

Typically only used internally, but could be used by a custom Animation class.

Parameters:

NameTypeRequiredDescription
animationAnimationYesSee Animation.js.
callbackfunctionYesCallback function.

stopTracking()

stopTracking();

Typically only used internally.

track()

track(tracking);

Typically only used internally.

Parameters:

NameTypeRequiredDescription
trackingAnimatedNodeYesSee AnimatedNode.js
Edit this page
Last updated on
- + diff --git a/docs/0.60/animatedvalue/index.html b/docs/0.60/animatedvalue/index.html index 8d6389a54ee..c0aa1e19613 100644 --- a/docs/0.60/animatedvalue/index.html +++ b/docs/0.60/animatedvalue/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

AnimatedValue

Standard value for driving animations. One Animated.Value can drive multiple properties in a synchronized fashion, but can only be driven by one mechanism at a time. Using a new mechanism (e.g. starting a new animation, or calling setValue) will stop any previous ones.

Typically initialized with new Animated.Value(0);

See also Animated.

Methods

Reference

Methods

setValue()

setValue(value);

Directly set the value. This will stop any animations running on the value and update all the bound properties.

Parameters:

NameTypeRequiredDescription
valuenumberYesValue

setOffset()

setOffset(offset);

Sets an offset that is applied on top of whatever value is set, whether via setValue, an animation, or Animated.event. Useful for compensating things like the start of a pan gesture.

Parameters:

NameTypeRequiredDescription
offsetnumberYesOffset value

flattenOffset()

flattenOffset();

Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.

extractOffset()

extractOffset();

Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.

addListener()

addListener(callback);

Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.

Returns a string that serves as an identifier for the listener.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesThe callback function which will receive an object with a value key set to the new value.

removeListener()

removeListener(id);

Unregister a listener. The id param shall match the identifier previously returned by addListener().

Parameters:

NameTypeRequiredDescription
idstringYesId for the listener being removed.

removeAllListeners()

removeAllListeners();

Remove all registered listeners.

stopAnimation()

stopAnimation([callback]);

Stops any running animation or tracking. callback is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the final value.

resetAnimation()

resetAnimation([callback]);

Stops any animation and resets the value to its original.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the original value.

interpolate()

interpolate(config);

Interpolates the value before updating the property, e.g. mapping 0-1 to 0-10.

See AnimatedInterpolation.js

Parameters:

NameTypeRequiredDescription
configobjectYesSee below.

The config object is composed of the following keys:

  • inputRange: an array of numbers
  • outputRange: an array of numbers or strings
  • easing (optional): a function that returns a number, given an input number
  • extrapolate (optional): a string such as 'extend', 'identity', or 'clamp'
  • extrapolateLeft (optional): a string such as 'extend', 'identity', or 'clamp'
  • extrapolateRight (optional): a string such as 'extend', 'identity', or 'clamp'

animate()

animate(animation, callback);

Typically only used internally, but could be used by a custom Animation class.

Parameters:

NameTypeRequiredDescription
animationAnimationYesSee Animation.js.
callbackfunctionYesCallback function.

stopTracking()

stopTracking();

Typically only used internally.

track()

track(tracking);

Typically only used internally.

Parameters:

NameTypeRequiredDescription
trackingAnimatedNodeYesSee AnimatedNode.js
Edit this page
Last updated on
- + diff --git a/docs/0.60/animatedvaluexy.html b/docs/0.60/animatedvaluexy.html index 350799b4d58..6baed0e8e4d 100644 --- a/docs/0.60/animatedvaluexy.html +++ b/docs/0.60/animatedvaluexy.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

AnimatedValueXY

2D Value for driving 2D animations, such as pan gestures. Almost identical API to normal Animated.Value, but multiplexed. Contains two regular Animated.Values under the hood.

See also Animated.

Example

class DraggableView extends React.Component {
constructor(props) {
super(props);
this.state = {
pan: new Animated.ValueXY() // inits to zero
};
this.state.panResponder = PanResponder.create({
onStartShouldSetPanResponder: () => true,
onPanResponderMove: Animated.event([
null,
{
dx: this.state.pan.x, // x,y are Animated.Value
dy: this.state.pan.y
}
]),
onPanResponderRelease: () => {
Animated.spring(
this.state.pan, // Auto-multiplexed
{ toValue: { x: 0, y: 0 } } // Back to zero
).start();
}
});
}
render() {
return (
<Animated.View
{...this.state.panResponder.panHandlers}
style={this.state.pan.getLayout()}>
{this.props.children}
</Animated.View>
);
}
}

Methods

Reference

Methods

setValue()

setValue(value);

Directly set the value. This will stop any animations running on the value and update all the bound properties.

Parameters:

NameTypeRequiredDescription
valuenumberYes

setOffset()

setOffset(offset);

Sets an offset that is applied on top of whatever value is set, whether via setValue, an animation, or Animated.event. Useful for compensating things like the start of a pan gesture.

Parameters:

NameTypeRequiredDescription
offsetnumberYes

flattenOffset()

flattenOffset();

Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.

extractOffset()

extractOffset();

Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.

addListener()

addListener(callback);

Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.

Returns a string that serves as an identifier for the listener.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesThe callback function which will receive an object with a value key set to the new value.

removeListener()

removeListener(id);

Unregister a listener. The id param shall match the identifier previously returned by addListener().

Parameters:

NameTypeRequiredDescription
idstringYesId for the listener being removed.

removeAllListeners()

removeAllListeners();

Remove all registered listeners.

stopAnimation()

stopAnimation([callback]);

Stops any running animation or tracking. callback is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the final value.

resetAnimation()

resetAnimation([callback]);

Stops any animation and resets the value to its original.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the original value.

getLayout()

getLayout();

Converts {x, y} into {left, top} for use in style, e.g.

style={this.state.anim.getLayout()}

getTranslateTransform()

getTranslateTransform();

Converts {x, y} into a useable translation transform, e.g.

style={{
transform: this.state.anim.getTranslateTransform()
}}
Edit this page
Last updated on
- + diff --git a/docs/0.60/animatedvaluexy/index.html b/docs/0.60/animatedvaluexy/index.html index 350799b4d58..6baed0e8e4d 100644 --- a/docs/0.60/animatedvaluexy/index.html +++ b/docs/0.60/animatedvaluexy/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

AnimatedValueXY

2D Value for driving 2D animations, such as pan gestures. Almost identical API to normal Animated.Value, but multiplexed. Contains two regular Animated.Values under the hood.

See also Animated.

Example

class DraggableView extends React.Component {
constructor(props) {
super(props);
this.state = {
pan: new Animated.ValueXY() // inits to zero
};
this.state.panResponder = PanResponder.create({
onStartShouldSetPanResponder: () => true,
onPanResponderMove: Animated.event([
null,
{
dx: this.state.pan.x, // x,y are Animated.Value
dy: this.state.pan.y
}
]),
onPanResponderRelease: () => {
Animated.spring(
this.state.pan, // Auto-multiplexed
{ toValue: { x: 0, y: 0 } } // Back to zero
).start();
}
});
}
render() {
return (
<Animated.View
{...this.state.panResponder.panHandlers}
style={this.state.pan.getLayout()}>
{this.props.children}
</Animated.View>
);
}
}

Methods

Reference

Methods

setValue()

setValue(value);

Directly set the value. This will stop any animations running on the value and update all the bound properties.

Parameters:

NameTypeRequiredDescription
valuenumberYes

setOffset()

setOffset(offset);

Sets an offset that is applied on top of whatever value is set, whether via setValue, an animation, or Animated.event. Useful for compensating things like the start of a pan gesture.

Parameters:

NameTypeRequiredDescription
offsetnumberYes

flattenOffset()

flattenOffset();

Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.

extractOffset()

extractOffset();

Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.

addListener()

addListener(callback);

Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.

Returns a string that serves as an identifier for the listener.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesThe callback function which will receive an object with a value key set to the new value.

removeListener()

removeListener(id);

Unregister a listener. The id param shall match the identifier previously returned by addListener().

Parameters:

NameTypeRequiredDescription
idstringYesId for the listener being removed.

removeAllListeners()

removeAllListeners();

Remove all registered listeners.

stopAnimation()

stopAnimation([callback]);

Stops any running animation or tracking. callback is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the final value.

resetAnimation()

resetAnimation([callback]);

Stops any animation and resets the value to its original.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the original value.

getLayout()

getLayout();

Converts {x, y} into {left, top} for use in style, e.g.

style={this.state.anim.getLayout()}

getTranslateTransform()

getTranslateTransform();

Converts {x, y} into a useable translation transform, e.g.

style={{
transform: this.state.anim.getTranslateTransform()
}}
Edit this page
Last updated on
- + diff --git a/docs/0.60/animations.html b/docs/0.60/animations.html index 3b0ba7f6bd4..aa0c67f03eb 100644 --- a/docs/0.60/animations.html +++ b/docs/0.60/animations.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Animated.spring(a, {
toValue: 2
}).start();

Interpolation

Each property can be run through an interpolation first. An interpolation maps input ranges to output ranges, typically using a linear interpolation but also supports easing functions. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value.

A mapping to convert a 0-1 range to a 0-100 range would be:

value.interpolate({
inputRange: [0, 1],
outputRange: [0, 100]
});

For example, you may want to think about your Animated.Value as going from 0 to 1, but animate the position from 150px to 0px and the opacity from 0 to 1. This can be done by modifying style from the example above like so:

style={{
opacity: this.state.fadeAnim, // Binds directly
transform: [{
translateY: this.state.fadeAnim.interpolate({
inputRange: [0, 1],
outputRange: [150, 0] // 0 : 150, 0.5 : 75, 1 : 0
}),
}],
}}

interpolate() supports multiple range segments as well, which is handy for defining dead zones and other handy tricks. For example, to get a negation relationship at -300 that goes to 0 at -100, then back up to 1 at 0, and then back down to zero at 100 followed by a dead-zone that remains at 0 for everything beyond that, you could do:

value.interpolate({
inputRange: [-300, -100, 0, 100, 101],
outputRange: [300, 0, 1, 0, 0]
});

Which would map like so:

Input | Output
------|-------
-400| 450
-300| 300
-200| 150
-100| 0
-50| 0.5
0| 1
50| 0.5
100| 0
101| 0
200| 0

interpolate() also supports mapping to strings, allowing you to animate colors as well as values with units. For example, if you wanted to animate a rotation you could do:

value.interpolate({
inputRange: [0, 360],
outputRange: ['0deg', '360deg']
});

interpolate() also supports arbitrary easing functions, many of which are already implemented in the Easing module. interpolate() also has configurable behavior for extrapolating the outputRange. You can set the extrapolation by setting the extrapolate, extrapolateLeft, or extrapolateRight options. The default value is extend but you can use clamp to prevent the output value from exceeding outputRange.

Tracking dynamic values

Animated values can also track other values. Set the toValue of an animation to another animated value instead of a plain number. For example, a "Chat Heads" animation like the one used by Messenger on Android could be implemented with a spring() pinned on another animated value, or with timing() and a duration of 0 for rigid tracking. They can also be composed with interpolations:

Animated.spring(follower, { toValue: leader }).start();
Animated.timing(opacity, {
toValue: pan.x.interpolate({
inputRange: [0, 300],
outputRange: [1, 0]
})
}).start();

The leader and follower animated values would be implemented using Animated.ValueXY(). ValueXY is a handy way to deal with 2D interactions, such as panning or dragging. It is a wrapper that contains two Animated.Value instances and some helper functions that call through to them, making ValueXY a drop-in replacement for Value in many cases. It allows us to track both x and y values in the example above.

Tracking gestures

Gestures, like panning or scrolling, and other events can map directly to animated values using Animated.event. This is done with a structured map syntax so that values can be extracted from complex event objects. The first level is an array to allow mapping across multiple args, and that array contains nested objects.

For example, when working with horizontal scrolling gestures, you would do the following in order to map event.nativeEvent.contentOffset.x to scrollX (an Animated.Value):

onScroll={Animated.event(
// scrollX = e.nativeEvent.contentOffset.x
[{ nativeEvent: {
contentOffset: {
x: scrollX
}
}
}]
)}

When using PanResponder, you could use the following code to extract the x and y positions from gestureState.dx and gestureState.dy. We use a null in the first position of the array, as we are only interested in the second argument passed to the PanResponder handler, which is the gestureState.

onPanResponderMove={Animated.event(
[null, // ignore the native event
// extract dx and dy from gestureState
// like 'pan.x = gestureState.dx, pan.y = gestureState.dy'
{dx: pan.x, dy: pan.y}
])}

Responding to the current animation value

You may notice that there is no clear way to read the current value while animating. This is because the value may only be known in the native runtime due to optimizations. If you need to run JavaScript in response to the current value, there are two approaches:

Animated is designed to be fully serializable so that animations can be run in a high performance way, independent of the normal JavaScript event loop. This does influence the API, so keep that in mind when it seems a little trickier to do something compared to a fully synchronous system. Check out Animated.Value.addListener as a way to work around some of these limitations, but use it sparingly since it might have performance implications in the future.

Using the native driver

The Animated API is designed to be serializable. By using the native driver, we send everything about the animation to native before starting the animation, allowing native code to perform the animation on the UI thread without having to go through the bridge on every frame. Once the animation has started, the JS thread can be blocked without affecting the animation.

To use the native driver for normal animations add useNativeDriver: true to the animation config when starting it.

Animated.timing(this.state.animatedValue, {
toValue: 1,
duration: 500,
useNativeDriver: true // <-- Add this
}).start();

Animated values are only compatible with one driver so if you use native driver when starting an animation on a value, make sure every animation on that value also uses the native driver.

The native driver also works with Animated.event. This is especially useful for animations that follow the scroll position as without the native driver, the animation will always run a frame behind the gesture due to the async nature of React Native.

<Animated.ScrollView // <-- Use the Animated ScrollView wrapper
scrollEventThrottle={1} // <-- Use 1 here to make sure no events are ever missed
onScroll={Animated.event(
[
{
nativeEvent: {
contentOffset: { y: this.state.animatedValue }
}
}
],
{ useNativeDriver: true } // <-- Add this
)}>
{content}
</Animated.ScrollView>

You can see the native driver in action by running the RNTester app, then loading the Native Animated Example. You can also take a look at the source code to learn how these examples were produced.

Caveats

Not everything you can do with Animated is currently supported by the native driver. The main limitation is that you can only animate non-layout properties: things like transform and opacity will work, but flexbox and position properties will not. When using Animated.event, it will only work with direct events and not bubbling events. This means it does not work with PanResponder but does work with things like ScrollView#onScroll.

When an animation is running, it can prevent VirtualizedList components from rendering more rows. If you need to run a long or looping animation while the user is scrolling through a list, you can use isInteraction: false in your animation's config to prevent this issue.

Bear in mind

While using transform styles such as rotateY, rotateX, and others ensure the transform style perspective is in place. At this time some animations may not render on Android without it. Example below.

<Animated.View
style={{
transform: [
{ scale: this.state.scale },
{ rotateY: this.state.rotateY },
{ perspective: 1000 } // without this line this Animation will not render on Android while working fine on iOS
]
}}
/>

Additional examples

The RNTester app has various examples of Animated in use:

LayoutAnimation API

LayoutAnimation allows you to globally configure create and update animations that will be used for all views in the next render/layout cycle. This is useful for doing flexbox layout updates without bothering to measure or calculate specific properties in order to animate them directly, and is especially useful when layout changes may affect ancestors, for example a "see more" expansion that also increases the size of the parent and pushes down the row below which would otherwise require explicit coordination between the components in order to animate them all in sync.

Note that although LayoutAnimation is very powerful and can be quite useful, it provides much less control than Animated and other animation libraries, so you may need to use another approach if you can't get LayoutAnimation to do what you want.

Note that in order to get this to work on Android you need to set the following flags via UIManager:

UIManager.setLayoutAnimationEnabledExperimental &&
UIManager.setLayoutAnimationEnabledExperimental(true);

This example uses a preset value, you can customize the animations as you need, see LayoutAnimation.js for more information.

Additional notes

requestAnimationFrame

requestAnimationFrame is a polyfill from the browser that you might be familiar with. It accepts a function as its only argument and calls that function before the next repaint. It is an essential building block for animations that underlies all of the JavaScript-based animation APIs. In general, you shouldn't need to call this yourself - the animation APIs will manage frame updates for you.

setNativeProps

As mentioned in the Direct Manipulation section, setNativeProps allows us to modify properties of native-backed components (components that are actually backed by native views, unlike composite components) directly, without having to setState and re-render the component hierarchy.

We could use this in the Rebound example to update the scale - this might be helpful if the component that we are updating is deeply nested and hasn't been optimized with shouldComponentUpdate.

If you find your animations with dropping frames (performing below 60 frames per second), look into using setNativeProps or shouldComponentUpdate to optimize them. Or you could run the animations on the UI thread rather than the JavaScript thread with the useNativeDriver 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.

Edit this page
Last updated on
- + diff --git a/docs/0.60/animations/index.html b/docs/0.60/animations/index.html index 3b0ba7f6bd4..aa0c67f03eb 100644 --- a/docs/0.60/animations/index.html +++ b/docs/0.60/animations/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Animated.spring(a, {
toValue: 2
}).start();

Interpolation

Each property can be run through an interpolation first. An interpolation maps input ranges to output ranges, typically using a linear interpolation but also supports easing functions. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value.

A mapping to convert a 0-1 range to a 0-100 range would be:

value.interpolate({
inputRange: [0, 1],
outputRange: [0, 100]
});

For example, you may want to think about your Animated.Value as going from 0 to 1, but animate the position from 150px to 0px and the opacity from 0 to 1. This can be done by modifying style from the example above like so:

style={{
opacity: this.state.fadeAnim, // Binds directly
transform: [{
translateY: this.state.fadeAnim.interpolate({
inputRange: [0, 1],
outputRange: [150, 0] // 0 : 150, 0.5 : 75, 1 : 0
}),
}],
}}

interpolate() supports multiple range segments as well, which is handy for defining dead zones and other handy tricks. For example, to get a negation relationship at -300 that goes to 0 at -100, then back up to 1 at 0, and then back down to zero at 100 followed by a dead-zone that remains at 0 for everything beyond that, you could do:

value.interpolate({
inputRange: [-300, -100, 0, 100, 101],
outputRange: [300, 0, 1, 0, 0]
});

Which would map like so:

Input | Output
------|-------
-400| 450
-300| 300
-200| 150
-100| 0
-50| 0.5
0| 1
50| 0.5
100| 0
101| 0
200| 0

interpolate() also supports mapping to strings, allowing you to animate colors as well as values with units. For example, if you wanted to animate a rotation you could do:

value.interpolate({
inputRange: [0, 360],
outputRange: ['0deg', '360deg']
});

interpolate() also supports arbitrary easing functions, many of which are already implemented in the Easing module. interpolate() also has configurable behavior for extrapolating the outputRange. You can set the extrapolation by setting the extrapolate, extrapolateLeft, or extrapolateRight options. The default value is extend but you can use clamp to prevent the output value from exceeding outputRange.

Tracking dynamic values

Animated values can also track other values. Set the toValue of an animation to another animated value instead of a plain number. For example, a "Chat Heads" animation like the one used by Messenger on Android could be implemented with a spring() pinned on another animated value, or with timing() and a duration of 0 for rigid tracking. They can also be composed with interpolations:

Animated.spring(follower, { toValue: leader }).start();
Animated.timing(opacity, {
toValue: pan.x.interpolate({
inputRange: [0, 300],
outputRange: [1, 0]
})
}).start();

The leader and follower animated values would be implemented using Animated.ValueXY(). ValueXY is a handy way to deal with 2D interactions, such as panning or dragging. It is a wrapper that contains two Animated.Value instances and some helper functions that call through to them, making ValueXY a drop-in replacement for Value in many cases. It allows us to track both x and y values in the example above.

Tracking gestures

Gestures, like panning or scrolling, and other events can map directly to animated values using Animated.event. This is done with a structured map syntax so that values can be extracted from complex event objects. The first level is an array to allow mapping across multiple args, and that array contains nested objects.

For example, when working with horizontal scrolling gestures, you would do the following in order to map event.nativeEvent.contentOffset.x to scrollX (an Animated.Value):

onScroll={Animated.event(
// scrollX = e.nativeEvent.contentOffset.x
[{ nativeEvent: {
contentOffset: {
x: scrollX
}
}
}]
)}

When using PanResponder, you could use the following code to extract the x and y positions from gestureState.dx and gestureState.dy. We use a null in the first position of the array, as we are only interested in the second argument passed to the PanResponder handler, which is the gestureState.

onPanResponderMove={Animated.event(
[null, // ignore the native event
// extract dx and dy from gestureState
// like 'pan.x = gestureState.dx, pan.y = gestureState.dy'
{dx: pan.x, dy: pan.y}
])}

Responding to the current animation value

You may notice that there is no clear way to read the current value while animating. This is because the value may only be known in the native runtime due to optimizations. If you need to run JavaScript in response to the current value, there are two approaches:

Animated is designed to be fully serializable so that animations can be run in a high performance way, independent of the normal JavaScript event loop. This does influence the API, so keep that in mind when it seems a little trickier to do something compared to a fully synchronous system. Check out Animated.Value.addListener as a way to work around some of these limitations, but use it sparingly since it might have performance implications in the future.

Using the native driver

The Animated API is designed to be serializable. By using the native driver, we send everything about the animation to native before starting the animation, allowing native code to perform the animation on the UI thread without having to go through the bridge on every frame. Once the animation has started, the JS thread can be blocked without affecting the animation.

To use the native driver for normal animations add useNativeDriver: true to the animation config when starting it.

Animated.timing(this.state.animatedValue, {
toValue: 1,
duration: 500,
useNativeDriver: true // <-- Add this
}).start();

Animated values are only compatible with one driver so if you use native driver when starting an animation on a value, make sure every animation on that value also uses the native driver.

The native driver also works with Animated.event. This is especially useful for animations that follow the scroll position as without the native driver, the animation will always run a frame behind the gesture due to the async nature of React Native.

<Animated.ScrollView // <-- Use the Animated ScrollView wrapper
scrollEventThrottle={1} // <-- Use 1 here to make sure no events are ever missed
onScroll={Animated.event(
[
{
nativeEvent: {
contentOffset: { y: this.state.animatedValue }
}
}
],
{ useNativeDriver: true } // <-- Add this
)}>
{content}
</Animated.ScrollView>

You can see the native driver in action by running the RNTester app, then loading the Native Animated Example. You can also take a look at the source code to learn how these examples were produced.

Caveats

Not everything you can do with Animated is currently supported by the native driver. The main limitation is that you can only animate non-layout properties: things like transform and opacity will work, but flexbox and position properties will not. When using Animated.event, it will only work with direct events and not bubbling events. This means it does not work with PanResponder but does work with things like ScrollView#onScroll.

When an animation is running, it can prevent VirtualizedList components from rendering more rows. If you need to run a long or looping animation while the user is scrolling through a list, you can use isInteraction: false in your animation's config to prevent this issue.

Bear in mind

While using transform styles such as rotateY, rotateX, and others ensure the transform style perspective is in place. At this time some animations may not render on Android without it. Example below.

<Animated.View
style={{
transform: [
{ scale: this.state.scale },
{ rotateY: this.state.rotateY },
{ perspective: 1000 } // without this line this Animation will not render on Android while working fine on iOS
]
}}
/>

Additional examples

The RNTester app has various examples of Animated in use:

LayoutAnimation API

LayoutAnimation allows you to globally configure create and update animations that will be used for all views in the next render/layout cycle. This is useful for doing flexbox layout updates without bothering to measure or calculate specific properties in order to animate them directly, and is especially useful when layout changes may affect ancestors, for example a "see more" expansion that also increases the size of the parent and pushes down the row below which would otherwise require explicit coordination between the components in order to animate them all in sync.

Note that although LayoutAnimation is very powerful and can be quite useful, it provides much less control than Animated and other animation libraries, so you may need to use another approach if you can't get LayoutAnimation to do what you want.

Note that in order to get this to work on Android you need to set the following flags via UIManager:

UIManager.setLayoutAnimationEnabledExperimental &&
UIManager.setLayoutAnimationEnabledExperimental(true);

This example uses a preset value, you can customize the animations as you need, see LayoutAnimation.js for more information.

Additional notes

requestAnimationFrame

requestAnimationFrame is a polyfill from the browser that you might be familiar with. It accepts a function as its only argument and calls that function before the next repaint. It is an essential building block for animations that underlies all of the JavaScript-based animation APIs. In general, you shouldn't need to call this yourself - the animation APIs will manage frame updates for you.

setNativeProps

As mentioned in the Direct Manipulation section, setNativeProps allows us to modify properties of native-backed components (components that are actually backed by native views, unlike composite components) directly, without having to setState and re-render the component hierarchy.

We could use this in the Rebound example to update the scale - this might be helpful if the component that we are updating is deeply nested and hasn't been optimized with shouldComponentUpdate.

If you find your animations with dropping frames (performing below 60 frames per second), look into using setNativeProps or shouldComponentUpdate to optimize them. Or you could run the animations on the UI thread rather than the JavaScript thread with the useNativeDriver 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.

Edit this page
Last updated on
- + diff --git a/docs/0.60/app-extensions.html b/docs/0.60/app-extensions.html index 62cb0081997..9ca07a28966 100644 --- a/docs/0.60/app-extensions.html +++ b/docs/0.60/app-extensions.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

App Extensions

App extensions let you provide custom functionality and content outside of your main app. There are different types of app extensions on iOS, and they are all covered in the App Extension Programming Guide. In this guide, we'll briefly cover how you may take advantage of app extensions on iOS.

Memory use in extensions

As these extensions are loaded outside of the regular app sandbox, it's highly likely that several of these app extensions will be loaded simultaneously. As you might expect, these extensions have small memory usage limits. Keep these in mind when developing your app extensions. It's always highly recommended to test your application on an actual device, and more so when developing app extensions: too frequently, developers find that their extension works fine in the iOS Simulator, only to get user reports that their extension is not loading on actual devices.

We highly recommend that you watch Conrad Kramer's talk on Memory Use in Extensions to learn more about this topic.

Today widget

The memory limit of a Today widget is 16 MB. As it happens, Today widget implementations using React Native may work unreliably because the memory usage tends to be too high. You can tell if your Today widget is exceeding the memory limit if it yields the message 'Unable to Load':

Always make sure to test your app extensions in a real device, but be aware that this may not be sufficient, especially when dealing with Today widgets. Debug-configured builds are more likely to exceed the memory limits, while release-configured builds don't fail right away. We highly recommend that you use Xcode's Instruments to analyze your real world memory usage, as it's very likely that your release-configured build is very close to the 16 MB limit. In situations like these, you can quickly go over the 16 MB limit by performing common operations, such as fetching data from an API.

To experiment with the limits of React Native Today widget implementations, try extending the example project in react-native-today-widget.

Other app extensions

Other types of app extensions have greater memory limits than the Today widget. For instance, Custom Keyboard extensions are limited to 48 MB, and Share extensions are limited to 120 MB. Implementing such app extensions with React Native is more viable. One proof of concept example is react-native-ios-share-extension.

Edit this page
Last updated on
- + diff --git a/docs/0.60/app-extensions/index.html b/docs/0.60/app-extensions/index.html index 62cb0081997..9ca07a28966 100644 --- a/docs/0.60/app-extensions/index.html +++ b/docs/0.60/app-extensions/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

App Extensions

App extensions let you provide custom functionality and content outside of your main app. There are different types of app extensions on iOS, and they are all covered in the App Extension Programming Guide. In this guide, we'll briefly cover how you may take advantage of app extensions on iOS.

Memory use in extensions

As these extensions are loaded outside of the regular app sandbox, it's highly likely that several of these app extensions will be loaded simultaneously. As you might expect, these extensions have small memory usage limits. Keep these in mind when developing your app extensions. It's always highly recommended to test your application on an actual device, and more so when developing app extensions: too frequently, developers find that their extension works fine in the iOS Simulator, only to get user reports that their extension is not loading on actual devices.

We highly recommend that you watch Conrad Kramer's talk on Memory Use in Extensions to learn more about this topic.

Today widget

The memory limit of a Today widget is 16 MB. As it happens, Today widget implementations using React Native may work unreliably because the memory usage tends to be too high. You can tell if your Today widget is exceeding the memory limit if it yields the message 'Unable to Load':

Always make sure to test your app extensions in a real device, but be aware that this may not be sufficient, especially when dealing with Today widgets. Debug-configured builds are more likely to exceed the memory limits, while release-configured builds don't fail right away. We highly recommend that you use Xcode's Instruments to analyze your real world memory usage, as it's very likely that your release-configured build is very close to the 16 MB limit. In situations like these, you can quickly go over the 16 MB limit by performing common operations, such as fetching data from an API.

To experiment with the limits of React Native Today widget implementations, try extending the example project in react-native-today-widget.

Other app extensions

Other types of app extensions have greater memory limits than the Today widget. For instance, Custom Keyboard extensions are limited to 48 MB, and Share extensions are limited to 120 MB. Implementing such app extensions with React Native is more viable. One proof of concept example is react-native-ios-share-extension.

Edit this page
Last updated on
- + diff --git a/docs/0.60/appregistry.html b/docs/0.60/appregistry.html index 268996b31aa..24a6709fbcd 100644 --- a/docs/0.60/appregistry.html +++ b/docs/0.60/appregistry.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

AppRegistry

AppRegistry is the JS entry point to running all React Native apps. App root components should register themselves with AppRegistry.registerComponent, then the native system can load the bundle for the app and then actually run the app when it's ready by invoking AppRegistry.runApplication.

To "stop" an application when a view should be destroyed, call AppRegistry.unmountApplicationComponentAtRootTag with the tag that was passed into runApplication. These should always be used as a pair.

AppRegistry should be required early in the require sequence to make sure the JS execution environment is setup before other modules are required.

Reference

Methods

setWrapperComponentProvider()

static setWrapperComponentProvider(provider)

registerConfig()

static registerConfig(config)

registerComponent()

static registerComponent(appKey, componentProvider, section?)

registerRunnable()

static registerRunnable(appKey, run)

registerSection()

static registerSection(appKey, component)

getAppKeys()

static getAppKeys()

getSectionKeys()

static getSectionKeys()

getSections()

static getSections()

getRunnable()

static getRunnable(appKey)

getRegistry()

static getRegistry()

setComponentProviderInstrumentationHook()

static setComponentProviderInstrumentationHook(hook)

runApplication()

static runApplication(appKey, appParameters)

unmountApplicationComponentAtRootTag()

static unmountApplicationComponentAtRootTag(rootTag)

registerHeadlessTask()

static registerHeadlessTask(taskKey, taskProvider)

Register a headless task. A headless task is a bit of code that runs without a UI. @param taskKey the key associated with this task @param taskProvider a promise returning function that takes some data passed from the native side as the only argument; when the promise is resolved or rejected the native side is notified of this event and it may decide to destroy the JS context.

registerCancellableHeadlessTask()

static registerCancellableHeadlessTask(taskKey, taskProvider, taskCancelProvider)

Register a headless task which can be cancelled. A headless task is a bit of code that runs without a UI. @param taskKey the key associated with this task @param taskProvider a promise returning function that takes some data passed from the native side as the only argument; when the promise is resolved or rejected the native side is notified of this event and it may decide to destroy the JS context. @param taskCancelProvider a void returning function that takes no arguments; when a cancellation is requested, the function being executed by taskProvider should wrap up and return ASAP.

startHeadlessTask()

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

cancelHeadlessTask()

static cancelHeadlessTask(taskId, taskKey)

Only called from native code. Cancels a headless task.

@param taskId the native id for this task instance that was used when startHeadlessTask was called @param taskKey the key for the task that was used when startHeadlessTask was called

Edit this page
Last updated on
- + diff --git a/docs/0.60/appregistry/index.html b/docs/0.60/appregistry/index.html index 268996b31aa..24a6709fbcd 100644 --- a/docs/0.60/appregistry/index.html +++ b/docs/0.60/appregistry/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

AppRegistry

AppRegistry is the JS entry point to running all React Native apps. App root components should register themselves with AppRegistry.registerComponent, then the native system can load the bundle for the app and then actually run the app when it's ready by invoking AppRegistry.runApplication.

To "stop" an application when a view should be destroyed, call AppRegistry.unmountApplicationComponentAtRootTag with the tag that was passed into runApplication. These should always be used as a pair.

AppRegistry should be required early in the require sequence to make sure the JS execution environment is setup before other modules are required.

Reference

Methods

setWrapperComponentProvider()

static setWrapperComponentProvider(provider)

registerConfig()

static registerConfig(config)

registerComponent()

static registerComponent(appKey, componentProvider, section?)

registerRunnable()

static registerRunnable(appKey, run)

registerSection()

static registerSection(appKey, component)

getAppKeys()

static getAppKeys()

getSectionKeys()

static getSectionKeys()

getSections()

static getSections()

getRunnable()

static getRunnable(appKey)

getRegistry()

static getRegistry()

setComponentProviderInstrumentationHook()

static setComponentProviderInstrumentationHook(hook)

runApplication()

static runApplication(appKey, appParameters)

unmountApplicationComponentAtRootTag()

static unmountApplicationComponentAtRootTag(rootTag)

registerHeadlessTask()

static registerHeadlessTask(taskKey, taskProvider)

Register a headless task. A headless task is a bit of code that runs without a UI. @param taskKey the key associated with this task @param taskProvider a promise returning function that takes some data passed from the native side as the only argument; when the promise is resolved or rejected the native side is notified of this event and it may decide to destroy the JS context.

registerCancellableHeadlessTask()

static registerCancellableHeadlessTask(taskKey, taskProvider, taskCancelProvider)

Register a headless task which can be cancelled. A headless task is a bit of code that runs without a UI. @param taskKey the key associated with this task @param taskProvider a promise returning function that takes some data passed from the native side as the only argument; when the promise is resolved or rejected the native side is notified of this event and it may decide to destroy the JS context. @param taskCancelProvider a void returning function that takes no arguments; when a cancellation is requested, the function being executed by taskProvider should wrap up and return ASAP.

startHeadlessTask()

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

cancelHeadlessTask()

static cancelHeadlessTask(taskId, taskKey)

Only called from native code. Cancels a headless task.

@param taskId the native id for this task instance that was used when startHeadlessTask was called @param taskKey the key for the task that was used when startHeadlessTask was called

Edit this page
Last updated on
- + diff --git a/docs/0.60/appstate.html b/docs/0.60/appstate.html index ee21729e586..d7f51adb4da 100644 --- a/docs/0.60/appstate.html +++ b/docs/0.60/appstate.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
render() {
return <Text>Current state is: {this.state.appState}</Text>;
}
}

This example will only ever appear to say "Current state is: active" because the app is only visible to the user when in the active state, and the null state will happen only momentarily.

Reference

Events

change

This even is received when the app state has changed. The listener is called with one of the current app state values.

focus

[Android only] Received when the app gains focus (the user is interacting with the app).

blur

[Android only] Received when the user is not actively interacting with the app. Useful in situations when the user pulls down the notification drawer. AppState won't change but the blur event will get fired.

Methods

addEventListener()

addEventListener(type, handler);

Add a handler to AppState changes by listening to the change event type and providing the handler

removeEventListener()

removeEventListener(type, handler);

Remove a handler by passing the change event type and the handler

Properties

currentState

AppState.currentState;
Edit this page
Last updated on
- + diff --git a/docs/0.60/appstate/index.html b/docs/0.60/appstate/index.html index ee21729e586..d7f51adb4da 100644 --- a/docs/0.60/appstate/index.html +++ b/docs/0.60/appstate/index.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
render() {
return <Text>Current state is: {this.state.appState}</Text>;
}
}

This example will only ever appear to say "Current state is: active" because the app is only visible to the user when in the active state, and the null state will happen only momentarily.

Reference

Events

change

This even is received when the app state has changed. The listener is called with one of the current app state values.

focus

[Android only] Received when the app gains focus (the user is interacting with the app).

blur

[Android only] Received when the user is not actively interacting with the app. Useful in situations when the user pulls down the notification drawer. AppState won't change but the blur event will get fired.

Methods

addEventListener()

addEventListener(type, handler);

Add a handler to AppState changes by listening to the change event type and providing the handler

removeEventListener()

removeEventListener(type, handler);

Remove a handler by passing the change event type and the handler

Properties

currentState

AppState.currentState;
Edit this page
Last updated on
- + diff --git a/docs/0.60/asyncstorage.html b/docs/0.60/asyncstorage.html index 2bcb1b2c65b..c8b3198589d 100644 --- a/docs/0.60/asyncstorage.html +++ b/docs/0.60/asyncstorage.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@
// 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"}}
Edit this page
Last updated on
- + diff --git a/docs/0.60/asyncstorage/index.html b/docs/0.60/asyncstorage/index.html index 2bcb1b2c65b..c8b3198589d 100644 --- a/docs/0.60/asyncstorage/index.html +++ b/docs/0.60/asyncstorage/index.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@
// 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"}}
Edit this page
Last updated on
- + diff --git a/docs/0.60/backandroid.html b/docs/0.60/backandroid.html index af2ff425f1e..6728e1d024b 100644 --- a/docs/0.60/backandroid.html +++ b/docs/0.60/backandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

BackAndroid

Deprecated. Use BackHandler instead.

Methods

Reference

Methods

exitApp()

static exitApp()

addEventListener()

static addEventListener(eventName, handler)

removeEventListener()

static removeEventListener(eventName, handler)
Edit this page
Last updated on
- + diff --git a/docs/0.60/backandroid/index.html b/docs/0.60/backandroid/index.html index af2ff425f1e..6728e1d024b 100644 --- a/docs/0.60/backandroid/index.html +++ b/docs/0.60/backandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

BackAndroid

Deprecated. Use BackHandler instead.

Methods

Reference

Methods

exitApp()

static exitApp()

addEventListener()

static addEventListener(eventName, handler)

removeEventListener()

static removeEventListener(eventName, handler)
Edit this page
Last updated on
- + diff --git a/docs/0.60/backhandler.html b/docs/0.60/backhandler.html index bb5631580ee..58cf1231377 100644 --- a/docs/0.60/backhandler.html +++ b/docs/0.60/backhandler.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
componentWillUnmount() {
this.backHandler.remove();
}

Reference

Methods

addEventListener()

static addEventListener(eventName, handler)

exitApp()

static exitApp()

removeEventListener()

static removeEventListener(eventName, handler)
Edit this page
Last updated on
- + diff --git a/docs/0.60/backhandler/index.html b/docs/0.60/backhandler/index.html index bb5631580ee..58cf1231377 100644 --- a/docs/0.60/backhandler/index.html +++ b/docs/0.60/backhandler/index.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
componentWillUnmount() {
this.backHandler.remove();
}

Reference

Methods

addEventListener()

static addEventListener(eventName, handler)

exitApp()

static exitApp()

removeEventListener()

static removeEventListener(eventName, handler)
Edit this page
Last updated on
- + diff --git a/docs/0.60/building-for-tv.html b/docs/0.60/building-for-tv.html index 63194e97276..b87a98b3398 100644 --- a/docs/0.60/building-for-tv.html +++ b/docs/0.60/building-for-tv.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
componentWillUnmount() {
this._disableTVEventHandler();
}
}
Edit this page
Last updated on
- + diff --git a/docs/0.60/building-for-tv/index.html b/docs/0.60/building-for-tv/index.html index 63194e97276..b87a98b3398 100644 --- a/docs/0.60/building-for-tv/index.html +++ b/docs/0.60/building-for-tv/index.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
componentWillUnmount() {
this._disableTVEventHandler();
}
}
Edit this page
Last updated on
- + diff --git a/docs/0.60/button.html b/docs/0.60/button.html index db35d3adcb4..eceb4b20cd3 100644 --- a/docs/0.60/button.html +++ b/docs/0.60/button.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

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 button using TouchableOpacity or TouchableNativeFeedback. For inspiration, look at the source code for this button component. Or, take a look at the wide variety of button components built by the community.

Example

Reference

Props

onPress

Handler to be called when the user taps the button

TypeRequired
functionYes

title

Text to display inside the button

TypeRequired
stringYes

accessibilityLabel

Text to display for blindness accessibility features

TypeRequired
stringNo

color

Color of the text (iOS), or background color of the button (Android)

TypeRequired
colorNo

disabled

If true, disable all interactions for this component.

TypeRequired
boolNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

nextFocusDown

Designates the next view to receive focus when the user navigates down. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusForward

Designates the next view to receive focus when the user navigates forward. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusLeft

Designates the next view to receive focus when the user navigates left. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusRight

Designates the next view to receive focus when the user navigates right. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusUp

Designates the next view to receive focus when the user navigates up. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

touchSoundDisabled

If true, doesn't play system sound on touch.

TypeRequiredPlatform
booleanNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.60/button/index.html b/docs/0.60/button/index.html index db35d3adcb4..eceb4b20cd3 100644 --- a/docs/0.60/button/index.html +++ b/docs/0.60/button/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

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 button using TouchableOpacity or TouchableNativeFeedback. For inspiration, look at the source code for this button component. Or, take a look at the wide variety of button components built by the community.

Example

Reference

Props

onPress

Handler to be called when the user taps the button

TypeRequired
functionYes

title

Text to display inside the button

TypeRequired
stringYes

accessibilityLabel

Text to display for blindness accessibility features

TypeRequired
stringNo

color

Color of the text (iOS), or background color of the button (Android)

TypeRequired
colorNo

disabled

If true, disable all interactions for this component.

TypeRequired
boolNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

nextFocusDown

Designates the next view to receive focus when the user navigates down. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusForward

Designates the next view to receive focus when the user navigates forward. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusLeft

Designates the next view to receive focus when the user navigates left. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusRight

Designates the next view to receive focus when the user navigates right. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusUp

Designates the next view to receive focus when the user navigates up. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

touchSoundDisabled

If true, doesn't play system sound on touch.

TypeRequiredPlatform
booleanNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.60/cameraroll.html b/docs/0.60/cameraroll.html index fbac655b105..de67c0a6994 100644 --- a/docs/0.60/cameraroll.html +++ b/docs/0.60/cameraroll.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

🚧 CameraRoll

Deprecated. Use @react-native-community/cameraroll instead.

CameraRoll provides access to the local camera roll or photo library.

On iOS, the CameraRoll API requires the RCTCameraRoll library to be linked. You can refer to Linking Libraries (iOS) to learn more.

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 app will use this data. This key will appear as Privacy - Photo Library Usage Description in Xcode.

If you are targeting devices running iOS 11 or later, you will also need to add the NSPhotoLibraryAddUsageDescription key in your Info.plist. Use this key to define a string that describes how your app will use this data. By adding this key to your Info.plist, you will be able to request write-only access permission from the user. If you try to save to the camera roll without this permission, your app will exit.

Reference

Methods

saveToCameraRoll()

CameraRoll.saveToCameraRoll(tag, [type]);

Saves the photo or video to the camera roll or photo library.

On Android, the tag must be a local image or video URI, such as "file:///sdcard/img.png".

On iOS, the tag can be any image URI (including local, remote asset-library and base64 data URIs) 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.

Parameters:

NameTypeRequiredDescription
tagstringYesSee above.
typeenum('photo', 'video')NoOverrides automatic detection based on the file extension.

getPhotos()

CameraRoll.getPhotos(params);

Returns a Promise with photo identifier objects from the local camera roll of the device matching shape defined by getPhotosReturnChecker.

Parameters:

NameTypeRequiredDescription
paramsobjectYesExpects a params with the shape described below.
  • 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 matches page_info { end_cursor } returned from a previous call to getPhotos.
  • groupTypes : {string} : Specifies which group types to filter the results to. Valid values are:
    • Album
    • All
    • Event
    • Faces
    • Library
    • PhotoStream
    • SavedPhotos // 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:
    • All
    • Videos
    • Photos // default
  • mimeTypes : {Array} : 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 objects
    • node: {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}
        • playableDuration: {number}
      • 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: {string}
    • end_cursor: {string}

Example

Loading images:

_handleButtonPress = () => {
CameraRoll.getPhotos({
first: 20,
assetType: 'Photos',
})
.then(r => {
this.setState({ photos: r.edges });
})
.catch((err) => {
//Error Loading Images
});
};
render() {
return (
<View>
<Button title="Load Images" onPress={this._handleButtonPress} />
<ScrollView>
{this.state.photos.map((p, i) => {
return (
<Image
key={i}
style={{
width: 300,
height: 100,
}}
source={{ uri: p.node.image.uri }}
/>
);
})}
</ScrollView>
</View>
);
}
Edit this page
Last updated on
- + diff --git a/docs/0.60/cameraroll/index.html b/docs/0.60/cameraroll/index.html index fbac655b105..de67c0a6994 100644 --- a/docs/0.60/cameraroll/index.html +++ b/docs/0.60/cameraroll/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

🚧 CameraRoll

Deprecated. Use @react-native-community/cameraroll instead.

CameraRoll provides access to the local camera roll or photo library.

On iOS, the CameraRoll API requires the RCTCameraRoll library to be linked. You can refer to Linking Libraries (iOS) to learn more.

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 app will use this data. This key will appear as Privacy - Photo Library Usage Description in Xcode.

If you are targeting devices running iOS 11 or later, you will also need to add the NSPhotoLibraryAddUsageDescription key in your Info.plist. Use this key to define a string that describes how your app will use this data. By adding this key to your Info.plist, you will be able to request write-only access permission from the user. If you try to save to the camera roll without this permission, your app will exit.

Reference

Methods

saveToCameraRoll()

CameraRoll.saveToCameraRoll(tag, [type]);

Saves the photo or video to the camera roll or photo library.

On Android, the tag must be a local image or video URI, such as "file:///sdcard/img.png".

On iOS, the tag can be any image URI (including local, remote asset-library and base64 data URIs) 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.

Parameters:

NameTypeRequiredDescription
tagstringYesSee above.
typeenum('photo', 'video')NoOverrides automatic detection based on the file extension.

getPhotos()

CameraRoll.getPhotos(params);

Returns a Promise with photo identifier objects from the local camera roll of the device matching shape defined by getPhotosReturnChecker.

Parameters:

NameTypeRequiredDescription
paramsobjectYesExpects a params with the shape described below.
  • 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 matches page_info { end_cursor } returned from a previous call to getPhotos.
  • groupTypes : {string} : Specifies which group types to filter the results to. Valid values are:
    • Album
    • All
    • Event
    • Faces
    • Library
    • PhotoStream
    • SavedPhotos // 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:
    • All
    • Videos
    • Photos // default
  • mimeTypes : {Array} : 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 objects
    • node: {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}
        • playableDuration: {number}
      • 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: {string}
    • end_cursor: {string}

Example

Loading images:

_handleButtonPress = () => {
CameraRoll.getPhotos({
first: 20,
assetType: 'Photos',
})
.then(r => {
this.setState({ photos: r.edges });
})
.catch((err) => {
//Error Loading Images
});
};
render() {
return (
<View>
<Button title="Load Images" onPress={this._handleButtonPress} />
<ScrollView>
{this.state.photos.map((p, i) => {
return (
<Image
key={i}
style={{
width: 300,
height: 100,
}}
source={{ uri: p.node.image.uri }}
/>
);
})}
</ScrollView>
</View>
);
}
Edit this page
Last updated on
- + diff --git a/docs/0.60/checkbox.html b/docs/0.60/checkbox.html index 5d5ea74b8ee..adf411bf015 100644 --- a/docs/0.60/checkbox.html +++ b/docs/0.60/checkbox.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

CheckBox

Renders a boolean input (Android only).

This is a controlled component that requires an onValueChange callback that updates the value prop in order for the component to reflect user actions. If the value prop is not updated, the component will continue to render the supplied value prop instead of the expected result of any user actions.

@keyword checkbox @keyword toggle

Props

Reference

Props

disabled

If true the user won't be able to toggle the checkbox. Default value is false.

TypeRequired
boolNo

onChange

Used in case the props change removes the component.

TypeRequired
functionNo

onValueChange

Invoked with the new value when the value changes.

TypeRequired
functionNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

value

The value of the checkbox. If true the checkbox will be turned on. Default value is false.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/checkbox/index.html b/docs/0.60/checkbox/index.html index 5d5ea74b8ee..adf411bf015 100644 --- a/docs/0.60/checkbox/index.html +++ b/docs/0.60/checkbox/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

CheckBox

Renders a boolean input (Android only).

This is a controlled component that requires an onValueChange callback that updates the value prop in order for the component to reflect user actions. If the value prop is not updated, the component will continue to render the supplied value prop instead of the expected result of any user actions.

@keyword checkbox @keyword toggle

Props

Reference

Props

disabled

If true the user won't be able to toggle the checkbox. Default value is false.

TypeRequired
boolNo

onChange

Used in case the props change removes the component.

TypeRequired
functionNo

onValueChange

Invoked with the new value when the value changes.

TypeRequired
functionNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

value

The value of the checkbox. If true the checkbox will be turned on. Default value is false.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/clipboard.html b/docs/0.60/clipboard.html index d562d6d49ac..a7b0f9598e5 100644 --- a/docs/0.60/clipboard.html +++ b/docs/0.60/clipboard.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Clipboard

Clipboard gives you an interface for setting and getting content from Clipboard on both Android and iOS

Reference

Methods

getString()

static getString()

Get content of string type, this method returns a Promise, so you can use following code to get clipboard content

async _getContent() {
var content = await Clipboard.getString();
}

setString()

static setString(content)

Set content of string type. You can use following code to set clipboard content

_setContent() {
Clipboard.setString('hello world');
}

@param the content to be stored in the clipboard.

Edit this page
Last updated on
- + diff --git a/docs/0.60/clipboard/index.html b/docs/0.60/clipboard/index.html index d562d6d49ac..a7b0f9598e5 100644 --- a/docs/0.60/clipboard/index.html +++ b/docs/0.60/clipboard/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Clipboard

Clipboard gives you an interface for setting and getting content from Clipboard on both Android and iOS

Reference

Methods

getString()

static getString()

Get content of string type, this method returns a Promise, so you can use following code to get clipboard content

async _getContent() {
var content = await Clipboard.getString();
}

setString()

static setString(content)

Set content of string type. You can use following code to set clipboard content

_setContent() {
Clipboard.setString('hello world');
}

@param the content to be stored in the clipboard.

Edit this page
Last updated on
- + diff --git a/docs/0.60/colors.html b/docs/0.60/colors.html index c8a481c0b4b..4be9898aab6 100644 --- a/docs/0.60/colors.html +++ b/docs/0.60/colors.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

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:

  • #f0f8ff aliceblue (#f0f8ff)
  • #faebd7 antiquewhite (#faebd7)
  • #00ffff aqua (#00ffff)
  • #7fffd4 aquamarine (#7fffd4)
  • #f0ffff azure (#f0ffff)
  • #f5f5dc beige (#f5f5dc)
  • #ffe4c4 bisque (#ffe4c4)
  • #000000 black (#000000)
  • #ffebcd blanchedalmond (#ffebcd)
  • #0000ff blue (#0000ff)
  • #8a2be2 blueviolet (#8a2be2)
  • #a52a2a brown (#a52a2a)
  • #deb887 burlywood (#deb887)
  • #5f9ea0 cadetblue (#5f9ea0)
  • #7fff00 chartreuse (#7fff00)
  • #d2691e chocolate (#d2691e)
  • #ff7f50 coral (#ff7f50)
  • #6495ed cornflowerblue (#6495ed)
  • #fff8dc cornsilk (#fff8dc)
  • #dc143c crimson (#dc143c)
  • #00ffff cyan (#00ffff)
  • #00008b darkblue (#00008b)
  • #008b8b darkcyan (#008b8b)
  • #b8860b darkgoldenrod (#b8860b)
  • #a9a9a9 darkgray (#a9a9a9)
  • #006400 darkgreen (#006400)
  • #a9a9a9 darkgrey (#a9a9a9)
  • #bdb76b darkkhaki (#bdb76b)
  • #8b008b darkmagenta (#8b008b)
  • #556b2f darkolivegreen (#556b2f)
  • #ff8c00 darkorange (#ff8c00)
  • #9932cc darkorchid (#9932cc)
  • #8b0000 darkred (#8b0000)
  • #e9967a darksalmon (#e9967a)
  • #8fbc8f darkseagreen (#8fbc8f)
  • #483d8b darkslateblue (#483d8b)
  • #2f4f4f darkslategrey (#2f4f4f)
  • #00ced1 darkturquoise (#00ced1)
  • #9400d3 darkviolet (#9400d3)
  • #ff1493 deeppink (#ff1493)
  • #00bfff deepskyblue (#00bfff)
  • #696969 dimgray (#696969)
  • #696969 dimgrey (#696969)
  • #1e90ff dodgerblue (#1e90ff)
  • #b22222 firebrick (#b22222)
  • #fffaf0 floralwhite (#fffaf0)
  • #228b22 forestgreen (#228b22)
  • #ff00ff fuchsia (#ff00ff)
  • #dcdcdc gainsboro (#dcdcdc)
  • #f8f8ff ghostwhite (#f8f8ff)
  • #ffd700 gold (#ffd700)
  • #daa520 goldenrod (#daa520)
  • #808080 gray (#808080)
  • #008000 green (#008000)
  • #adff2f greenyellow (#adff2f)
  • #808080 grey (#808080)
  • #f0fff0 honeydew (#f0fff0)
  • #ff69b4 hotpink (#ff69b4)
  • #cd5c5c indianred (#cd5c5c)
  • #4b0082 indigo (#4b0082)
  • #fffff0 ivory (#fffff0)
  • #f0e68c khaki (#f0e68c)
  • #e6e6fa lavender (#e6e6fa)
  • #fff0f5 lavenderblush (#fff0f5)
  • #7cfc00 lawngreen (#7cfc00)
  • #fffacd lemonchiffon (#fffacd)
  • #add8e6 lightblue (#add8e6)
  • #f08080 lightcoral (#f08080)
  • #e0ffff lightcyan (#e0ffff)
  • #fafad2 lightgoldenrodyellow (#fafad2)
  • #d3d3d3 lightgray (#d3d3d3)
  • #90ee90 lightgreen (#90ee90)
  • #d3d3d3 lightgrey (#d3d3d3)
  • #ffb6c1 lightpink (#ffb6c1)
  • #ffa07a lightsalmon (#ffa07a)
  • #20b2aa lightseagreen (#20b2aa)
  • #87cefa lightskyblue (#87cefa)
  • #778899 lightslategrey (#778899)
  • #b0c4de lightsteelblue (#b0c4de)
  • #ffffe0 lightyellow (#ffffe0)
  • #00ff00 lime (#00ff00)
  • #32cd32 limegreen (#32cd32)
  • #faf0e6 linen (#faf0e6)
  • #ff00ff magenta (#ff00ff)
  • #800000 maroon (#800000)
  • #66cdaa mediumaquamarine (#66cdaa)
  • #0000cd mediumblue (#0000cd)
  • #ba55d3 mediumorchid (#ba55d3)
  • #9370db mediumpurple (#9370db)
  • #3cb371 mediumseagreen (#3cb371)
  • #7b68ee mediumslateblue (#7b68ee)
  • #00fa9a mediumspringgreen (#00fa9a)
  • #48d1cc mediumturquoise (#48d1cc)
  • #c71585 mediumvioletred (#c71585)
  • #191970 midnightblue (#191970)
  • #f5fffa mintcream (#f5fffa)
  • #ffe4e1 mistyrose (#ffe4e1)
  • #ffe4b5 moccasin (#ffe4b5)
  • #ffdead navajowhite (#ffdead)
  • #000080 navy (#000080)
  • #fdf5e6 oldlace (#fdf5e6)
  • #808000 olive (#808000)
  • #6b8e23 olivedrab (#6b8e23)
  • #ffa500 orange (#ffa500)
  • #ff4500 orangered (#ff4500)
  • #da70d6 orchid (#da70d6)
  • #eee8aa palegoldenrod (#eee8aa)
  • #98fb98 palegreen (#98fb98)
  • #afeeee paleturquoise (#afeeee)
  • #db7093 palevioletred (#db7093)
  • #ffefd5 papayawhip (#ffefd5)
  • #ffdab9 peachpuff (#ffdab9)
  • #cd853f peru (#cd853f)
  • #ffc0cb pink (#ffc0cb)
  • #dda0dd plum (#dda0dd)
  • #b0e0e6 powderblue (#b0e0e6)
  • #800080 purple (#800080)
  • #663399 rebeccapurple (#663399)
  • #ff0000 red (#ff0000)
  • #bc8f8f rosybrown (#bc8f8f)
  • #4169e1 royalblue (#4169e1)
  • #8b4513 saddlebrown (#8b4513)
  • #fa8072 salmon (#fa8072)
  • #f4a460 sandybrown (#f4a460)
  • #2e8b57 seagreen (#2e8b57)
  • #fff5ee seashell (#fff5ee)
  • #a0522d sienna (#a0522d)
  • #c0c0c0 silver (#c0c0c0)
  • #87ceeb skyblue (#87ceeb)
  • #6a5acd slateblue (#6a5acd)
  • #708090 slategray (#708090)
  • #fffafa snow (#fffafa)
  • #00ff7f springgreen (#00ff7f)
  • #4682b4 steelblue (#4682b4)
  • #d2b48c tan (#d2b48c)
  • #008080 teal (#008080)
  • #d8bfd8 thistle (#d8bfd8)
  • #ff6347 tomato (#ff6347)
  • #40e0d0 turquoise (#40e0d0)
  • #ee82ee violet (#ee82ee)
  • #f5deb3 wheat (#f5deb3)
  • #ffffff white (#ffffff)
  • #f5f5f5 whitesmoke (#f5f5f5)
  • #ffff00 yellow (#ffff00)
  • #9acd32 yellowgreen (#9acd32)
Edit this page
Last updated on
- + diff --git a/docs/0.60/colors/index.html b/docs/0.60/colors/index.html index c8a481c0b4b..4be9898aab6 100644 --- a/docs/0.60/colors/index.html +++ b/docs/0.60/colors/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

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:

  • #f0f8ff aliceblue (#f0f8ff)
  • #faebd7 antiquewhite (#faebd7)
  • #00ffff aqua (#00ffff)
  • #7fffd4 aquamarine (#7fffd4)
  • #f0ffff azure (#f0ffff)
  • #f5f5dc beige (#f5f5dc)
  • #ffe4c4 bisque (#ffe4c4)
  • #000000 black (#000000)
  • #ffebcd blanchedalmond (#ffebcd)
  • #0000ff blue (#0000ff)
  • #8a2be2 blueviolet (#8a2be2)
  • #a52a2a brown (#a52a2a)
  • #deb887 burlywood (#deb887)
  • #5f9ea0 cadetblue (#5f9ea0)
  • #7fff00 chartreuse (#7fff00)
  • #d2691e chocolate (#d2691e)
  • #ff7f50 coral (#ff7f50)
  • #6495ed cornflowerblue (#6495ed)
  • #fff8dc cornsilk (#fff8dc)
  • #dc143c crimson (#dc143c)
  • #00ffff cyan (#00ffff)
  • #00008b darkblue (#00008b)
  • #008b8b darkcyan (#008b8b)
  • #b8860b darkgoldenrod (#b8860b)
  • #a9a9a9 darkgray (#a9a9a9)
  • #006400 darkgreen (#006400)
  • #a9a9a9 darkgrey (#a9a9a9)
  • #bdb76b darkkhaki (#bdb76b)
  • #8b008b darkmagenta (#8b008b)
  • #556b2f darkolivegreen (#556b2f)
  • #ff8c00 darkorange (#ff8c00)
  • #9932cc darkorchid (#9932cc)
  • #8b0000 darkred (#8b0000)
  • #e9967a darksalmon (#e9967a)
  • #8fbc8f darkseagreen (#8fbc8f)
  • #483d8b darkslateblue (#483d8b)
  • #2f4f4f darkslategrey (#2f4f4f)
  • #00ced1 darkturquoise (#00ced1)
  • #9400d3 darkviolet (#9400d3)
  • #ff1493 deeppink (#ff1493)
  • #00bfff deepskyblue (#00bfff)
  • #696969 dimgray (#696969)
  • #696969 dimgrey (#696969)
  • #1e90ff dodgerblue (#1e90ff)
  • #b22222 firebrick (#b22222)
  • #fffaf0 floralwhite (#fffaf0)
  • #228b22 forestgreen (#228b22)
  • #ff00ff fuchsia (#ff00ff)
  • #dcdcdc gainsboro (#dcdcdc)
  • #f8f8ff ghostwhite (#f8f8ff)
  • #ffd700 gold (#ffd700)
  • #daa520 goldenrod (#daa520)
  • #808080 gray (#808080)
  • #008000 green (#008000)
  • #adff2f greenyellow (#adff2f)
  • #808080 grey (#808080)
  • #f0fff0 honeydew (#f0fff0)
  • #ff69b4 hotpink (#ff69b4)
  • #cd5c5c indianred (#cd5c5c)
  • #4b0082 indigo (#4b0082)
  • #fffff0 ivory (#fffff0)
  • #f0e68c khaki (#f0e68c)
  • #e6e6fa lavender (#e6e6fa)
  • #fff0f5 lavenderblush (#fff0f5)
  • #7cfc00 lawngreen (#7cfc00)
  • #fffacd lemonchiffon (#fffacd)
  • #add8e6 lightblue (#add8e6)
  • #f08080 lightcoral (#f08080)
  • #e0ffff lightcyan (#e0ffff)
  • #fafad2 lightgoldenrodyellow (#fafad2)
  • #d3d3d3 lightgray (#d3d3d3)
  • #90ee90 lightgreen (#90ee90)
  • #d3d3d3 lightgrey (#d3d3d3)
  • #ffb6c1 lightpink (#ffb6c1)
  • #ffa07a lightsalmon (#ffa07a)
  • #20b2aa lightseagreen (#20b2aa)
  • #87cefa lightskyblue (#87cefa)
  • #778899 lightslategrey (#778899)
  • #b0c4de lightsteelblue (#b0c4de)
  • #ffffe0 lightyellow (#ffffe0)
  • #00ff00 lime (#00ff00)
  • #32cd32 limegreen (#32cd32)
  • #faf0e6 linen (#faf0e6)
  • #ff00ff magenta (#ff00ff)
  • #800000 maroon (#800000)
  • #66cdaa mediumaquamarine (#66cdaa)
  • #0000cd mediumblue (#0000cd)
  • #ba55d3 mediumorchid (#ba55d3)
  • #9370db mediumpurple (#9370db)
  • #3cb371 mediumseagreen (#3cb371)
  • #7b68ee mediumslateblue (#7b68ee)
  • #00fa9a mediumspringgreen (#00fa9a)
  • #48d1cc mediumturquoise (#48d1cc)
  • #c71585 mediumvioletred (#c71585)
  • #191970 midnightblue (#191970)
  • #f5fffa mintcream (#f5fffa)
  • #ffe4e1 mistyrose (#ffe4e1)
  • #ffe4b5 moccasin (#ffe4b5)
  • #ffdead navajowhite (#ffdead)
  • #000080 navy (#000080)
  • #fdf5e6 oldlace (#fdf5e6)
  • #808000 olive (#808000)
  • #6b8e23 olivedrab (#6b8e23)
  • #ffa500 orange (#ffa500)
  • #ff4500 orangered (#ff4500)
  • #da70d6 orchid (#da70d6)
  • #eee8aa palegoldenrod (#eee8aa)
  • #98fb98 palegreen (#98fb98)
  • #afeeee paleturquoise (#afeeee)
  • #db7093 palevioletred (#db7093)
  • #ffefd5 papayawhip (#ffefd5)
  • #ffdab9 peachpuff (#ffdab9)
  • #cd853f peru (#cd853f)
  • #ffc0cb pink (#ffc0cb)
  • #dda0dd plum (#dda0dd)
  • #b0e0e6 powderblue (#b0e0e6)
  • #800080 purple (#800080)
  • #663399 rebeccapurple (#663399)
  • #ff0000 red (#ff0000)
  • #bc8f8f rosybrown (#bc8f8f)
  • #4169e1 royalblue (#4169e1)
  • #8b4513 saddlebrown (#8b4513)
  • #fa8072 salmon (#fa8072)
  • #f4a460 sandybrown (#f4a460)
  • #2e8b57 seagreen (#2e8b57)
  • #fff5ee seashell (#fff5ee)
  • #a0522d sienna (#a0522d)
  • #c0c0c0 silver (#c0c0c0)
  • #87ceeb skyblue (#87ceeb)
  • #6a5acd slateblue (#6a5acd)
  • #708090 slategray (#708090)
  • #fffafa snow (#fffafa)
  • #00ff7f springgreen (#00ff7f)
  • #4682b4 steelblue (#4682b4)
  • #d2b48c tan (#d2b48c)
  • #008080 teal (#008080)
  • #d8bfd8 thistle (#d8bfd8)
  • #ff6347 tomato (#ff6347)
  • #40e0d0 turquoise (#40e0d0)
  • #ee82ee violet (#ee82ee)
  • #f5deb3 wheat (#f5deb3)
  • #ffffff white (#ffffff)
  • #f5f5f5 whitesmoke (#f5f5f5)
  • #ffff00 yellow (#ffff00)
  • #9acd32 yellowgreen (#9acd32)
Edit this page
Last updated on
- + diff --git a/docs/0.60/communication-android.html b/docs/0.60/communication-android.html index bf3f07dbf0d..d2e6c53ccd2 100644 --- a/docs/0.60/communication-android.html +++ b/docs/0.60/communication-android.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
mReactRootView.setAppProperties(updatedProps);

It is fine to update properties anytime. However, updates have to be performed on the main thread. You use the getter on any thread.

There is no way to update only a few properties at a time. We suggest that you build it into your own wrapper instead.

Note: Currently, JS function componentWillUpdateProps of the top level RN component will not be called after a prop update. However, you can access the new props in componentDidMount function.

Passing properties from React Native to native

The problem exposing properties of native components is covered in detail in this article. In short, properties that are to be reflected in JavaScript needs to be exposed as setter method annotated with @ReactProp, then use them in React Native as if the component was an ordinary React Native component.

Limits of properties

The main drawback of cross-language properties is that they do not support callbacks, which would allow us to handle bottom-up data bindings. Imagine you have a small RN view that you want to be removed from the native parent view as a result of a JS action. There is no way to do that with props, as the information would need to go bottom-up.

Although we have a flavor of cross-language callbacks (described here), these callbacks are not always the thing we need. The main problem is that they are not intended to be passed as properties. Rather, this mechanism allows us to trigger a native action from JS, and handle the result of that action in JS.

Other ways of cross-language interaction (events and native modules)

As stated in the previous chapter, using properties comes with some limitations. Sometimes properties are not enough to drive the logic of our app and we need a solution that gives more flexibility. This chapter covers other communication techniques available in React Native. They can be used for internal communication (between JS and native layers in RN) as well as for external communication (between RN and the 'pure native' part of your app).

React Native enables you to perform cross-language function calls. You can execute custom native code from JS and vice versa. Unfortunately, depending on the side we are working on, we achieve the same goal in different ways. For native - we use events mechanism to schedule an execution of a handler function in JS, while for React Native we directly call methods exported by native modules.

Calling React Native functions from native (events)

Events are described in detail in this article. Note that using events gives us no guarantees about execution time, as the event is handled on a separate thread.

Events are powerful, because they allow us to change React Native components without needing a reference to them. However, there are some pitfalls that you can fall into while using them:

Calling native functions from React Native (native modules)

Native modules are Java classes that are available in JS. Typically one instance of each module is created per JS bridge. They can export arbitrary functions and constants to React Native. They have been covered in detail in this article.

Warning: All native modules share the same namespace. Watch out for name collisions when creating new ones.

Edit this page
Last updated on
- + diff --git a/docs/0.60/communication-android/index.html b/docs/0.60/communication-android/index.html index bf3f07dbf0d..d2e6c53ccd2 100644 --- a/docs/0.60/communication-android/index.html +++ b/docs/0.60/communication-android/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
mReactRootView.setAppProperties(updatedProps);

It is fine to update properties anytime. However, updates have to be performed on the main thread. You use the getter on any thread.

There is no way to update only a few properties at a time. We suggest that you build it into your own wrapper instead.

Note: Currently, JS function componentWillUpdateProps of the top level RN component will not be called after a prop update. However, you can access the new props in componentDidMount function.

Passing properties from React Native to native

The problem exposing properties of native components is covered in detail in this article. In short, properties that are to be reflected in JavaScript needs to be exposed as setter method annotated with @ReactProp, then use them in React Native as if the component was an ordinary React Native component.

Limits of properties

The main drawback of cross-language properties is that they do not support callbacks, which would allow us to handle bottom-up data bindings. Imagine you have a small RN view that you want to be removed from the native parent view as a result of a JS action. There is no way to do that with props, as the information would need to go bottom-up.

Although we have a flavor of cross-language callbacks (described here), these callbacks are not always the thing we need. The main problem is that they are not intended to be passed as properties. Rather, this mechanism allows us to trigger a native action from JS, and handle the result of that action in JS.

Other ways of cross-language interaction (events and native modules)

As stated in the previous chapter, using properties comes with some limitations. Sometimes properties are not enough to drive the logic of our app and we need a solution that gives more flexibility. This chapter covers other communication techniques available in React Native. They can be used for internal communication (between JS and native layers in RN) as well as for external communication (between RN and the 'pure native' part of your app).

React Native enables you to perform cross-language function calls. You can execute custom native code from JS and vice versa. Unfortunately, depending on the side we are working on, we achieve the same goal in different ways. For native - we use events mechanism to schedule an execution of a handler function in JS, while for React Native we directly call methods exported by native modules.

Calling React Native functions from native (events)

Events are described in detail in this article. Note that using events gives us no guarantees about execution time, as the event is handled on a separate thread.

Events are powerful, because they allow us to change React Native components without needing a reference to them. However, there are some pitfalls that you can fall into while using them:

Calling native functions from React Native (native modules)

Native modules are Java classes that are available in JS. Typically one instance of each module is created per JS bridge. They can export arbitrary functions and constants to React Native. They have been covered in detail in this article.

Warning: All native modules share the same namespace. Watch out for name collisions when creating new ones.

Edit this page
Last updated on
- + diff --git a/docs/0.60/communication-ios.html b/docs/0.60/communication-ios.html index 7e0181dd5c7..b03642f3f05 100644 --- a/docs/0.60/communication-ios.html +++ b/docs/0.60/communication-ios.html @@ -19,7 +19,7 @@ - + @@ -44,7 +44,7 @@
rootView.frame = newFrame;
}

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 example 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 separate 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's hidden property). Then change its visibility in the delegate method.

Edit this page
Last updated on
- + diff --git a/docs/0.60/communication-ios/index.html b/docs/0.60/communication-ios/index.html index 7e0181dd5c7..b03642f3f05 100644 --- a/docs/0.60/communication-ios/index.html +++ b/docs/0.60/communication-ios/index.html @@ -19,7 +19,7 @@ - + @@ -44,7 +44,7 @@
rootView.frame = newFrame;
}

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 example 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 separate 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's hidden property). Then change its visibility in the delegate method.

Edit this page
Last updated on
- + diff --git a/docs/0.60/components-and-apis.html b/docs/0.60/components-and-apis.html index 701d8f18fd9..d7b1361da9b 100644 --- a/docs/0.60/components-and-apis.html +++ b/docs/0.60/components-and-apis.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Components and APIs

React Native provides a number of Core 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.

Text

A component for displaying text.

Image

A component for displaying images.

TextInput

A component for inputting text into the app via a keyboard.

ScrollView

Provides a scrolling container that can host multiple components and views.

StyleSheet

Provides an abstraction layer similar to CSS stylesheets.

User Interface

Render common user interface controls on any platform using the following components. For platform specific components, keep reading.

Button

A basic button component for handling touches that should render nicely on any platform.

Picker

Renders the native picker component on Android and iOS.

Slider

A component used to select a single value from a range of values.

Switch

Renders a boolean input.

List Views

Unlike the more generic ScrollView, the following list view components only render elements that are currently showing on the screen. This makes them a great choice for displaying long lists of data.

FlatList

A component for rendering performant scrollable lists.

SectionList

Like FlatList, but for sectioned lists.

iOS Components and APIs

Many of the following components provide wrappers for commonly used UIKit classes.

ActionSheetIOS

API to display an iOS action sheet or share sheet.

AlertIOS

Create an iOS alert dialog with a message or create a prompt for user input.

DatePickerIOS

Renders a date/time picker (selector) on iOS.

ImagePickerIOS

Renders a image picker on iOS.

ProgressViewIOS

Renders a UIProgressView on iOS.

PushNotificationIOS

Handle push notifications for your app, including permission handling and icon badge number.

SegmentedControlIOS

Renders a UISegmentedControl on iOS.

Android Components and APIs

Many of the following components provide wrappers for commonly used Android classes.

BackHandler

Detect hardware button presses for back navigation.

DatePickerAndroid

Opens the standard Android date picker dialog.

DrawerLayoutAndroid

Renders a DrawerLayout on Android.

PermissionsAndroid

Provides access to the permissions model introduced in Android M.

ProgressBarAndroid

Renders a ProgressBar on Android.

TimePickerAndroid

Opens the standard Android time picker dialog.

ToastAndroid

Create an Android Toast alert.

ToolbarAndroid

Renders a Toolbar on Android.

ViewPagerAndroid

Container that allows to flip left and right between child views.

Others

These components may come in handy for certain applications. For an exhaustive list of components and APIs, check out the sidebar to the left.

ActivityIndicator

Displays a circular loading indicator.

Alert

Launches an alert dialog with the specified title and message.

Animated

A library for creating fluid, powerful animations that are easy to build and maintain.

Clipboard

Provides an interface for setting and getting content from the clipboard on both Android and iOS.

Dimensions

Provides an interface for getting device dimensions.

KeyboardAvoidingView

Provides a view that moves out of the way of the virtual keyboard automatically.

Linking

Provides a general interface to interact with both incoming and outgoing app links.

Modal

Provides a simple way to present content above an enclosing view.

PixelRatio

Provides access to the device pixel density.

RefreshControl

This component is used inside a ScrollView to add pull to refresh functionality.

StatusBar

Component to control the app status bar.

Edit this page
Last updated on
- + diff --git a/docs/0.60/components-and-apis/index.html b/docs/0.60/components-and-apis/index.html index 701d8f18fd9..d7b1361da9b 100644 --- a/docs/0.60/components-and-apis/index.html +++ b/docs/0.60/components-and-apis/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Components and APIs

React Native provides a number of Core 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.

Text

A component for displaying text.

Image

A component for displaying images.

TextInput

A component for inputting text into the app via a keyboard.

ScrollView

Provides a scrolling container that can host multiple components and views.

StyleSheet

Provides an abstraction layer similar to CSS stylesheets.

User Interface

Render common user interface controls on any platform using the following components. For platform specific components, keep reading.

Button

A basic button component for handling touches that should render nicely on any platform.

Picker

Renders the native picker component on Android and iOS.

Slider

A component used to select a single value from a range of values.

Switch

Renders a boolean input.

List Views

Unlike the more generic ScrollView, the following list view components only render elements that are currently showing on the screen. This makes them a great choice for displaying long lists of data.

FlatList

A component for rendering performant scrollable lists.

SectionList

Like FlatList, but for sectioned lists.

iOS Components and APIs

Many of the following components provide wrappers for commonly used UIKit classes.

ActionSheetIOS

API to display an iOS action sheet or share sheet.

AlertIOS

Create an iOS alert dialog with a message or create a prompt for user input.

DatePickerIOS

Renders a date/time picker (selector) on iOS.

ImagePickerIOS

Renders a image picker on iOS.

ProgressViewIOS

Renders a UIProgressView on iOS.

PushNotificationIOS

Handle push notifications for your app, including permission handling and icon badge number.

SegmentedControlIOS

Renders a UISegmentedControl on iOS.

Android Components and APIs

Many of the following components provide wrappers for commonly used Android classes.

BackHandler

Detect hardware button presses for back navigation.

DatePickerAndroid

Opens the standard Android date picker dialog.

DrawerLayoutAndroid

Renders a DrawerLayout on Android.

PermissionsAndroid

Provides access to the permissions model introduced in Android M.

ProgressBarAndroid

Renders a ProgressBar on Android.

TimePickerAndroid

Opens the standard Android time picker dialog.

ToastAndroid

Create an Android Toast alert.

ToolbarAndroid

Renders a Toolbar on Android.

ViewPagerAndroid

Container that allows to flip left and right between child views.

Others

These components may come in handy for certain applications. For an exhaustive list of components and APIs, check out the sidebar to the left.

ActivityIndicator

Displays a circular loading indicator.

Alert

Launches an alert dialog with the specified title and message.

Animated

A library for creating fluid, powerful animations that are easy to build and maintain.

Clipboard

Provides an interface for setting and getting content from the clipboard on both Android and iOS.

Dimensions

Provides an interface for getting device dimensions.

KeyboardAvoidingView

Provides a view that moves out of the way of the virtual keyboard automatically.

Linking

Provides a general interface to interact with both incoming and outgoing app links.

Modal

Provides a simple way to present content above an enclosing view.

PixelRatio

Provides access to the device pixel density.

RefreshControl

This component is used inside a ScrollView to add pull to refresh functionality.

StatusBar

Component to control the app status bar.

Edit this page
Last updated on
- + diff --git a/docs/0.60/custom-webview-android.html b/docs/0.60/custom-webview-android.html index fa3f01cd029..cdafa4bd26c 100644 --- a/docs/0.60/custom-webview-android.html +++ b/docs/0.60/custom-webview-android.html @@ -19,7 +19,7 @@ - + @@ -60,7 +60,7 @@
render() {
return (
<WebView
{...this.props}
nativeConfig={{
component: RCTCustomWebView,
props: {
finalUrl: this.props.finalUrl,
onNavigationCompleted: this._onNavigationCompleted
}
}}
/>
);
}
}

Similar to regular native components, you must provide all your prop types in the component to have them forwarded on to the native component. However, if you have some prop types that are only used internally in component, you can add them to the nativeOnly property of the third argument previously mentioned. For event handlers, you have to use the value true instead of a regular prop type.

For example, if you wanted to add an internal event handler called onScrollToBottom, you would use,

const RCTCustomWebView = requireNativeComponent(
'RCTCustomWebView',
CustomWebView,
{
...WebView.extraNativeComponentConfig,
nativeOnly: {
...WebView.extraNativeComponentConfig.nativeOnly,
onScrollToBottom: true
}
}
);
Edit this page
Last updated on
- + diff --git a/docs/0.60/custom-webview-android/index.html b/docs/0.60/custom-webview-android/index.html index fa3f01cd029..cdafa4bd26c 100644 --- a/docs/0.60/custom-webview-android/index.html +++ b/docs/0.60/custom-webview-android/index.html @@ -19,7 +19,7 @@ - + @@ -60,7 +60,7 @@
render() {
return (
<WebView
{...this.props}
nativeConfig={{
component: RCTCustomWebView,
props: {
finalUrl: this.props.finalUrl,
onNavigationCompleted: this._onNavigationCompleted
}
}}
/>
);
}
}

Similar to regular native components, you must provide all your prop types in the component to have them forwarded on to the native component. However, if you have some prop types that are only used internally in component, you can add them to the nativeOnly property of the third argument previously mentioned. For event handlers, you have to use the value true instead of a regular prop type.

For example, if you wanted to add an internal event handler called onScrollToBottom, you would use,

const RCTCustomWebView = requireNativeComponent(
'RCTCustomWebView',
CustomWebView,
{
...WebView.extraNativeComponentConfig,
nativeOnly: {
...WebView.extraNativeComponentConfig.nativeOnly,
onScrollToBottom: true
}
}
);
Edit this page
Last updated on
- + diff --git a/docs/0.60/custom-webview-ios.html b/docs/0.60/custom-webview-ios.html index 63989dea296..fff2e469a0e 100644 --- a/docs/0.60/custom-webview-ios.html +++ b/docs/0.60/custom-webview-ios.html @@ -19,7 +19,7 @@ - + @@ -63,7 +63,7 @@
render() {
return (
<WebView
{...this.props}
nativeConfig={{
component: RCTCustomWebView,
props: {
finalUrl: this.props.finalUrl,
onNavigationCompleted: this._onNavigationCompleted
},
viewManager: CustomWebViewManager
}}
/>
);
}
}

Similar to regular native components, you must provide all your prop types in the component to have them forwarded on to the native component. However, if you have some prop types that are only used internally in component, you can add them to the nativeOnly property of the third argument previously mentioned. For event handlers, you have to use the value true instead of a regular prop type.

For example, if you wanted to add an internal event handler called onScrollToBottom, you would use,

const RCTCustomWebView = requireNativeComponent(
'RCTCustomWebView',
CustomWebView,
{
...WebView.extraNativeComponentConfig,
nativeOnly: {
...WebView.extraNativeComponentConfig.nativeOnly,
onScrollToBottom: true
}
}
);
Edit this page
Last updated on
- + diff --git a/docs/0.60/custom-webview-ios/index.html b/docs/0.60/custom-webview-ios/index.html index 63989dea296..fff2e469a0e 100644 --- a/docs/0.60/custom-webview-ios/index.html +++ b/docs/0.60/custom-webview-ios/index.html @@ -19,7 +19,7 @@ - + @@ -63,7 +63,7 @@
render() {
return (
<WebView
{...this.props}
nativeConfig={{
component: RCTCustomWebView,
props: {
finalUrl: this.props.finalUrl,
onNavigationCompleted: this._onNavigationCompleted
},
viewManager: CustomWebViewManager
}}
/>
);
}
}

Similar to regular native components, you must provide all your prop types in the component to have them forwarded on to the native component. However, if you have some prop types that are only used internally in component, you can add them to the nativeOnly property of the third argument previously mentioned. For event handlers, you have to use the value true instead of a regular prop type.

For example, if you wanted to add an internal event handler called onScrollToBottom, you would use,

const RCTCustomWebView = requireNativeComponent(
'RCTCustomWebView',
CustomWebView,
{
...WebView.extraNativeComponentConfig,
nativeOnly: {
...WebView.extraNativeComponentConfig.nativeOnly,
onScrollToBottom: true
}
}
);
Edit this page
Last updated on
- + diff --git a/docs/0.60/datepickerandroid.html b/docs/0.60/datepickerandroid.html index 7e90a13ecb5..5b32e4c2382 100644 --- a/docs/0.60/datepickerandroid.html +++ b/docs/0.60/datepickerandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

DatePickerAndroid

Opens the standard Android date picker dialog.

DatePickerAndroid has been merged with DatePickerIOS and TimePickerAndroid into a single component called DateTimePicker and will be removed in a future release.

Example

try {
const {
action,
year,
month,
day
} = await DatePickerAndroid.open({
// Use `new Date()` for current date.
// May 25 2020. Month 0 is January.
date: new Date(2020, 4, 25)
});
if (action !== DatePickerAndroid.dismissedAction) {
// Selected year, month (0-11), day
}
} catch ({ code, message }) {
console.warn('Cannot open date picker', message);
}

Reference

Methods

open()

static open(options)

Opens the standard Android date picker dialog.

The available keys for the options object are:

  • date (Date object or timestamp in milliseconds) - date to show by default
  • minDate (Date or timestamp in milliseconds) - minimum date that can be selected
  • maxDate (Date object or timestamp in milliseconds) - maximum date that can be selected
  • mode (enum('calendar', 'spinner', 'default')) - To set the date-picker mode to calendar/spinner/default
    • 'calendar': Show a date picker in calendar mode.
    • 'spinner': Show a date picker in spinner mode.
    • 'default': Show a default native date picker(spinner/calendar) based on android versions.

Returns a Promise which will be invoked an object containing action, year, month (0-11), 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 is equal to DatePickerAndroid.dateSetAction 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.

dateSetAction()

static dateSetAction()

A date has been selected.

dismissedAction()

static dismissedAction()

The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/0.60/datepickerandroid/index.html b/docs/0.60/datepickerandroid/index.html index 7e90a13ecb5..5b32e4c2382 100644 --- a/docs/0.60/datepickerandroid/index.html +++ b/docs/0.60/datepickerandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

DatePickerAndroid

Opens the standard Android date picker dialog.

DatePickerAndroid has been merged with DatePickerIOS and TimePickerAndroid into a single component called DateTimePicker and will be removed in a future release.

Example

try {
const {
action,
year,
month,
day
} = await DatePickerAndroid.open({
// Use `new Date()` for current date.
// May 25 2020. Month 0 is January.
date: new Date(2020, 4, 25)
});
if (action !== DatePickerAndroid.dismissedAction) {
// Selected year, month (0-11), day
}
} catch ({ code, message }) {
console.warn('Cannot open date picker', message);
}

Reference

Methods

open()

static open(options)

Opens the standard Android date picker dialog.

The available keys for the options object are:

  • date (Date object or timestamp in milliseconds) - date to show by default
  • minDate (Date or timestamp in milliseconds) - minimum date that can be selected
  • maxDate (Date object or timestamp in milliseconds) - maximum date that can be selected
  • mode (enum('calendar', 'spinner', 'default')) - To set the date-picker mode to calendar/spinner/default
    • 'calendar': Show a date picker in calendar mode.
    • 'spinner': Show a date picker in spinner mode.
    • 'default': Show a default native date picker(spinner/calendar) based on android versions.

Returns a Promise which will be invoked an object containing action, year, month (0-11), 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 is equal to DatePickerAndroid.dateSetAction 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.

dateSetAction()

static dateSetAction()

A date has been selected.

dismissedAction()

static dismissedAction()

The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/0.60/datepickerios.html b/docs/0.60/datepickerios.html index c1f24364dcc..14bad48824b 100644 --- a/docs/0.60/datepickerios.html +++ b/docs/0.60/datepickerios.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'center'
}
});

Reference

Props

Inherits View Props.

date

The currently selected date.

TypeRequired
DateYes

onChange

Date change handler.

This is called when the user changes the date or time in the UI. The first and only argument is an Event. For getting the date the picker was changed to, use onDateChange instead.

TypeRequired
functionNo

onDateChange

Date change handler.

This is called when the user changes the date or time in the UI. The first and only argument is a Date object representing the new date and time.

TypeRequired
functionYes

maximumDate

Maximum date.

Restricts the range of possible date/time values.

TypeRequired
DateNo

Example with maximumDate set to December 31, 2017:

minimumDate

Minimum date.

Restricts the range of possible date/time values.

TypeRequired
DateNo

See maximumDate for an example image.

minuteInterval

The interval at which minutes can be selected.

TypeRequired
enum(1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30)No

Example with minuteInterval set to 10:

mode

The date picker mode.

TypeRequired
enum('date', 'time', 'datetime', 'countdown')No

Example with mode set to date, time, and datetime:

locale

The locale for the date picker. Value needs to be a Locale ID.

TypeRequired
StringNo

timeZoneOffsetInMinutes

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.

TypeRequired
numberNo

initialDate

Provides an initial value that will change when the user starts selecting a date. It is useful for use-cases where you do not want to deal with listening to events and updating the date prop to keep the controlled state in sync. The controlled state has known bugs which causes it to go out of sync with native. The initialDate prop is intended to allow you to have native be source of truth.

TypeRequired
DateNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/datepickerios/index.html b/docs/0.60/datepickerios/index.html index c1f24364dcc..14bad48824b 100644 --- a/docs/0.60/datepickerios/index.html +++ b/docs/0.60/datepickerios/index.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'center'
}
});

Reference

Props

Inherits View Props.

date

The currently selected date.

TypeRequired
DateYes

onChange

Date change handler.

This is called when the user changes the date or time in the UI. The first and only argument is an Event. For getting the date the picker was changed to, use onDateChange instead.

TypeRequired
functionNo

onDateChange

Date change handler.

This is called when the user changes the date or time in the UI. The first and only argument is a Date object representing the new date and time.

TypeRequired
functionYes

maximumDate

Maximum date.

Restricts the range of possible date/time values.

TypeRequired
DateNo

Example with maximumDate set to December 31, 2017:

minimumDate

Minimum date.

Restricts the range of possible date/time values.

TypeRequired
DateNo

See maximumDate for an example image.

minuteInterval

The interval at which minutes can be selected.

TypeRequired
enum(1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30)No

Example with minuteInterval set to 10:

mode

The date picker mode.

TypeRequired
enum('date', 'time', 'datetime', 'countdown')No

Example with mode set to date, time, and datetime:

locale

The locale for the date picker. Value needs to be a Locale ID.

TypeRequired
StringNo

timeZoneOffsetInMinutes

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.

TypeRequired
numberNo

initialDate

Provides an initial value that will change when the user starts selecting a date. It is useful for use-cases where you do not want to deal with listening to events and updating the date prop to keep the controlled state in sync. The controlled state has known bugs which causes it to go out of sync with native. The initialDate prop is intended to allow you to have native be source of truth.

TypeRequired
DateNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/debugging.html b/docs/0.60/debugging.html index 727429d0b1c..d25afaeb594 100644 --- a/docs/0.60/debugging.html +++ b/docs/0.60/debugging.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

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 on Mac OS and Ctrl+M on Windows and Linux. Alternatively for Android, you can run the command adb shell input keyevent 82 to open the dev menu (82 being the Menu key code).

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.xcassets on iOS or the res/drawable folder 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:

import { YellowBox } from 'react-native';
YellowBox.ignoreWarnings(['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.

Safari Developer Tools

You can use Safari to debug the iOS version of your app without having to enable "Debug JS Remotely".

  • Enable Develop menu in Safari: Preferences → Advanced → Select "Show Develop menu in menu bar"
  • Select your app's JSContext: Develop → Simulator → JSContext
  • Safari's Web Inspector should open which has a Console and a Debugger

However, there are some disadvantages:

  1. No sourcemaps when debugging
  2. Every time the app is reloaded (using live reload, or by manually reloading), a new JSContext is created. Choosing "Automatically Show Web Inspectors for JSContexts" saves you from having to select the latest JSContext manually.

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:

npm install -g react-devtools

Now run react-devtools from the terminal to launch the standalone DevTools app:

react-devtools

React DevTools

It should connect to your simulator within a few seconds.

Note: if you prefer to avoid global installations, you can add react-devtools as a project dependency. Add the react-devtools package to your project using npm install --save-dev react-devtools, then add "react-devtools": "react-devtools" to the scripts section in your package.json, and then run npm run react-devtools from your project folder to open the DevTools.

Integration with React Native Inspector

Open the in-app developer menu and choose "Toggle Inspector". It will bring up an overlay that lets you tap on any UI element and see information about it:

React Native Inspector

However, when react-devtools is running, Inspector will enter a 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:

React DevTools Inspector Integration

You can choose "Toggle 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.

React DevTools Chrome Console Integration

Performance Monitor

You can enable a performance overlay to help you debug performance problems by selecting "Perf Monitor" in the Developer Menu.

Native Debugging

Accessing console logs

You can display the console logs for an iOS or Android app by using the following commands in a terminal while the app is running:

$ react-native log-ios
$ react-native log-android

You may also access these through Debug → Open System Log... in the iOS Simulator or by running adb logcat *:S ReactNative:V ReactNativeJS:V in a terminal while an Android app is running on a device or emulator.

If you're using Create React Native App or Expo CLI, console logs already appear in the same terminal output as the bundler.

Debugging on a device with Chrome Developer Tools

If you're using Create React Native App or Expo CLI, this is configured for you already.

On iOS devices, open the file RCTWebSocketExecutor.m and change "localhost" to the IP address of your computer, then select "Debug JS Remotely" from the Developer Menu.

On Android 5.0+ devices connected via USB, you can use the adb command line tool to setup port forwarding from the device to your computer:

adb reverse tcp:8081 tcp:8081

Alternatively, select "Dev Settings" from the Developer Menu, then update the "Debug server host for device" setting to match the IP address of your computer.

If you run into any issues, it may be possible that one of your Chrome extensions is interacting in unexpected ways with the debugger. Try disabling all of your extensions and re-enabling them one-by-one until you find the problematic extension.

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.

Edit this page
Last updated on
- + diff --git a/docs/0.60/debugging/index.html b/docs/0.60/debugging/index.html index 727429d0b1c..d25afaeb594 100644 --- a/docs/0.60/debugging/index.html +++ b/docs/0.60/debugging/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

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 on Mac OS and Ctrl+M on Windows and Linux. Alternatively for Android, you can run the command adb shell input keyevent 82 to open the dev menu (82 being the Menu key code).

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.xcassets on iOS or the res/drawable folder 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:

import { YellowBox } from 'react-native';
YellowBox.ignoreWarnings(['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.

Safari Developer Tools

You can use Safari to debug the iOS version of your app without having to enable "Debug JS Remotely".

  • Enable Develop menu in Safari: Preferences → Advanced → Select "Show Develop menu in menu bar"
  • Select your app's JSContext: Develop → Simulator → JSContext
  • Safari's Web Inspector should open which has a Console and a Debugger

However, there are some disadvantages:

  1. No sourcemaps when debugging
  2. Every time the app is reloaded (using live reload, or by manually reloading), a new JSContext is created. Choosing "Automatically Show Web Inspectors for JSContexts" saves you from having to select the latest JSContext manually.

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:

npm install -g react-devtools

Now run react-devtools from the terminal to launch the standalone DevTools app:

react-devtools

React DevTools

It should connect to your simulator within a few seconds.

Note: if you prefer to avoid global installations, you can add react-devtools as a project dependency. Add the react-devtools package to your project using npm install --save-dev react-devtools, then add "react-devtools": "react-devtools" to the scripts section in your package.json, and then run npm run react-devtools from your project folder to open the DevTools.

Integration with React Native Inspector

Open the in-app developer menu and choose "Toggle Inspector". It will bring up an overlay that lets you tap on any UI element and see information about it:

React Native Inspector

However, when react-devtools is running, Inspector will enter a 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:

React DevTools Inspector Integration

You can choose "Toggle 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.

React DevTools Chrome Console Integration

Performance Monitor

You can enable a performance overlay to help you debug performance problems by selecting "Perf Monitor" in the Developer Menu.

Native Debugging

Accessing console logs

You can display the console logs for an iOS or Android app by using the following commands in a terminal while the app is running:

$ react-native log-ios
$ react-native log-android

You may also access these through Debug → Open System Log... in the iOS Simulator or by running adb logcat *:S ReactNative:V ReactNativeJS:V in a terminal while an Android app is running on a device or emulator.

If you're using Create React Native App or Expo CLI, console logs already appear in the same terminal output as the bundler.

Debugging on a device with Chrome Developer Tools

If you're using Create React Native App or Expo CLI, this is configured for you already.

On iOS devices, open the file RCTWebSocketExecutor.m and change "localhost" to the IP address of your computer, then select "Debug JS Remotely" from the Developer Menu.

On Android 5.0+ devices connected via USB, you can use the adb command line tool to setup port forwarding from the device to your computer:

adb reverse tcp:8081 tcp:8081

Alternatively, select "Dev Settings" from the Developer Menu, then update the "Debug server host for device" setting to match the IP address of your computer.

If you run into any issues, it may be possible that one of your Chrome extensions is interacting in unexpected ways with the debugger. Try disabling all of your extensions and re-enabling them one-by-one until you find the problematic extension.

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.

Edit this page
Last updated on
- + diff --git a/docs/0.60/devsettings.html b/docs/0.60/devsettings.html index 84321dbd963..8d7d5b3102a 100644 --- a/docs/0.60/devsettings.html +++ b/docs/0.60/devsettings.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

DevSettings

The DevSettings module exposes methods for customizing settings for developers in development.

Reference

Methods

addMenuItem()

static addMenuItem(title: string, handler: function)

Add a custom menu item to the developer menu:

DevSettings.addMenuItem('Show Secret Dev Screen', () => {
Alert.alert('Showing secret dev screen!');
});

reload()

static reload()

Reload the application. Can be invoked directly or on user interaction:

<Button title="Reload" onPress={() => DevSettings.reload()} />
Edit this page
Last updated on
- + diff --git a/docs/0.60/devsettings/index.html b/docs/0.60/devsettings/index.html index 84321dbd963..8d7d5b3102a 100644 --- a/docs/0.60/devsettings/index.html +++ b/docs/0.60/devsettings/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

DevSettings

The DevSettings module exposes methods for customizing settings for developers in development.

Reference

Methods

addMenuItem()

static addMenuItem(title: string, handler: function)

Add a custom menu item to the developer menu:

DevSettings.addMenuItem('Show Secret Dev Screen', () => {
Alert.alert('Showing secret dev screen!');
});

reload()

static reload()

Reload the application. Can be invoked directly or on user interaction:

<Button title="Reload" onPress={() => DevSettings.reload()} />
Edit this page
Last updated on
- + diff --git a/docs/0.60/dimensions.html b/docs/0.60/dimensions.html index fac43a8da4e..75c60a3e090 100644 --- a/docs/0.60/dimensions.html +++ b/docs/0.60/dimensions.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Dimensions

import { Dimensions } from 'react-native';

You can get the application window's width and height using below code:

const windowWidth = Dimensions.get('window').width;
const windowHeight = Dimensions.get('window').height;

Although dimensions are available immediately, they may change (e.g due to device rotation, foldable devices etc) so any rendering logic or styles that depend on these constants should try to call this function on every render, rather than caching the value (for example, using inline styles rather than setting a value in a StyleSheet).

If you are targeting foldable devices or devices which can change the screen size or app window size, you can use the event listener available in the Dimensions module as shown in the below example.

Example

Reference

Methods

addEventListener()

static addEventListener(type, handler)

Add an event handler. Supported events:

  • change: Fires when a property within the Dimensions object changes. The argument to the event handler is an object with window and screen properties whose values are the same as the return values of Dimensions.get('window') and Dimensions.get('screen'), respectively.

get()

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 these constants should try to call this function on every render, rather than caching the value (for example, using inline styles rather than setting a value in a StyleSheet).

Example: var {height, width} = Dimensions.get('window');

@param {string} dim Name of dimension as defined when calling set. @returns {Object?} Value for the dimension.

For Android the window dimension will exclude the size used by the status bar (if not translucent) and bottom navigation bar

removeEventListener()

static removeEventListener(type, handler)

Remove an event handler.

set()

static set(dims)

This should only be called from native code by sending the didUpdateDimensions event.

@param {object} dims string-keyed object of dimensions to set

Edit this page
Last updated on
- + diff --git a/docs/0.60/dimensions/index.html b/docs/0.60/dimensions/index.html index fac43a8da4e..75c60a3e090 100644 --- a/docs/0.60/dimensions/index.html +++ b/docs/0.60/dimensions/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Dimensions

import { Dimensions } from 'react-native';

You can get the application window's width and height using below code:

const windowWidth = Dimensions.get('window').width;
const windowHeight = Dimensions.get('window').height;

Although dimensions are available immediately, they may change (e.g due to device rotation, foldable devices etc) so any rendering logic or styles that depend on these constants should try to call this function on every render, rather than caching the value (for example, using inline styles rather than setting a value in a StyleSheet).

If you are targeting foldable devices or devices which can change the screen size or app window size, you can use the event listener available in the Dimensions module as shown in the below example.

Example

Reference

Methods

addEventListener()

static addEventListener(type, handler)

Add an event handler. Supported events:

  • change: Fires when a property within the Dimensions object changes. The argument to the event handler is an object with window and screen properties whose values are the same as the return values of Dimensions.get('window') and Dimensions.get('screen'), respectively.

get()

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 these constants should try to call this function on every render, rather than caching the value (for example, using inline styles rather than setting a value in a StyleSheet).

Example: var {height, width} = Dimensions.get('window');

@param {string} dim Name of dimension as defined when calling set. @returns {Object?} Value for the dimension.

For Android the window dimension will exclude the size used by the status bar (if not translucent) and bottom navigation bar

removeEventListener()

static removeEventListener(type, handler)

Remove an event handler.

set()

static set(dims)

This should only be called from native code by sending the didUpdateDimensions event.

@param {object} dims string-keyed object of dimensions to set

Edit this page
Last updated on
- + diff --git a/docs/0.60/direct-manipulation.html b/docs/0.60/direct-manipulation.html index dabafe30433..9cc647fed10 100644 --- a/docs/0.60/direct-manipulation.html +++ b/docs/0.60/direct-manipulation.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
render() {
return (
<TouchableOpacity onPress={() => this.setState({myButtonOpacity: 0.5})}
onPressOut={() => this.setState({myButtonOpacity: 1})}>
<View style={[styles.button, {opacity: this.state.myButtonOpacity}]}>
<Text>Press me!</Text>
</View>
</TouchableOpacity>
)
}

This is computationally intensive compared to the original example - React needs to re-render the component hierarchy each time the opacity changes, even though other properties of the view and its children haven't changed. Usually this overhead isn't a concern but when performing continuous animations and responding to gestures, judiciously optimizing your components can improve your animations' fidelity.

If you look at the implementation of setNativeProps in NativeMethodsMixin you will notice that it is a wrapper around RCTUIManager.updateView - this is the exact same function call that results from re-rendering - see receiveComponent in ReactNativeBaseComponent.

Composite components and setNativeProps

Composite components are not backed by a native view, so you cannot call setNativeProps on them. Consider this example:

If you run this you will immediately see this error: Touchable child must either be native or forward setNativeProps to a native component. This occurs because MyButton isn't directly backed by a native view whose opacity should be set. You can think about it like this: if you define a component with createReactClass you would not expect to be able to set a style prop on it and have that work - you would need to pass the style prop down to a child, unless you are wrapping a native component. Similarly, we are going to forward setNativeProps to a native-backed child component.

Forward setNativeProps to a child

All we need to do is provide a setNativeProps method on our component that calls setNativeProps on the appropriate child with the given arguments.

You can now use MyButton inside of TouchableOpacity! A sidenote for clarity: we used the ref callback syntax here, rather than the traditional string-based ref.

You may have noticed that we passed all of the props down to the child view using {...this.props}. The reason for this is that TouchableOpacity is actually a composite component, and so in addition to depending on setNativeProps on its child, it also requires that the child perform touch handling. To do this, it passes on various props that call back to the TouchableOpacity component. TouchableHighlight, in contrast, is backed by a native view and only requires that we implement setNativeProps.

setNativeProps to clear TextInput value

Another very common use case of setNativeProps is to clear the value of a TextInput. The controlled prop of TextInput can sometimes drop characters when the bufferDelay is low and the user types very quickly. Some developers prefer to skip this prop entirely and instead use setNativeProps to directly manipulate the TextInput value when necessary. For example, the following code demonstrates clearing the input when you tap a button:

Avoiding conflicts with the render function

If you update a property that is also managed by the render function, you might end up with some unpredictable and confusing bugs because anytime the component re-renders and that property changes, whatever value was previously set from setNativeProps will be completely ignored and overridden.

setNativeProps & shouldComponentUpdate

By intelligently applying shouldComponentUpdate you can avoid the unnecessary overhead involved in reconciling unchanged component subtrees, to the point where it may be performant enough to use setState instead of setNativeProps.

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:

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:

measureLayout(relativeToNativeNode, onSuccess, onFail)

Like measure(), but measures the view relative to 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 findNodeHandle(component).

import { findNodeHandle } from 'react-native';

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().

Edit this page
Last updated on
- + diff --git a/docs/0.60/direct-manipulation/index.html b/docs/0.60/direct-manipulation/index.html index dabafe30433..9cc647fed10 100644 --- a/docs/0.60/direct-manipulation/index.html +++ b/docs/0.60/direct-manipulation/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
render() {
return (
<TouchableOpacity onPress={() => this.setState({myButtonOpacity: 0.5})}
onPressOut={() => this.setState({myButtonOpacity: 1})}>
<View style={[styles.button, {opacity: this.state.myButtonOpacity}]}>
<Text>Press me!</Text>
</View>
</TouchableOpacity>
)
}

This is computationally intensive compared to the original example - React needs to re-render the component hierarchy each time the opacity changes, even though other properties of the view and its children haven't changed. Usually this overhead isn't a concern but when performing continuous animations and responding to gestures, judiciously optimizing your components can improve your animations' fidelity.

If you look at the implementation of setNativeProps in NativeMethodsMixin you will notice that it is a wrapper around RCTUIManager.updateView - this is the exact same function call that results from re-rendering - see receiveComponent in ReactNativeBaseComponent.

Composite components and setNativeProps

Composite components are not backed by a native view, so you cannot call setNativeProps on them. Consider this example:

If you run this you will immediately see this error: Touchable child must either be native or forward setNativeProps to a native component. This occurs because MyButton isn't directly backed by a native view whose opacity should be set. You can think about it like this: if you define a component with createReactClass you would not expect to be able to set a style prop on it and have that work - you would need to pass the style prop down to a child, unless you are wrapping a native component. Similarly, we are going to forward setNativeProps to a native-backed child component.

Forward setNativeProps to a child

All we need to do is provide a setNativeProps method on our component that calls setNativeProps on the appropriate child with the given arguments.

You can now use MyButton inside of TouchableOpacity! A sidenote for clarity: we used the ref callback syntax here, rather than the traditional string-based ref.

You may have noticed that we passed all of the props down to the child view using {...this.props}. The reason for this is that TouchableOpacity is actually a composite component, and so in addition to depending on setNativeProps on its child, it also requires that the child perform touch handling. To do this, it passes on various props that call back to the TouchableOpacity component. TouchableHighlight, in contrast, is backed by a native view and only requires that we implement setNativeProps.

setNativeProps to clear TextInput value

Another very common use case of setNativeProps is to clear the value of a TextInput. The controlled prop of TextInput can sometimes drop characters when the bufferDelay is low and the user types very quickly. Some developers prefer to skip this prop entirely and instead use setNativeProps to directly manipulate the TextInput value when necessary. For example, the following code demonstrates clearing the input when you tap a button:

Avoiding conflicts with the render function

If you update a property that is also managed by the render function, you might end up with some unpredictable and confusing bugs because anytime the component re-renders and that property changes, whatever value was previously set from setNativeProps will be completely ignored and overridden.

setNativeProps & shouldComponentUpdate

By intelligently applying shouldComponentUpdate you can avoid the unnecessary overhead involved in reconciling unchanged component subtrees, to the point where it may be performant enough to use setState instead of setNativeProps.

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:

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:

measureLayout(relativeToNativeNode, onSuccess, onFail)

Like measure(), but measures the view relative to 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 findNodeHandle(component).

import { findNodeHandle } from 'react-native';

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().

Edit this page
Last updated on
- + diff --git a/docs/0.60/drawerlayoutandroid.html b/docs/0.60/drawerlayoutandroid.html index c4549fa0b66..063c1384fd8 100644 --- a/docs/0.60/drawerlayoutandroid.html +++ b/docs/0.60/drawerlayoutandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

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 side of the window specified by the drawerPosition prop and its width can be set by the drawerWidth prop.

Example:

render: function() {
var navigationView = (
<View style={{flex: 1, backgroundColor: '#fff'}}>
<Text style={{margin: 10, fontSize: 15, textAlign: 'left'}}>I'm in the Drawer!</Text>
</View>
);
return (
<DrawerLayoutAndroid
drawerWidth={300}
drawerPosition={DrawerLayoutAndroid.positions.Left}
renderNavigationView={() => navigationView}>
<View style={{flex: 1, alignItems: 'center'}}>
<Text style={{margin: 10, fontSize: 15, textAlign: 'right'}}>Hello</Text>
<Text style={{margin: 10, fontSize: 15, textAlign: 'right'}}>World!</Text>
</View>
</DrawerLayoutAndroid>
);
},

Reference

Props

Inherits View Props.

renderNavigationView

The navigation view that will be rendered to the side of the screen and can be pulled in.

TypeRequired
functionYes

onDrawerClose

Function called whenever the navigation view has been closed.

TypeRequired
functionNo

drawerPosition

Specifies the side of the screen from which the drawer will slide in.

TypeRequired
enum(DrawerConsts.DrawerPosition.Left, DrawerConsts.DrawerPosition.Right)No

drawerWidth

Specifies the width of the drawer, more precisely the width of the view that be pulled in from the edge of the window.

TypeRequired
numberNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

  • 'none' (the default), drags do not dismiss the keyboard.
  • 'on-drag', the keyboard is dismissed when a drag begins.
TypeRequired
enum('none', 'on-drag')No

drawerLockMode

Specifies the lock mode of the drawer. The drawer can be locked in 3 states:

  • unlocked (default), meaning that the drawer will respond (open/close) to touch gestures.
  • locked-closed, meaning that the drawer will stay closed and not respond to gestures.
  • locked-open, meaning that the drawer will stay opened and not respond to gestures. The drawer may still be opened and closed programmatically (openDrawer/closeDrawer).
TypeRequired
enum('unlocked', 'locked-closed', 'locked-open')No

onDrawerOpen

Function called whenever the navigation view has been opened.

TypeRequired
functionNo

onDrawerSlide

Function called whenever there is an interaction with the navigation view.

TypeRequired
functionNo

onDrawerStateChanged

Function called when the drawer state has changed. The drawer can be in 3 states:

  • idle, meaning there is no interaction with the navigation view happening at the time
  • dragging, meaning there is currently an interaction with the navigation view
  • settling, meaning that there was an interaction with the navigation view, and the navigation view is now finishing its closing or opening animation
TypeRequired
functionNo

drawerBackgroundColor

Specifies the background color of the drawer. The default value is white. If you want to set the opacity of the drawer, use rgba. Example:

return (
<DrawerLayoutAndroid drawerBackgroundColor="rgba(0,0,0,0.5)" />
);
TypeRequired
colorNo

statusBarBackgroundColor

Make the drawer take the entire screen and draw the background of the status bar to allow it to open over the status bar. It will only have an effect on API 21+.

TypeRequired
colorNo

Methods

openDrawer()

openDrawer();

Opens the drawer.

closeDrawer()

closeDrawer();

Closes the drawer.

Edit this page
Last updated on
- + diff --git a/docs/0.60/drawerlayoutandroid/index.html b/docs/0.60/drawerlayoutandroid/index.html index c4549fa0b66..063c1384fd8 100644 --- a/docs/0.60/drawerlayoutandroid/index.html +++ b/docs/0.60/drawerlayoutandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

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 side of the window specified by the drawerPosition prop and its width can be set by the drawerWidth prop.

Example:

render: function() {
var navigationView = (
<View style={{flex: 1, backgroundColor: '#fff'}}>
<Text style={{margin: 10, fontSize: 15, textAlign: 'left'}}>I'm in the Drawer!</Text>
</View>
);
return (
<DrawerLayoutAndroid
drawerWidth={300}
drawerPosition={DrawerLayoutAndroid.positions.Left}
renderNavigationView={() => navigationView}>
<View style={{flex: 1, alignItems: 'center'}}>
<Text style={{margin: 10, fontSize: 15, textAlign: 'right'}}>Hello</Text>
<Text style={{margin: 10, fontSize: 15, textAlign: 'right'}}>World!</Text>
</View>
</DrawerLayoutAndroid>
);
},

Reference

Props

Inherits View Props.

renderNavigationView

The navigation view that will be rendered to the side of the screen and can be pulled in.

TypeRequired
functionYes

onDrawerClose

Function called whenever the navigation view has been closed.

TypeRequired
functionNo

drawerPosition

Specifies the side of the screen from which the drawer will slide in.

TypeRequired
enum(DrawerConsts.DrawerPosition.Left, DrawerConsts.DrawerPosition.Right)No

drawerWidth

Specifies the width of the drawer, more precisely the width of the view that be pulled in from the edge of the window.

TypeRequired
numberNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

  • 'none' (the default), drags do not dismiss the keyboard.
  • 'on-drag', the keyboard is dismissed when a drag begins.
TypeRequired
enum('none', 'on-drag')No

drawerLockMode

Specifies the lock mode of the drawer. The drawer can be locked in 3 states:

  • unlocked (default), meaning that the drawer will respond (open/close) to touch gestures.
  • locked-closed, meaning that the drawer will stay closed and not respond to gestures.
  • locked-open, meaning that the drawer will stay opened and not respond to gestures. The drawer may still be opened and closed programmatically (openDrawer/closeDrawer).
TypeRequired
enum('unlocked', 'locked-closed', 'locked-open')No

onDrawerOpen

Function called whenever the navigation view has been opened.

TypeRequired
functionNo

onDrawerSlide

Function called whenever there is an interaction with the navigation view.

TypeRequired
functionNo

onDrawerStateChanged

Function called when the drawer state has changed. The drawer can be in 3 states:

  • idle, meaning there is no interaction with the navigation view happening at the time
  • dragging, meaning there is currently an interaction with the navigation view
  • settling, meaning that there was an interaction with the navigation view, and the navigation view is now finishing its closing or opening animation
TypeRequired
functionNo

drawerBackgroundColor

Specifies the background color of the drawer. The default value is white. If you want to set the opacity of the drawer, use rgba. Example:

return (
<DrawerLayoutAndroid drawerBackgroundColor="rgba(0,0,0,0.5)" />
);
TypeRequired
colorNo

statusBarBackgroundColor

Make the drawer take the entire screen and draw the background of the status bar to allow it to open over the status bar. It will only have an effect on API 21+.

TypeRequired
colorNo

Methods

openDrawer()

openDrawer();

Opens the drawer.

closeDrawer()

closeDrawer();

Closes the drawer.

Edit this page
Last updated on
- + diff --git a/docs/0.60/easing.html b/docs/0.60/easing.html index cc37d37abec..ecd87f46e00 100644 --- a/docs/0.60/easing.html +++ b/docs/0.60/easing.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Easing

The Easing module implements common easing functions. This module is used by Animated.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 following methods:

  • back provides a basic animation where the object goes slightly back before moving forward
  • bounce provides a bouncing animation
  • ease provides a basic inertial animation
  • elastic provides a basic spring interaction

Standard functions

Three standard easing functions are provided:

The poly function can be used to implement quartic, quintic, and other higher power functions.

Additional functions

Additional mathematical functions are provided by the following methods:

  • bezier provides a cubic bezier curve
  • circle provides a circular function
  • sin provides a sinusoidal function
  • exp provides an exponential function

The following helpers are used to modify other easing functions.

  • in runs an easing function forwards
  • inOut makes any easing function symmetrical
  • out runs an easing function backwards

Reference

Methods

step0()

static step0(n)

A stepping function, returns 1 for any positive value of n.

step1()

static step1(n)

A stepping function, returns 1 if n is greater than or equal to 1.

linear()

static linear(t)

A linear function, f(t) = t. Position correlates to elapsed time one to one.

http://cubic-bezier.com/#0,0,1,1

ease()

static ease(t)

A basic inertial interaction, similar to an object slowly accelerating to speed.

http://cubic-bezier.com/#.42,0,1,1

quad()

static quad(t)

A quadratic function, f(t) = t * t. Position equals the square of elapsed time.

http://easings.net/#easeInQuad

cubic()

static cubic(t)

A cubic function, f(t) = t * t * t. Position equals the cube of elapsed time.

http://easings.net/#easeInCubic

poly()

static poly(n)

A power function. Position is equal to the Nth power of elapsed time.

n = 4: http://easings.net/#easeInQuart n = 5: http://easings.net/#easeInQuint

sin()

static sin(t)

A sinusoidal function.

http://easings.net/#easeInSine

circle()

static circle(t)

A circular function.

http://easings.net/#easeInCirc

exp()

static exp(t)

An exponential function.

http://easings.net/#easeInExpo

elastic()

static elastic(bounciness)

A basic elastic interaction, similar to a spring oscillating back and forth.

Default bounciness is 1, which overshoots a little bit once. 0 bounciness doesn't overshoot at all, and bounciness of N > 1 will overshoot about N times.

http://easings.net/#easeInElastic

back()

static back(s)

Use with Animated.parallel() to create a basic effect where the object animates back slightly as the animation starts.

bounce()

static bounce(t)

Provides a basic bouncing effect.

http://easings.net/#easeInBounce

bezier()

static bezier(x1, y1, x2, y2)

Provides a cubic bezier curve, equivalent to CSS Transitions' transition-timing-function.

A useful tool to visualize cubic bezier curves can be found at http://cubic-bezier.com/

in()

static in easing;

Runs an easing function forwards.

out()

static out(easing)

Runs an easing function backwards.

inOut()

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.

Edit this page
Last updated on
- + diff --git a/docs/0.60/easing/index.html b/docs/0.60/easing/index.html index cc37d37abec..ecd87f46e00 100644 --- a/docs/0.60/easing/index.html +++ b/docs/0.60/easing/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Easing

The Easing module implements common easing functions. This module is used by Animated.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 following methods:

  • back provides a basic animation where the object goes slightly back before moving forward
  • bounce provides a bouncing animation
  • ease provides a basic inertial animation
  • elastic provides a basic spring interaction

Standard functions

Three standard easing functions are provided:

The poly function can be used to implement quartic, quintic, and other higher power functions.

Additional functions

Additional mathematical functions are provided by the following methods:

  • bezier provides a cubic bezier curve
  • circle provides a circular function
  • sin provides a sinusoidal function
  • exp provides an exponential function

The following helpers are used to modify other easing functions.

  • in runs an easing function forwards
  • inOut makes any easing function symmetrical
  • out runs an easing function backwards

Reference

Methods

step0()

static step0(n)

A stepping function, returns 1 for any positive value of n.

step1()

static step1(n)

A stepping function, returns 1 if n is greater than or equal to 1.

linear()

static linear(t)

A linear function, f(t) = t. Position correlates to elapsed time one to one.

http://cubic-bezier.com/#0,0,1,1

ease()

static ease(t)

A basic inertial interaction, similar to an object slowly accelerating to speed.

http://cubic-bezier.com/#.42,0,1,1

quad()

static quad(t)

A quadratic function, f(t) = t * t. Position equals the square of elapsed time.

http://easings.net/#easeInQuad

cubic()

static cubic(t)

A cubic function, f(t) = t * t * t. Position equals the cube of elapsed time.

http://easings.net/#easeInCubic

poly()

static poly(n)

A power function. Position is equal to the Nth power of elapsed time.

n = 4: http://easings.net/#easeInQuart n = 5: http://easings.net/#easeInQuint

sin()

static sin(t)

A sinusoidal function.

http://easings.net/#easeInSine

circle()

static circle(t)

A circular function.

http://easings.net/#easeInCirc

exp()

static exp(t)

An exponential function.

http://easings.net/#easeInExpo

elastic()

static elastic(bounciness)

A basic elastic interaction, similar to a spring oscillating back and forth.

Default bounciness is 1, which overshoots a little bit once. 0 bounciness doesn't overshoot at all, and bounciness of N > 1 will overshoot about N times.

http://easings.net/#easeInElastic

back()

static back(s)

Use with Animated.parallel() to create a basic effect where the object animates back slightly as the animation starts.

bounce()

static bounce(t)

Provides a basic bouncing effect.

http://easings.net/#easeInBounce

bezier()

static bezier(x1, y1, x2, y2)

Provides a cubic bezier curve, equivalent to CSS Transitions' transition-timing-function.

A useful tool to visualize cubic bezier curves can be found at http://cubic-bezier.com/

in()

static in easing;

Runs an easing function forwards.

out()

static out(easing)

Runs an easing function backwards.

inOut()

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.

Edit this page
Last updated on
- + diff --git a/docs/0.60/enviroment-setup.html b/docs/0.60/enviroment-setup.html index dd7ee441617..b020aaa5618 100644 --- a/docs/0.60/enviroment-setup.html +++ b/docs/0.60/enviroment-setup.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
cd AwesomeProject
npm start # you can also use: expo start

This will start a development server for you.

Running your React Native application

Install the Expo client app on your iOS or Android phone and connect to the same wireless network as your computer. On Android, use the Expo app to scan the QR code from your terminal to open your project. On iOS, use the built-in QR code scanner of the Camera app.

Modifying your app

Now that you have successfully run the app, let's modify it. Open App.js in your text editor of choice and edit some lines. The application should reload automatically once you save your changes.

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

Expo also has docs you can reference if you have questions specific to the tool. You can also ask for help at Expo forums.

These tools help you get started quickly, but before committing to building your app with Expo CLI, read about the limitations.

If you have a problem with Expo, before creating a new issue, please see if there's an existing issue about it:

If you're curious to learn more about React Native, check out the Introduction to React Native.

Running your app on a simulator or virtual device

Expo CLI allows you to run your React Native app on a physical device without setting up a development environment. If you want to run your app on the iOS Simulator or an Android Virtual Device, please refer to the instructions for "React Native CLI Quickstart" to learn how to install Xcode or set up your Android development environment.

Once you've set these up, you can launch your app on an Android Virtual Device by running npm run android, or on the iOS Simulator by running npm run ios (macOS only).

Caveats

Because you don't build any native code when using Expo to create a project, it's not possible to include custom native modules beyond the React Native APIs and components that are available in the Expo client app.

If you know that you'll eventually need to include your own native code, Expo is still a good way to get started. In that case you'll need to "eject" eventually to create your own native builds. If you do eject, the "React Native CLI Quickstart" instructions will be required to continue working on your project.

Expo CLI configures your project to use the most recent React Native version that is supported by the Expo client app. The Expo client app usually gains support for a given React Native version about a week after the React Native version is released as stable. You can check this document to find out what versions are supported.

If you're integrating React Native into an existing project, you'll want to skip Expo CLI and go directly to setting up the native build environment. Select "React Native CLI Quickstart" above for instructions on configuring a native build environment for React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.60/enviroment-setup/index.html b/docs/0.60/enviroment-setup/index.html index dd7ee441617..b020aaa5618 100644 --- a/docs/0.60/enviroment-setup/index.html +++ b/docs/0.60/enviroment-setup/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
cd AwesomeProject
npm start # you can also use: expo start

This will start a development server for you.

Running your React Native application

Install the Expo client app on your iOS or Android phone and connect to the same wireless network as your computer. On Android, use the Expo app to scan the QR code from your terminal to open your project. On iOS, use the built-in QR code scanner of the Camera app.

Modifying your app

Now that you have successfully run the app, let's modify it. Open App.js in your text editor of choice and edit some lines. The application should reload automatically once you save your changes.

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

Expo also has docs you can reference if you have questions specific to the tool. You can also ask for help at Expo forums.

These tools help you get started quickly, but before committing to building your app with Expo CLI, read about the limitations.

If you have a problem with Expo, before creating a new issue, please see if there's an existing issue about it:

If you're curious to learn more about React Native, check out the Introduction to React Native.

Running your app on a simulator or virtual device

Expo CLI allows you to run your React Native app on a physical device without setting up a development environment. If you want to run your app on the iOS Simulator or an Android Virtual Device, please refer to the instructions for "React Native CLI Quickstart" to learn how to install Xcode or set up your Android development environment.

Once you've set these up, you can launch your app on an Android Virtual Device by running npm run android, or on the iOS Simulator by running npm run ios (macOS only).

Caveats

Because you don't build any native code when using Expo to create a project, it's not possible to include custom native modules beyond the React Native APIs and components that are available in the Expo client app.

If you know that you'll eventually need to include your own native code, Expo is still a good way to get started. In that case you'll need to "eject" eventually to create your own native builds. If you do eject, the "React Native CLI Quickstart" instructions will be required to continue working on your project.

Expo CLI configures your project to use the most recent React Native version that is supported by the Expo client app. The Expo client app usually gains support for a given React Native version about a week after the React Native version is released as stable. You can check this document to find out what versions are supported.

If you're integrating React Native into an existing project, you'll want to skip Expo CLI and go directly to setting up the native build environment. Select "React Native CLI Quickstart" above for instructions on configuring a native build environment for React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.60/fast-refresh.html b/docs/0.60/fast-refresh.html index 300d799d659..922163efd13 100644 --- a/docs/0.60/fast-refresh.html +++ b/docs/0.60/fast-refresh.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Fast Refresh

Fast Refresh is a React Native feature that allows you to get near-instant feedback for changes in your React components. Fast Refresh is enabled by default, and you can toggle "Enable Fast Refresh" in the React Native developer menu. With Fast Refresh enabled, most edits should be visible within a second or two.

How It Works

  • If you edit a module that only exports React component(s), Fast Refresh will update the code only for that module, and re-render your component. You can edit anything in that file, including styles, rendering logic, event handlers, or effects.
  • If you edit a module with exports that aren't React components, Fast Refresh will re-run both that module, and the other modules importing it. So if both Button.js and Modal.js import Theme.js, editing Theme.js will update both components.
  • Finally, if you edit a file that's imported by modules outside of the React tree, Fast Refresh will fall back to doing a full reload. You might have a file which renders a React component but also exports a value that is imported by a non-React component. For example, maybe your component also exports a constant, and a non-React utility module imports it. In that case, consider migrating the query to a separate file and importing it into both files. This will re-enable Fast Refresh to work. Other cases can usually be solved in a similar way.

Error Resilience

If you make a syntax error during a Fast Refresh session, you can fix it and save the file again. The redbox will disappear. Modules with syntax errors are prevented from running, so you won't need to reload the app.

If you make a runtime error during the module initialization (for example, typing Style.create instead of StyleSheet.create), the Fast Refresh session will continue once you fix the error. The redbox will disappear, and the module will be updated.

If you make a mistake that leads to a runtime error inside your component, the Fast Refresh session will also continue after you fix the error. In that case, React will remount your application using the updated code.

If you have error boundaries in your app (which is a good idea for graceful failures in production), they will retry rendering on the next edit after a redbox. In that sense, having an error boundary can prevent you from always getting kicked out to the root app screen. However, keep in mind that error boundaries shouldn't be too granular. They are used by React in production, and should always be designed intentionally.

Limitations

Fast Refresh tries to preserve local React state in the component you're editing, but only if it's safe to do so. Here's a few reasons why you might see local state being reset on every edit to a file:

  • Local state is not preserved for class components (only function components and Hooks preserve state).
  • The module you're editing might have other exports in addition to a React component.
  • Sometimes, a module would export the result of calling higher-order component like createNavigationContainer(MyScreen). If the returned component is a class, state will be reset.

In the longer term, as more of your codebase moves to function components and Hooks, you can expect state to be preserved in more cases.

Tips

  • Fast Refresh preserves React local state in function components (and Hooks) by default.
  • Sometimes you might want to force the state to be reset, and a component to be remounted. For example, this can be handy if you're tweaking an animation that only happens on mount. To do this, you can add // @refresh reset anywhere in the file you're editing. This directive is local to the file, and instructs Fast Refresh to remount components defined in that file on every edit.

Fast Refresh and Hooks

When possible, Fast Refresh attempts to preserve the state of your component between edits. In particular, useState and useRef preserve their previous values as long as you don't change their arguments or the order of the Hook calls.

Hooks with dependencies—such as useEffect, useMemo, and useCallback—will always update during Fast Refresh. Their list of dependencies will be ignored while Fast Refresh is happening.

For example, when you edit useMemo(() => x * 2, [x]) to useMemo(() => x * 10, [x]), it will re-run even though x (the dependency) has not changed. If React didn't do that, your edit wouldn't reflect on the screen!

Sometimes, this can lead to unexpected results. For example, even a useEffect with an empty array of dependencies would still re-run once during Fast Refresh. However, writing code resilient to an occasional re-running of useEffect is a good practice even without Fast Refresh. This makes it easier for you to later introduce new dependencies to it.

Edit this page
Last updated on
- + diff --git a/docs/0.60/fast-refresh/index.html b/docs/0.60/fast-refresh/index.html index 300d799d659..922163efd13 100644 --- a/docs/0.60/fast-refresh/index.html +++ b/docs/0.60/fast-refresh/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Fast Refresh

Fast Refresh is a React Native feature that allows you to get near-instant feedback for changes in your React components. Fast Refresh is enabled by default, and you can toggle "Enable Fast Refresh" in the React Native developer menu. With Fast Refresh enabled, most edits should be visible within a second or two.

How It Works

  • If you edit a module that only exports React component(s), Fast Refresh will update the code only for that module, and re-render your component. You can edit anything in that file, including styles, rendering logic, event handlers, or effects.
  • If you edit a module with exports that aren't React components, Fast Refresh will re-run both that module, and the other modules importing it. So if both Button.js and Modal.js import Theme.js, editing Theme.js will update both components.
  • Finally, if you edit a file that's imported by modules outside of the React tree, Fast Refresh will fall back to doing a full reload. You might have a file which renders a React component but also exports a value that is imported by a non-React component. For example, maybe your component also exports a constant, and a non-React utility module imports it. In that case, consider migrating the query to a separate file and importing it into both files. This will re-enable Fast Refresh to work. Other cases can usually be solved in a similar way.

Error Resilience

If you make a syntax error during a Fast Refresh session, you can fix it and save the file again. The redbox will disappear. Modules with syntax errors are prevented from running, so you won't need to reload the app.

If you make a runtime error during the module initialization (for example, typing Style.create instead of StyleSheet.create), the Fast Refresh session will continue once you fix the error. The redbox will disappear, and the module will be updated.

If you make a mistake that leads to a runtime error inside your component, the Fast Refresh session will also continue after you fix the error. In that case, React will remount your application using the updated code.

If you have error boundaries in your app (which is a good idea for graceful failures in production), they will retry rendering on the next edit after a redbox. In that sense, having an error boundary can prevent you from always getting kicked out to the root app screen. However, keep in mind that error boundaries shouldn't be too granular. They are used by React in production, and should always be designed intentionally.

Limitations

Fast Refresh tries to preserve local React state in the component you're editing, but only if it's safe to do so. Here's a few reasons why you might see local state being reset on every edit to a file:

  • Local state is not preserved for class components (only function components and Hooks preserve state).
  • The module you're editing might have other exports in addition to a React component.
  • Sometimes, a module would export the result of calling higher-order component like createNavigationContainer(MyScreen). If the returned component is a class, state will be reset.

In the longer term, as more of your codebase moves to function components and Hooks, you can expect state to be preserved in more cases.

Tips

  • Fast Refresh preserves React local state in function components (and Hooks) by default.
  • Sometimes you might want to force the state to be reset, and a component to be remounted. For example, this can be handy if you're tweaking an animation that only happens on mount. To do this, you can add // @refresh reset anywhere in the file you're editing. This directive is local to the file, and instructs Fast Refresh to remount components defined in that file on every edit.

Fast Refresh and Hooks

When possible, Fast Refresh attempts to preserve the state of your component between edits. In particular, useState and useRef preserve their previous values as long as you don't change their arguments or the order of the Hook calls.

Hooks with dependencies—such as useEffect, useMemo, and useCallback—will always update during Fast Refresh. Their list of dependencies will be ignored while Fast Refresh is happening.

For example, when you edit useMemo(() => x * 2, [x]) to useMemo(() => x * 10, [x]), it will re-run even though x (the dependency) has not changed. If React didn't do that, your edit wouldn't reflect on the screen!

Sometimes, this can lead to unexpected results. For example, even a useEffect with an empty array of dependencies would still re-run once during Fast Refresh. However, writing code resilient to an occasional re-running of useEffect is a good practice even without Fast Refresh. This makes it easier for you to later introduce new dependencies to it.

Edit this page
Last updated on
- + diff --git a/docs/0.60/flatlist.html b/docs/0.60/flatlist.html index c437a4d3f3f..a406d440a18 100644 --- a/docs/0.60/flatlist.html +++ b/docs/0.60/flatlist.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
this.viewabilityConfig = {
waitForInteraction: true,
viewAreaCoveragePercentThreshold: 95
}
}
<FlatList
viewabilityConfig={this.viewabilityConfig}
...

minimumViewTime

Minimum amount of time (in milliseconds) that an item must be physically viewable before the viewability callback will be fired. A high number means that scrolling through content without stopping will not mark the content as viewable.

viewAreaCoveragePercentThreshold

Percent of viewport that must be covered for a partially occluded item to count as "viewable", 0-100. Fully visible items are always considered viewable. A value of 0 means that a single pixel in the viewport makes the item viewable, and a value of 100 means that an item must be either entirely visible or cover the entire viewport to count as viewable.

itemVisiblePercentThreshold

Similar to viewAreaCoveragePercentThreshold, but considers the percent of the item that is visible, rather than the fraction of the viewable area it covers.

waitForInteraction

Nothing is considered viewable until the user scrolls or recordInteraction is called after render.

viewabilityConfigCallbackPairs

List of ViewabilityConfig/onViewableItemsChanged pairs. A specific onViewableItemsChanged will be called when its corresponding ViewabilityConfig's conditions are met. See ViewabilityHelper.js for flow type and further documentation.

TypeRequired
array of ViewabilityConfigCallbackPairNo

Methods

scrollToEnd()

scrollToEnd([params]);

Scrolls to the end of the content. May be janky without getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectNoSee below.

Valid params keys are:

scrollToIndex()

scrollToIndex(params);

Scrolls to the item at the specified index such that it is positioned in the viewable area such that viewPosition 0 places it at the top, 1 at the bottom, and 0.5 centered in the middle.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

scrollToItem()

scrollToItem(params);

Requires linear scan through data - use scrollToIndex instead if possible.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

scrollToOffset()

scrollToOffset(params);

Scroll to a specific content pixel offset in the list.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

recordInteraction()

recordInteraction();

Tells the list an interaction has occurred, 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()

flashScrollIndicators();

Displays the scroll indicators momentarily.

getScrollResponder()

getScrollResponder();

Provides a handle to the underlying scroll responder.

getScrollableNode()

getScrollableNode();

Provides a handle to the underlying scroll node.

Edit this page
Last updated on
- + diff --git a/docs/0.60/flatlist/index.html b/docs/0.60/flatlist/index.html index c437a4d3f3f..a406d440a18 100644 --- a/docs/0.60/flatlist/index.html +++ b/docs/0.60/flatlist/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
this.viewabilityConfig = {
waitForInteraction: true,
viewAreaCoveragePercentThreshold: 95
}
}
<FlatList
viewabilityConfig={this.viewabilityConfig}
...

minimumViewTime

Minimum amount of time (in milliseconds) that an item must be physically viewable before the viewability callback will be fired. A high number means that scrolling through content without stopping will not mark the content as viewable.

viewAreaCoveragePercentThreshold

Percent of viewport that must be covered for a partially occluded item to count as "viewable", 0-100. Fully visible items are always considered viewable. A value of 0 means that a single pixel in the viewport makes the item viewable, and a value of 100 means that an item must be either entirely visible or cover the entire viewport to count as viewable.

itemVisiblePercentThreshold

Similar to viewAreaCoveragePercentThreshold, but considers the percent of the item that is visible, rather than the fraction of the viewable area it covers.

waitForInteraction

Nothing is considered viewable until the user scrolls or recordInteraction is called after render.

viewabilityConfigCallbackPairs

List of ViewabilityConfig/onViewableItemsChanged pairs. A specific onViewableItemsChanged will be called when its corresponding ViewabilityConfig's conditions are met. See ViewabilityHelper.js for flow type and further documentation.

TypeRequired
array of ViewabilityConfigCallbackPairNo

Methods

scrollToEnd()

scrollToEnd([params]);

Scrolls to the end of the content. May be janky without getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectNoSee below.

Valid params keys are:

scrollToIndex()

scrollToIndex(params);

Scrolls to the item at the specified index such that it is positioned in the viewable area such that viewPosition 0 places it at the top, 1 at the bottom, and 0.5 centered in the middle.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

scrollToItem()

scrollToItem(params);

Requires linear scan through data - use scrollToIndex instead if possible.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

scrollToOffset()

scrollToOffset(params);

Scroll to a specific content pixel offset in the list.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

recordInteraction()

recordInteraction();

Tells the list an interaction has occurred, 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()

flashScrollIndicators();

Displays the scroll indicators momentarily.

getScrollResponder()

getScrollResponder();

Provides a handle to the underlying scroll responder.

getScrollableNode()

getScrollableNode();

Provides a handle to the underlying scroll node.

Edit this page
Last updated on
- + diff --git a/docs/0.60/flexbox.html b/docs/0.60/flexbox.html index d14d776dd88..bf62660ac6c 100644 --- a/docs/0.60/flexbox.html +++ b/docs/0.60/flexbox.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

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 flexDirection defaulting to column instead of row, and the flex parameter only supporting a single number.

Flex

flex will define how your items are going to “fill” over the available space along your main axis. Space will be divided according to each element's flex property.

In the following example the red, yellow and the green views are all children in the container view that has flex: 1 set. The red view uses flex: 1 , the yellow view uses flex: 2 and the green view uses flex: 3 . 1+2+3 = 6 which means that the red view will get 1/6 of the space, the yellow 2/6 of the space and the green 3/6 of the space.

Flex

Flex Direction

flexDirection controls the direction in which the children of a node are laid out. This is also referred to as the main axis. The cross axis is the axis perpendicular to the main axis, or the axis which the wrapping lines are laid out in.

  • row Align children from left to right. If wrapping is enabled then the next line will start under the first item on the left of the container.

  • column (default value) Align children from top to bottom. If wrapping is enabled then the next line will start to the left first item on the top of the container.

  • row-reverse Align children from right to left. If wrapping is enabled then the next line will start under the first item on the right of the container.

  • column-reverse Align children from bottom to top. If wrapping is enabled then the next line will start to the left first item on the bottom of the container.

LEARN MORE HERE

Flex Direction

Layout Direction

Layout direction specifies the direction in which children and text in a hierarchy should be laid out. Layout direction also affects what edge start and end refer to. By default React Native lays out with LTR layout direction. In this mode start refers to left and end refers to right.

  • LTR (default value) Text and children are laid out from left to right. Margin and padding applied the start of an element are applied on the left side.

  • RTL Text and children are laid out from right to left. Margin and padding applied the start of an element are applied on the right side.

Justify Content

justifyContent describes how to align children within the main axis of their container. For example, you can use this property to center a child horizontally within a container with flexDirection set to row or vertically within a container with flexDirection set to column.

  • flex-start(default value) Align children of a container to the start of the container's main axis.

  • flex-end Align children of a container to the end of the container's main axis.

  • center Align children of a container in the center of the container's main axis.

  • space-between Evenly space of children across the container's main axis, distributing remaining space between the children.

  • space-around Evenly space of children across the container's main axis, distributing remaining space around the children. Compared to space-between using space-around will result in space being distributed to the beginning of the first child and end of the last child.

  • space-evenly Evenly distributed within the alignment container along the main axis. The spacing between each pair of adjacent items, the main-start edge and the first item, and the main-end edge and the last item, are all exactly the same.

LEARN MORE HERE

Justify Content

Align Items

alignItems describes how to align children along the cross axis of their container. Align items is very similar to justifyContent but instead of applying to the main axis, alignItems applies to the cross axis.

  • stretch (default value) Stretch children of a container to match the height of the container's cross axis.

  • flex-start Align children of a container to the start of the container's cross axis.

  • flex-end Align children of a container to the end of the container's cross axis.

  • center Align children of a container in the center of the container's cross axis.

  • baseline Align children of a container along a common baseline. Individual children can be set to be the reference baseline for their parents.

For stretch to have an effect, children must not have a fixed dimension along the secondary axis. In the following example, setting alignItems: stretch does nothing until the width: 50 is removed from the children.

LEARN MORE HERE

Align Items

Align Self

alignSelf has the same options and effect as alignItems but instead of affecting the children within a container, you can apply this property to a single child to change its alignment within its parent. alignSelf overrides any option set by the parent with alignItems.

Align Self

Align Content

alignContent defines the distribution of lines along the cross-axis. This only has effect when items are wrapped to multiple lines using flexWrap.

  • flex-start (default value) Align wrapped lines to the start of the container's cross axis.

  • flex-end Align wrapped lines to the end of the container's cross axis.

  • stretch wrapped lines to match the height of the container's cross axis.

  • center Align wrapped lines in the center of the container's cross axis.

  • space-between Evenly space wrapped lines across the container's main axis, distributing remaining space between the lines.

  • space-around Evenly space wrapped lines across the container's main axis, distributing remaining space around the lines. Compared to space between using space around will result in space being distributed to the begining of the first lines and end of the last line.

LEARN MORE HERE

Align Content

Flex Wrap

The flexWrap property is set on containers and controls what happens when children overflow the size of the container along the main axis. By default children are forced into a single line (which can shrink elements). If wrapping is allowed items are wrapped into multiple lines along the main axis if needed.

When wrapping lines alignContent can be used to specify how the lines are placed in the container. learn more here

Flex Wrap

Flex Basis, Grow, and Shrink

  • flexGrow describes how any space within a container should be distributed among its children along the main axis. After laying out its children, a container will distribute any remaining space according to the flex grow values specified by its children.

    flexGrow accepts any floating point value >= 0, with 0 being the default value. A container will distribute any remaining space among its children weighted by the child’s flex grow value.

  • flexShrink describes how to shrink children along the main axis in the case that the total size of the children overflow the size of the container on the main axis. Flex shrink is very similar to flex grow and can be thought of in the same way if any overflowing size is considered to be negative remaining space. These two properties also work well together by allowing children to grow and shrink as needed.

    Flex shrink accepts any floating point value >= 0, with 1 being the default value. A container will shrink its children weighted by the child’s flex shrink value.

  • flexBasis is an axis-independent way of providing the default size of an item along the main axis. Setting the flex basis of a child is similar to setting the width of that child if its parent is a container with flexDirection: row or setting the height of a child if its parent is a container with flexDirection: column. The flex basis of an item is the default size of that item, the size of the item before any flex grow and flex shrink calculations are performed.

LEARN MORE HERE

Width and Height

The width property in Yoga specifies the width of the element's content area. Similarly height property specifies the height of the element's content area.

Both width and height can take following values:

  • auto Is the default Value, React Native calculates the width/height for the element based on its content, whether that is other children, text, or an image.

  • pixels Defines the width/height in absolute pixels. Depending on other styles set on the component, this may or may not be the final dimension of the node.

  • percentage Defines the width or height in percentage of its parent's width or height respectively.

Absolute & Relative Layout

The position type of an element defines how it is positioned within its parent.

relative (default value) By default an element is positioned relatively. This means an element is positioned according to the normal flow of the layout, and then offset relative to that position based on the values of top, right, bottom, and left. The offset does not affect the position of any sibling or parent elements.

absolute When positioned absolutely an element doesn't take part in the normal layout flow. It is instead laid out independent of its siblings. The position is determined based on the top, right, bottom, and left values.

Absolute & Relative Layoutp

Going Deeper

Check out the interactive yoga playground that you can use to get a better understanding of flexbox.

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.

See some examples from Wix Engineers:

Edit this page
Last updated on
- + diff --git a/docs/0.60/flexbox/index.html b/docs/0.60/flexbox/index.html index d14d776dd88..bf62660ac6c 100644 --- a/docs/0.60/flexbox/index.html +++ b/docs/0.60/flexbox/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

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 flexDirection defaulting to column instead of row, and the flex parameter only supporting a single number.

Flex

flex will define how your items are going to “fill” over the available space along your main axis. Space will be divided according to each element's flex property.

In the following example the red, yellow and the green views are all children in the container view that has flex: 1 set. The red view uses flex: 1 , the yellow view uses flex: 2 and the green view uses flex: 3 . 1+2+3 = 6 which means that the red view will get 1/6 of the space, the yellow 2/6 of the space and the green 3/6 of the space.

Flex

Flex Direction

flexDirection controls the direction in which the children of a node are laid out. This is also referred to as the main axis. The cross axis is the axis perpendicular to the main axis, or the axis which the wrapping lines are laid out in.

  • row Align children from left to right. If wrapping is enabled then the next line will start under the first item on the left of the container.

  • column (default value) Align children from top to bottom. If wrapping is enabled then the next line will start to the left first item on the top of the container.

  • row-reverse Align children from right to left. If wrapping is enabled then the next line will start under the first item on the right of the container.

  • column-reverse Align children from bottom to top. If wrapping is enabled then the next line will start to the left first item on the bottom of the container.

LEARN MORE HERE

Flex Direction

Layout Direction

Layout direction specifies the direction in which children and text in a hierarchy should be laid out. Layout direction also affects what edge start and end refer to. By default React Native lays out with LTR layout direction. In this mode start refers to left and end refers to right.

  • LTR (default value) Text and children are laid out from left to right. Margin and padding applied the start of an element are applied on the left side.

  • RTL Text and children are laid out from right to left. Margin and padding applied the start of an element are applied on the right side.

Justify Content

justifyContent describes how to align children within the main axis of their container. For example, you can use this property to center a child horizontally within a container with flexDirection set to row or vertically within a container with flexDirection set to column.

  • flex-start(default value) Align children of a container to the start of the container's main axis.

  • flex-end Align children of a container to the end of the container's main axis.

  • center Align children of a container in the center of the container's main axis.

  • space-between Evenly space of children across the container's main axis, distributing remaining space between the children.

  • space-around Evenly space of children across the container's main axis, distributing remaining space around the children. Compared to space-between using space-around will result in space being distributed to the beginning of the first child and end of the last child.

  • space-evenly Evenly distributed within the alignment container along the main axis. The spacing between each pair of adjacent items, the main-start edge and the first item, and the main-end edge and the last item, are all exactly the same.

LEARN MORE HERE

Justify Content

Align Items

alignItems describes how to align children along the cross axis of their container. Align items is very similar to justifyContent but instead of applying to the main axis, alignItems applies to the cross axis.

  • stretch (default value) Stretch children of a container to match the height of the container's cross axis.

  • flex-start Align children of a container to the start of the container's cross axis.

  • flex-end Align children of a container to the end of the container's cross axis.

  • center Align children of a container in the center of the container's cross axis.

  • baseline Align children of a container along a common baseline. Individual children can be set to be the reference baseline for their parents.

For stretch to have an effect, children must not have a fixed dimension along the secondary axis. In the following example, setting alignItems: stretch does nothing until the width: 50 is removed from the children.

LEARN MORE HERE

Align Items

Align Self

alignSelf has the same options and effect as alignItems but instead of affecting the children within a container, you can apply this property to a single child to change its alignment within its parent. alignSelf overrides any option set by the parent with alignItems.

Align Self

Align Content

alignContent defines the distribution of lines along the cross-axis. This only has effect when items are wrapped to multiple lines using flexWrap.

  • flex-start (default value) Align wrapped lines to the start of the container's cross axis.

  • flex-end Align wrapped lines to the end of the container's cross axis.

  • stretch wrapped lines to match the height of the container's cross axis.

  • center Align wrapped lines in the center of the container's cross axis.

  • space-between Evenly space wrapped lines across the container's main axis, distributing remaining space between the lines.

  • space-around Evenly space wrapped lines across the container's main axis, distributing remaining space around the lines. Compared to space between using space around will result in space being distributed to the begining of the first lines and end of the last line.

LEARN MORE HERE

Align Content

Flex Wrap

The flexWrap property is set on containers and controls what happens when children overflow the size of the container along the main axis. By default children are forced into a single line (which can shrink elements). If wrapping is allowed items are wrapped into multiple lines along the main axis if needed.

When wrapping lines alignContent can be used to specify how the lines are placed in the container. learn more here

Flex Wrap

Flex Basis, Grow, and Shrink

  • flexGrow describes how any space within a container should be distributed among its children along the main axis. After laying out its children, a container will distribute any remaining space according to the flex grow values specified by its children.

    flexGrow accepts any floating point value >= 0, with 0 being the default value. A container will distribute any remaining space among its children weighted by the child’s flex grow value.

  • flexShrink describes how to shrink children along the main axis in the case that the total size of the children overflow the size of the container on the main axis. Flex shrink is very similar to flex grow and can be thought of in the same way if any overflowing size is considered to be negative remaining space. These two properties also work well together by allowing children to grow and shrink as needed.

    Flex shrink accepts any floating point value >= 0, with 1 being the default value. A container will shrink its children weighted by the child’s flex shrink value.

  • flexBasis is an axis-independent way of providing the default size of an item along the main axis. Setting the flex basis of a child is similar to setting the width of that child if its parent is a container with flexDirection: row or setting the height of a child if its parent is a container with flexDirection: column. The flex basis of an item is the default size of that item, the size of the item before any flex grow and flex shrink calculations are performed.

LEARN MORE HERE

Width and Height

The width property in Yoga specifies the width of the element's content area. Similarly height property specifies the height of the element's content area.

Both width and height can take following values:

  • auto Is the default Value, React Native calculates the width/height for the element based on its content, whether that is other children, text, or an image.

  • pixels Defines the width/height in absolute pixels. Depending on other styles set on the component, this may or may not be the final dimension of the node.

  • percentage Defines the width or height in percentage of its parent's width or height respectively.

Absolute & Relative Layout

The position type of an element defines how it is positioned within its parent.

relative (default value) By default an element is positioned relatively. This means an element is positioned according to the normal flow of the layout, and then offset relative to that position based on the values of top, right, bottom, and left. The offset does not affect the position of any sibling or parent elements.

absolute When positioned absolutely an element doesn't take part in the normal layout flow. It is instead laid out independent of its siblings. The position is determined based on the top, right, bottom, and left values.

Absolute & Relative Layoutp

Going Deeper

Check out the interactive yoga playground that you can use to get a better understanding of flexbox.

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.

See some examples from Wix Engineers:

Edit this page
Last updated on
- + diff --git a/docs/0.60/geolocation.html b/docs/0.60/geolocation.html index 32ad29cd7df..636ee01560e 100644 --- a/docs/0.60/geolocation.html +++ b/docs/0.60/geolocation.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

🚧 Geolocation

Deprecated. Use @react-native-community/geolocation instead.

The Geolocation API extends the Geolocation web spec.

As a browser polyfill, this API is available through the navigator.geolocation global - you do not need to import it.

On Android, this uses the android.location API. This API is not recommended by Google because it is less accurate and slower than the recommended Google Location Services API. In order to use it with React Native, use the react-native-geolocation-service module.

Configuration and Permissions

iOS

You need to include the NSLocationWhenInUseUsageDescription key in Info.plist to enable geolocation when using the app. Geolocation is enabled by default when you create a project with react-native init.

In order to enable geolocation in the background, you need to include the 'NSLocationAlwaysUsageDescription' key in Info.plist and add location as a background mode in the 'Capabilities' tab in Xcode.

If you are using CocoaPods for React Native, make sure to include the RCTGeolocation sub-podspec.

Android

To request access to location, you need to add the following line to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Android API >= 18 Positions will also contain a mocked boolean to indicate if position was created from a mock provider.

Android API >= 23 Requires an additional step to check for, and request the ACCESS_FINE_LOCATION permission using the PermissionsAndroid API. Failure to do so may result in a hard crash.

Methods

Reference

Methods

setRNConfiguration()

geolocation.setRNConfiguration(config);

Sets configuration options that will be used in all location requests.

Parameters:

NameTypeRequiredDescription
configobjectYesSee below.

Supported options:

  • skipPermissionRequests (boolean, iOS-only) - Defaults to false. If true, you must request permissions before using Geolocation APIs.

requestAuthorization()

geolocation.requestAuthorization();

Request suitable Location permission based on the key configured on pList. If NSLocationAlwaysUsageDescription is set, it will request Always authorization, although if NSLocationWhenInUseUsageDescription is set, it will request InUse authorization.

getCurrentPosition()

geolocation.getCurrentPosition(
geo_success,
[geo_error],
[geo_options]
);

Invokes the success callback once with the latest location info.

Parameters:

NameTypeRequiredDescription
geo_successfunctionYesInvoked with latest location info.
geo_errorfunctionNoInvoked whenever an error is encountered.
geo_optionsobjectNoSee below.

Supported options:

  • timeout (ms) - Is a positive value representing the maximum length of time (in milliseconds) the device is allowed to take in order to return a position. Defaults to INFINITY.
  • maximumAge (ms) - Is a positive value indicating the maximum age in milliseconds of a possible cached position that is acceptable to return. If set to 0, it means that the device cannot use a cached position and must attempt to retrieve the real current position. If set to Infinity the device will always return a cached position regardless of its age. Defaults to INFINITY.
  • enableHighAccuracy (bool) - Is a boolean representing if to use GPS or not. If set to true, a GPS position will be requested. If set to false, a WIFI location will be requested.

watchPosition()

geolocation.watchPosition(success, [error], [options]);

Invokes the success callback whenever the location changes. Returns a watchId (number).

Parameters:

NameTypeRequiredDescription
successfunctionYesInvoked whenever the location changes.
errorfunctionNoInvoked whenever an error is encountered.
optionsobjectNoSee below.

Supported options:

  • timeout (ms) - Is a positive value representing the maximum length of time (in milliseconds) the device is allowed to take in order to return a position. Defaults to INFINITY.
  • maximumAge (ms) - Is a positive value indicating the maximum age in milliseconds of a possible cached position that is acceptable to return. If set to 0, it means that the device cannot use a cached position and must attempt to retrieve the real current position. If set to Infinity the device will always return a cached position regardless of its age. Defaults to INFINITY.
  • enableHighAccuracy (bool) - Is a boolean representing if to use GPS or not. If set to true, a GPS position will be requested. If set to false, a WIFI location will be requested.
  • distanceFilter (m) - The minimum distance from the previous location to exceed before returning a new location. Set to 0 to not filter locations. Defaults to 100m.
  • useSignificantChanges (bool) - Uses the battery-efficient native significant changes APIs to return locations. Locations will only be returned when the device detects a significant distance has been breached. Defaults to FALSE.

clearWatch()

geolocation.clearWatch(watchID);

Parameters:

NameTypeRequiredDescription
watchIDnumberYesId as returned by watchPosition().

stopObserving()

geolocation.stopObserving();

Stops observing for device location changes. In addition, it removes all listeners previously registered.

Notice that this method has only effect if the geolocation.watchPosition(successCallback, errorCallback) method was previously invoked.

Edit this page
Last updated on
- + diff --git a/docs/0.60/geolocation/index.html b/docs/0.60/geolocation/index.html index 32ad29cd7df..636ee01560e 100644 --- a/docs/0.60/geolocation/index.html +++ b/docs/0.60/geolocation/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

🚧 Geolocation

Deprecated. Use @react-native-community/geolocation instead.

The Geolocation API extends the Geolocation web spec.

As a browser polyfill, this API is available through the navigator.geolocation global - you do not need to import it.

On Android, this uses the android.location API. This API is not recommended by Google because it is less accurate and slower than the recommended Google Location Services API. In order to use it with React Native, use the react-native-geolocation-service module.

Configuration and Permissions

iOS

You need to include the NSLocationWhenInUseUsageDescription key in Info.plist to enable geolocation when using the app. Geolocation is enabled by default when you create a project with react-native init.

In order to enable geolocation in the background, you need to include the 'NSLocationAlwaysUsageDescription' key in Info.plist and add location as a background mode in the 'Capabilities' tab in Xcode.

If you are using CocoaPods for React Native, make sure to include the RCTGeolocation sub-podspec.

Android

To request access to location, you need to add the following line to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Android API >= 18 Positions will also contain a mocked boolean to indicate if position was created from a mock provider.

Android API >= 23 Requires an additional step to check for, and request the ACCESS_FINE_LOCATION permission using the PermissionsAndroid API. Failure to do so may result in a hard crash.

Methods

Reference

Methods

setRNConfiguration()

geolocation.setRNConfiguration(config);

Sets configuration options that will be used in all location requests.

Parameters:

NameTypeRequiredDescription
configobjectYesSee below.

Supported options:

  • skipPermissionRequests (boolean, iOS-only) - Defaults to false. If true, you must request permissions before using Geolocation APIs.

requestAuthorization()

geolocation.requestAuthorization();

Request suitable Location permission based on the key configured on pList. If NSLocationAlwaysUsageDescription is set, it will request Always authorization, although if NSLocationWhenInUseUsageDescription is set, it will request InUse authorization.

getCurrentPosition()

geolocation.getCurrentPosition(
geo_success,
[geo_error],
[geo_options]
);

Invokes the success callback once with the latest location info.

Parameters:

NameTypeRequiredDescription
geo_successfunctionYesInvoked with latest location info.
geo_errorfunctionNoInvoked whenever an error is encountered.
geo_optionsobjectNoSee below.

Supported options:

  • timeout (ms) - Is a positive value representing the maximum length of time (in milliseconds) the device is allowed to take in order to return a position. Defaults to INFINITY.
  • maximumAge (ms) - Is a positive value indicating the maximum age in milliseconds of a possible cached position that is acceptable to return. If set to 0, it means that the device cannot use a cached position and must attempt to retrieve the real current position. If set to Infinity the device will always return a cached position regardless of its age. Defaults to INFINITY.
  • enableHighAccuracy (bool) - Is a boolean representing if to use GPS or not. If set to true, a GPS position will be requested. If set to false, a WIFI location will be requested.

watchPosition()

geolocation.watchPosition(success, [error], [options]);

Invokes the success callback whenever the location changes. Returns a watchId (number).

Parameters:

NameTypeRequiredDescription
successfunctionYesInvoked whenever the location changes.
errorfunctionNoInvoked whenever an error is encountered.
optionsobjectNoSee below.

Supported options:

  • timeout (ms) - Is a positive value representing the maximum length of time (in milliseconds) the device is allowed to take in order to return a position. Defaults to INFINITY.
  • maximumAge (ms) - Is a positive value indicating the maximum age in milliseconds of a possible cached position that is acceptable to return. If set to 0, it means that the device cannot use a cached position and must attempt to retrieve the real current position. If set to Infinity the device will always return a cached position regardless of its age. Defaults to INFINITY.
  • enableHighAccuracy (bool) - Is a boolean representing if to use GPS or not. If set to true, a GPS position will be requested. If set to false, a WIFI location will be requested.
  • distanceFilter (m) - The minimum distance from the previous location to exceed before returning a new location. Set to 0 to not filter locations. Defaults to 100m.
  • useSignificantChanges (bool) - Uses the battery-efficient native significant changes APIs to return locations. Locations will only be returned when the device detects a significant distance has been breached. Defaults to FALSE.

clearWatch()

geolocation.clearWatch(watchID);

Parameters:

NameTypeRequiredDescription
watchIDnumberYesId as returned by watchPosition().

stopObserving()

geolocation.stopObserving();

Stops observing for device location changes. In addition, it removes all listeners previously registered.

Notice that this method has only effect if the geolocation.watchPosition(successCallback, errorCallback) method was previously invoked.

Edit this page
Last updated on
- + diff --git a/docs/0.60/gesture-responder-system.html b/docs/0.60/gesture-responder-system.html index 6336c731c89..8e90ffde75d 100644 --- a/docs/0.60/gesture-responder-system.html +++ b/docs/0.60/gesture-responder-system.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

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.

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 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 happening
  • View.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 finger
  • View.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 release
  • View.props.onResponderTerminate: (evt) => {} - The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, 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:

  • nativeEvent
    • changedTouches - Array of all touch events that have changed since the last event
    • identifier - The ID of the touch
    • locationX - The X position of the touch, relative to the element
    • locationY - The Y position of the touch, relative to the element
    • pageX - The X position of the touch, relative to the root element
    • pageY - The Y position of the touch, relative to the root element
    • target - The node id of the element receiving the touch event
    • timestamp - A time identifier for the touch, useful for velocity calculation
    • touches - 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.

Edit this page
Last updated on
- + diff --git a/docs/0.60/gesture-responder-system/index.html b/docs/0.60/gesture-responder-system/index.html index 6336c731c89..8e90ffde75d 100644 --- a/docs/0.60/gesture-responder-system/index.html +++ b/docs/0.60/gesture-responder-system/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

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.

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 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 happening
  • View.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 finger
  • View.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 release
  • View.props.onResponderTerminate: (evt) => {} - The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, 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:

  • nativeEvent
    • changedTouches - Array of all touch events that have changed since the last event
    • identifier - The ID of the touch
    • locationX - The X position of the touch, relative to the element
    • locationY - The Y position of the touch, relative to the element
    • pageX - The X position of the touch, relative to the root element
    • pageY - The Y position of the touch, relative to the root element
    • target - The node id of the element receiving the touch event
    • timestamp - A time identifier for the touch, useful for velocity calculation
    • touches - 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.

Edit this page
Last updated on
- + diff --git a/docs/0.60/getting-started.html b/docs/0.60/getting-started.html index 53e1de4871b..b817c4960a0 100644 --- a/docs/0.60/getting-started.html +++ b/docs/0.60/getting-started.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Introduction

Welcome to the very start of your React Native journey! If you're looking for environment setup instructions, they've moved to [their own section](/docs/environment-setup). Continue reading for an introduction to the documentation, Native Components, React, and more!

Many different kinds of people use React Native: from advanced iOS developers to React beginners, to people getting started programming for the first time in their career. These docs were written for all learners, no matter their experience level or background.

How to use these docs

You can start here and read through these docs linearly like a book; or you can read the specific sections you need. Already familiar with React? You can skip that section—or read it for a light refresher.

Prerequisites

To work with React Native, you will need to have an understanding of JavaScript fundamentals. If you’re new to JavaScript or need a refresher, you can dive in or brush up at Mozilla Developer Network.

While we do our best to assume no prior knowledge of React, Android, or iOS development, these are valuable topics of study for the aspiring React Native developer. Where sensible, we have linked to resources and articles that go more in depth.

Interactive examples

This introduction lets you get started immediately in your browser with interactive examples like this one:

The above is a Snack Player. It’s a handy tool created by Expo to embed and run React Native projects and share how they render in platforms like Android and iOS. The code is live and editable, so you can play directly with it in your browser. Go ahead and try changing the "Try editing me!" text above to "Hello, world!"

Optionally, if you want to setup a local development environment, you can follow our guide to setting up your environment on your local machine and paste the code examples into your App.js file there. (If you are a web developer, you may already have a local environment set up for mobile browser testing!)

Function Components and Class Components

With React, you can make components using either classes or functions. Originally, class components were the only components that could have state. But since the introduction of React's Hooks API, you can add state and more to function components.

Hooks were introduced in React Native 0.59., and because Hooks are the future-facing way to write your React components, we wrote this introduction using function component examples. Where useful, we also cover class components under a toggle like so:

You can find more examples of class components in previous versions of this documentation.

Developer Notes

People from many different development backgrounds are learning React Native. You may have experience with a range of technologies, from web to Android to iOS and more. We try to write for developers from all backgrounds. Sometimes we provide explanations specific to one platform or another like so:

Web developers may be familiar with this concept.

Formatting

Menu paths are written in bold and use carets to navigate submenus. Example: Android Studio > Preferences

Now that you know how this guide works, it's time to get to know the foundation of React Native: Native Components.

Edit this page
Last updated on
- + diff --git a/docs/0.60/getting-started/index.html b/docs/0.60/getting-started/index.html index 53e1de4871b..b817c4960a0 100644 --- a/docs/0.60/getting-started/index.html +++ b/docs/0.60/getting-started/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Introduction

Welcome to the very start of your React Native journey! If you're looking for environment setup instructions, they've moved to [their own section](/docs/environment-setup). Continue reading for an introduction to the documentation, Native Components, React, and more!

Many different kinds of people use React Native: from advanced iOS developers to React beginners, to people getting started programming for the first time in their career. These docs were written for all learners, no matter their experience level or background.

How to use these docs

You can start here and read through these docs linearly like a book; or you can read the specific sections you need. Already familiar with React? You can skip that section—or read it for a light refresher.

Prerequisites

To work with React Native, you will need to have an understanding of JavaScript fundamentals. If you’re new to JavaScript or need a refresher, you can dive in or brush up at Mozilla Developer Network.

While we do our best to assume no prior knowledge of React, Android, or iOS development, these are valuable topics of study for the aspiring React Native developer. Where sensible, we have linked to resources and articles that go more in depth.

Interactive examples

This introduction lets you get started immediately in your browser with interactive examples like this one:

The above is a Snack Player. It’s a handy tool created by Expo to embed and run React Native projects and share how they render in platforms like Android and iOS. The code is live and editable, so you can play directly with it in your browser. Go ahead and try changing the "Try editing me!" text above to "Hello, world!"

Optionally, if you want to setup a local development environment, you can follow our guide to setting up your environment on your local machine and paste the code examples into your App.js file there. (If you are a web developer, you may already have a local environment set up for mobile browser testing!)

Function Components and Class Components

With React, you can make components using either classes or functions. Originally, class components were the only components that could have state. But since the introduction of React's Hooks API, you can add state and more to function components.

Hooks were introduced in React Native 0.59., and because Hooks are the future-facing way to write your React components, we wrote this introduction using function component examples. Where useful, we also cover class components under a toggle like so:

You can find more examples of class components in previous versions of this documentation.

Developer Notes

People from many different development backgrounds are learning React Native. You may have experience with a range of technologies, from web to Android to iOS and more. We try to write for developers from all backgrounds. Sometimes we provide explanations specific to one platform or another like so:

Web developers may be familiar with this concept.

Formatting

Menu paths are written in bold and use carets to navigate submenus. Example: Android Studio > Preferences

Now that you know how this guide works, it's time to get to know the foundation of React Native: Native Components.

Edit this page
Last updated on
- + diff --git a/docs/0.60/handling-text-input.html b/docs/0.60/handling-text-input.html index edb5b072d2e..169934c2fa1 100644 --- a/docs/0.60/handling-text-input.html +++ b/docs/0.60/handling-text-input.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Handling Text Input

TextInput is a Core Component that allows the user to enter text. It has an onChangeText prop that takes a function to be called every time the text changed, and an onSubmitEditing prop that takes a function to be called when the text is submitted.

For example, let's say that as the user types, you're translating their words into a different language. In this new language, every single word is written the same way: 🍕. So the sentence "Hello there Bob" would be translated as "🍕🍕🍕".

In this example, we store text in the state, because it changes over time.

There are a lot more things you might want to do with a text input. For example, you could validate the text inside while the user types. For more detailed examples, see the React docs on controlled components, or the reference docs for TextInput.

Text input is one of the ways the user interacts with the app. Next, let's look at another type of input and learn how to handle touches.

Edit this page
Last updated on
- + diff --git a/docs/0.60/handling-text-input/index.html b/docs/0.60/handling-text-input/index.html index edb5b072d2e..169934c2fa1 100644 --- a/docs/0.60/handling-text-input/index.html +++ b/docs/0.60/handling-text-input/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Handling Text Input

TextInput is a Core Component that allows the user to enter text. It has an onChangeText prop that takes a function to be called every time the text changed, and an onSubmitEditing prop that takes a function to be called when the text is submitted.

For example, let's say that as the user types, you're translating their words into a different language. In this new language, every single word is written the same way: 🍕. So the sentence "Hello there Bob" would be translated as "🍕🍕🍕".

In this example, we store text in the state, because it changes over time.

There are a lot more things you might want to do with a text input. For example, you could validate the text inside while the user types. For more detailed examples, see the React docs on controlled components, or the reference docs for TextInput.

Text input is one of the ways the user interacts with the app. Next, let's look at another type of input and learn how to handle touches.

Edit this page
Last updated on
- + diff --git a/docs/0.60/handling-touches.html b/docs/0.60/handling-touches.html index 1e7cc88b6d6..f6b456aa5e9 100644 --- a/docs/0.60/handling-touches.html +++ b/docs/0.60/handling-touches.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Handling Touches

Users interact with mobile apps mainly through touch. They can use a combination of gestures, such as tapping on a button, scrolling a list, or zooming on a map. React Native provides components to handle all sorts of common gestures, as well as a comprehensive gesture responder system to allow for more advanced gesture recognition, but the one component you will most likely be interested in is the basic Button.

Displaying a basic button

Button provides a basic button component that is rendered nicely on all platforms. The minimal example to display a button looks like this:

<Button
onPress={() => {
alert('You tapped the button!');
}}
title="Press Me"
/>

This will render a blue label on iOS, and a blue rounded rectangle with light text on Android. Pressing the button will call the "onPress" function, which in this case displays an alert popup. If you like, you can specify a "color" prop to change the color of your button.

Go ahead and play around with the Button component using the example below. You can select which platform your app is previewed in by clicking on the toggle in the bottom right, then click on "Tap to Play" to preview the app.

Touchables

If the basic button doesn't look right for your app, you can build your own button using any of the "Touchable" components provided by React Native. The "Touchable" components provide the capability to capture tapping gestures, and can display feedback when a gesture is recognized. These components do not provide any default styling, however, so you will need to do a bit of work to get them looking nicely in your app.

Which "Touchable" component you use will depend on what kind of feedback you want to provide:

  • Generally, you can use TouchableHighlight anywhere you would use a button or link on web. The view's background will be darkened when the user presses down on the button.

  • You may consider using TouchableNativeFeedback on Android to display ink surface reaction ripples that respond to the user's touch.

  • TouchableOpacity can be used to provide feedback by reducing the opacity of the button, allowing the background to be seen through while the user is pressing down.

  • If you need to handle a tap gesture but you don't want any feedback to be displayed, use TouchableWithoutFeedback.

In some cases, you may want to detect when a user presses and holds a view for a set amount of time. These long presses can be handled by passing a function to the onLongPress props of any of the "Touchable" components.

Let's see all of these in action:

Scrolling lists, swiping pages, and pinch-to-zoom

Another gesture commonly used in mobile apps is the swipe or pan. This gesture allows the user to scroll through a list of items, or swipe through pages of content. In order to handle these and other gestures, we'll learn how to use a ScrollView next.

Edit this page
Last updated on
- + diff --git a/docs/0.60/handling-touches/index.html b/docs/0.60/handling-touches/index.html index 1e7cc88b6d6..f6b456aa5e9 100644 --- a/docs/0.60/handling-touches/index.html +++ b/docs/0.60/handling-touches/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Handling Touches

Users interact with mobile apps mainly through touch. They can use a combination of gestures, such as tapping on a button, scrolling a list, or zooming on a map. React Native provides components to handle all sorts of common gestures, as well as a comprehensive gesture responder system to allow for more advanced gesture recognition, but the one component you will most likely be interested in is the basic Button.

Displaying a basic button

Button provides a basic button component that is rendered nicely on all platforms. The minimal example to display a button looks like this:

<Button
onPress={() => {
alert('You tapped the button!');
}}
title="Press Me"
/>

This will render a blue label on iOS, and a blue rounded rectangle with light text on Android. Pressing the button will call the "onPress" function, which in this case displays an alert popup. If you like, you can specify a "color" prop to change the color of your button.

Go ahead and play around with the Button component using the example below. You can select which platform your app is previewed in by clicking on the toggle in the bottom right, then click on "Tap to Play" to preview the app.

Touchables

If the basic button doesn't look right for your app, you can build your own button using any of the "Touchable" components provided by React Native. The "Touchable" components provide the capability to capture tapping gestures, and can display feedback when a gesture is recognized. These components do not provide any default styling, however, so you will need to do a bit of work to get them looking nicely in your app.

Which "Touchable" component you use will depend on what kind of feedback you want to provide:

  • Generally, you can use TouchableHighlight anywhere you would use a button or link on web. The view's background will be darkened when the user presses down on the button.

  • You may consider using TouchableNativeFeedback on Android to display ink surface reaction ripples that respond to the user's touch.

  • TouchableOpacity can be used to provide feedback by reducing the opacity of the button, allowing the background to be seen through while the user is pressing down.

  • If you need to handle a tap gesture but you don't want any feedback to be displayed, use TouchableWithoutFeedback.

In some cases, you may want to detect when a user presses and holds a view for a set amount of time. These long presses can be handled by passing a function to the onLongPress props of any of the "Touchable" components.

Let's see all of these in action:

Scrolling lists, swiping pages, and pinch-to-zoom

Another gesture commonly used in mobile apps is the swipe or pan. This gesture allows the user to scroll through a list of items, or swipe through pages of content. In order to handle these and other gestures, we'll learn how to use a ScrollView next.

Edit this page
Last updated on
- + diff --git a/docs/0.60/headless-js-android.html b/docs/0.60/headless-js-android.html index 7543450cc79..e02c29f8d26 100644 --- a/docs/0.60/headless-js-android.html +++ b/docs/0.60/headless-js-android.html @@ -19,7 +19,7 @@ - + @@ -43,7 +43,7 @@
}
Edit this page
Last updated on
- + diff --git a/docs/0.60/headless-js-android/index.html b/docs/0.60/headless-js-android/index.html index 7543450cc79..e02c29f8d26 100644 --- a/docs/0.60/headless-js-android/index.html +++ b/docs/0.60/headless-js-android/index.html @@ -19,7 +19,7 @@ - + @@ -43,7 +43,7 @@
}
Edit this page
Last updated on
- + diff --git a/docs/0.60/height-and-width.html b/docs/0.60/height-and-width.html index f5ef570c51e..91e16e2de45 100644 --- a/docs/0.60/height-and-width.html +++ b/docs/0.60/height-and-width.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Height and Width

A component's height and width determine its size on the screen.

Fixed Dimensions

The simplest way to set the dimensions of a component is by adding a fixed width and height to style. All dimensions in React Native are unitless, and represent density-independent pixels.

Setting dimensions this way is common for components that should always render at exactly the same size, regardless of screen dimensions.

Flex Dimensions

Use flex in a component's style to have the component expand and shrink dynamically based on available space. Normally you will use flex: 1, which tells a component to fill all available space, shared evenly amongst other components with the same parent. The larger the flex given, the higher the ratio of space a component will take compared to its siblings.

A component can only expand to fill available space if its parent has dimensions greater than 0. If a parent does not have either a fixed width and height or flex, the parent will have dimensions of 0 and the flex children will not be visible.

After you can control a component's size, the next step is to learn how to lay it out on the screen.

Edit this page
Last updated on
- + diff --git a/docs/0.60/height-and-width/index.html b/docs/0.60/height-and-width/index.html index f5ef570c51e..91e16e2de45 100644 --- a/docs/0.60/height-and-width/index.html +++ b/docs/0.60/height-and-width/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Height and Width

A component's height and width determine its size on the screen.

Fixed Dimensions

The simplest way to set the dimensions of a component is by adding a fixed width and height to style. All dimensions in React Native are unitless, and represent density-independent pixels.

Setting dimensions this way is common for components that should always render at exactly the same size, regardless of screen dimensions.

Flex Dimensions

Use flex in a component's style to have the component expand and shrink dynamically based on available space. Normally you will use flex: 1, which tells a component to fill all available space, shared evenly amongst other components with the same parent. The larger the flex given, the higher the ratio of space a component will take compared to its siblings.

A component can only expand to fill available space if its parent has dimensions greater than 0. If a parent does not have either a fixed width and height or flex, the parent will have dimensions of 0 and the flex children will not be visible.

After you can control a component's size, the next step is to learn how to lay it out on the screen.

Edit this page
Last updated on
- + diff --git a/docs/0.60/hermes.html b/docs/0.60/hermes.html index 22fba8ec76d..a67625d8a22 100644 --- a/docs/0.60/hermes.html +++ b/docs/0.60/hermes.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Using Hermes

Hermes is an open-source JavaScript engine optimized for running React Native apps on Android. For many apps, enabling Hermes will result in improved start-up time, decreased memory usage, and smaller app size. At this time Hermes is an opt-in React Native feature, and this guide explains how to enable it.

First, ensure you're using at least version 0.60.4 of React Native.

If you have an existing app based on an earlier version of React Native, you will have to upgrade it first. See Upgrading to new React Native Versions for how to do this. Make especially sure that all changes to android/app/build.gradle have been applied, as detailed by the React Native upgrade helper. After upgrading the app, make sure everything works before trying to switch to Hermes.

Note for Windows users.

Hermes requires Microsoft Visual C++ 2015 Redistributable

Edit your android/app/build.gradle file and make the change illustrated below:

project.ext.react = [
entryFile: "index.js",
- enableHermes: false // clean and rebuild if changing
+ enableHermes: true // clean and rebuild if changing
]

Also, if you're using ProGuard, you will need to add this rule in proguard-rules.pro :

-keep class com.facebook.hermes.unicode.** { *; }

Next, if you've already built your app at least once, clean the build:

$ cd android && ./gradlew clean

That's it! You should now be able to develop and deploy your app as normal:

$ react-native run-android

Confirming Hermes is in use

If you've recently created a new app from scratch you should see if Hermes is enabled in the welcome view:

Where to find JS engine status in AwesomeProject

A HermesInternal global variable will be available in JavaScript that can be used to verify that Hermes is in use:

const isHermes = () => global.HermesInternal != null;

To see the benefits of Hermes, try making a release build/deployment of your app to compare. For example:

$ react-native run-android --variant release

This will compile JavaScript to bytecode during build time which will improve your app's startup speed on device.

Debugging Hermes using Google Chrome's DevTools

Hermes supports the Chrome debugger by implementing the Chrome inspector protocol. This means Chrome's tools can be used to directly debug JavaScript running on Hermes, on an emulator or device.

Chrome connects to Hermes running on device via Metro, so you'll need to know where Metro is listening. Typically this will be on localhost:8081, but this is configurable. When running yarn start the address is written to stdout on startup.

Once you know where the Metro server is listening, you can connect with Chrome using the following steps:

  1. Navigate to chrome://inspect in a Chrome browser instance.

  2. Use the Configure... button to add the Metro server address (typically localhost:8081 as described above).

Configure button in Chrome DevTools devices page

Dialog for adding Chrome DevTools network targets

  1. You should now see a "Hermes React Native" target with an "inspect" link which can be used to bring up debugger. If you don't see the "inspect" link, make sure the Metro server is running. Target inspect link

  2. You can now use the Chrome debug tools. For example, to breakpoint the next time some JavaScript is run, click on the pause button and trigger an action in your app which would cause JavaScript to execute. Pause button in debug tools

Edit this page
Last updated on
- + diff --git a/docs/0.60/hermes/index.html b/docs/0.60/hermes/index.html index 22fba8ec76d..a67625d8a22 100644 --- a/docs/0.60/hermes/index.html +++ b/docs/0.60/hermes/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Using Hermes

Hermes is an open-source JavaScript engine optimized for running React Native apps on Android. For many apps, enabling Hermes will result in improved start-up time, decreased memory usage, and smaller app size. At this time Hermes is an opt-in React Native feature, and this guide explains how to enable it.

First, ensure you're using at least version 0.60.4 of React Native.

If you have an existing app based on an earlier version of React Native, you will have to upgrade it first. See Upgrading to new React Native Versions for how to do this. Make especially sure that all changes to android/app/build.gradle have been applied, as detailed by the React Native upgrade helper. After upgrading the app, make sure everything works before trying to switch to Hermes.

Note for Windows users.

Hermes requires Microsoft Visual C++ 2015 Redistributable

Edit your android/app/build.gradle file and make the change illustrated below:

project.ext.react = [
entryFile: "index.js",
- enableHermes: false // clean and rebuild if changing
+ enableHermes: true // clean and rebuild if changing
]

Also, if you're using ProGuard, you will need to add this rule in proguard-rules.pro :

-keep class com.facebook.hermes.unicode.** { *; }

Next, if you've already built your app at least once, clean the build:

$ cd android && ./gradlew clean

That's it! You should now be able to develop and deploy your app as normal:

$ react-native run-android

Confirming Hermes is in use

If you've recently created a new app from scratch you should see if Hermes is enabled in the welcome view:

Where to find JS engine status in AwesomeProject

A HermesInternal global variable will be available in JavaScript that can be used to verify that Hermes is in use:

const isHermes = () => global.HermesInternal != null;

To see the benefits of Hermes, try making a release build/deployment of your app to compare. For example:

$ react-native run-android --variant release

This will compile JavaScript to bytecode during build time which will improve your app's startup speed on device.

Debugging Hermes using Google Chrome's DevTools

Hermes supports the Chrome debugger by implementing the Chrome inspector protocol. This means Chrome's tools can be used to directly debug JavaScript running on Hermes, on an emulator or device.

Chrome connects to Hermes running on device via Metro, so you'll need to know where Metro is listening. Typically this will be on localhost:8081, but this is configurable. When running yarn start the address is written to stdout on startup.

Once you know where the Metro server is listening, you can connect with Chrome using the following steps:

  1. Navigate to chrome://inspect in a Chrome browser instance.

  2. Use the Configure... button to add the Metro server address (typically localhost:8081 as described above).

Configure button in Chrome DevTools devices page

Dialog for adding Chrome DevTools network targets

  1. You should now see a "Hermes React Native" target with an "inspect" link which can be used to bring up debugger. If you don't see the "inspect" link, make sure the Metro server is running. Target inspect link

  2. You can now use the Chrome debug tools. For example, to breakpoint the next time some JavaScript is run, click on the pause button and trigger an action in your app which would cause JavaScript to execute. Pause button in debug tools

Edit this page
Last updated on
- + diff --git a/docs/0.60/image-style-props.html b/docs/0.60/image-style-props.html index 09154f8af68..98ec595bdad 100644 --- a/docs/0.60/image-style-props.html +++ b/docs/0.60/image-style-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Image Style Props

Reference

Props

borderTopRightRadius

TypeRequired
numberNo

backfaceVisibility

TypeRequired
enum('visible', 'hidden')No

borderBottomLeftRadius

TypeRequired
numberNo

borderBottomRightRadius

TypeRequired
numberNo

borderColor

TypeRequired
colorNo

borderRadius

TypeRequired
numberNo

borderTopLeftRadius

TypeRequired
numberNo

backgroundColor

TypeRequired
colorNo

borderWidth

TypeRequired
numberNo

opacity

TypeRequired
numberNo

overflow

TypeRequired
enum('visible', 'hidden')No

resizeMode

TypeRequired
enum('cover', 'contain', 'stretch', 'repeat', 'center')No

tintColor

Changes the color of all the non-transparent pixels to the tintColor.

TypeRequired
colorNo

overlayColor

When the image has rounded corners, specifying an overlayColor will cause the remaining space in the corners to be filled with a solid color. This is useful in cases which are not supported by the Android implementation of rounded corners:

  • Certain resize modes, such as 'contain'
  • Animated GIFs

A typical way to use this prop is with images displayed on a solid background and setting the overlayColor to the same color as the background.

For details of how this works under the hood, see https://frescolib.org/docs/rounded-corners-and-circles.html

TypeRequiredPlatform
stringNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.60/image-style-props/index.html b/docs/0.60/image-style-props/index.html index 09154f8af68..98ec595bdad 100644 --- a/docs/0.60/image-style-props/index.html +++ b/docs/0.60/image-style-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Image Style Props

Reference

Props

borderTopRightRadius

TypeRequired
numberNo

backfaceVisibility

TypeRequired
enum('visible', 'hidden')No

borderBottomLeftRadius

TypeRequired
numberNo

borderBottomRightRadius

TypeRequired
numberNo

borderColor

TypeRequired
colorNo

borderRadius

TypeRequired
numberNo

borderTopLeftRadius

TypeRequired
numberNo

backgroundColor

TypeRequired
colorNo

borderWidth

TypeRequired
numberNo

opacity

TypeRequired
numberNo

overflow

TypeRequired
enum('visible', 'hidden')No

resizeMode

TypeRequired
enum('cover', 'contain', 'stretch', 'repeat', 'center')No

tintColor

Changes the color of all the non-transparent pixels to the tintColor.

TypeRequired
colorNo

overlayColor

When the image has rounded corners, specifying an overlayColor will cause the remaining space in the corners to be filled with a solid color. This is useful in cases which are not supported by the Android implementation of rounded corners:

  • Certain resize modes, such as 'contain'
  • Animated GIFs

A typical way to use this prop is with images displayed on a solid background and setting the overlayColor to the same color as the background.

For details of how this works under the hood, see https://frescolib.org/docs/rounded-corners-and-circles.html

TypeRequiredPlatform
stringNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.60/image.html b/docs/0.60/image.html index 4988f3089e7..daf72af145d 100644 --- a/docs/0.60/image.html +++ b/docs/0.60/image.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// For WebP support, without animations
implementation 'com.facebook.fresco:webpsupport:2.0.0'
}

Reference

Props

style

ImageResizeMode is an Enum for different image resizing modes, set via the resizeMode style property on Image components. The values are contain, cover, stretch, center, repeat.

TypeRequired
styleNo

blurRadius

blurRadius: the blur radius of the blur filter added to the image

TypeRequired
numberNo

onLayout

Invoked on mount and layout changes with {nativeEvent: {layout: {x, y, width, height}}}.

TypeRequired
functionNo

onLoad

Invoked when load completes successfully.

TypeRequired
functionNo

onLoadEnd

Invoked when load either succeeds or fails.

TypeRequired
functionNo

onLoadStart

Invoked on load start.

e.g., onLoadStart={(e) => this.setState({loading: true})}

TypeRequired
functionNo

resizeMode

Determines how to resize the image when the frame doesn't match the raw image dimensions. Defaults to cover.

TypeRequired
enum('cover', 'contain', 'stretch', 'repeat', 'center')No

source

The image source (either a remote URL or a local file resource).

This prop can also contain several remote URLs, specified together with their width and height and potentially with scale/other URI arguments. The native side will then choose the best uri to display based on the measured size of the image container. A cache property can be added to control how networked request interacts with the local cache. (For more information see Cache Control for Images).

The currently supported formats are png, jpg, jpeg, bmp, gif, webp (Android only), psd (iOS only). In addition, iOS supports several RAW image formats. Refer to Apple's documentation for the current list of supported camera models (for iOS 12, see https://support.apple.com/en-ca/HT208967).

TypeRequired
ImageSourcePropTypeNo

loadingIndicatorSource

Similarly to source, this property represents the resource used to render the loading indicator for the image, displayed until image is ready to be displayed, typically after when it got downloaded from network.

TypeRequired
array of ImageSourcePropTypes, numberNo

Can accept a number as returned by require('./image.jpg')

onError

Invoked on load error with {nativeEvent: {error}}.

TypeRequired
functionNo

testID

A unique identifier for this element to be used in UI Automation testing scripts.

TypeRequired
stringNo

resizeMethod

The mechanism that should be used to resize the image when the image's dimensions differ from the image view's dimensions. Defaults to auto.

More details about resize and scale can be found at http://frescolib.org/docs/resizing.html.

TypeRequiredPlatform
enum('auto', 'resize', 'scale')NoAndroid

accessibilityLabel

The text that's read by the screen reader when the user interacts with the image.

TypeRequiredPlatform
stringNoiOS

accessible

When true, indicates the image is an accessibility element.

TypeRequiredPlatform
boolNoiOS

capInsets

When the image is resized, the corners of the size specified by capInsets will stay a fixed size, but the center content and borders of the image will be stretched. This is useful for creating resizable rounded buttons, shadows, and other resizable assets. More info in the official Apple documentation.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

defaultSource

A static image to display while loading the image source.

TypeRequiredPlatform
object, numberNoiOS
numberNoAndroid

If passing an object, the general shape is {uri: string, width: number, height: number, scale: number}:

If passing a number:

Note: On Android, the default source prop is ignored on debug builds.

onPartialLoad

Invoked when a partial load of the image is complete. The definition of what constitutes a "partial load" is loader specific though this is meant for progressive JPEG loads.

TypeRequiredPlatform
functionNoiOS

onProgress

Invoked on download progress with {nativeEvent: {loaded, total}}.

TypeRequiredPlatform
functionNoiOS

fadeDuration

Android only. By default, it is 300ms.

TypeRequiredPlatform
numberNoAndroid

progressiveRenderingEnabled

Android only. When true, enables progressive jpeg streaming. https://frescolib.org/docs/progressive-jpegs.html

TypeRequiredPlatform
boolNoAndroid

Methods

getSize()

Image.getSize(uri, success, [failure]);

Retrieve the width and height (in pixels) of an image prior to displaying it. This method can fail if the image cannot be found, or fails to download.

In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API.

Parameters:

NameTypeRequiredDescription
uristringYesThe location of the image.
successfunctionYesThe function that will be called if the image was successfully found and width and height retrieved.
failurefunctionNoThe function that will be called if there was an error, such as failing to retrieve the image.

getSizeWithHeaders()

Image.getSizeWithHeaders(uri, headers, success, [failure]);

Retrieve the width and height (in pixels) of an image prior to displaying it with the ability to provide the headers for the request. This method can fail if the image cannot be found, or fails to download.

In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API.

Does not work for static image resources.

Parameters:

NameTypeRequiredDescription
uristringYesThe location of the image.
headersobjectYesThe headers for the request.
successfunctionYesThe function that will be called if the image was successfully found and width and height retrieved.
failurefunctionNoThe function that will be called if there was an error, such as failing toto retrieve the image.

prefetch()

Image.prefetch(url);

Prefetches a remote image for later use by downloading it to the disk cache

Parameters:

NameTypeRequiredDescription
urlstringYesThe remote location of the image.

abortPrefetch()

Image.abortPrefetch(requestId);

Abort prefetch request. Android-only.

Parameters:

NameTypeRequiredDescription
requestIdnumberYesId as returned by prefetch()

queryCache()

Image.queryCache(urls);

Perform cache interrogation. Returns a mapping from URL to cache status, such as "disk" or "memory". If a requested URL is not in the mapping, it means it's not in the cache.

Parameters:

NameTypeRequiredDescription
urlsarrayYesList of image URLs to check the cache for.

resolveAssetSource()

Image.resolveAssetSource(source);

Resolves an asset reference into an object which has the properties uri, width, and height.

Parameters:

NameTypeRequiredDescription
sourcenumber, objectYesA number (opaque type returned by require('./foo.png')) or an ImageSource.

ImageSource is an object like { uri: '<http location || file path>' }

Edit this page
Last updated on
- + diff --git a/docs/0.60/image/index.html b/docs/0.60/image/index.html index 4988f3089e7..daf72af145d 100644 --- a/docs/0.60/image/index.html +++ b/docs/0.60/image/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// For WebP support, without animations
implementation 'com.facebook.fresco:webpsupport:2.0.0'
}

Reference

Props

style

ImageResizeMode is an Enum for different image resizing modes, set via the resizeMode style property on Image components. The values are contain, cover, stretch, center, repeat.

TypeRequired
styleNo

blurRadius

blurRadius: the blur radius of the blur filter added to the image

TypeRequired
numberNo

onLayout

Invoked on mount and layout changes with {nativeEvent: {layout: {x, y, width, height}}}.

TypeRequired
functionNo

onLoad

Invoked when load completes successfully.

TypeRequired
functionNo

onLoadEnd

Invoked when load either succeeds or fails.

TypeRequired
functionNo

onLoadStart

Invoked on load start.

e.g., onLoadStart={(e) => this.setState({loading: true})}

TypeRequired
functionNo

resizeMode

Determines how to resize the image when the frame doesn't match the raw image dimensions. Defaults to cover.

TypeRequired
enum('cover', 'contain', 'stretch', 'repeat', 'center')No

source

The image source (either a remote URL or a local file resource).

This prop can also contain several remote URLs, specified together with their width and height and potentially with scale/other URI arguments. The native side will then choose the best uri to display based on the measured size of the image container. A cache property can be added to control how networked request interacts with the local cache. (For more information see Cache Control for Images).

The currently supported formats are png, jpg, jpeg, bmp, gif, webp (Android only), psd (iOS only). In addition, iOS supports several RAW image formats. Refer to Apple's documentation for the current list of supported camera models (for iOS 12, see https://support.apple.com/en-ca/HT208967).

TypeRequired
ImageSourcePropTypeNo

loadingIndicatorSource

Similarly to source, this property represents the resource used to render the loading indicator for the image, displayed until image is ready to be displayed, typically after when it got downloaded from network.

TypeRequired
array of ImageSourcePropTypes, numberNo

Can accept a number as returned by require('./image.jpg')

onError

Invoked on load error with {nativeEvent: {error}}.

TypeRequired
functionNo

testID

A unique identifier for this element to be used in UI Automation testing scripts.

TypeRequired
stringNo

resizeMethod

The mechanism that should be used to resize the image when the image's dimensions differ from the image view's dimensions. Defaults to auto.

More details about resize and scale can be found at http://frescolib.org/docs/resizing.html.

TypeRequiredPlatform
enum('auto', 'resize', 'scale')NoAndroid

accessibilityLabel

The text that's read by the screen reader when the user interacts with the image.

TypeRequiredPlatform
stringNoiOS

accessible

When true, indicates the image is an accessibility element.

TypeRequiredPlatform
boolNoiOS

capInsets

When the image is resized, the corners of the size specified by capInsets will stay a fixed size, but the center content and borders of the image will be stretched. This is useful for creating resizable rounded buttons, shadows, and other resizable assets. More info in the official Apple documentation.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

defaultSource

A static image to display while loading the image source.

TypeRequiredPlatform
object, numberNoiOS
numberNoAndroid

If passing an object, the general shape is {uri: string, width: number, height: number, scale: number}:

If passing a number:

Note: On Android, the default source prop is ignored on debug builds.

onPartialLoad

Invoked when a partial load of the image is complete. The definition of what constitutes a "partial load" is loader specific though this is meant for progressive JPEG loads.

TypeRequiredPlatform
functionNoiOS

onProgress

Invoked on download progress with {nativeEvent: {loaded, total}}.

TypeRequiredPlatform
functionNoiOS

fadeDuration

Android only. By default, it is 300ms.

TypeRequiredPlatform
numberNoAndroid

progressiveRenderingEnabled

Android only. When true, enables progressive jpeg streaming. https://frescolib.org/docs/progressive-jpegs.html

TypeRequiredPlatform
boolNoAndroid

Methods

getSize()

Image.getSize(uri, success, [failure]);

Retrieve the width and height (in pixels) of an image prior to displaying it. This method can fail if the image cannot be found, or fails to download.

In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API.

Parameters:

NameTypeRequiredDescription
uristringYesThe location of the image.
successfunctionYesThe function that will be called if the image was successfully found and width and height retrieved.
failurefunctionNoThe function that will be called if there was an error, such as failing to retrieve the image.

getSizeWithHeaders()

Image.getSizeWithHeaders(uri, headers, success, [failure]);

Retrieve the width and height (in pixels) of an image prior to displaying it with the ability to provide the headers for the request. This method can fail if the image cannot be found, or fails to download.

In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API.

Does not work for static image resources.

Parameters:

NameTypeRequiredDescription
uristringYesThe location of the image.
headersobjectYesThe headers for the request.
successfunctionYesThe function that will be called if the image was successfully found and width and height retrieved.
failurefunctionNoThe function that will be called if there was an error, such as failing toto retrieve the image.

prefetch()

Image.prefetch(url);

Prefetches a remote image for later use by downloading it to the disk cache

Parameters:

NameTypeRequiredDescription
urlstringYesThe remote location of the image.

abortPrefetch()

Image.abortPrefetch(requestId);

Abort prefetch request. Android-only.

Parameters:

NameTypeRequiredDescription
requestIdnumberYesId as returned by prefetch()

queryCache()

Image.queryCache(urls);

Perform cache interrogation. Returns a mapping from URL to cache status, such as "disk" or "memory". If a requested URL is not in the mapping, it means it's not in the cache.

Parameters:

NameTypeRequiredDescription
urlsarrayYesList of image URLs to check the cache for.

resolveAssetSource()

Image.resolveAssetSource(source);

Resolves an asset reference into an object which has the properties uri, width, and height.

Parameters:

NameTypeRequiredDescription
sourcenumber, objectYesA number (opaque type returned by require('./foo.png')) or an ImageSource.

ImageSource is an object like { uri: '<http location || file path>' }

Edit this page
Last updated on
- + diff --git a/docs/0.60/imagebackground.html b/docs/0.60/imagebackground.html index 331a866db6a..223a14bbaf5 100644 --- a/docs/0.60/imagebackground.html +++ b/docs/0.60/imagebackground.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

ImageBackground

A common feature request from developers familiar with the web is background-image. To handle this use case, you can use the <ImageBackground> component, which has the same props as <Image>, and add whatever children to it you would like to layer on top of it.

You might not want to use <ImageBackground> in some cases, since the implementation is basic. Refer to <ImageBackground>'s source code for more insight, and create your own custom component when needed.

Note that you must specify some width and height style attributes.

Example

return (
<ImageBackground source={...} style={{width: '100%', height: '100%'}}>
<Text>Inside</Text>
</ImageBackground>
);

Reference

Props

Inherits Image Props.

style

TypeRequired
view stylesNo

imageStyle

TypeRequired
image stylesNo

imageRef

Allows to set a reference to the inner Image component

TypeRequired
RefNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/imagebackground/index.html b/docs/0.60/imagebackground/index.html index 331a866db6a..223a14bbaf5 100644 --- a/docs/0.60/imagebackground/index.html +++ b/docs/0.60/imagebackground/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

ImageBackground

A common feature request from developers familiar with the web is background-image. To handle this use case, you can use the <ImageBackground> component, which has the same props as <Image>, and add whatever children to it you would like to layer on top of it.

You might not want to use <ImageBackground> in some cases, since the implementation is basic. Refer to <ImageBackground>'s source code for more insight, and create your own custom component when needed.

Note that you must specify some width and height style attributes.

Example

return (
<ImageBackground source={...} style={{width: '100%', height: '100%'}}>
<Text>Inside</Text>
</ImageBackground>
);

Reference

Props

Inherits Image Props.

style

TypeRequired
view stylesNo

imageStyle

TypeRequired
image stylesNo

imageRef

Allows to set a reference to the inner Image component

TypeRequired
RefNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/imageeditor.html b/docs/0.60/imageeditor.html index 16287b991da..40623b9082c 100644 --- a/docs/0.60/imageeditor.html +++ b/docs/0.60/imageeditor.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

ImageEditor

Deprecated. Use @react-native-community/image-editor instead.

Reference

Methods

cropImage()

static cropImage(uri, cropData, success, failure)

Crop the image specified by the URI param. If URI points to a remote image, it will be downloaded automatically. If the image cannot be loaded/downloaded, the failure callback will be called.

If the cropping process is successful, the resultant cropped image will be stored in the ImageStore, and the URI returned in the success callback will point to the image in the store. Remember to delete the cropped image from the ImageStore when you are done with it.

cropData

  • offset - The top-left corner of the cropped image, specified in the original image's coordinate space
  • size - Size (dimensions) of the cropped image
  • displaySize (optional) - Size to which you want to scale the cropped image
  • resizeMode (optional) - Resizing mode to use when scaling the image
cropData = {
offset: { x: number, y: number },
size: { width: number, height: number },
displaySize: { width: number, height: number },
resizeMode: 'contain/cover/stretch'
};
Edit this page
Last updated on
- + diff --git a/docs/0.60/imageeditor/index.html b/docs/0.60/imageeditor/index.html index 16287b991da..40623b9082c 100644 --- a/docs/0.60/imageeditor/index.html +++ b/docs/0.60/imageeditor/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

ImageEditor

Deprecated. Use @react-native-community/image-editor instead.

Reference

Methods

cropImage()

static cropImage(uri, cropData, success, failure)

Crop the image specified by the URI param. If URI points to a remote image, it will be downloaded automatically. If the image cannot be loaded/downloaded, the failure callback will be called.

If the cropping process is successful, the resultant cropped image will be stored in the ImageStore, and the URI returned in the success callback will point to the image in the store. Remember to delete the cropped image from the ImageStore when you are done with it.

cropData

  • offset - The top-left corner of the cropped image, specified in the original image's coordinate space
  • size - Size (dimensions) of the cropped image
  • displaySize (optional) - Size to which you want to scale the cropped image
  • resizeMode (optional) - Resizing mode to use when scaling the image
cropData = {
offset: { x: number, y: number },
size: { width: number, height: number },
displaySize: { width: number, height: number },
resizeMode: 'contain/cover/stretch'
};
Edit this page
Last updated on
- + diff --git a/docs/0.60/imagepickerios.html b/docs/0.60/imagepickerios.html index fd7a0fffb4e..0161acc4bc4 100644 --- a/docs/0.60/imagepickerios.html +++ b/docs/0.60/imagepickerios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

ImagePickerIOS

Deprecated. Use @react-native-community/image-picker-ios instead.

Reference

Methods

canRecordVideos()

static canRecordVideos(callback)

canUseCamera()

static canUseCamera(callback)

openCameraDialog()

static openCameraDialog(config, successCallback, cancelCallback)

Parameters:

NameTypeRequiredDescription
configobjectNoSee below.
successCallbackfunctionNoSee below.
cancelCallbackfunctionNoSee below.

config is an object containing:

  • videoMode : An optional boolean value that defaults to false.

successCallback is an optional callback function that's invoked when the select dialog is opened successfully. It will include the following data:

  • [string, number, number]

cancelCallback is an optional callback function that's invoked when the camera dialog is canceled.

openSelectDialog()

static openSelectDialog(config, successCallback, cancelCallback)

Parameters:

NameTypeRequiredDescription
configobjectNoSee below.
successCallbackfunctionNoSee below.
cancelCallbackfunctionNoSee below.

config is an object containing:

  • showImages : An optional boolean value that defaults to false.
  • showVideos: An optional boolean value that defaults to false.

successCallback is an optional callback function that's invoked when the select dialog is opened successfully. It will include the following data:

  • [string, number, number]

cancelCallback is an optional callback function that's invoked when the select dialog is canceled.

Edit this page
Last updated on
- + diff --git a/docs/0.60/imagepickerios/index.html b/docs/0.60/imagepickerios/index.html index fd7a0fffb4e..0161acc4bc4 100644 --- a/docs/0.60/imagepickerios/index.html +++ b/docs/0.60/imagepickerios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

ImagePickerIOS

Deprecated. Use @react-native-community/image-picker-ios instead.

Reference

Methods

canRecordVideos()

static canRecordVideos(callback)

canUseCamera()

static canUseCamera(callback)

openCameraDialog()

static openCameraDialog(config, successCallback, cancelCallback)

Parameters:

NameTypeRequiredDescription
configobjectNoSee below.
successCallbackfunctionNoSee below.
cancelCallbackfunctionNoSee below.

config is an object containing:

  • videoMode : An optional boolean value that defaults to false.

successCallback is an optional callback function that's invoked when the select dialog is opened successfully. It will include the following data:

  • [string, number, number]

cancelCallback is an optional callback function that's invoked when the camera dialog is canceled.

openSelectDialog()

static openSelectDialog(config, successCallback, cancelCallback)

Parameters:

NameTypeRequiredDescription
configobjectNoSee below.
successCallbackfunctionNoSee below.
cancelCallbackfunctionNoSee below.

config is an object containing:

  • showImages : An optional boolean value that defaults to false.
  • showVideos: An optional boolean value that defaults to false.

successCallback is an optional callback function that's invoked when the select dialog is opened successfully. It will include the following data:

  • [string, number, number]

cancelCallback is an optional callback function that's invoked when the select dialog is canceled.

Edit this page
Last updated on
- + diff --git a/docs/0.60/images.html b/docs/0.60/images.html index c821f9e46cb..58fb11ee9be 100644 --- a/docs/0.60/images.html +++ b/docs/0.60/images.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// BAD
<Image source={{uri: 'https://reactjs.org/logo-og.png'}} />

Network Requests for Images

If you would like to set such things as the HTTP-Verb, Headers or a Body along with the image request, you may do this by defining these properties on the source object:

<Image
source={{
uri: 'https://reactjs.org/logo-og.png',
method: 'POST',
headers: {
Pragma: 'no-cache'
},
body: 'Your Body goes here'
}}
style={{ width: 400, height: 400 }}
/>

Uri Data Images

Sometimes, you might be getting encoded image data from a REST API call. You can use the 'data:' uri scheme to use these images. Same as for network resources, you will need to manually specify the dimensions of your image.

This is recommended for very small and dynamic images only, like icons in a list from a DB.

// include at least width and height!
<Image
style={{
width: 51,
height: 51,
resizeMode: 'contain'
}}
source={{
uri:
'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADMAAAAzCAYAAAA6oTAqAAAAEXRFWHRTb2Z0d2FyZQBwbmdjcnVzaEB1SfMAAABQSURBVGje7dSxCQBACARB+2/ab8BEeQNhFi6WSYzYLYudDQYGBgYGBgYGBgYGBgYGBgZmcvDqYGBgmhivGQYGBgYGBgYGBgYGBgYGBgbmQw+P/eMrC5UTVAAAAABJRU5ErkJggg=='
}}
/>

Cache Control (iOS Only)

In some cases you might only want to display an image if it is already in the local cache, i.e. a low resolution placeholder until a higher resolution is available. In other cases you do not care if the image is outdated and are willing to display an outdated image to save bandwidth. The cache source property gives you control over how the network layer interacts with the cache.

<Image
source={{
uri: 'https://reactjs.org/logo-og.png',
cache: 'only-if-cached'
}}
style={{ width: 400, height: 400 }}
/>

Local Filesystem Images

See CameraRoll for an example of using local resources that are outside of Images.xcassets.

Best Camera Roll Image

iOS saves multiple sizes for the same image in your Camera Roll, it is very important to pick the one that's as close as possible for performance reasons. You wouldn't want to use the full quality 3264x2448 image as source when displaying a 200x200 thumbnail. If there's an exact match, React Native will pick it, otherwise it's going to use the first one that's at least 50% bigger in order to avoid blur when resizing from a close size. All of this is done by default so you don't have to worry about writing the tedious (and error prone) code to do it yourself.

Why Not Automatically Size Everything?

In the browser if you don't give a size to an image, the browser is going to render a 0x0 element, download the image, and then render the image based with the correct size. The big issue with this behavior is that your UI is going to jump all around as images load, this makes for a very bad user experience.

In React Native this behavior is intentionally not implemented. It is more work for the developer to know the dimensions (or aspect ratio) of the remote image in advance, but we believe that it leads to a better user experience. Static images loaded from the app bundle via the require('./my-icon.png') syntax can be automatically sized because their dimensions are available immediately at the time of mounting.

For example, the result of require('./my-icon.png') might be:

{"__packager_asset":true,"uri":"my-icon.png","width":591,"height":573}

Source as an object

In React Native, one interesting decision is that the src attribute is named source and doesn't take a string but an object with a uri attribute.

<Image source={{ uri: 'something.jpg' }} />

On the infrastructure side, the reason is that it allows us to attach metadata to this object. For example if you are using require('./my-icon.png'), then we add information about its actual location and size (don't rely on this fact, it might change in the future!). This is also future proofing, for example we may want to support sprites at some point, instead of outputting {uri: ...}, we can output {uri: ..., crop: {left: 10, top: 50, width: 20, height: 40}} and transparently support spriting on all the existing call sites.

On the user side, this lets you annotate the object with useful attributes such as the dimension of the image in order to compute the size it's going to be displayed in. Feel free to use it as your data structure to store more information about your image.

Background Image via Nesting

A common feature request from developers familiar with the web is background-image. To handle this use case, you can use the <ImageBackground> component, which has the same props as <Image>, and add whatever children to it you would like to layer on top of it.

You might not want to use <ImageBackground> in some cases, since the implementation is basic. Refer to <ImageBackground>'s documentation for more insight, and create your own custom component when needed.

return (
<ImageBackground source={...} style={{width: '100%', height: '100%'}}>
<Text>Inside</Text>
</ImageBackground>
);

Note that you must specify some width and height style attributes.

iOS Border Radius Styles

Please note that the following corner specific, border radius style properties are currently ignored by iOS's image component:

Off-thread Decoding

Image decoding can take more than a frame-worth of time. This is one of the major sources of frame drops on the web because decoding is done in the main thread. In React Native, image decoding is done in a different thread. In practice, you already need to handle the case when the image is not downloaded yet, so displaying the placeholder for a few more frames while it is decoding does not require any code change.

Edit this page
Last updated on
- + diff --git a/docs/0.60/images/index.html b/docs/0.60/images/index.html index c821f9e46cb..58fb11ee9be 100644 --- a/docs/0.60/images/index.html +++ b/docs/0.60/images/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// BAD
<Image source={{uri: 'https://reactjs.org/logo-og.png'}} />

Network Requests for Images

If you would like to set such things as the HTTP-Verb, Headers or a Body along with the image request, you may do this by defining these properties on the source object:

<Image
source={{
uri: 'https://reactjs.org/logo-og.png',
method: 'POST',
headers: {
Pragma: 'no-cache'
},
body: 'Your Body goes here'
}}
style={{ width: 400, height: 400 }}
/>

Uri Data Images

Sometimes, you might be getting encoded image data from a REST API call. You can use the 'data:' uri scheme to use these images. Same as for network resources, you will need to manually specify the dimensions of your image.

This is recommended for very small and dynamic images only, like icons in a list from a DB.

// include at least width and height!
<Image
style={{
width: 51,
height: 51,
resizeMode: 'contain'
}}
source={{
uri:
'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADMAAAAzCAYAAAA6oTAqAAAAEXRFWHRTb2Z0d2FyZQBwbmdjcnVzaEB1SfMAAABQSURBVGje7dSxCQBACARB+2/ab8BEeQNhFi6WSYzYLYudDQYGBgYGBgYGBgYGBgYGBgZmcvDqYGBgmhivGQYGBgYGBgYGBgYGBgYGBgbmQw+P/eMrC5UTVAAAAABJRU5ErkJggg=='
}}
/>

Cache Control (iOS Only)

In some cases you might only want to display an image if it is already in the local cache, i.e. a low resolution placeholder until a higher resolution is available. In other cases you do not care if the image is outdated and are willing to display an outdated image to save bandwidth. The cache source property gives you control over how the network layer interacts with the cache.

<Image
source={{
uri: 'https://reactjs.org/logo-og.png',
cache: 'only-if-cached'
}}
style={{ width: 400, height: 400 }}
/>

Local Filesystem Images

See CameraRoll for an example of using local resources that are outside of Images.xcassets.

Best Camera Roll Image

iOS saves multiple sizes for the same image in your Camera Roll, it is very important to pick the one that's as close as possible for performance reasons. You wouldn't want to use the full quality 3264x2448 image as source when displaying a 200x200 thumbnail. If there's an exact match, React Native will pick it, otherwise it's going to use the first one that's at least 50% bigger in order to avoid blur when resizing from a close size. All of this is done by default so you don't have to worry about writing the tedious (and error prone) code to do it yourself.

Why Not Automatically Size Everything?

In the browser if you don't give a size to an image, the browser is going to render a 0x0 element, download the image, and then render the image based with the correct size. The big issue with this behavior is that your UI is going to jump all around as images load, this makes for a very bad user experience.

In React Native this behavior is intentionally not implemented. It is more work for the developer to know the dimensions (or aspect ratio) of the remote image in advance, but we believe that it leads to a better user experience. Static images loaded from the app bundle via the require('./my-icon.png') syntax can be automatically sized because their dimensions are available immediately at the time of mounting.

For example, the result of require('./my-icon.png') might be:

{"__packager_asset":true,"uri":"my-icon.png","width":591,"height":573}

Source as an object

In React Native, one interesting decision is that the src attribute is named source and doesn't take a string but an object with a uri attribute.

<Image source={{ uri: 'something.jpg' }} />

On the infrastructure side, the reason is that it allows us to attach metadata to this object. For example if you are using require('./my-icon.png'), then we add information about its actual location and size (don't rely on this fact, it might change in the future!). This is also future proofing, for example we may want to support sprites at some point, instead of outputting {uri: ...}, we can output {uri: ..., crop: {left: 10, top: 50, width: 20, height: 40}} and transparently support spriting on all the existing call sites.

On the user side, this lets you annotate the object with useful attributes such as the dimension of the image in order to compute the size it's going to be displayed in. Feel free to use it as your data structure to store more information about your image.

Background Image via Nesting

A common feature request from developers familiar with the web is background-image. To handle this use case, you can use the <ImageBackground> component, which has the same props as <Image>, and add whatever children to it you would like to layer on top of it.

You might not want to use <ImageBackground> in some cases, since the implementation is basic. Refer to <ImageBackground>'s documentation for more insight, and create your own custom component when needed.

return (
<ImageBackground source={...} style={{width: '100%', height: '100%'}}>
<Text>Inside</Text>
</ImageBackground>
);

Note that you must specify some width and height style attributes.

iOS Border Radius Styles

Please note that the following corner specific, border radius style properties are currently ignored by iOS's image component:

Off-thread Decoding

Image decoding can take more than a frame-worth of time. This is one of the major sources of frame drops on the web because decoding is done in the main thread. In React Native, image decoding is done in a different thread. In practice, you already need to handle the case when the image is not downloaded yet, so displaying the placeholder for a few more frames while it is decoding does not require any code change.

Edit this page
Last updated on
- + diff --git a/docs/0.60/imagestore.html b/docs/0.60/imagestore.html index 6ba4f909da8..990f5f42a9e 100644 --- a/docs/0.60/imagestore.html +++ b/docs/0.60/imagestore.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

ImageStore

Deprecated. Use expo-file-system or react-native-fs instead.

Methods

Reference

Methods

hasImageForTag()

static hasImageForTag(uri, callback)

Check if the ImageStore contains image data for the specified URI. @platform ios

removeImageForTag()

static removeImageForTag(uri)

Delete an image from the ImageStore. Images are stored in memory and must be manually removed when you are finished with them, otherwise they will continue to use up RAM until the app is terminated. It is safe to call removeImageForTag() without first calling hasImageForTag(), it will fail silently. @platform ios

addImageFromBase64()

static addImageFromBase64(base64ImageData, success, failure)

Stores a base64-encoded image in the ImageStore, and returns a URI that can be used to access or display the image later. Images are stored in memory only, and must be manually deleted when you are finished with them by calling removeImageForTag().

Note that it is very inefficient to transfer large quantities of binary data between JS and native code, so you should avoid calling this more than necessary. @platform ios

getBase64ForTag()

static getBase64ForTag(uri, success, failure)

Retrieves the base64-encoded data for an image in the ImageStore. If the specified URI does not match an image in the store, the failure callback will be called.

Note that it is very inefficient to transfer large quantities of binary data between JS and native code, so you should avoid calling this more than necessary. To display an image in the ImageStore, you can pass the URI to an <Image/> component; there is no need to retrieve the base64 data.

Edit this page
Last updated on
- + diff --git a/docs/0.60/imagestore/index.html b/docs/0.60/imagestore/index.html index 6ba4f909da8..990f5f42a9e 100644 --- a/docs/0.60/imagestore/index.html +++ b/docs/0.60/imagestore/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

ImageStore

Deprecated. Use expo-file-system or react-native-fs instead.

Methods

Reference

Methods

hasImageForTag()

static hasImageForTag(uri, callback)

Check if the ImageStore contains image data for the specified URI. @platform ios

removeImageForTag()

static removeImageForTag(uri)

Delete an image from the ImageStore. Images are stored in memory and must be manually removed when you are finished with them, otherwise they will continue to use up RAM until the app is terminated. It is safe to call removeImageForTag() without first calling hasImageForTag(), it will fail silently. @platform ios

addImageFromBase64()

static addImageFromBase64(base64ImageData, success, failure)

Stores a base64-encoded image in the ImageStore, and returns a URI that can be used to access or display the image later. Images are stored in memory only, and must be manually deleted when you are finished with them by calling removeImageForTag().

Note that it is very inefficient to transfer large quantities of binary data between JS and native code, so you should avoid calling this more than necessary. @platform ios

getBase64ForTag()

static getBase64ForTag(uri, success, failure)

Retrieves the base64-encoded data for an image in the ImageStore. If the specified URI does not match an image in the store, the failure callback will be called.

Note that it is very inefficient to transfer large quantities of binary data between JS and native code, so you should avoid calling this more than necessary. To display an image in the ImageStore, you can pass the URI to an <Image/> component; there is no need to retrieve the base64 data.

Edit this page
Last updated on
- + diff --git a/docs/0.60/improvingux.html b/docs/0.60/improvingux.html index f74de7f0e72..ddd1ad5d931 100644 --- a/docs/0.60/improvingux.html +++ b/docs/0.60/improvingux.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Improving User Experience

Configure text inputs

Entering text on touch phone is a challenge - small screen, software keyboard. But based on what kind of data you need, you can make it easier by properly configuring the text inputs:

  • Focus the first field automatically
  • Use placeholder text as an example of expected data format
  • Enable or disable autocapitalization and autocorrect
  • Choose keyboard type (e.g. email, numeric)
  • Make sure the return button focuses the next field or submits the form

Check out TextInput docs for more configuration options.

Try it on your phone

Manage layout when keyboard is visible

Software keyboard takes almost half of the screen. If you have interactive elements that can get covered by the keyboard, make sure they are still accessible by using the KeyboardAvoidingView component.

Try it on your phone

Make tappable areas larger

On mobile phones it's hard to be very precise when pressing buttons. Make sure all interactive elements are 44x44 or larger. One way to do this is to leave enough space for the element, padding, minWidth and minHeight style values can be useful for that. Alternatively, you can use hitSlop prop to increase interactive area without affecting the layout. Here's a demo:

Try it on your phone

Use Android Ripple

Android API 21+ uses the material design ripple to provide user with feedback when they touch an interactable area on the screen. React Native exposes this through the TouchableNativeFeedback component. Using this touchable effect instead of opacity or highlight will often make your app feel much more fitting on the platform. That said, you need to be careful when using it because it doesn't work on iOS or on Android API < 21, so you will need to fallback to using one of the other Touchable components on iOS. You can use a library like react-native-platform-touchable to handle the platform differences for you.

Try it on your phone

Screen orientation lock

Multiple screen orientations should work fine by default unless you're using Dimensions API and don't handle orientation changes. If you don't want to support multiple screen orientations, you can lock the screen orientation to either portrait or landscape.

On iOS, in the General tab and Deployment Info section of Xcode enable the Device Orientation you want to support (ensure you have selected iPhone from the Devices menu when making the changes). For Android, open the AndroidManifest.xml file and within the activity element add 'android:screenOrientation="portrait"' to lock to portrait or 'android:screenOrientation="landscape"' to lock to landscape.

Learn more

Material Design and Human Interface Guidelines are great resources for learning more about designing for mobile platforms.

Edit this page
Last updated on
- + diff --git a/docs/0.60/improvingux/index.html b/docs/0.60/improvingux/index.html index f74de7f0e72..ddd1ad5d931 100644 --- a/docs/0.60/improvingux/index.html +++ b/docs/0.60/improvingux/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Improving User Experience

Configure text inputs

Entering text on touch phone is a challenge - small screen, software keyboard. But based on what kind of data you need, you can make it easier by properly configuring the text inputs:

  • Focus the first field automatically
  • Use placeholder text as an example of expected data format
  • Enable or disable autocapitalization and autocorrect
  • Choose keyboard type (e.g. email, numeric)
  • Make sure the return button focuses the next field or submits the form

Check out TextInput docs for more configuration options.

Try it on your phone

Manage layout when keyboard is visible

Software keyboard takes almost half of the screen. If you have interactive elements that can get covered by the keyboard, make sure they are still accessible by using the KeyboardAvoidingView component.

Try it on your phone

Make tappable areas larger

On mobile phones it's hard to be very precise when pressing buttons. Make sure all interactive elements are 44x44 or larger. One way to do this is to leave enough space for the element, padding, minWidth and minHeight style values can be useful for that. Alternatively, you can use hitSlop prop to increase interactive area without affecting the layout. Here's a demo:

Try it on your phone

Use Android Ripple

Android API 21+ uses the material design ripple to provide user with feedback when they touch an interactable area on the screen. React Native exposes this through the TouchableNativeFeedback component. Using this touchable effect instead of opacity or highlight will often make your app feel much more fitting on the platform. That said, you need to be careful when using it because it doesn't work on iOS or on Android API < 21, so you will need to fallback to using one of the other Touchable components on iOS. You can use a library like react-native-platform-touchable to handle the platform differences for you.

Try it on your phone

Screen orientation lock

Multiple screen orientations should work fine by default unless you're using Dimensions API and don't handle orientation changes. If you don't want to support multiple screen orientations, you can lock the screen orientation to either portrait or landscape.

On iOS, in the General tab and Deployment Info section of Xcode enable the Device Orientation you want to support (ensure you have selected iPhone from the Devices menu when making the changes). For Android, open the AndroidManifest.xml file and within the activity element add 'android:screenOrientation="portrait"' to lock to portrait or 'android:screenOrientation="landscape"' to lock to landscape.

Learn more

Material Design and Human Interface Guidelines are great resources for learning more about designing for mobile platforms.

Edit this page
Last updated on
- + diff --git a/docs/0.60/inputaccessoryview.html b/docs/0.60/inputaccessoryview.html index 2bb1543658e..07f238be9ea 100644 --- a/docs/0.60/inputaccessoryview.html +++ b/docs/0.60/inputaccessoryview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

InputAccessoryView

A component which enables customization of the keyboard input accessory view on iOS. The input accessory view is displayed above the keyboard whenever a TextInput has focus. This component can be used to create custom toolbars.

To use this component wrap your custom toolbar with the InputAccessoryView component, and set a nativeID. Then, pass that nativeID as the inputAccessoryViewID of whatever TextInput you desire. A basic example:

This component can also be used to create sticky text inputs (text inputs which are anchored to the top of the keyboard). To do this, wrap a TextInput with the InputAccessoryView component, and don't set a nativeID. For an example, look at InputAccessoryViewExample.js.

Reference

Props

backgroundColor

TypeRequired
colorNo

nativeID

An ID which is used to associate this InputAccessoryView to specified TextInput(s).

TypeRequired
stringNo

style

TypeRequired
styleNo

Known issues

Edit this page
Last updated on
- + diff --git a/docs/0.60/inputaccessoryview/index.html b/docs/0.60/inputaccessoryview/index.html index 2bb1543658e..07f238be9ea 100644 --- a/docs/0.60/inputaccessoryview/index.html +++ b/docs/0.60/inputaccessoryview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

InputAccessoryView

A component which enables customization of the keyboard input accessory view on iOS. The input accessory view is displayed above the keyboard whenever a TextInput has focus. This component can be used to create custom toolbars.

To use this component wrap your custom toolbar with the InputAccessoryView component, and set a nativeID. Then, pass that nativeID as the inputAccessoryViewID of whatever TextInput you desire. A basic example:

This component can also be used to create sticky text inputs (text inputs which are anchored to the top of the keyboard). To do this, wrap a TextInput with the InputAccessoryView component, and don't set a nativeID. For an example, look at InputAccessoryViewExample.js.

Reference

Props

backgroundColor

TypeRequired
colorNo

nativeID

An ID which is used to associate this InputAccessoryView to specified TextInput(s).

TypeRequired
stringNo

style

TypeRequired
styleNo

Known issues

Edit this page
Last updated on
- + diff --git a/docs/0.60/integration-with-existing-apps.html b/docs/0.60/integration-with-existing-apps.html index 24b0674bbc2..e95190c03aa 100644 --- a/docs/0.60/integration-with-existing-apps.html +++ b/docs/0.60/integration-with-existing-apps.html @@ -19,7 +19,7 @@ - + @@ -48,7 +48,7 @@
if (mReactInstanceManager != null) {
mReactInstanceManager.onHostDestroy(this);
}
if (mReactRootView != null) {
mReactRootView.unmountReactApplication();
}
}

We also need to pass back button events to React Native:

@Override
public void onBackPressed() {
if (mReactInstanceManager != null) {
mReactInstanceManager.onBackPressed();
} else {
super.onBackPressed();
}
}

This allows JavaScript to control what happens when the user presses the hardware back button (e.g. to implement navigation). When JavaScript doesn't handle the back button press, your invokeDefaultOnBackPressed method will be called. By default this finishes your Activity.

Finally, we need to hook up the dev menu. By default, this is activated by (rage) shaking the device, but this is not very useful in emulators. So we make it show when you press the hardware menu button (use Ctrl + M if you're using Android Studio emulator):

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
if (keyCode == KeyEvent.KEYCODE_MENU && mReactInstanceManager != null) {
mReactInstanceManager.showDevOptionsDialog();
return true;
}
return super.onKeyUp(keyCode, event);
}

Now your activity is ready to run some JavaScript code.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ yarn start
2. Run the app

Now build and run your Android app as normal.

Once you reach your React-powered activity inside the app, it should load the JavaScript code from the development server and display:

Screenshot

Creating a release build in Android Studio

You can use Android Studio to create your release builds too! It’s as quick as creating release builds of your previously-existing native Android app. There’s one additional step, which you’ll have to do before every release build. You need to execute the following to create a React Native bundle, which will be included with your native Android app:

$ npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/com/your-company-name/app-package-name/src/main/assets/index.android.bundle --assets-dest android/com/your-company-name/app-package-name/src/main/res/

Don’t forget to replace the paths with correct ones and create the assets folder if it doesn’t exist.

Now, create a release build of your native app from within Android Studio as usual and you should be good to go!

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.60/integration-with-existing-apps/index.html b/docs/0.60/integration-with-existing-apps/index.html index 24b0674bbc2..e95190c03aa 100644 --- a/docs/0.60/integration-with-existing-apps/index.html +++ b/docs/0.60/integration-with-existing-apps/index.html @@ -19,7 +19,7 @@ - + @@ -48,7 +48,7 @@
if (mReactInstanceManager != null) {
mReactInstanceManager.onHostDestroy(this);
}
if (mReactRootView != null) {
mReactRootView.unmountReactApplication();
}
}

We also need to pass back button events to React Native:

@Override
public void onBackPressed() {
if (mReactInstanceManager != null) {
mReactInstanceManager.onBackPressed();
} else {
super.onBackPressed();
}
}

This allows JavaScript to control what happens when the user presses the hardware back button (e.g. to implement navigation). When JavaScript doesn't handle the back button press, your invokeDefaultOnBackPressed method will be called. By default this finishes your Activity.

Finally, we need to hook up the dev menu. By default, this is activated by (rage) shaking the device, but this is not very useful in emulators. So we make it show when you press the hardware menu button (use Ctrl + M if you're using Android Studio emulator):

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
if (keyCode == KeyEvent.KEYCODE_MENU && mReactInstanceManager != null) {
mReactInstanceManager.showDevOptionsDialog();
return true;
}
return super.onKeyUp(keyCode, event);
}

Now your activity is ready to run some JavaScript code.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ yarn start
2. Run the app

Now build and run your Android app as normal.

Once you reach your React-powered activity inside the app, it should load the JavaScript code from the development server and display:

Screenshot

Creating a release build in Android Studio

You can use Android Studio to create your release builds too! It’s as quick as creating release builds of your previously-existing native Android app. There’s one additional step, which you’ll have to do before every release build. You need to execute the following to create a React Native bundle, which will be included with your native Android app:

$ npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/com/your-company-name/app-package-name/src/main/assets/index.android.bundle --assets-dest android/com/your-company-name/app-package-name/src/main/res/

Don’t forget to replace the paths with correct ones and create the assets folder if it doesn’t exist.

Now, create a release build of your native app from within Android Studio as usual and you should be good to go!

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.60/interactionmanager.html b/docs/0.60/interactionmanager.html index ba8a78e1482..d965b91f43b 100644 --- a/docs/0.60/interactionmanager.html +++ b/docs/0.60/interactionmanager.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

InteractionManager

InteractionManager allows long-running work to be scheduled after any interactions/animations have completed. In particular, this allows JavaScript animations to run smoothly.

Applications can schedule tasks to run after interactions with the following:

InteractionManager.runAfterInteractions(() => {
// ...long-running synchronous task...
});

Compare this to other scheduling alternatives:

  • requestAnimationFrame(): for code that animates a view over time.
  • setImmediate/setTimeout(): run code later, note this may delay animations.
  • runAfterInteractions(): run code later, without delaying active animations.

The touch handling system considers one or more active touches to be an 'interaction' and will delay runAfterInteractions() callbacks until all touches have ended or been cancelled.

InteractionManager also allows applications to register animations by creating an interaction 'handle' on animation start, and clearing it upon completion:

var handle = InteractionManager.createInteractionHandle();
// run animation... (`runAfterInteractions` tasks are queued)
// later, on animation completion:
InteractionManager.clearInteractionHandle(handle);
// queued tasks run if all handles were cleared

runAfterInteractions takes either a plain callback function, or a PromiseTask object with a gen method that returns a Promise. If a PromiseTask is supplied, then it is fully resolved (including asynchronous dependencies that also schedule more tasks via runAfterInteractions) before starting on the next task that might have been queued up synchronously earlier.

By default, queued tasks are executed together in a loop in one setImmediate batch. If setDeadline is called with a positive number, then tasks will only be executed until the deadline (in terms of js event loop run time) approaches, at which point execution will yield via setTimeout, allowing events such as touches to start interactions and block queued tasks from executing, making apps more responsive.

Reference

Methods

runAfterInteractions()

static runAfterInteractions(task)

Schedule a function to run after all interactions have completed. Returns a cancellable "promise".

createInteractionHandle()

static createInteractionHandle()

Notify manager that an interaction has started.

clearInteractionHandle()

static clearInteractionHandle(handle)

Notify manager that an interaction has completed.

setDeadline()

static setDeadline(deadline)

A positive number will use setTimeout to schedule any tasks after the eventLoopRunningTime hits the deadline value, otherwise all tasks will be executed in one setImmediate batch (default).

Properties

Edit this page
Last updated on
- + diff --git a/docs/0.60/interactionmanager/index.html b/docs/0.60/interactionmanager/index.html index ba8a78e1482..d965b91f43b 100644 --- a/docs/0.60/interactionmanager/index.html +++ b/docs/0.60/interactionmanager/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

InteractionManager

InteractionManager allows long-running work to be scheduled after any interactions/animations have completed. In particular, this allows JavaScript animations to run smoothly.

Applications can schedule tasks to run after interactions with the following:

InteractionManager.runAfterInteractions(() => {
// ...long-running synchronous task...
});

Compare this to other scheduling alternatives:

  • requestAnimationFrame(): for code that animates a view over time.
  • setImmediate/setTimeout(): run code later, note this may delay animations.
  • runAfterInteractions(): run code later, without delaying active animations.

The touch handling system considers one or more active touches to be an 'interaction' and will delay runAfterInteractions() callbacks until all touches have ended or been cancelled.

InteractionManager also allows applications to register animations by creating an interaction 'handle' on animation start, and clearing it upon completion:

var handle = InteractionManager.createInteractionHandle();
// run animation... (`runAfterInteractions` tasks are queued)
// later, on animation completion:
InteractionManager.clearInteractionHandle(handle);
// queued tasks run if all handles were cleared

runAfterInteractions takes either a plain callback function, or a PromiseTask object with a gen method that returns a Promise. If a PromiseTask is supplied, then it is fully resolved (including asynchronous dependencies that also schedule more tasks via runAfterInteractions) before starting on the next task that might have been queued up synchronously earlier.

By default, queued tasks are executed together in a loop in one setImmediate batch. If setDeadline is called with a positive number, then tasks will only be executed until the deadline (in terms of js event loop run time) approaches, at which point execution will yield via setTimeout, allowing events such as touches to start interactions and block queued tasks from executing, making apps more responsive.

Reference

Methods

runAfterInteractions()

static runAfterInteractions(task)

Schedule a function to run after all interactions have completed. Returns a cancellable "promise".

createInteractionHandle()

static createInteractionHandle()

Notify manager that an interaction has started.

clearInteractionHandle()

static clearInteractionHandle(handle)

Notify manager that an interaction has completed.

setDeadline()

static setDeadline(deadline)

A positive number will use setTimeout to schedule any tasks after the eventLoopRunningTime hits the deadline value, otherwise all tasks will be executed in one setImmediate batch (default).

Properties

Edit this page
Last updated on
- + diff --git a/docs/0.60/intro-react-native-components.html b/docs/0.60/intro-react-native-components.html index 405ee2a2507..f43317a87c0 100644 --- a/docs/0.60/intro-react-native-components.html +++ b/docs/0.60/intro-react-native-components.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Core Components and Native Components

React Native is an open source framework for building Android and iOS applications using React and the app platform’s native capabilities. With React Native, you use JavaScript to access your platform’s APIs as well as to describe the appearance and behavior of your UI using React components: bundles of reusable, nestable code. You can learn more about React in the next section. But first, let’s cover how components work in React Native.

Views and mobile development

In Android and iOS development, a view is the basic building block of UI: a small rectangular element on the screen which can be used to display text, images, or respond to user input. Even the smallest visual elements of an app, like a line of text or a button, are kinds of views. Some kinds of views can contain other views. It’s views all the way down!

Diagram of Android and iOS app showing them both built on top of atomic elements called views.
Just a sampling of the many views used in Android and iOS apps.

Native Components

In Android development, you write views in Kotlin or Java; in iOS development, you use Swift or Objective-C. With React Native, you can invoke these views with JavaScript using React components. At runtime, React Native creates the corresponding Android and iOS views for those components. Because React Native components are backed by the same views as Android and iOS, React Native apps look, feel, and perform like any other apps. We call these platform-backed components Native Components.

React Native lets you to build your own Native Components for Android and iOS to suit your app’s unique needs. We also have a thriving ecosystem of these community-contributed components. Check out Native Directory to find what the community has been creating.

React Native also includes a set of essential, ready-to-use Native Components you can use to start building your app today. These are React Native's Core Components.

Core Components

React Native has many Core Components for everything from form controls to activity indicators. You can find them all documented in the API section. You will mostly work with the following Core Components:

React Native UI ComponentAndroid ViewiOS ViewWeb AnalogDescription
<View><ViewGroup><UIView>A non-scrollling <div>A container that supports layout with flexbox, style, some touch handling, and accessibility controls
<Text><TextView><UITextView><p>Displays, styles, and nests strings of text and even handles touch events
<Image><ImageView><UIImageView><img>Displays different types of images
<ScrollView><ScrollView><UIScrollView><div>A generic scrolling container that can contain multiple components and views
<TextInput><EditText><UITextField><input type="text">Allows the user to enter text

In the next section, you will start combining these Core Components to learn about how React works. Have a play with them here now!

Because React Native uses the same API structure as React components, you’ll need to understand React component APIs to get started. The next section makes for a quick introduction or refresher on the topic. However, if you’re already familiar with React, feel free to skip ahead.

A diagram showing React Native's Core Components are a subset of React Components that ship with React Native.
Edit this page
Last updated on
- + diff --git a/docs/0.60/intro-react-native-components/index.html b/docs/0.60/intro-react-native-components/index.html index 405ee2a2507..f43317a87c0 100644 --- a/docs/0.60/intro-react-native-components/index.html +++ b/docs/0.60/intro-react-native-components/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Core Components and Native Components

React Native is an open source framework for building Android and iOS applications using React and the app platform’s native capabilities. With React Native, you use JavaScript to access your platform’s APIs as well as to describe the appearance and behavior of your UI using React components: bundles of reusable, nestable code. You can learn more about React in the next section. But first, let’s cover how components work in React Native.

Views and mobile development

In Android and iOS development, a view is the basic building block of UI: a small rectangular element on the screen which can be used to display text, images, or respond to user input. Even the smallest visual elements of an app, like a line of text or a button, are kinds of views. Some kinds of views can contain other views. It’s views all the way down!

Diagram of Android and iOS app showing them both built on top of atomic elements called views.
Just a sampling of the many views used in Android and iOS apps.

Native Components

In Android development, you write views in Kotlin or Java; in iOS development, you use Swift or Objective-C. With React Native, you can invoke these views with JavaScript using React components. At runtime, React Native creates the corresponding Android and iOS views for those components. Because React Native components are backed by the same views as Android and iOS, React Native apps look, feel, and perform like any other apps. We call these platform-backed components Native Components.

React Native lets you to build your own Native Components for Android and iOS to suit your app’s unique needs. We also have a thriving ecosystem of these community-contributed components. Check out Native Directory to find what the community has been creating.

React Native also includes a set of essential, ready-to-use Native Components you can use to start building your app today. These are React Native's Core Components.

Core Components

React Native has many Core Components for everything from form controls to activity indicators. You can find them all documented in the API section. You will mostly work with the following Core Components:

React Native UI ComponentAndroid ViewiOS ViewWeb AnalogDescription
<View><ViewGroup><UIView>A non-scrollling <div>A container that supports layout with flexbox, style, some touch handling, and accessibility controls
<Text><TextView><UITextView><p>Displays, styles, and nests strings of text and even handles touch events
<Image><ImageView><UIImageView><img>Displays different types of images
<ScrollView><ScrollView><UIScrollView><div>A generic scrolling container that can contain multiple components and views
<TextInput><EditText><UITextField><input type="text">Allows the user to enter text

In the next section, you will start combining these Core Components to learn about how React works. Have a play with them here now!

Because React Native uses the same API structure as React components, you’ll need to understand React component APIs to get started. The next section makes for a quick introduction or refresher on the topic. However, if you’re already familiar with React, feel free to skip ahead.

A diagram showing React Native's Core Components are a subset of React Components that ship with React Native.
Edit this page
Last updated on
- + diff --git a/docs/0.60/intro-react.html b/docs/0.60/intro-react.html index d2f32c550e0..52b82372cf7 100644 --- a/docs/0.60/intro-react.html +++ b/docs/0.60/intro-react.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
export default Cat;

This is one of many ways to export your component. This kind of export works well with the Snack Player. However, depending on your app’s file structure, you might need to use a different convention. This handy cheatsheet on JavaScript imports and exports can help.

Now take a closer look at that return statement. <Text>Hello, I am your cat!</Text> is using a kind of JavaScript syntax that makes writing elements convenient: JSX.

JSX

React and React Native use JSX, a syntax that lets you write elements inside JavaScript like so: <Text>Hello, I am your cat!</Text>. The React docs have a comprehensive guide to JSX you can reference to learn even more. Because JSX is JavaScript, you can use variables inside it. Here you are declaring a name for the cat, name, and embedding it with curly braces inside <Text>.

Any JavaScript expression will work between curly braces, including function calls like {getFullName("Rum", "Tum", "Tugger")}:

You can think of curly braces as creating a portal into JS functionality in your JSX!

Because JSX is included in the React library, it won’t work if you don’t have import React from 'react' at the top of your file!

Custom Components

You’ve already met React Native’s Core Components. React lets you nest these components inside each other to create new components. These nestable, reusable components are at the heart of the React paradigm.

For example, you can nest Text and TextInput inside a View below, and React Native will render them together:

Developer notes

If you’re familiar with web development, <View> and <Text> might remind you of HTML! You can think of them as the <div> and <p> tags of application development.

You can render this component multiple times and in multiple places without repeating your code by using <Cat>:

Any component that renders other components is a parent component. Here, Cafe is the parent component and each Cat is a child component.

You can put as many cats in your cafe as you like. Each <Cat> renders a unique element—which you can customize with props.

Props

Props is short for “properties.” Props let you customize React components. For example, here you pass each <Cat> a different name for Cat to render:

Most of React Native’s Core Components can be customized with props, too. For example, when using Image, you pass it a prop named source to define what image it shows:

Image has many different props, including style, which accepts a JS object of design and layout related property-value pairs.

Notice the double curly braces {{ }} surrounding style‘s width and height. In JSX, JavaScript values are referenced with {}. This is handy if you are passing something other than a string as props, like an array or number: <Cat food={["fish", "kibble"]} age={2} />. However, JS objects are also denoted with curly braces: {width: 200, height: 200}. Therefore, to pass a JS object in JSX, you must wrap the object in another pair of curly braces: {{width: 200, height: 200}}

You can build many things with props and the Core Components Text, Image, and View! But to build something interactive, you’ll need state.

State

While you can think of props as arguments you use to configure how components render, state is like a component’s personal data storage. State is useful for handling data that changes over time or that comes from user interaction. State gives your components memory!

As a general rule, use props to configure a component when it renders. Use state to keep track of any component data that you expect to change over time.

The following example takes place in a cat cafe where two hungry cats are waiting to be fed. Their hunger, which we expect to change over time (unlike their names), is stored as state. To feed the cats, press their buttons—which will update their state.

You can add state to a component by calling React’s useState Hook. A Hook is a kind of function that lets you “hook into” React features. For example, useState is a Hook that lets you add state to function components. You can learn more about other kinds of Hooks in the React documentation.

First, you will want to import useState from React like so:

import React, { useState } from 'react';

Then you declare the component’s state by calling useState inside its function. In this example, useState creates an isHungry state variable:

const Cat = (props) => {
const [isHungry, setIsHungry] = useState(true);
// ...
};

You can use useState to track any kind of data: strings, numbers, Booleans, arrays, objects. For example, you can track the number of times a cat has been petted with const [timesPetted, setTimesPetted] = useState(0)!

Calling useState does two things:

  • it creates a “state variable” with an initial value—in this case the state variable is isHungry and its initial value is true
  • it creates a function to set that state variable’s value—setIsHungry

It doesn’t matter what names you use. But it can be handy to think of the pattern as [<getter>, <setter>] = useState(<initialValue>).

Next you add the Button Core Component and give it an onPress prop:

<Button
onPress={() => {
setIsHungry(false);
}}
//..
/>

Now, when someone presses the button, onPress will fire, calling the setIsHungry(false). This sets the state variable isHungry to false. When isHungry is false, the Button’s disabled prop is set to true and its title also changes:

<Button
//..
disabled={!isHungry}
title={isHungry ? 'Pour me some milk, please!' : 'Thank you!'}
/>

You might’ve noticed that although isHungry is a const, it is seemingly reassignable! What is happening is when a state-setting function like setIsHungry is called, its component will re-render. In this case the Cat function will run again—and this time, useState will give us the next value of isHungry.

Finally, put your cats inside a Cafe component:

const Cafe = () => {
return (
<>
<Cat name="Munkustrap" />
<Cat name="Spot" />
</>
);
};

See the <> and </> above? These bits of JSX are fragments. Adjacent JSX elements must be wrapped in an enclosing tag. Fragments let you do that without nesting an extra, unnecessary wrapping element like View.

Now that you’ve covered both React and React Native’s Core Components, let’s dive deeper on some of these core components by looking at handling <TextInput>.

Edit this page
Last updated on
- + diff --git a/docs/0.60/intro-react/index.html b/docs/0.60/intro-react/index.html index d2f32c550e0..52b82372cf7 100644 --- a/docs/0.60/intro-react/index.html +++ b/docs/0.60/intro-react/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
export default Cat;

This is one of many ways to export your component. This kind of export works well with the Snack Player. However, depending on your app’s file structure, you might need to use a different convention. This handy cheatsheet on JavaScript imports and exports can help.

Now take a closer look at that return statement. <Text>Hello, I am your cat!</Text> is using a kind of JavaScript syntax that makes writing elements convenient: JSX.

JSX

React and React Native use JSX, a syntax that lets you write elements inside JavaScript like so: <Text>Hello, I am your cat!</Text>. The React docs have a comprehensive guide to JSX you can reference to learn even more. Because JSX is JavaScript, you can use variables inside it. Here you are declaring a name for the cat, name, and embedding it with curly braces inside <Text>.

Any JavaScript expression will work between curly braces, including function calls like {getFullName("Rum", "Tum", "Tugger")}:

You can think of curly braces as creating a portal into JS functionality in your JSX!

Because JSX is included in the React library, it won’t work if you don’t have import React from 'react' at the top of your file!

Custom Components

You’ve already met React Native’s Core Components. React lets you nest these components inside each other to create new components. These nestable, reusable components are at the heart of the React paradigm.

For example, you can nest Text and TextInput inside a View below, and React Native will render them together:

Developer notes

If you’re familiar with web development, <View> and <Text> might remind you of HTML! You can think of them as the <div> and <p> tags of application development.

You can render this component multiple times and in multiple places without repeating your code by using <Cat>:

Any component that renders other components is a parent component. Here, Cafe is the parent component and each Cat is a child component.

You can put as many cats in your cafe as you like. Each <Cat> renders a unique element—which you can customize with props.

Props

Props is short for “properties.” Props let you customize React components. For example, here you pass each <Cat> a different name for Cat to render:

Most of React Native’s Core Components can be customized with props, too. For example, when using Image, you pass it a prop named source to define what image it shows:

Image has many different props, including style, which accepts a JS object of design and layout related property-value pairs.

Notice the double curly braces {{ }} surrounding style‘s width and height. In JSX, JavaScript values are referenced with {}. This is handy if you are passing something other than a string as props, like an array or number: <Cat food={["fish", "kibble"]} age={2} />. However, JS objects are also denoted with curly braces: {width: 200, height: 200}. Therefore, to pass a JS object in JSX, you must wrap the object in another pair of curly braces: {{width: 200, height: 200}}

You can build many things with props and the Core Components Text, Image, and View! But to build something interactive, you’ll need state.

State

While you can think of props as arguments you use to configure how components render, state is like a component’s personal data storage. State is useful for handling data that changes over time or that comes from user interaction. State gives your components memory!

As a general rule, use props to configure a component when it renders. Use state to keep track of any component data that you expect to change over time.

The following example takes place in a cat cafe where two hungry cats are waiting to be fed. Their hunger, which we expect to change over time (unlike their names), is stored as state. To feed the cats, press their buttons—which will update their state.

You can add state to a component by calling React’s useState Hook. A Hook is a kind of function that lets you “hook into” React features. For example, useState is a Hook that lets you add state to function components. You can learn more about other kinds of Hooks in the React documentation.

First, you will want to import useState from React like so:

import React, { useState } from 'react';

Then you declare the component’s state by calling useState inside its function. In this example, useState creates an isHungry state variable:

const Cat = (props) => {
const [isHungry, setIsHungry] = useState(true);
// ...
};

You can use useState to track any kind of data: strings, numbers, Booleans, arrays, objects. For example, you can track the number of times a cat has been petted with const [timesPetted, setTimesPetted] = useState(0)!

Calling useState does two things:

  • it creates a “state variable” with an initial value—in this case the state variable is isHungry and its initial value is true
  • it creates a function to set that state variable’s value—setIsHungry

It doesn’t matter what names you use. But it can be handy to think of the pattern as [<getter>, <setter>] = useState(<initialValue>).

Next you add the Button Core Component and give it an onPress prop:

<Button
onPress={() => {
setIsHungry(false);
}}
//..
/>

Now, when someone presses the button, onPress will fire, calling the setIsHungry(false). This sets the state variable isHungry to false. When isHungry is false, the Button’s disabled prop is set to true and its title also changes:

<Button
//..
disabled={!isHungry}
title={isHungry ? 'Pour me some milk, please!' : 'Thank you!'}
/>

You might’ve noticed that although isHungry is a const, it is seemingly reassignable! What is happening is when a state-setting function like setIsHungry is called, its component will re-render. In this case the Cat function will run again—and this time, useState will give us the next value of isHungry.

Finally, put your cats inside a Cafe component:

const Cafe = () => {
return (
<>
<Cat name="Munkustrap" />
<Cat name="Spot" />
</>
);
};

See the <> and </> above? These bits of JSX are fragments. Adjacent JSX elements must be wrapped in an enclosing tag. Fragments let you do that without nesting an extra, unnecessary wrapping element like View.

Now that you’ve covered both React and React Native’s Core Components, let’s dive deeper on some of these core components by looking at handling <TextInput>.

Edit this page
Last updated on
- + diff --git a/docs/0.60/javascript-environment.html b/docs/0.60/javascript-environment.html index f1e31a73c19..a099caa9e2e 100644 --- a/docs/0.60/javascript-environment.html +++ b/docs/0.60/javascript-environment.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

JavaScript Environment

JavaScript Runtime

When using React Native, you're going to be running your JavaScript code in two environments:

  • In most cases, React Native will use JavaScriptCore, the JavaScript engine that powers Safari. Note that on iOS, JavaScriptCore does not use JIT due to the absence of writable executable memory in iOS apps.
  • When using Chrome debugging, all JavaScript code runs within Chrome itself, communicating with native code via WebSockets. Chrome uses V8 as its JavaScript engine.

While both environments are very similar, you may end up hitting some inconsistencies. We're likely going to experiment with other JavaScript engines in the future, so it's best to avoid relying on specifics of any runtime.

JavaScript Syntax Transformers

Syntax transformers make writing code more enjoyable by allowing you to use new JavaScript syntax without having to wait for support on all interpreters.

React Native ships with the Babel JavaScript compiler. Check Babel documentation on its supported transformations for more details.

A full list of React Native's enabled transformations can be found in metro-react-native-babel-preset.

ES5

  • Reserved Words: promise.catch(function() { });

ES6

ES8

Stage 3

Specific

  • JSX: <View style={{color: 'red'}} />
  • Flow: function foo(x: ?number): string {};
  • TypeScript: function foo(x: number | undefined): string {};
  • Babel Template: allows AST templating

Polyfills

Many standards functions are also available on all the supported JavaScript runtimes.

Browser

ES6

ES7

ES8

Specific

  • __DEV__
Edit this page
Last updated on
- + diff --git a/docs/0.60/javascript-environment/index.html b/docs/0.60/javascript-environment/index.html index f1e31a73c19..a099caa9e2e 100644 --- a/docs/0.60/javascript-environment/index.html +++ b/docs/0.60/javascript-environment/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

JavaScript Environment

JavaScript Runtime

When using React Native, you're going to be running your JavaScript code in two environments:

  • In most cases, React Native will use JavaScriptCore, the JavaScript engine that powers Safari. Note that on iOS, JavaScriptCore does not use JIT due to the absence of writable executable memory in iOS apps.
  • When using Chrome debugging, all JavaScript code runs within Chrome itself, communicating with native code via WebSockets. Chrome uses V8 as its JavaScript engine.

While both environments are very similar, you may end up hitting some inconsistencies. We're likely going to experiment with other JavaScript engines in the future, so it's best to avoid relying on specifics of any runtime.

JavaScript Syntax Transformers

Syntax transformers make writing code more enjoyable by allowing you to use new JavaScript syntax without having to wait for support on all interpreters.

React Native ships with the Babel JavaScript compiler. Check Babel documentation on its supported transformations for more details.

A full list of React Native's enabled transformations can be found in metro-react-native-babel-preset.

ES5

  • Reserved Words: promise.catch(function() { });

ES6

ES8

Stage 3

Specific

  • JSX: <View style={{color: 'red'}} />
  • Flow: function foo(x: ?number): string {};
  • TypeScript: function foo(x: number | undefined): string {};
  • Babel Template: allows AST templating

Polyfills

Many standards functions are also available on all the supported JavaScript runtimes.

Browser

ES6

ES7

ES8

Specific

  • __DEV__
Edit this page
Last updated on
- + diff --git a/docs/0.60/keyboard.html b/docs/0.60/keyboard.html index 497ebe22735..d15148f5ef9 100644 --- a/docs/0.60/keyboard.html +++ b/docs/0.60/keyboard.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
render() {
return <TextInput onSubmitEditing={Keyboard.dismiss} />;
}
}

Reference

Methods

addListener()

static addListener(eventName, callback)

The addListener function connects a JavaScript function to an identified native keyboard notification event.

This function then returns the reference to the listener.

@param {string} eventName The nativeEvent is the string that identifies the event you're listening for. This can be any of the following:

Note that if you set android:windowSoftInputMode to adjustResize, only keyboardDidShow and keyboardDidHide events will be available on Android. If you set android:windowSoftInputMode to adjustNothing, no events will be available on Android. keyboardWillShow as well as keyboardWillHide are generally not available on Android since there is no native corresponding event.

@param {function} callback function to be called when the event fires.

removeListener()

static removeListener(eventName, callback)

Removes a specific listener.

@param {string} eventName The nativeEvent is the string that identifies the event you're listening for. @param {function} callback function to be called when the event fires.

removeAllListeners()

static removeAllListeners(eventName)

Removes all listeners for a specific event type.

@param {string} eventType The native event string listeners are watching which will be removed.

dismiss()

static dismiss()

Dismisses the active keyboard and removes focus.

Edit this page
Last updated on
- + diff --git a/docs/0.60/keyboard/index.html b/docs/0.60/keyboard/index.html index 497ebe22735..d15148f5ef9 100644 --- a/docs/0.60/keyboard/index.html +++ b/docs/0.60/keyboard/index.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
render() {
return <TextInput onSubmitEditing={Keyboard.dismiss} />;
}
}

Reference

Methods

addListener()

static addListener(eventName, callback)

The addListener function connects a JavaScript function to an identified native keyboard notification event.

This function then returns the reference to the listener.

@param {string} eventName The nativeEvent is the string that identifies the event you're listening for. This can be any of the following:

Note that if you set android:windowSoftInputMode to adjustResize, only keyboardDidShow and keyboardDidHide events will be available on Android. If you set android:windowSoftInputMode to adjustNothing, no events will be available on Android. keyboardWillShow as well as keyboardWillHide are generally not available on Android since there is no native corresponding event.

@param {function} callback function to be called when the event fires.

removeListener()

static removeListener(eventName, callback)

Removes a specific listener.

@param {string} eventName The nativeEvent is the string that identifies the event you're listening for. @param {function} callback function to be called when the event fires.

removeAllListeners()

static removeAllListeners(eventName)

Removes all listeners for a specific event type.

@param {string} eventType The native event string listeners are watching which will be removed.

dismiss()

static dismiss()

Dismisses the active keyboard and removes focus.

Edit this page
Last updated on
- + diff --git a/docs/0.60/keyboardavoidingview.html b/docs/0.60/keyboardavoidingview.html index 90cc7303108..103e5c2bb6c 100644 --- a/docs/0.60/keyboardavoidingview.html +++ b/docs/0.60/keyboardavoidingview.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
<KeyboardAvoidingView
style={styles.container}
behavior="padding"
enabled>
... your UI ...
</KeyboardAvoidingView>;

Example

Reference

Props

Inherits View Props.

behavior

Specify how to react to the presence of the keyboard.

Note: Android and iOS both interact with this prop differently. Android may behave better when given no behavior prop at all, whereas iOS is the opposite.

TypeRequired
enum('height', 'position', 'padding')No

contentContainerStyle

The style of the content container(View) when behavior is 'position'.

TypeRequired
View.styleNo

enabled

Enabled or disabled KeyboardAvoidingView. The default is true.

TypeRequired
booleanNo

keyboardVerticalOffset

This is the distance between the top of the user screen and the react native view, may be non-zero in some use cases. Defaults to 0.

TypeRequired
numberNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/keyboardavoidingview/index.html b/docs/0.60/keyboardavoidingview/index.html index 90cc7303108..103e5c2bb6c 100644 --- a/docs/0.60/keyboardavoidingview/index.html +++ b/docs/0.60/keyboardavoidingview/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
<KeyboardAvoidingView
style={styles.container}
behavior="padding"
enabled>
... your UI ...
</KeyboardAvoidingView>;

Example

Reference

Props

Inherits View Props.

behavior

Specify how to react to the presence of the keyboard.

Note: Android and iOS both interact with this prop differently. Android may behave better when given no behavior prop at all, whereas iOS is the opposite.

TypeRequired
enum('height', 'position', 'padding')No

contentContainerStyle

The style of the content container(View) when behavior is 'position'.

TypeRequired
View.styleNo

enabled

Enabled or disabled KeyboardAvoidingView. The default is true.

TypeRequired
booleanNo

keyboardVerticalOffset

This is the distance between the top of the user screen and the react native view, may be non-zero in some use cases. Defaults to 0.

TypeRequired
numberNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/layout-props.html b/docs/0.60/layout-props.html index 0d7eddeae87..57a4de1ccf0 100644 --- a/docs/0.60/layout-props.html +++ b/docs/0.60/layout-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Layout Props

Reference

Props

alignContent

alignContent controls how rows align in the cross direction, overriding the alignContent of the parent. See https://developer.mozilla.org/en-US/docs/Web/CSS/align-content for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'stretch', 'space-between', 'space-around')No

alignItems

alignItems aligns children in the cross direction. For example, if children are flowing vertically, alignItems controls how they align horizontally. It works like align-items in CSS (default: stretch). See https://developer.mozilla.org/en-US/docs/Web/CSS/align-items for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'stretch', 'baseline')No

alignSelf

alignSelf controls how a child aligns in the cross direction, overriding the alignItems of the parent. It works like align-self in CSS (default: auto). See https://developer.mozilla.org/en-US/docs/Web/CSS/align-self for more details.

TypeRequired
enum('auto', 'flex-start', 'flex-end', 'center', 'stretch', 'baseline')No

aspectRatio

Aspect ratio controls the size of the undefined dimension of a node. Aspect ratio is a non-standard property only available in React Native and not CSS.

  • On a node with a set width/height aspect ratio controls the size of the unset dimension
  • On a node with a set flex basis aspect ratio controls the size of the node in the cross axis if unset
  • On a node with a measure function aspect ratio works as though the measure function measures the flex basis
  • On a node with flex grow/shrink aspect ratio controls the size of the node in the cross axis if unset
  • Aspect ratio takes min/max dimensions into account
TypeRequired
numberNo

borderBottomWidth

borderBottomWidth works like border-bottom-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-width for more details.

TypeRequired
numberNo

borderEndWidth

When direction is ltr, borderEndWidth is equivalent to borderRightWidth. When direction is rtl, borderEndWidth is equivalent to borderLeftWidth.

TypeRequired
numberNo

borderLeftWidth

borderLeftWidth works like border-left-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-left-width for more details.

TypeRequired
numberNo

borderRightWidth

borderRightWidth works like border-right-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-right-width for more details.

TypeRequired
numberNo

borderStartWidth

When direction is ltr, borderStartWidth is equivalent to borderLeftWidth. When direction is rtl, borderStartWidth is equivalent to borderRightWidth.

TypeRequired
numberNo

borderTopWidth

borderTopWidth works like border-top-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-top-width for more details.

TypeRequired
numberNo

borderWidth

borderWidth works like border-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-width for more details.

TypeRequired
numberNo

bottom

bottom is the number of logical pixels to offset the bottom edge of this component.

It works similarly to bottom in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/bottom for more details of how bottom affects layout.

TypeRequired
number, stringNo

direction

direction specifies the directional flow of the user interface. The default is inherit, except for root node which will have value based on the current locale. See https://yogalayout.com/docs/layout-direction for more details.

TypeRequiredPlatform
enum('inherit', 'ltr', 'rtl')NoiOS

display

display sets the display type of this component.

It works similarly to display in CSS, but only support 'flex' and 'none'. 'flex' is the default.

TypeRequired
enum('none', 'flex')No

end

When the direction is ltr, end is equivalent to right. When the direction is rtl, end is equivalent to left.

This style takes precedence over the left and right styles.

TypeRequired
number, stringNo

flex

In React Native flex does not work the same way that it does in CSS. flex is a number rather than a string, and it works according to the Yoga.

When flex is a positive number, it makes the component flexible and it will be sized proportional to its flex value. So a component with flex set to 2 will take twice the space as a component with flex set to 1. flex: <positive number> equates to flexGrow: <positive number>, flexShrink: 1, flexBasis: 0.

When flex is 0, the component is sized according to width and height and it is inflexible.

When flex is -1, the component is normally sized according width and height. However, if there's not enough space, the component will shrink to its minWidth and minHeight.

flexGrow, flexShrink, and flexBasis work the same as in CSS.

TypeRequired
numberNo

flexBasis

TypeRequired
number, stringNo

flexDirection

flexDirection controls which directions children of a container go. row goes left to right, column goes top to bottom, and you may be able to guess what the other two do. It works like flex-direction in CSS, except the default is column. See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction for more details.

TypeRequired
enum('row', 'row-reverse', 'column', 'column-reverse')No

flexGrow

TypeRequired
numberNo

flexShrink

TypeRequired
numberNo

flexWrap

flexWrap controls whether children can wrap around after they hit the end of a flex container. It works like flex-wrap in CSS (default: nowrap). See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-wrap for more details. Note it does not work anymore with alignItems: stretch (the default), so you may want to use alignItems: flex-start for example (breaking change details: https://github.com/facebook/react-native/releases/tag/v0.28.0).

TypeRequired
enum('wrap', 'nowrap')No

height

height sets the height of this component.

It works similarly to height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported. See https://developer.mozilla.org/en-US/docs/Web/CSS/height for more details.

TypeRequired
number, stringNo

justifyContent

justifyContent aligns children in the main direction. For example, if children are flowing vertically, justifyContent controls how they align vertically. It works like justify-content in CSS (default: flex-start). See https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'space-between', 'space-around', 'space-evenly')No

left

left is the number of logical pixels to offset the left edge of this component.

It works similarly to left in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/left for more details of how left affects layout.

TypeRequired
number, stringNo

margin

Setting margin has the same effect as setting each of marginTop, marginLeft, marginBottom, and marginRight. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin for more details.

TypeRequired
number, stringNo

marginBottom

marginBottom works like margin-bottom in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-bottom for more details.

TypeRequired
number, stringNo

marginEnd

When direction is ltr, marginEnd is equivalent to marginRight. When direction is rtl, marginEnd is equivalent to marginLeft.

TypeRequired
number, stringNo

marginHorizontal

Setting marginHorizontal has the same effect as setting both marginLeft and marginRight.

TypeRequired
number, stringNo

marginLeft

marginLeft works like margin-left in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-left for more details.

TypeRequired
number, stringNo

marginRight

marginRight works like margin-right in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-right for more details.

TypeRequired
number, stringNo

marginStart

When direction is ltr, marginStart is equivalent to marginLeft. When direction is rtl, marginStart is equivalent to marginRight.

TypeRequired
number, stringNo

marginTop

marginTop works like margin-top in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-top for more details.

TypeRequired
number, stringNo

marginVertical

Setting marginVertical has the same effect as setting both marginTop and marginBottom.

TypeRequired
number, stringNo

maxHeight

maxHeight is the maximum height for this component, in logical pixels.

It works similarly to max-height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/max-height for more details.

TypeRequired
number, stringNo

maxWidth

maxWidth is the maximum width for this component, in logical pixels.

It works similarly to max-width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/max-width for more details.

TypeRequired
number, stringNo

minHeight

minHeight is the minimum height for this component, in logical pixels.

It works similarly to min-height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/min-height for more details.

TypeRequired
number, stringNo

minWidth

minWidth is the minimum width for this component, in logical pixels.

It works similarly to min-width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/min-width for more details.

TypeRequired
number, stringNo

overflow

overflow controls how children are measured and displayed. overflow: hidden causes views to be clipped while overflow: scroll causes views to be measured independently of their parents main axis. It works like overflow in CSS (default: visible). See https://developer.mozilla.org/en/docs/Web/CSS/overflow for more details.

TypeRequired
enum('visible', 'hidden', 'scroll')No

padding

Setting padding has the same effect as setting each of paddingTop, paddingBottom, paddingLeft, and paddingRight. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding for more details.

TypeRequired
number, stringNo

paddingBottom

paddingBottom works like padding-bottom in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-bottom for more details.

TypeRequired
number, stringNo

paddingEnd

When direction is ltr, paddingEnd is equivalent to paddingRight. When direction is rtl, paddingEnd is equivalent to paddingLeft.

TypeRequired
number, stringNo

paddingHorizontal

Setting paddingHorizontal is like setting both of paddingLeft and paddingRight.

TypeRequired
number, stringNo

paddingLeft

paddingLeft works like padding-left in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-left for more details.

TypeRequired
number, stringNo

paddingRight

paddingRight works like padding-right in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-right for more details.

TypeRequired
number, stringNo

paddingStart

When direction is ltr, paddingStart is equivalent to paddingLeft. When direction is rtl, paddingStart is equivalent to paddingRight.

TypeRequired
number, stringNo

paddingTop

paddingTop works like padding-top in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-top for more details.

TypeRequired
number, ,stringNo

paddingVertical

Setting paddingVertical is like setting both of paddingTop and paddingBottom.

TypeRequired
number, stringNo

position

position in React Native is similar to regular CSS, but everything is set to relative by default, so absolute positioning is always relative to the parent.

If you want to position a child using specific numbers of logical pixels relative to its parent, set the child to have absolute position.

If you want to position a child relative to something that is not its parent, don't use styles for that. Use the component tree.

See https://github.com/facebook/yoga for more details on how position differs between React Native and CSS.

TypeRequired
enum('absolute', 'relative')No

right

right is the number of logical pixels to offset the right edge of this component.

It works similarly to right in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/right for more details of how right affects layout.

TypeRequired
number, stringNo

start

When the direction is ltr, start is equivalent to left. When the direction is rtl, start is equivalent to right.

This style takes precedence over the left, right, and end styles.

TypeRequired
number, stringNo

top

top is the number of logical pixels to offset the top edge of this component.

It works similarly to top in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/top for more details of how top affects layout.

TypeRequired
number, stringNo

width

width sets the width of this component.

It works similarly to width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported. See https://developer.mozilla.org/en-US/docs/Web/CSS/width for more details.

TypeRequired
number, stringNo

zIndex

zIndex controls which components display on top of others. Normally, you don't use zIndex. Components render according to their order in the document tree, so later components draw over earlier ones. zIndex may be useful if you have animations or custom modal interfaces where you don't want this behavior.

It works like the CSS z-index property - components with a larger zIndex will render on top. Think of the z-direction like it's pointing from the phone into your eyeball. See https://developer.mozilla.org/en-US/docs/Web/CSS/z-index for more details.

On iOS, zIndex may require Views to be siblings of each other for it to work as expected.

TypeRequired
numberNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/layout-props/index.html b/docs/0.60/layout-props/index.html index 0d7eddeae87..57a4de1ccf0 100644 --- a/docs/0.60/layout-props/index.html +++ b/docs/0.60/layout-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Layout Props

Reference

Props

alignContent

alignContent controls how rows align in the cross direction, overriding the alignContent of the parent. See https://developer.mozilla.org/en-US/docs/Web/CSS/align-content for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'stretch', 'space-between', 'space-around')No

alignItems

alignItems aligns children in the cross direction. For example, if children are flowing vertically, alignItems controls how they align horizontally. It works like align-items in CSS (default: stretch). See https://developer.mozilla.org/en-US/docs/Web/CSS/align-items for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'stretch', 'baseline')No

alignSelf

alignSelf controls how a child aligns in the cross direction, overriding the alignItems of the parent. It works like align-self in CSS (default: auto). See https://developer.mozilla.org/en-US/docs/Web/CSS/align-self for more details.

TypeRequired
enum('auto', 'flex-start', 'flex-end', 'center', 'stretch', 'baseline')No

aspectRatio

Aspect ratio controls the size of the undefined dimension of a node. Aspect ratio is a non-standard property only available in React Native and not CSS.

  • On a node with a set width/height aspect ratio controls the size of the unset dimension
  • On a node with a set flex basis aspect ratio controls the size of the node in the cross axis if unset
  • On a node with a measure function aspect ratio works as though the measure function measures the flex basis
  • On a node with flex grow/shrink aspect ratio controls the size of the node in the cross axis if unset
  • Aspect ratio takes min/max dimensions into account
TypeRequired
numberNo

borderBottomWidth

borderBottomWidth works like border-bottom-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-width for more details.

TypeRequired
numberNo

borderEndWidth

When direction is ltr, borderEndWidth is equivalent to borderRightWidth. When direction is rtl, borderEndWidth is equivalent to borderLeftWidth.

TypeRequired
numberNo

borderLeftWidth

borderLeftWidth works like border-left-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-left-width for more details.

TypeRequired
numberNo

borderRightWidth

borderRightWidth works like border-right-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-right-width for more details.

TypeRequired
numberNo

borderStartWidth

When direction is ltr, borderStartWidth is equivalent to borderLeftWidth. When direction is rtl, borderStartWidth is equivalent to borderRightWidth.

TypeRequired
numberNo

borderTopWidth

borderTopWidth works like border-top-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-top-width for more details.

TypeRequired
numberNo

borderWidth

borderWidth works like border-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-width for more details.

TypeRequired
numberNo

bottom

bottom is the number of logical pixels to offset the bottom edge of this component.

It works similarly to bottom in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/bottom for more details of how bottom affects layout.

TypeRequired
number, stringNo

direction

direction specifies the directional flow of the user interface. The default is inherit, except for root node which will have value based on the current locale. See https://yogalayout.com/docs/layout-direction for more details.

TypeRequiredPlatform
enum('inherit', 'ltr', 'rtl')NoiOS

display

display sets the display type of this component.

It works similarly to display in CSS, but only support 'flex' and 'none'. 'flex' is the default.

TypeRequired
enum('none', 'flex')No

end

When the direction is ltr, end is equivalent to right. When the direction is rtl, end is equivalent to left.

This style takes precedence over the left and right styles.

TypeRequired
number, stringNo

flex

In React Native flex does not work the same way that it does in CSS. flex is a number rather than a string, and it works according to the Yoga.

When flex is a positive number, it makes the component flexible and it will be sized proportional to its flex value. So a component with flex set to 2 will take twice the space as a component with flex set to 1. flex: <positive number> equates to flexGrow: <positive number>, flexShrink: 1, flexBasis: 0.

When flex is 0, the component is sized according to width and height and it is inflexible.

When flex is -1, the component is normally sized according width and height. However, if there's not enough space, the component will shrink to its minWidth and minHeight.

flexGrow, flexShrink, and flexBasis work the same as in CSS.

TypeRequired
numberNo

flexBasis

TypeRequired
number, stringNo

flexDirection

flexDirection controls which directions children of a container go. row goes left to right, column goes top to bottom, and you may be able to guess what the other two do. It works like flex-direction in CSS, except the default is column. See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction for more details.

TypeRequired
enum('row', 'row-reverse', 'column', 'column-reverse')No

flexGrow

TypeRequired
numberNo

flexShrink

TypeRequired
numberNo

flexWrap

flexWrap controls whether children can wrap around after they hit the end of a flex container. It works like flex-wrap in CSS (default: nowrap). See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-wrap for more details. Note it does not work anymore with alignItems: stretch (the default), so you may want to use alignItems: flex-start for example (breaking change details: https://github.com/facebook/react-native/releases/tag/v0.28.0).

TypeRequired
enum('wrap', 'nowrap')No

height

height sets the height of this component.

It works similarly to height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported. See https://developer.mozilla.org/en-US/docs/Web/CSS/height for more details.

TypeRequired
number, stringNo

justifyContent

justifyContent aligns children in the main direction. For example, if children are flowing vertically, justifyContent controls how they align vertically. It works like justify-content in CSS (default: flex-start). See https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'space-between', 'space-around', 'space-evenly')No

left

left is the number of logical pixels to offset the left edge of this component.

It works similarly to left in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/left for more details of how left affects layout.

TypeRequired
number, stringNo

margin

Setting margin has the same effect as setting each of marginTop, marginLeft, marginBottom, and marginRight. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin for more details.

TypeRequired
number, stringNo

marginBottom

marginBottom works like margin-bottom in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-bottom for more details.

TypeRequired
number, stringNo

marginEnd

When direction is ltr, marginEnd is equivalent to marginRight. When direction is rtl, marginEnd is equivalent to marginLeft.

TypeRequired
number, stringNo

marginHorizontal

Setting marginHorizontal has the same effect as setting both marginLeft and marginRight.

TypeRequired
number, stringNo

marginLeft

marginLeft works like margin-left in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-left for more details.

TypeRequired
number, stringNo

marginRight

marginRight works like margin-right in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-right for more details.

TypeRequired
number, stringNo

marginStart

When direction is ltr, marginStart is equivalent to marginLeft. When direction is rtl, marginStart is equivalent to marginRight.

TypeRequired
number, stringNo

marginTop

marginTop works like margin-top in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-top for more details.

TypeRequired
number, stringNo

marginVertical

Setting marginVertical has the same effect as setting both marginTop and marginBottom.

TypeRequired
number, stringNo

maxHeight

maxHeight is the maximum height for this component, in logical pixels.

It works similarly to max-height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/max-height for more details.

TypeRequired
number, stringNo

maxWidth

maxWidth is the maximum width for this component, in logical pixels.

It works similarly to max-width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/max-width for more details.

TypeRequired
number, stringNo

minHeight

minHeight is the minimum height for this component, in logical pixels.

It works similarly to min-height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/min-height for more details.

TypeRequired
number, stringNo

minWidth

minWidth is the minimum width for this component, in logical pixels.

It works similarly to min-width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/min-width for more details.

TypeRequired
number, stringNo

overflow

overflow controls how children are measured and displayed. overflow: hidden causes views to be clipped while overflow: scroll causes views to be measured independently of their parents main axis. It works like overflow in CSS (default: visible). See https://developer.mozilla.org/en/docs/Web/CSS/overflow for more details.

TypeRequired
enum('visible', 'hidden', 'scroll')No

padding

Setting padding has the same effect as setting each of paddingTop, paddingBottom, paddingLeft, and paddingRight. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding for more details.

TypeRequired
number, stringNo

paddingBottom

paddingBottom works like padding-bottom in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-bottom for more details.

TypeRequired
number, stringNo

paddingEnd

When direction is ltr, paddingEnd is equivalent to paddingRight. When direction is rtl, paddingEnd is equivalent to paddingLeft.

TypeRequired
number, stringNo

paddingHorizontal

Setting paddingHorizontal is like setting both of paddingLeft and paddingRight.

TypeRequired
number, stringNo

paddingLeft

paddingLeft works like padding-left in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-left for more details.

TypeRequired
number, stringNo

paddingRight

paddingRight works like padding-right in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-right for more details.

TypeRequired
number, stringNo

paddingStart

When direction is ltr, paddingStart is equivalent to paddingLeft. When direction is rtl, paddingStart is equivalent to paddingRight.

TypeRequired
number, stringNo

paddingTop

paddingTop works like padding-top in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-top for more details.

TypeRequired
number, ,stringNo

paddingVertical

Setting paddingVertical is like setting both of paddingTop and paddingBottom.

TypeRequired
number, stringNo

position

position in React Native is similar to regular CSS, but everything is set to relative by default, so absolute positioning is always relative to the parent.

If you want to position a child using specific numbers of logical pixels relative to its parent, set the child to have absolute position.

If you want to position a child relative to something that is not its parent, don't use styles for that. Use the component tree.

See https://github.com/facebook/yoga for more details on how position differs between React Native and CSS.

TypeRequired
enum('absolute', 'relative')No

right

right is the number of logical pixels to offset the right edge of this component.

It works similarly to right in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/right for more details of how right affects layout.

TypeRequired
number, stringNo

start

When the direction is ltr, start is equivalent to left. When the direction is rtl, start is equivalent to right.

This style takes precedence over the left, right, and end styles.

TypeRequired
number, stringNo

top

top is the number of logical pixels to offset the top edge of this component.

It works similarly to top in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/top for more details of how top affects layout.

TypeRequired
number, stringNo

width

width sets the width of this component.

It works similarly to width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported. See https://developer.mozilla.org/en-US/docs/Web/CSS/width for more details.

TypeRequired
number, stringNo

zIndex

zIndex controls which components display on top of others. Normally, you don't use zIndex. Components render according to their order in the document tree, so later components draw over earlier ones. zIndex may be useful if you have animations or custom modal interfaces where you don't want this behavior.

It works like the CSS z-index property - components with a larger zIndex will render on top. Think of the z-direction like it's pointing from the phone into your eyeball. See https://developer.mozilla.org/en-US/docs/Web/CSS/z-index for more details.

On iOS, zIndex may require Views to be siblings of each other for it to work as expected.

TypeRequired
numberNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/layoutanimation.html b/docs/0.60/layoutanimation.html index bd1d6b79793..27916f8b09a 100644 --- a/docs/0.60/layoutanimation.html +++ b/docs/0.60/layoutanimation.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
if (
Platform.OS === 'android' &&
UIManager.setLayoutAnimationEnabledExperimental
) {
UIManager.setLayoutAnimationEnabledExperimental(true);
}
class AnimatedCollapsible extends React.Component {
state = { expanded: false };
render() {
return (
<View style={{ overflow: 'hidden' }}>
<TouchableOpacity
onPress={() => {
LayoutAnimation.configureNext(
LayoutAnimation.Presets.spring
);
this.setState({ expanded: !this.state.expanded });
}}>
<Text>
Press me to{' '}
{this.state.expanded ? 'collapse' : 'expand'}!
</Text>
</TouchableOpacity>
{this.state.expanded && (
<Text>I disappear sometimes!</Text>
)}
</View>
);
}
}

Reference

Methods

configureNext()

static configureNext(config, onAnimationDidEnd?)

Schedules an animation to happen on the next layout.

Parameters:

NameTypeRequiredDescription
configobjectYesSee config description below.
onAnimationDidEndfunctionNoCalled when the animation finished. Only supported on iOS.

The config parameter is an object with the keys below. create returns a valid object for config, and the Presets objects can also all be passed as the config.

The config that's passed to create, update, or delete has the following keys:

create()

static create(duration, type, creationProp)

Helper that creates an object (with create, update, and delete fields) to pass into configureNext. The type parameter is an animation type, and the creationProp parameter is a layout property.

Example usage:

LayoutAnimation.configureNext(
LayoutAnimation.create(
500,
LayoutAnimation.Types.spring,
LayoutAnimation.Properties.scaleXY
)
);

Properties

Types

An enumeration of animation types to be used in the create method, or in the create/update/delete configs for configureNext. (example usage: LayoutAnimation.Types.easeIn)

Types
spring
linear
easeInEaseOut
easeIn
easeOut
keyboard

Properties

An enumeration of layout properties to be animated to be used in the create method, or in the create/update/delete configs for configureNext. (example usage: LayoutAnimation.Properties.opacity)

Properties
opacity
scaleX
scaleY
scaleXY

Presets

A set of predefined animation configs to pass into configureNext.

PresetsValue
easeInEaseOutcreate(300, 'easeInEaseOut', 'opacity')
linearcreate(500, 'linear', 'opacity')
spring{ duration: 700, create: { type: 'linear', property: 'opacity' }, update: { type: 'spring', springDamping: 0.4 }, delete: { type: 'linear', property: 'opacity' } }

easeInEaseOut()

Calls configureNext() with Presets.easeInEaseOut.

linear()

Calls configureNext() with Presets.linear.

spring()

Calls configureNext() with Presets.spring.

Edit this page
Last updated on
- + diff --git a/docs/0.60/layoutanimation/index.html b/docs/0.60/layoutanimation/index.html index bd1d6b79793..27916f8b09a 100644 --- a/docs/0.60/layoutanimation/index.html +++ b/docs/0.60/layoutanimation/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
if (
Platform.OS === 'android' &&
UIManager.setLayoutAnimationEnabledExperimental
) {
UIManager.setLayoutAnimationEnabledExperimental(true);
}
class AnimatedCollapsible extends React.Component {
state = { expanded: false };
render() {
return (
<View style={{ overflow: 'hidden' }}>
<TouchableOpacity
onPress={() => {
LayoutAnimation.configureNext(
LayoutAnimation.Presets.spring
);
this.setState({ expanded: !this.state.expanded });
}}>
<Text>
Press me to{' '}
{this.state.expanded ? 'collapse' : 'expand'}!
</Text>
</TouchableOpacity>
{this.state.expanded && (
<Text>I disappear sometimes!</Text>
)}
</View>
);
}
}

Reference

Methods

configureNext()

static configureNext(config, onAnimationDidEnd?)

Schedules an animation to happen on the next layout.

Parameters:

NameTypeRequiredDescription
configobjectYesSee config description below.
onAnimationDidEndfunctionNoCalled when the animation finished. Only supported on iOS.

The config parameter is an object with the keys below. create returns a valid object for config, and the Presets objects can also all be passed as the config.

The config that's passed to create, update, or delete has the following keys:

create()

static create(duration, type, creationProp)

Helper that creates an object (with create, update, and delete fields) to pass into configureNext. The type parameter is an animation type, and the creationProp parameter is a layout property.

Example usage:

LayoutAnimation.configureNext(
LayoutAnimation.create(
500,
LayoutAnimation.Types.spring,
LayoutAnimation.Properties.scaleXY
)
);

Properties

Types

An enumeration of animation types to be used in the create method, or in the create/update/delete configs for configureNext. (example usage: LayoutAnimation.Types.easeIn)

Types
spring
linear
easeInEaseOut
easeIn
easeOut
keyboard

Properties

An enumeration of layout properties to be animated to be used in the create method, or in the create/update/delete configs for configureNext. (example usage: LayoutAnimation.Properties.opacity)

Properties
opacity
scaleX
scaleY
scaleXY

Presets

A set of predefined animation configs to pass into configureNext.

PresetsValue
easeInEaseOutcreate(300, 'easeInEaseOut', 'opacity')
linearcreate(500, 'linear', 'opacity')
spring{ duration: 700, create: { type: 'linear', property: 'opacity' }, update: { type: 'spring', springDamping: 0.4 }, delete: { type: 'linear', property: 'opacity' } }

easeInEaseOut()

Calls configureNext() with Presets.easeInEaseOut.

linear()

Calls configureNext() with Presets.linear.

spring()

Calls configureNext() with Presets.spring.

Edit this page
Last updated on
- + diff --git a/docs/0.60/libraries.html b/docs/0.60/libraries.html index a5852ada480..1caa95a1c28 100644 --- a/docs/0.60/libraries.html +++ b/docs/0.60/libraries.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Using Libraries

React Native provides a set of built-in Core Components and APIs ready to use in your app. You're not limited to the components and APIs bundled with React Native. React Native has a community of thousands of developers. If the Core Components and APIs don't have what you are looking for, you may be able to find and install a library from the community to add the functionality to your app.

Selecting a Package Manager

React Native libraries are typically installed from the npm registry using a Node.js package manager such as npm CLI or Yarn Classic.

If you have Node.js installed on your computer then you already have the npm CLI installed. Some developers prefer to use Yarn Classic for slightly faster install times and additional advanced features like Workspaces. Both tools work great with React Native. We will assume npm for the rest of this guide for simplicity of explanation.

💡 The terms "library" and "package" are used interchangably in the JavaScript community.

Installing a Library

To install a library in your project, navigate to your project directory in your terminal and run npm install <name-of-the-library>. Let's try this with react-native-webview:

npm install react-native-webview

The library that we installed includes native code, and we need to link to our app before we use it.

Linking Native Code on iOS

React Native uses CocoaPods to manage iOS project dependencies and most React Native libraries follow this same convention. If a library you are using does not, then please refer to their README for additional instruction. In most cases, the following instructions will apply.

Run pod install in our ios directory in order to link it to our native iOS project. A shortcut for doing this without switching to the ios directory is to run npx pod-install.

npx pod-install

Once this is complete, re-build the app binary to start using your new library:

npx react-native run-ios

Linking Native Code on Android

React Native uses Gradle to manage Android project dependencies. After you install a library with native dependencies, you will need to re-build the app binary to use your new library:

npx react-native run-android

Finding Libraries

React Native Directory is a searchable database of libraries built specifically for React Native. This is the first place to look for a library for your React Native app.

Many of the libraries you will find on the directory are from React Native Community or Expo.

Libraries built by the React Native Community are driven by volunteers and individuals at companies that depend on React Native. They often support iOS, tvOS, Android, Windows, but this varies across projects. Many of the libraries in this organization were once React Native Core Components and APIs.

Libraries built by Expo are all written in TypeScript and support iOS, Android, and react-native-web wherever possible. They usually require that you first install react-native-unimodules in order to use in your React Native app.

After React Native Directory, the npm registry is the next best place if you can't find a library specifically for React Native on the directory. The npm registry is the definitive source for JavaScript libraries, but the libraries that it lists may not all be compatible with React Native. React Native is one of many JavaScript programming environments, including Node.js, web browsers, Electron, and more, and npm includes libraries that work for all of these environments.

Determining Library Compatibility

Does it work with React Native?

Usually libraries built specifically for other platforms will not work with React Native. Examples include react-select which is built for the web and specifically targets react-dom, and rimraf which is built for Node.js and interacts with your computer file system. Other libraries like lodash use only JavaScript language features and work in any environment. You will gain a sense for this over time, but until then the easiest way to find out is to try it yourself. You can remove packages using npm uninstall if it turns out that it does not work in React Native.

Does it work for the platforms that my app supports?

React Native Directory allows you to filter by platform compatibility, such as iOS, Android, Web, and Windows. If the library you would like to use is not currently listed there, refer to the README for the library to learn more.

Does it work with my app version of React Native?

The latest version of a library is typically compatible with the latest version of React Native. If you are using an older version, you should refer to the README to know which version of the library you should install. You can install a particular version of the library by running npm install <library-name>@<version-number>, for example: npm install @react-native-community/netinfo@^2.0.0.

Edit this page
Last updated on
- + diff --git a/docs/0.60/libraries/index.html b/docs/0.60/libraries/index.html index a5852ada480..1caa95a1c28 100644 --- a/docs/0.60/libraries/index.html +++ b/docs/0.60/libraries/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Using Libraries

React Native provides a set of built-in Core Components and APIs ready to use in your app. You're not limited to the components and APIs bundled with React Native. React Native has a community of thousands of developers. If the Core Components and APIs don't have what you are looking for, you may be able to find and install a library from the community to add the functionality to your app.

Selecting a Package Manager

React Native libraries are typically installed from the npm registry using a Node.js package manager such as npm CLI or Yarn Classic.

If you have Node.js installed on your computer then you already have the npm CLI installed. Some developers prefer to use Yarn Classic for slightly faster install times and additional advanced features like Workspaces. Both tools work great with React Native. We will assume npm for the rest of this guide for simplicity of explanation.

💡 The terms "library" and "package" are used interchangably in the JavaScript community.

Installing a Library

To install a library in your project, navigate to your project directory in your terminal and run npm install <name-of-the-library>. Let's try this with react-native-webview:

npm install react-native-webview

The library that we installed includes native code, and we need to link to our app before we use it.

Linking Native Code on iOS

React Native uses CocoaPods to manage iOS project dependencies and most React Native libraries follow this same convention. If a library you are using does not, then please refer to their README for additional instruction. In most cases, the following instructions will apply.

Run pod install in our ios directory in order to link it to our native iOS project. A shortcut for doing this without switching to the ios directory is to run npx pod-install.

npx pod-install

Once this is complete, re-build the app binary to start using your new library:

npx react-native run-ios

Linking Native Code on Android

React Native uses Gradle to manage Android project dependencies. After you install a library with native dependencies, you will need to re-build the app binary to use your new library:

npx react-native run-android

Finding Libraries

React Native Directory is a searchable database of libraries built specifically for React Native. This is the first place to look for a library for your React Native app.

Many of the libraries you will find on the directory are from React Native Community or Expo.

Libraries built by the React Native Community are driven by volunteers and individuals at companies that depend on React Native. They often support iOS, tvOS, Android, Windows, but this varies across projects. Many of the libraries in this organization were once React Native Core Components and APIs.

Libraries built by Expo are all written in TypeScript and support iOS, Android, and react-native-web wherever possible. They usually require that you first install react-native-unimodules in order to use in your React Native app.

After React Native Directory, the npm registry is the next best place if you can't find a library specifically for React Native on the directory. The npm registry is the definitive source for JavaScript libraries, but the libraries that it lists may not all be compatible with React Native. React Native is one of many JavaScript programming environments, including Node.js, web browsers, Electron, and more, and npm includes libraries that work for all of these environments.

Determining Library Compatibility

Does it work with React Native?

Usually libraries built specifically for other platforms will not work with React Native. Examples include react-select which is built for the web and specifically targets react-dom, and rimraf which is built for Node.js and interacts with your computer file system. Other libraries like lodash use only JavaScript language features and work in any environment. You will gain a sense for this over time, but until then the easiest way to find out is to try it yourself. You can remove packages using npm uninstall if it turns out that it does not work in React Native.

Does it work for the platforms that my app supports?

React Native Directory allows you to filter by platform compatibility, such as iOS, Android, Web, and Windows. If the library you would like to use is not currently listed there, refer to the README for the library to learn more.

Does it work with my app version of React Native?

The latest version of a library is typically compatible with the latest version of React Native. If you are using an older version, you should refer to the README to know which version of the library you should install. You can install a particular version of the library by running npm install <library-name>@<version-number>, for example: npm install @react-native-community/netinfo@^2.0.0.

Edit this page
Last updated on
- + diff --git a/docs/0.60/linking-libraries-ios.html b/docs/0.60/linking-libraries-ios.html index dc68469a84b..cbf348fd77d 100644 --- a/docs/0.60/linking-libraries-ios.html +++ b/docs/0.60/linking-libraries-ios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Linking Libraries

Not every app uses all the native capabilities, and including the code to support all those features would impact the binary size... But we still want to support these features whenever you need them.

With that in mind we exposed many of these features as independent static libraries.

For most of the libs it will be as quick as dragging two files, sometimes a third step will be necessary, but no more than that.

All the libraries we ship with React Native live on the Libraries folder in the root of the repository. Some of them are pure JavaScript, and you only need to require it. Other libraries also rely on some native code, in that case you'll have to add these files to your app, otherwise the app will throw an error as soon as you try to use the library.

Here are the few steps to link your libraries that contain native code

Automatic linking

Step 1

Install a library with native dependencies:

$ npm install <library-with-native-dependencies> --save

Note: --save or --save-dev flag is very important for this step. React Native will link your libs based on dependencies and devDependencies in your package.json file.

Step 2

Link your native dependencies:

$ react-native link

Done! All libraries with native dependencies should be successfully linked to your iOS/Android project.

Note: If your iOS project is using CocoaPods (contains Podfile) and linked library has podspec file, then react-native link will link library using Podfile. To support non-trivial Podfiles add # Add new pods below this line comment to places where you expect pods to be added.

Manual linking

Step 1

If the library has native code, there must be an .xcodeproj file inside its folder. Drag this file to your project on Xcode (usually under the Libraries group on Xcode);

Step 2

Click on your main project file (the one that represents the .xcodeproj) select Build Phases and drag the static library from the Products folder inside the Library you are importing to Link Binary With Libraries

Step 3

Not every library will need this step, what you need to consider is:

Do I need to know the contents of the library at compile time?

What that means is, are you using this library on the native side or only in JavaScript? If you are only using it in JavaScript, you are good to go!

If you do need to call it from native, then we need to know the library's headers. To achieve that you have to go to your project's file, select Build Settings and search for Header Search Paths. There you should include the path to your library. (This documentation used to recommend using recursive, but this is no longer recommended, as it can cause subtle build failures, especially with CocoaPods.)

Edit this page
Last updated on
- + diff --git a/docs/0.60/linking-libraries-ios/index.html b/docs/0.60/linking-libraries-ios/index.html index dc68469a84b..cbf348fd77d 100644 --- a/docs/0.60/linking-libraries-ios/index.html +++ b/docs/0.60/linking-libraries-ios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Linking Libraries

Not every app uses all the native capabilities, and including the code to support all those features would impact the binary size... But we still want to support these features whenever you need them.

With that in mind we exposed many of these features as independent static libraries.

For most of the libs it will be as quick as dragging two files, sometimes a third step will be necessary, but no more than that.

All the libraries we ship with React Native live on the Libraries folder in the root of the repository. Some of them are pure JavaScript, and you only need to require it. Other libraries also rely on some native code, in that case you'll have to add these files to your app, otherwise the app will throw an error as soon as you try to use the library.

Here are the few steps to link your libraries that contain native code

Automatic linking

Step 1

Install a library with native dependencies:

$ npm install <library-with-native-dependencies> --save

Note: --save or --save-dev flag is very important for this step. React Native will link your libs based on dependencies and devDependencies in your package.json file.

Step 2

Link your native dependencies:

$ react-native link

Done! All libraries with native dependencies should be successfully linked to your iOS/Android project.

Note: If your iOS project is using CocoaPods (contains Podfile) and linked library has podspec file, then react-native link will link library using Podfile. To support non-trivial Podfiles add # Add new pods below this line comment to places where you expect pods to be added.

Manual linking

Step 1

If the library has native code, there must be an .xcodeproj file inside its folder. Drag this file to your project on Xcode (usually under the Libraries group on Xcode);

Step 2

Click on your main project file (the one that represents the .xcodeproj) select Build Phases and drag the static library from the Products folder inside the Library you are importing to Link Binary With Libraries

Step 3

Not every library will need this step, what you need to consider is:

Do I need to know the contents of the library at compile time?

What that means is, are you using this library on the native side or only in JavaScript? If you are only using it in JavaScript, you are good to go!

If you do need to call it from native, then we need to know the library's headers. To achieve that you have to go to your project's file, select Build Settings and search for Header Search Paths. There you should include the path to your library. (This documentation used to recommend using recursive, but this is no longer recommended, as it can cause subtle build failures, especially with CocoaPods.)

Edit this page
Last updated on
- + diff --git a/docs/0.60/linking.html b/docs/0.60/linking.html index 37615f522b5..abb20bf3cbf 100644 --- a/docs/0.60/linking.html +++ b/docs/0.60/linking.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
{
return [RCTLinkingManager application:application openURL:url
sourceApplication:sourceApplication annotation:annotation];
}

If your app is using Universal Links, you'll need to add the following code as well:

- (BOOL)application:(UIApplication *)application continueUserActivity:(nonnull NSUserActivity *)userActivity
restorationHandler:(nonnull void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler
{
return [RCTLinkingManager application:application
continueUserActivity:userActivity
restorationHandler:restorationHandler];
}

And then on your React component you'll be able to listen to the events on Linking as follows:

componentDidMount() {
Linking.addEventListener('url', this._handleOpenURL);
},
componentWillUnmount() {
Linking.removeEventListener('url', this._handleOpenURL);
},
_handleOpenURL(event) {
console.log(event.url);
}

Opening external links

To start the corresponding activity for a link (web URL, email, contact etc.), call:

Linking.openURL(url).catch((err) =>
console.error('An error occurred', err)
);

If you want to check if any installed app can handle a given URL beforehand you can call:

Linking.canOpenURL(url)
.then((supported) => {
if (!supported) {
console.log("Can't handle url: " + url);
} else {
return Linking.openURL(url);
}
})
.catch((err) => console.error('An error occurred', err));

Reference

Methods

constructor()

constructor();

addEventListener()

addEventListener(type, handler);

Add a handler to Linking changes by listening to the url event type and providing the handler.

removeEventListener()

removeEventListener(type, handler);

Remove a handler by passing the url event type and the handler.

openURL()

openURL(url);

Try to open the given url with any of the installed apps.

You can use other URLs, like a location (e.g. "geo:37.484847,-122.148386" on Android or "http://maps.apple.com/?ll=37.484847,-122.148386" on iOS), a contact, or any other URL that can be opened with the installed apps.

The method returns a Promise object. If the user confirms the open dialog or the url automatically opens, the promise is resolved. If the user cancels the open dialog or there are no registered applications for the url, the promise is rejected.

Parameters:

NameTypeRequiredDescription
urlstringYesThe URL to open.

This method will fail if the system doesn't know how to open the specified URL. If you're passing in a non-http(s) URL, it's best to check {@code canOpenURL} first.

For web URLs, the protocol ("http://", "https://") must be set accordingly!

canOpenURL()

canOpenURL(url);

Determine whether or not an installed app can handle a given URL.

The method returns a Promise object. When it is determined whether or not the given URL can be handled, the promise is resolved and the first parameter is whether or not it can be opened.

The Promise will reject on Android if it was impossible to check if the URL can be opened, and on iOS if you didn't add the specific scheme in the LSApplicationQueriesSchemes key inside Info.plist (see bellow).

Parameters:

NameTypeRequiredDescription
urlstringYesThe URL to open.

For web URLs, the protocol ("http://", "https://") must be set accordingly!

As of iOS 9, your app needs to provide the LSApplicationQueriesSchemes key inside Info.plist or canOpenURL will always return false.

This method has limitations on iOS 9+. From the official Apple documentation:

If your app is linked against an earlier version of iOS but is running in iOS 9.0 or later, you can call this method up to 50 times. After reaching that limit, subsequent calls always return false. If the user reinstalls or upgrades the app, iOS resets the limit.

openSettings()

openSettings();

Open the Settings app and displays the app’s custom settings, if it has any.

getInitialURL()

getInitialURL();

If the app launch was triggered by an app link, it will give the link url, otherwise it will give null.

To support deep linking on Android, refer http://developer.android.com/training/app-indexing/deep-linking.html#handling-intents

sendIntent()

sendIntent(action: string, extras?: Array<{key: string, value: string | number | boolean}>)

@platform android

Android-Only. Launch an Android intent with extras (optional)

Edit this page
Last updated on
- + diff --git a/docs/0.60/linking/index.html b/docs/0.60/linking/index.html index 37615f522b5..abb20bf3cbf 100644 --- a/docs/0.60/linking/index.html +++ b/docs/0.60/linking/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
{
return [RCTLinkingManager application:application openURL:url
sourceApplication:sourceApplication annotation:annotation];
}

If your app is using Universal Links, you'll need to add the following code as well:

- (BOOL)application:(UIApplication *)application continueUserActivity:(nonnull NSUserActivity *)userActivity
restorationHandler:(nonnull void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler
{
return [RCTLinkingManager application:application
continueUserActivity:userActivity
restorationHandler:restorationHandler];
}

And then on your React component you'll be able to listen to the events on Linking as follows:

componentDidMount() {
Linking.addEventListener('url', this._handleOpenURL);
},
componentWillUnmount() {
Linking.removeEventListener('url', this._handleOpenURL);
},
_handleOpenURL(event) {
console.log(event.url);
}

Opening external links

To start the corresponding activity for a link (web URL, email, contact etc.), call:

Linking.openURL(url).catch((err) =>
console.error('An error occurred', err)
);

If you want to check if any installed app can handle a given URL beforehand you can call:

Linking.canOpenURL(url)
.then((supported) => {
if (!supported) {
console.log("Can't handle url: " + url);
} else {
return Linking.openURL(url);
}
})
.catch((err) => console.error('An error occurred', err));

Reference

Methods

constructor()

constructor();

addEventListener()

addEventListener(type, handler);

Add a handler to Linking changes by listening to the url event type and providing the handler.

removeEventListener()

removeEventListener(type, handler);

Remove a handler by passing the url event type and the handler.

openURL()

openURL(url);

Try to open the given url with any of the installed apps.

You can use other URLs, like a location (e.g. "geo:37.484847,-122.148386" on Android or "http://maps.apple.com/?ll=37.484847,-122.148386" on iOS), a contact, or any other URL that can be opened with the installed apps.

The method returns a Promise object. If the user confirms the open dialog or the url automatically opens, the promise is resolved. If the user cancels the open dialog or there are no registered applications for the url, the promise is rejected.

Parameters:

NameTypeRequiredDescription
urlstringYesThe URL to open.

This method will fail if the system doesn't know how to open the specified URL. If you're passing in a non-http(s) URL, it's best to check {@code canOpenURL} first.

For web URLs, the protocol ("http://", "https://") must be set accordingly!

canOpenURL()

canOpenURL(url);

Determine whether or not an installed app can handle a given URL.

The method returns a Promise object. When it is determined whether or not the given URL can be handled, the promise is resolved and the first parameter is whether or not it can be opened.

The Promise will reject on Android if it was impossible to check if the URL can be opened, and on iOS if you didn't add the specific scheme in the LSApplicationQueriesSchemes key inside Info.plist (see bellow).

Parameters:

NameTypeRequiredDescription
urlstringYesThe URL to open.

For web URLs, the protocol ("http://", "https://") must be set accordingly!

As of iOS 9, your app needs to provide the LSApplicationQueriesSchemes key inside Info.plist or canOpenURL will always return false.

This method has limitations on iOS 9+. From the official Apple documentation:

If your app is linked against an earlier version of iOS but is running in iOS 9.0 or later, you can call this method up to 50 times. After reaching that limit, subsequent calls always return false. If the user reinstalls or upgrades the app, iOS resets the limit.

openSettings()

openSettings();

Open the Settings app and displays the app’s custom settings, if it has any.

getInitialURL()

getInitialURL();

If the app launch was triggered by an app link, it will give the link url, otherwise it will give null.

To support deep linking on Android, refer http://developer.android.com/training/app-indexing/deep-linking.html#handling-intents

sendIntent()

sendIntent(action: string, extras?: Array<{key: string, value: string | number | boolean}>)

@platform android

Android-Only. Launch an Android intent with extras (optional)

Edit this page
Last updated on
- + diff --git a/docs/0.60/listview.html b/docs/0.60/listview.html index 452b3e7bdb5..34a6003198f 100644 --- a/docs/0.60/listview.html +++ b/docs/0.60/listview.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
render() {
return (
<ListView
dataSource={this.state.dataSource}
renderRow={(rowData) => <Text>{rowData}</Text>}
/>
);
}
}

ListView also supports more advanced features, including sections with sticky section headers, header and footer support, callbacks on reaching the end of the available data (onEndReached) and on the set of rows that are visible in the device viewport change (onChangeVisibleRows), and several performance optimizations.

There are a few performance operations designed to make ListView scroll smoothly while dynamically loading potentially very large (or conceptually infinite) data sets:

Props

Methods

Reference

Props

dataSource

An instance of ListView.DataSource to use

TypeRequired
ListViewDataSourceYes

initialListSize

How many rows to render on initial component mount. Use this to make it so that the first screen worth of data appears at one time instead of over the course of multiple frames.

TypeRequired
numberYes

onEndReachedThreshold

Threshold in pixels (virtual, not physical) for calling onEndReached.

TypeRequired
numberYes

pageSize

Number of rows to render per event loop. Note: if your 'rows' are actually cells, i.e. they don't span the full width of your view (as in the ListViewGridLayoutExample), you should set the pageSize to be a multiple of the number of cells per row, otherwise you're likely to see gaps at the edge of the ListView as new pages are loaded.

TypeRequired
numberYes

renderRow

(rowData, sectionID, rowID, highlightRow) => renderable

Takes a data entry from the data source and its ids and should return a renderable component to be rendered as the row. By default the data is exactly what was put into the data source, but it's also possible to provide custom extractors. ListView can be notified when a row is being highlighted by calling highlightRow(sectionID, rowID). This sets a boolean value of adjacentRowHighlighted in renderSeparator, allowing you to control the separators above and below the highlighted row. The highlighted state of a row can be reset by calling highlightRow(null).

TypeRequired
functionYes

renderScrollComponent

(props) => renderable

A function that returns the scrollable component in which the list rows are rendered. Defaults to returning a ScrollView with the given props.

TypeRequired
functionYes

scrollRenderAheadDistance

How early to start rendering rows before they come on screen, in pixels.

TypeRequired
numberYes

stickyHeaderIndices

An array of child indices determining which children get docked to the top of the screen when scrolling. For example, passing stickyHeaderIndices={[0]} will cause the first child to be fixed to the top of the scroll view. This property is not supported in conjunction with horizontal={true}.

TypeRequired
array of numberYes

enableEmptySections

Flag indicating whether empty section headers should be rendered. In the future release empty section headers will be rendered by default, and the flag will be deprecated. If empty sections are not desired to be rendered their indices should be excluded from sectionID object.

TypeRequired
boolNo

renderHeader

TypeRequired
functionNo

onEndReached

Called when all rows have been rendered and the list has been scrolled to within onEndReachedThreshold of the bottom. The native scroll event is provided.

TypeRequired
functionNo

stickySectionHeadersEnabled

Makes the sections headers sticky. The sticky behavior means that it will scroll with the content at the top of the section until it reaches the top of the screen, at which point it will stick to the top until it is pushed off the screen by the next section header. This property is not supported in conjunction with horizontal={true}. Only enabled by default on iOS because of typical platform standards.

TypeRequired
boolNo

renderSectionHeader

(sectionData, sectionID) => renderable

If provided, a header is rendered for this section.

TypeRequired
functionNo

renderSeparator

(sectionID, rowID, adjacentRowHighlighted) => renderable

If provided, a renderable component to be rendered as the separator below each row but not the last row if there is a section header below. Take a sectionID and rowID of the row above and whether its adjacent row is highlighted.

TypeRequired
functionNo

onChangeVisibleRows

(visibleRows, changedRows) => void

Called when the set of visible rows changes. visibleRows maps { sectionID: { rowID: true }} for all the visible rows, and changedRows maps { sectionID: { rowID: true | false }} for the rows that have changed their visibility, with true indicating visible, and false indicating the view has moved out of view.

TypeRequired
functionNo

removeClippedSubviews

A performance optimization for improving scroll perf of large lists, used in conjunction with overflow: 'hidden' on the row containers. This is enabled by default.

TypeRequired
boolNo

renderFooter

() => renderable

The header and footer are always rendered (if these props are provided) on every render pass. If they are expensive to re-render, wrap them in StaticContainer or other mechanism as appropriate. Footer is always at the bottom of the list, and header at the top, on every render pass. In a horizontal ListView, the header is rendered on the left and the footer on the right.

TypeRequired
functionNo

Methods

getMetrics()

getMetrics();

Exports some data, e.g. for perf investigations or analytics.

scrollTo()

scrollTo((...args: Array));

Scrolls to a given x, y offset, either immediately or with a smooth animation.

See ScrollView#scrollTo.

scrollToEnd()

scrollToEnd(([options]: object));

If this is a vertical ListView scrolls to the bottom. If this is a horizontal ListView scrolls to the right.

Use scrollToEnd({animated: true}) for smooth animated scrolling, scrollToEnd({animated: false}) for immediate scrolling. If no options are passed, animated defaults to true.

See ScrollView#scrollToEnd.

flashScrollIndicators()

flashScrollIndicators();

Displays the scroll indicators momentarily.

Edit this page
Last updated on
- + diff --git a/docs/0.60/listview/index.html b/docs/0.60/listview/index.html index 452b3e7bdb5..34a6003198f 100644 --- a/docs/0.60/listview/index.html +++ b/docs/0.60/listview/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
render() {
return (
<ListView
dataSource={this.state.dataSource}
renderRow={(rowData) => <Text>{rowData}</Text>}
/>
);
}
}

ListView also supports more advanced features, including sections with sticky section headers, header and footer support, callbacks on reaching the end of the available data (onEndReached) and on the set of rows that are visible in the device viewport change (onChangeVisibleRows), and several performance optimizations.

There are a few performance operations designed to make ListView scroll smoothly while dynamically loading potentially very large (or conceptually infinite) data sets:

Props

Methods

Reference

Props

dataSource

An instance of ListView.DataSource to use

TypeRequired
ListViewDataSourceYes

initialListSize

How many rows to render on initial component mount. Use this to make it so that the first screen worth of data appears at one time instead of over the course of multiple frames.

TypeRequired
numberYes

onEndReachedThreshold

Threshold in pixels (virtual, not physical) for calling onEndReached.

TypeRequired
numberYes

pageSize

Number of rows to render per event loop. Note: if your 'rows' are actually cells, i.e. they don't span the full width of your view (as in the ListViewGridLayoutExample), you should set the pageSize to be a multiple of the number of cells per row, otherwise you're likely to see gaps at the edge of the ListView as new pages are loaded.

TypeRequired
numberYes

renderRow

(rowData, sectionID, rowID, highlightRow) => renderable

Takes a data entry from the data source and its ids and should return a renderable component to be rendered as the row. By default the data is exactly what was put into the data source, but it's also possible to provide custom extractors. ListView can be notified when a row is being highlighted by calling highlightRow(sectionID, rowID). This sets a boolean value of adjacentRowHighlighted in renderSeparator, allowing you to control the separators above and below the highlighted row. The highlighted state of a row can be reset by calling highlightRow(null).

TypeRequired
functionYes

renderScrollComponent

(props) => renderable

A function that returns the scrollable component in which the list rows are rendered. Defaults to returning a ScrollView with the given props.

TypeRequired
functionYes

scrollRenderAheadDistance

How early to start rendering rows before they come on screen, in pixels.

TypeRequired
numberYes

stickyHeaderIndices

An array of child indices determining which children get docked to the top of the screen when scrolling. For example, passing stickyHeaderIndices={[0]} will cause the first child to be fixed to the top of the scroll view. This property is not supported in conjunction with horizontal={true}.

TypeRequired
array of numberYes

enableEmptySections

Flag indicating whether empty section headers should be rendered. In the future release empty section headers will be rendered by default, and the flag will be deprecated. If empty sections are not desired to be rendered their indices should be excluded from sectionID object.

TypeRequired
boolNo

renderHeader

TypeRequired
functionNo

onEndReached

Called when all rows have been rendered and the list has been scrolled to within onEndReachedThreshold of the bottom. The native scroll event is provided.

TypeRequired
functionNo

stickySectionHeadersEnabled

Makes the sections headers sticky. The sticky behavior means that it will scroll with the content at the top of the section until it reaches the top of the screen, at which point it will stick to the top until it is pushed off the screen by the next section header. This property is not supported in conjunction with horizontal={true}. Only enabled by default on iOS because of typical platform standards.

TypeRequired
boolNo

renderSectionHeader

(sectionData, sectionID) => renderable

If provided, a header is rendered for this section.

TypeRequired
functionNo

renderSeparator

(sectionID, rowID, adjacentRowHighlighted) => renderable

If provided, a renderable component to be rendered as the separator below each row but not the last row if there is a section header below. Take a sectionID and rowID of the row above and whether its adjacent row is highlighted.

TypeRequired
functionNo

onChangeVisibleRows

(visibleRows, changedRows) => void

Called when the set of visible rows changes. visibleRows maps { sectionID: { rowID: true }} for all the visible rows, and changedRows maps { sectionID: { rowID: true | false }} for the rows that have changed their visibility, with true indicating visible, and false indicating the view has moved out of view.

TypeRequired
functionNo

removeClippedSubviews

A performance optimization for improving scroll perf of large lists, used in conjunction with overflow: 'hidden' on the row containers. This is enabled by default.

TypeRequired
boolNo

renderFooter

() => renderable

The header and footer are always rendered (if these props are provided) on every render pass. If they are expensive to re-render, wrap them in StaticContainer or other mechanism as appropriate. Footer is always at the bottom of the list, and header at the top, on every render pass. In a horizontal ListView, the header is rendered on the left and the footer on the right.

TypeRequired
functionNo

Methods

getMetrics()

getMetrics();

Exports some data, e.g. for perf investigations or analytics.

scrollTo()

scrollTo((...args: Array));

Scrolls to a given x, y offset, either immediately or with a smooth animation.

See ScrollView#scrollTo.

scrollToEnd()

scrollToEnd(([options]: object));

If this is a vertical ListView scrolls to the bottom. If this is a horizontal ListView scrolls to the right.

Use scrollToEnd({animated: true}) for smooth animated scrolling, scrollToEnd({animated: false}) for immediate scrolling. If no options are passed, animated defaults to true.

See ScrollView#scrollToEnd.

flashScrollIndicators()

flashScrollIndicators();

Displays the scroll indicators momentarily.

Edit this page
Last updated on
- + diff --git a/docs/0.60/listviewdatasource.html b/docs/0.60/listviewdatasource.html index 59dc3760bb6..647a48e89e3 100644 --- a/docs/0.60/listviewdatasource.html +++ b/docs/0.60/listviewdatasource.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

ListViewDataSource

Provides efficient data processing and access to the ListView component. A ListViewDataSource is created with functions for extracting data from the input blob, and comparing elements (with default implementations for convenience). The input blob can be as flat as an array of strings, or an object with rows nested inside section objects.

To update the data in the datasource, use cloneWithRows (or cloneWithRowsAndSections if you care about sections). The data in the data source is immutable, so you can't modify it directly. The clone methods take in the new data and compute a diff for each row so ListView knows whether to re-render it or not.

In this example, a component receives data in chunks, handled by _onDataArrived, which concats the new data onto the old data and updates the data source. We use concat to create a new array - mutating this._data, e.g. with this._data.push(newRowData), would be an error. _rowHasChanged understands the shape of the row data and knows how to efficiently compare it.

getInitialState: function() {
var ds = new ListView.DataSource({rowHasChanged: this._rowHasChanged});
return {ds};
},
_onDataArrived(newData) {
this._data = this._data.concat(newData);
this.setState({
ds: this.state.ds.cloneWithRows(this._data)
});
}

Methods

Reference

Methods

constructor()

constructor(params);

You can provide custom extraction and hasChanged functions for section headers and rows. If absent, data will be extracted with the defaultGetRowData and defaultGetSectionHeaderData functions.

The default extractor expects data of one of the following forms:

{ sectionID_1: { rowID_1: <rowData1>, ... }, ... }

or

{ sectionID_1: [ <rowData1>, <rowData2>, ... ], ... }

or

[ [ <rowData1>, <rowData2>, ... ], ... ]

The constructor takes in a params argument that can contain any of the following:

  • getRowData(dataBlob, sectionID, rowID);
  • getSectionHeaderData(dataBlob, sectionID);
  • rowHasChanged(prevRowData, nextRowData);
  • sectionHeaderHasChanged(prevSectionData, nextSectionData);

cloneWithRows()

cloneWithRows(dataBlob, rowIdentities);

Clones this ListViewDataSource with the specified dataBlob and rowIdentities. The dataBlob an arbitrary blob of data. At construction an extractor to get the interesting information was defined (or the default was used).

The rowIdentities is a 2D array of identifiers for rows. ie. [['a1', 'a2'], ['b1', 'b2', 'b3'], ...]. If not provided, it's assumed that the keys of the section data are the row identities.

Note: This function does NOT clone the data in this data source. It only passes the functions defined at construction to a new data source with the data specified. If you wish to maintain the existing data you must handle merging of old and new data separately and then pass that into this function as the dataBlob.

cloneWithRowsAndSections()

cloneWithRowsAndSections(
dataBlob,
sectionIdentities,
rowIdentities
);

This performs the same function as the cloneWithRows function but here you also specify what your sectionIdentities are. If you don't care about sections you should safely be able to use cloneWithRows.

sectionIdentities is an array of identifiers for sections. ie. ['s1', 's2', ...]. The identifiers should correspond to the keys or array indexes of the data you wish to include. If not provided, it's assumed that the keys of dataBlob are the section identities.

Note: this returns a new object!

const dataSource = ds.cloneWithRowsAndSections({
addresses: ['row 1', 'row 2'],
phone_numbers: ['data 1', 'data 2'],
}, ['phone_numbers']);

getRowCount()

getRowCount();

Returns the total number of rows in the data source.

If you are specifying the rowIdentities or sectionIdentities, then getRowCount will return the number of rows in the filtered data source.

getRowAndSectionCount()

getRowAndSectionCount();

Returns the total number of rows in the data source (see getRowCount for how this is calculated) plus the number of sections in the data.

If you are specifying the rowIdentities or sectionIdentities, then getRowAndSectionCount will return the number of rows & sections in the filtered data source.

rowShouldUpdate()

rowShouldUpdate(sectionIndex, rowIndex);

Returns if the row is dirtied and needs to be rerendered

getRowData()

getRowData(sectionIndex, rowIndex);

Gets the data required to render the row.

getRowIDForFlatIndex()

getRowIDForFlatIndex(index);

Gets the rowID at index provided if the dataSource arrays were flattened, or null of out of range indexes.

getSectionIDForFlatIndex()

getSectionIDForFlatIndex(index);

Gets the sectionID at index provided if the dataSource arrays were flattened, or null for out of range indexes.

getSectionLengths()

getSectionLengths();

Returns an array containing the number of rows in each section

sectionHeaderShouldUpdate()

sectionHeaderShouldUpdate(sectionIndex);

Returns if the section header is dirtied and needs to be rerendered

getSectionHeaderData()

getSectionHeaderData(sectionIndex);

Gets the data required to render the section header

Edit this page
Last updated on
- + diff --git a/docs/0.60/listviewdatasource/index.html b/docs/0.60/listviewdatasource/index.html index 59dc3760bb6..647a48e89e3 100644 --- a/docs/0.60/listviewdatasource/index.html +++ b/docs/0.60/listviewdatasource/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

ListViewDataSource

Provides efficient data processing and access to the ListView component. A ListViewDataSource is created with functions for extracting data from the input blob, and comparing elements (with default implementations for convenience). The input blob can be as flat as an array of strings, or an object with rows nested inside section objects.

To update the data in the datasource, use cloneWithRows (or cloneWithRowsAndSections if you care about sections). The data in the data source is immutable, so you can't modify it directly. The clone methods take in the new data and compute a diff for each row so ListView knows whether to re-render it or not.

In this example, a component receives data in chunks, handled by _onDataArrived, which concats the new data onto the old data and updates the data source. We use concat to create a new array - mutating this._data, e.g. with this._data.push(newRowData), would be an error. _rowHasChanged understands the shape of the row data and knows how to efficiently compare it.

getInitialState: function() {
var ds = new ListView.DataSource({rowHasChanged: this._rowHasChanged});
return {ds};
},
_onDataArrived(newData) {
this._data = this._data.concat(newData);
this.setState({
ds: this.state.ds.cloneWithRows(this._data)
});
}

Methods

Reference

Methods

constructor()

constructor(params);

You can provide custom extraction and hasChanged functions for section headers and rows. If absent, data will be extracted with the defaultGetRowData and defaultGetSectionHeaderData functions.

The default extractor expects data of one of the following forms:

{ sectionID_1: { rowID_1: <rowData1>, ... }, ... }

or

{ sectionID_1: [ <rowData1>, <rowData2>, ... ], ... }

or

[ [ <rowData1>, <rowData2>, ... ], ... ]

The constructor takes in a params argument that can contain any of the following:

  • getRowData(dataBlob, sectionID, rowID);
  • getSectionHeaderData(dataBlob, sectionID);
  • rowHasChanged(prevRowData, nextRowData);
  • sectionHeaderHasChanged(prevSectionData, nextSectionData);

cloneWithRows()

cloneWithRows(dataBlob, rowIdentities);

Clones this ListViewDataSource with the specified dataBlob and rowIdentities. The dataBlob an arbitrary blob of data. At construction an extractor to get the interesting information was defined (or the default was used).

The rowIdentities is a 2D array of identifiers for rows. ie. [['a1', 'a2'], ['b1', 'b2', 'b3'], ...]. If not provided, it's assumed that the keys of the section data are the row identities.

Note: This function does NOT clone the data in this data source. It only passes the functions defined at construction to a new data source with the data specified. If you wish to maintain the existing data you must handle merging of old and new data separately and then pass that into this function as the dataBlob.

cloneWithRowsAndSections()

cloneWithRowsAndSections(
dataBlob,
sectionIdentities,
rowIdentities
);

This performs the same function as the cloneWithRows function but here you also specify what your sectionIdentities are. If you don't care about sections you should safely be able to use cloneWithRows.

sectionIdentities is an array of identifiers for sections. ie. ['s1', 's2', ...]. The identifiers should correspond to the keys or array indexes of the data you wish to include. If not provided, it's assumed that the keys of dataBlob are the section identities.

Note: this returns a new object!

const dataSource = ds.cloneWithRowsAndSections({
addresses: ['row 1', 'row 2'],
phone_numbers: ['data 1', 'data 2'],
}, ['phone_numbers']);

getRowCount()

getRowCount();

Returns the total number of rows in the data source.

If you are specifying the rowIdentities or sectionIdentities, then getRowCount will return the number of rows in the filtered data source.

getRowAndSectionCount()

getRowAndSectionCount();

Returns the total number of rows in the data source (see getRowCount for how this is calculated) plus the number of sections in the data.

If you are specifying the rowIdentities or sectionIdentities, then getRowAndSectionCount will return the number of rows & sections in the filtered data source.

rowShouldUpdate()

rowShouldUpdate(sectionIndex, rowIndex);

Returns if the row is dirtied and needs to be rerendered

getRowData()

getRowData(sectionIndex, rowIndex);

Gets the data required to render the row.

getRowIDForFlatIndex()

getRowIDForFlatIndex(index);

Gets the rowID at index provided if the dataSource arrays were flattened, or null of out of range indexes.

getSectionIDForFlatIndex()

getSectionIDForFlatIndex(index);

Gets the sectionID at index provided if the dataSource arrays were flattened, or null for out of range indexes.

getSectionLengths()

getSectionLengths();

Returns an array containing the number of rows in each section

sectionHeaderShouldUpdate()

sectionHeaderShouldUpdate(sectionIndex);

Returns if the section header is dirtied and needs to be rerendered

getSectionHeaderData()

getSectionHeaderData(sectionIndex);

Gets the data required to render the section header

Edit this page
Last updated on
- + diff --git a/docs/0.60/maskedviewios.html b/docs/0.60/maskedviewios.html index aaa41ecad1b..a95d8064bc2 100644 --- a/docs/0.60/maskedviewios.html +++ b/docs/0.60/maskedviewios.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
class MyMaskedView extends React.Component {
render() {
return (
// Determines shape of the mask
<MaskedViewIOS
style={{ flex: 1, flexDirection: 'row', height: '100%' }}
maskElement={
<View
style={{
// Transparent background because mask is based off alpha channel.
backgroundColor: 'transparent',
flex: 1,
justifyContent: 'center',
alignItems: 'center'
}}>
<Text
style={{
fontSize: 60,
color: 'black',
fontWeight: 'bold'
}}>
Basic Mask
</Text>
</View>
}>
{/* Shows behind the mask, you can put anything here, such as an image */}
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#324376'
}}
/>
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#F5DD90'
}}
/>
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#F76C5E'
}}
/>
</MaskedViewIOS>
);
}
}

The following image demonstrates that you can put almost anything behind the mask. The three examples shown are masked <View>, <Text>, and <Image>.

The alpha channel of the view rendered by the maskElement prop determines how much of the view's content and background shows through. Fully or partially opaque pixels allow the underlying content to show through but fully transparent pixels block that content.

Props

Reference

Props

maskElement

TypeRequired
elementYes
Edit this page
Last updated on
- + diff --git a/docs/0.60/maskedviewios/index.html b/docs/0.60/maskedviewios/index.html index aaa41ecad1b..a95d8064bc2 100644 --- a/docs/0.60/maskedviewios/index.html +++ b/docs/0.60/maskedviewios/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
class MyMaskedView extends React.Component {
render() {
return (
// Determines shape of the mask
<MaskedViewIOS
style={{ flex: 1, flexDirection: 'row', height: '100%' }}
maskElement={
<View
style={{
// Transparent background because mask is based off alpha channel.
backgroundColor: 'transparent',
flex: 1,
justifyContent: 'center',
alignItems: 'center'
}}>
<Text
style={{
fontSize: 60,
color: 'black',
fontWeight: 'bold'
}}>
Basic Mask
</Text>
</View>
}>
{/* Shows behind the mask, you can put anything here, such as an image */}
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#324376'
}}
/>
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#F5DD90'
}}
/>
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#F76C5E'
}}
/>
</MaskedViewIOS>
);
}
}

The following image demonstrates that you can put almost anything behind the mask. The three examples shown are masked <View>, <Text>, and <Image>.

The alpha channel of the view rendered by the maskElement prop determines how much of the view's content and background shows through. Fully or partially opaque pixels allow the underlying content to show through but fully transparent pixels block that content.

Props

Reference

Props

maskElement

TypeRequired
elementYes
Edit this page
Last updated on
- + diff --git a/docs/0.60/modal.html b/docs/0.60/modal.html index b08c7554bc7..b99b3685b01 100644 --- a/docs/0.60/modal.html +++ b/docs/0.60/modal.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
<TouchableHighlight
onPress={() => {
this.setModalVisible(true);
}}>
<Text>Show Modal</Text>
</TouchableHighlight>
</View>
);
}
}

Reference

Props

visible

The visible prop determines whether your modal is visible.

TypeRequired
boolNo

supportedOrientations

The supportedOrientations prop allows the modal to be rotated to any of the specified orientations. On iOS, the modal is still restricted by what's specified in your app's Info.plist's UISupportedInterfaceOrientations field. When using presentationStyle of pageSheet or formSheet, this property will be ignored by iOS.

TypeRequiredPlatform
array of enum('portrait', 'portrait-upside-down', 'landscape', 'landscape-left', 'landscape-right')NoiOS

onRequestClose

The onRequestClose callback is called when the user taps the hardware back button on Android or the menu button on Apple TV. Because of this required prop, be aware that BackHandler events will not be emitted as long as the modal is open.

TypeRequiredPlatform
functionYesAndroid, Platform.isTVOS
functionNo(Others)

onShow

The onShow prop allows passing a function that will be called once the modal has been shown.

TypeRequired
functionNo

transparent

The transparent prop determines whether your modal will fill the entire view. Setting this to true will render the modal over a transparent background.

TypeRequired
boolNo

animationType

The animationType prop controls how the modal animates.

Default is set to none.

TypeRequired
enum('none', 'slide', 'fade')No

hardwareAccelerated

The hardwareAccelerated prop controls whether to force hardware acceleration for the underlying window.

TypeRequiredPlatform
boolNoAndroid

onDismiss

The onDismiss prop allows passing a function that will be called once the modal has been dismissed.

TypeRequiredPlatform
functionNoiOS

onOrientationChange

The onOrientationChange callback is called when the orientation changes while the modal is being displayed. The orientation provided is only 'portrait' or 'landscape'. This callback is also called on initial render, regardless of the current orientation.

TypeRequiredPlatform
functionNoiOS

presentationStyle

The presentationStyle prop controls how the modal appears (generally on larger devices such as iPad or plus-sized iPhones). See https://developer.apple.com/reference/uikit/uimodalpresentationstyle for details.

Default is set to overFullScreen or fullScreen depending on transparent property.

TypeRequiredPlatform
enum('fullScreen', 'pageSheet', 'formSheet', 'overFullScreen')NoiOS

animated

Deprecated. Use the animationType prop instead.

Edit this page
Last updated on
- + diff --git a/docs/0.60/modal/index.html b/docs/0.60/modal/index.html index b08c7554bc7..b99b3685b01 100644 --- a/docs/0.60/modal/index.html +++ b/docs/0.60/modal/index.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
<TouchableHighlight
onPress={() => {
this.setModalVisible(true);
}}>
<Text>Show Modal</Text>
</TouchableHighlight>
</View>
);
}
}

Reference

Props

visible

The visible prop determines whether your modal is visible.

TypeRequired
boolNo

supportedOrientations

The supportedOrientations prop allows the modal to be rotated to any of the specified orientations. On iOS, the modal is still restricted by what's specified in your app's Info.plist's UISupportedInterfaceOrientations field. When using presentationStyle of pageSheet or formSheet, this property will be ignored by iOS.

TypeRequiredPlatform
array of enum('portrait', 'portrait-upside-down', 'landscape', 'landscape-left', 'landscape-right')NoiOS

onRequestClose

The onRequestClose callback is called when the user taps the hardware back button on Android or the menu button on Apple TV. Because of this required prop, be aware that BackHandler events will not be emitted as long as the modal is open.

TypeRequiredPlatform
functionYesAndroid, Platform.isTVOS
functionNo(Others)

onShow

The onShow prop allows passing a function that will be called once the modal has been shown.

TypeRequired
functionNo

transparent

The transparent prop determines whether your modal will fill the entire view. Setting this to true will render the modal over a transparent background.

TypeRequired
boolNo

animationType

The animationType prop controls how the modal animates.

Default is set to none.

TypeRequired
enum('none', 'slide', 'fade')No

hardwareAccelerated

The hardwareAccelerated prop controls whether to force hardware acceleration for the underlying window.

TypeRequiredPlatform
boolNoAndroid

onDismiss

The onDismiss prop allows passing a function that will be called once the modal has been dismissed.

TypeRequiredPlatform
functionNoiOS

onOrientationChange

The onOrientationChange callback is called when the orientation changes while the modal is being displayed. The orientation provided is only 'portrait' or 'landscape'. This callback is also called on initial render, regardless of the current orientation.

TypeRequiredPlatform
functionNoiOS

presentationStyle

The presentationStyle prop controls how the modal appears (generally on larger devices such as iPad or plus-sized iPhones). See https://developer.apple.com/reference/uikit/uimodalpresentationstyle for details.

Default is set to overFullScreen or fullScreen depending on transparent property.

TypeRequiredPlatform
enum('fullScreen', 'pageSheet', 'formSheet', 'overFullScreen')NoiOS

animated

Deprecated. Use the animationType prop instead.

Edit this page
Last updated on
- + diff --git a/docs/0.60/more-resources.html b/docs/0.60/more-resources.html index 886d6a72cc9..6526610fbd9 100644 --- a/docs/0.60/more-resources.html +++ b/docs/0.60/more-resources.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

More Resources

If you only read through this website, you should be able to build a pretty cool React Native app. But React Native isn't a product made by one company - it's a community of thousands of developers. So if you're interested in React Native, here's some related stuff you might want to check out.

Popular Libraries

If you're using React Native, you probably already know about React. So I feel a bit silly mentioning this. But if you haven't, check out React - it's the best way to build a modern website.

One common question is how to handle the "state" of your React Native application. The most popular library for this is Redux. Don't be afraid of how often Redux uses the word "reducer" - it's a pretty basic library, and there's also a nice series of videos explaining it.

If you're looking for a library that does a specific thing, check out Awesome React Native, a curated list of components that also has demos, articles, and other stuff.

Examples

Try out apps from the Showcase to see what React Native is capable of! There are also some example apps on GitHub. You can run the apps on a simulator or device, and you can see the source code for these apps, which is neat.

The folks who built the app for Facebook's F8 conference also open-sourced the code and wrote up a detailed series of tutorials. This is useful if you want a more in-depth example that's more realistic than most sample apps out there.

Extending React Native

  • Developers write and publish React Native modules to npm and open source them on GitHub.
  • Making modules helps grow the React Native ecosystem and community. We recommend writing modules for your use cases and sharing them on npm.
  • Read the guides on Native Modules (iOS, Android) and Native UI Components (iOS, Android) if you are interested in extending native functionality.
  • Looking for a pre-built component? Check JS.coach or Native Directory to find what the community has been creating.

Development Tools

Nuclide is the IDE that Facebook uses internally for JavaScript development. The killer feature of Nuclide is its debugging ability. It also has great inline Flow support. VS Code is another IDE that is popular with JavaScript developers.

Ignite is a starter kit that uses Redux and a few different common UI libraries. It has a CLI to generate apps, components, and containers. If you like all of the individual tech choices, Ignite could be perfect for you.

App Center is a service from Microsoft that allows you to deploy live updates to your React Native app. If you don't like going through the app store process to deploy little tweaks, and you also don't like setting up your own backend, give App Center a try.

Expo is a development environment plus application that focuses on letting you build React Native apps in the Expo development environment, without ever touching Xcode or Android Studio. If you wish React Native was even more JavaScripty and webby, check out Expo.

Yoga is a stand-alone layout engine that extends beyond React Native and allows product engineers to build layouts quickly for multiple platforms with a highly optimized open source layout engine designed with speed, size, and ease of use in mind.

Bugsnag, Microsoft App Center, and Sentry all provide excellent crash and error monitoring services for React and React Native apps. These services allow you to proactively monitor crashes and issues occurring on your apps in real time so you can fix them quickly and improve user experience.

The React Developer Tools are great for debugging React and React Native apps.

Edit this page
Last updated on
- + diff --git a/docs/0.60/more-resources/index.html b/docs/0.60/more-resources/index.html index 886d6a72cc9..6526610fbd9 100644 --- a/docs/0.60/more-resources/index.html +++ b/docs/0.60/more-resources/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

More Resources

If you only read through this website, you should be able to build a pretty cool React Native app. But React Native isn't a product made by one company - it's a community of thousands of developers. So if you're interested in React Native, here's some related stuff you might want to check out.

Popular Libraries

If you're using React Native, you probably already know about React. So I feel a bit silly mentioning this. But if you haven't, check out React - it's the best way to build a modern website.

One common question is how to handle the "state" of your React Native application. The most popular library for this is Redux. Don't be afraid of how often Redux uses the word "reducer" - it's a pretty basic library, and there's also a nice series of videos explaining it.

If you're looking for a library that does a specific thing, check out Awesome React Native, a curated list of components that also has demos, articles, and other stuff.

Examples

Try out apps from the Showcase to see what React Native is capable of! There are also some example apps on GitHub. You can run the apps on a simulator or device, and you can see the source code for these apps, which is neat.

The folks who built the app for Facebook's F8 conference also open-sourced the code and wrote up a detailed series of tutorials. This is useful if you want a more in-depth example that's more realistic than most sample apps out there.

Extending React Native

  • Developers write and publish React Native modules to npm and open source them on GitHub.
  • Making modules helps grow the React Native ecosystem and community. We recommend writing modules for your use cases and sharing them on npm.
  • Read the guides on Native Modules (iOS, Android) and Native UI Components (iOS, Android) if you are interested in extending native functionality.
  • Looking for a pre-built component? Check JS.coach or Native Directory to find what the community has been creating.

Development Tools

Nuclide is the IDE that Facebook uses internally for JavaScript development. The killer feature of Nuclide is its debugging ability. It also has great inline Flow support. VS Code is another IDE that is popular with JavaScript developers.

Ignite is a starter kit that uses Redux and a few different common UI libraries. It has a CLI to generate apps, components, and containers. If you like all of the individual tech choices, Ignite could be perfect for you.

App Center is a service from Microsoft that allows you to deploy live updates to your React Native app. If you don't like going through the app store process to deploy little tweaks, and you also don't like setting up your own backend, give App Center a try.

Expo is a development environment plus application that focuses on letting you build React Native apps in the Expo development environment, without ever touching Xcode or Android Studio. If you wish React Native was even more JavaScripty and webby, check out Expo.

Yoga is a stand-alone layout engine that extends beyond React Native and allows product engineers to build layouts quickly for multiple platforms with a highly optimized open source layout engine designed with speed, size, and ease of use in mind.

Bugsnag, Microsoft App Center, and Sentry all provide excellent crash and error monitoring services for React and React Native apps. These services allow you to proactively monitor crashes and issues occurring on your apps in real time so you can fix them quickly and improve user experience.

The React Developer Tools are great for debugging React and React Native apps.

Edit this page
Last updated on
- + diff --git a/docs/0.60/native-components-android.html b/docs/0.60/native-components-android.html index cba4348eac6..f5ce9bee0aa 100644 --- a/docs/0.60/native-components-android.html +++ b/docs/0.60/native-components-android.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
var RCTMyCustomView = requireNativeComponent(`RCTMyCustomView`);
Edit this page
Last updated on
- + diff --git a/docs/0.60/native-components-android/index.html b/docs/0.60/native-components-android/index.html index cba4348eac6..f5ce9bee0aa 100644 --- a/docs/0.60/native-components-android/index.html +++ b/docs/0.60/native-components-android/index.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
var RCTMyCustomView = requireNativeComponent(`RCTMyCustomView`);
Edit this page
Last updated on
- + diff --git a/docs/0.60/native-components-ios.html b/docs/0.60/native-components-ios.html index dd45ebda928..1a8b9bf6955 100644 --- a/docs/0.60/native-components-ios.html +++ b/docs/0.60/native-components-ios.html @@ -19,7 +19,7 @@ - + @@ -96,7 +96,7 @@
return @{
@"ComponentHeight": @(CGRectGetHeight(dp.frame)),
@"ComponentWidth": @(CGRectGetWidth(dp.frame)),
@"DatePickerModes": @{
@"time": @(UIDatePickerModeTime),
@"date": @(UIDatePickerModeDate),
@"datetime": @(UIDatePickerModeDateAndTime),
}
};
}

This guide covered many of the aspects of bridging over custom native components, but there is even more you might need to consider, such as custom hooks for inserting and laying out subviews. If you want to go even deeper, check out the source code of some of the implemented components.

Edit this page
Last updated on
- + diff --git a/docs/0.60/native-components-ios/index.html b/docs/0.60/native-components-ios/index.html index dd45ebda928..1a8b9bf6955 100644 --- a/docs/0.60/native-components-ios/index.html +++ b/docs/0.60/native-components-ios/index.html @@ -19,7 +19,7 @@ - + @@ -96,7 +96,7 @@
return @{
@"ComponentHeight": @(CGRectGetHeight(dp.frame)),
@"ComponentWidth": @(CGRectGetWidth(dp.frame)),
@"DatePickerModes": @{
@"time": @(UIDatePickerModeTime),
@"date": @(UIDatePickerModeDate),
@"datetime": @(UIDatePickerModeDateAndTime),
}
};
}

This guide covered many of the aspects of bridging over custom native components, but there is even more you might need to consider, such as custom hooks for inserting and laying out subviews. If you want to go even deeper, check out the source code of some of the implemented components.

Edit this page
Last updated on
- + diff --git a/docs/0.60/native-modules-android.html b/docs/0.60/native-modules-android.html index 54cf8b846b8..0c0e928cc15 100644 --- a/docs/0.60/native-modules-android.html +++ b/docs/0.60/native-modules-android.html @@ -19,7 +19,7 @@ - + @@ -83,7 +83,7 @@
@Override
public void onHostDestroy() {
// Activity `onDestroy`
}
Edit this page
Last updated on
- + diff --git a/docs/0.60/native-modules-android/index.html b/docs/0.60/native-modules-android/index.html index 54cf8b846b8..0c0e928cc15 100644 --- a/docs/0.60/native-modules-android/index.html +++ b/docs/0.60/native-modules-android/index.html @@ -19,7 +19,7 @@ - + @@ -83,7 +83,7 @@
@Override
public void onHostDestroy() {
// Activity `onDestroy`
}
Edit this page
Last updated on
- + diff --git a/docs/0.60/native-modules-ios.html b/docs/0.60/native-modules-ios.html index 84413b8cdd5..b81c33210e1 100644 --- a/docs/0.60/native-modules-ios.html +++ b/docs/0.60/native-modules-ios.html @@ -19,7 +19,7 @@ - + @@ -71,7 +71,7 @@
@end

For those of you new to Swift and Objective-C, whenever you mix the two languages in an iOS project, you will also need an additional bridging file, known as a bridging header, to expose the Objective-C files to Swift. Xcode will offer to create this header file for you if you add your Swift file to your app through the Xcode File>New File menu option. You will need to import RCTBridgeModule.h in this header file.

// CalendarManager-Bridging-Header.h
#import <React/RCTBridgeModule.h>

You can also use RCT_EXTERN_REMAP_MODULE and _RCT_EXTERN_REMAP_METHOD to alter the JavaScript name of the module or methods you are exporting. For more information see RCTBridgeModule.

Important when making third party modules: Static libraries with Swift are only supported in Xcode 9 and later. In order for the Xcode project to build when you use Swift in the iOS static library you include in the module, your main app project must contain Swift code and a bridging header itself. If your app project does not contain any Swift code, a workaround can be a single empty .swift file and an empty bridging header.

Edit this page
Last updated on
- + diff --git a/docs/0.60/native-modules-ios/index.html b/docs/0.60/native-modules-ios/index.html index 84413b8cdd5..b81c33210e1 100644 --- a/docs/0.60/native-modules-ios/index.html +++ b/docs/0.60/native-modules-ios/index.html @@ -19,7 +19,7 @@ - + @@ -71,7 +71,7 @@
@end

For those of you new to Swift and Objective-C, whenever you mix the two languages in an iOS project, you will also need an additional bridging file, known as a bridging header, to expose the Objective-C files to Swift. Xcode will offer to create this header file for you if you add your Swift file to your app through the Xcode File>New File menu option. You will need to import RCTBridgeModule.h in this header file.

// CalendarManager-Bridging-Header.h
#import <React/RCTBridgeModule.h>

You can also use RCT_EXTERN_REMAP_MODULE and _RCT_EXTERN_REMAP_METHOD to alter the JavaScript name of the module or methods you are exporting. For more information see RCTBridgeModule.

Important when making third party modules: Static libraries with Swift are only supported in Xcode 9 and later. In order for the Xcode project to build when you use Swift in the iOS static library you include in the module, your main app project must contain Swift code and a bridging header itself. If your app project does not contain any Swift code, a workaround can be a single empty .swift file and an empty bridging header.

Edit this page
Last updated on
- + diff --git a/docs/0.60/native-modules-setup.html b/docs/0.60/native-modules-setup.html index f8b1f22ddfa..d7f983f4f9c 100644 --- a/docs/0.60/native-modules-setup.html +++ b/docs/0.60/native-modules-setup.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Native Modules Setup

Native modules are usually distributed as npm packages, except that on top of the usual JavaScript they will include some native code per platform. To understand more about npm packages you may find this guide useful.

To get set up with the basic project structure for a native module we will use a third party tool create-react-native-module. You can go ahead further and dive deep into how that library works, for our needs we will only need:

$ yarn global add create-react-native-module
$ create-react-native-module MyLibrary

Where MyLibrary is the name you would like for the new module. After doing this you will navigate into MyLibrary folder and install the npm package to be locally available for your computer by doing:

$ yarn install

After this is done you can go to your main react app folder (which you created by doing react-native init MyApp)

  • add your newly created module as a dependency in your package.json
  • run yarn install to bring it along from your local npm repository.

After this, you will be able to continue to Native Modules (iOS) or Native Modules (Android) to add in some code. Make sure to read the README.md within your MyLibrary Directory for platform-specific instructions on how to include the project.

Edit this page
Last updated on
- + diff --git a/docs/0.60/native-modules-setup/index.html b/docs/0.60/native-modules-setup/index.html index f8b1f22ddfa..d7f983f4f9c 100644 --- a/docs/0.60/native-modules-setup/index.html +++ b/docs/0.60/native-modules-setup/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Native Modules Setup

Native modules are usually distributed as npm packages, except that on top of the usual JavaScript they will include some native code per platform. To understand more about npm packages you may find this guide useful.

To get set up with the basic project structure for a native module we will use a third party tool create-react-native-module. You can go ahead further and dive deep into how that library works, for our needs we will only need:

$ yarn global add create-react-native-module
$ create-react-native-module MyLibrary

Where MyLibrary is the name you would like for the new module. After doing this you will navigate into MyLibrary folder and install the npm package to be locally available for your computer by doing:

$ yarn install

After this is done you can go to your main react app folder (which you created by doing react-native init MyApp)

  • add your newly created module as a dependency in your package.json
  • run yarn install to bring it along from your local npm repository.

After this, you will be able to continue to Native Modules (iOS) or Native Modules (Android) to add in some code. Make sure to read the README.md within your MyLibrary Directory for platform-specific instructions on how to include the project.

Edit this page
Last updated on
- + diff --git a/docs/0.60/navigation.html b/docs/0.60/navigation.html index a3bb1be1cc1..43f8625479d 100644 --- a/docs/0.60/navigation.html +++ b/docs/0.60/navigation.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
function MyStack() {
return (
<NavigationContainer>
<Stack.Navigator>
<Stack.Screen
name="Home"
component={Home}
options={{ title: 'Welcome' }}
/>
<Stack.Screen name="Profile" component={Profile} />
</Stack.Navigator>
</NavigationContainer>
);
}

In this example, there are 2 screens (Home and Profile) defined using the Stack.Screen component. Similarly, you can define as many screens as you like.

You can set options such as the screen title for each screen in the options prop of Stack.Screen.

Each screen takes a component prop that is a React component. Those components receive a prop called navigation which has various methods to link to other screens. For example, you can use navigation.navigate to go to the Profile screen:

function HomeScreen({ navigation }) {
return (
<Button
title="Go to Jane's profile"
onPress={() =>
navigation.navigate('Profile', { name: 'Jane' })
}
/>
);
}

The views in the stack navigator use native components and the Animated library to deliver 60fps animations that are run on the native thread. Plus, the animations and gestures can be customized.

React Navigation also has packages for different kind of navigators such as tabs and drawer. You can use them to implement various patterns in your app.

For a complete intro to React Navigation, follow the React Navigation Getting Started Guide.

Edit this page
Last updated on
- + diff --git a/docs/0.60/navigation/index.html b/docs/0.60/navigation/index.html index a3bb1be1cc1..43f8625479d 100644 --- a/docs/0.60/navigation/index.html +++ b/docs/0.60/navigation/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
function MyStack() {
return (
<NavigationContainer>
<Stack.Navigator>
<Stack.Screen
name="Home"
component={Home}
options={{ title: 'Welcome' }}
/>
<Stack.Screen name="Profile" component={Profile} />
</Stack.Navigator>
</NavigationContainer>
);
}

In this example, there are 2 screens (Home and Profile) defined using the Stack.Screen component. Similarly, you can define as many screens as you like.

You can set options such as the screen title for each screen in the options prop of Stack.Screen.

Each screen takes a component prop that is a React component. Those components receive a prop called navigation which has various methods to link to other screens. For example, you can use navigation.navigate to go to the Profile screen:

function HomeScreen({ navigation }) {
return (
<Button
title="Go to Jane's profile"
onPress={() =>
navigation.navigate('Profile', { name: 'Jane' })
}
/>
);
}

The views in the stack navigator use native components and the Animated library to deliver 60fps animations that are run on the native thread. Plus, the animations and gestures can be customized.

React Navigation also has packages for different kind of navigators such as tabs and drawer. You can use them to implement various patterns in your app.

For a complete intro to React Navigation, follow the React Navigation Getting Started Guide.

Edit this page
Last updated on
- + diff --git a/docs/0.60/netinfo.html b/docs/0.60/netinfo.html index 33d7037adc3..45542c58021 100644 --- a/docs/0.60/netinfo.html +++ b/docs/0.60/netinfo.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

NetInfo

Deprecated. Use react-native-community/react-native-netinfo instead.

NetInfo exposes info about online/offline status

NetInfo.getConnectionInfo().then((connectionInfo) => {
console.log(
'Initial, type: ' +
connectionInfo.type +
', effectiveType: ' +
connectionInfo.effectiveType
);
});
function handleFirstConnectivityChange(connectionInfo) {
console.log(
'First change, type: ' +
connectionInfo.type +
', effectiveType: ' +
connectionInfo.effectiveType
);
NetInfo.removeEventListener(
'connectionChange',
handleFirstConnectivityChange
);
}
NetInfo.addEventListener(
'connectionChange',
handleFirstConnectivityChange
);

ConnectionType enum

ConnectionType describes the type of connection the device is using to communicate with the network.

Cross platform values for ConnectionType:

  • none - device is offline
  • wifi - device is online and connected via wifi, or is the iOS simulator
  • cellular - device is connected via Edge, 3G, WiMax, or LTE
  • unknown - error case and the network status is unknown

Android-only values for ConnectionType:

  • bluetooth - device is connected via Bluetooth
  • ethernet - device is connected via Ethernet
  • wimax - device is connected via WiMAX

EffectiveConnectionType enum

Cross platform values for EffectiveConnectionType:

  • 2g
  • 3g
  • 4g
  • unknown

Android

To request network info, you need to add the following line to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Methods

Properties

Reference

Methods

addEventListener()

NetInfo.addEventListener(eventName, handler);

Adds an event handler.

Parameters:

NameTypeRequiredDescription
eventNameenum(connectionChange, change)YesThe change event name.
handlerfunctionYesListener function.

Supported events:

  • connectionChange: Fires when the network status changes. The argument to the event handler is an object with keys:
    • type: A ConnectionType (listed above)
    • effectiveType: An EffectiveConnectionType (listed above)
  • change: This event is deprecated. Listen to connectionChange instead. Fires when the network status changes. The argument to the event handler is one of the deprecated connectivity types listed above.

removeEventListener()

NetInfo.removeEventListener(eventName, handler);

Removes the listener for network status changes.

Parameters:

NameTypeRequiredDescription
eventNameenum(connectionChange, change)YesThe change event name.
handlerfunctionYesListener function.

getConnectionInfo()

NetInfo.getConnectionInfo();

Returns a promise that resolves to an object with type and effectiveType keys whose values are a ConnectionType and an EffectiveConnectionType), respectively.

isConnectionExpensive()

NetInfo.isConnectionExpensive();

Available on Android. Detect if the current active connection is metered or not. A network is classified as metered when the user is sensitive to heavy data usage on that connection due to monetary costs, data limitations or battery/performance issues.

NetInfo.isConnectionExpensive()
.then(isConnectionExpensive => {
console.log('Connection is ' + (isConnectionExpensive ? 'Expensive' : 'Not Expensive'));
})
.catch(error => {
console.error(error);
});

Properties

isConnected

Available on all platforms. Asynchronously fetch a boolean to determine internet connectivity.

NetInfo.isConnected.fetch().then(isConnected => {
console.log('First, is ' + (isConnected ? 'online' : 'offline'));
});
function handleFirstConnectivityChange(isConnected) {
console.log('Then, is ' + (isConnected ? 'online' : 'offline'));
NetInfo.isConnected.removeEventListener(
'connectionChange',
handleFirstConnectivityChange
);
}
NetInfo.isConnected.addEventListener(
'connectionChange',
handleFirstConnectivityChange
);
Edit this page
Last updated on
- + diff --git a/docs/0.60/netinfo/index.html b/docs/0.60/netinfo/index.html index 33d7037adc3..45542c58021 100644 --- a/docs/0.60/netinfo/index.html +++ b/docs/0.60/netinfo/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

NetInfo

Deprecated. Use react-native-community/react-native-netinfo instead.

NetInfo exposes info about online/offline status

NetInfo.getConnectionInfo().then((connectionInfo) => {
console.log(
'Initial, type: ' +
connectionInfo.type +
', effectiveType: ' +
connectionInfo.effectiveType
);
});
function handleFirstConnectivityChange(connectionInfo) {
console.log(
'First change, type: ' +
connectionInfo.type +
', effectiveType: ' +
connectionInfo.effectiveType
);
NetInfo.removeEventListener(
'connectionChange',
handleFirstConnectivityChange
);
}
NetInfo.addEventListener(
'connectionChange',
handleFirstConnectivityChange
);

ConnectionType enum

ConnectionType describes the type of connection the device is using to communicate with the network.

Cross platform values for ConnectionType:

  • none - device is offline
  • wifi - device is online and connected via wifi, or is the iOS simulator
  • cellular - device is connected via Edge, 3G, WiMax, or LTE
  • unknown - error case and the network status is unknown

Android-only values for ConnectionType:

  • bluetooth - device is connected via Bluetooth
  • ethernet - device is connected via Ethernet
  • wimax - device is connected via WiMAX

EffectiveConnectionType enum

Cross platform values for EffectiveConnectionType:

  • 2g
  • 3g
  • 4g
  • unknown

Android

To request network info, you need to add the following line to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Methods

Properties

Reference

Methods

addEventListener()

NetInfo.addEventListener(eventName, handler);

Adds an event handler.

Parameters:

NameTypeRequiredDescription
eventNameenum(connectionChange, change)YesThe change event name.
handlerfunctionYesListener function.

Supported events:

  • connectionChange: Fires when the network status changes. The argument to the event handler is an object with keys:
    • type: A ConnectionType (listed above)
    • effectiveType: An EffectiveConnectionType (listed above)
  • change: This event is deprecated. Listen to connectionChange instead. Fires when the network status changes. The argument to the event handler is one of the deprecated connectivity types listed above.

removeEventListener()

NetInfo.removeEventListener(eventName, handler);

Removes the listener for network status changes.

Parameters:

NameTypeRequiredDescription
eventNameenum(connectionChange, change)YesThe change event name.
handlerfunctionYesListener function.

getConnectionInfo()

NetInfo.getConnectionInfo();

Returns a promise that resolves to an object with type and effectiveType keys whose values are a ConnectionType and an EffectiveConnectionType), respectively.

isConnectionExpensive()

NetInfo.isConnectionExpensive();

Available on Android. Detect if the current active connection is metered or not. A network is classified as metered when the user is sensitive to heavy data usage on that connection due to monetary costs, data limitations or battery/performance issues.

NetInfo.isConnectionExpensive()
.then(isConnectionExpensive => {
console.log('Connection is ' + (isConnectionExpensive ? 'Expensive' : 'Not Expensive'));
})
.catch(error => {
console.error(error);
});

Properties

isConnected

Available on all platforms. Asynchronously fetch a boolean to determine internet connectivity.

NetInfo.isConnected.fetch().then(isConnected => {
console.log('First, is ' + (isConnected ? 'online' : 'offline'));
});
function handleFirstConnectivityChange(isConnected) {
console.log('Then, is ' + (isConnected ? 'online' : 'offline'));
NetInfo.isConnected.removeEventListener(
'connectionChange',
handleFirstConnectivityChange
);
}
NetInfo.isConnected.addEventListener(
'connectionChange',
handleFirstConnectivityChange
);
Edit this page
Last updated on
- + diff --git a/docs/0.60/network.html b/docs/0.60/network.html index fff51c1b950..6197759deaf 100644 --- a/docs/0.60/network.html +++ b/docs/0.60/network.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
ws.onclose = (e) => {
// connection closed
console.log(e.code, e.reason);
};

Known Issues with fetch and cookie based authentication

The following options are currently not working with fetch

Edit this page
Last updated on
- + diff --git a/docs/0.60/network/index.html b/docs/0.60/network/index.html index fff51c1b950..6197759deaf 100644 --- a/docs/0.60/network/index.html +++ b/docs/0.60/network/index.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
ws.onclose = (e) => {
// connection closed
console.log(e.code, e.reason);
};

Known Issues with fetch and cookie based authentication

The following options are currently not working with fetch

Edit this page
Last updated on
- + diff --git a/docs/0.60/optimizing-flatlist-configuration.html b/docs/0.60/optimizing-flatlist-configuration.html index 60c5b64259b..f57b3141ee1 100644 --- a/docs/0.60/optimizing-flatlist-configuration.html +++ b/docs/0.60/optimizing-flatlist-configuration.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// ...
}
Edit this page
Last updated on
- + diff --git a/docs/0.60/optimizing-flatlist-configuration/index.html b/docs/0.60/optimizing-flatlist-configuration/index.html index 60c5b64259b..f57b3141ee1 100644 --- a/docs/0.60/optimizing-flatlist-configuration/index.html +++ b/docs/0.60/optimizing-flatlist-configuration/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// ...
}
Edit this page
Last updated on
- + diff --git a/docs/0.60/out-of-tree-platforms.html b/docs/0.60/out-of-tree-platforms.html index 28059f5f45e..8b1af6f322f 100644 --- a/docs/0.60/out-of-tree-platforms.html +++ b/docs/0.60/out-of-tree-platforms.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Out-of-Tree Platforms

React Native is not only for Android and iOS - there are community-supported projects that bring it to other platforms, such as:

Creating your own React Native platform

Right now the process of creating a React Native platform from scratch is not very well documented - one of the goals of the upcoming re-architecture (Fabric) is to make maintaining a platform easier.

Bundling

As of React Native 0.57 you can now register your React Native platform with React Native's JavaScript bundler, Metro. This means you can pass --platform example to react-native bundle, and it will look for JavaScript files with the .example.js suffix.

To register your platform with RNPM, your module's name must match one of these patterns:

  • react-native-example - It will search all top-level modules that start with react-native-
  • @org/react-native-example - It will search for modules that start with react-native- under any scope
  • @react-native-example/module - It will search in all modules under scopes with names starting with @react-native-

You must also have an entry in your package.json like this:

{
"rnpm": {
"haste": {
"providesModuleNodeModules": ["react-native-example"],
"platforms": ["example"]
}
}
}

"providesModuleNodeModules" is an array of modules that will get added to the Haste module search path, and "platforms" is an array of platform suffixes that will be added as valid platforms.

Edit this page
Last updated on
- + diff --git a/docs/0.60/out-of-tree-platforms/index.html b/docs/0.60/out-of-tree-platforms/index.html index 28059f5f45e..8b1af6f322f 100644 --- a/docs/0.60/out-of-tree-platforms/index.html +++ b/docs/0.60/out-of-tree-platforms/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Out-of-Tree Platforms

React Native is not only for Android and iOS - there are community-supported projects that bring it to other platforms, such as:

Creating your own React Native platform

Right now the process of creating a React Native platform from scratch is not very well documented - one of the goals of the upcoming re-architecture (Fabric) is to make maintaining a platform easier.

Bundling

As of React Native 0.57 you can now register your React Native platform with React Native's JavaScript bundler, Metro. This means you can pass --platform example to react-native bundle, and it will look for JavaScript files with the .example.js suffix.

To register your platform with RNPM, your module's name must match one of these patterns:

  • react-native-example - It will search all top-level modules that start with react-native-
  • @org/react-native-example - It will search for modules that start with react-native- under any scope
  • @react-native-example/module - It will search in all modules under scopes with names starting with @react-native-

You must also have an entry in your package.json like this:

{
"rnpm": {
"haste": {
"providesModuleNodeModules": ["react-native-example"],
"platforms": ["example"]
}
}
}

"providesModuleNodeModules" is an array of modules that will get added to the Haste module search path, and "platforms" is an array of platform suffixes that will be added as valid platforms.

Edit this page
Last updated on
- + diff --git a/docs/0.60/panresponder.html b/docs/0.60/panresponder.html index e6aa7b3f110..d04d29dfa32 100644 --- a/docs/0.60/panresponder.html +++ b/docs/0.60/panresponder.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
render() {
return <View {...this._panResponder.panHandlers} />;
}
}

Working Example

To see it in action, try the PanResponder example in RNTester

Reference

Methods

create()

static create(config)

@param {object} config Enhanced versions of all of the responder callbacks that provide not only the typical ResponderSyntheticEvent, but also the PanResponder gesture state, by replacing the word Responder with PanResponder in each of the typical onResponder* callbacks. For example, the config object would look like:

In general, for events that have capture equivalents, we update the gestureState once in the capture phase and can use it in the bubble phase as well.

Be careful with onStartShould* callbacks. They only reflect updated gestureState for start/end events that bubble/capture to the Node. Once the node is the responder, you can rely on every start/end event being processed by the gesture and gestureState being updated accordingly. (numberActiveTouches) may not be totally accurate unless you are the responder.

Edit this page
Last updated on
- + diff --git a/docs/0.60/panresponder/index.html b/docs/0.60/panresponder/index.html index e6aa7b3f110..d04d29dfa32 100644 --- a/docs/0.60/panresponder/index.html +++ b/docs/0.60/panresponder/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
render() {
return <View {...this._panResponder.panHandlers} />;
}
}

Working Example

To see it in action, try the PanResponder example in RNTester

Reference

Methods

create()

static create(config)

@param {object} config Enhanced versions of all of the responder callbacks that provide not only the typical ResponderSyntheticEvent, but also the PanResponder gesture state, by replacing the word Responder with PanResponder in each of the typical onResponder* callbacks. For example, the config object would look like:

In general, for events that have capture equivalents, we update the gestureState once in the capture phase and can use it in the bubble phase as well.

Be careful with onStartShould* callbacks. They only reflect updated gestureState for start/end events that bubble/capture to the Node. Once the node is the responder, you can rely on every start/end event being processed by the gesture and gestureState being updated accordingly. (numberActiveTouches) may not be totally accurate unless you are the responder.

Edit this page
Last updated on
- + diff --git a/docs/0.60/performance.html b/docs/0.60/performance.html index 18f05e66ed7..6c768eb4153 100644 --- a/docs/0.60/performance.html +++ b/docs/0.60/performance.html @@ -19,7 +19,7 @@ - + @@ -45,7 +45,7 @@
module.exports = config;

The preloadedModules entry in the config indicates which modules should be marked as preloaded when building a RAM bundle. When the bundle is loaded, those modules are immediately loaded, before any requires have even executed. The blacklist entry indicates that those modules should not be required inline. Because they are preloaded, there is no performance benefit from using an inline require. In fact the javascript spends extra time resolving the inline require every time the imports are referenced.

Test and Measure Improvements

You should now be ready to build your app using the RAM format and inline requires. Make sure you measure the before and after startup times.

Edit this page
Last updated on
- + diff --git a/docs/0.60/performance/index.html b/docs/0.60/performance/index.html index 18f05e66ed7..6c768eb4153 100644 --- a/docs/0.60/performance/index.html +++ b/docs/0.60/performance/index.html @@ -19,7 +19,7 @@ - + @@ -45,7 +45,7 @@
module.exports = config;

The preloadedModules entry in the config indicates which modules should be marked as preloaded when building a RAM bundle. When the bundle is loaded, those modules are immediately loaded, before any requires have even executed. The blacklist entry indicates that those modules should not be required inline. Because they are preloaded, there is no performance benefit from using an inline require. In fact the javascript spends extra time resolving the inline require every time the imports are referenced.

Test and Measure Improvements

You should now be ready to build your app using the RAM format and inline requires. Make sure you measure the before and after startup times.

Edit this page
Last updated on
- + diff --git a/docs/0.60/permissionsandroid.html b/docs/0.60/permissionsandroid.html index 7f06c9e3f24..c5feb935f6e 100644 --- a/docs/0.60/permissionsandroid.html +++ b/docs/0.60/permissionsandroid.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
async function requestCameraPermission() {
try {
const granted = await PermissionsAndroid.request(
PermissionsAndroid.PERMISSIONS.CAMERA,
{
title: 'Cool Photo App Camera Permission',
message:
'Cool Photo App needs access to your camera ' +
'so you can take awesome pictures.',
buttonNeutral: 'Ask Me Later',
buttonNegative: 'Cancel',
buttonPositive: 'OK'
}
);
if (granted === PermissionsAndroid.RESULTS.GRANTED) {
console.log('You can use the camera');
} else {
console.log('Camera permission denied');
}
} catch (err) {
console.warn(err);
}
}

Permissions that require prompting the user

Available as constants under PermissionsAndroid.PERMISSIONS:

Result strings for requesting permissions

Available as constants under PermissionsAndroid.RESULTS:

Reference

Methods

constructor()

constructor();

check()

check(permission);

Returns a promise resolving to a boolean value as to whether the specified permissions has been granted.

Parameters:

NameTypeRequiredDescription
permissionstringYesThe permission to check for.

request()

request(permission, [rationale]);

Prompts the user to enable a permission and returns a promise resolving to a string value (see result strings above) indicating whether the user allowed or denied the request or does not want to be asked again.

If rationale is provided, this function checks with the OS whether it is necessary to show a dialog explaining why the permission is needed (https://developer.android.com/training/permissions/requesting.html#explain) and then shows the system permission dialog.

Parameters:

NameTypeRequiredDescription
permissionstringYesThe permission to request.
rationaleobjectNoSee rationale below.

Rationale:

NameTypeRequiredDescription
titlestringYesThe title of the dialog.
messagestringYesThe message of the dialog.
buttonPositivestringYesThe text of the positive button.
buttonNegativestringNoThe text of the negative button.
buttonNeutralstringNoThe text of the neutral button.

requestMultiple()

requestMultiple(permissions);

Prompts the user to enable multiple permissions in the same dialog and returns an object with the permissions as keys and strings as values (see result strings above) indicating whether the user allowed or denied the request or does not want to be asked again.

Parameters:

NameTypeRequiredDescription
permissionsarrayYesArray of permissions to request.
Edit this page
Last updated on
- + diff --git a/docs/0.60/permissionsandroid/index.html b/docs/0.60/permissionsandroid/index.html index 7f06c9e3f24..c5feb935f6e 100644 --- a/docs/0.60/permissionsandroid/index.html +++ b/docs/0.60/permissionsandroid/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
async function requestCameraPermission() {
try {
const granted = await PermissionsAndroid.request(
PermissionsAndroid.PERMISSIONS.CAMERA,
{
title: 'Cool Photo App Camera Permission',
message:
'Cool Photo App needs access to your camera ' +
'so you can take awesome pictures.',
buttonNeutral: 'Ask Me Later',
buttonNegative: 'Cancel',
buttonPositive: 'OK'
}
);
if (granted === PermissionsAndroid.RESULTS.GRANTED) {
console.log('You can use the camera');
} else {
console.log('Camera permission denied');
}
} catch (err) {
console.warn(err);
}
}

Permissions that require prompting the user

Available as constants under PermissionsAndroid.PERMISSIONS:

Result strings for requesting permissions

Available as constants under PermissionsAndroid.RESULTS:

Reference

Methods

constructor()

constructor();

check()

check(permission);

Returns a promise resolving to a boolean value as to whether the specified permissions has been granted.

Parameters:

NameTypeRequiredDescription
permissionstringYesThe permission to check for.

request()

request(permission, [rationale]);

Prompts the user to enable a permission and returns a promise resolving to a string value (see result strings above) indicating whether the user allowed or denied the request or does not want to be asked again.

If rationale is provided, this function checks with the OS whether it is necessary to show a dialog explaining why the permission is needed (https://developer.android.com/training/permissions/requesting.html#explain) and then shows the system permission dialog.

Parameters:

NameTypeRequiredDescription
permissionstringYesThe permission to request.
rationaleobjectNoSee rationale below.

Rationale:

NameTypeRequiredDescription
titlestringYesThe title of the dialog.
messagestringYesThe message of the dialog.
buttonPositivestringYesThe text of the positive button.
buttonNegativestringNoThe text of the negative button.
buttonNeutralstringNoThe text of the neutral button.

requestMultiple()

requestMultiple(permissions);

Prompts the user to enable multiple permissions in the same dialog and returns an object with the permissions as keys and strings as values (see result strings above) indicating whether the user allowed or denied the request or does not want to be asked again.

Parameters:

NameTypeRequiredDescription
permissionsarrayYesArray of permissions to request.
Edit this page
Last updated on
- + diff --git a/docs/0.60/picker-item.html b/docs/0.60/picker-item.html index d614253699a..0aada2bc132 100644 --- a/docs/0.60/picker-item.html +++ b/docs/0.60/picker-item.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Picker.Item

Individual selectable item in a Picker.

Props

Reference

Props

label

Text to display for this item.

TypeRequired
stringYes

color

Color of this item's text.

TypeRequired
colorNo

testID

Used to locate the item in end-to-end tests.

TypeRequired
stringNo

value

The value to be passed to picker's onValueChange callback when this item is selected. Can be a string or an integer.

TypeRequiredPlatform
anyNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.60/picker-item/index.html b/docs/0.60/picker-item/index.html index d614253699a..0aada2bc132 100644 --- a/docs/0.60/picker-item/index.html +++ b/docs/0.60/picker-item/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Picker.Item

Individual selectable item in a Picker.

Props

Reference

Props

label

Text to display for this item.

TypeRequired
stringYes

color

Color of this item's text.

TypeRequired
colorNo

testID

Used to locate the item in end-to-end tests.

TypeRequired
stringNo

value

The value to be passed to picker's onValueChange callback when this item is selected. Can be a string or an integer.

TypeRequiredPlatform
anyNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.60/picker-style-props.html b/docs/0.60/picker-style-props.html index 02b25f54168..1af8b5454d7 100644 --- a/docs/0.60/picker-style-props.html +++ b/docs/0.60/picker-style-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.60/picker-style-props/index.html b/docs/0.60/picker-style-props/index.html index 02b25f54168..1af8b5454d7 100644 --- a/docs/0.60/picker-style-props/index.html +++ b/docs/0.60/picker-style-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.60/picker.html b/docs/0.60/picker.html index 6f0c5cdf1c6..c11007c8e6c 100644 --- a/docs/0.60/picker.html +++ b/docs/0.60/picker.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Picker

Renders the native picker component on Android and iOS. Example:

<Picker
selectedValue={this.state.language}
style={{ height: 50, width: 100 }}
onValueChange={(itemValue, itemIndex) =>
this.setState({ language: itemValue })
}>
<Picker.Item label="Java" value="java" />
<Picker.Item label="JavaScript" value="js" />
</Picker>

Reference

Props

Inherits View Props.

onValueChange

Callback for when an item is selected. This is called with the following parameters:

  • itemValue: the value prop of the item that was selected
  • itemPosition: the index of the selected item in this picker
TypeRequired
functionNo

selectedValue

Value matching value of one of the items. Can be a string or an integer.

TypeRequired
anyNo

style

TypeRequired
pickerStyleTypeNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

enabled

If set to false, the picker will be disabled, i.e. the user will not be able to make a selection.

TypeRequiredPlatform
boolNoAndroid

mode

On Android, specifies how to display the selection items when the user taps on the picker:

  • 'dialog': Show a modal dialog. This is the default.
  • 'dropdown': Shows a dropdown anchored to the picker view
TypeRequiredPlatform
enum('dialog', 'dropdown')NoAndroid

prompt

Prompt string for this picker, used on Android in dialog mode as the title of the dialog.

TypeRequiredPlatform
stringNoAndroid

itemStyle

Style to apply to each of the item labels.

TypeRequiredPlatform
text stylesNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.60/picker/index.html b/docs/0.60/picker/index.html index 6f0c5cdf1c6..c11007c8e6c 100644 --- a/docs/0.60/picker/index.html +++ b/docs/0.60/picker/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Picker

Renders the native picker component on Android and iOS. Example:

<Picker
selectedValue={this.state.language}
style={{ height: 50, width: 100 }}
onValueChange={(itemValue, itemIndex) =>
this.setState({ language: itemValue })
}>
<Picker.Item label="Java" value="java" />
<Picker.Item label="JavaScript" value="js" />
</Picker>

Reference

Props

Inherits View Props.

onValueChange

Callback for when an item is selected. This is called with the following parameters:

  • itemValue: the value prop of the item that was selected
  • itemPosition: the index of the selected item in this picker
TypeRequired
functionNo

selectedValue

Value matching value of one of the items. Can be a string or an integer.

TypeRequired
anyNo

style

TypeRequired
pickerStyleTypeNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

enabled

If set to false, the picker will be disabled, i.e. the user will not be able to make a selection.

TypeRequiredPlatform
boolNoAndroid

mode

On Android, specifies how to display the selection items when the user taps on the picker:

  • 'dialog': Show a modal dialog. This is the default.
  • 'dropdown': Shows a dropdown anchored to the picker view
TypeRequiredPlatform
enum('dialog', 'dropdown')NoAndroid

prompt

Prompt string for this picker, used on Android in dialog mode as the title of the dialog.

TypeRequiredPlatform
stringNoAndroid

itemStyle

Style to apply to each of the item labels.

TypeRequiredPlatform
text stylesNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.60/pickerios.html b/docs/0.60/pickerios.html index ec4e9065384..be6c6a937f3 100644 --- a/docs/0.60/pickerios.html +++ b/docs/0.60/pickerios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

PickerIOS

Deprecated. Use Picker instead.

Reference

Props

Inherits View Props.

itemStyle

TypeRequired
text stylesNo

onValueChange

TypeRequired
functionNo

onChange

TypeRequired
functionNo

selectedValue

TypeRequired
number or stringNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/pickerios/index.html b/docs/0.60/pickerios/index.html index ec4e9065384..be6c6a937f3 100644 --- a/docs/0.60/pickerios/index.html +++ b/docs/0.60/pickerios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

PickerIOS

Deprecated. Use Picker instead.

Reference

Props

Inherits View Props.

itemStyle

TypeRequired
text stylesNo

onValueChange

TypeRequired
functionNo

onChange

TypeRequired
functionNo

selectedValue

TypeRequired
number or stringNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/pixelratio.html b/docs/0.60/pixelratio.html index cccb9ff58b2..eabe856c9e6 100644 --- a/docs/0.60/pixelratio.html +++ b/docs/0.60/pixelratio.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

PixelRatio

PixelRatio class gives access to the device pixel density.

Fetching a correctly sized image

You should get a higher resolution image if you are on a high pixel density device. A good rule of thumb is to multiply the size of the image you display by the pixel ratio.

var image = getImage({
width: PixelRatio.getPixelSizeForLayoutSize(200),
height: PixelRatio.getPixelSizeForLayoutSize(100)
});
<Image source={image} style={{ width: 200, height: 100 }} />;

Pixel grid snapping

In iOS, you can specify positions and dimensions for elements with arbitrary precision, for example 29.674825. But, ultimately the physical display only have a fixed number of pixels, for example 640×960 for iPhone 4 or 750×1334 for iPhone 6. iOS tries to be as faithful as possible to the user value by spreading one original pixel into multiple ones to trick the eye. The downside of this technique is that it makes the resulting element look blurry.

In practice, we found out that developers do not want this feature and they have to work around it by doing manual rounding in order to avoid having blurry elements. In React Native, we are rounding all the pixels automatically.

We have to be careful when to do this rounding. You never want to work with rounded and unrounded values at the same time as you're going to accumulate rounding errors. Having even one rounding error is deadly because a one pixel border may vanish or be twice as big.

In React Native, everything in JavaScript and within the layout engine works with arbitrary precision numbers. It's only when we set the position and dimensions of the native element on the main thread that we round. Also, rounding is done relative to the root rather than the parent, again to avoid accumulating rounding errors.

Reference

Methods

get()

static get()

Returns the device pixel density. Some examples:

getFontScale()

static getFontScale()

Returns the scaling factor for font sizes. This is the ratio that is used to calculate the absolute font size, so any elements that heavily depend on that should use this to do calculations.

If a font scale is not set, this returns the device pixel ratio.

Currently this is only implemented on Android and reflects the user preference set in Settings > Display > Font size, on iOS it will always return the default pixel ratio. @platform android

getPixelSizeForLayoutSize()

static getPixelSizeForLayoutSize(layoutSize)

Converts a layout size (dp) to pixel size (px).

Guaranteed to return an integer number.

roundToNearestPixel()

static roundToNearestPixel(layoutSize)

Rounds a layout size (dp) to the nearest layout size that corresponds to an integer number of pixels. For example, on a device with a PixelRatio of 3, PixelRatio.roundToNearestPixel(8.4) = 8.33, which corresponds to exactly (8.33 * 3) = 25 pixels.

Edit this page
Last updated on
- + diff --git a/docs/0.60/pixelratio/index.html b/docs/0.60/pixelratio/index.html index cccb9ff58b2..eabe856c9e6 100644 --- a/docs/0.60/pixelratio/index.html +++ b/docs/0.60/pixelratio/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

PixelRatio

PixelRatio class gives access to the device pixel density.

Fetching a correctly sized image

You should get a higher resolution image if you are on a high pixel density device. A good rule of thumb is to multiply the size of the image you display by the pixel ratio.

var image = getImage({
width: PixelRatio.getPixelSizeForLayoutSize(200),
height: PixelRatio.getPixelSizeForLayoutSize(100)
});
<Image source={image} style={{ width: 200, height: 100 }} />;

Pixel grid snapping

In iOS, you can specify positions and dimensions for elements with arbitrary precision, for example 29.674825. But, ultimately the physical display only have a fixed number of pixels, for example 640×960 for iPhone 4 or 750×1334 for iPhone 6. iOS tries to be as faithful as possible to the user value by spreading one original pixel into multiple ones to trick the eye. The downside of this technique is that it makes the resulting element look blurry.

In practice, we found out that developers do not want this feature and they have to work around it by doing manual rounding in order to avoid having blurry elements. In React Native, we are rounding all the pixels automatically.

We have to be careful when to do this rounding. You never want to work with rounded and unrounded values at the same time as you're going to accumulate rounding errors. Having even one rounding error is deadly because a one pixel border may vanish or be twice as big.

In React Native, everything in JavaScript and within the layout engine works with arbitrary precision numbers. It's only when we set the position and dimensions of the native element on the main thread that we round. Also, rounding is done relative to the root rather than the parent, again to avoid accumulating rounding errors.

Reference

Methods

get()

static get()

Returns the device pixel density. Some examples:

getFontScale()

static getFontScale()

Returns the scaling factor for font sizes. This is the ratio that is used to calculate the absolute font size, so any elements that heavily depend on that should use this to do calculations.

If a font scale is not set, this returns the device pixel ratio.

Currently this is only implemented on Android and reflects the user preference set in Settings > Display > Font size, on iOS it will always return the default pixel ratio. @platform android

getPixelSizeForLayoutSize()

static getPixelSizeForLayoutSize(layoutSize)

Converts a layout size (dp) to pixel size (px).

Guaranteed to return an integer number.

roundToNearestPixel()

static roundToNearestPixel(layoutSize)

Rounds a layout size (dp) to the nearest layout size that corresponds to an integer number of pixels. For example, on a device with a PixelRatio of 3, PixelRatio.roundToNearestPixel(8.4) = 8.33, which corresponds to exactly (8.33 * 3) = 25 pixels.

Edit this page
Last updated on
- + diff --git a/docs/0.60/platform-specific-code.html b/docs/0.60/platform-specific-code.html index bcf3d002428..188c569ef5c 100644 --- a/docs/0.60/platform-specific-code.html +++ b/docs/0.60/platform-specific-code.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
const majorVersionIOS = parseInt(Platform.Version, 10);
if (majorVersionIOS <= 9) {
console.log('Work around a change in behavior');
}

Platform-specific extensions

When your platform-specific code is more complex, you should consider splitting the code out into separate files. React Native will detect when a file has a .ios. or .android. extension and load the relevant platform file when required from other components.

For example, say you have the following files in your project:

BigButton.ios.js
BigButton.android.js

You can then require the component as follows:

import BigButton from './BigButton';

React Native will automatically pick up the right file based on the running platform.

Native-specific extensions (i.e. sharing code with NodeJS and Web)

You can also use the .native.js extension when a module needs to be shared between NodeJS/Web and React Native but it has no Android/iOS differences. This is specially useful for projects that has common code shared among React Native and ReactJS.

For example, say you have the following files in your project:

Container.js # picked up by Webpack, Rollup or any other Web bundler
Container.native.js # picked up by the React Native bundler for both Android and iOS (Metro)

You can still require it without the .native extension, as follows:

import Container from './Container';

Pro tip: Configure your Web bundler to ignore .native.js extensions in order to avoid having unused code in your production bundle, thus reducing the final bundle size.

Edit this page
Last updated on
- + diff --git a/docs/0.60/platform-specific-code/index.html b/docs/0.60/platform-specific-code/index.html index bcf3d002428..188c569ef5c 100644 --- a/docs/0.60/platform-specific-code/index.html +++ b/docs/0.60/platform-specific-code/index.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
const majorVersionIOS = parseInt(Platform.Version, 10);
if (majorVersionIOS <= 9) {
console.log('Work around a change in behavior');
}

Platform-specific extensions

When your platform-specific code is more complex, you should consider splitting the code out into separate files. React Native will detect when a file has a .ios. or .android. extension and load the relevant platform file when required from other components.

For example, say you have the following files in your project:

BigButton.ios.js
BigButton.android.js

You can then require the component as follows:

import BigButton from './BigButton';

React Native will automatically pick up the right file based on the running platform.

Native-specific extensions (i.e. sharing code with NodeJS and Web)

You can also use the .native.js extension when a module needs to be shared between NodeJS/Web and React Native but it has no Android/iOS differences. This is specially useful for projects that has common code shared among React Native and ReactJS.

For example, say you have the following files in your project:

Container.js # picked up by Webpack, Rollup or any other Web bundler
Container.native.js # picked up by the React Native bundler for both Android and iOS (Metro)

You can still require it without the .native extension, as follows:

import Container from './Container';

Pro tip: Configure your Web bundler to ignore .native.js extensions in order to avoid having unused code in your production bundle, thus reducing the final bundle size.

Edit this page
Last updated on
- + diff --git a/docs/0.60/profiling.html b/docs/0.60/profiling.html index e2756135d5a..d6f72df99dc 100644 --- a/docs/0.60/profiling.html +++ b/docs/0.60/profiling.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Profiling

Use the built-in profiler to get detailed information about work done in the JavaScript thread and main thread side-by-side. Access it by selecting Perf Monitor from the Debug menu.

For iOS, Instruments is an invaluable tool, and on Android you should learn to use systrace.

But first, make sure that Development Mode is OFF! You should see __DEV__ === false, development-level warning are OFF, performance optimizations are ON in your application logs.

Another way to profile JavaScript is to use the Chrome profiler while debugging. This won't give you accurate results as the code is running in Chrome but will give you a general idea of where bottlenecks might be. Run the profiler under Chrome's Performance tab. A flame graph will appear under User Timing. To view more details in tabular format, click at the Bottom Up tab below and then select DedicatedWorker Thread at the top left menu.

Profiling Android UI Performance with systrace

Android supports 10k+ different phones and is generalized to support software rendering: the framework architecture and need to generalize across many hardware targets unfortunately means you get less for free relative to iOS. But sometimes, there are things you can improve -- and many times it's not native code's fault at all!

The first step for debugging this jank is to answer the fundamental question of where your time is being spent during each 16ms frame. For that, we'll be using a standard Android profiling tool called systrace.

systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.

1. Collecting a trace

First, connect a device that exhibits the stuttering you want to investigate to your computer via USB and get it to the point right before the navigation/animation you want to profile. Run systrace as follows:

$ <path_to_android_sdk>/platform-tools/systrace/systrace.py --time=10 -o trace.html sched gfx view -a <your_package_name>

A quick breakdown of this command:

  • time is the length of time the trace will be collected in seconds
  • sched, gfx, and view are the android SDK tags (collections of markers) we care about: sched gives you information about what's running on each core of your phone, gfx gives you graphics info such as frame boundaries, and view gives you information about measure, layout, and draw passes
  • -a <your_package_name> enables app-specific markers, specifically the ones built into the React Native framework. your_package_name can be found in the AndroidManifest.xml of your app and looks like com.example.app

Once the trace starts collecting, perform the animation or interaction you care about. At the end of the trace, systrace will give you a link to the trace which you can open in your browser.

2. Reading the trace

After opening the trace in your browser (preferably Chrome), you should see something like this:

Example

HINT: Use the WASD keys to strafe and zoom

If your trace .html file isn't opening correctly, check your browser console for the following:

ObjectObserveError

Since Object.observe was deprecated in recent browsers, you may have to open the file from the Google Chrome Tracing tool. You can do so by:

  • Opening tab in chrome chrome://tracing
  • Selecting load
  • Selecting the html file generated from the previous command.

Enable VSync highlighting

Check this checkbox at the top right of the screen to highlight the 16ms frame boundaries:

Enable VSync Highlighting

You should see zebra stripes as in the screenshot above. If you don't, try profiling on a different device: Samsung has been known to have issues displaying vsyncs while the Nexus series is generally pretty reliable.

3. Find your process

Scroll until you see (part of) the name of your package. In this case, I was profiling com.facebook.adsmanager, which shows up as book.adsmanager because of silly thread name limits in the kernel.

On the left side, you'll see a set of threads which correspond to the timeline rows on the right. There are a few threads we care about for our purposes: the UI thread (which has your package name or the name UI Thread), mqt_js, and mqt_native_modules. If you're running on Android 5+, we also care about the Render Thread.

  • UI Thread. This is where standard android measure/layout/draw happens. The thread name on the right will be your package name (in my case book.adsmanager) or UI Thread. The events that you see on this thread should look something like this and have to do with Choreographer, traversals, and DispatchUI:

    UI Thread Example

  • JS Thread. This is where JavaScript is executed. The thread name will be either mqt_js or <...> depending on how cooperative the kernel on your device is being. To identify it if it doesn't have a name, look for things like JSCall, Bridge.executeJSCall, etc:

    JS Thread Example

  • Native Modules Thread. This is where native module calls (e.g. the UIManager) are executed. The thread name will be either mqt_native_modules or <...>. To identify it in the latter case, look for things like NativeCall, callJavaModuleMethod, and onBatchComplete:

    Native Modules Thread Example

  • Bonus: Render Thread. If you're using Android L (5.0) and up, you will also have a render thread in your application. This thread generates the actual OpenGL commands used to draw your UI. The thread name will be either RenderThread or <...>. To identify it in the latter case, look for things like DrawFrame and queueBuffer:

    Render Thread Example

Identifying a culprit

A smooth animation should look something like the following:

Smooth Animation

Each change in color is a frame -- remember that in order to display a frame, all our UI work needs to be done by the end of that 16ms period. Notice that no thread is working close to the frame boundary. An application rendering like this is rendering at 60 FPS.

If you noticed chop, however, you might see something like this:

Choppy Animation from JS

Notice that the JS thread is executing almost all the time, and across frame boundaries! This app is not rendering at 60 FPS. In this case, the problem lies in JS.

You might also see something like this:

Choppy Animation from UI

In this case, the UI and render threads are the ones that have work crossing frame boundaries. The UI that we're trying to render on each frame is requiring too much work to be done. In this case, the problem lies in the native views being rendered.

At this point, you'll have some very helpful information to inform your next steps.

Resolving JavaScript issues

If you identified a JS problem, look for clues in the specific JS that you're executing. In the scenario above, we see RCTEventEmitter being called multiple times per frame. Here's a zoom-in of the JS thread from the trace above:

Too much JS

This doesn't seem right. Why is it being called so often? Are they actually different events? The answers to these questions will probably depend on your product code. And many times, you'll want to look into shouldComponentUpdate.

Resolving native UI Issues

If you identified a native UI problem, there are usually two scenarios:

  1. the UI you're trying to draw each frame involves too much work on the GPU, or
  2. You're constructing new UI during the animation/interaction (e.g. loading in new content during a scroll).

Too much GPU work

In the first scenario, you'll see a trace that has the UI thread and/or Render Thread looking like this:

Overloaded GPU

Notice the long amount of time spent in DrawFrame that crosses frame boundaries. This is time spent waiting for the GPU to drain its command buffer from the previous frame.

To mitigate this, you should:

  • investigate using renderToHardwareTextureAndroid for complex, static content that is being animated/transformed (e.g. the Navigator slide/alpha animations)
  • make sure that you are not using needsOffscreenAlphaCompositing, which is disabled by default, as it greatly increases the per-frame load on the GPU in most cases.

If these don't help and you want to dig deeper into what the GPU is actually doing, you can check out Tracer for OpenGL ES.

Creating new views on the UI thread

In the second scenario, you'll see something more like this:

Creating Views

Notice that first the JS thread thinks for a bit, then you see some work done on the native modules thread, followed by an expensive traversal on the UI thread.

There isn't a quick way to mitigate this unless you're able to postpone creating new UI until after the interaction, or you are able to simplify the UI you're creating. The react native team is working on an infrastructure level solution for this that will allow new UI to be created and configured off the main thread, allowing the interaction to continue smoothly.

Edit this page
Last updated on
- + diff --git a/docs/0.60/profiling/index.html b/docs/0.60/profiling/index.html index e2756135d5a..d6f72df99dc 100644 --- a/docs/0.60/profiling/index.html +++ b/docs/0.60/profiling/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Profiling

Use the built-in profiler to get detailed information about work done in the JavaScript thread and main thread side-by-side. Access it by selecting Perf Monitor from the Debug menu.

For iOS, Instruments is an invaluable tool, and on Android you should learn to use systrace.

But first, make sure that Development Mode is OFF! You should see __DEV__ === false, development-level warning are OFF, performance optimizations are ON in your application logs.

Another way to profile JavaScript is to use the Chrome profiler while debugging. This won't give you accurate results as the code is running in Chrome but will give you a general idea of where bottlenecks might be. Run the profiler under Chrome's Performance tab. A flame graph will appear under User Timing. To view more details in tabular format, click at the Bottom Up tab below and then select DedicatedWorker Thread at the top left menu.

Profiling Android UI Performance with systrace

Android supports 10k+ different phones and is generalized to support software rendering: the framework architecture and need to generalize across many hardware targets unfortunately means you get less for free relative to iOS. But sometimes, there are things you can improve -- and many times it's not native code's fault at all!

The first step for debugging this jank is to answer the fundamental question of where your time is being spent during each 16ms frame. For that, we'll be using a standard Android profiling tool called systrace.

systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.

1. Collecting a trace

First, connect a device that exhibits the stuttering you want to investigate to your computer via USB and get it to the point right before the navigation/animation you want to profile. Run systrace as follows:

$ <path_to_android_sdk>/platform-tools/systrace/systrace.py --time=10 -o trace.html sched gfx view -a <your_package_name>

A quick breakdown of this command:

  • time is the length of time the trace will be collected in seconds
  • sched, gfx, and view are the android SDK tags (collections of markers) we care about: sched gives you information about what's running on each core of your phone, gfx gives you graphics info such as frame boundaries, and view gives you information about measure, layout, and draw passes
  • -a <your_package_name> enables app-specific markers, specifically the ones built into the React Native framework. your_package_name can be found in the AndroidManifest.xml of your app and looks like com.example.app

Once the trace starts collecting, perform the animation or interaction you care about. At the end of the trace, systrace will give you a link to the trace which you can open in your browser.

2. Reading the trace

After opening the trace in your browser (preferably Chrome), you should see something like this:

Example

HINT: Use the WASD keys to strafe and zoom

If your trace .html file isn't opening correctly, check your browser console for the following:

ObjectObserveError

Since Object.observe was deprecated in recent browsers, you may have to open the file from the Google Chrome Tracing tool. You can do so by:

  • Opening tab in chrome chrome://tracing
  • Selecting load
  • Selecting the html file generated from the previous command.

Enable VSync highlighting

Check this checkbox at the top right of the screen to highlight the 16ms frame boundaries:

Enable VSync Highlighting

You should see zebra stripes as in the screenshot above. If you don't, try profiling on a different device: Samsung has been known to have issues displaying vsyncs while the Nexus series is generally pretty reliable.

3. Find your process

Scroll until you see (part of) the name of your package. In this case, I was profiling com.facebook.adsmanager, which shows up as book.adsmanager because of silly thread name limits in the kernel.

On the left side, you'll see a set of threads which correspond to the timeline rows on the right. There are a few threads we care about for our purposes: the UI thread (which has your package name or the name UI Thread), mqt_js, and mqt_native_modules. If you're running on Android 5+, we also care about the Render Thread.

  • UI Thread. This is where standard android measure/layout/draw happens. The thread name on the right will be your package name (in my case book.adsmanager) or UI Thread. The events that you see on this thread should look something like this and have to do with Choreographer, traversals, and DispatchUI:

    UI Thread Example

  • JS Thread. This is where JavaScript is executed. The thread name will be either mqt_js or <...> depending on how cooperative the kernel on your device is being. To identify it if it doesn't have a name, look for things like JSCall, Bridge.executeJSCall, etc:

    JS Thread Example

  • Native Modules Thread. This is where native module calls (e.g. the UIManager) are executed. The thread name will be either mqt_native_modules or <...>. To identify it in the latter case, look for things like NativeCall, callJavaModuleMethod, and onBatchComplete:

    Native Modules Thread Example

  • Bonus: Render Thread. If you're using Android L (5.0) and up, you will also have a render thread in your application. This thread generates the actual OpenGL commands used to draw your UI. The thread name will be either RenderThread or <...>. To identify it in the latter case, look for things like DrawFrame and queueBuffer:

    Render Thread Example

Identifying a culprit

A smooth animation should look something like the following:

Smooth Animation

Each change in color is a frame -- remember that in order to display a frame, all our UI work needs to be done by the end of that 16ms period. Notice that no thread is working close to the frame boundary. An application rendering like this is rendering at 60 FPS.

If you noticed chop, however, you might see something like this:

Choppy Animation from JS

Notice that the JS thread is executing almost all the time, and across frame boundaries! This app is not rendering at 60 FPS. In this case, the problem lies in JS.

You might also see something like this:

Choppy Animation from UI

In this case, the UI and render threads are the ones that have work crossing frame boundaries. The UI that we're trying to render on each frame is requiring too much work to be done. In this case, the problem lies in the native views being rendered.

At this point, you'll have some very helpful information to inform your next steps.

Resolving JavaScript issues

If you identified a JS problem, look for clues in the specific JS that you're executing. In the scenario above, we see RCTEventEmitter being called multiple times per frame. Here's a zoom-in of the JS thread from the trace above:

Too much JS

This doesn't seem right. Why is it being called so often? Are they actually different events? The answers to these questions will probably depend on your product code. And many times, you'll want to look into shouldComponentUpdate.

Resolving native UI Issues

If you identified a native UI problem, there are usually two scenarios:

  1. the UI you're trying to draw each frame involves too much work on the GPU, or
  2. You're constructing new UI during the animation/interaction (e.g. loading in new content during a scroll).

Too much GPU work

In the first scenario, you'll see a trace that has the UI thread and/or Render Thread looking like this:

Overloaded GPU

Notice the long amount of time spent in DrawFrame that crosses frame boundaries. This is time spent waiting for the GPU to drain its command buffer from the previous frame.

To mitigate this, you should:

  • investigate using renderToHardwareTextureAndroid for complex, static content that is being animated/transformed (e.g. the Navigator slide/alpha animations)
  • make sure that you are not using needsOffscreenAlphaCompositing, which is disabled by default, as it greatly increases the per-frame load on the GPU in most cases.

If these don't help and you want to dig deeper into what the GPU is actually doing, you can check out Tracer for OpenGL ES.

Creating new views on the UI thread

In the second scenario, you'll see something more like this:

Creating Views

Notice that first the JS thread thinks for a bit, then you see some work done on the native modules thread, followed by an expensive traversal on the UI thread.

There isn't a quick way to mitigate this unless you're able to postpone creating new UI until after the interaction, or you are able to simplify the UI you're creating. The react native team is working on an infrastructure level solution for this that will allow new UI to be created and configured off the main thread, allowing the interaction to continue smoothly.

Edit this page
Last updated on
- + diff --git a/docs/0.60/progressbarandroid.html b/docs/0.60/progressbarandroid.html index 37d58196c3d..ecd4caee69b 100644 --- a/docs/0.60/progressbarandroid.html +++ b/docs/0.60/progressbarandroid.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'space-evenly',
padding: 10
}
});

Reference

Props

Inherits View Props.

animating

Whether to show the ProgressBar (true, the default) or hide it (false).

TypeRequired
boolNo

color

Color of the progress bar.

TypeRequired
colorNo

indeterminate

If the progress bar will show indeterminate progress. Note that this can only be false if styleAttr is Horizontal, and requires a progress value.

TypeRequired
indeterminateTypeNo

progress

The progress value (between 0 and 1).

TypeRequired
numberNo

styleAttr

Style of the ProgressBar. One of:

TypeRequired
enum('Horizontal', 'Normal', 'Small', 'Large', 'Inverse', 'SmallInverse', 'LargeInverse')No

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/progressbarandroid/index.html b/docs/0.60/progressbarandroid/index.html index 37d58196c3d..ecd4caee69b 100644 --- a/docs/0.60/progressbarandroid/index.html +++ b/docs/0.60/progressbarandroid/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'space-evenly',
padding: 10
}
});

Reference

Props

Inherits View Props.

animating

Whether to show the ProgressBar (true, the default) or hide it (false).

TypeRequired
boolNo

color

Color of the progress bar.

TypeRequired
colorNo

indeterminate

If the progress bar will show indeterminate progress. Note that this can only be false if styleAttr is Horizontal, and requires a progress value.

TypeRequired
indeterminateTypeNo

progress

The progress value (between 0 and 1).

TypeRequired
numberNo

styleAttr

Style of the ProgressBar. One of:

TypeRequired
enum('Horizontal', 'Normal', 'Small', 'Large', 'Inverse', 'SmallInverse', 'LargeInverse')No

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/progressviewios.html b/docs/0.60/progressviewios.html index c2a2776feb6..751155bc874 100644 --- a/docs/0.60/progressviewios.html +++ b/docs/0.60/progressviewios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

ProgressViewIOS

Uses ProgressViewIOS to render a UIProgressView on iOS.

Reference

Props

Inherits View Props.

progress

The progress value (between 0 and 1).

TypeRequired
numberNo

progressImage

A stretchable image to display as the progress bar.

TypeRequired
Image.propTypes.sourceNo

progressTintColor

The tint color of the progress bar itself.

TypeRequired
stringNo

progressViewStyle

The progress bar style.

TypeRequired
enum('default', 'bar')No

trackImage

A stretchable image to display behind the progress bar.

TypeRequired
Image.propTypes.sourceNo

trackTintColor

The tint color of the progress bar track.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/progressviewios/index.html b/docs/0.60/progressviewios/index.html index c2a2776feb6..751155bc874 100644 --- a/docs/0.60/progressviewios/index.html +++ b/docs/0.60/progressviewios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

ProgressViewIOS

Uses ProgressViewIOS to render a UIProgressView on iOS.

Reference

Props

Inherits View Props.

progress

The progress value (between 0 and 1).

TypeRequired
numberNo

progressImage

A stretchable image to display as the progress bar.

TypeRequired
Image.propTypes.sourceNo

progressTintColor

The tint color of the progress bar itself.

TypeRequired
stringNo

progressViewStyle

The progress bar style.

TypeRequired
enum('default', 'bar')No

trackImage

A stretchable image to display behind the progress bar.

TypeRequired
Image.propTypes.sourceNo

trackTintColor

The tint color of the progress bar track.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/props.html b/docs/0.60/props.html index a54611659f7..c6166162df7 100644 --- a/docs/0.60/props.html +++ b/docs/0.60/props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Props

Most components can be customized when they are created, with different parameters. These creation parameters are called props, short for properties.

For example, one basic React Native component is the Image. When you create an image, you can use a prop named source to control what image it shows.

Notice the braces surrounding {pic} - these embed the variable pic into JSX. You can put any JavaScript expression inside braces in JSX.

Your own components can also use props. This lets you make a single component that is used in many different places in your app, with slightly different properties in each place by referring to this.props in your render function. Here's an example:

Using name as a prop lets us customize the Greeting component, so we can reuse that component for each of our greetings. This example also uses the Greeting component in JSX, similar to the Core Components. The power to do this is what makes React so cool - if you find yourself wishing that you had a different set of UI primitives to work with, you can invent new ones.

The other new thing going on here is the View component. A View is useful as a container for other components, to help control style and layout.

With props and the basic Text, Image, and View components, you can build a wide variety of static screens. To learn how to make your app change over time, you need to learn about State.

Edit this page
Last updated on
- + diff --git a/docs/0.60/props/index.html b/docs/0.60/props/index.html index a54611659f7..c6166162df7 100644 --- a/docs/0.60/props/index.html +++ b/docs/0.60/props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Props

Most components can be customized when they are created, with different parameters. These creation parameters are called props, short for properties.

For example, one basic React Native component is the Image. When you create an image, you can use a prop named source to control what image it shows.

Notice the braces surrounding {pic} - these embed the variable pic into JSX. You can put any JavaScript expression inside braces in JSX.

Your own components can also use props. This lets you make a single component that is used in many different places in your app, with slightly different properties in each place by referring to this.props in your render function. Here's an example:

Using name as a prop lets us customize the Greeting component, so we can reuse that component for each of our greetings. This example also uses the Greeting component in JSX, similar to the Core Components. The power to do this is what makes React so cool - if you find yourself wishing that you had a different set of UI primitives to work with, you can invent new ones.

The other new thing going on here is the View component. A View is useful as a container for other components, to help control style and layout.

With props and the basic Text, Image, and View components, you can build a wide variety of static screens. To learn how to make your app change over time, you need to learn about State.

Edit this page
Last updated on
- + diff --git a/docs/0.60/publishing-forks.html b/docs/0.60/publishing-forks.html index 9b49db5c0c6..43e2e2d083b 100644 --- a/docs/0.60/publishing-forks.html +++ b/docs/0.60/publishing-forks.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Publish your own version of react native

TL;DR

There is a docker image that helps you build the required Android sources without installing any additional tooling (other than Docker, which can be committed to a git branch as a fully functional React Native fork release.

Run this from a fork of the React Native repo.

git checkout -d release/my-react-native-release
docker run --rm --name rn-build -v $PWD:/pwd -w /pwd reactnativecommunity/react-native-android /bin/sh -c "./gradlew installArchives"
git add android --force
git commit -a -m 'my react native forked release'
git push

Install it in your app project package.json.

"dependencies": {
...
"react-native": "myName/react-native#release/my-react-native-release"
}

Rationale

The recommended approach to working with React Native is to always update to the latest version. No support is provided on older versions and if you run into issues the contributors will always ask you to upgrade to the latest version before even looking at your particular issue. Sometimes, though, you are temporarily stuck on an older React Native version, but you require some changes from newer versions urgently (bugfixes) without having to do a full upgrade right now. This situation should be short lived by definition and once you have the time, the real solution is to upgrade to the latest version.

With this goal of a shortlived fork of React Native in mind, you can publish your own version of React Native. The facebook/react-native repository contains all the dependencies required to be used directly as a git dependency, except for the Android React Native library binary (.aar).

Building

This binary needs to become available in your project's node_modules/react-native/android folder or directly in your gradle dependency of your Android app. You can achieve this in one of two ways: Git dependency branch, Android binary dependency through Maven.

To build the .aar React Native library, you can follow the steps to build from source first to install all required tooling. Then to build the actual library, you can run the following in the root of your react-native checkout:

./gradlew :ReactAndroid:installArchives --no-daemon

If you don't want to install the required toolchain for building from source, you can use a prebuilt docker image to create a react native binary;

docker run --rm --name rn-build -v $PWD:/pwd -w /pwd reactnativecommunity/react-native-android /bin/sh -c "./gradlew installArchives"

If you haven't used the Android NDK before or if you have a NDK version not exactly matching the required version for building React Native, this is the recommended approach.

The resulting binary can be made available to app projects in one of the two ways described below.

Publishing to Maven/Nexus

Upload the binaries from the android folder to maven and point your Android app project gradle dependency for React Native to your Maven/Nexus dependency.

Publishing to a git fork dependency

Instead of uploading to Maven/Nexus, you can add the binaries built in the previous steps to git, by changing the .gitignore and committing the binaries to your forked branch. This allows you to make your fork into a functioning git dependency for React Native app projects.

If you have changes that you want to actually merge to React Native, make them on another branch first and open a PR. To start making your dependency branch, make sure you are on a 'release/my-forked-release' branch, then merge any commits that you need from yourself or others into this branch. This release branch should never be merged into any other branch.

# create .aar, then:
git add android --force
git commit -m 'my release commit'
git push

Now you can use this branch as a git dependency in your app project, by pointing your package.json dependency to this branch:

"dependencies": {
...
"react-native": "my-name/react-native#release/my-forked-release,
...
}

No other modifications to your dependencies should be necessary for your native changes to be included in your project.

Edit this page
Last updated on
- + diff --git a/docs/0.60/publishing-forks/index.html b/docs/0.60/publishing-forks/index.html index 9b49db5c0c6..43e2e2d083b 100644 --- a/docs/0.60/publishing-forks/index.html +++ b/docs/0.60/publishing-forks/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Publish your own version of react native

TL;DR

There is a docker image that helps you build the required Android sources without installing any additional tooling (other than Docker, which can be committed to a git branch as a fully functional React Native fork release.

Run this from a fork of the React Native repo.

git checkout -d release/my-react-native-release
docker run --rm --name rn-build -v $PWD:/pwd -w /pwd reactnativecommunity/react-native-android /bin/sh -c "./gradlew installArchives"
git add android --force
git commit -a -m 'my react native forked release'
git push

Install it in your app project package.json.

"dependencies": {
...
"react-native": "myName/react-native#release/my-react-native-release"
}

Rationale

The recommended approach to working with React Native is to always update to the latest version. No support is provided on older versions and if you run into issues the contributors will always ask you to upgrade to the latest version before even looking at your particular issue. Sometimes, though, you are temporarily stuck on an older React Native version, but you require some changes from newer versions urgently (bugfixes) without having to do a full upgrade right now. This situation should be short lived by definition and once you have the time, the real solution is to upgrade to the latest version.

With this goal of a shortlived fork of React Native in mind, you can publish your own version of React Native. The facebook/react-native repository contains all the dependencies required to be used directly as a git dependency, except for the Android React Native library binary (.aar).

Building

This binary needs to become available in your project's node_modules/react-native/android folder or directly in your gradle dependency of your Android app. You can achieve this in one of two ways: Git dependency branch, Android binary dependency through Maven.

To build the .aar React Native library, you can follow the steps to build from source first to install all required tooling. Then to build the actual library, you can run the following in the root of your react-native checkout:

./gradlew :ReactAndroid:installArchives --no-daemon

If you don't want to install the required toolchain for building from source, you can use a prebuilt docker image to create a react native binary;

docker run --rm --name rn-build -v $PWD:/pwd -w /pwd reactnativecommunity/react-native-android /bin/sh -c "./gradlew installArchives"

If you haven't used the Android NDK before or if you have a NDK version not exactly matching the required version for building React Native, this is the recommended approach.

The resulting binary can be made available to app projects in one of the two ways described below.

Publishing to Maven/Nexus

Upload the binaries from the android folder to maven and point your Android app project gradle dependency for React Native to your Maven/Nexus dependency.

Publishing to a git fork dependency

Instead of uploading to Maven/Nexus, you can add the binaries built in the previous steps to git, by changing the .gitignore and committing the binaries to your forked branch. This allows you to make your fork into a functioning git dependency for React Native app projects.

If you have changes that you want to actually merge to React Native, make them on another branch first and open a PR. To start making your dependency branch, make sure you are on a 'release/my-forked-release' branch, then merge any commits that you need from yourself or others into this branch. This release branch should never be merged into any other branch.

# create .aar, then:
git add android --force
git commit -m 'my release commit'
git push

Now you can use this branch as a git dependency in your app project, by pointing your package.json dependency to this branch:

"dependencies": {
...
"react-native": "my-name/react-native#release/my-forked-release,
...
}

No other modifications to your dependencies should be necessary for your native changes to be included in your project.

Edit this page
Last updated on
- + diff --git a/docs/0.60/publishing-to-app-store.html b/docs/0.60/publishing-to-app-store.html index 6502a6d1a0e..62ed2912f89 100644 --- a/docs/0.60/publishing-to-app-store.html +++ b/docs/0.60/publishing-to-app-store.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Publishing to Apple App Store

The publishing process is the same as any other native iOS app, with some additional considerations to take into account.

If you are using Expo then read the Expo Guide for Building Standalone Apps.

1. Enable App Transport Security

App Transport Security is a security feature introduced in iOS 9 that rejects all HTTP requests that are not sent over HTTPS. This can result in HTTP traffic being blocked, including the developer React Native server. ATS is disabled for localhost by default in React Native projects in order to make development easier.

You should re-enable ATS prior to building your app for production by removing the localhost entry from the NSExceptionDomains dictionary and setting NSAllowsArbitraryLoads to false in your Info.plist file in the ios/ folder. You can also re-enable ATS from within Xcode by opening your target properties under the Info pane and editing the App Transport Security Settings entry.

If your application needs to access HTTP resources on production, see this post to learn how to configure ATS on your project.

2. Configure release scheme

Building an app for distribution in the App Store requires using the Release scheme in Xcode. Apps built for Release will automatically disable the in-app Developer menu, which will prevent your users from inadvertently accessing the menu in production. It will also bundle the JavaScript locally, so you can put the app on a device and test whilst not connected to the computer.

To configure your app to be built using the Release scheme, go to Product → Scheme → Edit Scheme. Select the Run tab in the sidebar, then set the Build Configuration dropdown to Release.

Pro Tips

As your App Bundle grows in size, you may start to see a blank screen flash between your splash screen and the display of your root application view. If this is the case, you can add the following code to AppDelegate.m in order to keep your splash screen displayed during the transition.

// Place this code after "[self.window makeKeyAndVisible]" and before "return YES;"
UIStoryboard *sb = [UIStoryboard storyboardWithName:@"LaunchScreen" bundle:nil];
UIViewController *vc = [sb instantiateInitialViewController];
rootView.loadingView = vc.view;

The static bundle is built every time you target a physical device, even in Debug. If you want to save time, turn off bundle generation in Debug by adding the following to your shell script in the Xcode Build Phase Bundle React Native code and images:

if [ "${CONFIGURATION}" == "Debug" ]; then
export SKIP_BUNDLING=true
fi

3. Build app for release

You can now build your app for release by tapping ⌘B or selecting Product → Build from the menu bar. Once built for release, you'll be able to distribute the app to beta testers and submit the app to the App Store.

You can also use the React Native CLI to perform this operation using the option --configuration with the value Release (e.g. npx react-native run-ios --configuration Release).

Edit this page
Last updated on
- + diff --git a/docs/0.60/publishing-to-app-store/index.html b/docs/0.60/publishing-to-app-store/index.html index 6502a6d1a0e..62ed2912f89 100644 --- a/docs/0.60/publishing-to-app-store/index.html +++ b/docs/0.60/publishing-to-app-store/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Publishing to Apple App Store

The publishing process is the same as any other native iOS app, with some additional considerations to take into account.

If you are using Expo then read the Expo Guide for Building Standalone Apps.

1. Enable App Transport Security

App Transport Security is a security feature introduced in iOS 9 that rejects all HTTP requests that are not sent over HTTPS. This can result in HTTP traffic being blocked, including the developer React Native server. ATS is disabled for localhost by default in React Native projects in order to make development easier.

You should re-enable ATS prior to building your app for production by removing the localhost entry from the NSExceptionDomains dictionary and setting NSAllowsArbitraryLoads to false in your Info.plist file in the ios/ folder. You can also re-enable ATS from within Xcode by opening your target properties under the Info pane and editing the App Transport Security Settings entry.

If your application needs to access HTTP resources on production, see this post to learn how to configure ATS on your project.

2. Configure release scheme

Building an app for distribution in the App Store requires using the Release scheme in Xcode. Apps built for Release will automatically disable the in-app Developer menu, which will prevent your users from inadvertently accessing the menu in production. It will also bundle the JavaScript locally, so you can put the app on a device and test whilst not connected to the computer.

To configure your app to be built using the Release scheme, go to Product → Scheme → Edit Scheme. Select the Run tab in the sidebar, then set the Build Configuration dropdown to Release.

Pro Tips

As your App Bundle grows in size, you may start to see a blank screen flash between your splash screen and the display of your root application view. If this is the case, you can add the following code to AppDelegate.m in order to keep your splash screen displayed during the transition.

// Place this code after "[self.window makeKeyAndVisible]" and before "return YES;"
UIStoryboard *sb = [UIStoryboard storyboardWithName:@"LaunchScreen" bundle:nil];
UIViewController *vc = [sb instantiateInitialViewController];
rootView.loadingView = vc.view;

The static bundle is built every time you target a physical device, even in Debug. If you want to save time, turn off bundle generation in Debug by adding the following to your shell script in the Xcode Build Phase Bundle React Native code and images:

if [ "${CONFIGURATION}" == "Debug" ]; then
export SKIP_BUNDLING=true
fi

3. Build app for release

You can now build your app for release by tapping ⌘B or selecting Product → Build from the menu bar. Once built for release, you'll be able to distribute the app to beta testers and submit the app to the App Store.

You can also use the React Native CLI to perform this operation using the option --configuration with the value Release (e.g. npx react-native run-ios --configuration Release).

Edit this page
Last updated on
- + diff --git a/docs/0.60/pushnotificationios.html b/docs/0.60/pushnotificationios.html index ac9433373c8..82cfe44d5fd 100644 --- a/docs/0.60/pushnotificationios.html +++ b/docs/0.60/pushnotificationios.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
//Called when a notification is delivered to a foreground app.
-(void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler
{
completionHandler(UNAuthorizationOptionSound | UNAuthorizationOptionAlert | UNAuthorizationOptionBadge);
}

Then enable Background Modes/Remote notifications to be able to use remote notifications properly. The easiest way to do this is via the project settings. Navigate to Targets -> Your App -> Capabilities -> Background Modes and check Remote notifications. This will automatically enable the required settings.

Reference

Methods

presentLocalNotification()

PushNotificationIOS.presentLocalNotification(details);

Schedules the localNotification for immediate presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

scheduleLocalNotification()

PushNotificationIOS.scheduleLocalNotification(details);

Schedules the localNotification for future presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

cancelAllLocalNotifications()

PushNotificationIOS.cancelAllLocalNotifications();

Cancels all scheduled localNotifications

removeAllDeliveredNotifications()

PushNotificationIOS.removeAllDeliveredNotifications();

Remove all delivered notifications from Notification Center

getDeliveredNotifications()

PushNotificationIOS.getDeliveredNotifications(callback);

Provides you with a list of the app’s notifications that are still displayed in Notification Center

Parameters:

NameTypeRequiredDescription
callbackfunctionYesFunction which receive an array of delivered notifications.

A delivered notification is an object containing:

removeDeliveredNotifications()

PushNotificationIOS.removeDeliveredNotifications(identifiers);

Removes the specified notifications from Notification Center

Parameters:

NameTypeRequiredDescription
identifiersarrayYesArray of notification identifiers.

setApplicationIconBadgeNumber()

PushNotificationIOS.setApplicationIconBadgeNumber(number);

Sets the badge number for the app icon on the home screen

Parameters:

NameTypeRequiredDescription
numbernumberYesBadge number for the app icon.

getApplicationIconBadgeNumber()

PushNotificationIOS.getApplicationIconBadgeNumber(callback);

Gets the current badge number for the app icon on the home screen

Parameters:

NameTypeRequiredDescription
callbackfunctionYesA function that will be passed the current badge number.

cancelLocalNotifications()

PushNotificationIOS.cancelLocalNotifications(userInfo);

Cancel local notifications.

Optionally restricts the set of canceled notifications to those notifications whose userInfo fields match the corresponding fields in the userInfo argument.

Parameters:

NameTypeRequiredDescription
userInfoobjectNo

getScheduledLocalNotifications()

PushNotificationIOS.getScheduledLocalNotifications(callback);

Gets the local notifications that are currently scheduled.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesA function that will be passed an array of objects describing local notifications.

addEventListener()

PushNotificationIOS.addEventListener(type, handler);

Attaches a listener to remote or local notification events while the app is running in the foreground or the background.

Parameters:

NameTypeRequiredDescription
typestringYesEvent type.
handlerfunctionYesListener.

Valid events are:

removeEventListener()

PushNotificationIOS.removeEventListener(type, handler);

Removes the event listener. Do this in componentWillUnmount to prevent memory leaks

Parameters:

NameTypeRequiredDescription
typestringYesEvent type.
handlerfunctionYesListener.

requestPermissions()

PushNotificationIOS.requestPermissions([permissions]);

Requests notification permissions from iOS, prompting the user's dialog box. By default, it will request all notification permissions, but a subset of these can be requested by passing a map of requested permissions. The following permissions are supported:

If a map is provided to the method, only the permissions with truthy values will be requested.

This method returns a promise that will resolve when the user accepts, rejects, or if the permissions were previously rejected. The promise resolves to the current state of the permission.

Parameters:

NameTypeRequiredDescription
permissionsarrayNoalert, badge, or sound

abandonPermissions()

PushNotificationIOS.abandonPermissions();

Unregister for all remote notifications received via Apple Push Notification service.

You should call this method in rare circumstances only, such as when a new version of the app removes support for all types of remote notifications. Users can temporarily prevent apps from receiving remote notifications through the Notifications section of the Settings app. Apps unregistered through this method can always re-register.

checkPermissions()

PushNotificationIOS.checkPermissions(callback);

See what push permissions are currently enabled.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesSee below.

callback will be invoked with a permissions object:

getInitialNotification()

PushNotificationIOS.getInitialNotification();

This method returns a promise. If the app was launched by a push notification, this promise resolves to an object of type PushNotificationIOS. Otherwise, it resolves to null.

constructor()

constructor(nativeNotif);

You will never need to instantiate PushNotificationIOS yourself. Listening to the notification event and invoking getInitialNotification is sufficient.

finish()

finish(fetchResult);

This method is available for remote notifications that have been received via: application:didReceiveRemoteNotification:fetchCompletionHandler: https://developer.apple.com/library/ios/documentation/UIKit/Reference/UIApplicationDelegate_Protocol/#//apple_ref/occ/intfm/UIApplicationDelegate/application:didReceiveRemoteNotification:fetchCompletionHandler:

Call this to execute when the remote notification handling is complete. When calling this block, pass in the fetch result value that best describes the results of your operation. You must call this handler and should do so as soon as possible. For a list of possible values, see PushNotificationIOS.FetchResult.

If you do not call this method your background remote notifications could be throttled, to read more about it see the above documentation link.

getMessage()

getMessage();

An alias for getAlert to get the notification's main message string

getSound()

getSound();

Gets the sound string from the aps object

getCategory()

getCategory();

Gets the category string from the aps object

getAlert()

getAlert();

Gets the notification's main message from the aps object

getContentAvailable()

getContentAvailable();

Gets the content-available number from the aps object

getBadgeCount()

getBadgeCount();

Gets the badge count number from the aps object

getData()

getData();

Gets the data object on the notification

getThreadID()

getThreadID();

Gets the thread ID on the notification

Edit this page
Last updated on
- + diff --git a/docs/0.60/pushnotificationios/index.html b/docs/0.60/pushnotificationios/index.html index ac9433373c8..82cfe44d5fd 100644 --- a/docs/0.60/pushnotificationios/index.html +++ b/docs/0.60/pushnotificationios/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
//Called when a notification is delivered to a foreground app.
-(void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler
{
completionHandler(UNAuthorizationOptionSound | UNAuthorizationOptionAlert | UNAuthorizationOptionBadge);
}

Then enable Background Modes/Remote notifications to be able to use remote notifications properly. The easiest way to do this is via the project settings. Navigate to Targets -> Your App -> Capabilities -> Background Modes and check Remote notifications. This will automatically enable the required settings.

Reference

Methods

presentLocalNotification()

PushNotificationIOS.presentLocalNotification(details);

Schedules the localNotification for immediate presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

scheduleLocalNotification()

PushNotificationIOS.scheduleLocalNotification(details);

Schedules the localNotification for future presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

cancelAllLocalNotifications()

PushNotificationIOS.cancelAllLocalNotifications();

Cancels all scheduled localNotifications

removeAllDeliveredNotifications()

PushNotificationIOS.removeAllDeliveredNotifications();

Remove all delivered notifications from Notification Center

getDeliveredNotifications()

PushNotificationIOS.getDeliveredNotifications(callback);

Provides you with a list of the app’s notifications that are still displayed in Notification Center

Parameters:

NameTypeRequiredDescription
callbackfunctionYesFunction which receive an array of delivered notifications.

A delivered notification is an object containing:

removeDeliveredNotifications()

PushNotificationIOS.removeDeliveredNotifications(identifiers);

Removes the specified notifications from Notification Center

Parameters:

NameTypeRequiredDescription
identifiersarrayYesArray of notification identifiers.

setApplicationIconBadgeNumber()

PushNotificationIOS.setApplicationIconBadgeNumber(number);

Sets the badge number for the app icon on the home screen

Parameters:

NameTypeRequiredDescription
numbernumberYesBadge number for the app icon.

getApplicationIconBadgeNumber()

PushNotificationIOS.getApplicationIconBadgeNumber(callback);

Gets the current badge number for the app icon on the home screen

Parameters:

NameTypeRequiredDescription
callbackfunctionYesA function that will be passed the current badge number.

cancelLocalNotifications()

PushNotificationIOS.cancelLocalNotifications(userInfo);

Cancel local notifications.

Optionally restricts the set of canceled notifications to those notifications whose userInfo fields match the corresponding fields in the userInfo argument.

Parameters:

NameTypeRequiredDescription
userInfoobjectNo

getScheduledLocalNotifications()

PushNotificationIOS.getScheduledLocalNotifications(callback);

Gets the local notifications that are currently scheduled.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesA function that will be passed an array of objects describing local notifications.

addEventListener()

PushNotificationIOS.addEventListener(type, handler);

Attaches a listener to remote or local notification events while the app is running in the foreground or the background.

Parameters:

NameTypeRequiredDescription
typestringYesEvent type.
handlerfunctionYesListener.

Valid events are:

removeEventListener()

PushNotificationIOS.removeEventListener(type, handler);

Removes the event listener. Do this in componentWillUnmount to prevent memory leaks

Parameters:

NameTypeRequiredDescription
typestringYesEvent type.
handlerfunctionYesListener.

requestPermissions()

PushNotificationIOS.requestPermissions([permissions]);

Requests notification permissions from iOS, prompting the user's dialog box. By default, it will request all notification permissions, but a subset of these can be requested by passing a map of requested permissions. The following permissions are supported:

If a map is provided to the method, only the permissions with truthy values will be requested.

This method returns a promise that will resolve when the user accepts, rejects, or if the permissions were previously rejected. The promise resolves to the current state of the permission.

Parameters:

NameTypeRequiredDescription
permissionsarrayNoalert, badge, or sound

abandonPermissions()

PushNotificationIOS.abandonPermissions();

Unregister for all remote notifications received via Apple Push Notification service.

You should call this method in rare circumstances only, such as when a new version of the app removes support for all types of remote notifications. Users can temporarily prevent apps from receiving remote notifications through the Notifications section of the Settings app. Apps unregistered through this method can always re-register.

checkPermissions()

PushNotificationIOS.checkPermissions(callback);

See what push permissions are currently enabled.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesSee below.

callback will be invoked with a permissions object:

getInitialNotification()

PushNotificationIOS.getInitialNotification();

This method returns a promise. If the app was launched by a push notification, this promise resolves to an object of type PushNotificationIOS. Otherwise, it resolves to null.

constructor()

constructor(nativeNotif);

You will never need to instantiate PushNotificationIOS yourself. Listening to the notification event and invoking getInitialNotification is sufficient.

finish()

finish(fetchResult);

This method is available for remote notifications that have been received via: application:didReceiveRemoteNotification:fetchCompletionHandler: https://developer.apple.com/library/ios/documentation/UIKit/Reference/UIApplicationDelegate_Protocol/#//apple_ref/occ/intfm/UIApplicationDelegate/application:didReceiveRemoteNotification:fetchCompletionHandler:

Call this to execute when the remote notification handling is complete. When calling this block, pass in the fetch result value that best describes the results of your operation. You must call this handler and should do so as soon as possible. For a list of possible values, see PushNotificationIOS.FetchResult.

If you do not call this method your background remote notifications could be throttled, to read more about it see the above documentation link.

getMessage()

getMessage();

An alias for getAlert to get the notification's main message string

getSound()

getSound();

Gets the sound string from the aps object

getCategory()

getCategory();

Gets the category string from the aps object

getAlert()

getAlert();

Gets the notification's main message from the aps object

getContentAvailable()

getContentAvailable();

Gets the content-available number from the aps object

getBadgeCount()

getBadgeCount();

Gets the badge count number from the aps object

getData()

getData();

Gets the data object on the notification

getThreadID()

getThreadID();

Gets the thread ID on the notification

Edit this page
Last updated on
- + diff --git a/docs/0.60/ram-bundles-inline-requires.html b/docs/0.60/ram-bundles-inline-requires.html index 498db421db5..34c55895fff 100644 --- a/docs/0.60/ram-bundles-inline-requires.html +++ b/docs/0.60/ram-bundles-inline-requires.html @@ -19,7 +19,7 @@ - + @@ -45,7 +45,7 @@
module.exports = config;

The preloadedModules entry in the config indicates which modules should be marked as preloaded when building a RAM bundle. When the bundle is loaded, those modules are immediately loaded, before any requires have even executed. The blacklist entry indicates that those modules should not be required inline. Because they are preloaded, there is no performance benefit from using an inline require. In fact the javascript spends extra time resolving the inline require every time the imports are referenced.

Test and Measure Improvements

You should now be ready to build your app using the RAM format and inline requires. Make sure you measure the before and after startup times.

Edit this page
Last updated on
- + diff --git a/docs/0.60/ram-bundles-inline-requires/index.html b/docs/0.60/ram-bundles-inline-requires/index.html index 498db421db5..34c55895fff 100644 --- a/docs/0.60/ram-bundles-inline-requires/index.html +++ b/docs/0.60/ram-bundles-inline-requires/index.html @@ -19,7 +19,7 @@ - + @@ -45,7 +45,7 @@
module.exports = config;

The preloadedModules entry in the config indicates which modules should be marked as preloaded when building a RAM bundle. When the bundle is loaded, those modules are immediately loaded, before any requires have even executed. The blacklist entry indicates that those modules should not be required inline. Because they are preloaded, there is no performance benefit from using an inline require. In fact the javascript spends extra time resolving the inline require every time the imports are referenced.

Test and Measure Improvements

You should now be ready to build your app using the RAM format and inline requires. Make sure you measure the before and after startup times.

Edit this page
Last updated on
- + diff --git a/docs/0.60/react-node.html b/docs/0.60/react-node.html index a01b779ce50..a7b0509e304 100644 --- a/docs/0.60/react-node.html +++ b/docs/0.60/react-node.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

React Node Object Type

A React Node is one of the following types:

  • Boolean (which is ignored)
  • null or undefined (which is ignored)
  • Number
  • String
  • A React element (result of JSX)
  • An array of any of the above, possibly a nested one
Edit this page
Last updated on
- + diff --git a/docs/0.60/react-node/index.html b/docs/0.60/react-node/index.html index a01b779ce50..a7b0509e304 100644 --- a/docs/0.60/react-node/index.html +++ b/docs/0.60/react-node/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

React Node Object Type

A React Node is one of the following types:

  • Boolean (which is ignored)
  • null or undefined (which is ignored)
  • Number
  • String
  • A React element (result of JSX)
  • An array of any of the above, possibly a nested one
Edit this page
Last updated on
- + diff --git a/docs/0.60/refreshcontrol.html b/docs/0.60/refreshcontrol.html index 2c500e79ce0..4cfc3189714 100644 --- a/docs/0.60/refreshcontrol.html +++ b/docs/0.60/refreshcontrol.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

RefreshControl

This component is used inside a ScrollView or ListView to add pull to refresh functionality. When the ScrollView is at scrollY: 0, swiping down triggers an onRefresh event.

Example

Note: refreshing is a controlled prop, this is why it needs to be set to true in the onRefresh function otherwise the refresh indicator will stop immediately.

Reference

Props

Inherits View Props.

refreshing

Whether the view should be indicating an active refresh.

TypeRequired
boolYes

onRefresh

Called when the view starts refreshing.

TypeRequired
functionNo

colors

The colors (at least one) that will be used to draw the refresh indicator.

TypeRequiredPlatform
array of colorNoAndroid

enabled

Whether the pull to refresh functionality is enabled.

TypeRequiredPlatform
boolNoAndroid

progressBackgroundColor

The background color of the refresh indicator.

TypeRequiredPlatform
colorNoAndroid

progressViewOffset

Progress view top offset

TypeRequiredPlatform
numberNoAndroid

size

Size of the refresh indicator, see RefreshControl.SIZE.

TypeRequiredPlatform
enum(RefreshLayoutConsts.SIZE.DEFAULT, RefreshLayoutConsts.SIZE.LARGE)NoAndroid

tintColor

The color of the refresh indicator.

TypeRequiredPlatform
colorNoiOS

title

The title displayed under the refresh indicator.

TypeRequiredPlatform
stringNoiOS

titleColor

Title color.

TypeRequiredPlatform
colorNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.60/refreshcontrol/index.html b/docs/0.60/refreshcontrol/index.html index 2c500e79ce0..4cfc3189714 100644 --- a/docs/0.60/refreshcontrol/index.html +++ b/docs/0.60/refreshcontrol/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

RefreshControl

This component is used inside a ScrollView or ListView to add pull to refresh functionality. When the ScrollView is at scrollY: 0, swiping down triggers an onRefresh event.

Example

Note: refreshing is a controlled prop, this is why it needs to be set to true in the onRefresh function otherwise the refresh indicator will stop immediately.

Reference

Props

Inherits View Props.

refreshing

Whether the view should be indicating an active refresh.

TypeRequired
boolYes

onRefresh

Called when the view starts refreshing.

TypeRequired
functionNo

colors

The colors (at least one) that will be used to draw the refresh indicator.

TypeRequiredPlatform
array of colorNoAndroid

enabled

Whether the pull to refresh functionality is enabled.

TypeRequiredPlatform
boolNoAndroid

progressBackgroundColor

The background color of the refresh indicator.

TypeRequiredPlatform
colorNoAndroid

progressViewOffset

Progress view top offset

TypeRequiredPlatform
numberNoAndroid

size

Size of the refresh indicator, see RefreshControl.SIZE.

TypeRequiredPlatform
enum(RefreshLayoutConsts.SIZE.DEFAULT, RefreshLayoutConsts.SIZE.LARGE)NoAndroid

tintColor

The color of the refresh indicator.

TypeRequiredPlatform
colorNoiOS

title

The title displayed under the refresh indicator.

TypeRequiredPlatform
stringNoiOS

titleColor

Title color.

TypeRequiredPlatform
colorNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.60/removing-default-permissions.html b/docs/0.60/removing-default-permissions.html index cd8c1cf6af0..28648f4aea7 100644 --- a/docs/0.60/removing-default-permissions.html +++ b/docs/0.60/removing-default-permissions.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Removing Default Permissions

By default, some permissions are added to your Android APK.

The default permissions that get added are:

  • android.permission.INTERNET - Required for debug mode.
  • android.permission.SYSTEM_ALERT_WINDOW - Required for debug mode.
  • android.permission.READ_PHONE_STATE - Not required for debug or production.
  • android.permission.WRITE_EXTERNAL_STORAGE - Not required for debug or production.
  • android.permission.READ_EXTERNAL_STORAGE - Not required for debug or production.

  1. Let's start by removing READ_PHONE_STATE, WRITE_EXTERNAL_STORAGE, and READ_EXTERNAL_STORAGE from both production and debug APKs, as it is not required in either. These storage permissions are still not needed if AsyncStorage module is in use, so it is safe to remove from both production and debug.

  2. Open your android/app/src/main/AndroidManifest.xml file.

  3. Even though these three permissions are not listed in the manifest they get added in. We add the three permissions with tools:node="remove" attribute, to make sure it gets removed during build. Note that the package identifier will be different, for below it is "com.myapp" because the project was created with react-native init myapp.

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.myappid"
    + xmlns:tools="http://schemas.android.com/tools"
    >
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
    + <uses-permission tools:node="remove" android:name="android.permission.READ_PHONE_STATE" />
    + <uses-permission tools:node="remove" android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    + <uses-permission tools:node="remove" android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <application
    android:name=".MainApplication"
    android:label="@string/app_name"
    android:icon="@mipmap/ic_launcher"
    android:allowBackup="false"
    android:theme="@style/AppTheme">
    <activity
    android:name=".MainActivity"
    android:label="@string/app_name"
    android:configChanges="keyboard|keyboardHidden|orientation|screenSize"
    android:windowSoftInputMode="adjustResize">
    <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    </activity>
    <activity android:name="com.facebook.react.devsupport.DevSettingsActivity" />
    </application>
    </manifest>

That's it. We did not remove the INTERNET permission as pretty much all apps use it. Now whenever you create a production APK, these 3 permissions will be removed. When you create a debug APK (react-native run-android) it will install the APK with these permissions added.

Edit this page
Last updated on
- + diff --git a/docs/0.60/removing-default-permissions/index.html b/docs/0.60/removing-default-permissions/index.html index cd8c1cf6af0..28648f4aea7 100644 --- a/docs/0.60/removing-default-permissions/index.html +++ b/docs/0.60/removing-default-permissions/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Removing Default Permissions

By default, some permissions are added to your Android APK.

The default permissions that get added are:

  • android.permission.INTERNET - Required for debug mode.
  • android.permission.SYSTEM_ALERT_WINDOW - Required for debug mode.
  • android.permission.READ_PHONE_STATE - Not required for debug or production.
  • android.permission.WRITE_EXTERNAL_STORAGE - Not required for debug or production.
  • android.permission.READ_EXTERNAL_STORAGE - Not required for debug or production.

  1. Let's start by removing READ_PHONE_STATE, WRITE_EXTERNAL_STORAGE, and READ_EXTERNAL_STORAGE from both production and debug APKs, as it is not required in either. These storage permissions are still not needed if AsyncStorage module is in use, so it is safe to remove from both production and debug.

  2. Open your android/app/src/main/AndroidManifest.xml file.

  3. Even though these three permissions are not listed in the manifest they get added in. We add the three permissions with tools:node="remove" attribute, to make sure it gets removed during build. Note that the package identifier will be different, for below it is "com.myapp" because the project was created with react-native init myapp.

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.myappid"
    + xmlns:tools="http://schemas.android.com/tools"
    >
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
    + <uses-permission tools:node="remove" android:name="android.permission.READ_PHONE_STATE" />
    + <uses-permission tools:node="remove" android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    + <uses-permission tools:node="remove" android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <application
    android:name=".MainApplication"
    android:label="@string/app_name"
    android:icon="@mipmap/ic_launcher"
    android:allowBackup="false"
    android:theme="@style/AppTheme">
    <activity
    android:name=".MainActivity"
    android:label="@string/app_name"
    android:configChanges="keyboard|keyboardHidden|orientation|screenSize"
    android:windowSoftInputMode="adjustResize">
    <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    </activity>
    <activity android:name="com.facebook.react.devsupport.DevSettingsActivity" />
    </application>
    </manifest>

That's it. We did not remove the INTERNET permission as pretty much all apps use it. Now whenever you create a production APK, these 3 permissions will be removed. When you create a debug APK (react-native run-android) it will install the APK with these permissions added.

Edit this page
Last updated on
- + diff --git a/docs/0.60/running-on-device.html b/docs/0.60/running-on-device.html index 91ed4a068ce..ad7ef2bc55a 100644 --- a/docs/0.60/running-on-device.html +++ b/docs/0.60/running-on-device.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Running On Device

It's always a good idea to test your app on an actual device before releasing it to your users. This document will guide you through the necessary steps to run your React Native app on a device and to get it ready for production.

If you used Expo CLI or Create React Native App to set up your project, you can preview your app on a device by scanning the QR code with the Expo app—but in order to build and run your app on a device, you will need to eject and install the native code dependencies from the environment setup guide.

Running your app on Android devices

Development OS

1. Enable Debugging over USB

Most Android devices can only install and run apps downloaded from Google Play, by default. You will need to enable USB Debugging on your device in order to install your app during development.

To enable USB debugging on your device, you will first need to enable the "Developer options" menu by going to Settings → About phone → Software information and then tapping the Build number row at the bottom seven times. You can then go back to Settings → Developer options to enable "USB debugging".

2. Plug in your device via USB

Let's now set up an Android device to run our React Native projects. Go ahead and plug in your device via USB to your development machine.

Next, check the manufacturer code by using lsusb (on mac, you must first install lsusb). lsusb should output something like this:

$ lsusb
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 003: ID 22b8:2e76 Motorola PCS
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

These lines represent the USB devices currently connected to your machine.

You want the line that represents your phone. If you're in doubt, try unplugging your phone and running the command again:

$ lsusb
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

You'll see that after removing the phone, the line which has the phone model ("Motorola PCS" in this case) disappeared from the list. This is the line that we care about.

Bus 001 Device 003: ID 22b8:2e76 Motorola PCS

From the above line, you want to grab the first four digits from the device ID:

22b8:2e76

In this case, it's 22b8. That's the identifier for Motorola.

You'll need to input this into your udev rules in order to get up and running:

echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="22b8", MODE="0666", GROUP="plugdev"' | sudo tee /etc/udev/rules.d/51-android-usb.rules

Make sure that you replace 22b8 with the identifier you get in the above command.

Now check that your device is properly connecting to ADB, the Android Debug Bridge, by running adb devices.

$ adb devices
List of devices attached
emulator-5554 offline # Google emulator
14ed2fcc device # Physical device

Seeing device in the right column means the device is connected. You must have only one device connected at a time.

3. Run your app

Type the following in your command prompt to install and launch your app on the device:

$ npx react-native run-android

If you get a "bridge configuration isn't available" error, see Using adb reverse.

Hint: You can also use the React Native CLI to generate and run a Release build (e.g. npx react-native run-android --variant=release).

Connecting to the development server

You can also iterate quickly on a device by connecting to the development server running on your development machine. There are several ways of accomplishing this, depending on whether you have access to a USB cable or a Wi-Fi network.

Method 1: Using adb reverse (recommended)

You can use this method if your device is running Android 5.0 (Lollipop) or newer, it has USB debugging enabled, and it is connected via USB to your development machine.

Run the following in a command prompt:

$ adb -s <device name> reverse tcp:8081 tcp:8081

To find the device name, run the following adb command:

$ adb devices

You can now enable Live reloading from the Developer menu. Your app will reload whenever your JavaScript code has changed.

Method 2: Connect via Wi-Fi

You can also connect to the development server over Wi-Fi. You'll first need to install the app on your device using a USB cable, but once that has been done you can debug wirelessly by following these instructions. You'll need your development machine's current IP address before proceeding.

Open a terminal and type /sbin/ifconfig to find your machine's IP address.

  1. Make sure your laptop and your phone are on the same Wi-Fi network.
  2. Open your React Native app on your device.
  3. You'll see a red screen with an error. This is OK. The following steps will fix that.
  4. Open the in-app Developer menu.
  5. Go to Dev Settings → Debug server host & port for device.
  6. Type in your machine's IP address and the port of the local dev server (e.g. 10.0.1.1:8081).
  7. Go back to the Developer menu and select Reload JS.

You can now enable Live reloading from the Developer menu. Your app will reload whenever your JavaScript code has changed.

Building your app for production

You have built a great app using React Native, and you are now itching to release it in the Play Store. The process is the same as any other native Android app, with some additional considerations to take into account. Follow the guide for generating a signed APK to learn more.

Edit this page
Last updated on
- + diff --git a/docs/0.60/running-on-device/index.html b/docs/0.60/running-on-device/index.html index 91ed4a068ce..ad7ef2bc55a 100644 --- a/docs/0.60/running-on-device/index.html +++ b/docs/0.60/running-on-device/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Running On Device

It's always a good idea to test your app on an actual device before releasing it to your users. This document will guide you through the necessary steps to run your React Native app on a device and to get it ready for production.

If you used Expo CLI or Create React Native App to set up your project, you can preview your app on a device by scanning the QR code with the Expo app—but in order to build and run your app on a device, you will need to eject and install the native code dependencies from the environment setup guide.

Running your app on Android devices

Development OS

1. Enable Debugging over USB

Most Android devices can only install and run apps downloaded from Google Play, by default. You will need to enable USB Debugging on your device in order to install your app during development.

To enable USB debugging on your device, you will first need to enable the "Developer options" menu by going to Settings → About phone → Software information and then tapping the Build number row at the bottom seven times. You can then go back to Settings → Developer options to enable "USB debugging".

2. Plug in your device via USB

Let's now set up an Android device to run our React Native projects. Go ahead and plug in your device via USB to your development machine.

Next, check the manufacturer code by using lsusb (on mac, you must first install lsusb). lsusb should output something like this:

$ lsusb
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 003: ID 22b8:2e76 Motorola PCS
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

These lines represent the USB devices currently connected to your machine.

You want the line that represents your phone. If you're in doubt, try unplugging your phone and running the command again:

$ lsusb
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

You'll see that after removing the phone, the line which has the phone model ("Motorola PCS" in this case) disappeared from the list. This is the line that we care about.

Bus 001 Device 003: ID 22b8:2e76 Motorola PCS

From the above line, you want to grab the first four digits from the device ID:

22b8:2e76

In this case, it's 22b8. That's the identifier for Motorola.

You'll need to input this into your udev rules in order to get up and running:

echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="22b8", MODE="0666", GROUP="plugdev"' | sudo tee /etc/udev/rules.d/51-android-usb.rules

Make sure that you replace 22b8 with the identifier you get in the above command.

Now check that your device is properly connecting to ADB, the Android Debug Bridge, by running adb devices.

$ adb devices
List of devices attached
emulator-5554 offline # Google emulator
14ed2fcc device # Physical device

Seeing device in the right column means the device is connected. You must have only one device connected at a time.

3. Run your app

Type the following in your command prompt to install and launch your app on the device:

$ npx react-native run-android

If you get a "bridge configuration isn't available" error, see Using adb reverse.

Hint: You can also use the React Native CLI to generate and run a Release build (e.g. npx react-native run-android --variant=release).

Connecting to the development server

You can also iterate quickly on a device by connecting to the development server running on your development machine. There are several ways of accomplishing this, depending on whether you have access to a USB cable or a Wi-Fi network.

Method 1: Using adb reverse (recommended)

You can use this method if your device is running Android 5.0 (Lollipop) or newer, it has USB debugging enabled, and it is connected via USB to your development machine.

Run the following in a command prompt:

$ adb -s <device name> reverse tcp:8081 tcp:8081

To find the device name, run the following adb command:

$ adb devices

You can now enable Live reloading from the Developer menu. Your app will reload whenever your JavaScript code has changed.

Method 2: Connect via Wi-Fi

You can also connect to the development server over Wi-Fi. You'll first need to install the app on your device using a USB cable, but once that has been done you can debug wirelessly by following these instructions. You'll need your development machine's current IP address before proceeding.

Open a terminal and type /sbin/ifconfig to find your machine's IP address.

  1. Make sure your laptop and your phone are on the same Wi-Fi network.
  2. Open your React Native app on your device.
  3. You'll see a red screen with an error. This is OK. The following steps will fix that.
  4. Open the in-app Developer menu.
  5. Go to Dev Settings → Debug server host & port for device.
  6. Type in your machine's IP address and the port of the local dev server (e.g. 10.0.1.1:8081).
  7. Go back to the Developer menu and select Reload JS.

You can now enable Live reloading from the Developer menu. Your app will reload whenever your JavaScript code has changed.

Building your app for production

You have built a great app using React Native, and you are now itching to release it in the Play Store. The process is the same as any other native Android app, with some additional considerations to take into account. Follow the guide for generating a signed APK to learn more.

Edit this page
Last updated on
- + diff --git a/docs/0.60/running-on-simulator-ios.html b/docs/0.60/running-on-simulator-ios.html index 5386a928d17..9170984cc94 100644 --- a/docs/0.60/running-on-simulator-ios.html +++ b/docs/0.60/running-on-simulator-ios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Running On Simulator

Starting the simulator

Once you have your React Native project initialized, you can run react-native run-ios inside the newly created project directory. If everything is set up correctly, you should see your new app running in the iOS Simulator shortly.

Specifying a device

You can specify the device the simulator should run with the --simulator flag, followed by the device name as a string. The default is "iPhone X". If you wish to run your app on an iPhone 5s, run react-native run-ios --simulator="iPhone 5s".

The device names correspond to the list of devices available in Xcode. You can check your available devices by running xcrun simctl list devices from the console.

Edit this page
Last updated on
- + diff --git a/docs/0.60/running-on-simulator-ios/index.html b/docs/0.60/running-on-simulator-ios/index.html index 5386a928d17..9170984cc94 100644 --- a/docs/0.60/running-on-simulator-ios/index.html +++ b/docs/0.60/running-on-simulator-ios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Running On Simulator

Starting the simulator

Once you have your React Native project initialized, you can run react-native run-ios inside the newly created project directory. If everything is set up correctly, you should see your new app running in the iOS Simulator shortly.

Specifying a device

You can specify the device the simulator should run with the --simulator flag, followed by the device name as a string. The default is "iPhone X". If you wish to run your app on an iPhone 5s, run react-native run-ios --simulator="iPhone 5s".

The device names correspond to the list of devices available in Xcode. You can check your available devices by running xcrun simctl list devices from the console.

Edit this page
Last updated on
- + diff --git a/docs/0.60/safeareaview.html b/docs/0.60/safeareaview.html index 2b12f7c749b..c59b23863af 100644 --- a/docs/0.60/safeareaview.html +++ b/docs/0.60/safeareaview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

SafeAreaView

The purpose of SafeAreaView is to render content within the safe area boundaries of a device. It is currently only applicable to iOS devices with iOS version 11 or later.

SafeAreaView renders nested content and automatically applies padding to reflect the portion of the view that is not covered by navigation bars, tab bars, toolbars, and other ancestor views. Moreover, and most importantly, Safe Area's paddings reflect the physical limitation of the screen, such as rounded corners or camera notches (i.e. the sensor housing area on iPhone X).

Usage Example

To use, wrap your top level view with a SafeAreaView with a flex: 1 style applied to it. You may also want to use a background color that matches your application's design.

Reference

Props

Inherits View Props.

emulateUnlessSupported

TypeRequiredDefault
boolNotrue
Edit this page
Last updated on
- + diff --git a/docs/0.60/safeareaview/index.html b/docs/0.60/safeareaview/index.html index 2b12f7c749b..c59b23863af 100644 --- a/docs/0.60/safeareaview/index.html +++ b/docs/0.60/safeareaview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

SafeAreaView

The purpose of SafeAreaView is to render content within the safe area boundaries of a device. It is currently only applicable to iOS devices with iOS version 11 or later.

SafeAreaView renders nested content and automatically applies padding to reflect the portion of the view that is not covered by navigation bars, tab bars, toolbars, and other ancestor views. Moreover, and most importantly, Safe Area's paddings reflect the physical limitation of the screen, such as rounded corners or camera notches (i.e. the sensor housing area on iPhone X).

Usage Example

To use, wrap your top level view with a SafeAreaView with a flex: 1 style applied to it. You may also want to use a background color that matches your application's design.

Reference

Props

Inherits View Props.

emulateUnlessSupported

TypeRequiredDefault
boolNotrue
Edit this page
Last updated on
- + diff --git a/docs/0.60/scrollview.html b/docs/0.60/scrollview.html index 2d415091164..41963a736da 100644 --- a/docs/0.60/scrollview.html +++ b/docs/0.60/scrollview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

ScrollView

Component that wraps platform ScrollView while providing integration with touch locking "responder" system.

Keep in mind that ScrollViews must have a bounded height in order to work, since they contain unbounded-height children into a bounded container (via a scroll interaction). In order to bound the height of a ScrollView, either set the height of the view directly (discouraged) or make sure all parent views have bounded height. Forgetting to transfer {flex: 1} down the view stack can lead to errors here, which the element inspector makes quick to debug.

Doesn't yet support other contained responders from blocking this scroll view from becoming the responder.

<ScrollView> vs <FlatList> - which one to use?

ScrollView renders all its react child components at once, but this has a performance downside.

Imagine you have a very long list of items you want to display, maybe several screens worth of content. Creating JS components and native views for everything all at once, much of which may not even be shown, will contribute to slow rendering and increased memory usage.

This is where FlatList comes into play. FlatList renders items lazily, when they are about to appear, and removes items that scroll way off screen to save memory and processing time.

FlatList is also handy if you want to render separators between your items, multiple columns, infinite scroll loading, or any number of other features it supports out of the box.

Example

Reference

Props

Inherits View Props.

alwaysBounceHorizontal

When true, the scroll view bounces horizontally when it reaches the end even if the content is smaller than the scroll view itself. The default value is true when horizontal={true} and false otherwise.

TypeRequiredPlatform
boolNoiOS

alwaysBounceVertical

When true, the scroll view bounces vertically when it reaches the end even if the content is smaller than the scroll view itself. The default value is false when horizontal={true} and true otherwise.

TypeRequiredPlatform
boolNoiOS

automaticallyAdjustContentInsets

Controls whether iOS should automatically adjust the content inset for scroll views that are placed behind a navigation bar or tab bar/ toolbar. The default value is true.

TypeRequiredPlatform
boolNoiOS

bounces

When true, the scroll view bounces when it reaches the end of the content if the content is larger then the scroll view along the axis of the scroll direction. When false, it disables all bouncing even if the alwaysBounce* props are true. The default value is true.

TypeRequiredPlatform
boolNoiOS

bouncesZoom

When true, gestures can drive zoom past min/max and the zoom will animate to the min/max value at gesture end, otherwise the zoom will not exceed the limits.

TypeRequiredPlatform
boolNoiOS

canCancelContentTouches

When false, once tracking starts, won't try to drag if the touch moves. The default value is true.

TypeRequiredPlatform
boolNoiOS

centerContent

When true, the scroll view automatically centers the content when the content is smaller than the scroll view bounds; when the content is larger than the scroll view, this property has no effect. The default value is false.

TypeRequiredPlatform
boolNoiOS

contentContainerStyle

These styles will be applied to the scroll view content container which wraps all of the child views. Example:

return (
<ScrollView contentContainerStyle={styles.contentContainer}>
</ScrollView>
);
...
const styles = StyleSheet.create({
contentContainer: {
paddingVertical: 20
}
});
TypeRequired
StyleSheetPropType(View Style props)No

contentInset

The amount by which the scroll view content is inset from the edges of the scroll view. Defaults to {top: 0, left: 0, bottom: 0, right: 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

contentInsetAdjustmentBehavior

This property specifies how the safe area insets are used to modify the content area of the scroll view. The default value of this property is "never". Available on iOS 11 and later.

TypeRequiredPlatform
enum('automatic', 'scrollableAxes', 'never', 'always')NoiOS

contentOffset

Used to manually set the starting scroll offset. The default value is {x: 0, y: 0}.

TypeRequiredPlatform
PointPropTypeNoiOS

decelerationRate

A floating-point number that determines how quickly the scroll view decelerates after the user lifts their finger. You may also use string shortcuts "normal" and "fast" which match the underlying iOS settings for UIScrollViewDecelerationRateNormal and UIScrollViewDecelerationRateFast respectively.

  • 'normal' (the default), 0.998 on iOS, 0.985 on Android.
  • 'fast', 0.99 on iOS, 0.9 on Android.
TypeRequired
enum('fast', 'normal'), ,numberNo

directionalLockEnabled

When true, the ScrollView will try to lock to only vertical or horizontal scrolling while dragging. The default value is false.

TypeRequiredPlatform
boolNoiOS

disableIntervalMomentum

When true, the scroll view stops on the next index (in relation to scroll position at release) regardless of how fast the gesture is. This can be used for horizontal pagination when the page is less than the width of the ScrollView. The default value is false.

TypeRequired
boolNo

disableScrollViewPanResponder

When true, the default JS pan responder on the ScrollView is disabled, and full control over touches inside the ScrollView is left to its child components. This is particularly useful if snapToInterval is enabled, since it does not follow typical touch patterns. Do not use this on regular ScrollView use cases without snapToInterval as it may cause unexpected touches to occur while scrolling. The default value is false.

TypeRequired
boolNo

endFillColor

Sometimes a scrollview takes up more space than its content fills. When this is the case, this prop will fill the rest of the scrollview with a color to avoid setting a background and creating unnecessary overdraw. This is an advanced optimization that is not needed in the general case.

TypeRequiredPlatform
colorNoAndroid

horizontal

When true, the scroll view's children are arranged horizontally in a row instead of vertically in a column. The default value is false.

TypeRequired
boolNo

indicatorStyle

The style of the scroll indicators.

  • 'default' (the default), same as black.
  • 'black', scroll indicator is black. This style is good against a light background.
  • 'white', scroll indicator is white. This style is good against a dark background.
TypeRequiredPlatform
enum('default', 'black', 'white')NoiOS

invertStickyHeaders

If sticky headers should stick at the bottom instead of the top of the ScrollView. This is usually used with inverted ScrollViews.

TypeRequired
boolNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

Cross platform

  • 'none' (the default), drags do not dismiss the keyboard.
  • 'on-drag', the keyboard is dismissed when a drag begins.

iOS Only

  • 'interactive', the keyboard is dismissed interactively with the drag and moves in synchrony with the touch; dragging upwards cancels the dismissal. On android this is not supported and it will have the same behavior as 'none'.
TypeRequired
enum('none', 'on-drag', 'interactive')No

keyboardShouldPersistTaps

Determines when the keyboard should stay visible after a tap.

  • 'never' (the default), tapping outside of the focused text input when the keyboard is up dismisses the keyboard. When this happens, children won't receive the tap.
  • 'always', the keyboard will not dismiss automatically, and the scroll view will not catch taps, but children of the scroll view can catch taps.
  • 'handled', the keyboard will not dismiss automatically when the tap was handled by children of the scroll view (or captured by an ancestor).
  • false, deprecated, use 'never' instead
  • true, deprecated, use 'always' instead
TypeRequired
enum('always', 'never', 'handled', false, true)No

maintainVisibleContentPosition

When set, the scroll view will adjust the scroll position so that the first child that is currently visible and at or beyond minIndexForVisible will not change position. This is useful for lists that are loading content in both directions, e.g. a chat thread, where new messages coming in might otherwise cause the scroll position to jump. A value of 0 is common, but other values such as 1 can be used to skip loading spinners or other content that should not maintain position.

The optional autoscrollToTopThreshold can be used to make the content automatically scroll to the top after making the adjustment if the user was within the threshold of the top before the adjustment was made. This is also useful for chat-like applications where you want to see new messages scroll into place, but not if the user has scrolled up a ways and it would be disruptive to scroll a bunch.

Caveat 1: Reordering elements in the scrollview with this enabled will probably cause jumpiness and jank. It can be fixed, but there are currently no plans to do so. For now, don't re-order the content of any ScrollViews or Lists that use this feature.

Caveat 2: This uses contentOffset and frame.origin in native code to compute visibility. Occlusion, transforms, and other complexity won't be taken into account as to whether content is "visible" or not.

TypeRequiredPlatform
object: { minIndexForVisible: number, autoscrollToTopThreshold: number }NoiOS

maximumZoomScale

The maximum allowed zoom scale. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

minimumZoomScale

The minimum allowed zoom scale. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

nestedScrollEnabled

Enables nested scrolling for Android API level 21+. Nested scrolling is supported by default on iOS.

TypeRequiredPlatform
boolNoAndroid

onContentSizeChange

Called when scrollable content view of the ScrollView changes.

Handler function is passed the content width and content height as parameters: (contentWidth, contentHeight)

It's implemented using onLayout handler attached to the content container which this ScrollView renders.

TypeRequired
functionNo

onMomentumScrollBegin

Called when the momentum scroll starts (scroll which occurs as the ScrollView starts gliding).

TypeRequired
functionNo

onMomentumScrollEnd

Called when the momentum scroll ends (scroll which occurs as the ScrollView glides to a stop).

TypeRequired
functionNo

onScroll

Fires at most once per frame during scrolling. The frequency of the events can be controlled using the scrollEventThrottle prop. The event has the shape { nativeEvent: { contentInset: { bottom, left, right, top }, contentOffset: { x, y }, contentSize: { height, width }, layoutMeasurement: { height, width }, zoomScale } }. All values are numbers.

TypeRequired
functionNo

onScrollBeginDrag

Called when the user begins to drag the scroll view.

TypeRequired
functionNo

onScrollEndDrag

Called when the user stops dragging the scroll view and it either stops or begins to glide.

TypeRequired
functionNo

onScrollToTop

Fires when the scroll view scrolls to top after the status bar has been tapped.

TypeRequiredPlatform
functionNoiOS

overScrollMode

Used to override default value of overScroll mode.

Possible values:

  • 'auto' - Default value, allow a user to over-scroll this view only if the content is large enough to meaningfully scroll.
  • 'always' - Always allow a user to over-scroll this view.
  • 'never' - Never allow a user to over-scroll this view.
TypeRequiredPlatform
enum('auto', 'always', 'never')NoAndroid

pagingEnabled

When true, the scroll view stops on multiples of the scroll view's size when scrolling. This can be used for horizontal pagination. The default value is false.

Note: Vertical pagination is not supported on Android.

TypeRequired
boolNo

persistentScrollbar

Causes the scrollbars not to turn transparent when they are not in use. The default value is false.

TypeRequiredPlatform
boolNoAndroid

pinchGestureEnabled

When true, ScrollView allows use of pinch gestures to zoom in and out. The default value is true.

TypeRequiredPlatform
boolNoiOS

refreshControl

A RefreshControl component, used to provide pull-to-refresh functionality for the ScrollView. Only works for vertical ScrollViews (horizontal prop must be false).

See RefreshControl.

TypeRequired
elementNo

removeClippedSubviews

Experimental: When true, offscreen child views (whose overflow value is hidden) are removed from their native backing superview when offscreen. This can improve scrolling performance on long lists. The default value is true.

TypeRequired
boolNo

scrollBarThumbImage

Optionally an image can be used for the scroll bar thumb. This will override the color. While the image is loading or the image fails to load the color will be used instead. Use an alpha of 0 in the color to avoid seeing it while the image is loading.

  • uri, a string representing the resource identifier for the image, which should be either a local file path or the name of a static image resource.
  • number, opaque type returned by something like import IMAGE from './image.jpg'.
TypeRequiredPlatform
numberNoVR

scrollEnabled

When false, the view cannot be scrolled via touch interaction. The default value is true.

Note that the view can always be scrolled by calling scrollTo.

TypeRequired
boolNo

scrollEventThrottle

This controls how often the scroll event will be fired while scrolling (as a time interval in ms). A lower number yields better accuracy for code that is tracking the scroll position, but can lead to scroll performance problems due to the volume of information being send over the bridge. You will not notice a difference between values set between 1-16 as the JS run loop is synced to the screen refresh rate. If you do not need precise scroll position tracking, set this value higher to limit the information being sent across the bridge. The default value is zero, which results in the scroll event being sent only once each time the view is scrolled.

TypeRequiredPlatform
numberNoiOS

scrollIndicatorInsets

The amount by which the scroll view indicators are inset from the edges of the scroll view. This should normally be set to the same value as the contentInset. Defaults to {0, 0, 0, 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

scrollPerfTag

Tag used to log scroll performance on this scroll view. Will force momentum events to be turned on (see sendMomentumEvents). This doesn't do anything out of the box and you need to implement a custom native FpsListener for it to be useful.

TypeRequiredPlatform
stringNoAndroid

scrollToOverflowEnabled

When true, the scroll view can be programmatically scrolled beyond its content size. The default value is false.

TypeRequiredPlatform
boolNoiOS

scrollsToTop

When true, the scroll view scrolls to top when the status bar is tapped. The default value is true.

TypeRequiredPlatform
boolNoiOS

DEPRECATED_sendUpdatedChildFrames

When true, ScrollView will emit updateChildFrames data in scroll events, otherwise will not compute or emit child frame data. This only exists to support legacy issues, onLayout should be used instead to retrieve frame data. The default value is false.

TypeRequiredPlatform
boolNoiOS

showsHorizontalScrollIndicator

When true, shows a horizontal scroll indicator. The default value is true.

TypeRequired
boolNo

showsVerticalScrollIndicator

When true, shows a vertical scroll indicator. The default value is true.

TypeRequired
boolNo

snapToAlignment

When snapToInterval is set, snapToAlignment will define the relationship of the snapping to the scroll view.

  • 'start' (the default) will align the snap at the left (horizontal) or top (vertical).
  • 'center' will align the snap in the center.
  • 'end' will align the snap at the right (horizontal) or bottom (vertical).
TypeRequiredPlatform
enum('start', 'center', 'end')NoiOS

snapToEnd

Use in conjunction with snapToOffsets. By default, the end of the list counts as a snap offset. Set snapToEnd to false to disable this behavior and allow the list to scroll freely between its end and the last snapToOffsets offset. The default value is true.

TypeRequired
booleanNo

snapToInterval

When set, causes the scroll view to stop at multiples of the value of snapToInterval. This can be used for paginating through children that have lengths smaller than the scroll view. Typically used in combination with snapToAlignment and decelerationRate="fast". Overrides less configurable pagingEnabled prop.

TypeRequired
numberNo

snapToOffsets

When set, causes the scroll view to stop at the defined offsets. This can be used for paginating through variously sized children that have lengths smaller than the scroll view. Typically used in combination with decelerationRate="fast". Overrides less configurable pagingEnabled and snapToInterval props.

TypeRequired
array of numberNo

snapToStart

Use in conjunction with snapToOffsets. By default, the beginning of the list counts as a snap offset. Set snapToStart to false to disable this behavior and allow the list to scroll freely between its start and the first snapToOffsets offset. The default value is true.

TypeRequired
booleanNo

stickyHeaderIndices

An array of child indices determining which children get docked to the top of the screen when scrolling. For example, passing stickyHeaderIndices={[0]} will cause the first child to be fixed to the top of the scroll view. This property is not supported in conjunction with horizontal={true}.

TypeRequired
array of numberNo

zoomScale

The current scale of the scroll view content. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

Methods

flashScrollIndicators()

flashScrollIndicators();

Displays the scroll indicators momentarily.

scrollTo()

scrollTo(
options?: {x?: number, y?: number, animated?: boolean} | number,
deprecatedX?: number,
deprecatedAnimated?: boolean,
);

Scrolls to a given x, y offset, either immediately, with a smooth animation.

Example:

scrollTo({x: 0, y: 0, animated: true})

Note: The weird function signature is due to the fact that, for historical reasons, the function also accepts separate arguments as an alternative to the options object. This is deprecated due to ambiguity (y before x), and SHOULD NOT BE USED.

scrollToEnd()

scrollToEnd(([options]: { animated: boolean, duration: number }));

If this is a vertical ScrollView scrolls to the bottom. If this is a horizontal ScrollView scrolls to the right.

Use scrollToEnd({animated: true}) for smooth animated scrolling, scrollToEnd({animated: false}) for immediate scrolling. For Android, you may specify a duration, e.g. scrollToEnd({duration: 500}) for a controlled duration scroll. If no options are passed, animated defaults to true.

scrollWithoutAnimationTo()

scrollWithoutAnimationTo(y, x);

Deprecated, use scrollTo instead.

Edit this page
Last updated on
- + diff --git a/docs/0.60/scrollview/index.html b/docs/0.60/scrollview/index.html index 2d415091164..41963a736da 100644 --- a/docs/0.60/scrollview/index.html +++ b/docs/0.60/scrollview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

ScrollView

Component that wraps platform ScrollView while providing integration with touch locking "responder" system.

Keep in mind that ScrollViews must have a bounded height in order to work, since they contain unbounded-height children into a bounded container (via a scroll interaction). In order to bound the height of a ScrollView, either set the height of the view directly (discouraged) or make sure all parent views have bounded height. Forgetting to transfer {flex: 1} down the view stack can lead to errors here, which the element inspector makes quick to debug.

Doesn't yet support other contained responders from blocking this scroll view from becoming the responder.

<ScrollView> vs <FlatList> - which one to use?

ScrollView renders all its react child components at once, but this has a performance downside.

Imagine you have a very long list of items you want to display, maybe several screens worth of content. Creating JS components and native views for everything all at once, much of which may not even be shown, will contribute to slow rendering and increased memory usage.

This is where FlatList comes into play. FlatList renders items lazily, when they are about to appear, and removes items that scroll way off screen to save memory and processing time.

FlatList is also handy if you want to render separators between your items, multiple columns, infinite scroll loading, or any number of other features it supports out of the box.

Example

Reference

Props

Inherits View Props.

alwaysBounceHorizontal

When true, the scroll view bounces horizontally when it reaches the end even if the content is smaller than the scroll view itself. The default value is true when horizontal={true} and false otherwise.

TypeRequiredPlatform
boolNoiOS

alwaysBounceVertical

When true, the scroll view bounces vertically when it reaches the end even if the content is smaller than the scroll view itself. The default value is false when horizontal={true} and true otherwise.

TypeRequiredPlatform
boolNoiOS

automaticallyAdjustContentInsets

Controls whether iOS should automatically adjust the content inset for scroll views that are placed behind a navigation bar or tab bar/ toolbar. The default value is true.

TypeRequiredPlatform
boolNoiOS

bounces

When true, the scroll view bounces when it reaches the end of the content if the content is larger then the scroll view along the axis of the scroll direction. When false, it disables all bouncing even if the alwaysBounce* props are true. The default value is true.

TypeRequiredPlatform
boolNoiOS

bouncesZoom

When true, gestures can drive zoom past min/max and the zoom will animate to the min/max value at gesture end, otherwise the zoom will not exceed the limits.

TypeRequiredPlatform
boolNoiOS

canCancelContentTouches

When false, once tracking starts, won't try to drag if the touch moves. The default value is true.

TypeRequiredPlatform
boolNoiOS

centerContent

When true, the scroll view automatically centers the content when the content is smaller than the scroll view bounds; when the content is larger than the scroll view, this property has no effect. The default value is false.

TypeRequiredPlatform
boolNoiOS

contentContainerStyle

These styles will be applied to the scroll view content container which wraps all of the child views. Example:

return (
<ScrollView contentContainerStyle={styles.contentContainer}>
</ScrollView>
);
...
const styles = StyleSheet.create({
contentContainer: {
paddingVertical: 20
}
});
TypeRequired
StyleSheetPropType(View Style props)No

contentInset

The amount by which the scroll view content is inset from the edges of the scroll view. Defaults to {top: 0, left: 0, bottom: 0, right: 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

contentInsetAdjustmentBehavior

This property specifies how the safe area insets are used to modify the content area of the scroll view. The default value of this property is "never". Available on iOS 11 and later.

TypeRequiredPlatform
enum('automatic', 'scrollableAxes', 'never', 'always')NoiOS

contentOffset

Used to manually set the starting scroll offset. The default value is {x: 0, y: 0}.

TypeRequiredPlatform
PointPropTypeNoiOS

decelerationRate

A floating-point number that determines how quickly the scroll view decelerates after the user lifts their finger. You may also use string shortcuts "normal" and "fast" which match the underlying iOS settings for UIScrollViewDecelerationRateNormal and UIScrollViewDecelerationRateFast respectively.

  • 'normal' (the default), 0.998 on iOS, 0.985 on Android.
  • 'fast', 0.99 on iOS, 0.9 on Android.
TypeRequired
enum('fast', 'normal'), ,numberNo

directionalLockEnabled

When true, the ScrollView will try to lock to only vertical or horizontal scrolling while dragging. The default value is false.

TypeRequiredPlatform
boolNoiOS

disableIntervalMomentum

When true, the scroll view stops on the next index (in relation to scroll position at release) regardless of how fast the gesture is. This can be used for horizontal pagination when the page is less than the width of the ScrollView. The default value is false.

TypeRequired
boolNo

disableScrollViewPanResponder

When true, the default JS pan responder on the ScrollView is disabled, and full control over touches inside the ScrollView is left to its child components. This is particularly useful if snapToInterval is enabled, since it does not follow typical touch patterns. Do not use this on regular ScrollView use cases without snapToInterval as it may cause unexpected touches to occur while scrolling. The default value is false.

TypeRequired
boolNo

endFillColor

Sometimes a scrollview takes up more space than its content fills. When this is the case, this prop will fill the rest of the scrollview with a color to avoid setting a background and creating unnecessary overdraw. This is an advanced optimization that is not needed in the general case.

TypeRequiredPlatform
colorNoAndroid

horizontal

When true, the scroll view's children are arranged horizontally in a row instead of vertically in a column. The default value is false.

TypeRequired
boolNo

indicatorStyle

The style of the scroll indicators.

  • 'default' (the default), same as black.
  • 'black', scroll indicator is black. This style is good against a light background.
  • 'white', scroll indicator is white. This style is good against a dark background.
TypeRequiredPlatform
enum('default', 'black', 'white')NoiOS

invertStickyHeaders

If sticky headers should stick at the bottom instead of the top of the ScrollView. This is usually used with inverted ScrollViews.

TypeRequired
boolNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

Cross platform

  • 'none' (the default), drags do not dismiss the keyboard.
  • 'on-drag', the keyboard is dismissed when a drag begins.

iOS Only

  • 'interactive', the keyboard is dismissed interactively with the drag and moves in synchrony with the touch; dragging upwards cancels the dismissal. On android this is not supported and it will have the same behavior as 'none'.
TypeRequired
enum('none', 'on-drag', 'interactive')No

keyboardShouldPersistTaps

Determines when the keyboard should stay visible after a tap.

  • 'never' (the default), tapping outside of the focused text input when the keyboard is up dismisses the keyboard. When this happens, children won't receive the tap.
  • 'always', the keyboard will not dismiss automatically, and the scroll view will not catch taps, but children of the scroll view can catch taps.
  • 'handled', the keyboard will not dismiss automatically when the tap was handled by children of the scroll view (or captured by an ancestor).
  • false, deprecated, use 'never' instead
  • true, deprecated, use 'always' instead
TypeRequired
enum('always', 'never', 'handled', false, true)No

maintainVisibleContentPosition

When set, the scroll view will adjust the scroll position so that the first child that is currently visible and at or beyond minIndexForVisible will not change position. This is useful for lists that are loading content in both directions, e.g. a chat thread, where new messages coming in might otherwise cause the scroll position to jump. A value of 0 is common, but other values such as 1 can be used to skip loading spinners or other content that should not maintain position.

The optional autoscrollToTopThreshold can be used to make the content automatically scroll to the top after making the adjustment if the user was within the threshold of the top before the adjustment was made. This is also useful for chat-like applications where you want to see new messages scroll into place, but not if the user has scrolled up a ways and it would be disruptive to scroll a bunch.

Caveat 1: Reordering elements in the scrollview with this enabled will probably cause jumpiness and jank. It can be fixed, but there are currently no plans to do so. For now, don't re-order the content of any ScrollViews or Lists that use this feature.

Caveat 2: This uses contentOffset and frame.origin in native code to compute visibility. Occlusion, transforms, and other complexity won't be taken into account as to whether content is "visible" or not.

TypeRequiredPlatform
object: { minIndexForVisible: number, autoscrollToTopThreshold: number }NoiOS

maximumZoomScale

The maximum allowed zoom scale. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

minimumZoomScale

The minimum allowed zoom scale. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

nestedScrollEnabled

Enables nested scrolling for Android API level 21+. Nested scrolling is supported by default on iOS.

TypeRequiredPlatform
boolNoAndroid

onContentSizeChange

Called when scrollable content view of the ScrollView changes.

Handler function is passed the content width and content height as parameters: (contentWidth, contentHeight)

It's implemented using onLayout handler attached to the content container which this ScrollView renders.

TypeRequired
functionNo

onMomentumScrollBegin

Called when the momentum scroll starts (scroll which occurs as the ScrollView starts gliding).

TypeRequired
functionNo

onMomentumScrollEnd

Called when the momentum scroll ends (scroll which occurs as the ScrollView glides to a stop).

TypeRequired
functionNo

onScroll

Fires at most once per frame during scrolling. The frequency of the events can be controlled using the scrollEventThrottle prop. The event has the shape { nativeEvent: { contentInset: { bottom, left, right, top }, contentOffset: { x, y }, contentSize: { height, width }, layoutMeasurement: { height, width }, zoomScale } }. All values are numbers.

TypeRequired
functionNo

onScrollBeginDrag

Called when the user begins to drag the scroll view.

TypeRequired
functionNo

onScrollEndDrag

Called when the user stops dragging the scroll view and it either stops or begins to glide.

TypeRequired
functionNo

onScrollToTop

Fires when the scroll view scrolls to top after the status bar has been tapped.

TypeRequiredPlatform
functionNoiOS

overScrollMode

Used to override default value of overScroll mode.

Possible values:

  • 'auto' - Default value, allow a user to over-scroll this view only if the content is large enough to meaningfully scroll.
  • 'always' - Always allow a user to over-scroll this view.
  • 'never' - Never allow a user to over-scroll this view.
TypeRequiredPlatform
enum('auto', 'always', 'never')NoAndroid

pagingEnabled

When true, the scroll view stops on multiples of the scroll view's size when scrolling. This can be used for horizontal pagination. The default value is false.

Note: Vertical pagination is not supported on Android.

TypeRequired
boolNo

persistentScrollbar

Causes the scrollbars not to turn transparent when they are not in use. The default value is false.

TypeRequiredPlatform
boolNoAndroid

pinchGestureEnabled

When true, ScrollView allows use of pinch gestures to zoom in and out. The default value is true.

TypeRequiredPlatform
boolNoiOS

refreshControl

A RefreshControl component, used to provide pull-to-refresh functionality for the ScrollView. Only works for vertical ScrollViews (horizontal prop must be false).

See RefreshControl.

TypeRequired
elementNo

removeClippedSubviews

Experimental: When true, offscreen child views (whose overflow value is hidden) are removed from their native backing superview when offscreen. This can improve scrolling performance on long lists. The default value is true.

TypeRequired
boolNo

scrollBarThumbImage

Optionally an image can be used for the scroll bar thumb. This will override the color. While the image is loading or the image fails to load the color will be used instead. Use an alpha of 0 in the color to avoid seeing it while the image is loading.

  • uri, a string representing the resource identifier for the image, which should be either a local file path or the name of a static image resource.
  • number, opaque type returned by something like import IMAGE from './image.jpg'.
TypeRequiredPlatform
numberNoVR

scrollEnabled

When false, the view cannot be scrolled via touch interaction. The default value is true.

Note that the view can always be scrolled by calling scrollTo.

TypeRequired
boolNo

scrollEventThrottle

This controls how often the scroll event will be fired while scrolling (as a time interval in ms). A lower number yields better accuracy for code that is tracking the scroll position, but can lead to scroll performance problems due to the volume of information being send over the bridge. You will not notice a difference between values set between 1-16 as the JS run loop is synced to the screen refresh rate. If you do not need precise scroll position tracking, set this value higher to limit the information being sent across the bridge. The default value is zero, which results in the scroll event being sent only once each time the view is scrolled.

TypeRequiredPlatform
numberNoiOS

scrollIndicatorInsets

The amount by which the scroll view indicators are inset from the edges of the scroll view. This should normally be set to the same value as the contentInset. Defaults to {0, 0, 0, 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

scrollPerfTag

Tag used to log scroll performance on this scroll view. Will force momentum events to be turned on (see sendMomentumEvents). This doesn't do anything out of the box and you need to implement a custom native FpsListener for it to be useful.

TypeRequiredPlatform
stringNoAndroid

scrollToOverflowEnabled

When true, the scroll view can be programmatically scrolled beyond its content size. The default value is false.

TypeRequiredPlatform
boolNoiOS

scrollsToTop

When true, the scroll view scrolls to top when the status bar is tapped. The default value is true.

TypeRequiredPlatform
boolNoiOS

DEPRECATED_sendUpdatedChildFrames

When true, ScrollView will emit updateChildFrames data in scroll events, otherwise will not compute or emit child frame data. This only exists to support legacy issues, onLayout should be used instead to retrieve frame data. The default value is false.

TypeRequiredPlatform
boolNoiOS

showsHorizontalScrollIndicator

When true, shows a horizontal scroll indicator. The default value is true.

TypeRequired
boolNo

showsVerticalScrollIndicator

When true, shows a vertical scroll indicator. The default value is true.

TypeRequired
boolNo

snapToAlignment

When snapToInterval is set, snapToAlignment will define the relationship of the snapping to the scroll view.

  • 'start' (the default) will align the snap at the left (horizontal) or top (vertical).
  • 'center' will align the snap in the center.
  • 'end' will align the snap at the right (horizontal) or bottom (vertical).
TypeRequiredPlatform
enum('start', 'center', 'end')NoiOS

snapToEnd

Use in conjunction with snapToOffsets. By default, the end of the list counts as a snap offset. Set snapToEnd to false to disable this behavior and allow the list to scroll freely between its end and the last snapToOffsets offset. The default value is true.

TypeRequired
booleanNo

snapToInterval

When set, causes the scroll view to stop at multiples of the value of snapToInterval. This can be used for paginating through children that have lengths smaller than the scroll view. Typically used in combination with snapToAlignment and decelerationRate="fast". Overrides less configurable pagingEnabled prop.

TypeRequired
numberNo

snapToOffsets

When set, causes the scroll view to stop at the defined offsets. This can be used for paginating through variously sized children that have lengths smaller than the scroll view. Typically used in combination with decelerationRate="fast". Overrides less configurable pagingEnabled and snapToInterval props.

TypeRequired
array of numberNo

snapToStart

Use in conjunction with snapToOffsets. By default, the beginning of the list counts as a snap offset. Set snapToStart to false to disable this behavior and allow the list to scroll freely between its start and the first snapToOffsets offset. The default value is true.

TypeRequired
booleanNo

stickyHeaderIndices

An array of child indices determining which children get docked to the top of the screen when scrolling. For example, passing stickyHeaderIndices={[0]} will cause the first child to be fixed to the top of the scroll view. This property is not supported in conjunction with horizontal={true}.

TypeRequired
array of numberNo

zoomScale

The current scale of the scroll view content. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

Methods

flashScrollIndicators()

flashScrollIndicators();

Displays the scroll indicators momentarily.

scrollTo()

scrollTo(
options?: {x?: number, y?: number, animated?: boolean} | number,
deprecatedX?: number,
deprecatedAnimated?: boolean,
);

Scrolls to a given x, y offset, either immediately, with a smooth animation.

Example:

scrollTo({x: 0, y: 0, animated: true})

Note: The weird function signature is due to the fact that, for historical reasons, the function also accepts separate arguments as an alternative to the options object. This is deprecated due to ambiguity (y before x), and SHOULD NOT BE USED.

scrollToEnd()

scrollToEnd(([options]: { animated: boolean, duration: number }));

If this is a vertical ScrollView scrolls to the bottom. If this is a horizontal ScrollView scrolls to the right.

Use scrollToEnd({animated: true}) for smooth animated scrolling, scrollToEnd({animated: false}) for immediate scrolling. For Android, you may specify a duration, e.g. scrollToEnd({duration: 500}) for a controlled duration scroll. If no options are passed, animated defaults to true.

scrollWithoutAnimationTo()

scrollWithoutAnimationTo(y, x);

Deprecated, use scrollTo instead.

Edit this page
Last updated on
- + diff --git a/docs/0.60/sectionlist.html b/docs/0.60/sectionlist.html index 2d523de6a4a..68f915ddac7 100644 --- a/docs/0.60/sectionlist.html +++ b/docs/0.60/sectionlist.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

SectionList

A performant interface for rendering sectioned lists, supporting the most handy features:

  • Fully cross-platform.
  • Configurable viewability callbacks.
  • List header support.
  • List footer support.
  • Item separator support.
  • Section header support.
  • Section separator support.
  • Heterogeneous data and item rendering support.
  • Pull to Refresh.
  • Scroll loading.

If you don't need section support and want a simpler interface, use <FlatList>.

Example

This is a convenience wrapper around <VirtualizedList>, and thus inherits its props (as well as those of <ScrollView> that aren't explicitly listed here, along with the following caveats:

  • Internal state is not preserved when content scrolls out of the render window. Make sure all your data is captured in the item data or external stores like Flux, Redux, or Relay.
  • This is a PureComponent which means that it will not re-render if props remain shallow-equal. Make sure that everything your renderItem function depends on is passed as a prop (e.g. extraData) that is not === after updates, otherwise your UI may not update on changes. This includes the data prop and parent component state.
  • In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate and momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application, and we are working on improving it behind the scenes.
  • By default, the list looks for a key prop on each item and uses that for the React key. Alternatively, you can provide a custom keyExtractor prop.

Props

Required props:

Optional props:

Methods

Type Definitions

Reference

Props

renderItem

Default renderer for every item in every section. Can be over-ridden on a per-section basis. Should return a React element.

TypeRequired
functionYes

The render function will be passed an object with the following keys:

  • 'item' (object) - the item object as specified in this section's data key
  • 'index' (number) - Item's index within the section.
  • 'section' (object) - The full section object as specified in sections.
  • 'separators' (object) - An object with the following keys:
    • 'highlight' (function) - () => void
    • 'unhighlight' (function) - () => void
    • 'updateProps' (function) - (select, newProps) => void
      • 'select' (enum) - possible values are 'leading', 'trailing'
      • 'newProps' (object)

sections

The actual data to render, akin to the data prop in FlatList.

TypeRequired
array of SectionsYes

extraData

A marker property for telling the list to re-render (since it implements PureComponent). If any of your renderItem, Header, Footer, etc. functions depend on anything outside of the data prop, stick it here and treat it immutably.

TypeRequired
anyNo

initialNumToRender

How many items to render in the initial batch. This should be enough to fill the screen but not much more. Note these items will never be unmounted as part of the windowed rendering in order to improve perceived performance of scroll-to-top actions.

TypeRequired
numberYes

inverted

Reverses the direction of scroll. Uses scale transforms of -1.

TypeRequired
[boolean]No

ItemSeparatorComponent

Rendered in between each item, but not at the top or bottom. By default, highlighted, section, and [leading/trailing][Item/Section] props are provided. renderItem provides separators.highlight/unhighlight which will update the highlighted prop, but you can also add custom props with separators.updateProps.

TypeRequired
[component, element]No

keyExtractor

Used to extract a unique key for a given item at the specified index. Key is used for caching and as the React key to track item re-ordering. The default extractor checks item.key, then falls back to using the index, like React does. Note that this sets keys for each item, but each overall section still needs its own key.

TypeRequired
(item: Item, index: number) => stringYes

legacyImplementation

The legacy implementation is no longer supported.

TypeRequired
[boolean]No

ListEmptyComponent

Rendered when the list is empty. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
[component, element]No

ListFooterComponent

Rendered at the very end of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
[component, element]No

ListHeaderComponent

Rendered at the very beginning of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
component, elementNo

onEndReached

Called once when the scroll position gets within onEndReachedThreshold of the rendered content.

TypeRequired
[(info: {distanceFromEnd: number}) => void]No

onEndReachedThreshold

How far from the end (in units of visible length of the list) the bottom edge of the list must be from the end of the content to trigger the onEndReached callback. Thus a value of 0.5 will trigger onEndReached when the end of the content is within half the visible length of the list.

TypeRequired
[number]No

onRefresh

If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the refreshing prop correctly. To offset the RefreshControl from the top (e.g. by 100 pts), use progressViewOffset={100}.

TypeRequired
[() => void]No

onViewableItemsChanged

Called when the viewability of rows changes, as defined by the viewabilityConfig prop.

TypeRequired
functionNo

The function will be passed an object with the following keys:

  • 'viewableItems' (array of ViewTokens)
  • 'changed' (array of ViewTokens)

The ViewToken type is exported by ViewabilityHelper.js:

NameTypeRequired
itemanyYes
keystringYes
indexnumberNo
isViewablebooleanYes
sectionanyNo

refreshing

Set this true while waiting for new data from a refresh.

TypeRequired
[boolean]No

removeClippedSubviews

Note: may have bugs (missing content) in some circumstances - use at your own risk.

This may improve scroll performance for large lists.

TypeRequired
booleanNo

renderSectionFooter

Rendered at the bottom of each section.

TypeRequired
[(info: {section: SectionT}) => ?React.Element<any>]No

renderSectionHeader

Rendered at the top of each section. These stick to the top of the ScrollView by default on iOS. See stickySectionHeadersEnabled.

TypeRequired
[(info: {section: SectionT}) => ?React.Element<any>]No

SectionSeparatorComponent

Rendered at the top and bottom of each section (note this is different from ItemSeparatorComponent which is only rendered between items). These are intended to separate sections from the headers above and below and typically have the same highlight response as ItemSeparatorComponent. Also receives highlighted, [leading/trailing][Item/Section], and any custom props from separators.updateProps.

TypeRequired
[ReactClass<any>]No

stickySectionHeadersEnabled

Makes section headers stick to the top of the screen until the next one pushes it off. Only enabled by default on iOS because that is the platform standard there.

TypeRequired
booleanNo

Methods

scrollToLocation()

scrollToLocation(params);

Scrolls to the item at the specified sectionIndex and itemIndex (within the section) positioned in the viewable area such that viewPosition 0 places it at the top (and may be covered by a sticky header), 1 at the bottom, and 0.5 centered in the middle.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout or onScrollToIndexFailed prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.
  • 'itemIndex' (number) - Index within section for the item to scroll to. Required.
  • 'sectionIndex' (number) - Index for section that contains the item to scroll to. Required.
  • 'viewOffset' (number) - A fixed number of pixels to offset the final target position, e.g. to compensate for sticky headers.
  • 'viewPosition' (number) - A value of 0 places the item specified by index at the top, 1 at the bottom, and 0.5 centered in the middle.

recordInteraction()

recordInteraction();

Tells the list an interaction has occurred, 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()

flashScrollIndicators();

Displays the scroll indicators momentarily.

Platfrom
iOS

Type Definitions

Section

An object that identifies the data to be rendered for a given section.

Type
any

Properties:

NameTypeDescription
dataarrayThe data for rendering items in this section. Array of objects, much like FlatList's data prop.
[key]stringOptional key to keep track of section re-ordering. If you don't plan on re-ordering sections, the array index will be used by default.
[renderItem]functionOptionally define an arbitrary item renderer for this section, overriding the default renderItem for the list.
[ItemSeparatorComponent]component, elementOptionally define an arbitrary item separator for this section, overriding the default ItemSeparatorComponent for the list.
[keyExtractor]functionOptionally define an arbitrary key extractor for this section, overriding the default keyExtractor.
Edit this page
Last updated on
- + diff --git a/docs/0.60/sectionlist/index.html b/docs/0.60/sectionlist/index.html index 2d523de6a4a..68f915ddac7 100644 --- a/docs/0.60/sectionlist/index.html +++ b/docs/0.60/sectionlist/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

SectionList

A performant interface for rendering sectioned lists, supporting the most handy features:

  • Fully cross-platform.
  • Configurable viewability callbacks.
  • List header support.
  • List footer support.
  • Item separator support.
  • Section header support.
  • Section separator support.
  • Heterogeneous data and item rendering support.
  • Pull to Refresh.
  • Scroll loading.

If you don't need section support and want a simpler interface, use <FlatList>.

Example

This is a convenience wrapper around <VirtualizedList>, and thus inherits its props (as well as those of <ScrollView> that aren't explicitly listed here, along with the following caveats:

  • Internal state is not preserved when content scrolls out of the render window. Make sure all your data is captured in the item data or external stores like Flux, Redux, or Relay.
  • This is a PureComponent which means that it will not re-render if props remain shallow-equal. Make sure that everything your renderItem function depends on is passed as a prop (e.g. extraData) that is not === after updates, otherwise your UI may not update on changes. This includes the data prop and parent component state.
  • In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate and momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application, and we are working on improving it behind the scenes.
  • By default, the list looks for a key prop on each item and uses that for the React key. Alternatively, you can provide a custom keyExtractor prop.

Props

Required props:

Optional props:

Methods

Type Definitions

Reference

Props

renderItem

Default renderer for every item in every section. Can be over-ridden on a per-section basis. Should return a React element.

TypeRequired
functionYes

The render function will be passed an object with the following keys:

  • 'item' (object) - the item object as specified in this section's data key
  • 'index' (number) - Item's index within the section.
  • 'section' (object) - The full section object as specified in sections.
  • 'separators' (object) - An object with the following keys:
    • 'highlight' (function) - () => void
    • 'unhighlight' (function) - () => void
    • 'updateProps' (function) - (select, newProps) => void
      • 'select' (enum) - possible values are 'leading', 'trailing'
      • 'newProps' (object)

sections

The actual data to render, akin to the data prop in FlatList.

TypeRequired
array of SectionsYes

extraData

A marker property for telling the list to re-render (since it implements PureComponent). If any of your renderItem, Header, Footer, etc. functions depend on anything outside of the data prop, stick it here and treat it immutably.

TypeRequired
anyNo

initialNumToRender

How many items to render in the initial batch. This should be enough to fill the screen but not much more. Note these items will never be unmounted as part of the windowed rendering in order to improve perceived performance of scroll-to-top actions.

TypeRequired
numberYes

inverted

Reverses the direction of scroll. Uses scale transforms of -1.

TypeRequired
[boolean]No

ItemSeparatorComponent

Rendered in between each item, but not at the top or bottom. By default, highlighted, section, and [leading/trailing][Item/Section] props are provided. renderItem provides separators.highlight/unhighlight which will update the highlighted prop, but you can also add custom props with separators.updateProps.

TypeRequired
[component, element]No

keyExtractor

Used to extract a unique key for a given item at the specified index. Key is used for caching and as the React key to track item re-ordering. The default extractor checks item.key, then falls back to using the index, like React does. Note that this sets keys for each item, but each overall section still needs its own key.

TypeRequired
(item: Item, index: number) => stringYes

legacyImplementation

The legacy implementation is no longer supported.

TypeRequired
[boolean]No

ListEmptyComponent

Rendered when the list is empty. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
[component, element]No

ListFooterComponent

Rendered at the very end of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
[component, element]No

ListHeaderComponent

Rendered at the very beginning of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
component, elementNo

onEndReached

Called once when the scroll position gets within onEndReachedThreshold of the rendered content.

TypeRequired
[(info: {distanceFromEnd: number}) => void]No

onEndReachedThreshold

How far from the end (in units of visible length of the list) the bottom edge of the list must be from the end of the content to trigger the onEndReached callback. Thus a value of 0.5 will trigger onEndReached when the end of the content is within half the visible length of the list.

TypeRequired
[number]No

onRefresh

If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the refreshing prop correctly. To offset the RefreshControl from the top (e.g. by 100 pts), use progressViewOffset={100}.

TypeRequired
[() => void]No

onViewableItemsChanged

Called when the viewability of rows changes, as defined by the viewabilityConfig prop.

TypeRequired
functionNo

The function will be passed an object with the following keys:

  • 'viewableItems' (array of ViewTokens)
  • 'changed' (array of ViewTokens)

The ViewToken type is exported by ViewabilityHelper.js:

NameTypeRequired
itemanyYes
keystringYes
indexnumberNo
isViewablebooleanYes
sectionanyNo

refreshing

Set this true while waiting for new data from a refresh.

TypeRequired
[boolean]No

removeClippedSubviews

Note: may have bugs (missing content) in some circumstances - use at your own risk.

This may improve scroll performance for large lists.

TypeRequired
booleanNo

renderSectionFooter

Rendered at the bottom of each section.

TypeRequired
[(info: {section: SectionT}) => ?React.Element<any>]No

renderSectionHeader

Rendered at the top of each section. These stick to the top of the ScrollView by default on iOS. See stickySectionHeadersEnabled.

TypeRequired
[(info: {section: SectionT}) => ?React.Element<any>]No

SectionSeparatorComponent

Rendered at the top and bottom of each section (note this is different from ItemSeparatorComponent which is only rendered between items). These are intended to separate sections from the headers above and below and typically have the same highlight response as ItemSeparatorComponent. Also receives highlighted, [leading/trailing][Item/Section], and any custom props from separators.updateProps.

TypeRequired
[ReactClass<any>]No

stickySectionHeadersEnabled

Makes section headers stick to the top of the screen until the next one pushes it off. Only enabled by default on iOS because that is the platform standard there.

TypeRequired
booleanNo

Methods

scrollToLocation()

scrollToLocation(params);

Scrolls to the item at the specified sectionIndex and itemIndex (within the section) positioned in the viewable area such that viewPosition 0 places it at the top (and may be covered by a sticky header), 1 at the bottom, and 0.5 centered in the middle.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout or onScrollToIndexFailed prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.
  • 'itemIndex' (number) - Index within section for the item to scroll to. Required.
  • 'sectionIndex' (number) - Index for section that contains the item to scroll to. Required.
  • 'viewOffset' (number) - A fixed number of pixels to offset the final target position, e.g. to compensate for sticky headers.
  • 'viewPosition' (number) - A value of 0 places the item specified by index at the top, 1 at the bottom, and 0.5 centered in the middle.

recordInteraction()

recordInteraction();

Tells the list an interaction has occurred, 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()

flashScrollIndicators();

Displays the scroll indicators momentarily.

Platfrom
iOS

Type Definitions

Section

An object that identifies the data to be rendered for a given section.

Type
any

Properties:

NameTypeDescription
dataarrayThe data for rendering items in this section. Array of objects, much like FlatList's data prop.
[key]stringOptional key to keep track of section re-ordering. If you don't plan on re-ordering sections, the array index will be used by default.
[renderItem]functionOptionally define an arbitrary item renderer for this section, overriding the default renderItem for the list.
[ItemSeparatorComponent]component, elementOptionally define an arbitrary item separator for this section, overriding the default ItemSeparatorComponent for the list.
[keyExtractor]functionOptionally define an arbitrary key extractor for this section, overriding the default keyExtractor.
Edit this page
Last updated on
- + diff --git a/docs/0.60/segmentedcontrolios.html b/docs/0.60/segmentedcontrolios.html index 540d059d7ee..78145641943 100644 --- a/docs/0.60/segmentedcontrolios.html +++ b/docs/0.60/segmentedcontrolios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

SegmentedControlIOS

Deprecated. Use @react-native-community/segmented-control instead.

Uses SegmentedControlIOS to render a UISegmentedControl iOS.

Programmatically changing selected index

The selected index can be changed on the fly by assigning the selectedIndex prop to a state variable, then changing that variable. Note that the state variable would need to be updated as the user selects a value and changes the index, as shown in the example below.

Example

Reference

Props

Inherits View Props.

enabled

If false the user won't be able to interact with the control. Default value is true.

TypeRequired
boolNo

momentary

If true, then selecting a segment won't persist visually. The onValueChange callback will still work as expected.

TypeRequired
boolNo

onChange

Callback that is called when the user taps a segment; passes the event as an argument

TypeRequired
functionNo

onValueChange

Callback that is called when the user taps a segment; passes the segment's value as an argument

TypeRequired
functionNo

selectedIndex

The index in props.values of the segment to be (pre)selected.

TypeRequired
numberNo

tintColor

Accent color of the control.

TypeRequired
stringNo

values

The labels for the control's segment buttons, in order.

TypeRequired
array of stringNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/segmentedcontrolios/index.html b/docs/0.60/segmentedcontrolios/index.html index 540d059d7ee..78145641943 100644 --- a/docs/0.60/segmentedcontrolios/index.html +++ b/docs/0.60/segmentedcontrolios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

SegmentedControlIOS

Deprecated. Use @react-native-community/segmented-control instead.

Uses SegmentedControlIOS to render a UISegmentedControl iOS.

Programmatically changing selected index

The selected index can be changed on the fly by assigning the selectedIndex prop to a state variable, then changing that variable. Note that the state variable would need to be updated as the user selects a value and changes the index, as shown in the example below.

Example

Reference

Props

Inherits View Props.

enabled

If false the user won't be able to interact with the control. Default value is true.

TypeRequired
boolNo

momentary

If true, then selecting a segment won't persist visually. The onValueChange callback will still work as expected.

TypeRequired
boolNo

onChange

Callback that is called when the user taps a segment; passes the event as an argument

TypeRequired
functionNo

onValueChange

Callback that is called when the user taps a segment; passes the segment's value as an argument

TypeRequired
functionNo

selectedIndex

The index in props.values of the segment to be (pre)selected.

TypeRequired
numberNo

tintColor

Accent color of the control.

TypeRequired
stringNo

values

The labels for the control's segment buttons, in order.

TypeRequired
array of stringNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/settings.html b/docs/0.60/settings.html index 144008fab02..67592720d1d 100644 --- a/docs/0.60/settings.html +++ b/docs/0.60/settings.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Settings

Settings serves as a wrapper for NSUserDefaults, a persistent key-value store available only on iOS.

Reference

Methods

clearWatch()

static clearWatch(watchId)

watchId is the number returned by watchKeys() when the subscription was originally configured.

get()

static get(key)

Get the current value for a key in NSUserDefaults.

set()

static set(settings)

Set one or more values in NSUserDefaults.

watchKeys()

static watchKeys(keys, callback)

Subscribe to be notified when the value for any of the keys specified by the keys array changes in NSUserDefaults. Returns a watchId number that may be used with clearWatch() to unsubscribe.

Edit this page
Last updated on
- + diff --git a/docs/0.60/settings/index.html b/docs/0.60/settings/index.html index 144008fab02..67592720d1d 100644 --- a/docs/0.60/settings/index.html +++ b/docs/0.60/settings/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Settings

Settings serves as a wrapper for NSUserDefaults, a persistent key-value store available only on iOS.

Reference

Methods

clearWatch()

static clearWatch(watchId)

watchId is the number returned by watchKeys() when the subscription was originally configured.

get()

static get(key)

Get the current value for a key in NSUserDefaults.

set()

static set(settings)

Set one or more values in NSUserDefaults.

watchKeys()

static watchKeys(keys, callback)

Subscribe to be notified when the value for any of the keys specified by the keys array changes in NSUserDefaults. Returns a watchId number that may be used with clearWatch() to unsubscribe.

Edit this page
Last updated on
- + diff --git a/docs/0.60/shadow-props.html b/docs/0.60/shadow-props.html index 8bf4dcd0688..db893645099 100644 --- a/docs/0.60/shadow-props.html +++ b/docs/0.60/shadow-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Shadow Props

Reference

Props

shadowColor

Sets the drop shadow color

TypeRequiredPlatform
colorNoiOS

shadowOffset

Sets the drop shadow offset

TypeRequiredPlatform
object: {width: number,height: number}NoiOS

shadowOpacity

Sets the drop shadow opacity (multiplied by the color's alpha component)

TypeRequiredPlatform
numberNoiOS

shadowRadius

Sets the drop shadow blur radius

TypeRequiredPlatform
numberNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.60/shadow-props/index.html b/docs/0.60/shadow-props/index.html index 8bf4dcd0688..db893645099 100644 --- a/docs/0.60/shadow-props/index.html +++ b/docs/0.60/shadow-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Shadow Props

Reference

Props

shadowColor

Sets the drop shadow color

TypeRequiredPlatform
colorNoiOS

shadowOffset

Sets the drop shadow offset

TypeRequiredPlatform
object: {width: number,height: number}NoiOS

shadowOpacity

Sets the drop shadow opacity (multiplied by the color's alpha component)

TypeRequiredPlatform
numberNoiOS

shadowRadius

Sets the drop shadow blur radius

TypeRequiredPlatform
numberNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.60/share.html b/docs/0.60/share.html index e004ebd5b35..e6096d826df 100644 --- a/docs/0.60/share.html +++ b/docs/0.60/share.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
render() {
return <Button onPress={this.onShare} title="Share" />;
}
}
Edit this page
Last updated on
- + diff --git a/docs/0.60/share/index.html b/docs/0.60/share/index.html index e004ebd5b35..e6096d826df 100644 --- a/docs/0.60/share/index.html +++ b/docs/0.60/share/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
render() {
return <Button onPress={this.onShare} title="Share" />;
}
}
Edit this page
Last updated on
- + diff --git a/docs/0.60/signed-apk-android.html b/docs/0.60/signed-apk-android.html index 02c65a40d31..8c05ca067d4 100644 --- a/docs/0.60/signed-apk-android.html +++ b/docs/0.60/signed-apk-android.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Publishing to Google Play Store

Android requires that all apps be digitally signed with a certificate before they can be installed. In order to distribute your Android application via Google Play store it needs to be signed with a release key that then needs to be used for all future updates. Since 2017 it is possible for Google Play to manage signing releases automatically thanks to App Signing by Google Play functionality. However, before your application binary is uploaded to Google Play it needs to be signed with an upload key. The Signing Your Applications page on Android Developers documentation describes the topic in detail. This guide covers the process in brief, as well as lists the steps required to package the JavaScript bundle.

Generating an upload key

You can generate a private signing key using keytool. On Windows keytool must be run from C:\Program Files\Java\jdkx.x.x_x\bin.

$ keytool -genkeypair -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

This command prompts you for passwords for the keystore and key and for the Distinguished Name fields for your key. It then generates the keystore as a file called my-upload-key.keystore.

The keystore contains a single key, valid for 10000 days. The alias is a name that you will use later when signing your app, so remember to take note of the alias.

On Mac, if you're not sure where your JDK bin folder is, then perform the following command to find it:

$ /usr/libexec/java_home

It will output the directory of the JDK, which will look something like this:

/Library/Java/JavaVirtualMachines/jdkX.X.X_XXX.jdk/Contents/Home

Navigate to that directory by using the command $ cd /your/jdk/path and use the keytool command with sudo permission as shown below.

$ sudo keytool -genkey -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

Note: Remember to keep the keystore file private. In case you've lost upload key or it's been compromised you should follow these instructions.

Setting up Gradle variables

  1. Place the my-upload-key.keystore file under the android/app directory in your project folder.
  2. Edit the file ~/.gradle/gradle.properties or android/gradle.properties, and add the following (replace ***** with the correct keystore password, alias and key password),
MYAPP_UPLOAD_STORE_FILE=my-upload-key.keystore
MYAPP_UPLOAD_KEY_ALIAS=my-key-alias
MYAPP_UPLOAD_STORE_PASSWORD=*****
MYAPP_UPLOAD_KEY_PASSWORD=*****

These are going to be global Gradle variables, which we can later use in our Gradle config to sign our app.

Note about security: If you are not keen on storing your passwords in plaintext, and you are running OSX, you can also store your credentials in the Keychain Access app. Then you can skip the two last rows in ~/.gradle/gradle.properties.

Adding signing config to your app's Gradle config

The last configuration step that needs to be done is to setup release builds to be signed using upload key. Edit the file android/app/build.gradle in your project folder, and add the signing config,

...
android {
...
defaultConfig { ... }
signingConfigs {
release {
if (project.hasProperty('MYAPP_UPLOAD_STORE_FILE')) {
storeFile file(MYAPP_UPLOAD_STORE_FILE)
storePassword MYAPP_UPLOAD_STORE_PASSWORD
keyAlias MYAPP_UPLOAD_KEY_ALIAS
keyPassword MYAPP_UPLOAD_KEY_PASSWORD
}
}
}
buildTypes {
release {
...
signingConfig signingConfigs.release
}
}
}
...

Generating the release APK

Run the following in a terminal:

$ cd android
$ ./gradlew bundleRelease

Gradle's bundleRelease will bundle all the JavaScript needed to run your app into the AAB (Android App Bundle). If you need to change the way the JavaScript bundle and/or drawable resources are bundled (e.g. if you changed the default file/folder names or the general structure of the project), have a look at android/app/build.gradle to see how you can update it to reflect these changes.

Note: Make sure gradle.properties does not include org.gradle.configureondemand=true as that will make the release build skip bundling JS and assets into the app binary.

The generated AAB can be found under android/app/build/outputs/bundle/release/app.aab, and is ready to be uploaded to Google Play.

Note: In order for Google Play to accept AAB format the App Signing by Google Play needs to be configured for your application on the Google Play Console. If you are updating an existing app that doesn't use App Signing by Google Play, please check our migration section to learn how to perform that configuration change.

Testing the release build of your app

Before uploading the release build to the Play Store, make sure you test it thoroughly. First uninstall any previous version of the app you already have installed. Install it on the device using:

$ react-native run-android --variant=release

Note that --variant=release is only available if you've set up signing as described above.

You can terminate any running bundler instances, since all your framework and JavaScript code is bundled in the APK's assets.

Publishing to other stores

By default, the generated APK has the native code for both x86 and ARMv7a CPU architectures. This makes it easier to share APKs that run on almost all Android devices. However, this has the downside that there will be some unused native code on any device, leading to unnecessarily bigger APKs.

You can create an APK for each CPU by changing the following line in android/app/build.gradle:

- ndk {
- abiFilters "armeabi-v7a", "x86"
- }
- def enableSeparateBuildPerCPUArchitecture = false
+ def enableSeparateBuildPerCPUArchitecture = true

Upload both these files to markets which support device targeting, such as Google Play and Amazon AppStore, and the users will automatically get the appropriate APK. If you want to upload to other markets, such as APKFiles, which do not support multiple APKs for a single app, change the following line as well to create the default universal APK with binaries for both CPUs.

- universalApk false // If true, also generate a universal APK
+ universalApk true // If true, also generate a universal APK

Enabling Proguard to reduce the size of the APK (optional)

Proguard is a tool that can slightly reduce the size of the APK. It does this by stripping parts of the React Native Java bytecode (and its dependencies) that your app is not using.

IMPORTANT: Make sure to thoroughly test your app if you've enabled Proguard. Proguard often requires configuration specific to each native library you're using. See app/proguard-rules.pro.

To enable Proguard, edit android/app/build.gradle:

/**
* Run Proguard to shrink the Java bytecode in release builds.
*/
def enableProguardInReleaseBuilds = true

Migrating old Android React Native apps to use App Signing by Google Play

If you are migrating from previous version of React Native chances are your app does not use App Signing by Google Play feature. We recommend you enable that in order to take advantage from things like automatic app splitting. In order to migrate from the old way of signing you need to start by generating new upload key and then replacing release signing config in android/app/build.gradle to use the upload key instead of the release one (see section about adding signing config to gradle). Once that's done you should follow the instructions from Google Play Help website in order to send your original release key to Google Play.

Edit this page
Last updated on
- + diff --git a/docs/0.60/signed-apk-android/index.html b/docs/0.60/signed-apk-android/index.html index 02c65a40d31..8c05ca067d4 100644 --- a/docs/0.60/signed-apk-android/index.html +++ b/docs/0.60/signed-apk-android/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Publishing to Google Play Store

Android requires that all apps be digitally signed with a certificate before they can be installed. In order to distribute your Android application via Google Play store it needs to be signed with a release key that then needs to be used for all future updates. Since 2017 it is possible for Google Play to manage signing releases automatically thanks to App Signing by Google Play functionality. However, before your application binary is uploaded to Google Play it needs to be signed with an upload key. The Signing Your Applications page on Android Developers documentation describes the topic in detail. This guide covers the process in brief, as well as lists the steps required to package the JavaScript bundle.

Generating an upload key

You can generate a private signing key using keytool. On Windows keytool must be run from C:\Program Files\Java\jdkx.x.x_x\bin.

$ keytool -genkeypair -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

This command prompts you for passwords for the keystore and key and for the Distinguished Name fields for your key. It then generates the keystore as a file called my-upload-key.keystore.

The keystore contains a single key, valid for 10000 days. The alias is a name that you will use later when signing your app, so remember to take note of the alias.

On Mac, if you're not sure where your JDK bin folder is, then perform the following command to find it:

$ /usr/libexec/java_home

It will output the directory of the JDK, which will look something like this:

/Library/Java/JavaVirtualMachines/jdkX.X.X_XXX.jdk/Contents/Home

Navigate to that directory by using the command $ cd /your/jdk/path and use the keytool command with sudo permission as shown below.

$ sudo keytool -genkey -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

Note: Remember to keep the keystore file private. In case you've lost upload key or it's been compromised you should follow these instructions.

Setting up Gradle variables

  1. Place the my-upload-key.keystore file under the android/app directory in your project folder.
  2. Edit the file ~/.gradle/gradle.properties or android/gradle.properties, and add the following (replace ***** with the correct keystore password, alias and key password),
MYAPP_UPLOAD_STORE_FILE=my-upload-key.keystore
MYAPP_UPLOAD_KEY_ALIAS=my-key-alias
MYAPP_UPLOAD_STORE_PASSWORD=*****
MYAPP_UPLOAD_KEY_PASSWORD=*****

These are going to be global Gradle variables, which we can later use in our Gradle config to sign our app.

Note about security: If you are not keen on storing your passwords in plaintext, and you are running OSX, you can also store your credentials in the Keychain Access app. Then you can skip the two last rows in ~/.gradle/gradle.properties.

Adding signing config to your app's Gradle config

The last configuration step that needs to be done is to setup release builds to be signed using upload key. Edit the file android/app/build.gradle in your project folder, and add the signing config,

...
android {
...
defaultConfig { ... }
signingConfigs {
release {
if (project.hasProperty('MYAPP_UPLOAD_STORE_FILE')) {
storeFile file(MYAPP_UPLOAD_STORE_FILE)
storePassword MYAPP_UPLOAD_STORE_PASSWORD
keyAlias MYAPP_UPLOAD_KEY_ALIAS
keyPassword MYAPP_UPLOAD_KEY_PASSWORD
}
}
}
buildTypes {
release {
...
signingConfig signingConfigs.release
}
}
}
...

Generating the release APK

Run the following in a terminal:

$ cd android
$ ./gradlew bundleRelease

Gradle's bundleRelease will bundle all the JavaScript needed to run your app into the AAB (Android App Bundle). If you need to change the way the JavaScript bundle and/or drawable resources are bundled (e.g. if you changed the default file/folder names or the general structure of the project), have a look at android/app/build.gradle to see how you can update it to reflect these changes.

Note: Make sure gradle.properties does not include org.gradle.configureondemand=true as that will make the release build skip bundling JS and assets into the app binary.

The generated AAB can be found under android/app/build/outputs/bundle/release/app.aab, and is ready to be uploaded to Google Play.

Note: In order for Google Play to accept AAB format the App Signing by Google Play needs to be configured for your application on the Google Play Console. If you are updating an existing app that doesn't use App Signing by Google Play, please check our migration section to learn how to perform that configuration change.

Testing the release build of your app

Before uploading the release build to the Play Store, make sure you test it thoroughly. First uninstall any previous version of the app you already have installed. Install it on the device using:

$ react-native run-android --variant=release

Note that --variant=release is only available if you've set up signing as described above.

You can terminate any running bundler instances, since all your framework and JavaScript code is bundled in the APK's assets.

Publishing to other stores

By default, the generated APK has the native code for both x86 and ARMv7a CPU architectures. This makes it easier to share APKs that run on almost all Android devices. However, this has the downside that there will be some unused native code on any device, leading to unnecessarily bigger APKs.

You can create an APK for each CPU by changing the following line in android/app/build.gradle:

- ndk {
- abiFilters "armeabi-v7a", "x86"
- }
- def enableSeparateBuildPerCPUArchitecture = false
+ def enableSeparateBuildPerCPUArchitecture = true

Upload both these files to markets which support device targeting, such as Google Play and Amazon AppStore, and the users will automatically get the appropriate APK. If you want to upload to other markets, such as APKFiles, which do not support multiple APKs for a single app, change the following line as well to create the default universal APK with binaries for both CPUs.

- universalApk false // If true, also generate a universal APK
+ universalApk true // If true, also generate a universal APK

Enabling Proguard to reduce the size of the APK (optional)

Proguard is a tool that can slightly reduce the size of the APK. It does this by stripping parts of the React Native Java bytecode (and its dependencies) that your app is not using.

IMPORTANT: Make sure to thoroughly test your app if you've enabled Proguard. Proguard often requires configuration specific to each native library you're using. See app/proguard-rules.pro.

To enable Proguard, edit android/app/build.gradle:

/**
* Run Proguard to shrink the Java bytecode in release builds.
*/
def enableProguardInReleaseBuilds = true

Migrating old Android React Native apps to use App Signing by Google Play

If you are migrating from previous version of React Native chances are your app does not use App Signing by Google Play feature. We recommend you enable that in order to take advantage from things like automatic app splitting. In order to migrate from the old way of signing you need to start by generating new upload key and then replacing release signing config in android/app/build.gradle to use the upload key instead of the release one (see section about adding signing config to gradle). Once that's done you should follow the instructions from Google Play Help website in order to send your original release key to Google Play.

Edit this page
Last updated on
- + diff --git a/docs/0.60/slider.html b/docs/0.60/slider.html index 03d4ff33db0..daf7b6e77f8 100644 --- a/docs/0.60/slider.html +++ b/docs/0.60/slider.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Slider

Deprecated. Use react-native-community/react-native-slider instead.

A component used to select a single value from a range of values.

Reference

Props

Inherits View Props.

style

Used to style and layout the Slider. See StyleSheet.js and ViewStylePropTypes.js for more info.

TypeRequired
View.styleNo

disabled

If true the user won't be able to move the slider. Default value is false.

TypeRequired
boolNo

maximumValue

Initial maximum value of the slider. Default value is 1.

TypeRequired
numberNo

minimumTrackTintColor

The color used for the track to the left of the button. Overrides the default blue gradient image on iOS.

TypeRequired
colorNo

minimumValue

Initial minimum value of the slider. Default value is 0.

TypeRequired
numberNo

onSlidingComplete

Callback that is called when the user releases the slider, regardless if the value has changed. The current value is passed as an argument to the callback handler.

TypeRequired
functionNo

onValueChange

Callback continuously called while the user is dragging the slider.

TypeRequired
functionNo

step

Step value of the slider. The value should be between 0 and (maximumValue - minimumValue). Default value is 0.

TypeRequired
numberNo

maximumTrackTintColor

The color used for the track to the right of the button. Overrides the default gray gradient image on iOS.

TypeRequired
colorNo

testID

Used to locate this view in UI automation tests.

TypeRequired
stringNo

value

Initial value of the slider. The value should be between minimumValue and maximumValue, which default to 0 and 1 respectively. Default value is 0.

This is not a controlled component, you don't need to update the value during dragging.

TypeRequired
numberNo

thumbTintColor

The color used to tint the default thumb images on iOS, or the color of the foreground switch grip on Android.

TypeRequired
colorNo

maximumTrackImage

Assigns a maximum track image. Only static images are supported. The leftmost pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

minimumTrackImage

Assigns a minimum track image. Only static images are supported. The rightmost pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

thumbImage

Sets an image for the thumb. Only static images are supported.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

trackImage

Assigns a single image for the track. Only static images are supported. The center pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.60/slider/index.html b/docs/0.60/slider/index.html index 03d4ff33db0..daf7b6e77f8 100644 --- a/docs/0.60/slider/index.html +++ b/docs/0.60/slider/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Slider

Deprecated. Use react-native-community/react-native-slider instead.

A component used to select a single value from a range of values.

Reference

Props

Inherits View Props.

style

Used to style and layout the Slider. See StyleSheet.js and ViewStylePropTypes.js for more info.

TypeRequired
View.styleNo

disabled

If true the user won't be able to move the slider. Default value is false.

TypeRequired
boolNo

maximumValue

Initial maximum value of the slider. Default value is 1.

TypeRequired
numberNo

minimumTrackTintColor

The color used for the track to the left of the button. Overrides the default blue gradient image on iOS.

TypeRequired
colorNo

minimumValue

Initial minimum value of the slider. Default value is 0.

TypeRequired
numberNo

onSlidingComplete

Callback that is called when the user releases the slider, regardless if the value has changed. The current value is passed as an argument to the callback handler.

TypeRequired
functionNo

onValueChange

Callback continuously called while the user is dragging the slider.

TypeRequired
functionNo

step

Step value of the slider. The value should be between 0 and (maximumValue - minimumValue). Default value is 0.

TypeRequired
numberNo

maximumTrackTintColor

The color used for the track to the right of the button. Overrides the default gray gradient image on iOS.

TypeRequired
colorNo

testID

Used to locate this view in UI automation tests.

TypeRequired
stringNo

value

Initial value of the slider. The value should be between minimumValue and maximumValue, which default to 0 and 1 respectively. Default value is 0.

This is not a controlled component, you don't need to update the value during dragging.

TypeRequired
numberNo

thumbTintColor

The color used to tint the default thumb images on iOS, or the color of the foreground switch grip on Android.

TypeRequired
colorNo

maximumTrackImage

Assigns a maximum track image. Only static images are supported. The leftmost pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

minimumTrackImage

Assigns a minimum track image. Only static images are supported. The rightmost pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

thumbImage

Sets an image for the thumb. Only static images are supported.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

trackImage

Assigns a single image for the track. Only static images are supported. The center pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.60/snapshotviewios.html b/docs/0.60/snapshotviewios.html index 0c1ac69709b..ba16031b124 100644 --- a/docs/0.60/snapshotviewios.html +++ b/docs/0.60/snapshotviewios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.60/snapshotviewios/index.html b/docs/0.60/snapshotviewios/index.html index 0c1ac69709b..ba16031b124 100644 --- a/docs/0.60/snapshotviewios/index.html +++ b/docs/0.60/snapshotviewios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.60/state.html b/docs/0.60/state.html index c71ce355164..39aca01324c 100644 --- a/docs/0.60/state.html +++ b/docs/0.60/state.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

State

There are two types of data that control a component: props and state. props are set by the parent and they are fixed throughout the lifetime of a component. For data that is going to change, we have to use state.

In general, you should initialize state in the constructor, and then call setState when you want to change it.

For example, let's say we want to make text that blinks all the time. The text itself gets set once when the blinking component gets created, so the text itself is a prop. The "whether the text is currently on or off" changes over time, so that should be kept in state.

In a real application, you probably won't be setting state with a timer. You might set state when you have new data from the server, or from user input. You can also use a state container like Redux or Mobx to control your data flow. In that case you would use Redux or Mobx to modify your state rather than calling setState directly.

When setState is called, BlinkApp will re-render its Component. By calling setState within the Timer, the component will re-render every time the Timer ticks.

State works the same way as it does in React, so for more details on handling state, you can look at the React.Component API. At this point, you might be annoyed that most of our examples so far use the default text color. To customize the text color, you will have to learn about Style.

Edit this page
Last updated on
- + diff --git a/docs/0.60/state/index.html b/docs/0.60/state/index.html index c71ce355164..39aca01324c 100644 --- a/docs/0.60/state/index.html +++ b/docs/0.60/state/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

State

There are two types of data that control a component: props and state. props are set by the parent and they are fixed throughout the lifetime of a component. For data that is going to change, we have to use state.

In general, you should initialize state in the constructor, and then call setState when you want to change it.

For example, let's say we want to make text that blinks all the time. The text itself gets set once when the blinking component gets created, so the text itself is a prop. The "whether the text is currently on or off" changes over time, so that should be kept in state.

In a real application, you probably won't be setting state with a timer. You might set state when you have new data from the server, or from user input. You can also use a state container like Redux or Mobx to control your data flow. In that case you would use Redux or Mobx to modify your state rather than calling setState directly.

When setState is called, BlinkApp will re-render its Component. By calling setState within the Timer, the component will re-render every time the Timer ticks.

State works the same way as it does in React, so for more details on handling state, you can look at the React.Component API. At this point, you might be annoyed that most of our examples so far use the default text color. To customize the text color, you will have to learn about Style.

Edit this page
Last updated on
- + diff --git a/docs/0.60/statusbar.html b/docs/0.60/statusbar.html index f77114fcf28..383df4bbb60 100644 --- a/docs/0.60/statusbar.html +++ b/docs/0.60/statusbar.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

StatusBar

Component to control the app status bar.

Usage with Navigator

It is possible to have multiple StatusBar components mounted at the same time. The props will be merged in the order the StatusBar components were mounted.

<View>
<StatusBar backgroundColor="blue" barStyle="light-content" />
<View>
<StatusBar hidden={route.statusBarHidden} />
...
</View>
</View>

Imperative API

For cases where using a component is not ideal, there is also an imperative API exposed as static functions on the component. It is however not recommended to use the static API and the component for the same prop because any value set by the static API will get overridden by the one set by the component in the next render.

Reference

Constants

currentHeight (Android only) The height of the status bar.

Props

animated

If the transition between status bar property changes should be animated. Supported for backgroundColor, barStyle and hidden.

TypeRequired
boolNo

backgroundColor

The background color of the status bar.

TypeRequiredPlatform
colorNoAndroid

barStyle

Sets the color of the status bar text.

TypeRequired
enum('default', 'light-content', 'dark-content')No

hidden

If the status bar is hidden.

TypeRequired
boolNo

networkActivityIndicatorVisible

If the network activity indicator should be visible.

TypeRequiredPlatform
boolNoiOS

showHideTransition

The transition effect when showing and hiding the status bar using the hidden prop. Defaults to 'fade'.

TypeRequiredPlatform
enum('fade', 'slide')NoiOS

translucent

If the status bar is translucent. When translucent is set to true, the app will draw under the status bar. This is useful when using a semi transparent status bar color.

TypeRequiredPlatform
boolNoAndroid

Methods

popStackEntry()

static popStackEntry(entry: any)

Get and remove the last a StatusBar entry from the stack.

Parameters:

NameTypeRequiredDescription
entryanyYesEntry returned from pushStackEntry.

pushStackEntry()

static pushStackEntry(props: any)

Push a StatusBar entry onto the stack. The return value should be passed to popStackEntry when complete.

Parameters:

NameTypeRequiredDescription
propsanyYesObject containing the StatusBar props to use in the stack entry.

replaceStackEntry()

static replaceStackEntry(entry: any, props: any)

Replace an existing StatusBar stack entry with new props.

Parameters:

NameTypeRequiredDescription
entryanyYesEntry returned from pushStackEntry to replace.
propsanyYesObject containing the StatusBar props to use in the replacement stack entry.

setBackgroundColor()

static setBackgroundColor(color: string, [animated]: boolean)

Set the background color for the status bar. Android-only

Parameters:

NameTypeRequiredDescription
colorstringYesBackground color.
animatedbooleanNoAnimate the style change.

setBarStyle()

static setBarStyle(style: StatusBarStyle, [animated]: boolean)

Set the status bar style

Parameters:

NameTypeRequiredDescription
styleStatusBarStyleYesStatus bar style to set
animatedbooleanNoAnimate the style change.

setHidden()

static setHidden(hidden: boolean, [animation]: StatusBarAnimation)

Show or hide the status bar

Parameters:

NameTypeRequiredDescription
hiddenbooleanYesHide the status bar.
animationStatusBarAnimationNoOptional animation when changing the status bar hidden property.

setNetworkActivityIndicatorVisible()

static setNetworkActivityIndicatorVisible(visible: boolean)

Control the visibility of the network activity indicator. iOS-only.

Parameters:

NameTypeRequiredDescription
visiblebooleanYesShow the indicator.

setTranslucent()

static setTranslucent(translucent: boolean)

Control the translucency of the status bar. Android-only.

Parameters:

NameTypeRequiredDescription
translucentbooleanYesSet as translucent.

Type Definitions

StatusBarAnimation

Status bar animation

Type
\$Enum

Constants:

ValueDescription
noneNo animation
fadeFade animation
slideSlide animation

StatusBarStyle

Status bar style

Type
\$Enum

Constants:

ValueDescription
defaultDefault status bar style (dark for iOS, light for Android)
light-contentDark background, white texts and icons
dark-contentLight background, dark texts and icons (requires API>=23 on Android)
Edit this page
Last updated on
- + diff --git a/docs/0.60/statusbar/index.html b/docs/0.60/statusbar/index.html index f77114fcf28..383df4bbb60 100644 --- a/docs/0.60/statusbar/index.html +++ b/docs/0.60/statusbar/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

StatusBar

Component to control the app status bar.

Usage with Navigator

It is possible to have multiple StatusBar components mounted at the same time. The props will be merged in the order the StatusBar components were mounted.

<View>
<StatusBar backgroundColor="blue" barStyle="light-content" />
<View>
<StatusBar hidden={route.statusBarHidden} />
...
</View>
</View>

Imperative API

For cases where using a component is not ideal, there is also an imperative API exposed as static functions on the component. It is however not recommended to use the static API and the component for the same prop because any value set by the static API will get overridden by the one set by the component in the next render.

Reference

Constants

currentHeight (Android only) The height of the status bar.

Props

animated

If the transition between status bar property changes should be animated. Supported for backgroundColor, barStyle and hidden.

TypeRequired
boolNo

backgroundColor

The background color of the status bar.

TypeRequiredPlatform
colorNoAndroid

barStyle

Sets the color of the status bar text.

TypeRequired
enum('default', 'light-content', 'dark-content')No

hidden

If the status bar is hidden.

TypeRequired
boolNo

networkActivityIndicatorVisible

If the network activity indicator should be visible.

TypeRequiredPlatform
boolNoiOS

showHideTransition

The transition effect when showing and hiding the status bar using the hidden prop. Defaults to 'fade'.

TypeRequiredPlatform
enum('fade', 'slide')NoiOS

translucent

If the status bar is translucent. When translucent is set to true, the app will draw under the status bar. This is useful when using a semi transparent status bar color.

TypeRequiredPlatform
boolNoAndroid

Methods

popStackEntry()

static popStackEntry(entry: any)

Get and remove the last a StatusBar entry from the stack.

Parameters:

NameTypeRequiredDescription
entryanyYesEntry returned from pushStackEntry.

pushStackEntry()

static pushStackEntry(props: any)

Push a StatusBar entry onto the stack. The return value should be passed to popStackEntry when complete.

Parameters:

NameTypeRequiredDescription
propsanyYesObject containing the StatusBar props to use in the stack entry.

replaceStackEntry()

static replaceStackEntry(entry: any, props: any)

Replace an existing StatusBar stack entry with new props.

Parameters:

NameTypeRequiredDescription
entryanyYesEntry returned from pushStackEntry to replace.
propsanyYesObject containing the StatusBar props to use in the replacement stack entry.

setBackgroundColor()

static setBackgroundColor(color: string, [animated]: boolean)

Set the background color for the status bar. Android-only

Parameters:

NameTypeRequiredDescription
colorstringYesBackground color.
animatedbooleanNoAnimate the style change.

setBarStyle()

static setBarStyle(style: StatusBarStyle, [animated]: boolean)

Set the status bar style

Parameters:

NameTypeRequiredDescription
styleStatusBarStyleYesStatus bar style to set
animatedbooleanNoAnimate the style change.

setHidden()

static setHidden(hidden: boolean, [animation]: StatusBarAnimation)

Show or hide the status bar

Parameters:

NameTypeRequiredDescription
hiddenbooleanYesHide the status bar.
animationStatusBarAnimationNoOptional animation when changing the status bar hidden property.

setNetworkActivityIndicatorVisible()

static setNetworkActivityIndicatorVisible(visible: boolean)

Control the visibility of the network activity indicator. iOS-only.

Parameters:

NameTypeRequiredDescription
visiblebooleanYesShow the indicator.

setTranslucent()

static setTranslucent(translucent: boolean)

Control the translucency of the status bar. Android-only.

Parameters:

NameTypeRequiredDescription
translucentbooleanYesSet as translucent.

Type Definitions

StatusBarAnimation

Status bar animation

Type
\$Enum

Constants:

ValueDescription
noneNo animation
fadeFade animation
slideSlide animation

StatusBarStyle

Status bar style

Type
\$Enum

Constants:

ValueDescription
defaultDefault status bar style (dark for iOS, light for Android)
light-contentDark background, white texts and icons
dark-contentLight background, dark texts and icons (requires API>=23 on Android)
Edit this page
Last updated on
- + diff --git a/docs/0.60/statusbarios.html b/docs/0.60/statusbarios.html index 5e752f87ffd..72854d12cfc 100644 --- a/docs/0.60/statusbarios.html +++ b/docs/0.60/statusbarios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

StatusBarIOS

Use StatusBar for mutating the status bar.

Edit this page
Last updated on
- + diff --git a/docs/0.60/statusbarios/index.html b/docs/0.60/statusbarios/index.html index 5e752f87ffd..72854d12cfc 100644 --- a/docs/0.60/statusbarios/index.html +++ b/docs/0.60/statusbarios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

StatusBarIOS

Use StatusBar for mutating the status bar.

Edit this page
Last updated on
- + diff --git a/docs/0.60/style.html b/docs/0.60/style.html index 1753603d43d..dd8cffc0eca 100644 --- a/docs/0.60/style.html +++ b/docs/0.60/style.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Style

With React Native, you style your application using JavaScript. All of the core components accept a prop named style. The style names and values usually match how CSS works on the web, except names are written using camel casing, e.g. backgroundColor rather than background-color.

The style prop can be a plain old JavaScript object. That's the simplest and what we usually use for example code. You can also pass an array of styles - the last style in the array has precedence, so you can use this to inherit styles.

As a component grows in complexity, it is often cleaner to use StyleSheet.create to define several styles in one place. Here's an example:

One common pattern is to make your component accept a style prop which in turn is used to style subcomponents. You can use this to make styles "cascade" the way they do in CSS.

There are a lot more ways to customize text style. Check out the Text component reference for a complete list.

Now you can make your text beautiful. The next step in becoming a style expert is to learn how to control component size.

Edit this page
Last updated on
- + diff --git a/docs/0.60/style/index.html b/docs/0.60/style/index.html index 1753603d43d..dd8cffc0eca 100644 --- a/docs/0.60/style/index.html +++ b/docs/0.60/style/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Style

With React Native, you style your application using JavaScript. All of the core components accept a prop named style. The style names and values usually match how CSS works on the web, except names are written using camel casing, e.g. backgroundColor rather than background-color.

The style prop can be a plain old JavaScript object. That's the simplest and what we usually use for example code. You can also pass an array of styles - the last style in the array has precedence, so you can use this to inherit styles.

As a component grows in complexity, it is often cleaner to use StyleSheet.create to define several styles in one place. Here's an example:

One common pattern is to make your component accept a style prop which in turn is used to style subcomponents. You can use this to make styles "cascade" the way they do in CSS.

There are a lot more ways to customize text style. Check out the Text component reference for a complete list.

Now you can make your text beautiful. The next step in becoming a style expert is to learn how to control component size.

Edit this page
Last updated on
- + diff --git a/docs/0.60/stylesheet.html b/docs/0.60/stylesheet.html index 02fb72e8aba..1d1c48a1f95 100644 --- a/docs/0.60/stylesheet.html +++ b/docs/0.60/stylesheet.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
StyleSheet.flatten(styles.listItem);
// returns { flex: 1, fontSize: 16, color: 'white' }
// Simply styles.listItem would return its ID (number)

This method internally uses StyleSheetRegistry.getStyleByID(style) to resolve style objects represented by IDs. Thus, an array of style objects (instances of StyleSheet.create()), are individually resolved to, their respective objects, merged as one and then returned. This also explains the alternative use.

compose

Combines two styles such that style2 will override any styles in style1. If either style is falsy, the other one is returned without allocating an array, saving allocations and maintaining reference equality for PureComponent checks.

static compose(style1, style2)

Properties

hairlineWidth

This is defined as the width of a thin line on the platform. It can be used as the thickness of a border or division between two elements. Example:

var styles = StyleSheet.create({
separator: {
borderBottomColor: '#bbb',
borderBottomWidth: StyleSheet.hairlineWidth
}
});

This constant will always be a round number of pixels (so a line defined by it can look crisp) and will try to match the standard width of a thin line on the underlying platform. However, you should not rely on it being a constant size, because on different platforms and screen densities its value may be calculated differently.

A line with hairline width may not be visible if your simulator is downscaled.

absoluteFill

A very common pattern is to create overlays with position absolute and zero positioning (position: 'absolute', left: 0, right: 0, top: 0, bottom: 0), so absoluteFill can be used for convenience and to reduce duplication of these repeated styles. If you want, absoluteFill can be used to create a customized entry in a StyleSheet, e.g.:

const styles = StyleSheet.create({
wrapper: {
...StyleSheet.absoluteFill
}
});

absoluteFillObject

Sometimes you may want absoluteFill but with a couple tweaks - absoluteFillObject can be used to create a customized entry in a StyleSheet, e.g.:

const styles = StyleSheet.create({
wrapper: {
...StyleSheet.absoluteFillObject,
top: 10,
backgroundColor: 'transparent'
}
});

absoluteFill vs. absoluteFillObject

Currently, there is no difference between using absoluteFill vs. absoluteFillObject as you can see in the source code

Edit this page
Last updated on
- + diff --git a/docs/0.60/stylesheet/index.html b/docs/0.60/stylesheet/index.html index 02fb72e8aba..1d1c48a1f95 100644 --- a/docs/0.60/stylesheet/index.html +++ b/docs/0.60/stylesheet/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
StyleSheet.flatten(styles.listItem);
// returns { flex: 1, fontSize: 16, color: 'white' }
// Simply styles.listItem would return its ID (number)

This method internally uses StyleSheetRegistry.getStyleByID(style) to resolve style objects represented by IDs. Thus, an array of style objects (instances of StyleSheet.create()), are individually resolved to, their respective objects, merged as one and then returned. This also explains the alternative use.

compose

Combines two styles such that style2 will override any styles in style1. If either style is falsy, the other one is returned without allocating an array, saving allocations and maintaining reference equality for PureComponent checks.

static compose(style1, style2)

Properties

hairlineWidth

This is defined as the width of a thin line on the platform. It can be used as the thickness of a border or division between two elements. Example:

var styles = StyleSheet.create({
separator: {
borderBottomColor: '#bbb',
borderBottomWidth: StyleSheet.hairlineWidth
}
});

This constant will always be a round number of pixels (so a line defined by it can look crisp) and will try to match the standard width of a thin line on the underlying platform. However, you should not rely on it being a constant size, because on different platforms and screen densities its value may be calculated differently.

A line with hairline width may not be visible if your simulator is downscaled.

absoluteFill

A very common pattern is to create overlays with position absolute and zero positioning (position: 'absolute', left: 0, right: 0, top: 0, bottom: 0), so absoluteFill can be used for convenience and to reduce duplication of these repeated styles. If you want, absoluteFill can be used to create a customized entry in a StyleSheet, e.g.:

const styles = StyleSheet.create({
wrapper: {
...StyleSheet.absoluteFill
}
});

absoluteFillObject

Sometimes you may want absoluteFill but with a couple tweaks - absoluteFillObject can be used to create a customized entry in a StyleSheet, e.g.:

const styles = StyleSheet.create({
wrapper: {
...StyleSheet.absoluteFillObject,
top: 10,
backgroundColor: 'transparent'
}
});

absoluteFill vs. absoluteFillObject

Currently, there is no difference between using absoluteFill vs. absoluteFillObject as you can see in the source code

Edit this page
Last updated on
- + diff --git a/docs/0.60/switch.html b/docs/0.60/switch.html index 6f257ff7c7c..ba44c0fa9d3 100644 --- a/docs/0.60/switch.html +++ b/docs/0.60/switch.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Switch

Renders a boolean input.

This is a controlled component that requires an onValueChange callback that updates the value prop in order for the component to reflect user actions. If the value prop is not updated, the component will continue to render the supplied value prop instead of the expected result of any user actions.

Reference

Props

Inherits View Props.

disabled

If true the user won't be able to toggle the switch. Default value is false.

TypeRequired
boolNo

ios_backgroundColor

On iOS, custom color for the background. This background color can be seen either when the switch value is false or when the switch is disabled (and the switch is translucent).

TypeRequired
colorNo

onChange

Invoked when the user tries to change the value of the switch. Receives the change event as an argument. If you want to only receive the new value, use onValueChange instead.

TypeRequired
functionNo

onValueChange

Invoked when the user tries to change the value of the switch. Receives the new value as an argument. If you want to instead receive an event, use onChange.

TypeRequired
functionNo

thumbColor

Color of the foreground switch grip. If this is set on iOS, the switch grip will lose its drop shadow.

TypeRequired
colorNo

trackColor

Custom colors for the switch track.

iOS: When the switch value is false, the track shrinks into the border. If you want to change the color of the background exposed by the shrunken track, use ios_backgroundColor.

TypeRequired
object: {false: color, true: color}No

value

The value of the switch. If true the switch will be turned on. Default value is false.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/switch/index.html b/docs/0.60/switch/index.html index 6f257ff7c7c..ba44c0fa9d3 100644 --- a/docs/0.60/switch/index.html +++ b/docs/0.60/switch/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Switch

Renders a boolean input.

This is a controlled component that requires an onValueChange callback that updates the value prop in order for the component to reflect user actions. If the value prop is not updated, the component will continue to render the supplied value prop instead of the expected result of any user actions.

Reference

Props

Inherits View Props.

disabled

If true the user won't be able to toggle the switch. Default value is false.

TypeRequired
boolNo

ios_backgroundColor

On iOS, custom color for the background. This background color can be seen either when the switch value is false or when the switch is disabled (and the switch is translucent).

TypeRequired
colorNo

onChange

Invoked when the user tries to change the value of the switch. Receives the change event as an argument. If you want to only receive the new value, use onValueChange instead.

TypeRequired
functionNo

onValueChange

Invoked when the user tries to change the value of the switch. Receives the new value as an argument. If you want to instead receive an event, use onChange.

TypeRequired
functionNo

thumbColor

Color of the foreground switch grip. If this is set on iOS, the switch grip will lose its drop shadow.

TypeRequired
colorNo

trackColor

Custom colors for the switch track.

iOS: When the switch value is false, the track shrinks into the border. If you want to change the color of the background exposed by the shrunken track, use ios_backgroundColor.

TypeRequired
object: {false: color, true: color}No

value

The value of the switch. If true the switch will be turned on. Default value is false.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/symbolication.html b/docs/0.60/symbolication.html index 684bcc6cf41..610dafd3df2 100644 --- a/docs/0.60/symbolication.html +++ b/docs/0.60/symbolication.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Symbolicating a stack trace

If a React Native app throws an unhandled exception in a release build, the output may be obfuscated and hard to read:

07-15 10:58:25.820 18979 18998 E AndroidRuntime: FATAL EXCEPTION: mqt_native_modules
07-15 10:58:25.820 18979 18998 E AndroidRuntime: Process: com.awesomeproject, PID: 18979 07-15 10:58:25.820 18979 18998 E AndroidRuntime: com.facebook.react.common.JavascriptException: Failed, js engine: hermes, stack:
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132161
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132084
07-15 10:58:25.820 18979 18998 E AndroidRuntime: f@1:131854
07-15 10:58:25.820 18979 18998 E AndroidRuntime: anonymous@1:131119

The sections like p@1:132161 are minified function names and bytecode offsets. To debug the problem, you would instead want to translate it into file, line and function name: AwesomeProject/App.js:54:initializeMap. This is known as symbolication. You can symbolicate minified function names and bytecode like the above by passing metro-symbolicate a generated source map and the stack trace.

The metro-symbolicate package is installed by default in the React Native template project from setting up your development environment.

From a file containing the stacktrace:

npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map < stacktrace.txt

From adb logcatdirectly:

adb logcat -d | npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map

This will turn each minified function name and offset like p@1:132161 into the actual file- and function name AwesomeProject/App.js:54:initializeMap.

Notes on Sourcemaps

  • Multiple source maps may be generated by the build process. Make sure to used the one in the location shown in the examples.
  • Make sure that the source map you use corresponds to the exact commit of the crashing app. Small changes in source code can cause large differences in offsets.
  • If metro-symbolicate exits immediately with success, make sure the input comes from a pipe or redirection and not from a terminal.
Edit this page
Last updated on
- + diff --git a/docs/0.60/symbolication/index.html b/docs/0.60/symbolication/index.html index 684bcc6cf41..610dafd3df2 100644 --- a/docs/0.60/symbolication/index.html +++ b/docs/0.60/symbolication/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Symbolicating a stack trace

If a React Native app throws an unhandled exception in a release build, the output may be obfuscated and hard to read:

07-15 10:58:25.820 18979 18998 E AndroidRuntime: FATAL EXCEPTION: mqt_native_modules
07-15 10:58:25.820 18979 18998 E AndroidRuntime: Process: com.awesomeproject, PID: 18979 07-15 10:58:25.820 18979 18998 E AndroidRuntime: com.facebook.react.common.JavascriptException: Failed, js engine: hermes, stack:
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132161
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132084
07-15 10:58:25.820 18979 18998 E AndroidRuntime: f@1:131854
07-15 10:58:25.820 18979 18998 E AndroidRuntime: anonymous@1:131119

The sections like p@1:132161 are minified function names and bytecode offsets. To debug the problem, you would instead want to translate it into file, line and function name: AwesomeProject/App.js:54:initializeMap. This is known as symbolication. You can symbolicate minified function names and bytecode like the above by passing metro-symbolicate a generated source map and the stack trace.

The metro-symbolicate package is installed by default in the React Native template project from setting up your development environment.

From a file containing the stacktrace:

npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map < stacktrace.txt

From adb logcatdirectly:

adb logcat -d | npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map

This will turn each minified function name and offset like p@1:132161 into the actual file- and function name AwesomeProject/App.js:54:initializeMap.

Notes on Sourcemaps

  • Multiple source maps may be generated by the build process. Make sure to used the one in the location shown in the examples.
  • Make sure that the source map you use corresponds to the exact commit of the crashing app. Small changes in source code can cause large differences in offsets.
  • If metro-symbolicate exits immediately with success, make sure the input comes from a pipe or redirection and not from a terminal.
Edit this page
Last updated on
- + diff --git a/docs/0.60/systrace.html b/docs/0.60/systrace.html index ddeb8506f04..195f49f304a 100644 --- a/docs/0.60/systrace.html +++ b/docs/0.60/systrace.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Systrace

Reference

Methods

installReactHook()

static installReactHook(useFiber)

setEnabled()

static setEnabled(enabled)

isEnabled()

static isEnabled()

beginEvent()

static beginEvent(profileName?, args?)

beginEvent/endEvent for starting and then ending a profile within the same call stack frame.

endEvent()

static endEvent()

beginAsyncEvent()

static beginAsyncEvent(profileName?)

beginAsyncEvent/endAsyncEvent for starting and then ending a profile where the end can either occur on another thread or out of the current stack frame, eg await the returned cookie variable should be used as input into the endAsyncEvent call to end the profile.

endAsyncEvent()

static endAsyncEvent(profileName?, cookie?)

counterEvent()

static counterEvent(profileName?, value?)

Register the value to the profileName on the systrace timeline.

Edit this page
Last updated on
- + diff --git a/docs/0.60/systrace/index.html b/docs/0.60/systrace/index.html index ddeb8506f04..195f49f304a 100644 --- a/docs/0.60/systrace/index.html +++ b/docs/0.60/systrace/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Systrace

Reference

Methods

installReactHook()

static installReactHook(useFiber)

setEnabled()

static setEnabled(enabled)

isEnabled()

static isEnabled()

beginEvent()

static beginEvent(profileName?, args?)

beginEvent/endEvent for starting and then ending a profile within the same call stack frame.

endEvent()

static endEvent()

beginAsyncEvent()

static beginAsyncEvent(profileName?)

beginAsyncEvent/endAsyncEvent for starting and then ending a profile where the end can either occur on another thread or out of the current stack frame, eg await the returned cookie variable should be used as input into the endAsyncEvent call to end the profile.

endAsyncEvent()

static endAsyncEvent(profileName?, cookie?)

counterEvent()

static counterEvent(profileName?, value?)

Register the value to the profileName on the systrace timeline.

Edit this page
Last updated on
- + diff --git a/docs/0.60/tabbarios-item.html b/docs/0.60/tabbarios-item.html index 072c3522321..2009c24ea36 100644 --- a/docs/0.60/tabbarios-item.html +++ b/docs/0.60/tabbarios-item.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

TabBarIOS.Item

Props

Reference

Props

selected

It specifies whether the children are visible or not. If you see a blank content, you probably forgot to add a selected one.

TypeRequired
boolNo

badge

Little red bubble that sits at the top right of the icon.

TypeRequired
string, ,numberNo

icon

A custom icon for the tab. It is ignored when a system icon is defined.

TypeRequired
Image.propTypes.sourceNo

onPress

Callback when this tab is being selected, you should change the state of your component to set selected={true}.

TypeRequired
functionNo

renderAsOriginal

If set to true it renders the image as original, it defaults to being displayed as a template

TypeRequired
boolNo

badgeColor

Background color for the badge. Available since iOS 10.

TypeRequired
colorNo

selectedIcon

A custom icon when the tab is selected. It is ignored when a system icon is defined. If left empty, the icon will be tinted in blue.

TypeRequired
Image.propTypes.sourceNo

style

React style object.

TypeRequired
View.styleNo

systemIcon

Items comes with a few predefined system icons. Note that if you are using them, the title and selectedIcon will be overridden with the system ones.

TypeRequired
enum('bookmarks', 'contacts', 'downloads', 'favorites', 'featured', 'history', 'more', 'most-recent', 'most-viewed', 'recents', 'search', 'top-rated')No

title

Text that appears under the icon. It is ignored when a system icon is defined.

TypeRequired
stringNo

isTVSelectable

(Apple TV only)* When set to true, this view will be focusable and navigable using the Apple TV remote.

TypeRequiredPlatform
boolNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.60/tabbarios-item/index.html b/docs/0.60/tabbarios-item/index.html index 072c3522321..2009c24ea36 100644 --- a/docs/0.60/tabbarios-item/index.html +++ b/docs/0.60/tabbarios-item/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

TabBarIOS.Item

Props

Reference

Props

selected

It specifies whether the children are visible or not. If you see a blank content, you probably forgot to add a selected one.

TypeRequired
boolNo

badge

Little red bubble that sits at the top right of the icon.

TypeRequired
string, ,numberNo

icon

A custom icon for the tab. It is ignored when a system icon is defined.

TypeRequired
Image.propTypes.sourceNo

onPress

Callback when this tab is being selected, you should change the state of your component to set selected={true}.

TypeRequired
functionNo

renderAsOriginal

If set to true it renders the image as original, it defaults to being displayed as a template

TypeRequired
boolNo

badgeColor

Background color for the badge. Available since iOS 10.

TypeRequired
colorNo

selectedIcon

A custom icon when the tab is selected. It is ignored when a system icon is defined. If left empty, the icon will be tinted in blue.

TypeRequired
Image.propTypes.sourceNo

style

React style object.

TypeRequired
View.styleNo

systemIcon

Items comes with a few predefined system icons. Note that if you are using them, the title and selectedIcon will be overridden with the system ones.

TypeRequired
enum('bookmarks', 'contacts', 'downloads', 'favorites', 'featured', 'history', 'more', 'most-recent', 'most-viewed', 'recents', 'search', 'top-rated')No

title

Text that appears under the icon. It is ignored when a system icon is defined.

TypeRequired
stringNo

isTVSelectable

(Apple TV only)* When set to true, this view will be focusable and navigable using the Apple TV remote.

TypeRequiredPlatform
boolNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.60/tabbarios.html b/docs/0.60/tabbarios.html index 2dfb2a215cb..03a6d1bd4c5 100644 --- a/docs/0.60/tabbarios.html +++ b/docs/0.60/tabbarios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

TabBarIOS

Props

Reference

Props

barStyle

The style of the tab bar. Supported values are 'default', 'black'. Use 'black' instead of setting barTintColor to black. This produces a tab bar with the native iOS style with higher translucency.

TypeRequired
enum('default', 'black')No

barTintColor

Background color of the tab bar

TypeRequired
colorNo

itemPositioning

Specifies tab bar item positioning. Available values are:

  • fill - distributes items across the entire width of the tab bar
  • center - centers item in the available tab bar space
  • auto (default) - distributes items dynamically according to the user interface idiom. In a horizontally compact environment (e.g. iPhone 5) this value defaults to fill, in a horizontally regular one (e.g. iPad) it defaults to center.
TypeRequired
enum('fill', 'center', 'auto')No

style

TypeRequired
View.styleNo

tintColor

Color of the currently selected tab icon

TypeRequired
colorNo

translucent

A Boolean value that indicates whether the tab bar is translucent

TypeRequired
boolNo

unselectedItemTintColor

Color of unselected tab icons. Available since iOS 10.

TypeRequired
colorNo

unselectedTintColor

Color of text on unselected tabs

TypeRequired
colorNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/tabbarios/index.html b/docs/0.60/tabbarios/index.html index 2dfb2a215cb..03a6d1bd4c5 100644 --- a/docs/0.60/tabbarios/index.html +++ b/docs/0.60/tabbarios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

TabBarIOS

Props

Reference

Props

barStyle

The style of the tab bar. Supported values are 'default', 'black'. Use 'black' instead of setting barTintColor to black. This produces a tab bar with the native iOS style with higher translucency.

TypeRequired
enum('default', 'black')No

barTintColor

Background color of the tab bar

TypeRequired
colorNo

itemPositioning

Specifies tab bar item positioning. Available values are:

  • fill - distributes items across the entire width of the tab bar
  • center - centers item in the available tab bar space
  • auto (default) - distributes items dynamically according to the user interface idiom. In a horizontally compact environment (e.g. iPhone 5) this value defaults to fill, in a horizontally regular one (e.g. iPad) it defaults to center.
TypeRequired
enum('fill', 'center', 'auto')No

style

TypeRequired
View.styleNo

tintColor

Color of the currently selected tab icon

TypeRequired
colorNo

translucent

A Boolean value that indicates whether the tab bar is translucent

TypeRequired
boolNo

unselectedItemTintColor

Color of unselected tab icons. Available since iOS 10.

TypeRequired
colorNo

unselectedTintColor

Color of text on unselected tabs

TypeRequired
colorNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/testing-overview.html b/docs/0.60/testing-overview.html index ac620f9cd9e..3724ace5474 100644 --- a/docs/0.60/testing-overview.html +++ b/docs/0.60/testing-overview.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
const bananaElements = getAllByText('banana');
expect(bananaElements).toHaveLength(1); // expect 'banana' to be on the list
});

This example is not testing how some state changes when you call a function. It tests what happens when a user changes text in the TextInput and presses the Button!

Testing Rendered Output

Snapshot testing is an advanced kind of testing enabled by Jest. It is a very powerful and low-level tool, so extra attention is advised when using it.

A "component snapshot" is a JSX-like string created by a custom React serializer built into Jest. This serializer lets Jest translate React component trees to string that's human-readable. Put another way: a component snapshot is a textual representation of your component’s render output generated during a test run. It may look like this:

<Text
style={
Object {
"fontSize": 20,
"textAlign": "center",
}
}>
Welcome to React Native!
</Text>

With snapshot testing, you typically first implement your component and then run the snapshot test. The snapshot test then creates a snapshot and saves it to a file in your repo as a reference snapshot. The file is then committed and checked during code review. Any future changes to the component render output will change its snapshot, which will cause the test to fail. You then need to update the stored reference snapshot for the test to pass. That change again needs to be committed and reviewed.

Snapshots have several weak points:

Snapshots themselves do not ensure that your component render logic is correct, they are merely good at guarding against unexpected changes and for checking that the components in the React tree under test receive the expected props (styles and etc.).

We recommend that you only use small snapshots (see no-large-snapshots rule). If you want to test a change between two React component states, use snapshot-diff. When in doubt, prefer explicit expectations as described in the previous paragraph.

End-to-End Tests

In end-to-end (E2E) tests, you verify your app is working as expected on a device (or a simulator / emulator) from the user perspective.

This is done by building your app in the release configuration and running the tests against it. In E2E tests, you no longer think about React components, React Native APIs, Redux stores or any business logic. That is not the purpose of E2E tests and those are not even accessible to you during E2E testing.

Instead, E2E testing libraries allow you to find and control elements in the screen of your app: for example, you can actually tap buttons or insert text into TextInputs the same way a real user would. Then you can make assertions about whether or not a certain element exists in the app’s screen, whether or not it’s visible, what text it contains, and so on.

E2E tests give you the highest possible confidence that part of your app is working. The tradeoffs include:

Try to cover the vital parts of your app with E2E tests: authentication flow, core functionalities, payments, etc. Use faster JS tests for the non-vital parts of your app. The more tests you add, the higher your confidence, but also, the more time you'll spend maintaining and running them. Consider the tradeoffs and decide what's best for you.

There are several E2E testing tools available: in the React Native community, Detox is a popular framework because it’s tailored for React Native apps. Another popular library in the space of iOS and Android apps is Appium.

Summary

We hope you enjoyed reading and learned something from this guide. There are many ways you can test your apps. It may be hard to decide what to use at first. However, we believe it all will make sense once you start adding tests to your awesome React Native app. So what are you waiting for? Get your coverage up!

Links

This guide originally authored and contributed in full by Vojtech Novak.

Edit this page
Last updated on
- + diff --git a/docs/0.60/testing-overview/index.html b/docs/0.60/testing-overview/index.html index ac620f9cd9e..3724ace5474 100644 --- a/docs/0.60/testing-overview/index.html +++ b/docs/0.60/testing-overview/index.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
const bananaElements = getAllByText('banana');
expect(bananaElements).toHaveLength(1); // expect 'banana' to be on the list
});

This example is not testing how some state changes when you call a function. It tests what happens when a user changes text in the TextInput and presses the Button!

Testing Rendered Output

Snapshot testing is an advanced kind of testing enabled by Jest. It is a very powerful and low-level tool, so extra attention is advised when using it.

A "component snapshot" is a JSX-like string created by a custom React serializer built into Jest. This serializer lets Jest translate React component trees to string that's human-readable. Put another way: a component snapshot is a textual representation of your component’s render output generated during a test run. It may look like this:

<Text
style={
Object {
"fontSize": 20,
"textAlign": "center",
}
}>
Welcome to React Native!
</Text>

With snapshot testing, you typically first implement your component and then run the snapshot test. The snapshot test then creates a snapshot and saves it to a file in your repo as a reference snapshot. The file is then committed and checked during code review. Any future changes to the component render output will change its snapshot, which will cause the test to fail. You then need to update the stored reference snapshot for the test to pass. That change again needs to be committed and reviewed.

Snapshots have several weak points:

Snapshots themselves do not ensure that your component render logic is correct, they are merely good at guarding against unexpected changes and for checking that the components in the React tree under test receive the expected props (styles and etc.).

We recommend that you only use small snapshots (see no-large-snapshots rule). If you want to test a change between two React component states, use snapshot-diff. When in doubt, prefer explicit expectations as described in the previous paragraph.

End-to-End Tests

In end-to-end (E2E) tests, you verify your app is working as expected on a device (or a simulator / emulator) from the user perspective.

This is done by building your app in the release configuration and running the tests against it. In E2E tests, you no longer think about React components, React Native APIs, Redux stores or any business logic. That is not the purpose of E2E tests and those are not even accessible to you during E2E testing.

Instead, E2E testing libraries allow you to find and control elements in the screen of your app: for example, you can actually tap buttons or insert text into TextInputs the same way a real user would. Then you can make assertions about whether or not a certain element exists in the app’s screen, whether or not it’s visible, what text it contains, and so on.

E2E tests give you the highest possible confidence that part of your app is working. The tradeoffs include:

Try to cover the vital parts of your app with E2E tests: authentication flow, core functionalities, payments, etc. Use faster JS tests for the non-vital parts of your app. The more tests you add, the higher your confidence, but also, the more time you'll spend maintaining and running them. Consider the tradeoffs and decide what's best for you.

There are several E2E testing tools available: in the React Native community, Detox is a popular framework because it’s tailored for React Native apps. Another popular library in the space of iOS and Android apps is Appium.

Summary

We hope you enjoyed reading and learned something from this guide. There are many ways you can test your apps. It may be hard to decide what to use at first. However, we believe it all will make sense once you start adding tests to your awesome React Native app. So what are you waiting for? Get your coverage up!

Links

This guide originally authored and contributed in full by Vojtech Novak.

Edit this page
Last updated on
- + diff --git a/docs/0.60/text-style-props.html b/docs/0.60/text-style-props.html index 103e6b18684..eb6ba19d595 100644 --- a/docs/0.60/text-style-props.html +++ b/docs/0.60/text-style-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Text Style Props

Reference

Props

textShadowOffset

TypeRequired
object: {width: number,height: number}No

color

TypeRequired
colorNo

fontSize

TypeRequired
numberNo

fontStyle

TypeRequired
enum('normal', 'italic')No

fontWeight

Specifies font weight. The values 'normal' and 'bold' are supported for most fonts. Not all fonts have a variant for each of the numeric values, in that case the closest one is chosen.

TypeRequired
enum('normal', 'bold', '100', '200', '300', '400', '500', '600', '700', '800', '900')No

lineHeight

TypeRequired
numberNo

textAlign

Specifies text alignment. The value 'justify' is only supported on iOS and fallbacks to left on Android.

TypeRequired
enum('auto', 'left', 'right', 'center', 'justify')No

textDecorationLine

TypeRequired
enum('none', 'underline', 'line-through', 'underline line-through')No

textShadowColor

TypeRequired
colorNo

fontFamily

TypeRequired
stringNo

textShadowRadius

TypeRequired
numberNo

includeFontPadding

Set to false to remove extra font padding intended to make space for certain ascenders / descenders. With some fonts, this padding can make text look slightly misaligned when centered vertically. For best results also set textAlignVertical to center. Default is true.

TypeRequiredPlatform
boolNoAndroid

textAlignVertical

TypeRequiredPlatform
enum('auto', 'top', 'bottom', 'center')NoAndroid

fontVariant

TypeRequiredPlatform
array of enum('small-caps', 'oldstyle-nums', 'lining-nums', 'tabular-nums', 'proportional-nums')NoiOS

letterSpacing

TypeRequiredPlatform
numberNoiOS, Android >= 5.0

textDecorationColor

TypeRequiredPlatform
colorNoiOS

textDecorationStyle

TypeRequiredPlatform
enum('solid', 'double', 'dotted', 'dashed')NoiOS

textTransform

TypeRequired
enum('none', 'uppercase', 'lowercase', 'capitalize')No

writingDirection

TypeRequiredPlatform
enum('auto', 'ltr', 'rtl')NoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.60/text-style-props/index.html b/docs/0.60/text-style-props/index.html index 103e6b18684..eb6ba19d595 100644 --- a/docs/0.60/text-style-props/index.html +++ b/docs/0.60/text-style-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Text Style Props

Reference

Props

textShadowOffset

TypeRequired
object: {width: number,height: number}No

color

TypeRequired
colorNo

fontSize

TypeRequired
numberNo

fontStyle

TypeRequired
enum('normal', 'italic')No

fontWeight

Specifies font weight. The values 'normal' and 'bold' are supported for most fonts. Not all fonts have a variant for each of the numeric values, in that case the closest one is chosen.

TypeRequired
enum('normal', 'bold', '100', '200', '300', '400', '500', '600', '700', '800', '900')No

lineHeight

TypeRequired
numberNo

textAlign

Specifies text alignment. The value 'justify' is only supported on iOS and fallbacks to left on Android.

TypeRequired
enum('auto', 'left', 'right', 'center', 'justify')No

textDecorationLine

TypeRequired
enum('none', 'underline', 'line-through', 'underline line-through')No

textShadowColor

TypeRequired
colorNo

fontFamily

TypeRequired
stringNo

textShadowRadius

TypeRequired
numberNo

includeFontPadding

Set to false to remove extra font padding intended to make space for certain ascenders / descenders. With some fonts, this padding can make text look slightly misaligned when centered vertically. For best results also set textAlignVertical to center. Default is true.

TypeRequiredPlatform
boolNoAndroid

textAlignVertical

TypeRequiredPlatform
enum('auto', 'top', 'bottom', 'center')NoAndroid

fontVariant

TypeRequiredPlatform
array of enum('small-caps', 'oldstyle-nums', 'lining-nums', 'tabular-nums', 'proportional-nums')NoiOS

letterSpacing

TypeRequiredPlatform
numberNoiOS, Android >= 5.0

textDecorationColor

TypeRequiredPlatform
colorNoiOS

textDecorationStyle

TypeRequiredPlatform
enum('solid', 'double', 'dotted', 'dashed')NoiOS

textTransform

TypeRequired
enum('none', 'uppercase', 'lowercase', 'capitalize')No

writingDirection

TypeRequiredPlatform
enum('auto', 'ltr', 'rtl')NoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.60/text.html b/docs/0.60/text.html index 0f72e1a834b..77ac2e79d1d 100644 --- a/docs/0.60/text.html +++ b/docs/0.60/text.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
// GOOD
<View>
<Text>
Some text
</Text>
</View>

You also lose the ability to set up a default font for an entire subtree. Meanwhile, fontFamily only accepts a single font name, which is different from font-family in CSS. The recommended way to use consistent fonts and sizes across your application is to create a component MyAppText that includes them and use this component across your app. You can also use this component to make more specific components like MyAppHeaderText for other kinds of text.

<View>
<MyAppText>
Text styled with the default font for the entire application
</MyAppText>
<MyAppHeaderText>Text styled as a header</MyAppHeaderText>
</View>

Assuming that MyAppText is a component that only renders out its children into a Text component with styling, then MyAppHeaderText can be defined as follows:

class MyAppHeaderText extends Component {
render() {
return (
<MyAppText>
<Text style={{ fontSize: 20 }}>
{this.props.children}
</Text>
</MyAppText>
);
}
}

Composing MyAppText in this way ensures that we get the styles from a top-level component, but leaves us the ability to add / override them in specific use cases.

React Native still has the concept of style inheritance, but limited to text subtrees. In this case, the second part will be both bold and red.

<Text style={{ fontWeight: 'bold' }}>
I am bold
<Text style={{ color: 'red' }}>and red</Text>
</Text>

We believe that this more constrained way to style text will yield better apps:

Reference

Props

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

adjustsFontSizeToFit

Specifies whether fonts should be scaled down automatically to fit given style constraints.

TypeRequiredPlatform
boolNoiOS

allowFontScaling

Specifies whether fonts should scale to respect Text Size accessibility settings. The default is true.

TypeRequired
boolNo

dataDetectorType

Determines the types of data converted to clickable URLs in the text element. By default no data types are detected.

You can provide only one type.

Possible values for dataDetectorType are:

TypeRequiredPlatform
enum('phoneNumber', 'link', 'email', 'none', 'all')NoAndroid

disabled

Specifies the disabled state of the text view for testing purposes

TypeRequiredPlatform
boolNoAndroid

ellipsizeMode

When numberOfLines is set, this prop defines how text will be truncated. numberOfLines must be set in conjunction with this prop.

This can be one of the following values:

The default is tail.

TypeRequired
enum('head', 'middle', 'tail', 'clip')No

maxFontSizeMultiplier

Specifies largest possible scale a font can reach when allowFontScaling is enabled. Possible values:

TypeRequired
numberNo

minimumFontScale

Specifies smallest possible scale a font can reach when adjustsFontSizeToFit is enabled. (values 0.01-1.0).

TypeRequiredPlatform
numberNoiOS

nativeID

Used to locate this view from native code.

TypeRequired
stringNo

numberOfLines

Used to truncate the text with an ellipsis after computing the text layout, including line wrapping, such that the total number of lines does not exceed this number.

This prop is commonly used with ellipsizeMode.

TypeRequired
numberNo

onLayout

Invoked on mount and layout changes with

{nativeEvent: {layout: {x, y, width, height}}}

TypeRequired
functionNo

onLongPress

This function is called on long press.

e.g., onLongPress={this.increaseSize}>

TypeRequired
functionNo

onMoveShouldSetResponder

Does this view want to "claim" touch responsiveness? This is called for every touch move on the View when it is not the responder.

View.props.onMoveShouldSetResponder: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onPress

This function is called on press.

e.g., onPress={() => console.log('1st')}

TypeRequired
functionNo

onResponderGrant

The View is now responding for touch events. This is the time to highlight and show the user what is happening.

View.props.onResponderGrant: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderMove

The user is moving their finger.

View.props.onResponderMove: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderRelease

Fired at the end of the touch.

View.props.onResponderRelease: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminate

The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS)

View.props.onResponderTerminate: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminationRequest

Some other View wants to become responder and is asking this View to release its responder. Returning true allows its release.

View.props.onResponderTerminationRequest: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onStartShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a touch start, it should have this handler which returns true.

View.props.onStartShouldSetResponderCapture: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onTextLayout

TODO.

pressRetentionOffset

When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

selectable

Lets the user select text, to use the native copy and paste functionality.

TypeRequired
boolNo

selectionColor

The highlight color of the text.

TypeRequiredPlatform
colorNoAndroid

style

TypeRequired
Text Style Props, View Style PropsNo

suppressHighlighting

When true, no visual change is made when text is pressed down. By default, a gray oval highlights the text on press down.

TypeRequiredPlatform
boolNoiOS

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

textBreakStrategy

Set text break strategy on Android API Level 23+, possible values are simple, highQuality, balanced The default value is highQuality.

TypeRequiredPlatform
enum('simple', 'highQuality', 'balanced')NoAndroid

Known issues

Edit this page
Last updated on
- + diff --git a/docs/0.60/text/index.html b/docs/0.60/text/index.html index 0f72e1a834b..77ac2e79d1d 100644 --- a/docs/0.60/text/index.html +++ b/docs/0.60/text/index.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
// GOOD
<View>
<Text>
Some text
</Text>
</View>

You also lose the ability to set up a default font for an entire subtree. Meanwhile, fontFamily only accepts a single font name, which is different from font-family in CSS. The recommended way to use consistent fonts and sizes across your application is to create a component MyAppText that includes them and use this component across your app. You can also use this component to make more specific components like MyAppHeaderText for other kinds of text.

<View>
<MyAppText>
Text styled with the default font for the entire application
</MyAppText>
<MyAppHeaderText>Text styled as a header</MyAppHeaderText>
</View>

Assuming that MyAppText is a component that only renders out its children into a Text component with styling, then MyAppHeaderText can be defined as follows:

class MyAppHeaderText extends Component {
render() {
return (
<MyAppText>
<Text style={{ fontSize: 20 }}>
{this.props.children}
</Text>
</MyAppText>
);
}
}

Composing MyAppText in this way ensures that we get the styles from a top-level component, but leaves us the ability to add / override them in specific use cases.

React Native still has the concept of style inheritance, but limited to text subtrees. In this case, the second part will be both bold and red.

<Text style={{ fontWeight: 'bold' }}>
I am bold
<Text style={{ color: 'red' }}>and red</Text>
</Text>

We believe that this more constrained way to style text will yield better apps:

Reference

Props

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

adjustsFontSizeToFit

Specifies whether fonts should be scaled down automatically to fit given style constraints.

TypeRequiredPlatform
boolNoiOS

allowFontScaling

Specifies whether fonts should scale to respect Text Size accessibility settings. The default is true.

TypeRequired
boolNo

dataDetectorType

Determines the types of data converted to clickable URLs in the text element. By default no data types are detected.

You can provide only one type.

Possible values for dataDetectorType are:

TypeRequiredPlatform
enum('phoneNumber', 'link', 'email', 'none', 'all')NoAndroid

disabled

Specifies the disabled state of the text view for testing purposes

TypeRequiredPlatform
boolNoAndroid

ellipsizeMode

When numberOfLines is set, this prop defines how text will be truncated. numberOfLines must be set in conjunction with this prop.

This can be one of the following values:

The default is tail.

TypeRequired
enum('head', 'middle', 'tail', 'clip')No

maxFontSizeMultiplier

Specifies largest possible scale a font can reach when allowFontScaling is enabled. Possible values:

TypeRequired
numberNo

minimumFontScale

Specifies smallest possible scale a font can reach when adjustsFontSizeToFit is enabled. (values 0.01-1.0).

TypeRequiredPlatform
numberNoiOS

nativeID

Used to locate this view from native code.

TypeRequired
stringNo

numberOfLines

Used to truncate the text with an ellipsis after computing the text layout, including line wrapping, such that the total number of lines does not exceed this number.

This prop is commonly used with ellipsizeMode.

TypeRequired
numberNo

onLayout

Invoked on mount and layout changes with

{nativeEvent: {layout: {x, y, width, height}}}

TypeRequired
functionNo

onLongPress

This function is called on long press.

e.g., onLongPress={this.increaseSize}>

TypeRequired
functionNo

onMoveShouldSetResponder

Does this view want to "claim" touch responsiveness? This is called for every touch move on the View when it is not the responder.

View.props.onMoveShouldSetResponder: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onPress

This function is called on press.

e.g., onPress={() => console.log('1st')}

TypeRequired
functionNo

onResponderGrant

The View is now responding for touch events. This is the time to highlight and show the user what is happening.

View.props.onResponderGrant: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderMove

The user is moving their finger.

View.props.onResponderMove: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderRelease

Fired at the end of the touch.

View.props.onResponderRelease: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminate

The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS)

View.props.onResponderTerminate: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminationRequest

Some other View wants to become responder and is asking this View to release its responder. Returning true allows its release.

View.props.onResponderTerminationRequest: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onStartShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a touch start, it should have this handler which returns true.

View.props.onStartShouldSetResponderCapture: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onTextLayout

TODO.

pressRetentionOffset

When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

selectable

Lets the user select text, to use the native copy and paste functionality.

TypeRequired
boolNo

selectionColor

The highlight color of the text.

TypeRequiredPlatform
colorNoAndroid

style

TypeRequired
Text Style Props, View Style PropsNo

suppressHighlighting

When true, no visual change is made when text is pressed down. By default, a gray oval highlights the text on press down.

TypeRequiredPlatform
boolNoiOS

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

textBreakStrategy

Set text break strategy on Android API Level 23+, possible values are simple, highQuality, balanced The default value is highQuality.

TypeRequiredPlatform
enum('simple', 'highQuality', 'balanced')NoAndroid

Known issues

Edit this page
Last updated on
- + diff --git a/docs/0.60/textinput.html b/docs/0.60/textinput.html index c71ddb7ff0c..0e2b1f2f267 100644 --- a/docs/0.60/textinput.html +++ b/docs/0.60/textinput.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

TextInput

A foundational component for inputting text into the app via a keyboard. Props provide configurability for several features, such as auto-correction, auto-capitalization, placeholder text, and different keyboard types, such as a numeric keypad.

The most basic use case is to plop down a TextInput and subscribe to the onChangeText events to read the user input. There are also other events, such as onSubmitEditing and onFocus that can be subscribed to. A minimal example:

Two methods exposed via the native element are .focus() and .blur() that will focus or blur the TextInput programmatically.

Note that some props are only available with multiline={true/false}. Additionally, border styles that apply to only one side of the element (e.g., borderBottomColor, borderLeftWidth, etc.) will not be applied if multiline=false. To achieve the same effect, you can wrap your TextInput in a View:

TextInput has by default a border at the bottom of its view. This border has its padding set by the background image provided by the system, and it cannot be changed. Solutions to avoid this is to either not set height explicitly, case in which the system will take care of displaying the border in the correct position, or to not display the border by setting underlineColorAndroid to transparent.

Note that on Android performing text selection in input can change app's activity windowSoftInputMode param to adjustResize. This may cause issues with components that have position: 'absolute' while keyboard is active. To avoid this behavior either specify windowSoftInputMode in AndroidManifest.xml ( https://developer.android.com/guide/topics/manifest/activity-element.html ) or control this param programmatically with native code.

Reference

Props

Inherits View Props.

allowFontScaling

Specifies whether fonts should scale to respect Text Size accessibility settings. The default is true.

TypeRequired
boolNo

autoCapitalize

Can tell TextInput to automatically capitalize certain characters. This property is not supported by some keyboard types such as name-phone-pad.

  • characters: all characters.
  • words: first letter of each word.
  • sentences: first letter of each sentence (default).
  • none: don't auto capitalize anything.
TypeRequired
enum('none', 'sentences', 'words', 'characters')No

autoCompleteType

Specifies autocomplete hints for the system, so it can provide autofill. On Android, the system will always attempt to offer autofill by using heuristics to identify the type of content. To disable autocomplete, set autoCompleteType to off.

Possible values for autoCompleteType are:

  • off
  • username
  • password
  • email
  • name
  • tel
  • street-address
  • postal-code
  • cc-number
  • cc-csc
  • cc-exp
  • cc-exp-month
  • cc-exp-year
TypeRequiredPlatform
enum('off', 'username', 'password', 'email', 'name', 'tel', 'street-address', 'postal-code', 'cc-number', 'cc-csc', 'cc-exp', 'cc-exp-month', 'cc-exp-year')NoAndroid

autoCorrect

If false, disables auto-correct. The default value is true.

TypeRequired
boolNo

autoFocus

If true, focuses the input on componentDidMount. The default value is false.

TypeRequired
boolNo

blurOnSubmit

If true, the text field will blur when submitted. The default value is true for single-line fields and false for multiline fields. Note that for multiline fields, setting blurOnSubmit to true means that pressing return will blur the field and trigger the onSubmitEditing event instead of inserting a newline into the field.

TypeRequired
boolNo

caretHidden

If true, caret is hidden. The default value is false.

TypeRequired
boolNo

clearButtonMode

When the clear button should appear on the right side of the text view. This property is supported only for single-line TextInput component. The default value is never.

TypeRequiredPlatform
enum('never', 'while-editing', 'unless-editing', 'always')NoiOS

clearTextOnFocus

If true, clears the text field automatically when editing begins.

TypeRequiredPlatform
boolNoiOS

contextMenuHidden

If true, context menu is hidden. The default value is false.

TypeRequired
boolNo

dataDetectorTypes

Determines the types of data converted to clickable URLs in the text input. Only valid if multiline={true} and editable={false}. By default no data types are detected.

You can provide one type or an array of many types.

Possible values for dataDetectorTypes are:

  • 'phoneNumber'
  • 'link'
  • 'address'
  • 'calendarEvent'
  • 'none'
  • 'all'
TypeRequiredPlatform
enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all'), ,array of enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all')NoiOS

defaultValue

Provides an initial value that will change when the user starts typing. Useful for use-cases where you do not want to deal with listening to events and updating the value prop to keep the controlled state in sync.

TypeRequired
stringNo

disableFullscreenUI

When false, if there is a small amount of space available around a text input (e.g. landscape orientation on a phone), the OS may choose to have the user edit the text inside of a full screen text input mode. When true, this feature is disabled and users will always edit the text directly inside of the text input. Defaults to false.

TypeRequiredPlatform
boolNoAndroid

editable

If false, text is not editable. The default value is true.

TypeRequired
boolNo

enablesReturnKeyAutomatically

If true, the keyboard disables the return key when there is no text and automatically enables it when there is text. The default value is false.

TypeRequiredPlatform
boolNoiOS

importantForAutofill

Say the system whether the individual fields in your app should be included in a view structure for autofill purposes on Android API Level 26+, possible values are auto, no, noExcludeDescendants, yes, yesExcludeDescendants. The default value is auto.

  • auto: Let the Android System use its heuristics to determine if the view is important for autofill.
  • no: This view isn't important for autofill.
  • noExcludeDescendants: This view and its children aren't important for autofill.
  • yes: This view is important for autofill.
  • yesExcludeDescendants: This view is important for autofill, but its children aren't important for autofill.
TypeRequiredPlatform
enum('auto', 'no', 'noExcludeDescendants', 'yes', 'yesExcludeDescendants')NoAndroid

inlineImageLeft

If defined, the provided image resource will be rendered on the left. The image resource must be inside /android/app/src/main/res/drawable and referenced like

<TextInput
inlineImageLeft='search_icon'
/>
TypeRequiredPlatform
stringNoAndroid

inlineImagePadding

Padding between the inline image, if any, and the text input itself.

TypeRequiredPlatform
numberNoAndroid

inputAccessoryViewID

An optional identifier which links a custom InputAccessoryView to this text input. The InputAccessoryView is rendered above the keyboard when this text input is focused.

TypeRequiredPlatform
stringNoiOS

keyboardAppearance

Determines the color of the keyboard.

TypeRequiredPlatform
enum('default', 'light', 'dark')NoiOS

keyboardType

Determines which keyboard to open, e.g.numeric.

See screenshots of all the types here.

The following values work across platforms:

  • default
  • number-pad
  • decimal-pad
  • numeric
  • email-address
  • phone-pad

iOS Only

The following values work on iOS only:

  • ascii-capable
  • numbers-and-punctuation
  • url
  • name-phone-pad
  • twitter
  • web-search

Android Only

The following values work on Android only:

  • visible-password
TypeRequired
enum('default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter', 'web-search', 'visible-password')No

maxFontSizeMultiplier

Specifies largest possible scale a font can reach when allowFontScaling is enabled. Possible values:

  • null/undefined (default): inherit from the parent node or the global default (0)
  • 0: no max, ignore parent/global default
  • >= 1: sets the maxFontSizeMultiplier of this node to this value
TypeRequired
numberNo

maxLength

Limits the maximum number of characters that can be entered. Use this instead of implementing the logic in JS to avoid flicker.

TypeRequired
numberNo

multiline

If true, the text input can be multiple lines. The default value is false. It is important to note that this aligns the text to the top on iOS, and centers it on Android. Use with textAlignVertical set to top for the same behavior in both platforms.

TypeRequired
boolNo

numberOfLines

Sets the number of lines for a TextInput. Use it with multiline set to true to be able to fill the lines.

TypeRequiredPlatform
numberNoAndroid

onBlur

Callback that is called when the text input is blurred.

TypeRequired
functionNo

onChange

Callback that is called when the text input's text changes. This will be called with { nativeEvent: { eventCount, target, text} }

TypeRequired
functionNo

onChangeText

Callback that is called when the text input's text changes. Changed text is passed as a single string argument to the callback handler.

TypeRequired
functionNo

onContentSizeChange

Callback that is called when the text input's content size changes. This will be called with { nativeEvent: { contentSize: { width, height } } }.

Only called for multiline text inputs.

TypeRequired
functionNo

onEndEditing

Callback that is called when text input ends.

TypeRequired
functionNo

onFocus

Callback that is called when the text input is focused. This is called with { nativeEvent: { target } }.

TypeRequired
functionNo

onKeyPress

Callback that is called when a key is pressed. This will be called with { nativeEvent: { key: keyValue } } where keyValue is 'Enter' or 'Backspace' for respective keys and the typed-in character otherwise including ' ' for space. Fires before onChange callbacks. Note: on Android only the inputs from soft keyboard are handled, not the hardware keyboard inputs.

TypeRequired
functionNo

onLayout

Invoked on mount and layout changes with { nativeEvent: {layout: {x, y, width, height}, target } }.

TypeRequired
functionNo

onScroll

Invoked on content scroll with { nativeEvent: { contentOffset: { x, y } } }. May also contain other properties from ScrollEvent but on Android contentSize is not provided for performance reasons.

TypeRequired
functionNo

onSelectionChange

Callback that is called when the text input selection is changed. This will be called with { nativeEvent: { selection: { start, end } } }. This prop requires multiline={true} to be set.

TypeRequired
functionNo

onSubmitEditing

Callback that is called when the text input's submit button is pressed with the argument {nativeEvent: {text, eventCount, target}}.

TypeRequired
functionNo

placeholder

The string that will be rendered before text input has been entered.

TypeRequired
stringNo

placeholderTextColor

The text color of the placeholder string.

TypeRequired
colorNo

returnKeyLabel

Sets the return key to the label. Use it instead of returnKeyType.

TypeRequiredPlatform
stringNoAndroid

returnKeyType

Determines how the return key should look. On Android you can also use returnKeyLabel.

Cross platform

The following values work across platforms:

  • done
  • go
  • next
  • search
  • send

Android Only

The following values work on Android only:

  • none
  • previous

iOS Only

The following values work on iOS only:

  • default
  • emergency-call
  • google
  • join
  • route
  • yahoo
TypeRequired
enum('done', 'go', 'next', 'search', 'send', 'none', 'previous', 'default', 'emergency-call', 'google', 'join', 'route', 'yahoo')No

rejectResponderTermination

iOS Only

If true, allows TextInput to pass touch events to the parent component. This allows components such as SwipeableListView to be swipeable from the TextInput on iOS, as is the case on Android by default. If false, TextInput always asks to handle the input (except when disabled). The default value is true.

TypeRequiredPlatform
boolNoiOS

scrollEnabled

If false, scrolling of the text view will be disabled. The default value is true. Only works with multiline={true}.

TypeRequiredPlatform
boolNoiOS

secureTextEntry

If true, the text input obscures the text entered so that sensitive text like passwords stay secure. The default value is false. Does not work with multiline={true}.

TypeRequired
boolNo

selection

The start and end of the text input's selection. Set start and end to the same value to position the cursor.

TypeRequired
object: {start: number,end: number}No

selectionColor

The highlight and cursor color of the text input.

TypeRequired
colorNo

selectionState

An instance of DocumentSelectionState, this is some state that is responsible for maintaining selection information for a document.

Some functionality that can be performed with this instance is:

  • blur()
  • focus()
  • update()
TypeRequiredPlatform
DocumentSelectionStateNoiOS

selectTextOnFocus

If true, all text will automatically be selected on focus.

TypeRequired
boolNo

showSoftInputOnFocus

When false, it will prevent the soft keyboard from showing when the field is focused. The default value is true.

TypeRequiredPlatform
boolNoAndroid

spellCheck

If false, disables spell-check style (i.e. red underlines). The default value is inherited from autoCorrect.

TypeRequiredPlatform
boolNoiOS

textContentType

Give the keyboard and the system information about the expected semantic meaning for the content that users enter.

For iOS 11+ you can set textContentType to username or password to enable autofill of login details from the device keychain.

For iOS 12+ newPassword can be used to indicate a new password input the user may want to save in the keychain, and oneTimeCode can be used to indicate that a field can be autofilled by a code arriving in an SMS.

To disable autofill, set textContentType to none.

Possible values for textContentType are:

  • none
  • URL
  • addressCity
  • addressCityAndState
  • addressState
  • countryName
  • creditCardNumber
  • emailAddress
  • familyName
  • fullStreetAddress
  • givenName
  • jobTitle
  • location
  • middleName
  • name
  • namePrefix
  • nameSuffix
  • nickname
  • organizationName
  • postalCode
  • streetAddressLine1
  • streetAddressLine2
  • sublocality
  • telephoneNumber
  • username
  • password
  • newPassword
  • oneTimeCode
TypeRequiredPlatform
enum('none', 'URL', 'addressCity', 'addressCityAndState', 'addressState', 'countryName', 'creditCardNumber', 'emailAddress', 'familyName', 'fullStreetAddress', 'givenName', 'jobTitle', 'location', 'middleName', 'name', 'namePrefix', 'nameSuffix', 'nickname', 'organizationName', 'postalCode', 'streetAddressLine1', 'streetAddressLine2', 'sublocality', 'telephoneNumber', 'username', 'password')NoiOS

style

Note that not all Text styles are supported, an incomplete list of what is not supported includes:

  • borderLeftWidth
  • borderTopWidth
  • borderRightWidth
  • borderBottomWidth
  • borderTopLeftRadius
  • borderTopRightRadius
  • borderBottomRightRadius
  • borderBottomLeftRadius

see Issue#7070 for more detail.

Styles

TypeRequired
TextNo

textBreakStrategy

Set text break strategy on Android API Level 23+, possible values are simple, highQuality, balanced The default value is simple.

TypeRequiredPlatform
enum('simple', 'highQuality', 'balanced')NoAndroid

underlineColorAndroid

The color of the TextInput underline.

TypeRequiredPlatform
colorNoAndroid

value

The value to show for the text input. TextInput is a controlled component, which means the native value will be forced to match this value prop if provided. For most uses, this works great, but in some cases this may cause flickering - one common cause is preventing edits by keeping value the same. In addition to setting the same value, either set editable={false}, or set/update maxLength to prevent unwanted edits without flicker.

TypeRequired
stringNo

Methods

clear()

clear();

Removes all text from the TextInput.

isFocused()

isFocused();

Returns true if the input is currently focused; false otherwise.

Known issues

Edit this page
Last updated on
- + diff --git a/docs/0.60/textinput/index.html b/docs/0.60/textinput/index.html index c71ddb7ff0c..0e2b1f2f267 100644 --- a/docs/0.60/textinput/index.html +++ b/docs/0.60/textinput/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

TextInput

A foundational component for inputting text into the app via a keyboard. Props provide configurability for several features, such as auto-correction, auto-capitalization, placeholder text, and different keyboard types, such as a numeric keypad.

The most basic use case is to plop down a TextInput and subscribe to the onChangeText events to read the user input. There are also other events, such as onSubmitEditing and onFocus that can be subscribed to. A minimal example:

Two methods exposed via the native element are .focus() and .blur() that will focus or blur the TextInput programmatically.

Note that some props are only available with multiline={true/false}. Additionally, border styles that apply to only one side of the element (e.g., borderBottomColor, borderLeftWidth, etc.) will not be applied if multiline=false. To achieve the same effect, you can wrap your TextInput in a View:

TextInput has by default a border at the bottom of its view. This border has its padding set by the background image provided by the system, and it cannot be changed. Solutions to avoid this is to either not set height explicitly, case in which the system will take care of displaying the border in the correct position, or to not display the border by setting underlineColorAndroid to transparent.

Note that on Android performing text selection in input can change app's activity windowSoftInputMode param to adjustResize. This may cause issues with components that have position: 'absolute' while keyboard is active. To avoid this behavior either specify windowSoftInputMode in AndroidManifest.xml ( https://developer.android.com/guide/topics/manifest/activity-element.html ) or control this param programmatically with native code.

Reference

Props

Inherits View Props.

allowFontScaling

Specifies whether fonts should scale to respect Text Size accessibility settings. The default is true.

TypeRequired
boolNo

autoCapitalize

Can tell TextInput to automatically capitalize certain characters. This property is not supported by some keyboard types such as name-phone-pad.

  • characters: all characters.
  • words: first letter of each word.
  • sentences: first letter of each sentence (default).
  • none: don't auto capitalize anything.
TypeRequired
enum('none', 'sentences', 'words', 'characters')No

autoCompleteType

Specifies autocomplete hints for the system, so it can provide autofill. On Android, the system will always attempt to offer autofill by using heuristics to identify the type of content. To disable autocomplete, set autoCompleteType to off.

Possible values for autoCompleteType are:

  • off
  • username
  • password
  • email
  • name
  • tel
  • street-address
  • postal-code
  • cc-number
  • cc-csc
  • cc-exp
  • cc-exp-month
  • cc-exp-year
TypeRequiredPlatform
enum('off', 'username', 'password', 'email', 'name', 'tel', 'street-address', 'postal-code', 'cc-number', 'cc-csc', 'cc-exp', 'cc-exp-month', 'cc-exp-year')NoAndroid

autoCorrect

If false, disables auto-correct. The default value is true.

TypeRequired
boolNo

autoFocus

If true, focuses the input on componentDidMount. The default value is false.

TypeRequired
boolNo

blurOnSubmit

If true, the text field will blur when submitted. The default value is true for single-line fields and false for multiline fields. Note that for multiline fields, setting blurOnSubmit to true means that pressing return will blur the field and trigger the onSubmitEditing event instead of inserting a newline into the field.

TypeRequired
boolNo

caretHidden

If true, caret is hidden. The default value is false.

TypeRequired
boolNo

clearButtonMode

When the clear button should appear on the right side of the text view. This property is supported only for single-line TextInput component. The default value is never.

TypeRequiredPlatform
enum('never', 'while-editing', 'unless-editing', 'always')NoiOS

clearTextOnFocus

If true, clears the text field automatically when editing begins.

TypeRequiredPlatform
boolNoiOS

contextMenuHidden

If true, context menu is hidden. The default value is false.

TypeRequired
boolNo

dataDetectorTypes

Determines the types of data converted to clickable URLs in the text input. Only valid if multiline={true} and editable={false}. By default no data types are detected.

You can provide one type or an array of many types.

Possible values for dataDetectorTypes are:

  • 'phoneNumber'
  • 'link'
  • 'address'
  • 'calendarEvent'
  • 'none'
  • 'all'
TypeRequiredPlatform
enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all'), ,array of enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all')NoiOS

defaultValue

Provides an initial value that will change when the user starts typing. Useful for use-cases where you do not want to deal with listening to events and updating the value prop to keep the controlled state in sync.

TypeRequired
stringNo

disableFullscreenUI

When false, if there is a small amount of space available around a text input (e.g. landscape orientation on a phone), the OS may choose to have the user edit the text inside of a full screen text input mode. When true, this feature is disabled and users will always edit the text directly inside of the text input. Defaults to false.

TypeRequiredPlatform
boolNoAndroid

editable

If false, text is not editable. The default value is true.

TypeRequired
boolNo

enablesReturnKeyAutomatically

If true, the keyboard disables the return key when there is no text and automatically enables it when there is text. The default value is false.

TypeRequiredPlatform
boolNoiOS

importantForAutofill

Say the system whether the individual fields in your app should be included in a view structure for autofill purposes on Android API Level 26+, possible values are auto, no, noExcludeDescendants, yes, yesExcludeDescendants. The default value is auto.

  • auto: Let the Android System use its heuristics to determine if the view is important for autofill.
  • no: This view isn't important for autofill.
  • noExcludeDescendants: This view and its children aren't important for autofill.
  • yes: This view is important for autofill.
  • yesExcludeDescendants: This view is important for autofill, but its children aren't important for autofill.
TypeRequiredPlatform
enum('auto', 'no', 'noExcludeDescendants', 'yes', 'yesExcludeDescendants')NoAndroid

inlineImageLeft

If defined, the provided image resource will be rendered on the left. The image resource must be inside /android/app/src/main/res/drawable and referenced like

<TextInput
inlineImageLeft='search_icon'
/>
TypeRequiredPlatform
stringNoAndroid

inlineImagePadding

Padding between the inline image, if any, and the text input itself.

TypeRequiredPlatform
numberNoAndroid

inputAccessoryViewID

An optional identifier which links a custom InputAccessoryView to this text input. The InputAccessoryView is rendered above the keyboard when this text input is focused.

TypeRequiredPlatform
stringNoiOS

keyboardAppearance

Determines the color of the keyboard.

TypeRequiredPlatform
enum('default', 'light', 'dark')NoiOS

keyboardType

Determines which keyboard to open, e.g.numeric.

See screenshots of all the types here.

The following values work across platforms:

  • default
  • number-pad
  • decimal-pad
  • numeric
  • email-address
  • phone-pad

iOS Only

The following values work on iOS only:

  • ascii-capable
  • numbers-and-punctuation
  • url
  • name-phone-pad
  • twitter
  • web-search

Android Only

The following values work on Android only:

  • visible-password
TypeRequired
enum('default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter', 'web-search', 'visible-password')No

maxFontSizeMultiplier

Specifies largest possible scale a font can reach when allowFontScaling is enabled. Possible values:

  • null/undefined (default): inherit from the parent node or the global default (0)
  • 0: no max, ignore parent/global default
  • >= 1: sets the maxFontSizeMultiplier of this node to this value
TypeRequired
numberNo

maxLength

Limits the maximum number of characters that can be entered. Use this instead of implementing the logic in JS to avoid flicker.

TypeRequired
numberNo

multiline

If true, the text input can be multiple lines. The default value is false. It is important to note that this aligns the text to the top on iOS, and centers it on Android. Use with textAlignVertical set to top for the same behavior in both platforms.

TypeRequired
boolNo

numberOfLines

Sets the number of lines for a TextInput. Use it with multiline set to true to be able to fill the lines.

TypeRequiredPlatform
numberNoAndroid

onBlur

Callback that is called when the text input is blurred.

TypeRequired
functionNo

onChange

Callback that is called when the text input's text changes. This will be called with { nativeEvent: { eventCount, target, text} }

TypeRequired
functionNo

onChangeText

Callback that is called when the text input's text changes. Changed text is passed as a single string argument to the callback handler.

TypeRequired
functionNo

onContentSizeChange

Callback that is called when the text input's content size changes. This will be called with { nativeEvent: { contentSize: { width, height } } }.

Only called for multiline text inputs.

TypeRequired
functionNo

onEndEditing

Callback that is called when text input ends.

TypeRequired
functionNo

onFocus

Callback that is called when the text input is focused. This is called with { nativeEvent: { target } }.

TypeRequired
functionNo

onKeyPress

Callback that is called when a key is pressed. This will be called with { nativeEvent: { key: keyValue } } where keyValue is 'Enter' or 'Backspace' for respective keys and the typed-in character otherwise including ' ' for space. Fires before onChange callbacks. Note: on Android only the inputs from soft keyboard are handled, not the hardware keyboard inputs.

TypeRequired
functionNo

onLayout

Invoked on mount and layout changes with { nativeEvent: {layout: {x, y, width, height}, target } }.

TypeRequired
functionNo

onScroll

Invoked on content scroll with { nativeEvent: { contentOffset: { x, y } } }. May also contain other properties from ScrollEvent but on Android contentSize is not provided for performance reasons.

TypeRequired
functionNo

onSelectionChange

Callback that is called when the text input selection is changed. This will be called with { nativeEvent: { selection: { start, end } } }. This prop requires multiline={true} to be set.

TypeRequired
functionNo

onSubmitEditing

Callback that is called when the text input's submit button is pressed with the argument {nativeEvent: {text, eventCount, target}}.

TypeRequired
functionNo

placeholder

The string that will be rendered before text input has been entered.

TypeRequired
stringNo

placeholderTextColor

The text color of the placeholder string.

TypeRequired
colorNo

returnKeyLabel

Sets the return key to the label. Use it instead of returnKeyType.

TypeRequiredPlatform
stringNoAndroid

returnKeyType

Determines how the return key should look. On Android you can also use returnKeyLabel.

Cross platform

The following values work across platforms:

  • done
  • go
  • next
  • search
  • send

Android Only

The following values work on Android only:

  • none
  • previous

iOS Only

The following values work on iOS only:

  • default
  • emergency-call
  • google
  • join
  • route
  • yahoo
TypeRequired
enum('done', 'go', 'next', 'search', 'send', 'none', 'previous', 'default', 'emergency-call', 'google', 'join', 'route', 'yahoo')No

rejectResponderTermination

iOS Only

If true, allows TextInput to pass touch events to the parent component. This allows components such as SwipeableListView to be swipeable from the TextInput on iOS, as is the case on Android by default. If false, TextInput always asks to handle the input (except when disabled). The default value is true.

TypeRequiredPlatform
boolNoiOS

scrollEnabled

If false, scrolling of the text view will be disabled. The default value is true. Only works with multiline={true}.

TypeRequiredPlatform
boolNoiOS

secureTextEntry

If true, the text input obscures the text entered so that sensitive text like passwords stay secure. The default value is false. Does not work with multiline={true}.

TypeRequired
boolNo

selection

The start and end of the text input's selection. Set start and end to the same value to position the cursor.

TypeRequired
object: {start: number,end: number}No

selectionColor

The highlight and cursor color of the text input.

TypeRequired
colorNo

selectionState

An instance of DocumentSelectionState, this is some state that is responsible for maintaining selection information for a document.

Some functionality that can be performed with this instance is:

  • blur()
  • focus()
  • update()
TypeRequiredPlatform
DocumentSelectionStateNoiOS

selectTextOnFocus

If true, all text will automatically be selected on focus.

TypeRequired
boolNo

showSoftInputOnFocus

When false, it will prevent the soft keyboard from showing when the field is focused. The default value is true.

TypeRequiredPlatform
boolNoAndroid

spellCheck

If false, disables spell-check style (i.e. red underlines). The default value is inherited from autoCorrect.

TypeRequiredPlatform
boolNoiOS

textContentType

Give the keyboard and the system information about the expected semantic meaning for the content that users enter.

For iOS 11+ you can set textContentType to username or password to enable autofill of login details from the device keychain.

For iOS 12+ newPassword can be used to indicate a new password input the user may want to save in the keychain, and oneTimeCode can be used to indicate that a field can be autofilled by a code arriving in an SMS.

To disable autofill, set textContentType to none.

Possible values for textContentType are:

  • none
  • URL
  • addressCity
  • addressCityAndState
  • addressState
  • countryName
  • creditCardNumber
  • emailAddress
  • familyName
  • fullStreetAddress
  • givenName
  • jobTitle
  • location
  • middleName
  • name
  • namePrefix
  • nameSuffix
  • nickname
  • organizationName
  • postalCode
  • streetAddressLine1
  • streetAddressLine2
  • sublocality
  • telephoneNumber
  • username
  • password
  • newPassword
  • oneTimeCode
TypeRequiredPlatform
enum('none', 'URL', 'addressCity', 'addressCityAndState', 'addressState', 'countryName', 'creditCardNumber', 'emailAddress', 'familyName', 'fullStreetAddress', 'givenName', 'jobTitle', 'location', 'middleName', 'name', 'namePrefix', 'nameSuffix', 'nickname', 'organizationName', 'postalCode', 'streetAddressLine1', 'streetAddressLine2', 'sublocality', 'telephoneNumber', 'username', 'password')NoiOS

style

Note that not all Text styles are supported, an incomplete list of what is not supported includes:

  • borderLeftWidth
  • borderTopWidth
  • borderRightWidth
  • borderBottomWidth
  • borderTopLeftRadius
  • borderTopRightRadius
  • borderBottomRightRadius
  • borderBottomLeftRadius

see Issue#7070 for more detail.

Styles

TypeRequired
TextNo

textBreakStrategy

Set text break strategy on Android API Level 23+, possible values are simple, highQuality, balanced The default value is simple.

TypeRequiredPlatform
enum('simple', 'highQuality', 'balanced')NoAndroid

underlineColorAndroid

The color of the TextInput underline.

TypeRequiredPlatform
colorNoAndroid

value

The value to show for the text input. TextInput is a controlled component, which means the native value will be forced to match this value prop if provided. For most uses, this works great, but in some cases this may cause flickering - one common cause is preventing edits by keeping value the same. In addition to setting the same value, either set editable={false}, or set/update maxLength to prevent unwanted edits without flicker.

TypeRequired
stringNo

Methods

clear()

clear();

Removes all text from the TextInput.

isFocused()

isFocused();

Returns true if the input is currently focused; false otherwise.

Known issues

Edit this page
Last updated on
- + diff --git a/docs/0.60/timepickerandroid.html b/docs/0.60/timepickerandroid.html index 532cfbc88c9..3418d54edc7 100644 --- a/docs/0.60/timepickerandroid.html +++ b/docs/0.60/timepickerandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

TimePickerAndroid

Opens the standard Android time picker dialog.

TimePickerAndroid has been merged with DatePickerIOS and DatePickerAndroid into a single component called DateTimePicker and will be removed in a future release.

Example

try {
const { action, hour, minute } = await TimePickerAndroid.open({
hour: 14,
minute: 0,
is24Hour: false // Will display '2 PM'
});
if (action !== TimePickerAndroid.dismissedAction) {
// Selected hour (0-23), minute (0-59)
}
} catch ({ code, message }) {
console.warn('Cannot open time picker', message);
}

Reference

Methods

open()

static open(options)

Opens the standard Android time picker dialog.

The available keys for the options object are:

  • hour (0-23) - the hour to show, defaults to the current time
  • minute (0-59) - the minute to show, defaults to the current time
  • is24Hour (boolean) - If true, the picker uses the 24-hour format. If false, the picker shows an AM/PM chooser. If undefined, the default for the current locale is used.
  • mode (enum('clock', 'spinner', 'default')) - set the time picker mode
    • 'clock': Show a time picker in clock mode.
    • 'spinner': Show a time picker in spinner mode.
    • 'default': Show a default time picker based on Android versions.

Returns a Promise which will be invoked an object containing action, hour (0-23), minute (0-59) if the user picked a time. If the user dismissed the dialog, the Promise will still be resolved with action being TimePickerAndroid.dismissedAction and all the other keys being undefined. Always check whether the action before reading the values.

timeSetAction()

static timeSetAction()

A time has been selected.

dismissedAction()

static dismissedAction()

The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/0.60/timepickerandroid/index.html b/docs/0.60/timepickerandroid/index.html index 532cfbc88c9..3418d54edc7 100644 --- a/docs/0.60/timepickerandroid/index.html +++ b/docs/0.60/timepickerandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

TimePickerAndroid

Opens the standard Android time picker dialog.

TimePickerAndroid has been merged with DatePickerIOS and DatePickerAndroid into a single component called DateTimePicker and will be removed in a future release.

Example

try {
const { action, hour, minute } = await TimePickerAndroid.open({
hour: 14,
minute: 0,
is24Hour: false // Will display '2 PM'
});
if (action !== TimePickerAndroid.dismissedAction) {
// Selected hour (0-23), minute (0-59)
}
} catch ({ code, message }) {
console.warn('Cannot open time picker', message);
}

Reference

Methods

open()

static open(options)

Opens the standard Android time picker dialog.

The available keys for the options object are:

  • hour (0-23) - the hour to show, defaults to the current time
  • minute (0-59) - the minute to show, defaults to the current time
  • is24Hour (boolean) - If true, the picker uses the 24-hour format. If false, the picker shows an AM/PM chooser. If undefined, the default for the current locale is used.
  • mode (enum('clock', 'spinner', 'default')) - set the time picker mode
    • 'clock': Show a time picker in clock mode.
    • 'spinner': Show a time picker in spinner mode.
    • 'default': Show a default time picker based on Android versions.

Returns a Promise which will be invoked an object containing action, hour (0-23), minute (0-59) if the user picked a time. If the user dismissed the dialog, the Promise will still be resolved with action being TimePickerAndroid.dismissedAction and all the other keys being undefined. Always check whether the action before reading the values.

timeSetAction()

static timeSetAction()

A time has been selected.

dismissedAction()

static dismissedAction()

The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/0.60/timers.html b/docs/0.60/timers.html index 01a7bc28091..393e351bce9 100644 --- a/docs/0.60/timers.html +++ b/docs/0.60/timers.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Timers

Timers are an important part of an application and React Native implements the browser timers.

Timers

  • setTimeout, clearTimeout
  • setInterval, clearInterval
  • setImmediate, clearImmediate
  • requestAnimationFrame, cancelAnimationFrame

requestAnimationFrame(fn) is not the same as setTimeout(fn, 0) - the former will fire after all the frame has flushed, whereas the latter will fire as quickly as possible (over 1000x per second on a iPhone 5S).

setImmediate is executed at the end of the current JavaScript execution block, right before sending the batched response back to native. Note that if you call setImmediate within a setImmediate callback, it will be executed right away, it won't yield back to native in between.

The Promise implementation uses setImmediate as its asynchronicity implementation.

InteractionManager

One reason why well-built native apps feel so smooth is by avoiding expensive operations during interactions and animations. In React Native, we currently have a limitation that there is only a single JS execution thread, but you can use InteractionManager to make sure long-running work is scheduled to start after any interactions/animations have completed.

Applications can schedule tasks to run after interactions with the following:

InteractionManager.runAfterInteractions(() => {
// ...long-running synchronous task...
});

Compare this to other scheduling alternatives:

  • requestAnimationFrame(): for code that animates a view over time.
  • setImmediate/setTimeout/setInterval(): run code later, note this may delay animations.
  • runAfterInteractions(): run code later, without delaying active animations.

The touch handling system considers one or more active touches to be an 'interaction' and will delay runAfterInteractions() callbacks until all touches have ended or been cancelled.

InteractionManager also allows applications to register animations by creating an interaction 'handle' on animation start, and clearing it upon completion:

var handle = InteractionManager.createInteractionHandle();
// run animation... (`runAfterInteractions` tasks are queued)
// later, on animation completion:
InteractionManager.clearInteractionHandle(handle);
// queued tasks run if all handles were cleared
Edit this page
Last updated on
- + diff --git a/docs/0.60/timers/index.html b/docs/0.60/timers/index.html index 01a7bc28091..393e351bce9 100644 --- a/docs/0.60/timers/index.html +++ b/docs/0.60/timers/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Timers

Timers are an important part of an application and React Native implements the browser timers.

Timers

  • setTimeout, clearTimeout
  • setInterval, clearInterval
  • setImmediate, clearImmediate
  • requestAnimationFrame, cancelAnimationFrame

requestAnimationFrame(fn) is not the same as setTimeout(fn, 0) - the former will fire after all the frame has flushed, whereas the latter will fire as quickly as possible (over 1000x per second on a iPhone 5S).

setImmediate is executed at the end of the current JavaScript execution block, right before sending the batched response back to native. Note that if you call setImmediate within a setImmediate callback, it will be executed right away, it won't yield back to native in between.

The Promise implementation uses setImmediate as its asynchronicity implementation.

InteractionManager

One reason why well-built native apps feel so smooth is by avoiding expensive operations during interactions and animations. In React Native, we currently have a limitation that there is only a single JS execution thread, but you can use InteractionManager to make sure long-running work is scheduled to start after any interactions/animations have completed.

Applications can schedule tasks to run after interactions with the following:

InteractionManager.runAfterInteractions(() => {
// ...long-running synchronous task...
});

Compare this to other scheduling alternatives:

  • requestAnimationFrame(): for code that animates a view over time.
  • setImmediate/setTimeout/setInterval(): run code later, note this may delay animations.
  • runAfterInteractions(): run code later, without delaying active animations.

The touch handling system considers one or more active touches to be an 'interaction' and will delay runAfterInteractions() callbacks until all touches have ended or been cancelled.

InteractionManager also allows applications to register animations by creating an interaction 'handle' on animation start, and clearing it upon completion:

var handle = InteractionManager.createInteractionHandle();
// run animation... (`runAfterInteractions` tasks are queued)
// later, on animation completion:
InteractionManager.clearInteractionHandle(handle);
// queued tasks run if all handles were cleared
Edit this page
Last updated on
- + diff --git a/docs/0.60/toastandroid.html b/docs/0.60/toastandroid.html index 6e47875ca46..8b27ed890fe 100644 --- a/docs/0.60/toastandroid.html +++ b/docs/0.60/toastandroid.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
render() {
return (
<View style={styles.container}>
<Toast visible={this.state.visible} message="Example" />
<Button
title="Toggle Modal"
onPress={this.handleButtonPress}
/>
</View>
);
}
}

Reference

Methods

show()

static show(message, duration)

showWithGravity()

static showWithGravity(message, duration, gravity)

showWithGravityAndOffset()

static showWithGravityAndOffset(message, duration, gravity, xOffset, yOffset)

Properties

SHORT

Indicates the duration on the screen.

ToastAndroid.SHORT;

LONG

Indicates the duration on the screen.

ToastAndroid.LONG;

TOP

Indicates the position on the screen.

ToastAndroid.TOP;

BOTTOM

Indicates the position on the screen.

ToastAndroid.BOTTOM;

CENTER

Indicates the position on the screen.

ToastAndroid.CENTER;
Edit this page
Last updated on
- + diff --git a/docs/0.60/toastandroid/index.html b/docs/0.60/toastandroid/index.html index 6e47875ca46..8b27ed890fe 100644 --- a/docs/0.60/toastandroid/index.html +++ b/docs/0.60/toastandroid/index.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
render() {
return (
<View style={styles.container}>
<Toast visible={this.state.visible} message="Example" />
<Button
title="Toggle Modal"
onPress={this.handleButtonPress}
/>
</View>
);
}
}

Reference

Methods

show()

static show(message, duration)

showWithGravity()

static showWithGravity(message, duration, gravity)

showWithGravityAndOffset()

static showWithGravityAndOffset(message, duration, gravity, xOffset, yOffset)

Properties

SHORT

Indicates the duration on the screen.

ToastAndroid.SHORT;

LONG

Indicates the duration on the screen.

ToastAndroid.LONG;

TOP

Indicates the position on the screen.

ToastAndroid.TOP;

BOTTOM

Indicates the position on the screen.

ToastAndroid.BOTTOM;

CENTER

Indicates the position on the screen.

ToastAndroid.CENTER;
Edit this page
Last updated on
- + diff --git a/docs/0.60/toolbarandroid.html b/docs/0.60/toolbarandroid.html index 8550b573800..0aba9679607 100644 --- a/docs/0.60/toolbarandroid.html +++ b/docs/0.60/toolbarandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

ToolbarAndroid

NOTE: Toolbar Android has been deprecated and removed from the package since React Native v0.61.0. Use @react-native-community/toolbar-android instead.

React component that wraps the Android-only Toolbar widget. A Toolbar can display a logo, navigation icon (e.g. hamburger menu), a title & subtitle and a list of actions. The title and subtitle are expanded so the logo and navigation icons are displayed on the left, title and subtitle in the middle and the actions on the right.

If the toolbar has an only child, it will be displayed between the title and actions.

Although the Toolbar supports remote images for the logo, navigation and action icons, this should only be used in DEV mode where require('./some_icon.png') translates into a bundler URL. In release mode you should always use a drawable resource for these icons. Using require('./some_icon.png') will do this automatically for you, so as long as you don't explicitly use e.g. {uri: 'http://...'}, you will be good.

Example:

render: function() {
return (
<ToolbarAndroid
logo={require('./app_logo.png')}
title="AwesomeApp"
actions={[{title: 'Settings', icon: require('./icon_settings.png'), show: 'always'}]}
onActionSelected={this.onActionSelected} />
)
},
onActionSelected: function(position) {
if (position === 0) { // index of 'Settings'
showSettings();
}
}

Reference

Props

Inherits View Props.

actions

Sets possible actions on the toolbar as part of the action menu. These are displayed as icons or text on the right side of the widget. If they don't fit they are placed in an 'overflow' menu.

This property takes an array of objects, where each object has the following keys:

  • title: required, the title of this action
  • icon: the icon for this action, e.g. require('./some_icon.png')
  • show: when to show this action as an icon or hide it in the overflow menu: always, ifRoom or never
  • showWithText: boolean, whether to show text alongside the icon or not
TypeRequired
array of object: {title: string,icon: optionalImageSource,show: enum('always', 'ifRoom', 'never'),showWithText: bool}No

contentInsetStart

Sets the content inset for the toolbar starting edge.

The content inset affects the valid area for Toolbar content other than the navigation button and menu. Insets define the minimum margin for these components and can be used to effectively align Toolbar content along well-known gridlines.

TypeRequired
numberNo

contentInsetEnd

Sets the content inset for the toolbar ending edge.

The content inset affects the valid area for Toolbar content other than the navigation button and menu. Insets define the minimum margin for these components and can be used to effectively align Toolbar content along well-known gridlines.

TypeRequired
numberNo

logo

Sets the toolbar logo.

TypeRequired
optionalImageSourceNo

navIcon

Sets the navigation icon.

TypeRequired
optionalImageSourceNo

onActionSelected

Callback that is called when an action is selected. The only argument that is passed to the callback is the position of the action in the actions array.

TypeRequired
functionNo

onIconClicked

Callback called when the icon is selected.

TypeRequired
functionNo

overflowIcon

Sets the overflow icon.

TypeRequired
optionalImageSourceNo

rtl

Used to set the toolbar direction to RTL. In addition to this property you need to add

android:supportsRtl="true"

to your application AndroidManifest.xml and then call setLayoutDirection(LayoutDirection.RTL) in your MainActivity onCreate method.

TypeRequired
boolNo

subtitle

Sets the toolbar subtitle.

TypeRequired
stringNo

subtitleColor

Sets the toolbar subtitle color.

TypeRequired
colorNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

title

Sets the toolbar title.

TypeRequired
stringNo

titleColor

Sets the toolbar title color.

TypeRequired
colorNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/toolbarandroid/index.html b/docs/0.60/toolbarandroid/index.html index 8550b573800..0aba9679607 100644 --- a/docs/0.60/toolbarandroid/index.html +++ b/docs/0.60/toolbarandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

ToolbarAndroid

NOTE: Toolbar Android has been deprecated and removed from the package since React Native v0.61.0. Use @react-native-community/toolbar-android instead.

React component that wraps the Android-only Toolbar widget. A Toolbar can display a logo, navigation icon (e.g. hamburger menu), a title & subtitle and a list of actions. The title and subtitle are expanded so the logo and navigation icons are displayed on the left, title and subtitle in the middle and the actions on the right.

If the toolbar has an only child, it will be displayed between the title and actions.

Although the Toolbar supports remote images for the logo, navigation and action icons, this should only be used in DEV mode where require('./some_icon.png') translates into a bundler URL. In release mode you should always use a drawable resource for these icons. Using require('./some_icon.png') will do this automatically for you, so as long as you don't explicitly use e.g. {uri: 'http://...'}, you will be good.

Example:

render: function() {
return (
<ToolbarAndroid
logo={require('./app_logo.png')}
title="AwesomeApp"
actions={[{title: 'Settings', icon: require('./icon_settings.png'), show: 'always'}]}
onActionSelected={this.onActionSelected} />
)
},
onActionSelected: function(position) {
if (position === 0) { // index of 'Settings'
showSettings();
}
}

Reference

Props

Inherits View Props.

actions

Sets possible actions on the toolbar as part of the action menu. These are displayed as icons or text on the right side of the widget. If they don't fit they are placed in an 'overflow' menu.

This property takes an array of objects, where each object has the following keys:

  • title: required, the title of this action
  • icon: the icon for this action, e.g. require('./some_icon.png')
  • show: when to show this action as an icon or hide it in the overflow menu: always, ifRoom or never
  • showWithText: boolean, whether to show text alongside the icon or not
TypeRequired
array of object: {title: string,icon: optionalImageSource,show: enum('always', 'ifRoom', 'never'),showWithText: bool}No

contentInsetStart

Sets the content inset for the toolbar starting edge.

The content inset affects the valid area for Toolbar content other than the navigation button and menu. Insets define the minimum margin for these components and can be used to effectively align Toolbar content along well-known gridlines.

TypeRequired
numberNo

contentInsetEnd

Sets the content inset for the toolbar ending edge.

The content inset affects the valid area for Toolbar content other than the navigation button and menu. Insets define the minimum margin for these components and can be used to effectively align Toolbar content along well-known gridlines.

TypeRequired
numberNo

logo

Sets the toolbar logo.

TypeRequired
optionalImageSourceNo

navIcon

Sets the navigation icon.

TypeRequired
optionalImageSourceNo

onActionSelected

Callback that is called when an action is selected. The only argument that is passed to the callback is the position of the action in the actions array.

TypeRequired
functionNo

onIconClicked

Callback called when the icon is selected.

TypeRequired
functionNo

overflowIcon

Sets the overflow icon.

TypeRequired
optionalImageSourceNo

rtl

Used to set the toolbar direction to RTL. In addition to this property you need to add

android:supportsRtl="true"

to your application AndroidManifest.xml and then call setLayoutDirection(LayoutDirection.RTL) in your MainActivity onCreate method.

TypeRequired
boolNo

subtitle

Sets the toolbar subtitle.

TypeRequired
stringNo

subtitleColor

Sets the toolbar subtitle color.

TypeRequired
colorNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

title

Sets the toolbar title.

TypeRequired
stringNo

titleColor

Sets the toolbar title color.

TypeRequired
colorNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/touchablehighlight.html b/docs/0.60/touchablehighlight.html index 01ce4df1257..36b12e14000 100644 --- a/docs/0.60/touchablehighlight.html +++ b/docs/0.60/touchablehighlight.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

TouchableHighlight

A wrapper for making views respond properly to touches. On press down, the opacity of the wrapped view is decreased, which allows the underlay color to show through, darkening or tinting the view.

The underlay comes from wrapping the child in a new View, which can affect layout, and sometimes cause unwanted visual artifacts if not used correctly, for example if the backgroundColor of the wrapped view isn't explicitly set to an opaque color.

TouchableHighlight must have one child (not zero or more than one). If you wish to have several child components, wrap them in a View.

Example:

renderButton: function() {
return (
<TouchableHighlight onPress={this._onPressButton}>
<Image
style={styles.button}
source={require('./myButton.png')}
/>
</TouchableHighlight>
);
},

Example

Props

Reference

Props

Inherits TouchableWithoutFeedback Props.

activeOpacity

Determines what the opacity of the wrapped view should be when touch is active. The value should be between 0 and 1. Defaults to 0.85. Requires underlayColor to be set.

TypeRequired
numberNo

onHideUnderlay

Called immediately after the underlay is hidden.

TypeRequired
functionNo

onShowUnderlay

Called immediately after the underlay is shown.

TypeRequired
functionNo

style

TypeRequired
View.styleNo

underlayColor

The color of the underlay that will show through when the touch is active.

TypeRequired
colorNo

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

tvParallaxProperties

(Apple TV only) Object with properties to control Apple TV parallax effects.

enabled: If true, parallax effects are enabled. Defaults to true. shiftDistanceX: Defaults to 2.0. shiftDistanceY: Defaults to 2.0. tiltAngle: Defaults to 0.05. magnification: Defaults to 1.0. pressMagnification: Defaults to 1.0. pressDuration: Defaults to 0.3. pressDelay: Defaults to 0.0.

TypeRequiredPlatform
objectNoiOS

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

testOnly_pressed

Handy for snapshot tests.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/touchablehighlight/index.html b/docs/0.60/touchablehighlight/index.html index 01ce4df1257..36b12e14000 100644 --- a/docs/0.60/touchablehighlight/index.html +++ b/docs/0.60/touchablehighlight/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

TouchableHighlight

A wrapper for making views respond properly to touches. On press down, the opacity of the wrapped view is decreased, which allows the underlay color to show through, darkening or tinting the view.

The underlay comes from wrapping the child in a new View, which can affect layout, and sometimes cause unwanted visual artifacts if not used correctly, for example if the backgroundColor of the wrapped view isn't explicitly set to an opaque color.

TouchableHighlight must have one child (not zero or more than one). If you wish to have several child components, wrap them in a View.

Example:

renderButton: function() {
return (
<TouchableHighlight onPress={this._onPressButton}>
<Image
style={styles.button}
source={require('./myButton.png')}
/>
</TouchableHighlight>
);
},

Example

Props

Reference

Props

Inherits TouchableWithoutFeedback Props.

activeOpacity

Determines what the opacity of the wrapped view should be when touch is active. The value should be between 0 and 1. Defaults to 0.85. Requires underlayColor to be set.

TypeRequired
numberNo

onHideUnderlay

Called immediately after the underlay is hidden.

TypeRequired
functionNo

onShowUnderlay

Called immediately after the underlay is shown.

TypeRequired
functionNo

style

TypeRequired
View.styleNo

underlayColor

The color of the underlay that will show through when the touch is active.

TypeRequired
colorNo

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

tvParallaxProperties

(Apple TV only) Object with properties to control Apple TV parallax effects.

enabled: If true, parallax effects are enabled. Defaults to true. shiftDistanceX: Defaults to 2.0. shiftDistanceY: Defaults to 2.0. tiltAngle: Defaults to 0.05. magnification: Defaults to 1.0. pressMagnification: Defaults to 1.0. pressDuration: Defaults to 0.3. pressDelay: Defaults to 0.0.

TypeRequiredPlatform
objectNoiOS

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

testOnly_pressed

Handy for snapshot tests.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/0.60/touchablenativefeedback.html b/docs/0.60/touchablenativefeedback.html index bb12db0bcc5..5583150592d 100644 --- a/docs/0.60/touchablenativefeedback.html +++ b/docs/0.60/touchablenativefeedback.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

TouchableNativeFeedback

A wrapper for making views respond properly to touches (Android only). On Android this component uses native state drawable to display touch feedback.

At the moment it only supports having a single View instance as a child node, as it's implemented by replacing that View with another instance of RCTView node with some additional properties set.

Background drawable of native feedback touchable can be customized with background property.

Example:

renderButton: function() {
return (
<TouchableNativeFeedback
onPress={this._onPressButton}
background={TouchableNativeFeedback.SelectableBackground()}>
<View style={{width: 150, height: 100, backgroundColor: 'red'}}>
<Text style={{margin: 30}}>Button</Text>
</View>
</TouchableNativeFeedback>
);
},

Reference

Props

Inherits TouchableWithoutFeedback Props.

background

Determines the type of background drawable that's going to be used to display feedback. It takes an object with type property and extra data depending on the type. It's recommended to use one of the static methods to generate that dictionary.

TypeRequired
backgroundPropTypeNo

useForeground

Set to true to add the ripple effect to the foreground of the view, instead of the background. This is useful if one of your child views has a background of its own, or you're e.g. displaying images, and you don't want the ripple to be covered by them.

Check TouchableNativeFeedback.canUseNativeForeground() first, as this is only available on Android 6.0 and above. If you try to use this on older versions you will get a warning and fallback to background.

TypeRequired
boolNo

hasTVPreferredFocus

TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

Methods

SelectableBackground()

static SelectableBackground()

Creates an object that represents android theme's default background for selectable elements (?android:attr/selectableItemBackground).

SelectableBackgroundBorderless()

static SelectableBackgroundBorderless()

Creates an object that represent android theme's default background for borderless selectable elements (?android:attr/selectableItemBackgroundBorderless). Available on android API level 21+.

Ripple()

static Ripple(color: string, borderless: boolean)

Creates an object that represents ripple drawable with specified color (as a string). If property borderless evaluates to true the ripple will render outside of the view bounds (see native actionbar buttons as an example of that behavior). This background type is available on Android API level 21+.

Parameters:

NameTypeRequiredDescription
colorstringYesThe ripple color
borderlessbooleanYesIf the ripple can render outside its bounds

canUseNativeForeground()

static canUseNativeForeground()
Edit this page
Last updated on
- + diff --git a/docs/0.60/touchablenativefeedback/index.html b/docs/0.60/touchablenativefeedback/index.html index bb12db0bcc5..5583150592d 100644 --- a/docs/0.60/touchablenativefeedback/index.html +++ b/docs/0.60/touchablenativefeedback/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

TouchableNativeFeedback

A wrapper for making views respond properly to touches (Android only). On Android this component uses native state drawable to display touch feedback.

At the moment it only supports having a single View instance as a child node, as it's implemented by replacing that View with another instance of RCTView node with some additional properties set.

Background drawable of native feedback touchable can be customized with background property.

Example:

renderButton: function() {
return (
<TouchableNativeFeedback
onPress={this._onPressButton}
background={TouchableNativeFeedback.SelectableBackground()}>
<View style={{width: 150, height: 100, backgroundColor: 'red'}}>
<Text style={{margin: 30}}>Button</Text>
</View>
</TouchableNativeFeedback>
);
},

Reference

Props

Inherits TouchableWithoutFeedback Props.

background

Determines the type of background drawable that's going to be used to display feedback. It takes an object with type property and extra data depending on the type. It's recommended to use one of the static methods to generate that dictionary.

TypeRequired
backgroundPropTypeNo

useForeground

Set to true to add the ripple effect to the foreground of the view, instead of the background. This is useful if one of your child views has a background of its own, or you're e.g. displaying images, and you don't want the ripple to be covered by them.

Check TouchableNativeFeedback.canUseNativeForeground() first, as this is only available on Android 6.0 and above. If you try to use this on older versions you will get a warning and fallback to background.

TypeRequired
boolNo

hasTVPreferredFocus

TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

Methods

SelectableBackground()

static SelectableBackground()

Creates an object that represents android theme's default background for selectable elements (?android:attr/selectableItemBackground).

SelectableBackgroundBorderless()

static SelectableBackgroundBorderless()

Creates an object that represent android theme's default background for borderless selectable elements (?android:attr/selectableItemBackgroundBorderless). Available on android API level 21+.

Ripple()

static Ripple(color: string, borderless: boolean)

Creates an object that represents ripple drawable with specified color (as a string). If property borderless evaluates to true the ripple will render outside of the view bounds (see native actionbar buttons as an example of that behavior). This background type is available on Android API level 21+.

Parameters:

NameTypeRequiredDescription
colorstringYesThe ripple color
borderlessbooleanYesIf the ripple can render outside its bounds

canUseNativeForeground()

static canUseNativeForeground()
Edit this page
Last updated on
- + diff --git a/docs/0.60/touchableopacity.html b/docs/0.60/touchableopacity.html index 56d76577b8d..bb14602612d 100644 --- a/docs/0.60/touchableopacity.html +++ b/docs/0.60/touchableopacity.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

TouchableOpacity

A wrapper for making views respond properly to touches. On press down, the opacity of the wrapped view is decreased, dimming it.

Opacity is controlled by wrapping the children in an Animated.View, which is added to the view hierarchy. Be aware that this can affect layout.

Example:

renderButton: function() {
return (
<TouchableOpacity onPress={this._onPressButton}>
<Image
style={styles.button}
source={require('./myButton.png')}
/>
</TouchableOpacity>
);
},

Example

Reference

Props

Inherits TouchableWithoutFeedback Props.

style

TypeRequired
View.styleNo

activeOpacity

Determines what the opacity of the wrapped view should be when touch is active. Defaults to 0.2.

TypeRequired
numberNo

tvParallaxProperties

(Apple TV only) Object with properties to control Apple TV parallax effects.

enabled: If true, parallax effects are enabled. Defaults to true. shiftDistanceX: Defaults to 2.0. shiftDistanceY: Defaults to 2.0. tiltAngle: Defaults to 0.05. magnification: Defaults to 1.0. pressMagnification: Defaults to 1.0. pressDuration: Defaults to 0.3. pressDelay: Defaults to 0.0.

TypeRequiredPlatform
objectNoiOS

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

Methods

setOpacityTo()

setOpacityTo((value: number), (duration: number));

Animate the touchable to a new opacity.

Edit this page
Last updated on
- + diff --git a/docs/0.60/touchableopacity/index.html b/docs/0.60/touchableopacity/index.html index 56d76577b8d..bb14602612d 100644 --- a/docs/0.60/touchableopacity/index.html +++ b/docs/0.60/touchableopacity/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

TouchableOpacity

A wrapper for making views respond properly to touches. On press down, the opacity of the wrapped view is decreased, dimming it.

Opacity is controlled by wrapping the children in an Animated.View, which is added to the view hierarchy. Be aware that this can affect layout.

Example:

renderButton: function() {
return (
<TouchableOpacity onPress={this._onPressButton}>
<Image
style={styles.button}
source={require('./myButton.png')}
/>
</TouchableOpacity>
);
},

Example

Reference

Props

Inherits TouchableWithoutFeedback Props.

style

TypeRequired
View.styleNo

activeOpacity

Determines what the opacity of the wrapped view should be when touch is active. Defaults to 0.2.

TypeRequired
numberNo

tvParallaxProperties

(Apple TV only) Object with properties to control Apple TV parallax effects.

enabled: If true, parallax effects are enabled. Defaults to true. shiftDistanceX: Defaults to 2.0. shiftDistanceY: Defaults to 2.0. tiltAngle: Defaults to 0.05. magnification: Defaults to 1.0. pressMagnification: Defaults to 1.0. pressDuration: Defaults to 0.3. pressDelay: Defaults to 0.0.

TypeRequiredPlatform
objectNoiOS

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

Methods

setOpacityTo()

setOpacityTo((value: number), (duration: number));

Animate the touchable to a new opacity.

Edit this page
Last updated on
- + diff --git a/docs/0.60/touchablewithoutfeedback.html b/docs/0.60/touchablewithoutfeedback.html index b69835e29ab..1f4e183f9ee 100644 --- a/docs/0.60/touchablewithoutfeedback.html +++ b/docs/0.60/touchablewithoutfeedback.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
<TouchableWithoutFeedback onPress={() => alert('Pressed!')}>
<MyComponent />
</TouchableWithoutFeedback>;

Reference

Props

accessibilityIgnoresInvertColors

TypeRequired
BooleanNo

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

accessibilityActions

Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The accessibilityActions property should contain a list of action objects. Each action object should contain the field name and label.

See the Accessibility guide for more information.

TypeRequired
arrayNo

onAccessibilityAction

Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform.

See the Accessibility guide for more information.

TypeRequired
functionNo

delayLongPress

Delay in ms, from onPressIn, before onLongPress is called.

TypeRequired
numberNo

delayPressIn

Delay in ms, from the start of the touch, before onPressIn is called.

TypeRequired
numberNo

delayPressOut

Delay in ms, from the release of the touch, before onPressOut is called.

TypeRequired
numberNo

disabled

If true, disable all interactions for this component.

TypeRequired
boolNo

hitSlop

This defines how far your touch can start away from the button. This is added to pressRetentionOffset when moving off of the button. NOTE The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

onBlur

Invoked when the item loses focus.

TypeRequired
functionNo

onFocus

Invoked when the item receives focus.

TypeRequired
functionNo

onLayout

Invoked on mount and layout changes with

{nativeEvent: {layout: {x, y, width, height}}}

TypeRequired
functionNo

onLongPress

TypeRequired
functionNo

onPress

Called when the touch is released, but not if cancelled (e.g. by a scroll that steals the responder lock).

TypeRequired
functionNo

onPressIn

Called as soon as the touchable element is pressed and invoked even before onPress. This can be useful when making network requests.

TypeRequired
functionNo

onPressOut

Called as soon as the touch is released even before onPress.

TypeRequired
functionNo

pressRetentionOffset

When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

nativeID

TypeRequired
stringNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

touchSoundDisabled

If true, doesn't play a system sound on touch.

TypeRequiredPlatform
BooleanNoAndroid

Type Definitions

Event

Type
Object
Edit this page
Last updated on
- + diff --git a/docs/0.60/touchablewithoutfeedback/index.html b/docs/0.60/touchablewithoutfeedback/index.html index b69835e29ab..1f4e183f9ee 100644 --- a/docs/0.60/touchablewithoutfeedback/index.html +++ b/docs/0.60/touchablewithoutfeedback/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
<TouchableWithoutFeedback onPress={() => alert('Pressed!')}>
<MyComponent />
</TouchableWithoutFeedback>;

Reference

Props

accessibilityIgnoresInvertColors

TypeRequired
BooleanNo

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

accessibilityActions

Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The accessibilityActions property should contain a list of action objects. Each action object should contain the field name and label.

See the Accessibility guide for more information.

TypeRequired
arrayNo

onAccessibilityAction

Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform.

See the Accessibility guide for more information.

TypeRequired
functionNo

delayLongPress

Delay in ms, from onPressIn, before onLongPress is called.

TypeRequired
numberNo

delayPressIn

Delay in ms, from the start of the touch, before onPressIn is called.

TypeRequired
numberNo

delayPressOut

Delay in ms, from the release of the touch, before onPressOut is called.

TypeRequired
numberNo

disabled

If true, disable all interactions for this component.

TypeRequired
boolNo

hitSlop

This defines how far your touch can start away from the button. This is added to pressRetentionOffset when moving off of the button. NOTE The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

onBlur

Invoked when the item loses focus.

TypeRequired
functionNo

onFocus

Invoked when the item receives focus.

TypeRequired
functionNo

onLayout

Invoked on mount and layout changes with

{nativeEvent: {layout: {x, y, width, height}}}

TypeRequired
functionNo

onLongPress

TypeRequired
functionNo

onPress

Called when the touch is released, but not if cancelled (e.g. by a scroll that steals the responder lock).

TypeRequired
functionNo

onPressIn

Called as soon as the touchable element is pressed and invoked even before onPress. This can be useful when making network requests.

TypeRequired
functionNo

onPressOut

Called as soon as the touch is released even before onPress.

TypeRequired
functionNo

pressRetentionOffset

When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

nativeID

TypeRequired
stringNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

touchSoundDisabled

If true, doesn't play a system sound on touch.

TypeRequiredPlatform
BooleanNoAndroid

Type Definitions

Event

Type
Object
Edit this page
Last updated on
- + diff --git a/docs/0.60/transforms.html b/docs/0.60/transforms.html index 5766134e960..290894aa361 100644 --- a/docs/0.60/transforms.html +++ b/docs/0.60/transforms.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Transforms

Reference

Props

decomposedMatrix

Deprecated. Use the transform prop instead.

TypeRequired
DecomposedMatrixPropTypeNo

rotation

TypeRequired
deprecatedPropType(ReactPropTypes.number, 'Use the transform prop instead.')No

scaleX

TypeRequired
deprecatedPropType(ReactPropTypes.number, 'Use the transform prop instead.')No

scaleY

TypeRequired
deprecatedPropType(ReactPropTypes.number, 'Use the transform prop instead.')No

transform

transform accepts an array of transformation objects. Each object specifies the property that will be transformed as the key, and the value to use in the transformation. Objects should not be combined. Use a single key/value pair per object.

The rotate transformations require a string so that the transform may be expressed in degrees (deg) or radians (rad). For example:

transform([{ rotateX: '45deg' }, { rotateZ: '0.785398rad' }])

The skew transformations require a string so that the transform may be expressed in degrees (deg). For example:

transform([{ skewX: '45deg' }])

TypeRequired
array of object: {perspective: number}, ,object: {rotate: string}, ,object: {rotateX: string}, ,object: {rotateY: string}, ,object: {rotateZ: string}, ,object: {scale: number}, ,object: {scaleX: number}, ,object: {scaleY: number}, ,object: {translateX: number}, ,object: {translateY: number}, ,object: {skewX: string}, ,object: {skewY: string}No

transformMatrix

Deprecated. Use the transform prop instead.

TypeRequired
TransformMatrixPropTypeNo

translateX

TypeRequired
deprecatedPropType(ReactPropTypes.number, 'Use the transform prop instead.')No

translateY

TypeRequired
deprecatedPropType(ReactPropTypes.number, 'Use the transform prop instead.')No
Edit this page
Last updated on
- + diff --git a/docs/0.60/transforms/index.html b/docs/0.60/transforms/index.html index 5766134e960..290894aa361 100644 --- a/docs/0.60/transforms/index.html +++ b/docs/0.60/transforms/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Transforms

Reference

Props

decomposedMatrix

Deprecated. Use the transform prop instead.

TypeRequired
DecomposedMatrixPropTypeNo

rotation

TypeRequired
deprecatedPropType(ReactPropTypes.number, 'Use the transform prop instead.')No

scaleX

TypeRequired
deprecatedPropType(ReactPropTypes.number, 'Use the transform prop instead.')No

scaleY

TypeRequired
deprecatedPropType(ReactPropTypes.number, 'Use the transform prop instead.')No

transform

transform accepts an array of transformation objects. Each object specifies the property that will be transformed as the key, and the value to use in the transformation. Objects should not be combined. Use a single key/value pair per object.

The rotate transformations require a string so that the transform may be expressed in degrees (deg) or radians (rad). For example:

transform([{ rotateX: '45deg' }, { rotateZ: '0.785398rad' }])

The skew transformations require a string so that the transform may be expressed in degrees (deg). For example:

transform([{ skewX: '45deg' }])

TypeRequired
array of object: {perspective: number}, ,object: {rotate: string}, ,object: {rotateX: string}, ,object: {rotateY: string}, ,object: {rotateZ: string}, ,object: {scale: number}, ,object: {scaleX: number}, ,object: {scaleY: number}, ,object: {translateX: number}, ,object: {translateY: number}, ,object: {skewX: string}, ,object: {skewY: string}No

transformMatrix

Deprecated. Use the transform prop instead.

TypeRequired
TransformMatrixPropTypeNo

translateX

TypeRequired
deprecatedPropType(ReactPropTypes.number, 'Use the transform prop instead.')No

translateY

TypeRequired
deprecatedPropType(ReactPropTypes.number, 'Use the transform prop instead.')No
Edit this page
Last updated on
- + diff --git a/docs/0.60/troubleshooting.html b/docs/0.60/troubleshooting.html index bceb10be3e7..0be70a76597 100644 --- a/docs/0.60/troubleshooting.html +++ b/docs/0.60/troubleshooting.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Troubleshooting

These are some common issues you may run into while setting up React Native. If you encounter something that is not listed here, try searching for the issue in GitHub.

Port already in use

The Metro bundler runs on port 8081. If another process is already using that port, you can either terminate that process, or change the port that the bundler uses.

Terminating a process on port 8081

Run the following command to find the id for the process that is listening on port 8081:

$ sudo lsof -i :8081

Then run the following to terminate the process:

$ kill -9 <PID>

On Windows you can find the process using port 8081 using Resource Monitor and stop it using Task Manager.

Using a port other than 8081

You can configure the bundler to use a port other than 8081 by using the port parameter:

$ react-native start --port=8088

You will also need to update your applications to load the JavaScript bundle from the new port. If running on device from Xcode, you can do this by updating occurrences of 8081 to your chosen port in the node_modules/react-native/React/React.xcodeproj/project.pbxproj file.

NPM locking error

If you encounter an error such as npm WARN locking Error: EACCES while using the React Native CLI, try running the following:

sudo chown -R $USER ~/.npm
sudo chown -R $USER /usr/local/lib/node_modules

Missing libraries for React

If you added React Native manually to your project, make sure you have included all the relevant dependencies that you are using, like RCTText.xcodeproj, RCTImage.xcodeproj. Next, the binaries built by these dependencies have to be linked to your app binary. Use the Linked Frameworks and Binaries section in the Xcode project settings. More detailed steps are here: Linking Libraries.

If you are using CocoaPods, verify that you have added React along with the subspecs to the Podfile. For example, if you were using the <Text />, <Image /> and fetch() APIs, you would need to add these in your Podfile:

pod 'React', :path => '../node_modules/react-native', :subspecs => [
'RCTText',
'RCTImage',
'RCTNetwork',
'RCTWebSocket',
]

Next, make sure you have run pod install and that a Pods/ directory has been created in your project with React installed. CocoaPods will instruct you to use the generated .xcworkspace file henceforth to be able to use these installed dependencies.

React Native does not compile when being used as a CocoaPod

There is a CocoaPods plugin called cocoapods-fix-react-native which handles any potential post-fixing of the source code due to differences when using a dependency manager.

Argument list too long: recursive header expansion failed

In the project's build settings, User Search Header Paths and Header Search Paths are two configs that specify where Xcode should look for #import header files specified in the code. For Pods, CocoaPods uses a default array of specific folders to look in. Verify that this particular config is not overwritten, and that none of the folders configured are too large. If one of the folders is a large folder, Xcode will attempt to recursively search the entire directory and throw above error at some point.

To revert the User Search Header Paths and Header Search Paths build settings to their defaults set by CocoaPods - select the entry in the Build Settings panel, and hit delete. It will remove the custom override and return to the CocoaPod defaults.

No transports available

React Native implements a polyfill for WebSockets. These polyfills are initialized as part of the react-native module that you include in your application through import React from 'react'. If you load another module that requires WebSockets, such as Firebase, be sure to load/require it after react-native:

import React from 'react';
import Firebase from 'firebase';

Shell Command Unresponsive Exception

If you encounter a ShellCommandUnresponsiveException exception such as:

Execution failed for task ':app:installDebug'.
com.android.builder.testing.api.DeviceException: com.android.ddmlib.ShellCommandUnresponsiveException

Try downgrading your Gradle version to 1.2.3 in android/build.gradle.

react-native init hangs

If you run into issues where running react-native init hangs in your system, try running it again in verbose mode and referring to #2797 for common causes:

react-native init --verbose

Unable to start react-native package manager (on Linux)

Case 1: Error "code":"ENOSPC","errno":"ENOSPC"

Issue caused by the number of directories inotify (used by watchman on Linux) can monitor. To solve it, run this command in your terminal window

echo fs.inotify.max_user_watches=582222 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
Edit this page
Last updated on
- + diff --git a/docs/0.60/troubleshooting/index.html b/docs/0.60/troubleshooting/index.html index bceb10be3e7..0be70a76597 100644 --- a/docs/0.60/troubleshooting/index.html +++ b/docs/0.60/troubleshooting/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Troubleshooting

These are some common issues you may run into while setting up React Native. If you encounter something that is not listed here, try searching for the issue in GitHub.

Port already in use

The Metro bundler runs on port 8081. If another process is already using that port, you can either terminate that process, or change the port that the bundler uses.

Terminating a process on port 8081

Run the following command to find the id for the process that is listening on port 8081:

$ sudo lsof -i :8081

Then run the following to terminate the process:

$ kill -9 <PID>

On Windows you can find the process using port 8081 using Resource Monitor and stop it using Task Manager.

Using a port other than 8081

You can configure the bundler to use a port other than 8081 by using the port parameter:

$ react-native start --port=8088

You will also need to update your applications to load the JavaScript bundle from the new port. If running on device from Xcode, you can do this by updating occurrences of 8081 to your chosen port in the node_modules/react-native/React/React.xcodeproj/project.pbxproj file.

NPM locking error

If you encounter an error such as npm WARN locking Error: EACCES while using the React Native CLI, try running the following:

sudo chown -R $USER ~/.npm
sudo chown -R $USER /usr/local/lib/node_modules

Missing libraries for React

If you added React Native manually to your project, make sure you have included all the relevant dependencies that you are using, like RCTText.xcodeproj, RCTImage.xcodeproj. Next, the binaries built by these dependencies have to be linked to your app binary. Use the Linked Frameworks and Binaries section in the Xcode project settings. More detailed steps are here: Linking Libraries.

If you are using CocoaPods, verify that you have added React along with the subspecs to the Podfile. For example, if you were using the <Text />, <Image /> and fetch() APIs, you would need to add these in your Podfile:

pod 'React', :path => '../node_modules/react-native', :subspecs => [
'RCTText',
'RCTImage',
'RCTNetwork',
'RCTWebSocket',
]

Next, make sure you have run pod install and that a Pods/ directory has been created in your project with React installed. CocoaPods will instruct you to use the generated .xcworkspace file henceforth to be able to use these installed dependencies.

React Native does not compile when being used as a CocoaPod

There is a CocoaPods plugin called cocoapods-fix-react-native which handles any potential post-fixing of the source code due to differences when using a dependency manager.

Argument list too long: recursive header expansion failed

In the project's build settings, User Search Header Paths and Header Search Paths are two configs that specify where Xcode should look for #import header files specified in the code. For Pods, CocoaPods uses a default array of specific folders to look in. Verify that this particular config is not overwritten, and that none of the folders configured are too large. If one of the folders is a large folder, Xcode will attempt to recursively search the entire directory and throw above error at some point.

To revert the User Search Header Paths and Header Search Paths build settings to their defaults set by CocoaPods - select the entry in the Build Settings panel, and hit delete. It will remove the custom override and return to the CocoaPod defaults.

No transports available

React Native implements a polyfill for WebSockets. These polyfills are initialized as part of the react-native module that you include in your application through import React from 'react'. If you load another module that requires WebSockets, such as Firebase, be sure to load/require it after react-native:

import React from 'react';
import Firebase from 'firebase';

Shell Command Unresponsive Exception

If you encounter a ShellCommandUnresponsiveException exception such as:

Execution failed for task ':app:installDebug'.
com.android.builder.testing.api.DeviceException: com.android.ddmlib.ShellCommandUnresponsiveException

Try downgrading your Gradle version to 1.2.3 in android/build.gradle.

react-native init hangs

If you run into issues where running react-native init hangs in your system, try running it again in verbose mode and referring to #2797 for common causes:

react-native init --verbose

Unable to start react-native package manager (on Linux)

Case 1: Error "code":"ENOSPC","errno":"ENOSPC"

Issue caused by the number of directories inotify (used by watchman on Linux) can monitor. To solve it, run this command in your terminal window

echo fs.inotify.max_user_watches=582222 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
Edit this page
Last updated on
- + diff --git a/docs/0.60/tutorial.html b/docs/0.60/tutorial.html index 8f6ecce9866..4e6a6456af5 100644 --- a/docs/0.60/tutorial.html +++ b/docs/0.60/tutorial.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Learn the Basics

React Native is like React, but it uses native components instead of web components as building blocks. So to understand the basic structure of a React Native app, you need to understand some of the basic React concepts, like JSX, components, state, and props. If you already know React, you still need to learn some React-Native-specific stuff, like the native components. This tutorial is aimed at all audiences, whether you have React experience or not.

Let's do this thing.

Hello World

In accordance with the ancient traditions of our people, we must first build an app that does nothing except say "Hello, world!". Here it is:

If you are feeling curious, you can play around with sample code directly in the web simulators. You can also paste it into your App.js file to create a real app on your local machine.

What's going on here?

Some of the things in here might not look like JavaScript to you. Don't panic. This is the future.

First of all, ES2015 (also known as ES6) is a set of improvements to JavaScript that is now part of the official standard, but not yet supported by all browsers, so often it isn't used yet in web development. React Native ships with ES2015 support, so you can use this stuff without worrying about compatibility. import, from, class, and extends in the example above are all ES2015 features. If you aren't familiar with ES2015, you can probably pick it up by reading through sample code like this tutorial has. If you want, this page has a good overview of ES2015 features.

The other unusual thing in this code example is <View><Text>Hello world!</Text></View>. This is JSX - a syntax for embedding XML within JavaScript. Many frameworks use a specialized templating language which lets you embed code inside markup language. In React, this is reversed. JSX lets you write your markup language inside code. It looks like HTML on the web, except instead of web things like <div> or <span>, you use React components. In this case, <Text> is a Core Component that displays some text and View is like the <div> or <span>.

Components

So this code is defining HelloWorldApp, a new Component. When you're building a React Native app, you'll be making new components a lot. Anything you see on the screen is some sort of component. A component can be pretty basic - the only thing that's required is a render function which returns some JSX to render.

This app doesn't do very much

Good point. To make components do more interesting things, you need to learn about Props.

Edit this page
Last updated on
- + diff --git a/docs/0.60/tutorial/index.html b/docs/0.60/tutorial/index.html index 8f6ecce9866..4e6a6456af5 100644 --- a/docs/0.60/tutorial/index.html +++ b/docs/0.60/tutorial/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Learn the Basics

React Native is like React, but it uses native components instead of web components as building blocks. So to understand the basic structure of a React Native app, you need to understand some of the basic React concepts, like JSX, components, state, and props. If you already know React, you still need to learn some React-Native-specific stuff, like the native components. This tutorial is aimed at all audiences, whether you have React experience or not.

Let's do this thing.

Hello World

In accordance with the ancient traditions of our people, we must first build an app that does nothing except say "Hello, world!". Here it is:

If you are feeling curious, you can play around with sample code directly in the web simulators. You can also paste it into your App.js file to create a real app on your local machine.

What's going on here?

Some of the things in here might not look like JavaScript to you. Don't panic. This is the future.

First of all, ES2015 (also known as ES6) is a set of improvements to JavaScript that is now part of the official standard, but not yet supported by all browsers, so often it isn't used yet in web development. React Native ships with ES2015 support, so you can use this stuff without worrying about compatibility. import, from, class, and extends in the example above are all ES2015 features. If you aren't familiar with ES2015, you can probably pick it up by reading through sample code like this tutorial has. If you want, this page has a good overview of ES2015 features.

The other unusual thing in this code example is <View><Text>Hello world!</Text></View>. This is JSX - a syntax for embedding XML within JavaScript. Many frameworks use a specialized templating language which lets you embed code inside markup language. In React, this is reversed. JSX lets you write your markup language inside code. It looks like HTML on the web, except instead of web things like <div> or <span>, you use React components. In this case, <Text> is a Core Component that displays some text and View is like the <div> or <span>.

Components

So this code is defining HelloWorldApp, a new Component. When you're building a React Native app, you'll be making new components a lot. Anything you see on the screen is some sort of component. A component can be pretty basic - the only thing that's required is a render function which returns some JSX to render.

This app doesn't do very much

Good point. To make components do more interesting things, you need to learn about Props.

Edit this page
Last updated on
- + diff --git a/docs/0.60/typescript.html b/docs/0.60/typescript.html index 4418fdec428..9bee120e956 100644 --- a/docs/0.60/typescript.html +++ b/docs/0.60/typescript.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@
// styles
const styles = StyleSheet.create({
root: {
alignItems: 'center',
alignSelf: 'center',
},
buttons: {
flexDirection: 'row',
minHeight: 70,
alignItems: 'stretch',
alignSelf: 'center',
borderWidth: 5,
},
button: {
flex: 1,
paddingVertical: 0,
},
greeting: {
color: '#999',
fontWeight: 'bold',
},
});

You can explore the syntax more in the TypeScript playground.

Where to Find Useful Advice

Using Custom Path Aliases with TypeScript

To use custom path aliases with TypeScript, you need to set the path aliases to work from both Babel and TypeScript. Here's how:

  1. Edit your tsconfig.json to have your custom path mappings. Set anything in the root of src to be available with no preceding path reference, and allow any test file to be accessed by using test/File.tsx:
"target": "esnext",
+ "baseUrl": ".",
+ "paths": {
+ "*": ["src/*"],
+ "tests": ["tests/*"]
+ },
}
  1. Configure the Babel side done by adding a new dependency, babel-plugin-module-resolver:
yarn add --dev babel-plugin-module-resolver
# or
npm install --save-dev babel-plugin-module-resolver
  1. Finally, configure your babel.config.js (note that the syntax for your babel.config.js is different from your tsconfig.json):
{
plugins: [
+ [
+ 'module-resolver',
+ {
+ root: ['./src'],
+ extensions: ['.ios.js', '.android.js', '.js', '.ts', '.tsx', '.json'],
+ alias: {
+ "test/*": ["./test/"],
+ }
+ }
+ ]
]
}
Edit this page
Last updated on
- + diff --git a/docs/0.60/typescript/index.html b/docs/0.60/typescript/index.html index 4418fdec428..9bee120e956 100644 --- a/docs/0.60/typescript/index.html +++ b/docs/0.60/typescript/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@
// styles
const styles = StyleSheet.create({
root: {
alignItems: 'center',
alignSelf: 'center',
},
buttons: {
flexDirection: 'row',
minHeight: 70,
alignItems: 'stretch',
alignSelf: 'center',
borderWidth: 5,
},
button: {
flex: 1,
paddingVertical: 0,
},
greeting: {
color: '#999',
fontWeight: 'bold',
},
});

You can explore the syntax more in the TypeScript playground.

Where to Find Useful Advice

Using Custom Path Aliases with TypeScript

To use custom path aliases with TypeScript, you need to set the path aliases to work from both Babel and TypeScript. Here's how:

  1. Edit your tsconfig.json to have your custom path mappings. Set anything in the root of src to be available with no preceding path reference, and allow any test file to be accessed by using test/File.tsx:
"target": "esnext",
+ "baseUrl": ".",
+ "paths": {
+ "*": ["src/*"],
+ "tests": ["tests/*"]
+ },
}
  1. Configure the Babel side done by adding a new dependency, babel-plugin-module-resolver:
yarn add --dev babel-plugin-module-resolver
# or
npm install --save-dev babel-plugin-module-resolver
  1. Finally, configure your babel.config.js (note that the syntax for your babel.config.js is different from your tsconfig.json):
{
plugins: [
+ [
+ 'module-resolver',
+ {
+ root: ['./src'],
+ extensions: ['.ios.js', '.android.js', '.js', '.ts', '.tsx', '.json'],
+ alias: {
+ "test/*": ["./test/"],
+ }
+ }
+ ]
]
}
Edit this page
Last updated on
- + diff --git a/docs/0.60/upgrading.html b/docs/0.60/upgrading.html index b784b606e39..22cce3cd6f3 100644 --- a/docs/0.60/upgrading.html +++ b/docs/0.60/upgrading.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Upgrading to new React Native versions

Upgrading to new versions of React Native will give you access to more APIs, views, developer tools and other goodies. Upgrading requires a small amount of effort, but we try to make it straightforward for you.

Expo projects

Upgrading your Expo project to a new version of React Native requires updating the react-native, react, and expo package versions in your package.json file. Please refer to this list to find out what versions are supported. You will also need to set the correct sdkVersion in your app.json file.

See the Upgrading Expo SDK Walkthrough for up-to-date information about upgrading your project.

React Native projects

Because typical React Native projects are essentially made up of an Android project, an iOS project, and a JavaScript project, upgrading can be rather tricky. There's currently two ways for upgrading your React Native project: by using React Native CLI or manually with Upgrade Helper.

React Native CLI

The React Native CLI comes with upgrade command that provides a one-step operation to upgrade the source files with a minimum of conflicts, it internally uses rn-diff-purge project to find out which files need to be created, removed or modified.

1. Run the upgrade command

The upgrade command works on top of Git by using git apply with 3-way merge, therefore it's required to use Git in order for this to work, if you don't use Git but still want to use this solution then you can check out how to do it in the Troubleshooting section.

Run the following command to start the process of upgrading to the latest version:

react-native upgrade

You may specify a React Native version by passing an argument, e.g. to upgrade to 0.61.0-rc.0 run:

react-native upgrade 0.61.0-rc.0

The project is upgraded using git apply with 3-way merge, it may happen that you'll need to resolve a few conflicts after it's finished.

2. Resolve the conflicts

Conflicted files include delimiters which make very clear where the changes come from. For example:

13B07F951A680F5B00A75B9A /* Release */ = {
isa = XCBuildConfiguration;
buildSettings = {
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
<<<<<<< ours
CODE_SIGN_IDENTITY = "iPhone Developer";
FRAMEWORK_SEARCH_PATHS = (
"$(inherited)",
"$(PROJECT_DIR)/HockeySDK.embeddedframework",
"$(PROJECT_DIR)/HockeySDK-iOS/HockeySDK.embeddedframework",
);
=======
CURRENT_PROJECT_VERSION = 1;
>>>>>>> theirs
HEADER_SEARCH_PATHS = (
"$(inherited)",
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include,
"$(SRCROOT)/../node_modules/react-native/React/**",
"$(SRCROOT)/../node_modules/react-native-code-push/ios/CodePush/**",
);

You can think of "ours" as "your team" and "theirs" as "the React Native development team".

Upgrade Helper

The Upgrade Helper is a web tool to help you out when upgrading your apps by providing the full set of changes happening between any two versions. It also shows comments on specific files to help understanding why that change is needed.

1. Select the versions

You first need to select from and to which version you wish to upgrade, by default the latest major versions are selected. After selecting you can click the button "Show me how to upgrade".

💡 Major updates will show an "useful content" section on the top with links to help you out when upgrading.

2. Upgrade dependencies

The first file that is shown is the package.json, it's good to update the dependencies that are showing in there. For example, if react-native and react appears as changes then you can install it in your project by running yarn add:

# {{VERSION}} and {{REACT_VERSION}} are the release versions showing in the diff
yarn add react-native@{{VERSION}}
yarn add react@{{REACT_VERSION}}

3. Upgrade your project files

The new release may contain updates to other files that are generated when you run react-native init, those files are listed after the package.json in the Upgrade Helper page. If there aren't other changes then you can rebuild the project and continue developing.

In case there are changes then you can either update them manually by copying and pasting from the changes in the page or you can do it with the React Native CLI upgrade command by running:

react-native upgrade

This will check your files against the latest template and perform the following:

  • If there is a new file in the template, it is created.
  • If a file in the template is identical to your file, it is skipped.
  • If a file is different in your project than the template, you will be prompted; you have options to keep your file or overwrite it with the template version.

Some upgrades won't be done automatically with the React Native CLI and require manual work, e.g. 0.28 to 0.29, or 0.56 to 0.57. Make sure to check the release notes when upgrading so that you can identify any manual changes your particular project may require.

Troubleshooting

I want to upgrade with React Native CLI but I don't use Git

While your project does not have to be handled by the Git versioning system -- you can use Mercurial, SVN, or nothing -- you will still need to install Git on your system in order to use react-native upgrade. Git will also need to be available in the PATH. If your project doesn't use Git, initialize it and commit:

git init # Initialize a Git repository
git add . # Stage all the current files
git commit -m "Upgrade react-native" # Save the current files in a commit

After you finish upgrading you may remove the .git directory.

I have done all the changes but my app is still using an old version

These sort of errors are usually related to caching, it's recommended to install react-native-clean-project to clear all your project's cache and then you can run it again.

Edit this page
Last updated on
- + diff --git a/docs/0.60/upgrading/index.html b/docs/0.60/upgrading/index.html index b784b606e39..22cce3cd6f3 100644 --- a/docs/0.60/upgrading/index.html +++ b/docs/0.60/upgrading/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Upgrading to new React Native versions

Upgrading to new versions of React Native will give you access to more APIs, views, developer tools and other goodies. Upgrading requires a small amount of effort, but we try to make it straightforward for you.

Expo projects

Upgrading your Expo project to a new version of React Native requires updating the react-native, react, and expo package versions in your package.json file. Please refer to this list to find out what versions are supported. You will also need to set the correct sdkVersion in your app.json file.

See the Upgrading Expo SDK Walkthrough for up-to-date information about upgrading your project.

React Native projects

Because typical React Native projects are essentially made up of an Android project, an iOS project, and a JavaScript project, upgrading can be rather tricky. There's currently two ways for upgrading your React Native project: by using React Native CLI or manually with Upgrade Helper.

React Native CLI

The React Native CLI comes with upgrade command that provides a one-step operation to upgrade the source files with a minimum of conflicts, it internally uses rn-diff-purge project to find out which files need to be created, removed or modified.

1. Run the upgrade command

The upgrade command works on top of Git by using git apply with 3-way merge, therefore it's required to use Git in order for this to work, if you don't use Git but still want to use this solution then you can check out how to do it in the Troubleshooting section.

Run the following command to start the process of upgrading to the latest version:

react-native upgrade

You may specify a React Native version by passing an argument, e.g. to upgrade to 0.61.0-rc.0 run:

react-native upgrade 0.61.0-rc.0

The project is upgraded using git apply with 3-way merge, it may happen that you'll need to resolve a few conflicts after it's finished.

2. Resolve the conflicts

Conflicted files include delimiters which make very clear where the changes come from. For example:

13B07F951A680F5B00A75B9A /* Release */ = {
isa = XCBuildConfiguration;
buildSettings = {
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
<<<<<<< ours
CODE_SIGN_IDENTITY = "iPhone Developer";
FRAMEWORK_SEARCH_PATHS = (
"$(inherited)",
"$(PROJECT_DIR)/HockeySDK.embeddedframework",
"$(PROJECT_DIR)/HockeySDK-iOS/HockeySDK.embeddedframework",
);
=======
CURRENT_PROJECT_VERSION = 1;
>>>>>>> theirs
HEADER_SEARCH_PATHS = (
"$(inherited)",
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include,
"$(SRCROOT)/../node_modules/react-native/React/**",
"$(SRCROOT)/../node_modules/react-native-code-push/ios/CodePush/**",
);

You can think of "ours" as "your team" and "theirs" as "the React Native development team".

Upgrade Helper

The Upgrade Helper is a web tool to help you out when upgrading your apps by providing the full set of changes happening between any two versions. It also shows comments on specific files to help understanding why that change is needed.

1. Select the versions

You first need to select from and to which version you wish to upgrade, by default the latest major versions are selected. After selecting you can click the button "Show me how to upgrade".

💡 Major updates will show an "useful content" section on the top with links to help you out when upgrading.

2. Upgrade dependencies

The first file that is shown is the package.json, it's good to update the dependencies that are showing in there. For example, if react-native and react appears as changes then you can install it in your project by running yarn add:

# {{VERSION}} and {{REACT_VERSION}} are the release versions showing in the diff
yarn add react-native@{{VERSION}}
yarn add react@{{REACT_VERSION}}

3. Upgrade your project files

The new release may contain updates to other files that are generated when you run react-native init, those files are listed after the package.json in the Upgrade Helper page. If there aren't other changes then you can rebuild the project and continue developing.

In case there are changes then you can either update them manually by copying and pasting from the changes in the page or you can do it with the React Native CLI upgrade command by running:

react-native upgrade

This will check your files against the latest template and perform the following:

  • If there is a new file in the template, it is created.
  • If a file in the template is identical to your file, it is skipped.
  • If a file is different in your project than the template, you will be prompted; you have options to keep your file or overwrite it with the template version.

Some upgrades won't be done automatically with the React Native CLI and require manual work, e.g. 0.28 to 0.29, or 0.56 to 0.57. Make sure to check the release notes when upgrading so that you can identify any manual changes your particular project may require.

Troubleshooting

I want to upgrade with React Native CLI but I don't use Git

While your project does not have to be handled by the Git versioning system -- you can use Mercurial, SVN, or nothing -- you will still need to install Git on your system in order to use react-native upgrade. Git will also need to be available in the PATH. If your project doesn't use Git, initialize it and commit:

git init # Initialize a Git repository
git add . # Stage all the current files
git commit -m "Upgrade react-native" # Save the current files in a commit

After you finish upgrading you may remove the .git directory.

I have done all the changes but my app is still using an old version

These sort of errors are usually related to caching, it's recommended to install react-native-clean-project to clear all your project's cache and then you can run it again.

Edit this page
Last updated on
- + diff --git a/docs/0.60/usewindowdimensions.html b/docs/0.60/usewindowdimensions.html index 89b32da6433..a6cd875f348 100644 --- a/docs/0.60/usewindowdimensions.html +++ b/docs/0.60/usewindowdimensions.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

useWindowDimensions

import { useWindowDimensions } from 'react-native';

useWindowDimensions automatically updates width and height values when screen size changes. You can get your application window's width and height like so:

const windowWidth = useWindowDimensions().width;
const windowHeight = useWindowDimensions().height;

Example

Properties

fontScale

The scale of the font currently used. Some operating systems allow users to scale their font sizes larger or smaller for reading comfort. This property will let you know what is in effect.

useWindowDimensions().fontScale;

height

The height in pixels of the window or screen your app occupies.

useWindowDimensions().height;

scale

The pixel ratio of the device your app is running on.

useWindowDimensions().scale;

A value of 1 indicates PPI/DPI of 96 (76 on some platforms). 2 indicates a Retina or high DPI display.

width

The width in pixels of the window or screen your app occupies.

useWindowDimensions().width;
Edit this page
Last updated on
- + diff --git a/docs/0.60/usewindowdimensions/index.html b/docs/0.60/usewindowdimensions/index.html index 89b32da6433..a6cd875f348 100644 --- a/docs/0.60/usewindowdimensions/index.html +++ b/docs/0.60/usewindowdimensions/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

useWindowDimensions

import { useWindowDimensions } from 'react-native';

useWindowDimensions automatically updates width and height values when screen size changes. You can get your application window's width and height like so:

const windowWidth = useWindowDimensions().width;
const windowHeight = useWindowDimensions().height;

Example

Properties

fontScale

The scale of the font currently used. Some operating systems allow users to scale their font sizes larger or smaller for reading comfort. This property will let you know what is in effect.

useWindowDimensions().fontScale;

height

The height in pixels of the window or screen your app occupies.

useWindowDimensions().height;

scale

The pixel ratio of the device your app is running on.

useWindowDimensions().scale;

A value of 1 indicates PPI/DPI of 96 (76 on some platforms). 2 indicates a Retina or high DPI display.

width

The width in pixels of the window or screen your app occupies.

useWindowDimensions().width;
Edit this page
Last updated on
- + diff --git a/docs/0.60/using-a-listview.html b/docs/0.60/using-a-listview.html index 7d9b6ed152a..5659d799bcd 100644 --- a/docs/0.60/using-a-listview.html +++ b/docs/0.60/using-a-listview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Using List Views

React Native provides a suite of components for presenting lists of data. Generally, you'll want to use either FlatList or SectionList.

The FlatList component displays a scrolling list of changing, but similarly structured, data. FlatList works well for long lists of data, where the number of items might change over time. Unlike the more generic ScrollView, the FlatList only renders elements that are currently showing on the screen, not all the elements at once.

The FlatList component requires two props: data and renderItem. data is the source of information for the list. renderItem takes one item from the source and returns a formatted component to render.

This example creates a basic FlatList of hardcoded data. Each item in the data props is rendered as a Text component. The FlatListBasics component then renders the FlatList and all Text components.

If you want to render a set of data broken into logical sections, maybe with section headers, similar to UITableViews on iOS, then a SectionList is the way to go.

One of the most common uses for a list view is displaying data that you fetch from a server. To do that, you will need to learn about networking in React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.60/using-a-listview/index.html b/docs/0.60/using-a-listview/index.html index 7d9b6ed152a..5659d799bcd 100644 --- a/docs/0.60/using-a-listview/index.html +++ b/docs/0.60/using-a-listview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Using List Views

React Native provides a suite of components for presenting lists of data. Generally, you'll want to use either FlatList or SectionList.

The FlatList component displays a scrolling list of changing, but similarly structured, data. FlatList works well for long lists of data, where the number of items might change over time. Unlike the more generic ScrollView, the FlatList only renders elements that are currently showing on the screen, not all the elements at once.

The FlatList component requires two props: data and renderItem. data is the source of information for the list. renderItem takes one item from the source and returns a formatted component to render.

This example creates a basic FlatList of hardcoded data. Each item in the data props is rendered as a Text component. The FlatListBasics component then renders the FlatList and all Text components.

If you want to render a set of data broken into logical sections, maybe with section headers, similar to UITableViews on iOS, then a SectionList is the way to go.

One of the most common uses for a list view is displaying data that you fetch from a server. To do that, you will need to learn about networking in React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.60/using-a-scrollview.html b/docs/0.60/using-a-scrollview.html index bc6f6a4ebca..20cb03e1707 100644 --- a/docs/0.60/using-a-scrollview.html +++ b/docs/0.60/using-a-scrollview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Using a ScrollView

The ScrollView is a generic scrolling container that can contain multiple components and views. The scrollable items need not be homogeneous, and you can scroll both vertically and horizontally (by setting the horizontal property).

This example creates a vertical ScrollView with both images and text mixed together.

ScrollViews can be configured to allow paging through views using swiping gestures by using the pagingEnabled props. Swiping horizontally between views can also be implemented on Android using the ViewPager component.

On iOS a ScrollView with a single item can be used to allow the user to zoom content. Set up the maximumZoomScale and minimumZoomScale props and your user will be able to use pinch and expand gestures to zoom in and out.

The ScrollView works best to present a small amount of things of a limited size. All the elements and views of a ScrollView are rendered, even if they are not currently shown on the screen. If you have a long list of more items than can fit on the screen, you should use a FlatList instead. So let's learn about list views next.

Edit this page
Last updated on
- + diff --git a/docs/0.60/using-a-scrollview/index.html b/docs/0.60/using-a-scrollview/index.html index bc6f6a4ebca..20cb03e1707 100644 --- a/docs/0.60/using-a-scrollview/index.html +++ b/docs/0.60/using-a-scrollview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

Using a ScrollView

The ScrollView is a generic scrolling container that can contain multiple components and views. The scrollable items need not be homogeneous, and you can scroll both vertically and horizontally (by setting the horizontal property).

This example creates a vertical ScrollView with both images and text mixed together.

ScrollViews can be configured to allow paging through views using swiping gestures by using the pagingEnabled props. Swiping horizontally between views can also be implemented on Android using the ViewPager component.

On iOS a ScrollView with a single item can be used to allow the user to zoom content. Set up the maximumZoomScale and minimumZoomScale props and your user will be able to use pinch and expand gestures to zoom in and out.

The ScrollView works best to present a small amount of things of a limited size. All the elements and views of a ScrollView are rendered, even if they are not currently shown on the screen. If you have a long list of more items than can fit on the screen, you should use a FlatList instead. So let's learn about list views next.

Edit this page
Last updated on
- + diff --git a/docs/0.60/vibration.html b/docs/0.60/vibration.html index a4662e0e9b2..3cb765b8345 100644 --- a/docs/0.60/vibration.html +++ b/docs/0.60/vibration.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
Vibration.cancel();
// Android: vibration stopped
// iOS: vibration stopped

Reference

Methods

vibrate()

Vibration.vibrate(pattern: number, Array<number>, repeat: boolean)

Trigger a vibration with specified pattern.

Parameters:

NameTypeRequiredDescription
patternnumber or Array<number>YesVibration pattern, accept a number or an array of numbers. Default to 400ms.
repeatbooleanNoRepeat vibration pattern until cancel(), default to false.

cancel()

Vibration.cancel();

Stop vibration.

Vibration.cancel()
Edit this page
Last updated on
- + diff --git a/docs/0.60/vibration/index.html b/docs/0.60/vibration/index.html index a4662e0e9b2..3cb765b8345 100644 --- a/docs/0.60/vibration/index.html +++ b/docs/0.60/vibration/index.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
Vibration.cancel();
// Android: vibration stopped
// iOS: vibration stopped

Reference

Methods

vibrate()

Vibration.vibrate(pattern: number, Array<number>, repeat: boolean)

Trigger a vibration with specified pattern.

Parameters:

NameTypeRequiredDescription
patternnumber or Array<number>YesVibration pattern, accept a number or an array of numbers. Default to 400ms.
repeatbooleanNoRepeat vibration pattern until cancel(), default to false.

cancel()

Vibration.cancel();

Stop vibration.

Vibration.cancel()
Edit this page
Last updated on
- + diff --git a/docs/0.60/vibrationios.html b/docs/0.60/vibrationios.html index b7d9dc603f4..bdaa461b3b9 100644 --- a/docs/0.60/vibrationios.html +++ b/docs/0.60/vibrationios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

VibrationIOS

NOTE: VibrationIOS is being deprecated. Use Vibration instead.

The Vibration API is exposed at VibrationIOS.vibrate(). On iOS, calling this function will trigger a one second vibration. The vibration is synchronous so this method will return immediately.

There will be no effect on devices that do not support Vibration, eg. the iOS simulator.

Vibration patterns are currently unsupported.

Methods

Reference

Methods

vibrate()

static vibrate()

@deprecated

Edit this page
Last updated on
- + diff --git a/docs/0.60/vibrationios/index.html b/docs/0.60/vibrationios/index.html index b7d9dc603f4..bdaa461b3b9 100644 --- a/docs/0.60/vibrationios/index.html +++ b/docs/0.60/vibrationios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

VibrationIOS

NOTE: VibrationIOS is being deprecated. Use Vibration instead.

The Vibration API is exposed at VibrationIOS.vibrate(). On iOS, calling this function will trigger a one second vibration. The vibration is synchronous so this method will return immediately.

There will be no effect on devices that do not support Vibration, eg. the iOS simulator.

Vibration patterns are currently unsupported.

Methods

Reference

Methods

vibrate()

static vibrate()

@deprecated

Edit this page
Last updated on
- + diff --git a/docs/0.60/view-style-props.html b/docs/0.60/view-style-props.html index 638c4563481..41c84c977fe 100644 --- a/docs/0.60/view-style-props.html +++ b/docs/0.60/view-style-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

View Style Props

Reference

Props

borderRightColor

TypeRequired
colorNo

backfaceVisibility

TypeRequired
enum('visible', 'hidden')No

borderBottomColor

TypeRequired
colorNo

borderBottomEndRadius

TypeRequired
numberNo

borderBottomLeftRadius

TypeRequired
numberNo

borderBottomRightRadius

TypeRequired
numberNo

borderBottomStartRadius

TypeRequired
numberNo

borderBottomWidth

TypeRequired
numberNo

borderColor

TypeRequired
colorNo

borderEndColor

TypeRequired
colorNo

borderLeftColor

TypeRequired
colorNo

borderLeftWidth

TypeRequired
numberNo

borderRadius

If the rounded border is not visible, try applying overflow: 'hidden' as well.

TypeRequired
numberNo

backgroundColor

TypeRequired
colorNo

borderRightWidth

TypeRequired
numberNo

borderStartColor

TypeRequired
colorNo

borderStyle

TypeRequired
enum('solid', 'dotted', 'dashed')No

borderTopColor

TypeRequired
colorNo

borderTopEndRadius

TypeRequired
numberNo

borderTopLeftRadius

TypeRequired
numberNo

borderTopRightRadius

TypeRequired
numberNo

borderTopStartRadius

TypeRequired
numberNo

borderTopWidth

TypeRequired
numberNo

borderWidth

TypeRequired
numberNo

opacity

TypeRequired
numberNo

elevation

(Android-only) Sets the elevation of a view, using Android's underlying elevation API. This adds a drop shadow to the item and affects z-order for overlapping views. Only supported on Android 5.0+, has no effect on earlier versions.

TypeRequiredPlatform
numberNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.60/view-style-props/index.html b/docs/0.60/view-style-props/index.html index 638c4563481..41c84c977fe 100644 --- a/docs/0.60/view-style-props/index.html +++ b/docs/0.60/view-style-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

View Style Props

Reference

Props

borderRightColor

TypeRequired
colorNo

backfaceVisibility

TypeRequired
enum('visible', 'hidden')No

borderBottomColor

TypeRequired
colorNo

borderBottomEndRadius

TypeRequired
numberNo

borderBottomLeftRadius

TypeRequired
numberNo

borderBottomRightRadius

TypeRequired
numberNo

borderBottomStartRadius

TypeRequired
numberNo

borderBottomWidth

TypeRequired
numberNo

borderColor

TypeRequired
colorNo

borderEndColor

TypeRequired
colorNo

borderLeftColor

TypeRequired
colorNo

borderLeftWidth

TypeRequired
numberNo

borderRadius

If the rounded border is not visible, try applying overflow: 'hidden' as well.

TypeRequired
numberNo

backgroundColor

TypeRequired
colorNo

borderRightWidth

TypeRequired
numberNo

borderStartColor

TypeRequired
colorNo

borderStyle

TypeRequired
enum('solid', 'dotted', 'dashed')No

borderTopColor

TypeRequired
colorNo

borderTopEndRadius

TypeRequired
numberNo

borderTopLeftRadius

TypeRequired
numberNo

borderTopRightRadius

TypeRequired
numberNo

borderTopStartRadius

TypeRequired
numberNo

borderTopWidth

TypeRequired
numberNo

borderWidth

TypeRequired
numberNo

opacity

TypeRequired
numberNo

elevation

(Android-only) Sets the elevation of a view, using Android's underlying elevation API. This adds a drop shadow to the item and affects z-order for overlapping views. Only supported on Android 5.0+, has no effect on earlier versions.

TypeRequiredPlatform
numberNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.60/view.html b/docs/0.60/view.html index eda120123f2..0737830ef95 100644 --- a/docs/0.60/view.html +++ b/docs/0.60/view.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

View

The most fundamental component for building a UI, View is a container that supports layout with flexbox, style, some touch handling, and accessibility controls. View maps directly to the native view equivalent on whatever platform React Native is running on, whether that is a UIView, <div>, android.view, etc.

View is designed to be nested inside other views and can have 0 to many children of any type.

This example creates a View that wraps two colored boxes and a text component in a row with padding.

class ViewColoredBoxesWithText extends Component {
render() {
return (
<View
style={{
flexDirection: 'row',
height: 100,
padding: 20
}}>
<View style={{ backgroundColor: 'blue', flex: 0.3 }} />
<View style={{ backgroundColor: 'red', flex: 0.5 }} />
<Text>Hello World!</Text>
</View>
);
}
}

Views are designed to be used with StyleSheet for clarity and performance, although inline styles are also supported.

Synthetic Touch Events

For View responder props (e.g., onResponderMove), the synthetic touch event passed to them are of the following form:

  • nativeEvent
    • changedTouches - Array of all touch events that have changed since the last event.
    • identifier - The ID of the touch.
    • locationX - The X position of the touch, relative to the element.
    • locationY - The Y position of the touch, relative to the element.
    • pageX - The X position of the touch, relative to the root element.
    • pageY - The Y position of the touch, relative to the root element.
    • target - The node id of the element receiving the touch event.
    • timestamp - A time identifier for the touch, useful for velocity calculation.
    • touches - Array of all current touches on the screen.

Reference

Props

onStartShouldSetResponder

Does this view want to become responder on the start of a touch?

View.props.onStartShouldSetResponder: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

  • 'none' - Used when the element has no role.
  • 'button' - Used when the element should be treated as a button.
  • 'link' - Used when the element should be treated as a link.
  • 'search' - Used when the text field element should also be treated as a search field.
  • 'image' - Used when the element should be treated as an image. Can be combined with button or link, for example.
  • 'keyboardkey' - Used when the element acts as a keyboard key.
  • 'text' - Used when the element should be treated as static text that cannot change.
  • 'adjustable' - Used when an element can be "adjusted" (e.g. a slider).
  • 'imagebutton' - Used when the element should be treated as a button and is also an image.
  • 'header' - Used when an element acts as a header for a content section (e.g. the title of a navigation bar).
  • 'summary' - Used when an element can be used to provide a quick summary of current conditions in the app when the app first launches.
  • 'alert' - Used when an element contains important text to be presented to the user.
  • 'checkbox' - Used when an element represents a checkbox which can be checked, unchecked, or have mixed checked state.
  • 'combobox' - Used when an element represents a combo box, which allows the user to select among several choices.
  • 'menu' - Used when the component is a menu of choices.
  • 'menubar' - Used when a component is a container of multiple menus.
  • 'menuitem' - Used to represent an item within a menu.
  • 'progressbar' - Used to represent a component which indicates progress of a task.
  • 'radio' - Used to represent a radio button.
  • 'radiogroup' - Used to represent a group of radio buttons.
  • 'scrollbar' - Used to represent a scroll bar.
  • 'spinbutton' - Used to represent a button which opens a list of choices.
  • 'switch' - Used to represent a switch which can be turned on and off.
  • 'tab' - Used to represent a tab.
  • 'tablist' - Used to represent a list of tabs.
  • 'timer' - Used to represent a timer.
  • 'toolbar' - Used to represent a tool bar (a container of action buttons or components).
TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

accessibilityValue

Represents the current value of a component. It can be a textual description of a component's value, or for range-based components, such as sliders and progress bars, it contains range information (minimum, current, and maximum).

See the Accessibility guide for more information.

TypeRequired
object: {min: number, max: number, now: number, text: string}No

accessibilityActions

Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The accessibilityActions property should contain a list of action objects. Each action object should contain the field name and label.

See the Accessibility guide for more information.

TypeRequired
arrayNo

onAccessibilityAction

Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform.

See the Accessibility guide for more information.

TypeRequired
functionNo

onAccessibilityTap

When accessible is true, the system will try to invoke this function when the user performs accessibility tap gesture.

TypeRequired
functionNo

onMagicTap

When accessible is true, the system will invoke this function when the user performs the magic tap gesture.

TypeRequiredPlatform
functionNoiOS

onAccessibilityEscape

When accessible is true, the system will invoke this function when the user performs the escape gesture.

TypeRequiredPlatform
functionNoiOS

accessibilityViewIsModal

A value indicating whether VoiceOver should ignore the elements within views that are siblings of the receiver. Default is false.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityElementsHidden

A value indicating whether the accessibility elements contained within this accessibility element are hidden. Default is false.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityIgnoresInvertColors

A value indicating this view should or should not be inverted when color inversion is turned on. A value of true will tell the view to not be inverted even if color inversion is turned on.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityLiveRegion

Indicates to accessibility services whether the user should be notified when this view changes. Works for Android API >= 19 only. Possible values:

  • 'none' - Accessibility services should not announce changes to this view.
  • 'polite'- Accessibility services should announce changes to this view.
  • 'assertive' - Accessibility services should interrupt ongoing speech to immediately announce changes to this view.

See the Android View docs for reference.

TypeRequiredPlatform
enum('none', 'polite', 'assertive')NoAndroid

importantForAccessibility

Controls how view is important for accessibility which is if it fires accessibility events and if it is reported to accessibility services that query the screen. Works for Android only.

Possible values:

  • 'auto' - The system determines whether the view is important for accessibility - default (recommended).
  • 'yes' - The view is important for accessibility.
  • 'no' - The view is not important for accessibility.
  • 'no-hide-descendants' - The view is not important for accessibility, nor are any of its descendant views.

See the Android importantForAccessibility docs for reference.

TypeRequiredPlatform
enum('auto', 'yes', 'no', 'no-hide-descendants')NoAndroid

hitSlop

This defines how far a touch event can start away from the view. Typical interface guidelines recommend touch targets that are at least 30 - 40 points/density-independent pixels.

For example, if a touchable view has a height of 20 the touchable height can be extended to 40 with hitSlop={{top: 10, bottom: 10, left: 0, right: 0}}

The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

nativeID

Used to locate this view from native classes.

This disables the 'layout-only view removal' optimization for this view!

TypeRequired
stringNo

onLayout

Invoked on mount and layout changes with:

{nativeEvent: { layout: {x, y, width, height}}}

This event is fired immediately once the layout has been calculated, but the new layout may not yet be reflected on the screen at the time the event is received, especially if a layout animation is in progress.

TypeRequired
functionNo

onMoveShouldSetResponder

Does this view want to "claim" touch responsiveness? This is called for every touch move on the View when it is not the responder.

View.props.onMoveShouldSetResponder: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onMoveShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a move, it should have this handler which returns true.

View.props.onMoveShouldSetResponderCapture: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderGrant

The View is now responding for touch events. This is the time to highlight and show the user what is happening.

View.props.onResponderGrant: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderMove

The user is moving their finger.

View.props.onResponderMove: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderReject

Another responder is already active and will not release it to that View asking to be the responder.

View.props.onResponderReject: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderRelease

Fired at the end of the touch.

View.props.onResponderRelease: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminate

The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS)

View.props.onResponderTerminate: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminationRequest

Some other View wants to become responder and is asking this View to release its responder. Returning true allows its release.

View.props.onResponderTerminationRequest: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onStartShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a touch start, it should have this handler which returns true.

View.props.onStartShouldSetResponderCapture: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

pointerEvents

Controls whether the View can be the target of touch events.

  • 'auto': The View can be the target of touch events.
  • 'none': The View is never the target of touch events.
  • 'box-none': The View is never the target of touch events but it's subviews can be. It behaves like if the view had the following classes in CSS:
.box-none {
pointer-events: none;
}
.box-none * {
pointer-events: auto;
}
  • 'box-only': The view can be the target of touch events but it's subviews cannot be. It behaves like if the view had the following classes in CSS:
.box-only {
pointer-events: auto;
}
.box-only * {
pointer-events: none;
}

Since pointerEvents does not affect layout/appearance, and we are already deviating from the spec by adding additional modes, we opt to not include pointerEvents on style. On some platforms, we would need to implement it as a className anyways. Using style or not is an implementation detail of the platform.

TypeRequired
enum('box-none', 'none', 'box-only', 'auto')No

removeClippedSubviews

This is a reserved performance property exposed by RCTView and is useful for scrolling content when there are many subviews, most of which are offscreen. For this property to be effective, it must be applied to a view that contains many subviews that extend outside its bound. The subviews must also have overflow: hidden, as should the containing view (or one of its superviews).

TypeRequired
boolNo

style

TypeRequired
view stylesNo

testID

Used to locate this view in end-to-end tests.

This disables the 'layout-only view removal' optimization for this view!

TypeRequired
stringNo

collapsable

Views that are only used to layout their children or otherwise don't draw anything may be automatically removed from the native hierarchy as an optimization. Set this property to false to disable this optimization and ensure that this View exists in the native view hierarchy.

TypeRequiredPlatform
boolNoAndroid

needsOffscreenAlphaCompositing

Whether this View needs to rendered offscreen and composited with an alpha in order to preserve 100% correct colors and blending behavior. The default (false) falls back to drawing the component and its children with an alpha applied to the paint used to draw each element instead of rendering the full component offscreen and compositing it back with an alpha value. This default may be noticeable and undesired in the case where the View you are setting an opacity on has multiple overlapping elements (e.g. multiple overlapping Views, or text and a background).

Rendering offscreen to preserve correct alpha behavior is extremely expensive and hard to debug for non-native developers, which is why it is not turned on by default. If you do need to enable this property for an animation, consider combining it with renderToHardwareTextureAndroid if the view contents are static (i.e. it doesn't need to be redrawn each frame). If that property is enabled, this View will be rendered off-screen once, saved in a hardware texture, and then composited onto the screen with an alpha each frame without having to switch rendering targets on the GPU.

TypeRequired
boolNo

renderToHardwareTextureAndroid

Whether this View should render itself (and all of its children) into a single hardware texture on the GPU.

On Android, this is useful for animations and interactions that only modify opacity, rotation, translation, and/or scale: in those cases, the view doesn't have to be redrawn and display lists don't need to be re-executed. The texture can be re-used and re-composited with different parameters. The downside is that this can use up limited video memory, so this prop should be set back to false at the end of the interaction/animation.

TypeRequiredPlatform
boolNoAndroid

shouldRasterizeIOS

Whether this View should be rendered as a bitmap before compositing.

On iOS, this is useful for animations and interactions that do not modify this component's dimensions nor its children; for example, when translating the position of a static view, rasterization allows the renderer to reuse a cached bitmap of a static view and quickly composite it during each frame.

Rasterization incurs an off-screen drawing pass and the bitmap consumes memory. Test and measure when using this property.

TypeRequiredPlatform
boolNoiOS

nextFocusDown

Designates the next view to receive focus when the user navigates down. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusForward

Designates the next view to receive focus when the user navigates forward. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusLeft

Designates the next view to receive focus when the user navigates left. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusRight

Designates the next view to receive focus when the user navigates right. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusUp

Designates the next view to receive focus when the user navigates up. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

clickable

Determines whether this View is clickable or tappable for accessibility hints.

TypeRequiredPlatform
booleanNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.60/view/index.html b/docs/0.60/view/index.html index eda120123f2..0737830ef95 100644 --- a/docs/0.60/view/index.html +++ b/docs/0.60/view/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

View

The most fundamental component for building a UI, View is a container that supports layout with flexbox, style, some touch handling, and accessibility controls. View maps directly to the native view equivalent on whatever platform React Native is running on, whether that is a UIView, <div>, android.view, etc.

View is designed to be nested inside other views and can have 0 to many children of any type.

This example creates a View that wraps two colored boxes and a text component in a row with padding.

class ViewColoredBoxesWithText extends Component {
render() {
return (
<View
style={{
flexDirection: 'row',
height: 100,
padding: 20
}}>
<View style={{ backgroundColor: 'blue', flex: 0.3 }} />
<View style={{ backgroundColor: 'red', flex: 0.5 }} />
<Text>Hello World!</Text>
</View>
);
}
}

Views are designed to be used with StyleSheet for clarity and performance, although inline styles are also supported.

Synthetic Touch Events

For View responder props (e.g., onResponderMove), the synthetic touch event passed to them are of the following form:

  • nativeEvent
    • changedTouches - Array of all touch events that have changed since the last event.
    • identifier - The ID of the touch.
    • locationX - The X position of the touch, relative to the element.
    • locationY - The Y position of the touch, relative to the element.
    • pageX - The X position of the touch, relative to the root element.
    • pageY - The Y position of the touch, relative to the root element.
    • target - The node id of the element receiving the touch event.
    • timestamp - A time identifier for the touch, useful for velocity calculation.
    • touches - Array of all current touches on the screen.

Reference

Props

onStartShouldSetResponder

Does this view want to become responder on the start of a touch?

View.props.onStartShouldSetResponder: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

  • 'none' - Used when the element has no role.
  • 'button' - Used when the element should be treated as a button.
  • 'link' - Used when the element should be treated as a link.
  • 'search' - Used when the text field element should also be treated as a search field.
  • 'image' - Used when the element should be treated as an image. Can be combined with button or link, for example.
  • 'keyboardkey' - Used when the element acts as a keyboard key.
  • 'text' - Used when the element should be treated as static text that cannot change.
  • 'adjustable' - Used when an element can be "adjusted" (e.g. a slider).
  • 'imagebutton' - Used when the element should be treated as a button and is also an image.
  • 'header' - Used when an element acts as a header for a content section (e.g. the title of a navigation bar).
  • 'summary' - Used when an element can be used to provide a quick summary of current conditions in the app when the app first launches.
  • 'alert' - Used when an element contains important text to be presented to the user.
  • 'checkbox' - Used when an element represents a checkbox which can be checked, unchecked, or have mixed checked state.
  • 'combobox' - Used when an element represents a combo box, which allows the user to select among several choices.
  • 'menu' - Used when the component is a menu of choices.
  • 'menubar' - Used when a component is a container of multiple menus.
  • 'menuitem' - Used to represent an item within a menu.
  • 'progressbar' - Used to represent a component which indicates progress of a task.
  • 'radio' - Used to represent a radio button.
  • 'radiogroup' - Used to represent a group of radio buttons.
  • 'scrollbar' - Used to represent a scroll bar.
  • 'spinbutton' - Used to represent a button which opens a list of choices.
  • 'switch' - Used to represent a switch which can be turned on and off.
  • 'tab' - Used to represent a tab.
  • 'tablist' - Used to represent a list of tabs.
  • 'timer' - Used to represent a timer.
  • 'toolbar' - Used to represent a tool bar (a container of action buttons or components).
TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

accessibilityValue

Represents the current value of a component. It can be a textual description of a component's value, or for range-based components, such as sliders and progress bars, it contains range information (minimum, current, and maximum).

See the Accessibility guide for more information.

TypeRequired
object: {min: number, max: number, now: number, text: string}No

accessibilityActions

Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The accessibilityActions property should contain a list of action objects. Each action object should contain the field name and label.

See the Accessibility guide for more information.

TypeRequired
arrayNo

onAccessibilityAction

Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform.

See the Accessibility guide for more information.

TypeRequired
functionNo

onAccessibilityTap

When accessible is true, the system will try to invoke this function when the user performs accessibility tap gesture.

TypeRequired
functionNo

onMagicTap

When accessible is true, the system will invoke this function when the user performs the magic tap gesture.

TypeRequiredPlatform
functionNoiOS

onAccessibilityEscape

When accessible is true, the system will invoke this function when the user performs the escape gesture.

TypeRequiredPlatform
functionNoiOS

accessibilityViewIsModal

A value indicating whether VoiceOver should ignore the elements within views that are siblings of the receiver. Default is false.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityElementsHidden

A value indicating whether the accessibility elements contained within this accessibility element are hidden. Default is false.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityIgnoresInvertColors

A value indicating this view should or should not be inverted when color inversion is turned on. A value of true will tell the view to not be inverted even if color inversion is turned on.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityLiveRegion

Indicates to accessibility services whether the user should be notified when this view changes. Works for Android API >= 19 only. Possible values:

  • 'none' - Accessibility services should not announce changes to this view.
  • 'polite'- Accessibility services should announce changes to this view.
  • 'assertive' - Accessibility services should interrupt ongoing speech to immediately announce changes to this view.

See the Android View docs for reference.

TypeRequiredPlatform
enum('none', 'polite', 'assertive')NoAndroid

importantForAccessibility

Controls how view is important for accessibility which is if it fires accessibility events and if it is reported to accessibility services that query the screen. Works for Android only.

Possible values:

  • 'auto' - The system determines whether the view is important for accessibility - default (recommended).
  • 'yes' - The view is important for accessibility.
  • 'no' - The view is not important for accessibility.
  • 'no-hide-descendants' - The view is not important for accessibility, nor are any of its descendant views.

See the Android importantForAccessibility docs for reference.

TypeRequiredPlatform
enum('auto', 'yes', 'no', 'no-hide-descendants')NoAndroid

hitSlop

This defines how far a touch event can start away from the view. Typical interface guidelines recommend touch targets that are at least 30 - 40 points/density-independent pixels.

For example, if a touchable view has a height of 20 the touchable height can be extended to 40 with hitSlop={{top: 10, bottom: 10, left: 0, right: 0}}

The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

nativeID

Used to locate this view from native classes.

This disables the 'layout-only view removal' optimization for this view!

TypeRequired
stringNo

onLayout

Invoked on mount and layout changes with:

{nativeEvent: { layout: {x, y, width, height}}}

This event is fired immediately once the layout has been calculated, but the new layout may not yet be reflected on the screen at the time the event is received, especially if a layout animation is in progress.

TypeRequired
functionNo

onMoveShouldSetResponder

Does this view want to "claim" touch responsiveness? This is called for every touch move on the View when it is not the responder.

View.props.onMoveShouldSetResponder: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onMoveShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a move, it should have this handler which returns true.

View.props.onMoveShouldSetResponderCapture: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderGrant

The View is now responding for touch events. This is the time to highlight and show the user what is happening.

View.props.onResponderGrant: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderMove

The user is moving their finger.

View.props.onResponderMove: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderReject

Another responder is already active and will not release it to that View asking to be the responder.

View.props.onResponderReject: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderRelease

Fired at the end of the touch.

View.props.onResponderRelease: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminate

The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS)

View.props.onResponderTerminate: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminationRequest

Some other View wants to become responder and is asking this View to release its responder. Returning true allows its release.

View.props.onResponderTerminationRequest: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onStartShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a touch start, it should have this handler which returns true.

View.props.onStartShouldSetResponderCapture: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

pointerEvents

Controls whether the View can be the target of touch events.

  • 'auto': The View can be the target of touch events.
  • 'none': The View is never the target of touch events.
  • 'box-none': The View is never the target of touch events but it's subviews can be. It behaves like if the view had the following classes in CSS:
.box-none {
pointer-events: none;
}
.box-none * {
pointer-events: auto;
}
  • 'box-only': The view can be the target of touch events but it's subviews cannot be. It behaves like if the view had the following classes in CSS:
.box-only {
pointer-events: auto;
}
.box-only * {
pointer-events: none;
}

Since pointerEvents does not affect layout/appearance, and we are already deviating from the spec by adding additional modes, we opt to not include pointerEvents on style. On some platforms, we would need to implement it as a className anyways. Using style or not is an implementation detail of the platform.

TypeRequired
enum('box-none', 'none', 'box-only', 'auto')No

removeClippedSubviews

This is a reserved performance property exposed by RCTView and is useful for scrolling content when there are many subviews, most of which are offscreen. For this property to be effective, it must be applied to a view that contains many subviews that extend outside its bound. The subviews must also have overflow: hidden, as should the containing view (or one of its superviews).

TypeRequired
boolNo

style

TypeRequired
view stylesNo

testID

Used to locate this view in end-to-end tests.

This disables the 'layout-only view removal' optimization for this view!

TypeRequired
stringNo

collapsable

Views that are only used to layout their children or otherwise don't draw anything may be automatically removed from the native hierarchy as an optimization. Set this property to false to disable this optimization and ensure that this View exists in the native view hierarchy.

TypeRequiredPlatform
boolNoAndroid

needsOffscreenAlphaCompositing

Whether this View needs to rendered offscreen and composited with an alpha in order to preserve 100% correct colors and blending behavior. The default (false) falls back to drawing the component and its children with an alpha applied to the paint used to draw each element instead of rendering the full component offscreen and compositing it back with an alpha value. This default may be noticeable and undesired in the case where the View you are setting an opacity on has multiple overlapping elements (e.g. multiple overlapping Views, or text and a background).

Rendering offscreen to preserve correct alpha behavior is extremely expensive and hard to debug for non-native developers, which is why it is not turned on by default. If you do need to enable this property for an animation, consider combining it with renderToHardwareTextureAndroid if the view contents are static (i.e. it doesn't need to be redrawn each frame). If that property is enabled, this View will be rendered off-screen once, saved in a hardware texture, and then composited onto the screen with an alpha each frame without having to switch rendering targets on the GPU.

TypeRequired
boolNo

renderToHardwareTextureAndroid

Whether this View should render itself (and all of its children) into a single hardware texture on the GPU.

On Android, this is useful for animations and interactions that only modify opacity, rotation, translation, and/or scale: in those cases, the view doesn't have to be redrawn and display lists don't need to be re-executed. The texture can be re-used and re-composited with different parameters. The downside is that this can use up limited video memory, so this prop should be set back to false at the end of the interaction/animation.

TypeRequiredPlatform
boolNoAndroid

shouldRasterizeIOS

Whether this View should be rendered as a bitmap before compositing.

On iOS, this is useful for animations and interactions that do not modify this component's dimensions nor its children; for example, when translating the position of a static view, rasterization allows the renderer to reuse a cached bitmap of a static view and quickly composite it during each frame.

Rasterization incurs an off-screen drawing pass and the bitmap consumes memory. Test and measure when using this property.

TypeRequiredPlatform
boolNoiOS

nextFocusDown

Designates the next view to receive focus when the user navigates down. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusForward

Designates the next view to receive focus when the user navigates forward. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusLeft

Designates the next view to receive focus when the user navigates left. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusRight

Designates the next view to receive focus when the user navigates right. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusUp

Designates the next view to receive focus when the user navigates up. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

clickable

Determines whether this View is clickable or tappable for accessibility hints.

TypeRequiredPlatform
booleanNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.60/viewpagerandroid.html b/docs/0.60/viewpagerandroid.html index 4c1975c0214..cc5890a6ba8 100644 --- a/docs/0.60/viewpagerandroid.html +++ b/docs/0.60/viewpagerandroid.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
const styles = {
...
viewPager: {
flex: 1
},
pageStyle: {
alignItems: 'center',
padding: 20,
}
}

Reference

Props

Inherits View Props.

initialPage

Index of initial page that should be selected. Use setPage method to update the page, and onPageSelected to monitor page changes

TypeRequired
numberNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

TypeRequired
enum('none', 'on-drag')No

onPageScroll

Executed when transitioning between pages (either because of animation for the requested page change or when user is swiping/dragging between pages) The event.nativeEvent object for this callback will carry following data:

TypeRequired
functionNo

onPageScrollStateChanged

Function called when the page scrolling state has changed. The page scrolling state can be in 3 states:

TypeRequired
functionNo

onPageSelected

This callback will be called once ViewPager finish navigating to selected page (when user swipes between pages). The event.nativeEvent object passed to this callback will have following fields:

TypeRequired
functionNo

pageMargin

Blank space to show between pages. This is only visible while scrolling, pages are still edge-to-edge.

TypeRequired
numberNo

peekEnabled

Whether enable showing peekFraction or not. If this is true, the preview of last and next page will show in current screen. Defaults to false.

TypeRequired
boolNo

scrollEnabled

When false, the content does not scroll. The default value is true.

TypeRequired
boolNo

setPage

A helper function to scroll to a specific page in the ViewPager. The transition between pages will be animated.

TypeRequired
NumberYes

setPageWithoutAnimation

A helper function to scroll to a specific page in the ViewPager. The transition between pages will not be animated.

TypeRequired
NumberYes

Type Definitions

ViewPagerScrollState

Type
\$Enum

Constants:

ValueDescription
idle
dragging
settling
Edit this page
Last updated on
- + diff --git a/docs/0.60/viewpagerandroid/index.html b/docs/0.60/viewpagerandroid/index.html index 4c1975c0214..cc5890a6ba8 100644 --- a/docs/0.60/viewpagerandroid/index.html +++ b/docs/0.60/viewpagerandroid/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
const styles = {
...
viewPager: {
flex: 1
},
pageStyle: {
alignItems: 'center',
padding: 20,
}
}

Reference

Props

Inherits View Props.

initialPage

Index of initial page that should be selected. Use setPage method to update the page, and onPageSelected to monitor page changes

TypeRequired
numberNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

TypeRequired
enum('none', 'on-drag')No

onPageScroll

Executed when transitioning between pages (either because of animation for the requested page change or when user is swiping/dragging between pages) The event.nativeEvent object for this callback will carry following data:

TypeRequired
functionNo

onPageScrollStateChanged

Function called when the page scrolling state has changed. The page scrolling state can be in 3 states:

TypeRequired
functionNo

onPageSelected

This callback will be called once ViewPager finish navigating to selected page (when user swipes between pages). The event.nativeEvent object passed to this callback will have following fields:

TypeRequired
functionNo

pageMargin

Blank space to show between pages. This is only visible while scrolling, pages are still edge-to-edge.

TypeRequired
numberNo

peekEnabled

Whether enable showing peekFraction or not. If this is true, the preview of last and next page will show in current screen. Defaults to false.

TypeRequired
boolNo

scrollEnabled

When false, the content does not scroll. The default value is true.

TypeRequired
boolNo

setPage

A helper function to scroll to a specific page in the ViewPager. The transition between pages will be animated.

TypeRequired
NumberYes

setPageWithoutAnimation

A helper function to scroll to a specific page in the ViewPager. The transition between pages will not be animated.

TypeRequired
NumberYes

Type Definitions

ViewPagerScrollState

Type
\$Enum

Constants:

ValueDescription
idle
dragging
settling
Edit this page
Last updated on
- + diff --git a/docs/0.60/virtualizedlist.html b/docs/0.60/virtualizedlist.html index 0783fae723f..07e6e67935c 100644 --- a/docs/0.60/virtualizedlist.html +++ b/docs/0.60/virtualizedlist.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

VirtualizedList

Base implementation for the more convenient <FlatList> and <SectionList> components, which are also better documented. In general, this should only really be used if you need more flexibility than FlatList provides, e.g. for use with immutable data instead of plain arrays.

Virtualization massively improves memory consumption and performance of large lists by maintaining a finite render window of active items and replacing all items outside of the render window with appropriately sized blank space. The window adapts to scrolling behavior, and items are rendered incrementally with low-pri (after any running interactions) if they are far from the visible area, or with hi-pri otherwise to minimize the potential of seeing blank space.

Some caveats:

  • Internal state is not preserved when content scrolls out of the render window. Make sure all your data is captured in the item data or external stores like Flux, Redux, or Relay.
  • This is a PureComponent which means that it will not re-render if props remain shallow-equal. Make sure that everything your renderItem function depends on is passed as a prop (e.g. extraData) that is not === after updates, otherwise your UI may not update on changes. This includes the data prop and parent component state.
  • In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate and momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application, and we are working on improving it behind the scenes.
  • By default, the list looks for a key prop on each item and uses that for the React key. Alternatively, you can provide a custom keyExtractor prop.

Reference

Props

Inherits ScrollView Props.

renderItem

(info: any) => ?React.Element<any>

Takes an item from data and renders it into the list

TypeRequired
functionYes

data

The default accessor functions assume this is an array of objects with shape {key: string} but you can override getItem, getItemCount, and keyExtractor to handle any type of index-based data.

TypeRequired
anyYes

getItem

(data: any, index: number) => object;

A generic accessor for extracting an item from any sort of data blob.

TypeRequired
functionYes

getItemCount

(data: any) => number;

Determines how many items are in the data blob.

TypeRequired
functionYes

debug

debug will turn on extra logging and visual overlays to aid with debugging both usage and implementation, but with a significant perf hit.

TypeRequired
booleanNo

extraData

A marker property for telling the list to re-render (since it implements PureComponent). If any of your renderItem, Header, Footer, etc. functions depend on anything outside of the data prop, stick it here and treat it immutably.

TypeRequired
anyNo

getItemLayout

(
data: any,
index: number,
) => {length: number, offset: number, index: number}
TypeRequired
functionNo

initialScrollIndex

Instead of starting at the top with the first item, start at initialScrollIndex. This disables the "scroll to top" optimization that keeps the first initialNumToRender items always rendered and immediately renders the items starting at this initial index. Requires getItemLayout to be implemented.

TypeRequired
numberNo

inverted

Reverses the direction of scroll. Uses scale transforms of -1.

TypeRequired
booleanNo

CellRendererComponent

Each cell is rendered using this element. Can be a React Component Class,or a render function. Defaults to using View.

TypeRequired
component, functionNo

listKey

A unique identifier for this list. If there are multiple VirtualizedLists at the same level of nesting within another VirtualizedList, this key is necessary for virtualization to work properly.

TypeRequired
stringTrue

ListEmptyComponent

Rendered when the list is empty. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
component, elementNo

ListItemComponent

Each data item is rendered using this element. Can be a React Component Class, or a render function

TypeRequired
component, functionNo

ListFooterComponent

Rendered at the bottom of all the items. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
component, elementNo

ListFooterComponentStyle

Styling for internal View for ListFooterComponent

TypeRequired
ViewStylePropNo

ListHeaderComponent

Rendered at the top of all the items. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
component, elementNo

ListHeaderComponentStyle

Styling for internal View for ListHeaderComponent

TypeRequired
ViewStylePropNo

onLayout

TypeRequired
functionNo

onRefresh

() => void

If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the refreshing prop correctly.

TypeRequired
functionNo

onScrollToIndexFailed

(info: {
index: number,
highestMeasuredFrameIndex: number,
averageItemLength: number,
}) => void

Used to handle failures when scrolling to an index that has not been measured yet. Recommended action is to either compute your own offset and scrollTo it, or scroll as far as possible and then try again after more items have been rendered.

TypeRequired
functionNo

onViewableItemsChanged

(info: {
viewableItems: array,
changed: array,
}) => void

Called when the viewability of rows changes, as defined by the viewabilityConfig prop.

TypeRequired
functionNo

refreshing

Set this true while waiting for new data from a refresh.

TypeRequired
booleanNo

refreshControl

A custom refresh control element. When set, it overrides the default <RefreshControl> component built internally. The onRefresh and refreshing props are also ignored. Only works for vertical VirtualizedList.

TypeRequired
elementNo

removeClippedSubviews

This may improve scroll performance for large lists.

Note: May have bugs (missing content) in some circumstances - use at your own risk.

TypeRequired
booleanNo

renderScrollComponent

(props: object) => element;

Render a custom scroll component, e.g. with a differently styled RefreshControl.

TypeRequired
functionNo

viewabilityConfig

See ViewabilityHelper.js for flow type and further documentation.

TypeRequired
ViewabilityConfigNo

viewabilityConfigCallbackPairs

List of ViewabilityConfig/onViewableItemsChanged pairs. A specific onViewableItemsChanged will be called when its corresponding ViewabilityConfig's conditions are met. See ViewabilityHelper.js for flow type and further documentation.

TypeRequired
array of ViewabilityConfigCallbackPairNo

horizontal

TypeRequired
booleanNo

initialNumToRender

How many items to render in the initial batch. This should be enough to fill the screen but not much more. Note these items will never be unmounted as part of the windowed rendering in order to improve perceived performance of scroll-to-top actions.

TypeRequired
numberNo

keyExtractor

(item: object, index: number) => string;

Used to extract a unique key for a given item at the specified index. Key is used for caching and as the react key to track item re-ordering. The default extractor checks item.key, then item.id, and then falls back to using the index, like React does.

TypeRequired
functionNo

maxToRenderPerBatch

The maximum number of items to render in each incremental render batch. The more rendered at once, the better the fill rate, but responsiveness may suffer because rendering content may interfere with responding to button taps or other interactions.

TypeRequired
numberNo

onEndReached

(info: {distanceFromEnd: number}) => void

Called once when the scroll position gets within onEndReachedThreshold of the rendered content.

TypeRequired
functionNo

onEndReachedThreshold

How far from the end (in units of visible length of the list) the bottom edge of the list must be from the end of the content to trigger the onEndReached callback. Thus a value of 0.5 will trigger onEndReached when the end of the content is within half the visible length of the list.

TypeRequired
numberNo

updateCellsBatchingPeriod

Amount of time between low-pri item render batches, e.g. for rendering items quite a ways off screen. Similar fill rate/responsiveness tradeoff as maxToRenderPerBatch.

TypeRequired
numberNo

windowSize

Determines the maximum number of items rendered outside of the visible area, in units of visible lengths. So if your list fills the screen, then windowSize={21} (the default) will render the visible screen area plus up to 10 screens above and 10 below the viewport. Reducing this number will reduce memory consumption and may improve performance, but will increase the chance that fast scrolling may reveal momentary blank areas of unrendered content.

TypeRequired
numberNo

disableVirtualization

Deprecated. Virtualization provides significant performance and memory optimizations, but fully unmounts react instances that are outside of the render window. You should only need to disable this for debugging purposes.

TypeRequired
No

persistentScrollbar

TypeRequired
boolNo

progressViewOffset

Set this when offset is needed for the loading indicator to show correctly.

TypeRequiredPlatform
numberNoAndroid

Methods

scrollToEnd()

scrollToEnd(([params]: object));

scrollToIndex()

scrollToIndex((params: object));

scrollToItem()

scrollToItem((params: object));

scrollToOffset()

scrollToOffset((params: object));

Scroll to a specific content pixel offset in the list.

Param offset expects the offset to scroll to. In case of horizontal is true, the offset is the x-value, in any other case the offset is the y-value.

Param animated (true by default) defines whether the list should do an animation while scrolling.

recordInteraction()

recordInteraction();

flashScrollIndicators()

flashScrollIndicators();
Edit this page
Last updated on
- + diff --git a/docs/0.60/virtualizedlist/index.html b/docs/0.60/virtualizedlist/index.html index 0783fae723f..07e6e67935c 100644 --- a/docs/0.60/virtualizedlist/index.html +++ b/docs/0.60/virtualizedlist/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.60

VirtualizedList

Base implementation for the more convenient <FlatList> and <SectionList> components, which are also better documented. In general, this should only really be used if you need more flexibility than FlatList provides, e.g. for use with immutable data instead of plain arrays.

Virtualization massively improves memory consumption and performance of large lists by maintaining a finite render window of active items and replacing all items outside of the render window with appropriately sized blank space. The window adapts to scrolling behavior, and items are rendered incrementally with low-pri (after any running interactions) if they are far from the visible area, or with hi-pri otherwise to minimize the potential of seeing blank space.

Some caveats:

  • Internal state is not preserved when content scrolls out of the render window. Make sure all your data is captured in the item data or external stores like Flux, Redux, or Relay.
  • This is a PureComponent which means that it will not re-render if props remain shallow-equal. Make sure that everything your renderItem function depends on is passed as a prop (e.g. extraData) that is not === after updates, otherwise your UI may not update on changes. This includes the data prop and parent component state.
  • In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate and momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application, and we are working on improving it behind the scenes.
  • By default, the list looks for a key prop on each item and uses that for the React key. Alternatively, you can provide a custom keyExtractor prop.

Reference

Props

Inherits ScrollView Props.

renderItem

(info: any) => ?React.Element<any>

Takes an item from data and renders it into the list

TypeRequired
functionYes

data

The default accessor functions assume this is an array of objects with shape {key: string} but you can override getItem, getItemCount, and keyExtractor to handle any type of index-based data.

TypeRequired
anyYes

getItem

(data: any, index: number) => object;

A generic accessor for extracting an item from any sort of data blob.

TypeRequired
functionYes

getItemCount

(data: any) => number;

Determines how many items are in the data blob.

TypeRequired
functionYes

debug

debug will turn on extra logging and visual overlays to aid with debugging both usage and implementation, but with a significant perf hit.

TypeRequired
booleanNo

extraData

A marker property for telling the list to re-render (since it implements PureComponent). If any of your renderItem, Header, Footer, etc. functions depend on anything outside of the data prop, stick it here and treat it immutably.

TypeRequired
anyNo

getItemLayout

(
data: any,
index: number,
) => {length: number, offset: number, index: number}
TypeRequired
functionNo

initialScrollIndex

Instead of starting at the top with the first item, start at initialScrollIndex. This disables the "scroll to top" optimization that keeps the first initialNumToRender items always rendered and immediately renders the items starting at this initial index. Requires getItemLayout to be implemented.

TypeRequired
numberNo

inverted

Reverses the direction of scroll. Uses scale transforms of -1.

TypeRequired
booleanNo

CellRendererComponent

Each cell is rendered using this element. Can be a React Component Class,or a render function. Defaults to using View.

TypeRequired
component, functionNo

listKey

A unique identifier for this list. If there are multiple VirtualizedLists at the same level of nesting within another VirtualizedList, this key is necessary for virtualization to work properly.

TypeRequired
stringTrue

ListEmptyComponent

Rendered when the list is empty. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
component, elementNo

ListItemComponent

Each data item is rendered using this element. Can be a React Component Class, or a render function

TypeRequired
component, functionNo

ListFooterComponent

Rendered at the bottom of all the items. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
component, elementNo

ListFooterComponentStyle

Styling for internal View for ListFooterComponent

TypeRequired
ViewStylePropNo

ListHeaderComponent

Rendered at the top of all the items. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
component, elementNo

ListHeaderComponentStyle

Styling for internal View for ListHeaderComponent

TypeRequired
ViewStylePropNo

onLayout

TypeRequired
functionNo

onRefresh

() => void

If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the refreshing prop correctly.

TypeRequired
functionNo

onScrollToIndexFailed

(info: {
index: number,
highestMeasuredFrameIndex: number,
averageItemLength: number,
}) => void

Used to handle failures when scrolling to an index that has not been measured yet. Recommended action is to either compute your own offset and scrollTo it, or scroll as far as possible and then try again after more items have been rendered.

TypeRequired
functionNo

onViewableItemsChanged

(info: {
viewableItems: array,
changed: array,
}) => void

Called when the viewability of rows changes, as defined by the viewabilityConfig prop.

TypeRequired
functionNo

refreshing

Set this true while waiting for new data from a refresh.

TypeRequired
booleanNo

refreshControl

A custom refresh control element. When set, it overrides the default <RefreshControl> component built internally. The onRefresh and refreshing props are also ignored. Only works for vertical VirtualizedList.

TypeRequired
elementNo

removeClippedSubviews

This may improve scroll performance for large lists.

Note: May have bugs (missing content) in some circumstances - use at your own risk.

TypeRequired
booleanNo

renderScrollComponent

(props: object) => element;

Render a custom scroll component, e.g. with a differently styled RefreshControl.

TypeRequired
functionNo

viewabilityConfig

See ViewabilityHelper.js for flow type and further documentation.

TypeRequired
ViewabilityConfigNo

viewabilityConfigCallbackPairs

List of ViewabilityConfig/onViewableItemsChanged pairs. A specific onViewableItemsChanged will be called when its corresponding ViewabilityConfig's conditions are met. See ViewabilityHelper.js for flow type and further documentation.

TypeRequired
array of ViewabilityConfigCallbackPairNo

horizontal

TypeRequired
booleanNo

initialNumToRender

How many items to render in the initial batch. This should be enough to fill the screen but not much more. Note these items will never be unmounted as part of the windowed rendering in order to improve perceived performance of scroll-to-top actions.

TypeRequired
numberNo

keyExtractor

(item: object, index: number) => string;

Used to extract a unique key for a given item at the specified index. Key is used for caching and as the react key to track item re-ordering. The default extractor checks item.key, then item.id, and then falls back to using the index, like React does.

TypeRequired
functionNo

maxToRenderPerBatch

The maximum number of items to render in each incremental render batch. The more rendered at once, the better the fill rate, but responsiveness may suffer because rendering content may interfere with responding to button taps or other interactions.

TypeRequired
numberNo

onEndReached

(info: {distanceFromEnd: number}) => void

Called once when the scroll position gets within onEndReachedThreshold of the rendered content.

TypeRequired
functionNo

onEndReachedThreshold

How far from the end (in units of visible length of the list) the bottom edge of the list must be from the end of the content to trigger the onEndReached callback. Thus a value of 0.5 will trigger onEndReached when the end of the content is within half the visible length of the list.

TypeRequired
numberNo

updateCellsBatchingPeriod

Amount of time between low-pri item render batches, e.g. for rendering items quite a ways off screen. Similar fill rate/responsiveness tradeoff as maxToRenderPerBatch.

TypeRequired
numberNo

windowSize

Determines the maximum number of items rendered outside of the visible area, in units of visible lengths. So if your list fills the screen, then windowSize={21} (the default) will render the visible screen area plus up to 10 screens above and 10 below the viewport. Reducing this number will reduce memory consumption and may improve performance, but will increase the chance that fast scrolling may reveal momentary blank areas of unrendered content.

TypeRequired
numberNo

disableVirtualization

Deprecated. Virtualization provides significant performance and memory optimizations, but fully unmounts react instances that are outside of the render window. You should only need to disable this for debugging purposes.

TypeRequired
No

persistentScrollbar

TypeRequired
boolNo

progressViewOffset

Set this when offset is needed for the loading indicator to show correctly.

TypeRequiredPlatform
numberNoAndroid

Methods

scrollToEnd()

scrollToEnd(([params]: object));

scrollToIndex()

scrollToIndex((params: object));

scrollToItem()

scrollToItem((params: object));

scrollToOffset()

scrollToOffset((params: object));

Scroll to a specific content pixel offset in the list.

Param offset expects the offset to scroll to. In case of horizontal is true, the offset is the x-value, in any other case the offset is the y-value.

Param animated (true by default) defines whether the list should do an animation while scrolling.

recordInteraction()

recordInteraction();

flashScrollIndicators()

flashScrollIndicators();
Edit this page
Last updated on
- + diff --git a/docs/0.60/webview.html b/docs/0.60/webview.html index 6485ecf56b8..b2805a52eca 100644 --- a/docs/0.60/webview.html +++ b/docs/0.60/webview.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
class MyInlineWeb extends Component {
render() {
return (
<WebView
originWhitelist={['*']}
source={{ html: '<h1>Hello world</h1>' }}
/>
);
}
}

You can use this component to navigate back and forth in the web view's history and configure various properties for the web content.

On iOS, the useWebKit prop can be used to opt into a WKWebView-backed implementation.

Security Warning: Currently, onMessage and postMessage do not allow specifying an origin. This can lead to cross-site scripting attacks if an unexpected document is loaded within a WebView instance. Please refer to the MDN documentation for Window.postMessage() for more details on the security implications of this.

Reference

Props

Inherits View Props.

source

Loads static HTML or a URI (with optional headers) in the WebView. Note that static HTML will require setting originWhitelist to ["*"].

The object passed to source can have either of the following shapes:

Load uri

Static HTML

TypeRequired
objectNo

automaticallyAdjustContentInsets

Controls whether to adjust the content inset for web views that are placed behind a navigation bar, tab bar, or toolbar. The default value is true.

TypeRequired
boolNo

injectJavaScript

Function that accepts a string that will be passed to the WebView and executed immediately as JavaScript.

TypeRequired
functionNo

injectedJavaScript

Set this to provide JavaScript that will be injected into the web page when the view loads.

TypeRequired
stringNo

mediaPlaybackRequiresUserAction

Boolean that determines whether HTML5 audio and video requires the user to tap them before they start playing. The default value is true.

TypeRequired
boolNo

nativeConfig

Override the native component used to render the WebView. Enables a custom native WebView which uses the same JavaScript as the original WebView.

The nativeConfig prop expects an object with the following keys:

TypeRequired
objectNo

onError

Function that is invoked when the WebView load fails.

TypeRequired
functionNo

onLoad

Function that is invoked when the WebView has finished loading.

TypeRequired
functionNo

onLoadEnd

Function that is invoked when the WebView load succeeds or fails.

TypeRequired
functionNo

onLoadStart

Function that is invoked when the WebView starts loading.

TypeRequired
functionNo

onMessage

A function that is invoked when the webview calls window.postMessage. Setting this property will inject a postMessage global into your webview, but will still call pre-existing values of postMessage.

window.postMessage accepts one argument, data, which will be available on the event object, event.nativeEvent.data. data must be a string.

TypeRequired
functionNo

onNavigationStateChange

Function that is invoked when the WebView loading starts or ends.

TypeRequired
functionNo

originWhitelist

List of origin strings to allow being navigated to. The strings allow wildcards and get matched against only the origin (not the full URL). If the user taps to navigate to a new page but the new page is not in this safelist, the URL will be handled by the OS. The default safelistlisted origins are "http://*" and "https://*".

TypeRequired
array of stringsNo

renderError

Function that returns a view to show if there's an error.

TypeRequired
functionNo

renderLoading

Function that returns a loading indicator. The startInLoadingState prop must be set to true in order to use this prop.

TypeRequired
functionNo

scalesPageToFit

Boolean that controls whether the web content is scaled to fit the view and enables the user to change the scale. The default value is true.

On iOS, when useWebKit=true, this prop will not work.

TypeRequired
boolNo

onShouldStartLoadWithRequest

Function that allows custom handling of any web view requests. Return true from the function to continue loading the request and false to stop loading.

TypeRequiredPlatform
functionNoiOS

startInLoadingState

Boolean value that forces the WebView to show the loading view on the first load. This prop must be set to true in order for the renderLoading prop to work.

TypeRequired
boolNo

decelerationRate

A floating-point number that determines how quickly the scroll view decelerates after the user lifts their finger. You may also use the string shortcuts "normal" and "fast" which match the underlying iOS settings for UIScrollViewDecelerationRateNormal and UIScrollViewDecelerationRateFast respectively:

TypeRequiredPlatform
numberNoiOS

domStorageEnabled

Boolean value to control whether DOM Storage is enabled. Used only in Android.

TypeRequiredPlatform
boolNoAndroid

javaScriptEnabled

Boolean value to enable JavaScript in the WebView. Used on Android only as JavaScript is enabled by default on iOS. The default value is true.

TypeRequiredPlatform
boolNoAndroid

mixedContentMode

Specifies the mixed content mode. i.e WebView will allow a secure origin to load content from any other origin.

Possible values for mixedContentMode are:

TypeRequiredPlatform
stringNoAndroid

thirdPartyCookiesEnabled

Boolean value to enable third party cookies in the WebView. Used on Android Lollipop and above only as third party cookies are enabled by default on Android Kitkat and below and on iOS. The default value is true.

TypeRequiredPlatform
boolNoAndroid

userAgent

Sets the user-agent for the WebView.

TypeRequiredPlatform
stringNoAndroid

allowsInlineMediaPlayback

Boolean that determines whether HTML5 videos play inline or use the native full-screen controller. The default value is false.

NOTE

In order for video to play inline, not only does this property need to be set to true, but the video element in the HTML document must also include the webkit-playsinline attribute.

TypeRequiredPlatform
boolNoiOS

bounces

Boolean value that determines whether the web view bounces when it reaches the edge of the content. The default value is true.

TypeRequiredPlatform
boolNoiOS

contentInset

The amount by which the web view content is inset from the edges of the scroll view. Defaults to {top: 0, left: 0, bottom: 0, right: 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

dataDetectorTypes

Determines the types of data converted to clickable URLs in the web view's content. By default only phone numbers are detected.

You can provide one type or an array of many types.

Possible values for dataDetectorTypes are:

With the new WebKit implementation, we have three new values:

TypeRequiredPlatform
string, or arrayNoiOS

scrollEnabled

Boolean value that determines whether scrolling is enabled in the WebView. The default value is true.

TypeRequiredPlatform
boolNoiOS

geolocationEnabled

Set whether Geolocation is enabled in the WebView. The default value is false. Used only in Android.

TypeRequiredPlatform
boolNoAndroid

allowUniversalAccessFromFileURLs

Boolean that sets whether JavaScript running in the context of a file scheme URL should be allowed to access content from any origin. Including accessing content from other file scheme URLs. The default value is false.

TypeRequiredPlatform
boolNoAndroid

allowFileAccess

Boolean that sets whether the WebView has access to the file system. The default value is false.

TypeRequiredPlatform
boolNoAndroid

useWebKit

If true, use WKWebView instead of UIWebView.

TypeRequiredPlatform
booleanNoiOS

url

Deprecated. Use the source prop instead.

TypeRequired
stringNo

html

Deprecated. Use the source prop instead.

TypeRequired
stringNo

Methods

extraNativeComponentConfig()

static extraNativeComponentConfig()

goForward()

goForward();

Go forward one page in the web view's history.

goBack()

goBack();

Go back one page in the web view's history.

reload()

reload();

Reloads the current page.

stopLoading()

stopLoading();

Stop loading the current page.

Edit this page
Last updated on
- + diff --git a/docs/0.60/webview/index.html b/docs/0.60/webview/index.html index 6485ecf56b8..b2805a52eca 100644 --- a/docs/0.60/webview/index.html +++ b/docs/0.60/webview/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
class MyInlineWeb extends Component {
render() {
return (
<WebView
originWhitelist={['*']}
source={{ html: '<h1>Hello world</h1>' }}
/>
);
}
}

You can use this component to navigate back and forth in the web view's history and configure various properties for the web content.

On iOS, the useWebKit prop can be used to opt into a WKWebView-backed implementation.

Security Warning: Currently, onMessage and postMessage do not allow specifying an origin. This can lead to cross-site scripting attacks if an unexpected document is loaded within a WebView instance. Please refer to the MDN documentation for Window.postMessage() for more details on the security implications of this.

Reference

Props

Inherits View Props.

source

Loads static HTML or a URI (with optional headers) in the WebView. Note that static HTML will require setting originWhitelist to ["*"].

The object passed to source can have either of the following shapes:

Load uri

Static HTML

TypeRequired
objectNo

automaticallyAdjustContentInsets

Controls whether to adjust the content inset for web views that are placed behind a navigation bar, tab bar, or toolbar. The default value is true.

TypeRequired
boolNo

injectJavaScript

Function that accepts a string that will be passed to the WebView and executed immediately as JavaScript.

TypeRequired
functionNo

injectedJavaScript

Set this to provide JavaScript that will be injected into the web page when the view loads.

TypeRequired
stringNo

mediaPlaybackRequiresUserAction

Boolean that determines whether HTML5 audio and video requires the user to tap them before they start playing. The default value is true.

TypeRequired
boolNo

nativeConfig

Override the native component used to render the WebView. Enables a custom native WebView which uses the same JavaScript as the original WebView.

The nativeConfig prop expects an object with the following keys:

TypeRequired
objectNo

onError

Function that is invoked when the WebView load fails.

TypeRequired
functionNo

onLoad

Function that is invoked when the WebView has finished loading.

TypeRequired
functionNo

onLoadEnd

Function that is invoked when the WebView load succeeds or fails.

TypeRequired
functionNo

onLoadStart

Function that is invoked when the WebView starts loading.

TypeRequired
functionNo

onMessage

A function that is invoked when the webview calls window.postMessage. Setting this property will inject a postMessage global into your webview, but will still call pre-existing values of postMessage.

window.postMessage accepts one argument, data, which will be available on the event object, event.nativeEvent.data. data must be a string.

TypeRequired
functionNo

onNavigationStateChange

Function that is invoked when the WebView loading starts or ends.

TypeRequired
functionNo

originWhitelist

List of origin strings to allow being navigated to. The strings allow wildcards and get matched against only the origin (not the full URL). If the user taps to navigate to a new page but the new page is not in this safelist, the URL will be handled by the OS. The default safelistlisted origins are "http://*" and "https://*".

TypeRequired
array of stringsNo

renderError

Function that returns a view to show if there's an error.

TypeRequired
functionNo

renderLoading

Function that returns a loading indicator. The startInLoadingState prop must be set to true in order to use this prop.

TypeRequired
functionNo

scalesPageToFit

Boolean that controls whether the web content is scaled to fit the view and enables the user to change the scale. The default value is true.

On iOS, when useWebKit=true, this prop will not work.

TypeRequired
boolNo

onShouldStartLoadWithRequest

Function that allows custom handling of any web view requests. Return true from the function to continue loading the request and false to stop loading.

TypeRequiredPlatform
functionNoiOS

startInLoadingState

Boolean value that forces the WebView to show the loading view on the first load. This prop must be set to true in order for the renderLoading prop to work.

TypeRequired
boolNo

decelerationRate

A floating-point number that determines how quickly the scroll view decelerates after the user lifts their finger. You may also use the string shortcuts "normal" and "fast" which match the underlying iOS settings for UIScrollViewDecelerationRateNormal and UIScrollViewDecelerationRateFast respectively:

TypeRequiredPlatform
numberNoiOS

domStorageEnabled

Boolean value to control whether DOM Storage is enabled. Used only in Android.

TypeRequiredPlatform
boolNoAndroid

javaScriptEnabled

Boolean value to enable JavaScript in the WebView. Used on Android only as JavaScript is enabled by default on iOS. The default value is true.

TypeRequiredPlatform
boolNoAndroid

mixedContentMode

Specifies the mixed content mode. i.e WebView will allow a secure origin to load content from any other origin.

Possible values for mixedContentMode are:

TypeRequiredPlatform
stringNoAndroid

thirdPartyCookiesEnabled

Boolean value to enable third party cookies in the WebView. Used on Android Lollipop and above only as third party cookies are enabled by default on Android Kitkat and below and on iOS. The default value is true.

TypeRequiredPlatform
boolNoAndroid

userAgent

Sets the user-agent for the WebView.

TypeRequiredPlatform
stringNoAndroid

allowsInlineMediaPlayback

Boolean that determines whether HTML5 videos play inline or use the native full-screen controller. The default value is false.

NOTE

In order for video to play inline, not only does this property need to be set to true, but the video element in the HTML document must also include the webkit-playsinline attribute.

TypeRequiredPlatform
boolNoiOS

bounces

Boolean value that determines whether the web view bounces when it reaches the edge of the content. The default value is true.

TypeRequiredPlatform
boolNoiOS

contentInset

The amount by which the web view content is inset from the edges of the scroll view. Defaults to {top: 0, left: 0, bottom: 0, right: 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

dataDetectorTypes

Determines the types of data converted to clickable URLs in the web view's content. By default only phone numbers are detected.

You can provide one type or an array of many types.

Possible values for dataDetectorTypes are:

With the new WebKit implementation, we have three new values:

TypeRequiredPlatform
string, or arrayNoiOS

scrollEnabled

Boolean value that determines whether scrolling is enabled in the WebView. The default value is true.

TypeRequiredPlatform
boolNoiOS

geolocationEnabled

Set whether Geolocation is enabled in the WebView. The default value is false. Used only in Android.

TypeRequiredPlatform
boolNoAndroid

allowUniversalAccessFromFileURLs

Boolean that sets whether JavaScript running in the context of a file scheme URL should be allowed to access content from any origin. Including accessing content from other file scheme URLs. The default value is false.

TypeRequiredPlatform
boolNoAndroid

allowFileAccess

Boolean that sets whether the WebView has access to the file system. The default value is false.

TypeRequiredPlatform
boolNoAndroid

useWebKit

If true, use WKWebView instead of UIWebView.

TypeRequiredPlatform
booleanNoiOS

url

Deprecated. Use the source prop instead.

TypeRequired
stringNo

html

Deprecated. Use the source prop instead.

TypeRequired
stringNo

Methods

extraNativeComponentConfig()

static extraNativeComponentConfig()

goForward()

goForward();

Go forward one page in the web view's history.

goBack()

goBack();

Go back one page in the web view's history.

reload()

reload();

Reloads the current page.

stopLoading()

stopLoading();

Stop loading the current page.

Edit this page
Last updated on
- + diff --git a/docs/0.61/_getting-started-linux-android.html b/docs/0.61/_getting-started-linux-android.html index 639ad9016a0..02c536f901b 100644 --- a/docs/0.61/_getting-started-linux-android.html +++ b/docs/0.61/_getting-started-linux-android.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: 0.61

_getting-started-linux-android

Installing dependencies

You will need Node, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node

Follow the installation instructions for your Linux distribution to install Node 10 or newer.

Java Development Kit

React Native requires at least the version 8 of the Java SE Development Kit (JDK). You may download and install OpenJDK from AdoptOpenJDK or your system packager. You may also Download and install Oracle JDK 14 if desired.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

Add the following lines to your $HOME/.bash_profile or $HOME/.bashrc (if you are using zsh then ~/.zprofile or ~/.zshrc) config file:

export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

.bash_profile is specific to bash. If you're using another shell, you will need to edit the appropriate shell-specific config file.

Type source $HOME/.bash_profile for bash or source $HOME/.zprofile to load the config into your current shell. Verify that ANDROID_HOME has been set by running echo $ANDROID_HOME and the appropriate directories have been added to your path by running echo $PATH.

Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Watchman

Follow the Watchman installation guide to compile and install Watchman from source.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance and increased compatibility in certain edge cases (translation: you may be able to get by without installing this, but your mileage may vary; installing this now may save you from a headache later).

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

We recommend configuring VM acceleration on your system to improve performance. Once you've followed those instructions, go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (Ctrl + M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.61/_getting-started-linux-android/index.html b/docs/0.61/_getting-started-linux-android/index.html index 639ad9016a0..02c536f901b 100644 --- a/docs/0.61/_getting-started-linux-android/index.html +++ b/docs/0.61/_getting-started-linux-android/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: 0.61

_getting-started-linux-android

Installing dependencies

You will need Node, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node

Follow the installation instructions for your Linux distribution to install Node 10 or newer.

Java Development Kit

React Native requires at least the version 8 of the Java SE Development Kit (JDK). You may download and install OpenJDK from AdoptOpenJDK or your system packager. You may also Download and install Oracle JDK 14 if desired.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

Add the following lines to your $HOME/.bash_profile or $HOME/.bashrc (if you are using zsh then ~/.zprofile or ~/.zshrc) config file:

export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

.bash_profile is specific to bash. If you're using another shell, you will need to edit the appropriate shell-specific config file.

Type source $HOME/.bash_profile for bash or source $HOME/.zprofile to load the config into your current shell. Verify that ANDROID_HOME has been set by running echo $ANDROID_HOME and the appropriate directories have been added to your path by running echo $PATH.

Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Watchman

Follow the Watchman installation guide to compile and install Watchman from source.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance and increased compatibility in certain edge cases (translation: you may be able to get by without installing this, but your mileage may vary; installing this now may save you from a headache later).

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

We recommend configuring VM acceleration on your system to improve performance. Once you've followed those instructions, go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (Ctrl + M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.61/_getting-started-macos-android.html b/docs/0.61/_getting-started-macos-android.html index 12b1721799a..6ffc8f85496 100644 --- a/docs/0.61/_getting-started-macos-android.html +++ b/docs/0.61/_getting-started-macos-android.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: 0.61

_getting-started-macos-android

Installing dependencies

You will need Node, Watchman, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node & Watchman

We recommend installing Node and Watchman using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install node
brew install watchman

If you have already installed Node on your system, make sure it is Node 10 or newer.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

Java Development Kit

We recommend installing JDK using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install --cask adoptopenjdk/openjdk/adoptopenjdk8

If you have already installed JDK on your system, make sure it is JDK 8 or newer.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device
  • If you are not already using Hyper-V: Performance (Intel ® HAXM) (See here for AMD or Hyper-V)

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

Android Studio Welcome

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

Add the following lines to your $HOME/.bash_profile or $HOME/.bashrc (if you are using zsh then ~/.zprofile or ~/.zshrc) config file:

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

.bash_profile is specific to bash. If you're using another shell, you will need to edit the appropriate shell-specific config file.

Type source $HOME/.bash_profile for bash or source $HOME/.zprofile to load the config into your current shell. Verify that ANDROID_HOME has been set by running echo $ANDROID_HOME and the appropriate directories have been added to your path by running echo $PATH.

Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

If you don't have HAXM installed, follow these instructions to set it up, then go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

AwesomeProject on Android

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (⌘M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.61/_getting-started-macos-android/index.html b/docs/0.61/_getting-started-macos-android/index.html index 12b1721799a..6ffc8f85496 100644 --- a/docs/0.61/_getting-started-macos-android/index.html +++ b/docs/0.61/_getting-started-macos-android/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: 0.61

_getting-started-macos-android

Installing dependencies

You will need Node, Watchman, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node & Watchman

We recommend installing Node and Watchman using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install node
brew install watchman

If you have already installed Node on your system, make sure it is Node 10 or newer.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

Java Development Kit

We recommend installing JDK using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install --cask adoptopenjdk/openjdk/adoptopenjdk8

If you have already installed JDK on your system, make sure it is JDK 8 or newer.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device
  • If you are not already using Hyper-V: Performance (Intel ® HAXM) (See here for AMD or Hyper-V)

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

Android Studio Welcome

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

Add the following lines to your $HOME/.bash_profile or $HOME/.bashrc (if you are using zsh then ~/.zprofile or ~/.zshrc) config file:

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

.bash_profile is specific to bash. If you're using another shell, you will need to edit the appropriate shell-specific config file.

Type source $HOME/.bash_profile for bash or source $HOME/.zprofile to load the config into your current shell. Verify that ANDROID_HOME has been set by running echo $ANDROID_HOME and the appropriate directories have been added to your path by running echo $PATH.

Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

If you don't have HAXM installed, follow these instructions to set it up, then go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

AwesomeProject on Android

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (⌘M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.61/_getting-started-macos-ios.html b/docs/0.61/_getting-started-macos-ios.html index 5a51c597391..34cf87543ef 100644 --- a/docs/0.61/_getting-started-macos-ios.html +++ b/docs/0.61/_getting-started-macos-ios.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: 0.61

_getting-started-macos-ios

Installing dependencies

You will need Node, Watchman, the React Native command line interface, and Xcode.

While you can use any editor of your choice to develop your app, you will need to install Xcode in order to set up the necessary tooling to build your React Native app for iOS.

Node & Watchman

We recommend installing Node and Watchman using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install node
brew install watchman

If you have already installed Node on your system, make sure it is Node 10 or newer.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

Xcode & CocoaPods

The easiest way to install Xcode is via the Mac App Store. Installing Xcode will also install the iOS Simulator and all the necessary tools to build your iOS app.

If you have already installed Xcode on your system, make sure it is version 9.4 or newer.

Command Line Tools

You will also need to install the Xcode Command Line Tools. Open Xcode, then choose "Preferences..." from the Xcode menu. Go to the Locations panel and install the tools by selecting the most recent version in the Command Line Tools dropdown.

Xcode Command Line Tools

Installing an iOS Simulator in Xcode

To install a simulator, open Xcode > Preferences... and select the Components tab. Select a simulator with the corresponding version of iOS you wish to use.

CocoaPods

CocoaPods is built with Ruby and it will be installable with the default Ruby available on macOS. You can use a Ruby Version manager, however we recommend that you use the standard Ruby available on macOS unless you know what you're doing.

Using the default Ruby install will require you to use sudo when installing gems. (This is only an issue for the duration of the gem installation, though.)

sudo gem install cocoapods

For more information, please visit CocoaPods Getting Started guide.

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

You can use React Native's built-in command line interface to generate a new project. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding iOS support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Note If the above command is failing, you may have old version of react-native or react-native-cli installed globally on your pc. Try uninstalling the cli and run the cli using npx.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-ios

You should see your new app running in the iOS Simulator shortly.

AwesomeProject on iOS

npx react-native run-ios is one way to run your app. You can also run it directly from within Xcode.

If you can't get this to work, see the Troubleshooting page.

Running on a device

The above command will automatically run your app on the iOS Simulator by default. If you want to run the app on an actual physical iOS device, please follow the instructions here.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Hit ⌘R in your iOS Simulator to reload the app and see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.61/_getting-started-macos-ios/index.html b/docs/0.61/_getting-started-macos-ios/index.html index 5a51c597391..34cf87543ef 100644 --- a/docs/0.61/_getting-started-macos-ios/index.html +++ b/docs/0.61/_getting-started-macos-ios/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: 0.61

_getting-started-macos-ios

Installing dependencies

You will need Node, Watchman, the React Native command line interface, and Xcode.

While you can use any editor of your choice to develop your app, you will need to install Xcode in order to set up the necessary tooling to build your React Native app for iOS.

Node & Watchman

We recommend installing Node and Watchman using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install node
brew install watchman

If you have already installed Node on your system, make sure it is Node 10 or newer.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

Xcode & CocoaPods

The easiest way to install Xcode is via the Mac App Store. Installing Xcode will also install the iOS Simulator and all the necessary tools to build your iOS app.

If you have already installed Xcode on your system, make sure it is version 9.4 or newer.

Command Line Tools

You will also need to install the Xcode Command Line Tools. Open Xcode, then choose "Preferences..." from the Xcode menu. Go to the Locations panel and install the tools by selecting the most recent version in the Command Line Tools dropdown.

Xcode Command Line Tools

Installing an iOS Simulator in Xcode

To install a simulator, open Xcode > Preferences... and select the Components tab. Select a simulator with the corresponding version of iOS you wish to use.

CocoaPods

CocoaPods is built with Ruby and it will be installable with the default Ruby available on macOS. You can use a Ruby Version manager, however we recommend that you use the standard Ruby available on macOS unless you know what you're doing.

Using the default Ruby install will require you to use sudo when installing gems. (This is only an issue for the duration of the gem installation, though.)

sudo gem install cocoapods

For more information, please visit CocoaPods Getting Started guide.

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

You can use React Native's built-in command line interface to generate a new project. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding iOS support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Note If the above command is failing, you may have old version of react-native or react-native-cli installed globally on your pc. Try uninstalling the cli and run the cli using npx.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-ios

You should see your new app running in the iOS Simulator shortly.

AwesomeProject on iOS

npx react-native run-ios is one way to run your app. You can also run it directly from within Xcode.

If you can't get this to work, see the Troubleshooting page.

Running on a device

The above command will automatically run your app on the iOS Simulator by default. If you want to run the app on an actual physical iOS device, please follow the instructions here.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Hit ⌘R in your iOS Simulator to reload the app and see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.61/_getting-started-windows-android.html b/docs/0.61/_getting-started-windows-android.html index 3d6fbae4fdf..e68718ee9e8 100644 --- a/docs/0.61/_getting-started-windows-android.html +++ b/docs/0.61/_getting-started-windows-android.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

_getting-started-windows-android

Installing dependencies

You will need Node, the React Native command line interface, Python2, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node, Python2, JDK

We recommend installing Node and Python2 via Chocolatey, a popular package manager for Windows.

React Native also requires Java SE Development Kit (JDK), as well as Python2. Both can be installed using Chocolatey.

Open an Administrator Command Prompt (right click Command Prompt and select "Run as Administrator"), then run the following command:

choco install -y nodejs.install python2 openjdk8

If you have already installed Node on your system, make sure it is Node 10 or newer. If you already have a JDK on your system, make sure it is version 8 or newer.

You can find additional installation options on Node's Downloads page.

If you're using the latest version of Java Development Kit, you'll need to change the Gradle version of your project so it can recognize the JDK. You can do that by going to {project root folder}\android\gradle\wrapper\gradle-wrapper.properties and changing the distributionUrl value to upgrade the Gradle version. You can check out here the lastest releases of Gradle.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device
  • If you are not already using Hyper-V: Performance (Intel ® HAXM) (See here for AMD or Hyper-V)

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

Android Studio Welcome

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

  1. Open the Windows Control Panel.
  2. Click on User Accounts, then click User Accounts again
  3. Click on Change my environment variables
  4. Click on New... to create a new ANDROID_HOME user variable that points to the path to your Android SDK:

ANDROID_HOME Environment Variable

The SDK is installed, by default, at the following location:

%LOCALAPPDATA%\Android\Sdk

You can find the actual location of the SDK in the Android Studio "Settings" dialog, under Appearance & Behavior → System Settings → Android SDK.

Open a new Command Prompt window to ensure the new environment variable is loaded before proceeding to the next step.

  1. Open powershell
  2. Copy and paste Get-ChildItem -Path Env:\ into powershell
  3. Verify ANDROID_HOME has been added

4. Add platform-tools to Path

  1. Open the Windows Control Panel.
  2. Click on User Accounts, then click User Accounts again
  3. Click on Change my environment variables
  4. Select the Path variable.
  5. Click Edit.
  6. Click New and add the path to platform-tools to the list.

The default location for this folder is:

%LOCALAPPDATA%\Android\Sdk\platform-tools

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

If you don't have HAXM installed, click on "Install HAXM" or follow these instructions to set it up, then go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

AwesomeProject on Android

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (Ctrl + M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.61/_getting-started-windows-android/index.html b/docs/0.61/_getting-started-windows-android/index.html index 3d6fbae4fdf..e68718ee9e8 100644 --- a/docs/0.61/_getting-started-windows-android/index.html +++ b/docs/0.61/_getting-started-windows-android/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

_getting-started-windows-android

Installing dependencies

You will need Node, the React Native command line interface, Python2, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node, Python2, JDK

We recommend installing Node and Python2 via Chocolatey, a popular package manager for Windows.

React Native also requires Java SE Development Kit (JDK), as well as Python2. Both can be installed using Chocolatey.

Open an Administrator Command Prompt (right click Command Prompt and select "Run as Administrator"), then run the following command:

choco install -y nodejs.install python2 openjdk8

If you have already installed Node on your system, make sure it is Node 10 or newer. If you already have a JDK on your system, make sure it is version 8 or newer.

You can find additional installation options on Node's Downloads page.

If you're using the latest version of Java Development Kit, you'll need to change the Gradle version of your project so it can recognize the JDK. You can do that by going to {project root folder}\android\gradle\wrapper\gradle-wrapper.properties and changing the distributionUrl value to upgrade the Gradle version. You can check out here the lastest releases of Gradle.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device
  • If you are not already using Hyper-V: Performance (Intel ® HAXM) (See here for AMD or Hyper-V)

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

Android Studio Welcome

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

  1. Open the Windows Control Panel.
  2. Click on User Accounts, then click User Accounts again
  3. Click on Change my environment variables
  4. Click on New... to create a new ANDROID_HOME user variable that points to the path to your Android SDK:

ANDROID_HOME Environment Variable

The SDK is installed, by default, at the following location:

%LOCALAPPDATA%\Android\Sdk

You can find the actual location of the SDK in the Android Studio "Settings" dialog, under Appearance & Behavior → System Settings → Android SDK.

Open a new Command Prompt window to ensure the new environment variable is loaded before proceeding to the next step.

  1. Open powershell
  2. Copy and paste Get-ChildItem -Path Env:\ into powershell
  3. Verify ANDROID_HOME has been added

4. Add platform-tools to Path

  1. Open the Windows Control Panel.
  2. Click on User Accounts, then click User Accounts again
  3. Click on Change my environment variables
  4. Select the Path variable.
  5. Click Edit.
  6. Click New and add the path to platform-tools to the list.

The default location for this folder is:

%LOCALAPPDATA%\Android\Sdk\platform-tools

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

If you don't have HAXM installed, click on "Install HAXM" or follow these instructions to set it up, then go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

AwesomeProject on Android

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (Ctrl + M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.61/_integration-with-exisiting-apps-java.html b/docs/0.61/_integration-with-exisiting-apps-java.html index c79e7d6c2c2..76ab074130a 100644 --- a/docs/0.61/_integration-with-exisiting-apps-java.html +++ b/docs/0.61/_integration-with-exisiting-apps-java.html @@ -19,7 +19,7 @@ - + @@ -48,7 +48,7 @@
if (mReactInstanceManager != null) {
mReactInstanceManager.onHostDestroy(this);
}
if (mReactRootView != null) {
mReactRootView.unmountReactApplication();
}
}

We also need to pass back button events to React Native:

@Override
public void onBackPressed() {
if (mReactInstanceManager != null) {
mReactInstanceManager.onBackPressed();
} else {
super.onBackPressed();
}
}

This allows JavaScript to control what happens when the user presses the hardware back button (e.g. to implement navigation). When JavaScript doesn't handle the back button press, your invokeDefaultOnBackPressed method will be called. By default this finishes your Activity.

Finally, we need to hook up the dev menu. By default, this is activated by (rage) shaking the device, but this is not very useful in emulators. So we make it show when you press the hardware menu button (use Ctrl + M if you're using Android Studio emulator):

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
if (keyCode == KeyEvent.KEYCODE_MENU && mReactInstanceManager != null) {
mReactInstanceManager.showDevOptionsDialog();
return true;
}
return super.onKeyUp(keyCode, event);
}

Now your activity is ready to run some JavaScript code.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ yarn start
2. Run the app

Now build and run your Android app as normal.

Once you reach your React-powered activity inside the app, it should load the JavaScript code from the development server and display:

Screenshot

Creating a release build in Android Studio

You can use Android Studio to create your release builds too! It’s as quick as creating release builds of your previously-existing native Android app. There’s one additional step, which you’ll have to do before every release build. You need to execute the following to create a React Native bundle, which will be included with your native Android app:

$ npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/com/your-company-name/app-package-name/src/main/assets/index.android.bundle --assets-dest android/com/your-company-name/app-package-name/src/main/res/

Don’t forget to replace the paths with correct ones and create the assets folder if it doesn’t exist.

Now, create a release build of your native app from within Android Studio as usual and you should be good to go!

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.61/_integration-with-exisiting-apps-java/index.html b/docs/0.61/_integration-with-exisiting-apps-java/index.html index c79e7d6c2c2..76ab074130a 100644 --- a/docs/0.61/_integration-with-exisiting-apps-java/index.html +++ b/docs/0.61/_integration-with-exisiting-apps-java/index.html @@ -19,7 +19,7 @@ - + @@ -48,7 +48,7 @@
if (mReactInstanceManager != null) {
mReactInstanceManager.onHostDestroy(this);
}
if (mReactRootView != null) {
mReactRootView.unmountReactApplication();
}
}

We also need to pass back button events to React Native:

@Override
public void onBackPressed() {
if (mReactInstanceManager != null) {
mReactInstanceManager.onBackPressed();
} else {
super.onBackPressed();
}
}

This allows JavaScript to control what happens when the user presses the hardware back button (e.g. to implement navigation). When JavaScript doesn't handle the back button press, your invokeDefaultOnBackPressed method will be called. By default this finishes your Activity.

Finally, we need to hook up the dev menu. By default, this is activated by (rage) shaking the device, but this is not very useful in emulators. So we make it show when you press the hardware menu button (use Ctrl + M if you're using Android Studio emulator):

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
if (keyCode == KeyEvent.KEYCODE_MENU && mReactInstanceManager != null) {
mReactInstanceManager.showDevOptionsDialog();
return true;
}
return super.onKeyUp(keyCode, event);
}

Now your activity is ready to run some JavaScript code.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ yarn start
2. Run the app

Now build and run your Android app as normal.

Once you reach your React-powered activity inside the app, it should load the JavaScript code from the development server and display:

Screenshot

Creating a release build in Android Studio

You can use Android Studio to create your release builds too! It’s as quick as creating release builds of your previously-existing native Android app. There’s one additional step, which you’ll have to do before every release build. You need to execute the following to create a React Native bundle, which will be included with your native Android app:

$ npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/com/your-company-name/app-package-name/src/main/assets/index.android.bundle --assets-dest android/com/your-company-name/app-package-name/src/main/res/

Don’t forget to replace the paths with correct ones and create the assets folder if it doesn’t exist.

Now, create a release build of your native app from within Android Studio as usual and you should be good to go!

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.61/_integration-with-exisiting-apps-objc.html b/docs/0.61/_integration-with-exisiting-apps-objc.html index 446c6dd082b..f13fe8fb419 100644 --- a/docs/0.61/_integration-with-exisiting-apps-objc.html +++ b/docs/0.61/_integration-with-exisiting-apps-objc.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
RCTRootView *rootView =
[[RCTRootView alloc] initWithBundleURL: jsCodeLocation
moduleName: @"RNHighScores"
initialProperties:
@{
@"scores" : @[
@{
@"name" : @"Alex",
@"value": @"42"
},
@{
@"name" : @"Joel",
@"value": @"10"
}
]
}
launchOptions: nil];
UIViewController *vc = [[UIViewController alloc] init];
vc.view = rootView;
[self presentViewController:vc animated:YES completion:nil];
}

Note that RCTRootView initWithURL starts up a new JSC VM. To save resources and simplify the communication between RN views in different parts of your native app, you can have multiple views powered by React Native that are associated with a single JS runtime. To do that, instead of using [RCTRootView alloc] initWithURL, use RCTBridge initWithBundleURL to create a bridge and then use RCTRootView initWithBridge.

When moving your app to production, the NSURL can point to a pre-bundled file on disk via something like [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];. You can use the react-native-xcode.sh script in node_modules/react-native/scripts/ to generate that pre-bundled file.

3. Wire Up

Wire up the new link in the main menu to the newly added event handler method.

Event Path

One of the easier ways to do this is to open the view in the storyboard and right click on the new link. Select something such as the Touch Up Inside event, drag that to the storyboard and then select the created method from the list provided.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Add App Transport Security exception

Apple has blocked implicit cleartext HTTP resource loading. So we need to add the following our project's Info.plist (or equivalent) file.

<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>localhost</key>
<dict>
<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
</dict>

App Transport Security is good for your users. Make sure to re-enable it prior to releasing your app for production.

2. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ npm start
3. Run the app

If you are using Xcode or your favorite editor, build and run your native iOS application as normal. Alternatively, you can run the app from the command line using:

# From the root of your project
$ npx react-native run-ios

In our sample application, you should see the link to the "High Scores" and then when you click on that you will see the rendering of your React Native component.

Here is the native application home screen:

Home Screen

Here is the React Native high score screen:

High Scores

If you are getting module resolution issues when running your application please see this GitHub issue for information and possible resolution. This comment seemed to be the latest possible resolution.

See the Code

You can examine the code that added the React Native screen to our sample app on GitHub.

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.61/_integration-with-exisiting-apps-objc/index.html b/docs/0.61/_integration-with-exisiting-apps-objc/index.html index 446c6dd082b..f13fe8fb419 100644 --- a/docs/0.61/_integration-with-exisiting-apps-objc/index.html +++ b/docs/0.61/_integration-with-exisiting-apps-objc/index.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
RCTRootView *rootView =
[[RCTRootView alloc] initWithBundleURL: jsCodeLocation
moduleName: @"RNHighScores"
initialProperties:
@{
@"scores" : @[
@{
@"name" : @"Alex",
@"value": @"42"
},
@{
@"name" : @"Joel",
@"value": @"10"
}
]
}
launchOptions: nil];
UIViewController *vc = [[UIViewController alloc] init];
vc.view = rootView;
[self presentViewController:vc animated:YES completion:nil];
}

Note that RCTRootView initWithURL starts up a new JSC VM. To save resources and simplify the communication between RN views in different parts of your native app, you can have multiple views powered by React Native that are associated with a single JS runtime. To do that, instead of using [RCTRootView alloc] initWithURL, use RCTBridge initWithBundleURL to create a bridge and then use RCTRootView initWithBridge.

When moving your app to production, the NSURL can point to a pre-bundled file on disk via something like [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];. You can use the react-native-xcode.sh script in node_modules/react-native/scripts/ to generate that pre-bundled file.

3. Wire Up

Wire up the new link in the main menu to the newly added event handler method.

Event Path

One of the easier ways to do this is to open the view in the storyboard and right click on the new link. Select something such as the Touch Up Inside event, drag that to the storyboard and then select the created method from the list provided.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Add App Transport Security exception

Apple has blocked implicit cleartext HTTP resource loading. So we need to add the following our project's Info.plist (or equivalent) file.

<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>localhost</key>
<dict>
<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
</dict>

App Transport Security is good for your users. Make sure to re-enable it prior to releasing your app for production.

2. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ npm start
3. Run the app

If you are using Xcode or your favorite editor, build and run your native iOS application as normal. Alternatively, you can run the app from the command line using:

# From the root of your project
$ npx react-native run-ios

In our sample application, you should see the link to the "High Scores" and then when you click on that you will see the rendering of your React Native component.

Here is the native application home screen:

Home Screen

Here is the React Native high score screen:

High Scores

If you are getting module resolution issues when running your application please see this GitHub issue for information and possible resolution. This comment seemed to be the latest possible resolution.

See the Code

You can examine the code that added the React Native screen to our sample app on GitHub.

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.61/_integration-with-exisiting-apps-swift.html b/docs/0.61/_integration-with-exisiting-apps-swift.html index 0488512a8a0..066eece377e 100644 --- a/docs/0.61/_integration-with-exisiting-apps-swift.html +++ b/docs/0.61/_integration-with-exisiting-apps-swift.html @@ -19,7 +19,7 @@ - + @@ -43,7 +43,7 @@
let rootView = RCTRootView(
bundleURL: jsCodeLocation,
moduleName: "RNHighScores",
initialProperties: mockData as [NSObject : AnyObject],
launchOptions: nil
)
let vc = UIViewController()
vc.view = rootView
self.present(vc, animated: true, completion: nil)
}

Note that RCTRootView bundleURL starts up a new JSC VM. To save resources and simplify the communication between RN views in different parts of your native app, you can have multiple views powered by React Native that are associated with a single JS runtime. To do that, instead of using RCTRootView bundleURL, use RCTBridge initWithBundleURL to create a bridge and then use RCTRootView initWithBridge.

When moving your app to production, the NSURL can point to a pre-bundled file on disk via something like let mainBundle = NSBundle(URLForResource: "main" withExtension:"jsbundle"). You can use the react-native-xcode.sh script in node_modules/react-native/scripts/ to generate that pre-bundled file.

3. Wire Up

Wire up the new link in the main menu to the newly added event handler method.

Event Path

One of the easier ways to do this is to open the view in the storyboard and right click on the new link. Select something such as the Touch Up Inside event, drag that to the storyboard and then select the created method from the list provided.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Add App Transport Security exception

Apple has blocked implicit cleartext HTTP resource loading. So we need to add the following our project's Info.plist (or equivalent) file.

<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>localhost</key>
<dict>
<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
</dict>

App Transport Security is good for your users. Make sure to re-enable it prior to releasing your app for production.

2. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ npm start
3. Run the app

If you are using Xcode or your favorite editor, build and run your native iOS application as normal. Alternatively, you can run the app from the command line using:

# From the root of your project
$ npx react-native run-ios

In our sample application, you should see the link to the "High Scores" and then when you click on that you will see the rendering of your React Native component.

Here is the native application home screen:

Home Screen

Here is the React Native high score screen:

High Scores

If you are getting module resolution issues when running your application please see this GitHub issue for information and possible resolution. This comment seemed to be the latest possible resolution.

See the Code

You can examine the code that added the React Native screen to our sample app on GitHub.

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.61/_integration-with-exisiting-apps-swift/index.html b/docs/0.61/_integration-with-exisiting-apps-swift/index.html index 0488512a8a0..066eece377e 100644 --- a/docs/0.61/_integration-with-exisiting-apps-swift/index.html +++ b/docs/0.61/_integration-with-exisiting-apps-swift/index.html @@ -19,7 +19,7 @@ - + @@ -43,7 +43,7 @@
let rootView = RCTRootView(
bundleURL: jsCodeLocation,
moduleName: "RNHighScores",
initialProperties: mockData as [NSObject : AnyObject],
launchOptions: nil
)
let vc = UIViewController()
vc.view = rootView
self.present(vc, animated: true, completion: nil)
}

Note that RCTRootView bundleURL starts up a new JSC VM. To save resources and simplify the communication between RN views in different parts of your native app, you can have multiple views powered by React Native that are associated with a single JS runtime. To do that, instead of using RCTRootView bundleURL, use RCTBridge initWithBundleURL to create a bridge and then use RCTRootView initWithBridge.

When moving your app to production, the NSURL can point to a pre-bundled file on disk via something like let mainBundle = NSBundle(URLForResource: "main" withExtension:"jsbundle"). You can use the react-native-xcode.sh script in node_modules/react-native/scripts/ to generate that pre-bundled file.

3. Wire Up

Wire up the new link in the main menu to the newly added event handler method.

Event Path

One of the easier ways to do this is to open the view in the storyboard and right click on the new link. Select something such as the Touch Up Inside event, drag that to the storyboard and then select the created method from the list provided.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Add App Transport Security exception

Apple has blocked implicit cleartext HTTP resource loading. So we need to add the following our project's Info.plist (or equivalent) file.

<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>localhost</key>
<dict>
<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
</dict>

App Transport Security is good for your users. Make sure to re-enable it prior to releasing your app for production.

2. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ npm start
3. Run the app

If you are using Xcode or your favorite editor, build and run your native iOS application as normal. Alternatively, you can run the app from the command line using:

# From the root of your project
$ npx react-native run-ios

In our sample application, you should see the link to the "High Scores" and then when you click on that you will see the rendering of your React Native component.

Here is the native application home screen:

Home Screen

Here is the React Native high score screen:

High Scores

If you are getting module resolution issues when running your application please see this GitHub issue for information and possible resolution. This comment seemed to be the latest possible resolution.

See the Code

You can examine the code that added the React Native screen to our sample app on GitHub.

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.61/accessibility.html b/docs/0.61/accessibility.html index 2509dffebc8..8b961b8bf7d 100644 --- a/docs/0.61/accessibility.html +++ b/docs/0.61/accessibility.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
# enable
adb shell settings put secure enabled_accessibility_services com.google.android.marvin.talkback/com.google.android.marvin.talkback.TalkBackService

Additional Resources

Edit this page
Last updated on
- + diff --git a/docs/0.61/accessibility/index.html b/docs/0.61/accessibility/index.html index 2509dffebc8..8b961b8bf7d 100644 --- a/docs/0.61/accessibility/index.html +++ b/docs/0.61/accessibility/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
# enable
adb shell settings put secure enabled_accessibility_services com.google.android.marvin.talkback/com.google.android.marvin.talkback.TalkBackService

Additional Resources

Edit this page
Last updated on
- + diff --git a/docs/0.61/accessibilityinfo.html b/docs/0.61/accessibilityinfo.html index 098382d6628..0acdada4dc2 100644 --- a/docs/0.61/accessibilityinfo.html +++ b/docs/0.61/accessibilityinfo.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@
render() {
return (
<View>
<Text>
The reduce motion is{' '}
{this.state.reduceMotionEnabled
? 'enabled'
: 'disabled'}
.
</Text>
<Text>
The screen reader is{' '}
{this.state.screenReaderEnabled
? 'enabled'
: 'disabled'}
.
</Text>
</View>
);
}
}

Reference

Methods

isBoldTextEnabled()

static isBoldTextEnabled()

iOS-Only. Query whether a bold text is currently enabled. Returns a promise which resolves to a boolean. The result is true when bold text is enabled and false otherwise.

isGrayscaleEnabled()

static isGrayscaleEnabled()

iOS-Only. Query whether grayscale is currently enabled. Returns a promise which resolves to a boolean. The result is true when grayscale is enabled and false otherwise.

isInvertColorsEnabled()

static isInvertColorsEnabled()

iOS-Only. Query whether invert colors is currently enabled. Returns a promise which resolves to a boolean. The result is true when invert colors is enabled and false otherwise.

isReduceMotionEnabled()

static isReduceMotionEnabled()

Query whether reduce motion is currently enabled. Returns a promise which resolves to a boolean. The result is true when reduce motion is enabled and false otherwise.

isReduceTransparencyEnabled()

static isReduceTransparencyEnabled()

iOS-Only. Query whether reduce transparency is currently enabled. Returns a promise which resolves to a boolean. The result is true when a reduce transparency is enabled and false otherwise.

isScreenReaderEnabled()

static isScreenReaderEnabled()

Query whether a screen reader is currently enabled. Returns a promise which resolves to a boolean. The result is true when a screen reader is enabled and false otherwise.

addEventListener()

static addEventListener(eventName, handler)

Add an event handler. Supported events:

setAccessibilityFocus()

static setAccessibilityFocus(reactTag)

Set accessibility focus to a React component. On Android, this is equivalent to UIManager.sendAccessibilityEvent(reactTag, UIManager.AccessibilityEventTypes.typeViewFocused);.

announceForAccessibility()

static announceForAccessibility(announcement)

Post a string to be announced by the screen reader.

removeEventListener()

static removeEventListener(eventName, handler)

Remove an event handler.

Edit this page
Last updated on
- + diff --git a/docs/0.61/accessibilityinfo/index.html b/docs/0.61/accessibilityinfo/index.html index 098382d6628..0acdada4dc2 100644 --- a/docs/0.61/accessibilityinfo/index.html +++ b/docs/0.61/accessibilityinfo/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@
render() {
return (
<View>
<Text>
The reduce motion is{' '}
{this.state.reduceMotionEnabled
? 'enabled'
: 'disabled'}
.
</Text>
<Text>
The screen reader is{' '}
{this.state.screenReaderEnabled
? 'enabled'
: 'disabled'}
.
</Text>
</View>
);
}
}

Reference

Methods

isBoldTextEnabled()

static isBoldTextEnabled()

iOS-Only. Query whether a bold text is currently enabled. Returns a promise which resolves to a boolean. The result is true when bold text is enabled and false otherwise.

isGrayscaleEnabled()

static isGrayscaleEnabled()

iOS-Only. Query whether grayscale is currently enabled. Returns a promise which resolves to a boolean. The result is true when grayscale is enabled and false otherwise.

isInvertColorsEnabled()

static isInvertColorsEnabled()

iOS-Only. Query whether invert colors is currently enabled. Returns a promise which resolves to a boolean. The result is true when invert colors is enabled and false otherwise.

isReduceMotionEnabled()

static isReduceMotionEnabled()

Query whether reduce motion is currently enabled. Returns a promise which resolves to a boolean. The result is true when reduce motion is enabled and false otherwise.

isReduceTransparencyEnabled()

static isReduceTransparencyEnabled()

iOS-Only. Query whether reduce transparency is currently enabled. Returns a promise which resolves to a boolean. The result is true when a reduce transparency is enabled and false otherwise.

isScreenReaderEnabled()

static isScreenReaderEnabled()

Query whether a screen reader is currently enabled. Returns a promise which resolves to a boolean. The result is true when a screen reader is enabled and false otherwise.

addEventListener()

static addEventListener(eventName, handler)

Add an event handler. Supported events:

setAccessibilityFocus()

static setAccessibilityFocus(reactTag)

Set accessibility focus to a React component. On Android, this is equivalent to UIManager.sendAccessibilityEvent(reactTag, UIManager.AccessibilityEventTypes.typeViewFocused);.

announceForAccessibility()

static announceForAccessibility(announcement)

Post a string to be announced by the screen reader.

removeEventListener()

static removeEventListener(eventName, handler)

Remove an event handler.

Edit this page
Last updated on
- + diff --git a/docs/0.61/actionsheetios.html b/docs/0.61/actionsheetios.html index 4d792644e3e..7353c5817b5 100644 --- a/docs/0.61/actionsheetios.html +++ b/docs/0.61/actionsheetios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

ActionSheetIOS

Reference

Methods

showActionSheetWithOptions()

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 in options
  • destructiveButtonIndex (int) - index of destructive button in options
  • title (string) - a title to show above the action sheet
  • message (string) - a message to show below the title
  • anchor (number) - the node to which the action sheet should be anchored (used for iPad)
  • tintColor (string) - the color used for non-destructive button titles

The 'callback' function takes one parameter, the zero-based index of the selected item.

Minimal example:

ActionSheetIOS.showActionSheetWithOptions(
{
options: ['Cancel', 'Remove'],
destructiveButtonIndex: 1,
cancelButtonIndex: 0
},
(buttonIndex) => {
if (buttonIndex === 1) {
/* destructive action */
}
}
);

showShareActionSheetWithOptions()

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 share
  • message (string) - a message to share
  • subject (string) - a subject for the message
  • excludedActivityTypes (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.

The 'failureCallback' function takes one parameter, an error object. The only property defined on this object is an optional stack property of type string.

The 'successCallback' function takes two parameters:

  • a boolean value signifying success or failure
  • a string that, in the case of success, indicates the method of sharing
Edit this page
Last updated on
- + diff --git a/docs/0.61/actionsheetios/index.html b/docs/0.61/actionsheetios/index.html index 4d792644e3e..7353c5817b5 100644 --- a/docs/0.61/actionsheetios/index.html +++ b/docs/0.61/actionsheetios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

ActionSheetIOS

Reference

Methods

showActionSheetWithOptions()

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 in options
  • destructiveButtonIndex (int) - index of destructive button in options
  • title (string) - a title to show above the action sheet
  • message (string) - a message to show below the title
  • anchor (number) - the node to which the action sheet should be anchored (used for iPad)
  • tintColor (string) - the color used for non-destructive button titles

The 'callback' function takes one parameter, the zero-based index of the selected item.

Minimal example:

ActionSheetIOS.showActionSheetWithOptions(
{
options: ['Cancel', 'Remove'],
destructiveButtonIndex: 1,
cancelButtonIndex: 0
},
(buttonIndex) => {
if (buttonIndex === 1) {
/* destructive action */
}
}
);

showShareActionSheetWithOptions()

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 share
  • message (string) - a message to share
  • subject (string) - a subject for the message
  • excludedActivityTypes (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.

The 'failureCallback' function takes one parameter, an error object. The only property defined on this object is an optional stack property of type string.

The 'successCallback' function takes two parameters:

  • a boolean value signifying success or failure
  • a string that, in the case of success, indicates the method of sharing
Edit this page
Last updated on
- + diff --git a/docs/0.61/activityindicator.html b/docs/0.61/activityindicator.html index 90ff0758f02..febe6dea5fd 100644 --- a/docs/0.61/activityindicator.html +++ b/docs/0.61/activityindicator.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

ActivityIndicator

Displays a circular loading indicator.

Example

Reference

Props

Inherits View Props.

animating

Whether to show the indicator (true, the default) or hide it (false).

TypeRequired
boolNo

color

The foreground color of the spinner (default is gray on iOS and dark cyan on Android).

TypeRequired
colorNo

hidesWhenStopped

Whether the indicator should hide when not animating (true by default).

TypeRequiredPlatform
boolNoiOS

size

Size of the indicator (default is 'small'). Passing a number to the size prop is only supported on Android.

TypeRequired
enum('small', 'large'), numberNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/activityindicator/index.html b/docs/0.61/activityindicator/index.html index 90ff0758f02..febe6dea5fd 100644 --- a/docs/0.61/activityindicator/index.html +++ b/docs/0.61/activityindicator/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

ActivityIndicator

Displays a circular loading indicator.

Example

Reference

Props

Inherits View Props.

animating

Whether to show the indicator (true, the default) or hide it (false).

TypeRequired
boolNo

color

The foreground color of the spinner (default is gray on iOS and dark cyan on Android).

TypeRequired
colorNo

hidesWhenStopped

Whether the indicator should hide when not animating (true by default).

TypeRequiredPlatform
boolNoiOS

size

Size of the indicator (default is 'small'). Passing a number to the size prop is only supported on Android.

TypeRequired
enum('small', 'large'), numberNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/alert.html b/docs/0.61/alert.html index 42fef4ab1cf..f1b21ed0806 100644 --- a/docs/0.61/alert.html +++ b/docs/0.61/alert.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

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 Android and iOS and can show static alerts. To show an alert that prompts the user to enter some information, see AlertIOS; entering text in an alert is common on iOS only.

Example

iOSAndroid

iOS

On iOS you can specify any number of buttons. Each button can optionally specify a style, which is one of 'default', 'cancel' or 'destructive'.

Android

On Android at most three buttons can be specified. Android has a concept of a neutral, negative and a positive button:

  • If you specify one button, it will be the 'positive' one (such as 'OK')
  • Two buttons mean 'negative', 'positive' (such as 'Cancel', 'OK')
  • Three buttons mean 'neutral', 'negative', 'positive' (such as 'Later', 'Cancel', 'OK')

By default alerts on Android can be dismissed by tapping outside of the alert box. This event can be handled by providing an optional options parameter, with an onDismiss callback property { onDismiss: () => {} }.

Alternatively, the dismissing behavior can be disabled altogether by providing an optional options parameter with the cancelable property set to false i.e. { cancelable: false }

Example usage:

// Works on both Android and iOS
Alert.alert(
'Alert Title',
'My Alert Msg',
[
{
text: 'Ask me later',
onPress: () => console.log('Ask me later pressed')
},
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{ text: 'OK', onPress: () => console.log('OK Pressed') }
],
{ cancelable: false }
);

Reference

Methods

alert()

static alert(title, message?, buttons?, options? type?)
Edit this page
Last updated on
- + diff --git a/docs/0.61/alert/index.html b/docs/0.61/alert/index.html index 42fef4ab1cf..f1b21ed0806 100644 --- a/docs/0.61/alert/index.html +++ b/docs/0.61/alert/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

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 Android and iOS and can show static alerts. To show an alert that prompts the user to enter some information, see AlertIOS; entering text in an alert is common on iOS only.

Example

iOSAndroid

iOS

On iOS you can specify any number of buttons. Each button can optionally specify a style, which is one of 'default', 'cancel' or 'destructive'.

Android

On Android at most three buttons can be specified. Android has a concept of a neutral, negative and a positive button:

  • If you specify one button, it will be the 'positive' one (such as 'OK')
  • Two buttons mean 'negative', 'positive' (such as 'Cancel', 'OK')
  • Three buttons mean 'neutral', 'negative', 'positive' (such as 'Later', 'Cancel', 'OK')

By default alerts on Android can be dismissed by tapping outside of the alert box. This event can be handled by providing an optional options parameter, with an onDismiss callback property { onDismiss: () => {} }.

Alternatively, the dismissing behavior can be disabled altogether by providing an optional options parameter with the cancelable property set to false i.e. { cancelable: false }

Example usage:

// Works on both Android and iOS
Alert.alert(
'Alert Title',
'My Alert Msg',
[
{
text: 'Ask me later',
onPress: () => console.log('Ask me later pressed')
},
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{ text: 'OK', onPress: () => console.log('OK Pressed') }
],
{ cancelable: false }
);

Reference

Methods

alert()

static alert(title, message?, buttons?, options? type?)
Edit this page
Last updated on
- + diff --git a/docs/0.61/alertios.html b/docs/0.61/alertios.html index 1d4548c1869..eac18ae4ccd 100644 --- a/docs/0.61/alertios.html +++ b/docs/0.61/alertios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 AlertIOS

Deprecated. Use Alert instead.

AlertIOS provides functionality to create an iOS alert dialog with a message or create a prompt for user input.

Creating an iOS alert:

AlertIOS.alert(
'Sync Complete',
'All your data are belong to us.'
);

Creating an iOS prompt:

AlertIOS.prompt('Enter a value', null, (text) =>
console.log('You entered ' + text)
);

We recommend using the Alert.alert method for cross-platform support if you don't need to create iOS-only prompts.

Reference

Methods

alert()

static alert(title: string, [message]: string, [callbackOrButtons]: ?(() => void), ButtonsArray, [type]: AlertType): [object Object]

Create and display a popup alert.

Parameters:

NameTypeRequiredDescription
titlestringYesThe dialog's title. Passing null or '' will hide the title.
messagestringNoAn optional message that appears below the dialog's title.
callbackOrButtons?(() => void),ButtonsArrayNoThis optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called when the user taps 'OK'. If passed an array of button configurations, each button should include a text key, as well as optional onPress and style keys. style should be one of 'default', 'cancel' or 'destructive'.
typeAlertTypeNoDeprecated, do not use.

Example with custom buttons:

AlertIOS.alert(
'Update available',
'Keep your app up to date to enjoy the latest features',
[
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{
text: 'Install',
onPress: () => console.log('Install Pressed')
}
]
);

prompt()

static prompt(title: string, [message]: string, [callbackOrButtons]: ?((text: string) => void), ButtonsArray, [type]: AlertType, [defaultValue]: string, [keyboardType]: string): [object Object]

Create and display a prompt to enter some text.

Parameters:

NameTypeRequiredDescription
titlestringYesThe dialog's title.
messagestringNoAn optional message that appears above the text input.
callbackOrButtons?((text: string) => void),ButtonsArrayNoThis optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called with the prompt's value when the user taps 'OK'. If passed an array of button configurations, each button should include a text key, as well as optional onPress and style keys (see example). style should be one of 'default', 'cancel' or 'destructive'.
typeAlertTypeNoThis configures the text input. One of 'plain-text', 'secure-text' or 'login-password'.
defaultValuestringNoThe default text in text input.
keyboardTypestringNoThe keyboard type of first text field(if exists). One of 'default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter' or 'web-search'.

Example with custom buttons:

AlertIOS.prompt(
'Enter password',
'Enter your password to claim your $1.5B in lottery winnings',
[
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{
text: 'OK',
onPress: (password) =>
console.log('OK Pressed, password: ' + password)
}
],
'secure-text'
);

,

Example with the default button and a custom callback:

AlertIOS.prompt(
'Update username',
null,
(text) => console.log('Your username is ' + text),
null,
'default'
);

Type Definitions

AlertType

An Alert button type

Type
\$Enum

Constants:

ValueDescription
defaultDefault alert with no inputs
plain-textPlain text input alert
secure-textSecure text input alert
login-passwordLogin and password alert

AlertButtonStyle

An Alert button style

Type
\$Enum

Constants:

ValueDescription
defaultDefault button style
cancelCancel button style
destructiveDestructive button style

ButtonsArray

Array or buttons

Type
Array

Properties:

NameTypeDescription
[text]stringButton label
[onPress]functionCallback function when button pressed
[style]AlertButtonStyleButton style

Constants:

ValueDescription
textButton label
onPressCallback function when button pressed
styleButton style
Edit this page
Last updated on
- + diff --git a/docs/0.61/alertios/index.html b/docs/0.61/alertios/index.html index 1d4548c1869..eac18ae4ccd 100644 --- a/docs/0.61/alertios/index.html +++ b/docs/0.61/alertios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 AlertIOS

Deprecated. Use Alert instead.

AlertIOS provides functionality to create an iOS alert dialog with a message or create a prompt for user input.

Creating an iOS alert:

AlertIOS.alert(
'Sync Complete',
'All your data are belong to us.'
);

Creating an iOS prompt:

AlertIOS.prompt('Enter a value', null, (text) =>
console.log('You entered ' + text)
);

We recommend using the Alert.alert method for cross-platform support if you don't need to create iOS-only prompts.

Reference

Methods

alert()

static alert(title: string, [message]: string, [callbackOrButtons]: ?(() => void), ButtonsArray, [type]: AlertType): [object Object]

Create and display a popup alert.

Parameters:

NameTypeRequiredDescription
titlestringYesThe dialog's title. Passing null or '' will hide the title.
messagestringNoAn optional message that appears below the dialog's title.
callbackOrButtons?(() => void),ButtonsArrayNoThis optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called when the user taps 'OK'. If passed an array of button configurations, each button should include a text key, as well as optional onPress and style keys. style should be one of 'default', 'cancel' or 'destructive'.
typeAlertTypeNoDeprecated, do not use.

Example with custom buttons:

AlertIOS.alert(
'Update available',
'Keep your app up to date to enjoy the latest features',
[
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{
text: 'Install',
onPress: () => console.log('Install Pressed')
}
]
);

prompt()

static prompt(title: string, [message]: string, [callbackOrButtons]: ?((text: string) => void), ButtonsArray, [type]: AlertType, [defaultValue]: string, [keyboardType]: string): [object Object]

Create and display a prompt to enter some text.

Parameters:

NameTypeRequiredDescription
titlestringYesThe dialog's title.
messagestringNoAn optional message that appears above the text input.
callbackOrButtons?((text: string) => void),ButtonsArrayNoThis optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called with the prompt's value when the user taps 'OK'. If passed an array of button configurations, each button should include a text key, as well as optional onPress and style keys (see example). style should be one of 'default', 'cancel' or 'destructive'.
typeAlertTypeNoThis configures the text input. One of 'plain-text', 'secure-text' or 'login-password'.
defaultValuestringNoThe default text in text input.
keyboardTypestringNoThe keyboard type of first text field(if exists). One of 'default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter' or 'web-search'.

Example with custom buttons:

AlertIOS.prompt(
'Enter password',
'Enter your password to claim your $1.5B in lottery winnings',
[
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{
text: 'OK',
onPress: (password) =>
console.log('OK Pressed, password: ' + password)
}
],
'secure-text'
);

,

Example with the default button and a custom callback:

AlertIOS.prompt(
'Update username',
null,
(text) => console.log('Your username is ' + text),
null,
'default'
);

Type Definitions

AlertType

An Alert button type

Type
\$Enum

Constants:

ValueDescription
defaultDefault alert with no inputs
plain-textPlain text input alert
secure-textSecure text input alert
login-passwordLogin and password alert

AlertButtonStyle

An Alert button style

Type
\$Enum

Constants:

ValueDescription
defaultDefault button style
cancelCancel button style
destructiveDestructive button style

ButtonsArray

Array or buttons

Type
Array

Properties:

NameTypeDescription
[text]stringButton label
[onPress]functionCallback function when button pressed
[style]AlertButtonStyleButton style

Constants:

ValueDescription
textButton label
onPressCallback function when button pressed
styleButton style
Edit this page
Last updated on
- + diff --git a/docs/0.61/animated.html b/docs/0.61/animated.html index ff11b6aeb47..cc9de334870 100644 --- a/docs/0.61/animated.html +++ b/docs/0.61/animated.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Animated

The Animated library is designed to make animations fluid, powerful, and painless to build and maintain. Animated focuses on declarative relationships between inputs and outputs, with configurable transforms in between, and start/stop methods to control time-based animation execution.

The most basic workflow for creating an animation is to create an Animated.Value, hook it up to one or more style attributes of an animated component, and then drive updates via animations using Animated.timing():

Animated.timing(
// Animate value over time
this.state.fadeAnim, // The value to drive
{
toValue: 1 // Animate to final value of 1
}
).start(); // Start the animation

Refer to the Animations guide to see additional examples of Animated in action.

Overview

There are two value types you can use with Animated:

Animated.Value can bind to style properties or other props, and can be interpolated as well. A single Animated.Value can drive any number of properties.

Configuring animations

Animated provides three types of animation types. Each animation type provides a particular animation curve that controls how your values animate from their initial value to the final value:

In most cases, you will be using timing(). By default, it uses a symmetric easeInOut curve that conveys the gradual acceleration of an object to full speed and concludes by gradually decelerating to a stop.

Working with animations

Animations are started by calling start() on your animation. start() takes a completion callback that will be called when the animation is done. If the animation finished running normally, the completion callback will be invoked with {finished: true}. If the animation is done because stop() was called on it before it could finish (e.g. because it was interrupted by a gesture or another animation), then it will receive {finished: false}.

Using the native driver

By using the native driver, we send everything about the animation to native before starting the animation, allowing native code to perform the animation on the UI thread without having to go through the bridge on every frame. Once the animation has started, the JS thread can be blocked without affecting the animation.

You can use the native driver by specifying useNativeDriver: true in your animation configuration. See the Animations guide to learn more.

Animatable components

Only animatable components can be animated. These unique components do the magic of binding the animated values to the properties, and do targeted native updates to avoid the cost of the react render and reconciliation process on every frame. They also handle cleanup on unmount so they are safe by default.

Animated exports the following animatable components using the above wrapper:

  • Animated.Image
  • Animated.ScrollView
  • Animated.Text
  • Animated.View
  • Animated.FlatList
  • Animated.SectionList

Composing animations

Animations can also be combined in complex ways using composition functions:

Animations can also be chained together by setting the toValue of one animation to be another Animated.Value. See Tracking dynamic values in the Animations guide.

By default, if one animation is stopped or interrupted, then all other animations in the group are also stopped.

Combining animated values

You can combine two animated values via addition, subtraction, multiplication, division, or modulo to make a new animated value:

Interpolation

The interpolate() function allows input ranges to map to different output ranges. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value. It uses linear interpolation by default but also supports easing functions.

Read more about interpolation in the Animation guide.

Handling gestures and other events

Gestures, like panning or scrolling, and other events can map directly to animated values using Animated.event(). This is done with a structured map syntax so that values can be extracted from complex event objects. The first level is an array to allow mapping across multiple args, and that array contains nested objects.

For example, when working with horizontal scrolling gestures, you would do the following in order to map event.nativeEvent.contentOffset.x to scrollX (an Animated.Value):

onScroll={Animated.event(
// scrollX = e.nativeEvent.contentOffset.x
[{ nativeEvent: {
contentOffset: {
x: scrollX
}
}
}]
)}

Reference

Methods

When the given value is a ValueXY instead of a Value, each config option may be a vector of the form {x: ..., y: ...} instead of a scalar.

decay()

static decay(value, config)

Animates a value from an initial velocity to zero based on a decay coefficient.

Config is an object that may have the following options:

  • velocity: Initial velocity. Required.
  • deceleration: Rate of decay. Default 0.997.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

timing()

static timing(value, config)

Animates a value along a timed easing curve. The Easing module has tons of predefined curves, or you can use your own function.

Config is an object that may have the following options:

  • duration: Length of animation (milliseconds). Default 500.
  • easing: Easing function to define curve. Default is Easing.inOut(Easing.ease).
  • delay: Start the animation after delay (milliseconds). Default 0.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

spring()

static spring(value, config)

Animates a value according to an analytical spring model based on damped harmonic oscillation. Tracks velocity state to create fluid motions as the toValue updates, and can be chained together.

Config is an object that may have the following options.

Note that you can only define one of bounciness/speed, tension/friction, or stiffness/damping/mass, but not more than one:

The friction/tension or bounciness/speed options match the spring model in Facebook Pop, Rebound, and Origami.

  • friction: Controls "bounciness"/overshoot. Default 7.
  • tension: Controls speed. Default 40.
  • speed: Controls speed of the animation. Default 12.
  • bounciness: Controls bounciness. Default 8.

Specifying stiffness/damping/mass as parameters makes Animated.spring use an analytical spring model based on the motion equations of a damped harmonic oscillator. This behavior is slightly more precise and faithful to the physics behind spring dynamics, and closely mimics the implementation in iOS's CASpringAnimation.

  • stiffness: The spring stiffness coefficient. Default 100.
  • damping: Defines how the spring’s motion should be damped due to the forces of friction. Default 10.
  • mass: The mass of the object attached to the end of the spring. Default 1.

Other configuration options are as follows:

  • velocity: The initial velocity of the object attached to the spring. Default 0 (object is at rest).
  • overshootClamping: Boolean indicating whether the spring should be clamped and not bounce. Default false.
  • restDisplacementThreshold: The threshold of displacement from rest below which the spring should be considered at rest. Default 0.001.
  • restSpeedThreshold: The speed at which the spring should be considered at rest in pixels per second. Default 0.001.
  • delay: Start the animation after delay (milliseconds). Default 0.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

add()

static add(a, b)

Creates a new Animated value composed from two Animated values added together.

subtract()

static subtract(a, b)

Creates a new Animated value composed by subtracting the second Animated value from the first Animated value.

divide()

static divide(a, b)

Creates a new Animated value composed by dividing the first Animated value by the second Animated value.

multiply()

static multiply(a, b)

Creates a new Animated value composed from two Animated values multiplied together.

modulo()

static modulo(a, modulus)

Creates a new Animated value that is the (non-negative) modulo of the provided Animated value

diffClamp()

static diffClamp(a, min, max)

Create a new Animated value that is limited between 2 values. It uses the difference between the last value so even if the value is far from the bounds it will start changing when the value starts getting closer again. (value = clamp(value + diff, min, max)).

This is useful with scroll events, for example, to show the navbar when scrolling up and to hide it when scrolling down.

delay()

static delay(time)

Starts an animation after the given delay.

sequence()

static sequence(animations)

Starts an array of animations in order, waiting for each to complete before starting the next. If the current running animation is stopped, no following animations will be started.

parallel()

static parallel(animations, config?)

Starts an array of animations all at the same time. By default, if one of the animations is stopped, they will all be stopped. You can override this with the stopTogether flag.

stagger()

static stagger(time, animations)

Array of animations may run in parallel (overlap), but are started in sequence with successive delays. Nice for doing trailing effects.

loop()

static loop(animation, config?)

Loops a given animation continuously, so that each time it reaches the end, it resets and begins again from the start. Will loop without blocking the UI thread if the child animation is set to useNativeDriver: true. In addition, loops can prevent VirtualizedList-based components from rendering more rows while the animation is running. You can pass isInteraction: false in the child animation config to fix this.

Config is an object that may have the following options:

  • iterations: Number of times the animation should loop. Default -1 (infinite).

event()

static event(argMapping, config?)

Takes an array of mappings and extracts values from each arg accordingly, then calls setValue on the mapped outputs. e.g.

onScroll={Animated.event(
[{nativeEvent: {contentOffset: {x: this._scrollX}}}],
{listener: (event) => console.log(event)}, // Optional async listener
)}
...
onPanResponderMove: Animated.event([
null, // raw event arg ignored
{dx: this._panX}], // gestureState arg
{listener: (event, gestureState) => console.log(event, gestureState)}, // Optional async listener
),

Config is an object that may have the following options:

  • listener: Optional async listener.
  • useNativeDriver: Uses the native driver when true. Default false.

forkEvent()

static forkEvent(event, listener)

Advanced imperative API for snooping on animated events that are passed in through props. It permits to add a new javascript listener to an existing AnimatedEvent. If animatedEvent is a javascript listener, it will merge the 2 listeners into a single one, and if animatedEvent is null/undefined, it will assign the javascript listener directly. Use values directly where possible.

unforkEvent()

static unforkEvent(event, listener)

Properties

Value

Standard value class for driving animations. Typically initialized with new Animated.Value(0);

ValueXY

2D value class for driving 2D animations, such as pan gestures.

Interpolation

Exported to use the Interpolation type in flow.

Node

Exported for ease of type checking. All animated values derive from this class.

createAnimatedComponent

Make any React component Animatable. Used to create Animated.View, etc.

attachNativeEvent

Imperative API to attach an animated value to an event on a view. Prefer using Animated.event with useNativeDrive: true if possible.

Edit this page
Last updated on
- + diff --git a/docs/0.61/animated/index.html b/docs/0.61/animated/index.html index ff11b6aeb47..cc9de334870 100644 --- a/docs/0.61/animated/index.html +++ b/docs/0.61/animated/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Animated

The Animated library is designed to make animations fluid, powerful, and painless to build and maintain. Animated focuses on declarative relationships between inputs and outputs, with configurable transforms in between, and start/stop methods to control time-based animation execution.

The most basic workflow for creating an animation is to create an Animated.Value, hook it up to one or more style attributes of an animated component, and then drive updates via animations using Animated.timing():

Animated.timing(
// Animate value over time
this.state.fadeAnim, // The value to drive
{
toValue: 1 // Animate to final value of 1
}
).start(); // Start the animation

Refer to the Animations guide to see additional examples of Animated in action.

Overview

There are two value types you can use with Animated:

Animated.Value can bind to style properties or other props, and can be interpolated as well. A single Animated.Value can drive any number of properties.

Configuring animations

Animated provides three types of animation types. Each animation type provides a particular animation curve that controls how your values animate from their initial value to the final value:

In most cases, you will be using timing(). By default, it uses a symmetric easeInOut curve that conveys the gradual acceleration of an object to full speed and concludes by gradually decelerating to a stop.

Working with animations

Animations are started by calling start() on your animation. start() takes a completion callback that will be called when the animation is done. If the animation finished running normally, the completion callback will be invoked with {finished: true}. If the animation is done because stop() was called on it before it could finish (e.g. because it was interrupted by a gesture or another animation), then it will receive {finished: false}.

Using the native driver

By using the native driver, we send everything about the animation to native before starting the animation, allowing native code to perform the animation on the UI thread without having to go through the bridge on every frame. Once the animation has started, the JS thread can be blocked without affecting the animation.

You can use the native driver by specifying useNativeDriver: true in your animation configuration. See the Animations guide to learn more.

Animatable components

Only animatable components can be animated. These unique components do the magic of binding the animated values to the properties, and do targeted native updates to avoid the cost of the react render and reconciliation process on every frame. They also handle cleanup on unmount so they are safe by default.

Animated exports the following animatable components using the above wrapper:

  • Animated.Image
  • Animated.ScrollView
  • Animated.Text
  • Animated.View
  • Animated.FlatList
  • Animated.SectionList

Composing animations

Animations can also be combined in complex ways using composition functions:

Animations can also be chained together by setting the toValue of one animation to be another Animated.Value. See Tracking dynamic values in the Animations guide.

By default, if one animation is stopped or interrupted, then all other animations in the group are also stopped.

Combining animated values

You can combine two animated values via addition, subtraction, multiplication, division, or modulo to make a new animated value:

Interpolation

The interpolate() function allows input ranges to map to different output ranges. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value. It uses linear interpolation by default but also supports easing functions.

Read more about interpolation in the Animation guide.

Handling gestures and other events

Gestures, like panning or scrolling, and other events can map directly to animated values using Animated.event(). This is done with a structured map syntax so that values can be extracted from complex event objects. The first level is an array to allow mapping across multiple args, and that array contains nested objects.

For example, when working with horizontal scrolling gestures, you would do the following in order to map event.nativeEvent.contentOffset.x to scrollX (an Animated.Value):

onScroll={Animated.event(
// scrollX = e.nativeEvent.contentOffset.x
[{ nativeEvent: {
contentOffset: {
x: scrollX
}
}
}]
)}

Reference

Methods

When the given value is a ValueXY instead of a Value, each config option may be a vector of the form {x: ..., y: ...} instead of a scalar.

decay()

static decay(value, config)

Animates a value from an initial velocity to zero based on a decay coefficient.

Config is an object that may have the following options:

  • velocity: Initial velocity. Required.
  • deceleration: Rate of decay. Default 0.997.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

timing()

static timing(value, config)

Animates a value along a timed easing curve. The Easing module has tons of predefined curves, or you can use your own function.

Config is an object that may have the following options:

  • duration: Length of animation (milliseconds). Default 500.
  • easing: Easing function to define curve. Default is Easing.inOut(Easing.ease).
  • delay: Start the animation after delay (milliseconds). Default 0.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

spring()

static spring(value, config)

Animates a value according to an analytical spring model based on damped harmonic oscillation. Tracks velocity state to create fluid motions as the toValue updates, and can be chained together.

Config is an object that may have the following options.

Note that you can only define one of bounciness/speed, tension/friction, or stiffness/damping/mass, but not more than one:

The friction/tension or bounciness/speed options match the spring model in Facebook Pop, Rebound, and Origami.

  • friction: Controls "bounciness"/overshoot. Default 7.
  • tension: Controls speed. Default 40.
  • speed: Controls speed of the animation. Default 12.
  • bounciness: Controls bounciness. Default 8.

Specifying stiffness/damping/mass as parameters makes Animated.spring use an analytical spring model based on the motion equations of a damped harmonic oscillator. This behavior is slightly more precise and faithful to the physics behind spring dynamics, and closely mimics the implementation in iOS's CASpringAnimation.

  • stiffness: The spring stiffness coefficient. Default 100.
  • damping: Defines how the spring’s motion should be damped due to the forces of friction. Default 10.
  • mass: The mass of the object attached to the end of the spring. Default 1.

Other configuration options are as follows:

  • velocity: The initial velocity of the object attached to the spring. Default 0 (object is at rest).
  • overshootClamping: Boolean indicating whether the spring should be clamped and not bounce. Default false.
  • restDisplacementThreshold: The threshold of displacement from rest below which the spring should be considered at rest. Default 0.001.
  • restSpeedThreshold: The speed at which the spring should be considered at rest in pixels per second. Default 0.001.
  • delay: Start the animation after delay (milliseconds). Default 0.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

add()

static add(a, b)

Creates a new Animated value composed from two Animated values added together.

subtract()

static subtract(a, b)

Creates a new Animated value composed by subtracting the second Animated value from the first Animated value.

divide()

static divide(a, b)

Creates a new Animated value composed by dividing the first Animated value by the second Animated value.

multiply()

static multiply(a, b)

Creates a new Animated value composed from two Animated values multiplied together.

modulo()

static modulo(a, modulus)

Creates a new Animated value that is the (non-negative) modulo of the provided Animated value

diffClamp()

static diffClamp(a, min, max)

Create a new Animated value that is limited between 2 values. It uses the difference between the last value so even if the value is far from the bounds it will start changing when the value starts getting closer again. (value = clamp(value + diff, min, max)).

This is useful with scroll events, for example, to show the navbar when scrolling up and to hide it when scrolling down.

delay()

static delay(time)

Starts an animation after the given delay.

sequence()

static sequence(animations)

Starts an array of animations in order, waiting for each to complete before starting the next. If the current running animation is stopped, no following animations will be started.

parallel()

static parallel(animations, config?)

Starts an array of animations all at the same time. By default, if one of the animations is stopped, they will all be stopped. You can override this with the stopTogether flag.

stagger()

static stagger(time, animations)

Array of animations may run in parallel (overlap), but are started in sequence with successive delays. Nice for doing trailing effects.

loop()

static loop(animation, config?)

Loops a given animation continuously, so that each time it reaches the end, it resets and begins again from the start. Will loop without blocking the UI thread if the child animation is set to useNativeDriver: true. In addition, loops can prevent VirtualizedList-based components from rendering more rows while the animation is running. You can pass isInteraction: false in the child animation config to fix this.

Config is an object that may have the following options:

  • iterations: Number of times the animation should loop. Default -1 (infinite).

event()

static event(argMapping, config?)

Takes an array of mappings and extracts values from each arg accordingly, then calls setValue on the mapped outputs. e.g.

onScroll={Animated.event(
[{nativeEvent: {contentOffset: {x: this._scrollX}}}],
{listener: (event) => console.log(event)}, // Optional async listener
)}
...
onPanResponderMove: Animated.event([
null, // raw event arg ignored
{dx: this._panX}], // gestureState arg
{listener: (event, gestureState) => console.log(event, gestureState)}, // Optional async listener
),

Config is an object that may have the following options:

  • listener: Optional async listener.
  • useNativeDriver: Uses the native driver when true. Default false.

forkEvent()

static forkEvent(event, listener)

Advanced imperative API for snooping on animated events that are passed in through props. It permits to add a new javascript listener to an existing AnimatedEvent. If animatedEvent is a javascript listener, it will merge the 2 listeners into a single one, and if animatedEvent is null/undefined, it will assign the javascript listener directly. Use values directly where possible.

unforkEvent()

static unforkEvent(event, listener)

Properties

Value

Standard value class for driving animations. Typically initialized with new Animated.Value(0);

ValueXY

2D value class for driving 2D animations, such as pan gestures.

Interpolation

Exported to use the Interpolation type in flow.

Node

Exported for ease of type checking. All animated values derive from this class.

createAnimatedComponent

Make any React component Animatable. Used to create Animated.View, etc.

attachNativeEvent

Imperative API to attach an animated value to an event on a view. Prefer using Animated.event with useNativeDrive: true if possible.

Edit this page
Last updated on
- + diff --git a/docs/0.61/animatedvalue.html b/docs/0.61/animatedvalue.html index 21d364eb419..2c672eee45f 100644 --- a/docs/0.61/animatedvalue.html +++ b/docs/0.61/animatedvalue.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

AnimatedValue

Standard value for driving animations. One Animated.Value can drive multiple properties in a synchronized fashion, but can only be driven by one mechanism at a time. Using a new mechanism (e.g. starting a new animation, or calling setValue) will stop any previous ones.

Typically initialized with new Animated.Value(0);

See also Animated.

Methods

Reference

Methods

setValue()

setValue(value);

Directly set the value. This will stop any animations running on the value and update all the bound properties.

Parameters:

NameTypeRequiredDescription
valuenumberYesValue

setOffset()

setOffset(offset);

Sets an offset that is applied on top of whatever value is set, whether via setValue, an animation, or Animated.event. Useful for compensating things like the start of a pan gesture.

Parameters:

NameTypeRequiredDescription
offsetnumberYesOffset value

flattenOffset()

flattenOffset();

Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.

extractOffset()

extractOffset();

Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.

addListener()

addListener(callback);

Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.

Returns a string that serves as an identifier for the listener.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesThe callback function which will receive an object with a value key set to the new value.

removeListener()

removeListener(id);

Unregister a listener. The id param shall match the identifier previously returned by addListener().

Parameters:

NameTypeRequiredDescription
idstringYesId for the listener being removed.

removeAllListeners()

removeAllListeners();

Remove all registered listeners.

stopAnimation()

stopAnimation([callback]);

Stops any running animation or tracking. callback is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the final value.

resetAnimation()

resetAnimation([callback]);

Stops any animation and resets the value to its original.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the original value.

interpolate()

interpolate(config);

Interpolates the value before updating the property, e.g. mapping 0-1 to 0-10.

See AnimatedInterpolation.js

Parameters:

NameTypeRequiredDescription
configobjectYesSee below.

The config object is composed of the following keys:

  • inputRange: an array of numbers
  • outputRange: an array of numbers or strings
  • easing (optional): a function that returns a number, given an input number
  • extrapolate (optional): a string such as 'extend', 'identity', or 'clamp'
  • extrapolateLeft (optional): a string such as 'extend', 'identity', or 'clamp'
  • extrapolateRight (optional): a string such as 'extend', 'identity', or 'clamp'

animate()

animate(animation, callback);

Typically only used internally, but could be used by a custom Animation class.

Parameters:

NameTypeRequiredDescription
animationAnimationYesSee Animation.js.
callbackfunctionYesCallback function.

stopTracking()

stopTracking();

Typically only used internally.

track()

track(tracking);

Typically only used internally.

Parameters:

NameTypeRequiredDescription
trackingAnimatedNodeYesSee AnimatedNode.js
Edit this page
Last updated on
- + diff --git a/docs/0.61/animatedvalue/index.html b/docs/0.61/animatedvalue/index.html index 21d364eb419..2c672eee45f 100644 --- a/docs/0.61/animatedvalue/index.html +++ b/docs/0.61/animatedvalue/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

AnimatedValue

Standard value for driving animations. One Animated.Value can drive multiple properties in a synchronized fashion, but can only be driven by one mechanism at a time. Using a new mechanism (e.g. starting a new animation, or calling setValue) will stop any previous ones.

Typically initialized with new Animated.Value(0);

See also Animated.

Methods

Reference

Methods

setValue()

setValue(value);

Directly set the value. This will stop any animations running on the value and update all the bound properties.

Parameters:

NameTypeRequiredDescription
valuenumberYesValue

setOffset()

setOffset(offset);

Sets an offset that is applied on top of whatever value is set, whether via setValue, an animation, or Animated.event. Useful for compensating things like the start of a pan gesture.

Parameters:

NameTypeRequiredDescription
offsetnumberYesOffset value

flattenOffset()

flattenOffset();

Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.

extractOffset()

extractOffset();

Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.

addListener()

addListener(callback);

Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.

Returns a string that serves as an identifier for the listener.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesThe callback function which will receive an object with a value key set to the new value.

removeListener()

removeListener(id);

Unregister a listener. The id param shall match the identifier previously returned by addListener().

Parameters:

NameTypeRequiredDescription
idstringYesId for the listener being removed.

removeAllListeners()

removeAllListeners();

Remove all registered listeners.

stopAnimation()

stopAnimation([callback]);

Stops any running animation or tracking. callback is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the final value.

resetAnimation()

resetAnimation([callback]);

Stops any animation and resets the value to its original.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the original value.

interpolate()

interpolate(config);

Interpolates the value before updating the property, e.g. mapping 0-1 to 0-10.

See AnimatedInterpolation.js

Parameters:

NameTypeRequiredDescription
configobjectYesSee below.

The config object is composed of the following keys:

  • inputRange: an array of numbers
  • outputRange: an array of numbers or strings
  • easing (optional): a function that returns a number, given an input number
  • extrapolate (optional): a string such as 'extend', 'identity', or 'clamp'
  • extrapolateLeft (optional): a string such as 'extend', 'identity', or 'clamp'
  • extrapolateRight (optional): a string such as 'extend', 'identity', or 'clamp'

animate()

animate(animation, callback);

Typically only used internally, but could be used by a custom Animation class.

Parameters:

NameTypeRequiredDescription
animationAnimationYesSee Animation.js.
callbackfunctionYesCallback function.

stopTracking()

stopTracking();

Typically only used internally.

track()

track(tracking);

Typically only used internally.

Parameters:

NameTypeRequiredDescription
trackingAnimatedNodeYesSee AnimatedNode.js
Edit this page
Last updated on
- + diff --git a/docs/0.61/animatedvaluexy.html b/docs/0.61/animatedvaluexy.html index 3bf2c185391..75360d4dc4b 100644 --- a/docs/0.61/animatedvaluexy.html +++ b/docs/0.61/animatedvaluexy.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

AnimatedValueXY

2D Value for driving 2D animations, such as pan gestures. Almost identical API to normal Animated.Value, but multiplexed. Contains two regular Animated.Values under the hood.

See also Animated.

Example

class DraggableView extends React.Component {
constructor(props) {
super(props);
this.state = {
pan: new Animated.ValueXY() // inits to zero
};
this.state.panResponder = PanResponder.create({
onStartShouldSetPanResponder: () => true,
onPanResponderMove: Animated.event([
null,
{
dx: this.state.pan.x, // x,y are Animated.Value
dy: this.state.pan.y
}
]),
onPanResponderRelease: () => {
Animated.spring(
this.state.pan, // Auto-multiplexed
{ toValue: { x: 0, y: 0 } } // Back to zero
).start();
}
});
}
render() {
return (
<Animated.View
{...this.state.panResponder.panHandlers}
style={this.state.pan.getLayout()}>
{this.props.children}
</Animated.View>
);
}
}

Methods

Reference

Methods

setValue()

setValue(value);

Directly set the value. This will stop any animations running on the value and update all the bound properties.

Parameters:

NameTypeRequiredDescription
valuenumberYes

setOffset()

setOffset(offset);

Sets an offset that is applied on top of whatever value is set, whether via setValue, an animation, or Animated.event. Useful for compensating things like the start of a pan gesture.

Parameters:

NameTypeRequiredDescription
offsetnumberYes

flattenOffset()

flattenOffset();

Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.

extractOffset()

extractOffset();

Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.

addListener()

addListener(callback);

Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.

Returns a string that serves as an identifier for the listener.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesThe callback function which will receive an object with a value key set to the new value.

removeListener()

removeListener(id);

Unregister a listener. The id param shall match the identifier previously returned by addListener().

Parameters:

NameTypeRequiredDescription
idstringYesId for the listener being removed.

removeAllListeners()

removeAllListeners();

Remove all registered listeners.

stopAnimation()

stopAnimation([callback]);

Stops any running animation or tracking. callback is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the final value.

resetAnimation()

resetAnimation([callback]);

Stops any animation and resets the value to its original.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the original value.

getLayout()

getLayout();

Converts {x, y} into {left, top} for use in style, e.g.

style={this.state.anim.getLayout()}

getTranslateTransform()

getTranslateTransform();

Converts {x, y} into a useable translation transform, e.g.

style={{
transform: this.state.anim.getTranslateTransform()
}}
Edit this page
Last updated on
- + diff --git a/docs/0.61/animatedvaluexy/index.html b/docs/0.61/animatedvaluexy/index.html index 3bf2c185391..75360d4dc4b 100644 --- a/docs/0.61/animatedvaluexy/index.html +++ b/docs/0.61/animatedvaluexy/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

AnimatedValueXY

2D Value for driving 2D animations, such as pan gestures. Almost identical API to normal Animated.Value, but multiplexed. Contains two regular Animated.Values under the hood.

See also Animated.

Example

class DraggableView extends React.Component {
constructor(props) {
super(props);
this.state = {
pan: new Animated.ValueXY() // inits to zero
};
this.state.panResponder = PanResponder.create({
onStartShouldSetPanResponder: () => true,
onPanResponderMove: Animated.event([
null,
{
dx: this.state.pan.x, // x,y are Animated.Value
dy: this.state.pan.y
}
]),
onPanResponderRelease: () => {
Animated.spring(
this.state.pan, // Auto-multiplexed
{ toValue: { x: 0, y: 0 } } // Back to zero
).start();
}
});
}
render() {
return (
<Animated.View
{...this.state.panResponder.panHandlers}
style={this.state.pan.getLayout()}>
{this.props.children}
</Animated.View>
);
}
}

Methods

Reference

Methods

setValue()

setValue(value);

Directly set the value. This will stop any animations running on the value and update all the bound properties.

Parameters:

NameTypeRequiredDescription
valuenumberYes

setOffset()

setOffset(offset);

Sets an offset that is applied on top of whatever value is set, whether via setValue, an animation, or Animated.event. Useful for compensating things like the start of a pan gesture.

Parameters:

NameTypeRequiredDescription
offsetnumberYes

flattenOffset()

flattenOffset();

Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.

extractOffset()

extractOffset();

Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.

addListener()

addListener(callback);

Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.

Returns a string that serves as an identifier for the listener.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesThe callback function which will receive an object with a value key set to the new value.

removeListener()

removeListener(id);

Unregister a listener. The id param shall match the identifier previously returned by addListener().

Parameters:

NameTypeRequiredDescription
idstringYesId for the listener being removed.

removeAllListeners()

removeAllListeners();

Remove all registered listeners.

stopAnimation()

stopAnimation([callback]);

Stops any running animation or tracking. callback is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the final value.

resetAnimation()

resetAnimation([callback]);

Stops any animation and resets the value to its original.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the original value.

getLayout()

getLayout();

Converts {x, y} into {left, top} for use in style, e.g.

style={this.state.anim.getLayout()}

getTranslateTransform()

getTranslateTransform();

Converts {x, y} into a useable translation transform, e.g.

style={{
transform: this.state.anim.getTranslateTransform()
}}
Edit this page
Last updated on
- + diff --git a/docs/0.61/animations.html b/docs/0.61/animations.html index cea20473579..aad9b286236 100644 --- a/docs/0.61/animations.html +++ b/docs/0.61/animations.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Animated.spring(a, {
toValue: 2
}).start();

Interpolation

Each property can be run through an interpolation first. An interpolation maps input ranges to output ranges, typically using a linear interpolation but also supports easing functions. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value.

A mapping to convert a 0-1 range to a 0-100 range would be:

value.interpolate({
inputRange: [0, 1],
outputRange: [0, 100]
});

For example, you may want to think about your Animated.Value as going from 0 to 1, but animate the position from 150px to 0px and the opacity from 0 to 1. This can be done by modifying style from the example above like so:

style={{
opacity: this.state.fadeAnim, // Binds directly
transform: [{
translateY: this.state.fadeAnim.interpolate({
inputRange: [0, 1],
outputRange: [150, 0] // 0 : 150, 0.5 : 75, 1 : 0
}),
}],
}}

interpolate() supports multiple range segments as well, which is handy for defining dead zones and other handy tricks. For example, to get a negation relationship at -300 that goes to 0 at -100, then back up to 1 at 0, and then back down to zero at 100 followed by a dead-zone that remains at 0 for everything beyond that, you could do:

value.interpolate({
inputRange: [-300, -100, 0, 100, 101],
outputRange: [300, 0, 1, 0, 0]
});

Which would map like so:

Input | Output
------|-------
-400| 450
-300| 300
-200| 150
-100| 0
-50| 0.5
0| 1
50| 0.5
100| 0
101| 0
200| 0

interpolate() also supports mapping to strings, allowing you to animate colors as well as values with units. For example, if you wanted to animate a rotation you could do:

value.interpolate({
inputRange: [0, 360],
outputRange: ['0deg', '360deg']
});

interpolate() also supports arbitrary easing functions, many of which are already implemented in the Easing module. interpolate() also has configurable behavior for extrapolating the outputRange. You can set the extrapolation by setting the extrapolate, extrapolateLeft, or extrapolateRight options. The default value is extend but you can use clamp to prevent the output value from exceeding outputRange.

Tracking dynamic values

Animated values can also track other values. Set the toValue of an animation to another animated value instead of a plain number. For example, a "Chat Heads" animation like the one used by Messenger on Android could be implemented with a spring() pinned on another animated value, or with timing() and a duration of 0 for rigid tracking. They can also be composed with interpolations:

Animated.spring(follower, { toValue: leader }).start();
Animated.timing(opacity, {
toValue: pan.x.interpolate({
inputRange: [0, 300],
outputRange: [1, 0]
})
}).start();

The leader and follower animated values would be implemented using Animated.ValueXY(). ValueXY is a handy way to deal with 2D interactions, such as panning or dragging. It is a wrapper that contains two Animated.Value instances and some helper functions that call through to them, making ValueXY a drop-in replacement for Value in many cases. It allows us to track both x and y values in the example above.

Tracking gestures

Gestures, like panning or scrolling, and other events can map directly to animated values using Animated.event. This is done with a structured map syntax so that values can be extracted from complex event objects. The first level is an array to allow mapping across multiple args, and that array contains nested objects.

For example, when working with horizontal scrolling gestures, you would do the following in order to map event.nativeEvent.contentOffset.x to scrollX (an Animated.Value):

onScroll={Animated.event(
// scrollX = e.nativeEvent.contentOffset.x
[{ nativeEvent: {
contentOffset: {
x: scrollX
}
}
}]
)}

When using PanResponder, you could use the following code to extract the x and y positions from gestureState.dx and gestureState.dy. We use a null in the first position of the array, as we are only interested in the second argument passed to the PanResponder handler, which is the gestureState.

onPanResponderMove={Animated.event(
[null, // ignore the native event
// extract dx and dy from gestureState
// like 'pan.x = gestureState.dx, pan.y = gestureState.dy'
{dx: pan.x, dy: pan.y}
])}

Responding to the current animation value

You may notice that there is no clear way to read the current value while animating. This is because the value may only be known in the native runtime due to optimizations. If you need to run JavaScript in response to the current value, there are two approaches:

Animated is designed to be fully serializable so that animations can be run in a high performance way, independent of the normal JavaScript event loop. This does influence the API, so keep that in mind when it seems a little trickier to do something compared to a fully synchronous system. Check out Animated.Value.addListener as a way to work around some of these limitations, but use it sparingly since it might have performance implications in the future.

Using the native driver

The Animated API is designed to be serializable. By using the native driver, we send everything about the animation to native before starting the animation, allowing native code to perform the animation on the UI thread without having to go through the bridge on every frame. Once the animation has started, the JS thread can be blocked without affecting the animation.

To use the native driver for normal animations add useNativeDriver: true to the animation config when starting it.

Animated.timing(this.state.animatedValue, {
toValue: 1,
duration: 500,
useNativeDriver: true // <-- Add this
}).start();

Animated values are only compatible with one driver so if you use native driver when starting an animation on a value, make sure every animation on that value also uses the native driver.

The native driver also works with Animated.event. This is especially useful for animations that follow the scroll position as without the native driver, the animation will always run a frame behind the gesture due to the async nature of React Native.

<Animated.ScrollView // <-- Use the Animated ScrollView wrapper
scrollEventThrottle={1} // <-- Use 1 here to make sure no events are ever missed
onScroll={Animated.event(
[
{
nativeEvent: {
contentOffset: { y: this.state.animatedValue }
}
}
],
{ useNativeDriver: true } // <-- Add this
)}>
{content}
</Animated.ScrollView>

You can see the native driver in action by running the RNTester app, then loading the Native Animated Example. You can also take a look at the source code to learn how these examples were produced.

Caveats

Not everything you can do with Animated is currently supported by the native driver. The main limitation is that you can only animate non-layout properties: things like transform and opacity will work, but flexbox and position properties will not. When using Animated.event, it will only work with direct events and not bubbling events. This means it does not work with PanResponder but does work with things like ScrollView#onScroll.

When an animation is running, it can prevent VirtualizedList components from rendering more rows. If you need to run a long or looping animation while the user is scrolling through a list, you can use isInteraction: false in your animation's config to prevent this issue.

Bear in mind

While using transform styles such as rotateY, rotateX, and others ensure the transform style perspective is in place. At this time some animations may not render on Android without it. Example below.

<Animated.View
style={{
transform: [
{ scale: this.state.scale },
{ rotateY: this.state.rotateY },
{ perspective: 1000 } // without this line this Animation will not render on Android while working fine on iOS
]
}}
/>

Additional examples

The RNTester app has various examples of Animated in use:

LayoutAnimation API

LayoutAnimation allows you to globally configure create and update animations that will be used for all views in the next render/layout cycle. This is useful for doing flexbox layout updates without bothering to measure or calculate specific properties in order to animate them directly, and is especially useful when layout changes may affect ancestors, for example a "see more" expansion that also increases the size of the parent and pushes down the row below which would otherwise require explicit coordination between the components in order to animate them all in sync.

Note that although LayoutAnimation is very powerful and can be quite useful, it provides much less control than Animated and other animation libraries, so you may need to use another approach if you can't get LayoutAnimation to do what you want.

Note that in order to get this to work on Android you need to set the following flags via UIManager:

UIManager.setLayoutAnimationEnabledExperimental &&
UIManager.setLayoutAnimationEnabledExperimental(true);

This example uses a preset value, you can customize the animations as you need, see LayoutAnimation.js for more information.

Additional notes

requestAnimationFrame

requestAnimationFrame is a polyfill from the browser that you might be familiar with. It accepts a function as its only argument and calls that function before the next repaint. It is an essential building block for animations that underlies all of the JavaScript-based animation APIs. In general, you shouldn't need to call this yourself - the animation APIs will manage frame updates for you.

setNativeProps

As mentioned in the Direct Manipulation section, setNativeProps allows us to modify properties of native-backed components (components that are actually backed by native views, unlike composite components) directly, without having to setState and re-render the component hierarchy.

We could use this in the Rebound example to update the scale - this might be helpful if the component that we are updating is deeply nested and hasn't been optimized with shouldComponentUpdate.

If you find your animations with dropping frames (performing below 60 frames per second), look into using setNativeProps or shouldComponentUpdate to optimize them. Or you could run the animations on the UI thread rather than the JavaScript thread with the useNativeDriver 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.

Edit this page
Last updated on
- + diff --git a/docs/0.61/animations/index.html b/docs/0.61/animations/index.html index cea20473579..aad9b286236 100644 --- a/docs/0.61/animations/index.html +++ b/docs/0.61/animations/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Animated.spring(a, {
toValue: 2
}).start();

Interpolation

Each property can be run through an interpolation first. An interpolation maps input ranges to output ranges, typically using a linear interpolation but also supports easing functions. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value.

A mapping to convert a 0-1 range to a 0-100 range would be:

value.interpolate({
inputRange: [0, 1],
outputRange: [0, 100]
});

For example, you may want to think about your Animated.Value as going from 0 to 1, but animate the position from 150px to 0px and the opacity from 0 to 1. This can be done by modifying style from the example above like so:

style={{
opacity: this.state.fadeAnim, // Binds directly
transform: [{
translateY: this.state.fadeAnim.interpolate({
inputRange: [0, 1],
outputRange: [150, 0] // 0 : 150, 0.5 : 75, 1 : 0
}),
}],
}}

interpolate() supports multiple range segments as well, which is handy for defining dead zones and other handy tricks. For example, to get a negation relationship at -300 that goes to 0 at -100, then back up to 1 at 0, and then back down to zero at 100 followed by a dead-zone that remains at 0 for everything beyond that, you could do:

value.interpolate({
inputRange: [-300, -100, 0, 100, 101],
outputRange: [300, 0, 1, 0, 0]
});

Which would map like so:

Input | Output
------|-------
-400| 450
-300| 300
-200| 150
-100| 0
-50| 0.5
0| 1
50| 0.5
100| 0
101| 0
200| 0

interpolate() also supports mapping to strings, allowing you to animate colors as well as values with units. For example, if you wanted to animate a rotation you could do:

value.interpolate({
inputRange: [0, 360],
outputRange: ['0deg', '360deg']
});

interpolate() also supports arbitrary easing functions, many of which are already implemented in the Easing module. interpolate() also has configurable behavior for extrapolating the outputRange. You can set the extrapolation by setting the extrapolate, extrapolateLeft, or extrapolateRight options. The default value is extend but you can use clamp to prevent the output value from exceeding outputRange.

Tracking dynamic values

Animated values can also track other values. Set the toValue of an animation to another animated value instead of a plain number. For example, a "Chat Heads" animation like the one used by Messenger on Android could be implemented with a spring() pinned on another animated value, or with timing() and a duration of 0 for rigid tracking. They can also be composed with interpolations:

Animated.spring(follower, { toValue: leader }).start();
Animated.timing(opacity, {
toValue: pan.x.interpolate({
inputRange: [0, 300],
outputRange: [1, 0]
})
}).start();

The leader and follower animated values would be implemented using Animated.ValueXY(). ValueXY is a handy way to deal with 2D interactions, such as panning or dragging. It is a wrapper that contains two Animated.Value instances and some helper functions that call through to them, making ValueXY a drop-in replacement for Value in many cases. It allows us to track both x and y values in the example above.

Tracking gestures

Gestures, like panning or scrolling, and other events can map directly to animated values using Animated.event. This is done with a structured map syntax so that values can be extracted from complex event objects. The first level is an array to allow mapping across multiple args, and that array contains nested objects.

For example, when working with horizontal scrolling gestures, you would do the following in order to map event.nativeEvent.contentOffset.x to scrollX (an Animated.Value):

onScroll={Animated.event(
// scrollX = e.nativeEvent.contentOffset.x
[{ nativeEvent: {
contentOffset: {
x: scrollX
}
}
}]
)}

When using PanResponder, you could use the following code to extract the x and y positions from gestureState.dx and gestureState.dy. We use a null in the first position of the array, as we are only interested in the second argument passed to the PanResponder handler, which is the gestureState.

onPanResponderMove={Animated.event(
[null, // ignore the native event
// extract dx and dy from gestureState
// like 'pan.x = gestureState.dx, pan.y = gestureState.dy'
{dx: pan.x, dy: pan.y}
])}

Responding to the current animation value

You may notice that there is no clear way to read the current value while animating. This is because the value may only be known in the native runtime due to optimizations. If you need to run JavaScript in response to the current value, there are two approaches:

Animated is designed to be fully serializable so that animations can be run in a high performance way, independent of the normal JavaScript event loop. This does influence the API, so keep that in mind when it seems a little trickier to do something compared to a fully synchronous system. Check out Animated.Value.addListener as a way to work around some of these limitations, but use it sparingly since it might have performance implications in the future.

Using the native driver

The Animated API is designed to be serializable. By using the native driver, we send everything about the animation to native before starting the animation, allowing native code to perform the animation on the UI thread without having to go through the bridge on every frame. Once the animation has started, the JS thread can be blocked without affecting the animation.

To use the native driver for normal animations add useNativeDriver: true to the animation config when starting it.

Animated.timing(this.state.animatedValue, {
toValue: 1,
duration: 500,
useNativeDriver: true // <-- Add this
}).start();

Animated values are only compatible with one driver so if you use native driver when starting an animation on a value, make sure every animation on that value also uses the native driver.

The native driver also works with Animated.event. This is especially useful for animations that follow the scroll position as without the native driver, the animation will always run a frame behind the gesture due to the async nature of React Native.

<Animated.ScrollView // <-- Use the Animated ScrollView wrapper
scrollEventThrottle={1} // <-- Use 1 here to make sure no events are ever missed
onScroll={Animated.event(
[
{
nativeEvent: {
contentOffset: { y: this.state.animatedValue }
}
}
],
{ useNativeDriver: true } // <-- Add this
)}>
{content}
</Animated.ScrollView>

You can see the native driver in action by running the RNTester app, then loading the Native Animated Example. You can also take a look at the source code to learn how these examples were produced.

Caveats

Not everything you can do with Animated is currently supported by the native driver. The main limitation is that you can only animate non-layout properties: things like transform and opacity will work, but flexbox and position properties will not. When using Animated.event, it will only work with direct events and not bubbling events. This means it does not work with PanResponder but does work with things like ScrollView#onScroll.

When an animation is running, it can prevent VirtualizedList components from rendering more rows. If you need to run a long or looping animation while the user is scrolling through a list, you can use isInteraction: false in your animation's config to prevent this issue.

Bear in mind

While using transform styles such as rotateY, rotateX, and others ensure the transform style perspective is in place. At this time some animations may not render on Android without it. Example below.

<Animated.View
style={{
transform: [
{ scale: this.state.scale },
{ rotateY: this.state.rotateY },
{ perspective: 1000 } // without this line this Animation will not render on Android while working fine on iOS
]
}}
/>

Additional examples

The RNTester app has various examples of Animated in use:

LayoutAnimation API

LayoutAnimation allows you to globally configure create and update animations that will be used for all views in the next render/layout cycle. This is useful for doing flexbox layout updates without bothering to measure or calculate specific properties in order to animate them directly, and is especially useful when layout changes may affect ancestors, for example a "see more" expansion that also increases the size of the parent and pushes down the row below which would otherwise require explicit coordination between the components in order to animate them all in sync.

Note that although LayoutAnimation is very powerful and can be quite useful, it provides much less control than Animated and other animation libraries, so you may need to use another approach if you can't get LayoutAnimation to do what you want.

Note that in order to get this to work on Android you need to set the following flags via UIManager:

UIManager.setLayoutAnimationEnabledExperimental &&
UIManager.setLayoutAnimationEnabledExperimental(true);

This example uses a preset value, you can customize the animations as you need, see LayoutAnimation.js for more information.

Additional notes

requestAnimationFrame

requestAnimationFrame is a polyfill from the browser that you might be familiar with. It accepts a function as its only argument and calls that function before the next repaint. It is an essential building block for animations that underlies all of the JavaScript-based animation APIs. In general, you shouldn't need to call this yourself - the animation APIs will manage frame updates for you.

setNativeProps

As mentioned in the Direct Manipulation section, setNativeProps allows us to modify properties of native-backed components (components that are actually backed by native views, unlike composite components) directly, without having to setState and re-render the component hierarchy.

We could use this in the Rebound example to update the scale - this might be helpful if the component that we are updating is deeply nested and hasn't been optimized with shouldComponentUpdate.

If you find your animations with dropping frames (performing below 60 frames per second), look into using setNativeProps or shouldComponentUpdate to optimize them. Or you could run the animations on the UI thread rather than the JavaScript thread with the useNativeDriver 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.

Edit this page
Last updated on
- + diff --git a/docs/0.61/app-extensions.html b/docs/0.61/app-extensions.html index aaf144fee0c..c9e6751f229 100644 --- a/docs/0.61/app-extensions.html +++ b/docs/0.61/app-extensions.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

App Extensions

App extensions let you provide custom functionality and content outside of your main app. There are different types of app extensions on iOS, and they are all covered in the App Extension Programming Guide. In this guide, we'll briefly cover how you may take advantage of app extensions on iOS.

Memory use in extensions

As these extensions are loaded outside of the regular app sandbox, it's highly likely that several of these app extensions will be loaded simultaneously. As you might expect, these extensions have small memory usage limits. Keep these in mind when developing your app extensions. It's always highly recommended to test your application on an actual device, and more so when developing app extensions: too frequently, developers find that their extension works fine in the iOS Simulator, only to get user reports that their extension is not loading on actual devices.

We highly recommend that you watch Conrad Kramer's talk on Memory Use in Extensions to learn more about this topic.

Today widget

The memory limit of a Today widget is 16 MB. As it happens, Today widget implementations using React Native may work unreliably because the memory usage tends to be too high. You can tell if your Today widget is exceeding the memory limit if it yields the message 'Unable to Load':

Always make sure to test your app extensions in a real device, but be aware that this may not be sufficient, especially when dealing with Today widgets. Debug-configured builds are more likely to exceed the memory limits, while release-configured builds don't fail right away. We highly recommend that you use Xcode's Instruments to analyze your real world memory usage, as it's very likely that your release-configured build is very close to the 16 MB limit. In situations like these, you can quickly go over the 16 MB limit by performing common operations, such as fetching data from an API.

To experiment with the limits of React Native Today widget implementations, try extending the example project in react-native-today-widget.

Other app extensions

Other types of app extensions have greater memory limits than the Today widget. For instance, Custom Keyboard extensions are limited to 48 MB, and Share extensions are limited to 120 MB. Implementing such app extensions with React Native is more viable. One proof of concept example is react-native-ios-share-extension.

Edit this page
Last updated on
- + diff --git a/docs/0.61/app-extensions/index.html b/docs/0.61/app-extensions/index.html index aaf144fee0c..c9e6751f229 100644 --- a/docs/0.61/app-extensions/index.html +++ b/docs/0.61/app-extensions/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

App Extensions

App extensions let you provide custom functionality and content outside of your main app. There are different types of app extensions on iOS, and they are all covered in the App Extension Programming Guide. In this guide, we'll briefly cover how you may take advantage of app extensions on iOS.

Memory use in extensions

As these extensions are loaded outside of the regular app sandbox, it's highly likely that several of these app extensions will be loaded simultaneously. As you might expect, these extensions have small memory usage limits. Keep these in mind when developing your app extensions. It's always highly recommended to test your application on an actual device, and more so when developing app extensions: too frequently, developers find that their extension works fine in the iOS Simulator, only to get user reports that their extension is not loading on actual devices.

We highly recommend that you watch Conrad Kramer's talk on Memory Use in Extensions to learn more about this topic.

Today widget

The memory limit of a Today widget is 16 MB. As it happens, Today widget implementations using React Native may work unreliably because the memory usage tends to be too high. You can tell if your Today widget is exceeding the memory limit if it yields the message 'Unable to Load':

Always make sure to test your app extensions in a real device, but be aware that this may not be sufficient, especially when dealing with Today widgets. Debug-configured builds are more likely to exceed the memory limits, while release-configured builds don't fail right away. We highly recommend that you use Xcode's Instruments to analyze your real world memory usage, as it's very likely that your release-configured build is very close to the 16 MB limit. In situations like these, you can quickly go over the 16 MB limit by performing common operations, such as fetching data from an API.

To experiment with the limits of React Native Today widget implementations, try extending the example project in react-native-today-widget.

Other app extensions

Other types of app extensions have greater memory limits than the Today widget. For instance, Custom Keyboard extensions are limited to 48 MB, and Share extensions are limited to 120 MB. Implementing such app extensions with React Native is more viable. One proof of concept example is react-native-ios-share-extension.

Edit this page
Last updated on
- + diff --git a/docs/0.61/appregistry.html b/docs/0.61/appregistry.html index e9e7e4c4291..e49c5ae811e 100644 --- a/docs/0.61/appregistry.html +++ b/docs/0.61/appregistry.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

AppRegistry

AppRegistry is the JS entry point to running all React Native apps. App root components should register themselves with AppRegistry.registerComponent, then the native system can load the bundle for the app and then actually run the app when it's ready by invoking AppRegistry.runApplication.

To "stop" an application when a view should be destroyed, call AppRegistry.unmountApplicationComponentAtRootTag with the tag that was passed into runApplication. These should always be used as a pair.

AppRegistry should be required early in the require sequence to make sure the JS execution environment is setup before other modules are required.

Reference

Methods

setWrapperComponentProvider()

static setWrapperComponentProvider(provider)

registerConfig()

static registerConfig(config)

registerComponent()

static registerComponent(appKey, componentProvider, section?)

registerRunnable()

static registerRunnable(appKey, run)

registerSection()

static registerSection(appKey, component)

getAppKeys()

static getAppKeys()

getSectionKeys()

static getSectionKeys()

getSections()

static getSections()

getRunnable()

static getRunnable(appKey)

getRegistry()

static getRegistry()

setComponentProviderInstrumentationHook()

static setComponentProviderInstrumentationHook(hook)

runApplication()

static runApplication(appKey, appParameters)

unmountApplicationComponentAtRootTag()

static unmountApplicationComponentAtRootTag(rootTag)

registerHeadlessTask()

static registerHeadlessTask(taskKey, taskProvider)

Register a headless task. A headless task is a bit of code that runs without a UI. @param taskKey the key associated with this task @param taskProvider a promise returning function that takes some data passed from the native side as the only argument; when the promise is resolved or rejected the native side is notified of this event and it may decide to destroy the JS context.

registerCancellableHeadlessTask()

static registerCancellableHeadlessTask(taskKey, taskProvider, taskCancelProvider)

Register a headless task which can be cancelled. A headless task is a bit of code that runs without a UI. @param taskKey the key associated with this task @param taskProvider a promise returning function that takes some data passed from the native side as the only argument; when the promise is resolved or rejected the native side is notified of this event and it may decide to destroy the JS context. @param taskCancelProvider a void returning function that takes no arguments; when a cancellation is requested, the function being executed by taskProvider should wrap up and return ASAP.

startHeadlessTask()

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

cancelHeadlessTask()

static cancelHeadlessTask(taskId, taskKey)

Only called from native code. Cancels a headless task.

@param taskId the native id for this task instance that was used when startHeadlessTask was called @param taskKey the key for the task that was used when startHeadlessTask was called

Edit this page
Last updated on
- + diff --git a/docs/0.61/appregistry/index.html b/docs/0.61/appregistry/index.html index e9e7e4c4291..e49c5ae811e 100644 --- a/docs/0.61/appregistry/index.html +++ b/docs/0.61/appregistry/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

AppRegistry

AppRegistry is the JS entry point to running all React Native apps. App root components should register themselves with AppRegistry.registerComponent, then the native system can load the bundle for the app and then actually run the app when it's ready by invoking AppRegistry.runApplication.

To "stop" an application when a view should be destroyed, call AppRegistry.unmountApplicationComponentAtRootTag with the tag that was passed into runApplication. These should always be used as a pair.

AppRegistry should be required early in the require sequence to make sure the JS execution environment is setup before other modules are required.

Reference

Methods

setWrapperComponentProvider()

static setWrapperComponentProvider(provider)

registerConfig()

static registerConfig(config)

registerComponent()

static registerComponent(appKey, componentProvider, section?)

registerRunnable()

static registerRunnable(appKey, run)

registerSection()

static registerSection(appKey, component)

getAppKeys()

static getAppKeys()

getSectionKeys()

static getSectionKeys()

getSections()

static getSections()

getRunnable()

static getRunnable(appKey)

getRegistry()

static getRegistry()

setComponentProviderInstrumentationHook()

static setComponentProviderInstrumentationHook(hook)

runApplication()

static runApplication(appKey, appParameters)

unmountApplicationComponentAtRootTag()

static unmountApplicationComponentAtRootTag(rootTag)

registerHeadlessTask()

static registerHeadlessTask(taskKey, taskProvider)

Register a headless task. A headless task is a bit of code that runs without a UI. @param taskKey the key associated with this task @param taskProvider a promise returning function that takes some data passed from the native side as the only argument; when the promise is resolved or rejected the native side is notified of this event and it may decide to destroy the JS context.

registerCancellableHeadlessTask()

static registerCancellableHeadlessTask(taskKey, taskProvider, taskCancelProvider)

Register a headless task which can be cancelled. A headless task is a bit of code that runs without a UI. @param taskKey the key associated with this task @param taskProvider a promise returning function that takes some data passed from the native side as the only argument; when the promise is resolved or rejected the native side is notified of this event and it may decide to destroy the JS context. @param taskCancelProvider a void returning function that takes no arguments; when a cancellation is requested, the function being executed by taskProvider should wrap up and return ASAP.

startHeadlessTask()

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

cancelHeadlessTask()

static cancelHeadlessTask(taskId, taskKey)

Only called from native code. Cancels a headless task.

@param taskId the native id for this task instance that was used when startHeadlessTask was called @param taskKey the key for the task that was used when startHeadlessTask was called

Edit this page
Last updated on
- + diff --git a/docs/0.61/appstate.html b/docs/0.61/appstate.html index 6628e84b3e2..75deafd3161 100644 --- a/docs/0.61/appstate.html +++ b/docs/0.61/appstate.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
render() {
return <Text>Current state is: {this.state.appState}</Text>;
}
}

This example will only ever appear to say "Current state is: active" because the app is only visible to the user when in the active state, and the null state will happen only momentarily.

Reference

Events

change

This even is received when the app state has changed. The listener is called with one of the current app state values.

focus

[Android only] Received when the app gains focus (the user is interacting with the app).

blur

[Android only] Received when the user is not actively interacting with the app. Useful in situations when the user pulls down the notification drawer. AppState won't change but the blur event will get fired.

Methods

addEventListener()

addEventListener(type, handler);

Add a handler to AppState changes by listening to the change event type and providing the handler

removeEventListener()

removeEventListener(type, handler);

Remove a handler by passing the change event type and the handler

Properties

currentState

AppState.currentState;
Edit this page
Last updated on
- + diff --git a/docs/0.61/appstate/index.html b/docs/0.61/appstate/index.html index 6628e84b3e2..75deafd3161 100644 --- a/docs/0.61/appstate/index.html +++ b/docs/0.61/appstate/index.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
render() {
return <Text>Current state is: {this.state.appState}</Text>;
}
}

This example will only ever appear to say "Current state is: active" because the app is only visible to the user when in the active state, and the null state will happen only momentarily.

Reference

Events

change

This even is received when the app state has changed. The listener is called with one of the current app state values.

focus

[Android only] Received when the app gains focus (the user is interacting with the app).

blur

[Android only] Received when the user is not actively interacting with the app. Useful in situations when the user pulls down the notification drawer. AppState won't change but the blur event will get fired.

Methods

addEventListener()

addEventListener(type, handler);

Add a handler to AppState changes by listening to the change event type and providing the handler

removeEventListener()

removeEventListener(type, handler);

Remove a handler by passing the change event type and the handler

Properties

currentState

AppState.currentState;
Edit this page
Last updated on
- + diff --git a/docs/0.61/asyncstorage.html b/docs/0.61/asyncstorage.html index 5b0a04f9be0..7907b155788 100644 --- a/docs/0.61/asyncstorage.html +++ b/docs/0.61/asyncstorage.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@
// 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"}}
Edit this page
Last updated on
- + diff --git a/docs/0.61/asyncstorage/index.html b/docs/0.61/asyncstorage/index.html index 5b0a04f9be0..7907b155788 100644 --- a/docs/0.61/asyncstorage/index.html +++ b/docs/0.61/asyncstorage/index.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@
// 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"}}
Edit this page
Last updated on
- + diff --git a/docs/0.61/backandroid.html b/docs/0.61/backandroid.html index 85d9901bda0..32a2cb9feea 100644 --- a/docs/0.61/backandroid.html +++ b/docs/0.61/backandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

BackAndroid

Deprecated. Use BackHandler instead.

Methods

Reference

Methods

exitApp()

static exitApp()

addEventListener()

static addEventListener(eventName, handler)

removeEventListener()

static removeEventListener(eventName, handler)
Edit this page
Last updated on
- + diff --git a/docs/0.61/backandroid/index.html b/docs/0.61/backandroid/index.html index 85d9901bda0..32a2cb9feea 100644 --- a/docs/0.61/backandroid/index.html +++ b/docs/0.61/backandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

BackAndroid

Deprecated. Use BackHandler instead.

Methods

Reference

Methods

exitApp()

static exitApp()

addEventListener()

static addEventListener(eventName, handler)

removeEventListener()

static removeEventListener(eventName, handler)
Edit this page
Last updated on
- + diff --git a/docs/0.61/backhandler.html b/docs/0.61/backhandler.html index 6e839a350fe..be1e6807d72 100644 --- a/docs/0.61/backhandler.html +++ b/docs/0.61/backhandler.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
componentWillUnmount() {
this.backHandler.remove();
}

Reference

Methods

addEventListener()

static addEventListener(eventName, handler)

exitApp()

static exitApp()

removeEventListener()

static removeEventListener(eventName, handler)
Edit this page
Last updated on
- + diff --git a/docs/0.61/backhandler/index.html b/docs/0.61/backhandler/index.html index 6e839a350fe..be1e6807d72 100644 --- a/docs/0.61/backhandler/index.html +++ b/docs/0.61/backhandler/index.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
componentWillUnmount() {
this.backHandler.remove();
}

Reference

Methods

addEventListener()

static addEventListener(eventName, handler)

exitApp()

static exitApp()

removeEventListener()

static removeEventListener(eventName, handler)
Edit this page
Last updated on
- + diff --git a/docs/0.61/building-for-tv.html b/docs/0.61/building-for-tv.html index c090fa58d3b..cbff2690c0a 100644 --- a/docs/0.61/building-for-tv.html +++ b/docs/0.61/building-for-tv.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
componentWillUnmount() {
this._disableTVEventHandler();
}
}
Edit this page
Last updated on
- + diff --git a/docs/0.61/building-for-tv/index.html b/docs/0.61/building-for-tv/index.html index c090fa58d3b..cbff2690c0a 100644 --- a/docs/0.61/building-for-tv/index.html +++ b/docs/0.61/building-for-tv/index.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
componentWillUnmount() {
this._disableTVEventHandler();
}
}
Edit this page
Last updated on
- + diff --git a/docs/0.61/button.html b/docs/0.61/button.html index e041cc42b23..5692e98406f 100644 --- a/docs/0.61/button.html +++ b/docs/0.61/button.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

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 button using TouchableOpacity or TouchableNativeFeedback. For inspiration, look at the source code for this button component. Or, take a look at the wide variety of button components built by the community.

Example

Reference

Props

onPress

Handler to be called when the user taps the button

TypeRequired
functionYes

title

Text to display inside the button

TypeRequired
stringYes

accessibilityLabel

Text to display for blindness accessibility features

TypeRequired
stringNo

color

Color of the text (iOS), or background color of the button (Android)

TypeRequired
colorNo

disabled

If true, disable all interactions for this component.

TypeRequired
boolNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

nextFocusDown

Designates the next view to receive focus when the user navigates down. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusForward

Designates the next view to receive focus when the user navigates forward. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusLeft

Designates the next view to receive focus when the user navigates left. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusRight

Designates the next view to receive focus when the user navigates right. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusUp

Designates the next view to receive focus when the user navigates up. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

touchSoundDisabled

If true, doesn't play system sound on touch.

TypeRequiredPlatform
booleanNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.61/button/index.html b/docs/0.61/button/index.html index e041cc42b23..5692e98406f 100644 --- a/docs/0.61/button/index.html +++ b/docs/0.61/button/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

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 button using TouchableOpacity or TouchableNativeFeedback. For inspiration, look at the source code for this button component. Or, take a look at the wide variety of button components built by the community.

Example

Reference

Props

onPress

Handler to be called when the user taps the button

TypeRequired
functionYes

title

Text to display inside the button

TypeRequired
stringYes

accessibilityLabel

Text to display for blindness accessibility features

TypeRequired
stringNo

color

Color of the text (iOS), or background color of the button (Android)

TypeRequired
colorNo

disabled

If true, disable all interactions for this component.

TypeRequired
boolNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

nextFocusDown

Designates the next view to receive focus when the user navigates down. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusForward

Designates the next view to receive focus when the user navigates forward. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusLeft

Designates the next view to receive focus when the user navigates left. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusRight

Designates the next view to receive focus when the user navigates right. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusUp

Designates the next view to receive focus when the user navigates up. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

touchSoundDisabled

If true, doesn't play system sound on touch.

TypeRequiredPlatform
booleanNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.61/cameraroll.html b/docs/0.61/cameraroll.html index 7c5e17f7689..88522849579 100644 --- a/docs/0.61/cameraroll.html +++ b/docs/0.61/cameraroll.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 CameraRoll

Deprecated. Use @react-native-community/cameraroll instead.

CameraRoll provides access to the local camera roll or photo library.

On iOS, the CameraRoll API requires the RCTCameraRoll library to be linked. You can refer to Linking Libraries (iOS) to learn more.

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 app will use this data. This key will appear as Privacy - Photo Library Usage Description in Xcode.

If you are targeting devices running iOS 11 or later, you will also need to add the NSPhotoLibraryAddUsageDescription key in your Info.plist. Use this key to define a string that describes how your app will use this data. By adding this key to your Info.plist, you will be able to request write-only access permission from the user. If you try to save to the camera roll without this permission, your app will exit.

Reference

Methods

saveToCameraRoll()

CameraRoll.saveToCameraRoll(tag, [type]);

Saves the photo or video to the camera roll or photo library.

On Android, the tag must be a local image or video URI, such as "file:///sdcard/img.png".

On iOS, the tag can be any image URI (including local, remote asset-library and base64 data URIs) 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.

Parameters:

NameTypeRequiredDescription
tagstringYesSee above.
typeenum('photo', 'video')NoOverrides automatic detection based on the file extension.

getPhotos()

CameraRoll.getPhotos(params);

Returns a Promise with photo identifier objects from the local camera roll of the device matching shape defined by getPhotosReturnChecker.

Parameters:

NameTypeRequiredDescription
paramsobjectYesExpects a params with the shape described below.
  • 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 matches page_info { end_cursor } returned from a previous call to getPhotos.
  • groupTypes : {string} : Specifies which group types to filter the results to. Valid values are:
    • Album
    • All
    • Event
    • Faces
    • Library
    • PhotoStream
    • SavedPhotos // 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:
    • All
    • Videos
    • Photos // default
  • mimeTypes : {Array} : 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 objects
    • node: {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}
        • playableDuration: {number}
      • 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: {string}
    • end_cursor: {string}

Example

Loading images:

_handleButtonPress = () => {
CameraRoll.getPhotos({
first: 20,
assetType: 'Photos',
})
.then(r => {
this.setState({ photos: r.edges });
})
.catch((err) => {
//Error Loading Images
});
};
render() {
return (
<View>
<Button title="Load Images" onPress={this._handleButtonPress} />
<ScrollView>
{this.state.photos.map((p, i) => {
return (
<Image
key={i}
style={{
width: 300,
height: 100,
}}
source={{ uri: p.node.image.uri }}
/>
);
})}
</ScrollView>
</View>
);
}
Edit this page
Last updated on
- + diff --git a/docs/0.61/cameraroll/index.html b/docs/0.61/cameraroll/index.html index 7c5e17f7689..88522849579 100644 --- a/docs/0.61/cameraroll/index.html +++ b/docs/0.61/cameraroll/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 CameraRoll

Deprecated. Use @react-native-community/cameraroll instead.

CameraRoll provides access to the local camera roll or photo library.

On iOS, the CameraRoll API requires the RCTCameraRoll library to be linked. You can refer to Linking Libraries (iOS) to learn more.

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 app will use this data. This key will appear as Privacy - Photo Library Usage Description in Xcode.

If you are targeting devices running iOS 11 or later, you will also need to add the NSPhotoLibraryAddUsageDescription key in your Info.plist. Use this key to define a string that describes how your app will use this data. By adding this key to your Info.plist, you will be able to request write-only access permission from the user. If you try to save to the camera roll without this permission, your app will exit.

Reference

Methods

saveToCameraRoll()

CameraRoll.saveToCameraRoll(tag, [type]);

Saves the photo or video to the camera roll or photo library.

On Android, the tag must be a local image or video URI, such as "file:///sdcard/img.png".

On iOS, the tag can be any image URI (including local, remote asset-library and base64 data URIs) 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.

Parameters:

NameTypeRequiredDescription
tagstringYesSee above.
typeenum('photo', 'video')NoOverrides automatic detection based on the file extension.

getPhotos()

CameraRoll.getPhotos(params);

Returns a Promise with photo identifier objects from the local camera roll of the device matching shape defined by getPhotosReturnChecker.

Parameters:

NameTypeRequiredDescription
paramsobjectYesExpects a params with the shape described below.
  • 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 matches page_info { end_cursor } returned from a previous call to getPhotos.
  • groupTypes : {string} : Specifies which group types to filter the results to. Valid values are:
    • Album
    • All
    • Event
    • Faces
    • Library
    • PhotoStream
    • SavedPhotos // 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:
    • All
    • Videos
    • Photos // default
  • mimeTypes : {Array} : 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 objects
    • node: {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}
        • playableDuration: {number}
      • 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: {string}
    • end_cursor: {string}

Example

Loading images:

_handleButtonPress = () => {
CameraRoll.getPhotos({
first: 20,
assetType: 'Photos',
})
.then(r => {
this.setState({ photos: r.edges });
})
.catch((err) => {
//Error Loading Images
});
};
render() {
return (
<View>
<Button title="Load Images" onPress={this._handleButtonPress} />
<ScrollView>
{this.state.photos.map((p, i) => {
return (
<Image
key={i}
style={{
width: 300,
height: 100,
}}
source={{ uri: p.node.image.uri }}
/>
);
})}
</ScrollView>
</View>
);
}
Edit this page
Last updated on
- + diff --git a/docs/0.61/checkbox.html b/docs/0.61/checkbox.html index af5fd8aea14..f51f4e325af 100644 --- a/docs/0.61/checkbox.html +++ b/docs/0.61/checkbox.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 CheckBox

Deprecated. Use @react-native-community/checkbox instead.

Renders a boolean input (Android only).

This is a controlled component that requires an onValueChange callback that updates the value prop in order for the component to reflect user actions. If the value prop is not updated, the component will continue to render the supplied value prop instead of the expected result of any user actions.

Example

Reference

Props

Inherits View Props.

disabled

If true the user won't be able to toggle the checkbox. Default value is false.

TypeRequired
boolNo

onChange

Used in case the props change removes the component.

TypeRequired
functionNo

onValueChange

Invoked with the new value when the value changes.

TypeRequired
functionNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

value

The value of the checkbox. If true the checkbox will be turned on. Default value is false.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/checkbox/index.html b/docs/0.61/checkbox/index.html index af5fd8aea14..f51f4e325af 100644 --- a/docs/0.61/checkbox/index.html +++ b/docs/0.61/checkbox/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 CheckBox

Deprecated. Use @react-native-community/checkbox instead.

Renders a boolean input (Android only).

This is a controlled component that requires an onValueChange callback that updates the value prop in order for the component to reflect user actions. If the value prop is not updated, the component will continue to render the supplied value prop instead of the expected result of any user actions.

Example

Reference

Props

Inherits View Props.

disabled

If true the user won't be able to toggle the checkbox. Default value is false.

TypeRequired
boolNo

onChange

Used in case the props change removes the component.

TypeRequired
functionNo

onValueChange

Invoked with the new value when the value changes.

TypeRequired
functionNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

value

The value of the checkbox. If true the checkbox will be turned on. Default value is false.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/clipboard.html b/docs/0.61/clipboard.html index 678c10dae61..a83f4027a5e 100644 --- a/docs/0.61/clipboard.html +++ b/docs/0.61/clipboard.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 Clipboard

Deprecated. Use @react-native-community/clipboard instead.

Clipboard gives you an interface for setting and getting content from Clipboard on both Android and iOS

Reference

Methods

getString()

static getString()

Get content of string type, this method returns a Promise, so you can use following code to get clipboard content

async _getContent() {
var content = await Clipboard.getString();
}

setString()

static setString(content)

Set content of string type. You can use following code to set clipboard content

_setContent() {
Clipboard.setString('hello world');
}

@param the content to be stored in the clipboard.

Edit this page
Last updated on
- + diff --git a/docs/0.61/clipboard/index.html b/docs/0.61/clipboard/index.html index 678c10dae61..a83f4027a5e 100644 --- a/docs/0.61/clipboard/index.html +++ b/docs/0.61/clipboard/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 Clipboard

Deprecated. Use @react-native-community/clipboard instead.

Clipboard gives you an interface for setting and getting content from Clipboard on both Android and iOS

Reference

Methods

getString()

static getString()

Get content of string type, this method returns a Promise, so you can use following code to get clipboard content

async _getContent() {
var content = await Clipboard.getString();
}

setString()

static setString(content)

Set content of string type. You can use following code to set clipboard content

_setContent() {
Clipboard.setString('hello world');
}

@param the content to be stored in the clipboard.

Edit this page
Last updated on
- + diff --git a/docs/0.61/colors.html b/docs/0.61/colors.html index 8592c8ba57d..8d49fe78fe0 100644 --- a/docs/0.61/colors.html +++ b/docs/0.61/colors.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

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:

  • #f0f8ff aliceblue (#f0f8ff)
  • #faebd7 antiquewhite (#faebd7)
  • #00ffff aqua (#00ffff)
  • #7fffd4 aquamarine (#7fffd4)
  • #f0ffff azure (#f0ffff)
  • #f5f5dc beige (#f5f5dc)
  • #ffe4c4 bisque (#ffe4c4)
  • #000000 black (#000000)
  • #ffebcd blanchedalmond (#ffebcd)
  • #0000ff blue (#0000ff)
  • #8a2be2 blueviolet (#8a2be2)
  • #a52a2a brown (#a52a2a)
  • #deb887 burlywood (#deb887)
  • #5f9ea0 cadetblue (#5f9ea0)
  • #7fff00 chartreuse (#7fff00)
  • #d2691e chocolate (#d2691e)
  • #ff7f50 coral (#ff7f50)
  • #6495ed cornflowerblue (#6495ed)
  • #fff8dc cornsilk (#fff8dc)
  • #dc143c crimson (#dc143c)
  • #00ffff cyan (#00ffff)
  • #00008b darkblue (#00008b)
  • #008b8b darkcyan (#008b8b)
  • #b8860b darkgoldenrod (#b8860b)
  • #a9a9a9 darkgray (#a9a9a9)
  • #006400 darkgreen (#006400)
  • #a9a9a9 darkgrey (#a9a9a9)
  • #bdb76b darkkhaki (#bdb76b)
  • #8b008b darkmagenta (#8b008b)
  • #556b2f darkolivegreen (#556b2f)
  • #ff8c00 darkorange (#ff8c00)
  • #9932cc darkorchid (#9932cc)
  • #8b0000 darkred (#8b0000)
  • #e9967a darksalmon (#e9967a)
  • #8fbc8f darkseagreen (#8fbc8f)
  • #483d8b darkslateblue (#483d8b)
  • #2f4f4f darkslategrey (#2f4f4f)
  • #00ced1 darkturquoise (#00ced1)
  • #9400d3 darkviolet (#9400d3)
  • #ff1493 deeppink (#ff1493)
  • #00bfff deepskyblue (#00bfff)
  • #696969 dimgray (#696969)
  • #696969 dimgrey (#696969)
  • #1e90ff dodgerblue (#1e90ff)
  • #b22222 firebrick (#b22222)
  • #fffaf0 floralwhite (#fffaf0)
  • #228b22 forestgreen (#228b22)
  • #ff00ff fuchsia (#ff00ff)
  • #dcdcdc gainsboro (#dcdcdc)
  • #f8f8ff ghostwhite (#f8f8ff)
  • #ffd700 gold (#ffd700)
  • #daa520 goldenrod (#daa520)
  • #808080 gray (#808080)
  • #008000 green (#008000)
  • #adff2f greenyellow (#adff2f)
  • #808080 grey (#808080)
  • #f0fff0 honeydew (#f0fff0)
  • #ff69b4 hotpink (#ff69b4)
  • #cd5c5c indianred (#cd5c5c)
  • #4b0082 indigo (#4b0082)
  • #fffff0 ivory (#fffff0)
  • #f0e68c khaki (#f0e68c)
  • #e6e6fa lavender (#e6e6fa)
  • #fff0f5 lavenderblush (#fff0f5)
  • #7cfc00 lawngreen (#7cfc00)
  • #fffacd lemonchiffon (#fffacd)
  • #add8e6 lightblue (#add8e6)
  • #f08080 lightcoral (#f08080)
  • #e0ffff lightcyan (#e0ffff)
  • #fafad2 lightgoldenrodyellow (#fafad2)
  • #d3d3d3 lightgray (#d3d3d3)
  • #90ee90 lightgreen (#90ee90)
  • #d3d3d3 lightgrey (#d3d3d3)
  • #ffb6c1 lightpink (#ffb6c1)
  • #ffa07a lightsalmon (#ffa07a)
  • #20b2aa lightseagreen (#20b2aa)
  • #87cefa lightskyblue (#87cefa)
  • #778899 lightslategrey (#778899)
  • #b0c4de lightsteelblue (#b0c4de)
  • #ffffe0 lightyellow (#ffffe0)
  • #00ff00 lime (#00ff00)
  • #32cd32 limegreen (#32cd32)
  • #faf0e6 linen (#faf0e6)
  • #ff00ff magenta (#ff00ff)
  • #800000 maroon (#800000)
  • #66cdaa mediumaquamarine (#66cdaa)
  • #0000cd mediumblue (#0000cd)
  • #ba55d3 mediumorchid (#ba55d3)
  • #9370db mediumpurple (#9370db)
  • #3cb371 mediumseagreen (#3cb371)
  • #7b68ee mediumslateblue (#7b68ee)
  • #00fa9a mediumspringgreen (#00fa9a)
  • #48d1cc mediumturquoise (#48d1cc)
  • #c71585 mediumvioletred (#c71585)
  • #191970 midnightblue (#191970)
  • #f5fffa mintcream (#f5fffa)
  • #ffe4e1 mistyrose (#ffe4e1)
  • #ffe4b5 moccasin (#ffe4b5)
  • #ffdead navajowhite (#ffdead)
  • #000080 navy (#000080)
  • #fdf5e6 oldlace (#fdf5e6)
  • #808000 olive (#808000)
  • #6b8e23 olivedrab (#6b8e23)
  • #ffa500 orange (#ffa500)
  • #ff4500 orangered (#ff4500)
  • #da70d6 orchid (#da70d6)
  • #eee8aa palegoldenrod (#eee8aa)
  • #98fb98 palegreen (#98fb98)
  • #afeeee paleturquoise (#afeeee)
  • #db7093 palevioletred (#db7093)
  • #ffefd5 papayawhip (#ffefd5)
  • #ffdab9 peachpuff (#ffdab9)
  • #cd853f peru (#cd853f)
  • #ffc0cb pink (#ffc0cb)
  • #dda0dd plum (#dda0dd)
  • #b0e0e6 powderblue (#b0e0e6)
  • #800080 purple (#800080)
  • #663399 rebeccapurple (#663399)
  • #ff0000 red (#ff0000)
  • #bc8f8f rosybrown (#bc8f8f)
  • #4169e1 royalblue (#4169e1)
  • #8b4513 saddlebrown (#8b4513)
  • #fa8072 salmon (#fa8072)
  • #f4a460 sandybrown (#f4a460)
  • #2e8b57 seagreen (#2e8b57)
  • #fff5ee seashell (#fff5ee)
  • #a0522d sienna (#a0522d)
  • #c0c0c0 silver (#c0c0c0)
  • #87ceeb skyblue (#87ceeb)
  • #6a5acd slateblue (#6a5acd)
  • #708090 slategray (#708090)
  • #fffafa snow (#fffafa)
  • #00ff7f springgreen (#00ff7f)
  • #4682b4 steelblue (#4682b4)
  • #d2b48c tan (#d2b48c)
  • #008080 teal (#008080)
  • #d8bfd8 thistle (#d8bfd8)
  • #ff6347 tomato (#ff6347)
  • #40e0d0 turquoise (#40e0d0)
  • #ee82ee violet (#ee82ee)
  • #f5deb3 wheat (#f5deb3)
  • #ffffff white (#ffffff)
  • #f5f5f5 whitesmoke (#f5f5f5)
  • #ffff00 yellow (#ffff00)
  • #9acd32 yellowgreen (#9acd32)
Edit this page
Last updated on
- + diff --git a/docs/0.61/colors/index.html b/docs/0.61/colors/index.html index 8592c8ba57d..8d49fe78fe0 100644 --- a/docs/0.61/colors/index.html +++ b/docs/0.61/colors/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

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:

  • #f0f8ff aliceblue (#f0f8ff)
  • #faebd7 antiquewhite (#faebd7)
  • #00ffff aqua (#00ffff)
  • #7fffd4 aquamarine (#7fffd4)
  • #f0ffff azure (#f0ffff)
  • #f5f5dc beige (#f5f5dc)
  • #ffe4c4 bisque (#ffe4c4)
  • #000000 black (#000000)
  • #ffebcd blanchedalmond (#ffebcd)
  • #0000ff blue (#0000ff)
  • #8a2be2 blueviolet (#8a2be2)
  • #a52a2a brown (#a52a2a)
  • #deb887 burlywood (#deb887)
  • #5f9ea0 cadetblue (#5f9ea0)
  • #7fff00 chartreuse (#7fff00)
  • #d2691e chocolate (#d2691e)
  • #ff7f50 coral (#ff7f50)
  • #6495ed cornflowerblue (#6495ed)
  • #fff8dc cornsilk (#fff8dc)
  • #dc143c crimson (#dc143c)
  • #00ffff cyan (#00ffff)
  • #00008b darkblue (#00008b)
  • #008b8b darkcyan (#008b8b)
  • #b8860b darkgoldenrod (#b8860b)
  • #a9a9a9 darkgray (#a9a9a9)
  • #006400 darkgreen (#006400)
  • #a9a9a9 darkgrey (#a9a9a9)
  • #bdb76b darkkhaki (#bdb76b)
  • #8b008b darkmagenta (#8b008b)
  • #556b2f darkolivegreen (#556b2f)
  • #ff8c00 darkorange (#ff8c00)
  • #9932cc darkorchid (#9932cc)
  • #8b0000 darkred (#8b0000)
  • #e9967a darksalmon (#e9967a)
  • #8fbc8f darkseagreen (#8fbc8f)
  • #483d8b darkslateblue (#483d8b)
  • #2f4f4f darkslategrey (#2f4f4f)
  • #00ced1 darkturquoise (#00ced1)
  • #9400d3 darkviolet (#9400d3)
  • #ff1493 deeppink (#ff1493)
  • #00bfff deepskyblue (#00bfff)
  • #696969 dimgray (#696969)
  • #696969 dimgrey (#696969)
  • #1e90ff dodgerblue (#1e90ff)
  • #b22222 firebrick (#b22222)
  • #fffaf0 floralwhite (#fffaf0)
  • #228b22 forestgreen (#228b22)
  • #ff00ff fuchsia (#ff00ff)
  • #dcdcdc gainsboro (#dcdcdc)
  • #f8f8ff ghostwhite (#f8f8ff)
  • #ffd700 gold (#ffd700)
  • #daa520 goldenrod (#daa520)
  • #808080 gray (#808080)
  • #008000 green (#008000)
  • #adff2f greenyellow (#adff2f)
  • #808080 grey (#808080)
  • #f0fff0 honeydew (#f0fff0)
  • #ff69b4 hotpink (#ff69b4)
  • #cd5c5c indianred (#cd5c5c)
  • #4b0082 indigo (#4b0082)
  • #fffff0 ivory (#fffff0)
  • #f0e68c khaki (#f0e68c)
  • #e6e6fa lavender (#e6e6fa)
  • #fff0f5 lavenderblush (#fff0f5)
  • #7cfc00 lawngreen (#7cfc00)
  • #fffacd lemonchiffon (#fffacd)
  • #add8e6 lightblue (#add8e6)
  • #f08080 lightcoral (#f08080)
  • #e0ffff lightcyan (#e0ffff)
  • #fafad2 lightgoldenrodyellow (#fafad2)
  • #d3d3d3 lightgray (#d3d3d3)
  • #90ee90 lightgreen (#90ee90)
  • #d3d3d3 lightgrey (#d3d3d3)
  • #ffb6c1 lightpink (#ffb6c1)
  • #ffa07a lightsalmon (#ffa07a)
  • #20b2aa lightseagreen (#20b2aa)
  • #87cefa lightskyblue (#87cefa)
  • #778899 lightslategrey (#778899)
  • #b0c4de lightsteelblue (#b0c4de)
  • #ffffe0 lightyellow (#ffffe0)
  • #00ff00 lime (#00ff00)
  • #32cd32 limegreen (#32cd32)
  • #faf0e6 linen (#faf0e6)
  • #ff00ff magenta (#ff00ff)
  • #800000 maroon (#800000)
  • #66cdaa mediumaquamarine (#66cdaa)
  • #0000cd mediumblue (#0000cd)
  • #ba55d3 mediumorchid (#ba55d3)
  • #9370db mediumpurple (#9370db)
  • #3cb371 mediumseagreen (#3cb371)
  • #7b68ee mediumslateblue (#7b68ee)
  • #00fa9a mediumspringgreen (#00fa9a)
  • #48d1cc mediumturquoise (#48d1cc)
  • #c71585 mediumvioletred (#c71585)
  • #191970 midnightblue (#191970)
  • #f5fffa mintcream (#f5fffa)
  • #ffe4e1 mistyrose (#ffe4e1)
  • #ffe4b5 moccasin (#ffe4b5)
  • #ffdead navajowhite (#ffdead)
  • #000080 navy (#000080)
  • #fdf5e6 oldlace (#fdf5e6)
  • #808000 olive (#808000)
  • #6b8e23 olivedrab (#6b8e23)
  • #ffa500 orange (#ffa500)
  • #ff4500 orangered (#ff4500)
  • #da70d6 orchid (#da70d6)
  • #eee8aa palegoldenrod (#eee8aa)
  • #98fb98 palegreen (#98fb98)
  • #afeeee paleturquoise (#afeeee)
  • #db7093 palevioletred (#db7093)
  • #ffefd5 papayawhip (#ffefd5)
  • #ffdab9 peachpuff (#ffdab9)
  • #cd853f peru (#cd853f)
  • #ffc0cb pink (#ffc0cb)
  • #dda0dd plum (#dda0dd)
  • #b0e0e6 powderblue (#b0e0e6)
  • #800080 purple (#800080)
  • #663399 rebeccapurple (#663399)
  • #ff0000 red (#ff0000)
  • #bc8f8f rosybrown (#bc8f8f)
  • #4169e1 royalblue (#4169e1)
  • #8b4513 saddlebrown (#8b4513)
  • #fa8072 salmon (#fa8072)
  • #f4a460 sandybrown (#f4a460)
  • #2e8b57 seagreen (#2e8b57)
  • #fff5ee seashell (#fff5ee)
  • #a0522d sienna (#a0522d)
  • #c0c0c0 silver (#c0c0c0)
  • #87ceeb skyblue (#87ceeb)
  • #6a5acd slateblue (#6a5acd)
  • #708090 slategray (#708090)
  • #fffafa snow (#fffafa)
  • #00ff7f springgreen (#00ff7f)
  • #4682b4 steelblue (#4682b4)
  • #d2b48c tan (#d2b48c)
  • #008080 teal (#008080)
  • #d8bfd8 thistle (#d8bfd8)
  • #ff6347 tomato (#ff6347)
  • #40e0d0 turquoise (#40e0d0)
  • #ee82ee violet (#ee82ee)
  • #f5deb3 wheat (#f5deb3)
  • #ffffff white (#ffffff)
  • #f5f5f5 whitesmoke (#f5f5f5)
  • #ffff00 yellow (#ffff00)
  • #9acd32 yellowgreen (#9acd32)
Edit this page
Last updated on
- + diff --git a/docs/0.61/communication-android.html b/docs/0.61/communication-android.html index 02f193d81b7..005f7e08edb 100644 --- a/docs/0.61/communication-android.html +++ b/docs/0.61/communication-android.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
mReactRootView.setAppProperties(updatedProps);

It is fine to update properties anytime. However, updates have to be performed on the main thread. You use the getter on any thread.

There is no way to update only a few properties at a time. We suggest that you build it into your own wrapper instead.

Note: Currently, JS function componentWillUpdateProps of the top level RN component will not be called after a prop update. However, you can access the new props in componentDidMount function.

Passing properties from React Native to native

The problem exposing properties of native components is covered in detail in this article. In short, properties that are to be reflected in JavaScript needs to be exposed as setter method annotated with @ReactProp, then use them in React Native as if the component was an ordinary React Native component.

Limits of properties

The main drawback of cross-language properties is that they do not support callbacks, which would allow us to handle bottom-up data bindings. Imagine you have a small RN view that you want to be removed from the native parent view as a result of a JS action. There is no way to do that with props, as the information would need to go bottom-up.

Although we have a flavor of cross-language callbacks (described here), these callbacks are not always the thing we need. The main problem is that they are not intended to be passed as properties. Rather, this mechanism allows us to trigger a native action from JS, and handle the result of that action in JS.

Other ways of cross-language interaction (events and native modules)

As stated in the previous chapter, using properties comes with some limitations. Sometimes properties are not enough to drive the logic of our app and we need a solution that gives more flexibility. This chapter covers other communication techniques available in React Native. They can be used for internal communication (between JS and native layers in RN) as well as for external communication (between RN and the 'pure native' part of your app).

React Native enables you to perform cross-language function calls. You can execute custom native code from JS and vice versa. Unfortunately, depending on the side we are working on, we achieve the same goal in different ways. For native - we use events mechanism to schedule an execution of a handler function in JS, while for React Native we directly call methods exported by native modules.

Calling React Native functions from native (events)

Events are described in detail in this article. Note that using events gives us no guarantees about execution time, as the event is handled on a separate thread.

Events are powerful, because they allow us to change React Native components without needing a reference to them. However, there are some pitfalls that you can fall into while using them:

Calling native functions from React Native (native modules)

Native modules are Java classes that are available in JS. Typically one instance of each module is created per JS bridge. They can export arbitrary functions and constants to React Native. They have been covered in detail in this article.

Warning: All native modules share the same namespace. Watch out for name collisions when creating new ones.

Edit this page
Last updated on
- + diff --git a/docs/0.61/communication-android/index.html b/docs/0.61/communication-android/index.html index 02f193d81b7..005f7e08edb 100644 --- a/docs/0.61/communication-android/index.html +++ b/docs/0.61/communication-android/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
mReactRootView.setAppProperties(updatedProps);

It is fine to update properties anytime. However, updates have to be performed on the main thread. You use the getter on any thread.

There is no way to update only a few properties at a time. We suggest that you build it into your own wrapper instead.

Note: Currently, JS function componentWillUpdateProps of the top level RN component will not be called after a prop update. However, you can access the new props in componentDidMount function.

Passing properties from React Native to native

The problem exposing properties of native components is covered in detail in this article. In short, properties that are to be reflected in JavaScript needs to be exposed as setter method annotated with @ReactProp, then use them in React Native as if the component was an ordinary React Native component.

Limits of properties

The main drawback of cross-language properties is that they do not support callbacks, which would allow us to handle bottom-up data bindings. Imagine you have a small RN view that you want to be removed from the native parent view as a result of a JS action. There is no way to do that with props, as the information would need to go bottom-up.

Although we have a flavor of cross-language callbacks (described here), these callbacks are not always the thing we need. The main problem is that they are not intended to be passed as properties. Rather, this mechanism allows us to trigger a native action from JS, and handle the result of that action in JS.

Other ways of cross-language interaction (events and native modules)

As stated in the previous chapter, using properties comes with some limitations. Sometimes properties are not enough to drive the logic of our app and we need a solution that gives more flexibility. This chapter covers other communication techniques available in React Native. They can be used for internal communication (between JS and native layers in RN) as well as for external communication (between RN and the 'pure native' part of your app).

React Native enables you to perform cross-language function calls. You can execute custom native code from JS and vice versa. Unfortunately, depending on the side we are working on, we achieve the same goal in different ways. For native - we use events mechanism to schedule an execution of a handler function in JS, while for React Native we directly call methods exported by native modules.

Calling React Native functions from native (events)

Events are described in detail in this article. Note that using events gives us no guarantees about execution time, as the event is handled on a separate thread.

Events are powerful, because they allow us to change React Native components without needing a reference to them. However, there are some pitfalls that you can fall into while using them:

Calling native functions from React Native (native modules)

Native modules are Java classes that are available in JS. Typically one instance of each module is created per JS bridge. They can export arbitrary functions and constants to React Native. They have been covered in detail in this article.

Warning: All native modules share the same namespace. Watch out for name collisions when creating new ones.

Edit this page
Last updated on
- + diff --git a/docs/0.61/communication-ios.html b/docs/0.61/communication-ios.html index a0e8f453e32..48941c361ff 100644 --- a/docs/0.61/communication-ios.html +++ b/docs/0.61/communication-ios.html @@ -19,7 +19,7 @@ - + @@ -44,7 +44,7 @@
rootView.frame = newFrame;
}

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 example 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 separate 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's hidden property). Then change its visibility in the delegate method.

Edit this page
Last updated on
- + diff --git a/docs/0.61/communication-ios/index.html b/docs/0.61/communication-ios/index.html index a0e8f453e32..48941c361ff 100644 --- a/docs/0.61/communication-ios/index.html +++ b/docs/0.61/communication-ios/index.html @@ -19,7 +19,7 @@ - + @@ -44,7 +44,7 @@
rootView.frame = newFrame;
}

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 example 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 separate 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's hidden property). Then change its visibility in the delegate method.

Edit this page
Last updated on
- + diff --git a/docs/0.61/components-and-apis.html b/docs/0.61/components-and-apis.html index 4ca59c7ff50..e02963e3906 100644 --- a/docs/0.61/components-and-apis.html +++ b/docs/0.61/components-and-apis.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Components and APIs

React Native provides a number of Core 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.

Text

A component for displaying text.

Image

A component for displaying images.

TextInput

A component for inputting text into the app via a keyboard.

ScrollView

Provides a scrolling container that can host multiple components and views.

StyleSheet

Provides an abstraction layer similar to CSS stylesheets.

User Interface

Render common user interface controls on any platform using the following components. For platform specific components, keep reading.

Button

A basic button component for handling touches that should render nicely on any platform.

Picker

Renders the native picker component on Android and iOS.

Slider

A component used to select a single value from a range of values.

Switch

Renders a boolean input.

List Views

Unlike the more generic ScrollView, the following list view components only render elements that are currently showing on the screen. This makes them a great choice for displaying long lists of data.

FlatList

A component for rendering performant scrollable lists.

SectionList

Like FlatList, but for sectioned lists.

iOS Components and APIs

Many of the following components provide wrappers for commonly used UIKit classes.

ActionSheetIOS

API to display an iOS action sheet or share sheet.

AlertIOS

Create an iOS alert dialog with a message or create a prompt for user input.

DatePickerIOS

Renders a date/time picker (selector) on iOS.

ImagePickerIOS

Renders a image picker on iOS.

ProgressViewIOS

Renders a UIProgressView on iOS.

PushNotificationIOS

Handle push notifications for your app, including permission handling and icon badge number.

SegmentedControlIOS

Renders a UISegmentedControl on iOS.

Android Components and APIs

Many of the following components provide wrappers for commonly used Android classes.

BackHandler

Detect hardware button presses for back navigation.

DatePickerAndroid

Opens the standard Android date picker dialog.

DrawerLayoutAndroid

Renders a DrawerLayout on Android.

PermissionsAndroid

Provides access to the permissions model introduced in Android M.

ProgressBarAndroid

Renders a ProgressBar on Android.

TimePickerAndroid

Opens the standard Android time picker dialog.

ToastAndroid

Create an Android Toast alert.

ToolbarAndroid

Renders a Toolbar on Android.

ViewPagerAndroid

Container that allows to flip left and right between child views.

Others

These components may come in handy for certain applications. For an exhaustive list of components and APIs, check out the sidebar to the left.

ActivityIndicator

Displays a circular loading indicator.

Alert

Launches an alert dialog with the specified title and message.

Animated

A library for creating fluid, powerful animations that are easy to build and maintain.

Clipboard

Provides an interface for setting and getting content from the clipboard on both Android and iOS.

Dimensions

Provides an interface for getting device dimensions.

KeyboardAvoidingView

Provides a view that moves out of the way of the virtual keyboard automatically.

Linking

Provides a general interface to interact with both incoming and outgoing app links.

Modal

Provides a simple way to present content above an enclosing view.

PixelRatio

Provides access to the device pixel density.

RefreshControl

This component is used inside a ScrollView to add pull to refresh functionality.

StatusBar

Component to control the app status bar.

Edit this page
Last updated on
- + diff --git a/docs/0.61/components-and-apis/index.html b/docs/0.61/components-and-apis/index.html index 4ca59c7ff50..e02963e3906 100644 --- a/docs/0.61/components-and-apis/index.html +++ b/docs/0.61/components-and-apis/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Components and APIs

React Native provides a number of Core 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.

Text

A component for displaying text.

Image

A component for displaying images.

TextInput

A component for inputting text into the app via a keyboard.

ScrollView

Provides a scrolling container that can host multiple components and views.

StyleSheet

Provides an abstraction layer similar to CSS stylesheets.

User Interface

Render common user interface controls on any platform using the following components. For platform specific components, keep reading.

Button

A basic button component for handling touches that should render nicely on any platform.

Picker

Renders the native picker component on Android and iOS.

Slider

A component used to select a single value from a range of values.

Switch

Renders a boolean input.

List Views

Unlike the more generic ScrollView, the following list view components only render elements that are currently showing on the screen. This makes them a great choice for displaying long lists of data.

FlatList

A component for rendering performant scrollable lists.

SectionList

Like FlatList, but for sectioned lists.

iOS Components and APIs

Many of the following components provide wrappers for commonly used UIKit classes.

ActionSheetIOS

API to display an iOS action sheet or share sheet.

AlertIOS

Create an iOS alert dialog with a message or create a prompt for user input.

DatePickerIOS

Renders a date/time picker (selector) on iOS.

ImagePickerIOS

Renders a image picker on iOS.

ProgressViewIOS

Renders a UIProgressView on iOS.

PushNotificationIOS

Handle push notifications for your app, including permission handling and icon badge number.

SegmentedControlIOS

Renders a UISegmentedControl on iOS.

Android Components and APIs

Many of the following components provide wrappers for commonly used Android classes.

BackHandler

Detect hardware button presses for back navigation.

DatePickerAndroid

Opens the standard Android date picker dialog.

DrawerLayoutAndroid

Renders a DrawerLayout on Android.

PermissionsAndroid

Provides access to the permissions model introduced in Android M.

ProgressBarAndroid

Renders a ProgressBar on Android.

TimePickerAndroid

Opens the standard Android time picker dialog.

ToastAndroid

Create an Android Toast alert.

ToolbarAndroid

Renders a Toolbar on Android.

ViewPagerAndroid

Container that allows to flip left and right between child views.

Others

These components may come in handy for certain applications. For an exhaustive list of components and APIs, check out the sidebar to the left.

ActivityIndicator

Displays a circular loading indicator.

Alert

Launches an alert dialog with the specified title and message.

Animated

A library for creating fluid, powerful animations that are easy to build and maintain.

Clipboard

Provides an interface for setting and getting content from the clipboard on both Android and iOS.

Dimensions

Provides an interface for getting device dimensions.

KeyboardAvoidingView

Provides a view that moves out of the way of the virtual keyboard automatically.

Linking

Provides a general interface to interact with both incoming and outgoing app links.

Modal

Provides a simple way to present content above an enclosing view.

PixelRatio

Provides access to the device pixel density.

RefreshControl

This component is used inside a ScrollView to add pull to refresh functionality.

StatusBar

Component to control the app status bar.

Edit this page
Last updated on
- + diff --git a/docs/0.61/custom-webview-android.html b/docs/0.61/custom-webview-android.html index 989ca7e9266..6768c7a5343 100644 --- a/docs/0.61/custom-webview-android.html +++ b/docs/0.61/custom-webview-android.html @@ -19,7 +19,7 @@ - + @@ -60,7 +60,7 @@
render() {
return (
<WebView
{...this.props}
nativeConfig={{
component: RCTCustomWebView,
props: {
finalUrl: this.props.finalUrl,
onNavigationCompleted: this._onNavigationCompleted
}
}}
/>
);
}
}

Similar to regular native components, you must provide all your prop types in the component to have them forwarded on to the native component. However, if you have some prop types that are only used internally in component, you can add them to the nativeOnly property of the third argument previously mentioned. For event handlers, you have to use the value true instead of a regular prop type.

For example, if you wanted to add an internal event handler called onScrollToBottom, you would use,

const RCTCustomWebView = requireNativeComponent(
'RCTCustomWebView',
CustomWebView,
{
...WebView.extraNativeComponentConfig,
nativeOnly: {
...WebView.extraNativeComponentConfig.nativeOnly,
onScrollToBottom: true
}
}
);
Edit this page
Last updated on
- + diff --git a/docs/0.61/custom-webview-android/index.html b/docs/0.61/custom-webview-android/index.html index 989ca7e9266..6768c7a5343 100644 --- a/docs/0.61/custom-webview-android/index.html +++ b/docs/0.61/custom-webview-android/index.html @@ -19,7 +19,7 @@ - + @@ -60,7 +60,7 @@
render() {
return (
<WebView
{...this.props}
nativeConfig={{
component: RCTCustomWebView,
props: {
finalUrl: this.props.finalUrl,
onNavigationCompleted: this._onNavigationCompleted
}
}}
/>
);
}
}

Similar to regular native components, you must provide all your prop types in the component to have them forwarded on to the native component. However, if you have some prop types that are only used internally in component, you can add them to the nativeOnly property of the third argument previously mentioned. For event handlers, you have to use the value true instead of a regular prop type.

For example, if you wanted to add an internal event handler called onScrollToBottom, you would use,

const RCTCustomWebView = requireNativeComponent(
'RCTCustomWebView',
CustomWebView,
{
...WebView.extraNativeComponentConfig,
nativeOnly: {
...WebView.extraNativeComponentConfig.nativeOnly,
onScrollToBottom: true
}
}
);
Edit this page
Last updated on
- + diff --git a/docs/0.61/custom-webview-ios.html b/docs/0.61/custom-webview-ios.html index 8dd43b60c49..1daafb0cc8d 100644 --- a/docs/0.61/custom-webview-ios.html +++ b/docs/0.61/custom-webview-ios.html @@ -19,7 +19,7 @@ - + @@ -63,7 +63,7 @@
render() {
return (
<WebView
{...this.props}
nativeConfig={{
component: RCTCustomWebView,
props: {
finalUrl: this.props.finalUrl,
onNavigationCompleted: this._onNavigationCompleted
},
viewManager: CustomWebViewManager
}}
/>
);
}
}

Similar to regular native components, you must provide all your prop types in the component to have them forwarded on to the native component. However, if you have some prop types that are only used internally in component, you can add them to the nativeOnly property of the third argument previously mentioned. For event handlers, you have to use the value true instead of a regular prop type.

For example, if you wanted to add an internal event handler called onScrollToBottom, you would use,

const RCTCustomWebView = requireNativeComponent(
'RCTCustomWebView',
CustomWebView,
{
...WebView.extraNativeComponentConfig,
nativeOnly: {
...WebView.extraNativeComponentConfig.nativeOnly,
onScrollToBottom: true
}
}
);
Edit this page
Last updated on
- + diff --git a/docs/0.61/custom-webview-ios/index.html b/docs/0.61/custom-webview-ios/index.html index 8dd43b60c49..1daafb0cc8d 100644 --- a/docs/0.61/custom-webview-ios/index.html +++ b/docs/0.61/custom-webview-ios/index.html @@ -19,7 +19,7 @@ - + @@ -63,7 +63,7 @@
render() {
return (
<WebView
{...this.props}
nativeConfig={{
component: RCTCustomWebView,
props: {
finalUrl: this.props.finalUrl,
onNavigationCompleted: this._onNavigationCompleted
},
viewManager: CustomWebViewManager
}}
/>
);
}
}

Similar to regular native components, you must provide all your prop types in the component to have them forwarded on to the native component. However, if you have some prop types that are only used internally in component, you can add them to the nativeOnly property of the third argument previously mentioned. For event handlers, you have to use the value true instead of a regular prop type.

For example, if you wanted to add an internal event handler called onScrollToBottom, you would use,

const RCTCustomWebView = requireNativeComponent(
'RCTCustomWebView',
CustomWebView,
{
...WebView.extraNativeComponentConfig,
nativeOnly: {
...WebView.extraNativeComponentConfig.nativeOnly,
onScrollToBottom: true
}
}
);
Edit this page
Last updated on
- + diff --git a/docs/0.61/datepickerandroid.html b/docs/0.61/datepickerandroid.html index 9fe5c494a0e..4f1a18e4418 100644 --- a/docs/0.61/datepickerandroid.html +++ b/docs/0.61/datepickerandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 DatePickerAndroid

Deprecated. Use @react-native-community/datetimepicker instead.

Opens the standard Android date picker dialog.

DatePickerAndroid has been merged with DatePickerIOS and TimePickerAndroid into a single component called DateTimePicker and will be removed in a future release.

Example

try {
const {
action,
year,
month,
day
} = await DatePickerAndroid.open({
// Use `new Date()` for current date.
// May 25 2020. Month 0 is January.
date: new Date(2020, 4, 25)
});
if (action !== DatePickerAndroid.dismissedAction) {
// Selected year, month (0-11), day
}
} catch ({ code, message }) {
console.warn('Cannot open date picker', message);
}

Reference

Methods

open()

static open(options)

Opens the standard Android date picker dialog.

The available keys for the options object are:

  • date (Date object or timestamp in milliseconds) - date to show by default
  • minDate (Date or timestamp in milliseconds) - minimum date that can be selected
  • maxDate (Date object or timestamp in milliseconds) - maximum date that can be selected
  • mode (enum('calendar', 'spinner', 'default')) - To set the date-picker mode to calendar/spinner/default
    • 'calendar': Show a date picker in calendar mode.
    • 'spinner': Show a date picker in spinner mode.
    • 'default': Show a default native date picker(spinner/calendar) based on android versions.

Returns a Promise which will be invoked an object containing action, year, month (0-11), 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 is equal to DatePickerAndroid.dateSetAction 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.

dateSetAction()

static dateSetAction()

A date has been selected.

dismissedAction()

static dismissedAction()

The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/0.61/datepickerandroid/index.html b/docs/0.61/datepickerandroid/index.html index 9fe5c494a0e..4f1a18e4418 100644 --- a/docs/0.61/datepickerandroid/index.html +++ b/docs/0.61/datepickerandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 DatePickerAndroid

Deprecated. Use @react-native-community/datetimepicker instead.

Opens the standard Android date picker dialog.

DatePickerAndroid has been merged with DatePickerIOS and TimePickerAndroid into a single component called DateTimePicker and will be removed in a future release.

Example

try {
const {
action,
year,
month,
day
} = await DatePickerAndroid.open({
// Use `new Date()` for current date.
// May 25 2020. Month 0 is January.
date: new Date(2020, 4, 25)
});
if (action !== DatePickerAndroid.dismissedAction) {
// Selected year, month (0-11), day
}
} catch ({ code, message }) {
console.warn('Cannot open date picker', message);
}

Reference

Methods

open()

static open(options)

Opens the standard Android date picker dialog.

The available keys for the options object are:

  • date (Date object or timestamp in milliseconds) - date to show by default
  • minDate (Date or timestamp in milliseconds) - minimum date that can be selected
  • maxDate (Date object or timestamp in milliseconds) - maximum date that can be selected
  • mode (enum('calendar', 'spinner', 'default')) - To set the date-picker mode to calendar/spinner/default
    • 'calendar': Show a date picker in calendar mode.
    • 'spinner': Show a date picker in spinner mode.
    • 'default': Show a default native date picker(spinner/calendar) based on android versions.

Returns a Promise which will be invoked an object containing action, year, month (0-11), 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 is equal to DatePickerAndroid.dateSetAction 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.

dateSetAction()

static dateSetAction()

A date has been selected.

dismissedAction()

static dismissedAction()

The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/0.61/datepickerios.html b/docs/0.61/datepickerios.html index 14586f72bd1..adf59d1bc4e 100644 --- a/docs/0.61/datepickerios.html +++ b/docs/0.61/datepickerios.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'center'
}
});

Reference

Props

Inherits View Props.

date

The currently selected date.

TypeRequired
DateYes

onChange

Date change handler.

This is called when the user changes the date or time in the UI. The first and only argument is an Event. For getting the date the picker was changed to, use onDateChange instead.

TypeRequired
functionNo

onDateChange

Date change handler.

This is called when the user changes the date or time in the UI. The first and only argument is a Date object representing the new date and time.

TypeRequired
functionYes

maximumDate

Maximum date.

Restricts the range of possible date/time values.

TypeRequired
DateNo

Example with maximumDate set to December 31, 2017:

minimumDate

Minimum date.

Restricts the range of possible date/time values.

TypeRequired
DateNo

See maximumDate for an example image.

minuteInterval

The interval at which minutes can be selected.

TypeRequired
enum(1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30)No

Example with minuteInterval set to 10:

mode

The date picker mode.

TypeRequired
enum('date', 'time', 'datetime', 'countdown')No

Example with mode set to date, time, and datetime:

locale

The locale for the date picker. Value needs to be a Locale ID.

TypeRequired
StringNo

timeZoneOffsetInMinutes

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.

TypeRequired
numberNo

initialDate

Provides an initial value that will change when the user starts selecting a date. It is useful for use-cases where you do not want to deal with listening to events and updating the date prop to keep the controlled state in sync. The controlled state has known bugs which causes it to go out of sync with native. The initialDate prop is intended to allow you to have native be source of truth.

TypeRequired
DateNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/datepickerios/index.html b/docs/0.61/datepickerios/index.html index 14586f72bd1..adf59d1bc4e 100644 --- a/docs/0.61/datepickerios/index.html +++ b/docs/0.61/datepickerios/index.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'center'
}
});

Reference

Props

Inherits View Props.

date

The currently selected date.

TypeRequired
DateYes

onChange

Date change handler.

This is called when the user changes the date or time in the UI. The first and only argument is an Event. For getting the date the picker was changed to, use onDateChange instead.

TypeRequired
functionNo

onDateChange

Date change handler.

This is called when the user changes the date or time in the UI. The first and only argument is a Date object representing the new date and time.

TypeRequired
functionYes

maximumDate

Maximum date.

Restricts the range of possible date/time values.

TypeRequired
DateNo

Example with maximumDate set to December 31, 2017:

minimumDate

Minimum date.

Restricts the range of possible date/time values.

TypeRequired
DateNo

See maximumDate for an example image.

minuteInterval

The interval at which minutes can be selected.

TypeRequired
enum(1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30)No

Example with minuteInterval set to 10:

mode

The date picker mode.

TypeRequired
enum('date', 'time', 'datetime', 'countdown')No

Example with mode set to date, time, and datetime:

locale

The locale for the date picker. Value needs to be a Locale ID.

TypeRequired
StringNo

timeZoneOffsetInMinutes

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.

TypeRequired
numberNo

initialDate

Provides an initial value that will change when the user starts selecting a date. It is useful for use-cases where you do not want to deal with listening to events and updating the date prop to keep the controlled state in sync. The controlled state has known bugs which causes it to go out of sync with native. The initialDate prop is intended to allow you to have native be source of truth.

TypeRequired
DateNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/debugging.html b/docs/0.61/debugging.html index cb1866b89d3..c3106879300 100644 --- a/docs/0.61/debugging.html +++ b/docs/0.61/debugging.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Debugging

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 on Mac OS and Ctrl+M on Windows and Linux. Alternatively for Android, you can run the command adb shell input keyevent 82 to open the dev menu (82 being the Menu key code).

The Developer Menu is disabled in release (production) builds.

Enabling Fast Refresh

Fast Refresh is a React Native feature that allows you to get near-instant feedback for changes in your React components. While debugging, it can help to have Fast Refresh enabled. Fast Refresh is enabled by default, and you can toggle "Enable Fast Refresh" in the React Native developer menu. When enabled, most of your edits should be visible within a second or two.

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.

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:

import { YellowBox } from 'react-native';
YellowBox.ignoreWarnings(['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.

Safari Developer Tools

You can use Safari to debug the iOS version of your app without having to enable "Debug JS Remotely".

  • Enable Develop menu in Safari: Preferences → Advanced → Select "Show Develop menu in menu bar"
  • Select your app's JSContext: Develop → Simulator → JSContext
  • Safari's Web Inspector should open which has a Console and a Debugger

However, there are some disadvantages:

  1. No sourcemaps when debugging
  2. Every time the app is reloaded (using live reload, or by manually reloading), a new JSContext is created. Choosing "Automatically Show Web Inspectors for JSContexts" saves you from having to select the latest JSContext manually.

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:

npm install -g react-devtools

Now run react-devtools from the terminal to launch the standalone DevTools app:

react-devtools

React DevTools

It should connect to your simulator within a few seconds.

Note: if you prefer to avoid global installations, you can add react-devtools as a project dependency. Add the react-devtools package to your project using npm install --save-dev react-devtools, then add "react-devtools": "react-devtools" to the scripts section in your package.json, and then run npm run react-devtools from your project folder to open the DevTools.

Integration with React Native Inspector

Open the in-app developer menu and choose "Toggle Inspector". It will bring up an overlay that lets you tap on any UI element and see information about it:

React Native Inspector

However, when react-devtools is running, Inspector will enter a 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:

React DevTools Inspector Integration

You can choose "Toggle 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.

React DevTools Chrome Console Integration

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

Accessing console logs

You can display the console logs for an iOS or Android app by using the following commands in a terminal while the app is running:

$ react-native log-ios
$ react-native log-android

You may also access these through Debug → Open System Log... in the iOS Simulator or by running adb logcat *:S ReactNative:V ReactNativeJS:V in a terminal while an Android app is running on a device or emulator.

If you're using Create React Native App or Expo CLI, console logs already appear in the same terminal output as the bundler.

Debugging on a device with Chrome Developer Tools

If you're using Create React Native App or Expo CLI, this is configured for you already.

On iOS devices, open the file RCTWebSocketExecutor.m and change "localhost" to the IP address of your computer, then select "Debug JS Remotely" from the Developer Menu.

On Android 5.0+ devices connected via USB, you can use the adb command line tool to setup port forwarding from the device to your computer:

adb reverse tcp:8081 tcp:8081

Alternatively, select "Dev Settings" from the Developer Menu, then update the "Debug server host for device" setting to match the IP address of your computer.

If you run into any issues, it may be possible that one of your Chrome extensions is interacting in unexpected ways with the debugger. Try disabling all of your extensions and re-enabling them one-by-one until you find the problematic extension.

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.

Edit this page
Last updated on
- + diff --git a/docs/0.61/debugging/index.html b/docs/0.61/debugging/index.html index cb1866b89d3..c3106879300 100644 --- a/docs/0.61/debugging/index.html +++ b/docs/0.61/debugging/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Debugging

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 on Mac OS and Ctrl+M on Windows and Linux. Alternatively for Android, you can run the command adb shell input keyevent 82 to open the dev menu (82 being the Menu key code).

The Developer Menu is disabled in release (production) builds.

Enabling Fast Refresh

Fast Refresh is a React Native feature that allows you to get near-instant feedback for changes in your React components. While debugging, it can help to have Fast Refresh enabled. Fast Refresh is enabled by default, and you can toggle "Enable Fast Refresh" in the React Native developer menu. When enabled, most of your edits should be visible within a second or two.

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.

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:

import { YellowBox } from 'react-native';
YellowBox.ignoreWarnings(['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.

Safari Developer Tools

You can use Safari to debug the iOS version of your app without having to enable "Debug JS Remotely".

  • Enable Develop menu in Safari: Preferences → Advanced → Select "Show Develop menu in menu bar"
  • Select your app's JSContext: Develop → Simulator → JSContext
  • Safari's Web Inspector should open which has a Console and a Debugger

However, there are some disadvantages:

  1. No sourcemaps when debugging
  2. Every time the app is reloaded (using live reload, or by manually reloading), a new JSContext is created. Choosing "Automatically Show Web Inspectors for JSContexts" saves you from having to select the latest JSContext manually.

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:

npm install -g react-devtools

Now run react-devtools from the terminal to launch the standalone DevTools app:

react-devtools

React DevTools

It should connect to your simulator within a few seconds.

Note: if you prefer to avoid global installations, you can add react-devtools as a project dependency. Add the react-devtools package to your project using npm install --save-dev react-devtools, then add "react-devtools": "react-devtools" to the scripts section in your package.json, and then run npm run react-devtools from your project folder to open the DevTools.

Integration with React Native Inspector

Open the in-app developer menu and choose "Toggle Inspector". It will bring up an overlay that lets you tap on any UI element and see information about it:

React Native Inspector

However, when react-devtools is running, Inspector will enter a 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:

React DevTools Inspector Integration

You can choose "Toggle 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.

React DevTools Chrome Console Integration

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

Accessing console logs

You can display the console logs for an iOS or Android app by using the following commands in a terminal while the app is running:

$ react-native log-ios
$ react-native log-android

You may also access these through Debug → Open System Log... in the iOS Simulator or by running adb logcat *:S ReactNative:V ReactNativeJS:V in a terminal while an Android app is running on a device or emulator.

If you're using Create React Native App or Expo CLI, console logs already appear in the same terminal output as the bundler.

Debugging on a device with Chrome Developer Tools

If you're using Create React Native App or Expo CLI, this is configured for you already.

On iOS devices, open the file RCTWebSocketExecutor.m and change "localhost" to the IP address of your computer, then select "Debug JS Remotely" from the Developer Menu.

On Android 5.0+ devices connected via USB, you can use the adb command line tool to setup port forwarding from the device to your computer:

adb reverse tcp:8081 tcp:8081

Alternatively, select "Dev Settings" from the Developer Menu, then update the "Debug server host for device" setting to match the IP address of your computer.

If you run into any issues, it may be possible that one of your Chrome extensions is interacting in unexpected ways with the debugger. Try disabling all of your extensions and re-enabling them one-by-one until you find the problematic extension.

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.

Edit this page
Last updated on
- + diff --git a/docs/0.61/devsettings.html b/docs/0.61/devsettings.html index a667499b2b3..1ea43c45d24 100644 --- a/docs/0.61/devsettings.html +++ b/docs/0.61/devsettings.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

DevSettings

The DevSettings module exposes methods for customizing settings for developers in development.

Reference

Methods

addMenuItem()

static addMenuItem(title: string, handler: function)

Add a custom menu item to the developer menu:

DevSettings.addMenuItem('Show Secret Dev Screen', () => {
Alert.alert('Showing secret dev screen!');
});

reload()

static reload()

Reload the application. Can be invoked directly or on user interaction:

<Button title="Reload" onPress={() => DevSettings.reload()} />
Edit this page
Last updated on
- + diff --git a/docs/0.61/devsettings/index.html b/docs/0.61/devsettings/index.html index a667499b2b3..1ea43c45d24 100644 --- a/docs/0.61/devsettings/index.html +++ b/docs/0.61/devsettings/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

DevSettings

The DevSettings module exposes methods for customizing settings for developers in development.

Reference

Methods

addMenuItem()

static addMenuItem(title: string, handler: function)

Add a custom menu item to the developer menu:

DevSettings.addMenuItem('Show Secret Dev Screen', () => {
Alert.alert('Showing secret dev screen!');
});

reload()

static reload()

Reload the application. Can be invoked directly or on user interaction:

<Button title="Reload" onPress={() => DevSettings.reload()} />
Edit this page
Last updated on
- + diff --git a/docs/0.61/dimensions.html b/docs/0.61/dimensions.html index f171ad1b901..b0dca46a61b 100644 --- a/docs/0.61/dimensions.html +++ b/docs/0.61/dimensions.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Dimensions

useWindowDimensions is the preffered API for React components. Unlike Dimensions, it updates as the window's dimensions update. This works nicely with the React paradigm.

import { Dimensions } from 'react-native';

You can get the application window's width and height using below code:

const windowWidth = Dimensions.get('window').width;
const windowHeight = Dimensions.get('window').height;

Although dimensions are available immediately, they may change (e.g due to device rotation, foldable devices etc) so any rendering logic or styles that depend on these constants should try to call this function on every render, rather than caching the value (for example, using inline styles rather than setting a value in a StyleSheet).

If you are targeting foldable devices or devices which can change the screen size or app window size, you can use the event listener available in the Dimensions module as shown in the below example.

Example

Reference

Methods

addEventListener()

static addEventListener(type, handler)

Add an event handler. Supported events:

  • change: Fires when a property within the Dimensions object changes. The argument to the event handler is an object with window and screen properties whose values are the same as the return values of Dimensions.get('window') and Dimensions.get('screen'), respectively.

get()

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 these constants should try to call this function on every render, rather than caching the value (for example, using inline styles rather than setting a value in a StyleSheet).

Example: var {height, width} = Dimensions.get('window');

@param {string} dim Name of dimension as defined when calling set. @returns {Object?} Value for the dimension.

For Android the window dimension will exclude the size used by the status bar (if not translucent) and bottom navigation bar

removeEventListener()

static removeEventListener(type, handler)

Remove an event handler.

set()

static set(dims)

This should only be called from native code by sending the didUpdateDimensions event.

@param {object} dims string-keyed object of dimensions to set

Edit this page
Last updated on
- + diff --git a/docs/0.61/dimensions/index.html b/docs/0.61/dimensions/index.html index f171ad1b901..b0dca46a61b 100644 --- a/docs/0.61/dimensions/index.html +++ b/docs/0.61/dimensions/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Dimensions

useWindowDimensions is the preffered API for React components. Unlike Dimensions, it updates as the window's dimensions update. This works nicely with the React paradigm.

import { Dimensions } from 'react-native';

You can get the application window's width and height using below code:

const windowWidth = Dimensions.get('window').width;
const windowHeight = Dimensions.get('window').height;

Although dimensions are available immediately, they may change (e.g due to device rotation, foldable devices etc) so any rendering logic or styles that depend on these constants should try to call this function on every render, rather than caching the value (for example, using inline styles rather than setting a value in a StyleSheet).

If you are targeting foldable devices or devices which can change the screen size or app window size, you can use the event listener available in the Dimensions module as shown in the below example.

Example

Reference

Methods

addEventListener()

static addEventListener(type, handler)

Add an event handler. Supported events:

  • change: Fires when a property within the Dimensions object changes. The argument to the event handler is an object with window and screen properties whose values are the same as the return values of Dimensions.get('window') and Dimensions.get('screen'), respectively.

get()

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 these constants should try to call this function on every render, rather than caching the value (for example, using inline styles rather than setting a value in a StyleSheet).

Example: var {height, width} = Dimensions.get('window');

@param {string} dim Name of dimension as defined when calling set. @returns {Object?} Value for the dimension.

For Android the window dimension will exclude the size used by the status bar (if not translucent) and bottom navigation bar

removeEventListener()

static removeEventListener(type, handler)

Remove an event handler.

set()

static set(dims)

This should only be called from native code by sending the didUpdateDimensions event.

@param {object} dims string-keyed object of dimensions to set

Edit this page
Last updated on
- + diff --git a/docs/0.61/direct-manipulation.html b/docs/0.61/direct-manipulation.html index 06f8ae8494f..90ac124174e 100644 --- a/docs/0.61/direct-manipulation.html +++ b/docs/0.61/direct-manipulation.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
render() {
return (
<TouchableOpacity onPress={() => this.setState({myButtonOpacity: 0.5})}
onPressOut={() => this.setState({myButtonOpacity: 1})}>
<View style={[styles.button, {opacity: this.state.myButtonOpacity}]}>
<Text>Press me!</Text>
</View>
</TouchableOpacity>
)
}

This is computationally intensive compared to the original example - React needs to re-render the component hierarchy each time the opacity changes, even though other properties of the view and its children haven't changed. Usually this overhead isn't a concern but when performing continuous animations and responding to gestures, judiciously optimizing your components can improve your animations' fidelity.

If you look at the implementation of setNativeProps in NativeMethodsMixin you will notice that it is a wrapper around RCTUIManager.updateView - this is the exact same function call that results from re-rendering - see receiveComponent in ReactNativeBaseComponent.

Composite components and setNativeProps

Composite components are not backed by a native view, so you cannot call setNativeProps on them. Consider this example:

If you run this you will immediately see this error: Touchable child must either be native or forward setNativeProps to a native component. This occurs because MyButton isn't directly backed by a native view whose opacity should be set. You can think about it like this: if you define a component with createReactClass you would not expect to be able to set a style prop on it and have that work - you would need to pass the style prop down to a child, unless you are wrapping a native component. Similarly, we are going to forward setNativeProps to a native-backed child component.

Forward setNativeProps to a child

All we need to do is provide a setNativeProps method on our component that calls setNativeProps on the appropriate child with the given arguments.

You can now use MyButton inside of TouchableOpacity! A sidenote for clarity: we used the ref callback syntax here, rather than the traditional string-based ref.

You may have noticed that we passed all of the props down to the child view using {...this.props}. The reason for this is that TouchableOpacity is actually a composite component, and so in addition to depending on setNativeProps on its child, it also requires that the child perform touch handling. To do this, it passes on various props that call back to the TouchableOpacity component. TouchableHighlight, in contrast, is backed by a native view and only requires that we implement setNativeProps.

setNativeProps to clear TextInput value

Another very common use case of setNativeProps is to clear the value of a TextInput. The controlled prop of TextInput can sometimes drop characters when the bufferDelay is low and the user types very quickly. Some developers prefer to skip this prop entirely and instead use setNativeProps to directly manipulate the TextInput value when necessary. For example, the following code demonstrates clearing the input when you tap a button:

Avoiding conflicts with the render function

If you update a property that is also managed by the render function, you might end up with some unpredictable and confusing bugs because anytime the component re-renders and that property changes, whatever value was previously set from setNativeProps will be completely ignored and overridden.

setNativeProps & shouldComponentUpdate

By intelligently applying shouldComponentUpdate you can avoid the unnecessary overhead involved in reconciling unchanged component subtrees, to the point where it may be performant enough to use setState instead of setNativeProps.

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:

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:

measureLayout(relativeToNativeNode, onSuccess, onFail)

Like measure(), but measures the view relative to 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 findNodeHandle(component).

import { findNodeHandle } from 'react-native';

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().

Edit this page
Last updated on
- + diff --git a/docs/0.61/direct-manipulation/index.html b/docs/0.61/direct-manipulation/index.html index 06f8ae8494f..90ac124174e 100644 --- a/docs/0.61/direct-manipulation/index.html +++ b/docs/0.61/direct-manipulation/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
render() {
return (
<TouchableOpacity onPress={() => this.setState({myButtonOpacity: 0.5})}
onPressOut={() => this.setState({myButtonOpacity: 1})}>
<View style={[styles.button, {opacity: this.state.myButtonOpacity}]}>
<Text>Press me!</Text>
</View>
</TouchableOpacity>
)
}

This is computationally intensive compared to the original example - React needs to re-render the component hierarchy each time the opacity changes, even though other properties of the view and its children haven't changed. Usually this overhead isn't a concern but when performing continuous animations and responding to gestures, judiciously optimizing your components can improve your animations' fidelity.

If you look at the implementation of setNativeProps in NativeMethodsMixin you will notice that it is a wrapper around RCTUIManager.updateView - this is the exact same function call that results from re-rendering - see receiveComponent in ReactNativeBaseComponent.

Composite components and setNativeProps

Composite components are not backed by a native view, so you cannot call setNativeProps on them. Consider this example:

If you run this you will immediately see this error: Touchable child must either be native or forward setNativeProps to a native component. This occurs because MyButton isn't directly backed by a native view whose opacity should be set. You can think about it like this: if you define a component with createReactClass you would not expect to be able to set a style prop on it and have that work - you would need to pass the style prop down to a child, unless you are wrapping a native component. Similarly, we are going to forward setNativeProps to a native-backed child component.

Forward setNativeProps to a child

All we need to do is provide a setNativeProps method on our component that calls setNativeProps on the appropriate child with the given arguments.

You can now use MyButton inside of TouchableOpacity! A sidenote for clarity: we used the ref callback syntax here, rather than the traditional string-based ref.

You may have noticed that we passed all of the props down to the child view using {...this.props}. The reason for this is that TouchableOpacity is actually a composite component, and so in addition to depending on setNativeProps on its child, it also requires that the child perform touch handling. To do this, it passes on various props that call back to the TouchableOpacity component. TouchableHighlight, in contrast, is backed by a native view and only requires that we implement setNativeProps.

setNativeProps to clear TextInput value

Another very common use case of setNativeProps is to clear the value of a TextInput. The controlled prop of TextInput can sometimes drop characters when the bufferDelay is low and the user types very quickly. Some developers prefer to skip this prop entirely and instead use setNativeProps to directly manipulate the TextInput value when necessary. For example, the following code demonstrates clearing the input when you tap a button:

Avoiding conflicts with the render function

If you update a property that is also managed by the render function, you might end up with some unpredictable and confusing bugs because anytime the component re-renders and that property changes, whatever value was previously set from setNativeProps will be completely ignored and overridden.

setNativeProps & shouldComponentUpdate

By intelligently applying shouldComponentUpdate you can avoid the unnecessary overhead involved in reconciling unchanged component subtrees, to the point where it may be performant enough to use setState instead of setNativeProps.

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:

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:

measureLayout(relativeToNativeNode, onSuccess, onFail)

Like measure(), but measures the view relative to 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 findNodeHandle(component).

import { findNodeHandle } from 'react-native';

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().

Edit this page
Last updated on
- + diff --git a/docs/0.61/drawerlayoutandroid.html b/docs/0.61/drawerlayoutandroid.html index e4d4414f7c8..6e26804b207 100644 --- a/docs/0.61/drawerlayoutandroid.html +++ b/docs/0.61/drawerlayoutandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

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 side of the window specified by the drawerPosition prop and its width can be set by the drawerWidth prop.

Example:

render: function() {
var navigationView = (
<View style={{flex: 1, backgroundColor: '#fff'}}>
<Text style={{margin: 10, fontSize: 15, textAlign: 'left'}}>I'm in the Drawer!</Text>
</View>
);
return (
<DrawerLayoutAndroid
drawerWidth={300}
drawerPosition={DrawerLayoutAndroid.positions.Left}
renderNavigationView={() => navigationView}>
<View style={{flex: 1, alignItems: 'center'}}>
<Text style={{margin: 10, fontSize: 15, textAlign: 'right'}}>Hello</Text>
<Text style={{margin: 10, fontSize: 15, textAlign: 'right'}}>World!</Text>
</View>
</DrawerLayoutAndroid>
);
},

Reference

Props

Inherits View Props.

renderNavigationView

The navigation view that will be rendered to the side of the screen and can be pulled in.

TypeRequired
functionYes

onDrawerClose

Function called whenever the navigation view has been closed.

TypeRequired
functionNo

drawerPosition

Specifies the side of the screen from which the drawer will slide in.

TypeRequired
enum(DrawerConsts.DrawerPosition.Left, DrawerConsts.DrawerPosition.Right)No

drawerWidth

Specifies the width of the drawer, more precisely the width of the view that be pulled in from the edge of the window.

TypeRequired
numberNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

  • 'none' (the default), drags do not dismiss the keyboard.
  • 'on-drag', the keyboard is dismissed when a drag begins.
TypeRequired
enum('none', 'on-drag')No

drawerLockMode

Specifies the lock mode of the drawer. The drawer can be locked in 3 states:

  • unlocked (default), meaning that the drawer will respond (open/close) to touch gestures.
  • locked-closed, meaning that the drawer will stay closed and not respond to gestures.
  • locked-open, meaning that the drawer will stay opened and not respond to gestures. The drawer may still be opened and closed programmatically (openDrawer/closeDrawer).
TypeRequired
enum('unlocked', 'locked-closed', 'locked-open')No

onDrawerOpen

Function called whenever the navigation view has been opened.

TypeRequired
functionNo

onDrawerSlide

Function called whenever there is an interaction with the navigation view.

TypeRequired
functionNo

onDrawerStateChanged

Function called when the drawer state has changed. The drawer can be in 3 states:

  • idle, meaning there is no interaction with the navigation view happening at the time
  • dragging, meaning there is currently an interaction with the navigation view
  • settling, meaning that there was an interaction with the navigation view, and the navigation view is now finishing its closing or opening animation
TypeRequired
functionNo

drawerBackgroundColor

Specifies the background color of the drawer. The default value is white. If you want to set the opacity of the drawer, use rgba. Example:

return (
<DrawerLayoutAndroid drawerBackgroundColor="rgba(0,0,0,0.5)" />
);
TypeRequired
colorNo

statusBarBackgroundColor

Make the drawer take the entire screen and draw the background of the status bar to allow it to open over the status bar. It will only have an effect on API 21+.

TypeRequired
colorNo

Methods

openDrawer()

openDrawer();

Opens the drawer.

closeDrawer()

closeDrawer();

Closes the drawer.

Edit this page
Last updated on
- + diff --git a/docs/0.61/drawerlayoutandroid/index.html b/docs/0.61/drawerlayoutandroid/index.html index e4d4414f7c8..6e26804b207 100644 --- a/docs/0.61/drawerlayoutandroid/index.html +++ b/docs/0.61/drawerlayoutandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

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 side of the window specified by the drawerPosition prop and its width can be set by the drawerWidth prop.

Example:

render: function() {
var navigationView = (
<View style={{flex: 1, backgroundColor: '#fff'}}>
<Text style={{margin: 10, fontSize: 15, textAlign: 'left'}}>I'm in the Drawer!</Text>
</View>
);
return (
<DrawerLayoutAndroid
drawerWidth={300}
drawerPosition={DrawerLayoutAndroid.positions.Left}
renderNavigationView={() => navigationView}>
<View style={{flex: 1, alignItems: 'center'}}>
<Text style={{margin: 10, fontSize: 15, textAlign: 'right'}}>Hello</Text>
<Text style={{margin: 10, fontSize: 15, textAlign: 'right'}}>World!</Text>
</View>
</DrawerLayoutAndroid>
);
},

Reference

Props

Inherits View Props.

renderNavigationView

The navigation view that will be rendered to the side of the screen and can be pulled in.

TypeRequired
functionYes

onDrawerClose

Function called whenever the navigation view has been closed.

TypeRequired
functionNo

drawerPosition

Specifies the side of the screen from which the drawer will slide in.

TypeRequired
enum(DrawerConsts.DrawerPosition.Left, DrawerConsts.DrawerPosition.Right)No

drawerWidth

Specifies the width of the drawer, more precisely the width of the view that be pulled in from the edge of the window.

TypeRequired
numberNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

  • 'none' (the default), drags do not dismiss the keyboard.
  • 'on-drag', the keyboard is dismissed when a drag begins.
TypeRequired
enum('none', 'on-drag')No

drawerLockMode

Specifies the lock mode of the drawer. The drawer can be locked in 3 states:

  • unlocked (default), meaning that the drawer will respond (open/close) to touch gestures.
  • locked-closed, meaning that the drawer will stay closed and not respond to gestures.
  • locked-open, meaning that the drawer will stay opened and not respond to gestures. The drawer may still be opened and closed programmatically (openDrawer/closeDrawer).
TypeRequired
enum('unlocked', 'locked-closed', 'locked-open')No

onDrawerOpen

Function called whenever the navigation view has been opened.

TypeRequired
functionNo

onDrawerSlide

Function called whenever there is an interaction with the navigation view.

TypeRequired
functionNo

onDrawerStateChanged

Function called when the drawer state has changed. The drawer can be in 3 states:

  • idle, meaning there is no interaction with the navigation view happening at the time
  • dragging, meaning there is currently an interaction with the navigation view
  • settling, meaning that there was an interaction with the navigation view, and the navigation view is now finishing its closing or opening animation
TypeRequired
functionNo

drawerBackgroundColor

Specifies the background color of the drawer. The default value is white. If you want to set the opacity of the drawer, use rgba. Example:

return (
<DrawerLayoutAndroid drawerBackgroundColor="rgba(0,0,0,0.5)" />
);
TypeRequired
colorNo

statusBarBackgroundColor

Make the drawer take the entire screen and draw the background of the status bar to allow it to open over the status bar. It will only have an effect on API 21+.

TypeRequired
colorNo

Methods

openDrawer()

openDrawer();

Opens the drawer.

closeDrawer()

closeDrawer();

Closes the drawer.

Edit this page
Last updated on
- + diff --git a/docs/0.61/easing.html b/docs/0.61/easing.html index e7112b2246c..f92d1f306f1 100644 --- a/docs/0.61/easing.html +++ b/docs/0.61/easing.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Easing

The Easing module implements common easing functions. This module is used by Animated.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 following methods:

  • back provides a basic animation where the object goes slightly back before moving forward
  • bounce provides a bouncing animation
  • ease provides a basic inertial animation
  • elastic provides a basic spring interaction

Standard functions

Three standard easing functions are provided:

The poly function can be used to implement quartic, quintic, and other higher power functions.

Additional functions

Additional mathematical functions are provided by the following methods:

  • bezier provides a cubic bezier curve
  • circle provides a circular function
  • sin provides a sinusoidal function
  • exp provides an exponential function

The following helpers are used to modify other easing functions.

  • in runs an easing function forwards
  • inOut makes any easing function symmetrical
  • out runs an easing function backwards

Reference

Methods

step0()

static step0(n)

A stepping function, returns 1 for any positive value of n.

step1()

static step1(n)

A stepping function, returns 1 if n is greater than or equal to 1.

linear()

static linear(t)

A linear function, f(t) = t. Position correlates to elapsed time one to one.

http://cubic-bezier.com/#0,0,1,1

ease()

static ease(t)

A basic inertial interaction, similar to an object slowly accelerating to speed.

http://cubic-bezier.com/#.42,0,1,1

quad()

static quad(t)

A quadratic function, f(t) = t * t. Position equals the square of elapsed time.

http://easings.net/#easeInQuad

cubic()

static cubic(t)

A cubic function, f(t) = t * t * t. Position equals the cube of elapsed time.

http://easings.net/#easeInCubic

poly()

static poly(n)

A power function. Position is equal to the Nth power of elapsed time.

n = 4: http://easings.net/#easeInQuart n = 5: http://easings.net/#easeInQuint

sin()

static sin(t)

A sinusoidal function.

http://easings.net/#easeInSine

circle()

static circle(t)

A circular function.

http://easings.net/#easeInCirc

exp()

static exp(t)

An exponential function.

http://easings.net/#easeInExpo

elastic()

static elastic(bounciness)

A basic elastic interaction, similar to a spring oscillating back and forth.

Default bounciness is 1, which overshoots a little bit once. 0 bounciness doesn't overshoot at all, and bounciness of N > 1 will overshoot about N times.

http://easings.net/#easeInElastic

back()

static back(s)

Use with Animated.parallel() to create a basic effect where the object animates back slightly as the animation starts.

bounce()

static bounce(t)

Provides a basic bouncing effect.

http://easings.net/#easeInBounce

bezier()

static bezier(x1, y1, x2, y2)

Provides a cubic bezier curve, equivalent to CSS Transitions' transition-timing-function.

A useful tool to visualize cubic bezier curves can be found at http://cubic-bezier.com/

in()

static in easing;

Runs an easing function forwards.

out()

static out(easing)

Runs an easing function backwards.

inOut()

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.

Edit this page
Last updated on
- + diff --git a/docs/0.61/easing/index.html b/docs/0.61/easing/index.html index e7112b2246c..f92d1f306f1 100644 --- a/docs/0.61/easing/index.html +++ b/docs/0.61/easing/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Easing

The Easing module implements common easing functions. This module is used by Animated.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 following methods:

  • back provides a basic animation where the object goes slightly back before moving forward
  • bounce provides a bouncing animation
  • ease provides a basic inertial animation
  • elastic provides a basic spring interaction

Standard functions

Three standard easing functions are provided:

The poly function can be used to implement quartic, quintic, and other higher power functions.

Additional functions

Additional mathematical functions are provided by the following methods:

  • bezier provides a cubic bezier curve
  • circle provides a circular function
  • sin provides a sinusoidal function
  • exp provides an exponential function

The following helpers are used to modify other easing functions.

  • in runs an easing function forwards
  • inOut makes any easing function symmetrical
  • out runs an easing function backwards

Reference

Methods

step0()

static step0(n)

A stepping function, returns 1 for any positive value of n.

step1()

static step1(n)

A stepping function, returns 1 if n is greater than or equal to 1.

linear()

static linear(t)

A linear function, f(t) = t. Position correlates to elapsed time one to one.

http://cubic-bezier.com/#0,0,1,1

ease()

static ease(t)

A basic inertial interaction, similar to an object slowly accelerating to speed.

http://cubic-bezier.com/#.42,0,1,1

quad()

static quad(t)

A quadratic function, f(t) = t * t. Position equals the square of elapsed time.

http://easings.net/#easeInQuad

cubic()

static cubic(t)

A cubic function, f(t) = t * t * t. Position equals the cube of elapsed time.

http://easings.net/#easeInCubic

poly()

static poly(n)

A power function. Position is equal to the Nth power of elapsed time.

n = 4: http://easings.net/#easeInQuart n = 5: http://easings.net/#easeInQuint

sin()

static sin(t)

A sinusoidal function.

http://easings.net/#easeInSine

circle()

static circle(t)

A circular function.

http://easings.net/#easeInCirc

exp()

static exp(t)

An exponential function.

http://easings.net/#easeInExpo

elastic()

static elastic(bounciness)

A basic elastic interaction, similar to a spring oscillating back and forth.

Default bounciness is 1, which overshoots a little bit once. 0 bounciness doesn't overshoot at all, and bounciness of N > 1 will overshoot about N times.

http://easings.net/#easeInElastic

back()

static back(s)

Use with Animated.parallel() to create a basic effect where the object animates back slightly as the animation starts.

bounce()

static bounce(t)

Provides a basic bouncing effect.

http://easings.net/#easeInBounce

bezier()

static bezier(x1, y1, x2, y2)

Provides a cubic bezier curve, equivalent to CSS Transitions' transition-timing-function.

A useful tool to visualize cubic bezier curves can be found at http://cubic-bezier.com/

in()

static in easing;

Runs an easing function forwards.

out()

static out(easing)

Runs an easing function backwards.

inOut()

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.

Edit this page
Last updated on
- + diff --git a/docs/0.61/enviroment-setup.html b/docs/0.61/enviroment-setup.html index dace96effdb..83527bf45a9 100644 --- a/docs/0.61/enviroment-setup.html +++ b/docs/0.61/enviroment-setup.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
cd AwesomeProject
npm start # you can also use: expo start

This will start a development server for you.

Running your React Native application

Install the Expo client app on your iOS or Android phone and connect to the same wireless network as your computer. On Android, use the Expo app to scan the QR code from your terminal to open your project. On iOS, use the built-in QR code scanner of the Camera app.

Modifying your app

Now that you have successfully run the app, let's modify it. Open App.js in your text editor of choice and edit some lines. The application should reload automatically once you save your changes.

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

Expo also has docs you can reference if you have questions specific to the tool. You can also ask for help at Expo forums.

These tools help you get started quickly, but before committing to building your app with Expo CLI, read about the limitations.

If you have a problem with Expo, before creating a new issue, please see if there's an existing issue about it:

If you're curious to learn more about React Native, check out the Introduction to React Native.

Running your app on a simulator or virtual device

Expo CLI allows you to run your React Native app on a physical device without setting up a development environment. If you want to run your app on the iOS Simulator or an Android Virtual Device, please refer to the instructions for "React Native CLI Quickstart" to learn how to install Xcode or set up your Android development environment.

Once you've set these up, you can launch your app on an Android Virtual Device by running npm run android, or on the iOS Simulator by running npm run ios (macOS only).

Caveats

Because you don't build any native code when using Expo to create a project, it's not possible to include custom native modules beyond the React Native APIs and components that are available in the Expo client app.

If you know that you'll eventually need to include your own native code, Expo is still a good way to get started. In that case you'll need to "eject" eventually to create your own native builds. If you do eject, the "React Native CLI Quickstart" instructions will be required to continue working on your project.

Expo CLI configures your project to use the most recent React Native version that is supported by the Expo client app. The Expo client app usually gains support for a given React Native version about a week after the React Native version is released as stable. You can check this document to find out what versions are supported.

If you're integrating React Native into an existing project, you'll want to skip Expo CLI and go directly to setting up the native build environment. Select "React Native CLI Quickstart" above for instructions on configuring a native build environment for React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.61/enviroment-setup/index.html b/docs/0.61/enviroment-setup/index.html index dace96effdb..83527bf45a9 100644 --- a/docs/0.61/enviroment-setup/index.html +++ b/docs/0.61/enviroment-setup/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
cd AwesomeProject
npm start # you can also use: expo start

This will start a development server for you.

Running your React Native application

Install the Expo client app on your iOS or Android phone and connect to the same wireless network as your computer. On Android, use the Expo app to scan the QR code from your terminal to open your project. On iOS, use the built-in QR code scanner of the Camera app.

Modifying your app

Now that you have successfully run the app, let's modify it. Open App.js in your text editor of choice and edit some lines. The application should reload automatically once you save your changes.

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

Expo also has docs you can reference if you have questions specific to the tool. You can also ask for help at Expo forums.

These tools help you get started quickly, but before committing to building your app with Expo CLI, read about the limitations.

If you have a problem with Expo, before creating a new issue, please see if there's an existing issue about it:

If you're curious to learn more about React Native, check out the Introduction to React Native.

Running your app on a simulator or virtual device

Expo CLI allows you to run your React Native app on a physical device without setting up a development environment. If you want to run your app on the iOS Simulator or an Android Virtual Device, please refer to the instructions for "React Native CLI Quickstart" to learn how to install Xcode or set up your Android development environment.

Once you've set these up, you can launch your app on an Android Virtual Device by running npm run android, or on the iOS Simulator by running npm run ios (macOS only).

Caveats

Because you don't build any native code when using Expo to create a project, it's not possible to include custom native modules beyond the React Native APIs and components that are available in the Expo client app.

If you know that you'll eventually need to include your own native code, Expo is still a good way to get started. In that case you'll need to "eject" eventually to create your own native builds. If you do eject, the "React Native CLI Quickstart" instructions will be required to continue working on your project.

Expo CLI configures your project to use the most recent React Native version that is supported by the Expo client app. The Expo client app usually gains support for a given React Native version about a week after the React Native version is released as stable. You can check this document to find out what versions are supported.

If you're integrating React Native into an existing project, you'll want to skip Expo CLI and go directly to setting up the native build environment. Select "React Native CLI Quickstart" above for instructions on configuring a native build environment for React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.61/fast-refresh.html b/docs/0.61/fast-refresh.html index e6c394fd9e4..f2caeaa3b57 100644 --- a/docs/0.61/fast-refresh.html +++ b/docs/0.61/fast-refresh.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Fast Refresh

Fast Refresh is a React Native feature that allows you to get near-instant feedback for changes in your React components. Fast Refresh is enabled by default, and you can toggle "Enable Fast Refresh" in the React Native developer menu. With Fast Refresh enabled, most edits should be visible within a second or two.

How It Works

  • If you edit a module that only exports React component(s), Fast Refresh will update the code only for that module, and re-render your component. You can edit anything in that file, including styles, rendering logic, event handlers, or effects.
  • If you edit a module with exports that aren't React components, Fast Refresh will re-run both that module, and the other modules importing it. So if both Button.js and Modal.js import Theme.js, editing Theme.js will update both components.
  • Finally, if you edit a file that's imported by modules outside of the React tree, Fast Refresh will fall back to doing a full reload. You might have a file which renders a React component but also exports a value that is imported by a non-React component. For example, maybe your component also exports a constant, and a non-React utility module imports it. In that case, consider migrating the query to a separate file and importing it into both files. This will re-enable Fast Refresh to work. Other cases can usually be solved in a similar way.

Error Resilience

If you make a syntax error during a Fast Refresh session, you can fix it and save the file again. The redbox will disappear. Modules with syntax errors are prevented from running, so you won't need to reload the app.

If you make a runtime error during the module initialization (for example, typing Style.create instead of StyleSheet.create), the Fast Refresh session will continue once you fix the error. The redbox will disappear, and the module will be updated.

If you make a mistake that leads to a runtime error inside your component, the Fast Refresh session will also continue after you fix the error. In that case, React will remount your application using the updated code.

If you have error boundaries in your app (which is a good idea for graceful failures in production), they will retry rendering on the next edit after a redbox. In that sense, having an error boundary can prevent you from always getting kicked out to the root app screen. However, keep in mind that error boundaries shouldn't be too granular. They are used by React in production, and should always be designed intentionally.

Limitations

Fast Refresh tries to preserve local React state in the component you're editing, but only if it's safe to do so. Here's a few reasons why you might see local state being reset on every edit to a file:

  • Local state is not preserved for class components (only function components and Hooks preserve state).
  • The module you're editing might have other exports in addition to a React component.
  • Sometimes, a module would export the result of calling higher-order component like createNavigationContainer(MyScreen). If the returned component is a class, state will be reset.

In longer term, as more of your codebase moves to function components and Hooks, you can expect state to be preserved in more cases.

Tips

  • Fast Refresh preserves React local state in function components (and Hooks) by default.
  • Sometimes you might want to force the state to be reset, and a component to be remounted. For example, this can be handy if you're tweaking an animation that only happens on mount. To do this, you can add // @refresh reset anywhere in the file you're editing. This directive is local to the file, and instructs Fast Refresh to remount components defined in that file on every edit.
  • You can put console.log or debugger; into the components you edit during a Fast Refresh session.
Edit this page
Last updated on
- + diff --git a/docs/0.61/fast-refresh/index.html b/docs/0.61/fast-refresh/index.html index e6c394fd9e4..f2caeaa3b57 100644 --- a/docs/0.61/fast-refresh/index.html +++ b/docs/0.61/fast-refresh/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Fast Refresh

Fast Refresh is a React Native feature that allows you to get near-instant feedback for changes in your React components. Fast Refresh is enabled by default, and you can toggle "Enable Fast Refresh" in the React Native developer menu. With Fast Refresh enabled, most edits should be visible within a second or two.

How It Works

  • If you edit a module that only exports React component(s), Fast Refresh will update the code only for that module, and re-render your component. You can edit anything in that file, including styles, rendering logic, event handlers, or effects.
  • If you edit a module with exports that aren't React components, Fast Refresh will re-run both that module, and the other modules importing it. So if both Button.js and Modal.js import Theme.js, editing Theme.js will update both components.
  • Finally, if you edit a file that's imported by modules outside of the React tree, Fast Refresh will fall back to doing a full reload. You might have a file which renders a React component but also exports a value that is imported by a non-React component. For example, maybe your component also exports a constant, and a non-React utility module imports it. In that case, consider migrating the query to a separate file and importing it into both files. This will re-enable Fast Refresh to work. Other cases can usually be solved in a similar way.

Error Resilience

If you make a syntax error during a Fast Refresh session, you can fix it and save the file again. The redbox will disappear. Modules with syntax errors are prevented from running, so you won't need to reload the app.

If you make a runtime error during the module initialization (for example, typing Style.create instead of StyleSheet.create), the Fast Refresh session will continue once you fix the error. The redbox will disappear, and the module will be updated.

If you make a mistake that leads to a runtime error inside your component, the Fast Refresh session will also continue after you fix the error. In that case, React will remount your application using the updated code.

If you have error boundaries in your app (which is a good idea for graceful failures in production), they will retry rendering on the next edit after a redbox. In that sense, having an error boundary can prevent you from always getting kicked out to the root app screen. However, keep in mind that error boundaries shouldn't be too granular. They are used by React in production, and should always be designed intentionally.

Limitations

Fast Refresh tries to preserve local React state in the component you're editing, but only if it's safe to do so. Here's a few reasons why you might see local state being reset on every edit to a file:

  • Local state is not preserved for class components (only function components and Hooks preserve state).
  • The module you're editing might have other exports in addition to a React component.
  • Sometimes, a module would export the result of calling higher-order component like createNavigationContainer(MyScreen). If the returned component is a class, state will be reset.

In longer term, as more of your codebase moves to function components and Hooks, you can expect state to be preserved in more cases.

Tips

  • Fast Refresh preserves React local state in function components (and Hooks) by default.
  • Sometimes you might want to force the state to be reset, and a component to be remounted. For example, this can be handy if you're tweaking an animation that only happens on mount. To do this, you can add // @refresh reset anywhere in the file you're editing. This directive is local to the file, and instructs Fast Refresh to remount components defined in that file on every edit.
  • You can put console.log or debugger; into the components you edit during a Fast Refresh session.
Edit this page
Last updated on
- + diff --git a/docs/0.61/flatlist.html b/docs/0.61/flatlist.html index a624b25163e..1010cc412a5 100644 --- a/docs/0.61/flatlist.html +++ b/docs/0.61/flatlist.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
this.viewabilityConfig = {
waitForInteraction: true,
viewAreaCoveragePercentThreshold: 95
}
}
<FlatList
viewabilityConfig={this.viewabilityConfig}
...

minimumViewTime

Minimum amount of time (in milliseconds) that an item must be physically viewable before the viewability callback will be fired. A high number means that scrolling through content without stopping will not mark the content as viewable.

viewAreaCoveragePercentThreshold

Percent of viewport that must be covered for a partially occluded item to count as "viewable", 0-100. Fully visible items are always considered viewable. A value of 0 means that a single pixel in the viewport makes the item viewable, and a value of 100 means that an item must be either entirely visible or cover the entire viewport to count as viewable.

itemVisiblePercentThreshold

Similar to viewAreaCoveragePercentThreshold, but considers the percent of the item that is visible, rather than the fraction of the viewable area it covers.

waitForInteraction

Nothing is considered viewable until the user scrolls or recordInteraction is called after render.

viewabilityConfigCallbackPairs

List of ViewabilityConfig/onViewableItemsChanged pairs. A specific onViewableItemsChanged will be called when its corresponding ViewabilityConfig's conditions are met. See ViewabilityHelper.js for flow type and further documentation.

TypeRequired
array of ViewabilityConfigCallbackPairNo

Methods

scrollToEnd()

scrollToEnd([params]);

Scrolls to the end of the content. May be janky without getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectNoSee below.

Valid params keys are:

scrollToIndex()

scrollToIndex(params);

Scrolls to the item at the specified index such that it is positioned in the viewable area such that viewPosition 0 places it at the top, 1 at the bottom, and 0.5 centered in the middle.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

scrollToItem()

scrollToItem(params);

Requires linear scan through data - use scrollToIndex instead if possible.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

scrollToOffset()

scrollToOffset(params);

Scroll to a specific content pixel offset in the list.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

recordInteraction()

recordInteraction();

Tells the list an interaction has occurred, 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()

flashScrollIndicators();

Displays the scroll indicators momentarily.

getScrollResponder()

getScrollResponder();

Provides a handle to the underlying scroll responder.

getScrollableNode()

getScrollableNode();

Provides a handle to the underlying scroll node.

Edit this page
Last updated on
- + diff --git a/docs/0.61/flatlist/index.html b/docs/0.61/flatlist/index.html index a624b25163e..1010cc412a5 100644 --- a/docs/0.61/flatlist/index.html +++ b/docs/0.61/flatlist/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
this.viewabilityConfig = {
waitForInteraction: true,
viewAreaCoveragePercentThreshold: 95
}
}
<FlatList
viewabilityConfig={this.viewabilityConfig}
...

minimumViewTime

Minimum amount of time (in milliseconds) that an item must be physically viewable before the viewability callback will be fired. A high number means that scrolling through content without stopping will not mark the content as viewable.

viewAreaCoveragePercentThreshold

Percent of viewport that must be covered for a partially occluded item to count as "viewable", 0-100. Fully visible items are always considered viewable. A value of 0 means that a single pixel in the viewport makes the item viewable, and a value of 100 means that an item must be either entirely visible or cover the entire viewport to count as viewable.

itemVisiblePercentThreshold

Similar to viewAreaCoveragePercentThreshold, but considers the percent of the item that is visible, rather than the fraction of the viewable area it covers.

waitForInteraction

Nothing is considered viewable until the user scrolls or recordInteraction is called after render.

viewabilityConfigCallbackPairs

List of ViewabilityConfig/onViewableItemsChanged pairs. A specific onViewableItemsChanged will be called when its corresponding ViewabilityConfig's conditions are met. See ViewabilityHelper.js for flow type and further documentation.

TypeRequired
array of ViewabilityConfigCallbackPairNo

Methods

scrollToEnd()

scrollToEnd([params]);

Scrolls to the end of the content. May be janky without getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectNoSee below.

Valid params keys are:

scrollToIndex()

scrollToIndex(params);

Scrolls to the item at the specified index such that it is positioned in the viewable area such that viewPosition 0 places it at the top, 1 at the bottom, and 0.5 centered in the middle.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

scrollToItem()

scrollToItem(params);

Requires linear scan through data - use scrollToIndex instead if possible.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

scrollToOffset()

scrollToOffset(params);

Scroll to a specific content pixel offset in the list.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

recordInteraction()

recordInteraction();

Tells the list an interaction has occurred, 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()

flashScrollIndicators();

Displays the scroll indicators momentarily.

getScrollResponder()

getScrollResponder();

Provides a handle to the underlying scroll responder.

getScrollableNode()

getScrollableNode();

Provides a handle to the underlying scroll node.

Edit this page
Last updated on
- + diff --git a/docs/0.61/flexbox.html b/docs/0.61/flexbox.html index 6535fca48cc..145f4780c92 100644 --- a/docs/0.61/flexbox.html +++ b/docs/0.61/flexbox.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

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 flexDirection defaulting to column instead of row, and the flex parameter only supporting a single number.

Flex

flex will define how your items are going to “fill” over the available space along your main axis. Space will be divided according to each element's flex property.

In the following example the red, yellow and the green views are all children in the container view that has flex: 1 set. The red view uses flex: 1 , the yellow view uses flex: 2 and the green view uses flex: 3 . 1+2+3 = 6 which means that the red view will get 1/6 of the space, the yellow 2/6 of the space and the green 3/6 of the space.

Flex

Flex Direction

flexDirection controls the direction in which the children of a node are laid out. This is also referred to as the main axis. The cross axis is the axis perpendicular to the main axis, or the axis which the wrapping lines are laid out in.

  • row Align children from left to right. If wrapping is enabled then the next line will start under the first item on the left of the container.

  • column (default value) Align children from top to bottom. If wrapping is enabled then the next line will start to the left first item on the top of the container.

  • row-reverse Align children from right to left. If wrapping is enabled then the next line will start under the first item on the right of the container.

  • column-reverse Align children from bottom to top. If wrapping is enabled then the next line will start to the left first item on the bottom of the container.

LEARN MORE HERE

Flex Direction

Layout Direction

Layout direction specifies the direction in which children and text in a hierarchy should be laid out. Layout direction also affects what edge start and end refer to. By default React Native lays out with LTR layout direction. In this mode start refers to left and end refers to right.

  • LTR (default value) Text and children are laid out from left to right. Margin and padding applied the start of an element are applied on the left side.

  • RTL Text and children are laid out from right to left. Margin and padding applied the start of an element are applied on the right side.

Justify Content

justifyContent describes how to align children within the main axis of their container. For example, you can use this property to center a child horizontally within a container with flexDirection set to row or vertically within a container with flexDirection set to column.

  • flex-start(default value) Align children of a container to the start of the container's main axis.

  • flex-end Align children of a container to the end of the container's main axis.

  • center Align children of a container in the center of the container's main axis.

  • space-between Evenly space of children across the container's main axis, distributing remaining space between the children.

  • space-around Evenly space of children across the container's main axis, distributing remaining space around the children. Compared to space-between using space-around will result in space being distributed to the beginning of the first child and end of the last child.

  • space-evenly Evenly distributed within the alignment container along the main axis. The spacing between each pair of adjacent items, the main-start edge and the first item, and the main-end edge and the last item, are all exactly the same.

LEARN MORE HERE

Justify Content

Align Items

alignItems describes how to align children along the cross axis of their container. Align items is very similar to justifyContent but instead of applying to the main axis, alignItems applies to the cross axis.

  • stretch (default value) Stretch children of a container to match the height of the container's cross axis.

  • flex-start Align children of a container to the start of the container's cross axis.

  • flex-end Align children of a container to the end of the container's cross axis.

  • center Align children of a container in the center of the container's cross axis.

  • baseline Align children of a container along a common baseline. Individual children can be set to be the reference baseline for their parents.

For stretch to have an effect, children must not have a fixed dimension along the secondary axis. In the following example, setting alignItems: stretch does nothing until the width: 50 is removed from the children.

LEARN MORE HERE

Align Items

Align Self

alignSelf has the same options and effect as alignItems but instead of affecting the children within a container, you can apply this property to a single child to change its alignment within its parent. alignSelf overrides any option set by the parent with alignItems.

Align Self

Align Content

alignContent defines the distribution of lines along the cross-axis. This only has effect when items are wrapped to multiple lines using flexWrap.

  • flex-start (default value) Align wrapped lines to the start of the container's cross axis.

  • flex-end Align wrapped lines to the end of the container's cross axis.

  • stretch wrapped lines to match the height of the container's cross axis.

  • center Align wrapped lines in the center of the container's cross axis.

  • space-between Evenly space wrapped lines across the container's main axis, distributing remaining space between the lines.

  • space-around Evenly space wrapped lines across the container's main axis, distributing remaining space around the lines. Compared to space between using space around will result in space being distributed to the begining of the first lines and end of the last line.

LEARN MORE HERE

Align Content

Flex Wrap

The flexWrap property is set on containers and controls what happens when children overflow the size of the container along the main axis. By default children are forced into a single line (which can shrink elements). If wrapping is allowed items are wrapped into multiple lines along the main axis if needed.

When wrapping lines alignContent can be used to specify how the lines are placed in the container. learn more here

Flex Wrap

Flex Basis, Grow, and Shrink

  • flexGrow describes how any space within a container should be distributed among its children along the main axis. After laying out its children, a container will distribute any remaining space according to the flex grow values specified by its children.

    flexGrow accepts any floating point value >= 0, with 0 being the default value. A container will distribute any remaining space among its children weighted by the child’s flex grow value.

  • flexShrink describes how to shrink children along the main axis in the case that the total size of the children overflow the size of the container on the main axis. Flex shrink is very similar to flex grow and can be thought of in the same way if any overflowing size is considered to be negative remaining space. These two properties also work well together by allowing children to grow and shrink as needed.

    Flex shrink accepts any floating point value >= 0, with 1 being the default value. A container will shrink its children weighted by the child’s flex shrink value.

  • flexBasis is an axis-independent way of providing the default size of an item along the main axis. Setting the flex basis of a child is similar to setting the width of that child if its parent is a container with flexDirection: row or setting the height of a child if its parent is a container with flexDirection: column. The flex basis of an item is the default size of that item, the size of the item before any flex grow and flex shrink calculations are performed.

LEARN MORE HERE

Width and Height

The width property in Yoga specifies the width of the element's content area. Similarly height property specifies the height of the element's content area.

Both width and height can take following values:

  • auto Is the default Value, React Native calculates the width/height for the element based on its content, whether that is other children, text, or an image.

  • pixels Defines the width/height in absolute pixels. Depending on other styles set on the component, this may or may not be the final dimension of the node.

  • percentage Defines the width or height in percentage of its parent's width or height respectively.

Absolute & Relative Layout

The position type of an element defines how it is positioned within its parent.

relative (default value) By default an element is positioned relatively. This means an element is positioned according to the normal flow of the layout, and then offset relative to that position based on the values of top, right, bottom, and left. The offset does not affect the position of any sibling or parent elements.

absolute When positioned absolutely an element doesn't take part in the normal layout flow. It is instead laid out independent of its siblings. The position is determined based on the top, right, bottom, and left values.

Absolute & Relative Layoutp

Going Deeper

Check out the interactive yoga playground that you can use to get a better understanding of flexbox.

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.

See some examples from Wix Engineers:

Edit this page
Last updated on
- + diff --git a/docs/0.61/flexbox/index.html b/docs/0.61/flexbox/index.html index 6535fca48cc..145f4780c92 100644 --- a/docs/0.61/flexbox/index.html +++ b/docs/0.61/flexbox/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

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 flexDirection defaulting to column instead of row, and the flex parameter only supporting a single number.

Flex

flex will define how your items are going to “fill” over the available space along your main axis. Space will be divided according to each element's flex property.

In the following example the red, yellow and the green views are all children in the container view that has flex: 1 set. The red view uses flex: 1 , the yellow view uses flex: 2 and the green view uses flex: 3 . 1+2+3 = 6 which means that the red view will get 1/6 of the space, the yellow 2/6 of the space and the green 3/6 of the space.

Flex

Flex Direction

flexDirection controls the direction in which the children of a node are laid out. This is also referred to as the main axis. The cross axis is the axis perpendicular to the main axis, or the axis which the wrapping lines are laid out in.

  • row Align children from left to right. If wrapping is enabled then the next line will start under the first item on the left of the container.

  • column (default value) Align children from top to bottom. If wrapping is enabled then the next line will start to the left first item on the top of the container.

  • row-reverse Align children from right to left. If wrapping is enabled then the next line will start under the first item on the right of the container.

  • column-reverse Align children from bottom to top. If wrapping is enabled then the next line will start to the left first item on the bottom of the container.

LEARN MORE HERE

Flex Direction

Layout Direction

Layout direction specifies the direction in which children and text in a hierarchy should be laid out. Layout direction also affects what edge start and end refer to. By default React Native lays out with LTR layout direction. In this mode start refers to left and end refers to right.

  • LTR (default value) Text and children are laid out from left to right. Margin and padding applied the start of an element are applied on the left side.

  • RTL Text and children are laid out from right to left. Margin and padding applied the start of an element are applied on the right side.

Justify Content

justifyContent describes how to align children within the main axis of their container. For example, you can use this property to center a child horizontally within a container with flexDirection set to row or vertically within a container with flexDirection set to column.

  • flex-start(default value) Align children of a container to the start of the container's main axis.

  • flex-end Align children of a container to the end of the container's main axis.

  • center Align children of a container in the center of the container's main axis.

  • space-between Evenly space of children across the container's main axis, distributing remaining space between the children.

  • space-around Evenly space of children across the container's main axis, distributing remaining space around the children. Compared to space-between using space-around will result in space being distributed to the beginning of the first child and end of the last child.

  • space-evenly Evenly distributed within the alignment container along the main axis. The spacing between each pair of adjacent items, the main-start edge and the first item, and the main-end edge and the last item, are all exactly the same.

LEARN MORE HERE

Justify Content

Align Items

alignItems describes how to align children along the cross axis of their container. Align items is very similar to justifyContent but instead of applying to the main axis, alignItems applies to the cross axis.

  • stretch (default value) Stretch children of a container to match the height of the container's cross axis.

  • flex-start Align children of a container to the start of the container's cross axis.

  • flex-end Align children of a container to the end of the container's cross axis.

  • center Align children of a container in the center of the container's cross axis.

  • baseline Align children of a container along a common baseline. Individual children can be set to be the reference baseline for their parents.

For stretch to have an effect, children must not have a fixed dimension along the secondary axis. In the following example, setting alignItems: stretch does nothing until the width: 50 is removed from the children.

LEARN MORE HERE

Align Items

Align Self

alignSelf has the same options and effect as alignItems but instead of affecting the children within a container, you can apply this property to a single child to change its alignment within its parent. alignSelf overrides any option set by the parent with alignItems.

Align Self

Align Content

alignContent defines the distribution of lines along the cross-axis. This only has effect when items are wrapped to multiple lines using flexWrap.

  • flex-start (default value) Align wrapped lines to the start of the container's cross axis.

  • flex-end Align wrapped lines to the end of the container's cross axis.

  • stretch wrapped lines to match the height of the container's cross axis.

  • center Align wrapped lines in the center of the container's cross axis.

  • space-between Evenly space wrapped lines across the container's main axis, distributing remaining space between the lines.

  • space-around Evenly space wrapped lines across the container's main axis, distributing remaining space around the lines. Compared to space between using space around will result in space being distributed to the begining of the first lines and end of the last line.

LEARN MORE HERE

Align Content

Flex Wrap

The flexWrap property is set on containers and controls what happens when children overflow the size of the container along the main axis. By default children are forced into a single line (which can shrink elements). If wrapping is allowed items are wrapped into multiple lines along the main axis if needed.

When wrapping lines alignContent can be used to specify how the lines are placed in the container. learn more here

Flex Wrap

Flex Basis, Grow, and Shrink

  • flexGrow describes how any space within a container should be distributed among its children along the main axis. After laying out its children, a container will distribute any remaining space according to the flex grow values specified by its children.

    flexGrow accepts any floating point value >= 0, with 0 being the default value. A container will distribute any remaining space among its children weighted by the child’s flex grow value.

  • flexShrink describes how to shrink children along the main axis in the case that the total size of the children overflow the size of the container on the main axis. Flex shrink is very similar to flex grow and can be thought of in the same way if any overflowing size is considered to be negative remaining space. These two properties also work well together by allowing children to grow and shrink as needed.

    Flex shrink accepts any floating point value >= 0, with 1 being the default value. A container will shrink its children weighted by the child’s flex shrink value.

  • flexBasis is an axis-independent way of providing the default size of an item along the main axis. Setting the flex basis of a child is similar to setting the width of that child if its parent is a container with flexDirection: row or setting the height of a child if its parent is a container with flexDirection: column. The flex basis of an item is the default size of that item, the size of the item before any flex grow and flex shrink calculations are performed.

LEARN MORE HERE

Width and Height

The width property in Yoga specifies the width of the element's content area. Similarly height property specifies the height of the element's content area.

Both width and height can take following values:

  • auto Is the default Value, React Native calculates the width/height for the element based on its content, whether that is other children, text, or an image.

  • pixels Defines the width/height in absolute pixels. Depending on other styles set on the component, this may or may not be the final dimension of the node.

  • percentage Defines the width or height in percentage of its parent's width or height respectively.

Absolute & Relative Layout

The position type of an element defines how it is positioned within its parent.

relative (default value) By default an element is positioned relatively. This means an element is positioned according to the normal flow of the layout, and then offset relative to that position based on the values of top, right, bottom, and left. The offset does not affect the position of any sibling or parent elements.

absolute When positioned absolutely an element doesn't take part in the normal layout flow. It is instead laid out independent of its siblings. The position is determined based on the top, right, bottom, and left values.

Absolute & Relative Layoutp

Going Deeper

Check out the interactive yoga playground that you can use to get a better understanding of flexbox.

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.

See some examples from Wix Engineers:

Edit this page
Last updated on
- + diff --git a/docs/0.61/geolocation.html b/docs/0.61/geolocation.html index a0e69547f0d..3c7cb5fa0b5 100644 --- a/docs/0.61/geolocation.html +++ b/docs/0.61/geolocation.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 Geolocation

Deprecated. Use @react-native-community/geolocation instead.

The Geolocation API extends the Geolocation web spec.

As a browser polyfill, this API is available through the navigator.geolocation global - you do not need to import it.

On Android, this uses the android.location API. This API is not recommended by Google because it is less accurate and slower than the recommended Google Location Services API. In order to use it with React Native, use the react-native-geolocation-service module.

Configuration and Permissions

iOS

You need to include the NSLocationWhenInUseUsageDescription key in Info.plist to enable geolocation when using the app. Geolocation is enabled by default when you create a project with react-native init.

In order to enable geolocation in the background, you need to include the 'NSLocationAlwaysUsageDescription' key in Info.plist and add location as a background mode in the 'Capabilities' tab in Xcode.

If you are using CocoaPods for React Native, make sure to include the RCTGeolocation sub-podspec.

Android

To request access to location, you need to add the following line to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Android API >= 18 Positions will also contain a mocked boolean to indicate if position was created from a mock provider.

Android API >= 23 Requires an additional step to check for, and request the ACCESS_FINE_LOCATION permission using the PermissionsAndroid API. Failure to do so may result in a hard crash.

Methods

Reference

Methods

setRNConfiguration()

geolocation.setRNConfiguration(config);

Sets configuration options that will be used in all location requests.

Parameters:

NameTypeRequiredDescription
configobjectYesSee below.

Supported options:

  • skipPermissionRequests (boolean, iOS-only) - Defaults to false. If true, you must request permissions before using Geolocation APIs.

requestAuthorization()

geolocation.requestAuthorization();

Request suitable Location permission based on the key configured on pList. If NSLocationAlwaysUsageDescription is set, it will request Always authorization, although if NSLocationWhenInUseUsageDescription is set, it will request InUse authorization.

getCurrentPosition()

geolocation.getCurrentPosition(
geo_success,
[geo_error],
[geo_options]
);

Invokes the success callback once with the latest location info.

Parameters:

NameTypeRequiredDescription
geo_successfunctionYesInvoked with latest location info.
geo_errorfunctionNoInvoked whenever an error is encountered.
geo_optionsobjectNoSee below.

Supported options:

  • timeout (ms) - Is a positive value representing the maximum length of time (in milliseconds) the device is allowed to take in order to return a position. Defaults to INFINITY.
  • maximumAge (ms) - Is a positive value indicating the maximum age in milliseconds of a possible cached position that is acceptable to return. If set to 0, it means that the device cannot use a cached position and must attempt to retrieve the real current position. If set to Infinity the device will always return a cached position regardless of its age. Defaults to INFINITY.
  • enableHighAccuracy (bool) - Is a boolean representing if to use GPS or not. If set to true, a GPS position will be requested. If set to false, a WIFI location will be requested.

watchPosition()

geolocation.watchPosition(success, [error], [options]);

Invokes the success callback whenever the location changes. Returns a watchId (number).

Parameters:

NameTypeRequiredDescription
successfunctionYesInvoked whenever the location changes.
errorfunctionNoInvoked whenever an error is encountered.
optionsobjectNoSee below.

Supported options:

  • timeout (ms) - Is a positive value representing the maximum length of time (in milliseconds) the device is allowed to take in order to return a position. Defaults to INFINITY.
  • maximumAge (ms) - Is a positive value indicating the maximum age in milliseconds of a possible cached position that is acceptable to return. If set to 0, it means that the device cannot use a cached position and must attempt to retrieve the real current position. If set to Infinity the device will always return a cached position regardless of its age. Defaults to INFINITY.
  • enableHighAccuracy (bool) - Is a boolean representing if to use GPS or not. If set to true, a GPS position will be requested. If set to false, a WIFI location will be requested.
  • distanceFilter (m) - The minimum distance from the previous location to exceed before returning a new location. Set to 0 to not filter locations. Defaults to 100m.
  • useSignificantChanges (bool) - Uses the battery-efficient native significant changes APIs to return locations. Locations will only be returned when the device detects a significant distance has been breached. Defaults to FALSE.

clearWatch()

geolocation.clearWatch(watchID);

Parameters:

NameTypeRequiredDescription
watchIDnumberYesId as returned by watchPosition().

stopObserving()

geolocation.stopObserving();

Stops observing for device location changes. In addition, it removes all listeners previously registered.

Notice that this method has only effect if the geolocation.watchPosition(successCallback, errorCallback) method was previously invoked.

Edit this page
Last updated on
- + diff --git a/docs/0.61/geolocation/index.html b/docs/0.61/geolocation/index.html index a0e69547f0d..3c7cb5fa0b5 100644 --- a/docs/0.61/geolocation/index.html +++ b/docs/0.61/geolocation/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 Geolocation

Deprecated. Use @react-native-community/geolocation instead.

The Geolocation API extends the Geolocation web spec.

As a browser polyfill, this API is available through the navigator.geolocation global - you do not need to import it.

On Android, this uses the android.location API. This API is not recommended by Google because it is less accurate and slower than the recommended Google Location Services API. In order to use it with React Native, use the react-native-geolocation-service module.

Configuration and Permissions

iOS

You need to include the NSLocationWhenInUseUsageDescription key in Info.plist to enable geolocation when using the app. Geolocation is enabled by default when you create a project with react-native init.

In order to enable geolocation in the background, you need to include the 'NSLocationAlwaysUsageDescription' key in Info.plist and add location as a background mode in the 'Capabilities' tab in Xcode.

If you are using CocoaPods for React Native, make sure to include the RCTGeolocation sub-podspec.

Android

To request access to location, you need to add the following line to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Android API >= 18 Positions will also contain a mocked boolean to indicate if position was created from a mock provider.

Android API >= 23 Requires an additional step to check for, and request the ACCESS_FINE_LOCATION permission using the PermissionsAndroid API. Failure to do so may result in a hard crash.

Methods

Reference

Methods

setRNConfiguration()

geolocation.setRNConfiguration(config);

Sets configuration options that will be used in all location requests.

Parameters:

NameTypeRequiredDescription
configobjectYesSee below.

Supported options:

  • skipPermissionRequests (boolean, iOS-only) - Defaults to false. If true, you must request permissions before using Geolocation APIs.

requestAuthorization()

geolocation.requestAuthorization();

Request suitable Location permission based on the key configured on pList. If NSLocationAlwaysUsageDescription is set, it will request Always authorization, although if NSLocationWhenInUseUsageDescription is set, it will request InUse authorization.

getCurrentPosition()

geolocation.getCurrentPosition(
geo_success,
[geo_error],
[geo_options]
);

Invokes the success callback once with the latest location info.

Parameters:

NameTypeRequiredDescription
geo_successfunctionYesInvoked with latest location info.
geo_errorfunctionNoInvoked whenever an error is encountered.
geo_optionsobjectNoSee below.

Supported options:

  • timeout (ms) - Is a positive value representing the maximum length of time (in milliseconds) the device is allowed to take in order to return a position. Defaults to INFINITY.
  • maximumAge (ms) - Is a positive value indicating the maximum age in milliseconds of a possible cached position that is acceptable to return. If set to 0, it means that the device cannot use a cached position and must attempt to retrieve the real current position. If set to Infinity the device will always return a cached position regardless of its age. Defaults to INFINITY.
  • enableHighAccuracy (bool) - Is a boolean representing if to use GPS or not. If set to true, a GPS position will be requested. If set to false, a WIFI location will be requested.

watchPosition()

geolocation.watchPosition(success, [error], [options]);

Invokes the success callback whenever the location changes. Returns a watchId (number).

Parameters:

NameTypeRequiredDescription
successfunctionYesInvoked whenever the location changes.
errorfunctionNoInvoked whenever an error is encountered.
optionsobjectNoSee below.

Supported options:

  • timeout (ms) - Is a positive value representing the maximum length of time (in milliseconds) the device is allowed to take in order to return a position. Defaults to INFINITY.
  • maximumAge (ms) - Is a positive value indicating the maximum age in milliseconds of a possible cached position that is acceptable to return. If set to 0, it means that the device cannot use a cached position and must attempt to retrieve the real current position. If set to Infinity the device will always return a cached position regardless of its age. Defaults to INFINITY.
  • enableHighAccuracy (bool) - Is a boolean representing if to use GPS or not. If set to true, a GPS position will be requested. If set to false, a WIFI location will be requested.
  • distanceFilter (m) - The minimum distance from the previous location to exceed before returning a new location. Set to 0 to not filter locations. Defaults to 100m.
  • useSignificantChanges (bool) - Uses the battery-efficient native significant changes APIs to return locations. Locations will only be returned when the device detects a significant distance has been breached. Defaults to FALSE.

clearWatch()

geolocation.clearWatch(watchID);

Parameters:

NameTypeRequiredDescription
watchIDnumberYesId as returned by watchPosition().

stopObserving()

geolocation.stopObserving();

Stops observing for device location changes. In addition, it removes all listeners previously registered.

Notice that this method has only effect if the geolocation.watchPosition(successCallback, errorCallback) method was previously invoked.

Edit this page
Last updated on
- + diff --git a/docs/0.61/gesture-responder-system.html b/docs/0.61/gesture-responder-system.html index fc5eb947277..5a6fa6aaf17 100644 --- a/docs/0.61/gesture-responder-system.html +++ b/docs/0.61/gesture-responder-system.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

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.

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 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 happening
  • View.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 finger
  • View.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 release
  • View.props.onResponderTerminate: (evt) => {} - The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, 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:

  • nativeEvent
    • changedTouches - Array of all touch events that have changed since the last event
    • identifier - The ID of the touch
    • locationX - The X position of the touch, relative to the element
    • locationY - The Y position of the touch, relative to the element
    • pageX - The X position of the touch, relative to the root element
    • pageY - The Y position of the touch, relative to the root element
    • target - The node id of the element receiving the touch event
    • timestamp - A time identifier for the touch, useful for velocity calculation
    • touches - 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.

Edit this page
Last updated on
- + diff --git a/docs/0.61/gesture-responder-system/index.html b/docs/0.61/gesture-responder-system/index.html index fc5eb947277..5a6fa6aaf17 100644 --- a/docs/0.61/gesture-responder-system/index.html +++ b/docs/0.61/gesture-responder-system/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

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.

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 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 happening
  • View.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 finger
  • View.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 release
  • View.props.onResponderTerminate: (evt) => {} - The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, 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:

  • nativeEvent
    • changedTouches - Array of all touch events that have changed since the last event
    • identifier - The ID of the touch
    • locationX - The X position of the touch, relative to the element
    • locationY - The Y position of the touch, relative to the element
    • pageX - The X position of the touch, relative to the root element
    • pageY - The Y position of the touch, relative to the root element
    • target - The node id of the element receiving the touch event
    • timestamp - A time identifier for the touch, useful for velocity calculation
    • touches - 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.

Edit this page
Last updated on
- + diff --git a/docs/0.61/getting-started.html b/docs/0.61/getting-started.html index a5f8b6fd9ad..e387f03d01c 100644 --- a/docs/0.61/getting-started.html +++ b/docs/0.61/getting-started.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Introduction

Welcome to the very start of your React Native journey! If you're looking for environment setup instructions, they've moved to [their own section](/docs/environment-setup). Continue reading for an introduction to the documentation, Native Components, React, and more!

Many different kinds of people use React Native: from advanced iOS developers to React beginners, to people getting started programming for the first time in their career. These docs were written for all learners, no matter their experience level or background.

How to use these docs

You can start here and read through these docs linearly like a book; or you can read the specific sections you need. Already familiar with React? You can skip that section—or read it for a light refresher.

Prerequisites

To work with React Native, you will need to have an understanding of JavaScript fundamentals. If you’re new to JavaScript or need a refresher, you can dive in or brush up at Mozilla Developer Network.

While we do our best to assume no prior knowledge of React, Android, or iOS development, these are valuable topics of study for the aspiring React Native developer. Where sensible, we have linked to resources and articles that go more in depth.

Interactive examples

This introduction lets you get started immediately in your browser with interactive examples like this one:

The above is a Snack Player. It’s a handy tool created by Expo to embed and run React Native projects and share how they render in platforms like Android and iOS. The code is live and editable, so you can play directly with it in your browser. Go ahead and try changing the "Try editing me!" text above to "Hello, world!"

Optionally, if you want to setup a local development environment, you can follow our guide to setting up your environment on your local machine and paste the code examples into your App.js file there. (If you are a web developer, you may already have a local environment set up for mobile browser testing!)

Function Components and Class Components

With React, you can make components using either classes or functions. Originally, class components were the only components that could have state. But since the introduction of React's Hooks API, you can add state and more to function components.

Hooks were introduced in React Native 0.59., and because Hooks are the future-facing way to write your React components, we wrote this introduction using function component examples. Where useful, we also cover class components under a toggle like so:

You can find more examples of class components in previous versions of this documentation.

Developer Notes

People from many different development backgrounds are learning React Native. You may have experience with a range of technologies, from web to Android to iOS and more. We try to write for developers from all backgrounds. Sometimes we provide explanations specific to one platform or another like so:

Web developers may be familiar with this concept.

Formatting

Menu paths are written in bold and use carets to navigate submenus. Example: Android Studio > Preferences

Now that you know how this guide works, it's time to get to know the foundation of React Native: Native Components.

Edit this page
Last updated on
- + diff --git a/docs/0.61/getting-started/index.html b/docs/0.61/getting-started/index.html index a5f8b6fd9ad..e387f03d01c 100644 --- a/docs/0.61/getting-started/index.html +++ b/docs/0.61/getting-started/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Introduction

Welcome to the very start of your React Native journey! If you're looking for environment setup instructions, they've moved to [their own section](/docs/environment-setup). Continue reading for an introduction to the documentation, Native Components, React, and more!

Many different kinds of people use React Native: from advanced iOS developers to React beginners, to people getting started programming for the first time in their career. These docs were written for all learners, no matter their experience level or background.

How to use these docs

You can start here and read through these docs linearly like a book; or you can read the specific sections you need. Already familiar with React? You can skip that section—or read it for a light refresher.

Prerequisites

To work with React Native, you will need to have an understanding of JavaScript fundamentals. If you’re new to JavaScript or need a refresher, you can dive in or brush up at Mozilla Developer Network.

While we do our best to assume no prior knowledge of React, Android, or iOS development, these are valuable topics of study for the aspiring React Native developer. Where sensible, we have linked to resources and articles that go more in depth.

Interactive examples

This introduction lets you get started immediately in your browser with interactive examples like this one:

The above is a Snack Player. It’s a handy tool created by Expo to embed and run React Native projects and share how they render in platforms like Android and iOS. The code is live and editable, so you can play directly with it in your browser. Go ahead and try changing the "Try editing me!" text above to "Hello, world!"

Optionally, if you want to setup a local development environment, you can follow our guide to setting up your environment on your local machine and paste the code examples into your App.js file there. (If you are a web developer, you may already have a local environment set up for mobile browser testing!)

Function Components and Class Components

With React, you can make components using either classes or functions. Originally, class components were the only components that could have state. But since the introduction of React's Hooks API, you can add state and more to function components.

Hooks were introduced in React Native 0.59., and because Hooks are the future-facing way to write your React components, we wrote this introduction using function component examples. Where useful, we also cover class components under a toggle like so:

You can find more examples of class components in previous versions of this documentation.

Developer Notes

People from many different development backgrounds are learning React Native. You may have experience with a range of technologies, from web to Android to iOS and more. We try to write for developers from all backgrounds. Sometimes we provide explanations specific to one platform or another like so:

Web developers may be familiar with this concept.

Formatting

Menu paths are written in bold and use carets to navigate submenus. Example: Android Studio > Preferences

Now that you know how this guide works, it's time to get to know the foundation of React Native: Native Components.

Edit this page
Last updated on
- + diff --git a/docs/0.61/handling-text-input.html b/docs/0.61/handling-text-input.html index 0e02e1827dd..d4b8e437ce6 100644 --- a/docs/0.61/handling-text-input.html +++ b/docs/0.61/handling-text-input.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Handling Text Input

TextInput is a Core Component that allows the user to enter text. It has an onChangeText prop that takes a function to be called every time the text changed, and an onSubmitEditing prop that takes a function to be called when the text is submitted.

For example, let's say that as the user types, you're translating their words into a different language. In this new language, every single word is written the same way: 🍕. So the sentence "Hello there Bob" would be translated as "🍕🍕🍕".

In this example, we store text in the state, because it changes over time.

There are a lot more things you might want to do with a text input. For example, you could validate the text inside while the user types. For more detailed examples, see the React docs on controlled components, or the reference docs for TextInput.

Text input is one of the ways the user interacts with the app. Next, let's look at another type of input and learn how to handle touches.

Edit this page
Last updated on
- + diff --git a/docs/0.61/handling-text-input/index.html b/docs/0.61/handling-text-input/index.html index 0e02e1827dd..d4b8e437ce6 100644 --- a/docs/0.61/handling-text-input/index.html +++ b/docs/0.61/handling-text-input/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Handling Text Input

TextInput is a Core Component that allows the user to enter text. It has an onChangeText prop that takes a function to be called every time the text changed, and an onSubmitEditing prop that takes a function to be called when the text is submitted.

For example, let's say that as the user types, you're translating their words into a different language. In this new language, every single word is written the same way: 🍕. So the sentence "Hello there Bob" would be translated as "🍕🍕🍕".

In this example, we store text in the state, because it changes over time.

There are a lot more things you might want to do with a text input. For example, you could validate the text inside while the user types. For more detailed examples, see the React docs on controlled components, or the reference docs for TextInput.

Text input is one of the ways the user interacts with the app. Next, let's look at another type of input and learn how to handle touches.

Edit this page
Last updated on
- + diff --git a/docs/0.61/handling-touches.html b/docs/0.61/handling-touches.html index 2ea271d3ec4..7970089f16b 100644 --- a/docs/0.61/handling-touches.html +++ b/docs/0.61/handling-touches.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Handling Touches

Users interact with mobile apps mainly through touch. They can use a combination of gestures, such as tapping on a button, scrolling a list, or zooming on a map. React Native provides components to handle all sorts of common gestures, as well as a comprehensive gesture responder system to allow for more advanced gesture recognition, but the one component you will most likely be interested in is the basic Button.

Displaying a basic button

Button provides a basic button component that is rendered nicely on all platforms. The minimal example to display a button looks like this:

<Button
onPress={() => {
alert('You tapped the button!');
}}
title="Press Me"
/>

This will render a blue label on iOS, and a blue rounded rectangle with light text on Android. Pressing the button will call the "onPress" function, which in this case displays an alert popup. If you like, you can specify a "color" prop to change the color of your button.

Go ahead and play around with the Button component using the example below. You can select which platform your app is previewed in by clicking on the toggle in the bottom right, then click on "Tap to Play" to preview the app.

Touchables

If the basic button doesn't look right for your app, you can build your own button using any of the "Touchable" components provided by React Native. The "Touchable" components provide the capability to capture tapping gestures, and can display feedback when a gesture is recognized. These components do not provide any default styling, however, so you will need to do a bit of work to get them looking nicely in your app.

Which "Touchable" component you use will depend on what kind of feedback you want to provide:

  • Generally, you can use TouchableHighlight anywhere you would use a button or link on web. The view's background will be darkened when the user presses down on the button.

  • You may consider using TouchableNativeFeedback on Android to display ink surface reaction ripples that respond to the user's touch.

  • TouchableOpacity can be used to provide feedback by reducing the opacity of the button, allowing the background to be seen through while the user is pressing down.

  • If you need to handle a tap gesture but you don't want any feedback to be displayed, use TouchableWithoutFeedback.

In some cases, you may want to detect when a user presses and holds a view for a set amount of time. These long presses can be handled by passing a function to the onLongPress props of any of the "Touchable" components.

Let's see all of these in action:

Scrolling lists, swiping pages, and pinch-to-zoom

Another gesture commonly used in mobile apps is the swipe or pan. This gesture allows the user to scroll through a list of items, or swipe through pages of content. In order to handle these and other gestures, we'll learn how to use a ScrollView next.

Edit this page
Last updated on
- + diff --git a/docs/0.61/handling-touches/index.html b/docs/0.61/handling-touches/index.html index 2ea271d3ec4..7970089f16b 100644 --- a/docs/0.61/handling-touches/index.html +++ b/docs/0.61/handling-touches/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Handling Touches

Users interact with mobile apps mainly through touch. They can use a combination of gestures, such as tapping on a button, scrolling a list, or zooming on a map. React Native provides components to handle all sorts of common gestures, as well as a comprehensive gesture responder system to allow for more advanced gesture recognition, but the one component you will most likely be interested in is the basic Button.

Displaying a basic button

Button provides a basic button component that is rendered nicely on all platforms. The minimal example to display a button looks like this:

<Button
onPress={() => {
alert('You tapped the button!');
}}
title="Press Me"
/>

This will render a blue label on iOS, and a blue rounded rectangle with light text on Android. Pressing the button will call the "onPress" function, which in this case displays an alert popup. If you like, you can specify a "color" prop to change the color of your button.

Go ahead and play around with the Button component using the example below. You can select which platform your app is previewed in by clicking on the toggle in the bottom right, then click on "Tap to Play" to preview the app.

Touchables

If the basic button doesn't look right for your app, you can build your own button using any of the "Touchable" components provided by React Native. The "Touchable" components provide the capability to capture tapping gestures, and can display feedback when a gesture is recognized. These components do not provide any default styling, however, so you will need to do a bit of work to get them looking nicely in your app.

Which "Touchable" component you use will depend on what kind of feedback you want to provide:

  • Generally, you can use TouchableHighlight anywhere you would use a button or link on web. The view's background will be darkened when the user presses down on the button.

  • You may consider using TouchableNativeFeedback on Android to display ink surface reaction ripples that respond to the user's touch.

  • TouchableOpacity can be used to provide feedback by reducing the opacity of the button, allowing the background to be seen through while the user is pressing down.

  • If you need to handle a tap gesture but you don't want any feedback to be displayed, use TouchableWithoutFeedback.

In some cases, you may want to detect when a user presses and holds a view for a set amount of time. These long presses can be handled by passing a function to the onLongPress props of any of the "Touchable" components.

Let's see all of these in action:

Scrolling lists, swiping pages, and pinch-to-zoom

Another gesture commonly used in mobile apps is the swipe or pan. This gesture allows the user to scroll through a list of items, or swipe through pages of content. In order to handle these and other gestures, we'll learn how to use a ScrollView next.

Edit this page
Last updated on
- + diff --git a/docs/0.61/headless-js-android.html b/docs/0.61/headless-js-android.html index 821e4082f9c..90eeeff58e2 100644 --- a/docs/0.61/headless-js-android.html +++ b/docs/0.61/headless-js-android.html @@ -19,7 +19,7 @@ - + @@ -43,7 +43,7 @@
}
Edit this page
Last updated on
- + diff --git a/docs/0.61/headless-js-android/index.html b/docs/0.61/headless-js-android/index.html index 821e4082f9c..90eeeff58e2 100644 --- a/docs/0.61/headless-js-android/index.html +++ b/docs/0.61/headless-js-android/index.html @@ -19,7 +19,7 @@ - + @@ -43,7 +43,7 @@
}
Edit this page
Last updated on
- + diff --git a/docs/0.61/height-and-width.html b/docs/0.61/height-and-width.html index ef8d166d937..06865b036cb 100644 --- a/docs/0.61/height-and-width.html +++ b/docs/0.61/height-and-width.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Height and Width

A component's height and width determine its size on the screen.

Fixed Dimensions

The simplest way to set the dimensions of a component is by adding a fixed width and height to style. All dimensions in React Native are unitless, and represent density-independent pixels.

Setting dimensions this way is common for components that should always render at exactly the same size, regardless of screen dimensions.

Flex Dimensions

Use flex in a component's style to have the component expand and shrink dynamically based on available space. Normally you will use flex: 1, which tells a component to fill all available space, shared evenly amongst other components with the same parent. The larger the flex given, the higher the ratio of space a component will take compared to its siblings.

A component can only expand to fill available space if its parent has dimensions greater than 0. If a parent does not have either a fixed width and height or flex, the parent will have dimensions of 0 and the flex children will not be visible.

After you can control a component's size, the next step is to learn how to lay it out on the screen.

Edit this page
Last updated on
- + diff --git a/docs/0.61/height-and-width/index.html b/docs/0.61/height-and-width/index.html index ef8d166d937..06865b036cb 100644 --- a/docs/0.61/height-and-width/index.html +++ b/docs/0.61/height-and-width/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Height and Width

A component's height and width determine its size on the screen.

Fixed Dimensions

The simplest way to set the dimensions of a component is by adding a fixed width and height to style. All dimensions in React Native are unitless, and represent density-independent pixels.

Setting dimensions this way is common for components that should always render at exactly the same size, regardless of screen dimensions.

Flex Dimensions

Use flex in a component's style to have the component expand and shrink dynamically based on available space. Normally you will use flex: 1, which tells a component to fill all available space, shared evenly amongst other components with the same parent. The larger the flex given, the higher the ratio of space a component will take compared to its siblings.

A component can only expand to fill available space if its parent has dimensions greater than 0. If a parent does not have either a fixed width and height or flex, the parent will have dimensions of 0 and the flex children will not be visible.

After you can control a component's size, the next step is to learn how to lay it out on the screen.

Edit this page
Last updated on
- + diff --git a/docs/0.61/hermes.html b/docs/0.61/hermes.html index e3ad7ef1b39..51124b1ad07 100644 --- a/docs/0.61/hermes.html +++ b/docs/0.61/hermes.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Using Hermes

Hermes is an open-source JavaScript engine optimized for running React Native apps on Android. For many apps, enabling Hermes will result in improved start-up time, decreased memory usage, and smaller app size. At this time Hermes is an opt-in React Native feature, and this guide explains how to enable it.

First, ensure you're using at least version 0.60.4 of React Native.

If you have an existing app based on an earlier version of React Native, you will have to upgrade it first. See Upgrading to new React Native Versions for how to do this. Make especially sure that all changes to android/app/build.gradle have been applied, as detailed by the React Native upgrade helper. After upgrading the app, make sure everything works before trying to switch to Hermes.

Note for Windows users.

Hermes requires Microsoft Visual C++ 2015 Redistributable

Edit your android/app/build.gradle file and make the change illustrated below:

project.ext.react = [
entryFile: "index.js",
- enableHermes: false // clean and rebuild if changing
+ enableHermes: true // clean and rebuild if changing
]

Also, if you're using ProGuard, you will need to add this rule in proguard-rules.pro :

-keep class com.facebook.hermes.unicode.** { *; }

Next, if you've already built your app at least once, clean the build:

$ cd android && ./gradlew clean

That's it! You should now be able to develop and deploy your app as normal:

$ react-native run-android

Confirming Hermes is in use

If you've recently created a new app from scratch you should see if Hermes is enabled in the welcome view:

Where to find JS engine status in AwesomeProject

A HermesInternal global variable will be available in JavaScript that can be used to verify that Hermes is in use:

const isHermes = () => global.HermesInternal != null;

To see the benefits of Hermes, try making a release build/deployment of your app to compare. For example:

$ react-native run-android --variant release

This will compile JavaScript to bytecode during build time which will improve your app's startup speed on device.

Debugging Hermes using Google Chrome's DevTools

Hermes supports the Chrome debugger by implementing the Chrome inspector protocol. This means Chrome's tools can be used to directly debug JavaScript running on Hermes, on an emulator or device.

Chrome connects to Hermes running on device via Metro, so you'll need to know where Metro is listening. Typically this will be on localhost:8081, but this is configurable. When running yarn start the address is written to stdout on startup.

Once you know where the Metro server is listening, you can connect with Chrome using the following steps:

  1. Navigate to chrome://inspect in a Chrome browser instance.

  2. Use the Configure... button to add the Metro server address (typically localhost:8081 as described above).

Configure button in Chrome DevTools devices page

Dialog for adding Chrome DevTools network targets

  1. You should now see a "Hermes React Native" target with an "inspect" link which can be used to bring up debugger. If you don't see the "inspect" link, make sure the Metro server is running. Target inspect link

  2. You can now use the Chrome debug tools. For example, to breakpoint the next time some JavaScript is run, click on the pause button and trigger an action in your app which would cause JavaScript to execute. Pause button in debug tools

Edit this page
Last updated on
- + diff --git a/docs/0.61/hermes/index.html b/docs/0.61/hermes/index.html index e3ad7ef1b39..51124b1ad07 100644 --- a/docs/0.61/hermes/index.html +++ b/docs/0.61/hermes/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Using Hermes

Hermes is an open-source JavaScript engine optimized for running React Native apps on Android. For many apps, enabling Hermes will result in improved start-up time, decreased memory usage, and smaller app size. At this time Hermes is an opt-in React Native feature, and this guide explains how to enable it.

First, ensure you're using at least version 0.60.4 of React Native.

If you have an existing app based on an earlier version of React Native, you will have to upgrade it first. See Upgrading to new React Native Versions for how to do this. Make especially sure that all changes to android/app/build.gradle have been applied, as detailed by the React Native upgrade helper. After upgrading the app, make sure everything works before trying to switch to Hermes.

Note for Windows users.

Hermes requires Microsoft Visual C++ 2015 Redistributable

Edit your android/app/build.gradle file and make the change illustrated below:

project.ext.react = [
entryFile: "index.js",
- enableHermes: false // clean and rebuild if changing
+ enableHermes: true // clean and rebuild if changing
]

Also, if you're using ProGuard, you will need to add this rule in proguard-rules.pro :

-keep class com.facebook.hermes.unicode.** { *; }

Next, if you've already built your app at least once, clean the build:

$ cd android && ./gradlew clean

That's it! You should now be able to develop and deploy your app as normal:

$ react-native run-android

Confirming Hermes is in use

If you've recently created a new app from scratch you should see if Hermes is enabled in the welcome view:

Where to find JS engine status in AwesomeProject

A HermesInternal global variable will be available in JavaScript that can be used to verify that Hermes is in use:

const isHermes = () => global.HermesInternal != null;

To see the benefits of Hermes, try making a release build/deployment of your app to compare. For example:

$ react-native run-android --variant release

This will compile JavaScript to bytecode during build time which will improve your app's startup speed on device.

Debugging Hermes using Google Chrome's DevTools

Hermes supports the Chrome debugger by implementing the Chrome inspector protocol. This means Chrome's tools can be used to directly debug JavaScript running on Hermes, on an emulator or device.

Chrome connects to Hermes running on device via Metro, so you'll need to know where Metro is listening. Typically this will be on localhost:8081, but this is configurable. When running yarn start the address is written to stdout on startup.

Once you know where the Metro server is listening, you can connect with Chrome using the following steps:

  1. Navigate to chrome://inspect in a Chrome browser instance.

  2. Use the Configure... button to add the Metro server address (typically localhost:8081 as described above).

Configure button in Chrome DevTools devices page

Dialog for adding Chrome DevTools network targets

  1. You should now see a "Hermes React Native" target with an "inspect" link which can be used to bring up debugger. If you don't see the "inspect" link, make sure the Metro server is running. Target inspect link

  2. You can now use the Chrome debug tools. For example, to breakpoint the next time some JavaScript is run, click on the pause button and trigger an action in your app which would cause JavaScript to execute. Pause button in debug tools

Edit this page
Last updated on
- + diff --git a/docs/0.61/image-style-props.html b/docs/0.61/image-style-props.html index eda3b764978..7339e03e36c 100644 --- a/docs/0.61/image-style-props.html +++ b/docs/0.61/image-style-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Image Style Props

Reference

Props

borderTopRightRadius

TypeRequired
numberNo

backfaceVisibility

TypeRequired
enum('visible', 'hidden')No

borderBottomLeftRadius

TypeRequired
numberNo

borderBottomRightRadius

TypeRequired
numberNo

borderColor

TypeRequired
colorNo

borderRadius

TypeRequired
numberNo

borderTopLeftRadius

TypeRequired
numberNo

backgroundColor

TypeRequired
colorNo

borderWidth

TypeRequired
numberNo

opacity

TypeRequired
numberNo

overflow

TypeRequired
enum('visible', 'hidden')No

resizeMode

TypeRequired
enum('cover', 'contain', 'stretch', 'repeat', 'center')No

tintColor

Changes the color of all the non-transparent pixels to the tintColor.

TypeRequired
colorNo

overlayColor

When the image has rounded corners, specifying an overlayColor will cause the remaining space in the corners to be filled with a solid color. This is useful in cases which are not supported by the Android implementation of rounded corners:

  • Certain resize modes, such as 'contain'
  • Animated GIFs

A typical way to use this prop is with images displayed on a solid background and setting the overlayColor to the same color as the background.

For details of how this works under the hood, see https://frescolib.org/docs/rounded-corners-and-circles.html

TypeRequiredPlatform
stringNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.61/image-style-props/index.html b/docs/0.61/image-style-props/index.html index eda3b764978..7339e03e36c 100644 --- a/docs/0.61/image-style-props/index.html +++ b/docs/0.61/image-style-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Image Style Props

Reference

Props

borderTopRightRadius

TypeRequired
numberNo

backfaceVisibility

TypeRequired
enum('visible', 'hidden')No

borderBottomLeftRadius

TypeRequired
numberNo

borderBottomRightRadius

TypeRequired
numberNo

borderColor

TypeRequired
colorNo

borderRadius

TypeRequired
numberNo

borderTopLeftRadius

TypeRequired
numberNo

backgroundColor

TypeRequired
colorNo

borderWidth

TypeRequired
numberNo

opacity

TypeRequired
numberNo

overflow

TypeRequired
enum('visible', 'hidden')No

resizeMode

TypeRequired
enum('cover', 'contain', 'stretch', 'repeat', 'center')No

tintColor

Changes the color of all the non-transparent pixels to the tintColor.

TypeRequired
colorNo

overlayColor

When the image has rounded corners, specifying an overlayColor will cause the remaining space in the corners to be filled with a solid color. This is useful in cases which are not supported by the Android implementation of rounded corners:

  • Certain resize modes, such as 'contain'
  • Animated GIFs

A typical way to use this prop is with images displayed on a solid background and setting the overlayColor to the same color as the background.

For details of how this works under the hood, see https://frescolib.org/docs/rounded-corners-and-circles.html

TypeRequiredPlatform
stringNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.61/image.html b/docs/0.61/image.html index 18910a872be..2d41cf5d65f 100644 --- a/docs/0.61/image.html +++ b/docs/0.61/image.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// For WebP support, without animations
implementation 'com.facebook.fresco:webpsupport:2.0.0'
}

Reference

Props

style

ImageResizeMode is an Enum for different image resizing modes, set via the resizeMode style property on Image components. The values are contain, cover, stretch, center, repeat.

TypeRequired
styleNo

blurRadius

blurRadius: the blur radius of the blur filter added to the image

TypeRequired
numberNo

onLayout

Invoked on mount and layout changes with {nativeEvent: {layout: {x, y, width, height}}}.

TypeRequired
functionNo

onLoad

Invoked when load completes successfully.

TypeRequired
functionNo

onLoadEnd

Invoked when load either succeeds or fails.

TypeRequired
functionNo

onLoadStart

Invoked on load start.

e.g., onLoadStart={(e) => this.setState({loading: true})}

TypeRequired
functionNo

resizeMode

Determines how to resize the image when the frame doesn't match the raw image dimensions. Defaults to cover.

TypeRequired
enum('cover', 'contain', 'stretch', 'repeat', 'center')No

source

The image source (either a remote URL or a local file resource).

This prop can also contain several remote URLs, specified together with their width and height and potentially with scale/other URI arguments. The native side will then choose the best uri to display based on the measured size of the image container. A cache property can be added to control how networked request interacts with the local cache. (For more information see Cache Control for Images).

The currently supported formats are png, jpg, jpeg, bmp, gif, webp (Android only), psd (iOS only). In addition, iOS supports several RAW image formats. Refer to Apple's documentation for the current list of supported camera models (for iOS 12, see https://support.apple.com/en-ca/HT208967).

TypeRequired
ImageSourcePropTypeNo

loadingIndicatorSource

Similarly to source, this property represents the resource used to render the loading indicator for the image, displayed until image is ready to be displayed, typically after when it got downloaded from network.

TypeRequired
array of ImageSourcePropTypes, numberNo

Can accept a number as returned by require('./image.jpg')

onError

Invoked on load error with {nativeEvent: {error}}.

TypeRequired
functionNo

testID

A unique identifier for this element to be used in UI Automation testing scripts.

TypeRequired
stringNo

resizeMethod

The mechanism that should be used to resize the image when the image's dimensions differ from the image view's dimensions. Defaults to auto.

More details about resize and scale can be found at http://frescolib.org/docs/resizing.html.

TypeRequiredPlatform
enum('auto', 'resize', 'scale')NoAndroid

accessibilityLabel

The text that's read by the screen reader when the user interacts with the image.

TypeRequiredPlatform
stringNoiOS

accessible

When true, indicates the image is an accessibility element.

TypeRequiredPlatform
boolNoiOS

capInsets

When the image is resized, the corners of the size specified by capInsets will stay a fixed size, but the center content and borders of the image will be stretched. This is useful for creating resizable rounded buttons, shadows, and other resizable assets. More info in the official Apple documentation.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

defaultSource

A static image to display while loading the image source.

TypeRequiredPlatform
object, numberNoiOS
numberNoAndroid

If passing an object, the general shape is {uri: string, width: number, height: number, scale: number}:

If passing a number:

Note: On Android, the default source prop is ignored on debug builds.

onPartialLoad

Invoked when a partial load of the image is complete. The definition of what constitutes a "partial load" is loader specific though this is meant for progressive JPEG loads.

TypeRequiredPlatform
functionNoiOS

onProgress

Invoked on download progress with {nativeEvent: {loaded, total}}.

TypeRequiredPlatform
functionNoiOS

fadeDuration

Android only. By default, it is 300ms.

TypeRequiredPlatform
numberNoAndroid

progressiveRenderingEnabled

Android only. When true, enables progressive jpeg streaming. https://frescolib.org/docs/progressive-jpegs.html

TypeRequiredPlatform
boolNoAndroid

Methods

getSize()

Image.getSize(uri, success, [failure]);

Retrieve the width and height (in pixels) of an image prior to displaying it. This method can fail if the image cannot be found, or fails to download.

In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API.

Parameters:

NameTypeRequiredDescription
uristringYesThe location of the image.
successfunctionYesThe function that will be called if the image was successfully found and width and height retrieved.
failurefunctionNoThe function that will be called if there was an error, such as failing to retrieve the image.

getSizeWithHeaders()

Image.getSizeWithHeaders(uri, headers, success, [failure]);

Retrieve the width and height (in pixels) of an image prior to displaying it with the ability to provide the headers for the request. This method can fail if the image cannot be found, or fails to download.

In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API.

Does not work for static image resources.

Parameters:

NameTypeRequiredDescription
uristringYesThe location of the image.
headersobjectYesThe headers for the request.
successfunctionYesThe function that will be called if the image was successfully found and width and height retrieved.
failurefunctionNoThe function that will be called if there was an error, such as failing toto retrieve the image.

prefetch()

Image.prefetch(url);

Prefetches a remote image for later use by downloading it to the disk cache

Parameters:

NameTypeRequiredDescription
urlstringYesThe remote location of the image.

abortPrefetch()

Image.abortPrefetch(requestId);

Abort prefetch request. Android-only.

Parameters:

NameTypeRequiredDescription
requestIdnumberYesId as returned by prefetch()

queryCache()

Image.queryCache(urls);

Perform cache interrogation. Returns a mapping from URL to cache status, such as "disk" or "memory". If a requested URL is not in the mapping, it means it's not in the cache.

Parameters:

NameTypeRequiredDescription
urlsarrayYesList of image URLs to check the cache for.

resolveAssetSource()

Image.resolveAssetSource(source);

Resolves an asset reference into an object which has the properties uri, width, and height.

Parameters:

NameTypeRequiredDescription
sourcenumber, objectYesA number (opaque type returned by require('./foo.png')) or an ImageSource.

ImageSource is an object like { uri: '<http location || file path>' }

Edit this page
Last updated on
- + diff --git a/docs/0.61/image/index.html b/docs/0.61/image/index.html index 18910a872be..2d41cf5d65f 100644 --- a/docs/0.61/image/index.html +++ b/docs/0.61/image/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// For WebP support, without animations
implementation 'com.facebook.fresco:webpsupport:2.0.0'
}

Reference

Props

style

ImageResizeMode is an Enum for different image resizing modes, set via the resizeMode style property on Image components. The values are contain, cover, stretch, center, repeat.

TypeRequired
styleNo

blurRadius

blurRadius: the blur radius of the blur filter added to the image

TypeRequired
numberNo

onLayout

Invoked on mount and layout changes with {nativeEvent: {layout: {x, y, width, height}}}.

TypeRequired
functionNo

onLoad

Invoked when load completes successfully.

TypeRequired
functionNo

onLoadEnd

Invoked when load either succeeds or fails.

TypeRequired
functionNo

onLoadStart

Invoked on load start.

e.g., onLoadStart={(e) => this.setState({loading: true})}

TypeRequired
functionNo

resizeMode

Determines how to resize the image when the frame doesn't match the raw image dimensions. Defaults to cover.

TypeRequired
enum('cover', 'contain', 'stretch', 'repeat', 'center')No

source

The image source (either a remote URL or a local file resource).

This prop can also contain several remote URLs, specified together with their width and height and potentially with scale/other URI arguments. The native side will then choose the best uri to display based on the measured size of the image container. A cache property can be added to control how networked request interacts with the local cache. (For more information see Cache Control for Images).

The currently supported formats are png, jpg, jpeg, bmp, gif, webp (Android only), psd (iOS only). In addition, iOS supports several RAW image formats. Refer to Apple's documentation for the current list of supported camera models (for iOS 12, see https://support.apple.com/en-ca/HT208967).

TypeRequired
ImageSourcePropTypeNo

loadingIndicatorSource

Similarly to source, this property represents the resource used to render the loading indicator for the image, displayed until image is ready to be displayed, typically after when it got downloaded from network.

TypeRequired
array of ImageSourcePropTypes, numberNo

Can accept a number as returned by require('./image.jpg')

onError

Invoked on load error with {nativeEvent: {error}}.

TypeRequired
functionNo

testID

A unique identifier for this element to be used in UI Automation testing scripts.

TypeRequired
stringNo

resizeMethod

The mechanism that should be used to resize the image when the image's dimensions differ from the image view's dimensions. Defaults to auto.

More details about resize and scale can be found at http://frescolib.org/docs/resizing.html.

TypeRequiredPlatform
enum('auto', 'resize', 'scale')NoAndroid

accessibilityLabel

The text that's read by the screen reader when the user interacts with the image.

TypeRequiredPlatform
stringNoiOS

accessible

When true, indicates the image is an accessibility element.

TypeRequiredPlatform
boolNoiOS

capInsets

When the image is resized, the corners of the size specified by capInsets will stay a fixed size, but the center content and borders of the image will be stretched. This is useful for creating resizable rounded buttons, shadows, and other resizable assets. More info in the official Apple documentation.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

defaultSource

A static image to display while loading the image source.

TypeRequiredPlatform
object, numberNoiOS
numberNoAndroid

If passing an object, the general shape is {uri: string, width: number, height: number, scale: number}:

If passing a number:

Note: On Android, the default source prop is ignored on debug builds.

onPartialLoad

Invoked when a partial load of the image is complete. The definition of what constitutes a "partial load" is loader specific though this is meant for progressive JPEG loads.

TypeRequiredPlatform
functionNoiOS

onProgress

Invoked on download progress with {nativeEvent: {loaded, total}}.

TypeRequiredPlatform
functionNoiOS

fadeDuration

Android only. By default, it is 300ms.

TypeRequiredPlatform
numberNoAndroid

progressiveRenderingEnabled

Android only. When true, enables progressive jpeg streaming. https://frescolib.org/docs/progressive-jpegs.html

TypeRequiredPlatform
boolNoAndroid

Methods

getSize()

Image.getSize(uri, success, [failure]);

Retrieve the width and height (in pixels) of an image prior to displaying it. This method can fail if the image cannot be found, or fails to download.

In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API.

Parameters:

NameTypeRequiredDescription
uristringYesThe location of the image.
successfunctionYesThe function that will be called if the image was successfully found and width and height retrieved.
failurefunctionNoThe function that will be called if there was an error, such as failing to retrieve the image.

getSizeWithHeaders()

Image.getSizeWithHeaders(uri, headers, success, [failure]);

Retrieve the width and height (in pixels) of an image prior to displaying it with the ability to provide the headers for the request. This method can fail if the image cannot be found, or fails to download.

In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API.

Does not work for static image resources.

Parameters:

NameTypeRequiredDescription
uristringYesThe location of the image.
headersobjectYesThe headers for the request.
successfunctionYesThe function that will be called if the image was successfully found and width and height retrieved.
failurefunctionNoThe function that will be called if there was an error, such as failing toto retrieve the image.

prefetch()

Image.prefetch(url);

Prefetches a remote image for later use by downloading it to the disk cache

Parameters:

NameTypeRequiredDescription
urlstringYesThe remote location of the image.

abortPrefetch()

Image.abortPrefetch(requestId);

Abort prefetch request. Android-only.

Parameters:

NameTypeRequiredDescription
requestIdnumberYesId as returned by prefetch()

queryCache()

Image.queryCache(urls);

Perform cache interrogation. Returns a mapping from URL to cache status, such as "disk" or "memory". If a requested URL is not in the mapping, it means it's not in the cache.

Parameters:

NameTypeRequiredDescription
urlsarrayYesList of image URLs to check the cache for.

resolveAssetSource()

Image.resolveAssetSource(source);

Resolves an asset reference into an object which has the properties uri, width, and height.

Parameters:

NameTypeRequiredDescription
sourcenumber, objectYesA number (opaque type returned by require('./foo.png')) or an ImageSource.

ImageSource is an object like { uri: '<http location || file path>' }

Edit this page
Last updated on
- + diff --git a/docs/0.61/imagebackground.html b/docs/0.61/imagebackground.html index c4ad2c4e4cb..d7db2d5340b 100644 --- a/docs/0.61/imagebackground.html +++ b/docs/0.61/imagebackground.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

ImageBackground

A common feature request from developers familiar with the web is background-image. To handle this use case, you can use the <ImageBackground> component, which has the same props as <Image>, and add whatever children to it you would like to layer on top of it.

You might not want to use <ImageBackground> in some cases, since the implementation is basic. Refer to <ImageBackground>'s source code for more insight, and create your own custom component when needed.

Note that you must specify some width and height style attributes.

Example

return (
<ImageBackground source={...} style={{width: '100%', height: '100%'}}>
<Text>Inside</Text>
</ImageBackground>
);

Reference

Props

Inherits Image Props.

style

TypeRequired
view stylesNo

imageStyle

TypeRequired
image stylesNo

imageRef

Allows to set a reference to the inner Image component

TypeRequired
RefNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/imagebackground/index.html b/docs/0.61/imagebackground/index.html index c4ad2c4e4cb..d7db2d5340b 100644 --- a/docs/0.61/imagebackground/index.html +++ b/docs/0.61/imagebackground/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

ImageBackground

A common feature request from developers familiar with the web is background-image. To handle this use case, you can use the <ImageBackground> component, which has the same props as <Image>, and add whatever children to it you would like to layer on top of it.

You might not want to use <ImageBackground> in some cases, since the implementation is basic. Refer to <ImageBackground>'s source code for more insight, and create your own custom component when needed.

Note that you must specify some width and height style attributes.

Example

return (
<ImageBackground source={...} style={{width: '100%', height: '100%'}}>
<Text>Inside</Text>
</ImageBackground>
);

Reference

Props

Inherits Image Props.

style

TypeRequired
view stylesNo

imageStyle

TypeRequired
image stylesNo

imageRef

Allows to set a reference to the inner Image component

TypeRequired
RefNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/imageeditor.html b/docs/0.61/imageeditor.html index 60b43a1be06..c456c430ccc 100644 --- a/docs/0.61/imageeditor.html +++ b/docs/0.61/imageeditor.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 ImageEditor

Deprecated. Use @react-native-community/image-editor instead.

Reference

Methods

cropImage()

static cropImage(uri, cropData, success, failure)

Crop the image specified by the URI param. If URI points to a remote image, it will be downloaded automatically. If the image cannot be loaded/downloaded, the failure callback will be called.

If the cropping process is successful, the resultant cropped image will be stored in the ImageStore, and the URI returned in the success callback will point to the image in the store. Remember to delete the cropped image from the ImageStore when you are done with it.

cropData

  • offset - The top-left corner of the cropped image, specified in the original image's coordinate space
  • size - Size (dimensions) of the cropped image
  • displaySize (optional) - Size to which you want to scale the cropped image
  • resizeMode (optional) - Resizing mode to use when scaling the image
cropData = {
offset: { x: number, y: number },
size: { width: number, height: number },
displaySize: { width: number, height: number },
resizeMode: 'contain/cover/stretch'
};
Edit this page
Last updated on
- + diff --git a/docs/0.61/imageeditor/index.html b/docs/0.61/imageeditor/index.html index 60b43a1be06..c456c430ccc 100644 --- a/docs/0.61/imageeditor/index.html +++ b/docs/0.61/imageeditor/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 ImageEditor

Deprecated. Use @react-native-community/image-editor instead.

Reference

Methods

cropImage()

static cropImage(uri, cropData, success, failure)

Crop the image specified by the URI param. If URI points to a remote image, it will be downloaded automatically. If the image cannot be loaded/downloaded, the failure callback will be called.

If the cropping process is successful, the resultant cropped image will be stored in the ImageStore, and the URI returned in the success callback will point to the image in the store. Remember to delete the cropped image from the ImageStore when you are done with it.

cropData

  • offset - The top-left corner of the cropped image, specified in the original image's coordinate space
  • size - Size (dimensions) of the cropped image
  • displaySize (optional) - Size to which you want to scale the cropped image
  • resizeMode (optional) - Resizing mode to use when scaling the image
cropData = {
offset: { x: number, y: number },
size: { width: number, height: number },
displaySize: { width: number, height: number },
resizeMode: 'contain/cover/stretch'
};
Edit this page
Last updated on
- + diff --git a/docs/0.61/imagepickerios.html b/docs/0.61/imagepickerios.html index 7e0b1b915de..6782bf5d7e9 100644 --- a/docs/0.61/imagepickerios.html +++ b/docs/0.61/imagepickerios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 ImagePickerIOS

Deprecated. Use @react-native-community/image-picker-ios instead.

Reference

Methods

canRecordVideos()

static canRecordVideos(callback)

canUseCamera()

static canUseCamera(callback)

openCameraDialog()

static openCameraDialog(config, successCallback, cancelCallback)

Parameters:

NameTypeRequiredDescription
configobjectNoSee below.
successCallbackfunctionNoSee below.
cancelCallbackfunctionNoSee below.

config is an object containing:

  • videoMode : An optional boolean value that defaults to false.

successCallback is an optional callback function that's invoked when the select dialog is opened successfully. It will include the following data:

  • [string, number, number]

cancelCallback is an optional callback function that's invoked when the camera dialog is canceled.

openSelectDialog()

static openSelectDialog(config, successCallback, cancelCallback)

Parameters:

NameTypeRequiredDescription
configobjectNoSee below.
successCallbackfunctionNoSee below.
cancelCallbackfunctionNoSee below.

config is an object containing:

  • showImages : An optional boolean value that defaults to false.
  • showVideos: An optional boolean value that defaults to false.

successCallback is an optional callback function that's invoked when the select dialog is opened successfully. It will include the following data:

  • [string, number, number]

cancelCallback is an optional callback function that's invoked when the select dialog is canceled.

Edit this page
Last updated on
- + diff --git a/docs/0.61/imagepickerios/index.html b/docs/0.61/imagepickerios/index.html index 7e0b1b915de..6782bf5d7e9 100644 --- a/docs/0.61/imagepickerios/index.html +++ b/docs/0.61/imagepickerios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 ImagePickerIOS

Deprecated. Use @react-native-community/image-picker-ios instead.

Reference

Methods

canRecordVideos()

static canRecordVideos(callback)

canUseCamera()

static canUseCamera(callback)

openCameraDialog()

static openCameraDialog(config, successCallback, cancelCallback)

Parameters:

NameTypeRequiredDescription
configobjectNoSee below.
successCallbackfunctionNoSee below.
cancelCallbackfunctionNoSee below.

config is an object containing:

  • videoMode : An optional boolean value that defaults to false.

successCallback is an optional callback function that's invoked when the select dialog is opened successfully. It will include the following data:

  • [string, number, number]

cancelCallback is an optional callback function that's invoked when the camera dialog is canceled.

openSelectDialog()

static openSelectDialog(config, successCallback, cancelCallback)

Parameters:

NameTypeRequiredDescription
configobjectNoSee below.
successCallbackfunctionNoSee below.
cancelCallbackfunctionNoSee below.

config is an object containing:

  • showImages : An optional boolean value that defaults to false.
  • showVideos: An optional boolean value that defaults to false.

successCallback is an optional callback function that's invoked when the select dialog is opened successfully. It will include the following data:

  • [string, number, number]

cancelCallback is an optional callback function that's invoked when the select dialog is canceled.

Edit this page
Last updated on
- + diff --git a/docs/0.61/images.html b/docs/0.61/images.html index ca6782a2901..a613d6bd8c3 100644 --- a/docs/0.61/images.html +++ b/docs/0.61/images.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// BAD
<Image source={{uri: 'https://reactjs.org/logo-og.png'}} />

Network Requests for Images

If you would like to set such things as the HTTP-Verb, Headers or a Body along with the image request, you may do this by defining these properties on the source object:

<Image
source={{
uri: 'https://reactjs.org/logo-og.png',
method: 'POST',
headers: {
Pragma: 'no-cache'
},
body: 'Your Body goes here'
}}
style={{ width: 400, height: 400 }}
/>

Uri Data Images

Sometimes, you might be getting encoded image data from a REST API call. You can use the 'data:' uri scheme to use these images. Same as for network resources, you will need to manually specify the dimensions of your image.

This is recommended for very small and dynamic images only, like icons in a list from a DB.

// include at least width and height!
<Image
style={{
width: 51,
height: 51,
resizeMode: 'contain'
}}
source={{
uri:
'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADMAAAAzCAYAAAA6oTAqAAAAEXRFWHRTb2Z0d2FyZQBwbmdjcnVzaEB1SfMAAABQSURBVGje7dSxCQBACARB+2/ab8BEeQNhFi6WSYzYLYudDQYGBgYGBgYGBgYGBgYGBgZmcvDqYGBgmhivGQYGBgYGBgYGBgYGBgYGBgbmQw+P/eMrC5UTVAAAAABJRU5ErkJggg=='
}}
/>

Cache Control (iOS Only)

In some cases you might only want to display an image if it is already in the local cache, i.e. a low resolution placeholder until a higher resolution is available. In other cases you do not care if the image is outdated and are willing to display an outdated image to save bandwidth. The cache source property gives you control over how the network layer interacts with the cache.

<Image
source={{
uri: 'https://reactjs.org/logo-og.png',
cache: 'only-if-cached'
}}
style={{ width: 400, height: 400 }}
/>

Local Filesystem Images

See CameraRoll for an example of using local resources that are outside of Images.xcassets.

Best Camera Roll Image

iOS saves multiple sizes for the same image in your Camera Roll, it is very important to pick the one that's as close as possible for performance reasons. You wouldn't want to use the full quality 3264x2448 image as source when displaying a 200x200 thumbnail. If there's an exact match, React Native will pick it, otherwise it's going to use the first one that's at least 50% bigger in order to avoid blur when resizing from a close size. All of this is done by default so you don't have to worry about writing the tedious (and error prone) code to do it yourself.

Why Not Automatically Size Everything?

In the browser if you don't give a size to an image, the browser is going to render a 0x0 element, download the image, and then render the image based with the correct size. The big issue with this behavior is that your UI is going to jump all around as images load, this makes for a very bad user experience.

In React Native this behavior is intentionally not implemented. It is more work for the developer to know the dimensions (or aspect ratio) of the remote image in advance, but we believe that it leads to a better user experience. Static images loaded from the app bundle via the require('./my-icon.png') syntax can be automatically sized because their dimensions are available immediately at the time of mounting.

For example, the result of require('./my-icon.png') might be:

{"__packager_asset":true,"uri":"my-icon.png","width":591,"height":573}

Source as an object

In React Native, one interesting decision is that the src attribute is named source and doesn't take a string but an object with a uri attribute.

<Image source={{ uri: 'something.jpg' }} />

On the infrastructure side, the reason is that it allows us to attach metadata to this object. For example if you are using require('./my-icon.png'), then we add information about its actual location and size (don't rely on this fact, it might change in the future!). This is also future proofing, for example we may want to support sprites at some point, instead of outputting {uri: ...}, we can output {uri: ..., crop: {left: 10, top: 50, width: 20, height: 40}} and transparently support spriting on all the existing call sites.

On the user side, this lets you annotate the object with useful attributes such as the dimension of the image in order to compute the size it's going to be displayed in. Feel free to use it as your data structure to store more information about your image.

Background Image via Nesting

A common feature request from developers familiar with the web is background-image. To handle this use case, you can use the <ImageBackground> component, which has the same props as <Image>, and add whatever children to it you would like to layer on top of it.

You might not want to use <ImageBackground> in some cases, since the implementation is basic. Refer to <ImageBackground>'s documentation for more insight, and create your own custom component when needed.

return (
<ImageBackground source={...} style={{width: '100%', height: '100%'}}>
<Text>Inside</Text>
</ImageBackground>
);

Note that you must specify some width and height style attributes.

iOS Border Radius Styles

Please note that the following corner specific, border radius style properties are currently ignored by iOS's image component:

Off-thread Decoding

Image decoding can take more than a frame-worth of time. This is one of the major sources of frame drops on the web because decoding is done in the main thread. In React Native, image decoding is done in a different thread. In practice, you already need to handle the case when the image is not downloaded yet, so displaying the placeholder for a few more frames while it is decoding does not require any code change.

Edit this page
Last updated on
- + diff --git a/docs/0.61/images/index.html b/docs/0.61/images/index.html index ca6782a2901..a613d6bd8c3 100644 --- a/docs/0.61/images/index.html +++ b/docs/0.61/images/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// BAD
<Image source={{uri: 'https://reactjs.org/logo-og.png'}} />

Network Requests for Images

If you would like to set such things as the HTTP-Verb, Headers or a Body along with the image request, you may do this by defining these properties on the source object:

<Image
source={{
uri: 'https://reactjs.org/logo-og.png',
method: 'POST',
headers: {
Pragma: 'no-cache'
},
body: 'Your Body goes here'
}}
style={{ width: 400, height: 400 }}
/>

Uri Data Images

Sometimes, you might be getting encoded image data from a REST API call. You can use the 'data:' uri scheme to use these images. Same as for network resources, you will need to manually specify the dimensions of your image.

This is recommended for very small and dynamic images only, like icons in a list from a DB.

// include at least width and height!
<Image
style={{
width: 51,
height: 51,
resizeMode: 'contain'
}}
source={{
uri:
'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADMAAAAzCAYAAAA6oTAqAAAAEXRFWHRTb2Z0d2FyZQBwbmdjcnVzaEB1SfMAAABQSURBVGje7dSxCQBACARB+2/ab8BEeQNhFi6WSYzYLYudDQYGBgYGBgYGBgYGBgYGBgZmcvDqYGBgmhivGQYGBgYGBgYGBgYGBgYGBgbmQw+P/eMrC5UTVAAAAABJRU5ErkJggg=='
}}
/>

Cache Control (iOS Only)

In some cases you might only want to display an image if it is already in the local cache, i.e. a low resolution placeholder until a higher resolution is available. In other cases you do not care if the image is outdated and are willing to display an outdated image to save bandwidth. The cache source property gives you control over how the network layer interacts with the cache.

<Image
source={{
uri: 'https://reactjs.org/logo-og.png',
cache: 'only-if-cached'
}}
style={{ width: 400, height: 400 }}
/>

Local Filesystem Images

See CameraRoll for an example of using local resources that are outside of Images.xcassets.

Best Camera Roll Image

iOS saves multiple sizes for the same image in your Camera Roll, it is very important to pick the one that's as close as possible for performance reasons. You wouldn't want to use the full quality 3264x2448 image as source when displaying a 200x200 thumbnail. If there's an exact match, React Native will pick it, otherwise it's going to use the first one that's at least 50% bigger in order to avoid blur when resizing from a close size. All of this is done by default so you don't have to worry about writing the tedious (and error prone) code to do it yourself.

Why Not Automatically Size Everything?

In the browser if you don't give a size to an image, the browser is going to render a 0x0 element, download the image, and then render the image based with the correct size. The big issue with this behavior is that your UI is going to jump all around as images load, this makes for a very bad user experience.

In React Native this behavior is intentionally not implemented. It is more work for the developer to know the dimensions (or aspect ratio) of the remote image in advance, but we believe that it leads to a better user experience. Static images loaded from the app bundle via the require('./my-icon.png') syntax can be automatically sized because their dimensions are available immediately at the time of mounting.

For example, the result of require('./my-icon.png') might be:

{"__packager_asset":true,"uri":"my-icon.png","width":591,"height":573}

Source as an object

In React Native, one interesting decision is that the src attribute is named source and doesn't take a string but an object with a uri attribute.

<Image source={{ uri: 'something.jpg' }} />

On the infrastructure side, the reason is that it allows us to attach metadata to this object. For example if you are using require('./my-icon.png'), then we add information about its actual location and size (don't rely on this fact, it might change in the future!). This is also future proofing, for example we may want to support sprites at some point, instead of outputting {uri: ...}, we can output {uri: ..., crop: {left: 10, top: 50, width: 20, height: 40}} and transparently support spriting on all the existing call sites.

On the user side, this lets you annotate the object with useful attributes such as the dimension of the image in order to compute the size it's going to be displayed in. Feel free to use it as your data structure to store more information about your image.

Background Image via Nesting

A common feature request from developers familiar with the web is background-image. To handle this use case, you can use the <ImageBackground> component, which has the same props as <Image>, and add whatever children to it you would like to layer on top of it.

You might not want to use <ImageBackground> in some cases, since the implementation is basic. Refer to <ImageBackground>'s documentation for more insight, and create your own custom component when needed.

return (
<ImageBackground source={...} style={{width: '100%', height: '100%'}}>
<Text>Inside</Text>
</ImageBackground>
);

Note that you must specify some width and height style attributes.

iOS Border Radius Styles

Please note that the following corner specific, border radius style properties are currently ignored by iOS's image component:

Off-thread Decoding

Image decoding can take more than a frame-worth of time. This is one of the major sources of frame drops on the web because decoding is done in the main thread. In React Native, image decoding is done in a different thread. In practice, you already need to handle the case when the image is not downloaded yet, so displaying the placeholder for a few more frames while it is decoding does not require any code change.

Edit this page
Last updated on
- + diff --git a/docs/0.61/imagestore.html b/docs/0.61/imagestore.html index d637ca3badd..652f0069785 100644 --- a/docs/0.61/imagestore.html +++ b/docs/0.61/imagestore.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

ImageStore

Deprecated. Use expo-file-system or react-native-fs instead.

Methods

Reference

Methods

hasImageForTag()

static hasImageForTag(uri, callback)

Check if the ImageStore contains image data for the specified URI. @platform ios

removeImageForTag()

static removeImageForTag(uri)

Delete an image from the ImageStore. Images are stored in memory and must be manually removed when you are finished with them, otherwise they will continue to use up RAM until the app is terminated. It is safe to call removeImageForTag() without first calling hasImageForTag(), it will fail silently. @platform ios

addImageFromBase64()

static addImageFromBase64(base64ImageData, success, failure)

Stores a base64-encoded image in the ImageStore, and returns a URI that can be used to access or display the image later. Images are stored in memory only, and must be manually deleted when you are finished with them by calling removeImageForTag().

Note that it is very inefficient to transfer large quantities of binary data between JS and native code, so you should avoid calling this more than necessary. @platform ios

getBase64ForTag()

static getBase64ForTag(uri, success, failure)

Retrieves the base64-encoded data for an image in the ImageStore. If the specified URI does not match an image in the store, the failure callback will be called.

Note that it is very inefficient to transfer large quantities of binary data between JS and native code, so you should avoid calling this more than necessary. To display an image in the ImageStore, you can pass the URI to an <Image/> component; there is no need to retrieve the base64 data.

Edit this page
Last updated on
- + diff --git a/docs/0.61/imagestore/index.html b/docs/0.61/imagestore/index.html index d637ca3badd..652f0069785 100644 --- a/docs/0.61/imagestore/index.html +++ b/docs/0.61/imagestore/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

ImageStore

Deprecated. Use expo-file-system or react-native-fs instead.

Methods

Reference

Methods

hasImageForTag()

static hasImageForTag(uri, callback)

Check if the ImageStore contains image data for the specified URI. @platform ios

removeImageForTag()

static removeImageForTag(uri)

Delete an image from the ImageStore. Images are stored in memory and must be manually removed when you are finished with them, otherwise they will continue to use up RAM until the app is terminated. It is safe to call removeImageForTag() without first calling hasImageForTag(), it will fail silently. @platform ios

addImageFromBase64()

static addImageFromBase64(base64ImageData, success, failure)

Stores a base64-encoded image in the ImageStore, and returns a URI that can be used to access or display the image later. Images are stored in memory only, and must be manually deleted when you are finished with them by calling removeImageForTag().

Note that it is very inefficient to transfer large quantities of binary data between JS and native code, so you should avoid calling this more than necessary. @platform ios

getBase64ForTag()

static getBase64ForTag(uri, success, failure)

Retrieves the base64-encoded data for an image in the ImageStore. If the specified URI does not match an image in the store, the failure callback will be called.

Note that it is very inefficient to transfer large quantities of binary data between JS and native code, so you should avoid calling this more than necessary. To display an image in the ImageStore, you can pass the URI to an <Image/> component; there is no need to retrieve the base64 data.

Edit this page
Last updated on
- + diff --git a/docs/0.61/improvingux.html b/docs/0.61/improvingux.html index b8cbe2b22d1..f86e08e41d2 100644 --- a/docs/0.61/improvingux.html +++ b/docs/0.61/improvingux.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Improving User Experience

Configure text inputs

Entering text on touch phone is a challenge - small screen, software keyboard. But based on what kind of data you need, you can make it easier by properly configuring the text inputs:

  • Focus the first field automatically
  • Use placeholder text as an example of expected data format
  • Enable or disable autocapitalization and autocorrect
  • Choose keyboard type (e.g. email, numeric)
  • Make sure the return button focuses the next field or submits the form

Check out TextInput docs for more configuration options.

Try it on your phone

Manage layout when keyboard is visible

Software keyboard takes almost half of the screen. If you have interactive elements that can get covered by the keyboard, make sure they are still accessible by using the KeyboardAvoidingView component.

Try it on your phone

Make tappable areas larger

On mobile phones it's hard to be very precise when pressing buttons. Make sure all interactive elements are 44x44 or larger. One way to do this is to leave enough space for the element, padding, minWidth and minHeight style values can be useful for that. Alternatively, you can use hitSlop prop to increase interactive area without affecting the layout. Here's a demo:

Try it on your phone

Use Android Ripple

Android API 21+ uses the material design ripple to provide user with feedback when they touch an interactable area on the screen. React Native exposes this through the TouchableNativeFeedback component. Using this touchable effect instead of opacity or highlight will often make your app feel much more fitting on the platform. That said, you need to be careful when using it because it doesn't work on iOS or on Android API < 21, so you will need to fallback to using one of the other Touchable components on iOS. You can use a library like react-native-platform-touchable to handle the platform differences for you.

Try it on your phone

Screen orientation lock

Multiple screen orientations should work fine by default unless you're using Dimensions API and don't handle orientation changes. If you don't want to support multiple screen orientations, you can lock the screen orientation to either portrait or landscape.

On iOS, in the General tab and Deployment Info section of Xcode enable the Device Orientation you want to support (ensure you have selected iPhone from the Devices menu when making the changes). For Android, open the AndroidManifest.xml file and within the activity element add 'android:screenOrientation="portrait"' to lock to portrait or 'android:screenOrientation="landscape"' to lock to landscape.

Learn more

Material Design and Human Interface Guidelines are great resources for learning more about designing for mobile platforms.

Edit this page
Last updated on
- + diff --git a/docs/0.61/improvingux/index.html b/docs/0.61/improvingux/index.html index b8cbe2b22d1..f86e08e41d2 100644 --- a/docs/0.61/improvingux/index.html +++ b/docs/0.61/improvingux/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Improving User Experience

Configure text inputs

Entering text on touch phone is a challenge - small screen, software keyboard. But based on what kind of data you need, you can make it easier by properly configuring the text inputs:

  • Focus the first field automatically
  • Use placeholder text as an example of expected data format
  • Enable or disable autocapitalization and autocorrect
  • Choose keyboard type (e.g. email, numeric)
  • Make sure the return button focuses the next field or submits the form

Check out TextInput docs for more configuration options.

Try it on your phone

Manage layout when keyboard is visible

Software keyboard takes almost half of the screen. If you have interactive elements that can get covered by the keyboard, make sure they are still accessible by using the KeyboardAvoidingView component.

Try it on your phone

Make tappable areas larger

On mobile phones it's hard to be very precise when pressing buttons. Make sure all interactive elements are 44x44 or larger. One way to do this is to leave enough space for the element, padding, minWidth and minHeight style values can be useful for that. Alternatively, you can use hitSlop prop to increase interactive area without affecting the layout. Here's a demo:

Try it on your phone

Use Android Ripple

Android API 21+ uses the material design ripple to provide user with feedback when they touch an interactable area on the screen. React Native exposes this through the TouchableNativeFeedback component. Using this touchable effect instead of opacity or highlight will often make your app feel much more fitting on the platform. That said, you need to be careful when using it because it doesn't work on iOS or on Android API < 21, so you will need to fallback to using one of the other Touchable components on iOS. You can use a library like react-native-platform-touchable to handle the platform differences for you.

Try it on your phone

Screen orientation lock

Multiple screen orientations should work fine by default unless you're using Dimensions API and don't handle orientation changes. If you don't want to support multiple screen orientations, you can lock the screen orientation to either portrait or landscape.

On iOS, in the General tab and Deployment Info section of Xcode enable the Device Orientation you want to support (ensure you have selected iPhone from the Devices menu when making the changes). For Android, open the AndroidManifest.xml file and within the activity element add 'android:screenOrientation="portrait"' to lock to portrait or 'android:screenOrientation="landscape"' to lock to landscape.

Learn more

Material Design and Human Interface Guidelines are great resources for learning more about designing for mobile platforms.

Edit this page
Last updated on
- + diff --git a/docs/0.61/inputaccessoryview.html b/docs/0.61/inputaccessoryview.html index 8e2224ea390..d2cab291cb4 100644 --- a/docs/0.61/inputaccessoryview.html +++ b/docs/0.61/inputaccessoryview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

InputAccessoryView

A component which enables customization of the keyboard input accessory view on iOS. The input accessory view is displayed above the keyboard whenever a TextInput has focus. This component can be used to create custom toolbars.

To use this component wrap your custom toolbar with the InputAccessoryView component, and set a nativeID. Then, pass that nativeID as the inputAccessoryViewID of whatever TextInput you desire. A basic example:

This component can also be used to create sticky text inputs (text inputs which are anchored to the top of the keyboard). To do this, wrap a TextInput with the InputAccessoryView component, and don't set a nativeID. For an example, look at InputAccessoryViewExample.js.

Reference

Props

backgroundColor

TypeRequired
colorNo

nativeID

An ID which is used to associate this InputAccessoryView to specified TextInput(s).

TypeRequired
stringNo

style

TypeRequired
styleNo

Known issues

Edit this page
Last updated on
- + diff --git a/docs/0.61/inputaccessoryview/index.html b/docs/0.61/inputaccessoryview/index.html index 8e2224ea390..d2cab291cb4 100644 --- a/docs/0.61/inputaccessoryview/index.html +++ b/docs/0.61/inputaccessoryview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

InputAccessoryView

A component which enables customization of the keyboard input accessory view on iOS. The input accessory view is displayed above the keyboard whenever a TextInput has focus. This component can be used to create custom toolbars.

To use this component wrap your custom toolbar with the InputAccessoryView component, and set a nativeID. Then, pass that nativeID as the inputAccessoryViewID of whatever TextInput you desire. A basic example:

This component can also be used to create sticky text inputs (text inputs which are anchored to the top of the keyboard). To do this, wrap a TextInput with the InputAccessoryView component, and don't set a nativeID. For an example, look at InputAccessoryViewExample.js.

Reference

Props

backgroundColor

TypeRequired
colorNo

nativeID

An ID which is used to associate this InputAccessoryView to specified TextInput(s).

TypeRequired
stringNo

style

TypeRequired
styleNo

Known issues

Edit this page
Last updated on
- + diff --git a/docs/0.61/integration-with-existing-apps.html b/docs/0.61/integration-with-existing-apps.html index 56a67d29514..24f2bb849f4 100644 --- a/docs/0.61/integration-with-existing-apps.html +++ b/docs/0.61/integration-with-existing-apps.html @@ -19,7 +19,7 @@ - + @@ -48,7 +48,7 @@
if (mReactInstanceManager != null) {
mReactInstanceManager.onHostDestroy(this);
}
if (mReactRootView != null) {
mReactRootView.unmountReactApplication();
}
}

We also need to pass back button events to React Native:

@Override
public void onBackPressed() {
if (mReactInstanceManager != null) {
mReactInstanceManager.onBackPressed();
} else {
super.onBackPressed();
}
}

This allows JavaScript to control what happens when the user presses the hardware back button (e.g. to implement navigation). When JavaScript doesn't handle the back button press, your invokeDefaultOnBackPressed method will be called. By default this finishes your Activity.

Finally, we need to hook up the dev menu. By default, this is activated by (rage) shaking the device, but this is not very useful in emulators. So we make it show when you press the hardware menu button (use Ctrl + M if you're using Android Studio emulator):

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
if (keyCode == KeyEvent.KEYCODE_MENU && mReactInstanceManager != null) {
mReactInstanceManager.showDevOptionsDialog();
return true;
}
return super.onKeyUp(keyCode, event);
}

Now your activity is ready to run some JavaScript code.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ yarn start
2. Run the app

Now build and run your Android app as normal.

Once you reach your React-powered activity inside the app, it should load the JavaScript code from the development server and display:

Screenshot

Creating a release build in Android Studio

You can use Android Studio to create your release builds too! It’s as quick as creating release builds of your previously-existing native Android app. There’s one additional step, which you’ll have to do before every release build. You need to execute the following to create a React Native bundle, which will be included with your native Android app:

$ npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/com/your-company-name/app-package-name/src/main/assets/index.android.bundle --assets-dest android/com/your-company-name/app-package-name/src/main/res/

Don’t forget to replace the paths with correct ones and create the assets folder if it doesn’t exist.

Now, create a release build of your native app from within Android Studio as usual and you should be good to go!

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.61/integration-with-existing-apps/index.html b/docs/0.61/integration-with-existing-apps/index.html index 56a67d29514..24f2bb849f4 100644 --- a/docs/0.61/integration-with-existing-apps/index.html +++ b/docs/0.61/integration-with-existing-apps/index.html @@ -19,7 +19,7 @@ - + @@ -48,7 +48,7 @@
if (mReactInstanceManager != null) {
mReactInstanceManager.onHostDestroy(this);
}
if (mReactRootView != null) {
mReactRootView.unmountReactApplication();
}
}

We also need to pass back button events to React Native:

@Override
public void onBackPressed() {
if (mReactInstanceManager != null) {
mReactInstanceManager.onBackPressed();
} else {
super.onBackPressed();
}
}

This allows JavaScript to control what happens when the user presses the hardware back button (e.g. to implement navigation). When JavaScript doesn't handle the back button press, your invokeDefaultOnBackPressed method will be called. By default this finishes your Activity.

Finally, we need to hook up the dev menu. By default, this is activated by (rage) shaking the device, but this is not very useful in emulators. So we make it show when you press the hardware menu button (use Ctrl + M if you're using Android Studio emulator):

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
if (keyCode == KeyEvent.KEYCODE_MENU && mReactInstanceManager != null) {
mReactInstanceManager.showDevOptionsDialog();
return true;
}
return super.onKeyUp(keyCode, event);
}

Now your activity is ready to run some JavaScript code.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ yarn start
2. Run the app

Now build and run your Android app as normal.

Once you reach your React-powered activity inside the app, it should load the JavaScript code from the development server and display:

Screenshot

Creating a release build in Android Studio

You can use Android Studio to create your release builds too! It’s as quick as creating release builds of your previously-existing native Android app. There’s one additional step, which you’ll have to do before every release build. You need to execute the following to create a React Native bundle, which will be included with your native Android app:

$ npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/com/your-company-name/app-package-name/src/main/assets/index.android.bundle --assets-dest android/com/your-company-name/app-package-name/src/main/res/

Don’t forget to replace the paths with correct ones and create the assets folder if it doesn’t exist.

Now, create a release build of your native app from within Android Studio as usual and you should be good to go!

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.61/interactionmanager.html b/docs/0.61/interactionmanager.html index cb6e7ef5219..aea9582b260 100644 --- a/docs/0.61/interactionmanager.html +++ b/docs/0.61/interactionmanager.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

InteractionManager

InteractionManager allows long-running work to be scheduled after any interactions/animations have completed. In particular, this allows JavaScript animations to run smoothly.

Applications can schedule tasks to run after interactions with the following:

InteractionManager.runAfterInteractions(() => {
// ...long-running synchronous task...
});

Compare this to other scheduling alternatives:

  • requestAnimationFrame(): for code that animates a view over time.
  • setImmediate/setTimeout(): run code later, note this may delay animations.
  • runAfterInteractions(): run code later, without delaying active animations.

The touch handling system considers one or more active touches to be an 'interaction' and will delay runAfterInteractions() callbacks until all touches have ended or been cancelled.

InteractionManager also allows applications to register animations by creating an interaction 'handle' on animation start, and clearing it upon completion:

var handle = InteractionManager.createInteractionHandle();
// run animation... (`runAfterInteractions` tasks are queued)
// later, on animation completion:
InteractionManager.clearInteractionHandle(handle);
// queued tasks run if all handles were cleared

runAfterInteractions takes either a plain callback function, or a PromiseTask object with a gen method that returns a Promise. If a PromiseTask is supplied, then it is fully resolved (including asynchronous dependencies that also schedule more tasks via runAfterInteractions) before starting on the next task that might have been queued up synchronously earlier.

By default, queued tasks are executed together in a loop in one setImmediate batch. If setDeadline is called with a positive number, then tasks will only be executed until the deadline (in terms of js event loop run time) approaches, at which point execution will yield via setTimeout, allowing events such as touches to start interactions and block queued tasks from executing, making apps more responsive.

Reference

Methods

runAfterInteractions()

static runAfterInteractions(task)

Schedule a function to run after all interactions have completed. Returns a cancellable "promise".

createInteractionHandle()

static createInteractionHandle()

Notify manager that an interaction has started.

clearInteractionHandle()

static clearInteractionHandle(handle)

Notify manager that an interaction has completed.

setDeadline()

static setDeadline(deadline)

A positive number will use setTimeout to schedule any tasks after the eventLoopRunningTime hits the deadline value, otherwise all tasks will be executed in one setImmediate batch (default).

Properties

Edit this page
Last updated on
- + diff --git a/docs/0.61/interactionmanager/index.html b/docs/0.61/interactionmanager/index.html index cb6e7ef5219..aea9582b260 100644 --- a/docs/0.61/interactionmanager/index.html +++ b/docs/0.61/interactionmanager/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

InteractionManager

InteractionManager allows long-running work to be scheduled after any interactions/animations have completed. In particular, this allows JavaScript animations to run smoothly.

Applications can schedule tasks to run after interactions with the following:

InteractionManager.runAfterInteractions(() => {
// ...long-running synchronous task...
});

Compare this to other scheduling alternatives:

  • requestAnimationFrame(): for code that animates a view over time.
  • setImmediate/setTimeout(): run code later, note this may delay animations.
  • runAfterInteractions(): run code later, without delaying active animations.

The touch handling system considers one or more active touches to be an 'interaction' and will delay runAfterInteractions() callbacks until all touches have ended or been cancelled.

InteractionManager also allows applications to register animations by creating an interaction 'handle' on animation start, and clearing it upon completion:

var handle = InteractionManager.createInteractionHandle();
// run animation... (`runAfterInteractions` tasks are queued)
// later, on animation completion:
InteractionManager.clearInteractionHandle(handle);
// queued tasks run if all handles were cleared

runAfterInteractions takes either a plain callback function, or a PromiseTask object with a gen method that returns a Promise. If a PromiseTask is supplied, then it is fully resolved (including asynchronous dependencies that also schedule more tasks via runAfterInteractions) before starting on the next task that might have been queued up synchronously earlier.

By default, queued tasks are executed together in a loop in one setImmediate batch. If setDeadline is called with a positive number, then tasks will only be executed until the deadline (in terms of js event loop run time) approaches, at which point execution will yield via setTimeout, allowing events such as touches to start interactions and block queued tasks from executing, making apps more responsive.

Reference

Methods

runAfterInteractions()

static runAfterInteractions(task)

Schedule a function to run after all interactions have completed. Returns a cancellable "promise".

createInteractionHandle()

static createInteractionHandle()

Notify manager that an interaction has started.

clearInteractionHandle()

static clearInteractionHandle(handle)

Notify manager that an interaction has completed.

setDeadline()

static setDeadline(deadline)

A positive number will use setTimeout to schedule any tasks after the eventLoopRunningTime hits the deadline value, otherwise all tasks will be executed in one setImmediate batch (default).

Properties

Edit this page
Last updated on
- + diff --git a/docs/0.61/intro-react-native-components.html b/docs/0.61/intro-react-native-components.html index 21676a952b5..f454da734d3 100644 --- a/docs/0.61/intro-react-native-components.html +++ b/docs/0.61/intro-react-native-components.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Core Components and Native Components

React Native is an open source framework for building Android and iOS applications using React and the app platform’s native capabilities. With React Native, you use JavaScript to access your platform’s APIs as well as to describe the appearance and behavior of your UI using React components: bundles of reusable, nestable code. You can learn more about React in the next section. But first, let’s cover how components work in React Native.

Views and mobile development

In Android and iOS development, a view is the basic building block of UI: a small rectangular element on the screen which can be used to display text, images, or respond to user input. Even the smallest visual elements of an app, like a line of text or a button, are kinds of views. Some kinds of views can contain other views. It’s views all the way down!

Diagram of Android and iOS app showing them both built on top of atomic elements called views.
Just a sampling of the many views used in Android and iOS apps.

Native Components

In Android development, you write views in Kotlin or Java; in iOS development, you use Swift or Objective-C. With React Native, you can invoke these views with JavaScript using React components. At runtime, React Native creates the corresponding Android and iOS views for those components. Because React Native components are backed by the same views as Android and iOS, React Native apps look, feel, and perform like any other apps. We call these platform-backed components Native Components.

React Native lets you to build your own Native Components for Android and iOS to suit your app’s unique needs. We also have a thriving ecosystem of these community-contributed components. Check out Native Directory to find what the community has been creating.

React Native also includes a set of essential, ready-to-use Native Components you can use to start building your app today. These are React Native's Core Components.

Core Components

React Native has many Core Components for everything from form controls to activity indicators. You can find them all documented in the API section. You will mostly work with the following Core Components:

React Native UI ComponentAndroid ViewiOS ViewWeb AnalogDescription
<View><ViewGroup><UIView>A non-scrollling <div>A container that supports layout with flexbox, style, some touch handling, and accessibility controls
<Text><TextView><UITextView><p>Displays, styles, and nests strings of text and even handles touch events
<Image><ImageView><UIImageView><img>Displays different types of images
<ScrollView><ScrollView><UIScrollView><div>A generic scrolling container that can contain multiple components and views
<TextInput><EditText><UITextField><input type="text">Allows the user to enter text

In the next section, you will start combining these Core Components to learn about how React works. Have a play with them here now!

Because React Native uses the same API structure as React components, you’ll need to understand React component APIs to get started. The next section makes for a quick introduction or refresher on the topic. However, if you’re already familiar with React, feel free to skip ahead.

A diagram showing React Native's Core Components are a subset of React Components that ship with React Native.
Edit this page
Last updated on
- + diff --git a/docs/0.61/intro-react-native-components/index.html b/docs/0.61/intro-react-native-components/index.html index 21676a952b5..f454da734d3 100644 --- a/docs/0.61/intro-react-native-components/index.html +++ b/docs/0.61/intro-react-native-components/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Core Components and Native Components

React Native is an open source framework for building Android and iOS applications using React and the app platform’s native capabilities. With React Native, you use JavaScript to access your platform’s APIs as well as to describe the appearance and behavior of your UI using React components: bundles of reusable, nestable code. You can learn more about React in the next section. But first, let’s cover how components work in React Native.

Views and mobile development

In Android and iOS development, a view is the basic building block of UI: a small rectangular element on the screen which can be used to display text, images, or respond to user input. Even the smallest visual elements of an app, like a line of text or a button, are kinds of views. Some kinds of views can contain other views. It’s views all the way down!

Diagram of Android and iOS app showing them both built on top of atomic elements called views.
Just a sampling of the many views used in Android and iOS apps.

Native Components

In Android development, you write views in Kotlin or Java; in iOS development, you use Swift or Objective-C. With React Native, you can invoke these views with JavaScript using React components. At runtime, React Native creates the corresponding Android and iOS views for those components. Because React Native components are backed by the same views as Android and iOS, React Native apps look, feel, and perform like any other apps. We call these platform-backed components Native Components.

React Native lets you to build your own Native Components for Android and iOS to suit your app’s unique needs. We also have a thriving ecosystem of these community-contributed components. Check out Native Directory to find what the community has been creating.

React Native also includes a set of essential, ready-to-use Native Components you can use to start building your app today. These are React Native's Core Components.

Core Components

React Native has many Core Components for everything from form controls to activity indicators. You can find them all documented in the API section. You will mostly work with the following Core Components:

React Native UI ComponentAndroid ViewiOS ViewWeb AnalogDescription
<View><ViewGroup><UIView>A non-scrollling <div>A container that supports layout with flexbox, style, some touch handling, and accessibility controls
<Text><TextView><UITextView><p>Displays, styles, and nests strings of text and even handles touch events
<Image><ImageView><UIImageView><img>Displays different types of images
<ScrollView><ScrollView><UIScrollView><div>A generic scrolling container that can contain multiple components and views
<TextInput><EditText><UITextField><input type="text">Allows the user to enter text

In the next section, you will start combining these Core Components to learn about how React works. Have a play with them here now!

Because React Native uses the same API structure as React components, you’ll need to understand React component APIs to get started. The next section makes for a quick introduction or refresher on the topic. However, if you’re already familiar with React, feel free to skip ahead.

A diagram showing React Native's Core Components are a subset of React Components that ship with React Native.
Edit this page
Last updated on
- + diff --git a/docs/0.61/intro-react.html b/docs/0.61/intro-react.html index 1fac2021f8b..fdf6b4ec2fb 100644 --- a/docs/0.61/intro-react.html +++ b/docs/0.61/intro-react.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
export default Cat;

This is one of many ways to export your component. This kind of export works well with the Snack Player. However, depending on your app’s file structure, you might need to use a different convention. This handy cheatsheet on JavaScript imports and exports can help.

Now take a closer look at that return statement. <Text>Hello, I am your cat!</Text> is using a kind of JavaScript syntax that makes writing elements convenient: JSX.

JSX

React and React Native use JSX, a syntax that lets you write elements inside JavaScript like so: <Text>Hello, I am your cat!</Text>. The React docs have a comprehensive guide to JSX you can reference to learn even more. Because JSX is JavaScript, you can use variables inside it. Here you are declaring a name for the cat, name, and embedding it with curly braces inside <Text>.

Any JavaScript expression will work between curly braces, including function calls like {getFullName("Rum", "Tum", "Tugger")}:

You can think of curly braces as creating a portal into JS functionality in your JSX!

Because JSX is included in the React library, it won’t work if you don’t have import React from 'react' at the top of your file!

Custom Components

You’ve already met React Native’s Core Components. React lets you nest these components inside each other to create new components. These nestable, reusable components are at the heart of the React paradigm.

For example, you can nest Text and TextInput inside a View below, and React Native will render them together:

Developer notes

If you’re familiar with web development, <View> and <Text> might remind you of HTML! You can think of them as the <div> and <p> tags of application development.

You can render this component multiple times and in multiple places without repeating your code by using <Cat>:

Any component that renders other components is a parent component. Here, Cafe is the parent component and each Cat is a child component.

You can put as many cats in your cafe as you like. Each <Cat> renders a unique element—which you can customize with props.

Props

Props is short for “properties.” Props let you customize React components. For example, here you pass each <Cat> a different name for Cat to render:

Most of React Native’s Core Components can be customized with props, too. For example, when using Image, you pass it a prop named source to define what image it shows:

Image has many different props, including style, which accepts a JS object of design and layout related property-value pairs.

Notice the double curly braces {{ }} surrounding style‘s width and height. In JSX, JavaScript values are referenced with {}. This is handy if you are passing something other than a string as props, like an array or number: <Cat food={["fish", "kibble"]} age={2} />. However, JS objects are also denoted with curly braces: {width: 200, height: 200}. Therefore, to pass a JS object in JSX, you must wrap the object in another pair of curly braces: {{width: 200, height: 200}}

You can build many things with props and the Core Components Text, Image, and View! But to build something interactive, you’ll need state.

State

While you can think of props as arguments you use to configure how components render, state is like a component’s personal data storage. State is useful for handling data that changes over time or that comes from user interaction. State gives your components memory!

As a general rule, use props to configure a component when it renders. Use state to keep track of any component data that you expect to change over time.

The following example takes place in a cat cafe where two hungry cats are waiting to be fed. Their hunger, which we expect to change over time (unlike their names), is stored as state. To feed the cats, press their buttons—which will update their state.

You can add state to a component by calling React’s useState Hook. A Hook is a kind of function that lets you “hook into” React features. For example, useState is a Hook that lets you add state to function components. You can learn more about other kinds of Hooks in the React documentation.

First, you will want to import useState from React like so:

import React, { useState } from 'react';

Then you declare the component’s state by calling useState inside its function. In this example, useState creates an isHungry state variable:

const Cat = (props) => {
const [isHungry, setIsHungry] = useState(true);
// ...
};

You can use useState to track any kind of data: strings, numbers, Booleans, arrays, objects. For example, you can track the number of times a cat has been petted with const [timesPetted, setTimesPetted] = useState(0)!

Calling useState does two things:

  • it creates a “state variable” with an initial value—in this case the state variable is isHungry and its initial value is true
  • it creates a function to set that state variable’s value—setIsHungry

It doesn’t matter what names you use. But it can be handy to think of the pattern as [<getter>, <setter>] = useState(<initialValue>).

Next you add the Button Core Component and give it an onPress prop:

<Button
onPress={() => {
setIsHungry(false);
}}
//..
/>

Now, when someone presses the button, onPress will fire, calling the setIsHungry(false). This sets the state variable isHungry to false. When isHungry is false, the Button’s disabled prop is set to true and its title also changes:

<Button
//..
disabled={!isHungry}
title={isHungry ? 'Pour me some milk, please!' : 'Thank you!'}
/>

You might’ve noticed that although isHungry is a const, it is seemingly reassignable! What is happening is when a state-setting function like setIsHungry is called, its component will re-render. In this case the Cat function will run again—and this time, useState will give us the next value of isHungry.

Finally, put your cats inside a Cafe component:

const Cafe = () => {
return (
<>
<Cat name="Munkustrap" />
<Cat name="Spot" />
</>
);
};

See the <> and </> above? These bits of JSX are fragments. Adjacent JSX elements must be wrapped in an enclosing tag. Fragments let you do that without nesting an extra, unnecessary wrapping element like View.

Now that you’ve covered both React and React Native’s Core Components, let’s dive deeper on some of these core components by looking at handling <TextInput>.

Edit this page
Last updated on
- + diff --git a/docs/0.61/intro-react/index.html b/docs/0.61/intro-react/index.html index 1fac2021f8b..fdf6b4ec2fb 100644 --- a/docs/0.61/intro-react/index.html +++ b/docs/0.61/intro-react/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
export default Cat;

This is one of many ways to export your component. This kind of export works well with the Snack Player. However, depending on your app’s file structure, you might need to use a different convention. This handy cheatsheet on JavaScript imports and exports can help.

Now take a closer look at that return statement. <Text>Hello, I am your cat!</Text> is using a kind of JavaScript syntax that makes writing elements convenient: JSX.

JSX

React and React Native use JSX, a syntax that lets you write elements inside JavaScript like so: <Text>Hello, I am your cat!</Text>. The React docs have a comprehensive guide to JSX you can reference to learn even more. Because JSX is JavaScript, you can use variables inside it. Here you are declaring a name for the cat, name, and embedding it with curly braces inside <Text>.

Any JavaScript expression will work between curly braces, including function calls like {getFullName("Rum", "Tum", "Tugger")}:

You can think of curly braces as creating a portal into JS functionality in your JSX!

Because JSX is included in the React library, it won’t work if you don’t have import React from 'react' at the top of your file!

Custom Components

You’ve already met React Native’s Core Components. React lets you nest these components inside each other to create new components. These nestable, reusable components are at the heart of the React paradigm.

For example, you can nest Text and TextInput inside a View below, and React Native will render them together:

Developer notes

If you’re familiar with web development, <View> and <Text> might remind you of HTML! You can think of them as the <div> and <p> tags of application development.

You can render this component multiple times and in multiple places without repeating your code by using <Cat>:

Any component that renders other components is a parent component. Here, Cafe is the parent component and each Cat is a child component.

You can put as many cats in your cafe as you like. Each <Cat> renders a unique element—which you can customize with props.

Props

Props is short for “properties.” Props let you customize React components. For example, here you pass each <Cat> a different name for Cat to render:

Most of React Native’s Core Components can be customized with props, too. For example, when using Image, you pass it a prop named source to define what image it shows:

Image has many different props, including style, which accepts a JS object of design and layout related property-value pairs.

Notice the double curly braces {{ }} surrounding style‘s width and height. In JSX, JavaScript values are referenced with {}. This is handy if you are passing something other than a string as props, like an array or number: <Cat food={["fish", "kibble"]} age={2} />. However, JS objects are also denoted with curly braces: {width: 200, height: 200}. Therefore, to pass a JS object in JSX, you must wrap the object in another pair of curly braces: {{width: 200, height: 200}}

You can build many things with props and the Core Components Text, Image, and View! But to build something interactive, you’ll need state.

State

While you can think of props as arguments you use to configure how components render, state is like a component’s personal data storage. State is useful for handling data that changes over time or that comes from user interaction. State gives your components memory!

As a general rule, use props to configure a component when it renders. Use state to keep track of any component data that you expect to change over time.

The following example takes place in a cat cafe where two hungry cats are waiting to be fed. Their hunger, which we expect to change over time (unlike their names), is stored as state. To feed the cats, press their buttons—which will update their state.

You can add state to a component by calling React’s useState Hook. A Hook is a kind of function that lets you “hook into” React features. For example, useState is a Hook that lets you add state to function components. You can learn more about other kinds of Hooks in the React documentation.

First, you will want to import useState from React like so:

import React, { useState } from 'react';

Then you declare the component’s state by calling useState inside its function. In this example, useState creates an isHungry state variable:

const Cat = (props) => {
const [isHungry, setIsHungry] = useState(true);
// ...
};

You can use useState to track any kind of data: strings, numbers, Booleans, arrays, objects. For example, you can track the number of times a cat has been petted with const [timesPetted, setTimesPetted] = useState(0)!

Calling useState does two things:

  • it creates a “state variable” with an initial value—in this case the state variable is isHungry and its initial value is true
  • it creates a function to set that state variable’s value—setIsHungry

It doesn’t matter what names you use. But it can be handy to think of the pattern as [<getter>, <setter>] = useState(<initialValue>).

Next you add the Button Core Component and give it an onPress prop:

<Button
onPress={() => {
setIsHungry(false);
}}
//..
/>

Now, when someone presses the button, onPress will fire, calling the setIsHungry(false). This sets the state variable isHungry to false. When isHungry is false, the Button’s disabled prop is set to true and its title also changes:

<Button
//..
disabled={!isHungry}
title={isHungry ? 'Pour me some milk, please!' : 'Thank you!'}
/>

You might’ve noticed that although isHungry is a const, it is seemingly reassignable! What is happening is when a state-setting function like setIsHungry is called, its component will re-render. In this case the Cat function will run again—and this time, useState will give us the next value of isHungry.

Finally, put your cats inside a Cafe component:

const Cafe = () => {
return (
<>
<Cat name="Munkustrap" />
<Cat name="Spot" />
</>
);
};

See the <> and </> above? These bits of JSX are fragments. Adjacent JSX elements must be wrapped in an enclosing tag. Fragments let you do that without nesting an extra, unnecessary wrapping element like View.

Now that you’ve covered both React and React Native’s Core Components, let’s dive deeper on some of these core components by looking at handling <TextInput>.

Edit this page
Last updated on
- + diff --git a/docs/0.61/javascript-environment.html b/docs/0.61/javascript-environment.html index 8c0bf672d57..14671ef1d53 100644 --- a/docs/0.61/javascript-environment.html +++ b/docs/0.61/javascript-environment.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

JavaScript Environment

JavaScript Runtime

When using React Native, you're going to be running your JavaScript code in two environments:

  • In most cases, React Native will use JavaScriptCore, the JavaScript engine that powers Safari. Note that on iOS, JavaScriptCore does not use JIT due to the absence of writable executable memory in iOS apps.
  • When using Chrome debugging, all JavaScript code runs within Chrome itself, communicating with native code via WebSockets. Chrome uses V8 as its JavaScript engine.

While both environments are very similar, you may end up hitting some inconsistencies. We're likely going to experiment with other JavaScript engines in the future, so it's best to avoid relying on specifics of any runtime.

JavaScript Syntax Transformers

Syntax transformers make writing code more enjoyable by allowing you to use new JavaScript syntax without having to wait for support on all interpreters.

React Native ships with the Babel JavaScript compiler. Check Babel documentation on its supported transformations for more details.

A full list of React Native's enabled transformations can be found in metro-react-native-babel-preset.

ES5

  • Reserved Words: promise.catch(function() { });

ES6

ES8

Stage 3

Specific

  • JSX: <View style={{color: 'red'}} />
  • Flow: function foo(x: ?number): string {};
  • TypeScript: function foo(x: number | undefined): string {};
  • Babel Template: allows AST templating

Polyfills

Many standards functions are also available on all the supported JavaScript runtimes.

Browser

ES6

ES7

ES8

Specific

  • __DEV__
Edit this page
Last updated on
- + diff --git a/docs/0.61/javascript-environment/index.html b/docs/0.61/javascript-environment/index.html index 8c0bf672d57..14671ef1d53 100644 --- a/docs/0.61/javascript-environment/index.html +++ b/docs/0.61/javascript-environment/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

JavaScript Environment

JavaScript Runtime

When using React Native, you're going to be running your JavaScript code in two environments:

  • In most cases, React Native will use JavaScriptCore, the JavaScript engine that powers Safari. Note that on iOS, JavaScriptCore does not use JIT due to the absence of writable executable memory in iOS apps.
  • When using Chrome debugging, all JavaScript code runs within Chrome itself, communicating with native code via WebSockets. Chrome uses V8 as its JavaScript engine.

While both environments are very similar, you may end up hitting some inconsistencies. We're likely going to experiment with other JavaScript engines in the future, so it's best to avoid relying on specifics of any runtime.

JavaScript Syntax Transformers

Syntax transformers make writing code more enjoyable by allowing you to use new JavaScript syntax without having to wait for support on all interpreters.

React Native ships with the Babel JavaScript compiler. Check Babel documentation on its supported transformations for more details.

A full list of React Native's enabled transformations can be found in metro-react-native-babel-preset.

ES5

  • Reserved Words: promise.catch(function() { });

ES6

ES8

Stage 3

Specific

  • JSX: <View style={{color: 'red'}} />
  • Flow: function foo(x: ?number): string {};
  • TypeScript: function foo(x: number | undefined): string {};
  • Babel Template: allows AST templating

Polyfills

Many standards functions are also available on all the supported JavaScript runtimes.

Browser

ES6

ES7

ES8

Specific

  • __DEV__
Edit this page
Last updated on
- + diff --git a/docs/0.61/keyboard.html b/docs/0.61/keyboard.html index 17473ae3800..8cfb4f64dee 100644 --- a/docs/0.61/keyboard.html +++ b/docs/0.61/keyboard.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
render() {
return <TextInput onSubmitEditing={Keyboard.dismiss} />;
}
}

Reference

Methods

addListener()

static addListener(eventName, callback)

The addListener function connects a JavaScript function to an identified native keyboard notification event.

This function then returns the reference to the listener.

@param {string} eventName The nativeEvent is the string that identifies the event you're listening for. This can be any of the following:

Note that if you set android:windowSoftInputMode to adjustResize, only keyboardDidShow and keyboardDidHide events will be available on Android. If you set android:windowSoftInputMode to adjustNothing, no events will be available on Android. keyboardWillShow as well as keyboardWillHide are generally not available on Android since there is no native corresponding event.

@param {function} callback function to be called when the event fires.

removeListener()

static removeListener(eventName, callback)

Removes a specific listener.

@param {string} eventName The nativeEvent is the string that identifies the event you're listening for. @param {function} callback function to be called when the event fires.

removeAllListeners()

static removeAllListeners(eventName)

Removes all listeners for a specific event type.

@param {string} eventType The native event string listeners are watching which will be removed.

dismiss()

static dismiss()

Dismisses the active keyboard and removes focus.

Edit this page
Last updated on
- + diff --git a/docs/0.61/keyboard/index.html b/docs/0.61/keyboard/index.html index 17473ae3800..8cfb4f64dee 100644 --- a/docs/0.61/keyboard/index.html +++ b/docs/0.61/keyboard/index.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
render() {
return <TextInput onSubmitEditing={Keyboard.dismiss} />;
}
}

Reference

Methods

addListener()

static addListener(eventName, callback)

The addListener function connects a JavaScript function to an identified native keyboard notification event.

This function then returns the reference to the listener.

@param {string} eventName The nativeEvent is the string that identifies the event you're listening for. This can be any of the following:

Note that if you set android:windowSoftInputMode to adjustResize, only keyboardDidShow and keyboardDidHide events will be available on Android. If you set android:windowSoftInputMode to adjustNothing, no events will be available on Android. keyboardWillShow as well as keyboardWillHide are generally not available on Android since there is no native corresponding event.

@param {function} callback function to be called when the event fires.

removeListener()

static removeListener(eventName, callback)

Removes a specific listener.

@param {string} eventName The nativeEvent is the string that identifies the event you're listening for. @param {function} callback function to be called when the event fires.

removeAllListeners()

static removeAllListeners(eventName)

Removes all listeners for a specific event type.

@param {string} eventType The native event string listeners are watching which will be removed.

dismiss()

static dismiss()

Dismisses the active keyboard and removes focus.

Edit this page
Last updated on
- + diff --git a/docs/0.61/keyboardavoidingview.html b/docs/0.61/keyboardavoidingview.html index 775e6988290..944572a4ee9 100644 --- a/docs/0.61/keyboardavoidingview.html +++ b/docs/0.61/keyboardavoidingview.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
<KeyboardAvoidingView
style={styles.container}
behavior="padding"
enabled>
... your UI ...
</KeyboardAvoidingView>;

Example

Reference

Props

Inherits View Props.

behavior

Specify how to react to the presence of the keyboard.

Note: Android and iOS both interact with this prop differently. Android may behave better when given no behavior prop at all, whereas iOS is the opposite.

TypeRequired
enum('height', 'position', 'padding')No

contentContainerStyle

The style of the content container(View) when behavior is 'position'.

TypeRequired
View.styleNo

enabled

Enabled or disabled KeyboardAvoidingView. The default is true.

TypeRequired
booleanNo

keyboardVerticalOffset

This is the distance between the top of the user screen and the react native view, may be non-zero in some use cases. Defaults to 0.

TypeRequired
numberNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/keyboardavoidingview/index.html b/docs/0.61/keyboardavoidingview/index.html index 775e6988290..944572a4ee9 100644 --- a/docs/0.61/keyboardavoidingview/index.html +++ b/docs/0.61/keyboardavoidingview/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
<KeyboardAvoidingView
style={styles.container}
behavior="padding"
enabled>
... your UI ...
</KeyboardAvoidingView>;

Example

Reference

Props

Inherits View Props.

behavior

Specify how to react to the presence of the keyboard.

Note: Android and iOS both interact with this prop differently. Android may behave better when given no behavior prop at all, whereas iOS is the opposite.

TypeRequired
enum('height', 'position', 'padding')No

contentContainerStyle

The style of the content container(View) when behavior is 'position'.

TypeRequired
View.styleNo

enabled

Enabled or disabled KeyboardAvoidingView. The default is true.

TypeRequired
booleanNo

keyboardVerticalOffset

This is the distance between the top of the user screen and the react native view, may be non-zero in some use cases. Defaults to 0.

TypeRequired
numberNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/layout-props.html b/docs/0.61/layout-props.html index 9b11fbcf9fa..f3e0d826ef7 100644 --- a/docs/0.61/layout-props.html +++ b/docs/0.61/layout-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Layout Props

Reference

Props

alignContent

alignContent controls how rows align in the cross direction, overriding the alignContent of the parent. See https://developer.mozilla.org/en-US/docs/Web/CSS/align-content for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'stretch', 'space-between', 'space-around')No

alignItems

alignItems aligns children in the cross direction. For example, if children are flowing vertically, alignItems controls how they align horizontally. It works like align-items in CSS (default: stretch). See https://developer.mozilla.org/en-US/docs/Web/CSS/align-items for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'stretch', 'baseline')No

alignSelf

alignSelf controls how a child aligns in the cross direction, overriding the alignItems of the parent. It works like align-self in CSS (default: auto). See https://developer.mozilla.org/en-US/docs/Web/CSS/align-self for more details.

TypeRequired
enum('auto', 'flex-start', 'flex-end', 'center', 'stretch', 'baseline')No

aspectRatio

Aspect ratio controls the size of the undefined dimension of a node. Aspect ratio is a non-standard property only available in React Native and not CSS.

  • On a node with a set width/height aspect ratio controls the size of the unset dimension
  • On a node with a set flex basis aspect ratio controls the size of the node in the cross axis if unset
  • On a node with a measure function aspect ratio works as though the measure function measures the flex basis
  • On a node with flex grow/shrink aspect ratio controls the size of the node in the cross axis if unset
  • Aspect ratio takes min/max dimensions into account
TypeRequired
numberNo

borderBottomWidth

borderBottomWidth works like border-bottom-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-width for more details.

TypeRequired
numberNo

borderEndWidth

When direction is ltr, borderEndWidth is equivalent to borderRightWidth. When direction is rtl, borderEndWidth is equivalent to borderLeftWidth.

TypeRequired
numberNo

borderLeftWidth

borderLeftWidth works like border-left-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-left-width for more details.

TypeRequired
numberNo

borderRightWidth

borderRightWidth works like border-right-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-right-width for more details.

TypeRequired
numberNo

borderStartWidth

When direction is ltr, borderStartWidth is equivalent to borderLeftWidth. When direction is rtl, borderStartWidth is equivalent to borderRightWidth.

TypeRequired
numberNo

borderTopWidth

borderTopWidth works like border-top-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-top-width for more details.

TypeRequired
numberNo

borderWidth

borderWidth works like border-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-width for more details.

TypeRequired
numberNo

bottom

bottom is the number of logical pixels to offset the bottom edge of this component.

It works similarly to bottom in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/bottom for more details of how bottom affects layout.

TypeRequired
number, stringNo

direction

direction specifies the directional flow of the user interface. The default is inherit, except for root node which will have value based on the current locale. See https://yogalayout.com/docs/layout-direction for more details.

TypeRequiredPlatform
enum('inherit', 'ltr', 'rtl')NoiOS

display

display sets the display type of this component.

It works similarly to display in CSS, but only support 'flex' and 'none'. 'flex' is the default.

TypeRequired
enum('none', 'flex')No

end

When the direction is ltr, end is equivalent to right. When the direction is rtl, end is equivalent to left.

This style takes precedence over the left and right styles.

TypeRequired
number, stringNo

flex

In React Native flex does not work the same way that it does in CSS. flex is a number rather than a string, and it works according to the Yoga.

When flex is a positive number, it makes the component flexible and it will be sized proportional to its flex value. So a component with flex set to 2 will take twice the space as a component with flex set to 1. flex: <positive number> equates to flexGrow: <positive number>, flexShrink: 1, flexBasis: 0.

When flex is 0, the component is sized according to width and height and it is inflexible.

When flex is -1, the component is normally sized according width and height. However, if there's not enough space, the component will shrink to its minWidth and minHeight.

flexGrow, flexShrink, and flexBasis work the same as in CSS.

TypeRequired
numberNo

flexBasis

TypeRequired
number, stringNo

flexDirection

flexDirection controls which directions children of a container go. row goes left to right, column goes top to bottom, and you may be able to guess what the other two do. It works like flex-direction in CSS, except the default is column. See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction for more details.

TypeRequired
enum('row', 'row-reverse', 'column', 'column-reverse')No

flexGrow

TypeRequired
numberNo

flexShrink

TypeRequired
numberNo

flexWrap

flexWrap controls whether children can wrap around after they hit the end of a flex container. It works like flex-wrap in CSS (default: nowrap). See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-wrap for more details. Note it does not work anymore with alignItems: stretch (the default), so you may want to use alignItems: flex-start for example (breaking change details: https://github.com/facebook/react-native/releases/tag/v0.28.0).

TypeRequired
enum('wrap', 'nowrap')No

height

height sets the height of this component.

It works similarly to height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported. See https://developer.mozilla.org/en-US/docs/Web/CSS/height for more details.

TypeRequired
number, stringNo

justifyContent

justifyContent aligns children in the main direction. For example, if children are flowing vertically, justifyContent controls how they align vertically. It works like justify-content in CSS (default: flex-start). See https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'space-between', 'space-around', 'space-evenly')No

left

left is the number of logical pixels to offset the left edge of this component.

It works similarly to left in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/left for more details of how left affects layout.

TypeRequired
number, stringNo

margin

Setting margin has the same effect as setting each of marginTop, marginLeft, marginBottom, and marginRight. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin for more details.

TypeRequired
number, stringNo

marginBottom

marginBottom works like margin-bottom in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-bottom for more details.

TypeRequired
number, stringNo

marginEnd

When direction is ltr, marginEnd is equivalent to marginRight. When direction is rtl, marginEnd is equivalent to marginLeft.

TypeRequired
number, stringNo

marginHorizontal

Setting marginHorizontal has the same effect as setting both marginLeft and marginRight.

TypeRequired
number, stringNo

marginLeft

marginLeft works like margin-left in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-left for more details.

TypeRequired
number, stringNo

marginRight

marginRight works like margin-right in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-right for more details.

TypeRequired
number, stringNo

marginStart

When direction is ltr, marginStart is equivalent to marginLeft. When direction is rtl, marginStart is equivalent to marginRight.

TypeRequired
number, stringNo

marginTop

marginTop works like margin-top in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-top for more details.

TypeRequired
number, stringNo

marginVertical

Setting marginVertical has the same effect as setting both marginTop and marginBottom.

TypeRequired
number, stringNo

maxHeight

maxHeight is the maximum height for this component, in logical pixels.

It works similarly to max-height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/max-height for more details.

TypeRequired
number, stringNo

maxWidth

maxWidth is the maximum width for this component, in logical pixels.

It works similarly to max-width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/max-width for more details.

TypeRequired
number, stringNo

minHeight

minHeight is the minimum height for this component, in logical pixels.

It works similarly to min-height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/min-height for more details.

TypeRequired
number, stringNo

minWidth

minWidth is the minimum width for this component, in logical pixels.

It works similarly to min-width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/min-width for more details.

TypeRequired
number, stringNo

overflow

overflow controls how children are measured and displayed. overflow: hidden causes views to be clipped while overflow: scroll causes views to be measured independently of their parents main axis. It works like overflow in CSS (default: visible). See https://developer.mozilla.org/en/docs/Web/CSS/overflow for more details.

TypeRequired
enum('visible', 'hidden', 'scroll')No

padding

Setting padding has the same effect as setting each of paddingTop, paddingBottom, paddingLeft, and paddingRight. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding for more details.

TypeRequired
number, stringNo

paddingBottom

paddingBottom works like padding-bottom in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-bottom for more details.

TypeRequired
number, stringNo

paddingEnd

When direction is ltr, paddingEnd is equivalent to paddingRight. When direction is rtl, paddingEnd is equivalent to paddingLeft.

TypeRequired
number, stringNo

paddingHorizontal

Setting paddingHorizontal is like setting both of paddingLeft and paddingRight.

TypeRequired
number, stringNo

paddingLeft

paddingLeft works like padding-left in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-left for more details.

TypeRequired
number, stringNo

paddingRight

paddingRight works like padding-right in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-right for more details.

TypeRequired
number, stringNo

paddingStart

When direction is ltr, paddingStart is equivalent to paddingLeft. When direction is rtl, paddingStart is equivalent to paddingRight.

TypeRequired
number, stringNo

paddingTop

paddingTop works like padding-top in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-top for more details.

TypeRequired
number, ,stringNo

paddingVertical

Setting paddingVertical is like setting both of paddingTop and paddingBottom.

TypeRequired
number, stringNo

position

position in React Native is similar to regular CSS, but everything is set to relative by default, so absolute positioning is always relative to the parent.

If you want to position a child using specific numbers of logical pixels relative to its parent, set the child to have absolute position.

If you want to position a child relative to something that is not its parent, don't use styles for that. Use the component tree.

See https://github.com/facebook/yoga for more details on how position differs between React Native and CSS.

TypeRequired
enum('absolute', 'relative')No

right

right is the number of logical pixels to offset the right edge of this component.

It works similarly to right in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/right for more details of how right affects layout.

TypeRequired
number, stringNo

start

When the direction is ltr, start is equivalent to left. When the direction is rtl, start is equivalent to right.

This style takes precedence over the left, right, and end styles.

TypeRequired
number, stringNo

top

top is the number of logical pixels to offset the top edge of this component.

It works similarly to top in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/top for more details of how top affects layout.

TypeRequired
number, stringNo

width

width sets the width of this component.

It works similarly to width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported. See https://developer.mozilla.org/en-US/docs/Web/CSS/width for more details.

TypeRequired
number, stringNo

zIndex

zIndex controls which components display on top of others. Normally, you don't use zIndex. Components render according to their order in the document tree, so later components draw over earlier ones. zIndex may be useful if you have animations or custom modal interfaces where you don't want this behavior.

It works like the CSS z-index property - components with a larger zIndex will render on top. Think of the z-direction like it's pointing from the phone into your eyeball. See https://developer.mozilla.org/en-US/docs/Web/CSS/z-index for more details.

On iOS, zIndex may require Views to be siblings of each other for it to work as expected.

TypeRequired
numberNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/layout-props/index.html b/docs/0.61/layout-props/index.html index 9b11fbcf9fa..f3e0d826ef7 100644 --- a/docs/0.61/layout-props/index.html +++ b/docs/0.61/layout-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Layout Props

Reference

Props

alignContent

alignContent controls how rows align in the cross direction, overriding the alignContent of the parent. See https://developer.mozilla.org/en-US/docs/Web/CSS/align-content for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'stretch', 'space-between', 'space-around')No

alignItems

alignItems aligns children in the cross direction. For example, if children are flowing vertically, alignItems controls how they align horizontally. It works like align-items in CSS (default: stretch). See https://developer.mozilla.org/en-US/docs/Web/CSS/align-items for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'stretch', 'baseline')No

alignSelf

alignSelf controls how a child aligns in the cross direction, overriding the alignItems of the parent. It works like align-self in CSS (default: auto). See https://developer.mozilla.org/en-US/docs/Web/CSS/align-self for more details.

TypeRequired
enum('auto', 'flex-start', 'flex-end', 'center', 'stretch', 'baseline')No

aspectRatio

Aspect ratio controls the size of the undefined dimension of a node. Aspect ratio is a non-standard property only available in React Native and not CSS.

  • On a node with a set width/height aspect ratio controls the size of the unset dimension
  • On a node with a set flex basis aspect ratio controls the size of the node in the cross axis if unset
  • On a node with a measure function aspect ratio works as though the measure function measures the flex basis
  • On a node with flex grow/shrink aspect ratio controls the size of the node in the cross axis if unset
  • Aspect ratio takes min/max dimensions into account
TypeRequired
numberNo

borderBottomWidth

borderBottomWidth works like border-bottom-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-width for more details.

TypeRequired
numberNo

borderEndWidth

When direction is ltr, borderEndWidth is equivalent to borderRightWidth. When direction is rtl, borderEndWidth is equivalent to borderLeftWidth.

TypeRequired
numberNo

borderLeftWidth

borderLeftWidth works like border-left-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-left-width for more details.

TypeRequired
numberNo

borderRightWidth

borderRightWidth works like border-right-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-right-width for more details.

TypeRequired
numberNo

borderStartWidth

When direction is ltr, borderStartWidth is equivalent to borderLeftWidth. When direction is rtl, borderStartWidth is equivalent to borderRightWidth.

TypeRequired
numberNo

borderTopWidth

borderTopWidth works like border-top-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-top-width for more details.

TypeRequired
numberNo

borderWidth

borderWidth works like border-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-width for more details.

TypeRequired
numberNo

bottom

bottom is the number of logical pixels to offset the bottom edge of this component.

It works similarly to bottom in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/bottom for more details of how bottom affects layout.

TypeRequired
number, stringNo

direction

direction specifies the directional flow of the user interface. The default is inherit, except for root node which will have value based on the current locale. See https://yogalayout.com/docs/layout-direction for more details.

TypeRequiredPlatform
enum('inherit', 'ltr', 'rtl')NoiOS

display

display sets the display type of this component.

It works similarly to display in CSS, but only support 'flex' and 'none'. 'flex' is the default.

TypeRequired
enum('none', 'flex')No

end

When the direction is ltr, end is equivalent to right. When the direction is rtl, end is equivalent to left.

This style takes precedence over the left and right styles.

TypeRequired
number, stringNo

flex

In React Native flex does not work the same way that it does in CSS. flex is a number rather than a string, and it works according to the Yoga.

When flex is a positive number, it makes the component flexible and it will be sized proportional to its flex value. So a component with flex set to 2 will take twice the space as a component with flex set to 1. flex: <positive number> equates to flexGrow: <positive number>, flexShrink: 1, flexBasis: 0.

When flex is 0, the component is sized according to width and height and it is inflexible.

When flex is -1, the component is normally sized according width and height. However, if there's not enough space, the component will shrink to its minWidth and minHeight.

flexGrow, flexShrink, and flexBasis work the same as in CSS.

TypeRequired
numberNo

flexBasis

TypeRequired
number, stringNo

flexDirection

flexDirection controls which directions children of a container go. row goes left to right, column goes top to bottom, and you may be able to guess what the other two do. It works like flex-direction in CSS, except the default is column. See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction for more details.

TypeRequired
enum('row', 'row-reverse', 'column', 'column-reverse')No

flexGrow

TypeRequired
numberNo

flexShrink

TypeRequired
numberNo

flexWrap

flexWrap controls whether children can wrap around after they hit the end of a flex container. It works like flex-wrap in CSS (default: nowrap). See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-wrap for more details. Note it does not work anymore with alignItems: stretch (the default), so you may want to use alignItems: flex-start for example (breaking change details: https://github.com/facebook/react-native/releases/tag/v0.28.0).

TypeRequired
enum('wrap', 'nowrap')No

height

height sets the height of this component.

It works similarly to height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported. See https://developer.mozilla.org/en-US/docs/Web/CSS/height for more details.

TypeRequired
number, stringNo

justifyContent

justifyContent aligns children in the main direction. For example, if children are flowing vertically, justifyContent controls how they align vertically. It works like justify-content in CSS (default: flex-start). See https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'space-between', 'space-around', 'space-evenly')No

left

left is the number of logical pixels to offset the left edge of this component.

It works similarly to left in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/left for more details of how left affects layout.

TypeRequired
number, stringNo

margin

Setting margin has the same effect as setting each of marginTop, marginLeft, marginBottom, and marginRight. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin for more details.

TypeRequired
number, stringNo

marginBottom

marginBottom works like margin-bottom in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-bottom for more details.

TypeRequired
number, stringNo

marginEnd

When direction is ltr, marginEnd is equivalent to marginRight. When direction is rtl, marginEnd is equivalent to marginLeft.

TypeRequired
number, stringNo

marginHorizontal

Setting marginHorizontal has the same effect as setting both marginLeft and marginRight.

TypeRequired
number, stringNo

marginLeft

marginLeft works like margin-left in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-left for more details.

TypeRequired
number, stringNo

marginRight

marginRight works like margin-right in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-right for more details.

TypeRequired
number, stringNo

marginStart

When direction is ltr, marginStart is equivalent to marginLeft. When direction is rtl, marginStart is equivalent to marginRight.

TypeRequired
number, stringNo

marginTop

marginTop works like margin-top in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-top for more details.

TypeRequired
number, stringNo

marginVertical

Setting marginVertical has the same effect as setting both marginTop and marginBottom.

TypeRequired
number, stringNo

maxHeight

maxHeight is the maximum height for this component, in logical pixels.

It works similarly to max-height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/max-height for more details.

TypeRequired
number, stringNo

maxWidth

maxWidth is the maximum width for this component, in logical pixels.

It works similarly to max-width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/max-width for more details.

TypeRequired
number, stringNo

minHeight

minHeight is the minimum height for this component, in logical pixels.

It works similarly to min-height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/min-height for more details.

TypeRequired
number, stringNo

minWidth

minWidth is the minimum width for this component, in logical pixels.

It works similarly to min-width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/min-width for more details.

TypeRequired
number, stringNo

overflow

overflow controls how children are measured and displayed. overflow: hidden causes views to be clipped while overflow: scroll causes views to be measured independently of their parents main axis. It works like overflow in CSS (default: visible). See https://developer.mozilla.org/en/docs/Web/CSS/overflow for more details.

TypeRequired
enum('visible', 'hidden', 'scroll')No

padding

Setting padding has the same effect as setting each of paddingTop, paddingBottom, paddingLeft, and paddingRight. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding for more details.

TypeRequired
number, stringNo

paddingBottom

paddingBottom works like padding-bottom in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-bottom for more details.

TypeRequired
number, stringNo

paddingEnd

When direction is ltr, paddingEnd is equivalent to paddingRight. When direction is rtl, paddingEnd is equivalent to paddingLeft.

TypeRequired
number, stringNo

paddingHorizontal

Setting paddingHorizontal is like setting both of paddingLeft and paddingRight.

TypeRequired
number, stringNo

paddingLeft

paddingLeft works like padding-left in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-left for more details.

TypeRequired
number, stringNo

paddingRight

paddingRight works like padding-right in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-right for more details.

TypeRequired
number, stringNo

paddingStart

When direction is ltr, paddingStart is equivalent to paddingLeft. When direction is rtl, paddingStart is equivalent to paddingRight.

TypeRequired
number, stringNo

paddingTop

paddingTop works like padding-top in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-top for more details.

TypeRequired
number, ,stringNo

paddingVertical

Setting paddingVertical is like setting both of paddingTop and paddingBottom.

TypeRequired
number, stringNo

position

position in React Native is similar to regular CSS, but everything is set to relative by default, so absolute positioning is always relative to the parent.

If you want to position a child using specific numbers of logical pixels relative to its parent, set the child to have absolute position.

If you want to position a child relative to something that is not its parent, don't use styles for that. Use the component tree.

See https://github.com/facebook/yoga for more details on how position differs between React Native and CSS.

TypeRequired
enum('absolute', 'relative')No

right

right is the number of logical pixels to offset the right edge of this component.

It works similarly to right in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/right for more details of how right affects layout.

TypeRequired
number, stringNo

start

When the direction is ltr, start is equivalent to left. When the direction is rtl, start is equivalent to right.

This style takes precedence over the left, right, and end styles.

TypeRequired
number, stringNo

top

top is the number of logical pixels to offset the top edge of this component.

It works similarly to top in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/top for more details of how top affects layout.

TypeRequired
number, stringNo

width

width sets the width of this component.

It works similarly to width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported. See https://developer.mozilla.org/en-US/docs/Web/CSS/width for more details.

TypeRequired
number, stringNo

zIndex

zIndex controls which components display on top of others. Normally, you don't use zIndex. Components render according to their order in the document tree, so later components draw over earlier ones. zIndex may be useful if you have animations or custom modal interfaces where you don't want this behavior.

It works like the CSS z-index property - components with a larger zIndex will render on top. Think of the z-direction like it's pointing from the phone into your eyeball. See https://developer.mozilla.org/en-US/docs/Web/CSS/z-index for more details.

On iOS, zIndex may require Views to be siblings of each other for it to work as expected.

TypeRequired
numberNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/layoutanimation.html b/docs/0.61/layoutanimation.html index 18f4c7a48da..450905ac8de 100644 --- a/docs/0.61/layoutanimation.html +++ b/docs/0.61/layoutanimation.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
if (
Platform.OS === 'android' &&
UIManager.setLayoutAnimationEnabledExperimental
) {
UIManager.setLayoutAnimationEnabledExperimental(true);
}
class AnimatedCollapsible extends React.Component {
state = { expanded: false };
render() {
return (
<View style={{ overflow: 'hidden' }}>
<TouchableOpacity
onPress={() => {
LayoutAnimation.configureNext(
LayoutAnimation.Presets.spring
);
this.setState({ expanded: !this.state.expanded });
}}>
<Text>
Press me to{' '}
{this.state.expanded ? 'collapse' : 'expand'}!
</Text>
</TouchableOpacity>
{this.state.expanded && (
<Text>I disappear sometimes!</Text>
)}
</View>
);
}
}

Reference

Methods

configureNext()

static configureNext(config, onAnimationDidEnd?)

Schedules an animation to happen on the next layout.

Parameters:

NameTypeRequiredDescription
configobjectYesSee config description below.
onAnimationDidEndfunctionNoCalled when the animation finished. Only supported on iOS.

The config parameter is an object with the keys below. create returns a valid object for config, and the Presets objects can also all be passed as the config.

The config that's passed to create, update, or delete has the following keys:

create()

static create(duration, type, creationProp)

Helper that creates an object (with create, update, and delete fields) to pass into configureNext. The type parameter is an animation type, and the creationProp parameter is a layout property.

Example usage:

LayoutAnimation.configureNext(
LayoutAnimation.create(
500,
LayoutAnimation.Types.spring,
LayoutAnimation.Properties.scaleXY
)
);

Properties

Types

An enumeration of animation types to be used in the create method, or in the create/update/delete configs for configureNext. (example usage: LayoutAnimation.Types.easeIn)

Types
spring
linear
easeInEaseOut
easeIn
easeOut
keyboard

Properties

An enumeration of layout properties to be animated to be used in the create method, or in the create/update/delete configs for configureNext. (example usage: LayoutAnimation.Properties.opacity)

Properties
opacity
scaleX
scaleY
scaleXY

Presets

A set of predefined animation configs to pass into configureNext.

PresetsValue
easeInEaseOutcreate(300, 'easeInEaseOut', 'opacity')
linearcreate(500, 'linear', 'opacity')
spring{ duration: 700, create: { type: 'linear', property: 'opacity' }, update: { type: 'spring', springDamping: 0.4 }, delete: { type: 'linear', property: 'opacity' } }

easeInEaseOut()

Calls configureNext() with Presets.easeInEaseOut.

linear()

Calls configureNext() with Presets.linear.

spring()

Calls configureNext() with Presets.spring.

Edit this page
Last updated on
- + diff --git a/docs/0.61/layoutanimation/index.html b/docs/0.61/layoutanimation/index.html index 18f4c7a48da..450905ac8de 100644 --- a/docs/0.61/layoutanimation/index.html +++ b/docs/0.61/layoutanimation/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
if (
Platform.OS === 'android' &&
UIManager.setLayoutAnimationEnabledExperimental
) {
UIManager.setLayoutAnimationEnabledExperimental(true);
}
class AnimatedCollapsible extends React.Component {
state = { expanded: false };
render() {
return (
<View style={{ overflow: 'hidden' }}>
<TouchableOpacity
onPress={() => {
LayoutAnimation.configureNext(
LayoutAnimation.Presets.spring
);
this.setState({ expanded: !this.state.expanded });
}}>
<Text>
Press me to{' '}
{this.state.expanded ? 'collapse' : 'expand'}!
</Text>
</TouchableOpacity>
{this.state.expanded && (
<Text>I disappear sometimes!</Text>
)}
</View>
);
}
}

Reference

Methods

configureNext()

static configureNext(config, onAnimationDidEnd?)

Schedules an animation to happen on the next layout.

Parameters:

NameTypeRequiredDescription
configobjectYesSee config description below.
onAnimationDidEndfunctionNoCalled when the animation finished. Only supported on iOS.

The config parameter is an object with the keys below. create returns a valid object for config, and the Presets objects can also all be passed as the config.

The config that's passed to create, update, or delete has the following keys:

create()

static create(duration, type, creationProp)

Helper that creates an object (with create, update, and delete fields) to pass into configureNext. The type parameter is an animation type, and the creationProp parameter is a layout property.

Example usage:

LayoutAnimation.configureNext(
LayoutAnimation.create(
500,
LayoutAnimation.Types.spring,
LayoutAnimation.Properties.scaleXY
)
);

Properties

Types

An enumeration of animation types to be used in the create method, or in the create/update/delete configs for configureNext. (example usage: LayoutAnimation.Types.easeIn)

Types
spring
linear
easeInEaseOut
easeIn
easeOut
keyboard

Properties

An enumeration of layout properties to be animated to be used in the create method, or in the create/update/delete configs for configureNext. (example usage: LayoutAnimation.Properties.opacity)

Properties
opacity
scaleX
scaleY
scaleXY

Presets

A set of predefined animation configs to pass into configureNext.

PresetsValue
easeInEaseOutcreate(300, 'easeInEaseOut', 'opacity')
linearcreate(500, 'linear', 'opacity')
spring{ duration: 700, create: { type: 'linear', property: 'opacity' }, update: { type: 'spring', springDamping: 0.4 }, delete: { type: 'linear', property: 'opacity' } }

easeInEaseOut()

Calls configureNext() with Presets.easeInEaseOut.

linear()

Calls configureNext() with Presets.linear.

spring()

Calls configureNext() with Presets.spring.

Edit this page
Last updated on
- + diff --git a/docs/0.61/libraries.html b/docs/0.61/libraries.html index 3b80d996e15..961a7b9ee20 100644 --- a/docs/0.61/libraries.html +++ b/docs/0.61/libraries.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Using Libraries

React Native provides a set of built-in Core Components and APIs ready to use in your app. You're not limited to the components and APIs bundled with React Native. React Native has a community of thousands of developers. If the Core Components and APIs don't have what you are looking for, you may be able to find and install a library from the community to add the functionality to your app.

Selecting a Package Manager

React Native libraries are typically installed from the npm registry using a Node.js package manager such as npm CLI or Yarn Classic.

If you have Node.js installed on your computer then you already have the npm CLI installed. Some developers prefer to use Yarn Classic for slightly faster install times and additional advanced features like Workspaces. Both tools work great with React Native. We will assume npm for the rest of this guide for simplicity of explanation.

💡 The terms "library" and "package" are used interchangably in the JavaScript community.

Installing a Library

To install a library in your project, navigate to your project directory in your terminal and run npm install <name-of-the-library>. Let's try this with react-native-webview:

npm install react-native-webview

The library that we installed includes native code, and we need to link to our app before we use it.

Linking Native Code on iOS

React Native uses CocoaPods to manage iOS project dependencies and most React Native libraries follow this same convention. If a library you are using does not, then please refer to their README for additional instruction. In most cases, the following instructions will apply.

Run pod install in our ios directory in order to link it to our native iOS project. A shortcut for doing this without switching to the ios directory is to run npx pod-install.

npx pod-install

Once this is complete, re-build the app binary to start using your new library:

npx react-native run-ios

Linking Native Code on Android

React Native uses Gradle to manage Android project dependencies. After you install a library with native dependencies, you will need to re-build the app binary to use your new library:

npx react-native run-android

Finding Libraries

React Native Directory is a searchable database of libraries built specifically for React Native. This is the first place to look for a library for your React Native app.

Many of the libraries you will find on the directory are from React Native Community or Expo.

Libraries built by the React Native Community are driven by volunteers and individuals at companies that depend on React Native. They often support iOS, tvOS, Android, Windows, but this varies across projects. Many of the libraries in this organization were once React Native Core Components and APIs.

Libraries built by Expo are all written in TypeScript and support iOS, Android, and react-native-web wherever possible. They usually require that you first install react-native-unimodules in order to use in your React Native app.

After React Native Directory, the npm registry is the next best place if you can't find a library specifically for React Native on the directory. The npm registry is the definitive source for JavaScript libraries, but the libraries that it lists may not all be compatible with React Native. React Native is one of many JavaScript programming environments, including Node.js, web browsers, Electron, and more, and npm includes libraries that work for all of these environments.

Determining Library Compatibility

Does it work with React Native?

Usually libraries built specifically for other platforms will not work with React Native. Examples include react-select which is built for the web and specifically targets react-dom, and rimraf which is built for Node.js and interacts with your computer file system. Other libraries like lodash use only JavaScript language features and work in any environment. You will gain a sense for this over time, but until then the easiest way to find out is to try it yourself. You can remove packages using npm uninstall if it turns out that it does not work in React Native.

Does it work for the platforms that my app supports?

React Native Directory allows you to filter by platform compatibility, such as iOS, Android, Web, and Windows. If the library you would like to use is not currently listed there, refer to the README for the library to learn more.

Does it work with my app version of React Native?

The latest version of a library is typically compatible with the latest version of React Native. If you are using an older version, you should refer to the README to know which version of the library you should install. You can install a particular version of the library by running npm install <library-name>@<version-number>, for example: npm install @react-native-community/netinfo@^2.0.0.

Edit this page
Last updated on
- + diff --git a/docs/0.61/libraries/index.html b/docs/0.61/libraries/index.html index 3b80d996e15..961a7b9ee20 100644 --- a/docs/0.61/libraries/index.html +++ b/docs/0.61/libraries/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Using Libraries

React Native provides a set of built-in Core Components and APIs ready to use in your app. You're not limited to the components and APIs bundled with React Native. React Native has a community of thousands of developers. If the Core Components and APIs don't have what you are looking for, you may be able to find and install a library from the community to add the functionality to your app.

Selecting a Package Manager

React Native libraries are typically installed from the npm registry using a Node.js package manager such as npm CLI or Yarn Classic.

If you have Node.js installed on your computer then you already have the npm CLI installed. Some developers prefer to use Yarn Classic for slightly faster install times and additional advanced features like Workspaces. Both tools work great with React Native. We will assume npm for the rest of this guide for simplicity of explanation.

💡 The terms "library" and "package" are used interchangably in the JavaScript community.

Installing a Library

To install a library in your project, navigate to your project directory in your terminal and run npm install <name-of-the-library>. Let's try this with react-native-webview:

npm install react-native-webview

The library that we installed includes native code, and we need to link to our app before we use it.

Linking Native Code on iOS

React Native uses CocoaPods to manage iOS project dependencies and most React Native libraries follow this same convention. If a library you are using does not, then please refer to their README for additional instruction. In most cases, the following instructions will apply.

Run pod install in our ios directory in order to link it to our native iOS project. A shortcut for doing this without switching to the ios directory is to run npx pod-install.

npx pod-install

Once this is complete, re-build the app binary to start using your new library:

npx react-native run-ios

Linking Native Code on Android

React Native uses Gradle to manage Android project dependencies. After you install a library with native dependencies, you will need to re-build the app binary to use your new library:

npx react-native run-android

Finding Libraries

React Native Directory is a searchable database of libraries built specifically for React Native. This is the first place to look for a library for your React Native app.

Many of the libraries you will find on the directory are from React Native Community or Expo.

Libraries built by the React Native Community are driven by volunteers and individuals at companies that depend on React Native. They often support iOS, tvOS, Android, Windows, but this varies across projects. Many of the libraries in this organization were once React Native Core Components and APIs.

Libraries built by Expo are all written in TypeScript and support iOS, Android, and react-native-web wherever possible. They usually require that you first install react-native-unimodules in order to use in your React Native app.

After React Native Directory, the npm registry is the next best place if you can't find a library specifically for React Native on the directory. The npm registry is the definitive source for JavaScript libraries, but the libraries that it lists may not all be compatible with React Native. React Native is one of many JavaScript programming environments, including Node.js, web browsers, Electron, and more, and npm includes libraries that work for all of these environments.

Determining Library Compatibility

Does it work with React Native?

Usually libraries built specifically for other platforms will not work with React Native. Examples include react-select which is built for the web and specifically targets react-dom, and rimraf which is built for Node.js and interacts with your computer file system. Other libraries like lodash use only JavaScript language features and work in any environment. You will gain a sense for this over time, but until then the easiest way to find out is to try it yourself. You can remove packages using npm uninstall if it turns out that it does not work in React Native.

Does it work for the platforms that my app supports?

React Native Directory allows you to filter by platform compatibility, such as iOS, Android, Web, and Windows. If the library you would like to use is not currently listed there, refer to the README for the library to learn more.

Does it work with my app version of React Native?

The latest version of a library is typically compatible with the latest version of React Native. If you are using an older version, you should refer to the README to know which version of the library you should install. You can install a particular version of the library by running npm install <library-name>@<version-number>, for example: npm install @react-native-community/netinfo@^2.0.0.

Edit this page
Last updated on
- + diff --git a/docs/0.61/linking-libraries-ios.html b/docs/0.61/linking-libraries-ios.html index 76c0ba6bf69..14b8411df73 100644 --- a/docs/0.61/linking-libraries-ios.html +++ b/docs/0.61/linking-libraries-ios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Linking Libraries

Not every app uses all the native capabilities, and including the code to support all those features would impact the binary size... But we still want to support these features whenever you need them.

With that in mind we exposed many of these features as independent static libraries.

For most of the libs it will be as quick as dragging two files, sometimes a third step will be necessary, but no more than that.

All the libraries we ship with React Native live on the Libraries folder in the root of the repository. Some of them are pure JavaScript, and you only need to require it. Other libraries also rely on some native code, in that case you'll have to add these files to your app, otherwise the app will throw an error as soon as you try to use the library.

Here are the few steps to link your libraries that contain native code

Automatic linking

Step 1

Install a library with native dependencies:

$ npm install <library-with-native-dependencies> --save

Note: --save or --save-dev flag is very important for this step. React Native will link your libs based on dependencies and devDependencies in your package.json file.

Step 2

Link your native dependencies:

$ react-native link

Done! All libraries with native dependencies should be successfully linked to your iOS/Android project.

Note: If your iOS project is using CocoaPods (contains Podfile) and linked library has podspec file, then react-native link will link library using Podfile. To support non-trivial Podfiles add # Add new pods below this line comment to places where you expect pods to be added.

Manual linking

Step 1

If the library has native code, there must be an .xcodeproj file inside its folder. Drag this file to your project on Xcode (usually under the Libraries group on Xcode);

Step 2

Click on your main project file (the one that represents the .xcodeproj) select Build Phases and drag the static library from the Products folder inside the Library you are importing to Link Binary With Libraries

Step 3

Not every library will need this step, what you need to consider is:

Do I need to know the contents of the library at compile time?

What that means is, are you using this library on the native side or only in JavaScript? If you are only using it in JavaScript, you are good to go!

If you do need to call it from native, then we need to know the library's headers. To achieve that you have to go to your project's file, select Build Settings and search for Header Search Paths. There you should include the path to your library. (This documentation used to recommend using recursive, but this is no longer recommended, as it can cause subtle build failures, especially with CocoaPods.)

Edit this page
Last updated on
- + diff --git a/docs/0.61/linking-libraries-ios/index.html b/docs/0.61/linking-libraries-ios/index.html index 76c0ba6bf69..14b8411df73 100644 --- a/docs/0.61/linking-libraries-ios/index.html +++ b/docs/0.61/linking-libraries-ios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Linking Libraries

Not every app uses all the native capabilities, and including the code to support all those features would impact the binary size... But we still want to support these features whenever you need them.

With that in mind we exposed many of these features as independent static libraries.

For most of the libs it will be as quick as dragging two files, sometimes a third step will be necessary, but no more than that.

All the libraries we ship with React Native live on the Libraries folder in the root of the repository. Some of them are pure JavaScript, and you only need to require it. Other libraries also rely on some native code, in that case you'll have to add these files to your app, otherwise the app will throw an error as soon as you try to use the library.

Here are the few steps to link your libraries that contain native code

Automatic linking

Step 1

Install a library with native dependencies:

$ npm install <library-with-native-dependencies> --save

Note: --save or --save-dev flag is very important for this step. React Native will link your libs based on dependencies and devDependencies in your package.json file.

Step 2

Link your native dependencies:

$ react-native link

Done! All libraries with native dependencies should be successfully linked to your iOS/Android project.

Note: If your iOS project is using CocoaPods (contains Podfile) and linked library has podspec file, then react-native link will link library using Podfile. To support non-trivial Podfiles add # Add new pods below this line comment to places where you expect pods to be added.

Manual linking

Step 1

If the library has native code, there must be an .xcodeproj file inside its folder. Drag this file to your project on Xcode (usually under the Libraries group on Xcode);

Step 2

Click on your main project file (the one that represents the .xcodeproj) select Build Phases and drag the static library from the Products folder inside the Library you are importing to Link Binary With Libraries

Step 3

Not every library will need this step, what you need to consider is:

Do I need to know the contents of the library at compile time?

What that means is, are you using this library on the native side or only in JavaScript? If you are only using it in JavaScript, you are good to go!

If you do need to call it from native, then we need to know the library's headers. To achieve that you have to go to your project's file, select Build Settings and search for Header Search Paths. There you should include the path to your library. (This documentation used to recommend using recursive, but this is no longer recommended, as it can cause subtle build failures, especially with CocoaPods.)

Edit this page
Last updated on
- + diff --git a/docs/0.61/linking.html b/docs/0.61/linking.html index b743ef0a8e7..6d3edfbc3e5 100644 --- a/docs/0.61/linking.html +++ b/docs/0.61/linking.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
{
return [RCTLinkingManager application:application openURL:url
sourceApplication:sourceApplication annotation:annotation];
}

If your app is using Universal Links, you'll need to add the following code as well:

- (BOOL)application:(UIApplication *)application continueUserActivity:(nonnull NSUserActivity *)userActivity
restorationHandler:(nonnull void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler
{
return [RCTLinkingManager application:application
continueUserActivity:userActivity
restorationHandler:restorationHandler];
}

And then on your React component you'll be able to listen to the events on Linking as follows:

componentDidMount() {
Linking.addEventListener('url', this._handleOpenURL);
},
componentWillUnmount() {
Linking.removeEventListener('url', this._handleOpenURL);
},
_handleOpenURL(event) {
console.log(event.url);
}

Opening external links

To start the corresponding activity for a link (web URL, email, contact etc.), call:

Linking.openURL(url).catch((err) =>
console.error('An error occurred', err)
);

If you want to check if any installed app can handle a given URL beforehand you can call:

Linking.canOpenURL(url)
.then((supported) => {
if (!supported) {
console.log("Can't handle url: " + url);
} else {
return Linking.openURL(url);
}
})
.catch((err) => console.error('An error occurred', err));

Reference

Methods

constructor()

constructor();

addEventListener()

addEventListener(type, handler);

Add a handler to Linking changes by listening to the url event type and providing the handler.

removeEventListener()

removeEventListener(type, handler);

Remove a handler by passing the url event type and the handler.

openURL()

openURL(url);

Try to open the given url with any of the installed apps.

You can use other URLs, like a location (e.g. "geo:37.484847,-122.148386" on Android or "http://maps.apple.com/?ll=37.484847,-122.148386" on iOS), a contact, or any other URL that can be opened with the installed apps.

The method returns a Promise object. If the user confirms the open dialog or the url automatically opens, the promise is resolved. If the user cancels the open dialog or there are no registered applications for the url, the promise is rejected.

Parameters:

NameTypeRequiredDescription
urlstringYesThe URL to open.

This method will fail if the system doesn't know how to open the specified URL. If you're passing in a non-http(s) URL, it's best to check {@code canOpenURL} first.

For web URLs, the protocol ("http://", "https://") must be set accordingly!

canOpenURL()

canOpenURL(url);

Determine whether or not an installed app can handle a given URL.

The method returns a Promise object. When it is determined whether or not the given URL can be handled, the promise is resolved and the first parameter is whether or not it can be opened.

The Promise will reject on Android if it was impossible to check if the URL can be opened, and on iOS if you didn't add the specific scheme in the LSApplicationQueriesSchemes key inside Info.plist (see bellow).

Parameters:

NameTypeRequiredDescription
urlstringYesThe URL to open.

For web URLs, the protocol ("http://", "https://") must be set accordingly!

As of iOS 9, your app needs to provide the LSApplicationQueriesSchemes key inside Info.plist or canOpenURL will always return false.

This method has limitations on iOS 9+. From the official Apple documentation:

If your app is linked against an earlier version of iOS but is running in iOS 9.0 or later, you can call this method up to 50 times. After reaching that limit, subsequent calls always return false. If the user reinstalls or upgrades the app, iOS resets the limit.

openSettings()

openSettings();

Open the Settings app and displays the app’s custom settings, if it has any.

getInitialURL()

getInitialURL();

If the app launch was triggered by an app link, it will give the link url, otherwise it will give null.

To support deep linking on Android, refer http://developer.android.com/training/app-indexing/deep-linking.html#handling-intents

sendIntent()

sendIntent(action: string, extras?: Array<{key: string, value: string | number | boolean}>)

@platform android

Android-Only. Launch an Android intent with extras (optional)

Edit this page
Last updated on
- + diff --git a/docs/0.61/linking/index.html b/docs/0.61/linking/index.html index b743ef0a8e7..6d3edfbc3e5 100644 --- a/docs/0.61/linking/index.html +++ b/docs/0.61/linking/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
{
return [RCTLinkingManager application:application openURL:url
sourceApplication:sourceApplication annotation:annotation];
}

If your app is using Universal Links, you'll need to add the following code as well:

- (BOOL)application:(UIApplication *)application continueUserActivity:(nonnull NSUserActivity *)userActivity
restorationHandler:(nonnull void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler
{
return [RCTLinkingManager application:application
continueUserActivity:userActivity
restorationHandler:restorationHandler];
}

And then on your React component you'll be able to listen to the events on Linking as follows:

componentDidMount() {
Linking.addEventListener('url', this._handleOpenURL);
},
componentWillUnmount() {
Linking.removeEventListener('url', this._handleOpenURL);
},
_handleOpenURL(event) {
console.log(event.url);
}

Opening external links

To start the corresponding activity for a link (web URL, email, contact etc.), call:

Linking.openURL(url).catch((err) =>
console.error('An error occurred', err)
);

If you want to check if any installed app can handle a given URL beforehand you can call:

Linking.canOpenURL(url)
.then((supported) => {
if (!supported) {
console.log("Can't handle url: " + url);
} else {
return Linking.openURL(url);
}
})
.catch((err) => console.error('An error occurred', err));

Reference

Methods

constructor()

constructor();

addEventListener()

addEventListener(type, handler);

Add a handler to Linking changes by listening to the url event type and providing the handler.

removeEventListener()

removeEventListener(type, handler);

Remove a handler by passing the url event type and the handler.

openURL()

openURL(url);

Try to open the given url with any of the installed apps.

You can use other URLs, like a location (e.g. "geo:37.484847,-122.148386" on Android or "http://maps.apple.com/?ll=37.484847,-122.148386" on iOS), a contact, or any other URL that can be opened with the installed apps.

The method returns a Promise object. If the user confirms the open dialog or the url automatically opens, the promise is resolved. If the user cancels the open dialog or there are no registered applications for the url, the promise is rejected.

Parameters:

NameTypeRequiredDescription
urlstringYesThe URL to open.

This method will fail if the system doesn't know how to open the specified URL. If you're passing in a non-http(s) URL, it's best to check {@code canOpenURL} first.

For web URLs, the protocol ("http://", "https://") must be set accordingly!

canOpenURL()

canOpenURL(url);

Determine whether or not an installed app can handle a given URL.

The method returns a Promise object. When it is determined whether or not the given URL can be handled, the promise is resolved and the first parameter is whether or not it can be opened.

The Promise will reject on Android if it was impossible to check if the URL can be opened, and on iOS if you didn't add the specific scheme in the LSApplicationQueriesSchemes key inside Info.plist (see bellow).

Parameters:

NameTypeRequiredDescription
urlstringYesThe URL to open.

For web URLs, the protocol ("http://", "https://") must be set accordingly!

As of iOS 9, your app needs to provide the LSApplicationQueriesSchemes key inside Info.plist or canOpenURL will always return false.

This method has limitations on iOS 9+. From the official Apple documentation:

If your app is linked against an earlier version of iOS but is running in iOS 9.0 or later, you can call this method up to 50 times. After reaching that limit, subsequent calls always return false. If the user reinstalls or upgrades the app, iOS resets the limit.

openSettings()

openSettings();

Open the Settings app and displays the app’s custom settings, if it has any.

getInitialURL()

getInitialURL();

If the app launch was triggered by an app link, it will give the link url, otherwise it will give null.

To support deep linking on Android, refer http://developer.android.com/training/app-indexing/deep-linking.html#handling-intents

sendIntent()

sendIntent(action: string, extras?: Array<{key: string, value: string | number | boolean}>)

@platform android

Android-Only. Launch an Android intent with extras (optional)

Edit this page
Last updated on
- + diff --git a/docs/0.61/listview.html b/docs/0.61/listview.html index 23de5e63ee4..600cabd0d48 100644 --- a/docs/0.61/listview.html +++ b/docs/0.61/listview.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
render() {
return (
<ListView
dataSource={this.state.dataSource}
renderRow={(rowData) => <Text>{rowData}</Text>}
/>
);
}
}

ListView also supports more advanced features, including sections with sticky section headers, header and footer support, callbacks on reaching the end of the available data (onEndReached) and on the set of rows that are visible in the device viewport change (onChangeVisibleRows), and several performance optimizations.

There are a few performance operations designed to make ListView scroll smoothly while dynamically loading potentially very large (or conceptually infinite) data sets:

Props

Methods

Reference

Props

dataSource

An instance of ListView.DataSource to use

TypeRequired
ListViewDataSourceYes

initialListSize

How many rows to render on initial component mount. Use this to make it so that the first screen worth of data appears at one time instead of over the course of multiple frames.

TypeRequired
numberYes

onEndReachedThreshold

Threshold in pixels (virtual, not physical) for calling onEndReached.

TypeRequired
numberYes

pageSize

Number of rows to render per event loop. Note: if your 'rows' are actually cells, i.e. they don't span the full width of your view (as in the ListViewGridLayoutExample), you should set the pageSize to be a multiple of the number of cells per row, otherwise you're likely to see gaps at the edge of the ListView as new pages are loaded.

TypeRequired
numberYes

renderRow

(rowData, sectionID, rowID, highlightRow) => renderable

Takes a data entry from the data source and its ids and should return a renderable component to be rendered as the row. By default the data is exactly what was put into the data source, but it's also possible to provide custom extractors. ListView can be notified when a row is being highlighted by calling highlightRow(sectionID, rowID). This sets a boolean value of adjacentRowHighlighted in renderSeparator, allowing you to control the separators above and below the highlighted row. The highlighted state of a row can be reset by calling highlightRow(null).

TypeRequired
functionYes

renderScrollComponent

(props) => renderable

A function that returns the scrollable component in which the list rows are rendered. Defaults to returning a ScrollView with the given props.

TypeRequired
functionYes

scrollRenderAheadDistance

How early to start rendering rows before they come on screen, in pixels.

TypeRequired
numberYes

stickyHeaderIndices

An array of child indices determining which children get docked to the top of the screen when scrolling. For example, passing stickyHeaderIndices={[0]} will cause the first child to be fixed to the top of the scroll view. This property is not supported in conjunction with horizontal={true}.

TypeRequired
array of numberYes

enableEmptySections

Flag indicating whether empty section headers should be rendered. In the future release empty section headers will be rendered by default, and the flag will be deprecated. If empty sections are not desired to be rendered their indices should be excluded from sectionID object.

TypeRequired
boolNo

renderHeader

TypeRequired
functionNo

onEndReached

Called when all rows have been rendered and the list has been scrolled to within onEndReachedThreshold of the bottom. The native scroll event is provided.

TypeRequired
functionNo

stickySectionHeadersEnabled

Makes the sections headers sticky. The sticky behavior means that it will scroll with the content at the top of the section until it reaches the top of the screen, at which point it will stick to the top until it is pushed off the screen by the next section header. This property is not supported in conjunction with horizontal={true}. Only enabled by default on iOS because of typical platform standards.

TypeRequired
boolNo

renderSectionHeader

(sectionData, sectionID) => renderable

If provided, a header is rendered for this section.

TypeRequired
functionNo

renderSeparator

(sectionID, rowID, adjacentRowHighlighted) => renderable

If provided, a renderable component to be rendered as the separator below each row but not the last row if there is a section header below. Take a sectionID and rowID of the row above and whether its adjacent row is highlighted.

TypeRequired
functionNo

onChangeVisibleRows

(visibleRows, changedRows) => void

Called when the set of visible rows changes. visibleRows maps { sectionID: { rowID: true }} for all the visible rows, and changedRows maps { sectionID: { rowID: true | false }} for the rows that have changed their visibility, with true indicating visible, and false indicating the view has moved out of view.

TypeRequired
functionNo

removeClippedSubviews

A performance optimization for improving scroll perf of large lists, used in conjunction with overflow: 'hidden' on the row containers. This is enabled by default.

TypeRequired
boolNo

renderFooter

() => renderable

The header and footer are always rendered (if these props are provided) on every render pass. If they are expensive to re-render, wrap them in StaticContainer or other mechanism as appropriate. Footer is always at the bottom of the list, and header at the top, on every render pass. In a horizontal ListView, the header is rendered on the left and the footer on the right.

TypeRequired
functionNo

Methods

getMetrics()

getMetrics();

Exports some data, e.g. for perf investigations or analytics.

scrollTo()

scrollTo((...args: Array));

Scrolls to a given x, y offset, either immediately or with a smooth animation.

See ScrollView#scrollTo.

scrollToEnd()

scrollToEnd(([options]: object));

If this is a vertical ListView scrolls to the bottom. If this is a horizontal ListView scrolls to the right.

Use scrollToEnd({animated: true}) for smooth animated scrolling, scrollToEnd({animated: false}) for immediate scrolling. If no options are passed, animated defaults to true.

See ScrollView#scrollToEnd.

flashScrollIndicators()

flashScrollIndicators();

Displays the scroll indicators momentarily.

Edit this page
Last updated on
- + diff --git a/docs/0.61/listview/index.html b/docs/0.61/listview/index.html index 23de5e63ee4..600cabd0d48 100644 --- a/docs/0.61/listview/index.html +++ b/docs/0.61/listview/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
render() {
return (
<ListView
dataSource={this.state.dataSource}
renderRow={(rowData) => <Text>{rowData}</Text>}
/>
);
}
}

ListView also supports more advanced features, including sections with sticky section headers, header and footer support, callbacks on reaching the end of the available data (onEndReached) and on the set of rows that are visible in the device viewport change (onChangeVisibleRows), and several performance optimizations.

There are a few performance operations designed to make ListView scroll smoothly while dynamically loading potentially very large (or conceptually infinite) data sets:

Props

Methods

Reference

Props

dataSource

An instance of ListView.DataSource to use

TypeRequired
ListViewDataSourceYes

initialListSize

How many rows to render on initial component mount. Use this to make it so that the first screen worth of data appears at one time instead of over the course of multiple frames.

TypeRequired
numberYes

onEndReachedThreshold

Threshold in pixels (virtual, not physical) for calling onEndReached.

TypeRequired
numberYes

pageSize

Number of rows to render per event loop. Note: if your 'rows' are actually cells, i.e. they don't span the full width of your view (as in the ListViewGridLayoutExample), you should set the pageSize to be a multiple of the number of cells per row, otherwise you're likely to see gaps at the edge of the ListView as new pages are loaded.

TypeRequired
numberYes

renderRow

(rowData, sectionID, rowID, highlightRow) => renderable

Takes a data entry from the data source and its ids and should return a renderable component to be rendered as the row. By default the data is exactly what was put into the data source, but it's also possible to provide custom extractors. ListView can be notified when a row is being highlighted by calling highlightRow(sectionID, rowID). This sets a boolean value of adjacentRowHighlighted in renderSeparator, allowing you to control the separators above and below the highlighted row. The highlighted state of a row can be reset by calling highlightRow(null).

TypeRequired
functionYes

renderScrollComponent

(props) => renderable

A function that returns the scrollable component in which the list rows are rendered. Defaults to returning a ScrollView with the given props.

TypeRequired
functionYes

scrollRenderAheadDistance

How early to start rendering rows before they come on screen, in pixels.

TypeRequired
numberYes

stickyHeaderIndices

An array of child indices determining which children get docked to the top of the screen when scrolling. For example, passing stickyHeaderIndices={[0]} will cause the first child to be fixed to the top of the scroll view. This property is not supported in conjunction with horizontal={true}.

TypeRequired
array of numberYes

enableEmptySections

Flag indicating whether empty section headers should be rendered. In the future release empty section headers will be rendered by default, and the flag will be deprecated. If empty sections are not desired to be rendered their indices should be excluded from sectionID object.

TypeRequired
boolNo

renderHeader

TypeRequired
functionNo

onEndReached

Called when all rows have been rendered and the list has been scrolled to within onEndReachedThreshold of the bottom. The native scroll event is provided.

TypeRequired
functionNo

stickySectionHeadersEnabled

Makes the sections headers sticky. The sticky behavior means that it will scroll with the content at the top of the section until it reaches the top of the screen, at which point it will stick to the top until it is pushed off the screen by the next section header. This property is not supported in conjunction with horizontal={true}. Only enabled by default on iOS because of typical platform standards.

TypeRequired
boolNo

renderSectionHeader

(sectionData, sectionID) => renderable

If provided, a header is rendered for this section.

TypeRequired
functionNo

renderSeparator

(sectionID, rowID, adjacentRowHighlighted) => renderable

If provided, a renderable component to be rendered as the separator below each row but not the last row if there is a section header below. Take a sectionID and rowID of the row above and whether its adjacent row is highlighted.

TypeRequired
functionNo

onChangeVisibleRows

(visibleRows, changedRows) => void

Called when the set of visible rows changes. visibleRows maps { sectionID: { rowID: true }} for all the visible rows, and changedRows maps { sectionID: { rowID: true | false }} for the rows that have changed their visibility, with true indicating visible, and false indicating the view has moved out of view.

TypeRequired
functionNo

removeClippedSubviews

A performance optimization for improving scroll perf of large lists, used in conjunction with overflow: 'hidden' on the row containers. This is enabled by default.

TypeRequired
boolNo

renderFooter

() => renderable

The header and footer are always rendered (if these props are provided) on every render pass. If they are expensive to re-render, wrap them in StaticContainer or other mechanism as appropriate. Footer is always at the bottom of the list, and header at the top, on every render pass. In a horizontal ListView, the header is rendered on the left and the footer on the right.

TypeRequired
functionNo

Methods

getMetrics()

getMetrics();

Exports some data, e.g. for perf investigations or analytics.

scrollTo()

scrollTo((...args: Array));

Scrolls to a given x, y offset, either immediately or with a smooth animation.

See ScrollView#scrollTo.

scrollToEnd()

scrollToEnd(([options]: object));

If this is a vertical ListView scrolls to the bottom. If this is a horizontal ListView scrolls to the right.

Use scrollToEnd({animated: true}) for smooth animated scrolling, scrollToEnd({animated: false}) for immediate scrolling. If no options are passed, animated defaults to true.

See ScrollView#scrollToEnd.

flashScrollIndicators()

flashScrollIndicators();

Displays the scroll indicators momentarily.

Edit this page
Last updated on
- + diff --git a/docs/0.61/listviewdatasource.html b/docs/0.61/listviewdatasource.html index b32fd8b672d..9a97c1796ac 100644 --- a/docs/0.61/listviewdatasource.html +++ b/docs/0.61/listviewdatasource.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

ListViewDataSource

Provides efficient data processing and access to the ListView component. A ListViewDataSource is created with functions for extracting data from the input blob, and comparing elements (with default implementations for convenience). The input blob can be as flat as an array of strings, or an object with rows nested inside section objects.

To update the data in the datasource, use cloneWithRows (or cloneWithRowsAndSections if you care about sections). The data in the data source is immutable, so you can't modify it directly. The clone methods take in the new data and compute a diff for each row so ListView knows whether to re-render it or not.

In this example, a component receives data in chunks, handled by _onDataArrived, which concats the new data onto the old data and updates the data source. We use concat to create a new array - mutating this._data, e.g. with this._data.push(newRowData), would be an error. _rowHasChanged understands the shape of the row data and knows how to efficiently compare it.

getInitialState: function() {
var ds = new ListView.DataSource({rowHasChanged: this._rowHasChanged});
return {ds};
},
_onDataArrived(newData) {
this._data = this._data.concat(newData);
this.setState({
ds: this.state.ds.cloneWithRows(this._data)
});
}

Methods

Reference

Methods

constructor()

constructor(params);

You can provide custom extraction and hasChanged functions for section headers and rows. If absent, data will be extracted with the defaultGetRowData and defaultGetSectionHeaderData functions.

The default extractor expects data of one of the following forms:

{ sectionID_1: { rowID_1: <rowData1>, ... }, ... }

or

{ sectionID_1: [ <rowData1>, <rowData2>, ... ], ... }

or

[ [ <rowData1>, <rowData2>, ... ], ... ]

The constructor takes in a params argument that can contain any of the following:

  • getRowData(dataBlob, sectionID, rowID);
  • getSectionHeaderData(dataBlob, sectionID);
  • rowHasChanged(prevRowData, nextRowData);
  • sectionHeaderHasChanged(prevSectionData, nextSectionData);

cloneWithRows()

cloneWithRows(dataBlob, rowIdentities);

Clones this ListViewDataSource with the specified dataBlob and rowIdentities. The dataBlob an arbitrary blob of data. At construction an extractor to get the interesting information was defined (or the default was used).

The rowIdentities is a 2D array of identifiers for rows. ie. [['a1', 'a2'], ['b1', 'b2', 'b3'], ...]. If not provided, it's assumed that the keys of the section data are the row identities.

Note: This function does NOT clone the data in this data source. It only passes the functions defined at construction to a new data source with the data specified. If you wish to maintain the existing data you must handle merging of old and new data separately and then pass that into this function as the dataBlob.

cloneWithRowsAndSections()

cloneWithRowsAndSections(
dataBlob,
sectionIdentities,
rowIdentities
);

This performs the same function as the cloneWithRows function but here you also specify what your sectionIdentities are. If you don't care about sections you should safely be able to use cloneWithRows.

sectionIdentities is an array of identifiers for sections. ie. ['s1', 's2', ...]. The identifiers should correspond to the keys or array indexes of the data you wish to include. If not provided, it's assumed that the keys of dataBlob are the section identities.

Note: this returns a new object!

const dataSource = ds.cloneWithRowsAndSections({
addresses: ['row 1', 'row 2'],
phone_numbers: ['data 1', 'data 2'],
}, ['phone_numbers']);

getRowCount()

getRowCount();

Returns the total number of rows in the data source.

If you are specifying the rowIdentities or sectionIdentities, then getRowCount will return the number of rows in the filtered data source.

getRowAndSectionCount()

getRowAndSectionCount();

Returns the total number of rows in the data source (see getRowCount for how this is calculated) plus the number of sections in the data.

If you are specifying the rowIdentities or sectionIdentities, then getRowAndSectionCount will return the number of rows & sections in the filtered data source.

rowShouldUpdate()

rowShouldUpdate(sectionIndex, rowIndex);

Returns if the row is dirtied and needs to be rerendered

getRowData()

getRowData(sectionIndex, rowIndex);

Gets the data required to render the row.

getRowIDForFlatIndex()

getRowIDForFlatIndex(index);

Gets the rowID at index provided if the dataSource arrays were flattened, or null of out of range indexes.

getSectionIDForFlatIndex()

getSectionIDForFlatIndex(index);

Gets the sectionID at index provided if the dataSource arrays were flattened, or null for out of range indexes.

getSectionLengths()

getSectionLengths();

Returns an array containing the number of rows in each section

sectionHeaderShouldUpdate()

sectionHeaderShouldUpdate(sectionIndex);

Returns if the section header is dirtied and needs to be rerendered

getSectionHeaderData()

getSectionHeaderData(sectionIndex);

Gets the data required to render the section header

Edit this page
Last updated on
- + diff --git a/docs/0.61/listviewdatasource/index.html b/docs/0.61/listviewdatasource/index.html index b32fd8b672d..9a97c1796ac 100644 --- a/docs/0.61/listviewdatasource/index.html +++ b/docs/0.61/listviewdatasource/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

ListViewDataSource

Provides efficient data processing and access to the ListView component. A ListViewDataSource is created with functions for extracting data from the input blob, and comparing elements (with default implementations for convenience). The input blob can be as flat as an array of strings, or an object with rows nested inside section objects.

To update the data in the datasource, use cloneWithRows (or cloneWithRowsAndSections if you care about sections). The data in the data source is immutable, so you can't modify it directly. The clone methods take in the new data and compute a diff for each row so ListView knows whether to re-render it or not.

In this example, a component receives data in chunks, handled by _onDataArrived, which concats the new data onto the old data and updates the data source. We use concat to create a new array - mutating this._data, e.g. with this._data.push(newRowData), would be an error. _rowHasChanged understands the shape of the row data and knows how to efficiently compare it.

getInitialState: function() {
var ds = new ListView.DataSource({rowHasChanged: this._rowHasChanged});
return {ds};
},
_onDataArrived(newData) {
this._data = this._data.concat(newData);
this.setState({
ds: this.state.ds.cloneWithRows(this._data)
});
}

Methods

Reference

Methods

constructor()

constructor(params);

You can provide custom extraction and hasChanged functions for section headers and rows. If absent, data will be extracted with the defaultGetRowData and defaultGetSectionHeaderData functions.

The default extractor expects data of one of the following forms:

{ sectionID_1: { rowID_1: <rowData1>, ... }, ... }

or

{ sectionID_1: [ <rowData1>, <rowData2>, ... ], ... }

or

[ [ <rowData1>, <rowData2>, ... ], ... ]

The constructor takes in a params argument that can contain any of the following:

  • getRowData(dataBlob, sectionID, rowID);
  • getSectionHeaderData(dataBlob, sectionID);
  • rowHasChanged(prevRowData, nextRowData);
  • sectionHeaderHasChanged(prevSectionData, nextSectionData);

cloneWithRows()

cloneWithRows(dataBlob, rowIdentities);

Clones this ListViewDataSource with the specified dataBlob and rowIdentities. The dataBlob an arbitrary blob of data. At construction an extractor to get the interesting information was defined (or the default was used).

The rowIdentities is a 2D array of identifiers for rows. ie. [['a1', 'a2'], ['b1', 'b2', 'b3'], ...]. If not provided, it's assumed that the keys of the section data are the row identities.

Note: This function does NOT clone the data in this data source. It only passes the functions defined at construction to a new data source with the data specified. If you wish to maintain the existing data you must handle merging of old and new data separately and then pass that into this function as the dataBlob.

cloneWithRowsAndSections()

cloneWithRowsAndSections(
dataBlob,
sectionIdentities,
rowIdentities
);

This performs the same function as the cloneWithRows function but here you also specify what your sectionIdentities are. If you don't care about sections you should safely be able to use cloneWithRows.

sectionIdentities is an array of identifiers for sections. ie. ['s1', 's2', ...]. The identifiers should correspond to the keys or array indexes of the data you wish to include. If not provided, it's assumed that the keys of dataBlob are the section identities.

Note: this returns a new object!

const dataSource = ds.cloneWithRowsAndSections({
addresses: ['row 1', 'row 2'],
phone_numbers: ['data 1', 'data 2'],
}, ['phone_numbers']);

getRowCount()

getRowCount();

Returns the total number of rows in the data source.

If you are specifying the rowIdentities or sectionIdentities, then getRowCount will return the number of rows in the filtered data source.

getRowAndSectionCount()

getRowAndSectionCount();

Returns the total number of rows in the data source (see getRowCount for how this is calculated) plus the number of sections in the data.

If you are specifying the rowIdentities or sectionIdentities, then getRowAndSectionCount will return the number of rows & sections in the filtered data source.

rowShouldUpdate()

rowShouldUpdate(sectionIndex, rowIndex);

Returns if the row is dirtied and needs to be rerendered

getRowData()

getRowData(sectionIndex, rowIndex);

Gets the data required to render the row.

getRowIDForFlatIndex()

getRowIDForFlatIndex(index);

Gets the rowID at index provided if the dataSource arrays were flattened, or null of out of range indexes.

getSectionIDForFlatIndex()

getSectionIDForFlatIndex(index);

Gets the sectionID at index provided if the dataSource arrays were flattened, or null for out of range indexes.

getSectionLengths()

getSectionLengths();

Returns an array containing the number of rows in each section

sectionHeaderShouldUpdate()

sectionHeaderShouldUpdate(sectionIndex);

Returns if the section header is dirtied and needs to be rerendered

getSectionHeaderData()

getSectionHeaderData(sectionIndex);

Gets the data required to render the section header

Edit this page
Last updated on
- + diff --git a/docs/0.61/maskedviewios.html b/docs/0.61/maskedviewios.html index cba1083d666..8476d1016bc 100644 --- a/docs/0.61/maskedviewios.html +++ b/docs/0.61/maskedviewios.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
class MyMaskedView extends React.Component {
render() {
return (
// Determines shape of the mask
<MaskedViewIOS
style={{ flex: 1, flexDirection: 'row', height: '100%' }}
maskElement={
<View
style={{
// Transparent background because mask is based off alpha channel.
backgroundColor: 'transparent',
flex: 1,
justifyContent: 'center',
alignItems: 'center'
}}>
<Text
style={{
fontSize: 60,
color: 'black',
fontWeight: 'bold'
}}>
Basic Mask
</Text>
</View>
}>
{/* Shows behind the mask, you can put anything here, such as an image */}
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#324376'
}}
/>
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#F5DD90'
}}
/>
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#F76C5E'
}}
/>
</MaskedViewIOS>
);
}
}

The following image demonstrates that you can put almost anything behind the mask. The three examples shown are masked <View>, <Text>, and <Image>.

The alpha channel of the view rendered by the maskElement prop determines how much of the view's content and background shows through. Fully or partially opaque pixels allow the underlying content to show through but fully transparent pixels block that content.

Props

Reference

Props

maskElement

TypeRequired
elementYes
Edit this page
Last updated on
- + diff --git a/docs/0.61/maskedviewios/index.html b/docs/0.61/maskedviewios/index.html index cba1083d666..8476d1016bc 100644 --- a/docs/0.61/maskedviewios/index.html +++ b/docs/0.61/maskedviewios/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
class MyMaskedView extends React.Component {
render() {
return (
// Determines shape of the mask
<MaskedViewIOS
style={{ flex: 1, flexDirection: 'row', height: '100%' }}
maskElement={
<View
style={{
// Transparent background because mask is based off alpha channel.
backgroundColor: 'transparent',
flex: 1,
justifyContent: 'center',
alignItems: 'center'
}}>
<Text
style={{
fontSize: 60,
color: 'black',
fontWeight: 'bold'
}}>
Basic Mask
</Text>
</View>
}>
{/* Shows behind the mask, you can put anything here, such as an image */}
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#324376'
}}
/>
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#F5DD90'
}}
/>
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#F76C5E'
}}
/>
</MaskedViewIOS>
);
}
}

The following image demonstrates that you can put almost anything behind the mask. The three examples shown are masked <View>, <Text>, and <Image>.

The alpha channel of the view rendered by the maskElement prop determines how much of the view's content and background shows through. Fully or partially opaque pixels allow the underlying content to show through but fully transparent pixels block that content.

Props

Reference

Props

maskElement

TypeRequired
elementYes
Edit this page
Last updated on
- + diff --git a/docs/0.61/modal.html b/docs/0.61/modal.html index 5d093890126..2950c3be4dd 100644 --- a/docs/0.61/modal.html +++ b/docs/0.61/modal.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
<TouchableHighlight
onPress={() => {
this.setModalVisible(true);
}}>
<Text>Show Modal</Text>
</TouchableHighlight>
</View>
);
}
}

Reference

Props

visible

The visible prop determines whether your modal is visible.

TypeRequired
boolNo

supportedOrientations

The supportedOrientations prop allows the modal to be rotated to any of the specified orientations. On iOS, the modal is still restricted by what's specified in your app's Info.plist's UISupportedInterfaceOrientations field. When using presentationStyle of pageSheet or formSheet, this property will be ignored by iOS.

TypeRequiredPlatform
array of enum('portrait', 'portrait-upside-down', 'landscape', 'landscape-left', 'landscape-right')NoiOS

onRequestClose

The onRequestClose callback is called when the user taps the hardware back button on Android or the menu button on Apple TV. Because of this required prop, be aware that BackHandler events will not be emitted as long as the modal is open.

TypeRequiredPlatform
functionYesAndroid, Platform.isTVOS
functionNo(Others)

onShow

The onShow prop allows passing a function that will be called once the modal has been shown.

TypeRequired
functionNo

transparent

The transparent prop determines whether your modal will fill the entire view. Setting this to true will render the modal over a transparent background.

TypeRequired
boolNo

animationType

The animationType prop controls how the modal animates.

Default is set to none.

TypeRequired
enum('none', 'slide', 'fade')No

hardwareAccelerated

The hardwareAccelerated prop controls whether to force hardware acceleration for the underlying window.

TypeRequiredPlatform
boolNoAndroid

onDismiss

The onDismiss prop allows passing a function that will be called once the modal has been dismissed.

TypeRequiredPlatform
functionNoiOS

onOrientationChange

The onOrientationChange callback is called when the orientation changes while the modal is being displayed. The orientation provided is only 'portrait' or 'landscape'. This callback is also called on initial render, regardless of the current orientation.

TypeRequiredPlatform
functionNoiOS

presentationStyle

The presentationStyle prop controls how the modal appears (generally on larger devices such as iPad or plus-sized iPhones). See https://developer.apple.com/reference/uikit/uimodalpresentationstyle for details.

Default is set to overFullScreen or fullScreen depending on transparent property.

TypeRequiredPlatform
enum('fullScreen', 'pageSheet', 'formSheet', 'overFullScreen')NoiOS

animated

Deprecated. Use the animationType prop instead.

Edit this page
Last updated on
- + diff --git a/docs/0.61/modal/index.html b/docs/0.61/modal/index.html index 5d093890126..2950c3be4dd 100644 --- a/docs/0.61/modal/index.html +++ b/docs/0.61/modal/index.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
<TouchableHighlight
onPress={() => {
this.setModalVisible(true);
}}>
<Text>Show Modal</Text>
</TouchableHighlight>
</View>
);
}
}

Reference

Props

visible

The visible prop determines whether your modal is visible.

TypeRequired
boolNo

supportedOrientations

The supportedOrientations prop allows the modal to be rotated to any of the specified orientations. On iOS, the modal is still restricted by what's specified in your app's Info.plist's UISupportedInterfaceOrientations field. When using presentationStyle of pageSheet or formSheet, this property will be ignored by iOS.

TypeRequiredPlatform
array of enum('portrait', 'portrait-upside-down', 'landscape', 'landscape-left', 'landscape-right')NoiOS

onRequestClose

The onRequestClose callback is called when the user taps the hardware back button on Android or the menu button on Apple TV. Because of this required prop, be aware that BackHandler events will not be emitted as long as the modal is open.

TypeRequiredPlatform
functionYesAndroid, Platform.isTVOS
functionNo(Others)

onShow

The onShow prop allows passing a function that will be called once the modal has been shown.

TypeRequired
functionNo

transparent

The transparent prop determines whether your modal will fill the entire view. Setting this to true will render the modal over a transparent background.

TypeRequired
boolNo

animationType

The animationType prop controls how the modal animates.

Default is set to none.

TypeRequired
enum('none', 'slide', 'fade')No

hardwareAccelerated

The hardwareAccelerated prop controls whether to force hardware acceleration for the underlying window.

TypeRequiredPlatform
boolNoAndroid

onDismiss

The onDismiss prop allows passing a function that will be called once the modal has been dismissed.

TypeRequiredPlatform
functionNoiOS

onOrientationChange

The onOrientationChange callback is called when the orientation changes while the modal is being displayed. The orientation provided is only 'portrait' or 'landscape'. This callback is also called on initial render, regardless of the current orientation.

TypeRequiredPlatform
functionNoiOS

presentationStyle

The presentationStyle prop controls how the modal appears (generally on larger devices such as iPad or plus-sized iPhones). See https://developer.apple.com/reference/uikit/uimodalpresentationstyle for details.

Default is set to overFullScreen or fullScreen depending on transparent property.

TypeRequiredPlatform
enum('fullScreen', 'pageSheet', 'formSheet', 'overFullScreen')NoiOS

animated

Deprecated. Use the animationType prop instead.

Edit this page
Last updated on
- + diff --git a/docs/0.61/more-resources.html b/docs/0.61/more-resources.html index 2f163872ca2..928eb63f632 100644 --- a/docs/0.61/more-resources.html +++ b/docs/0.61/more-resources.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

More Resources

If you only read through this website, you should be able to build a pretty cool React Native app. But React Native isn't a product made by one company - it's a community of thousands of developers. So if you're interested in React Native, here's some related stuff you might want to check out.

Popular Libraries

If you're using React Native, you probably already know about React. So I feel a bit silly mentioning this. But if you haven't, check out React - it's the best way to build a modern website.

One common question is how to handle the "state" of your React Native application. The most popular library for this is Redux. Don't be afraid of how often Redux uses the word "reducer" - it's a pretty basic library, and there's also a nice series of videos explaining it.

If you're looking for a library that does a specific thing, check out Awesome React Native, a curated list of components that also has demos, articles, and other stuff.

Examples

Try out apps from the Showcase to see what React Native is capable of! There are also some example apps on GitHub. You can run the apps on a simulator or device, and you can see the source code for these apps, which is neat.

The folks who built the app for Facebook's F8 conference also open-sourced the code and wrote up a detailed series of tutorials. This is useful if you want a more in-depth example that's more realistic than most sample apps out there.

Extending React Native

  • Developers write and publish React Native modules to npm and open source them on GitHub.
  • Making modules helps grow the React Native ecosystem and community. We recommend writing modules for your use cases and sharing them on npm.
  • Read the guides on Native Modules (iOS, Android) and Native UI Components (iOS, Android) if you are interested in extending native functionality.
  • Looking for a pre-built component? Check JS.coach or Native Directory to find what the community has been creating.

Development Tools

Nuclide is the IDE that Facebook uses internally for JavaScript development. The killer feature of Nuclide is its debugging ability. It also has great inline Flow support. VS Code is another IDE that is popular with JavaScript developers.

Ignite is a starter kit that uses Redux and a few different common UI libraries. It has a CLI to generate apps, components, and containers. If you like all of the individual tech choices, Ignite could be perfect for you.

App Center is a service from Microsoft that allows you to deploy live updates to your React Native app. If you don't like going through the app store process to deploy little tweaks, and you also don't like setting up your own backend, give App Center a try.

Expo is a development environment plus application that focuses on letting you build React Native apps in the Expo development environment, without ever touching Xcode or Android Studio. If you wish React Native was even more JavaScripty and webby, check out Expo.

Yoga is a stand-alone layout engine that extends beyond React Native and allows product engineers to build layouts quickly for multiple platforms with a highly optimized open source layout engine designed with speed, size, and ease of use in mind.

Bugsnag, Microsoft App Center, and Sentry all provide excellent crash and error monitoring services for React and React Native apps. These services allow you to proactively monitor crashes and issues occurring on your apps in real time so you can fix them quickly and improve user experience.

The React Developer Tools are great for debugging React and React Native apps.

Edit this page
Last updated on
- + diff --git a/docs/0.61/more-resources/index.html b/docs/0.61/more-resources/index.html index 2f163872ca2..928eb63f632 100644 --- a/docs/0.61/more-resources/index.html +++ b/docs/0.61/more-resources/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

More Resources

If you only read through this website, you should be able to build a pretty cool React Native app. But React Native isn't a product made by one company - it's a community of thousands of developers. So if you're interested in React Native, here's some related stuff you might want to check out.

Popular Libraries

If you're using React Native, you probably already know about React. So I feel a bit silly mentioning this. But if you haven't, check out React - it's the best way to build a modern website.

One common question is how to handle the "state" of your React Native application. The most popular library for this is Redux. Don't be afraid of how often Redux uses the word "reducer" - it's a pretty basic library, and there's also a nice series of videos explaining it.

If you're looking for a library that does a specific thing, check out Awesome React Native, a curated list of components that also has demos, articles, and other stuff.

Examples

Try out apps from the Showcase to see what React Native is capable of! There are also some example apps on GitHub. You can run the apps on a simulator or device, and you can see the source code for these apps, which is neat.

The folks who built the app for Facebook's F8 conference also open-sourced the code and wrote up a detailed series of tutorials. This is useful if you want a more in-depth example that's more realistic than most sample apps out there.

Extending React Native

  • Developers write and publish React Native modules to npm and open source them on GitHub.
  • Making modules helps grow the React Native ecosystem and community. We recommend writing modules for your use cases and sharing them on npm.
  • Read the guides on Native Modules (iOS, Android) and Native UI Components (iOS, Android) if you are interested in extending native functionality.
  • Looking for a pre-built component? Check JS.coach or Native Directory to find what the community has been creating.

Development Tools

Nuclide is the IDE that Facebook uses internally for JavaScript development. The killer feature of Nuclide is its debugging ability. It also has great inline Flow support. VS Code is another IDE that is popular with JavaScript developers.

Ignite is a starter kit that uses Redux and a few different common UI libraries. It has a CLI to generate apps, components, and containers. If you like all of the individual tech choices, Ignite could be perfect for you.

App Center is a service from Microsoft that allows you to deploy live updates to your React Native app. If you don't like going through the app store process to deploy little tweaks, and you also don't like setting up your own backend, give App Center a try.

Expo is a development environment plus application that focuses on letting you build React Native apps in the Expo development environment, without ever touching Xcode or Android Studio. If you wish React Native was even more JavaScripty and webby, check out Expo.

Yoga is a stand-alone layout engine that extends beyond React Native and allows product engineers to build layouts quickly for multiple platforms with a highly optimized open source layout engine designed with speed, size, and ease of use in mind.

Bugsnag, Microsoft App Center, and Sentry all provide excellent crash and error monitoring services for React and React Native apps. These services allow you to proactively monitor crashes and issues occurring on your apps in real time so you can fix them quickly and improve user experience.

The React Developer Tools are great for debugging React and React Native apps.

Edit this page
Last updated on
- + diff --git a/docs/0.61/native-components-android.html b/docs/0.61/native-components-android.html index b0cb37351d1..067f3ff8fea 100644 --- a/docs/0.61/native-components-android.html +++ b/docs/0.61/native-components-android.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
var RCTMyCustomView = requireNativeComponent(`RCTMyCustomView`);
Edit this page
Last updated on
- + diff --git a/docs/0.61/native-components-android/index.html b/docs/0.61/native-components-android/index.html index b0cb37351d1..067f3ff8fea 100644 --- a/docs/0.61/native-components-android/index.html +++ b/docs/0.61/native-components-android/index.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
var RCTMyCustomView = requireNativeComponent(`RCTMyCustomView`);
Edit this page
Last updated on
- + diff --git a/docs/0.61/native-components-ios.html b/docs/0.61/native-components-ios.html index 4045017637d..2349b2d770d 100644 --- a/docs/0.61/native-components-ios.html +++ b/docs/0.61/native-components-ios.html @@ -19,7 +19,7 @@ - + @@ -96,7 +96,7 @@
return @{
@"ComponentHeight": @(CGRectGetHeight(dp.frame)),
@"ComponentWidth": @(CGRectGetWidth(dp.frame)),
@"DatePickerModes": @{
@"time": @(UIDatePickerModeTime),
@"date": @(UIDatePickerModeDate),
@"datetime": @(UIDatePickerModeDateAndTime),
}
};
}

This guide covered many of the aspects of bridging over custom native components, but there is even more you might need to consider, such as custom hooks for inserting and laying out subviews. If you want to go even deeper, check out the source code of some of the implemented components.

Edit this page
Last updated on
- + diff --git a/docs/0.61/native-components-ios/index.html b/docs/0.61/native-components-ios/index.html index 4045017637d..2349b2d770d 100644 --- a/docs/0.61/native-components-ios/index.html +++ b/docs/0.61/native-components-ios/index.html @@ -19,7 +19,7 @@ - + @@ -96,7 +96,7 @@
return @{
@"ComponentHeight": @(CGRectGetHeight(dp.frame)),
@"ComponentWidth": @(CGRectGetWidth(dp.frame)),
@"DatePickerModes": @{
@"time": @(UIDatePickerModeTime),
@"date": @(UIDatePickerModeDate),
@"datetime": @(UIDatePickerModeDateAndTime),
}
};
}

This guide covered many of the aspects of bridging over custom native components, but there is even more you might need to consider, such as custom hooks for inserting and laying out subviews. If you want to go even deeper, check out the source code of some of the implemented components.

Edit this page
Last updated on
- + diff --git a/docs/0.61/native-modules-android.html b/docs/0.61/native-modules-android.html index eedfd6db067..39d7b98af32 100644 --- a/docs/0.61/native-modules-android.html +++ b/docs/0.61/native-modules-android.html @@ -19,7 +19,7 @@ - + @@ -83,7 +83,7 @@
@Override
public void onHostDestroy() {
// Activity `onDestroy`
}
Edit this page
Last updated on
- + diff --git a/docs/0.61/native-modules-android/index.html b/docs/0.61/native-modules-android/index.html index eedfd6db067..39d7b98af32 100644 --- a/docs/0.61/native-modules-android/index.html +++ b/docs/0.61/native-modules-android/index.html @@ -19,7 +19,7 @@ - + @@ -83,7 +83,7 @@
@Override
public void onHostDestroy() {
// Activity `onDestroy`
}
Edit this page
Last updated on
- + diff --git a/docs/0.61/native-modules-ios.html b/docs/0.61/native-modules-ios.html index d84d256fac2..03a1a0b496c 100644 --- a/docs/0.61/native-modules-ios.html +++ b/docs/0.61/native-modules-ios.html @@ -19,7 +19,7 @@ - + @@ -71,7 +71,7 @@
@end

For those of you new to Swift and Objective-C, whenever you mix the two languages in an iOS project, you will also need an additional bridging file, known as a bridging header, to expose the Objective-C files to Swift. Xcode will offer to create this header file for you if you add your Swift file to your app through the Xcode File>New File menu option. You will need to import RCTBridgeModule.h in this header file.

// CalendarManager-Bridging-Header.h
#import <React/RCTBridgeModule.h>

You can also use RCT_EXTERN_REMAP_MODULE and _RCT_EXTERN_REMAP_METHOD to alter the JavaScript name of the module or methods you are exporting. For more information see RCTBridgeModule.

Important when making third party modules: Static libraries with Swift are only supported in Xcode 9 and later. In order for the Xcode project to build when you use Swift in the iOS static library you include in the module, your main app project must contain Swift code and a bridging header itself. If your app project does not contain any Swift code, a workaround can be a single empty .swift file and an empty bridging header.

Edit this page
Last updated on
- + diff --git a/docs/0.61/native-modules-ios/index.html b/docs/0.61/native-modules-ios/index.html index d84d256fac2..03a1a0b496c 100644 --- a/docs/0.61/native-modules-ios/index.html +++ b/docs/0.61/native-modules-ios/index.html @@ -19,7 +19,7 @@ - + @@ -71,7 +71,7 @@
@end

For those of you new to Swift and Objective-C, whenever you mix the two languages in an iOS project, you will also need an additional bridging file, known as a bridging header, to expose the Objective-C files to Swift. Xcode will offer to create this header file for you if you add your Swift file to your app through the Xcode File>New File menu option. You will need to import RCTBridgeModule.h in this header file.

// CalendarManager-Bridging-Header.h
#import <React/RCTBridgeModule.h>

You can also use RCT_EXTERN_REMAP_MODULE and _RCT_EXTERN_REMAP_METHOD to alter the JavaScript name of the module or methods you are exporting. For more information see RCTBridgeModule.

Important when making third party modules: Static libraries with Swift are only supported in Xcode 9 and later. In order for the Xcode project to build when you use Swift in the iOS static library you include in the module, your main app project must contain Swift code and a bridging header itself. If your app project does not contain any Swift code, a workaround can be a single empty .swift file and an empty bridging header.

Edit this page
Last updated on
- + diff --git a/docs/0.61/native-modules-setup.html b/docs/0.61/native-modules-setup.html index 48e68795f54..ee12778245d 100644 --- a/docs/0.61/native-modules-setup.html +++ b/docs/0.61/native-modules-setup.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Native Modules Setup

Native modules are usually distributed as npm packages, except that on top of the usual JavaScript they will include some native code per platform. To understand more about npm packages you may find this guide useful.

To get set up with the basic project structure for a native module we will use a third party tool create-react-native-module. You can go ahead further and dive deep into how that library works, for our needs we will only need:

$ yarn global add create-react-native-module
$ create-react-native-module MyLibrary

Where MyLibrary is the name you would like for the new module. After doing this you will navigate into MyLibrary folder and install the npm package to be locally available for your computer by doing:

$ yarn install

After this is done you can go to your main react app folder (which you created by doing react-native init MyApp)

  • add your newly created module as a dependency in your package.json
  • run yarn install to bring it along from your local npm repository.

After this, you will be able to continue to Native Modules (iOS) or Native Modules (Android) to add in some code. Make sure to read the README.md within your MyLibrary Directory for platform-specific instructions on how to include the project.

Edit this page
Last updated on
- + diff --git a/docs/0.61/native-modules-setup/index.html b/docs/0.61/native-modules-setup/index.html index 48e68795f54..ee12778245d 100644 --- a/docs/0.61/native-modules-setup/index.html +++ b/docs/0.61/native-modules-setup/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Native Modules Setup

Native modules are usually distributed as npm packages, except that on top of the usual JavaScript they will include some native code per platform. To understand more about npm packages you may find this guide useful.

To get set up with the basic project structure for a native module we will use a third party tool create-react-native-module. You can go ahead further and dive deep into how that library works, for our needs we will only need:

$ yarn global add create-react-native-module
$ create-react-native-module MyLibrary

Where MyLibrary is the name you would like for the new module. After doing this you will navigate into MyLibrary folder and install the npm package to be locally available for your computer by doing:

$ yarn install

After this is done you can go to your main react app folder (which you created by doing react-native init MyApp)

  • add your newly created module as a dependency in your package.json
  • run yarn install to bring it along from your local npm repository.

After this, you will be able to continue to Native Modules (iOS) or Native Modules (Android) to add in some code. Make sure to read the README.md within your MyLibrary Directory for platform-specific instructions on how to include the project.

Edit this page
Last updated on
- + diff --git a/docs/0.61/navigation.html b/docs/0.61/navigation.html index ec3cc5a08f9..ee59c43d28a 100644 --- a/docs/0.61/navigation.html +++ b/docs/0.61/navigation.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
function MyStack() {
return (
<NavigationContainer>
<Stack.Navigator>
<Stack.Screen
name="Home"
component={Home}
options={{ title: 'Welcome' }}
/>
<Stack.Screen name="Profile" component={Profile} />
</Stack.Navigator>
</NavigationContainer>
);
}

In this example, there are 2 screens (Home and Profile) defined using the Stack.Screen component. Similarly, you can define as many screens as you like.

You can set options such as the screen title for each screen in the options prop of Stack.Screen.

Each screen takes a component prop that is a React component. Those components receive a prop called navigation which has various methods to link to other screens. For example, you can use navigation.navigate to go to the Profile screen:

function HomeScreen({ navigation }) {
return (
<Button
title="Go to Jane's profile"
onPress={() =>
navigation.navigate('Profile', { name: 'Jane' })
}
/>
);
}

The views in the stack navigator use native components and the Animated library to deliver 60fps animations that are run on the native thread. Plus, the animations and gestures can be customized.

React Navigation also has packages for different kind of navigators such as tabs and drawer. You can use them to implement various patterns in your app.

For a complete intro to React Navigation, follow the React Navigation Getting Started Guide.

Edit this page
Last updated on
- + diff --git a/docs/0.61/navigation/index.html b/docs/0.61/navigation/index.html index ec3cc5a08f9..ee59c43d28a 100644 --- a/docs/0.61/navigation/index.html +++ b/docs/0.61/navigation/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
function MyStack() {
return (
<NavigationContainer>
<Stack.Navigator>
<Stack.Screen
name="Home"
component={Home}
options={{ title: 'Welcome' }}
/>
<Stack.Screen name="Profile" component={Profile} />
</Stack.Navigator>
</NavigationContainer>
);
}

In this example, there are 2 screens (Home and Profile) defined using the Stack.Screen component. Similarly, you can define as many screens as you like.

You can set options such as the screen title for each screen in the options prop of Stack.Screen.

Each screen takes a component prop that is a React component. Those components receive a prop called navigation which has various methods to link to other screens. For example, you can use navigation.navigate to go to the Profile screen:

function HomeScreen({ navigation }) {
return (
<Button
title="Go to Jane's profile"
onPress={() =>
navigation.navigate('Profile', { name: 'Jane' })
}
/>
);
}

The views in the stack navigator use native components and the Animated library to deliver 60fps animations that are run on the native thread. Plus, the animations and gestures can be customized.

React Navigation also has packages for different kind of navigators such as tabs and drawer. You can use them to implement various patterns in your app.

For a complete intro to React Navigation, follow the React Navigation Getting Started Guide.

Edit this page
Last updated on
- + diff --git a/docs/0.61/netinfo.html b/docs/0.61/netinfo.html index 0ad209042a3..4daf296e5c3 100644 --- a/docs/0.61/netinfo.html +++ b/docs/0.61/netinfo.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

NetInfo

Deprecated. Use react-native-community/react-native-netinfo instead.

NetInfo exposes info about online/offline status

NetInfo.getConnectionInfo().then((connectionInfo) => {
console.log(
'Initial, type: ' +
connectionInfo.type +
', effectiveType: ' +
connectionInfo.effectiveType
);
});
function handleFirstConnectivityChange(connectionInfo) {
console.log(
'First change, type: ' +
connectionInfo.type +
', effectiveType: ' +
connectionInfo.effectiveType
);
NetInfo.removeEventListener(
'connectionChange',
handleFirstConnectivityChange
);
}
NetInfo.addEventListener(
'connectionChange',
handleFirstConnectivityChange
);

ConnectionType enum

ConnectionType describes the type of connection the device is using to communicate with the network.

Cross platform values for ConnectionType:

  • none - device is offline
  • wifi - device is online and connected via wifi, or is the iOS simulator
  • cellular - device is connected via Edge, 3G, WiMax, or LTE
  • unknown - error case and the network status is unknown

Android-only values for ConnectionType:

  • bluetooth - device is connected via Bluetooth
  • ethernet - device is connected via Ethernet
  • wimax - device is connected via WiMAX

EffectiveConnectionType enum

Cross platform values for EffectiveConnectionType:

  • 2g
  • 3g
  • 4g
  • unknown

Android

To request network info, you need to add the following line to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Methods

Properties

Reference

Methods

addEventListener()

NetInfo.addEventListener(eventName, handler);

Adds an event handler.

Parameters:

NameTypeRequiredDescription
eventNameenum(connectionChange, change)YesThe change event name.
handlerfunctionYesListener function.

Supported events:

  • connectionChange: Fires when the network status changes. The argument to the event handler is an object with keys:
    • type: A ConnectionType (listed above)
    • effectiveType: An EffectiveConnectionType (listed above)
  • change: This event is deprecated. Listen to connectionChange instead. Fires when the network status changes. The argument to the event handler is one of the deprecated connectivity types listed above.

removeEventListener()

NetInfo.removeEventListener(eventName, handler);

Removes the listener for network status changes.

Parameters:

NameTypeRequiredDescription
eventNameenum(connectionChange, change)YesThe change event name.
handlerfunctionYesListener function.

getConnectionInfo()

NetInfo.getConnectionInfo();

Returns a promise that resolves to an object with type and effectiveType keys whose values are a ConnectionType and an EffectiveConnectionType), respectively.

isConnectionExpensive()

NetInfo.isConnectionExpensive();

Available on Android. Detect if the current active connection is metered or not. A network is classified as metered when the user is sensitive to heavy data usage on that connection due to monetary costs, data limitations or battery/performance issues.

NetInfo.isConnectionExpensive()
.then(isConnectionExpensive => {
console.log('Connection is ' + (isConnectionExpensive ? 'Expensive' : 'Not Expensive'));
})
.catch(error => {
console.error(error);
});

Properties

isConnected

Available on all platforms. Asynchronously fetch a boolean to determine internet connectivity.

NetInfo.isConnected.fetch().then(isConnected => {
console.log('First, is ' + (isConnected ? 'online' : 'offline'));
});
function handleFirstConnectivityChange(isConnected) {
console.log('Then, is ' + (isConnected ? 'online' : 'offline'));
NetInfo.isConnected.removeEventListener(
'connectionChange',
handleFirstConnectivityChange
);
}
NetInfo.isConnected.addEventListener(
'connectionChange',
handleFirstConnectivityChange
);
Edit this page
Last updated on
- + diff --git a/docs/0.61/netinfo/index.html b/docs/0.61/netinfo/index.html index 0ad209042a3..4daf296e5c3 100644 --- a/docs/0.61/netinfo/index.html +++ b/docs/0.61/netinfo/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

NetInfo

Deprecated. Use react-native-community/react-native-netinfo instead.

NetInfo exposes info about online/offline status

NetInfo.getConnectionInfo().then((connectionInfo) => {
console.log(
'Initial, type: ' +
connectionInfo.type +
', effectiveType: ' +
connectionInfo.effectiveType
);
});
function handleFirstConnectivityChange(connectionInfo) {
console.log(
'First change, type: ' +
connectionInfo.type +
', effectiveType: ' +
connectionInfo.effectiveType
);
NetInfo.removeEventListener(
'connectionChange',
handleFirstConnectivityChange
);
}
NetInfo.addEventListener(
'connectionChange',
handleFirstConnectivityChange
);

ConnectionType enum

ConnectionType describes the type of connection the device is using to communicate with the network.

Cross platform values for ConnectionType:

  • none - device is offline
  • wifi - device is online and connected via wifi, or is the iOS simulator
  • cellular - device is connected via Edge, 3G, WiMax, or LTE
  • unknown - error case and the network status is unknown

Android-only values for ConnectionType:

  • bluetooth - device is connected via Bluetooth
  • ethernet - device is connected via Ethernet
  • wimax - device is connected via WiMAX

EffectiveConnectionType enum

Cross platform values for EffectiveConnectionType:

  • 2g
  • 3g
  • 4g
  • unknown

Android

To request network info, you need to add the following line to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Methods

Properties

Reference

Methods

addEventListener()

NetInfo.addEventListener(eventName, handler);

Adds an event handler.

Parameters:

NameTypeRequiredDescription
eventNameenum(connectionChange, change)YesThe change event name.
handlerfunctionYesListener function.

Supported events:

  • connectionChange: Fires when the network status changes. The argument to the event handler is an object with keys:
    • type: A ConnectionType (listed above)
    • effectiveType: An EffectiveConnectionType (listed above)
  • change: This event is deprecated. Listen to connectionChange instead. Fires when the network status changes. The argument to the event handler is one of the deprecated connectivity types listed above.

removeEventListener()

NetInfo.removeEventListener(eventName, handler);

Removes the listener for network status changes.

Parameters:

NameTypeRequiredDescription
eventNameenum(connectionChange, change)YesThe change event name.
handlerfunctionYesListener function.

getConnectionInfo()

NetInfo.getConnectionInfo();

Returns a promise that resolves to an object with type and effectiveType keys whose values are a ConnectionType and an EffectiveConnectionType), respectively.

isConnectionExpensive()

NetInfo.isConnectionExpensive();

Available on Android. Detect if the current active connection is metered or not. A network is classified as metered when the user is sensitive to heavy data usage on that connection due to monetary costs, data limitations or battery/performance issues.

NetInfo.isConnectionExpensive()
.then(isConnectionExpensive => {
console.log('Connection is ' + (isConnectionExpensive ? 'Expensive' : 'Not Expensive'));
})
.catch(error => {
console.error(error);
});

Properties

isConnected

Available on all platforms. Asynchronously fetch a boolean to determine internet connectivity.

NetInfo.isConnected.fetch().then(isConnected => {
console.log('First, is ' + (isConnected ? 'online' : 'offline'));
});
function handleFirstConnectivityChange(isConnected) {
console.log('Then, is ' + (isConnected ? 'online' : 'offline'));
NetInfo.isConnected.removeEventListener(
'connectionChange',
handleFirstConnectivityChange
);
}
NetInfo.isConnected.addEventListener(
'connectionChange',
handleFirstConnectivityChange
);
Edit this page
Last updated on
- + diff --git a/docs/0.61/network.html b/docs/0.61/network.html index 6ca7a1e5cb7..633dba3e008 100644 --- a/docs/0.61/network.html +++ b/docs/0.61/network.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
ws.onclose = (e) => {
// connection closed
console.log(e.code, e.reason);
};

Known Issues with fetch and cookie based authentication

The following options are currently not working with fetch

Edit this page
Last updated on
- + diff --git a/docs/0.61/network/index.html b/docs/0.61/network/index.html index 6ca7a1e5cb7..633dba3e008 100644 --- a/docs/0.61/network/index.html +++ b/docs/0.61/network/index.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
ws.onclose = (e) => {
// connection closed
console.log(e.code, e.reason);
};

Known Issues with fetch and cookie based authentication

The following options are currently not working with fetch

Edit this page
Last updated on
- + diff --git a/docs/0.61/optimizing-flatlist-configuration.html b/docs/0.61/optimizing-flatlist-configuration.html index 8e9843a1550..858c493aaa5 100644 --- a/docs/0.61/optimizing-flatlist-configuration.html +++ b/docs/0.61/optimizing-flatlist-configuration.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// ...
}
Edit this page
Last updated on
- + diff --git a/docs/0.61/optimizing-flatlist-configuration/index.html b/docs/0.61/optimizing-flatlist-configuration/index.html index 8e9843a1550..858c493aaa5 100644 --- a/docs/0.61/optimizing-flatlist-configuration/index.html +++ b/docs/0.61/optimizing-flatlist-configuration/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// ...
}
Edit this page
Last updated on
- + diff --git a/docs/0.61/out-of-tree-platforms.html b/docs/0.61/out-of-tree-platforms.html index ccb8a5c8770..90d0752b140 100644 --- a/docs/0.61/out-of-tree-platforms.html +++ b/docs/0.61/out-of-tree-platforms.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Out-of-Tree Platforms

React Native is not only for Android and iOS - there are community-supported projects that bring it to other platforms, such as:

Creating your own React Native platform

Right now the process of creating a React Native platform from scratch is not very well documented - one of the goals of the upcoming re-architecture (Fabric) is to make maintaining a platform easier.

Bundling

As of React Native 0.57 you can now register your React Native platform with React Native's JavaScript bundler, Metro. This means you can pass --platform example to react-native bundle, and it will look for JavaScript files with the .example.js suffix.

To register your platform with RNPM, your module's name must match one of these patterns:

  • react-native-example - It will search all top-level modules that start with react-native-
  • @org/react-native-example - It will search for modules that start with react-native- under any scope
  • @react-native-example/module - It will search in all modules under scopes with names starting with @react-native-

You must also have an entry in your package.json like this:

{
"rnpm": {
"haste": {
"providesModuleNodeModules": ["react-native-example"],
"platforms": ["example"]
}
}
}

"providesModuleNodeModules" is an array of modules that will get added to the Haste module search path, and "platforms" is an array of platform suffixes that will be added as valid platforms.

Edit this page
Last updated on
- + diff --git a/docs/0.61/out-of-tree-platforms/index.html b/docs/0.61/out-of-tree-platforms/index.html index ccb8a5c8770..90d0752b140 100644 --- a/docs/0.61/out-of-tree-platforms/index.html +++ b/docs/0.61/out-of-tree-platforms/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Out-of-Tree Platforms

React Native is not only for Android and iOS - there are community-supported projects that bring it to other platforms, such as:

Creating your own React Native platform

Right now the process of creating a React Native platform from scratch is not very well documented - one of the goals of the upcoming re-architecture (Fabric) is to make maintaining a platform easier.

Bundling

As of React Native 0.57 you can now register your React Native platform with React Native's JavaScript bundler, Metro. This means you can pass --platform example to react-native bundle, and it will look for JavaScript files with the .example.js suffix.

To register your platform with RNPM, your module's name must match one of these patterns:

  • react-native-example - It will search all top-level modules that start with react-native-
  • @org/react-native-example - It will search for modules that start with react-native- under any scope
  • @react-native-example/module - It will search in all modules under scopes with names starting with @react-native-

You must also have an entry in your package.json like this:

{
"rnpm": {
"haste": {
"providesModuleNodeModules": ["react-native-example"],
"platforms": ["example"]
}
}
}

"providesModuleNodeModules" is an array of modules that will get added to the Haste module search path, and "platforms" is an array of platform suffixes that will be added as valid platforms.

Edit this page
Last updated on
- + diff --git a/docs/0.61/panresponder.html b/docs/0.61/panresponder.html index e67edcd618d..73513665d09 100644 --- a/docs/0.61/panresponder.html +++ b/docs/0.61/panresponder.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
render() {
return <View {...this._panResponder.panHandlers} />;
}
}

Working Example

To see it in action, try the PanResponder example in RNTester

Reference

Methods

create()

static create(config)

@param {object} config Enhanced versions of all of the responder callbacks that provide not only the typical ResponderSyntheticEvent, but also the PanResponder gesture state, by replacing the word Responder with PanResponder in each of the typical onResponder* callbacks. For example, the config object would look like:

In general, for events that have capture equivalents, we update the gestureState once in the capture phase and can use it in the bubble phase as well.

Be careful with onStartShould* callbacks. They only reflect updated gestureState for start/end events that bubble/capture to the Node. Once the node is the responder, you can rely on every start/end event being processed by the gesture and gestureState being updated accordingly. (numberActiveTouches) may not be totally accurate unless you are the responder.

Edit this page
Last updated on
- + diff --git a/docs/0.61/panresponder/index.html b/docs/0.61/panresponder/index.html index e67edcd618d..73513665d09 100644 --- a/docs/0.61/panresponder/index.html +++ b/docs/0.61/panresponder/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
render() {
return <View {...this._panResponder.panHandlers} />;
}
}

Working Example

To see it in action, try the PanResponder example in RNTester

Reference

Methods

create()

static create(config)

@param {object} config Enhanced versions of all of the responder callbacks that provide not only the typical ResponderSyntheticEvent, but also the PanResponder gesture state, by replacing the word Responder with PanResponder in each of the typical onResponder* callbacks. For example, the config object would look like:

In general, for events that have capture equivalents, we update the gestureState once in the capture phase and can use it in the bubble phase as well.

Be careful with onStartShould* callbacks. They only reflect updated gestureState for start/end events that bubble/capture to the Node. Once the node is the responder, you can rely on every start/end event being processed by the gesture and gestureState being updated accordingly. (numberActiveTouches) may not be totally accurate unless you are the responder.

Edit this page
Last updated on
- + diff --git a/docs/0.61/performance.html b/docs/0.61/performance.html index 530cce981bd..58f815d7235 100644 --- a/docs/0.61/performance.html +++ b/docs/0.61/performance.html @@ -19,7 +19,7 @@ - + @@ -45,7 +45,7 @@
module.exports = config;

The preloadedModules entry in the config indicates which modules should be marked as preloaded when building a RAM bundle. When the bundle is loaded, those modules are immediately loaded, before any requires have even executed. The blacklist entry indicates that those modules should not be required inline. Because they are preloaded, there is no performance benefit from using an inline require. In fact the javascript spends extra time resolving the inline require every time the imports are referenced.

Test and Measure Improvements

You should now be ready to build your app using the RAM format and inline requires. Make sure you measure the before and after startup times.

Edit this page
Last updated on
- + diff --git a/docs/0.61/performance/index.html b/docs/0.61/performance/index.html index 530cce981bd..58f815d7235 100644 --- a/docs/0.61/performance/index.html +++ b/docs/0.61/performance/index.html @@ -19,7 +19,7 @@ - + @@ -45,7 +45,7 @@
module.exports = config;

The preloadedModules entry in the config indicates which modules should be marked as preloaded when building a RAM bundle. When the bundle is loaded, those modules are immediately loaded, before any requires have even executed. The blacklist entry indicates that those modules should not be required inline. Because they are preloaded, there is no performance benefit from using an inline require. In fact the javascript spends extra time resolving the inline require every time the imports are referenced.

Test and Measure Improvements

You should now be ready to build your app using the RAM format and inline requires. Make sure you measure the before and after startup times.

Edit this page
Last updated on
- + diff --git a/docs/0.61/permissionsandroid.html b/docs/0.61/permissionsandroid.html index 54abccbd5a6..b6ed5e8bc7b 100644 --- a/docs/0.61/permissionsandroid.html +++ b/docs/0.61/permissionsandroid.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
async function requestCameraPermission() {
try {
const granted = await PermissionsAndroid.request(
PermissionsAndroid.PERMISSIONS.CAMERA,
{
title: 'Cool Photo App Camera Permission',
message:
'Cool Photo App needs access to your camera ' +
'so you can take awesome pictures.',
buttonNeutral: 'Ask Me Later',
buttonNegative: 'Cancel',
buttonPositive: 'OK'
}
);
if (granted === PermissionsAndroid.RESULTS.GRANTED) {
console.log('You can use the camera');
} else {
console.log('Camera permission denied');
}
} catch (err) {
console.warn(err);
}
}

Permissions that require prompting the user

Available as constants under PermissionsAndroid.PERMISSIONS:

Result strings for requesting permissions

Available as constants under PermissionsAndroid.RESULTS:

Reference

Methods

constructor()

constructor();

check()

check(permission);

Returns a promise resolving to a boolean value as to whether the specified permissions has been granted.

Parameters:

NameTypeRequiredDescription
permissionstringYesThe permission to check for.

request()

request(permission, [rationale]);

Prompts the user to enable a permission and returns a promise resolving to a string value (see result strings above) indicating whether the user allowed or denied the request or does not want to be asked again.

If rationale is provided, this function checks with the OS whether it is necessary to show a dialog explaining why the permission is needed (https://developer.android.com/training/permissions/requesting.html#explain) and then shows the system permission dialog.

Parameters:

NameTypeRequiredDescription
permissionstringYesThe permission to request.
rationaleobjectNoSee rationale below.

Rationale:

NameTypeRequiredDescription
titlestringYesThe title of the dialog.
messagestringYesThe message of the dialog.
buttonPositivestringYesThe text of the positive button.
buttonNegativestringNoThe text of the negative button.
buttonNeutralstringNoThe text of the neutral button.

requestMultiple()

requestMultiple(permissions);

Prompts the user to enable multiple permissions in the same dialog and returns an object with the permissions as keys and strings as values (see result strings above) indicating whether the user allowed or denied the request or does not want to be asked again.

Parameters:

NameTypeRequiredDescription
permissionsarrayYesArray of permissions to request.
Edit this page
Last updated on
- + diff --git a/docs/0.61/permissionsandroid/index.html b/docs/0.61/permissionsandroid/index.html index 54abccbd5a6..b6ed5e8bc7b 100644 --- a/docs/0.61/permissionsandroid/index.html +++ b/docs/0.61/permissionsandroid/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
async function requestCameraPermission() {
try {
const granted = await PermissionsAndroid.request(
PermissionsAndroid.PERMISSIONS.CAMERA,
{
title: 'Cool Photo App Camera Permission',
message:
'Cool Photo App needs access to your camera ' +
'so you can take awesome pictures.',
buttonNeutral: 'Ask Me Later',
buttonNegative: 'Cancel',
buttonPositive: 'OK'
}
);
if (granted === PermissionsAndroid.RESULTS.GRANTED) {
console.log('You can use the camera');
} else {
console.log('Camera permission denied');
}
} catch (err) {
console.warn(err);
}
}

Permissions that require prompting the user

Available as constants under PermissionsAndroid.PERMISSIONS:

Result strings for requesting permissions

Available as constants under PermissionsAndroid.RESULTS:

Reference

Methods

constructor()

constructor();

check()

check(permission);

Returns a promise resolving to a boolean value as to whether the specified permissions has been granted.

Parameters:

NameTypeRequiredDescription
permissionstringYesThe permission to check for.

request()

request(permission, [rationale]);

Prompts the user to enable a permission and returns a promise resolving to a string value (see result strings above) indicating whether the user allowed or denied the request or does not want to be asked again.

If rationale is provided, this function checks with the OS whether it is necessary to show a dialog explaining why the permission is needed (https://developer.android.com/training/permissions/requesting.html#explain) and then shows the system permission dialog.

Parameters:

NameTypeRequiredDescription
permissionstringYesThe permission to request.
rationaleobjectNoSee rationale below.

Rationale:

NameTypeRequiredDescription
titlestringYesThe title of the dialog.
messagestringYesThe message of the dialog.
buttonPositivestringYesThe text of the positive button.
buttonNegativestringNoThe text of the negative button.
buttonNeutralstringNoThe text of the neutral button.

requestMultiple()

requestMultiple(permissions);

Prompts the user to enable multiple permissions in the same dialog and returns an object with the permissions as keys and strings as values (see result strings above) indicating whether the user allowed or denied the request or does not want to be asked again.

Parameters:

NameTypeRequiredDescription
permissionsarrayYesArray of permissions to request.
Edit this page
Last updated on
- + diff --git a/docs/0.61/picker-item.html b/docs/0.61/picker-item.html index 2dfe2399338..53fa804164b 100644 --- a/docs/0.61/picker-item.html +++ b/docs/0.61/picker-item.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Picker.Item

Individual selectable item in a Picker.

Props

Reference

Props

label

Text to display for this item.

TypeRequired
stringYes

color

Color of this item's text.

TypeRequired
colorNo

testID

Used to locate the item in end-to-end tests.

TypeRequired
stringNo

value

The value to be passed to picker's onValueChange callback when this item is selected. Can be a string or an integer.

TypeRequiredPlatform
anyNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.61/picker-item/index.html b/docs/0.61/picker-item/index.html index 2dfe2399338..53fa804164b 100644 --- a/docs/0.61/picker-item/index.html +++ b/docs/0.61/picker-item/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Picker.Item

Individual selectable item in a Picker.

Props

Reference

Props

label

Text to display for this item.

TypeRequired
stringYes

color

Color of this item's text.

TypeRequired
colorNo

testID

Used to locate the item in end-to-end tests.

TypeRequired
stringNo

value

The value to be passed to picker's onValueChange callback when this item is selected. Can be a string or an integer.

TypeRequiredPlatform
anyNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.61/picker-style-props.html b/docs/0.61/picker-style-props.html index 7001442d466..5b3a64d1108 100644 --- a/docs/0.61/picker-style-props.html +++ b/docs/0.61/picker-style-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.61/picker-style-props/index.html b/docs/0.61/picker-style-props/index.html index 7001442d466..5b3a64d1108 100644 --- a/docs/0.61/picker-style-props/index.html +++ b/docs/0.61/picker-style-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.61/picker.html b/docs/0.61/picker.html index 27048fccdb2..35deb5b0a67 100644 --- a/docs/0.61/picker.html +++ b/docs/0.61/picker.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Picker

Renders the native picker component on Android and iOS. Example:

<Picker
selectedValue={this.state.language}
style={{ height: 50, width: 100 }}
onValueChange={(itemValue, itemIndex) =>
this.setState({ language: itemValue })
}>
<Picker.Item label="Java" value="java" />
<Picker.Item label="JavaScript" value="js" />
</Picker>

Reference

Props

Inherits View Props.

onValueChange

Callback for when an item is selected. This is called with the following parameters:

  • itemValue: the value prop of the item that was selected
  • itemPosition: the index of the selected item in this picker
TypeRequired
functionNo

selectedValue

Value matching value of one of the items. Can be a string or an integer.

TypeRequired
anyNo

style

TypeRequired
pickerStyleTypeNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

enabled

If set to false, the picker will be disabled, i.e. the user will not be able to make a selection.

TypeRequiredPlatform
boolNoAndroid

mode

On Android, specifies how to display the selection items when the user taps on the picker:

  • 'dialog': Show a modal dialog. This is the default.
  • 'dropdown': Shows a dropdown anchored to the picker view
TypeRequiredPlatform
enum('dialog', 'dropdown')NoAndroid

prompt

Prompt string for this picker, used on Android in dialog mode as the title of the dialog.

TypeRequiredPlatform
stringNoAndroid

itemStyle

Style to apply to each of the item labels.

TypeRequiredPlatform
text stylesNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.61/picker/index.html b/docs/0.61/picker/index.html index 27048fccdb2..35deb5b0a67 100644 --- a/docs/0.61/picker/index.html +++ b/docs/0.61/picker/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Picker

Renders the native picker component on Android and iOS. Example:

<Picker
selectedValue={this.state.language}
style={{ height: 50, width: 100 }}
onValueChange={(itemValue, itemIndex) =>
this.setState({ language: itemValue })
}>
<Picker.Item label="Java" value="java" />
<Picker.Item label="JavaScript" value="js" />
</Picker>

Reference

Props

Inherits View Props.

onValueChange

Callback for when an item is selected. This is called with the following parameters:

  • itemValue: the value prop of the item that was selected
  • itemPosition: the index of the selected item in this picker
TypeRequired
functionNo

selectedValue

Value matching value of one of the items. Can be a string or an integer.

TypeRequired
anyNo

style

TypeRequired
pickerStyleTypeNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

enabled

If set to false, the picker will be disabled, i.e. the user will not be able to make a selection.

TypeRequiredPlatform
boolNoAndroid

mode

On Android, specifies how to display the selection items when the user taps on the picker:

  • 'dialog': Show a modal dialog. This is the default.
  • 'dropdown': Shows a dropdown anchored to the picker view
TypeRequiredPlatform
enum('dialog', 'dropdown')NoAndroid

prompt

Prompt string for this picker, used on Android in dialog mode as the title of the dialog.

TypeRequiredPlatform
stringNoAndroid

itemStyle

Style to apply to each of the item labels.

TypeRequiredPlatform
text stylesNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.61/pickerios.html b/docs/0.61/pickerios.html index 59bad4bcbc6..50b728c54e7 100644 --- a/docs/0.61/pickerios.html +++ b/docs/0.61/pickerios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.61/pickerios/index.html b/docs/0.61/pickerios/index.html index 59bad4bcbc6..50b728c54e7 100644 --- a/docs/0.61/pickerios/index.html +++ b/docs/0.61/pickerios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.61/pixelratio.html b/docs/0.61/pixelratio.html index aebc1cb3bac..8dd3f9460d9 100644 --- a/docs/0.61/pixelratio.html +++ b/docs/0.61/pixelratio.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

PixelRatio

PixelRatio class gives access to the device pixel density.

Fetching a correctly sized image

You should get a higher resolution image if you are on a high pixel density device. A good rule of thumb is to multiply the size of the image you display by the pixel ratio.

var image = getImage({
width: PixelRatio.getPixelSizeForLayoutSize(200),
height: PixelRatio.getPixelSizeForLayoutSize(100)
});
<Image source={image} style={{ width: 200, height: 100 }} />;

Pixel grid snapping

In iOS, you can specify positions and dimensions for elements with arbitrary precision, for example 29.674825. But, ultimately the physical display only have a fixed number of pixels, for example 640×960 for iPhone 4 or 750×1334 for iPhone 6. iOS tries to be as faithful as possible to the user value by spreading one original pixel into multiple ones to trick the eye. The downside of this technique is that it makes the resulting element look blurry.

In practice, we found out that developers do not want this feature and they have to work around it by doing manual rounding in order to avoid having blurry elements. In React Native, we are rounding all the pixels automatically.

We have to be careful when to do this rounding. You never want to work with rounded and unrounded values at the same time as you're going to accumulate rounding errors. Having even one rounding error is deadly because a one pixel border may vanish or be twice as big.

In React Native, everything in JavaScript and within the layout engine works with arbitrary precision numbers. It's only when we set the position and dimensions of the native element on the main thread that we round. Also, rounding is done relative to the root rather than the parent, again to avoid accumulating rounding errors.

Reference

Methods

get()

static get()

Returns the device pixel density. Some examples:

getFontScale()

static getFontScale()

Returns the scaling factor for font sizes. This is the ratio that is used to calculate the absolute font size, so any elements that heavily depend on that should use this to do calculations.

If a font scale is not set, this returns the device pixel ratio.

Currently this is only implemented on Android and reflects the user preference set in Settings > Display > Font size, on iOS it will always return the default pixel ratio. @platform android

getPixelSizeForLayoutSize()

static getPixelSizeForLayoutSize(layoutSize)

Converts a layout size (dp) to pixel size (px).

Guaranteed to return an integer number.

roundToNearestPixel()

static roundToNearestPixel(layoutSize)

Rounds a layout size (dp) to the nearest layout size that corresponds to an integer number of pixels. For example, on a device with a PixelRatio of 3, PixelRatio.roundToNearestPixel(8.4) = 8.33, which corresponds to exactly (8.33 * 3) = 25 pixels.

Edit this page
Last updated on
- + diff --git a/docs/0.61/pixelratio/index.html b/docs/0.61/pixelratio/index.html index aebc1cb3bac..8dd3f9460d9 100644 --- a/docs/0.61/pixelratio/index.html +++ b/docs/0.61/pixelratio/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

PixelRatio

PixelRatio class gives access to the device pixel density.

Fetching a correctly sized image

You should get a higher resolution image if you are on a high pixel density device. A good rule of thumb is to multiply the size of the image you display by the pixel ratio.

var image = getImage({
width: PixelRatio.getPixelSizeForLayoutSize(200),
height: PixelRatio.getPixelSizeForLayoutSize(100)
});
<Image source={image} style={{ width: 200, height: 100 }} />;

Pixel grid snapping

In iOS, you can specify positions and dimensions for elements with arbitrary precision, for example 29.674825. But, ultimately the physical display only have a fixed number of pixels, for example 640×960 for iPhone 4 or 750×1334 for iPhone 6. iOS tries to be as faithful as possible to the user value by spreading one original pixel into multiple ones to trick the eye. The downside of this technique is that it makes the resulting element look blurry.

In practice, we found out that developers do not want this feature and they have to work around it by doing manual rounding in order to avoid having blurry elements. In React Native, we are rounding all the pixels automatically.

We have to be careful when to do this rounding. You never want to work with rounded and unrounded values at the same time as you're going to accumulate rounding errors. Having even one rounding error is deadly because a one pixel border may vanish or be twice as big.

In React Native, everything in JavaScript and within the layout engine works with arbitrary precision numbers. It's only when we set the position and dimensions of the native element on the main thread that we round. Also, rounding is done relative to the root rather than the parent, again to avoid accumulating rounding errors.

Reference

Methods

get()

static get()

Returns the device pixel density. Some examples:

getFontScale()

static getFontScale()

Returns the scaling factor for font sizes. This is the ratio that is used to calculate the absolute font size, so any elements that heavily depend on that should use this to do calculations.

If a font scale is not set, this returns the device pixel ratio.

Currently this is only implemented on Android and reflects the user preference set in Settings > Display > Font size, on iOS it will always return the default pixel ratio. @platform android

getPixelSizeForLayoutSize()

static getPixelSizeForLayoutSize(layoutSize)

Converts a layout size (dp) to pixel size (px).

Guaranteed to return an integer number.

roundToNearestPixel()

static roundToNearestPixel(layoutSize)

Rounds a layout size (dp) to the nearest layout size that corresponds to an integer number of pixels. For example, on a device with a PixelRatio of 3, PixelRatio.roundToNearestPixel(8.4) = 8.33, which corresponds to exactly (8.33 * 3) = 25 pixels.

Edit this page
Last updated on
- + diff --git a/docs/0.61/platform-specific-code.html b/docs/0.61/platform-specific-code.html index 3103d2570cd..866d40fe0c5 100644 --- a/docs/0.61/platform-specific-code.html +++ b/docs/0.61/platform-specific-code.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
const majorVersionIOS = parseInt(Platform.Version, 10);
if (majorVersionIOS <= 9) {
console.log('Work around a change in behavior');
}

Platform-specific extensions

When your platform-specific code is more complex, you should consider splitting the code out into separate files. React Native will detect when a file has a .ios. or .android. extension and load the relevant platform file when required from other components.

For example, say you have the following files in your project:

BigButton.ios.js
BigButton.android.js

You can then require the component as follows:

import BigButton from './BigButton';

React Native will automatically pick up the right file based on the running platform.

Native-specific extensions (i.e. sharing code with NodeJS and Web)

You can also use the .native.js extension when a module needs to be shared between NodeJS/Web and React Native but it has no Android/iOS differences. This is specially useful for projects that has common code shared among React Native and ReactJS.

For example, say you have the following files in your project:

Container.js # picked up by Webpack, Rollup or any other Web bundler
Container.native.js # picked up by the React Native bundler for both Android and iOS (Metro)

You can still require it without the .native extension, as follows:

import Container from './Container';

Pro tip: Configure your Web bundler to ignore .native.js extensions in order to avoid having unused code in your production bundle, thus reducing the final bundle size.

Edit this page
Last updated on
- + diff --git a/docs/0.61/platform-specific-code/index.html b/docs/0.61/platform-specific-code/index.html index 3103d2570cd..866d40fe0c5 100644 --- a/docs/0.61/platform-specific-code/index.html +++ b/docs/0.61/platform-specific-code/index.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
const majorVersionIOS = parseInt(Platform.Version, 10);
if (majorVersionIOS <= 9) {
console.log('Work around a change in behavior');
}

Platform-specific extensions

When your platform-specific code is more complex, you should consider splitting the code out into separate files. React Native will detect when a file has a .ios. or .android. extension and load the relevant platform file when required from other components.

For example, say you have the following files in your project:

BigButton.ios.js
BigButton.android.js

You can then require the component as follows:

import BigButton from './BigButton';

React Native will automatically pick up the right file based on the running platform.

Native-specific extensions (i.e. sharing code with NodeJS and Web)

You can also use the .native.js extension when a module needs to be shared between NodeJS/Web and React Native but it has no Android/iOS differences. This is specially useful for projects that has common code shared among React Native and ReactJS.

For example, say you have the following files in your project:

Container.js # picked up by Webpack, Rollup or any other Web bundler
Container.native.js # picked up by the React Native bundler for both Android and iOS (Metro)

You can still require it without the .native extension, as follows:

import Container from './Container';

Pro tip: Configure your Web bundler to ignore .native.js extensions in order to avoid having unused code in your production bundle, thus reducing the final bundle size.

Edit this page
Last updated on
- + diff --git a/docs/0.61/profiling.html b/docs/0.61/profiling.html index 9a3312da508..8339acacf31 100644 --- a/docs/0.61/profiling.html +++ b/docs/0.61/profiling.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Profiling

Use the built-in profiler to get detailed information about work done in the JavaScript thread and main thread side-by-side. Access it by selecting Perf Monitor from the Debug menu.

For iOS, Instruments is an invaluable tool, and on Android you should learn to use systrace.

But first, make sure that Development Mode is OFF! You should see __DEV__ === false, development-level warning are OFF, performance optimizations are ON in your application logs.

Another way to profile JavaScript is to use the Chrome profiler while debugging. This won't give you accurate results as the code is running in Chrome but will give you a general idea of where bottlenecks might be. Run the profiler under Chrome's Performance tab. A flame graph will appear under User Timing. To view more details in tabular format, click at the Bottom Up tab below and then select DedicatedWorker Thread at the top left menu.

Profiling Android UI Performance with systrace

Android supports 10k+ different phones and is generalized to support software rendering: the framework architecture and need to generalize across many hardware targets unfortunately means you get less for free relative to iOS. But sometimes, there are things you can improve -- and many times it's not native code's fault at all!

The first step for debugging this jank is to answer the fundamental question of where your time is being spent during each 16ms frame. For that, we'll be using a standard Android profiling tool called systrace.

systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.

1. Collecting a trace

First, connect a device that exhibits the stuttering you want to investigate to your computer via USB and get it to the point right before the navigation/animation you want to profile. Run systrace as follows:

$ <path_to_android_sdk>/platform-tools/systrace/systrace.py --time=10 -o trace.html sched gfx view -a <your_package_name>

A quick breakdown of this command:

  • time is the length of time the trace will be collected in seconds
  • sched, gfx, and view are the android SDK tags (collections of markers) we care about: sched gives you information about what's running on each core of your phone, gfx gives you graphics info such as frame boundaries, and view gives you information about measure, layout, and draw passes
  • -a <your_package_name> enables app-specific markers, specifically the ones built into the React Native framework. your_package_name can be found in the AndroidManifest.xml of your app and looks like com.example.app

Once the trace starts collecting, perform the animation or interaction you care about. At the end of the trace, systrace will give you a link to the trace which you can open in your browser.

2. Reading the trace

After opening the trace in your browser (preferably Chrome), you should see something like this:

Example

HINT: Use the WASD keys to strafe and zoom

If your trace .html file isn't opening correctly, check your browser console for the following:

ObjectObserveError

Since Object.observe was deprecated in recent browsers, you may have to open the file from the Google Chrome Tracing tool. You can do so by:

  • Opening tab in chrome chrome://tracing
  • Selecting load
  • Selecting the html file generated from the previous command.

Enable VSync highlighting

Check this checkbox at the top right of the screen to highlight the 16ms frame boundaries:

Enable VSync Highlighting

You should see zebra stripes as in the screenshot above. If you don't, try profiling on a different device: Samsung has been known to have issues displaying vsyncs while the Nexus series is generally pretty reliable.

3. Find your process

Scroll until you see (part of) the name of your package. In this case, I was profiling com.facebook.adsmanager, which shows up as book.adsmanager because of silly thread name limits in the kernel.

On the left side, you'll see a set of threads which correspond to the timeline rows on the right. There are a few threads we care about for our purposes: the UI thread (which has your package name or the name UI Thread), mqt_js, and mqt_native_modules. If you're running on Android 5+, we also care about the Render Thread.

  • UI Thread. This is where standard android measure/layout/draw happens. The thread name on the right will be your package name (in my case book.adsmanager) or UI Thread. The events that you see on this thread should look something like this and have to do with Choreographer, traversals, and DispatchUI:

    UI Thread Example

  • JS Thread. This is where JavaScript is executed. The thread name will be either mqt_js or <...> depending on how cooperative the kernel on your device is being. To identify it if it doesn't have a name, look for things like JSCall, Bridge.executeJSCall, etc:

    JS Thread Example

  • Native Modules Thread. This is where native module calls (e.g. the UIManager) are executed. The thread name will be either mqt_native_modules or <...>. To identify it in the latter case, look for things like NativeCall, callJavaModuleMethod, and onBatchComplete:

    Native Modules Thread Example

  • Bonus: Render Thread. If you're using Android L (5.0) and up, you will also have a render thread in your application. This thread generates the actual OpenGL commands used to draw your UI. The thread name will be either RenderThread or <...>. To identify it in the latter case, look for things like DrawFrame and queueBuffer:

    Render Thread Example

Identifying a culprit

A smooth animation should look something like the following:

Smooth Animation

Each change in color is a frame -- remember that in order to display a frame, all our UI work needs to be done by the end of that 16ms period. Notice that no thread is working close to the frame boundary. An application rendering like this is rendering at 60 FPS.

If you noticed chop, however, you might see something like this:

Choppy Animation from JS

Notice that the JS thread is executing almost all the time, and across frame boundaries! This app is not rendering at 60 FPS. In this case, the problem lies in JS.

You might also see something like this:

Choppy Animation from UI

In this case, the UI and render threads are the ones that have work crossing frame boundaries. The UI that we're trying to render on each frame is requiring too much work to be done. In this case, the problem lies in the native views being rendered.

At this point, you'll have some very helpful information to inform your next steps.

Resolving JavaScript issues

If you identified a JS problem, look for clues in the specific JS that you're executing. In the scenario above, we see RCTEventEmitter being called multiple times per frame. Here's a zoom-in of the JS thread from the trace above:

Too much JS

This doesn't seem right. Why is it being called so often? Are they actually different events? The answers to these questions will probably depend on your product code. And many times, you'll want to look into shouldComponentUpdate.

Resolving native UI Issues

If you identified a native UI problem, there are usually two scenarios:

  1. the UI you're trying to draw each frame involves too much work on the GPU, or
  2. You're constructing new UI during the animation/interaction (e.g. loading in new content during a scroll).

Too much GPU work

In the first scenario, you'll see a trace that has the UI thread and/or Render Thread looking like this:

Overloaded GPU

Notice the long amount of time spent in DrawFrame that crosses frame boundaries. This is time spent waiting for the GPU to drain its command buffer from the previous frame.

To mitigate this, you should:

  • investigate using renderToHardwareTextureAndroid for complex, static content that is being animated/transformed (e.g. the Navigator slide/alpha animations)
  • make sure that you are not using needsOffscreenAlphaCompositing, which is disabled by default, as it greatly increases the per-frame load on the GPU in most cases.

If these don't help and you want to dig deeper into what the GPU is actually doing, you can check out Tracer for OpenGL ES.

Creating new views on the UI thread

In the second scenario, you'll see something more like this:

Creating Views

Notice that first the JS thread thinks for a bit, then you see some work done on the native modules thread, followed by an expensive traversal on the UI thread.

There isn't a quick way to mitigate this unless you're able to postpone creating new UI until after the interaction, or you are able to simplify the UI you're creating. The react native team is working on an infrastructure level solution for this that will allow new UI to be created and configured off the main thread, allowing the interaction to continue smoothly.

Edit this page
Last updated on
- + diff --git a/docs/0.61/profiling/index.html b/docs/0.61/profiling/index.html index 9a3312da508..8339acacf31 100644 --- a/docs/0.61/profiling/index.html +++ b/docs/0.61/profiling/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Profiling

Use the built-in profiler to get detailed information about work done in the JavaScript thread and main thread side-by-side. Access it by selecting Perf Monitor from the Debug menu.

For iOS, Instruments is an invaluable tool, and on Android you should learn to use systrace.

But first, make sure that Development Mode is OFF! You should see __DEV__ === false, development-level warning are OFF, performance optimizations are ON in your application logs.

Another way to profile JavaScript is to use the Chrome profiler while debugging. This won't give you accurate results as the code is running in Chrome but will give you a general idea of where bottlenecks might be. Run the profiler under Chrome's Performance tab. A flame graph will appear under User Timing. To view more details in tabular format, click at the Bottom Up tab below and then select DedicatedWorker Thread at the top left menu.

Profiling Android UI Performance with systrace

Android supports 10k+ different phones and is generalized to support software rendering: the framework architecture and need to generalize across many hardware targets unfortunately means you get less for free relative to iOS. But sometimes, there are things you can improve -- and many times it's not native code's fault at all!

The first step for debugging this jank is to answer the fundamental question of where your time is being spent during each 16ms frame. For that, we'll be using a standard Android profiling tool called systrace.

systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.

1. Collecting a trace

First, connect a device that exhibits the stuttering you want to investigate to your computer via USB and get it to the point right before the navigation/animation you want to profile. Run systrace as follows:

$ <path_to_android_sdk>/platform-tools/systrace/systrace.py --time=10 -o trace.html sched gfx view -a <your_package_name>

A quick breakdown of this command:

  • time is the length of time the trace will be collected in seconds
  • sched, gfx, and view are the android SDK tags (collections of markers) we care about: sched gives you information about what's running on each core of your phone, gfx gives you graphics info such as frame boundaries, and view gives you information about measure, layout, and draw passes
  • -a <your_package_name> enables app-specific markers, specifically the ones built into the React Native framework. your_package_name can be found in the AndroidManifest.xml of your app and looks like com.example.app

Once the trace starts collecting, perform the animation or interaction you care about. At the end of the trace, systrace will give you a link to the trace which you can open in your browser.

2. Reading the trace

After opening the trace in your browser (preferably Chrome), you should see something like this:

Example

HINT: Use the WASD keys to strafe and zoom

If your trace .html file isn't opening correctly, check your browser console for the following:

ObjectObserveError

Since Object.observe was deprecated in recent browsers, you may have to open the file from the Google Chrome Tracing tool. You can do so by:

  • Opening tab in chrome chrome://tracing
  • Selecting load
  • Selecting the html file generated from the previous command.

Enable VSync highlighting

Check this checkbox at the top right of the screen to highlight the 16ms frame boundaries:

Enable VSync Highlighting

You should see zebra stripes as in the screenshot above. If you don't, try profiling on a different device: Samsung has been known to have issues displaying vsyncs while the Nexus series is generally pretty reliable.

3. Find your process

Scroll until you see (part of) the name of your package. In this case, I was profiling com.facebook.adsmanager, which shows up as book.adsmanager because of silly thread name limits in the kernel.

On the left side, you'll see a set of threads which correspond to the timeline rows on the right. There are a few threads we care about for our purposes: the UI thread (which has your package name or the name UI Thread), mqt_js, and mqt_native_modules. If you're running on Android 5+, we also care about the Render Thread.

  • UI Thread. This is where standard android measure/layout/draw happens. The thread name on the right will be your package name (in my case book.adsmanager) or UI Thread. The events that you see on this thread should look something like this and have to do with Choreographer, traversals, and DispatchUI:

    UI Thread Example

  • JS Thread. This is where JavaScript is executed. The thread name will be either mqt_js or <...> depending on how cooperative the kernel on your device is being. To identify it if it doesn't have a name, look for things like JSCall, Bridge.executeJSCall, etc:

    JS Thread Example

  • Native Modules Thread. This is where native module calls (e.g. the UIManager) are executed. The thread name will be either mqt_native_modules or <...>. To identify it in the latter case, look for things like NativeCall, callJavaModuleMethod, and onBatchComplete:

    Native Modules Thread Example

  • Bonus: Render Thread. If you're using Android L (5.0) and up, you will also have a render thread in your application. This thread generates the actual OpenGL commands used to draw your UI. The thread name will be either RenderThread or <...>. To identify it in the latter case, look for things like DrawFrame and queueBuffer:

    Render Thread Example

Identifying a culprit

A smooth animation should look something like the following:

Smooth Animation

Each change in color is a frame -- remember that in order to display a frame, all our UI work needs to be done by the end of that 16ms period. Notice that no thread is working close to the frame boundary. An application rendering like this is rendering at 60 FPS.

If you noticed chop, however, you might see something like this:

Choppy Animation from JS

Notice that the JS thread is executing almost all the time, and across frame boundaries! This app is not rendering at 60 FPS. In this case, the problem lies in JS.

You might also see something like this:

Choppy Animation from UI

In this case, the UI and render threads are the ones that have work crossing frame boundaries. The UI that we're trying to render on each frame is requiring too much work to be done. In this case, the problem lies in the native views being rendered.

At this point, you'll have some very helpful information to inform your next steps.

Resolving JavaScript issues

If you identified a JS problem, look for clues in the specific JS that you're executing. In the scenario above, we see RCTEventEmitter being called multiple times per frame. Here's a zoom-in of the JS thread from the trace above:

Too much JS

This doesn't seem right. Why is it being called so often? Are they actually different events? The answers to these questions will probably depend on your product code. And many times, you'll want to look into shouldComponentUpdate.

Resolving native UI Issues

If you identified a native UI problem, there are usually two scenarios:

  1. the UI you're trying to draw each frame involves too much work on the GPU, or
  2. You're constructing new UI during the animation/interaction (e.g. loading in new content during a scroll).

Too much GPU work

In the first scenario, you'll see a trace that has the UI thread and/or Render Thread looking like this:

Overloaded GPU

Notice the long amount of time spent in DrawFrame that crosses frame boundaries. This is time spent waiting for the GPU to drain its command buffer from the previous frame.

To mitigate this, you should:

  • investigate using renderToHardwareTextureAndroid for complex, static content that is being animated/transformed (e.g. the Navigator slide/alpha animations)
  • make sure that you are not using needsOffscreenAlphaCompositing, which is disabled by default, as it greatly increases the per-frame load on the GPU in most cases.

If these don't help and you want to dig deeper into what the GPU is actually doing, you can check out Tracer for OpenGL ES.

Creating new views on the UI thread

In the second scenario, you'll see something more like this:

Creating Views

Notice that first the JS thread thinks for a bit, then you see some work done on the native modules thread, followed by an expensive traversal on the UI thread.

There isn't a quick way to mitigate this unless you're able to postpone creating new UI until after the interaction, or you are able to simplify the UI you're creating. The react native team is working on an infrastructure level solution for this that will allow new UI to be created and configured off the main thread, allowing the interaction to continue smoothly.

Edit this page
Last updated on
- + diff --git a/docs/0.61/progressbarandroid.html b/docs/0.61/progressbarandroid.html index e05acfe07c8..6a046a11838 100644 --- a/docs/0.61/progressbarandroid.html +++ b/docs/0.61/progressbarandroid.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'space-evenly',
padding: 10
}
});

Reference

Props

Inherits View Props.

animating

Whether to show the ProgressBar (true, the default) or hide it (false).

TypeRequired
boolNo

color

Color of the progress bar.

TypeRequired
colorNo

indeterminate

If the progress bar will show indeterminate progress. Note that this can only be false if styleAttr is Horizontal, and requires a progress value.

TypeRequired
indeterminateTypeNo

progress

The progress value (between 0 and 1).

TypeRequired
numberNo

styleAttr

Style of the ProgressBar. One of:

TypeRequired
enum('Horizontal', 'Normal', 'Small', 'Large', 'Inverse', 'SmallInverse', 'LargeInverse')No

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/progressbarandroid/index.html b/docs/0.61/progressbarandroid/index.html index e05acfe07c8..6a046a11838 100644 --- a/docs/0.61/progressbarandroid/index.html +++ b/docs/0.61/progressbarandroid/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'space-evenly',
padding: 10
}
});

Reference

Props

Inherits View Props.

animating

Whether to show the ProgressBar (true, the default) or hide it (false).

TypeRequired
boolNo

color

Color of the progress bar.

TypeRequired
colorNo

indeterminate

If the progress bar will show indeterminate progress. Note that this can only be false if styleAttr is Horizontal, and requires a progress value.

TypeRequired
indeterminateTypeNo

progress

The progress value (between 0 and 1).

TypeRequired
numberNo

styleAttr

Style of the ProgressBar. One of:

TypeRequired
enum('Horizontal', 'Normal', 'Small', 'Large', 'Inverse', 'SmallInverse', 'LargeInverse')No

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/progressviewios.html b/docs/0.61/progressviewios.html index c7d978a17c4..a6f5dc3c2ac 100644 --- a/docs/0.61/progressviewios.html +++ b/docs/0.61/progressviewios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 ProgressViewIOS

Deprecated. Use @react-native-community/progress-view instead.

Uses ProgressViewIOS to render a UIProgressView on iOS.

Reference

Props

Inherits View Props.

progress

The progress value (between 0 and 1).

TypeRequired
numberNo

progressImage

A stretchable image to display as the progress bar.

TypeRequired
Image.propTypes.sourceNo

progressTintColor

The tint color of the progress bar itself.

TypeRequired
stringNo

progressViewStyle

The progress bar style.

TypeRequired
enum('default', 'bar')No

trackImage

A stretchable image to display behind the progress bar.

TypeRequired
Image.propTypes.sourceNo

trackTintColor

The tint color of the progress bar track.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/progressviewios/index.html b/docs/0.61/progressviewios/index.html index c7d978a17c4..a6f5dc3c2ac 100644 --- a/docs/0.61/progressviewios/index.html +++ b/docs/0.61/progressviewios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 ProgressViewIOS

Deprecated. Use @react-native-community/progress-view instead.

Uses ProgressViewIOS to render a UIProgressView on iOS.

Reference

Props

Inherits View Props.

progress

The progress value (between 0 and 1).

TypeRequired
numberNo

progressImage

A stretchable image to display as the progress bar.

TypeRequired
Image.propTypes.sourceNo

progressTintColor

The tint color of the progress bar itself.

TypeRequired
stringNo

progressViewStyle

The progress bar style.

TypeRequired
enum('default', 'bar')No

trackImage

A stretchable image to display behind the progress bar.

TypeRequired
Image.propTypes.sourceNo

trackTintColor

The tint color of the progress bar track.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/props.html b/docs/0.61/props.html index 774840c3871..ba5e98c1281 100644 --- a/docs/0.61/props.html +++ b/docs/0.61/props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Props

Most components can be customized when they are created, with different parameters. These creation parameters are called props, short for properties.

For example, one basic React Native component is the Image. When you create an image, you can use a prop named source to control what image it shows.

Notice the braces surrounding {pic} - these embed the variable pic into JSX. You can put any JavaScript expression inside braces in JSX.

Your own components can also use props. This lets you make a single component that is used in many different places in your app, with slightly different properties in each place by referring to this.props in your render function. Here's an example:

Using name as a prop lets us customize the Greeting component, so we can reuse that component for each of our greetings. This example also uses the Greeting component in JSX, similar to the Core Components. The power to do this is what makes React so cool - if you find yourself wishing that you had a different set of UI primitives to work with, you can invent new ones.

The other new thing going on here is the View component. A View is useful as a container for other components, to help control style and layout.

With props and the basic Text, Image, and View components, you can build a wide variety of static screens. To learn how to make your app change over time, you need to learn about State.

Edit this page
Last updated on
- + diff --git a/docs/0.61/props/index.html b/docs/0.61/props/index.html index 774840c3871..ba5e98c1281 100644 --- a/docs/0.61/props/index.html +++ b/docs/0.61/props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Props

Most components can be customized when they are created, with different parameters. These creation parameters are called props, short for properties.

For example, one basic React Native component is the Image. When you create an image, you can use a prop named source to control what image it shows.

Notice the braces surrounding {pic} - these embed the variable pic into JSX. You can put any JavaScript expression inside braces in JSX.

Your own components can also use props. This lets you make a single component that is used in many different places in your app, with slightly different properties in each place by referring to this.props in your render function. Here's an example:

Using name as a prop lets us customize the Greeting component, so we can reuse that component for each of our greetings. This example also uses the Greeting component in JSX, similar to the Core Components. The power to do this is what makes React so cool - if you find yourself wishing that you had a different set of UI primitives to work with, you can invent new ones.

The other new thing going on here is the View component. A View is useful as a container for other components, to help control style and layout.

With props and the basic Text, Image, and View components, you can build a wide variety of static screens. To learn how to make your app change over time, you need to learn about State.

Edit this page
Last updated on
- + diff --git a/docs/0.61/publishing-forks.html b/docs/0.61/publishing-forks.html index 2ae799628f5..5e0d19ddc27 100644 --- a/docs/0.61/publishing-forks.html +++ b/docs/0.61/publishing-forks.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Publish your own version of react native

TL;DR

There is a docker image that helps you build the required Android sources without installing any additional tooling (other than Docker, which can be committed to a git branch as a fully functional React Native fork release.

Run this from a fork of the React Native repo.

git checkout -d release/my-react-native-release
docker run --rm --name rn-build -v $PWD:/pwd -w /pwd reactnativecommunity/react-native-android /bin/sh -c "./gradlew installArchives"
git add android --force
git commit -a -m 'my react native forked release'
git push

Install it in your app project package.json.

"dependencies": {
...
"react-native": "myName/react-native#release/my-react-native-release"
}

Rationale

The recommended approach to working with React Native is to always update to the latest version. No support is provided on older versions and if you run into issues the contributors will always ask you to upgrade to the latest version before even looking at your particular issue. Sometimes, though, you are temporarily stuck on an older React Native version, but you require some changes from newer versions urgently (bugfixes) without having to do a full upgrade right now. This situation should be short lived by definition and once you have the time, the real solution is to upgrade to the latest version.

With this goal of a shortlived fork of React Native in mind, you can publish your own version of React Native. The facebook/react-native repository contains all the dependencies required to be used directly as a git dependency, except for the Android React Native library binary (.aar).

Building

This binary needs to become available in your project's node_modules/react-native/android folder or directly in your gradle dependency of your Android app. You can achieve this in one of two ways: Git dependency branch, Android binary dependency through Maven.

To build the .aar React Native library, you can follow the steps to build from source first to install all required tooling. Then to build the actual library, you can run the following in the root of your react-native checkout:

./gradlew :ReactAndroid:installArchives --no-daemon

If you don't want to install the required toolchain for building from source, you can use a prebuilt docker image to create a react native binary;

docker run --rm --name rn-build -v $PWD:/pwd -w /pwd reactnativecommunity/react-native-android /bin/sh -c "./gradlew installArchives"

If you haven't used the Android NDK before or if you have a NDK version not exactly matching the required version for building React Native, this is the recommended approach.

The resulting binary can be made available to app projects in one of the two ways described below.

Publishing to Maven/Nexus

Upload the binaries from the android folder to maven and point your Android app project gradle dependency for React Native to your Maven/Nexus dependency.

Publishing to a git fork dependency

Instead of uploading to Maven/Nexus, you can add the binaries built in the previous steps to git, by changing the .gitignore and committing the binaries to your forked branch. This allows you to make your fork into a functioning git dependency for React Native app projects.

If you have changes that you want to actually merge to React Native, make them on another branch first and open a PR. To start making your dependency branch, make sure you are on a 'release/my-forked-release' branch, then merge any commits that you need from yourself or others into this branch. This release branch should never be merged into any other branch.

# create .aar, then:
git add android --force
git commit -m 'my release commit'
git push

Now you can use this branch as a git dependency in your app project, by pointing your package.json dependency to this branch:

"dependencies": {
...
"react-native": "my-name/react-native#release/my-forked-release,
...
}

No other modifications to your dependencies should be necessary for your native changes to be included in your project.

Edit this page
Last updated on
- + diff --git a/docs/0.61/publishing-forks/index.html b/docs/0.61/publishing-forks/index.html index 2ae799628f5..5e0d19ddc27 100644 --- a/docs/0.61/publishing-forks/index.html +++ b/docs/0.61/publishing-forks/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Publish your own version of react native

TL;DR

There is a docker image that helps you build the required Android sources without installing any additional tooling (other than Docker, which can be committed to a git branch as a fully functional React Native fork release.

Run this from a fork of the React Native repo.

git checkout -d release/my-react-native-release
docker run --rm --name rn-build -v $PWD:/pwd -w /pwd reactnativecommunity/react-native-android /bin/sh -c "./gradlew installArchives"
git add android --force
git commit -a -m 'my react native forked release'
git push

Install it in your app project package.json.

"dependencies": {
...
"react-native": "myName/react-native#release/my-react-native-release"
}

Rationale

The recommended approach to working with React Native is to always update to the latest version. No support is provided on older versions and if you run into issues the contributors will always ask you to upgrade to the latest version before even looking at your particular issue. Sometimes, though, you are temporarily stuck on an older React Native version, but you require some changes from newer versions urgently (bugfixes) without having to do a full upgrade right now. This situation should be short lived by definition and once you have the time, the real solution is to upgrade to the latest version.

With this goal of a shortlived fork of React Native in mind, you can publish your own version of React Native. The facebook/react-native repository contains all the dependencies required to be used directly as a git dependency, except for the Android React Native library binary (.aar).

Building

This binary needs to become available in your project's node_modules/react-native/android folder or directly in your gradle dependency of your Android app. You can achieve this in one of two ways: Git dependency branch, Android binary dependency through Maven.

To build the .aar React Native library, you can follow the steps to build from source first to install all required tooling. Then to build the actual library, you can run the following in the root of your react-native checkout:

./gradlew :ReactAndroid:installArchives --no-daemon

If you don't want to install the required toolchain for building from source, you can use a prebuilt docker image to create a react native binary;

docker run --rm --name rn-build -v $PWD:/pwd -w /pwd reactnativecommunity/react-native-android /bin/sh -c "./gradlew installArchives"

If you haven't used the Android NDK before or if you have a NDK version not exactly matching the required version for building React Native, this is the recommended approach.

The resulting binary can be made available to app projects in one of the two ways described below.

Publishing to Maven/Nexus

Upload the binaries from the android folder to maven and point your Android app project gradle dependency for React Native to your Maven/Nexus dependency.

Publishing to a git fork dependency

Instead of uploading to Maven/Nexus, you can add the binaries built in the previous steps to git, by changing the .gitignore and committing the binaries to your forked branch. This allows you to make your fork into a functioning git dependency for React Native app projects.

If you have changes that you want to actually merge to React Native, make them on another branch first and open a PR. To start making your dependency branch, make sure you are on a 'release/my-forked-release' branch, then merge any commits that you need from yourself or others into this branch. This release branch should never be merged into any other branch.

# create .aar, then:
git add android --force
git commit -m 'my release commit'
git push

Now you can use this branch as a git dependency in your app project, by pointing your package.json dependency to this branch:

"dependencies": {
...
"react-native": "my-name/react-native#release/my-forked-release,
...
}

No other modifications to your dependencies should be necessary for your native changes to be included in your project.

Edit this page
Last updated on
- + diff --git a/docs/0.61/publishing-to-app-store.html b/docs/0.61/publishing-to-app-store.html index 370f233ae9c..0c116455d9d 100644 --- a/docs/0.61/publishing-to-app-store.html +++ b/docs/0.61/publishing-to-app-store.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Publishing to Apple App Store

The publishing process is the same as any other native iOS app, with some additional considerations to take into account.

If you are using Expo then read the Expo Guide for Building Standalone Apps.

1. Enable App Transport Security

App Transport Security is a security feature introduced in iOS 9 that rejects all HTTP requests that are not sent over HTTPS. This can result in HTTP traffic being blocked, including the developer React Native server. ATS is disabled for localhost by default in React Native projects in order to make development easier.

You should re-enable ATS prior to building your app for production by removing the localhost entry from the NSExceptionDomains dictionary and setting NSAllowsArbitraryLoads to false in your Info.plist file in the ios/ folder. You can also re-enable ATS from within Xcode by opening your target properties under the Info pane and editing the App Transport Security Settings entry.

If your application needs to access HTTP resources on production, see this post to learn how to configure ATS on your project.

2. Configure release scheme

Building an app for distribution in the App Store requires using the Release scheme in Xcode. Apps built for Release will automatically disable the in-app Developer menu, which will prevent your users from inadvertently accessing the menu in production. It will also bundle the JavaScript locally, so you can put the app on a device and test whilst not connected to the computer.

To configure your app to be built using the Release scheme, go to Product → Scheme → Edit Scheme. Select the Run tab in the sidebar, then set the Build Configuration dropdown to Release.

Pro Tips

As your App Bundle grows in size, you may start to see a blank screen flash between your splash screen and the display of your root application view. If this is the case, you can add the following code to AppDelegate.m in order to keep your splash screen displayed during the transition.

// Place this code after "[self.window makeKeyAndVisible]" and before "return YES;"
UIStoryboard *sb = [UIStoryboard storyboardWithName:@"LaunchScreen" bundle:nil];
UIViewController *vc = [sb instantiateInitialViewController];
rootView.loadingView = vc.view;

The static bundle is built every time you target a physical device, even in Debug. If you want to save time, turn off bundle generation in Debug by adding the following to your shell script in the Xcode Build Phase Bundle React Native code and images:

if [ "${CONFIGURATION}" == "Debug" ]; then
export SKIP_BUNDLING=true
fi

3. Build app for release

You can now build your app for release by tapping ⌘B or selecting Product → Build from the menu bar. Once built for release, you'll be able to distribute the app to beta testers and submit the app to the App Store.

You can also use the React Native CLI to perform this operation using the option --configuration with the value Release (e.g. npx react-native run-ios --configuration Release).

Edit this page
Last updated on
- + diff --git a/docs/0.61/publishing-to-app-store/index.html b/docs/0.61/publishing-to-app-store/index.html index 370f233ae9c..0c116455d9d 100644 --- a/docs/0.61/publishing-to-app-store/index.html +++ b/docs/0.61/publishing-to-app-store/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Publishing to Apple App Store

The publishing process is the same as any other native iOS app, with some additional considerations to take into account.

If you are using Expo then read the Expo Guide for Building Standalone Apps.

1. Enable App Transport Security

App Transport Security is a security feature introduced in iOS 9 that rejects all HTTP requests that are not sent over HTTPS. This can result in HTTP traffic being blocked, including the developer React Native server. ATS is disabled for localhost by default in React Native projects in order to make development easier.

You should re-enable ATS prior to building your app for production by removing the localhost entry from the NSExceptionDomains dictionary and setting NSAllowsArbitraryLoads to false in your Info.plist file in the ios/ folder. You can also re-enable ATS from within Xcode by opening your target properties under the Info pane and editing the App Transport Security Settings entry.

If your application needs to access HTTP resources on production, see this post to learn how to configure ATS on your project.

2. Configure release scheme

Building an app for distribution in the App Store requires using the Release scheme in Xcode. Apps built for Release will automatically disable the in-app Developer menu, which will prevent your users from inadvertently accessing the menu in production. It will also bundle the JavaScript locally, so you can put the app on a device and test whilst not connected to the computer.

To configure your app to be built using the Release scheme, go to Product → Scheme → Edit Scheme. Select the Run tab in the sidebar, then set the Build Configuration dropdown to Release.

Pro Tips

As your App Bundle grows in size, you may start to see a blank screen flash between your splash screen and the display of your root application view. If this is the case, you can add the following code to AppDelegate.m in order to keep your splash screen displayed during the transition.

// Place this code after "[self.window makeKeyAndVisible]" and before "return YES;"
UIStoryboard *sb = [UIStoryboard storyboardWithName:@"LaunchScreen" bundle:nil];
UIViewController *vc = [sb instantiateInitialViewController];
rootView.loadingView = vc.view;

The static bundle is built every time you target a physical device, even in Debug. If you want to save time, turn off bundle generation in Debug by adding the following to your shell script in the Xcode Build Phase Bundle React Native code and images:

if [ "${CONFIGURATION}" == "Debug" ]; then
export SKIP_BUNDLING=true
fi

3. Build app for release

You can now build your app for release by tapping ⌘B or selecting Product → Build from the menu bar. Once built for release, you'll be able to distribute the app to beta testers and submit the app to the App Store.

You can also use the React Native CLI to perform this operation using the option --configuration with the value Release (e.g. npx react-native run-ios --configuration Release).

Edit this page
Last updated on
- + diff --git a/docs/0.61/pushnotificationios.html b/docs/0.61/pushnotificationios.html index 3587c27ae8c..68e436ccf8e 100644 --- a/docs/0.61/pushnotificationios.html +++ b/docs/0.61/pushnotificationios.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
//Called when a notification is delivered to a foreground app.
-(void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler
{
completionHandler(UNAuthorizationOptionSound | UNAuthorizationOptionAlert | UNAuthorizationOptionBadge);
}

Then enable Background Modes/Remote notifications to be able to use remote notifications properly. The easiest way to do this is via the project settings. Navigate to Targets -> Your App -> Capabilities -> Background Modes and check Remote notifications. This will automatically enable the required settings.

Reference

Methods

presentLocalNotification()

PushNotificationIOS.presentLocalNotification(details);

Schedules the localNotification for immediate presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

scheduleLocalNotification()

PushNotificationIOS.scheduleLocalNotification(details);

Schedules the localNotification for future presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

cancelAllLocalNotifications()

PushNotificationIOS.cancelAllLocalNotifications();

Cancels all scheduled localNotifications

removeAllDeliveredNotifications()

PushNotificationIOS.removeAllDeliveredNotifications();

Remove all delivered notifications from Notification Center

getDeliveredNotifications()

PushNotificationIOS.getDeliveredNotifications(callback);

Provides you with a list of the app’s notifications that are still displayed in Notification Center

Parameters:

NameTypeRequiredDescription
callbackfunctionYesFunction which receive an array of delivered notifications.

A delivered notification is an object containing:

removeDeliveredNotifications()

PushNotificationIOS.removeDeliveredNotifications(identifiers);

Removes the specified notifications from Notification Center

Parameters:

NameTypeRequiredDescription
identifiersarrayYesArray of notification identifiers.

setApplicationIconBadgeNumber()

PushNotificationIOS.setApplicationIconBadgeNumber(number);

Sets the badge number for the app icon on the home screen

Parameters:

NameTypeRequiredDescription
numbernumberYesBadge number for the app icon.

getApplicationIconBadgeNumber()

PushNotificationIOS.getApplicationIconBadgeNumber(callback);

Gets the current badge number for the app icon on the home screen

Parameters:

NameTypeRequiredDescription
callbackfunctionYesA function that will be passed the current badge number.

cancelLocalNotifications()

PushNotificationIOS.cancelLocalNotifications(userInfo);

Cancel local notifications.

Optionally restricts the set of canceled notifications to those notifications whose userInfo fields match the corresponding fields in the userInfo argument.

Parameters:

NameTypeRequiredDescription
userInfoobjectNo

getScheduledLocalNotifications()

PushNotificationIOS.getScheduledLocalNotifications(callback);

Gets the local notifications that are currently scheduled.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesA function that will be passed an array of objects describing local notifications.

addEventListener()

PushNotificationIOS.addEventListener(type, handler);

Attaches a listener to remote or local notification events while the app is running in the foreground or the background.

Parameters:

NameTypeRequiredDescription
typestringYesEvent type.
handlerfunctionYesListener.

Valid events are:

removeEventListener()

PushNotificationIOS.removeEventListener(type, handler);

Removes the event listener. Do this in componentWillUnmount to prevent memory leaks

Parameters:

NameTypeRequiredDescription
typestringYesEvent type.
handlerfunctionYesListener.

requestPermissions()

PushNotificationIOS.requestPermissions([permissions]);

Requests notification permissions from iOS, prompting the user's dialog box. By default, it will request all notification permissions, but a subset of these can be requested by passing a map of requested permissions. The following permissions are supported:

If a map is provided to the method, only the permissions with truthy values will be requested.

This method returns a promise that will resolve when the user accepts, rejects, or if the permissions were previously rejected. The promise resolves to the current state of the permission.

Parameters:

NameTypeRequiredDescription
permissionsarrayNoalert, badge, or sound

abandonPermissions()

PushNotificationIOS.abandonPermissions();

Unregister for all remote notifications received via Apple Push Notification service.

You should call this method in rare circumstances only, such as when a new version of the app removes support for all types of remote notifications. Users can temporarily prevent apps from receiving remote notifications through the Notifications section of the Settings app. Apps unregistered through this method can always re-register.

checkPermissions()

PushNotificationIOS.checkPermissions(callback);

See what push permissions are currently enabled.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesSee below.

callback will be invoked with a permissions object:

getInitialNotification()

PushNotificationIOS.getInitialNotification();

This method returns a promise. If the app was launched by a push notification, this promise resolves to an object of type PushNotificationIOS. Otherwise, it resolves to null.

constructor()

constructor(nativeNotif);

You will never need to instantiate PushNotificationIOS yourself. Listening to the notification event and invoking getInitialNotification is sufficient.

finish()

finish(fetchResult);

This method is available for remote notifications that have been received via: application:didReceiveRemoteNotification:fetchCompletionHandler: https://developer.apple.com/library/ios/documentation/UIKit/Reference/UIApplicationDelegate_Protocol/#//apple_ref/occ/intfm/UIApplicationDelegate/application:didReceiveRemoteNotification:fetchCompletionHandler:

Call this to execute when the remote notification handling is complete. When calling this block, pass in the fetch result value that best describes the results of your operation. You must call this handler and should do so as soon as possible. For a list of possible values, see PushNotificationIOS.FetchResult.

If you do not call this method your background remote notifications could be throttled, to read more about it see the above documentation link.

getMessage()

getMessage();

An alias for getAlert to get the notification's main message string

getSound()

getSound();

Gets the sound string from the aps object

getCategory()

getCategory();

Gets the category string from the aps object

getAlert()

getAlert();

Gets the notification's main message from the aps object

getContentAvailable()

getContentAvailable();

Gets the content-available number from the aps object

getBadgeCount()

getBadgeCount();

Gets the badge count number from the aps object

getData()

getData();

Gets the data object on the notification

getThreadID()

getThreadID();

Gets the thread ID on the notification

Edit this page
Last updated on
- + diff --git a/docs/0.61/pushnotificationios/index.html b/docs/0.61/pushnotificationios/index.html index 3587c27ae8c..68e436ccf8e 100644 --- a/docs/0.61/pushnotificationios/index.html +++ b/docs/0.61/pushnotificationios/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
//Called when a notification is delivered to a foreground app.
-(void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler
{
completionHandler(UNAuthorizationOptionSound | UNAuthorizationOptionAlert | UNAuthorizationOptionBadge);
}

Then enable Background Modes/Remote notifications to be able to use remote notifications properly. The easiest way to do this is via the project settings. Navigate to Targets -> Your App -> Capabilities -> Background Modes and check Remote notifications. This will automatically enable the required settings.

Reference

Methods

presentLocalNotification()

PushNotificationIOS.presentLocalNotification(details);

Schedules the localNotification for immediate presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

scheduleLocalNotification()

PushNotificationIOS.scheduleLocalNotification(details);

Schedules the localNotification for future presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

cancelAllLocalNotifications()

PushNotificationIOS.cancelAllLocalNotifications();

Cancels all scheduled localNotifications

removeAllDeliveredNotifications()

PushNotificationIOS.removeAllDeliveredNotifications();

Remove all delivered notifications from Notification Center

getDeliveredNotifications()

PushNotificationIOS.getDeliveredNotifications(callback);

Provides you with a list of the app’s notifications that are still displayed in Notification Center

Parameters:

NameTypeRequiredDescription
callbackfunctionYesFunction which receive an array of delivered notifications.

A delivered notification is an object containing:

removeDeliveredNotifications()

PushNotificationIOS.removeDeliveredNotifications(identifiers);

Removes the specified notifications from Notification Center

Parameters:

NameTypeRequiredDescription
identifiersarrayYesArray of notification identifiers.

setApplicationIconBadgeNumber()

PushNotificationIOS.setApplicationIconBadgeNumber(number);

Sets the badge number for the app icon on the home screen

Parameters:

NameTypeRequiredDescription
numbernumberYesBadge number for the app icon.

getApplicationIconBadgeNumber()

PushNotificationIOS.getApplicationIconBadgeNumber(callback);

Gets the current badge number for the app icon on the home screen

Parameters:

NameTypeRequiredDescription
callbackfunctionYesA function that will be passed the current badge number.

cancelLocalNotifications()

PushNotificationIOS.cancelLocalNotifications(userInfo);

Cancel local notifications.

Optionally restricts the set of canceled notifications to those notifications whose userInfo fields match the corresponding fields in the userInfo argument.

Parameters:

NameTypeRequiredDescription
userInfoobjectNo

getScheduledLocalNotifications()

PushNotificationIOS.getScheduledLocalNotifications(callback);

Gets the local notifications that are currently scheduled.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesA function that will be passed an array of objects describing local notifications.

addEventListener()

PushNotificationIOS.addEventListener(type, handler);

Attaches a listener to remote or local notification events while the app is running in the foreground or the background.

Parameters:

NameTypeRequiredDescription
typestringYesEvent type.
handlerfunctionYesListener.

Valid events are:

removeEventListener()

PushNotificationIOS.removeEventListener(type, handler);

Removes the event listener. Do this in componentWillUnmount to prevent memory leaks

Parameters:

NameTypeRequiredDescription
typestringYesEvent type.
handlerfunctionYesListener.

requestPermissions()

PushNotificationIOS.requestPermissions([permissions]);

Requests notification permissions from iOS, prompting the user's dialog box. By default, it will request all notification permissions, but a subset of these can be requested by passing a map of requested permissions. The following permissions are supported:

If a map is provided to the method, only the permissions with truthy values will be requested.

This method returns a promise that will resolve when the user accepts, rejects, or if the permissions were previously rejected. The promise resolves to the current state of the permission.

Parameters:

NameTypeRequiredDescription
permissionsarrayNoalert, badge, or sound

abandonPermissions()

PushNotificationIOS.abandonPermissions();

Unregister for all remote notifications received via Apple Push Notification service.

You should call this method in rare circumstances only, such as when a new version of the app removes support for all types of remote notifications. Users can temporarily prevent apps from receiving remote notifications through the Notifications section of the Settings app. Apps unregistered through this method can always re-register.

checkPermissions()

PushNotificationIOS.checkPermissions(callback);

See what push permissions are currently enabled.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesSee below.

callback will be invoked with a permissions object:

getInitialNotification()

PushNotificationIOS.getInitialNotification();

This method returns a promise. If the app was launched by a push notification, this promise resolves to an object of type PushNotificationIOS. Otherwise, it resolves to null.

constructor()

constructor(nativeNotif);

You will never need to instantiate PushNotificationIOS yourself. Listening to the notification event and invoking getInitialNotification is sufficient.

finish()

finish(fetchResult);

This method is available for remote notifications that have been received via: application:didReceiveRemoteNotification:fetchCompletionHandler: https://developer.apple.com/library/ios/documentation/UIKit/Reference/UIApplicationDelegate_Protocol/#//apple_ref/occ/intfm/UIApplicationDelegate/application:didReceiveRemoteNotification:fetchCompletionHandler:

Call this to execute when the remote notification handling is complete. When calling this block, pass in the fetch result value that best describes the results of your operation. You must call this handler and should do so as soon as possible. For a list of possible values, see PushNotificationIOS.FetchResult.

If you do not call this method your background remote notifications could be throttled, to read more about it see the above documentation link.

getMessage()

getMessage();

An alias for getAlert to get the notification's main message string

getSound()

getSound();

Gets the sound string from the aps object

getCategory()

getCategory();

Gets the category string from the aps object

getAlert()

getAlert();

Gets the notification's main message from the aps object

getContentAvailable()

getContentAvailable();

Gets the content-available number from the aps object

getBadgeCount()

getBadgeCount();

Gets the badge count number from the aps object

getData()

getData();

Gets the data object on the notification

getThreadID()

getThreadID();

Gets the thread ID on the notification

Edit this page
Last updated on
- + diff --git a/docs/0.61/ram-bundles-inline-requires.html b/docs/0.61/ram-bundles-inline-requires.html index b77d9fb9092..3d2153c758e 100644 --- a/docs/0.61/ram-bundles-inline-requires.html +++ b/docs/0.61/ram-bundles-inline-requires.html @@ -19,7 +19,7 @@ - + @@ -45,7 +45,7 @@
module.exports = config;

The preloadedModules entry in the config indicates which modules should be marked as preloaded when building a RAM bundle. When the bundle is loaded, those modules are immediately loaded, before any requires have even executed. The blacklist entry indicates that those modules should not be required inline. Because they are preloaded, there is no performance benefit from using an inline require. In fact the javascript spends extra time resolving the inline require every time the imports are referenced.

Test and Measure Improvements

You should now be ready to build your app using the RAM format and inline requires. Make sure you measure the before and after startup times.

Edit this page
Last updated on
- + diff --git a/docs/0.61/ram-bundles-inline-requires/index.html b/docs/0.61/ram-bundles-inline-requires/index.html index b77d9fb9092..3d2153c758e 100644 --- a/docs/0.61/ram-bundles-inline-requires/index.html +++ b/docs/0.61/ram-bundles-inline-requires/index.html @@ -19,7 +19,7 @@ - + @@ -45,7 +45,7 @@
module.exports = config;

The preloadedModules entry in the config indicates which modules should be marked as preloaded when building a RAM bundle. When the bundle is loaded, those modules are immediately loaded, before any requires have even executed. The blacklist entry indicates that those modules should not be required inline. Because they are preloaded, there is no performance benefit from using an inline require. In fact the javascript spends extra time resolving the inline require every time the imports are referenced.

Test and Measure Improvements

You should now be ready to build your app using the RAM format and inline requires. Make sure you measure the before and after startup times.

Edit this page
Last updated on
- + diff --git a/docs/0.61/react-node.html b/docs/0.61/react-node.html index ffba6c627a0..e909629fde6 100644 --- a/docs/0.61/react-node.html +++ b/docs/0.61/react-node.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

React Node Object Type

A React Node is one of the following types:

  • Boolean (which is ignored)
  • null or undefined (which is ignored)
  • Number
  • String
  • A React element (result of JSX)
  • An array of any of the above, possibly a nested one
Edit this page
Last updated on
- + diff --git a/docs/0.61/react-node/index.html b/docs/0.61/react-node/index.html index ffba6c627a0..e909629fde6 100644 --- a/docs/0.61/react-node/index.html +++ b/docs/0.61/react-node/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

React Node Object Type

A React Node is one of the following types:

  • Boolean (which is ignored)
  • null or undefined (which is ignored)
  • Number
  • String
  • A React element (result of JSX)
  • An array of any of the above, possibly a nested one
Edit this page
Last updated on
- + diff --git a/docs/0.61/refreshcontrol.html b/docs/0.61/refreshcontrol.html index d75d489f835..e79dc603136 100644 --- a/docs/0.61/refreshcontrol.html +++ b/docs/0.61/refreshcontrol.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

RefreshControl

This component is used inside a ScrollView or ListView to add pull to refresh functionality. When the ScrollView is at scrollY: 0, swiping down triggers an onRefresh event.

Example

Note: refreshing is a controlled prop, this is why it needs to be set to true in the onRefresh function otherwise the refresh indicator will stop immediately.

Reference

Props

Inherits View Props.

refreshing

Whether the view should be indicating an active refresh.

TypeRequired
boolYes

onRefresh

Called when the view starts refreshing.

TypeRequired
functionNo

colors

The colors (at least one) that will be used to draw the refresh indicator.

TypeRequiredPlatform
array of colorNoAndroid

enabled

Whether the pull to refresh functionality is enabled.

TypeRequiredPlatform
boolNoAndroid

progressBackgroundColor

The background color of the refresh indicator.

TypeRequiredPlatform
colorNoAndroid

progressViewOffset

Progress view top offset

TypeRequiredPlatform
numberNoAndroid

size

Size of the refresh indicator, see RefreshControl.SIZE.

TypeRequiredPlatform
enum(RefreshLayoutConsts.SIZE.DEFAULT, RefreshLayoutConsts.SIZE.LARGE)NoAndroid

tintColor

The color of the refresh indicator.

TypeRequiredPlatform
colorNoiOS

title

The title displayed under the refresh indicator.

TypeRequiredPlatform
stringNoiOS

titleColor

Title color.

TypeRequiredPlatform
colorNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.61/refreshcontrol/index.html b/docs/0.61/refreshcontrol/index.html index d75d489f835..e79dc603136 100644 --- a/docs/0.61/refreshcontrol/index.html +++ b/docs/0.61/refreshcontrol/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

RefreshControl

This component is used inside a ScrollView or ListView to add pull to refresh functionality. When the ScrollView is at scrollY: 0, swiping down triggers an onRefresh event.

Example

Note: refreshing is a controlled prop, this is why it needs to be set to true in the onRefresh function otherwise the refresh indicator will stop immediately.

Reference

Props

Inherits View Props.

refreshing

Whether the view should be indicating an active refresh.

TypeRequired
boolYes

onRefresh

Called when the view starts refreshing.

TypeRequired
functionNo

colors

The colors (at least one) that will be used to draw the refresh indicator.

TypeRequiredPlatform
array of colorNoAndroid

enabled

Whether the pull to refresh functionality is enabled.

TypeRequiredPlatform
boolNoAndroid

progressBackgroundColor

The background color of the refresh indicator.

TypeRequiredPlatform
colorNoAndroid

progressViewOffset

Progress view top offset

TypeRequiredPlatform
numberNoAndroid

size

Size of the refresh indicator, see RefreshControl.SIZE.

TypeRequiredPlatform
enum(RefreshLayoutConsts.SIZE.DEFAULT, RefreshLayoutConsts.SIZE.LARGE)NoAndroid

tintColor

The color of the refresh indicator.

TypeRequiredPlatform
colorNoiOS

title

The title displayed under the refresh indicator.

TypeRequiredPlatform
stringNoiOS

titleColor

Title color.

TypeRequiredPlatform
colorNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.61/removing-default-permissions.html b/docs/0.61/removing-default-permissions.html index 4f9d1389e02..12bc2044e75 100644 --- a/docs/0.61/removing-default-permissions.html +++ b/docs/0.61/removing-default-permissions.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Removing Default Permissions

By default, some permissions are added to your Android APK.

The default permissions that get added are:

  • android.permission.INTERNET - Required for debug mode.
  • android.permission.SYSTEM_ALERT_WINDOW - Required for debug mode.
  • android.permission.READ_PHONE_STATE - Not required for debug or production.
  • android.permission.WRITE_EXTERNAL_STORAGE - Not required for debug or production.
  • android.permission.READ_EXTERNAL_STORAGE - Not required for debug or production.

  1. Let's start by removing READ_PHONE_STATE, WRITE_EXTERNAL_STORAGE, and READ_EXTERNAL_STORAGE from both production and debug APKs, as it is not required in either. These storage permissions are still not needed if AsyncStorage module is in use, so it is safe to remove from both production and debug.

  2. Open your android/app/src/main/AndroidManifest.xml file.

  3. Even though these three permissions are not listed in the manifest they get added in. We add the three permissions with tools:node="remove" attribute, to make sure it gets removed during build. Note that the package identifier will be different, for below it is "com.myapp" because the project was created with react-native init myapp.

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.myappid"
    + xmlns:tools="http://schemas.android.com/tools"
    >
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
    + <uses-permission tools:node="remove" android:name="android.permission.READ_PHONE_STATE" />
    + <uses-permission tools:node="remove" android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    + <uses-permission tools:node="remove" android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <application
    android:name=".MainApplication"
    android:label="@string/app_name"
    android:icon="@mipmap/ic_launcher"
    android:allowBackup="false"
    android:theme="@style/AppTheme">
    <activity
    android:name=".MainActivity"
    android:label="@string/app_name"
    android:configChanges="keyboard|keyboardHidden|orientation|screenSize"
    android:windowSoftInputMode="adjustResize">
    <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    </activity>
    <activity android:name="com.facebook.react.devsupport.DevSettingsActivity" />
    </application>
    </manifest>

That's it. We did not remove the INTERNET permission as pretty much all apps use it. Now whenever you create a production APK, these 3 permissions will be removed. When you create a debug APK (react-native run-android) it will install the APK with these permissions added.

Edit this page
Last updated on
- + diff --git a/docs/0.61/removing-default-permissions/index.html b/docs/0.61/removing-default-permissions/index.html index 4f9d1389e02..12bc2044e75 100644 --- a/docs/0.61/removing-default-permissions/index.html +++ b/docs/0.61/removing-default-permissions/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Removing Default Permissions

By default, some permissions are added to your Android APK.

The default permissions that get added are:

  • android.permission.INTERNET - Required for debug mode.
  • android.permission.SYSTEM_ALERT_WINDOW - Required for debug mode.
  • android.permission.READ_PHONE_STATE - Not required for debug or production.
  • android.permission.WRITE_EXTERNAL_STORAGE - Not required for debug or production.
  • android.permission.READ_EXTERNAL_STORAGE - Not required for debug or production.

  1. Let's start by removing READ_PHONE_STATE, WRITE_EXTERNAL_STORAGE, and READ_EXTERNAL_STORAGE from both production and debug APKs, as it is not required in either. These storage permissions are still not needed if AsyncStorage module is in use, so it is safe to remove from both production and debug.

  2. Open your android/app/src/main/AndroidManifest.xml file.

  3. Even though these three permissions are not listed in the manifest they get added in. We add the three permissions with tools:node="remove" attribute, to make sure it gets removed during build. Note that the package identifier will be different, for below it is "com.myapp" because the project was created with react-native init myapp.

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.myappid"
    + xmlns:tools="http://schemas.android.com/tools"
    >
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
    + <uses-permission tools:node="remove" android:name="android.permission.READ_PHONE_STATE" />
    + <uses-permission tools:node="remove" android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    + <uses-permission tools:node="remove" android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <application
    android:name=".MainApplication"
    android:label="@string/app_name"
    android:icon="@mipmap/ic_launcher"
    android:allowBackup="false"
    android:theme="@style/AppTheme">
    <activity
    android:name=".MainActivity"
    android:label="@string/app_name"
    android:configChanges="keyboard|keyboardHidden|orientation|screenSize"
    android:windowSoftInputMode="adjustResize">
    <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    </activity>
    <activity android:name="com.facebook.react.devsupport.DevSettingsActivity" />
    </application>
    </manifest>

That's it. We did not remove the INTERNET permission as pretty much all apps use it. Now whenever you create a production APK, these 3 permissions will be removed. When you create a debug APK (react-native run-android) it will install the APK with these permissions added.

Edit this page
Last updated on
- + diff --git a/docs/0.61/running-on-device.html b/docs/0.61/running-on-device.html index 1787c5de0db..17a8633575d 100644 --- a/docs/0.61/running-on-device.html +++ b/docs/0.61/running-on-device.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Running On Device

It's always a good idea to test your app on an actual device before releasing it to your users. This document will guide you through the necessary steps to run your React Native app on a device and to get it ready for production.

If you used Expo CLI or Create React Native App to set up your project, you can preview your app on a device by scanning the QR code with the Expo app—but in order to build and run your app on a device, you will need to eject and install the native code dependencies from the environment setup guide.

Running your app on Android devices

Development OS

1. Enable Debugging over USB

Most Android devices can only install and run apps downloaded from Google Play, by default. You will need to enable USB Debugging on your device in order to install your app during development.

To enable USB debugging on your device, you will first need to enable the "Developer options" menu by going to Settings → About phone → Software information and then tapping the Build number row at the bottom seven times. You can then go back to Settings → Developer options to enable "USB debugging".

2. Plug in your device via USB

Let's now set up an Android device to run our React Native projects. Go ahead and plug in your device via USB to your development machine.

Next, check the manufacturer code by using lsusb (on mac, you must first install lsusb). lsusb should output something like this:

$ lsusb
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 003: ID 22b8:2e76 Motorola PCS
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

These lines represent the USB devices currently connected to your machine.

You want the line that represents your phone. If you're in doubt, try unplugging your phone and running the command again:

$ lsusb
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

You'll see that after removing the phone, the line which has the phone model ("Motorola PCS" in this case) disappeared from the list. This is the line that we care about.

Bus 001 Device 003: ID 22b8:2e76 Motorola PCS

From the above line, you want to grab the first four digits from the device ID:

22b8:2e76

In this case, it's 22b8. That's the identifier for Motorola.

You'll need to input this into your udev rules in order to get up and running:

echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="22b8", MODE="0666", GROUP="plugdev"' | sudo tee /etc/udev/rules.d/51-android-usb.rules

Make sure that you replace 22b8 with the identifier you get in the above command.

Now check that your device is properly connecting to ADB, the Android Debug Bridge, by running adb devices.

$ adb devices
List of devices attached
emulator-5554 offline # Google emulator
14ed2fcc device # Physical device

Seeing device in the right column means the device is connected. You must have only one device connected at a time.

3. Run your app

Type the following in your command prompt to install and launch your app on the device:

$ npx react-native run-android

If you get a "bridge configuration isn't available" error, see Using adb reverse.

Hint: You can also use the React Native CLI to generate and run a Release build (e.g. npx react-native run-android --variant=release).

Connecting to the development server

You can also iterate quickly on a device by connecting to the development server running on your development machine. There are several ways of accomplishing this, depending on whether you have access to a USB cable or a Wi-Fi network.

Method 1: Using adb reverse (recommended)

You can use this method if your device is running Android 5.0 (Lollipop) or newer, it has USB debugging enabled, and it is connected via USB to your development machine.

Run the following in a command prompt:

$ adb -s <device name> reverse tcp:8081 tcp:8081

To find the device name, run the following adb command:

$ adb devices

You can now enable Live reloading from the Developer menu. Your app will reload whenever your JavaScript code has changed.

Method 2: Connect via Wi-Fi

You can also connect to the development server over Wi-Fi. You'll first need to install the app on your device using a USB cable, but once that has been done you can debug wirelessly by following these instructions. You'll need your development machine's current IP address before proceeding.

Open a terminal and type /sbin/ifconfig to find your machine's IP address.

  1. Make sure your laptop and your phone are on the same Wi-Fi network.
  2. Open your React Native app on your device.
  3. You'll see a red screen with an error. This is OK. The following steps will fix that.
  4. Open the in-app Developer menu.
  5. Go to Dev Settings → Debug server host & port for device.
  6. Type in your machine's IP address and the port of the local dev server (e.g. 10.0.1.1:8081).
  7. Go back to the Developer menu and select Reload JS.

You can now enable Live reloading from the Developer menu. Your app will reload whenever your JavaScript code has changed.

Building your app for production

You have built a great app using React Native, and you are now itching to release it in the Play Store. The process is the same as any other native Android app, with some additional considerations to take into account. Follow the guide for generating a signed APK to learn more.

Edit this page
Last updated on
- + diff --git a/docs/0.61/running-on-device/index.html b/docs/0.61/running-on-device/index.html index 1787c5de0db..17a8633575d 100644 --- a/docs/0.61/running-on-device/index.html +++ b/docs/0.61/running-on-device/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Running On Device

It's always a good idea to test your app on an actual device before releasing it to your users. This document will guide you through the necessary steps to run your React Native app on a device and to get it ready for production.

If you used Expo CLI or Create React Native App to set up your project, you can preview your app on a device by scanning the QR code with the Expo app—but in order to build and run your app on a device, you will need to eject and install the native code dependencies from the environment setup guide.

Running your app on Android devices

Development OS

1. Enable Debugging over USB

Most Android devices can only install and run apps downloaded from Google Play, by default. You will need to enable USB Debugging on your device in order to install your app during development.

To enable USB debugging on your device, you will first need to enable the "Developer options" menu by going to Settings → About phone → Software information and then tapping the Build number row at the bottom seven times. You can then go back to Settings → Developer options to enable "USB debugging".

2. Plug in your device via USB

Let's now set up an Android device to run our React Native projects. Go ahead and plug in your device via USB to your development machine.

Next, check the manufacturer code by using lsusb (on mac, you must first install lsusb). lsusb should output something like this:

$ lsusb
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 003: ID 22b8:2e76 Motorola PCS
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

These lines represent the USB devices currently connected to your machine.

You want the line that represents your phone. If you're in doubt, try unplugging your phone and running the command again:

$ lsusb
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

You'll see that after removing the phone, the line which has the phone model ("Motorola PCS" in this case) disappeared from the list. This is the line that we care about.

Bus 001 Device 003: ID 22b8:2e76 Motorola PCS

From the above line, you want to grab the first four digits from the device ID:

22b8:2e76

In this case, it's 22b8. That's the identifier for Motorola.

You'll need to input this into your udev rules in order to get up and running:

echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="22b8", MODE="0666", GROUP="plugdev"' | sudo tee /etc/udev/rules.d/51-android-usb.rules

Make sure that you replace 22b8 with the identifier you get in the above command.

Now check that your device is properly connecting to ADB, the Android Debug Bridge, by running adb devices.

$ adb devices
List of devices attached
emulator-5554 offline # Google emulator
14ed2fcc device # Physical device

Seeing device in the right column means the device is connected. You must have only one device connected at a time.

3. Run your app

Type the following in your command prompt to install and launch your app on the device:

$ npx react-native run-android

If you get a "bridge configuration isn't available" error, see Using adb reverse.

Hint: You can also use the React Native CLI to generate and run a Release build (e.g. npx react-native run-android --variant=release).

Connecting to the development server

You can also iterate quickly on a device by connecting to the development server running on your development machine. There are several ways of accomplishing this, depending on whether you have access to a USB cable or a Wi-Fi network.

Method 1: Using adb reverse (recommended)

You can use this method if your device is running Android 5.0 (Lollipop) or newer, it has USB debugging enabled, and it is connected via USB to your development machine.

Run the following in a command prompt:

$ adb -s <device name> reverse tcp:8081 tcp:8081

To find the device name, run the following adb command:

$ adb devices

You can now enable Live reloading from the Developer menu. Your app will reload whenever your JavaScript code has changed.

Method 2: Connect via Wi-Fi

You can also connect to the development server over Wi-Fi. You'll first need to install the app on your device using a USB cable, but once that has been done you can debug wirelessly by following these instructions. You'll need your development machine's current IP address before proceeding.

Open a terminal and type /sbin/ifconfig to find your machine's IP address.

  1. Make sure your laptop and your phone are on the same Wi-Fi network.
  2. Open your React Native app on your device.
  3. You'll see a red screen with an error. This is OK. The following steps will fix that.
  4. Open the in-app Developer menu.
  5. Go to Dev Settings → Debug server host & port for device.
  6. Type in your machine's IP address and the port of the local dev server (e.g. 10.0.1.1:8081).
  7. Go back to the Developer menu and select Reload JS.

You can now enable Live reloading from the Developer menu. Your app will reload whenever your JavaScript code has changed.

Building your app for production

You have built a great app using React Native, and you are now itching to release it in the Play Store. The process is the same as any other native Android app, with some additional considerations to take into account. Follow the guide for generating a signed APK to learn more.

Edit this page
Last updated on
- + diff --git a/docs/0.61/running-on-simulator-ios.html b/docs/0.61/running-on-simulator-ios.html index ff070e0b4d8..05330af1152 100644 --- a/docs/0.61/running-on-simulator-ios.html +++ b/docs/0.61/running-on-simulator-ios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Running On Simulator

Starting the simulator

Once you have your React Native project initialized, you can run react-native run-ios inside the newly created project directory. If everything is set up correctly, you should see your new app running in the iOS Simulator shortly.

Specifying a device

You can specify the device the simulator should run with the --simulator flag, followed by the device name as a string. The default is "iPhone X". If you wish to run your app on an iPhone 5s, run react-native run-ios --simulator="iPhone 5s".

The device names correspond to the list of devices available in Xcode. You can check your available devices by running xcrun simctl list devices from the console.

Edit this page
Last updated on
- + diff --git a/docs/0.61/running-on-simulator-ios/index.html b/docs/0.61/running-on-simulator-ios/index.html index ff070e0b4d8..05330af1152 100644 --- a/docs/0.61/running-on-simulator-ios/index.html +++ b/docs/0.61/running-on-simulator-ios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Running On Simulator

Starting the simulator

Once you have your React Native project initialized, you can run react-native run-ios inside the newly created project directory. If everything is set up correctly, you should see your new app running in the iOS Simulator shortly.

Specifying a device

You can specify the device the simulator should run with the --simulator flag, followed by the device name as a string. The default is "iPhone X". If you wish to run your app on an iPhone 5s, run react-native run-ios --simulator="iPhone 5s".

The device names correspond to the list of devices available in Xcode. You can check your available devices by running xcrun simctl list devices from the console.

Edit this page
Last updated on
- + diff --git a/docs/0.61/safeareaview.html b/docs/0.61/safeareaview.html index 3166cb0e0c0..b87ff43b35e 100644 --- a/docs/0.61/safeareaview.html +++ b/docs/0.61/safeareaview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

SafeAreaView

The purpose of SafeAreaView is to render content within the safe area boundaries of a device. It is currently only applicable to iOS devices with iOS version 11 or later.

SafeAreaView renders nested content and automatically applies padding to reflect the portion of the view that is not covered by navigation bars, tab bars, toolbars, and other ancestor views. Moreover, and most importantly, Safe Area's paddings reflect the physical limitation of the screen, such as rounded corners or camera notches (i.e. the sensor housing area on iPhone X).

Usage Example

To use, wrap your top level view with a SafeAreaView with a flex: 1 style applied to it. You may also want to use a background color that matches your application's design.

Reference

Props

Inherits View Props.

emulateUnlessSupported

TypeRequiredDefault
boolNotrue
Edit this page
Last updated on
- + diff --git a/docs/0.61/safeareaview/index.html b/docs/0.61/safeareaview/index.html index 3166cb0e0c0..b87ff43b35e 100644 --- a/docs/0.61/safeareaview/index.html +++ b/docs/0.61/safeareaview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

SafeAreaView

The purpose of SafeAreaView is to render content within the safe area boundaries of a device. It is currently only applicable to iOS devices with iOS version 11 or later.

SafeAreaView renders nested content and automatically applies padding to reflect the portion of the view that is not covered by navigation bars, tab bars, toolbars, and other ancestor views. Moreover, and most importantly, Safe Area's paddings reflect the physical limitation of the screen, such as rounded corners or camera notches (i.e. the sensor housing area on iPhone X).

Usage Example

To use, wrap your top level view with a SafeAreaView with a flex: 1 style applied to it. You may also want to use a background color that matches your application's design.

Reference

Props

Inherits View Props.

emulateUnlessSupported

TypeRequiredDefault
boolNotrue
Edit this page
Last updated on
- + diff --git a/docs/0.61/scrollview.html b/docs/0.61/scrollview.html index d41524631c4..aafcdc1af1c 100644 --- a/docs/0.61/scrollview.html +++ b/docs/0.61/scrollview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

ScrollView

Component that wraps platform ScrollView while providing integration with touch locking "responder" system.

Keep in mind that ScrollViews must have a bounded height in order to work, since they contain unbounded-height children into a bounded container (via a scroll interaction). In order to bound the height of a ScrollView, either set the height of the view directly (discouraged) or make sure all parent views have bounded height. Forgetting to transfer {flex: 1} down the view stack can lead to errors here, which the element inspector makes quick to debug.

Doesn't yet support other contained responders from blocking this scroll view from becoming the responder.

<ScrollView> vs <FlatList> - which one to use?

ScrollView renders all its react child components at once, but this has a performance downside.

Imagine you have a very long list of items you want to display, maybe several screens worth of content. Creating JS components and native views for everything all at once, much of which may not even be shown, will contribute to slow rendering and increased memory usage.

This is where FlatList comes into play. FlatList renders items lazily, when they are about to appear, and removes items that scroll way off screen to save memory and processing time.

FlatList is also handy if you want to render separators between your items, multiple columns, infinite scroll loading, or any number of other features it supports out of the box.

Example

Reference

Props

Inherits View Props.

alwaysBounceHorizontal

When true, the scroll view bounces horizontally when it reaches the end even if the content is smaller than the scroll view itself. The default value is true when horizontal={true} and false otherwise.

TypeRequiredPlatform
boolNoiOS

alwaysBounceVertical

When true, the scroll view bounces vertically when it reaches the end even if the content is smaller than the scroll view itself. The default value is false when horizontal={true} and true otherwise.

TypeRequiredPlatform
boolNoiOS

automaticallyAdjustContentInsets

Controls whether iOS should automatically adjust the content inset for scroll views that are placed behind a navigation bar or tab bar/ toolbar. The default value is true.

TypeRequiredPlatform
boolNoiOS

bounces

When true, the scroll view bounces when it reaches the end of the content if the content is larger then the scroll view along the axis of the scroll direction. When false, it disables all bouncing even if the alwaysBounce* props are true. The default value is true.

TypeRequiredPlatform
boolNoiOS

bouncesZoom

When true, gestures can drive zoom past min/max and the zoom will animate to the min/max value at gesture end, otherwise the zoom will not exceed the limits.

TypeRequiredPlatform
boolNoiOS

canCancelContentTouches

When false, once tracking starts, won't try to drag if the touch moves. The default value is true.

TypeRequiredPlatform
boolNoiOS

centerContent

When true, the scroll view automatically centers the content when the content is smaller than the scroll view bounds; when the content is larger than the scroll view, this property has no effect. The default value is false.

TypeRequiredPlatform
boolNoiOS

contentContainerStyle

These styles will be applied to the scroll view content container which wraps all of the child views. Example:

return (
<ScrollView contentContainerStyle={styles.contentContainer}>
</ScrollView>
);
...
const styles = StyleSheet.create({
contentContainer: {
paddingVertical: 20
}
});
TypeRequired
StyleSheetPropType(View Style props)No

contentInset

The amount by which the scroll view content is inset from the edges of the scroll view. Defaults to {top: 0, left: 0, bottom: 0, right: 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

contentInsetAdjustmentBehavior

This property specifies how the safe area insets are used to modify the content area of the scroll view. The default value of this property is "never". Available on iOS 11 and later.

TypeRequiredPlatform
enum('automatic', 'scrollableAxes', 'never', 'always')NoiOS

contentOffset

Used to manually set the starting scroll offset. The default value is {x: 0, y: 0}.

TypeRequiredPlatform
PointPropTypeNoiOS

decelerationRate

A floating-point number that determines how quickly the scroll view decelerates after the user lifts their finger. You may also use string shortcuts "normal" and "fast" which match the underlying iOS settings for UIScrollViewDecelerationRateNormal and UIScrollViewDecelerationRateFast respectively.

  • 'normal' (the default), 0.998 on iOS, 0.985 on Android.
  • 'fast', 0.99 on iOS, 0.9 on Android.
TypeRequired
enum('fast', 'normal'), ,numberNo

directionalLockEnabled

When true, the ScrollView will try to lock to only vertical or horizontal scrolling while dragging. The default value is false.

TypeRequiredPlatform
boolNoiOS

disableIntervalMomentum

When true, the scroll view stops on the next index (in relation to scroll position at release) regardless of how fast the gesture is. This can be used for horizontal pagination when the page is less than the width of the ScrollView. The default value is false.

TypeRequired
boolNo

disableScrollViewPanResponder

When true, the default JS pan responder on the ScrollView is disabled, and full control over touches inside the ScrollView is left to its child components. This is particularly useful if snapToInterval is enabled, since it does not follow typical touch patterns. Do not use this on regular ScrollView use cases without snapToInterval as it may cause unexpected touches to occur while scrolling. The default value is false.

TypeRequired
boolNo

endFillColor

Sometimes a scrollview takes up more space than its content fills. When this is the case, this prop will fill the rest of the scrollview with a color to avoid setting a background and creating unnecessary overdraw. This is an advanced optimization that is not needed in the general case.

TypeRequiredPlatform
colorNoAndroid

horizontal

When true, the scroll view's children are arranged horizontally in a row instead of vertically in a column. The default value is false.

TypeRequired
boolNo

indicatorStyle

The style of the scroll indicators.

  • 'default' (the default), same as black.
  • 'black', scroll indicator is black. This style is good against a light background.
  • 'white', scroll indicator is white. This style is good against a dark background.
TypeRequiredPlatform
enum('default', 'black', 'white')NoiOS

invertStickyHeaders

If sticky headers should stick at the bottom instead of the top of the ScrollView. This is usually used with inverted ScrollViews.

TypeRequired
boolNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

Cross platform

  • 'none' (the default), drags do not dismiss the keyboard.
  • 'on-drag', the keyboard is dismissed when a drag begins.

iOS Only

  • 'interactive', the keyboard is dismissed interactively with the drag and moves in synchrony with the touch; dragging upwards cancels the dismissal. On android this is not supported and it will have the same behavior as 'none'.
TypeRequired
enum('none', 'on-drag', 'interactive')No

keyboardShouldPersistTaps

Determines when the keyboard should stay visible after a tap.

  • 'never' (the default), tapping outside of the focused text input when the keyboard is up dismisses the keyboard. When this happens, children won't receive the tap.
  • 'always', the keyboard will not dismiss automatically, and the scroll view will not catch taps, but children of the scroll view can catch taps.
  • 'handled', the keyboard will not dismiss automatically when the tap was handled by children of the scroll view (or captured by an ancestor).
  • false, deprecated, use 'never' instead
  • true, deprecated, use 'always' instead
TypeRequired
enum('always', 'never', 'handled', false, true)No

maintainVisibleContentPosition

When set, the scroll view will adjust the scroll position so that the first child that is currently visible and at or beyond minIndexForVisible will not change position. This is useful for lists that are loading content in both directions, e.g. a chat thread, where new messages coming in might otherwise cause the scroll position to jump. A value of 0 is common, but other values such as 1 can be used to skip loading spinners or other content that should not maintain position.

The optional autoscrollToTopThreshold can be used to make the content automatically scroll to the top after making the adjustment if the user was within the threshold of the top before the adjustment was made. This is also useful for chat-like applications where you want to see new messages scroll into place, but not if the user has scrolled up a ways and it would be disruptive to scroll a bunch.

Caveat 1: Reordering elements in the scrollview with this enabled will probably cause jumpiness and jank. It can be fixed, but there are currently no plans to do so. For now, don't re-order the content of any ScrollViews or Lists that use this feature.

Caveat 2: This uses contentOffset and frame.origin in native code to compute visibility. Occlusion, transforms, and other complexity won't be taken into account as to whether content is "visible" or not.

TypeRequiredPlatform
object: { minIndexForVisible: number, autoscrollToTopThreshold: number }NoiOS

maximumZoomScale

The maximum allowed zoom scale. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

minimumZoomScale

The minimum allowed zoom scale. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

nestedScrollEnabled

Enables nested scrolling for Android API level 21+. Nested scrolling is supported by default on iOS.

TypeRequiredPlatform
boolNoAndroid

onContentSizeChange

Called when scrollable content view of the ScrollView changes.

Handler function is passed the content width and content height as parameters: (contentWidth, contentHeight)

It's implemented using onLayout handler attached to the content container which this ScrollView renders.

TypeRequired
functionNo

onMomentumScrollBegin

Called when the momentum scroll starts (scroll which occurs as the ScrollView starts gliding).

TypeRequired
functionNo

onMomentumScrollEnd

Called when the momentum scroll ends (scroll which occurs as the ScrollView glides to a stop).

TypeRequired
functionNo

onScroll

Fires at most once per frame during scrolling. The frequency of the events can be controlled using the scrollEventThrottle prop. The event has the shape { nativeEvent: { contentInset: { bottom, left, right, top }, contentOffset: { x, y }, contentSize: { height, width }, layoutMeasurement: { height, width }, zoomScale } }. All values are numbers.

TypeRequired
functionNo

onScrollBeginDrag

Called when the user begins to drag the scroll view.

TypeRequired
functionNo

onScrollEndDrag

Called when the user stops dragging the scroll view and it either stops or begins to glide.

TypeRequired
functionNo

onScrollToTop

Fires when the scroll view scrolls to top after the status bar has been tapped.

TypeRequiredPlatform
functionNoiOS

overScrollMode

Used to override default value of overScroll mode.

Possible values:

  • 'auto' - Default value, allow a user to over-scroll this view only if the content is large enough to meaningfully scroll.
  • 'always' - Always allow a user to over-scroll this view.
  • 'never' - Never allow a user to over-scroll this view.
TypeRequiredPlatform
enum('auto', 'always', 'never')NoAndroid

pagingEnabled

When true, the scroll view stops on multiples of the scroll view's size when scrolling. This can be used for horizontal pagination. The default value is false.

Note: Vertical pagination is not supported on Android.

TypeRequired
boolNo

persistentScrollbar

Causes the scrollbars not to turn transparent when they are not in use. The default value is false.

TypeRequiredPlatform
boolNoAndroid

pinchGestureEnabled

When true, ScrollView allows use of pinch gestures to zoom in and out. The default value is true.

TypeRequiredPlatform
boolNoiOS

refreshControl

A RefreshControl component, used to provide pull-to-refresh functionality for the ScrollView. Only works for vertical ScrollViews (horizontal prop must be false).

See RefreshControl.

TypeRequired
elementNo

removeClippedSubviews

Experimental: When true, offscreen child views (whose overflow value is hidden) are removed from their native backing superview when offscreen. This can improve scrolling performance on long lists. The default value is true.

TypeRequired
boolNo

scrollBarThumbImage

Optionally an image can be used for the scroll bar thumb. This will override the color. While the image is loading or the image fails to load the color will be used instead. Use an alpha of 0 in the color to avoid seeing it while the image is loading.

  • uri, a string representing the resource identifier for the image, which should be either a local file path or the name of a static image resource.
  • number, opaque type returned by something like import IMAGE from './image.jpg'.
TypeRequiredPlatform
numberNoVR

scrollEnabled

When false, the view cannot be scrolled via touch interaction. The default value is true.

Note that the view can always be scrolled by calling scrollTo.

TypeRequired
boolNo

scrollEventThrottle

This controls how often the scroll event will be fired while scrolling (as a time interval in ms). A lower number yields better accuracy for code that is tracking the scroll position, but can lead to scroll performance problems due to the volume of information being send over the bridge. You will not notice a difference between values set between 1-16 as the JS run loop is synced to the screen refresh rate. If you do not need precise scroll position tracking, set this value higher to limit the information being sent across the bridge. The default value is zero, which results in the scroll event being sent only once each time the view is scrolled.

TypeRequiredPlatform
numberNoiOS

scrollIndicatorInsets

The amount by which the scroll view indicators are inset from the edges of the scroll view. This should normally be set to the same value as the contentInset. Defaults to {0, 0, 0, 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

scrollPerfTag

Tag used to log scroll performance on this scroll view. Will force momentum events to be turned on (see sendMomentumEvents). This doesn't do anything out of the box and you need to implement a custom native FpsListener for it to be useful.

TypeRequiredPlatform
stringNoAndroid

scrollToOverflowEnabled

When true, the scroll view can be programmatically scrolled beyond its content size. The default value is false.

TypeRequiredPlatform
boolNoiOS

scrollsToTop

When true, the scroll view scrolls to top when the status bar is tapped. The default value is true.

TypeRequiredPlatform
boolNoiOS

DEPRECATED_sendUpdatedChildFrames

When true, ScrollView will emit updateChildFrames data in scroll events, otherwise will not compute or emit child frame data. This only exists to support legacy issues, onLayout should be used instead to retrieve frame data. The default value is false.

TypeRequiredPlatform
boolNoiOS

showsHorizontalScrollIndicator

When true, shows a horizontal scroll indicator. The default value is true.

TypeRequired
boolNo

showsVerticalScrollIndicator

When true, shows a vertical scroll indicator. The default value is true.

TypeRequired
boolNo

snapToAlignment

When snapToInterval is set, snapToAlignment will define the relationship of the snapping to the scroll view.

  • 'start' (the default) will align the snap at the left (horizontal) or top (vertical).
  • 'center' will align the snap in the center.
  • 'end' will align the snap at the right (horizontal) or bottom (vertical).
TypeRequiredPlatform
enum('start', 'center', 'end')NoiOS

snapToEnd

Use in conjunction with snapToOffsets. By default, the end of the list counts as a snap offset. Set snapToEnd to false to disable this behavior and allow the list to scroll freely between its end and the last snapToOffsets offset. The default value is true.

TypeRequired
booleanNo

snapToInterval

When set, causes the scroll view to stop at multiples of the value of snapToInterval. This can be used for paginating through children that have lengths smaller than the scroll view. Typically used in combination with snapToAlignment and decelerationRate="fast". Overrides less configurable pagingEnabled prop.

TypeRequired
numberNo

snapToOffsets

When set, causes the scroll view to stop at the defined offsets. This can be used for paginating through variously sized children that have lengths smaller than the scroll view. Typically used in combination with decelerationRate="fast". Overrides less configurable pagingEnabled and snapToInterval props.

TypeRequired
array of numberNo

snapToStart

Use in conjunction with snapToOffsets. By default, the beginning of the list counts as a snap offset. Set snapToStart to false to disable this behavior and allow the list to scroll freely between its start and the first snapToOffsets offset. The default value is true.

TypeRequired
booleanNo

stickyHeaderIndices

An array of child indices determining which children get docked to the top of the screen when scrolling. For example, passing stickyHeaderIndices={[0]} will cause the first child to be fixed to the top of the scroll view. This property is not supported in conjunction with horizontal={true}.

TypeRequired
array of numberNo

zoomScale

The current scale of the scroll view content. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

Methods

flashScrollIndicators()

flashScrollIndicators();

Displays the scroll indicators momentarily.

scrollTo()

scrollTo(
options?: {x?: number, y?: number, animated?: boolean} | number,
deprecatedX?: number,
deprecatedAnimated?: boolean,
);

Scrolls to a given x, y offset, either immediately, with a smooth animation.

Example:

scrollTo({x: 0, y: 0, animated: true})

Note: The weird function signature is due to the fact that, for historical reasons, the function also accepts separate arguments as an alternative to the options object. This is deprecated due to ambiguity (y before x), and SHOULD NOT BE USED.

scrollToEnd()

scrollToEnd(([options]: { animated: boolean, duration: number }));

If this is a vertical ScrollView scrolls to the bottom. If this is a horizontal ScrollView scrolls to the right.

Use scrollToEnd({animated: true}) for smooth animated scrolling, scrollToEnd({animated: false}) for immediate scrolling. For Android, you may specify a duration, e.g. scrollToEnd({duration: 500}) for a controlled duration scroll. If no options are passed, animated defaults to true.

scrollWithoutAnimationTo()

scrollWithoutAnimationTo(y, x);

Deprecated, use scrollTo instead.

Edit this page
Last updated on
- + diff --git a/docs/0.61/scrollview/index.html b/docs/0.61/scrollview/index.html index d41524631c4..aafcdc1af1c 100644 --- a/docs/0.61/scrollview/index.html +++ b/docs/0.61/scrollview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

ScrollView

Component that wraps platform ScrollView while providing integration with touch locking "responder" system.

Keep in mind that ScrollViews must have a bounded height in order to work, since they contain unbounded-height children into a bounded container (via a scroll interaction). In order to bound the height of a ScrollView, either set the height of the view directly (discouraged) or make sure all parent views have bounded height. Forgetting to transfer {flex: 1} down the view stack can lead to errors here, which the element inspector makes quick to debug.

Doesn't yet support other contained responders from blocking this scroll view from becoming the responder.

<ScrollView> vs <FlatList> - which one to use?

ScrollView renders all its react child components at once, but this has a performance downside.

Imagine you have a very long list of items you want to display, maybe several screens worth of content. Creating JS components and native views for everything all at once, much of which may not even be shown, will contribute to slow rendering and increased memory usage.

This is where FlatList comes into play. FlatList renders items lazily, when they are about to appear, and removes items that scroll way off screen to save memory and processing time.

FlatList is also handy if you want to render separators between your items, multiple columns, infinite scroll loading, or any number of other features it supports out of the box.

Example

Reference

Props

Inherits View Props.

alwaysBounceHorizontal

When true, the scroll view bounces horizontally when it reaches the end even if the content is smaller than the scroll view itself. The default value is true when horizontal={true} and false otherwise.

TypeRequiredPlatform
boolNoiOS

alwaysBounceVertical

When true, the scroll view bounces vertically when it reaches the end even if the content is smaller than the scroll view itself. The default value is false when horizontal={true} and true otherwise.

TypeRequiredPlatform
boolNoiOS

automaticallyAdjustContentInsets

Controls whether iOS should automatically adjust the content inset for scroll views that are placed behind a navigation bar or tab bar/ toolbar. The default value is true.

TypeRequiredPlatform
boolNoiOS

bounces

When true, the scroll view bounces when it reaches the end of the content if the content is larger then the scroll view along the axis of the scroll direction. When false, it disables all bouncing even if the alwaysBounce* props are true. The default value is true.

TypeRequiredPlatform
boolNoiOS

bouncesZoom

When true, gestures can drive zoom past min/max and the zoom will animate to the min/max value at gesture end, otherwise the zoom will not exceed the limits.

TypeRequiredPlatform
boolNoiOS

canCancelContentTouches

When false, once tracking starts, won't try to drag if the touch moves. The default value is true.

TypeRequiredPlatform
boolNoiOS

centerContent

When true, the scroll view automatically centers the content when the content is smaller than the scroll view bounds; when the content is larger than the scroll view, this property has no effect. The default value is false.

TypeRequiredPlatform
boolNoiOS

contentContainerStyle

These styles will be applied to the scroll view content container which wraps all of the child views. Example:

return (
<ScrollView contentContainerStyle={styles.contentContainer}>
</ScrollView>
);
...
const styles = StyleSheet.create({
contentContainer: {
paddingVertical: 20
}
});
TypeRequired
StyleSheetPropType(View Style props)No

contentInset

The amount by which the scroll view content is inset from the edges of the scroll view. Defaults to {top: 0, left: 0, bottom: 0, right: 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

contentInsetAdjustmentBehavior

This property specifies how the safe area insets are used to modify the content area of the scroll view. The default value of this property is "never". Available on iOS 11 and later.

TypeRequiredPlatform
enum('automatic', 'scrollableAxes', 'never', 'always')NoiOS

contentOffset

Used to manually set the starting scroll offset. The default value is {x: 0, y: 0}.

TypeRequiredPlatform
PointPropTypeNoiOS

decelerationRate

A floating-point number that determines how quickly the scroll view decelerates after the user lifts their finger. You may also use string shortcuts "normal" and "fast" which match the underlying iOS settings for UIScrollViewDecelerationRateNormal and UIScrollViewDecelerationRateFast respectively.

  • 'normal' (the default), 0.998 on iOS, 0.985 on Android.
  • 'fast', 0.99 on iOS, 0.9 on Android.
TypeRequired
enum('fast', 'normal'), ,numberNo

directionalLockEnabled

When true, the ScrollView will try to lock to only vertical or horizontal scrolling while dragging. The default value is false.

TypeRequiredPlatform
boolNoiOS

disableIntervalMomentum

When true, the scroll view stops on the next index (in relation to scroll position at release) regardless of how fast the gesture is. This can be used for horizontal pagination when the page is less than the width of the ScrollView. The default value is false.

TypeRequired
boolNo

disableScrollViewPanResponder

When true, the default JS pan responder on the ScrollView is disabled, and full control over touches inside the ScrollView is left to its child components. This is particularly useful if snapToInterval is enabled, since it does not follow typical touch patterns. Do not use this on regular ScrollView use cases without snapToInterval as it may cause unexpected touches to occur while scrolling. The default value is false.

TypeRequired
boolNo

endFillColor

Sometimes a scrollview takes up more space than its content fills. When this is the case, this prop will fill the rest of the scrollview with a color to avoid setting a background and creating unnecessary overdraw. This is an advanced optimization that is not needed in the general case.

TypeRequiredPlatform
colorNoAndroid

horizontal

When true, the scroll view's children are arranged horizontally in a row instead of vertically in a column. The default value is false.

TypeRequired
boolNo

indicatorStyle

The style of the scroll indicators.

  • 'default' (the default), same as black.
  • 'black', scroll indicator is black. This style is good against a light background.
  • 'white', scroll indicator is white. This style is good against a dark background.
TypeRequiredPlatform
enum('default', 'black', 'white')NoiOS

invertStickyHeaders

If sticky headers should stick at the bottom instead of the top of the ScrollView. This is usually used with inverted ScrollViews.

TypeRequired
boolNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

Cross platform

  • 'none' (the default), drags do not dismiss the keyboard.
  • 'on-drag', the keyboard is dismissed when a drag begins.

iOS Only

  • 'interactive', the keyboard is dismissed interactively with the drag and moves in synchrony with the touch; dragging upwards cancels the dismissal. On android this is not supported and it will have the same behavior as 'none'.
TypeRequired
enum('none', 'on-drag', 'interactive')No

keyboardShouldPersistTaps

Determines when the keyboard should stay visible after a tap.

  • 'never' (the default), tapping outside of the focused text input when the keyboard is up dismisses the keyboard. When this happens, children won't receive the tap.
  • 'always', the keyboard will not dismiss automatically, and the scroll view will not catch taps, but children of the scroll view can catch taps.
  • 'handled', the keyboard will not dismiss automatically when the tap was handled by children of the scroll view (or captured by an ancestor).
  • false, deprecated, use 'never' instead
  • true, deprecated, use 'always' instead
TypeRequired
enum('always', 'never', 'handled', false, true)No

maintainVisibleContentPosition

When set, the scroll view will adjust the scroll position so that the first child that is currently visible and at or beyond minIndexForVisible will not change position. This is useful for lists that are loading content in both directions, e.g. a chat thread, where new messages coming in might otherwise cause the scroll position to jump. A value of 0 is common, but other values such as 1 can be used to skip loading spinners or other content that should not maintain position.

The optional autoscrollToTopThreshold can be used to make the content automatically scroll to the top after making the adjustment if the user was within the threshold of the top before the adjustment was made. This is also useful for chat-like applications where you want to see new messages scroll into place, but not if the user has scrolled up a ways and it would be disruptive to scroll a bunch.

Caveat 1: Reordering elements in the scrollview with this enabled will probably cause jumpiness and jank. It can be fixed, but there are currently no plans to do so. For now, don't re-order the content of any ScrollViews or Lists that use this feature.

Caveat 2: This uses contentOffset and frame.origin in native code to compute visibility. Occlusion, transforms, and other complexity won't be taken into account as to whether content is "visible" or not.

TypeRequiredPlatform
object: { minIndexForVisible: number, autoscrollToTopThreshold: number }NoiOS

maximumZoomScale

The maximum allowed zoom scale. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

minimumZoomScale

The minimum allowed zoom scale. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

nestedScrollEnabled

Enables nested scrolling for Android API level 21+. Nested scrolling is supported by default on iOS.

TypeRequiredPlatform
boolNoAndroid

onContentSizeChange

Called when scrollable content view of the ScrollView changes.

Handler function is passed the content width and content height as parameters: (contentWidth, contentHeight)

It's implemented using onLayout handler attached to the content container which this ScrollView renders.

TypeRequired
functionNo

onMomentumScrollBegin

Called when the momentum scroll starts (scroll which occurs as the ScrollView starts gliding).

TypeRequired
functionNo

onMomentumScrollEnd

Called when the momentum scroll ends (scroll which occurs as the ScrollView glides to a stop).

TypeRequired
functionNo

onScroll

Fires at most once per frame during scrolling. The frequency of the events can be controlled using the scrollEventThrottle prop. The event has the shape { nativeEvent: { contentInset: { bottom, left, right, top }, contentOffset: { x, y }, contentSize: { height, width }, layoutMeasurement: { height, width }, zoomScale } }. All values are numbers.

TypeRequired
functionNo

onScrollBeginDrag

Called when the user begins to drag the scroll view.

TypeRequired
functionNo

onScrollEndDrag

Called when the user stops dragging the scroll view and it either stops or begins to glide.

TypeRequired
functionNo

onScrollToTop

Fires when the scroll view scrolls to top after the status bar has been tapped.

TypeRequiredPlatform
functionNoiOS

overScrollMode

Used to override default value of overScroll mode.

Possible values:

  • 'auto' - Default value, allow a user to over-scroll this view only if the content is large enough to meaningfully scroll.
  • 'always' - Always allow a user to over-scroll this view.
  • 'never' - Never allow a user to over-scroll this view.
TypeRequiredPlatform
enum('auto', 'always', 'never')NoAndroid

pagingEnabled

When true, the scroll view stops on multiples of the scroll view's size when scrolling. This can be used for horizontal pagination. The default value is false.

Note: Vertical pagination is not supported on Android.

TypeRequired
boolNo

persistentScrollbar

Causes the scrollbars not to turn transparent when they are not in use. The default value is false.

TypeRequiredPlatform
boolNoAndroid

pinchGestureEnabled

When true, ScrollView allows use of pinch gestures to zoom in and out. The default value is true.

TypeRequiredPlatform
boolNoiOS

refreshControl

A RefreshControl component, used to provide pull-to-refresh functionality for the ScrollView. Only works for vertical ScrollViews (horizontal prop must be false).

See RefreshControl.

TypeRequired
elementNo

removeClippedSubviews

Experimental: When true, offscreen child views (whose overflow value is hidden) are removed from their native backing superview when offscreen. This can improve scrolling performance on long lists. The default value is true.

TypeRequired
boolNo

scrollBarThumbImage

Optionally an image can be used for the scroll bar thumb. This will override the color. While the image is loading or the image fails to load the color will be used instead. Use an alpha of 0 in the color to avoid seeing it while the image is loading.

  • uri, a string representing the resource identifier for the image, which should be either a local file path or the name of a static image resource.
  • number, opaque type returned by something like import IMAGE from './image.jpg'.
TypeRequiredPlatform
numberNoVR

scrollEnabled

When false, the view cannot be scrolled via touch interaction. The default value is true.

Note that the view can always be scrolled by calling scrollTo.

TypeRequired
boolNo

scrollEventThrottle

This controls how often the scroll event will be fired while scrolling (as a time interval in ms). A lower number yields better accuracy for code that is tracking the scroll position, but can lead to scroll performance problems due to the volume of information being send over the bridge. You will not notice a difference between values set between 1-16 as the JS run loop is synced to the screen refresh rate. If you do not need precise scroll position tracking, set this value higher to limit the information being sent across the bridge. The default value is zero, which results in the scroll event being sent only once each time the view is scrolled.

TypeRequiredPlatform
numberNoiOS

scrollIndicatorInsets

The amount by which the scroll view indicators are inset from the edges of the scroll view. This should normally be set to the same value as the contentInset. Defaults to {0, 0, 0, 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

scrollPerfTag

Tag used to log scroll performance on this scroll view. Will force momentum events to be turned on (see sendMomentumEvents). This doesn't do anything out of the box and you need to implement a custom native FpsListener for it to be useful.

TypeRequiredPlatform
stringNoAndroid

scrollToOverflowEnabled

When true, the scroll view can be programmatically scrolled beyond its content size. The default value is false.

TypeRequiredPlatform
boolNoiOS

scrollsToTop

When true, the scroll view scrolls to top when the status bar is tapped. The default value is true.

TypeRequiredPlatform
boolNoiOS

DEPRECATED_sendUpdatedChildFrames

When true, ScrollView will emit updateChildFrames data in scroll events, otherwise will not compute or emit child frame data. This only exists to support legacy issues, onLayout should be used instead to retrieve frame data. The default value is false.

TypeRequiredPlatform
boolNoiOS

showsHorizontalScrollIndicator

When true, shows a horizontal scroll indicator. The default value is true.

TypeRequired
boolNo

showsVerticalScrollIndicator

When true, shows a vertical scroll indicator. The default value is true.

TypeRequired
boolNo

snapToAlignment

When snapToInterval is set, snapToAlignment will define the relationship of the snapping to the scroll view.

  • 'start' (the default) will align the snap at the left (horizontal) or top (vertical).
  • 'center' will align the snap in the center.
  • 'end' will align the snap at the right (horizontal) or bottom (vertical).
TypeRequiredPlatform
enum('start', 'center', 'end')NoiOS

snapToEnd

Use in conjunction with snapToOffsets. By default, the end of the list counts as a snap offset. Set snapToEnd to false to disable this behavior and allow the list to scroll freely between its end and the last snapToOffsets offset. The default value is true.

TypeRequired
booleanNo

snapToInterval

When set, causes the scroll view to stop at multiples of the value of snapToInterval. This can be used for paginating through children that have lengths smaller than the scroll view. Typically used in combination with snapToAlignment and decelerationRate="fast". Overrides less configurable pagingEnabled prop.

TypeRequired
numberNo

snapToOffsets

When set, causes the scroll view to stop at the defined offsets. This can be used for paginating through variously sized children that have lengths smaller than the scroll view. Typically used in combination with decelerationRate="fast". Overrides less configurable pagingEnabled and snapToInterval props.

TypeRequired
array of numberNo

snapToStart

Use in conjunction with snapToOffsets. By default, the beginning of the list counts as a snap offset. Set snapToStart to false to disable this behavior and allow the list to scroll freely between its start and the first snapToOffsets offset. The default value is true.

TypeRequired
booleanNo

stickyHeaderIndices

An array of child indices determining which children get docked to the top of the screen when scrolling. For example, passing stickyHeaderIndices={[0]} will cause the first child to be fixed to the top of the scroll view. This property is not supported in conjunction with horizontal={true}.

TypeRequired
array of numberNo

zoomScale

The current scale of the scroll view content. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

Methods

flashScrollIndicators()

flashScrollIndicators();

Displays the scroll indicators momentarily.

scrollTo()

scrollTo(
options?: {x?: number, y?: number, animated?: boolean} | number,
deprecatedX?: number,
deprecatedAnimated?: boolean,
);

Scrolls to a given x, y offset, either immediately, with a smooth animation.

Example:

scrollTo({x: 0, y: 0, animated: true})

Note: The weird function signature is due to the fact that, for historical reasons, the function also accepts separate arguments as an alternative to the options object. This is deprecated due to ambiguity (y before x), and SHOULD NOT BE USED.

scrollToEnd()

scrollToEnd(([options]: { animated: boolean, duration: number }));

If this is a vertical ScrollView scrolls to the bottom. If this is a horizontal ScrollView scrolls to the right.

Use scrollToEnd({animated: true}) for smooth animated scrolling, scrollToEnd({animated: false}) for immediate scrolling. For Android, you may specify a duration, e.g. scrollToEnd({duration: 500}) for a controlled duration scroll. If no options are passed, animated defaults to true.

scrollWithoutAnimationTo()

scrollWithoutAnimationTo(y, x);

Deprecated, use scrollTo instead.

Edit this page
Last updated on
- + diff --git a/docs/0.61/sectionlist.html b/docs/0.61/sectionlist.html index 49bc057d038..dc4d342cc74 100644 --- a/docs/0.61/sectionlist.html +++ b/docs/0.61/sectionlist.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

SectionList

A performant interface for rendering sectioned lists, supporting the most handy features:

  • Fully cross-platform.
  • Configurable viewability callbacks.
  • List header support.
  • List footer support.
  • Item separator support.
  • Section header support.
  • Section separator support.
  • Heterogeneous data and item rendering support.
  • Pull to Refresh.
  • Scroll loading.

If you don't need section support and want a simpler interface, use <FlatList>.

Example

This is a convenience wrapper around <VirtualizedList>, and thus inherits its props (as well as those of <ScrollView> that aren't explicitly listed here, along with the following caveats:

  • Internal state is not preserved when content scrolls out of the render window. Make sure all your data is captured in the item data or external stores like Flux, Redux, or Relay.
  • This is a PureComponent which means that it will not re-render if props remain shallow-equal. Make sure that everything your renderItem function depends on is passed as a prop (e.g. extraData) that is not === after updates, otherwise your UI may not update on changes. This includes the data prop and parent component state.
  • In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate and momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application, and we are working on improving it behind the scenes.
  • By default, the list looks for a key prop on each item and uses that for the React key. Alternatively, you can provide a custom keyExtractor prop.

Props

Required props:

Optional props:

Methods

Type Definitions

Reference

Props

renderItem

Default renderer for every item in every section. Can be over-ridden on a per-section basis. Should return a React element.

TypeRequired
functionYes

The render function will be passed an object with the following keys:

  • 'item' (object) - the item object as specified in this section's data key
  • 'index' (number) - Item's index within the section.
  • 'section' (object) - The full section object as specified in sections.
  • 'separators' (object) - An object with the following keys:
    • 'highlight' (function) - () => void
    • 'unhighlight' (function) - () => void
    • 'updateProps' (function) - (select, newProps) => void
      • 'select' (enum) - possible values are 'leading', 'trailing'
      • 'newProps' (object)

sections

The actual data to render, akin to the data prop in FlatList.

TypeRequired
array of SectionsYes

extraData

A marker property for telling the list to re-render (since it implements PureComponent). If any of your renderItem, Header, Footer, etc. functions depend on anything outside of the data prop, stick it here and treat it immutably.

TypeRequired
anyNo

initialNumToRender

How many items to render in the initial batch. This should be enough to fill the screen but not much more. Note these items will never be unmounted as part of the windowed rendering in order to improve perceived performance of scroll-to-top actions.

TypeRequired
numberYes

inverted

Reverses the direction of scroll. Uses scale transforms of -1.

TypeRequired
[boolean]No

ItemSeparatorComponent

Rendered in between each item, but not at the top or bottom. By default, highlighted, section, and [leading/trailing][Item/Section] props are provided. renderItem provides separators.highlight/unhighlight which will update the highlighted prop, but you can also add custom props with separators.updateProps.

TypeRequired
[component, element]No

keyExtractor

Used to extract a unique key for a given item at the specified index. Key is used for caching and as the React key to track item re-ordering. The default extractor checks item.key, then falls back to using the index, like React does. Note that this sets keys for each item, but each overall section still needs its own key.

TypeRequired
(item: Item, index: number) => stringYes

legacyImplementation

The legacy implementation is no longer supported.

TypeRequired
[boolean]No

ListEmptyComponent

Rendered when the list is empty. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
[component, element]No

ListFooterComponent

Rendered at the very end of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
[component, element]No

ListHeaderComponent

Rendered at the very beginning of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
component, elementNo

onEndReached

Called once when the scroll position gets within onEndReachedThreshold of the rendered content.

TypeRequired
[(info: {distanceFromEnd: number}) => void]No

onEndReachedThreshold

How far from the end (in units of visible length of the list) the bottom edge of the list must be from the end of the content to trigger the onEndReached callback. Thus a value of 0.5 will trigger onEndReached when the end of the content is within half the visible length of the list.

TypeRequired
[number]No

onRefresh

If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the refreshing prop correctly. To offset the RefreshControl from the top (e.g. by 100 pts), use progressViewOffset={100}.

TypeRequired
[() => void]No

onViewableItemsChanged

Called when the viewability of rows changes, as defined by the viewabilityConfig prop.

TypeRequired
functionNo

The function will be passed an object with the following keys:

  • 'viewableItems' (array of ViewTokens)
  • 'changed' (array of ViewTokens)

The ViewToken type is exported by ViewabilityHelper.js:

NameTypeRequired
itemanyYes
keystringYes
indexnumberNo
isViewablebooleanYes
sectionanyNo

refreshing

Set this true while waiting for new data from a refresh.

TypeRequired
[boolean]No

removeClippedSubviews

Note: may have bugs (missing content) in some circumstances - use at your own risk.

This may improve scroll performance for large lists.

TypeRequired
booleanNo

renderSectionFooter

Rendered at the bottom of each section.

TypeRequired
[(info: {section: SectionT}) => ?React.Element<any>]No

renderSectionHeader

Rendered at the top of each section. These stick to the top of the ScrollView by default on iOS. See stickySectionHeadersEnabled.

TypeRequired
[(info: {section: SectionT}) => ?React.Element<any>]No

SectionSeparatorComponent

Rendered at the top and bottom of each section (note this is different from ItemSeparatorComponent which is only rendered between items). These are intended to separate sections from the headers above and below and typically have the same highlight response as ItemSeparatorComponent. Also receives highlighted, [leading/trailing][Item/Section], and any custom props from separators.updateProps.

TypeRequired
[ReactClass<any>]No

stickySectionHeadersEnabled

Makes section headers stick to the top of the screen until the next one pushes it off. Only enabled by default on iOS because that is the platform standard there.

TypeRequired
booleanNo

Methods

scrollToLocation()

scrollToLocation(params);

Scrolls to the item at the specified sectionIndex and itemIndex (within the section) positioned in the viewable area such that viewPosition 0 places it at the top (and may be covered by a sticky header), 1 at the bottom, and 0.5 centered in the middle.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout or onScrollToIndexFailed prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.
  • 'itemIndex' (number) - Index within section for the item to scroll to. Required.
  • 'sectionIndex' (number) - Index for section that contains the item to scroll to. Required.
  • 'viewOffset' (number) - A fixed number of pixels to offset the final target position, e.g. to compensate for sticky headers.
  • 'viewPosition' (number) - A value of 0 places the item specified by index at the top, 1 at the bottom, and 0.5 centered in the middle.

recordInteraction()

recordInteraction();

Tells the list an interaction has occurred, 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()

flashScrollIndicators();

Displays the scroll indicators momentarily.

Platfrom
iOS

Type Definitions

Section

An object that identifies the data to be rendered for a given section.

Type
any

Properties:

NameTypeDescription
dataarrayThe data for rendering items in this section. Array of objects, much like FlatList's data prop.
[key]stringOptional key to keep track of section re-ordering. If you don't plan on re-ordering sections, the array index will be used by default.
[renderItem]functionOptionally define an arbitrary item renderer for this section, overriding the default renderItem for the list.
[ItemSeparatorComponent]component, elementOptionally define an arbitrary item separator for this section, overriding the default ItemSeparatorComponent for the list.
[keyExtractor]functionOptionally define an arbitrary key extractor for this section, overriding the default keyExtractor.
Edit this page
Last updated on
- + diff --git a/docs/0.61/sectionlist/index.html b/docs/0.61/sectionlist/index.html index 49bc057d038..dc4d342cc74 100644 --- a/docs/0.61/sectionlist/index.html +++ b/docs/0.61/sectionlist/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

SectionList

A performant interface for rendering sectioned lists, supporting the most handy features:

  • Fully cross-platform.
  • Configurable viewability callbacks.
  • List header support.
  • List footer support.
  • Item separator support.
  • Section header support.
  • Section separator support.
  • Heterogeneous data and item rendering support.
  • Pull to Refresh.
  • Scroll loading.

If you don't need section support and want a simpler interface, use <FlatList>.

Example

This is a convenience wrapper around <VirtualizedList>, and thus inherits its props (as well as those of <ScrollView> that aren't explicitly listed here, along with the following caveats:

  • Internal state is not preserved when content scrolls out of the render window. Make sure all your data is captured in the item data or external stores like Flux, Redux, or Relay.
  • This is a PureComponent which means that it will not re-render if props remain shallow-equal. Make sure that everything your renderItem function depends on is passed as a prop (e.g. extraData) that is not === after updates, otherwise your UI may not update on changes. This includes the data prop and parent component state.
  • In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate and momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application, and we are working on improving it behind the scenes.
  • By default, the list looks for a key prop on each item and uses that for the React key. Alternatively, you can provide a custom keyExtractor prop.

Props

Required props:

Optional props:

Methods

Type Definitions

Reference

Props

renderItem

Default renderer for every item in every section. Can be over-ridden on a per-section basis. Should return a React element.

TypeRequired
functionYes

The render function will be passed an object with the following keys:

  • 'item' (object) - the item object as specified in this section's data key
  • 'index' (number) - Item's index within the section.
  • 'section' (object) - The full section object as specified in sections.
  • 'separators' (object) - An object with the following keys:
    • 'highlight' (function) - () => void
    • 'unhighlight' (function) - () => void
    • 'updateProps' (function) - (select, newProps) => void
      • 'select' (enum) - possible values are 'leading', 'trailing'
      • 'newProps' (object)

sections

The actual data to render, akin to the data prop in FlatList.

TypeRequired
array of SectionsYes

extraData

A marker property for telling the list to re-render (since it implements PureComponent). If any of your renderItem, Header, Footer, etc. functions depend on anything outside of the data prop, stick it here and treat it immutably.

TypeRequired
anyNo

initialNumToRender

How many items to render in the initial batch. This should be enough to fill the screen but not much more. Note these items will never be unmounted as part of the windowed rendering in order to improve perceived performance of scroll-to-top actions.

TypeRequired
numberYes

inverted

Reverses the direction of scroll. Uses scale transforms of -1.

TypeRequired
[boolean]No

ItemSeparatorComponent

Rendered in between each item, but not at the top or bottom. By default, highlighted, section, and [leading/trailing][Item/Section] props are provided. renderItem provides separators.highlight/unhighlight which will update the highlighted prop, but you can also add custom props with separators.updateProps.

TypeRequired
[component, element]No

keyExtractor

Used to extract a unique key for a given item at the specified index. Key is used for caching and as the React key to track item re-ordering. The default extractor checks item.key, then falls back to using the index, like React does. Note that this sets keys for each item, but each overall section still needs its own key.

TypeRequired
(item: Item, index: number) => stringYes

legacyImplementation

The legacy implementation is no longer supported.

TypeRequired
[boolean]No

ListEmptyComponent

Rendered when the list is empty. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
[component, element]No

ListFooterComponent

Rendered at the very end of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
[component, element]No

ListHeaderComponent

Rendered at the very beginning of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
component, elementNo

onEndReached

Called once when the scroll position gets within onEndReachedThreshold of the rendered content.

TypeRequired
[(info: {distanceFromEnd: number}) => void]No

onEndReachedThreshold

How far from the end (in units of visible length of the list) the bottom edge of the list must be from the end of the content to trigger the onEndReached callback. Thus a value of 0.5 will trigger onEndReached when the end of the content is within half the visible length of the list.

TypeRequired
[number]No

onRefresh

If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the refreshing prop correctly. To offset the RefreshControl from the top (e.g. by 100 pts), use progressViewOffset={100}.

TypeRequired
[() => void]No

onViewableItemsChanged

Called when the viewability of rows changes, as defined by the viewabilityConfig prop.

TypeRequired
functionNo

The function will be passed an object with the following keys:

  • 'viewableItems' (array of ViewTokens)
  • 'changed' (array of ViewTokens)

The ViewToken type is exported by ViewabilityHelper.js:

NameTypeRequired
itemanyYes
keystringYes
indexnumberNo
isViewablebooleanYes
sectionanyNo

refreshing

Set this true while waiting for new data from a refresh.

TypeRequired
[boolean]No

removeClippedSubviews

Note: may have bugs (missing content) in some circumstances - use at your own risk.

This may improve scroll performance for large lists.

TypeRequired
booleanNo

renderSectionFooter

Rendered at the bottom of each section.

TypeRequired
[(info: {section: SectionT}) => ?React.Element<any>]No

renderSectionHeader

Rendered at the top of each section. These stick to the top of the ScrollView by default on iOS. See stickySectionHeadersEnabled.

TypeRequired
[(info: {section: SectionT}) => ?React.Element<any>]No

SectionSeparatorComponent

Rendered at the top and bottom of each section (note this is different from ItemSeparatorComponent which is only rendered between items). These are intended to separate sections from the headers above and below and typically have the same highlight response as ItemSeparatorComponent. Also receives highlighted, [leading/trailing][Item/Section], and any custom props from separators.updateProps.

TypeRequired
[ReactClass<any>]No

stickySectionHeadersEnabled

Makes section headers stick to the top of the screen until the next one pushes it off. Only enabled by default on iOS because that is the platform standard there.

TypeRequired
booleanNo

Methods

scrollToLocation()

scrollToLocation(params);

Scrolls to the item at the specified sectionIndex and itemIndex (within the section) positioned in the viewable area such that viewPosition 0 places it at the top (and may be covered by a sticky header), 1 at the bottom, and 0.5 centered in the middle.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout or onScrollToIndexFailed prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.
  • 'itemIndex' (number) - Index within section for the item to scroll to. Required.
  • 'sectionIndex' (number) - Index for section that contains the item to scroll to. Required.
  • 'viewOffset' (number) - A fixed number of pixels to offset the final target position, e.g. to compensate for sticky headers.
  • 'viewPosition' (number) - A value of 0 places the item specified by index at the top, 1 at the bottom, and 0.5 centered in the middle.

recordInteraction()

recordInteraction();

Tells the list an interaction has occurred, 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()

flashScrollIndicators();

Displays the scroll indicators momentarily.

Platfrom
iOS

Type Definitions

Section

An object that identifies the data to be rendered for a given section.

Type
any

Properties:

NameTypeDescription
dataarrayThe data for rendering items in this section. Array of objects, much like FlatList's data prop.
[key]stringOptional key to keep track of section re-ordering. If you don't plan on re-ordering sections, the array index will be used by default.
[renderItem]functionOptionally define an arbitrary item renderer for this section, overriding the default renderItem for the list.
[ItemSeparatorComponent]component, elementOptionally define an arbitrary item separator for this section, overriding the default ItemSeparatorComponent for the list.
[keyExtractor]functionOptionally define an arbitrary key extractor for this section, overriding the default keyExtractor.
Edit this page
Last updated on
- + diff --git a/docs/0.61/segmentedcontrolios.html b/docs/0.61/segmentedcontrolios.html index e36be123917..8d039c661f9 100644 --- a/docs/0.61/segmentedcontrolios.html +++ b/docs/0.61/segmentedcontrolios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 SegmentedControlIOS

Deprecated. Use @react-native-community/segmented-control instead.

Uses SegmentedControlIOS to render a UISegmentedControl iOS.

Programmatically changing selected index

The selected index can be changed on the fly by assigning the selectedIndex prop to a state variable, then changing that variable. Note that the state variable would need to be updated as the user selects a value and changes the index, as shown in the example below.

Example

Reference

Props

Inherits View Props.

enabled

If false the user won't be able to interact with the control. Default value is true.

TypeRequired
boolNo

momentary

If true, then selecting a segment won't persist visually. The onValueChange callback will still work as expected.

TypeRequired
boolNo

onChange

Callback that is called when the user taps a segment; passes the event as an argument

TypeRequired
functionNo

onValueChange

Callback that is called when the user taps a segment; passes the segment's value as an argument

TypeRequired
functionNo

selectedIndex

The index in props.values of the segment to be (pre)selected.

TypeRequired
numberNo

tintColor

Accent color of the control.

TypeRequired
stringNo

values

The labels for the control's segment buttons, in order.

TypeRequired
array of stringNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/segmentedcontrolios/index.html b/docs/0.61/segmentedcontrolios/index.html index e36be123917..8d039c661f9 100644 --- a/docs/0.61/segmentedcontrolios/index.html +++ b/docs/0.61/segmentedcontrolios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 SegmentedControlIOS

Deprecated. Use @react-native-community/segmented-control instead.

Uses SegmentedControlIOS to render a UISegmentedControl iOS.

Programmatically changing selected index

The selected index can be changed on the fly by assigning the selectedIndex prop to a state variable, then changing that variable. Note that the state variable would need to be updated as the user selects a value and changes the index, as shown in the example below.

Example

Reference

Props

Inherits View Props.

enabled

If false the user won't be able to interact with the control. Default value is true.

TypeRequired
boolNo

momentary

If true, then selecting a segment won't persist visually. The onValueChange callback will still work as expected.

TypeRequired
boolNo

onChange

Callback that is called when the user taps a segment; passes the event as an argument

TypeRequired
functionNo

onValueChange

Callback that is called when the user taps a segment; passes the segment's value as an argument

TypeRequired
functionNo

selectedIndex

The index in props.values of the segment to be (pre)selected.

TypeRequired
numberNo

tintColor

Accent color of the control.

TypeRequired
stringNo

values

The labels for the control's segment buttons, in order.

TypeRequired
array of stringNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/settings.html b/docs/0.61/settings.html index dbcc03478be..a7b5663b4c7 100644 --- a/docs/0.61/settings.html +++ b/docs/0.61/settings.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Settings

Settings serves as a wrapper for NSUserDefaults, a persistent key-value store available only on iOS.

Reference

Methods

clearWatch()

static clearWatch(watchId)

watchId is the number returned by watchKeys() when the subscription was originally configured.

get()

static get(key)

Get the current value for a key in NSUserDefaults.

set()

static set(settings)

Set one or more values in NSUserDefaults.

watchKeys()

static watchKeys(keys, callback)

Subscribe to be notified when the value for any of the keys specified by the keys array changes in NSUserDefaults. Returns a watchId number that may be used with clearWatch() to unsubscribe.

Edit this page
Last updated on
- + diff --git a/docs/0.61/settings/index.html b/docs/0.61/settings/index.html index dbcc03478be..a7b5663b4c7 100644 --- a/docs/0.61/settings/index.html +++ b/docs/0.61/settings/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Settings

Settings serves as a wrapper for NSUserDefaults, a persistent key-value store available only on iOS.

Reference

Methods

clearWatch()

static clearWatch(watchId)

watchId is the number returned by watchKeys() when the subscription was originally configured.

get()

static get(key)

Get the current value for a key in NSUserDefaults.

set()

static set(settings)

Set one or more values in NSUserDefaults.

watchKeys()

static watchKeys(keys, callback)

Subscribe to be notified when the value for any of the keys specified by the keys array changes in NSUserDefaults. Returns a watchId number that may be used with clearWatch() to unsubscribe.

Edit this page
Last updated on
- + diff --git a/docs/0.61/shadow-props.html b/docs/0.61/shadow-props.html index 303eee77092..98ab81d25b2 100644 --- a/docs/0.61/shadow-props.html +++ b/docs/0.61/shadow-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Shadow Props

Reference

Props

shadowColor

Sets the drop shadow color

TypeRequiredPlatform
colorNoiOS

shadowOffset

Sets the drop shadow offset

TypeRequiredPlatform
object: {width: number,height: number}NoiOS

shadowOpacity

Sets the drop shadow opacity (multiplied by the color's alpha component)

TypeRequiredPlatform
numberNoiOS

shadowRadius

Sets the drop shadow blur radius

TypeRequiredPlatform
numberNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.61/shadow-props/index.html b/docs/0.61/shadow-props/index.html index 303eee77092..98ab81d25b2 100644 --- a/docs/0.61/shadow-props/index.html +++ b/docs/0.61/shadow-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Shadow Props

Reference

Props

shadowColor

Sets the drop shadow color

TypeRequiredPlatform
colorNoiOS

shadowOffset

Sets the drop shadow offset

TypeRequiredPlatform
object: {width: number,height: number}NoiOS

shadowOpacity

Sets the drop shadow opacity (multiplied by the color's alpha component)

TypeRequiredPlatform
numberNoiOS

shadowRadius

Sets the drop shadow blur radius

TypeRequiredPlatform
numberNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.61/share.html b/docs/0.61/share.html index 5d930bc4c11..7b8eb887fb6 100644 --- a/docs/0.61/share.html +++ b/docs/0.61/share.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
render() {
return <Button onPress={this.onShare} title="Share" />;
}
}
Edit this page
Last updated on
- + diff --git a/docs/0.61/share/index.html b/docs/0.61/share/index.html index 5d930bc4c11..7b8eb887fb6 100644 --- a/docs/0.61/share/index.html +++ b/docs/0.61/share/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
render() {
return <Button onPress={this.onShare} title="Share" />;
}
}
Edit this page
Last updated on
- + diff --git a/docs/0.61/signed-apk-android.html b/docs/0.61/signed-apk-android.html index 545eb572716..00ca662c2ba 100644 --- a/docs/0.61/signed-apk-android.html +++ b/docs/0.61/signed-apk-android.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Publishing to Google Play Store

Android requires that all apps be digitally signed with a certificate before they can be installed. In order to distribute your Android application via Google Play store it needs to be signed with a release key that then needs to be used for all future updates. Since 2017 it is possible for Google Play to manage signing releases automatically thanks to App Signing by Google Play functionality. However, before your application binary is uploaded to Google Play it needs to be signed with an upload key. The Signing Your Applications page on Android Developers documentation describes the topic in detail. This guide covers the process in brief, as well as lists the steps required to package the JavaScript bundle.

Generating an upload key

You can generate a private signing key using keytool. On Windows keytool must be run from C:\Program Files\Java\jdkx.x.x_x\bin.

$ keytool -genkeypair -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

This command prompts you for passwords for the keystore and key and for the Distinguished Name fields for your key. It then generates the keystore as a file called my-upload-key.keystore.

The keystore contains a single key, valid for 10000 days. The alias is a name that you will use later when signing your app, so remember to take note of the alias.

On Mac, if you're not sure where your JDK bin folder is, then perform the following command to find it:

$ /usr/libexec/java_home

It will output the directory of the JDK, which will look something like this:

/Library/Java/JavaVirtualMachines/jdkX.X.X_XXX.jdk/Contents/Home

Navigate to that directory by using the command $ cd /your/jdk/path and use the keytool command with sudo permission as shown below.

$ sudo keytool -genkey -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

Note: Remember to keep the keystore file private. In case you've lost upload key or it's been compromised you should follow these instructions.

Setting up Gradle variables

  1. Place the my-upload-key.keystore file under the android/app directory in your project folder.
  2. Edit the file ~/.gradle/gradle.properties or android/gradle.properties, and add the following (replace ***** with the correct keystore password, alias and key password),
MYAPP_UPLOAD_STORE_FILE=my-upload-key.keystore
MYAPP_UPLOAD_KEY_ALIAS=my-key-alias
MYAPP_UPLOAD_STORE_PASSWORD=*****
MYAPP_UPLOAD_KEY_PASSWORD=*****

These are going to be global Gradle variables, which we can later use in our Gradle config to sign our app.

Note about security: If you are not keen on storing your passwords in plaintext, and you are running OSX, you can also store your credentials in the Keychain Access app. Then you can skip the two last rows in ~/.gradle/gradle.properties.

Adding signing config to your app's Gradle config

The last configuration step that needs to be done is to setup release builds to be signed using upload key. Edit the file android/app/build.gradle in your project folder, and add the signing config,

...
android {
...
defaultConfig { ... }
signingConfigs {
release {
if (project.hasProperty('MYAPP_UPLOAD_STORE_FILE')) {
storeFile file(MYAPP_UPLOAD_STORE_FILE)
storePassword MYAPP_UPLOAD_STORE_PASSWORD
keyAlias MYAPP_UPLOAD_KEY_ALIAS
keyPassword MYAPP_UPLOAD_KEY_PASSWORD
}
}
}
buildTypes {
release {
...
signingConfig signingConfigs.release
}
}
}
...

Generating the release APK

Run the following in a terminal:

$ cd android
$ ./gradlew bundleRelease

Gradle's bundleRelease will bundle all the JavaScript needed to run your app into the AAB (Android App Bundle). If you need to change the way the JavaScript bundle and/or drawable resources are bundled (e.g. if you changed the default file/folder names or the general structure of the project), have a look at android/app/build.gradle to see how you can update it to reflect these changes.

Note: Make sure gradle.properties does not include org.gradle.configureondemand=true as that will make the release build skip bundling JS and assets into the app binary.

The generated AAB can be found under android/app/build/outputs/bundle/release/app.aab, and is ready to be uploaded to Google Play.

Note: In order for Google Play to accept AAB format the App Signing by Google Play needs to be configured for your application on the Google Play Console. If you are updating an existing app that doesn't use App Signing by Google Play, please check our migration section to learn how to perform that configuration change.

Testing the release build of your app

Before uploading the release build to the Play Store, make sure you test it thoroughly. First uninstall any previous version of the app you already have installed. Install it on the device using:

$ react-native run-android --variant=release

Note that --variant=release is only available if you've set up signing as described above.

You can terminate any running bundler instances, since all your framework and JavaScript code is bundled in the APK's assets.

Publishing to other stores

By default, the generated APK has the native code for both x86 and ARMv7a CPU architectures. This makes it easier to share APKs that run on almost all Android devices. However, this has the downside that there will be some unused native code on any device, leading to unnecessarily bigger APKs.

You can create an APK for each CPU by changing the following line in android/app/build.gradle:

- ndk {
- abiFilters "armeabi-v7a", "x86"
- }
- def enableSeparateBuildPerCPUArchitecture = false
+ def enableSeparateBuildPerCPUArchitecture = true

Upload both these files to markets which support device targeting, such as Google Play and Amazon AppStore, and the users will automatically get the appropriate APK. If you want to upload to other markets, such as APKFiles, which do not support multiple APKs for a single app, change the following line as well to create the default universal APK with binaries for both CPUs.

- universalApk false // If true, also generate a universal APK
+ universalApk true // If true, also generate a universal APK

Enabling Proguard to reduce the size of the APK (optional)

Proguard is a tool that can slightly reduce the size of the APK. It does this by stripping parts of the React Native Java bytecode (and its dependencies) that your app is not using.

IMPORTANT: Make sure to thoroughly test your app if you've enabled Proguard. Proguard often requires configuration specific to each native library you're using. See app/proguard-rules.pro.

To enable Proguard, edit android/app/build.gradle:

/**
* Run Proguard to shrink the Java bytecode in release builds.
*/
def enableProguardInReleaseBuilds = true

Migrating old Android React Native apps to use App Signing by Google Play

If you are migrating from previous version of React Native chances are your app does not use App Signing by Google Play feature. We recommend you enable that in order to take advantage from things like automatic app splitting. In order to migrate from the old way of signing you need to start by generating new upload key and then replacing release signing config in android/app/build.gradle to use the upload key instead of the release one (see section about adding signing config to gradle). Once that's done you should follow the instructions from Google Play Help website in order to send your original release key to Google Play.

Edit this page
Last updated on
- + diff --git a/docs/0.61/signed-apk-android/index.html b/docs/0.61/signed-apk-android/index.html index 545eb572716..00ca662c2ba 100644 --- a/docs/0.61/signed-apk-android/index.html +++ b/docs/0.61/signed-apk-android/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Publishing to Google Play Store

Android requires that all apps be digitally signed with a certificate before they can be installed. In order to distribute your Android application via Google Play store it needs to be signed with a release key that then needs to be used for all future updates. Since 2017 it is possible for Google Play to manage signing releases automatically thanks to App Signing by Google Play functionality. However, before your application binary is uploaded to Google Play it needs to be signed with an upload key. The Signing Your Applications page on Android Developers documentation describes the topic in detail. This guide covers the process in brief, as well as lists the steps required to package the JavaScript bundle.

Generating an upload key

You can generate a private signing key using keytool. On Windows keytool must be run from C:\Program Files\Java\jdkx.x.x_x\bin.

$ keytool -genkeypair -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

This command prompts you for passwords for the keystore and key and for the Distinguished Name fields for your key. It then generates the keystore as a file called my-upload-key.keystore.

The keystore contains a single key, valid for 10000 days. The alias is a name that you will use later when signing your app, so remember to take note of the alias.

On Mac, if you're not sure where your JDK bin folder is, then perform the following command to find it:

$ /usr/libexec/java_home

It will output the directory of the JDK, which will look something like this:

/Library/Java/JavaVirtualMachines/jdkX.X.X_XXX.jdk/Contents/Home

Navigate to that directory by using the command $ cd /your/jdk/path and use the keytool command with sudo permission as shown below.

$ sudo keytool -genkey -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

Note: Remember to keep the keystore file private. In case you've lost upload key or it's been compromised you should follow these instructions.

Setting up Gradle variables

  1. Place the my-upload-key.keystore file under the android/app directory in your project folder.
  2. Edit the file ~/.gradle/gradle.properties or android/gradle.properties, and add the following (replace ***** with the correct keystore password, alias and key password),
MYAPP_UPLOAD_STORE_FILE=my-upload-key.keystore
MYAPP_UPLOAD_KEY_ALIAS=my-key-alias
MYAPP_UPLOAD_STORE_PASSWORD=*****
MYAPP_UPLOAD_KEY_PASSWORD=*****

These are going to be global Gradle variables, which we can later use in our Gradle config to sign our app.

Note about security: If you are not keen on storing your passwords in plaintext, and you are running OSX, you can also store your credentials in the Keychain Access app. Then you can skip the two last rows in ~/.gradle/gradle.properties.

Adding signing config to your app's Gradle config

The last configuration step that needs to be done is to setup release builds to be signed using upload key. Edit the file android/app/build.gradle in your project folder, and add the signing config,

...
android {
...
defaultConfig { ... }
signingConfigs {
release {
if (project.hasProperty('MYAPP_UPLOAD_STORE_FILE')) {
storeFile file(MYAPP_UPLOAD_STORE_FILE)
storePassword MYAPP_UPLOAD_STORE_PASSWORD
keyAlias MYAPP_UPLOAD_KEY_ALIAS
keyPassword MYAPP_UPLOAD_KEY_PASSWORD
}
}
}
buildTypes {
release {
...
signingConfig signingConfigs.release
}
}
}
...

Generating the release APK

Run the following in a terminal:

$ cd android
$ ./gradlew bundleRelease

Gradle's bundleRelease will bundle all the JavaScript needed to run your app into the AAB (Android App Bundle). If you need to change the way the JavaScript bundle and/or drawable resources are bundled (e.g. if you changed the default file/folder names or the general structure of the project), have a look at android/app/build.gradle to see how you can update it to reflect these changes.

Note: Make sure gradle.properties does not include org.gradle.configureondemand=true as that will make the release build skip bundling JS and assets into the app binary.

The generated AAB can be found under android/app/build/outputs/bundle/release/app.aab, and is ready to be uploaded to Google Play.

Note: In order for Google Play to accept AAB format the App Signing by Google Play needs to be configured for your application on the Google Play Console. If you are updating an existing app that doesn't use App Signing by Google Play, please check our migration section to learn how to perform that configuration change.

Testing the release build of your app

Before uploading the release build to the Play Store, make sure you test it thoroughly. First uninstall any previous version of the app you already have installed. Install it on the device using:

$ react-native run-android --variant=release

Note that --variant=release is only available if you've set up signing as described above.

You can terminate any running bundler instances, since all your framework and JavaScript code is bundled in the APK's assets.

Publishing to other stores

By default, the generated APK has the native code for both x86 and ARMv7a CPU architectures. This makes it easier to share APKs that run on almost all Android devices. However, this has the downside that there will be some unused native code on any device, leading to unnecessarily bigger APKs.

You can create an APK for each CPU by changing the following line in android/app/build.gradle:

- ndk {
- abiFilters "armeabi-v7a", "x86"
- }
- def enableSeparateBuildPerCPUArchitecture = false
+ def enableSeparateBuildPerCPUArchitecture = true

Upload both these files to markets which support device targeting, such as Google Play and Amazon AppStore, and the users will automatically get the appropriate APK. If you want to upload to other markets, such as APKFiles, which do not support multiple APKs for a single app, change the following line as well to create the default universal APK with binaries for both CPUs.

- universalApk false // If true, also generate a universal APK
+ universalApk true // If true, also generate a universal APK

Enabling Proguard to reduce the size of the APK (optional)

Proguard is a tool that can slightly reduce the size of the APK. It does this by stripping parts of the React Native Java bytecode (and its dependencies) that your app is not using.

IMPORTANT: Make sure to thoroughly test your app if you've enabled Proguard. Proguard often requires configuration specific to each native library you're using. See app/proguard-rules.pro.

To enable Proguard, edit android/app/build.gradle:

/**
* Run Proguard to shrink the Java bytecode in release builds.
*/
def enableProguardInReleaseBuilds = true

Migrating old Android React Native apps to use App Signing by Google Play

If you are migrating from previous version of React Native chances are your app does not use App Signing by Google Play feature. We recommend you enable that in order to take advantage from things like automatic app splitting. In order to migrate from the old way of signing you need to start by generating new upload key and then replacing release signing config in android/app/build.gradle to use the upload key instead of the release one (see section about adding signing config to gradle). Once that's done you should follow the instructions from Google Play Help website in order to send your original release key to Google Play.

Edit this page
Last updated on
- + diff --git a/docs/0.61/slider.html b/docs/0.61/slider.html index 783b39f5828..b8ff24c0264 100644 --- a/docs/0.61/slider.html +++ b/docs/0.61/slider.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 Slider

Deprecated. Use react-native-community/react-native-slider instead.

A component used to select a single value from a range of values.

Reference

Props

Inherits View Props.

style

Used to style and layout the Slider. See StyleSheet.js and ViewStylePropTypes.js for more info.

TypeRequired
View.styleNo

disabled

If true the user won't be able to move the slider. Default value is false.

TypeRequired
boolNo

maximumValue

Initial maximum value of the slider. Default value is 1.

TypeRequired
numberNo

minimumTrackTintColor

The color used for the track to the left of the button. Overrides the default blue gradient image on iOS.

TypeRequired
colorNo

minimumValue

Initial minimum value of the slider. Default value is 0.

TypeRequired
numberNo

onSlidingComplete

Callback that is called when the user releases the slider, regardless if the value has changed. The current value is passed as an argument to the callback handler.

TypeRequired
functionNo

onValueChange

Callback continuously called while the user is dragging the slider.

TypeRequired
functionNo

step

Step value of the slider. The value should be between 0 and (maximumValue - minimumValue). Default value is 0.

TypeRequired
numberNo

maximumTrackTintColor

The color used for the track to the right of the button. Overrides the default gray gradient image on iOS.

TypeRequired
colorNo

testID

Used to locate this view in UI automation tests.

TypeRequired
stringNo

value

Initial value of the slider. The value should be between minimumValue and maximumValue, which default to 0 and 1 respectively. Default value is 0.

This is not a controlled component, you don't need to update the value during dragging.

TypeRequired
numberNo

thumbTintColor

The color used to tint the default thumb images on iOS, or the color of the foreground switch grip on Android.

TypeRequired
colorNo

maximumTrackImage

Assigns a maximum track image. Only static images are supported. The leftmost pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

minimumTrackImage

Assigns a minimum track image. Only static images are supported. The rightmost pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

thumbImage

Sets an image for the thumb. Only static images are supported.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

trackImage

Assigns a single image for the track. Only static images are supported. The center pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.61/slider/index.html b/docs/0.61/slider/index.html index 783b39f5828..b8ff24c0264 100644 --- a/docs/0.61/slider/index.html +++ b/docs/0.61/slider/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 Slider

Deprecated. Use react-native-community/react-native-slider instead.

A component used to select a single value from a range of values.

Reference

Props

Inherits View Props.

style

Used to style and layout the Slider. See StyleSheet.js and ViewStylePropTypes.js for more info.

TypeRequired
View.styleNo

disabled

If true the user won't be able to move the slider. Default value is false.

TypeRequired
boolNo

maximumValue

Initial maximum value of the slider. Default value is 1.

TypeRequired
numberNo

minimumTrackTintColor

The color used for the track to the left of the button. Overrides the default blue gradient image on iOS.

TypeRequired
colorNo

minimumValue

Initial minimum value of the slider. Default value is 0.

TypeRequired
numberNo

onSlidingComplete

Callback that is called when the user releases the slider, regardless if the value has changed. The current value is passed as an argument to the callback handler.

TypeRequired
functionNo

onValueChange

Callback continuously called while the user is dragging the slider.

TypeRequired
functionNo

step

Step value of the slider. The value should be between 0 and (maximumValue - minimumValue). Default value is 0.

TypeRequired
numberNo

maximumTrackTintColor

The color used for the track to the right of the button. Overrides the default gray gradient image on iOS.

TypeRequired
colorNo

testID

Used to locate this view in UI automation tests.

TypeRequired
stringNo

value

Initial value of the slider. The value should be between minimumValue and maximumValue, which default to 0 and 1 respectively. Default value is 0.

This is not a controlled component, you don't need to update the value during dragging.

TypeRequired
numberNo

thumbTintColor

The color used to tint the default thumb images on iOS, or the color of the foreground switch grip on Android.

TypeRequired
colorNo

maximumTrackImage

Assigns a maximum track image. Only static images are supported. The leftmost pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

minimumTrackImage

Assigns a minimum track image. Only static images are supported. The rightmost pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

thumbImage

Sets an image for the thumb. Only static images are supported.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

trackImage

Assigns a single image for the track. Only static images are supported. The center pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.61/snapshotviewios.html b/docs/0.61/snapshotviewios.html index 92eada73690..2a3d1fef24d 100644 --- a/docs/0.61/snapshotviewios.html +++ b/docs/0.61/snapshotviewios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.61/snapshotviewios/index.html b/docs/0.61/snapshotviewios/index.html index 92eada73690..2a3d1fef24d 100644 --- a/docs/0.61/snapshotviewios/index.html +++ b/docs/0.61/snapshotviewios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.61/state.html b/docs/0.61/state.html index facf3a20f40..875a3a1a0f7 100644 --- a/docs/0.61/state.html +++ b/docs/0.61/state.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

State

There are two types of data that control a component: props and state. props are set by the parent and they are fixed throughout the lifetime of a component. For data that is going to change, we have to use state.

In general, you should initialize state in the constructor, and then call setState when you want to change it.

For example, let's say we want to make text that blinks all the time. The text itself gets set once when the blinking component gets created, so the text itself is a prop. The "whether the text is currently on or off" changes over time, so that should be kept in state.

In a real application, you probably won't be setting state with a timer. You might set state when you have new data from the server, or from user input. You can also use a state container like Redux or Mobx to control your data flow. In that case you would use Redux or Mobx to modify your state rather than calling setState directly.

When setState is called, BlinkApp will re-render its Component. By calling setState within the Timer, the component will re-render every time the Timer ticks.

State works the same way as it does in React, so for more details on handling state, you can look at the React.Component API. At this point, you might be annoyed that most of our examples so far use the default text color. To customize the text color, you will have to learn about Style.

Edit this page
Last updated on
- + diff --git a/docs/0.61/state/index.html b/docs/0.61/state/index.html index facf3a20f40..875a3a1a0f7 100644 --- a/docs/0.61/state/index.html +++ b/docs/0.61/state/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

State

There are two types of data that control a component: props and state. props are set by the parent and they are fixed throughout the lifetime of a component. For data that is going to change, we have to use state.

In general, you should initialize state in the constructor, and then call setState when you want to change it.

For example, let's say we want to make text that blinks all the time. The text itself gets set once when the blinking component gets created, so the text itself is a prop. The "whether the text is currently on or off" changes over time, so that should be kept in state.

In a real application, you probably won't be setting state with a timer. You might set state when you have new data from the server, or from user input. You can also use a state container like Redux or Mobx to control your data flow. In that case you would use Redux or Mobx to modify your state rather than calling setState directly.

When setState is called, BlinkApp will re-render its Component. By calling setState within the Timer, the component will re-render every time the Timer ticks.

State works the same way as it does in React, so for more details on handling state, you can look at the React.Component API. At this point, you might be annoyed that most of our examples so far use the default text color. To customize the text color, you will have to learn about Style.

Edit this page
Last updated on
- + diff --git a/docs/0.61/statusbar.html b/docs/0.61/statusbar.html index f3c5b207fbd..acfd432ad67 100644 --- a/docs/0.61/statusbar.html +++ b/docs/0.61/statusbar.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

StatusBar

Component to control the app status bar.

Usage with Navigator

It is possible to have multiple StatusBar components mounted at the same time. The props will be merged in the order the StatusBar components were mounted.

<View>
<StatusBar backgroundColor="blue" barStyle="light-content" />
<View>
<StatusBar hidden={route.statusBarHidden} />
...
</View>
</View>

Imperative API

For cases where using a component is not ideal, there is also an imperative API exposed as static functions on the component. It is however not recommended to use the static API and the component for the same prop because any value set by the static API will get overridden by the one set by the component in the next render.

Reference

Constants

currentHeight (Android only) The height of the status bar.

Props

animated

If the transition between status bar property changes should be animated. Supported for backgroundColor, barStyle and hidden.

TypeRequired
boolNo

backgroundColor

The background color of the status bar.

TypeRequiredPlatform
colorNoAndroid

barStyle

Sets the color of the status bar text.

TypeRequired
enum('default', 'light-content', 'dark-content')No

hidden

If the status bar is hidden.

TypeRequired
boolNo

networkActivityIndicatorVisible

If the network activity indicator should be visible.

TypeRequiredPlatform
boolNoiOS

showHideTransition

The transition effect when showing and hiding the status bar using the hidden prop. Defaults to 'fade'.

TypeRequiredPlatform
enum('fade', 'slide')NoiOS

translucent

If the status bar is translucent. When translucent is set to true, the app will draw under the status bar. This is useful when using a semi transparent status bar color.

TypeRequiredPlatform
boolNoAndroid

Methods

popStackEntry()

static popStackEntry(entry: any)

Get and remove the last a StatusBar entry from the stack.

Parameters:

NameTypeRequiredDescription
entryanyYesEntry returned from pushStackEntry.

pushStackEntry()

static pushStackEntry(props: any)

Push a StatusBar entry onto the stack. The return value should be passed to popStackEntry when complete.

Parameters:

NameTypeRequiredDescription
propsanyYesObject containing the StatusBar props to use in the stack entry.

replaceStackEntry()

static replaceStackEntry(entry: any, props: any)

Replace an existing StatusBar stack entry with new props.

Parameters:

NameTypeRequiredDescription
entryanyYesEntry returned from pushStackEntry to replace.
propsanyYesObject containing the StatusBar props to use in the replacement stack entry.

setBackgroundColor()

static setBackgroundColor(color: string, [animated]: boolean)

Set the background color for the status bar. Android-only

Parameters:

NameTypeRequiredDescription
colorstringYesBackground color.
animatedbooleanNoAnimate the style change.

setBarStyle()

static setBarStyle(style: StatusBarStyle, [animated]: boolean)

Set the status bar style

Parameters:

NameTypeRequiredDescription
styleStatusBarStyleYesStatus bar style to set
animatedbooleanNoAnimate the style change.

setHidden()

static setHidden(hidden: boolean, [animation]: StatusBarAnimation)

Show or hide the status bar

Parameters:

NameTypeRequiredDescription
hiddenbooleanYesHide the status bar.
animationStatusBarAnimationNoOptional animation when changing the status bar hidden property.

setNetworkActivityIndicatorVisible()

static setNetworkActivityIndicatorVisible(visible: boolean)

Control the visibility of the network activity indicator. iOS-only.

Parameters:

NameTypeRequiredDescription
visiblebooleanYesShow the indicator.

setTranslucent()

static setTranslucent(translucent: boolean)

Control the translucency of the status bar. Android-only.

Parameters:

NameTypeRequiredDescription
translucentbooleanYesSet as translucent.

Type Definitions

StatusBarAnimation

Status bar animation

Type
\$Enum

Constants:

ValueDescription
noneNo animation
fadeFade animation
slideSlide animation

StatusBarStyle

Status bar style

Type
\$Enum

Constants:

ValueDescription
defaultDefault status bar style (dark for iOS, light for Android)
light-contentDark background, white texts and icons
dark-contentLight background, dark texts and icons (requires API>=23 on Android)
Edit this page
Last updated on
- + diff --git a/docs/0.61/statusbar/index.html b/docs/0.61/statusbar/index.html index f3c5b207fbd..acfd432ad67 100644 --- a/docs/0.61/statusbar/index.html +++ b/docs/0.61/statusbar/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

StatusBar

Component to control the app status bar.

Usage with Navigator

It is possible to have multiple StatusBar components mounted at the same time. The props will be merged in the order the StatusBar components were mounted.

<View>
<StatusBar backgroundColor="blue" barStyle="light-content" />
<View>
<StatusBar hidden={route.statusBarHidden} />
...
</View>
</View>

Imperative API

For cases where using a component is not ideal, there is also an imperative API exposed as static functions on the component. It is however not recommended to use the static API and the component for the same prop because any value set by the static API will get overridden by the one set by the component in the next render.

Reference

Constants

currentHeight (Android only) The height of the status bar.

Props

animated

If the transition between status bar property changes should be animated. Supported for backgroundColor, barStyle and hidden.

TypeRequired
boolNo

backgroundColor

The background color of the status bar.

TypeRequiredPlatform
colorNoAndroid

barStyle

Sets the color of the status bar text.

TypeRequired
enum('default', 'light-content', 'dark-content')No

hidden

If the status bar is hidden.

TypeRequired
boolNo

networkActivityIndicatorVisible

If the network activity indicator should be visible.

TypeRequiredPlatform
boolNoiOS

showHideTransition

The transition effect when showing and hiding the status bar using the hidden prop. Defaults to 'fade'.

TypeRequiredPlatform
enum('fade', 'slide')NoiOS

translucent

If the status bar is translucent. When translucent is set to true, the app will draw under the status bar. This is useful when using a semi transparent status bar color.

TypeRequiredPlatform
boolNoAndroid

Methods

popStackEntry()

static popStackEntry(entry: any)

Get and remove the last a StatusBar entry from the stack.

Parameters:

NameTypeRequiredDescription
entryanyYesEntry returned from pushStackEntry.

pushStackEntry()

static pushStackEntry(props: any)

Push a StatusBar entry onto the stack. The return value should be passed to popStackEntry when complete.

Parameters:

NameTypeRequiredDescription
propsanyYesObject containing the StatusBar props to use in the stack entry.

replaceStackEntry()

static replaceStackEntry(entry: any, props: any)

Replace an existing StatusBar stack entry with new props.

Parameters:

NameTypeRequiredDescription
entryanyYesEntry returned from pushStackEntry to replace.
propsanyYesObject containing the StatusBar props to use in the replacement stack entry.

setBackgroundColor()

static setBackgroundColor(color: string, [animated]: boolean)

Set the background color for the status bar. Android-only

Parameters:

NameTypeRequiredDescription
colorstringYesBackground color.
animatedbooleanNoAnimate the style change.

setBarStyle()

static setBarStyle(style: StatusBarStyle, [animated]: boolean)

Set the status bar style

Parameters:

NameTypeRequiredDescription
styleStatusBarStyleYesStatus bar style to set
animatedbooleanNoAnimate the style change.

setHidden()

static setHidden(hidden: boolean, [animation]: StatusBarAnimation)

Show or hide the status bar

Parameters:

NameTypeRequiredDescription
hiddenbooleanYesHide the status bar.
animationStatusBarAnimationNoOptional animation when changing the status bar hidden property.

setNetworkActivityIndicatorVisible()

static setNetworkActivityIndicatorVisible(visible: boolean)

Control the visibility of the network activity indicator. iOS-only.

Parameters:

NameTypeRequiredDescription
visiblebooleanYesShow the indicator.

setTranslucent()

static setTranslucent(translucent: boolean)

Control the translucency of the status bar. Android-only.

Parameters:

NameTypeRequiredDescription
translucentbooleanYesSet as translucent.

Type Definitions

StatusBarAnimation

Status bar animation

Type
\$Enum

Constants:

ValueDescription
noneNo animation
fadeFade animation
slideSlide animation

StatusBarStyle

Status bar style

Type
\$Enum

Constants:

ValueDescription
defaultDefault status bar style (dark for iOS, light for Android)
light-contentDark background, white texts and icons
dark-contentLight background, dark texts and icons (requires API>=23 on Android)
Edit this page
Last updated on
- + diff --git a/docs/0.61/statusbarios.html b/docs/0.61/statusbarios.html index 38cdd7a9571..6fff7922257 100644 --- a/docs/0.61/statusbarios.html +++ b/docs/0.61/statusbarios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 StatusBarIOS

Deprecated. Use StatusBar for mutating the status bar.

Edit this page
Last updated on
- + diff --git a/docs/0.61/statusbarios/index.html b/docs/0.61/statusbarios/index.html index 38cdd7a9571..6fff7922257 100644 --- a/docs/0.61/statusbarios/index.html +++ b/docs/0.61/statusbarios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 StatusBarIOS

Deprecated. Use StatusBar for mutating the status bar.

Edit this page
Last updated on
- + diff --git a/docs/0.61/style.html b/docs/0.61/style.html index 8607169efba..06f058b1ffc 100644 --- a/docs/0.61/style.html +++ b/docs/0.61/style.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Style

With React Native, you style your application using JavaScript. All of the core components accept a prop named style. The style names and values usually match how CSS works on the web, except names are written using camel casing, e.g. backgroundColor rather than background-color.

The style prop can be a plain old JavaScript object. That's the simplest and what we usually use for example code. You can also pass an array of styles - the last style in the array has precedence, so you can use this to inherit styles.

As a component grows in complexity, it is often cleaner to use StyleSheet.create to define several styles in one place. Here's an example:

One common pattern is to make your component accept a style prop which in turn is used to style subcomponents. You can use this to make styles "cascade" the way they do in CSS.

There are a lot more ways to customize text style. Check out the Text component reference for a complete list.

Now you can make your text beautiful. The next step in becoming a style expert is to learn how to control component size.

Edit this page
Last updated on
- + diff --git a/docs/0.61/style/index.html b/docs/0.61/style/index.html index 8607169efba..06f058b1ffc 100644 --- a/docs/0.61/style/index.html +++ b/docs/0.61/style/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Style

With React Native, you style your application using JavaScript. All of the core components accept a prop named style. The style names and values usually match how CSS works on the web, except names are written using camel casing, e.g. backgroundColor rather than background-color.

The style prop can be a plain old JavaScript object. That's the simplest and what we usually use for example code. You can also pass an array of styles - the last style in the array has precedence, so you can use this to inherit styles.

As a component grows in complexity, it is often cleaner to use StyleSheet.create to define several styles in one place. Here's an example:

One common pattern is to make your component accept a style prop which in turn is used to style subcomponents. You can use this to make styles "cascade" the way they do in CSS.

There are a lot more ways to customize text style. Check out the Text component reference for a complete list.

Now you can make your text beautiful. The next step in becoming a style expert is to learn how to control component size.

Edit this page
Last updated on
- + diff --git a/docs/0.61/stylesheet.html b/docs/0.61/stylesheet.html index bdb05bc4cf5..61a0c339cf3 100644 --- a/docs/0.61/stylesheet.html +++ b/docs/0.61/stylesheet.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
StyleSheet.flatten(styles.listItem);
// returns { flex: 1, fontSize: 16, color: 'white' }
// Simply styles.listItem would return its ID (number)

This method internally uses StyleSheetRegistry.getStyleByID(style) to resolve style objects represented by IDs. Thus, an array of style objects (instances of StyleSheet.create()), are individually resolved to, their respective objects, merged as one and then returned. This also explains the alternative use.

compose

Combines two styles such that style2 will override any styles in style1. If either style is falsy, the other one is returned without allocating an array, saving allocations and maintaining reference equality for PureComponent checks.

static compose(style1, style2)

Properties

hairlineWidth

This is defined as the width of a thin line on the platform. It can be used as the thickness of a border or division between two elements. Example:

var styles = StyleSheet.create({
separator: {
borderBottomColor: '#bbb',
borderBottomWidth: StyleSheet.hairlineWidth
}
});

This constant will always be a round number of pixels (so a line defined by it can look crisp) and will try to match the standard width of a thin line on the underlying platform. However, you should not rely on it being a constant size, because on different platforms and screen densities its value may be calculated differently.

A line with hairline width may not be visible if your simulator is downscaled.

absoluteFill

A very common pattern is to create overlays with position absolute and zero positioning (position: 'absolute', left: 0, right: 0, top: 0, bottom: 0), so absoluteFill can be used for convenience and to reduce duplication of these repeated styles. If you want, absoluteFill can be used to create a customized entry in a StyleSheet, e.g.:

const styles = StyleSheet.create({
wrapper: {
...StyleSheet.absoluteFill
}
});

absoluteFillObject

Sometimes you may want absoluteFill but with a couple tweaks - absoluteFillObject can be used to create a customized entry in a StyleSheet, e.g.:

const styles = StyleSheet.create({
wrapper: {
...StyleSheet.absoluteFillObject,
top: 10,
backgroundColor: 'transparent'
}
});

absoluteFill vs. absoluteFillObject

Currently, there is no difference between using absoluteFill vs. absoluteFillObject as you can see in the source code

Edit this page
Last updated on
- + diff --git a/docs/0.61/stylesheet/index.html b/docs/0.61/stylesheet/index.html index bdb05bc4cf5..61a0c339cf3 100644 --- a/docs/0.61/stylesheet/index.html +++ b/docs/0.61/stylesheet/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
StyleSheet.flatten(styles.listItem);
// returns { flex: 1, fontSize: 16, color: 'white' }
// Simply styles.listItem would return its ID (number)

This method internally uses StyleSheetRegistry.getStyleByID(style) to resolve style objects represented by IDs. Thus, an array of style objects (instances of StyleSheet.create()), are individually resolved to, their respective objects, merged as one and then returned. This also explains the alternative use.

compose

Combines two styles such that style2 will override any styles in style1. If either style is falsy, the other one is returned without allocating an array, saving allocations and maintaining reference equality for PureComponent checks.

static compose(style1, style2)

Properties

hairlineWidth

This is defined as the width of a thin line on the platform. It can be used as the thickness of a border or division between two elements. Example:

var styles = StyleSheet.create({
separator: {
borderBottomColor: '#bbb',
borderBottomWidth: StyleSheet.hairlineWidth
}
});

This constant will always be a round number of pixels (so a line defined by it can look crisp) and will try to match the standard width of a thin line on the underlying platform. However, you should not rely on it being a constant size, because on different platforms and screen densities its value may be calculated differently.

A line with hairline width may not be visible if your simulator is downscaled.

absoluteFill

A very common pattern is to create overlays with position absolute and zero positioning (position: 'absolute', left: 0, right: 0, top: 0, bottom: 0), so absoluteFill can be used for convenience and to reduce duplication of these repeated styles. If you want, absoluteFill can be used to create a customized entry in a StyleSheet, e.g.:

const styles = StyleSheet.create({
wrapper: {
...StyleSheet.absoluteFill
}
});

absoluteFillObject

Sometimes you may want absoluteFill but with a couple tweaks - absoluteFillObject can be used to create a customized entry in a StyleSheet, e.g.:

const styles = StyleSheet.create({
wrapper: {
...StyleSheet.absoluteFillObject,
top: 10,
backgroundColor: 'transparent'
}
});

absoluteFill vs. absoluteFillObject

Currently, there is no difference between using absoluteFill vs. absoluteFillObject as you can see in the source code

Edit this page
Last updated on
- + diff --git a/docs/0.61/switch.html b/docs/0.61/switch.html index ee913f97ccd..43db8fa5e71 100644 --- a/docs/0.61/switch.html +++ b/docs/0.61/switch.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Switch

Renders a boolean input.

This is a controlled component that requires an onValueChange callback that updates the value prop in order for the component to reflect user actions. If the value prop is not updated, the component will continue to render the supplied value prop instead of the expected result of any user actions.

Reference

Props

Inherits View Props.

disabled

If true the user won't be able to toggle the switch. Default value is false.

TypeRequired
boolNo

ios_backgroundColor

On iOS, custom color for the background. This background color can be seen either when the switch value is false or when the switch is disabled (and the switch is translucent).

TypeRequired
colorNo

onChange

Invoked when the user tries to change the value of the switch. Receives the change event as an argument. If you want to only receive the new value, use onValueChange instead.

TypeRequired
functionNo

onValueChange

Invoked when the user tries to change the value of the switch. Receives the new value as an argument. If you want to instead receive an event, use onChange.

TypeRequired
functionNo

thumbColor

Color of the foreground switch grip. If this is set on iOS, the switch grip will lose its drop shadow.

TypeRequired
colorNo

trackColor

Custom colors for the switch track.

iOS: When the switch value is false, the track shrinks into the border. If you want to change the color of the background exposed by the shrunken track, use ios_backgroundColor.

TypeRequired
object: {false: color, true: color}No

value

The value of the switch. If true the switch will be turned on. Default value is false.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/switch/index.html b/docs/0.61/switch/index.html index ee913f97ccd..43db8fa5e71 100644 --- a/docs/0.61/switch/index.html +++ b/docs/0.61/switch/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Switch

Renders a boolean input.

This is a controlled component that requires an onValueChange callback that updates the value prop in order for the component to reflect user actions. If the value prop is not updated, the component will continue to render the supplied value prop instead of the expected result of any user actions.

Reference

Props

Inherits View Props.

disabled

If true the user won't be able to toggle the switch. Default value is false.

TypeRequired
boolNo

ios_backgroundColor

On iOS, custom color for the background. This background color can be seen either when the switch value is false or when the switch is disabled (and the switch is translucent).

TypeRequired
colorNo

onChange

Invoked when the user tries to change the value of the switch. Receives the change event as an argument. If you want to only receive the new value, use onValueChange instead.

TypeRequired
functionNo

onValueChange

Invoked when the user tries to change the value of the switch. Receives the new value as an argument. If you want to instead receive an event, use onChange.

TypeRequired
functionNo

thumbColor

Color of the foreground switch grip. If this is set on iOS, the switch grip will lose its drop shadow.

TypeRequired
colorNo

trackColor

Custom colors for the switch track.

iOS: When the switch value is false, the track shrinks into the border. If you want to change the color of the background exposed by the shrunken track, use ios_backgroundColor.

TypeRequired
object: {false: color, true: color}No

value

The value of the switch. If true the switch will be turned on. Default value is false.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/symbolication.html b/docs/0.61/symbolication.html index 6ea9551b0e8..4d72dde7515 100644 --- a/docs/0.61/symbolication.html +++ b/docs/0.61/symbolication.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Symbolicating a stack trace

If a React Native app throws an unhandled exception in a release build, the output may be obfuscated and hard to read:

07-15 10:58:25.820 18979 18998 E AndroidRuntime: FATAL EXCEPTION: mqt_native_modules
07-15 10:58:25.820 18979 18998 E AndroidRuntime: Process: com.awesomeproject, PID: 18979 07-15 10:58:25.820 18979 18998 E AndroidRuntime: com.facebook.react.common.JavascriptException: Failed, js engine: hermes, stack:
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132161
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132084
07-15 10:58:25.820 18979 18998 E AndroidRuntime: f@1:131854
07-15 10:58:25.820 18979 18998 E AndroidRuntime: anonymous@1:131119

The sections like p@1:132161 are minified function names and bytecode offsets. To debug the problem, you would instead want to translate it into file, line and function name: AwesomeProject/App.js:54:initializeMap. This is known as symbolication. You can symbolicate minified function names and bytecode like the above by passing metro-symbolicate a generated source map and the stack trace.

The metro-symbolicate package is installed by default in the React Native template project from setting up your development environment.

From a file containing the stacktrace:

npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map < stacktrace.txt

From adb logcatdirectly:

adb logcat -d | npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map

This will turn each minified function name and offset like p@1:132161 into the actual file- and function name AwesomeProject/App.js:54:initializeMap.

Notes on Sourcemaps

  • Multiple source maps may be generated by the build process. Make sure to used the one in the location shown in the examples.
  • Make sure that the source map you use corresponds to the exact commit of the crashing app. Small changes in source code can cause large differences in offsets.
  • If metro-symbolicate exits immediately with success, make sure the input comes from a pipe or redirection and not from a terminal.
Edit this page
Last updated on
- + diff --git a/docs/0.61/symbolication/index.html b/docs/0.61/symbolication/index.html index 6ea9551b0e8..4d72dde7515 100644 --- a/docs/0.61/symbolication/index.html +++ b/docs/0.61/symbolication/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Symbolicating a stack trace

If a React Native app throws an unhandled exception in a release build, the output may be obfuscated and hard to read:

07-15 10:58:25.820 18979 18998 E AndroidRuntime: FATAL EXCEPTION: mqt_native_modules
07-15 10:58:25.820 18979 18998 E AndroidRuntime: Process: com.awesomeproject, PID: 18979 07-15 10:58:25.820 18979 18998 E AndroidRuntime: com.facebook.react.common.JavascriptException: Failed, js engine: hermes, stack:
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132161
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132084
07-15 10:58:25.820 18979 18998 E AndroidRuntime: f@1:131854
07-15 10:58:25.820 18979 18998 E AndroidRuntime: anonymous@1:131119

The sections like p@1:132161 are minified function names and bytecode offsets. To debug the problem, you would instead want to translate it into file, line and function name: AwesomeProject/App.js:54:initializeMap. This is known as symbolication. You can symbolicate minified function names and bytecode like the above by passing metro-symbolicate a generated source map and the stack trace.

The metro-symbolicate package is installed by default in the React Native template project from setting up your development environment.

From a file containing the stacktrace:

npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map < stacktrace.txt

From adb logcatdirectly:

adb logcat -d | npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map

This will turn each minified function name and offset like p@1:132161 into the actual file- and function name AwesomeProject/App.js:54:initializeMap.

Notes on Sourcemaps

  • Multiple source maps may be generated by the build process. Make sure to used the one in the location shown in the examples.
  • Make sure that the source map you use corresponds to the exact commit of the crashing app. Small changes in source code can cause large differences in offsets.
  • If metro-symbolicate exits immediately with success, make sure the input comes from a pipe or redirection and not from a terminal.
Edit this page
Last updated on
- + diff --git a/docs/0.61/systrace.html b/docs/0.61/systrace.html index cc9119a0d94..c608c71b36e 100644 --- a/docs/0.61/systrace.html +++ b/docs/0.61/systrace.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Systrace

Reference

Methods

installReactHook()

static installReactHook(useFiber)

setEnabled()

static setEnabled(enabled)

isEnabled()

static isEnabled()

beginEvent()

static beginEvent(profileName?, args?)

beginEvent/endEvent for starting and then ending a profile within the same call stack frame.

endEvent()

static endEvent()

beginAsyncEvent()

static beginAsyncEvent(profileName?)

beginAsyncEvent/endAsyncEvent for starting and then ending a profile where the end can either occur on another thread or out of the current stack frame, eg await the returned cookie variable should be used as input into the endAsyncEvent call to end the profile.

endAsyncEvent()

static endAsyncEvent(profileName?, cookie?)

counterEvent()

static counterEvent(profileName?, value?)

Register the value to the profileName on the systrace timeline.

Edit this page
Last updated on
- + diff --git a/docs/0.61/systrace/index.html b/docs/0.61/systrace/index.html index cc9119a0d94..c608c71b36e 100644 --- a/docs/0.61/systrace/index.html +++ b/docs/0.61/systrace/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Systrace

Reference

Methods

installReactHook()

static installReactHook(useFiber)

setEnabled()

static setEnabled(enabled)

isEnabled()

static isEnabled()

beginEvent()

static beginEvent(profileName?, args?)

beginEvent/endEvent for starting and then ending a profile within the same call stack frame.

endEvent()

static endEvent()

beginAsyncEvent()

static beginAsyncEvent(profileName?)

beginAsyncEvent/endAsyncEvent for starting and then ending a profile where the end can either occur on another thread or out of the current stack frame, eg await the returned cookie variable should be used as input into the endAsyncEvent call to end the profile.

endAsyncEvent()

static endAsyncEvent(profileName?, cookie?)

counterEvent()

static counterEvent(profileName?, value?)

Register the value to the profileName on the systrace timeline.

Edit this page
Last updated on
- + diff --git a/docs/0.61/tabbarios-item.html b/docs/0.61/tabbarios-item.html index b787f7a1367..cb5b74df5b3 100644 --- a/docs/0.61/tabbarios-item.html +++ b/docs/0.61/tabbarios-item.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

TabBarIOS.Item

Props

Reference

Props

selected

It specifies whether the children are visible or not. If you see a blank content, you probably forgot to add a selected one.

TypeRequired
boolNo

badge

Little red bubble that sits at the top right of the icon.

TypeRequired
string, ,numberNo

icon

A custom icon for the tab. It is ignored when a system icon is defined.

TypeRequired
Image.propTypes.sourceNo

onPress

Callback when this tab is being selected, you should change the state of your component to set selected={true}.

TypeRequired
functionNo

renderAsOriginal

If set to true it renders the image as original, it defaults to being displayed as a template

TypeRequired
boolNo

badgeColor

Background color for the badge. Available since iOS 10.

TypeRequired
colorNo

selectedIcon

A custom icon when the tab is selected. It is ignored when a system icon is defined. If left empty, the icon will be tinted in blue.

TypeRequired
Image.propTypes.sourceNo

style

React style object.

TypeRequired
View.styleNo

systemIcon

Items comes with a few predefined system icons. Note that if you are using them, the title and selectedIcon will be overridden with the system ones.

TypeRequired
enum('bookmarks', 'contacts', 'downloads', 'favorites', 'featured', 'history', 'more', 'most-recent', 'most-viewed', 'recents', 'search', 'top-rated')No

title

Text that appears under the icon. It is ignored when a system icon is defined.

TypeRequired
stringNo

isTVSelectable

(Apple TV only)* When set to true, this view will be focusable and navigable using the Apple TV remote.

TypeRequiredPlatform
boolNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.61/tabbarios-item/index.html b/docs/0.61/tabbarios-item/index.html index b787f7a1367..cb5b74df5b3 100644 --- a/docs/0.61/tabbarios-item/index.html +++ b/docs/0.61/tabbarios-item/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

TabBarIOS.Item

Props

Reference

Props

selected

It specifies whether the children are visible or not. If you see a blank content, you probably forgot to add a selected one.

TypeRequired
boolNo

badge

Little red bubble that sits at the top right of the icon.

TypeRequired
string, ,numberNo

icon

A custom icon for the tab. It is ignored when a system icon is defined.

TypeRequired
Image.propTypes.sourceNo

onPress

Callback when this tab is being selected, you should change the state of your component to set selected={true}.

TypeRequired
functionNo

renderAsOriginal

If set to true it renders the image as original, it defaults to being displayed as a template

TypeRequired
boolNo

badgeColor

Background color for the badge. Available since iOS 10.

TypeRequired
colorNo

selectedIcon

A custom icon when the tab is selected. It is ignored when a system icon is defined. If left empty, the icon will be tinted in blue.

TypeRequired
Image.propTypes.sourceNo

style

React style object.

TypeRequired
View.styleNo

systemIcon

Items comes with a few predefined system icons. Note that if you are using them, the title and selectedIcon will be overridden with the system ones.

TypeRequired
enum('bookmarks', 'contacts', 'downloads', 'favorites', 'featured', 'history', 'more', 'most-recent', 'most-viewed', 'recents', 'search', 'top-rated')No

title

Text that appears under the icon. It is ignored when a system icon is defined.

TypeRequired
stringNo

isTVSelectable

(Apple TV only)* When set to true, this view will be focusable and navigable using the Apple TV remote.

TypeRequiredPlatform
boolNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.61/tabbarios.html b/docs/0.61/tabbarios.html index d75ae7826ea..431563f7c5f 100644 --- a/docs/0.61/tabbarios.html +++ b/docs/0.61/tabbarios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

TabBarIOS

Props

Reference

Props

barStyle

The style of the tab bar. Supported values are 'default', 'black'. Use 'black' instead of setting barTintColor to black. This produces a tab bar with the native iOS style with higher translucency.

TypeRequired
enum('default', 'black')No

barTintColor

Background color of the tab bar

TypeRequired
colorNo

itemPositioning

Specifies tab bar item positioning. Available values are:

  • fill - distributes items across the entire width of the tab bar
  • center - centers item in the available tab bar space
  • auto (default) - distributes items dynamically according to the user interface idiom. In a horizontally compact environment (e.g. iPhone 5) this value defaults to fill, in a horizontally regular one (e.g. iPad) it defaults to center.
TypeRequired
enum('fill', 'center', 'auto')No

style

TypeRequired
View.styleNo

tintColor

Color of the currently selected tab icon

TypeRequired
colorNo

translucent

A Boolean value that indicates whether the tab bar is translucent

TypeRequired
boolNo

unselectedItemTintColor

Color of unselected tab icons. Available since iOS 10.

TypeRequired
colorNo

unselectedTintColor

Color of text on unselected tabs

TypeRequired
colorNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/tabbarios/index.html b/docs/0.61/tabbarios/index.html index d75ae7826ea..431563f7c5f 100644 --- a/docs/0.61/tabbarios/index.html +++ b/docs/0.61/tabbarios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

TabBarIOS

Props

Reference

Props

barStyle

The style of the tab bar. Supported values are 'default', 'black'. Use 'black' instead of setting barTintColor to black. This produces a tab bar with the native iOS style with higher translucency.

TypeRequired
enum('default', 'black')No

barTintColor

Background color of the tab bar

TypeRequired
colorNo

itemPositioning

Specifies tab bar item positioning. Available values are:

  • fill - distributes items across the entire width of the tab bar
  • center - centers item in the available tab bar space
  • auto (default) - distributes items dynamically according to the user interface idiom. In a horizontally compact environment (e.g. iPhone 5) this value defaults to fill, in a horizontally regular one (e.g. iPad) it defaults to center.
TypeRequired
enum('fill', 'center', 'auto')No

style

TypeRequired
View.styleNo

tintColor

Color of the currently selected tab icon

TypeRequired
colorNo

translucent

A Boolean value that indicates whether the tab bar is translucent

TypeRequired
boolNo

unselectedItemTintColor

Color of unselected tab icons. Available since iOS 10.

TypeRequired
colorNo

unselectedTintColor

Color of text on unselected tabs

TypeRequired
colorNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/testing-overview.html b/docs/0.61/testing-overview.html index 40f71b7bd3a..2e176244b4e 100644 --- a/docs/0.61/testing-overview.html +++ b/docs/0.61/testing-overview.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
const bananaElements = getAllByText('banana');
expect(bananaElements).toHaveLength(1); // expect 'banana' to be on the list
});

This example is not testing how some state changes when you call a function. It tests what happens when a user changes text in the TextInput and presses the Button!

Testing Rendered Output

Snapshot testing is an advanced kind of testing enabled by Jest. It is a very powerful and low-level tool, so extra attention is advised when using it.

A "component snapshot" is a JSX-like string created by a custom React serializer built into Jest. This serializer lets Jest translate React component trees to string that's human-readable. Put another way: a component snapshot is a textual representation of your component’s render output generated during a test run. It may look like this:

<Text
style={
Object {
"fontSize": 20,
"textAlign": "center",
}
}>
Welcome to React Native!
</Text>

With snapshot testing, you typically first implement your component and then run the snapshot test. The snapshot test then creates a snapshot and saves it to a file in your repo as a reference snapshot. The file is then committed and checked during code review. Any future changes to the component render output will change its snapshot, which will cause the test to fail. You then need to update the stored reference snapshot for the test to pass. That change again needs to be committed and reviewed.

Snapshots have several weak points:

Snapshots themselves do not ensure that your component render logic is correct, they are merely good at guarding against unexpected changes and for checking that the components in the React tree under test receive the expected props (styles and etc.).

We recommend that you only use small snapshots (see no-large-snapshots rule). If you want to test a change between two React component states, use snapshot-diff. When in doubt, prefer explicit expectations as described in the previous paragraph.

End-to-End Tests

In end-to-end (E2E) tests, you verify your app is working as expected on a device (or a simulator / emulator) from the user perspective.

This is done by building your app in the release configuration and running the tests against it. In E2E tests, you no longer think about React components, React Native APIs, Redux stores or any business logic. That is not the purpose of E2E tests and those are not even accessible to you during E2E testing.

Instead, E2E testing libraries allow you to find and control elements in the screen of your app: for example, you can actually tap buttons or insert text into TextInputs the same way a real user would. Then you can make assertions about whether or not a certain element exists in the app’s screen, whether or not it’s visible, what text it contains, and so on.

E2E tests give you the highest possible confidence that part of your app is working. The tradeoffs include:

Try to cover the vital parts of your app with E2E tests: authentication flow, core functionalities, payments, etc. Use faster JS tests for the non-vital parts of your app. The more tests you add, the higher your confidence, but also, the more time you'll spend maintaining and running them. Consider the tradeoffs and decide what's best for you.

There are several E2E testing tools available: in the React Native community, Detox is a popular framework because it’s tailored for React Native apps. Another popular library in the space of iOS and Android apps is Appium.

Summary

We hope you enjoyed reading and learned something from this guide. There are many ways you can test your apps. It may be hard to decide what to use at first. However, we believe it all will make sense once you start adding tests to your awesome React Native app. So what are you waiting for? Get your coverage up!

Links

This guide originally authored and contributed in full by Vojtech Novak.

Edit this page
Last updated on
- + diff --git a/docs/0.61/testing-overview/index.html b/docs/0.61/testing-overview/index.html index 40f71b7bd3a..2e176244b4e 100644 --- a/docs/0.61/testing-overview/index.html +++ b/docs/0.61/testing-overview/index.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
const bananaElements = getAllByText('banana');
expect(bananaElements).toHaveLength(1); // expect 'banana' to be on the list
});

This example is not testing how some state changes when you call a function. It tests what happens when a user changes text in the TextInput and presses the Button!

Testing Rendered Output

Snapshot testing is an advanced kind of testing enabled by Jest. It is a very powerful and low-level tool, so extra attention is advised when using it.

A "component snapshot" is a JSX-like string created by a custom React serializer built into Jest. This serializer lets Jest translate React component trees to string that's human-readable. Put another way: a component snapshot is a textual representation of your component’s render output generated during a test run. It may look like this:

<Text
style={
Object {
"fontSize": 20,
"textAlign": "center",
}
}>
Welcome to React Native!
</Text>

With snapshot testing, you typically first implement your component and then run the snapshot test. The snapshot test then creates a snapshot and saves it to a file in your repo as a reference snapshot. The file is then committed and checked during code review. Any future changes to the component render output will change its snapshot, which will cause the test to fail. You then need to update the stored reference snapshot for the test to pass. That change again needs to be committed and reviewed.

Snapshots have several weak points:

Snapshots themselves do not ensure that your component render logic is correct, they are merely good at guarding against unexpected changes and for checking that the components in the React tree under test receive the expected props (styles and etc.).

We recommend that you only use small snapshots (see no-large-snapshots rule). If you want to test a change between two React component states, use snapshot-diff. When in doubt, prefer explicit expectations as described in the previous paragraph.

End-to-End Tests

In end-to-end (E2E) tests, you verify your app is working as expected on a device (or a simulator / emulator) from the user perspective.

This is done by building your app in the release configuration and running the tests against it. In E2E tests, you no longer think about React components, React Native APIs, Redux stores or any business logic. That is not the purpose of E2E tests and those are not even accessible to you during E2E testing.

Instead, E2E testing libraries allow you to find and control elements in the screen of your app: for example, you can actually tap buttons or insert text into TextInputs the same way a real user would. Then you can make assertions about whether or not a certain element exists in the app’s screen, whether or not it’s visible, what text it contains, and so on.

E2E tests give you the highest possible confidence that part of your app is working. The tradeoffs include:

Try to cover the vital parts of your app with E2E tests: authentication flow, core functionalities, payments, etc. Use faster JS tests for the non-vital parts of your app. The more tests you add, the higher your confidence, but also, the more time you'll spend maintaining and running them. Consider the tradeoffs and decide what's best for you.

There are several E2E testing tools available: in the React Native community, Detox is a popular framework because it’s tailored for React Native apps. Another popular library in the space of iOS and Android apps is Appium.

Summary

We hope you enjoyed reading and learned something from this guide. There are many ways you can test your apps. It may be hard to decide what to use at first. However, we believe it all will make sense once you start adding tests to your awesome React Native app. So what are you waiting for? Get your coverage up!

Links

This guide originally authored and contributed in full by Vojtech Novak.

Edit this page
Last updated on
- + diff --git a/docs/0.61/text-style-props.html b/docs/0.61/text-style-props.html index 3c30d36a262..ab6843fd612 100644 --- a/docs/0.61/text-style-props.html +++ b/docs/0.61/text-style-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Text Style Props

Reference

Props

textShadowOffset

TypeRequired
object: {width: number,height: number}No

color

TypeRequired
colorNo

fontSize

TypeRequired
numberNo

fontStyle

TypeRequired
enum('normal', 'italic')No

fontWeight

Specifies font weight. The values 'normal' and 'bold' are supported for most fonts. Not all fonts have a variant for each of the numeric values, in that case the closest one is chosen.

TypeRequired
enum('normal', 'bold', '100', '200', '300', '400', '500', '600', '700', '800', '900')No

lineHeight

TypeRequired
numberNo

textAlign

Specifies text alignment. The value 'justify' is only supported on iOS and fallbacks to left on Android.

TypeRequired
enum('auto', 'left', 'right', 'center', 'justify')No

textDecorationLine

TypeRequired
enum('none', 'underline', 'line-through', 'underline line-through')No

textShadowColor

TypeRequired
colorNo

fontFamily

TypeRequired
stringNo

textShadowRadius

TypeRequired
numberNo

includeFontPadding

Set to false to remove extra font padding intended to make space for certain ascenders / descenders. With some fonts, this padding can make text look slightly misaligned when centered vertically. For best results also set textAlignVertical to center. Default is true.

TypeRequiredPlatform
boolNoAndroid

textAlignVertical

TypeRequiredPlatform
enum('auto', 'top', 'bottom', 'center')NoAndroid

fontVariant

TypeRequiredPlatform
array of enum('small-caps', 'oldstyle-nums', 'lining-nums', 'tabular-nums', 'proportional-nums')NoiOS

letterSpacing

TypeRequiredPlatform
numberNoiOS, Android >= 5.0

textDecorationColor

TypeRequiredPlatform
colorNoiOS

textDecorationStyle

TypeRequiredPlatform
enum('solid', 'double', 'dotted', 'dashed')NoiOS

textTransform

TypeRequired
enum('none', 'uppercase', 'lowercase', 'capitalize')No

writingDirection

TypeRequiredPlatform
enum('auto', 'ltr', 'rtl')NoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.61/text-style-props/index.html b/docs/0.61/text-style-props/index.html index 3c30d36a262..ab6843fd612 100644 --- a/docs/0.61/text-style-props/index.html +++ b/docs/0.61/text-style-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Text Style Props

Reference

Props

textShadowOffset

TypeRequired
object: {width: number,height: number}No

color

TypeRequired
colorNo

fontSize

TypeRequired
numberNo

fontStyle

TypeRequired
enum('normal', 'italic')No

fontWeight

Specifies font weight. The values 'normal' and 'bold' are supported for most fonts. Not all fonts have a variant for each of the numeric values, in that case the closest one is chosen.

TypeRequired
enum('normal', 'bold', '100', '200', '300', '400', '500', '600', '700', '800', '900')No

lineHeight

TypeRequired
numberNo

textAlign

Specifies text alignment. The value 'justify' is only supported on iOS and fallbacks to left on Android.

TypeRequired
enum('auto', 'left', 'right', 'center', 'justify')No

textDecorationLine

TypeRequired
enum('none', 'underline', 'line-through', 'underline line-through')No

textShadowColor

TypeRequired
colorNo

fontFamily

TypeRequired
stringNo

textShadowRadius

TypeRequired
numberNo

includeFontPadding

Set to false to remove extra font padding intended to make space for certain ascenders / descenders. With some fonts, this padding can make text look slightly misaligned when centered vertically. For best results also set textAlignVertical to center. Default is true.

TypeRequiredPlatform
boolNoAndroid

textAlignVertical

TypeRequiredPlatform
enum('auto', 'top', 'bottom', 'center')NoAndroid

fontVariant

TypeRequiredPlatform
array of enum('small-caps', 'oldstyle-nums', 'lining-nums', 'tabular-nums', 'proportional-nums')NoiOS

letterSpacing

TypeRequiredPlatform
numberNoiOS, Android >= 5.0

textDecorationColor

TypeRequiredPlatform
colorNoiOS

textDecorationStyle

TypeRequiredPlatform
enum('solid', 'double', 'dotted', 'dashed')NoiOS

textTransform

TypeRequired
enum('none', 'uppercase', 'lowercase', 'capitalize')No

writingDirection

TypeRequiredPlatform
enum('auto', 'ltr', 'rtl')NoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.61/text.html b/docs/0.61/text.html index 8b0d82c1877..df829280107 100644 --- a/docs/0.61/text.html +++ b/docs/0.61/text.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
// GOOD
<View>
<Text>
Some text
</Text>
</View>

You also lose the ability to set up a default font for an entire subtree. Meanwhile, fontFamily only accepts a single font name, which is different from font-family in CSS. The recommended way to use consistent fonts and sizes across your application is to create a component MyAppText that includes them and use this component across your app. You can also use this component to make more specific components like MyAppHeaderText for other kinds of text.

<View>
<MyAppText>
Text styled with the default font for the entire application
</MyAppText>
<MyAppHeaderText>Text styled as a header</MyAppHeaderText>
</View>

Assuming that MyAppText is a component that only renders out its children into a Text component with styling, then MyAppHeaderText can be defined as follows:

class MyAppHeaderText extends Component {
render() {
return (
<MyAppText>
<Text style={{ fontSize: 20 }}>
{this.props.children}
</Text>
</MyAppText>
);
}
}

Composing MyAppText in this way ensures that we get the styles from a top-level component, but leaves us the ability to add / override them in specific use cases.

React Native still has the concept of style inheritance, but limited to text subtrees. In this case, the second part will be both bold and red.

<Text style={{ fontWeight: 'bold' }}>
I am bold
<Text style={{ color: 'red' }}>and red</Text>
</Text>

We believe that this more constrained way to style text will yield better apps:

Reference

Props

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

adjustsFontSizeToFit

Specifies whether fonts should be scaled down automatically to fit given style constraints.

TypeRequiredPlatform
boolNoiOS

allowFontScaling

Specifies whether fonts should scale to respect Text Size accessibility settings. The default is true.

TypeRequired
boolNo

dataDetectorType

Determines the types of data converted to clickable URLs in the text element. By default no data types are detected.

You can provide only one type.

Possible values for dataDetectorType are:

TypeRequiredPlatform
enum('phoneNumber', 'link', 'email', 'none', 'all')NoAndroid

disabled

Specifies the disabled state of the text view for testing purposes

TypeRequiredPlatform
boolNoAndroid

ellipsizeMode

When numberOfLines is set, this prop defines how text will be truncated. numberOfLines must be set in conjunction with this prop.

This can be one of the following values:

The default is tail.

TypeRequired
enum('head', 'middle', 'tail', 'clip')No

maxFontSizeMultiplier

Specifies largest possible scale a font can reach when allowFontScaling is enabled. Possible values:

TypeRequired
numberNo

minimumFontScale

Specifies smallest possible scale a font can reach when adjustsFontSizeToFit is enabled. (values 0.01-1.0).

TypeRequiredPlatform
numberNoiOS

nativeID

Used to locate this view from native code.

TypeRequired
stringNo

numberOfLines

Used to truncate the text with an ellipsis after computing the text layout, including line wrapping, such that the total number of lines does not exceed this number.

This prop is commonly used with ellipsizeMode.

TypeRequired
numberNo

onLayout

Invoked on mount and layout changes with

{nativeEvent: {layout: {x, y, width, height}}}

TypeRequired
functionNo

onLongPress

This function is called on long press.

e.g., onLongPress={this.increaseSize}>

TypeRequired
functionNo

onMoveShouldSetResponder

Does this view want to "claim" touch responsiveness? This is called for every touch move on the View when it is not the responder.

View.props.onMoveShouldSetResponder: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onPress

This function is called on press.

e.g., onPress={() => console.log('1st')}

TypeRequired
functionNo

onResponderGrant

The View is now responding for touch events. This is the time to highlight and show the user what is happening.

View.props.onResponderGrant: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderMove

The user is moving their finger.

View.props.onResponderMove: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderRelease

Fired at the end of the touch.

View.props.onResponderRelease: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminate

The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS)

View.props.onResponderTerminate: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminationRequest

Some other View wants to become responder and is asking this View to release its responder. Returning true allows its release.

View.props.onResponderTerminationRequest: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onStartShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a touch start, it should have this handler which returns true.

View.props.onStartShouldSetResponderCapture: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onTextLayout

TODO.

pressRetentionOffset

When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

selectable

Lets the user select text, to use the native copy and paste functionality.

TypeRequired
boolNo

selectionColor

The highlight color of the text.

TypeRequiredPlatform
colorNoAndroid

style

TypeRequired
Text Style Props, View Style PropsNo

suppressHighlighting

When true, no visual change is made when text is pressed down. By default, a gray oval highlights the text on press down.

TypeRequiredPlatform
boolNoiOS

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

textBreakStrategy

Set text break strategy on Android API Level 23+, possible values are simple, highQuality, balanced The default value is highQuality.

TypeRequiredPlatform
enum('simple', 'highQuality', 'balanced')NoAndroid

Known issues

Edit this page
Last updated on
- + diff --git a/docs/0.61/text/index.html b/docs/0.61/text/index.html index 8b0d82c1877..df829280107 100644 --- a/docs/0.61/text/index.html +++ b/docs/0.61/text/index.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
// GOOD
<View>
<Text>
Some text
</Text>
</View>

You also lose the ability to set up a default font for an entire subtree. Meanwhile, fontFamily only accepts a single font name, which is different from font-family in CSS. The recommended way to use consistent fonts and sizes across your application is to create a component MyAppText that includes them and use this component across your app. You can also use this component to make more specific components like MyAppHeaderText for other kinds of text.

<View>
<MyAppText>
Text styled with the default font for the entire application
</MyAppText>
<MyAppHeaderText>Text styled as a header</MyAppHeaderText>
</View>

Assuming that MyAppText is a component that only renders out its children into a Text component with styling, then MyAppHeaderText can be defined as follows:

class MyAppHeaderText extends Component {
render() {
return (
<MyAppText>
<Text style={{ fontSize: 20 }}>
{this.props.children}
</Text>
</MyAppText>
);
}
}

Composing MyAppText in this way ensures that we get the styles from a top-level component, but leaves us the ability to add / override them in specific use cases.

React Native still has the concept of style inheritance, but limited to text subtrees. In this case, the second part will be both bold and red.

<Text style={{ fontWeight: 'bold' }}>
I am bold
<Text style={{ color: 'red' }}>and red</Text>
</Text>

We believe that this more constrained way to style text will yield better apps:

Reference

Props

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

adjustsFontSizeToFit

Specifies whether fonts should be scaled down automatically to fit given style constraints.

TypeRequiredPlatform
boolNoiOS

allowFontScaling

Specifies whether fonts should scale to respect Text Size accessibility settings. The default is true.

TypeRequired
boolNo

dataDetectorType

Determines the types of data converted to clickable URLs in the text element. By default no data types are detected.

You can provide only one type.

Possible values for dataDetectorType are:

TypeRequiredPlatform
enum('phoneNumber', 'link', 'email', 'none', 'all')NoAndroid

disabled

Specifies the disabled state of the text view for testing purposes

TypeRequiredPlatform
boolNoAndroid

ellipsizeMode

When numberOfLines is set, this prop defines how text will be truncated. numberOfLines must be set in conjunction with this prop.

This can be one of the following values:

The default is tail.

TypeRequired
enum('head', 'middle', 'tail', 'clip')No

maxFontSizeMultiplier

Specifies largest possible scale a font can reach when allowFontScaling is enabled. Possible values:

TypeRequired
numberNo

minimumFontScale

Specifies smallest possible scale a font can reach when adjustsFontSizeToFit is enabled. (values 0.01-1.0).

TypeRequiredPlatform
numberNoiOS

nativeID

Used to locate this view from native code.

TypeRequired
stringNo

numberOfLines

Used to truncate the text with an ellipsis after computing the text layout, including line wrapping, such that the total number of lines does not exceed this number.

This prop is commonly used with ellipsizeMode.

TypeRequired
numberNo

onLayout

Invoked on mount and layout changes with

{nativeEvent: {layout: {x, y, width, height}}}

TypeRequired
functionNo

onLongPress

This function is called on long press.

e.g., onLongPress={this.increaseSize}>

TypeRequired
functionNo

onMoveShouldSetResponder

Does this view want to "claim" touch responsiveness? This is called for every touch move on the View when it is not the responder.

View.props.onMoveShouldSetResponder: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onPress

This function is called on press.

e.g., onPress={() => console.log('1st')}

TypeRequired
functionNo

onResponderGrant

The View is now responding for touch events. This is the time to highlight and show the user what is happening.

View.props.onResponderGrant: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderMove

The user is moving their finger.

View.props.onResponderMove: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderRelease

Fired at the end of the touch.

View.props.onResponderRelease: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminate

The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS)

View.props.onResponderTerminate: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminationRequest

Some other View wants to become responder and is asking this View to release its responder. Returning true allows its release.

View.props.onResponderTerminationRequest: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onStartShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a touch start, it should have this handler which returns true.

View.props.onStartShouldSetResponderCapture: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onTextLayout

TODO.

pressRetentionOffset

When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

selectable

Lets the user select text, to use the native copy and paste functionality.

TypeRequired
boolNo

selectionColor

The highlight color of the text.

TypeRequiredPlatform
colorNoAndroid

style

TypeRequired
Text Style Props, View Style PropsNo

suppressHighlighting

When true, no visual change is made when text is pressed down. By default, a gray oval highlights the text on press down.

TypeRequiredPlatform
boolNoiOS

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

textBreakStrategy

Set text break strategy on Android API Level 23+, possible values are simple, highQuality, balanced The default value is highQuality.

TypeRequiredPlatform
enum('simple', 'highQuality', 'balanced')NoAndroid

Known issues

Edit this page
Last updated on
- + diff --git a/docs/0.61/textinput.html b/docs/0.61/textinput.html index 46e6b39014d..4202ccfbe61 100644 --- a/docs/0.61/textinput.html +++ b/docs/0.61/textinput.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

TextInput

A foundational component for inputting text into the app via a keyboard. Props provide configurability for several features, such as auto-correction, auto-capitalization, placeholder text, and different keyboard types, such as a numeric keypad.

The most basic use case is to plop down a TextInput and subscribe to the onChangeText events to read the user input. There are also other events, such as onSubmitEditing and onFocus that can be subscribed to. A minimal example:

Two methods exposed via the native element are .focus() and .blur() that will focus or blur the TextInput programmatically.

Note that some props are only available with multiline={true/false}. Additionally, border styles that apply to only one side of the element (e.g., borderBottomColor, borderLeftWidth, etc.) will not be applied if multiline=false. To achieve the same effect, you can wrap your TextInput in a View:

TextInput has by default a border at the bottom of its view. This border has its padding set by the background image provided by the system, and it cannot be changed. Solutions to avoid this is to either not set height explicitly, case in which the system will take care of displaying the border in the correct position, or to not display the border by setting underlineColorAndroid to transparent.

Note that on Android performing text selection in input can change app's activity windowSoftInputMode param to adjustResize. This may cause issues with components that have position: 'absolute' while keyboard is active. To avoid this behavior either specify windowSoftInputMode in AndroidManifest.xml ( https://developer.android.com/guide/topics/manifest/activity-element.html ) or control this param programmatically with native code.

Reference

Props

Inherits View Props.

allowFontScaling

Specifies whether fonts should scale to respect Text Size accessibility settings. The default is true.

TypeRequired
boolNo

autoCapitalize

Can tell TextInput to automatically capitalize certain characters. This property is not supported by some keyboard types such as name-phone-pad.

  • characters: all characters.
  • words: first letter of each word.
  • sentences: first letter of each sentence (default).
  • none: don't auto capitalize anything.
TypeRequired
enum('none', 'sentences', 'words', 'characters')No

autoCompleteType

Specifies autocomplete hints for the system, so it can provide autofill. On Android, the system will always attempt to offer autofill by using heuristics to identify the type of content. To disable autocomplete, set autoCompleteType to off.

Possible values for autoCompleteType are:

  • off
  • username
  • password
  • email
  • name
  • tel
  • street-address
  • postal-code
  • cc-number
  • cc-csc
  • cc-exp
  • cc-exp-month
  • cc-exp-year
TypeRequiredPlatform
enum('off', 'username', 'password', 'email', 'name', 'tel', 'street-address', 'postal-code', 'cc-number', 'cc-csc', 'cc-exp', 'cc-exp-month', 'cc-exp-year')NoAndroid

autoCorrect

If false, disables auto-correct. The default value is true.

TypeRequired
boolNo

autoFocus

If true, focuses the input on componentDidMount. The default value is false.

TypeRequired
boolNo

blurOnSubmit

If true, the text field will blur when submitted. The default value is true for single-line fields and false for multiline fields. Note that for multiline fields, setting blurOnSubmit to true means that pressing return will blur the field and trigger the onSubmitEditing event instead of inserting a newline into the field.

TypeRequired
boolNo

caretHidden

If true, caret is hidden. The default value is false.

TypeRequired
boolNo

clearButtonMode

When the clear button should appear on the right side of the text view. This property is supported only for single-line TextInput component. The default value is never.

TypeRequiredPlatform
enum('never', 'while-editing', 'unless-editing', 'always')NoiOS

clearTextOnFocus

If true, clears the text field automatically when editing begins.

TypeRequiredPlatform
boolNoiOS

contextMenuHidden

If true, context menu is hidden. The default value is false.

TypeRequired
boolNo

dataDetectorTypes

Determines the types of data converted to clickable URLs in the text input. Only valid if multiline={true} and editable={false}. By default no data types are detected.

You can provide one type or an array of many types.

Possible values for dataDetectorTypes are:

  • 'phoneNumber'
  • 'link'
  • 'address'
  • 'calendarEvent'
  • 'none'
  • 'all'
TypeRequiredPlatform
enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all'), ,array of enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all')NoiOS

defaultValue

Provides an initial value that will change when the user starts typing. Useful for use-cases where you do not want to deal with listening to events and updating the value prop to keep the controlled state in sync.

TypeRequired
stringNo

disableFullscreenUI

When false, if there is a small amount of space available around a text input (e.g. landscape orientation on a phone), the OS may choose to have the user edit the text inside of a full screen text input mode. When true, this feature is disabled and users will always edit the text directly inside of the text input. Defaults to false.

TypeRequiredPlatform
boolNoAndroid

editable

If false, text is not editable. The default value is true.

TypeRequired
boolNo

enablesReturnKeyAutomatically

If true, the keyboard disables the return key when there is no text and automatically enables it when there is text. The default value is false.

TypeRequiredPlatform
boolNoiOS

importantForAutofill

Say the system whether the individual fields in your app should be included in a view structure for autofill purposes on Android API Level 26+, possible values are auto, no, noExcludeDescendants, yes, yesExcludeDescendants. The default value is auto.

  • auto: Let the Android System use its heuristics to determine if the view is important for autofill.
  • no: This view isn't important for autofill.
  • noExcludeDescendants: This view and its children aren't important for autofill.
  • yes: This view is important for autofill.
  • yesExcludeDescendants: This view is important for autofill, but its children aren't important for autofill.
TypeRequiredPlatform
enum('auto', 'no', 'noExcludeDescendants', 'yes', 'yesExcludeDescendants')NoAndroid

inlineImageLeft

If defined, the provided image resource will be rendered on the left. The image resource must be inside /android/app/src/main/res/drawable and referenced like

<TextInput
inlineImageLeft='search_icon'
/>
TypeRequiredPlatform
stringNoAndroid

inlineImagePadding

Padding between the inline image, if any, and the text input itself.

TypeRequiredPlatform
numberNoAndroid

inputAccessoryViewID

An optional identifier which links a custom InputAccessoryView to this text input. The InputAccessoryView is rendered above the keyboard when this text input is focused.

TypeRequiredPlatform
stringNoiOS

keyboardAppearance

Determines the color of the keyboard.

TypeRequiredPlatform
enum('default', 'light', 'dark')NoiOS

keyboardType

Determines which keyboard to open, e.g.numeric.

See screenshots of all the types here.

The following values work across platforms:

  • default
  • number-pad
  • decimal-pad
  • numeric
  • email-address
  • phone-pad

iOS Only

The following values work on iOS only:

  • ascii-capable
  • numbers-and-punctuation
  • url
  • name-phone-pad
  • twitter
  • web-search

Android Only

The following values work on Android only:

  • visible-password
TypeRequired
enum('default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter', 'web-search', 'visible-password')No

maxFontSizeMultiplier

Specifies largest possible scale a font can reach when allowFontScaling is enabled. Possible values:

  • null/undefined (default): inherit from the parent node or the global default (0)
  • 0: no max, ignore parent/global default
  • >= 1: sets the maxFontSizeMultiplier of this node to this value
TypeRequired
numberNo

maxLength

Limits the maximum number of characters that can be entered. Use this instead of implementing the logic in JS to avoid flicker.

TypeRequired
numberNo

multiline

If true, the text input can be multiple lines. The default value is false. It is important to note that this aligns the text to the top on iOS, and centers it on Android. Use with textAlignVertical set to top for the same behavior in both platforms.

TypeRequired
boolNo

numberOfLines

Sets the number of lines for a TextInput. Use it with multiline set to true to be able to fill the lines.

TypeRequiredPlatform
numberNoAndroid

onBlur

Callback that is called when the text input is blurred.

TypeRequired
functionNo

onChange

Callback that is called when the text input's text changes. This will be called with { nativeEvent: { eventCount, target, text} }

TypeRequired
functionNo

onChangeText

Callback that is called when the text input's text changes. Changed text is passed as a single string argument to the callback handler.

TypeRequired
functionNo

onContentSizeChange

Callback that is called when the text input's content size changes. This will be called with { nativeEvent: { contentSize: { width, height } } }.

Only called for multiline text inputs.

TypeRequired
functionNo

onEndEditing

Callback that is called when text input ends.

TypeRequired
functionNo

onFocus

Callback that is called when the text input is focused. This is called with { nativeEvent: { target } }.

TypeRequired
functionNo

onKeyPress

Callback that is called when a key is pressed. This will be called with { nativeEvent: { key: keyValue } } where keyValue is 'Enter' or 'Backspace' for respective keys and the typed-in character otherwise including ' ' for space. Fires before onChange callbacks. Note: on Android only the inputs from soft keyboard are handled, not the hardware keyboard inputs.

TypeRequired
functionNo

onLayout

Invoked on mount and layout changes with { nativeEvent: {layout: {x, y, width, height}, target } }.

TypeRequired
functionNo

onScroll

Invoked on content scroll with { nativeEvent: { contentOffset: { x, y } } }. May also contain other properties from ScrollEvent but on Android contentSize is not provided for performance reasons.

TypeRequired
functionNo

onSelectionChange

Callback that is called when the text input selection is changed. This will be called with { nativeEvent: { selection: { start, end } } }. This prop requires multiline={true} to be set.

TypeRequired
functionNo

onSubmitEditing

Callback that is called when the text input's submit button is pressed with the argument {nativeEvent: {text, eventCount, target}}.

TypeRequired
functionNo

placeholder

The string that will be rendered before text input has been entered.

TypeRequired
stringNo

placeholderTextColor

The text color of the placeholder string.

TypeRequired
colorNo

returnKeyLabel

Sets the return key to the label. Use it instead of returnKeyType.

TypeRequiredPlatform
stringNoAndroid

returnKeyType

Determines how the return key should look. On Android you can also use returnKeyLabel.

Cross platform

The following values work across platforms:

  • done
  • go
  • next
  • search
  • send

Android Only

The following values work on Android only:

  • none
  • previous

iOS Only

The following values work on iOS only:

  • default
  • emergency-call
  • google
  • join
  • route
  • yahoo
TypeRequired
enum('done', 'go', 'next', 'search', 'send', 'none', 'previous', 'default', 'emergency-call', 'google', 'join', 'route', 'yahoo')No

rejectResponderTermination

iOS Only

If true, allows TextInput to pass touch events to the parent component. This allows components such as SwipeableListView to be swipeable from the TextInput on iOS, as is the case on Android by default. If false, TextInput always asks to handle the input (except when disabled). The default value is true.

TypeRequiredPlatform
boolNoiOS

scrollEnabled

If false, scrolling of the text view will be disabled. The default value is true. Only works with multiline={true}.

TypeRequiredPlatform
boolNoiOS

secureTextEntry

If true, the text input obscures the text entered so that sensitive text like passwords stay secure. The default value is false. Does not work with multiline={true}.

TypeRequired
boolNo

selection

The start and end of the text input's selection. Set start and end to the same value to position the cursor.

TypeRequired
object: {start: number,end: number}No

selectionColor

The highlight and cursor color of the text input.

TypeRequired
colorNo

selectionState

An instance of DocumentSelectionState, this is some state that is responsible for maintaining selection information for a document.

Some functionality that can be performed with this instance is:

  • blur()
  • focus()
  • update()
TypeRequiredPlatform
DocumentSelectionStateNoiOS

selectTextOnFocus

If true, all text will automatically be selected on focus.

TypeRequired
boolNo

showSoftInputOnFocus

When false, it will prevent the soft keyboard from showing when the field is focused. The default value is true.

TypeRequiredPlatform
boolNoAndroid

spellCheck

If false, disables spell-check style (i.e. red underlines). The default value is inherited from autoCorrect.

TypeRequiredPlatform
boolNoiOS

textContentType

Give the keyboard and the system information about the expected semantic meaning for the content that users enter.

For iOS 11+ you can set textContentType to username or password to enable autofill of login details from the device keychain.

For iOS 12+ newPassword can be used to indicate a new password input the user may want to save in the keychain, and oneTimeCode can be used to indicate that a field can be autofilled by a code arriving in an SMS.

To disable autofill, set textContentType to none.

Possible values for textContentType are:

  • none
  • URL
  • addressCity
  • addressCityAndState
  • addressState
  • countryName
  • creditCardNumber
  • emailAddress
  • familyName
  • fullStreetAddress
  • givenName
  • jobTitle
  • location
  • middleName
  • name
  • namePrefix
  • nameSuffix
  • nickname
  • organizationName
  • postalCode
  • streetAddressLine1
  • streetAddressLine2
  • sublocality
  • telephoneNumber
  • username
  • password
  • newPassword
  • oneTimeCode
TypeRequiredPlatform
enum('none', 'URL', 'addressCity', 'addressCityAndState', 'addressState', 'countryName', 'creditCardNumber', 'emailAddress', 'familyName', 'fullStreetAddress', 'givenName', 'jobTitle', 'location', 'middleName', 'name', 'namePrefix', 'nameSuffix', 'nickname', 'organizationName', 'postalCode', 'streetAddressLine1', 'streetAddressLine2', 'sublocality', 'telephoneNumber', 'username', 'password')NoiOS

style

Note that not all Text styles are supported, an incomplete list of what is not supported includes:

  • borderLeftWidth
  • borderTopWidth
  • borderRightWidth
  • borderBottomWidth
  • borderTopLeftRadius
  • borderTopRightRadius
  • borderBottomRightRadius
  • borderBottomLeftRadius

see Issue#7070 for more detail.

Styles

TypeRequired
TextNo

textBreakStrategy

Set text break strategy on Android API Level 23+, possible values are simple, highQuality, balanced The default value is simple.

TypeRequiredPlatform
enum('simple', 'highQuality', 'balanced')NoAndroid

underlineColorAndroid

The color of the TextInput underline.

TypeRequiredPlatform
colorNoAndroid

value

The value to show for the text input. TextInput is a controlled component, which means the native value will be forced to match this value prop if provided. For most uses, this works great, but in some cases this may cause flickering - one common cause is preventing edits by keeping value the same. In addition to setting the same value, either set editable={false}, or set/update maxLength to prevent unwanted edits without flicker.

TypeRequired
stringNo

Methods

clear()

clear();

Removes all text from the TextInput.

isFocused()

isFocused();

Returns true if the input is currently focused; false otherwise.

Known issues

Edit this page
Last updated on
- + diff --git a/docs/0.61/textinput/index.html b/docs/0.61/textinput/index.html index 46e6b39014d..4202ccfbe61 100644 --- a/docs/0.61/textinput/index.html +++ b/docs/0.61/textinput/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

TextInput

A foundational component for inputting text into the app via a keyboard. Props provide configurability for several features, such as auto-correction, auto-capitalization, placeholder text, and different keyboard types, such as a numeric keypad.

The most basic use case is to plop down a TextInput and subscribe to the onChangeText events to read the user input. There are also other events, such as onSubmitEditing and onFocus that can be subscribed to. A minimal example:

Two methods exposed via the native element are .focus() and .blur() that will focus or blur the TextInput programmatically.

Note that some props are only available with multiline={true/false}. Additionally, border styles that apply to only one side of the element (e.g., borderBottomColor, borderLeftWidth, etc.) will not be applied if multiline=false. To achieve the same effect, you can wrap your TextInput in a View:

TextInput has by default a border at the bottom of its view. This border has its padding set by the background image provided by the system, and it cannot be changed. Solutions to avoid this is to either not set height explicitly, case in which the system will take care of displaying the border in the correct position, or to not display the border by setting underlineColorAndroid to transparent.

Note that on Android performing text selection in input can change app's activity windowSoftInputMode param to adjustResize. This may cause issues with components that have position: 'absolute' while keyboard is active. To avoid this behavior either specify windowSoftInputMode in AndroidManifest.xml ( https://developer.android.com/guide/topics/manifest/activity-element.html ) or control this param programmatically with native code.

Reference

Props

Inherits View Props.

allowFontScaling

Specifies whether fonts should scale to respect Text Size accessibility settings. The default is true.

TypeRequired
boolNo

autoCapitalize

Can tell TextInput to automatically capitalize certain characters. This property is not supported by some keyboard types such as name-phone-pad.

  • characters: all characters.
  • words: first letter of each word.
  • sentences: first letter of each sentence (default).
  • none: don't auto capitalize anything.
TypeRequired
enum('none', 'sentences', 'words', 'characters')No

autoCompleteType

Specifies autocomplete hints for the system, so it can provide autofill. On Android, the system will always attempt to offer autofill by using heuristics to identify the type of content. To disable autocomplete, set autoCompleteType to off.

Possible values for autoCompleteType are:

  • off
  • username
  • password
  • email
  • name
  • tel
  • street-address
  • postal-code
  • cc-number
  • cc-csc
  • cc-exp
  • cc-exp-month
  • cc-exp-year
TypeRequiredPlatform
enum('off', 'username', 'password', 'email', 'name', 'tel', 'street-address', 'postal-code', 'cc-number', 'cc-csc', 'cc-exp', 'cc-exp-month', 'cc-exp-year')NoAndroid

autoCorrect

If false, disables auto-correct. The default value is true.

TypeRequired
boolNo

autoFocus

If true, focuses the input on componentDidMount. The default value is false.

TypeRequired
boolNo

blurOnSubmit

If true, the text field will blur when submitted. The default value is true for single-line fields and false for multiline fields. Note that for multiline fields, setting blurOnSubmit to true means that pressing return will blur the field and trigger the onSubmitEditing event instead of inserting a newline into the field.

TypeRequired
boolNo

caretHidden

If true, caret is hidden. The default value is false.

TypeRequired
boolNo

clearButtonMode

When the clear button should appear on the right side of the text view. This property is supported only for single-line TextInput component. The default value is never.

TypeRequiredPlatform
enum('never', 'while-editing', 'unless-editing', 'always')NoiOS

clearTextOnFocus

If true, clears the text field automatically when editing begins.

TypeRequiredPlatform
boolNoiOS

contextMenuHidden

If true, context menu is hidden. The default value is false.

TypeRequired
boolNo

dataDetectorTypes

Determines the types of data converted to clickable URLs in the text input. Only valid if multiline={true} and editable={false}. By default no data types are detected.

You can provide one type or an array of many types.

Possible values for dataDetectorTypes are:

  • 'phoneNumber'
  • 'link'
  • 'address'
  • 'calendarEvent'
  • 'none'
  • 'all'
TypeRequiredPlatform
enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all'), ,array of enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all')NoiOS

defaultValue

Provides an initial value that will change when the user starts typing. Useful for use-cases where you do not want to deal with listening to events and updating the value prop to keep the controlled state in sync.

TypeRequired
stringNo

disableFullscreenUI

When false, if there is a small amount of space available around a text input (e.g. landscape orientation on a phone), the OS may choose to have the user edit the text inside of a full screen text input mode. When true, this feature is disabled and users will always edit the text directly inside of the text input. Defaults to false.

TypeRequiredPlatform
boolNoAndroid

editable

If false, text is not editable. The default value is true.

TypeRequired
boolNo

enablesReturnKeyAutomatically

If true, the keyboard disables the return key when there is no text and automatically enables it when there is text. The default value is false.

TypeRequiredPlatform
boolNoiOS

importantForAutofill

Say the system whether the individual fields in your app should be included in a view structure for autofill purposes on Android API Level 26+, possible values are auto, no, noExcludeDescendants, yes, yesExcludeDescendants. The default value is auto.

  • auto: Let the Android System use its heuristics to determine if the view is important for autofill.
  • no: This view isn't important for autofill.
  • noExcludeDescendants: This view and its children aren't important for autofill.
  • yes: This view is important for autofill.
  • yesExcludeDescendants: This view is important for autofill, but its children aren't important for autofill.
TypeRequiredPlatform
enum('auto', 'no', 'noExcludeDescendants', 'yes', 'yesExcludeDescendants')NoAndroid

inlineImageLeft

If defined, the provided image resource will be rendered on the left. The image resource must be inside /android/app/src/main/res/drawable and referenced like

<TextInput
inlineImageLeft='search_icon'
/>
TypeRequiredPlatform
stringNoAndroid

inlineImagePadding

Padding between the inline image, if any, and the text input itself.

TypeRequiredPlatform
numberNoAndroid

inputAccessoryViewID

An optional identifier which links a custom InputAccessoryView to this text input. The InputAccessoryView is rendered above the keyboard when this text input is focused.

TypeRequiredPlatform
stringNoiOS

keyboardAppearance

Determines the color of the keyboard.

TypeRequiredPlatform
enum('default', 'light', 'dark')NoiOS

keyboardType

Determines which keyboard to open, e.g.numeric.

See screenshots of all the types here.

The following values work across platforms:

  • default
  • number-pad
  • decimal-pad
  • numeric
  • email-address
  • phone-pad

iOS Only

The following values work on iOS only:

  • ascii-capable
  • numbers-and-punctuation
  • url
  • name-phone-pad
  • twitter
  • web-search

Android Only

The following values work on Android only:

  • visible-password
TypeRequired
enum('default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter', 'web-search', 'visible-password')No

maxFontSizeMultiplier

Specifies largest possible scale a font can reach when allowFontScaling is enabled. Possible values:

  • null/undefined (default): inherit from the parent node or the global default (0)
  • 0: no max, ignore parent/global default
  • >= 1: sets the maxFontSizeMultiplier of this node to this value
TypeRequired
numberNo

maxLength

Limits the maximum number of characters that can be entered. Use this instead of implementing the logic in JS to avoid flicker.

TypeRequired
numberNo

multiline

If true, the text input can be multiple lines. The default value is false. It is important to note that this aligns the text to the top on iOS, and centers it on Android. Use with textAlignVertical set to top for the same behavior in both platforms.

TypeRequired
boolNo

numberOfLines

Sets the number of lines for a TextInput. Use it with multiline set to true to be able to fill the lines.

TypeRequiredPlatform
numberNoAndroid

onBlur

Callback that is called when the text input is blurred.

TypeRequired
functionNo

onChange

Callback that is called when the text input's text changes. This will be called with { nativeEvent: { eventCount, target, text} }

TypeRequired
functionNo

onChangeText

Callback that is called when the text input's text changes. Changed text is passed as a single string argument to the callback handler.

TypeRequired
functionNo

onContentSizeChange

Callback that is called when the text input's content size changes. This will be called with { nativeEvent: { contentSize: { width, height } } }.

Only called for multiline text inputs.

TypeRequired
functionNo

onEndEditing

Callback that is called when text input ends.

TypeRequired
functionNo

onFocus

Callback that is called when the text input is focused. This is called with { nativeEvent: { target } }.

TypeRequired
functionNo

onKeyPress

Callback that is called when a key is pressed. This will be called with { nativeEvent: { key: keyValue } } where keyValue is 'Enter' or 'Backspace' for respective keys and the typed-in character otherwise including ' ' for space. Fires before onChange callbacks. Note: on Android only the inputs from soft keyboard are handled, not the hardware keyboard inputs.

TypeRequired
functionNo

onLayout

Invoked on mount and layout changes with { nativeEvent: {layout: {x, y, width, height}, target } }.

TypeRequired
functionNo

onScroll

Invoked on content scroll with { nativeEvent: { contentOffset: { x, y } } }. May also contain other properties from ScrollEvent but on Android contentSize is not provided for performance reasons.

TypeRequired
functionNo

onSelectionChange

Callback that is called when the text input selection is changed. This will be called with { nativeEvent: { selection: { start, end } } }. This prop requires multiline={true} to be set.

TypeRequired
functionNo

onSubmitEditing

Callback that is called when the text input's submit button is pressed with the argument {nativeEvent: {text, eventCount, target}}.

TypeRequired
functionNo

placeholder

The string that will be rendered before text input has been entered.

TypeRequired
stringNo

placeholderTextColor

The text color of the placeholder string.

TypeRequired
colorNo

returnKeyLabel

Sets the return key to the label. Use it instead of returnKeyType.

TypeRequiredPlatform
stringNoAndroid

returnKeyType

Determines how the return key should look. On Android you can also use returnKeyLabel.

Cross platform

The following values work across platforms:

  • done
  • go
  • next
  • search
  • send

Android Only

The following values work on Android only:

  • none
  • previous

iOS Only

The following values work on iOS only:

  • default
  • emergency-call
  • google
  • join
  • route
  • yahoo
TypeRequired
enum('done', 'go', 'next', 'search', 'send', 'none', 'previous', 'default', 'emergency-call', 'google', 'join', 'route', 'yahoo')No

rejectResponderTermination

iOS Only

If true, allows TextInput to pass touch events to the parent component. This allows components such as SwipeableListView to be swipeable from the TextInput on iOS, as is the case on Android by default. If false, TextInput always asks to handle the input (except when disabled). The default value is true.

TypeRequiredPlatform
boolNoiOS

scrollEnabled

If false, scrolling of the text view will be disabled. The default value is true. Only works with multiline={true}.

TypeRequiredPlatform
boolNoiOS

secureTextEntry

If true, the text input obscures the text entered so that sensitive text like passwords stay secure. The default value is false. Does not work with multiline={true}.

TypeRequired
boolNo

selection

The start and end of the text input's selection. Set start and end to the same value to position the cursor.

TypeRequired
object: {start: number,end: number}No

selectionColor

The highlight and cursor color of the text input.

TypeRequired
colorNo

selectionState

An instance of DocumentSelectionState, this is some state that is responsible for maintaining selection information for a document.

Some functionality that can be performed with this instance is:

  • blur()
  • focus()
  • update()
TypeRequiredPlatform
DocumentSelectionStateNoiOS

selectTextOnFocus

If true, all text will automatically be selected on focus.

TypeRequired
boolNo

showSoftInputOnFocus

When false, it will prevent the soft keyboard from showing when the field is focused. The default value is true.

TypeRequiredPlatform
boolNoAndroid

spellCheck

If false, disables spell-check style (i.e. red underlines). The default value is inherited from autoCorrect.

TypeRequiredPlatform
boolNoiOS

textContentType

Give the keyboard and the system information about the expected semantic meaning for the content that users enter.

For iOS 11+ you can set textContentType to username or password to enable autofill of login details from the device keychain.

For iOS 12+ newPassword can be used to indicate a new password input the user may want to save in the keychain, and oneTimeCode can be used to indicate that a field can be autofilled by a code arriving in an SMS.

To disable autofill, set textContentType to none.

Possible values for textContentType are:

  • none
  • URL
  • addressCity
  • addressCityAndState
  • addressState
  • countryName
  • creditCardNumber
  • emailAddress
  • familyName
  • fullStreetAddress
  • givenName
  • jobTitle
  • location
  • middleName
  • name
  • namePrefix
  • nameSuffix
  • nickname
  • organizationName
  • postalCode
  • streetAddressLine1
  • streetAddressLine2
  • sublocality
  • telephoneNumber
  • username
  • password
  • newPassword
  • oneTimeCode
TypeRequiredPlatform
enum('none', 'URL', 'addressCity', 'addressCityAndState', 'addressState', 'countryName', 'creditCardNumber', 'emailAddress', 'familyName', 'fullStreetAddress', 'givenName', 'jobTitle', 'location', 'middleName', 'name', 'namePrefix', 'nameSuffix', 'nickname', 'organizationName', 'postalCode', 'streetAddressLine1', 'streetAddressLine2', 'sublocality', 'telephoneNumber', 'username', 'password')NoiOS

style

Note that not all Text styles are supported, an incomplete list of what is not supported includes:

  • borderLeftWidth
  • borderTopWidth
  • borderRightWidth
  • borderBottomWidth
  • borderTopLeftRadius
  • borderTopRightRadius
  • borderBottomRightRadius
  • borderBottomLeftRadius

see Issue#7070 for more detail.

Styles

TypeRequired
TextNo

textBreakStrategy

Set text break strategy on Android API Level 23+, possible values are simple, highQuality, balanced The default value is simple.

TypeRequiredPlatform
enum('simple', 'highQuality', 'balanced')NoAndroid

underlineColorAndroid

The color of the TextInput underline.

TypeRequiredPlatform
colorNoAndroid

value

The value to show for the text input. TextInput is a controlled component, which means the native value will be forced to match this value prop if provided. For most uses, this works great, but in some cases this may cause flickering - one common cause is preventing edits by keeping value the same. In addition to setting the same value, either set editable={false}, or set/update maxLength to prevent unwanted edits without flicker.

TypeRequired
stringNo

Methods

clear()

clear();

Removes all text from the TextInput.

isFocused()

isFocused();

Returns true if the input is currently focused; false otherwise.

Known issues

Edit this page
Last updated on
- + diff --git a/docs/0.61/timepickerandroid.html b/docs/0.61/timepickerandroid.html index dcd5350294c..e80151ac373 100644 --- a/docs/0.61/timepickerandroid.html +++ b/docs/0.61/timepickerandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 TimePickerAndroid

Deprecated. Use @react-native-community/datetimepicker instead.

Opens the standard Android time picker dialog.

TimePickerAndroid has been merged with DatePickerIOS and DatePickerAndroid into a single component called DateTimePicker and will be removed in a future release.

Example

try {
const { action, hour, minute } = await TimePickerAndroid.open({
hour: 14,
minute: 0,
is24Hour: false // Will display '2 PM'
});
if (action !== TimePickerAndroid.dismissedAction) {
// Selected hour (0-23), minute (0-59)
}
} catch ({ code, message }) {
console.warn('Cannot open time picker', message);
}

Reference

Methods

open()

static open(options)

Opens the standard Android time picker dialog.

The available keys for the options object are:

  • hour (0-23) - the hour to show, defaults to the current time
  • minute (0-59) - the minute to show, defaults to the current time
  • is24Hour (boolean) - If true, the picker uses the 24-hour format. If false, the picker shows an AM/PM chooser. If undefined, the default for the current locale is used.
  • mode (enum('clock', 'spinner', 'default')) - set the time picker mode
    • 'clock': Show a time picker in clock mode.
    • 'spinner': Show a time picker in spinner mode.
    • 'default': Show a default time picker based on Android versions.

Returns a Promise which will be invoked an object containing action, hour (0-23), minute (0-59) if the user picked a time. If the user dismissed the dialog, the Promise will still be resolved with action being TimePickerAndroid.dismissedAction and all the other keys being undefined. Always check whether the action before reading the values.

timeSetAction()

static timeSetAction()

A time has been selected.

dismissedAction()

static dismissedAction()

The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/0.61/timepickerandroid/index.html b/docs/0.61/timepickerandroid/index.html index dcd5350294c..e80151ac373 100644 --- a/docs/0.61/timepickerandroid/index.html +++ b/docs/0.61/timepickerandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

🚧 TimePickerAndroid

Deprecated. Use @react-native-community/datetimepicker instead.

Opens the standard Android time picker dialog.

TimePickerAndroid has been merged with DatePickerIOS and DatePickerAndroid into a single component called DateTimePicker and will be removed in a future release.

Example

try {
const { action, hour, minute } = await TimePickerAndroid.open({
hour: 14,
minute: 0,
is24Hour: false // Will display '2 PM'
});
if (action !== TimePickerAndroid.dismissedAction) {
// Selected hour (0-23), minute (0-59)
}
} catch ({ code, message }) {
console.warn('Cannot open time picker', message);
}

Reference

Methods

open()

static open(options)

Opens the standard Android time picker dialog.

The available keys for the options object are:

  • hour (0-23) - the hour to show, defaults to the current time
  • minute (0-59) - the minute to show, defaults to the current time
  • is24Hour (boolean) - If true, the picker uses the 24-hour format. If false, the picker shows an AM/PM chooser. If undefined, the default for the current locale is used.
  • mode (enum('clock', 'spinner', 'default')) - set the time picker mode
    • 'clock': Show a time picker in clock mode.
    • 'spinner': Show a time picker in spinner mode.
    • 'default': Show a default time picker based on Android versions.

Returns a Promise which will be invoked an object containing action, hour (0-23), minute (0-59) if the user picked a time. If the user dismissed the dialog, the Promise will still be resolved with action being TimePickerAndroid.dismissedAction and all the other keys being undefined. Always check whether the action before reading the values.

timeSetAction()

static timeSetAction()

A time has been selected.

dismissedAction()

static dismissedAction()

The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/0.61/timers.html b/docs/0.61/timers.html index c5b24cb4a3d..6b9cc0883c4 100644 --- a/docs/0.61/timers.html +++ b/docs/0.61/timers.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Timers

Timers are an important part of an application and React Native implements the browser timers.

Timers

  • setTimeout, clearTimeout
  • setInterval, clearInterval
  • setImmediate, clearImmediate
  • requestAnimationFrame, cancelAnimationFrame

requestAnimationFrame(fn) is not the same as setTimeout(fn, 0) - the former will fire after all the frame has flushed, whereas the latter will fire as quickly as possible (over 1000x per second on a iPhone 5S).

setImmediate is executed at the end of the current JavaScript execution block, right before sending the batched response back to native. Note that if you call setImmediate within a setImmediate callback, it will be executed right away, it won't yield back to native in between.

The Promise implementation uses setImmediate as its asynchronicity implementation.

InteractionManager

One reason why well-built native apps feel so smooth is by avoiding expensive operations during interactions and animations. In React Native, we currently have a limitation that there is only a single JS execution thread, but you can use InteractionManager to make sure long-running work is scheduled to start after any interactions/animations have completed.

Applications can schedule tasks to run after interactions with the following:

InteractionManager.runAfterInteractions(() => {
// ...long-running synchronous task...
});

Compare this to other scheduling alternatives:

  • requestAnimationFrame(): for code that animates a view over time.
  • setImmediate/setTimeout/setInterval(): run code later, note this may delay animations.
  • runAfterInteractions(): run code later, without delaying active animations.

The touch handling system considers one or more active touches to be an 'interaction' and will delay runAfterInteractions() callbacks until all touches have ended or been cancelled.

InteractionManager also allows applications to register animations by creating an interaction 'handle' on animation start, and clearing it upon completion:

var handle = InteractionManager.createInteractionHandle();
// run animation... (`runAfterInteractions` tasks are queued)
// later, on animation completion:
InteractionManager.clearInteractionHandle(handle);
// queued tasks run if all handles were cleared
Edit this page
Last updated on
- + diff --git a/docs/0.61/timers/index.html b/docs/0.61/timers/index.html index c5b24cb4a3d..6b9cc0883c4 100644 --- a/docs/0.61/timers/index.html +++ b/docs/0.61/timers/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Timers

Timers are an important part of an application and React Native implements the browser timers.

Timers

  • setTimeout, clearTimeout
  • setInterval, clearInterval
  • setImmediate, clearImmediate
  • requestAnimationFrame, cancelAnimationFrame

requestAnimationFrame(fn) is not the same as setTimeout(fn, 0) - the former will fire after all the frame has flushed, whereas the latter will fire as quickly as possible (over 1000x per second on a iPhone 5S).

setImmediate is executed at the end of the current JavaScript execution block, right before sending the batched response back to native. Note that if you call setImmediate within a setImmediate callback, it will be executed right away, it won't yield back to native in between.

The Promise implementation uses setImmediate as its asynchronicity implementation.

InteractionManager

One reason why well-built native apps feel so smooth is by avoiding expensive operations during interactions and animations. In React Native, we currently have a limitation that there is only a single JS execution thread, but you can use InteractionManager to make sure long-running work is scheduled to start after any interactions/animations have completed.

Applications can schedule tasks to run after interactions with the following:

InteractionManager.runAfterInteractions(() => {
// ...long-running synchronous task...
});

Compare this to other scheduling alternatives:

  • requestAnimationFrame(): for code that animates a view over time.
  • setImmediate/setTimeout/setInterval(): run code later, note this may delay animations.
  • runAfterInteractions(): run code later, without delaying active animations.

The touch handling system considers one or more active touches to be an 'interaction' and will delay runAfterInteractions() callbacks until all touches have ended or been cancelled.

InteractionManager also allows applications to register animations by creating an interaction 'handle' on animation start, and clearing it upon completion:

var handle = InteractionManager.createInteractionHandle();
// run animation... (`runAfterInteractions` tasks are queued)
// later, on animation completion:
InteractionManager.clearInteractionHandle(handle);
// queued tasks run if all handles were cleared
Edit this page
Last updated on
- + diff --git a/docs/0.61/toastandroid.html b/docs/0.61/toastandroid.html index 83cc4f08f7c..594451e2f1b 100644 --- a/docs/0.61/toastandroid.html +++ b/docs/0.61/toastandroid.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
render() {
return (
<View style={styles.container}>
<Toast visible={this.state.visible} message="Example" />
<Button
title="Toggle Modal"
onPress={this.handleButtonPress}
/>
</View>
);
}
}

Reference

Methods

show()

static show(message, duration)

showWithGravity()

static showWithGravity(message, duration, gravity)

showWithGravityAndOffset()

static showWithGravityAndOffset(message, duration, gravity, xOffset, yOffset)

Properties

SHORT

Indicates the duration on the screen.

ToastAndroid.SHORT;

LONG

Indicates the duration on the screen.

ToastAndroid.LONG;

TOP

Indicates the position on the screen.

ToastAndroid.TOP;

BOTTOM

Indicates the position on the screen.

ToastAndroid.BOTTOM;

CENTER

Indicates the position on the screen.

ToastAndroid.CENTER;
Edit this page
Last updated on
- + diff --git a/docs/0.61/toastandroid/index.html b/docs/0.61/toastandroid/index.html index 83cc4f08f7c..594451e2f1b 100644 --- a/docs/0.61/toastandroid/index.html +++ b/docs/0.61/toastandroid/index.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
render() {
return (
<View style={styles.container}>
<Toast visible={this.state.visible} message="Example" />
<Button
title="Toggle Modal"
onPress={this.handleButtonPress}
/>
</View>
);
}
}

Reference

Methods

show()

static show(message, duration)

showWithGravity()

static showWithGravity(message, duration, gravity)

showWithGravityAndOffset()

static showWithGravityAndOffset(message, duration, gravity, xOffset, yOffset)

Properties

SHORT

Indicates the duration on the screen.

ToastAndroid.SHORT;

LONG

Indicates the duration on the screen.

ToastAndroid.LONG;

TOP

Indicates the position on the screen.

ToastAndroid.TOP;

BOTTOM

Indicates the position on the screen.

ToastAndroid.BOTTOM;

CENTER

Indicates the position on the screen.

ToastAndroid.CENTER;
Edit this page
Last updated on
- + diff --git a/docs/0.61/toolbarandroid.html b/docs/0.61/toolbarandroid.html index a8fb7265290..0b43bee949d 100644 --- a/docs/0.61/toolbarandroid.html +++ b/docs/0.61/toolbarandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

ToolbarAndroid

NOTE: Toolbar Android has been deprecated and removed from the package since React Native v0.61.0. Use @react-native-community/toolbar-android instead.

React component that wraps the Android-only Toolbar widget. A Toolbar can display a logo, navigation icon (e.g. hamburger menu), a title & subtitle and a list of actions. The title and subtitle are expanded so the logo and navigation icons are displayed on the left, title and subtitle in the middle and the actions on the right.

If the toolbar has an only child, it will be displayed between the title and actions.

Although the Toolbar supports remote images for the logo, navigation and action icons, this should only be used in DEV mode where require('./some_icon.png') translates into a bundler URL. In release mode you should always use a drawable resource for these icons. Using require('./some_icon.png') will do this automatically for you, so as long as you don't explicitly use e.g. {uri: 'http://...'}, you will be good.

Example:

render: function() {
return (
<ToolbarAndroid
logo={require('./app_logo.png')}
title="AwesomeApp"
actions={[{title: 'Settings', icon: require('./icon_settings.png'), show: 'always'}]}
onActionSelected={this.onActionSelected} />
)
},
onActionSelected: function(position) {
if (position === 0) { // index of 'Settings'
showSettings();
}
}

Reference

Props

Inherits View Props.

actions

Sets possible actions on the toolbar as part of the action menu. These are displayed as icons or text on the right side of the widget. If they don't fit they are placed in an 'overflow' menu.

This property takes an array of objects, where each object has the following keys:

  • title: required, the title of this action
  • icon: the icon for this action, e.g. require('./some_icon.png')
  • show: when to show this action as an icon or hide it in the overflow menu: always, ifRoom or never
  • showWithText: boolean, whether to show text alongside the icon or not
TypeRequired
array of object: {title: string,icon: optionalImageSource,show: enum('always', 'ifRoom', 'never'),showWithText: bool}No

contentInsetStart

Sets the content inset for the toolbar starting edge.

The content inset affects the valid area for Toolbar content other than the navigation button and menu. Insets define the minimum margin for these components and can be used to effectively align Toolbar content along well-known gridlines.

TypeRequired
numberNo

contentInsetEnd

Sets the content inset for the toolbar ending edge.

The content inset affects the valid area for Toolbar content other than the navigation button and menu. Insets define the minimum margin for these components and can be used to effectively align Toolbar content along well-known gridlines.

TypeRequired
numberNo

logo

Sets the toolbar logo.

TypeRequired
optionalImageSourceNo

navIcon

Sets the navigation icon.

TypeRequired
optionalImageSourceNo

onActionSelected

Callback that is called when an action is selected. The only argument that is passed to the callback is the position of the action in the actions array.

TypeRequired
functionNo

onIconClicked

Callback called when the icon is selected.

TypeRequired
functionNo

overflowIcon

Sets the overflow icon.

TypeRequired
optionalImageSourceNo

rtl

Used to set the toolbar direction to RTL. In addition to this property you need to add

android:supportsRtl="true"

to your application AndroidManifest.xml and then call setLayoutDirection(LayoutDirection.RTL) in your MainActivity onCreate method.

TypeRequired
boolNo

subtitle

Sets the toolbar subtitle.

TypeRequired
stringNo

subtitleColor

Sets the toolbar subtitle color.

TypeRequired
colorNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

title

Sets the toolbar title.

TypeRequired
stringNo

titleColor

Sets the toolbar title color.

TypeRequired
colorNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/toolbarandroid/index.html b/docs/0.61/toolbarandroid/index.html index a8fb7265290..0b43bee949d 100644 --- a/docs/0.61/toolbarandroid/index.html +++ b/docs/0.61/toolbarandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

ToolbarAndroid

NOTE: Toolbar Android has been deprecated and removed from the package since React Native v0.61.0. Use @react-native-community/toolbar-android instead.

React component that wraps the Android-only Toolbar widget. A Toolbar can display a logo, navigation icon (e.g. hamburger menu), a title & subtitle and a list of actions. The title and subtitle are expanded so the logo and navigation icons are displayed on the left, title and subtitle in the middle and the actions on the right.

If the toolbar has an only child, it will be displayed between the title and actions.

Although the Toolbar supports remote images for the logo, navigation and action icons, this should only be used in DEV mode where require('./some_icon.png') translates into a bundler URL. In release mode you should always use a drawable resource for these icons. Using require('./some_icon.png') will do this automatically for you, so as long as you don't explicitly use e.g. {uri: 'http://...'}, you will be good.

Example:

render: function() {
return (
<ToolbarAndroid
logo={require('./app_logo.png')}
title="AwesomeApp"
actions={[{title: 'Settings', icon: require('./icon_settings.png'), show: 'always'}]}
onActionSelected={this.onActionSelected} />
)
},
onActionSelected: function(position) {
if (position === 0) { // index of 'Settings'
showSettings();
}
}

Reference

Props

Inherits View Props.

actions

Sets possible actions on the toolbar as part of the action menu. These are displayed as icons or text on the right side of the widget. If they don't fit they are placed in an 'overflow' menu.

This property takes an array of objects, where each object has the following keys:

  • title: required, the title of this action
  • icon: the icon for this action, e.g. require('./some_icon.png')
  • show: when to show this action as an icon or hide it in the overflow menu: always, ifRoom or never
  • showWithText: boolean, whether to show text alongside the icon or not
TypeRequired
array of object: {title: string,icon: optionalImageSource,show: enum('always', 'ifRoom', 'never'),showWithText: bool}No

contentInsetStart

Sets the content inset for the toolbar starting edge.

The content inset affects the valid area for Toolbar content other than the navigation button and menu. Insets define the minimum margin for these components and can be used to effectively align Toolbar content along well-known gridlines.

TypeRequired
numberNo

contentInsetEnd

Sets the content inset for the toolbar ending edge.

The content inset affects the valid area for Toolbar content other than the navigation button and menu. Insets define the minimum margin for these components and can be used to effectively align Toolbar content along well-known gridlines.

TypeRequired
numberNo

logo

Sets the toolbar logo.

TypeRequired
optionalImageSourceNo

navIcon

Sets the navigation icon.

TypeRequired
optionalImageSourceNo

onActionSelected

Callback that is called when an action is selected. The only argument that is passed to the callback is the position of the action in the actions array.

TypeRequired
functionNo

onIconClicked

Callback called when the icon is selected.

TypeRequired
functionNo

overflowIcon

Sets the overflow icon.

TypeRequired
optionalImageSourceNo

rtl

Used to set the toolbar direction to RTL. In addition to this property you need to add

android:supportsRtl="true"

to your application AndroidManifest.xml and then call setLayoutDirection(LayoutDirection.RTL) in your MainActivity onCreate method.

TypeRequired
boolNo

subtitle

Sets the toolbar subtitle.

TypeRequired
stringNo

subtitleColor

Sets the toolbar subtitle color.

TypeRequired
colorNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

title

Sets the toolbar title.

TypeRequired
stringNo

titleColor

Sets the toolbar title color.

TypeRequired
colorNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/touchablehighlight.html b/docs/0.61/touchablehighlight.html index ef6a1f4fadd..650149c60f0 100644 --- a/docs/0.61/touchablehighlight.html +++ b/docs/0.61/touchablehighlight.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

TouchableHighlight

A wrapper for making views respond properly to touches. On press down, the opacity of the wrapped view is decreased, which allows the underlay color to show through, darkening or tinting the view.

The underlay comes from wrapping the child in a new View, which can affect layout, and sometimes cause unwanted visual artifacts if not used correctly, for example if the backgroundColor of the wrapped view isn't explicitly set to an opaque color.

TouchableHighlight must have one child (not zero or more than one). If you wish to have several child components, wrap them in a View.

Example:

renderButton: function() {
return (
<TouchableHighlight onPress={this._onPressButton}>
<Image
style={styles.button}
source={require('./myButton.png')}
/>
</TouchableHighlight>
);
},

Example

Props

Reference

Props

Inherits TouchableWithoutFeedback Props.

activeOpacity

Determines what the opacity of the wrapped view should be when touch is active. The value should be between 0 and 1. Defaults to 0.85. Requires underlayColor to be set.

TypeRequired
numberNo

onHideUnderlay

Called immediately after the underlay is hidden.

TypeRequired
functionNo

onShowUnderlay

Called immediately after the underlay is shown.

TypeRequired
functionNo

style

TypeRequired
View.styleNo

underlayColor

The color of the underlay that will show through when the touch is active.

TypeRequired
colorNo

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

tvParallaxProperties

(Apple TV only) Object with properties to control Apple TV parallax effects.

enabled: If true, parallax effects are enabled. Defaults to true. shiftDistanceX: Defaults to 2.0. shiftDistanceY: Defaults to 2.0. tiltAngle: Defaults to 0.05. magnification: Defaults to 1.0. pressMagnification: Defaults to 1.0. pressDuration: Defaults to 0.3. pressDelay: Defaults to 0.0.

TypeRequiredPlatform
objectNoiOS

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

testOnly_pressed

Handy for snapshot tests.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/touchablehighlight/index.html b/docs/0.61/touchablehighlight/index.html index ef6a1f4fadd..650149c60f0 100644 --- a/docs/0.61/touchablehighlight/index.html +++ b/docs/0.61/touchablehighlight/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

TouchableHighlight

A wrapper for making views respond properly to touches. On press down, the opacity of the wrapped view is decreased, which allows the underlay color to show through, darkening or tinting the view.

The underlay comes from wrapping the child in a new View, which can affect layout, and sometimes cause unwanted visual artifacts if not used correctly, for example if the backgroundColor of the wrapped view isn't explicitly set to an opaque color.

TouchableHighlight must have one child (not zero or more than one). If you wish to have several child components, wrap them in a View.

Example:

renderButton: function() {
return (
<TouchableHighlight onPress={this._onPressButton}>
<Image
style={styles.button}
source={require('./myButton.png')}
/>
</TouchableHighlight>
);
},

Example

Props

Reference

Props

Inherits TouchableWithoutFeedback Props.

activeOpacity

Determines what the opacity of the wrapped view should be when touch is active. The value should be between 0 and 1. Defaults to 0.85. Requires underlayColor to be set.

TypeRequired
numberNo

onHideUnderlay

Called immediately after the underlay is hidden.

TypeRequired
functionNo

onShowUnderlay

Called immediately after the underlay is shown.

TypeRequired
functionNo

style

TypeRequired
View.styleNo

underlayColor

The color of the underlay that will show through when the touch is active.

TypeRequired
colorNo

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

tvParallaxProperties

(Apple TV only) Object with properties to control Apple TV parallax effects.

enabled: If true, parallax effects are enabled. Defaults to true. shiftDistanceX: Defaults to 2.0. shiftDistanceY: Defaults to 2.0. tiltAngle: Defaults to 0.05. magnification: Defaults to 1.0. pressMagnification: Defaults to 1.0. pressDuration: Defaults to 0.3. pressDelay: Defaults to 0.0.

TypeRequiredPlatform
objectNoiOS

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

testOnly_pressed

Handy for snapshot tests.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/0.61/touchablenativefeedback.html b/docs/0.61/touchablenativefeedback.html index 75b20ac227c..e4e70b4ba9c 100644 --- a/docs/0.61/touchablenativefeedback.html +++ b/docs/0.61/touchablenativefeedback.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

TouchableNativeFeedback

A wrapper for making views respond properly to touches (Android only). On Android this component uses native state drawable to display touch feedback.

At the moment it only supports having a single View instance as a child node, as it's implemented by replacing that View with another instance of RCTView node with some additional properties set.

Background drawable of native feedback touchable can be customized with background property.

Example:

renderButton: function() {
return (
<TouchableNativeFeedback
onPress={this._onPressButton}
background={TouchableNativeFeedback.SelectableBackground()}>
<View style={{width: 150, height: 100, backgroundColor: 'red'}}>
<Text style={{margin: 30}}>Button</Text>
</View>
</TouchableNativeFeedback>
);
},

Reference

Props

Inherits TouchableWithoutFeedback Props.

background

Determines the type of background drawable that's going to be used to display feedback. It takes an object with type property and extra data depending on the type. It's recommended to use one of the static methods to generate that dictionary.

TypeRequired
backgroundPropTypeNo

useForeground

Set to true to add the ripple effect to the foreground of the view, instead of the background. This is useful if one of your child views has a background of its own, or you're e.g. displaying images, and you don't want the ripple to be covered by them.

Check TouchableNativeFeedback.canUseNativeForeground() first, as this is only available on Android 6.0 and above. If you try to use this on older versions you will get a warning and fallback to background.

TypeRequired
boolNo

hasTVPreferredFocus

TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

Methods

SelectableBackground()

static SelectableBackground()

Creates an object that represents android theme's default background for selectable elements (?android:attr/selectableItemBackground).

SelectableBackgroundBorderless()

static SelectableBackgroundBorderless()

Creates an object that represent android theme's default background for borderless selectable elements (?android:attr/selectableItemBackgroundBorderless). Available on android API level 21+.

Ripple()

static Ripple(color: string, borderless: boolean)

Creates an object that represents ripple drawable with specified color (as a string). If property borderless evaluates to true the ripple will render outside of the view bounds (see native actionbar buttons as an example of that behavior). This background type is available on Android API level 21+.

Parameters:

NameTypeRequiredDescription
colorstringYesThe ripple color
borderlessbooleanYesIf the ripple can render outside its bounds

canUseNativeForeground()

static canUseNativeForeground()
Edit this page
Last updated on
- + diff --git a/docs/0.61/touchablenativefeedback/index.html b/docs/0.61/touchablenativefeedback/index.html index 75b20ac227c..e4e70b4ba9c 100644 --- a/docs/0.61/touchablenativefeedback/index.html +++ b/docs/0.61/touchablenativefeedback/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

TouchableNativeFeedback

A wrapper for making views respond properly to touches (Android only). On Android this component uses native state drawable to display touch feedback.

At the moment it only supports having a single View instance as a child node, as it's implemented by replacing that View with another instance of RCTView node with some additional properties set.

Background drawable of native feedback touchable can be customized with background property.

Example:

renderButton: function() {
return (
<TouchableNativeFeedback
onPress={this._onPressButton}
background={TouchableNativeFeedback.SelectableBackground()}>
<View style={{width: 150, height: 100, backgroundColor: 'red'}}>
<Text style={{margin: 30}}>Button</Text>
</View>
</TouchableNativeFeedback>
);
},

Reference

Props

Inherits TouchableWithoutFeedback Props.

background

Determines the type of background drawable that's going to be used to display feedback. It takes an object with type property and extra data depending on the type. It's recommended to use one of the static methods to generate that dictionary.

TypeRequired
backgroundPropTypeNo

useForeground

Set to true to add the ripple effect to the foreground of the view, instead of the background. This is useful if one of your child views has a background of its own, or you're e.g. displaying images, and you don't want the ripple to be covered by them.

Check TouchableNativeFeedback.canUseNativeForeground() first, as this is only available on Android 6.0 and above. If you try to use this on older versions you will get a warning and fallback to background.

TypeRequired
boolNo

hasTVPreferredFocus

TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

Methods

SelectableBackground()

static SelectableBackground()

Creates an object that represents android theme's default background for selectable elements (?android:attr/selectableItemBackground).

SelectableBackgroundBorderless()

static SelectableBackgroundBorderless()

Creates an object that represent android theme's default background for borderless selectable elements (?android:attr/selectableItemBackgroundBorderless). Available on android API level 21+.

Ripple()

static Ripple(color: string, borderless: boolean)

Creates an object that represents ripple drawable with specified color (as a string). If property borderless evaluates to true the ripple will render outside of the view bounds (see native actionbar buttons as an example of that behavior). This background type is available on Android API level 21+.

Parameters:

NameTypeRequiredDescription
colorstringYesThe ripple color
borderlessbooleanYesIf the ripple can render outside its bounds

canUseNativeForeground()

static canUseNativeForeground()
Edit this page
Last updated on
- + diff --git a/docs/0.61/touchableopacity.html b/docs/0.61/touchableopacity.html index bcfc92a1a9b..9edcec37c50 100644 --- a/docs/0.61/touchableopacity.html +++ b/docs/0.61/touchableopacity.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

TouchableOpacity

A wrapper for making views respond properly to touches. On press down, the opacity of the wrapped view is decreased, dimming it.

Opacity is controlled by wrapping the children in an Animated.View, which is added to the view hierarchy. Be aware that this can affect layout.

Example:

renderButton: function() {
return (
<TouchableOpacity onPress={this._onPressButton}>
<Image
style={styles.button}
source={require('./myButton.png')}
/>
</TouchableOpacity>
);
},

Example

Reference

Props

Inherits TouchableWithoutFeedback Props.

style

TypeRequired
View.styleNo

activeOpacity

Determines what the opacity of the wrapped view should be when touch is active. Defaults to 0.2.

TypeRequired
numberNo

tvParallaxProperties

(Apple TV only) Object with properties to control Apple TV parallax effects.

enabled: If true, parallax effects are enabled. Defaults to true. shiftDistanceX: Defaults to 2.0. shiftDistanceY: Defaults to 2.0. tiltAngle: Defaults to 0.05. magnification: Defaults to 1.0. pressMagnification: Defaults to 1.0. pressDuration: Defaults to 0.3. pressDelay: Defaults to 0.0.

TypeRequiredPlatform
objectNoiOS

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

Methods

setOpacityTo()

setOpacityTo((value: number), (duration: number));

Animate the touchable to a new opacity.

Edit this page
Last updated on
- + diff --git a/docs/0.61/touchableopacity/index.html b/docs/0.61/touchableopacity/index.html index bcfc92a1a9b..9edcec37c50 100644 --- a/docs/0.61/touchableopacity/index.html +++ b/docs/0.61/touchableopacity/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

TouchableOpacity

A wrapper for making views respond properly to touches. On press down, the opacity of the wrapped view is decreased, dimming it.

Opacity is controlled by wrapping the children in an Animated.View, which is added to the view hierarchy. Be aware that this can affect layout.

Example:

renderButton: function() {
return (
<TouchableOpacity onPress={this._onPressButton}>
<Image
style={styles.button}
source={require('./myButton.png')}
/>
</TouchableOpacity>
);
},

Example

Reference

Props

Inherits TouchableWithoutFeedback Props.

style

TypeRequired
View.styleNo

activeOpacity

Determines what the opacity of the wrapped view should be when touch is active. Defaults to 0.2.

TypeRequired
numberNo

tvParallaxProperties

(Apple TV only) Object with properties to control Apple TV parallax effects.

enabled: If true, parallax effects are enabled. Defaults to true. shiftDistanceX: Defaults to 2.0. shiftDistanceY: Defaults to 2.0. tiltAngle: Defaults to 0.05. magnification: Defaults to 1.0. pressMagnification: Defaults to 1.0. pressDuration: Defaults to 0.3. pressDelay: Defaults to 0.0.

TypeRequiredPlatform
objectNoiOS

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

Methods

setOpacityTo()

setOpacityTo((value: number), (duration: number));

Animate the touchable to a new opacity.

Edit this page
Last updated on
- + diff --git a/docs/0.61/touchablewithoutfeedback.html b/docs/0.61/touchablewithoutfeedback.html index df28c3ccc66..ca1f7d5ab8f 100644 --- a/docs/0.61/touchablewithoutfeedback.html +++ b/docs/0.61/touchablewithoutfeedback.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
<TouchableWithoutFeedback onPress={() => alert('Pressed!')}>
<MyComponent />
</TouchableWithoutFeedback>;

Reference

Props

accessibilityIgnoresInvertColors

TypeRequired
BooleanNo

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

accessibilityActions

Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The accessibilityActions property should contain a list of action objects. Each action object should contain the field name and label.

See the Accessibility guide for more information.

TypeRequired
arrayNo

onAccessibilityAction

Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform.

See the Accessibility guide for more information.

TypeRequired
functionNo

delayLongPress

Delay in ms, from onPressIn, before onLongPress is called.

TypeRequired
numberNo

delayPressIn

Delay in ms, from the start of the touch, before onPressIn is called.

TypeRequired
numberNo

delayPressOut

Delay in ms, from the release of the touch, before onPressOut is called.

TypeRequired
numberNo

disabled

If true, disable all interactions for this component.

TypeRequired
boolNo

hitSlop

This defines how far your touch can start away from the button. This is added to pressRetentionOffset when moving off of the button. NOTE The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

onBlur

Invoked when the item loses focus.

TypeRequired
functionNo

onFocus

Invoked when the item receives focus.

TypeRequired
functionNo

onLayout

Invoked on mount and layout changes with

{nativeEvent: {layout: {x, y, width, height}}}

TypeRequired
functionNo

onLongPress

TypeRequired
functionNo

onPress

Called when the touch is released, but not if cancelled (e.g. by a scroll that steals the responder lock).

TypeRequired
functionNo

onPressIn

Called as soon as the touchable element is pressed and invoked even before onPress. This can be useful when making network requests.

TypeRequired
functionNo

onPressOut

Called as soon as the touch is released even before onPress.

TypeRequired
functionNo

pressRetentionOffset

When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

nativeID

TypeRequired
stringNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

touchSoundDisabled

If true, doesn't play a system sound on touch.

TypeRequiredPlatform
BooleanNoAndroid

Type Definitions

Event

Type
Object
Edit this page
Last updated on
- + diff --git a/docs/0.61/touchablewithoutfeedback/index.html b/docs/0.61/touchablewithoutfeedback/index.html index df28c3ccc66..ca1f7d5ab8f 100644 --- a/docs/0.61/touchablewithoutfeedback/index.html +++ b/docs/0.61/touchablewithoutfeedback/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
<TouchableWithoutFeedback onPress={() => alert('Pressed!')}>
<MyComponent />
</TouchableWithoutFeedback>;

Reference

Props

accessibilityIgnoresInvertColors

TypeRequired
BooleanNo

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

accessibilityActions

Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The accessibilityActions property should contain a list of action objects. Each action object should contain the field name and label.

See the Accessibility guide for more information.

TypeRequired
arrayNo

onAccessibilityAction

Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform.

See the Accessibility guide for more information.

TypeRequired
functionNo

delayLongPress

Delay in ms, from onPressIn, before onLongPress is called.

TypeRequired
numberNo

delayPressIn

Delay in ms, from the start of the touch, before onPressIn is called.

TypeRequired
numberNo

delayPressOut

Delay in ms, from the release of the touch, before onPressOut is called.

TypeRequired
numberNo

disabled

If true, disable all interactions for this component.

TypeRequired
boolNo

hitSlop

This defines how far your touch can start away from the button. This is added to pressRetentionOffset when moving off of the button. NOTE The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

onBlur

Invoked when the item loses focus.

TypeRequired
functionNo

onFocus

Invoked when the item receives focus.

TypeRequired
functionNo

onLayout

Invoked on mount and layout changes with

{nativeEvent: {layout: {x, y, width, height}}}

TypeRequired
functionNo

onLongPress

TypeRequired
functionNo

onPress

Called when the touch is released, but not if cancelled (e.g. by a scroll that steals the responder lock).

TypeRequired
functionNo

onPressIn

Called as soon as the touchable element is pressed and invoked even before onPress. This can be useful when making network requests.

TypeRequired
functionNo

onPressOut

Called as soon as the touch is released even before onPress.

TypeRequired
functionNo

pressRetentionOffset

When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

nativeID

TypeRequired
stringNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

touchSoundDisabled

If true, doesn't play a system sound on touch.

TypeRequiredPlatform
BooleanNoAndroid

Type Definitions

Event

Type
Object
Edit this page
Last updated on
- + diff --git a/docs/0.61/transforms.html b/docs/0.61/transforms.html index 3207d47c702..45e34e98b34 100644 --- a/docs/0.61/transforms.html +++ b/docs/0.61/transforms.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Transforms

Reference

Props

decomposedMatrix

Deprecated. Use the transform prop instead.

TypeRequired
DecomposedMatrixPropTypeNo

rotation

TypeRequired
deprecatedPropType(ReactPropTypes.number, 'Use the transform prop instead.')No

scaleX

TypeRequired
deprecatedPropType(ReactPropTypes.number, 'Use the transform prop instead.')No

scaleY

TypeRequired
deprecatedPropType(ReactPropTypes.number, 'Use the transform prop instead.')No

transform

transform accepts an array of transformation objects. Each object specifies the property that will be transformed as the key, and the value to use in the transformation. Objects should not be combined. Use a single key/value pair per object.

The rotate transformations require a string so that the transform may be expressed in degrees (deg) or radians (rad). For example:

transform([{ rotateX: '45deg' }, { rotateZ: '0.785398rad' }])

The skew transformations require a string so that the transform may be expressed in degrees (deg). For example:

transform([{ skewX: '45deg' }])

TypeRequired
array of object: {perspective: number}, ,object: {rotate: string}, ,object: {rotateX: string}, ,object: {rotateY: string}, ,object: {rotateZ: string}, ,object: {scale: number}, ,object: {scaleX: number}, ,object: {scaleY: number}, ,object: {translateX: number}, ,object: {translateY: number}, ,object: {skewX: string}, ,object: {skewY: string}No

transformMatrix

Deprecated. Use the transform prop instead.

TypeRequired
TransformMatrixPropTypeNo

translateX

TypeRequired
deprecatedPropType(ReactPropTypes.number, 'Use the transform prop instead.')No

translateY

TypeRequired
deprecatedPropType(ReactPropTypes.number, 'Use the transform prop instead.')No
Edit this page
Last updated on
- + diff --git a/docs/0.61/transforms/index.html b/docs/0.61/transforms/index.html index 3207d47c702..45e34e98b34 100644 --- a/docs/0.61/transforms/index.html +++ b/docs/0.61/transforms/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Transforms

Reference

Props

decomposedMatrix

Deprecated. Use the transform prop instead.

TypeRequired
DecomposedMatrixPropTypeNo

rotation

TypeRequired
deprecatedPropType(ReactPropTypes.number, 'Use the transform prop instead.')No

scaleX

TypeRequired
deprecatedPropType(ReactPropTypes.number, 'Use the transform prop instead.')No

scaleY

TypeRequired
deprecatedPropType(ReactPropTypes.number, 'Use the transform prop instead.')No

transform

transform accepts an array of transformation objects. Each object specifies the property that will be transformed as the key, and the value to use in the transformation. Objects should not be combined. Use a single key/value pair per object.

The rotate transformations require a string so that the transform may be expressed in degrees (deg) or radians (rad). For example:

transform([{ rotateX: '45deg' }, { rotateZ: '0.785398rad' }])

The skew transformations require a string so that the transform may be expressed in degrees (deg). For example:

transform([{ skewX: '45deg' }])

TypeRequired
array of object: {perspective: number}, ,object: {rotate: string}, ,object: {rotateX: string}, ,object: {rotateY: string}, ,object: {rotateZ: string}, ,object: {scale: number}, ,object: {scaleX: number}, ,object: {scaleY: number}, ,object: {translateX: number}, ,object: {translateY: number}, ,object: {skewX: string}, ,object: {skewY: string}No

transformMatrix

Deprecated. Use the transform prop instead.

TypeRequired
TransformMatrixPropTypeNo

translateX

TypeRequired
deprecatedPropType(ReactPropTypes.number, 'Use the transform prop instead.')No

translateY

TypeRequired
deprecatedPropType(ReactPropTypes.number, 'Use the transform prop instead.')No
Edit this page
Last updated on
- + diff --git a/docs/0.61/troubleshooting.html b/docs/0.61/troubleshooting.html index cbe891b37ac..b2d23c39d0c 100644 --- a/docs/0.61/troubleshooting.html +++ b/docs/0.61/troubleshooting.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Troubleshooting

These are some common issues you may run into while setting up React Native. If you encounter something that is not listed here, try searching for the issue in GitHub.

Port already in use

The Metro bundler runs on port 8081. If another process is already using that port, you can either terminate that process, or change the port that the bundler uses.

Terminating a process on port 8081

Run the following command to find the id for the process that is listening on port 8081:

$ sudo lsof -i :8081

Then run the following to terminate the process:

$ kill -9 <PID>

On Windows you can find the process using port 8081 using Resource Monitor and stop it using Task Manager.

Using a port other than 8081

You can configure the bundler to use a port other than 8081 by using the port parameter:

$ react-native start --port=8088

You will also need to update your applications to load the JavaScript bundle from the new port. If running on device from Xcode, you can do this by updating occurrences of 8081 to your chosen port in the node_modules/react-native/React/React.xcodeproj/project.pbxproj file.

NPM locking error

If you encounter an error such as npm WARN locking Error: EACCES while using the React Native CLI, try running the following:

sudo chown -R $USER ~/.npm
sudo chown -R $USER /usr/local/lib/node_modules

Missing libraries for React

If you added React Native manually to your project, make sure you have included all the relevant dependencies that you are using, like RCTText.xcodeproj, RCTImage.xcodeproj. Next, the binaries built by these dependencies have to be linked to your app binary. Use the Linked Frameworks and Binaries section in the Xcode project settings. More detailed steps are here: Linking Libraries.

If you are using CocoaPods, verify that you have added React along with the subspecs to the Podfile. For example, if you were using the <Text />, <Image /> and fetch() APIs, you would need to add these in your Podfile:

pod 'React', :path => '../node_modules/react-native', :subspecs => [
'RCTText',
'RCTImage',
'RCTNetwork',
'RCTWebSocket',
]

Next, make sure you have run pod install and that a Pods/ directory has been created in your project with React installed. CocoaPods will instruct you to use the generated .xcworkspace file henceforth to be able to use these installed dependencies.

React Native does not compile when being used as a CocoaPod

There is a CocoaPods plugin called cocoapods-fix-react-native which handles any potential post-fixing of the source code due to differences when using a dependency manager.

Argument list too long: recursive header expansion failed

In the project's build settings, User Search Header Paths and Header Search Paths are two configs that specify where Xcode should look for #import header files specified in the code. For Pods, CocoaPods uses a default array of specific folders to look in. Verify that this particular config is not overwritten, and that none of the folders configured are too large. If one of the folders is a large folder, Xcode will attempt to recursively search the entire directory and throw above error at some point.

To revert the User Search Header Paths and Header Search Paths build settings to their defaults set by CocoaPods - select the entry in the Build Settings panel, and hit delete. It will remove the custom override and return to the CocoaPod defaults.

No transports available

React Native implements a polyfill for WebSockets. These polyfills are initialized as part of the react-native module that you include in your application through import React from 'react'. If you load another module that requires WebSockets, such as Firebase, be sure to load/require it after react-native:

import React from 'react';
import Firebase from 'firebase';

Shell Command Unresponsive Exception

If you encounter a ShellCommandUnresponsiveException exception such as:

Execution failed for task ':app:installDebug'.
com.android.builder.testing.api.DeviceException: com.android.ddmlib.ShellCommandUnresponsiveException

Try downgrading your Gradle version to 1.2.3 in android/build.gradle.

react-native init hangs

If you run into issues where running react-native init hangs in your system, try running it again in verbose mode and referring to #2797 for common causes:

react-native init --verbose

Unable to start react-native package manager (on Linux)

Case 1: Error "code":"ENOSPC","errno":"ENOSPC"

Issue caused by the number of directories inotify (used by watchman on Linux) can monitor. To solve it, run this command in your terminal window

echo fs.inotify.max_user_watches=582222 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
Edit this page
Last updated on
- + diff --git a/docs/0.61/troubleshooting/index.html b/docs/0.61/troubleshooting/index.html index cbe891b37ac..b2d23c39d0c 100644 --- a/docs/0.61/troubleshooting/index.html +++ b/docs/0.61/troubleshooting/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Troubleshooting

These are some common issues you may run into while setting up React Native. If you encounter something that is not listed here, try searching for the issue in GitHub.

Port already in use

The Metro bundler runs on port 8081. If another process is already using that port, you can either terminate that process, or change the port that the bundler uses.

Terminating a process on port 8081

Run the following command to find the id for the process that is listening on port 8081:

$ sudo lsof -i :8081

Then run the following to terminate the process:

$ kill -9 <PID>

On Windows you can find the process using port 8081 using Resource Monitor and stop it using Task Manager.

Using a port other than 8081

You can configure the bundler to use a port other than 8081 by using the port parameter:

$ react-native start --port=8088

You will also need to update your applications to load the JavaScript bundle from the new port. If running on device from Xcode, you can do this by updating occurrences of 8081 to your chosen port in the node_modules/react-native/React/React.xcodeproj/project.pbxproj file.

NPM locking error

If you encounter an error such as npm WARN locking Error: EACCES while using the React Native CLI, try running the following:

sudo chown -R $USER ~/.npm
sudo chown -R $USER /usr/local/lib/node_modules

Missing libraries for React

If you added React Native manually to your project, make sure you have included all the relevant dependencies that you are using, like RCTText.xcodeproj, RCTImage.xcodeproj. Next, the binaries built by these dependencies have to be linked to your app binary. Use the Linked Frameworks and Binaries section in the Xcode project settings. More detailed steps are here: Linking Libraries.

If you are using CocoaPods, verify that you have added React along with the subspecs to the Podfile. For example, if you were using the <Text />, <Image /> and fetch() APIs, you would need to add these in your Podfile:

pod 'React', :path => '../node_modules/react-native', :subspecs => [
'RCTText',
'RCTImage',
'RCTNetwork',
'RCTWebSocket',
]

Next, make sure you have run pod install and that a Pods/ directory has been created in your project with React installed. CocoaPods will instruct you to use the generated .xcworkspace file henceforth to be able to use these installed dependencies.

React Native does not compile when being used as a CocoaPod

There is a CocoaPods plugin called cocoapods-fix-react-native which handles any potential post-fixing of the source code due to differences when using a dependency manager.

Argument list too long: recursive header expansion failed

In the project's build settings, User Search Header Paths and Header Search Paths are two configs that specify where Xcode should look for #import header files specified in the code. For Pods, CocoaPods uses a default array of specific folders to look in. Verify that this particular config is not overwritten, and that none of the folders configured are too large. If one of the folders is a large folder, Xcode will attempt to recursively search the entire directory and throw above error at some point.

To revert the User Search Header Paths and Header Search Paths build settings to their defaults set by CocoaPods - select the entry in the Build Settings panel, and hit delete. It will remove the custom override and return to the CocoaPod defaults.

No transports available

React Native implements a polyfill for WebSockets. These polyfills are initialized as part of the react-native module that you include in your application through import React from 'react'. If you load another module that requires WebSockets, such as Firebase, be sure to load/require it after react-native:

import React from 'react';
import Firebase from 'firebase';

Shell Command Unresponsive Exception

If you encounter a ShellCommandUnresponsiveException exception such as:

Execution failed for task ':app:installDebug'.
com.android.builder.testing.api.DeviceException: com.android.ddmlib.ShellCommandUnresponsiveException

Try downgrading your Gradle version to 1.2.3 in android/build.gradle.

react-native init hangs

If you run into issues where running react-native init hangs in your system, try running it again in verbose mode and referring to #2797 for common causes:

react-native init --verbose

Unable to start react-native package manager (on Linux)

Case 1: Error "code":"ENOSPC","errno":"ENOSPC"

Issue caused by the number of directories inotify (used by watchman on Linux) can monitor. To solve it, run this command in your terminal window

echo fs.inotify.max_user_watches=582222 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
Edit this page
Last updated on
- + diff --git a/docs/0.61/tutorial.html b/docs/0.61/tutorial.html index f142be55065..87ba9ff1e6a 100644 --- a/docs/0.61/tutorial.html +++ b/docs/0.61/tutorial.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Learn the Basics

React Native is like React, but it uses native components instead of web components as building blocks. So to understand the basic structure of a React Native app, you need to understand some of the basic React concepts, like JSX, components, state, and props. If you already know React, you still need to learn some React-Native-specific stuff, like the native components. This tutorial is aimed at all audiences, whether you have React experience or not.

Let's do this thing.

Hello World

In accordance with the ancient traditions of our people, we must first build an app that does nothing except say "Hello, world!". Here it is:

If you are feeling curious, you can play around with sample code directly in the web simulators. You can also paste it into your App.js file to create a real app on your local machine.

What's going on here?

Some of the things in here might not look like JavaScript to you. Don't panic. This is the future.

First of all, ES2015 (also known as ES6) is a set of improvements to JavaScript that is now part of the official standard, but not yet supported by all browsers, so often it isn't used yet in web development. React Native ships with ES2015 support, so you can use this stuff without worrying about compatibility. import, from, class, and extends in the example above are all ES2015 features. If you aren't familiar with ES2015, you can probably pick it up by reading through sample code like this tutorial has. If you want, this page has a good overview of ES2015 features.

The other unusual thing in this code example is <View><Text>Hello world!</Text></View>. This is JSX - a syntax for embedding XML within JavaScript. Many frameworks use a specialized templating language which lets you embed code inside markup language. In React, this is reversed. JSX lets you write your markup language inside code. It looks like HTML on the web, except instead of web things like <div> or <span>, you use React components. In this case, <Text> is a Core Component that displays some text and View is like the <div> or <span>.

Components

So this code is defining HelloWorldApp, a new Component. When you're building a React Native app, you'll be making new components a lot. Anything you see on the screen is some sort of component. A component can be pretty basic - the only thing that's required is a render function which returns some JSX to render.

This app doesn't do very much

Good point. To make components do more interesting things, you need to learn about Props.

Edit this page
Last updated on
- + diff --git a/docs/0.61/tutorial/index.html b/docs/0.61/tutorial/index.html index f142be55065..87ba9ff1e6a 100644 --- a/docs/0.61/tutorial/index.html +++ b/docs/0.61/tutorial/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Learn the Basics

React Native is like React, but it uses native components instead of web components as building blocks. So to understand the basic structure of a React Native app, you need to understand some of the basic React concepts, like JSX, components, state, and props. If you already know React, you still need to learn some React-Native-specific stuff, like the native components. This tutorial is aimed at all audiences, whether you have React experience or not.

Let's do this thing.

Hello World

In accordance with the ancient traditions of our people, we must first build an app that does nothing except say "Hello, world!". Here it is:

If you are feeling curious, you can play around with sample code directly in the web simulators. You can also paste it into your App.js file to create a real app on your local machine.

What's going on here?

Some of the things in here might not look like JavaScript to you. Don't panic. This is the future.

First of all, ES2015 (also known as ES6) is a set of improvements to JavaScript that is now part of the official standard, but not yet supported by all browsers, so often it isn't used yet in web development. React Native ships with ES2015 support, so you can use this stuff without worrying about compatibility. import, from, class, and extends in the example above are all ES2015 features. If you aren't familiar with ES2015, you can probably pick it up by reading through sample code like this tutorial has. If you want, this page has a good overview of ES2015 features.

The other unusual thing in this code example is <View><Text>Hello world!</Text></View>. This is JSX - a syntax for embedding XML within JavaScript. Many frameworks use a specialized templating language which lets you embed code inside markup language. In React, this is reversed. JSX lets you write your markup language inside code. It looks like HTML on the web, except instead of web things like <div> or <span>, you use React components. In this case, <Text> is a Core Component that displays some text and View is like the <div> or <span>.

Components

So this code is defining HelloWorldApp, a new Component. When you're building a React Native app, you'll be making new components a lot. Anything you see on the screen is some sort of component. A component can be pretty basic - the only thing that's required is a render function which returns some JSX to render.

This app doesn't do very much

Good point. To make components do more interesting things, you need to learn about Props.

Edit this page
Last updated on
- + diff --git a/docs/0.61/typescript.html b/docs/0.61/typescript.html index f766671e527..56a7eab8e26 100644 --- a/docs/0.61/typescript.html +++ b/docs/0.61/typescript.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@
// styles
const styles = StyleSheet.create({
root: {
alignItems: 'center',
alignSelf: 'center',
},
buttons: {
flexDirection: 'row',
minHeight: 70,
alignItems: 'stretch',
alignSelf: 'center',
borderWidth: 5,
},
button: {
flex: 1,
paddingVertical: 0,
},
greeting: {
color: '#999',
fontWeight: 'bold',
},
});

You can explore the syntax more in the TypeScript playground.

Where to Find Useful Advice

Using Custom Path Aliases with TypeScript

To use custom path aliases with TypeScript, you need to set the path aliases to work from both Babel and TypeScript. Here's how:

  1. Edit your tsconfig.json to have your custom path mappings. Set anything in the root of src to be available with no preceding path reference, and allow any test file to be accessed by using test/File.tsx:
"target": "esnext",
+ "baseUrl": ".",
+ "paths": {
+ "*": ["src/*"],
+ "tests": ["tests/*"]
+ },
}
  1. Configure the Babel side done by adding a new dependency, babel-plugin-module-resolver:
yarn add --dev babel-plugin-module-resolver
# or
npm install --save-dev babel-plugin-module-resolver
  1. Finally, configure your babel.config.js (note that the syntax for your babel.config.js is different from your tsconfig.json):
{
plugins: [
+ [
+ 'module-resolver',
+ {
+ root: ['./src'],
+ extensions: ['.ios.js', '.android.js', '.js', '.ts', '.tsx', '.json'],
+ alias: {
+ "test/*": ["./test/"],
+ }
+ }
+ ]
]
}
Edit this page
Last updated on
- + diff --git a/docs/0.61/typescript/index.html b/docs/0.61/typescript/index.html index f766671e527..56a7eab8e26 100644 --- a/docs/0.61/typescript/index.html +++ b/docs/0.61/typescript/index.html @@ -19,7 +19,7 @@ - + @@ -40,7 +40,7 @@
// styles
const styles = StyleSheet.create({
root: {
alignItems: 'center',
alignSelf: 'center',
},
buttons: {
flexDirection: 'row',
minHeight: 70,
alignItems: 'stretch',
alignSelf: 'center',
borderWidth: 5,
},
button: {
flex: 1,
paddingVertical: 0,
},
greeting: {
color: '#999',
fontWeight: 'bold',
},
});

You can explore the syntax more in the TypeScript playground.

Where to Find Useful Advice

Using Custom Path Aliases with TypeScript

To use custom path aliases with TypeScript, you need to set the path aliases to work from both Babel and TypeScript. Here's how:

  1. Edit your tsconfig.json to have your custom path mappings. Set anything in the root of src to be available with no preceding path reference, and allow any test file to be accessed by using test/File.tsx:
"target": "esnext",
+ "baseUrl": ".",
+ "paths": {
+ "*": ["src/*"],
+ "tests": ["tests/*"]
+ },
}
  1. Configure the Babel side done by adding a new dependency, babel-plugin-module-resolver:
yarn add --dev babel-plugin-module-resolver
# or
npm install --save-dev babel-plugin-module-resolver
  1. Finally, configure your babel.config.js (note that the syntax for your babel.config.js is different from your tsconfig.json):
{
plugins: [
+ [
+ 'module-resolver',
+ {
+ root: ['./src'],
+ extensions: ['.ios.js', '.android.js', '.js', '.ts', '.tsx', '.json'],
+ alias: {
+ "test/*": ["./test/"],
+ }
+ }
+ ]
]
}
Edit this page
Last updated on
- + diff --git a/docs/0.61/upgrading.html b/docs/0.61/upgrading.html index 21a4f831c21..e12f7a87cdc 100644 --- a/docs/0.61/upgrading.html +++ b/docs/0.61/upgrading.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Upgrading to new React Native versions

Upgrading to new versions of React Native will give you access to more APIs, views, developer tools and other goodies. Upgrading requires a small amount of effort, but we try to make it straightforward for you.

Expo projects

Upgrading your Expo project to a new version of React Native requires updating the react-native, react, and expo package versions in your package.json file. Please refer to this list to find out what versions are supported. You will also need to set the correct sdkVersion in your app.json file.

See the Upgrading Expo SDK Walkthrough for up-to-date information about upgrading your project.

React Native projects

Because typical React Native projects are essentially made up of an Android project, an iOS project, and a JavaScript project, upgrading can be rather tricky. There's currently two ways for upgrading your React Native project: by using React Native CLI or manually with Upgrade Helper.

React Native CLI

The React Native CLI comes with upgrade command that provides a one-step operation to upgrade the source files with a minimum of conflicts, it internally uses rn-diff-purge project to find out which files need to be created, removed or modified.

1. Run the upgrade command

The upgrade command works on top of Git by using git apply with 3-way merge, therefore it's required to use Git in order for this to work, if you don't use Git but still want to use this solution then you can check out how to do it in the Troubleshooting section.

Run the following command to start the process of upgrading to the latest version:

react-native upgrade

You may specify a React Native version by passing an argument, e.g. to upgrade to 0.61.0-rc.0 run:

react-native upgrade 0.61.0-rc.0

The project is upgraded using git apply with 3-way merge, it may happen that you'll need to resolve a few conflicts after it's finished.

2. Resolve the conflicts

Conflicted files include delimiters which make very clear where the changes come from. For example:

13B07F951A680F5B00A75B9A /* Release */ = {
isa = XCBuildConfiguration;
buildSettings = {
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
<<<<<<< ours
CODE_SIGN_IDENTITY = "iPhone Developer";
FRAMEWORK_SEARCH_PATHS = (
"$(inherited)",
"$(PROJECT_DIR)/HockeySDK.embeddedframework",
"$(PROJECT_DIR)/HockeySDK-iOS/HockeySDK.embeddedframework",
);
=======
CURRENT_PROJECT_VERSION = 1;
>>>>>>> theirs
HEADER_SEARCH_PATHS = (
"$(inherited)",
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include,
"$(SRCROOT)/../node_modules/react-native/React/**",
"$(SRCROOT)/../node_modules/react-native-code-push/ios/CodePush/**",
);

You can think of "ours" as "your team" and "theirs" as "the React Native development team".

Upgrade Helper

The Upgrade Helper is a web tool to help you out when upgrading your apps by providing the full set of changes happening between any two versions. It also shows comments on specific files to help understanding why that change is needed.

1. Select the versions

You first need to select from and to which version you wish to upgrade, by default the latest major versions are selected. After selecting you can click the button "Show me how to upgrade".

💡 Major updates will show an "useful content" section on the top with links to help you out when upgrading.

2. Upgrade dependencies

The first file that is shown is the package.json, it's good to update the dependencies that are showing in there. For example, if react-native and react appears as changes then you can install it in your project by running yarn add:

# {{VERSION}} and {{REACT_VERSION}} are the release versions showing in the diff
yarn add react-native@{{VERSION}}
yarn add react@{{REACT_VERSION}}

3. Upgrade your project files

The new release may contain updates to other files that are generated when you run react-native init, those files are listed after the package.json in the Upgrade Helper page. If there aren't other changes then you can rebuild the project and continue developing.

In case there are changes then you can either update them manually by copying and pasting from the changes in the page or you can do it with the React Native CLI upgrade command by running:

react-native upgrade

This will check your files against the latest template and perform the following:

  • If there is a new file in the template, it is created.
  • If a file in the template is identical to your file, it is skipped.
  • If a file is different in your project than the template, you will be prompted; you have options to keep your file or overwrite it with the template version.

Some upgrades won't be done automatically with the React Native CLI and require manual work, e.g. 0.28 to 0.29, or 0.56 to 0.57. Make sure to check the release notes when upgrading so that you can identify any manual changes your particular project may require.

Troubleshooting

I want to upgrade with React Native CLI but I don't use Git

While your project does not have to be handled by the Git versioning system -- you can use Mercurial, SVN, or nothing -- you will still need to install Git on your system in order to use react-native upgrade. Git will also need to be available in the PATH. If your project doesn't use Git, initialize it and commit:

git init # Initialize a Git repository
git add . # Stage all the current files
git commit -m "Upgrade react-native" # Save the current files in a commit

After you finish upgrading you may remove the .git directory.

I have done all the changes but my app is still using an old version

These sort of errors are usually related to caching, it's recommended to install react-native-clean-project to clear all your project's cache and then you can run it again.

Edit this page
Last updated on
- + diff --git a/docs/0.61/upgrading/index.html b/docs/0.61/upgrading/index.html index 21a4f831c21..e12f7a87cdc 100644 --- a/docs/0.61/upgrading/index.html +++ b/docs/0.61/upgrading/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Upgrading to new React Native versions

Upgrading to new versions of React Native will give you access to more APIs, views, developer tools and other goodies. Upgrading requires a small amount of effort, but we try to make it straightforward for you.

Expo projects

Upgrading your Expo project to a new version of React Native requires updating the react-native, react, and expo package versions in your package.json file. Please refer to this list to find out what versions are supported. You will also need to set the correct sdkVersion in your app.json file.

See the Upgrading Expo SDK Walkthrough for up-to-date information about upgrading your project.

React Native projects

Because typical React Native projects are essentially made up of an Android project, an iOS project, and a JavaScript project, upgrading can be rather tricky. There's currently two ways for upgrading your React Native project: by using React Native CLI or manually with Upgrade Helper.

React Native CLI

The React Native CLI comes with upgrade command that provides a one-step operation to upgrade the source files with a minimum of conflicts, it internally uses rn-diff-purge project to find out which files need to be created, removed or modified.

1. Run the upgrade command

The upgrade command works on top of Git by using git apply with 3-way merge, therefore it's required to use Git in order for this to work, if you don't use Git but still want to use this solution then you can check out how to do it in the Troubleshooting section.

Run the following command to start the process of upgrading to the latest version:

react-native upgrade

You may specify a React Native version by passing an argument, e.g. to upgrade to 0.61.0-rc.0 run:

react-native upgrade 0.61.0-rc.0

The project is upgraded using git apply with 3-way merge, it may happen that you'll need to resolve a few conflicts after it's finished.

2. Resolve the conflicts

Conflicted files include delimiters which make very clear where the changes come from. For example:

13B07F951A680F5B00A75B9A /* Release */ = {
isa = XCBuildConfiguration;
buildSettings = {
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
<<<<<<< ours
CODE_SIGN_IDENTITY = "iPhone Developer";
FRAMEWORK_SEARCH_PATHS = (
"$(inherited)",
"$(PROJECT_DIR)/HockeySDK.embeddedframework",
"$(PROJECT_DIR)/HockeySDK-iOS/HockeySDK.embeddedframework",
);
=======
CURRENT_PROJECT_VERSION = 1;
>>>>>>> theirs
HEADER_SEARCH_PATHS = (
"$(inherited)",
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include,
"$(SRCROOT)/../node_modules/react-native/React/**",
"$(SRCROOT)/../node_modules/react-native-code-push/ios/CodePush/**",
);

You can think of "ours" as "your team" and "theirs" as "the React Native development team".

Upgrade Helper

The Upgrade Helper is a web tool to help you out when upgrading your apps by providing the full set of changes happening between any two versions. It also shows comments on specific files to help understanding why that change is needed.

1. Select the versions

You first need to select from and to which version you wish to upgrade, by default the latest major versions are selected. After selecting you can click the button "Show me how to upgrade".

💡 Major updates will show an "useful content" section on the top with links to help you out when upgrading.

2. Upgrade dependencies

The first file that is shown is the package.json, it's good to update the dependencies that are showing in there. For example, if react-native and react appears as changes then you can install it in your project by running yarn add:

# {{VERSION}} and {{REACT_VERSION}} are the release versions showing in the diff
yarn add react-native@{{VERSION}}
yarn add react@{{REACT_VERSION}}

3. Upgrade your project files

The new release may contain updates to other files that are generated when you run react-native init, those files are listed after the package.json in the Upgrade Helper page. If there aren't other changes then you can rebuild the project and continue developing.

In case there are changes then you can either update them manually by copying and pasting from the changes in the page or you can do it with the React Native CLI upgrade command by running:

react-native upgrade

This will check your files against the latest template and perform the following:

  • If there is a new file in the template, it is created.
  • If a file in the template is identical to your file, it is skipped.
  • If a file is different in your project than the template, you will be prompted; you have options to keep your file or overwrite it with the template version.

Some upgrades won't be done automatically with the React Native CLI and require manual work, e.g. 0.28 to 0.29, or 0.56 to 0.57. Make sure to check the release notes when upgrading so that you can identify any manual changes your particular project may require.

Troubleshooting

I want to upgrade with React Native CLI but I don't use Git

While your project does not have to be handled by the Git versioning system -- you can use Mercurial, SVN, or nothing -- you will still need to install Git on your system in order to use react-native upgrade. Git will also need to be available in the PATH. If your project doesn't use Git, initialize it and commit:

git init # Initialize a Git repository
git add . # Stage all the current files
git commit -m "Upgrade react-native" # Save the current files in a commit

After you finish upgrading you may remove the .git directory.

I have done all the changes but my app is still using an old version

These sort of errors are usually related to caching, it's recommended to install react-native-clean-project to clear all your project's cache and then you can run it again.

Edit this page
Last updated on
- + diff --git a/docs/0.61/usewindowdimensions.html b/docs/0.61/usewindowdimensions.html index 1f522baa8f3..176433c0501 100644 --- a/docs/0.61/usewindowdimensions.html +++ b/docs/0.61/usewindowdimensions.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

useWindowDimensions

import { useWindowDimensions } from 'react-native';

useWindowDimensions automatically updates width and height values when screen size changes. You can get your application window's width and height like so:

const windowWidth = useWindowDimensions().width;
const windowHeight = useWindowDimensions().height;

Example

Properties

fontScale

The scale of the font currently used. Some operating systems allow users to scale their font sizes larger or smaller for reading comfort. This property will let you know what is in effect.

useWindowDimensions().fontScale;

height

The height in pixels of the window or screen your app occupies.

useWindowDimensions().height;

scale

The ]pixel ratio of the device your app is running on.

useWindowDimensions().scale;

A value of 1 indicates PPI/DPI of 96 (76 on some platforms). 2 indicates a Retina or high DPI display.

width

The width in pixels of the window or screen your app occupies.

useWindowDimensions().width;
Edit this page
Last updated on
- + diff --git a/docs/0.61/usewindowdimensions/index.html b/docs/0.61/usewindowdimensions/index.html index 1f522baa8f3..176433c0501 100644 --- a/docs/0.61/usewindowdimensions/index.html +++ b/docs/0.61/usewindowdimensions/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

useWindowDimensions

import { useWindowDimensions } from 'react-native';

useWindowDimensions automatically updates width and height values when screen size changes. You can get your application window's width and height like so:

const windowWidth = useWindowDimensions().width;
const windowHeight = useWindowDimensions().height;

Example

Properties

fontScale

The scale of the font currently used. Some operating systems allow users to scale their font sizes larger or smaller for reading comfort. This property will let you know what is in effect.

useWindowDimensions().fontScale;

height

The height in pixels of the window or screen your app occupies.

useWindowDimensions().height;

scale

The ]pixel ratio of the device your app is running on.

useWindowDimensions().scale;

A value of 1 indicates PPI/DPI of 96 (76 on some platforms). 2 indicates a Retina or high DPI display.

width

The width in pixels of the window or screen your app occupies.

useWindowDimensions().width;
Edit this page
Last updated on
- + diff --git a/docs/0.61/using-a-listview.html b/docs/0.61/using-a-listview.html index 55c5f90ef41..6918eb6d3d4 100644 --- a/docs/0.61/using-a-listview.html +++ b/docs/0.61/using-a-listview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Using List Views

React Native provides a suite of components for presenting lists of data. Generally, you'll want to use either FlatList or SectionList.

The FlatList component displays a scrolling list of changing, but similarly structured, data. FlatList works well for long lists of data, where the number of items might change over time. Unlike the more generic ScrollView, the FlatList only renders elements that are currently showing on the screen, not all the elements at once.

The FlatList component requires two props: data and renderItem. data is the source of information for the list. renderItem takes one item from the source and returns a formatted component to render.

This example creates a basic FlatList of hardcoded data. Each item in the data props is rendered as a Text component. The FlatListBasics component then renders the FlatList and all Text components.

If you want to render a set of data broken into logical sections, maybe with section headers, similar to UITableViews on iOS, then a SectionList is the way to go.

One of the most common uses for a list view is displaying data that you fetch from a server. To do that, you will need to learn about networking in React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.61/using-a-listview/index.html b/docs/0.61/using-a-listview/index.html index 55c5f90ef41..6918eb6d3d4 100644 --- a/docs/0.61/using-a-listview/index.html +++ b/docs/0.61/using-a-listview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Using List Views

React Native provides a suite of components for presenting lists of data. Generally, you'll want to use either FlatList or SectionList.

The FlatList component displays a scrolling list of changing, but similarly structured, data. FlatList works well for long lists of data, where the number of items might change over time. Unlike the more generic ScrollView, the FlatList only renders elements that are currently showing on the screen, not all the elements at once.

The FlatList component requires two props: data and renderItem. data is the source of information for the list. renderItem takes one item from the source and returns a formatted component to render.

This example creates a basic FlatList of hardcoded data. Each item in the data props is rendered as a Text component. The FlatListBasics component then renders the FlatList and all Text components.

If you want to render a set of data broken into logical sections, maybe with section headers, similar to UITableViews on iOS, then a SectionList is the way to go.

One of the most common uses for a list view is displaying data that you fetch from a server. To do that, you will need to learn about networking in React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.61/using-a-scrollview.html b/docs/0.61/using-a-scrollview.html index de6b22de289..ea3e6090a9a 100644 --- a/docs/0.61/using-a-scrollview.html +++ b/docs/0.61/using-a-scrollview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Using a ScrollView

The ScrollView is a generic scrolling container that can contain multiple components and views. The scrollable items need not be homogeneous, and you can scroll both vertically and horizontally (by setting the horizontal property).

This example creates a vertical ScrollView with both images and text mixed together.

ScrollViews can be configured to allow paging through views using swiping gestures by using the pagingEnabled props. Swiping horizontally between views can also be implemented on Android using the ViewPager component.

On iOS a ScrollView with a single item can be used to allow the user to zoom content. Set up the maximumZoomScale and minimumZoomScale props and your user will be able to use pinch and expand gestures to zoom in and out.

The ScrollView works best to present a small amount of things of a limited size. All the elements and views of a ScrollView are rendered, even if they are not currently shown on the screen. If you have a long list of more items than can fit on the screen, you should use a FlatList instead. So let's learn about list views next.

Edit this page
Last updated on
- + diff --git a/docs/0.61/using-a-scrollview/index.html b/docs/0.61/using-a-scrollview/index.html index de6b22de289..ea3e6090a9a 100644 --- a/docs/0.61/using-a-scrollview/index.html +++ b/docs/0.61/using-a-scrollview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

Using a ScrollView

The ScrollView is a generic scrolling container that can contain multiple components and views. The scrollable items need not be homogeneous, and you can scroll both vertically and horizontally (by setting the horizontal property).

This example creates a vertical ScrollView with both images and text mixed together.

ScrollViews can be configured to allow paging through views using swiping gestures by using the pagingEnabled props. Swiping horizontally between views can also be implemented on Android using the ViewPager component.

On iOS a ScrollView with a single item can be used to allow the user to zoom content. Set up the maximumZoomScale and minimumZoomScale props and your user will be able to use pinch and expand gestures to zoom in and out.

The ScrollView works best to present a small amount of things of a limited size. All the elements and views of a ScrollView are rendered, even if they are not currently shown on the screen. If you have a long list of more items than can fit on the screen, you should use a FlatList instead. So let's learn about list views next.

Edit this page
Last updated on
- + diff --git a/docs/0.61/vibration.html b/docs/0.61/vibration.html index d97e8aefb08..5a1f6230d14 100644 --- a/docs/0.61/vibration.html +++ b/docs/0.61/vibration.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
Vibration.cancel();
// Android: vibration stopped
// iOS: vibration stopped

Reference

Methods

vibrate()

Vibration.vibrate(pattern: number, Array<number>, repeat: boolean)

Trigger a vibration with specified pattern.

Parameters:

NameTypeRequiredDescription
patternnumber or Array<number>YesVibration pattern, accept a number or an array of numbers. Default to 400ms.
repeatbooleanNoRepeat vibration pattern until cancel(), default to false.

cancel()

Vibration.cancel();

Stop vibration.

Vibration.cancel()
Edit this page
Last updated on
- + diff --git a/docs/0.61/vibration/index.html b/docs/0.61/vibration/index.html index d97e8aefb08..5a1f6230d14 100644 --- a/docs/0.61/vibration/index.html +++ b/docs/0.61/vibration/index.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
Vibration.cancel();
// Android: vibration stopped
// iOS: vibration stopped

Reference

Methods

vibrate()

Vibration.vibrate(pattern: number, Array<number>, repeat: boolean)

Trigger a vibration with specified pattern.

Parameters:

NameTypeRequiredDescription
patternnumber or Array<number>YesVibration pattern, accept a number or an array of numbers. Default to 400ms.
repeatbooleanNoRepeat vibration pattern until cancel(), default to false.

cancel()

Vibration.cancel();

Stop vibration.

Vibration.cancel()
Edit this page
Last updated on
- + diff --git a/docs/0.61/vibrationios.html b/docs/0.61/vibrationios.html index 4b8643a6f4d..ad41bcc727a 100644 --- a/docs/0.61/vibrationios.html +++ b/docs/0.61/vibrationios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

VibrationIOS

NOTE: VibrationIOS is being deprecated. Use Vibration instead.

The Vibration API is exposed at VibrationIOS.vibrate(). On iOS, calling this function will trigger a one second vibration. The vibration is synchronous so this method will return immediately.

There will be no effect on devices that do not support Vibration, eg. the iOS simulator.

Vibration patterns are currently unsupported.

Methods

Reference

Methods

vibrate()

static vibrate()

@deprecated

Edit this page
Last updated on
- + diff --git a/docs/0.61/vibrationios/index.html b/docs/0.61/vibrationios/index.html index 4b8643a6f4d..ad41bcc727a 100644 --- a/docs/0.61/vibrationios/index.html +++ b/docs/0.61/vibrationios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

VibrationIOS

NOTE: VibrationIOS is being deprecated. Use Vibration instead.

The Vibration API is exposed at VibrationIOS.vibrate(). On iOS, calling this function will trigger a one second vibration. The vibration is synchronous so this method will return immediately.

There will be no effect on devices that do not support Vibration, eg. the iOS simulator.

Vibration patterns are currently unsupported.

Methods

Reference

Methods

vibrate()

static vibrate()

@deprecated

Edit this page
Last updated on
- + diff --git a/docs/0.61/view-style-props.html b/docs/0.61/view-style-props.html index de29c46c247..3544ebece66 100644 --- a/docs/0.61/view-style-props.html +++ b/docs/0.61/view-style-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

View Style Props

Reference

Props

borderRightColor

TypeRequired
colorNo

backfaceVisibility

TypeRequired
enum('visible', 'hidden')No

borderBottomColor

TypeRequired
colorNo

borderBottomEndRadius

TypeRequired
numberNo

borderBottomLeftRadius

TypeRequired
numberNo

borderBottomRightRadius

TypeRequired
numberNo

borderBottomStartRadius

TypeRequired
numberNo

borderBottomWidth

TypeRequired
numberNo

borderColor

TypeRequired
colorNo

borderEndColor

TypeRequired
colorNo

borderLeftColor

TypeRequired
colorNo

borderLeftWidth

TypeRequired
numberNo

borderRadius

If the rounded border is not visible, try applying overflow: 'hidden' as well.

TypeRequired
numberNo

backgroundColor

TypeRequired
colorNo

borderRightWidth

TypeRequired
numberNo

borderStartColor

TypeRequired
colorNo

borderStyle

TypeRequired
enum('solid', 'dotted', 'dashed')No

borderTopColor

TypeRequired
colorNo

borderTopEndRadius

TypeRequired
numberNo

borderTopLeftRadius

TypeRequired
numberNo

borderTopRightRadius

TypeRequired
numberNo

borderTopStartRadius

TypeRequired
numberNo

borderTopWidth

TypeRequired
numberNo

borderWidth

TypeRequired
numberNo

opacity

TypeRequired
numberNo

elevation

(Android-only) Sets the elevation of a view, using Android's underlying elevation API. This adds a drop shadow to the item and affects z-order for overlapping views. Only supported on Android 5.0+, has no effect on earlier versions.

TypeRequiredPlatform
numberNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.61/view-style-props/index.html b/docs/0.61/view-style-props/index.html index de29c46c247..3544ebece66 100644 --- a/docs/0.61/view-style-props/index.html +++ b/docs/0.61/view-style-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

View Style Props

Reference

Props

borderRightColor

TypeRequired
colorNo

backfaceVisibility

TypeRequired
enum('visible', 'hidden')No

borderBottomColor

TypeRequired
colorNo

borderBottomEndRadius

TypeRequired
numberNo

borderBottomLeftRadius

TypeRequired
numberNo

borderBottomRightRadius

TypeRequired
numberNo

borderBottomStartRadius

TypeRequired
numberNo

borderBottomWidth

TypeRequired
numberNo

borderColor

TypeRequired
colorNo

borderEndColor

TypeRequired
colorNo

borderLeftColor

TypeRequired
colorNo

borderLeftWidth

TypeRequired
numberNo

borderRadius

If the rounded border is not visible, try applying overflow: 'hidden' as well.

TypeRequired
numberNo

backgroundColor

TypeRequired
colorNo

borderRightWidth

TypeRequired
numberNo

borderStartColor

TypeRequired
colorNo

borderStyle

TypeRequired
enum('solid', 'dotted', 'dashed')No

borderTopColor

TypeRequired
colorNo

borderTopEndRadius

TypeRequired
numberNo

borderTopLeftRadius

TypeRequired
numberNo

borderTopRightRadius

TypeRequired
numberNo

borderTopStartRadius

TypeRequired
numberNo

borderTopWidth

TypeRequired
numberNo

borderWidth

TypeRequired
numberNo

opacity

TypeRequired
numberNo

elevation

(Android-only) Sets the elevation of a view, using Android's underlying elevation API. This adds a drop shadow to the item and affects z-order for overlapping views. Only supported on Android 5.0+, has no effect on earlier versions.

TypeRequiredPlatform
numberNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.61/view.html b/docs/0.61/view.html index fa7fde52501..fca64f33d35 100644 --- a/docs/0.61/view.html +++ b/docs/0.61/view.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

View

The most fundamental component for building a UI, View is a container that supports layout with flexbox, style, some touch handling, and accessibility controls. View maps directly to the native view equivalent on whatever platform React Native is running on, whether that is a UIView, <div>, android.view, etc.

View is designed to be nested inside other views and can have 0 to many children of any type.

This example creates a View that wraps two colored boxes and a text component in a row with padding.

class ViewColoredBoxesWithText extends Component {
render() {
return (
<View
style={{
flexDirection: 'row',
height: 100,
padding: 20
}}>
<View style={{ backgroundColor: 'blue', flex: 0.3 }} />
<View style={{ backgroundColor: 'red', flex: 0.5 }} />
<Text>Hello World!</Text>
</View>
);
}
}

Views are designed to be used with StyleSheet for clarity and performance, although inline styles are also supported.

Synthetic Touch Events

For View responder props (e.g., onResponderMove), the synthetic touch event passed to them are of the following form:

  • nativeEvent
    • changedTouches - Array of all touch events that have changed since the last event.
    • identifier - The ID of the touch.
    • locationX - The X position of the touch, relative to the element.
    • locationY - The Y position of the touch, relative to the element.
    • pageX - The X position of the touch, relative to the root element.
    • pageY - The Y position of the touch, relative to the root element.
    • target - The node id of the element receiving the touch event.
    • timestamp - A time identifier for the touch, useful for velocity calculation.
    • touches - Array of all current touches on the screen.

Reference

Props

onStartShouldSetResponder

Does this view want to become responder on the start of a touch?

View.props.onStartShouldSetResponder: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

  • 'none' - Used when the element has no role.
  • 'button' - Used when the element should be treated as a button.
  • 'link' - Used when the element should be treated as a link.
  • 'search' - Used when the text field element should also be treated as a search field.
  • 'image' - Used when the element should be treated as an image. Can be combined with button or link, for example.
  • 'keyboardkey' - Used when the element acts as a keyboard key.
  • 'text' - Used when the element should be treated as static text that cannot change.
  • 'adjustable' - Used when an element can be "adjusted" (e.g. a slider).
  • 'imagebutton' - Used when the element should be treated as a button and is also an image.
  • 'header' - Used when an element acts as a header for a content section (e.g. the title of a navigation bar).
  • 'summary' - Used when an element can be used to provide a quick summary of current conditions in the app when the app first launches.
  • 'alert' - Used when an element contains important text to be presented to the user.
  • 'checkbox' - Used when an element represents a checkbox which can be checked, unchecked, or have mixed checked state.
  • 'combobox' - Used when an element represents a combo box, which allows the user to select among several choices.
  • 'menu' - Used when the component is a menu of choices.
  • 'menubar' - Used when a component is a container of multiple menus.
  • 'menuitem' - Used to represent an item within a menu.
  • 'progressbar' - Used to represent a component which indicates progress of a task.
  • 'radio' - Used to represent a radio button.
  • 'radiogroup' - Used to represent a group of radio buttons.
  • 'scrollbar' - Used to represent a scroll bar.
  • 'spinbutton' - Used to represent a button which opens a list of choices.
  • 'switch' - Used to represent a switch which can be turned on and off.
  • 'tab' - Used to represent a tab.
  • 'tablist' - Used to represent a list of tabs.
  • 'timer' - Used to represent a timer.
  • 'toolbar' - Used to represent a tool bar (a container of action buttons or components).
TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

accessibilityValue

Represents the current value of a component. It can be a textual description of a component's value, or for range-based components, such as sliders and progress bars, it contains range information (minimum, current, and maximum).

See the Accessibility guide for more information.

TypeRequired
object: {min: number, max: number, now: number, text: string}No

accessibilityActions

Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The accessibilityActions property should contain a list of action objects. Each action object should contain the field name and label.

See the Accessibility guide for more information.

TypeRequired
arrayNo

onAccessibilityAction

Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform.

See the Accessibility guide for more information.

TypeRequired
functionNo

onAccessibilityTap

When accessible is true, the system will try to invoke this function when the user performs accessibility tap gesture.

TypeRequired
functionNo

onMagicTap

When accessible is true, the system will invoke this function when the user performs the magic tap gesture.

TypeRequiredPlatform
functionNoiOS

onAccessibilityEscape

When accessible is true, the system will invoke this function when the user performs the escape gesture.

TypeRequiredPlatform
functionNoiOS

accessibilityViewIsModal

A value indicating whether VoiceOver should ignore the elements within views that are siblings of the receiver. Default is false.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityElementsHidden

A value indicating whether the accessibility elements contained within this accessibility element are hidden. Default is false.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityIgnoresInvertColors

A value indicating this view should or should not be inverted when color inversion is turned on. A value of true will tell the view to not be inverted even if color inversion is turned on.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityLiveRegion

Indicates to accessibility services whether the user should be notified when this view changes. Works for Android API >= 19 only. Possible values:

  • 'none' - Accessibility services should not announce changes to this view.
  • 'polite'- Accessibility services should announce changes to this view.
  • 'assertive' - Accessibility services should interrupt ongoing speech to immediately announce changes to this view.

See the Android View docs for reference.

TypeRequiredPlatform
enum('none', 'polite', 'assertive')NoAndroid

importantForAccessibility

Controls how view is important for accessibility which is if it fires accessibility events and if it is reported to accessibility services that query the screen. Works for Android only.

Possible values:

  • 'auto' - The system determines whether the view is important for accessibility - default (recommended).
  • 'yes' - The view is important for accessibility.
  • 'no' - The view is not important for accessibility.
  • 'no-hide-descendants' - The view is not important for accessibility, nor are any of its descendant views.

See the Android importantForAccessibility docs for reference.

TypeRequiredPlatform
enum('auto', 'yes', 'no', 'no-hide-descendants')NoAndroid

hitSlop

This defines how far a touch event can start away from the view. Typical interface guidelines recommend touch targets that are at least 30 - 40 points/density-independent pixels.

For example, if a touchable view has a height of 20 the touchable height can be extended to 40 with hitSlop={{top: 10, bottom: 10, left: 0, right: 0}}

The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

nativeID

Used to locate this view from native classes.

This disables the 'layout-only view removal' optimization for this view!

TypeRequired
stringNo

onLayout

Invoked on mount and layout changes with:

{nativeEvent: { layout: {x, y, width, height}}}

This event is fired immediately once the layout has been calculated, but the new layout may not yet be reflected on the screen at the time the event is received, especially if a layout animation is in progress.

TypeRequired
functionNo

onMoveShouldSetResponder

Does this view want to "claim" touch responsiveness? This is called for every touch move on the View when it is not the responder.

View.props.onMoveShouldSetResponder: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onMoveShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a move, it should have this handler which returns true.

View.props.onMoveShouldSetResponderCapture: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderGrant

The View is now responding for touch events. This is the time to highlight and show the user what is happening.

View.props.onResponderGrant: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderMove

The user is moving their finger.

View.props.onResponderMove: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderReject

Another responder is already active and will not release it to that View asking to be the responder.

View.props.onResponderReject: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderRelease

Fired at the end of the touch.

View.props.onResponderRelease: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminate

The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS)

View.props.onResponderTerminate: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminationRequest

Some other View wants to become responder and is asking this View to release its responder. Returning true allows its release.

View.props.onResponderTerminationRequest: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onStartShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a touch start, it should have this handler which returns true.

View.props.onStartShouldSetResponderCapture: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

pointerEvents

Controls whether the View can be the target of touch events.

  • 'auto': The View can be the target of touch events.
  • 'none': The View is never the target of touch events.
  • 'box-none': The View is never the target of touch events but it's subviews can be. It behaves like if the view had the following classes in CSS:
.box-none {
pointer-events: none;
}
.box-none * {
pointer-events: auto;
}
  • 'box-only': The view can be the target of touch events but it's subviews cannot be. It behaves like if the view had the following classes in CSS:
.box-only {
pointer-events: auto;
}
.box-only * {
pointer-events: none;
}

Since pointerEvents does not affect layout/appearance, and we are already deviating from the spec by adding additional modes, we opt to not include pointerEvents on style. On some platforms, we would need to implement it as a className anyways. Using style or not is an implementation detail of the platform.

TypeRequired
enum('box-none', 'none', 'box-only', 'auto')No

removeClippedSubviews

This is a reserved performance property exposed by RCTView and is useful for scrolling content when there are many subviews, most of which are offscreen. For this property to be effective, it must be applied to a view that contains many subviews that extend outside its bound. The subviews must also have overflow: hidden, as should the containing view (or one of its superviews).

TypeRequired
boolNo

style

TypeRequired
view stylesNo

testID

Used to locate this view in end-to-end tests.

This disables the 'layout-only view removal' optimization for this view!

TypeRequired
stringNo

collapsable

Views that are only used to layout their children or otherwise don't draw anything may be automatically removed from the native hierarchy as an optimization. Set this property to false to disable this optimization and ensure that this View exists in the native view hierarchy.

TypeRequiredPlatform
boolNoAndroid

needsOffscreenAlphaCompositing

Whether this View needs to rendered offscreen and composited with an alpha in order to preserve 100% correct colors and blending behavior. The default (false) falls back to drawing the component and its children with an alpha applied to the paint used to draw each element instead of rendering the full component offscreen and compositing it back with an alpha value. This default may be noticeable and undesired in the case where the View you are setting an opacity on has multiple overlapping elements (e.g. multiple overlapping Views, or text and a background).

Rendering offscreen to preserve correct alpha behavior is extremely expensive and hard to debug for non-native developers, which is why it is not turned on by default. If you do need to enable this property for an animation, consider combining it with renderToHardwareTextureAndroid if the view contents are static (i.e. it doesn't need to be redrawn each frame). If that property is enabled, this View will be rendered off-screen once, saved in a hardware texture, and then composited onto the screen with an alpha each frame without having to switch rendering targets on the GPU.

TypeRequired
boolNo

renderToHardwareTextureAndroid

Whether this View should render itself (and all of its children) into a single hardware texture on the GPU.

On Android, this is useful for animations and interactions that only modify opacity, rotation, translation, and/or scale: in those cases, the view doesn't have to be redrawn and display lists don't need to be re-executed. The texture can be re-used and re-composited with different parameters. The downside is that this can use up limited video memory, so this prop should be set back to false at the end of the interaction/animation.

TypeRequiredPlatform
boolNoAndroid

shouldRasterizeIOS

Whether this View should be rendered as a bitmap before compositing.

On iOS, this is useful for animations and interactions that do not modify this component's dimensions nor its children; for example, when translating the position of a static view, rasterization allows the renderer to reuse a cached bitmap of a static view and quickly composite it during each frame.

Rasterization incurs an off-screen drawing pass and the bitmap consumes memory. Test and measure when using this property.

TypeRequiredPlatform
boolNoiOS

nextFocusDown

Designates the next view to receive focus when the user navigates down. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusForward

Designates the next view to receive focus when the user navigates forward. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusLeft

Designates the next view to receive focus when the user navigates left. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusRight

Designates the next view to receive focus when the user navigates right. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusUp

Designates the next view to receive focus when the user navigates up. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

clickable

Determines whether this View is clickable or tappable for accessibility hints.

TypeRequiredPlatform
booleanNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.61/view/index.html b/docs/0.61/view/index.html index fa7fde52501..fca64f33d35 100644 --- a/docs/0.61/view/index.html +++ b/docs/0.61/view/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

View

The most fundamental component for building a UI, View is a container that supports layout with flexbox, style, some touch handling, and accessibility controls. View maps directly to the native view equivalent on whatever platform React Native is running on, whether that is a UIView, <div>, android.view, etc.

View is designed to be nested inside other views and can have 0 to many children of any type.

This example creates a View that wraps two colored boxes and a text component in a row with padding.

class ViewColoredBoxesWithText extends Component {
render() {
return (
<View
style={{
flexDirection: 'row',
height: 100,
padding: 20
}}>
<View style={{ backgroundColor: 'blue', flex: 0.3 }} />
<View style={{ backgroundColor: 'red', flex: 0.5 }} />
<Text>Hello World!</Text>
</View>
);
}
}

Views are designed to be used with StyleSheet for clarity and performance, although inline styles are also supported.

Synthetic Touch Events

For View responder props (e.g., onResponderMove), the synthetic touch event passed to them are of the following form:

  • nativeEvent
    • changedTouches - Array of all touch events that have changed since the last event.
    • identifier - The ID of the touch.
    • locationX - The X position of the touch, relative to the element.
    • locationY - The Y position of the touch, relative to the element.
    • pageX - The X position of the touch, relative to the root element.
    • pageY - The Y position of the touch, relative to the root element.
    • target - The node id of the element receiving the touch event.
    • timestamp - A time identifier for the touch, useful for velocity calculation.
    • touches - Array of all current touches on the screen.

Reference

Props

onStartShouldSetResponder

Does this view want to become responder on the start of a touch?

View.props.onStartShouldSetResponder: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

  • 'none' - Used when the element has no role.
  • 'button' - Used when the element should be treated as a button.
  • 'link' - Used when the element should be treated as a link.
  • 'search' - Used when the text field element should also be treated as a search field.
  • 'image' - Used when the element should be treated as an image. Can be combined with button or link, for example.
  • 'keyboardkey' - Used when the element acts as a keyboard key.
  • 'text' - Used when the element should be treated as static text that cannot change.
  • 'adjustable' - Used when an element can be "adjusted" (e.g. a slider).
  • 'imagebutton' - Used when the element should be treated as a button and is also an image.
  • 'header' - Used when an element acts as a header for a content section (e.g. the title of a navigation bar).
  • 'summary' - Used when an element can be used to provide a quick summary of current conditions in the app when the app first launches.
  • 'alert' - Used when an element contains important text to be presented to the user.
  • 'checkbox' - Used when an element represents a checkbox which can be checked, unchecked, or have mixed checked state.
  • 'combobox' - Used when an element represents a combo box, which allows the user to select among several choices.
  • 'menu' - Used when the component is a menu of choices.
  • 'menubar' - Used when a component is a container of multiple menus.
  • 'menuitem' - Used to represent an item within a menu.
  • 'progressbar' - Used to represent a component which indicates progress of a task.
  • 'radio' - Used to represent a radio button.
  • 'radiogroup' - Used to represent a group of radio buttons.
  • 'scrollbar' - Used to represent a scroll bar.
  • 'spinbutton' - Used to represent a button which opens a list of choices.
  • 'switch' - Used to represent a switch which can be turned on and off.
  • 'tab' - Used to represent a tab.
  • 'tablist' - Used to represent a list of tabs.
  • 'timer' - Used to represent a timer.
  • 'toolbar' - Used to represent a tool bar (a container of action buttons or components).
TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

accessibilityValue

Represents the current value of a component. It can be a textual description of a component's value, or for range-based components, such as sliders and progress bars, it contains range information (minimum, current, and maximum).

See the Accessibility guide for more information.

TypeRequired
object: {min: number, max: number, now: number, text: string}No

accessibilityActions

Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The accessibilityActions property should contain a list of action objects. Each action object should contain the field name and label.

See the Accessibility guide for more information.

TypeRequired
arrayNo

onAccessibilityAction

Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform.

See the Accessibility guide for more information.

TypeRequired
functionNo

onAccessibilityTap

When accessible is true, the system will try to invoke this function when the user performs accessibility tap gesture.

TypeRequired
functionNo

onMagicTap

When accessible is true, the system will invoke this function when the user performs the magic tap gesture.

TypeRequiredPlatform
functionNoiOS

onAccessibilityEscape

When accessible is true, the system will invoke this function when the user performs the escape gesture.

TypeRequiredPlatform
functionNoiOS

accessibilityViewIsModal

A value indicating whether VoiceOver should ignore the elements within views that are siblings of the receiver. Default is false.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityElementsHidden

A value indicating whether the accessibility elements contained within this accessibility element are hidden. Default is false.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityIgnoresInvertColors

A value indicating this view should or should not be inverted when color inversion is turned on. A value of true will tell the view to not be inverted even if color inversion is turned on.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityLiveRegion

Indicates to accessibility services whether the user should be notified when this view changes. Works for Android API >= 19 only. Possible values:

  • 'none' - Accessibility services should not announce changes to this view.
  • 'polite'- Accessibility services should announce changes to this view.
  • 'assertive' - Accessibility services should interrupt ongoing speech to immediately announce changes to this view.

See the Android View docs for reference.

TypeRequiredPlatform
enum('none', 'polite', 'assertive')NoAndroid

importantForAccessibility

Controls how view is important for accessibility which is if it fires accessibility events and if it is reported to accessibility services that query the screen. Works for Android only.

Possible values:

  • 'auto' - The system determines whether the view is important for accessibility - default (recommended).
  • 'yes' - The view is important for accessibility.
  • 'no' - The view is not important for accessibility.
  • 'no-hide-descendants' - The view is not important for accessibility, nor are any of its descendant views.

See the Android importantForAccessibility docs for reference.

TypeRequiredPlatform
enum('auto', 'yes', 'no', 'no-hide-descendants')NoAndroid

hitSlop

This defines how far a touch event can start away from the view. Typical interface guidelines recommend touch targets that are at least 30 - 40 points/density-independent pixels.

For example, if a touchable view has a height of 20 the touchable height can be extended to 40 with hitSlop={{top: 10, bottom: 10, left: 0, right: 0}}

The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

nativeID

Used to locate this view from native classes.

This disables the 'layout-only view removal' optimization for this view!

TypeRequired
stringNo

onLayout

Invoked on mount and layout changes with:

{nativeEvent: { layout: {x, y, width, height}}}

This event is fired immediately once the layout has been calculated, but the new layout may not yet be reflected on the screen at the time the event is received, especially if a layout animation is in progress.

TypeRequired
functionNo

onMoveShouldSetResponder

Does this view want to "claim" touch responsiveness? This is called for every touch move on the View when it is not the responder.

View.props.onMoveShouldSetResponder: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onMoveShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a move, it should have this handler which returns true.

View.props.onMoveShouldSetResponderCapture: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderGrant

The View is now responding for touch events. This is the time to highlight and show the user what is happening.

View.props.onResponderGrant: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderMove

The user is moving their finger.

View.props.onResponderMove: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderReject

Another responder is already active and will not release it to that View asking to be the responder.

View.props.onResponderReject: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderRelease

Fired at the end of the touch.

View.props.onResponderRelease: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminate

The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS)

View.props.onResponderTerminate: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminationRequest

Some other View wants to become responder and is asking this View to release its responder. Returning true allows its release.

View.props.onResponderTerminationRequest: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onStartShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a touch start, it should have this handler which returns true.

View.props.onStartShouldSetResponderCapture: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

pointerEvents

Controls whether the View can be the target of touch events.

  • 'auto': The View can be the target of touch events.
  • 'none': The View is never the target of touch events.
  • 'box-none': The View is never the target of touch events but it's subviews can be. It behaves like if the view had the following classes in CSS:
.box-none {
pointer-events: none;
}
.box-none * {
pointer-events: auto;
}
  • 'box-only': The view can be the target of touch events but it's subviews cannot be. It behaves like if the view had the following classes in CSS:
.box-only {
pointer-events: auto;
}
.box-only * {
pointer-events: none;
}

Since pointerEvents does not affect layout/appearance, and we are already deviating from the spec by adding additional modes, we opt to not include pointerEvents on style. On some platforms, we would need to implement it as a className anyways. Using style or not is an implementation detail of the platform.

TypeRequired
enum('box-none', 'none', 'box-only', 'auto')No

removeClippedSubviews

This is a reserved performance property exposed by RCTView and is useful for scrolling content when there are many subviews, most of which are offscreen. For this property to be effective, it must be applied to a view that contains many subviews that extend outside its bound. The subviews must also have overflow: hidden, as should the containing view (or one of its superviews).

TypeRequired
boolNo

style

TypeRequired
view stylesNo

testID

Used to locate this view in end-to-end tests.

This disables the 'layout-only view removal' optimization for this view!

TypeRequired
stringNo

collapsable

Views that are only used to layout their children or otherwise don't draw anything may be automatically removed from the native hierarchy as an optimization. Set this property to false to disable this optimization and ensure that this View exists in the native view hierarchy.

TypeRequiredPlatform
boolNoAndroid

needsOffscreenAlphaCompositing

Whether this View needs to rendered offscreen and composited with an alpha in order to preserve 100% correct colors and blending behavior. The default (false) falls back to drawing the component and its children with an alpha applied to the paint used to draw each element instead of rendering the full component offscreen and compositing it back with an alpha value. This default may be noticeable and undesired in the case where the View you are setting an opacity on has multiple overlapping elements (e.g. multiple overlapping Views, or text and a background).

Rendering offscreen to preserve correct alpha behavior is extremely expensive and hard to debug for non-native developers, which is why it is not turned on by default. If you do need to enable this property for an animation, consider combining it with renderToHardwareTextureAndroid if the view contents are static (i.e. it doesn't need to be redrawn each frame). If that property is enabled, this View will be rendered off-screen once, saved in a hardware texture, and then composited onto the screen with an alpha each frame without having to switch rendering targets on the GPU.

TypeRequired
boolNo

renderToHardwareTextureAndroid

Whether this View should render itself (and all of its children) into a single hardware texture on the GPU.

On Android, this is useful for animations and interactions that only modify opacity, rotation, translation, and/or scale: in those cases, the view doesn't have to be redrawn and display lists don't need to be re-executed. The texture can be re-used and re-composited with different parameters. The downside is that this can use up limited video memory, so this prop should be set back to false at the end of the interaction/animation.

TypeRequiredPlatform
boolNoAndroid

shouldRasterizeIOS

Whether this View should be rendered as a bitmap before compositing.

On iOS, this is useful for animations and interactions that do not modify this component's dimensions nor its children; for example, when translating the position of a static view, rasterization allows the renderer to reuse a cached bitmap of a static view and quickly composite it during each frame.

Rasterization incurs an off-screen drawing pass and the bitmap consumes memory. Test and measure when using this property.

TypeRequiredPlatform
boolNoiOS

nextFocusDown

Designates the next view to receive focus when the user navigates down. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusForward

Designates the next view to receive focus when the user navigates forward. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusLeft

Designates the next view to receive focus when the user navigates left. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusRight

Designates the next view to receive focus when the user navigates right. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusUp

Designates the next view to receive focus when the user navigates up. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

clickable

Determines whether this View is clickable or tappable for accessibility hints.

TypeRequiredPlatform
booleanNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.61/viewpagerandroid.html b/docs/0.61/viewpagerandroid.html index 3d134cf36a0..b32ea1d785f 100644 --- a/docs/0.61/viewpagerandroid.html +++ b/docs/0.61/viewpagerandroid.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
const styles = {
...
viewPager: {
flex: 1
},
pageStyle: {
alignItems: 'center',
padding: 20,
}
}

Reference

Props

Inherits View Props.

initialPage

Index of initial page that should be selected. Use setPage method to update the page, and onPageSelected to monitor page changes

TypeRequired
numberNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

TypeRequired
enum('none', 'on-drag')No

onPageScroll

Executed when transitioning between pages (either because of animation for the requested page change or when user is swiping/dragging between pages) The event.nativeEvent object for this callback will carry following data:

TypeRequired
functionNo

onPageScrollStateChanged

Function called when the page scrolling state has changed. The page scrolling state can be in 3 states:

TypeRequired
functionNo

onPageSelected

This callback will be called once ViewPager finish navigating to selected page (when user swipes between pages). The event.nativeEvent object passed to this callback will have following fields:

TypeRequired
functionNo

pageMargin

Blank space to show between pages. This is only visible while scrolling, pages are still edge-to-edge.

TypeRequired
numberNo

peekEnabled

Whether enable showing peekFraction or not. If this is true, the preview of last and next page will show in current screen. Defaults to false.

TypeRequired
boolNo

scrollEnabled

When false, the content does not scroll. The default value is true.

TypeRequired
boolNo

setPage

A helper function to scroll to a specific page in the ViewPager. The transition between pages will be animated.

TypeRequired
NumberYes

setPageWithoutAnimation

A helper function to scroll to a specific page in the ViewPager. The transition between pages will not be animated.

TypeRequired
NumberYes

Type Definitions

ViewPagerScrollState

Type
\$Enum

Constants:

ValueDescription
idle
dragging
settling
Edit this page
Last updated on
- + diff --git a/docs/0.61/viewpagerandroid/index.html b/docs/0.61/viewpagerandroid/index.html index 3d134cf36a0..b32ea1d785f 100644 --- a/docs/0.61/viewpagerandroid/index.html +++ b/docs/0.61/viewpagerandroid/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
const styles = {
...
viewPager: {
flex: 1
},
pageStyle: {
alignItems: 'center',
padding: 20,
}
}

Reference

Props

Inherits View Props.

initialPage

Index of initial page that should be selected. Use setPage method to update the page, and onPageSelected to monitor page changes

TypeRequired
numberNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

TypeRequired
enum('none', 'on-drag')No

onPageScroll

Executed when transitioning between pages (either because of animation for the requested page change or when user is swiping/dragging between pages) The event.nativeEvent object for this callback will carry following data:

TypeRequired
functionNo

onPageScrollStateChanged

Function called when the page scrolling state has changed. The page scrolling state can be in 3 states:

TypeRequired
functionNo

onPageSelected

This callback will be called once ViewPager finish navigating to selected page (when user swipes between pages). The event.nativeEvent object passed to this callback will have following fields:

TypeRequired
functionNo

pageMargin

Blank space to show between pages. This is only visible while scrolling, pages are still edge-to-edge.

TypeRequired
numberNo

peekEnabled

Whether enable showing peekFraction or not. If this is true, the preview of last and next page will show in current screen. Defaults to false.

TypeRequired
boolNo

scrollEnabled

When false, the content does not scroll. The default value is true.

TypeRequired
boolNo

setPage

A helper function to scroll to a specific page in the ViewPager. The transition between pages will be animated.

TypeRequired
NumberYes

setPageWithoutAnimation

A helper function to scroll to a specific page in the ViewPager. The transition between pages will not be animated.

TypeRequired
NumberYes

Type Definitions

ViewPagerScrollState

Type
\$Enum

Constants:

ValueDescription
idle
dragging
settling
Edit this page
Last updated on
- + diff --git a/docs/0.61/virtualizedlist.html b/docs/0.61/virtualizedlist.html index f8b177185de..ebb87f894d7 100644 --- a/docs/0.61/virtualizedlist.html +++ b/docs/0.61/virtualizedlist.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

VirtualizedList

Base implementation for the more convenient <FlatList> and <SectionList> components, which are also better documented. In general, this should only really be used if you need more flexibility than FlatList provides, e.g. for use with immutable data instead of plain arrays.

Virtualization massively improves memory consumption and performance of large lists by maintaining a finite render window of active items and replacing all items outside of the render window with appropriately sized blank space. The window adapts to scrolling behavior, and items are rendered incrementally with low-pri (after any running interactions) if they are far from the visible area, or with hi-pri otherwise to minimize the potential of seeing blank space.

Some caveats:

  • Internal state is not preserved when content scrolls out of the render window. Make sure all your data is captured in the item data or external stores like Flux, Redux, or Relay.
  • This is a PureComponent which means that it will not re-render if props remain shallow-equal. Make sure that everything your renderItem function depends on is passed as a prop (e.g. extraData) that is not === after updates, otherwise your UI may not update on changes. This includes the data prop and parent component state.
  • In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate and momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application, and we are working on improving it behind the scenes.
  • By default, the list looks for a key prop on each item and uses that for the React key. Alternatively, you can provide a custom keyExtractor prop.

Reference

Props

Inherits ScrollView Props.

renderItem

(info: any) => ?React.Element<any>

Takes an item from data and renders it into the list

TypeRequired
functionYes

data

The default accessor functions assume this is an array of objects with shape {key: string} but you can override getItem, getItemCount, and keyExtractor to handle any type of index-based data.

TypeRequired
anyYes

getItem

(data: any, index: number) => object;

A generic accessor for extracting an item from any sort of data blob.

TypeRequired
functionYes

getItemCount

(data: any) => number;

Determines how many items are in the data blob.

TypeRequired
functionYes

debug

debug will turn on extra logging and visual overlays to aid with debugging both usage and implementation, but with a significant perf hit.

TypeRequired
booleanNo

extraData

A marker property for telling the list to re-render (since it implements PureComponent). If any of your renderItem, Header, Footer, etc. functions depend on anything outside of the data prop, stick it here and treat it immutably.

TypeRequired
anyNo

getItemLayout

(
data: any,
index: number,
) => {length: number, offset: number, index: number}
TypeRequired
functionNo

initialScrollIndex

Instead of starting at the top with the first item, start at initialScrollIndex. This disables the "scroll to top" optimization that keeps the first initialNumToRender items always rendered and immediately renders the items starting at this initial index. Requires getItemLayout to be implemented.

TypeRequired
numberNo

inverted

Reverses the direction of scroll. Uses scale transforms of -1.

TypeRequired
booleanNo

CellRendererComponent

Each cell is rendered using this element. Can be a React Component Class,or a render function. Defaults to using View.

TypeRequired
component, functionNo

listKey

A unique identifier for this list. If there are multiple VirtualizedLists at the same level of nesting within another VirtualizedList, this key is necessary for virtualization to work properly.

TypeRequired
stringTrue

ListEmptyComponent

Rendered when the list is empty. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
component, elementNo

ListItemComponent

Each data item is rendered using this element. Can be a React Component Class, or a render function

TypeRequired
component, functionNo

ListFooterComponent

Rendered at the bottom of all the items. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
component, elementNo

ListFooterComponentStyle

Styling for internal View for ListFooterComponent

TypeRequired
ViewStylePropNo

ListHeaderComponent

Rendered at the top of all the items. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
component, elementNo

ListHeaderComponentStyle

Styling for internal View for ListHeaderComponent

TypeRequired
ViewStylePropNo

onLayout

TypeRequired
functionNo

onRefresh

() => void

If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the refreshing prop correctly.

TypeRequired
functionNo

onScrollToIndexFailed

(info: {
index: number,
highestMeasuredFrameIndex: number,
averageItemLength: number,
}) => void

Used to handle failures when scrolling to an index that has not been measured yet. Recommended action is to either compute your own offset and scrollTo it, or scroll as far as possible and then try again after more items have been rendered.

TypeRequired
functionNo

onViewableItemsChanged

(info: {
viewableItems: array,
changed: array,
}) => void

Called when the viewability of rows changes, as defined by the viewabilityConfig prop.

TypeRequired
functionNo

refreshing

Set this true while waiting for new data from a refresh.

TypeRequired
booleanNo

refreshControl

A custom refresh control element. When set, it overrides the default <RefreshControl> component built internally. The onRefresh and refreshing props are also ignored. Only works for vertical VirtualizedList.

TypeRequired
elementNo

removeClippedSubviews

This may improve scroll performance for large lists.

Note: May have bugs (missing content) in some circumstances - use at your own risk.

TypeRequired
booleanNo

renderScrollComponent

(props: object) => element;

Render a custom scroll component, e.g. with a differently styled RefreshControl.

TypeRequired
functionNo

viewabilityConfig

See ViewabilityHelper.js for flow type and further documentation.

TypeRequired
ViewabilityConfigNo

viewabilityConfigCallbackPairs

List of ViewabilityConfig/onViewableItemsChanged pairs. A specific onViewableItemsChanged will be called when its corresponding ViewabilityConfig's conditions are met. See ViewabilityHelper.js for flow type and further documentation.

TypeRequired
array of ViewabilityConfigCallbackPairNo

horizontal

TypeRequired
booleanNo

initialNumToRender

How many items to render in the initial batch. This should be enough to fill the screen but not much more. Note these items will never be unmounted as part of the windowed rendering in order to improve perceived performance of scroll-to-top actions.

TypeRequired
numberNo

keyExtractor

(item: object, index: number) => string;

Used to extract a unique key for a given item at the specified index. Key is used for caching and as the react key to track item re-ordering. The default extractor checks item.key, then item.id, and then falls back to using the index, like React does.

TypeRequired
functionNo

maxToRenderPerBatch

The maximum number of items to render in each incremental render batch. The more rendered at once, the better the fill rate, but responsiveness may suffer because rendering content may interfere with responding to button taps or other interactions.

TypeRequired
numberNo

onEndReached

(info: {distanceFromEnd: number}) => void

Called once when the scroll position gets within onEndReachedThreshold of the rendered content.

TypeRequired
functionNo

onEndReachedThreshold

How far from the end (in units of visible length of the list) the bottom edge of the list must be from the end of the content to trigger the onEndReached callback. Thus a value of 0.5 will trigger onEndReached when the end of the content is within half the visible length of the list.

TypeRequired
numberNo

updateCellsBatchingPeriod

Amount of time between low-pri item render batches, e.g. for rendering items quite a ways off screen. Similar fill rate/responsiveness tradeoff as maxToRenderPerBatch.

TypeRequired
numberNo

windowSize

Determines the maximum number of items rendered outside of the visible area, in units of visible lengths. So if your list fills the screen, then windowSize={21} (the default) will render the visible screen area plus up to 10 screens above and 10 below the viewport. Reducing this number will reduce memory consumption and may improve performance, but will increase the chance that fast scrolling may reveal momentary blank areas of unrendered content.

TypeRequired
numberNo

disableVirtualization

Deprecated. Virtualization provides significant performance and memory optimizations, but fully unmounts react instances that are outside of the render window. You should only need to disable this for debugging purposes.

TypeRequired
No

persistentScrollbar

TypeRequired
boolNo

progressViewOffset

Set this when offset is needed for the loading indicator to show correctly.

TypeRequiredPlatform
numberNoAndroid

Methods

scrollToEnd()

scrollToEnd(([params]: object));

scrollToIndex()

scrollToIndex((params: object));

scrollToItem()

scrollToItem((params: object));

scrollToOffset()

scrollToOffset((params: object));

Scroll to a specific content pixel offset in the list.

Param offset expects the offset to scroll to. In case of horizontal is true, the offset is the x-value, in any other case the offset is the y-value.

Param animated (true by default) defines whether the list should do an animation while scrolling.

recordInteraction()

recordInteraction();

flashScrollIndicators()

flashScrollIndicators();
Edit this page
Last updated on
- + diff --git a/docs/0.61/virtualizedlist/index.html b/docs/0.61/virtualizedlist/index.html index f8b177185de..ebb87f894d7 100644 --- a/docs/0.61/virtualizedlist/index.html +++ b/docs/0.61/virtualizedlist/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.61

VirtualizedList

Base implementation for the more convenient <FlatList> and <SectionList> components, which are also better documented. In general, this should only really be used if you need more flexibility than FlatList provides, e.g. for use with immutable data instead of plain arrays.

Virtualization massively improves memory consumption and performance of large lists by maintaining a finite render window of active items and replacing all items outside of the render window with appropriately sized blank space. The window adapts to scrolling behavior, and items are rendered incrementally with low-pri (after any running interactions) if they are far from the visible area, or with hi-pri otherwise to minimize the potential of seeing blank space.

Some caveats:

  • Internal state is not preserved when content scrolls out of the render window. Make sure all your data is captured in the item data or external stores like Flux, Redux, or Relay.
  • This is a PureComponent which means that it will not re-render if props remain shallow-equal. Make sure that everything your renderItem function depends on is passed as a prop (e.g. extraData) that is not === after updates, otherwise your UI may not update on changes. This includes the data prop and parent component state.
  • In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate and momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application, and we are working on improving it behind the scenes.
  • By default, the list looks for a key prop on each item and uses that for the React key. Alternatively, you can provide a custom keyExtractor prop.

Reference

Props

Inherits ScrollView Props.

renderItem

(info: any) => ?React.Element<any>

Takes an item from data and renders it into the list

TypeRequired
functionYes

data

The default accessor functions assume this is an array of objects with shape {key: string} but you can override getItem, getItemCount, and keyExtractor to handle any type of index-based data.

TypeRequired
anyYes

getItem

(data: any, index: number) => object;

A generic accessor for extracting an item from any sort of data blob.

TypeRequired
functionYes

getItemCount

(data: any) => number;

Determines how many items are in the data blob.

TypeRequired
functionYes

debug

debug will turn on extra logging and visual overlays to aid with debugging both usage and implementation, but with a significant perf hit.

TypeRequired
booleanNo

extraData

A marker property for telling the list to re-render (since it implements PureComponent). If any of your renderItem, Header, Footer, etc. functions depend on anything outside of the data prop, stick it here and treat it immutably.

TypeRequired
anyNo

getItemLayout

(
data: any,
index: number,
) => {length: number, offset: number, index: number}
TypeRequired
functionNo

initialScrollIndex

Instead of starting at the top with the first item, start at initialScrollIndex. This disables the "scroll to top" optimization that keeps the first initialNumToRender items always rendered and immediately renders the items starting at this initial index. Requires getItemLayout to be implemented.

TypeRequired
numberNo

inverted

Reverses the direction of scroll. Uses scale transforms of -1.

TypeRequired
booleanNo

CellRendererComponent

Each cell is rendered using this element. Can be a React Component Class,or a render function. Defaults to using View.

TypeRequired
component, functionNo

listKey

A unique identifier for this list. If there are multiple VirtualizedLists at the same level of nesting within another VirtualizedList, this key is necessary for virtualization to work properly.

TypeRequired
stringTrue

ListEmptyComponent

Rendered when the list is empty. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
component, elementNo

ListItemComponent

Each data item is rendered using this element. Can be a React Component Class, or a render function

TypeRequired
component, functionNo

ListFooterComponent

Rendered at the bottom of all the items. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
component, elementNo

ListFooterComponentStyle

Styling for internal View for ListFooterComponent

TypeRequired
ViewStylePropNo

ListHeaderComponent

Rendered at the top of all the items. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
component, elementNo

ListHeaderComponentStyle

Styling for internal View for ListHeaderComponent

TypeRequired
ViewStylePropNo

onLayout

TypeRequired
functionNo

onRefresh

() => void

If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the refreshing prop correctly.

TypeRequired
functionNo

onScrollToIndexFailed

(info: {
index: number,
highestMeasuredFrameIndex: number,
averageItemLength: number,
}) => void

Used to handle failures when scrolling to an index that has not been measured yet. Recommended action is to either compute your own offset and scrollTo it, or scroll as far as possible and then try again after more items have been rendered.

TypeRequired
functionNo

onViewableItemsChanged

(info: {
viewableItems: array,
changed: array,
}) => void

Called when the viewability of rows changes, as defined by the viewabilityConfig prop.

TypeRequired
functionNo

refreshing

Set this true while waiting for new data from a refresh.

TypeRequired
booleanNo

refreshControl

A custom refresh control element. When set, it overrides the default <RefreshControl> component built internally. The onRefresh and refreshing props are also ignored. Only works for vertical VirtualizedList.

TypeRequired
elementNo

removeClippedSubviews

This may improve scroll performance for large lists.

Note: May have bugs (missing content) in some circumstances - use at your own risk.

TypeRequired
booleanNo

renderScrollComponent

(props: object) => element;

Render a custom scroll component, e.g. with a differently styled RefreshControl.

TypeRequired
functionNo

viewabilityConfig

See ViewabilityHelper.js for flow type and further documentation.

TypeRequired
ViewabilityConfigNo

viewabilityConfigCallbackPairs

List of ViewabilityConfig/onViewableItemsChanged pairs. A specific onViewableItemsChanged will be called when its corresponding ViewabilityConfig's conditions are met. See ViewabilityHelper.js for flow type and further documentation.

TypeRequired
array of ViewabilityConfigCallbackPairNo

horizontal

TypeRequired
booleanNo

initialNumToRender

How many items to render in the initial batch. This should be enough to fill the screen but not much more. Note these items will never be unmounted as part of the windowed rendering in order to improve perceived performance of scroll-to-top actions.

TypeRequired
numberNo

keyExtractor

(item: object, index: number) => string;

Used to extract a unique key for a given item at the specified index. Key is used for caching and as the react key to track item re-ordering. The default extractor checks item.key, then item.id, and then falls back to using the index, like React does.

TypeRequired
functionNo

maxToRenderPerBatch

The maximum number of items to render in each incremental render batch. The more rendered at once, the better the fill rate, but responsiveness may suffer because rendering content may interfere with responding to button taps or other interactions.

TypeRequired
numberNo

onEndReached

(info: {distanceFromEnd: number}) => void

Called once when the scroll position gets within onEndReachedThreshold of the rendered content.

TypeRequired
functionNo

onEndReachedThreshold

How far from the end (in units of visible length of the list) the bottom edge of the list must be from the end of the content to trigger the onEndReached callback. Thus a value of 0.5 will trigger onEndReached when the end of the content is within half the visible length of the list.

TypeRequired
numberNo

updateCellsBatchingPeriod

Amount of time between low-pri item render batches, e.g. for rendering items quite a ways off screen. Similar fill rate/responsiveness tradeoff as maxToRenderPerBatch.

TypeRequired
numberNo

windowSize

Determines the maximum number of items rendered outside of the visible area, in units of visible lengths. So if your list fills the screen, then windowSize={21} (the default) will render the visible screen area plus up to 10 screens above and 10 below the viewport. Reducing this number will reduce memory consumption and may improve performance, but will increase the chance that fast scrolling may reveal momentary blank areas of unrendered content.

TypeRequired
numberNo

disableVirtualization

Deprecated. Virtualization provides significant performance and memory optimizations, but fully unmounts react instances that are outside of the render window. You should only need to disable this for debugging purposes.

TypeRequired
No

persistentScrollbar

TypeRequired
boolNo

progressViewOffset

Set this when offset is needed for the loading indicator to show correctly.

TypeRequiredPlatform
numberNoAndroid

Methods

scrollToEnd()

scrollToEnd(([params]: object));

scrollToIndex()

scrollToIndex((params: object));

scrollToItem()

scrollToItem((params: object));

scrollToOffset()

scrollToOffset((params: object));

Scroll to a specific content pixel offset in the list.

Param offset expects the offset to scroll to. In case of horizontal is true, the offset is the x-value, in any other case the offset is the y-value.

Param animated (true by default) defines whether the list should do an animation while scrolling.

recordInteraction()

recordInteraction();

flashScrollIndicators()

flashScrollIndicators();
Edit this page
Last updated on
- + diff --git a/docs/0.61/webview.html b/docs/0.61/webview.html index b27895ff8a2..561d060cdbd 100644 --- a/docs/0.61/webview.html +++ b/docs/0.61/webview.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
class MyInlineWeb extends Component {
render() {
return (
<WebView
originWhitelist={['*']}
source={{ html: '<h1>Hello world</h1>' }}
/>
);
}
}

You can use this component to navigate back and forth in the web view's history and configure various properties for the web content.

On iOS, the useWebKit prop can be used to opt into a WKWebView-backed implementation.

Security Warning: Currently, onMessage and postMessage do not allow specifying an origin. This can lead to cross-site scripting attacks if an unexpected document is loaded within a WebView instance. Please refer to the MDN documentation for Window.postMessage() for more details on the security implications of this.

Reference

Props

Inherits View Props.

source

Loads static HTML or a URI (with optional headers) in the WebView. Note that static HTML will require setting originWhitelist to ["*"].

The object passed to source can have either of the following shapes:

Load uri

Static HTML

TypeRequired
objectNo

automaticallyAdjustContentInsets

Controls whether to adjust the content inset for web views that are placed behind a navigation bar, tab bar, or toolbar. The default value is true.

TypeRequired
boolNo

injectJavaScript

Function that accepts a string that will be passed to the WebView and executed immediately as JavaScript.

TypeRequired
functionNo

injectedJavaScript

Set this to provide JavaScript that will be injected into the web page when the view loads.

TypeRequired
stringNo

mediaPlaybackRequiresUserAction

Boolean that determines whether HTML5 audio and video requires the user to tap them before they start playing. The default value is true.

TypeRequired
boolNo

nativeConfig

Override the native component used to render the WebView. Enables a custom native WebView which uses the same JavaScript as the original WebView.

The nativeConfig prop expects an object with the following keys:

TypeRequired
objectNo

onError

Function that is invoked when the WebView load fails.

TypeRequired
functionNo

onLoad

Function that is invoked when the WebView has finished loading.

TypeRequired
functionNo

onLoadEnd

Function that is invoked when the WebView load succeeds or fails.

TypeRequired
functionNo

onLoadStart

Function that is invoked when the WebView starts loading.

TypeRequired
functionNo

onMessage

A function that is invoked when the webview calls window.postMessage. Setting this property will inject a postMessage global into your webview, but will still call pre-existing values of postMessage.

window.postMessage accepts one argument, data, which will be available on the event object, event.nativeEvent.data. data must be a string.

TypeRequired
functionNo

onNavigationStateChange

Function that is invoked when the WebView loading starts or ends.

TypeRequired
functionNo

originWhitelist

List of origin strings to allow being navigated to. The strings allow wildcards and get matched against only the origin (not the full URL). If the user taps to navigate to a new page but the new page is not in this safelist, the URL will be handled by the OS. The default safelistlisted origins are "http://*" and "https://*".

TypeRequired
array of stringsNo

renderError

Function that returns a view to show if there's an error.

TypeRequired
functionNo

renderLoading

Function that returns a loading indicator. The startInLoadingState prop must be set to true in order to use this prop.

TypeRequired
functionNo

scalesPageToFit

Boolean that controls whether the web content is scaled to fit the view and enables the user to change the scale. The default value is true.

On iOS, when useWebKit=true, this prop will not work.

TypeRequired
boolNo

onShouldStartLoadWithRequest

Function that allows custom handling of any web view requests. Return true from the function to continue loading the request and false to stop loading.

TypeRequiredPlatform
functionNoiOS

startInLoadingState

Boolean value that forces the WebView to show the loading view on the first load. This prop must be set to true in order for the renderLoading prop to work.

TypeRequired
boolNo

decelerationRate

A floating-point number that determines how quickly the scroll view decelerates after the user lifts their finger. You may also use the string shortcuts "normal" and "fast" which match the underlying iOS settings for UIScrollViewDecelerationRateNormal and UIScrollViewDecelerationRateFast respectively:

TypeRequiredPlatform
numberNoiOS

domStorageEnabled

Boolean value to control whether DOM Storage is enabled. Used only in Android.

TypeRequiredPlatform
boolNoAndroid

javaScriptEnabled

Boolean value to enable JavaScript in the WebView. Used on Android only as JavaScript is enabled by default on iOS. The default value is true.

TypeRequiredPlatform
boolNoAndroid

mixedContentMode

Specifies the mixed content mode. i.e WebView will allow a secure origin to load content from any other origin.

Possible values for mixedContentMode are:

TypeRequiredPlatform
stringNoAndroid

thirdPartyCookiesEnabled

Boolean value to enable third party cookies in the WebView. Used on Android Lollipop and above only as third party cookies are enabled by default on Android Kitkat and below and on iOS. The default value is true.

TypeRequiredPlatform
boolNoAndroid

userAgent

Sets the user-agent for the WebView.

TypeRequiredPlatform
stringNoAndroid

allowsInlineMediaPlayback

Boolean that determines whether HTML5 videos play inline or use the native full-screen controller. The default value is false.

NOTE

In order for video to play inline, not only does this property need to be set to true, but the video element in the HTML document must also include the webkit-playsinline attribute.

TypeRequiredPlatform
boolNoiOS

bounces

Boolean value that determines whether the web view bounces when it reaches the edge of the content. The default value is true.

TypeRequiredPlatform
boolNoiOS

contentInset

The amount by which the web view content is inset from the edges of the scroll view. Defaults to {top: 0, left: 0, bottom: 0, right: 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

dataDetectorTypes

Determines the types of data converted to clickable URLs in the web view's content. By default only phone numbers are detected.

You can provide one type or an array of many types.

Possible values for dataDetectorTypes are:

With the new WebKit implementation, we have three new values:

TypeRequiredPlatform
string, or arrayNoiOS

scrollEnabled

Boolean value that determines whether scrolling is enabled in the WebView. The default value is true.

TypeRequiredPlatform
boolNoiOS

geolocationEnabled

Set whether Geolocation is enabled in the WebView. The default value is false. Used only in Android.

TypeRequiredPlatform
boolNoAndroid

allowUniversalAccessFromFileURLs

Boolean that sets whether JavaScript running in the context of a file scheme URL should be allowed to access content from any origin. Including accessing content from other file scheme URLs. The default value is false.

TypeRequiredPlatform
boolNoAndroid

allowFileAccess

Boolean that sets whether the WebView has access to the file system. The default value is false.

TypeRequiredPlatform
boolNoAndroid

useWebKit

If true, use WKWebView instead of UIWebView.

TypeRequiredPlatform
booleanNoiOS

url

Deprecated. Use the source prop instead.

TypeRequired
stringNo

html

Deprecated. Use the source prop instead.

TypeRequired
stringNo

Methods

extraNativeComponentConfig()

static extraNativeComponentConfig()

goForward()

goForward();

Go forward one page in the web view's history.

goBack()

goBack();

Go back one page in the web view's history.

reload()

reload();

Reloads the current page.

stopLoading()

stopLoading();

Stop loading the current page.

Edit this page
Last updated on
- + diff --git a/docs/0.61/webview/index.html b/docs/0.61/webview/index.html index b27895ff8a2..561d060cdbd 100644 --- a/docs/0.61/webview/index.html +++ b/docs/0.61/webview/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
class MyInlineWeb extends Component {
render() {
return (
<WebView
originWhitelist={['*']}
source={{ html: '<h1>Hello world</h1>' }}
/>
);
}
}

You can use this component to navigate back and forth in the web view's history and configure various properties for the web content.

On iOS, the useWebKit prop can be used to opt into a WKWebView-backed implementation.

Security Warning: Currently, onMessage and postMessage do not allow specifying an origin. This can lead to cross-site scripting attacks if an unexpected document is loaded within a WebView instance. Please refer to the MDN documentation for Window.postMessage() for more details on the security implications of this.

Reference

Props

Inherits View Props.

source

Loads static HTML or a URI (with optional headers) in the WebView. Note that static HTML will require setting originWhitelist to ["*"].

The object passed to source can have either of the following shapes:

Load uri

Static HTML

TypeRequired
objectNo

automaticallyAdjustContentInsets

Controls whether to adjust the content inset for web views that are placed behind a navigation bar, tab bar, or toolbar. The default value is true.

TypeRequired
boolNo

injectJavaScript

Function that accepts a string that will be passed to the WebView and executed immediately as JavaScript.

TypeRequired
functionNo

injectedJavaScript

Set this to provide JavaScript that will be injected into the web page when the view loads.

TypeRequired
stringNo

mediaPlaybackRequiresUserAction

Boolean that determines whether HTML5 audio and video requires the user to tap them before they start playing. The default value is true.

TypeRequired
boolNo

nativeConfig

Override the native component used to render the WebView. Enables a custom native WebView which uses the same JavaScript as the original WebView.

The nativeConfig prop expects an object with the following keys:

TypeRequired
objectNo

onError

Function that is invoked when the WebView load fails.

TypeRequired
functionNo

onLoad

Function that is invoked when the WebView has finished loading.

TypeRequired
functionNo

onLoadEnd

Function that is invoked when the WebView load succeeds or fails.

TypeRequired
functionNo

onLoadStart

Function that is invoked when the WebView starts loading.

TypeRequired
functionNo

onMessage

A function that is invoked when the webview calls window.postMessage. Setting this property will inject a postMessage global into your webview, but will still call pre-existing values of postMessage.

window.postMessage accepts one argument, data, which will be available on the event object, event.nativeEvent.data. data must be a string.

TypeRequired
functionNo

onNavigationStateChange

Function that is invoked when the WebView loading starts or ends.

TypeRequired
functionNo

originWhitelist

List of origin strings to allow being navigated to. The strings allow wildcards and get matched against only the origin (not the full URL). If the user taps to navigate to a new page but the new page is not in this safelist, the URL will be handled by the OS. The default safelistlisted origins are "http://*" and "https://*".

TypeRequired
array of stringsNo

renderError

Function that returns a view to show if there's an error.

TypeRequired
functionNo

renderLoading

Function that returns a loading indicator. The startInLoadingState prop must be set to true in order to use this prop.

TypeRequired
functionNo

scalesPageToFit

Boolean that controls whether the web content is scaled to fit the view and enables the user to change the scale. The default value is true.

On iOS, when useWebKit=true, this prop will not work.

TypeRequired
boolNo

onShouldStartLoadWithRequest

Function that allows custom handling of any web view requests. Return true from the function to continue loading the request and false to stop loading.

TypeRequiredPlatform
functionNoiOS

startInLoadingState

Boolean value that forces the WebView to show the loading view on the first load. This prop must be set to true in order for the renderLoading prop to work.

TypeRequired
boolNo

decelerationRate

A floating-point number that determines how quickly the scroll view decelerates after the user lifts their finger. You may also use the string shortcuts "normal" and "fast" which match the underlying iOS settings for UIScrollViewDecelerationRateNormal and UIScrollViewDecelerationRateFast respectively:

TypeRequiredPlatform
numberNoiOS

domStorageEnabled

Boolean value to control whether DOM Storage is enabled. Used only in Android.

TypeRequiredPlatform
boolNoAndroid

javaScriptEnabled

Boolean value to enable JavaScript in the WebView. Used on Android only as JavaScript is enabled by default on iOS. The default value is true.

TypeRequiredPlatform
boolNoAndroid

mixedContentMode

Specifies the mixed content mode. i.e WebView will allow a secure origin to load content from any other origin.

Possible values for mixedContentMode are:

TypeRequiredPlatform
stringNoAndroid

thirdPartyCookiesEnabled

Boolean value to enable third party cookies in the WebView. Used on Android Lollipop and above only as third party cookies are enabled by default on Android Kitkat and below and on iOS. The default value is true.

TypeRequiredPlatform
boolNoAndroid

userAgent

Sets the user-agent for the WebView.

TypeRequiredPlatform
stringNoAndroid

allowsInlineMediaPlayback

Boolean that determines whether HTML5 videos play inline or use the native full-screen controller. The default value is false.

NOTE

In order for video to play inline, not only does this property need to be set to true, but the video element in the HTML document must also include the webkit-playsinline attribute.

TypeRequiredPlatform
boolNoiOS

bounces

Boolean value that determines whether the web view bounces when it reaches the edge of the content. The default value is true.

TypeRequiredPlatform
boolNoiOS

contentInset

The amount by which the web view content is inset from the edges of the scroll view. Defaults to {top: 0, left: 0, bottom: 0, right: 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

dataDetectorTypes

Determines the types of data converted to clickable URLs in the web view's content. By default only phone numbers are detected.

You can provide one type or an array of many types.

Possible values for dataDetectorTypes are:

With the new WebKit implementation, we have three new values:

TypeRequiredPlatform
string, or arrayNoiOS

scrollEnabled

Boolean value that determines whether scrolling is enabled in the WebView. The default value is true.

TypeRequiredPlatform
boolNoiOS

geolocationEnabled

Set whether Geolocation is enabled in the WebView. The default value is false. Used only in Android.

TypeRequiredPlatform
boolNoAndroid

allowUniversalAccessFromFileURLs

Boolean that sets whether JavaScript running in the context of a file scheme URL should be allowed to access content from any origin. Including accessing content from other file scheme URLs. The default value is false.

TypeRequiredPlatform
boolNoAndroid

allowFileAccess

Boolean that sets whether the WebView has access to the file system. The default value is false.

TypeRequiredPlatform
boolNoAndroid

useWebKit

If true, use WKWebView instead of UIWebView.

TypeRequiredPlatform
booleanNoiOS

url

Deprecated. Use the source prop instead.

TypeRequired
stringNo

html

Deprecated. Use the source prop instead.

TypeRequired
stringNo

Methods

extraNativeComponentConfig()

static extraNativeComponentConfig()

goForward()

goForward();

Go forward one page in the web view's history.

goBack()

goBack();

Go back one page in the web view's history.

reload()

reload();

Reloads the current page.

stopLoading()

stopLoading();

Stop loading the current page.

Edit this page
Last updated on
- + diff --git a/docs/0.62/_getting-started-linux-android.html b/docs/0.62/_getting-started-linux-android.html index af1d7edf203..a9135845258 100644 --- a/docs/0.62/_getting-started-linux-android.html +++ b/docs/0.62/_getting-started-linux-android.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: 0.62

_getting-started-linux-android

Installing dependencies

You will need Node, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node

Follow the installation instructions for your Linux distribution to install Node 10 or newer.

Java Development Kit

React Native requires at least the version 8 of the Java SE Development Kit (JDK). You may download and install OpenJDK from AdoptOpenJDK or your system packager. You may also Download and install Oracle JDK 14 if desired.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

Add the following lines to your $HOME/.bash_profile or $HOME/.bashrc (if you are using zsh then ~/.zprofile or ~/.zshrc) config file:

export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

.bash_profile is specific to bash. If you're using another shell, you will need to edit the appropriate shell-specific config file.

Type source $HOME/.bash_profile for bash or source $HOME/.zprofile to load the config into your current shell. Verify that ANDROID_HOME has been set by running echo $ANDROID_HOME and the appropriate directories have been added to your path by running echo $PATH.

Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Watchman

Follow the Watchman installation guide to compile and install Watchman from source.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance and increased compatibility in certain edge cases (translation: you may be able to get by without installing this, but your mileage may vary; installing this now may save you from a headache later).

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

We recommend configuring VM acceleration on your system to improve performance. Once you've followed those instructions, go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (Ctrl + M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.62/_getting-started-linux-android/index.html b/docs/0.62/_getting-started-linux-android/index.html index af1d7edf203..a9135845258 100644 --- a/docs/0.62/_getting-started-linux-android/index.html +++ b/docs/0.62/_getting-started-linux-android/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: 0.62

_getting-started-linux-android

Installing dependencies

You will need Node, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node

Follow the installation instructions for your Linux distribution to install Node 10 or newer.

Java Development Kit

React Native requires at least the version 8 of the Java SE Development Kit (JDK). You may download and install OpenJDK from AdoptOpenJDK or your system packager. You may also Download and install Oracle JDK 14 if desired.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

Add the following lines to your $HOME/.bash_profile or $HOME/.bashrc (if you are using zsh then ~/.zprofile or ~/.zshrc) config file:

export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

.bash_profile is specific to bash. If you're using another shell, you will need to edit the appropriate shell-specific config file.

Type source $HOME/.bash_profile for bash or source $HOME/.zprofile to load the config into your current shell. Verify that ANDROID_HOME has been set by running echo $ANDROID_HOME and the appropriate directories have been added to your path by running echo $PATH.

Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Watchman

Follow the Watchman installation guide to compile and install Watchman from source.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance and increased compatibility in certain edge cases (translation: you may be able to get by without installing this, but your mileage may vary; installing this now may save you from a headache later).

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

We recommend configuring VM acceleration on your system to improve performance. Once you've followed those instructions, go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (Ctrl + M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.62/_getting-started-macos-android.html b/docs/0.62/_getting-started-macos-android.html index 3c140fdba57..c43aa7ed213 100644 --- a/docs/0.62/_getting-started-macos-android.html +++ b/docs/0.62/_getting-started-macos-android.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: 0.62

_getting-started-macos-android

Installing dependencies

You will need Node, Watchman, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node & Watchman

We recommend installing Node and Watchman using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install node
brew install watchman

If you have already installed Node on your system, make sure it is Node 10 or newer.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

Java Development Kit

We recommend installing JDK using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install --cask adoptopenjdk/openjdk/adoptopenjdk8

If you have already installed JDK on your system, make sure it is JDK 8 or newer.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device
  • If you are not already using Hyper-V: Performance (Intel ® HAXM) (See here for AMD or Hyper-V)

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

Android Studio Welcome

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

Add the following lines to your $HOME/.bash_profile or $HOME/.bashrc (if you are using zsh then ~/.zprofile or ~/.zshrc) config file:

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

.bash_profile is specific to bash. If you're using another shell, you will need to edit the appropriate shell-specific config file.

Type source $HOME/.bash_profile for bash or source $HOME/.zprofile to load the config into your current shell. Verify that ANDROID_HOME has been set by running echo $ANDROID_HOME and the appropriate directories have been added to your path by running echo $PATH.

Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

If you don't have HAXM installed, follow these instructions to set it up, then go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

AwesomeProject on Android

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (⌘M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.62/_getting-started-macos-android/index.html b/docs/0.62/_getting-started-macos-android/index.html index 3c140fdba57..c43aa7ed213 100644 --- a/docs/0.62/_getting-started-macos-android/index.html +++ b/docs/0.62/_getting-started-macos-android/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: 0.62

_getting-started-macos-android

Installing dependencies

You will need Node, Watchman, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node & Watchman

We recommend installing Node and Watchman using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install node
brew install watchman

If you have already installed Node on your system, make sure it is Node 10 or newer.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

Java Development Kit

We recommend installing JDK using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install --cask adoptopenjdk/openjdk/adoptopenjdk8

If you have already installed JDK on your system, make sure it is JDK 8 or newer.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device
  • If you are not already using Hyper-V: Performance (Intel ® HAXM) (See here for AMD or Hyper-V)

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

Android Studio Welcome

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

Add the following lines to your $HOME/.bash_profile or $HOME/.bashrc (if you are using zsh then ~/.zprofile or ~/.zshrc) config file:

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

.bash_profile is specific to bash. If you're using another shell, you will need to edit the appropriate shell-specific config file.

Type source $HOME/.bash_profile for bash or source $HOME/.zprofile to load the config into your current shell. Verify that ANDROID_HOME has been set by running echo $ANDROID_HOME and the appropriate directories have been added to your path by running echo $PATH.

Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

If you don't have HAXM installed, follow these instructions to set it up, then go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

AwesomeProject on Android

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (⌘M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.62/_getting-started-macos-ios.html b/docs/0.62/_getting-started-macos-ios.html index 0d9522bca7d..bce95d30974 100644 --- a/docs/0.62/_getting-started-macos-ios.html +++ b/docs/0.62/_getting-started-macos-ios.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: 0.62

_getting-started-macos-ios

Installing dependencies

You will need Node, Watchman, the React Native command line interface, and Xcode.

While you can use any editor of your choice to develop your app, you will need to install Xcode in order to set up the necessary tooling to build your React Native app for iOS.

Node & Watchman

We recommend installing Node and Watchman using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install node
brew install watchman

If you have already installed Node on your system, make sure it is Node 10 or newer.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

Xcode & CocoaPods

The easiest way to install Xcode is via the Mac App Store. Installing Xcode will also install the iOS Simulator and all the necessary tools to build your iOS app.

If you have already installed Xcode on your system, make sure it is version 9.4 or newer.

Command Line Tools

You will also need to install the Xcode Command Line Tools. Open Xcode, then choose "Preferences..." from the Xcode menu. Go to the Locations panel and install the tools by selecting the most recent version in the Command Line Tools dropdown.

Xcode Command Line Tools

Installing an iOS Simulator in Xcode

To install a simulator, open Xcode > Preferences... and select the Components tab. Select a simulator with the corresponding version of iOS you wish to use.

CocoaPods

CocoaPods is built with Ruby and it will be installable with the default Ruby available on macOS. You can use a Ruby Version manager, however we recommend that you use the standard Ruby available on macOS unless you know what you're doing.

Using the default Ruby install will require you to use sudo when installing gems. (This is only an issue for the duration of the gem installation, though.)

sudo gem install cocoapods

For more information, please visit CocoaPods Getting Started guide.

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

You can use React Native's built-in command line interface to generate a new project. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding iOS support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Note If the above command is failing, you may have old version of react-native or react-native-cli installed globally on your pc. Try uninstalling the cli and run the cli using npx.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-ios

You should see your new app running in the iOS Simulator shortly.

AwesomeProject on iOS

npx react-native run-ios is one way to run your app. You can also run it directly from within Xcode.

If you can't get this to work, see the Troubleshooting page.

Running on a device

The above command will automatically run your app on the iOS Simulator by default. If you want to run the app on an actual physical iOS device, please follow the instructions here.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Hit ⌘R in your iOS Simulator to reload the app and see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.62/_getting-started-macos-ios/index.html b/docs/0.62/_getting-started-macos-ios/index.html index 0d9522bca7d..bce95d30974 100644 --- a/docs/0.62/_getting-started-macos-ios/index.html +++ b/docs/0.62/_getting-started-macos-ios/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: 0.62

_getting-started-macos-ios

Installing dependencies

You will need Node, Watchman, the React Native command line interface, and Xcode.

While you can use any editor of your choice to develop your app, you will need to install Xcode in order to set up the necessary tooling to build your React Native app for iOS.

Node & Watchman

We recommend installing Node and Watchman using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install node
brew install watchman

If you have already installed Node on your system, make sure it is Node 10 or newer.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

Xcode & CocoaPods

The easiest way to install Xcode is via the Mac App Store. Installing Xcode will also install the iOS Simulator and all the necessary tools to build your iOS app.

If you have already installed Xcode on your system, make sure it is version 9.4 or newer.

Command Line Tools

You will also need to install the Xcode Command Line Tools. Open Xcode, then choose "Preferences..." from the Xcode menu. Go to the Locations panel and install the tools by selecting the most recent version in the Command Line Tools dropdown.

Xcode Command Line Tools

Installing an iOS Simulator in Xcode

To install a simulator, open Xcode > Preferences... and select the Components tab. Select a simulator with the corresponding version of iOS you wish to use.

CocoaPods

CocoaPods is built with Ruby and it will be installable with the default Ruby available on macOS. You can use a Ruby Version manager, however we recommend that you use the standard Ruby available on macOS unless you know what you're doing.

Using the default Ruby install will require you to use sudo when installing gems. (This is only an issue for the duration of the gem installation, though.)

sudo gem install cocoapods

For more information, please visit CocoaPods Getting Started guide.

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

You can use React Native's built-in command line interface to generate a new project. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding iOS support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Note If the above command is failing, you may have old version of react-native or react-native-cli installed globally on your pc. Try uninstalling the cli and run the cli using npx.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-ios

You should see your new app running in the iOS Simulator shortly.

AwesomeProject on iOS

npx react-native run-ios is one way to run your app. You can also run it directly from within Xcode.

If you can't get this to work, see the Troubleshooting page.

Running on a device

The above command will automatically run your app on the iOS Simulator by default. If you want to run the app on an actual physical iOS device, please follow the instructions here.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Hit ⌘R in your iOS Simulator to reload the app and see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.62/_getting-started-windows-android.html b/docs/0.62/_getting-started-windows-android.html index 6dda45ab44e..05a6612d5ca 100644 --- a/docs/0.62/_getting-started-windows-android.html +++ b/docs/0.62/_getting-started-windows-android.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: 0.62

_getting-started-windows-android

Installing dependencies

You will need Node, the React Native command line interface, Python2, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node, Python2, JDK

We recommend installing Node and Python2 via Chocolatey, a popular package manager for Windows.

React Native also requires Java SE Development Kit (JDK), as well as Python2. Both can be installed using Chocolatey.

Open an Administrator Command Prompt (right click Command Prompt and select "Run as Administrator"), then run the following command:

choco install -y nodejs.install python2 openjdk8

If you have already installed Node on your system, make sure it is Node 10 or newer. If you already have a JDK on your system, make sure it is version 8 or newer.

You can find additional installation options on Node's Downloads page.

If you're using the latest version of Java Development Kit, you'll need to change the Gradle version of your project so it can recognize the JDK. You can do that by going to {project root folder}\android\gradle\wrapper\gradle-wrapper.properties and changing the distributionUrl value to upgrade the Gradle version. You can check out here the lastest releases of Gradle.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device
  • If you are not already using Hyper-V: Performance (Intel ® HAXM) (See here for AMD or Hyper-V)

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

Android Studio Welcome

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

  1. Open the Windows Control Panel.
  2. Click on User Accounts, then click User Accounts again
  3. Click on Change my environment variables
  4. Click on New... to create a new ANDROID_HOME user variable that points to the path to your Android SDK:

ANDROID_HOME Environment Variable

The SDK is installed, by default, at the following location:

%LOCALAPPDATA%\Android\Sdk

You can find the actual location of the SDK in the Android Studio "Settings" dialog, under Appearance & Behavior → System Settings → Android SDK.

Open a new Command Prompt window to ensure the new environment variable is loaded before proceeding to the next step.

  1. Open powershell
  2. Copy and paste Get-ChildItem -Path Env:\ into powershell
  3. Verify ANDROID_HOME has been added

4. Add platform-tools to Path

  1. Open the Windows Control Panel.
  2. Click on User Accounts, then click User Accounts again
  3. Click on Change my environment variables
  4. Select the Path variable.
  5. Click Edit.
  6. Click New and add the path to platform-tools to the list.

The default location for this folder is:

%LOCALAPPDATA%\Android\Sdk\platform-tools

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

If you don't have HAXM installed, click on "Install HAXM" or follow these instructions to set it up, then go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

AwesomeProject on Android

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (Ctrl + M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.62/_getting-started-windows-android/index.html b/docs/0.62/_getting-started-windows-android/index.html index 6dda45ab44e..05a6612d5ca 100644 --- a/docs/0.62/_getting-started-windows-android/index.html +++ b/docs/0.62/_getting-started-windows-android/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: 0.62

_getting-started-windows-android

Installing dependencies

You will need Node, the React Native command line interface, Python2, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node, Python2, JDK

We recommend installing Node and Python2 via Chocolatey, a popular package manager for Windows.

React Native also requires Java SE Development Kit (JDK), as well as Python2. Both can be installed using Chocolatey.

Open an Administrator Command Prompt (right click Command Prompt and select "Run as Administrator"), then run the following command:

choco install -y nodejs.install python2 openjdk8

If you have already installed Node on your system, make sure it is Node 10 or newer. If you already have a JDK on your system, make sure it is version 8 or newer.

You can find additional installation options on Node's Downloads page.

If you're using the latest version of Java Development Kit, you'll need to change the Gradle version of your project so it can recognize the JDK. You can do that by going to {project root folder}\android\gradle\wrapper\gradle-wrapper.properties and changing the distributionUrl value to upgrade the Gradle version. You can check out here the lastest releases of Gradle.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device
  • If you are not already using Hyper-V: Performance (Intel ® HAXM) (See here for AMD or Hyper-V)

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

Android Studio Welcome

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

  1. Open the Windows Control Panel.
  2. Click on User Accounts, then click User Accounts again
  3. Click on Change my environment variables
  4. Click on New... to create a new ANDROID_HOME user variable that points to the path to your Android SDK:

ANDROID_HOME Environment Variable

The SDK is installed, by default, at the following location:

%LOCALAPPDATA%\Android\Sdk

You can find the actual location of the SDK in the Android Studio "Settings" dialog, under Appearance & Behavior → System Settings → Android SDK.

Open a new Command Prompt window to ensure the new environment variable is loaded before proceeding to the next step.

  1. Open powershell
  2. Copy and paste Get-ChildItem -Path Env:\ into powershell
  3. Verify ANDROID_HOME has been added

4. Add platform-tools to Path

  1. Open the Windows Control Panel.
  2. Click on User Accounts, then click User Accounts again
  3. Click on Change my environment variables
  4. Select the Path variable.
  5. Click Edit.
  6. Click New and add the path to platform-tools to the list.

The default location for this folder is:

%LOCALAPPDATA%\Android\Sdk\platform-tools

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

If you don't have HAXM installed, click on "Install HAXM" or follow these instructions to set it up, then go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

AwesomeProject on Android

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (Ctrl + M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.62/_integration-with-exisiting-apps-java.html b/docs/0.62/_integration-with-exisiting-apps-java.html index 6928f3d7dc0..19da7abbd78 100644 --- a/docs/0.62/_integration-with-exisiting-apps-java.html +++ b/docs/0.62/_integration-with-exisiting-apps-java.html @@ -19,7 +19,7 @@ - + @@ -48,7 +48,7 @@
if (mReactInstanceManager != null) {
mReactInstanceManager.onHostDestroy(this);
}
if (mReactRootView != null) {
mReactRootView.unmountReactApplication();
}
}

We also need to pass back button events to React Native:

@Override
public void onBackPressed() {
if (mReactInstanceManager != null) {
mReactInstanceManager.onBackPressed();
} else {
super.onBackPressed();
}
}

This allows JavaScript to control what happens when the user presses the hardware back button (e.g. to implement navigation). When JavaScript doesn't handle the back button press, your invokeDefaultOnBackPressed method will be called. By default this finishes your Activity.

Finally, we need to hook up the dev menu. By default, this is activated by (rage) shaking the device, but this is not very useful in emulators. So we make it show when you press the hardware menu button (use Ctrl + M if you're using Android Studio emulator):

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
if (keyCode == KeyEvent.KEYCODE_MENU && mReactInstanceManager != null) {
mReactInstanceManager.showDevOptionsDialog();
return true;
}
return super.onKeyUp(keyCode, event);
}

Now your activity is ready to run some JavaScript code.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ yarn start
2. Run the app

Now build and run your Android app as normal.

Once you reach your React-powered activity inside the app, it should load the JavaScript code from the development server and display:

Screenshot

Creating a release build in Android Studio

You can use Android Studio to create your release builds too! It’s as quick as creating release builds of your previously-existing native Android app. There’s one additional step, which you’ll have to do before every release build. You need to execute the following to create a React Native bundle, which will be included with your native Android app:

$ npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/com/your-company-name/app-package-name/src/main/assets/index.android.bundle --assets-dest android/com/your-company-name/app-package-name/src/main/res/

Don’t forget to replace the paths with correct ones and create the assets folder if it doesn’t exist.

Now, create a release build of your native app from within Android Studio as usual and you should be good to go!

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.62/_integration-with-exisiting-apps-java/index.html b/docs/0.62/_integration-with-exisiting-apps-java/index.html index 6928f3d7dc0..19da7abbd78 100644 --- a/docs/0.62/_integration-with-exisiting-apps-java/index.html +++ b/docs/0.62/_integration-with-exisiting-apps-java/index.html @@ -19,7 +19,7 @@ - + @@ -48,7 +48,7 @@
if (mReactInstanceManager != null) {
mReactInstanceManager.onHostDestroy(this);
}
if (mReactRootView != null) {
mReactRootView.unmountReactApplication();
}
}

We also need to pass back button events to React Native:

@Override
public void onBackPressed() {
if (mReactInstanceManager != null) {
mReactInstanceManager.onBackPressed();
} else {
super.onBackPressed();
}
}

This allows JavaScript to control what happens when the user presses the hardware back button (e.g. to implement navigation). When JavaScript doesn't handle the back button press, your invokeDefaultOnBackPressed method will be called. By default this finishes your Activity.

Finally, we need to hook up the dev menu. By default, this is activated by (rage) shaking the device, but this is not very useful in emulators. So we make it show when you press the hardware menu button (use Ctrl + M if you're using Android Studio emulator):

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
if (keyCode == KeyEvent.KEYCODE_MENU && mReactInstanceManager != null) {
mReactInstanceManager.showDevOptionsDialog();
return true;
}
return super.onKeyUp(keyCode, event);
}

Now your activity is ready to run some JavaScript code.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ yarn start
2. Run the app

Now build and run your Android app as normal.

Once you reach your React-powered activity inside the app, it should load the JavaScript code from the development server and display:

Screenshot

Creating a release build in Android Studio

You can use Android Studio to create your release builds too! It’s as quick as creating release builds of your previously-existing native Android app. There’s one additional step, which you’ll have to do before every release build. You need to execute the following to create a React Native bundle, which will be included with your native Android app:

$ npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/com/your-company-name/app-package-name/src/main/assets/index.android.bundle --assets-dest android/com/your-company-name/app-package-name/src/main/res/

Don’t forget to replace the paths with correct ones and create the assets folder if it doesn’t exist.

Now, create a release build of your native app from within Android Studio as usual and you should be good to go!

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.62/_integration-with-exisiting-apps-objc.html b/docs/0.62/_integration-with-exisiting-apps-objc.html index f958ed2494e..7346f7fef3b 100644 --- a/docs/0.62/_integration-with-exisiting-apps-objc.html +++ b/docs/0.62/_integration-with-exisiting-apps-objc.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
RCTRootView *rootView =
[[RCTRootView alloc] initWithBundleURL: jsCodeLocation
moduleName: @"RNHighScores"
initialProperties:
@{
@"scores" : @[
@{
@"name" : @"Alex",
@"value": @"42"
},
@{
@"name" : @"Joel",
@"value": @"10"
}
]
}
launchOptions: nil];
UIViewController *vc = [[UIViewController alloc] init];
vc.view = rootView;
[self presentViewController:vc animated:YES completion:nil];
}

Note that RCTRootView initWithURL starts up a new JSC VM. To save resources and simplify the communication between RN views in different parts of your native app, you can have multiple views powered by React Native that are associated with a single JS runtime. To do that, instead of using [RCTRootView alloc] initWithURL, use RCTBridge initWithBundleURL to create a bridge and then use RCTRootView initWithBridge.

When moving your app to production, the NSURL can point to a pre-bundled file on disk via something like [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];. You can use the react-native-xcode.sh script in node_modules/react-native/scripts/ to generate that pre-bundled file.

3. Wire Up

Wire up the new link in the main menu to the newly added event handler method.

Event Path

One of the easier ways to do this is to open the view in the storyboard and right click on the new link. Select something such as the Touch Up Inside event, drag that to the storyboard and then select the created method from the list provided.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Add App Transport Security exception

Apple has blocked implicit cleartext HTTP resource loading. So we need to add the following our project's Info.plist (or equivalent) file.

<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>localhost</key>
<dict>
<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
</dict>

App Transport Security is good for your users. Make sure to re-enable it prior to releasing your app for production.

2. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ npm start
3. Run the app

If you are using Xcode or your favorite editor, build and run your native iOS application as normal. Alternatively, you can run the app from the command line using:

# From the root of your project
$ npx react-native run-ios

In our sample application, you should see the link to the "High Scores" and then when you click on that you will see the rendering of your React Native component.

Here is the native application home screen:

Home Screen

Here is the React Native high score screen:

High Scores

If you are getting module resolution issues when running your application please see this GitHub issue for information and possible resolution. This comment seemed to be the latest possible resolution.

See the Code

You can examine the code that added the React Native screen to our sample app on GitHub.

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.62/_integration-with-exisiting-apps-objc/index.html b/docs/0.62/_integration-with-exisiting-apps-objc/index.html index f958ed2494e..7346f7fef3b 100644 --- a/docs/0.62/_integration-with-exisiting-apps-objc/index.html +++ b/docs/0.62/_integration-with-exisiting-apps-objc/index.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
RCTRootView *rootView =
[[RCTRootView alloc] initWithBundleURL: jsCodeLocation
moduleName: @"RNHighScores"
initialProperties:
@{
@"scores" : @[
@{
@"name" : @"Alex",
@"value": @"42"
},
@{
@"name" : @"Joel",
@"value": @"10"
}
]
}
launchOptions: nil];
UIViewController *vc = [[UIViewController alloc] init];
vc.view = rootView;
[self presentViewController:vc animated:YES completion:nil];
}

Note that RCTRootView initWithURL starts up a new JSC VM. To save resources and simplify the communication between RN views in different parts of your native app, you can have multiple views powered by React Native that are associated with a single JS runtime. To do that, instead of using [RCTRootView alloc] initWithURL, use RCTBridge initWithBundleURL to create a bridge and then use RCTRootView initWithBridge.

When moving your app to production, the NSURL can point to a pre-bundled file on disk via something like [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];. You can use the react-native-xcode.sh script in node_modules/react-native/scripts/ to generate that pre-bundled file.

3. Wire Up

Wire up the new link in the main menu to the newly added event handler method.

Event Path

One of the easier ways to do this is to open the view in the storyboard and right click on the new link. Select something such as the Touch Up Inside event, drag that to the storyboard and then select the created method from the list provided.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Add App Transport Security exception

Apple has blocked implicit cleartext HTTP resource loading. So we need to add the following our project's Info.plist (or equivalent) file.

<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>localhost</key>
<dict>
<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
</dict>

App Transport Security is good for your users. Make sure to re-enable it prior to releasing your app for production.

2. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ npm start
3. Run the app

If you are using Xcode or your favorite editor, build and run your native iOS application as normal. Alternatively, you can run the app from the command line using:

# From the root of your project
$ npx react-native run-ios

In our sample application, you should see the link to the "High Scores" and then when you click on that you will see the rendering of your React Native component.

Here is the native application home screen:

Home Screen

Here is the React Native high score screen:

High Scores

If you are getting module resolution issues when running your application please see this GitHub issue for information and possible resolution. This comment seemed to be the latest possible resolution.

See the Code

You can examine the code that added the React Native screen to our sample app on GitHub.

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.62/_integration-with-exisiting-apps-swift.html b/docs/0.62/_integration-with-exisiting-apps-swift.html index 40f3ec5264a..876ab03f9a3 100644 --- a/docs/0.62/_integration-with-exisiting-apps-swift.html +++ b/docs/0.62/_integration-with-exisiting-apps-swift.html @@ -19,7 +19,7 @@ - + @@ -43,7 +43,7 @@
let rootView = RCTRootView(
bundleURL: jsCodeLocation,
moduleName: "RNHighScores",
initialProperties: mockData as [NSObject : AnyObject],
launchOptions: nil
)
let vc = UIViewController()
vc.view = rootView
self.present(vc, animated: true, completion: nil)
}

Note that RCTRootView bundleURL starts up a new JSC VM. To save resources and simplify the communication between RN views in different parts of your native app, you can have multiple views powered by React Native that are associated with a single JS runtime. To do that, instead of using RCTRootView bundleURL, use RCTBridge initWithBundleURL to create a bridge and then use RCTRootView initWithBridge.

When moving your app to production, the NSURL can point to a pre-bundled file on disk via something like let mainBundle = NSBundle(URLForResource: "main" withExtension:"jsbundle"). You can use the react-native-xcode.sh script in node_modules/react-native/scripts/ to generate that pre-bundled file.

3. Wire Up

Wire up the new link in the main menu to the newly added event handler method.

Event Path

One of the easier ways to do this is to open the view in the storyboard and right click on the new link. Select something such as the Touch Up Inside event, drag that to the storyboard and then select the created method from the list provided.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Add App Transport Security exception

Apple has blocked implicit cleartext HTTP resource loading. So we need to add the following our project's Info.plist (or equivalent) file.

<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>localhost</key>
<dict>
<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
</dict>

App Transport Security is good for your users. Make sure to re-enable it prior to releasing your app for production.

2. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ npm start
3. Run the app

If you are using Xcode or your favorite editor, build and run your native iOS application as normal. Alternatively, you can run the app from the command line using:

# From the root of your project
$ npx react-native run-ios

In our sample application, you should see the link to the "High Scores" and then when you click on that you will see the rendering of your React Native component.

Here is the native application home screen:

Home Screen

Here is the React Native high score screen:

High Scores

If you are getting module resolution issues when running your application please see this GitHub issue for information and possible resolution. This comment seemed to be the latest possible resolution.

See the Code

You can examine the code that added the React Native screen to our sample app on GitHub.

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.62/_integration-with-exisiting-apps-swift/index.html b/docs/0.62/_integration-with-exisiting-apps-swift/index.html index 40f3ec5264a..876ab03f9a3 100644 --- a/docs/0.62/_integration-with-exisiting-apps-swift/index.html +++ b/docs/0.62/_integration-with-exisiting-apps-swift/index.html @@ -19,7 +19,7 @@ - + @@ -43,7 +43,7 @@
let rootView = RCTRootView(
bundleURL: jsCodeLocation,
moduleName: "RNHighScores",
initialProperties: mockData as [NSObject : AnyObject],
launchOptions: nil
)
let vc = UIViewController()
vc.view = rootView
self.present(vc, animated: true, completion: nil)
}

Note that RCTRootView bundleURL starts up a new JSC VM. To save resources and simplify the communication between RN views in different parts of your native app, you can have multiple views powered by React Native that are associated with a single JS runtime. To do that, instead of using RCTRootView bundleURL, use RCTBridge initWithBundleURL to create a bridge and then use RCTRootView initWithBridge.

When moving your app to production, the NSURL can point to a pre-bundled file on disk via something like let mainBundle = NSBundle(URLForResource: "main" withExtension:"jsbundle"). You can use the react-native-xcode.sh script in node_modules/react-native/scripts/ to generate that pre-bundled file.

3. Wire Up

Wire up the new link in the main menu to the newly added event handler method.

Event Path

One of the easier ways to do this is to open the view in the storyboard and right click on the new link. Select something such as the Touch Up Inside event, drag that to the storyboard and then select the created method from the list provided.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Add App Transport Security exception

Apple has blocked implicit cleartext HTTP resource loading. So we need to add the following our project's Info.plist (or equivalent) file.

<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>localhost</key>
<dict>
<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
</dict>

App Transport Security is good for your users. Make sure to re-enable it prior to releasing your app for production.

2. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ npm start
3. Run the app

If you are using Xcode or your favorite editor, build and run your native iOS application as normal. Alternatively, you can run the app from the command line using:

# From the root of your project
$ npx react-native run-ios

In our sample application, you should see the link to the "High Scores" and then when you click on that you will see the rendering of your React Native component.

Here is the native application home screen:

Home Screen

Here is the React Native high score screen:

High Scores

If you are getting module resolution issues when running your application please see this GitHub issue for information and possible resolution. This comment seemed to be the latest possible resolution.

See the Code

You can examine the code that added the React Native screen to our sample app on GitHub.

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.62/accessibility.html b/docs/0.62/accessibility.html index cf6981ef19c..a9c508dea5d 100644 --- a/docs/0.62/accessibility.html +++ b/docs/0.62/accessibility.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
# enable
adb shell settings put secure enabled_accessibility_services com.google.android.marvin.talkback/com.google.android.marvin.talkback.TalkBackService

Additional Resources

Edit this page
Last updated on
- + diff --git a/docs/0.62/accessibility/index.html b/docs/0.62/accessibility/index.html index cf6981ef19c..a9c508dea5d 100644 --- a/docs/0.62/accessibility/index.html +++ b/docs/0.62/accessibility/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
# enable
adb shell settings put secure enabled_accessibility_services com.google.android.marvin.talkback/com.google.android.marvin.talkback.TalkBackService

Additional Resources

Edit this page
Last updated on
- + diff --git a/docs/0.62/accessibilityinfo.html b/docs/0.62/accessibilityinfo.html index 708af3bafb9..41f3ff0a187 100644 --- a/docs/0.62/accessibilityinfo.html +++ b/docs/0.62/accessibilityinfo.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

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.

Example

Reference

Methods

isBoldTextEnabled()

static isBoldTextEnabled()

iOS-Only. Query whether a bold text is currently enabled. Returns a promise which resolves to a boolean. The result is true when bold text is enabled and false otherwise.

isGrayscaleEnabled()

static isGrayscaleEnabled()

iOS-Only. Query whether grayscale is currently enabled. Returns a promise which resolves to a boolean. The result is true when grayscale is enabled and false otherwise.

isInvertColorsEnabled()

static isInvertColorsEnabled()

iOS-Only. Query whether invert colors is currently enabled. Returns a promise which resolves to a boolean. The result is true when invert colors is enabled and false otherwise.

isReduceMotionEnabled()

static isReduceMotionEnabled()

Query whether reduce motion is currently enabled. Returns a promise which resolves to a boolean. The result is true when reduce motion is enabled and false otherwise.

isReduceTransparencyEnabled()

static isReduceTransparencyEnabled()

iOS-Only. Query whether reduce transparency is currently enabled. Returns a promise which resolves to a boolean. The result is true when a reduce transparency is enabled and false otherwise.

isScreenReaderEnabled()

static isScreenReaderEnabled()

Query whether a screen reader is currently enabled. Returns a promise which resolves to a boolean. The result is true when a screen reader is enabled and false otherwise.

addEventListener()

static addEventListener(eventName, handler)

Add an event handler. Supported events:

  • boldTextChanged: iOS-only event. Fires when the state of the bold text toggle changes. The argument to the event handler is a boolean. The boolean is true when bold text is enabled and false otherwise.
  • grayscaleChanged: iOS-only event. Fires when the state of the gray scale toggle changes. The argument to the event handler is a boolean. The boolean is true when a gray scale is enabled and false otherwise.
  • invertColorsChanged: iOS-only event. Fires when the state of the invert colors toggle changes. The argument to the event handler is a boolean. The boolean is true when invert colors is enabled and false otherwise.
  • reduceMotionChanged: Fires when the state of the reduce motion toggle changes. The argument to the event handler is a boolean. The boolean is true when a reduce motion is enabled (or when "Transition Animation Scale" in "Developer options" is "Animation off") and false otherwise.
  • screenReaderChanged: Fires when the state of the screen reader changes. The argument to the event handler is a boolean. The boolean is true when a screen reader is enabled and false otherwise.
  • reduceTransparencyChanged: iOS-only event. Fires when the state of the reduce transparency toggle changes. The argument to the event handler is a boolean. The boolean is true when reduce transparency is enabled and false otherwise.
  • announcementFinished: iOS-only event. Fires when the screen reader has finished making an announcement. The argument to the event handler is a dictionary with these keys:
    • announcement: The string announced by the screen reader.
    • success: A boolean indicating whether the announcement was successfully made.

setAccessibilityFocus()

static setAccessibilityFocus(reactTag)

Set accessibility focus to a React component. On Android, this calls UIManager.sendAccessibilityEvent(reactTag, UIManager.AccessibilityEventTypes.typeViewFocused);.

Note: Make sure that any View you want to receive the accessibility focus has accessible={true}.

announceForAccessibility()

static announceForAccessibility(announcement)

Post a string to be announced by the screen reader.

removeEventListener()

static removeEventListener(eventName, handler)

Remove an event handler.

Edit this page
Last updated on
- + diff --git a/docs/0.62/accessibilityinfo/index.html b/docs/0.62/accessibilityinfo/index.html index 708af3bafb9..41f3ff0a187 100644 --- a/docs/0.62/accessibilityinfo/index.html +++ b/docs/0.62/accessibilityinfo/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

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.

Example

Reference

Methods

isBoldTextEnabled()

static isBoldTextEnabled()

iOS-Only. Query whether a bold text is currently enabled. Returns a promise which resolves to a boolean. The result is true when bold text is enabled and false otherwise.

isGrayscaleEnabled()

static isGrayscaleEnabled()

iOS-Only. Query whether grayscale is currently enabled. Returns a promise which resolves to a boolean. The result is true when grayscale is enabled and false otherwise.

isInvertColorsEnabled()

static isInvertColorsEnabled()

iOS-Only. Query whether invert colors is currently enabled. Returns a promise which resolves to a boolean. The result is true when invert colors is enabled and false otherwise.

isReduceMotionEnabled()

static isReduceMotionEnabled()

Query whether reduce motion is currently enabled. Returns a promise which resolves to a boolean. The result is true when reduce motion is enabled and false otherwise.

isReduceTransparencyEnabled()

static isReduceTransparencyEnabled()

iOS-Only. Query whether reduce transparency is currently enabled. Returns a promise which resolves to a boolean. The result is true when a reduce transparency is enabled and false otherwise.

isScreenReaderEnabled()

static isScreenReaderEnabled()

Query whether a screen reader is currently enabled. Returns a promise which resolves to a boolean. The result is true when a screen reader is enabled and false otherwise.

addEventListener()

static addEventListener(eventName, handler)

Add an event handler. Supported events:

  • boldTextChanged: iOS-only event. Fires when the state of the bold text toggle changes. The argument to the event handler is a boolean. The boolean is true when bold text is enabled and false otherwise.
  • grayscaleChanged: iOS-only event. Fires when the state of the gray scale toggle changes. The argument to the event handler is a boolean. The boolean is true when a gray scale is enabled and false otherwise.
  • invertColorsChanged: iOS-only event. Fires when the state of the invert colors toggle changes. The argument to the event handler is a boolean. The boolean is true when invert colors is enabled and false otherwise.
  • reduceMotionChanged: Fires when the state of the reduce motion toggle changes. The argument to the event handler is a boolean. The boolean is true when a reduce motion is enabled (or when "Transition Animation Scale" in "Developer options" is "Animation off") and false otherwise.
  • screenReaderChanged: Fires when the state of the screen reader changes. The argument to the event handler is a boolean. The boolean is true when a screen reader is enabled and false otherwise.
  • reduceTransparencyChanged: iOS-only event. Fires when the state of the reduce transparency toggle changes. The argument to the event handler is a boolean. The boolean is true when reduce transparency is enabled and false otherwise.
  • announcementFinished: iOS-only event. Fires when the screen reader has finished making an announcement. The argument to the event handler is a dictionary with these keys:
    • announcement: The string announced by the screen reader.
    • success: A boolean indicating whether the announcement was successfully made.

setAccessibilityFocus()

static setAccessibilityFocus(reactTag)

Set accessibility focus to a React component. On Android, this calls UIManager.sendAccessibilityEvent(reactTag, UIManager.AccessibilityEventTypes.typeViewFocused);.

Note: Make sure that any View you want to receive the accessibility focus has accessible={true}.

announceForAccessibility()

static announceForAccessibility(announcement)

Post a string to be announced by the screen reader.

removeEventListener()

static removeEventListener(eventName, handler)

Remove an event handler.

Edit this page
Last updated on
- + diff --git a/docs/0.62/actionsheetios.html b/docs/0.62/actionsheetios.html index baf7eea2be4..fd7170dc47c 100644 --- a/docs/0.62/actionsheetios.html +++ b/docs/0.62/actionsheetios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

ActionSheetIOS

Displays native to iOS Action Sheet component.

Example

Reference

Methods

showActionSheetWithOptions()

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 in options
  • destructiveButtonIndex (int) - index of destructive button in options
  • title (string) - a title to show above the action sheet
  • message (string) - a message to show below the title
  • anchor (number) - the node to which the action sheet should be anchored (used for iPad)
  • tintColor (string) - the color used for non-destructive button titles

The 'callback' function takes one parameter, the zero-based index of the selected item.

Minimal example:

ActionSheetIOS.showActionSheetWithOptions(
{
options: ['Cancel', 'Remove'],
destructiveButtonIndex: 1,
cancelButtonIndex: 0
},
(buttonIndex) => {
if (buttonIndex === 1) {
/* destructive action */
}
}
);

showShareActionSheetWithOptions()

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 share
  • message (string) - a message to share
  • subject (string) - a subject for the message
  • excludedActivityTypes (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.

The 'failureCallback' function takes one parameter, an error object. The only property defined on this object is an optional stack property of type string.

The 'successCallback' function takes two parameters:

  • a boolean value signifying success or failure
  • a string that, in the case of success, indicates the method of sharing
Edit this page
Last updated on
- + diff --git a/docs/0.62/actionsheetios/index.html b/docs/0.62/actionsheetios/index.html index baf7eea2be4..fd7170dc47c 100644 --- a/docs/0.62/actionsheetios/index.html +++ b/docs/0.62/actionsheetios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

ActionSheetIOS

Displays native to iOS Action Sheet component.

Example

Reference

Methods

showActionSheetWithOptions()

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 in options
  • destructiveButtonIndex (int) - index of destructive button in options
  • title (string) - a title to show above the action sheet
  • message (string) - a message to show below the title
  • anchor (number) - the node to which the action sheet should be anchored (used for iPad)
  • tintColor (string) - the color used for non-destructive button titles

The 'callback' function takes one parameter, the zero-based index of the selected item.

Minimal example:

ActionSheetIOS.showActionSheetWithOptions(
{
options: ['Cancel', 'Remove'],
destructiveButtonIndex: 1,
cancelButtonIndex: 0
},
(buttonIndex) => {
if (buttonIndex === 1) {
/* destructive action */
}
}
);

showShareActionSheetWithOptions()

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 share
  • message (string) - a message to share
  • subject (string) - a subject for the message
  • excludedActivityTypes (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.

The 'failureCallback' function takes one parameter, an error object. The only property defined on this object is an optional stack property of type string.

The 'successCallback' function takes two parameters:

  • a boolean value signifying success or failure
  • a string that, in the case of success, indicates the method of sharing
Edit this page
Last updated on
- + diff --git a/docs/0.62/activityindicator.html b/docs/0.62/activityindicator.html index 2bcdd64444e..a74466669ee 100644 --- a/docs/0.62/activityindicator.html +++ b/docs/0.62/activityindicator.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

ActivityIndicator

Displays a circular loading indicator.

Example

Reference

Props

Inherits View Props.

animating

Whether to show the indicator (true, the default) or hide it (false).

TypeRequired
boolNo

color

The foreground color of the spinner (default is gray on iOS and dark cyan on Android).

TypeRequired
colorNo

hidesWhenStopped

Whether the indicator should hide when not animating (true by default).

TypeRequiredPlatform
boolNoiOS

size

Size of the indicator (default is 'small'). Passing a number to the size prop is only supported on Android.

TypeRequired
enum('small', 'large'), numberNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/activityindicator/index.html b/docs/0.62/activityindicator/index.html index 2bcdd64444e..a74466669ee 100644 --- a/docs/0.62/activityindicator/index.html +++ b/docs/0.62/activityindicator/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

ActivityIndicator

Displays a circular loading indicator.

Example

Reference

Props

Inherits View Props.

animating

Whether to show the indicator (true, the default) or hide it (false).

TypeRequired
boolNo

color

The foreground color of the spinner (default is gray on iOS and dark cyan on Android).

TypeRequired
colorNo

hidesWhenStopped

Whether the indicator should hide when not animating (true by default).

TypeRequiredPlatform
boolNoiOS

size

Size of the indicator (default is 'small'). Passing a number to the size prop is only supported on Android.

TypeRequired
enum('small', 'large'), numberNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/alert.html b/docs/0.62/alert.html index 4be68caa431..b58463c614c 100644 --- a/docs/0.62/alert.html +++ b/docs/0.62/alert.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

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 Android and iOS and can show static alerts. To show an alert that prompts the user to enter some information, see AlertIOS; entering text in an alert is common on iOS only.

Example

iOS

On iOS you can specify any number of buttons. Each button can optionally specify a style, which is one of 'default', 'cancel', or 'destructive'.

Android

On Android at most three buttons can be specified. Android has a concept of a neutral, negative and a positive button:

  • If you specify one button, it will be the 'positive' one (such as 'OK')
  • Two buttons mean 'negative', 'positive' (such as 'Cancel', 'OK')
  • Three buttons mean 'neutral', 'negative', 'positive' (such as 'Later', 'Cancel', 'OK')

By default alerts on Android can be dismissed by tapping outside of the alert box. This event can be handled by providing an optional options parameter, with an onDismiss callback property { onDismiss: () => {} }.

Alternatively, the dismissing behavior can be disabled altogether by providing an optional options parameter with the cancelable property set to false i.e. { cancelable: false }.

Example usage:

// Works on both Android and iOS
Alert.alert(
'Alert Title',
'My Alert Msg',
[
{
text: 'Ask me later',
onPress: () => console.log('Ask me later pressed')
},
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{ text: 'OK', onPress: () => console.log('OK Pressed') }
],
{ cancelable: false }
);

Reference

Methods

alert()

static alert(title, message?, buttons?, options?)
Edit this page
Last updated on
- + diff --git a/docs/0.62/alert/index.html b/docs/0.62/alert/index.html index 4be68caa431..b58463c614c 100644 --- a/docs/0.62/alert/index.html +++ b/docs/0.62/alert/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

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 Android and iOS and can show static alerts. To show an alert that prompts the user to enter some information, see AlertIOS; entering text in an alert is common on iOS only.

Example

iOS

On iOS you can specify any number of buttons. Each button can optionally specify a style, which is one of 'default', 'cancel', or 'destructive'.

Android

On Android at most three buttons can be specified. Android has a concept of a neutral, negative and a positive button:

  • If you specify one button, it will be the 'positive' one (such as 'OK')
  • Two buttons mean 'negative', 'positive' (such as 'Cancel', 'OK')
  • Three buttons mean 'neutral', 'negative', 'positive' (such as 'Later', 'Cancel', 'OK')

By default alerts on Android can be dismissed by tapping outside of the alert box. This event can be handled by providing an optional options parameter, with an onDismiss callback property { onDismiss: () => {} }.

Alternatively, the dismissing behavior can be disabled altogether by providing an optional options parameter with the cancelable property set to false i.e. { cancelable: false }.

Example usage:

// Works on both Android and iOS
Alert.alert(
'Alert Title',
'My Alert Msg',
[
{
text: 'Ask me later',
onPress: () => console.log('Ask me later pressed')
},
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{ text: 'OK', onPress: () => console.log('OK Pressed') }
],
{ cancelable: false }
);

Reference

Methods

alert()

static alert(title, message?, buttons?, options?)
Edit this page
Last updated on
- + diff --git a/docs/0.62/alertios.html b/docs/0.62/alertios.html index 1f739552de5..13c7138a1b8 100644 --- a/docs/0.62/alertios.html +++ b/docs/0.62/alertios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 AlertIOS

Deprecated. Use Alert instead.

AlertIOS provides functionality to create an iOS alert dialog with a message or create a prompt for user input.

Creating an iOS alert:

AlertIOS.alert(
'Sync Complete',
'All your data are belong to us.'
);

Creating an iOS prompt:

AlertIOS.prompt('Enter a value', null, (text) =>
console.log('You entered ' + text)
);

We recommend using the Alert.alert method for cross-platform support if you don't need to create iOS-only prompts.

Reference

Methods

alert()

static alert(title: string, [message]: string, [callbackOrButtons]: ?(() => void), ButtonsArray, [type]: AlertType): [object Object]

Create and display a popup alert.

Parameters:

NameTypeRequiredDescription
titlestringYesThe dialog's title. Passing null or '' will hide the title.
messagestringNoAn optional message that appears below the dialog's title.
callbackOrButtons?(() => void),ButtonsArrayNoThis optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called when the user taps 'OK'. If passed an array of button configurations, each button should include a text key, as well as optional onPress and style keys. style should be one of 'default', 'cancel' or 'destructive'.
typeAlertTypeNoDeprecated, do not use.

Example with custom buttons:

AlertIOS.alert(
'Update available',
'Keep your app up to date to enjoy the latest features',
[
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{
text: 'Install',
onPress: () => console.log('Install Pressed')
}
]
);

prompt()

static prompt(title: string, [message]: string, [callbackOrButtons]: ?((text: string) => void), ButtonsArray, [type]: AlertType, [defaultValue]: string, [keyboardType]: string): [object Object]

Create and display a prompt to enter some text.

Parameters:

NameTypeRequiredDescription
titlestringYesThe dialog's title.
messagestringNoAn optional message that appears above the text input.
callbackOrButtons?((text: string) => void),ButtonsArrayNoThis optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called with the prompt's value when the user taps 'OK'. If passed an array of button configurations, each button should include a text key, as well as optional onPress and style keys (see example). style should be one of 'default', 'cancel' or 'destructive'.
typeAlertTypeNoThis configures the text input. One of 'plain-text', 'secure-text' or 'login-password'.
defaultValuestringNoThe default text in text input.
keyboardTypestringNoThe keyboard type of first text field(if exists). One of 'default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter' or 'web-search'.

Example with custom buttons:

AlertIOS.prompt(
'Enter password',
'Enter your password to claim your $1.5B in lottery winnings',
[
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{
text: 'OK',
onPress: (password) =>
console.log('OK Pressed, password: ' + password)
}
],
'secure-text'
);

,

Example with the default button and a custom callback:

AlertIOS.prompt(
'Update username',
null,
(text) => console.log('Your username is ' + text),
null,
'default'
);

Type Definitions

AlertType

An Alert button type

Type
\$Enum

Constants:

ValueDescription
defaultDefault alert with no inputs
plain-textPlain text input alert
secure-textSecure text input alert
login-passwordLogin and password alert

AlertButtonStyle

An Alert button style

Type
\$Enum

Constants:

ValueDescription
defaultDefault button style
cancelCancel button style
destructiveDestructive button style

ButtonsArray

Array or buttons

Type
Array

Properties:

NameTypeDescription
[text]stringButton label
[onPress]functionCallback function when button pressed
[style]AlertButtonStyleButton style

Constants:

ValueDescription
textButton label
onPressCallback function when button pressed
styleButton style
Edit this page
Last updated on
- + diff --git a/docs/0.62/alertios/index.html b/docs/0.62/alertios/index.html index 1f739552de5..13c7138a1b8 100644 --- a/docs/0.62/alertios/index.html +++ b/docs/0.62/alertios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 AlertIOS

Deprecated. Use Alert instead.

AlertIOS provides functionality to create an iOS alert dialog with a message or create a prompt for user input.

Creating an iOS alert:

AlertIOS.alert(
'Sync Complete',
'All your data are belong to us.'
);

Creating an iOS prompt:

AlertIOS.prompt('Enter a value', null, (text) =>
console.log('You entered ' + text)
);

We recommend using the Alert.alert method for cross-platform support if you don't need to create iOS-only prompts.

Reference

Methods

alert()

static alert(title: string, [message]: string, [callbackOrButtons]: ?(() => void), ButtonsArray, [type]: AlertType): [object Object]

Create and display a popup alert.

Parameters:

NameTypeRequiredDescription
titlestringYesThe dialog's title. Passing null or '' will hide the title.
messagestringNoAn optional message that appears below the dialog's title.
callbackOrButtons?(() => void),ButtonsArrayNoThis optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called when the user taps 'OK'. If passed an array of button configurations, each button should include a text key, as well as optional onPress and style keys. style should be one of 'default', 'cancel' or 'destructive'.
typeAlertTypeNoDeprecated, do not use.

Example with custom buttons:

AlertIOS.alert(
'Update available',
'Keep your app up to date to enjoy the latest features',
[
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{
text: 'Install',
onPress: () => console.log('Install Pressed')
}
]
);

prompt()

static prompt(title: string, [message]: string, [callbackOrButtons]: ?((text: string) => void), ButtonsArray, [type]: AlertType, [defaultValue]: string, [keyboardType]: string): [object Object]

Create and display a prompt to enter some text.

Parameters:

NameTypeRequiredDescription
titlestringYesThe dialog's title.
messagestringNoAn optional message that appears above the text input.
callbackOrButtons?((text: string) => void),ButtonsArrayNoThis optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called with the prompt's value when the user taps 'OK'. If passed an array of button configurations, each button should include a text key, as well as optional onPress and style keys (see example). style should be one of 'default', 'cancel' or 'destructive'.
typeAlertTypeNoThis configures the text input. One of 'plain-text', 'secure-text' or 'login-password'.
defaultValuestringNoThe default text in text input.
keyboardTypestringNoThe keyboard type of first text field(if exists). One of 'default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter' or 'web-search'.

Example with custom buttons:

AlertIOS.prompt(
'Enter password',
'Enter your password to claim your $1.5B in lottery winnings',
[
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{
text: 'OK',
onPress: (password) =>
console.log('OK Pressed, password: ' + password)
}
],
'secure-text'
);

,

Example with the default button and a custom callback:

AlertIOS.prompt(
'Update username',
null,
(text) => console.log('Your username is ' + text),
null,
'default'
);

Type Definitions

AlertType

An Alert button type

Type
\$Enum

Constants:

ValueDescription
defaultDefault alert with no inputs
plain-textPlain text input alert
secure-textSecure text input alert
login-passwordLogin and password alert

AlertButtonStyle

An Alert button style

Type
\$Enum

Constants:

ValueDescription
defaultDefault button style
cancelCancel button style
destructiveDestructive button style

ButtonsArray

Array or buttons

Type
Array

Properties:

NameTypeDescription
[text]stringButton label
[onPress]functionCallback function when button pressed
[style]AlertButtonStyleButton style

Constants:

ValueDescription
textButton label
onPressCallback function when button pressed
styleButton style
Edit this page
Last updated on
- + diff --git a/docs/0.62/animated.html b/docs/0.62/animated.html index cd172dabe0b..412ba48ce08 100644 --- a/docs/0.62/animated.html +++ b/docs/0.62/animated.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Animated

The Animated library is designed to make animations fluid, powerful, and painless to build and maintain. Animated focuses on declarative relationships between inputs and outputs, configurable transforms in between, and start/stop methods to control time-based animation execution.

The core workflow for creating an animation is to create an Animated.Value, hook it up to one or more style attributes of an animated component, and then drive updates via animations using Animated.timing().

Don't modify the animated value directly. You can use the useRef Hook to return a mutable ref object. This ref object's current property is initialized as the given argument and persists throughout the component lifecycle.

Example

The following example contains a View which will fade in and fade out based on the animated value fadeAnim

Refer to the Animations guide to see additional examples of Animated in action.

Overview

There are two value types you can use with Animated:

Animated.Value can bind to style properties or other props, and can be interpolated as well. A single Animated.Value can drive any number of properties.

Configuring animations

Animated provides three types of animation types. Each animation type provides a particular animation curve that controls how your values animate from their initial value to the final value:

In most cases, you will be using timing(). By default, it uses a symmetric easeInOut curve that conveys the gradual acceleration of an object to full speed and concludes by gradually decelerating to a stop.

Working with animations

Animations are started by calling start() on your animation. start() takes a completion callback that will be called when the animation is done. If the animation finished running normally, the completion callback will be invoked with {finished: true}. If the animation is done because stop() was called on it before it could finish (e.g. because it was interrupted by a gesture or another animation), then it will receive {finished: false}.

Animated.timing({}).start(({ finished }) => {
/* completion callback */
});

Using the native driver

By using the native driver, we send everything about the animation to native before starting the animation, allowing native code to perform the animation on the UI thread without having to go through the bridge on every frame. Once the animation has started, the JS thread can be blocked without affecting the animation.

You can use the native driver by specifying useNativeDriver: true in your animation configuration. See the Animations guide to learn more.

Animatable components

Only animatable components can be animated. These unique components do the magic of binding the animated values to the properties, and do targeted native updates to avoid the cost of the react render and reconciliation process on every frame. They also handle cleanup on unmount so they are safe by default.

Animated exports the following animatable components using the above wrapper:

  • Animated.Image
  • Animated.ScrollView
  • Animated.Text
  • Animated.View
  • Animated.FlatList
  • Animated.SectionList

Composing animations

Animations can also be combined in complex ways using composition functions:

Animations can also be chained together by setting the toValue of one animation to be another Animated.Value. See Tracking dynamic values in the Animations guide.

By default, if one animation is stopped or interrupted, then all other animations in the group are also stopped.

Combining animated values

You can combine two animated values via addition, subtraction, multiplication, division, or modulo to make a new animated value:

Interpolation

The interpolate() function allows input ranges to map to different output ranges. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value. It uses linear interpolation by default but also supports easing functions.

Read more about interpolation in the Animation guide.

Handling gestures and other events

Gestures, like panning or scrolling, and other events can map directly to animated values using Animated.event(). This is done with a structured map syntax so that values can be extracted from complex event objects. The first level is an array to allow mapping across multiple args, and that array contains nested objects.

For example, when working with horizontal scrolling gestures, you would do the following in order to map event.nativeEvent.contentOffset.x to scrollX (an Animated.Value):

onScroll={Animated.event(
// scrollX = e.nativeEvent.contentOffset.x
[{ nativeEvent: {
contentOffset: {
x: scrollX
}
}
}]
)}

Reference

Methods

When the given value is a ValueXY instead of a Value, each config option may be a vector of the form {x: ..., y: ...} instead of a scalar.

decay()

static decay(value, config)

Animates a value from an initial velocity to zero based on a decay coefficient.

Config is an object that may have the following options:

  • velocity: Initial velocity. Required.
  • deceleration: Rate of decay. Default 0.997.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

timing()

static timing(value, config)

Animates a value along a timed easing curve. The Easing module has tons of predefined curves, or you can use your own function.

Config is an object that may have the following options:

  • duration: Length of animation (milliseconds). Default 500.
  • easing: Easing function to define curve. Default is Easing.inOut(Easing.ease).
  • delay: Start the animation after delay (milliseconds). Default 0.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

spring()

static spring(value, config)

Animates a value according to an analytical spring model based on damped harmonic oscillation. Tracks velocity state to create fluid motions as the toValue updates, and can be chained together.

Config is an object that may have the following options.

Note that you can only define one of bounciness/speed, tension/friction, or stiffness/damping/mass, but not more than one:

The friction/tension or bounciness/speed options match the spring model in Facebook Pop, Rebound, and Origami.

  • friction: Controls "bounciness"/overshoot. Default 7.
  • tension: Controls speed. Default 40.
  • speed: Controls speed of the animation. Default 12.
  • bounciness: Controls bounciness. Default 8.

Specifying stiffness/damping/mass as parameters makes Animated.spring use an analytical spring model based on the motion equations of a damped harmonic oscillator. This behavior is slightly more precise and faithful to the physics behind spring dynamics, and closely mimics the implementation in iOS's CASpringAnimation.

  • stiffness: The spring stiffness coefficient. Default 100.
  • damping: Defines how the spring’s motion should be damped due to the forces of friction. Default 10.
  • mass: The mass of the object attached to the end of the spring. Default 1.

Other configuration options are as follows:

  • velocity: The initial velocity of the object attached to the spring. Default 0 (object is at rest).
  • overshootClamping: Boolean indicating whether the spring should be clamped and not bounce. Default false.
  • restDisplacementThreshold: The threshold of displacement from rest below which the spring should be considered at rest. Default 0.001.
  • restSpeedThreshold: The speed at which the spring should be considered at rest in pixels per second. Default 0.001.
  • delay: Start the animation after delay (milliseconds). Default 0.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

add()

static add(a, b)

Creates a new Animated value composed from two Animated values added together.

subtract()

static subtract(a, b)

Creates a new Animated value composed by subtracting the second Animated value from the first Animated value.

divide()

static divide(a, b)

Creates a new Animated value composed by dividing the first Animated value by the second Animated value.

multiply()

static multiply(a, b)

Creates a new Animated value composed from two Animated values multiplied together.

modulo()

static modulo(a, modulus)

Creates a new Animated value that is the (non-negative) modulo of the provided Animated value

diffClamp()

static diffClamp(a, min, max)

Create a new Animated value that is limited between 2 values. It uses the difference between the last value so even if the value is far from the bounds it will start changing when the value starts getting closer again. (value = clamp(value + diff, min, max)).

This is useful with scroll events, for example, to show the navbar when scrolling up and to hide it when scrolling down.

delay()

static delay(time)

Starts an animation after the given delay.

sequence()

static sequence(animations)

Starts an array of animations in order, waiting for each to complete before starting the next. If the current running animation is stopped, no following animations will be started.

parallel()

static parallel(animations, config?)

Starts an array of animations all at the same time. By default, if one of the animations is stopped, they will all be stopped. You can override this with the stopTogether flag.

stagger()

static stagger(time, animations)

Array of animations may run in parallel (overlap), but are started in sequence with successive delays. Nice for doing trailing effects.

loop()

static loop(animation, config?)

Loops a given animation continuously, so that each time it reaches the end, it resets and begins again from the start. Will loop without blocking the JS thread if the child animation is set to useNativeDriver: true. In addition, loops can prevent VirtualizedList-based components from rendering more rows while the animation is running. You can pass isInteraction: false in the child animation config to fix this.

Config is an object that may have the following options:

  • iterations: Number of times the animation should loop. Default -1 (infinite).

event()

static event(argMapping, config?)

Takes an array of mappings and extracts values from each arg accordingly, then calls setValue on the mapped outputs. e.g.

onScroll={Animated.event(
[{nativeEvent: {contentOffset: {x: this._scrollX}}}],
{listener: (event) => console.log(event)}, // Optional async listener
)}
...
onPanResponderMove: Animated.event([
null, // raw event arg ignored
{dx: this._panX}], // gestureState arg
{listener: (event, gestureState) => console.log(event, gestureState)}, // Optional async listener
),

Config is an object that may have the following options:

  • listener: Optional async listener.
  • useNativeDriver: Uses the native driver when true. Default false.

forkEvent()

static forkEvent(event, listener)

Advanced imperative API for snooping on animated events that are passed in through props. It permits to add a new javascript listener to an existing AnimatedEvent. If animatedEvent is a javascript listener, it will merge the 2 listeners into a single one, and if animatedEvent is null/undefined, it will assign the javascript listener directly. Use values directly where possible.aa

unforkEvent()

static unforkEvent(event, listener)

start()

static start([callback]: ?(result?: {finished: boolean}) => void)

Animations are started by calling start() on your animation. start() takes a completion callback that will be called when the animation is done or when the animation is done because stop() was called on it before it could finish.

Parameters:

NameTypeRequiredDescription
callback?(result?: {finished: boolean})NoFunction that will be called after the animation finished running normally or when the animation is done because stop() was called on it before it could finish

Start example with callback:

Animated.timing({}).start(({ finished }) => {
/* completion callback */
});

stop()

static stop()

Stops any running animation.

reset()

static reset()

Stops any running animation and resets the value to its original.

Properties

Value

Standard value class for driving animations. Typically initialized with new Animated.Value(0);

ValueXY

2D value class for driving 2D animations, such as pan gestures.

Interpolation

Exported to use the Interpolation type in flow.

Node

Exported for ease of type checking. All animated values derive from this class.

createAnimatedComponent

Make any React component Animatable. Used to create Animated.View, etc.

attachNativeEvent

Imperative API to attach an animated value to an event on a view. Prefer using Animated.event with useNativeDrive: true if possible.

Edit this page
Last updated on
- + diff --git a/docs/0.62/animated/index.html b/docs/0.62/animated/index.html index cd172dabe0b..412ba48ce08 100644 --- a/docs/0.62/animated/index.html +++ b/docs/0.62/animated/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Animated

The Animated library is designed to make animations fluid, powerful, and painless to build and maintain. Animated focuses on declarative relationships between inputs and outputs, configurable transforms in between, and start/stop methods to control time-based animation execution.

The core workflow for creating an animation is to create an Animated.Value, hook it up to one or more style attributes of an animated component, and then drive updates via animations using Animated.timing().

Don't modify the animated value directly. You can use the useRef Hook to return a mutable ref object. This ref object's current property is initialized as the given argument and persists throughout the component lifecycle.

Example

The following example contains a View which will fade in and fade out based on the animated value fadeAnim

Refer to the Animations guide to see additional examples of Animated in action.

Overview

There are two value types you can use with Animated:

Animated.Value can bind to style properties or other props, and can be interpolated as well. A single Animated.Value can drive any number of properties.

Configuring animations

Animated provides three types of animation types. Each animation type provides a particular animation curve that controls how your values animate from their initial value to the final value:

In most cases, you will be using timing(). By default, it uses a symmetric easeInOut curve that conveys the gradual acceleration of an object to full speed and concludes by gradually decelerating to a stop.

Working with animations

Animations are started by calling start() on your animation. start() takes a completion callback that will be called when the animation is done. If the animation finished running normally, the completion callback will be invoked with {finished: true}. If the animation is done because stop() was called on it before it could finish (e.g. because it was interrupted by a gesture or another animation), then it will receive {finished: false}.

Animated.timing({}).start(({ finished }) => {
/* completion callback */
});

Using the native driver

By using the native driver, we send everything about the animation to native before starting the animation, allowing native code to perform the animation on the UI thread without having to go through the bridge on every frame. Once the animation has started, the JS thread can be blocked without affecting the animation.

You can use the native driver by specifying useNativeDriver: true in your animation configuration. See the Animations guide to learn more.

Animatable components

Only animatable components can be animated. These unique components do the magic of binding the animated values to the properties, and do targeted native updates to avoid the cost of the react render and reconciliation process on every frame. They also handle cleanup on unmount so they are safe by default.

Animated exports the following animatable components using the above wrapper:

  • Animated.Image
  • Animated.ScrollView
  • Animated.Text
  • Animated.View
  • Animated.FlatList
  • Animated.SectionList

Composing animations

Animations can also be combined in complex ways using composition functions:

Animations can also be chained together by setting the toValue of one animation to be another Animated.Value. See Tracking dynamic values in the Animations guide.

By default, if one animation is stopped or interrupted, then all other animations in the group are also stopped.

Combining animated values

You can combine two animated values via addition, subtraction, multiplication, division, or modulo to make a new animated value:

Interpolation

The interpolate() function allows input ranges to map to different output ranges. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value. It uses linear interpolation by default but also supports easing functions.

Read more about interpolation in the Animation guide.

Handling gestures and other events

Gestures, like panning or scrolling, and other events can map directly to animated values using Animated.event(). This is done with a structured map syntax so that values can be extracted from complex event objects. The first level is an array to allow mapping across multiple args, and that array contains nested objects.

For example, when working with horizontal scrolling gestures, you would do the following in order to map event.nativeEvent.contentOffset.x to scrollX (an Animated.Value):

onScroll={Animated.event(
// scrollX = e.nativeEvent.contentOffset.x
[{ nativeEvent: {
contentOffset: {
x: scrollX
}
}
}]
)}

Reference

Methods

When the given value is a ValueXY instead of a Value, each config option may be a vector of the form {x: ..., y: ...} instead of a scalar.

decay()

static decay(value, config)

Animates a value from an initial velocity to zero based on a decay coefficient.

Config is an object that may have the following options:

  • velocity: Initial velocity. Required.
  • deceleration: Rate of decay. Default 0.997.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

timing()

static timing(value, config)

Animates a value along a timed easing curve. The Easing module has tons of predefined curves, or you can use your own function.

Config is an object that may have the following options:

  • duration: Length of animation (milliseconds). Default 500.
  • easing: Easing function to define curve. Default is Easing.inOut(Easing.ease).
  • delay: Start the animation after delay (milliseconds). Default 0.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

spring()

static spring(value, config)

Animates a value according to an analytical spring model based on damped harmonic oscillation. Tracks velocity state to create fluid motions as the toValue updates, and can be chained together.

Config is an object that may have the following options.

Note that you can only define one of bounciness/speed, tension/friction, or stiffness/damping/mass, but not more than one:

The friction/tension or bounciness/speed options match the spring model in Facebook Pop, Rebound, and Origami.

  • friction: Controls "bounciness"/overshoot. Default 7.
  • tension: Controls speed. Default 40.
  • speed: Controls speed of the animation. Default 12.
  • bounciness: Controls bounciness. Default 8.

Specifying stiffness/damping/mass as parameters makes Animated.spring use an analytical spring model based on the motion equations of a damped harmonic oscillator. This behavior is slightly more precise and faithful to the physics behind spring dynamics, and closely mimics the implementation in iOS's CASpringAnimation.

  • stiffness: The spring stiffness coefficient. Default 100.
  • damping: Defines how the spring’s motion should be damped due to the forces of friction. Default 10.
  • mass: The mass of the object attached to the end of the spring. Default 1.

Other configuration options are as follows:

  • velocity: The initial velocity of the object attached to the spring. Default 0 (object is at rest).
  • overshootClamping: Boolean indicating whether the spring should be clamped and not bounce. Default false.
  • restDisplacementThreshold: The threshold of displacement from rest below which the spring should be considered at rest. Default 0.001.
  • restSpeedThreshold: The speed at which the spring should be considered at rest in pixels per second. Default 0.001.
  • delay: Start the animation after delay (milliseconds). Default 0.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

add()

static add(a, b)

Creates a new Animated value composed from two Animated values added together.

subtract()

static subtract(a, b)

Creates a new Animated value composed by subtracting the second Animated value from the first Animated value.

divide()

static divide(a, b)

Creates a new Animated value composed by dividing the first Animated value by the second Animated value.

multiply()

static multiply(a, b)

Creates a new Animated value composed from two Animated values multiplied together.

modulo()

static modulo(a, modulus)

Creates a new Animated value that is the (non-negative) modulo of the provided Animated value

diffClamp()

static diffClamp(a, min, max)

Create a new Animated value that is limited between 2 values. It uses the difference between the last value so even if the value is far from the bounds it will start changing when the value starts getting closer again. (value = clamp(value + diff, min, max)).

This is useful with scroll events, for example, to show the navbar when scrolling up and to hide it when scrolling down.

delay()

static delay(time)

Starts an animation after the given delay.

sequence()

static sequence(animations)

Starts an array of animations in order, waiting for each to complete before starting the next. If the current running animation is stopped, no following animations will be started.

parallel()

static parallel(animations, config?)

Starts an array of animations all at the same time. By default, if one of the animations is stopped, they will all be stopped. You can override this with the stopTogether flag.

stagger()

static stagger(time, animations)

Array of animations may run in parallel (overlap), but are started in sequence with successive delays. Nice for doing trailing effects.

loop()

static loop(animation, config?)

Loops a given animation continuously, so that each time it reaches the end, it resets and begins again from the start. Will loop without blocking the JS thread if the child animation is set to useNativeDriver: true. In addition, loops can prevent VirtualizedList-based components from rendering more rows while the animation is running. You can pass isInteraction: false in the child animation config to fix this.

Config is an object that may have the following options:

  • iterations: Number of times the animation should loop. Default -1 (infinite).

event()

static event(argMapping, config?)

Takes an array of mappings and extracts values from each arg accordingly, then calls setValue on the mapped outputs. e.g.

onScroll={Animated.event(
[{nativeEvent: {contentOffset: {x: this._scrollX}}}],
{listener: (event) => console.log(event)}, // Optional async listener
)}
...
onPanResponderMove: Animated.event([
null, // raw event arg ignored
{dx: this._panX}], // gestureState arg
{listener: (event, gestureState) => console.log(event, gestureState)}, // Optional async listener
),

Config is an object that may have the following options:

  • listener: Optional async listener.
  • useNativeDriver: Uses the native driver when true. Default false.

forkEvent()

static forkEvent(event, listener)

Advanced imperative API for snooping on animated events that are passed in through props. It permits to add a new javascript listener to an existing AnimatedEvent. If animatedEvent is a javascript listener, it will merge the 2 listeners into a single one, and if animatedEvent is null/undefined, it will assign the javascript listener directly. Use values directly where possible.aa

unforkEvent()

static unforkEvent(event, listener)

start()

static start([callback]: ?(result?: {finished: boolean}) => void)

Animations are started by calling start() on your animation. start() takes a completion callback that will be called when the animation is done or when the animation is done because stop() was called on it before it could finish.

Parameters:

NameTypeRequiredDescription
callback?(result?: {finished: boolean})NoFunction that will be called after the animation finished running normally or when the animation is done because stop() was called on it before it could finish

Start example with callback:

Animated.timing({}).start(({ finished }) => {
/* completion callback */
});

stop()

static stop()

Stops any running animation.

reset()

static reset()

Stops any running animation and resets the value to its original.

Properties

Value

Standard value class for driving animations. Typically initialized with new Animated.Value(0);

ValueXY

2D value class for driving 2D animations, such as pan gestures.

Interpolation

Exported to use the Interpolation type in flow.

Node

Exported for ease of type checking. All animated values derive from this class.

createAnimatedComponent

Make any React component Animatable. Used to create Animated.View, etc.

attachNativeEvent

Imperative API to attach an animated value to an event on a view. Prefer using Animated.event with useNativeDrive: true if possible.

Edit this page
Last updated on
- + diff --git a/docs/0.62/animatedvalue.html b/docs/0.62/animatedvalue.html index 54023edf5cd..d541598c0dc 100644 --- a/docs/0.62/animatedvalue.html +++ b/docs/0.62/animatedvalue.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

AnimatedValue

Standard value for driving animations. One Animated.Value can drive multiple properties in a synchronized fashion, but can only be driven by one mechanism at a time. Using a new mechanism (e.g. starting a new animation, or calling setValue) will stop any previous ones.

Typically initialized with new Animated.Value(0);

See also Animated.

Methods

Reference

Methods

setValue()

setValue(value);

Directly set the value. This will stop any animations running on the value and update all the bound properties.

Parameters:

NameTypeRequiredDescription
valuenumberYesValue

setOffset()

setOffset(offset);

Sets an offset that is applied on top of whatever value is set, whether via setValue, an animation, or Animated.event. Useful for compensating things like the start of a pan gesture.

Parameters:

NameTypeRequiredDescription
offsetnumberYesOffset value

flattenOffset()

flattenOffset();

Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.

extractOffset()

extractOffset();

Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.

addListener()

addListener(callback);

Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.

Returns a string that serves as an identifier for the listener.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesThe callback function which will receive an object with a value key set to the new value.

removeListener()

removeListener(id);

Unregister a listener. The id param shall match the identifier previously returned by addListener().

Parameters:

NameTypeRequiredDescription
idstringYesId for the listener being removed.

removeAllListeners()

removeAllListeners();

Remove all registered listeners.

stopAnimation()

stopAnimation([callback]);

Stops any running animation or tracking. callback is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the final value.

resetAnimation()

resetAnimation([callback]);

Stops any animation and resets the value to its original.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the original value.

interpolate()

interpolate(config);

Interpolates the value before updating the property, e.g. mapping 0-1 to 0-10.

See AnimatedInterpolation.js

Parameters:

NameTypeRequiredDescription
configobjectYesSee below.

The config object is composed of the following keys:

  • inputRange: an array of numbers
  • outputRange: an array of numbers or strings
  • easing (optional): a function that returns a number, given an input number
  • extrapolate (optional): a string such as 'extend', 'identity', or 'clamp'
  • extrapolateLeft (optional): a string such as 'extend', 'identity', or 'clamp'
  • extrapolateRight (optional): a string such as 'extend', 'identity', or 'clamp'

animate()

animate(animation, callback);

Typically only used internally, but could be used by a custom Animation class.

Parameters:

NameTypeRequiredDescription
animationAnimationYesSee Animation.js.
callbackfunctionYesCallback function.

stopTracking()

stopTracking();

Typically only used internally.

track()

track(tracking);

Typically only used internally.

Parameters:

NameTypeRequiredDescription
trackingAnimatedNodeYesSee AnimatedNode.js
Edit this page
Last updated on
- + diff --git a/docs/0.62/animatedvalue/index.html b/docs/0.62/animatedvalue/index.html index 54023edf5cd..d541598c0dc 100644 --- a/docs/0.62/animatedvalue/index.html +++ b/docs/0.62/animatedvalue/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

AnimatedValue

Standard value for driving animations. One Animated.Value can drive multiple properties in a synchronized fashion, but can only be driven by one mechanism at a time. Using a new mechanism (e.g. starting a new animation, or calling setValue) will stop any previous ones.

Typically initialized with new Animated.Value(0);

See also Animated.

Methods

Reference

Methods

setValue()

setValue(value);

Directly set the value. This will stop any animations running on the value and update all the bound properties.

Parameters:

NameTypeRequiredDescription
valuenumberYesValue

setOffset()

setOffset(offset);

Sets an offset that is applied on top of whatever value is set, whether via setValue, an animation, or Animated.event. Useful for compensating things like the start of a pan gesture.

Parameters:

NameTypeRequiredDescription
offsetnumberYesOffset value

flattenOffset()

flattenOffset();

Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.

extractOffset()

extractOffset();

Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.

addListener()

addListener(callback);

Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.

Returns a string that serves as an identifier for the listener.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesThe callback function which will receive an object with a value key set to the new value.

removeListener()

removeListener(id);

Unregister a listener. The id param shall match the identifier previously returned by addListener().

Parameters:

NameTypeRequiredDescription
idstringYesId for the listener being removed.

removeAllListeners()

removeAllListeners();

Remove all registered listeners.

stopAnimation()

stopAnimation([callback]);

Stops any running animation or tracking. callback is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the final value.

resetAnimation()

resetAnimation([callback]);

Stops any animation and resets the value to its original.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the original value.

interpolate()

interpolate(config);

Interpolates the value before updating the property, e.g. mapping 0-1 to 0-10.

See AnimatedInterpolation.js

Parameters:

NameTypeRequiredDescription
configobjectYesSee below.

The config object is composed of the following keys:

  • inputRange: an array of numbers
  • outputRange: an array of numbers or strings
  • easing (optional): a function that returns a number, given an input number
  • extrapolate (optional): a string such as 'extend', 'identity', or 'clamp'
  • extrapolateLeft (optional): a string such as 'extend', 'identity', or 'clamp'
  • extrapolateRight (optional): a string such as 'extend', 'identity', or 'clamp'

animate()

animate(animation, callback);

Typically only used internally, but could be used by a custom Animation class.

Parameters:

NameTypeRequiredDescription
animationAnimationYesSee Animation.js.
callbackfunctionYesCallback function.

stopTracking()

stopTracking();

Typically only used internally.

track()

track(tracking);

Typically only used internally.

Parameters:

NameTypeRequiredDescription
trackingAnimatedNodeYesSee AnimatedNode.js
Edit this page
Last updated on
- + diff --git a/docs/0.62/animatedvaluexy.html b/docs/0.62/animatedvaluexy.html index 06eaff82f62..53426c0c77b 100644 --- a/docs/0.62/animatedvaluexy.html +++ b/docs/0.62/animatedvaluexy.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

AnimatedValueXY

2D Value for driving 2D animations, such as pan gestures. Almost identical API to normal Animated.Value, but multiplexed. Contains two regular Animated.Values under the hood.

See also Animated.

Example

class DraggableView extends React.Component {
constructor(props) {
super(props);
this.state = {
pan: new Animated.ValueXY() // inits to zero
};
this.state.panResponder = PanResponder.create({
onStartShouldSetPanResponder: () => true,
onPanResponderMove: Animated.event([
null,
{
dx: this.state.pan.x, // x,y are Animated.Value
dy: this.state.pan.y
}
]),
onPanResponderRelease: () => {
Animated.spring(
this.state.pan, // Auto-multiplexed
{ toValue: { x: 0, y: 0 } } // Back to zero
).start();
}
});
}
render() {
return (
<Animated.View
{...this.state.panResponder.panHandlers}
style={this.state.pan.getLayout()}>
{this.props.children}
</Animated.View>
);
}
}

Methods

Reference

Methods

setValue()

setValue(value);

Directly set the value. This will stop any animations running on the value and update all the bound properties.

Parameters:

NameTypeRequiredDescription
valuenumberYes

setOffset()

setOffset(offset);

Sets an offset that is applied on top of whatever value is set, whether via setValue, an animation, or Animated.event. Useful for compensating things like the start of a pan gesture.

Parameters:

NameTypeRequiredDescription
offsetnumberYes

flattenOffset()

flattenOffset();

Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.

extractOffset()

extractOffset();

Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.

addListener()

addListener(callback);

Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.

Returns a string that serves as an identifier for the listener.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesThe callback function which will receive an object with a value key set to the new value.

removeListener()

removeListener(id);

Unregister a listener. The id param shall match the identifier previously returned by addListener().

Parameters:

NameTypeRequiredDescription
idstringYesId for the listener being removed.

removeAllListeners()

removeAllListeners();

Remove all registered listeners.

stopAnimation()

stopAnimation([callback]);

Stops any running animation or tracking. callback is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the final value.

resetAnimation()

resetAnimation([callback]);

Stops any animation and resets the value to its original.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the original value.

getLayout()

getLayout();

Converts {x, y} into {left, top} for use in style, e.g.

style={this.state.anim.getLayout()}

getTranslateTransform()

getTranslateTransform();

Converts {x, y} into a useable translation transform, e.g.

style={{
transform: this.state.anim.getTranslateTransform()
}}
Edit this page
Last updated on
- + diff --git a/docs/0.62/animatedvaluexy/index.html b/docs/0.62/animatedvaluexy/index.html index 06eaff82f62..53426c0c77b 100644 --- a/docs/0.62/animatedvaluexy/index.html +++ b/docs/0.62/animatedvaluexy/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

AnimatedValueXY

2D Value for driving 2D animations, such as pan gestures. Almost identical API to normal Animated.Value, but multiplexed. Contains two regular Animated.Values under the hood.

See also Animated.

Example

class DraggableView extends React.Component {
constructor(props) {
super(props);
this.state = {
pan: new Animated.ValueXY() // inits to zero
};
this.state.panResponder = PanResponder.create({
onStartShouldSetPanResponder: () => true,
onPanResponderMove: Animated.event([
null,
{
dx: this.state.pan.x, // x,y are Animated.Value
dy: this.state.pan.y
}
]),
onPanResponderRelease: () => {
Animated.spring(
this.state.pan, // Auto-multiplexed
{ toValue: { x: 0, y: 0 } } // Back to zero
).start();
}
});
}
render() {
return (
<Animated.View
{...this.state.panResponder.panHandlers}
style={this.state.pan.getLayout()}>
{this.props.children}
</Animated.View>
);
}
}

Methods

Reference

Methods

setValue()

setValue(value);

Directly set the value. This will stop any animations running on the value and update all the bound properties.

Parameters:

NameTypeRequiredDescription
valuenumberYes

setOffset()

setOffset(offset);

Sets an offset that is applied on top of whatever value is set, whether via setValue, an animation, or Animated.event. Useful for compensating things like the start of a pan gesture.

Parameters:

NameTypeRequiredDescription
offsetnumberYes

flattenOffset()

flattenOffset();

Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.

extractOffset()

extractOffset();

Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.

addListener()

addListener(callback);

Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.

Returns a string that serves as an identifier for the listener.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesThe callback function which will receive an object with a value key set to the new value.

removeListener()

removeListener(id);

Unregister a listener. The id param shall match the identifier previously returned by addListener().

Parameters:

NameTypeRequiredDescription
idstringYesId for the listener being removed.

removeAllListeners()

removeAllListeners();

Remove all registered listeners.

stopAnimation()

stopAnimation([callback]);

Stops any running animation or tracking. callback is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the final value.

resetAnimation()

resetAnimation([callback]);

Stops any animation and resets the value to its original.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the original value.

getLayout()

getLayout();

Converts {x, y} into {left, top} for use in style, e.g.

style={this.state.anim.getLayout()}

getTranslateTransform()

getTranslateTransform();

Converts {x, y} into a useable translation transform, e.g.

style={{
transform: this.state.anim.getTranslateTransform()
}}
Edit this page
Last updated on
- + diff --git a/docs/0.62/animations.html b/docs/0.62/animations.html index a85ca6b5c61..973a71a0cd2 100644 --- a/docs/0.62/animations.html +++ b/docs/0.62/animations.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Animated.spring(a, {
toValue: 2
}).start();

Interpolation

Each property can be run through an interpolation first. An interpolation maps input ranges to output ranges, typically using a linear interpolation but also supports easing functions. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value.

A basic mapping to convert a 0-1 range to a 0-100 range would be:

value.interpolate({
inputRange: [0, 1],
outputRange: [0, 100]
});

For example, you may want to think about your Animated.Value as going from 0 to 1, but animate the position from 150px to 0px and the opacity from 0 to 1. This can be done by modifying style from the example above like so:

style={{
opacity: this.state.fadeAnim, // Binds directly
transform: [{
translateY: this.state.fadeAnim.interpolate({
inputRange: [0, 1],
outputRange: [150, 0] // 0 : 150, 0.5 : 75, 1 : 0
}),
}],
}}

interpolate() supports multiple range segments as well, which is handy for defining dead zones and other handy tricks. For example, to get a negation relationship at -300 that goes to 0 at -100, then back up to 1 at 0, and then back down to zero at 100 followed by a dead-zone that remains at 0 for everything beyond that, you could do:

value.interpolate({
inputRange: [-300, -100, 0, 100, 101],
outputRange: [300, 0, 1, 0, 0]
});

Which would map like so:

Input | Output
------|-------
-400| 450
-300| 300
-200| 150
-100| 0
-50| 0.5
0| 1
50| 0.5
100| 0
101| 0
200| 0

interpolate() also supports mapping to strings, allowing you to animate colors as well as values with units. For example, if you wanted to animate a rotation you could do:

value.interpolate({
inputRange: [0, 360],
outputRange: ['0deg', '360deg']
});

interpolate() also supports arbitrary easing functions, many of which are already implemented in the Easing module. interpolate() also has configurable behavior for extrapolating the outputRange. You can set the extrapolation by setting the extrapolate, extrapolateLeft, or extrapolateRight options. The default value is extend but you can use clamp to prevent the output value from exceeding outputRange.

Tracking dynamic values

Animated values can also track other values by setting the toValue of an animation to another animated value instead of a plain number. For example, a "Chat Heads" animation like the one used by Messenger on Android could be implemented with a spring() pinned on another animated value, or with timing() and a duration of 0 for rigid tracking. They can also be composed with interpolations:

Animated.spring(follower, { toValue: leader }).start();
Animated.timing(opacity, {
toValue: pan.x.interpolate({
inputRange: [0, 300],
outputRange: [1, 0]
})
}).start();

The leader and follower animated values would be implemented using Animated.ValueXY(). ValueXY is a handy way to deal with 2D interactions, such as panning or dragging. It is a basic wrapper that contains two Animated.Value instances and some helper functions that call through to them, making ValueXY a drop-in replacement for Value in many cases. It allows us to track both x and y values in the example above.

Tracking gestures

Gestures, like panning or scrolling, and other events can map directly to animated values using Animated.event. This is done with a structured map syntax so that values can be extracted from complex event objects. The first level is an array to allow mapping across multiple args, and that array contains nested objects.

For example, when working with horizontal scrolling gestures, you would do the following in order to map event.nativeEvent.contentOffset.x to scrollX (an Animated.Value):

onScroll={Animated.event(
// scrollX = e.nativeEvent.contentOffset.x
[{ nativeEvent: {
contentOffset: {
x: scrollX
}
}
}]
)}

The following example implements a horizontal scrolling carousel where the scroll position indicators are animated using the Animated.event used in the ScrollView

ScrollView with Animated Event Example

When using PanResponder, you could use the following code to extract the x and y positions from gestureState.dx and gestureState.dy. We use a null in the first position of the array, as we are only interested in the second argument passed to the PanResponder handler, which is the gestureState.

onPanResponderMove={Animated.event(
[null, // ignore the native event
// extract dx and dy from gestureState
// like 'pan.x = gestureState.dx, pan.y = gestureState.dy'
{dx: pan.x, dy: pan.y}
])}

PanResponder with Animated Event Example

Responding to the current animation value

You may notice that there is no clear way to read the current value while animating. This is because the value may only be known in the native runtime due to optimizations. If you need to run JavaScript in response to the current value, there are two approaches:

Animated is designed to be fully serializable so that animations can be run in a high performance way, independent of the normal JavaScript event loop. This does influence the API, so keep that in mind when it seems a little trickier to do something compared to a fully synchronous system. Check out Animated.Value.addListener as a way to work around some of these limitations, but use it sparingly since it might have performance implications in the future.

Using the native driver

The Animated API is designed to be serializable. By using the native driver, we send everything about the animation to native before starting the animation, allowing native code to perform the animation on the UI thread without having to go through the bridge on every frame. Once the animation has started, the JS thread can be blocked without affecting the animation.

Using the native driver for normal animations is straightforward. You can add useNativeDriver: true to the animation config when starting it.

Animated.timing(this.state.animatedValue, {
toValue: 1,
duration: 500,
useNativeDriver: true // <-- Add this
}).start();

Animated values are only compatible with one driver so if you use native driver when starting an animation on a value, make sure every animation on that value also uses the native driver.

The native driver also works with Animated.event. This is especially useful for animations that follow the scroll position as without the native driver, the animation will always run a frame behind the gesture due to the async nature of React Native.

<Animated.ScrollView // <-- Use the Animated ScrollView wrapper
scrollEventThrottle={1} // <-- Use 1 here to make sure no events are ever missed
onScroll={Animated.event(
[
{
nativeEvent: {
contentOffset: { y: this.state.animatedValue }
}
}
],
{ useNativeDriver: true } // <-- Add this
)}>
{content}
</Animated.ScrollView>

You can see the native driver in action by running the RNTester app, then loading the Native Animated Example. You can also take a look at the source code to learn how these examples were produced.

Caveats

Not everything you can do with Animated is currently supported by the native driver. The main limitation is that you can only animate non-layout properties: things like transform and opacity will work, but Flexbox and position properties will not. When using Animated.event, it will only work with direct events and not bubbling events. This means it does not work with PanResponder but does work with things like ScrollView#onScroll.

When an animation is running, it can prevent VirtualizedList components from rendering more rows. If you need to run a long or looping animation while the user is scrolling through a list, you can use isInteraction: false in your animation's config to prevent this issue.

Bear in mind

While using transform styles such as rotateY, rotateX, and others ensure the transform style perspective is in place. At this time some animations may not render on Android without it. Example below.

<Animated.View
style={{
transform: [
{ scale: this.state.scale },
{ rotateY: this.state.rotateY },
{ perspective: 1000 } // without this line this Animation will not render on Android while working fine on iOS
]
}}
/>

Additional examples

The RNTester app has various examples of Animated in use:

LayoutAnimation API

LayoutAnimation allows you to globally configure create and update animations that will be used for all views in the next render/layout cycle. This is useful for doing Flexbox layout updates without bothering to measure or calculate specific properties in order to animate them directly, and is especially useful when layout changes may affect ancestors, for example a "see more" expansion that also increases the size of the parent and pushes down the row below which would otherwise require explicit coordination between the components in order to animate them all in sync.

Note that although LayoutAnimation is very powerful and can be quite useful, it provides much less control than Animated and other animation libraries, so you may need to use another approach if you can't get LayoutAnimation to do what you want.

Note that in order to get this to work on Android you need to set the following flags via UIManager:

UIManager.setLayoutAnimationEnabledExperimental &&
UIManager.setLayoutAnimationEnabledExperimental(true);

This example uses a preset value, you can customize the animations as you need, see LayoutAnimation.js for more information.

Additional notes

requestAnimationFrame

requestAnimationFrame is a polyfill from the browser that you might be familiar with. It accepts a function as its only argument and calls that function before the next repaint. It is an essential building block for animations that underlies all of the JavaScript-based animation APIs. In general, you shouldn't need to call this yourself - the animation APIs will manage frame updates for you.

setNativeProps

As mentioned in the Direct Manipulation section, setNativeProps allows us to modify properties of native-backed components (components that are actually backed by native views, unlike composite components) directly, without having to setState and re-render the component hierarchy.

We could use this in the Rebound example to update the scale - this might be helpful if the component that we are updating is deeply nested and hasn't been optimized with shouldComponentUpdate.

If you find your animations with dropping frames (performing below 60 frames per second), look into using setNativeProps or shouldComponentUpdate to optimize them. Or you could run the animations on the UI thread rather than the JavaScript thread with the useNativeDriver 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.

Edit this page
Last updated on
- + diff --git a/docs/0.62/animations/index.html b/docs/0.62/animations/index.html index a85ca6b5c61..973a71a0cd2 100644 --- a/docs/0.62/animations/index.html +++ b/docs/0.62/animations/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Animated.spring(a, {
toValue: 2
}).start();

Interpolation

Each property can be run through an interpolation first. An interpolation maps input ranges to output ranges, typically using a linear interpolation but also supports easing functions. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value.

A basic mapping to convert a 0-1 range to a 0-100 range would be:

value.interpolate({
inputRange: [0, 1],
outputRange: [0, 100]
});

For example, you may want to think about your Animated.Value as going from 0 to 1, but animate the position from 150px to 0px and the opacity from 0 to 1. This can be done by modifying style from the example above like so:

style={{
opacity: this.state.fadeAnim, // Binds directly
transform: [{
translateY: this.state.fadeAnim.interpolate({
inputRange: [0, 1],
outputRange: [150, 0] // 0 : 150, 0.5 : 75, 1 : 0
}),
}],
}}

interpolate() supports multiple range segments as well, which is handy for defining dead zones and other handy tricks. For example, to get a negation relationship at -300 that goes to 0 at -100, then back up to 1 at 0, and then back down to zero at 100 followed by a dead-zone that remains at 0 for everything beyond that, you could do:

value.interpolate({
inputRange: [-300, -100, 0, 100, 101],
outputRange: [300, 0, 1, 0, 0]
});

Which would map like so:

Input | Output
------|-------
-400| 450
-300| 300
-200| 150
-100| 0
-50| 0.5
0| 1
50| 0.5
100| 0
101| 0
200| 0

interpolate() also supports mapping to strings, allowing you to animate colors as well as values with units. For example, if you wanted to animate a rotation you could do:

value.interpolate({
inputRange: [0, 360],
outputRange: ['0deg', '360deg']
});

interpolate() also supports arbitrary easing functions, many of which are already implemented in the Easing module. interpolate() also has configurable behavior for extrapolating the outputRange. You can set the extrapolation by setting the extrapolate, extrapolateLeft, or extrapolateRight options. The default value is extend but you can use clamp to prevent the output value from exceeding outputRange.

Tracking dynamic values

Animated values can also track other values by setting the toValue of an animation to another animated value instead of a plain number. For example, a "Chat Heads" animation like the one used by Messenger on Android could be implemented with a spring() pinned on another animated value, or with timing() and a duration of 0 for rigid tracking. They can also be composed with interpolations:

Animated.spring(follower, { toValue: leader }).start();
Animated.timing(opacity, {
toValue: pan.x.interpolate({
inputRange: [0, 300],
outputRange: [1, 0]
})
}).start();

The leader and follower animated values would be implemented using Animated.ValueXY(). ValueXY is a handy way to deal with 2D interactions, such as panning or dragging. It is a basic wrapper that contains two Animated.Value instances and some helper functions that call through to them, making ValueXY a drop-in replacement for Value in many cases. It allows us to track both x and y values in the example above.

Tracking gestures

Gestures, like panning or scrolling, and other events can map directly to animated values using Animated.event. This is done with a structured map syntax so that values can be extracted from complex event objects. The first level is an array to allow mapping across multiple args, and that array contains nested objects.

For example, when working with horizontal scrolling gestures, you would do the following in order to map event.nativeEvent.contentOffset.x to scrollX (an Animated.Value):

onScroll={Animated.event(
// scrollX = e.nativeEvent.contentOffset.x
[{ nativeEvent: {
contentOffset: {
x: scrollX
}
}
}]
)}

The following example implements a horizontal scrolling carousel where the scroll position indicators are animated using the Animated.event used in the ScrollView

ScrollView with Animated Event Example

When using PanResponder, you could use the following code to extract the x and y positions from gestureState.dx and gestureState.dy. We use a null in the first position of the array, as we are only interested in the second argument passed to the PanResponder handler, which is the gestureState.

onPanResponderMove={Animated.event(
[null, // ignore the native event
// extract dx and dy from gestureState
// like 'pan.x = gestureState.dx, pan.y = gestureState.dy'
{dx: pan.x, dy: pan.y}
])}

PanResponder with Animated Event Example

Responding to the current animation value

You may notice that there is no clear way to read the current value while animating. This is because the value may only be known in the native runtime due to optimizations. If you need to run JavaScript in response to the current value, there are two approaches:

Animated is designed to be fully serializable so that animations can be run in a high performance way, independent of the normal JavaScript event loop. This does influence the API, so keep that in mind when it seems a little trickier to do something compared to a fully synchronous system. Check out Animated.Value.addListener as a way to work around some of these limitations, but use it sparingly since it might have performance implications in the future.

Using the native driver

The Animated API is designed to be serializable. By using the native driver, we send everything about the animation to native before starting the animation, allowing native code to perform the animation on the UI thread without having to go through the bridge on every frame. Once the animation has started, the JS thread can be blocked without affecting the animation.

Using the native driver for normal animations is straightforward. You can add useNativeDriver: true to the animation config when starting it.

Animated.timing(this.state.animatedValue, {
toValue: 1,
duration: 500,
useNativeDriver: true // <-- Add this
}).start();

Animated values are only compatible with one driver so if you use native driver when starting an animation on a value, make sure every animation on that value also uses the native driver.

The native driver also works with Animated.event. This is especially useful for animations that follow the scroll position as without the native driver, the animation will always run a frame behind the gesture due to the async nature of React Native.

<Animated.ScrollView // <-- Use the Animated ScrollView wrapper
scrollEventThrottle={1} // <-- Use 1 here to make sure no events are ever missed
onScroll={Animated.event(
[
{
nativeEvent: {
contentOffset: { y: this.state.animatedValue }
}
}
],
{ useNativeDriver: true } // <-- Add this
)}>
{content}
</Animated.ScrollView>

You can see the native driver in action by running the RNTester app, then loading the Native Animated Example. You can also take a look at the source code to learn how these examples were produced.

Caveats

Not everything you can do with Animated is currently supported by the native driver. The main limitation is that you can only animate non-layout properties: things like transform and opacity will work, but Flexbox and position properties will not. When using Animated.event, it will only work with direct events and not bubbling events. This means it does not work with PanResponder but does work with things like ScrollView#onScroll.

When an animation is running, it can prevent VirtualizedList components from rendering more rows. If you need to run a long or looping animation while the user is scrolling through a list, you can use isInteraction: false in your animation's config to prevent this issue.

Bear in mind

While using transform styles such as rotateY, rotateX, and others ensure the transform style perspective is in place. At this time some animations may not render on Android without it. Example below.

<Animated.View
style={{
transform: [
{ scale: this.state.scale },
{ rotateY: this.state.rotateY },
{ perspective: 1000 } // without this line this Animation will not render on Android while working fine on iOS
]
}}
/>

Additional examples

The RNTester app has various examples of Animated in use:

LayoutAnimation API

LayoutAnimation allows you to globally configure create and update animations that will be used for all views in the next render/layout cycle. This is useful for doing Flexbox layout updates without bothering to measure or calculate specific properties in order to animate them directly, and is especially useful when layout changes may affect ancestors, for example a "see more" expansion that also increases the size of the parent and pushes down the row below which would otherwise require explicit coordination between the components in order to animate them all in sync.

Note that although LayoutAnimation is very powerful and can be quite useful, it provides much less control than Animated and other animation libraries, so you may need to use another approach if you can't get LayoutAnimation to do what you want.

Note that in order to get this to work on Android you need to set the following flags via UIManager:

UIManager.setLayoutAnimationEnabledExperimental &&
UIManager.setLayoutAnimationEnabledExperimental(true);

This example uses a preset value, you can customize the animations as you need, see LayoutAnimation.js for more information.

Additional notes

requestAnimationFrame

requestAnimationFrame is a polyfill from the browser that you might be familiar with. It accepts a function as its only argument and calls that function before the next repaint. It is an essential building block for animations that underlies all of the JavaScript-based animation APIs. In general, you shouldn't need to call this yourself - the animation APIs will manage frame updates for you.

setNativeProps

As mentioned in the Direct Manipulation section, setNativeProps allows us to modify properties of native-backed components (components that are actually backed by native views, unlike composite components) directly, without having to setState and re-render the component hierarchy.

We could use this in the Rebound example to update the scale - this might be helpful if the component that we are updating is deeply nested and hasn't been optimized with shouldComponentUpdate.

If you find your animations with dropping frames (performing below 60 frames per second), look into using setNativeProps or shouldComponentUpdate to optimize them. Or you could run the animations on the UI thread rather than the JavaScript thread with the useNativeDriver 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.

Edit this page
Last updated on
- + diff --git a/docs/0.62/app-extensions.html b/docs/0.62/app-extensions.html index ef7da6d66bf..6c7dd2b05de 100644 --- a/docs/0.62/app-extensions.html +++ b/docs/0.62/app-extensions.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

App Extensions

App extensions let you provide custom functionality and content outside of your main app. There are different types of app extensions on iOS, and they are all covered in the App Extension Programming Guide. In this guide, we'll briefly cover how you may take advantage of app extensions on iOS.

Memory use in extensions

As these extensions are loaded outside of the regular app sandbox, it's highly likely that several of these app extensions will be loaded simultaneously. As you might expect, these extensions have small memory usage limits. Keep these in mind when developing your app extensions. It's always highly recommended to test your application on an actual device, and more so when developing app extensions: too frequently, developers find that their extension works fine in the iOS Simulator, only to get user reports that their extension is not loading on actual devices.

We highly recommend that you watch Conrad Kramer's talk on Memory Use in Extensions to learn more about this topic.

Today widget

The memory limit of a Today widget is 16 MB. As it happens, Today widget implementations using React Native may work unreliably because the memory usage tends to be too high. You can tell if your Today widget is exceeding the memory limit if it yields the message 'Unable to Load':

Always make sure to test your app extensions in a real device, but be aware that this may not be sufficient, especially when dealing with Today widgets. Debug-configured builds are more likely to exceed the memory limits, while release-configured builds don't fail right away. We highly recommend that you use Xcode's Instruments to analyze your real world memory usage, as it's very likely that your release-configured build is very close to the 16 MB limit. In situations like these, you can quickly go over the 16 MB limit by performing common operations, such as fetching data from an API.

To experiment with the limits of React Native Today widget implementations, try extending the example project in react-native-today-widget.

Other app extensions

Other types of app extensions have greater memory limits than the Today widget. For instance, Custom Keyboard extensions are limited to 48 MB, and Share extensions are limited to 120 MB. Implementing such app extensions with React Native is more viable. One proof of concept example is react-native-ios-share-extension.

Edit this page
Last updated on
- + diff --git a/docs/0.62/app-extensions/index.html b/docs/0.62/app-extensions/index.html index ef7da6d66bf..6c7dd2b05de 100644 --- a/docs/0.62/app-extensions/index.html +++ b/docs/0.62/app-extensions/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

App Extensions

App extensions let you provide custom functionality and content outside of your main app. There are different types of app extensions on iOS, and they are all covered in the App Extension Programming Guide. In this guide, we'll briefly cover how you may take advantage of app extensions on iOS.

Memory use in extensions

As these extensions are loaded outside of the regular app sandbox, it's highly likely that several of these app extensions will be loaded simultaneously. As you might expect, these extensions have small memory usage limits. Keep these in mind when developing your app extensions. It's always highly recommended to test your application on an actual device, and more so when developing app extensions: too frequently, developers find that their extension works fine in the iOS Simulator, only to get user reports that their extension is not loading on actual devices.

We highly recommend that you watch Conrad Kramer's talk on Memory Use in Extensions to learn more about this topic.

Today widget

The memory limit of a Today widget is 16 MB. As it happens, Today widget implementations using React Native may work unreliably because the memory usage tends to be too high. You can tell if your Today widget is exceeding the memory limit if it yields the message 'Unable to Load':

Always make sure to test your app extensions in a real device, but be aware that this may not be sufficient, especially when dealing with Today widgets. Debug-configured builds are more likely to exceed the memory limits, while release-configured builds don't fail right away. We highly recommend that you use Xcode's Instruments to analyze your real world memory usage, as it's very likely that your release-configured build is very close to the 16 MB limit. In situations like these, you can quickly go over the 16 MB limit by performing common operations, such as fetching data from an API.

To experiment with the limits of React Native Today widget implementations, try extending the example project in react-native-today-widget.

Other app extensions

Other types of app extensions have greater memory limits than the Today widget. For instance, Custom Keyboard extensions are limited to 48 MB, and Share extensions are limited to 120 MB. Implementing such app extensions with React Native is more viable. One proof of concept example is react-native-ios-share-extension.

Edit this page
Last updated on
- + diff --git a/docs/0.62/appearance.html b/docs/0.62/appearance.html index fee3bd1c83c..9b8d8ffd460 100644 --- a/docs/0.62/appearance.html +++ b/docs/0.62/appearance.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Appearance

import { Appearance } from 'react-native';

The Appearance module exposes information about the user's appearance preferences, such as their preferred color scheme (light or dark).

Developer notes

The Appearance API is inspired by the Media Queries draft from the W3C. The color scheme preference is modeled after the prefers-color-scheme CSS media feature.

Example

You can use the Appearance module to determine if the user prefers a dark color scheme:

const colorScheme = Appearance.getColorScheme();
if (colorScheme === 'dark') {
// Use dark color scheme
}

Although the color scheme is available immediately, this may change (e.g. scheduled color scheme change at sunrise or sunset). Any rendering logic or styles that depend on the user preferred color scheme should try to call this function on every render, rather than caching the value. For example, you may use the useColorScheme React hook as it provides and subscribes to color scheme updates, or you may use inline styles rather than setting a value in a StyleSheet.

Reference

Methods

getColorScheme()

static getColorScheme()

Indicates the current user preferred color scheme. The value may be updated later, either through direct user action (e.g. theme selection in device settings) or on a schedule (e.g. light and dark themes that follow the day/night cycle).

Supported color schemes:

  • light: The user prefers a light color theme.
  • dark: The user prefers a dark color theme.
  • null: The user has not indicated a preferred color theme.

See also: useColorScheme hook.

Note: getColorScheme() will always return light when debugging with Chrome.

addChangeListener()

static addChangeListener(listener)

Add an event handler that is fired when appearance preferences change.

removeChangeListener()

static removeChangeListener(listener)

Remove an event handler.

Edit this page
Last updated on
- + diff --git a/docs/0.62/appearance/index.html b/docs/0.62/appearance/index.html index fee3bd1c83c..9b8d8ffd460 100644 --- a/docs/0.62/appearance/index.html +++ b/docs/0.62/appearance/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Appearance

import { Appearance } from 'react-native';

The Appearance module exposes information about the user's appearance preferences, such as their preferred color scheme (light or dark).

Developer notes

The Appearance API is inspired by the Media Queries draft from the W3C. The color scheme preference is modeled after the prefers-color-scheme CSS media feature.

Example

You can use the Appearance module to determine if the user prefers a dark color scheme:

const colorScheme = Appearance.getColorScheme();
if (colorScheme === 'dark') {
// Use dark color scheme
}

Although the color scheme is available immediately, this may change (e.g. scheduled color scheme change at sunrise or sunset). Any rendering logic or styles that depend on the user preferred color scheme should try to call this function on every render, rather than caching the value. For example, you may use the useColorScheme React hook as it provides and subscribes to color scheme updates, or you may use inline styles rather than setting a value in a StyleSheet.

Reference

Methods

getColorScheme()

static getColorScheme()

Indicates the current user preferred color scheme. The value may be updated later, either through direct user action (e.g. theme selection in device settings) or on a schedule (e.g. light and dark themes that follow the day/night cycle).

Supported color schemes:

  • light: The user prefers a light color theme.
  • dark: The user prefers a dark color theme.
  • null: The user has not indicated a preferred color theme.

See also: useColorScheme hook.

Note: getColorScheme() will always return light when debugging with Chrome.

addChangeListener()

static addChangeListener(listener)

Add an event handler that is fired when appearance preferences change.

removeChangeListener()

static removeChangeListener(listener)

Remove an event handler.

Edit this page
Last updated on
- + diff --git a/docs/0.62/appregistry.html b/docs/0.62/appregistry.html index ab0d1bc1ccc..a5c73664ef8 100644 --- a/docs/0.62/appregistry.html +++ b/docs/0.62/appregistry.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
AppRegistry.registerComponent('Appname', () => App);

To "stop" an application when a view should be destroyed, call AppRegistry.unmountApplicationComponentAtRootTag with the tag that was passed into runApplication. These should always be used as a pair.

AppRegistry should be required early in the require sequence to make sure the JS execution environment is setup before other modules are required.

Reference

Methods

setWrapperComponentProvider()

static setWrapperComponentProvider(provider)

Parameters:

NameTypeRequired
providerComponentProvideryes

enableArchitectureIndicator()

static enableArchitectureIndicator(enabled)

Parameters:

NameTypeRequired
enabledbooleanyes

registerConfig()

static registerConfig([config])

Parameters:

NameTypeRequiredDescription
configAppConfigyesSee below.

Valid AppConfig keys are:

registerComponent()

static registerComponent(appKey, componentProvider, section?)

Parameters:

NameTypeRequired
appKeystringyes
componentProviderComponentProvideryes
sectionbooleanno

registerRunnable()

static registerRunnable(appKey, run)

Parameters:

NameTypeRequired
appKeystringyes
runFunctionyes

registerSection()

static registerSection(appKey, component)

Parameters:

NameTypeRequired
appKeystringyes
componentComponentProvideryes

getAppKeys()

static getAppKeys()

Returns an Array of AppKeys

getSectionKeys()

static getSectionKeys()

Returns an Array of SectionKeys

getSections()

static getSections()

Returns all Runnables which is an object with key of AppKeys and value of type of Runnable which consist of:

getRunnable()

static getRunnable(appKey)

Returns a Runnable object which consist of:

getRegistry()

static getRegistry()

Returns a type Registry which consist of:

setComponentProviderInstrumentationHook()

static setComponentProviderInstrumentationHook(hook)

Parameters:

NameTypeRequiredDescription
hookFunctionyesSee below.

A valid hook accepts the following as arguments:

The hook function returns a React Component

runApplication()

static runApplication(appKey, appParameters)

Loads the JavaScript bundle and runs the app.

Parameters:

NameTypeRequired
appKeystringyes
appParametersanyyes

unmountApplicationComponentAtRootTag()

static unmountApplicationComponentAtRootTag(rootTag)

Stops an application when a view should be destroyed.

Parameters:

NameTypeRequired
rootTagnumberyes

registerHeadlessTask()

static registerHeadlessTask(taskKey, taskProvider)

Register a headless task. A headless task is a bit of code that runs without a UI. @param taskKey the key associated with this task @param taskProvider a promise returning function that takes some data passed from the native side as the only argument; when the promise is resolved or rejected the native side is notified of this event and it may decide to destroy the JS context.

This is a way to run tasks in JavaScript while your app is in the background. It can be used, for example, to sync fresh data, handle push notifications, or play music.

Parameters:

NameTypeRequiredDescription
taskKeyStringyesSee below.
taskProviderTaskProvideryesSee below.

registerCancellableHeadlessTask()

static registerCancellableHeadlessTask(taskKey, taskProvider, taskCancelProvider)

Register a headless task which can be cancelled. A headless task is a bit of code that runs without a UI. @param taskKey the key associated with this task @param taskProvider a promise returning function that takes some data passed from the native side as the only argument; when the promise is resolved or rejected the native side is notified of this event and it may decide to destroy the JS context. @param taskCancelProvider a void returning function that takes no arguments; when a cancellation is requested, the function being executed by taskProvider should wrap up and return ASAP.

Parameters:

NameTypeRequiredDescription
taskKeyStringyesSee below.
taskProviderTaskProvideryesSee below.
taskCancelProviderTaskCancelProvideryesSee below.

startHeadlessTask()

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

Parameters:

NameTypeRequired
taskIdnumberyes
taskKeystringyes
dataanyyes

cancelHeadlessTask()

static cancelHeadlessTask(taskId, taskKey)

Only called from native code. Cancels a headless task.

@param taskId the native id for this task instance that was used when startHeadlessTask was called @param taskKey the key for the task that was used when startHeadlessTask was called

Parameters:

NameTypeRequired
taskIdnumberyes
taskKeystringyes
Edit this page
Last updated on
- + diff --git a/docs/0.62/appregistry/index.html b/docs/0.62/appregistry/index.html index ab0d1bc1ccc..a5c73664ef8 100644 --- a/docs/0.62/appregistry/index.html +++ b/docs/0.62/appregistry/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
AppRegistry.registerComponent('Appname', () => App);

To "stop" an application when a view should be destroyed, call AppRegistry.unmountApplicationComponentAtRootTag with the tag that was passed into runApplication. These should always be used as a pair.

AppRegistry should be required early in the require sequence to make sure the JS execution environment is setup before other modules are required.

Reference

Methods

setWrapperComponentProvider()

static setWrapperComponentProvider(provider)

Parameters:

NameTypeRequired
providerComponentProvideryes

enableArchitectureIndicator()

static enableArchitectureIndicator(enabled)

Parameters:

NameTypeRequired
enabledbooleanyes

registerConfig()

static registerConfig([config])

Parameters:

NameTypeRequiredDescription
configAppConfigyesSee below.

Valid AppConfig keys are:

registerComponent()

static registerComponent(appKey, componentProvider, section?)

Parameters:

NameTypeRequired
appKeystringyes
componentProviderComponentProvideryes
sectionbooleanno

registerRunnable()

static registerRunnable(appKey, run)

Parameters:

NameTypeRequired
appKeystringyes
runFunctionyes

registerSection()

static registerSection(appKey, component)

Parameters:

NameTypeRequired
appKeystringyes
componentComponentProvideryes

getAppKeys()

static getAppKeys()

Returns an Array of AppKeys

getSectionKeys()

static getSectionKeys()

Returns an Array of SectionKeys

getSections()

static getSections()

Returns all Runnables which is an object with key of AppKeys and value of type of Runnable which consist of:

getRunnable()

static getRunnable(appKey)

Returns a Runnable object which consist of:

getRegistry()

static getRegistry()

Returns a type Registry which consist of:

setComponentProviderInstrumentationHook()

static setComponentProviderInstrumentationHook(hook)

Parameters:

NameTypeRequiredDescription
hookFunctionyesSee below.

A valid hook accepts the following as arguments:

The hook function returns a React Component

runApplication()

static runApplication(appKey, appParameters)

Loads the JavaScript bundle and runs the app.

Parameters:

NameTypeRequired
appKeystringyes
appParametersanyyes

unmountApplicationComponentAtRootTag()

static unmountApplicationComponentAtRootTag(rootTag)

Stops an application when a view should be destroyed.

Parameters:

NameTypeRequired
rootTagnumberyes

registerHeadlessTask()

static registerHeadlessTask(taskKey, taskProvider)

Register a headless task. A headless task is a bit of code that runs without a UI. @param taskKey the key associated with this task @param taskProvider a promise returning function that takes some data passed from the native side as the only argument; when the promise is resolved or rejected the native side is notified of this event and it may decide to destroy the JS context.

This is a way to run tasks in JavaScript while your app is in the background. It can be used, for example, to sync fresh data, handle push notifications, or play music.

Parameters:

NameTypeRequiredDescription
taskKeyStringyesSee below.
taskProviderTaskProvideryesSee below.

registerCancellableHeadlessTask()

static registerCancellableHeadlessTask(taskKey, taskProvider, taskCancelProvider)

Register a headless task which can be cancelled. A headless task is a bit of code that runs without a UI. @param taskKey the key associated with this task @param taskProvider a promise returning function that takes some data passed from the native side as the only argument; when the promise is resolved or rejected the native side is notified of this event and it may decide to destroy the JS context. @param taskCancelProvider a void returning function that takes no arguments; when a cancellation is requested, the function being executed by taskProvider should wrap up and return ASAP.

Parameters:

NameTypeRequiredDescription
taskKeyStringyesSee below.
taskProviderTaskProvideryesSee below.
taskCancelProviderTaskCancelProvideryesSee below.

startHeadlessTask()

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

Parameters:

NameTypeRequired
taskIdnumberyes
taskKeystringyes
dataanyyes

cancelHeadlessTask()

static cancelHeadlessTask(taskId, taskKey)

Only called from native code. Cancels a headless task.

@param taskId the native id for this task instance that was used when startHeadlessTask was called @param taskKey the key for the task that was used when startHeadlessTask was called

Parameters:

NameTypeRequired
taskIdnumberyes
taskKeystringyes
Edit this page
Last updated on
- + diff --git a/docs/0.62/appstate.html b/docs/0.62/appstate.html index 9a8fa1353fc..d1c84316828 100644 --- a/docs/0.62/appstate.html +++ b/docs/0.62/appstate.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

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 foreground
  • background - The app is running in the background. The user is either:
    • in another app
    • on the home screen
    • [Android] on another Activity (even if it was launched by your app)
  • [iOS] inactive - This is a state that occurs when transitioning between foreground & background, and during periods of inactivity such as entering the Multitasking view or in the event of an incoming call

For more information, see Apple's documentation

Basic Usage

To see the current state, you can check AppState.currentState, which will be kept up-to-date. However, currentState will be null at launch while AppState retrieves it over the bridge.

This example will only ever appear to say "Current state is: active" because the app is only visible to the user when in the active state, and the null state will happen only momentarily.

Reference

Events

change

This event is received when the app state has changed. The listener is called with one of the current app state values.

memoryWarning

This event is used in the need of throwing memory warning or releasing it.

focus

[Android only] Received when the app gains focus (the user is interacting with the app).

blur

[Android only] Received when the user is not actively interacting with the app. Useful in situations when the user pulls down the notification drawer. AppState won't change but the blur event will get fired.

Methods

addEventListener()

addEventListener(type, handler);

Add a handler to AppState changes by listening to the change event type and providing the handler

TODO: now that AppState is a subclass of NativeEventEmitter, we could deprecate addEventListener and removeEventListener and use addListener and listener.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()

removeEventListener(type, handler);

Remove a handler by passing the change event type and the handler

Properties

currentState

AppState.currentState;
Edit this page
Last updated on
- + diff --git a/docs/0.62/appstate/index.html b/docs/0.62/appstate/index.html index 9a8fa1353fc..d1c84316828 100644 --- a/docs/0.62/appstate/index.html +++ b/docs/0.62/appstate/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

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 foreground
  • background - The app is running in the background. The user is either:
    • in another app
    • on the home screen
    • [Android] on another Activity (even if it was launched by your app)
  • [iOS] inactive - This is a state that occurs when transitioning between foreground & background, and during periods of inactivity such as entering the Multitasking view or in the event of an incoming call

For more information, see Apple's documentation

Basic Usage

To see the current state, you can check AppState.currentState, which will be kept up-to-date. However, currentState will be null at launch while AppState retrieves it over the bridge.

This example will only ever appear to say "Current state is: active" because the app is only visible to the user when in the active state, and the null state will happen only momentarily.

Reference

Events

change

This event is received when the app state has changed. The listener is called with one of the current app state values.

memoryWarning

This event is used in the need of throwing memory warning or releasing it.

focus

[Android only] Received when the app gains focus (the user is interacting with the app).

blur

[Android only] Received when the user is not actively interacting with the app. Useful in situations when the user pulls down the notification drawer. AppState won't change but the blur event will get fired.

Methods

addEventListener()

addEventListener(type, handler);

Add a handler to AppState changes by listening to the change event type and providing the handler

TODO: now that AppState is a subclass of NativeEventEmitter, we could deprecate addEventListener and removeEventListener and use addListener and listener.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()

removeEventListener(type, handler);

Remove a handler by passing the change event type and the handler

Properties

currentState

AppState.currentState;
Edit this page
Last updated on
- + diff --git a/docs/0.62/asyncstorage.html b/docs/0.62/asyncstorage.html index 35e389d815e..18d0f9b0b66 100644 --- a/docs/0.62/asyncstorage.html +++ b/docs/0.62/asyncstorage.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@
// 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"}}
Edit this page
Last updated on
- + diff --git a/docs/0.62/asyncstorage/index.html b/docs/0.62/asyncstorage/index.html index 35e389d815e..18d0f9b0b66 100644 --- a/docs/0.62/asyncstorage/index.html +++ b/docs/0.62/asyncstorage/index.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@
// 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"}}
Edit this page
Last updated on
- + diff --git a/docs/0.62/backandroid.html b/docs/0.62/backandroid.html index badba751194..3f66ffe81c0 100644 --- a/docs/0.62/backandroid.html +++ b/docs/0.62/backandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

BackAndroid

Deprecated. Use BackHandler instead.

Methods

Reference

Methods

exitApp()

static exitApp()

addEventListener()

static addEventListener(eventName, handler)

removeEventListener()

static removeEventListener(eventName, handler)
Edit this page
Last updated on
- + diff --git a/docs/0.62/backandroid/index.html b/docs/0.62/backandroid/index.html index badba751194..3f66ffe81c0 100644 --- a/docs/0.62/backandroid/index.html +++ b/docs/0.62/backandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

BackAndroid

Deprecated. Use BackHandler instead.

Methods

Reference

Methods

exitApp()

static exitApp()

addEventListener()

static addEventListener(eventName, handler)

removeEventListener()

static removeEventListener(eventName, handler)
Edit this page
Last updated on
- + diff --git a/docs/0.62/backhandler.html b/docs/0.62/backhandler.html index 59bd2baa052..d50a8a7d508 100644 --- a/docs/0.62/backhandler.html +++ b/docs/0.62/backhandler.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
if (!this.onMainScreen()) {
this.goBack();
/**
* When true is returned the event will not be bubbled up
* & no other back action will execute
*/
return true;
}
/**
* Returning false will let the event to bubble up & let other event listeners
* or the system's default back action to be executed.
*/
return false;
});

Example

The following example implements a scenario where you confirm if the user wants to exit the app:

BackHandler.addEventListener creates an event listener & returns a NativeEventSubscription object which should be cleared using NativeEventSubscription.remove method.

Additionally BackHandler.removeEventListener can also be used to clear the event listener. Ensure the callback has the reference to the same function used in the addEventListener call as shown the following example ﹣

Usage with React Navigation

If you are using React Navigation to navigate across different screens, you can follow their guide on Custom Android back button behaviour

Backhandler hook

React Native Hooks has a nice useBackHandler hook which will simplify the process of setting up event listeners.

Reference

Methods

addEventListener()

static addEventListener(eventName, handler)

exitApp()

static exitApp()

removeEventListener()

static removeEventListener(eventName, handler)
Edit this page
Last updated on
- + diff --git a/docs/0.62/backhandler/index.html b/docs/0.62/backhandler/index.html index 59bd2baa052..d50a8a7d508 100644 --- a/docs/0.62/backhandler/index.html +++ b/docs/0.62/backhandler/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
if (!this.onMainScreen()) {
this.goBack();
/**
* When true is returned the event will not be bubbled up
* & no other back action will execute
*/
return true;
}
/**
* Returning false will let the event to bubble up & let other event listeners
* or the system's default back action to be executed.
*/
return false;
});

Example

The following example implements a scenario where you confirm if the user wants to exit the app:

BackHandler.addEventListener creates an event listener & returns a NativeEventSubscription object which should be cleared using NativeEventSubscription.remove method.

Additionally BackHandler.removeEventListener can also be used to clear the event listener. Ensure the callback has the reference to the same function used in the addEventListener call as shown the following example ﹣

Usage with React Navigation

If you are using React Navigation to navigate across different screens, you can follow their guide on Custom Android back button behaviour

Backhandler hook

React Native Hooks has a nice useBackHandler hook which will simplify the process of setting up event listeners.

Reference

Methods

addEventListener()

static addEventListener(eventName, handler)

exitApp()

static exitApp()

removeEventListener()

static removeEventListener(eventName, handler)
Edit this page
Last updated on
- + diff --git a/docs/0.62/building-for-tv.html b/docs/0.62/building-for-tv.html index 47827d49cfe..773492904a6 100644 --- a/docs/0.62/building-for-tv.html +++ b/docs/0.62/building-for-tv.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
componentWillUnmount() {
this._disableTVEventHandler();
}
}
Edit this page
Last updated on
- + diff --git a/docs/0.62/building-for-tv/index.html b/docs/0.62/building-for-tv/index.html index 47827d49cfe..773492904a6 100644 --- a/docs/0.62/building-for-tv/index.html +++ b/docs/0.62/building-for-tv/index.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
componentWillUnmount() {
this._disableTVEventHandler();
}
}
Edit this page
Last updated on
- + diff --git a/docs/0.62/button.html b/docs/0.62/button.html index e207c9ca0a3..407967372ac 100644 --- a/docs/0.62/button.html +++ b/docs/0.62/button.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

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 button using TouchableOpacity or TouchableNativeFeedback. For inspiration, look at the source code for this button component. Or, take a look at the wide variety of button components built by the community.

<Button
onPress={onPressLearnMore}
title="Learn More"
color="#841584"
accessibilityLabel="Learn more about this purple button"
/>

Example

Reference

Props

onPress

Handler to be called when the user taps the button

TypeRequired
functionYes

title

Text to display inside the button

TypeRequired
stringYes

accessibilityLabel

Text to display for blindness accessibility features

TypeRequired
stringNo

color

Color of the text (iOS), or background color of the button (Android)

TypeRequired
colorNo

disabled

If true, disable all interactions for this component.

TypeRequired
boolNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

nextFocusDown

Designates the next view to receive focus when the user navigates down. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusForward

Designates the next view to receive focus when the user navigates forward. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusLeft

Designates the next view to receive focus when the user navigates left. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusRight

Designates the next view to receive focus when the user navigates right. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusUp

Designates the next view to receive focus when the user navigates up. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

touchSoundDisabled

If true, doesn't play system sound on touch.

TypeRequiredPlatform
booleanNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.62/button/index.html b/docs/0.62/button/index.html index e207c9ca0a3..407967372ac 100644 --- a/docs/0.62/button/index.html +++ b/docs/0.62/button/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

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 button using TouchableOpacity or TouchableNativeFeedback. For inspiration, look at the source code for this button component. Or, take a look at the wide variety of button components built by the community.

<Button
onPress={onPressLearnMore}
title="Learn More"
color="#841584"
accessibilityLabel="Learn more about this purple button"
/>

Example

Reference

Props

onPress

Handler to be called when the user taps the button

TypeRequired
functionYes

title

Text to display inside the button

TypeRequired
stringYes

accessibilityLabel

Text to display for blindness accessibility features

TypeRequired
stringNo

color

Color of the text (iOS), or background color of the button (Android)

TypeRequired
colorNo

disabled

If true, disable all interactions for this component.

TypeRequired
boolNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

nextFocusDown

Designates the next view to receive focus when the user navigates down. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusForward

Designates the next view to receive focus when the user navigates forward. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusLeft

Designates the next view to receive focus when the user navigates left. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusRight

Designates the next view to receive focus when the user navigates right. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusUp

Designates the next view to receive focus when the user navigates up. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

touchSoundDisabled

If true, doesn't play system sound on touch.

TypeRequiredPlatform
booleanNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.62/cameraroll.html b/docs/0.62/cameraroll.html index 51ae77e0982..fc873b9b627 100644 --- a/docs/0.62/cameraroll.html +++ b/docs/0.62/cameraroll.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 CameraRoll

Deprecated. Use @react-native-community/cameraroll instead.

CameraRoll provides access to the local camera roll or photo library.

On iOS, the CameraRoll API requires the RCTCameraRoll library to be linked. You can refer to Linking Libraries (iOS) to learn more.

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 app will use this data. This key will appear as Privacy - Photo Library Usage Description in Xcode.

If you are targeting devices running iOS 11 or later, you will also need to add the NSPhotoLibraryAddUsageDescription key in your Info.plist. Use this key to define a string that describes how your app will use this data. By adding this key to your Info.plist, you will be able to request write-only access permission from the user. If you try to save to the camera roll without this permission, your app will exit.

Reference

Methods

saveToCameraRoll()

CameraRoll.saveToCameraRoll(tag, [type]);

Saves the photo or video to the camera roll or photo library.

On Android, the tag must be a local image or video URI, such as "file:///sdcard/img.png".

On iOS, the tag can be any image URI (including local, remote asset-library and base64 data URIs) 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.

Parameters:

NameTypeRequiredDescription
tagstringYesSee above.
typeenum('photo', 'video')NoOverrides automatic detection based on the file extension.

getPhotos()

CameraRoll.getPhotos(params);

Returns a Promise with photo identifier objects from the local camera roll of the device matching shape defined by getPhotosReturnChecker.

Parameters:

NameTypeRequiredDescription
paramsobjectYesExpects a params with the shape described below.
  • 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 matches page_info { end_cursor } returned from a previous call to getPhotos.
  • groupTypes : {string} : Specifies which group types to filter the results to. Valid values are:
    • Album
    • All
    • Event
    • Faces
    • Library
    • PhotoStream
    • SavedPhotos // 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:
    • All
    • Videos
    • Photos // default
  • mimeTypes : {Array} : 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 objects
    • node: {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}
        • playableDuration: {number}
      • 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: {string}
    • end_cursor: {string}

Example

Loading images:

_handleButtonPress = () => {
CameraRoll.getPhotos({
first: 20,
assetType: 'Photos',
})
.then(r => {
this.setState({ photos: r.edges });
})
.catch((err) => {
//Error Loading Images
});
};
render() {
return (
<View>
<Button title="Load Images" onPress={this._handleButtonPress} />
<ScrollView>
{this.state.photos.map((p, i) => {
return (
<Image
key={i}
style={{
width: 300,
height: 100,
}}
source={{ uri: p.node.image.uri }}
/>
);
})}
</ScrollView>
</View>
);
}
Edit this page
Last updated on
- + diff --git a/docs/0.62/cameraroll/index.html b/docs/0.62/cameraroll/index.html index 51ae77e0982..fc873b9b627 100644 --- a/docs/0.62/cameraroll/index.html +++ b/docs/0.62/cameraroll/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 CameraRoll

Deprecated. Use @react-native-community/cameraroll instead.

CameraRoll provides access to the local camera roll or photo library.

On iOS, the CameraRoll API requires the RCTCameraRoll library to be linked. You can refer to Linking Libraries (iOS) to learn more.

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 app will use this data. This key will appear as Privacy - Photo Library Usage Description in Xcode.

If you are targeting devices running iOS 11 or later, you will also need to add the NSPhotoLibraryAddUsageDescription key in your Info.plist. Use this key to define a string that describes how your app will use this data. By adding this key to your Info.plist, you will be able to request write-only access permission from the user. If you try to save to the camera roll without this permission, your app will exit.

Reference

Methods

saveToCameraRoll()

CameraRoll.saveToCameraRoll(tag, [type]);

Saves the photo or video to the camera roll or photo library.

On Android, the tag must be a local image or video URI, such as "file:///sdcard/img.png".

On iOS, the tag can be any image URI (including local, remote asset-library and base64 data URIs) 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.

Parameters:

NameTypeRequiredDescription
tagstringYesSee above.
typeenum('photo', 'video')NoOverrides automatic detection based on the file extension.

getPhotos()

CameraRoll.getPhotos(params);

Returns a Promise with photo identifier objects from the local camera roll of the device matching shape defined by getPhotosReturnChecker.

Parameters:

NameTypeRequiredDescription
paramsobjectYesExpects a params with the shape described below.
  • 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 matches page_info { end_cursor } returned from a previous call to getPhotos.
  • groupTypes : {string} : Specifies which group types to filter the results to. Valid values are:
    • Album
    • All
    • Event
    • Faces
    • Library
    • PhotoStream
    • SavedPhotos // 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:
    • All
    • Videos
    • Photos // default
  • mimeTypes : {Array} : 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 objects
    • node: {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}
        • playableDuration: {number}
      • 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: {string}
    • end_cursor: {string}

Example

Loading images:

_handleButtonPress = () => {
CameraRoll.getPhotos({
first: 20,
assetType: 'Photos',
})
.then(r => {
this.setState({ photos: r.edges });
})
.catch((err) => {
//Error Loading Images
});
};
render() {
return (
<View>
<Button title="Load Images" onPress={this._handleButtonPress} />
<ScrollView>
{this.state.photos.map((p, i) => {
return (
<Image
key={i}
style={{
width: 300,
height: 100,
}}
source={{ uri: p.node.image.uri }}
/>
);
})}
</ScrollView>
</View>
);
}
Edit this page
Last updated on
- + diff --git a/docs/0.62/checkbox.html b/docs/0.62/checkbox.html index 0a70cd6231a..a087c3ebccd 100644 --- a/docs/0.62/checkbox.html +++ b/docs/0.62/checkbox.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 CheckBox

Deprecated. Use @react-native-community/checkbox instead.

Renders a boolean input (Android only).

This is a controlled component that requires an onValueChange callback that updates the value prop in order for the component to reflect user actions. If the value prop is not updated, the component will continue to render the supplied value prop instead of the expected result of any user actions.

Example

Reference

Props

Inherits View Props.

disabled

If true the user won't be able to toggle the checkbox. Default value is false.

TypeRequired
boolNo

onChange

Used in case the props change removes the component.

TypeRequired
functionNo

onValueChange

Invoked with the new value when the value changes.

TypeRequired
functionNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

value

The value of the checkbox. If true the checkbox will be turned on. Default value is false.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/checkbox/index.html b/docs/0.62/checkbox/index.html index 0a70cd6231a..a087c3ebccd 100644 --- a/docs/0.62/checkbox/index.html +++ b/docs/0.62/checkbox/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 CheckBox

Deprecated. Use @react-native-community/checkbox instead.

Renders a boolean input (Android only).

This is a controlled component that requires an onValueChange callback that updates the value prop in order for the component to reflect user actions. If the value prop is not updated, the component will continue to render the supplied value prop instead of the expected result of any user actions.

Example

Reference

Props

Inherits View Props.

disabled

If true the user won't be able to toggle the checkbox. Default value is false.

TypeRequired
boolNo

onChange

Used in case the props change removes the component.

TypeRequired
functionNo

onValueChange

Invoked with the new value when the value changes.

TypeRequired
functionNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

value

The value of the checkbox. If true the checkbox will be turned on. Default value is false.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/clipboard.html b/docs/0.62/clipboard.html index ff03e56450a..dfd76f4959f 100644 --- a/docs/0.62/clipboard.html +++ b/docs/0.62/clipboard.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 Clipboard

Deprecated. Use @react-native-community/clipboard instead.

Clipboard gives you an interface for setting and getting content from Clipboard on both Android and iOS

Example

Reference

Methods

getString()

static getString()

Get content of string type, this method returns a Promise, so you can use following code to get clipboard content

async _getContent() {
var content = await Clipboard.getString();
}

setString()

static setString(content)

Set content of string type. You can use following code to set clipboard content

_setContent() {
Clipboard.setString('hello world');
}

Parameters:

NameTypeRequiredDescription
contentstringYesThe content to be stored in the clipboard

Notice

Be careful when you're trying to copy to clipboard any data except string and number, some data need additional stringification. For example, if you will try to copy array - Android will raise an exception, but iOS will not.

Edit this page
Last updated on
- + diff --git a/docs/0.62/clipboard/index.html b/docs/0.62/clipboard/index.html index ff03e56450a..dfd76f4959f 100644 --- a/docs/0.62/clipboard/index.html +++ b/docs/0.62/clipboard/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 Clipboard

Deprecated. Use @react-native-community/clipboard instead.

Clipboard gives you an interface for setting and getting content from Clipboard on both Android and iOS

Example

Reference

Methods

getString()

static getString()

Get content of string type, this method returns a Promise, so you can use following code to get clipboard content

async _getContent() {
var content = await Clipboard.getString();
}

setString()

static setString(content)

Set content of string type. You can use following code to set clipboard content

_setContent() {
Clipboard.setString('hello world');
}

Parameters:

NameTypeRequiredDescription
contentstringYesThe content to be stored in the clipboard

Notice

Be careful when you're trying to copy to clipboard any data except string and number, some data need additional stringification. For example, if you will try to copy array - Android will raise an exception, but iOS will not.

Edit this page
Last updated on
- + diff --git a/docs/0.62/colors.html b/docs/0.62/colors.html index 8900a92e74d..e18baa84713 100644 --- a/docs/0.62/colors.html +++ b/docs/0.62/colors.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Color Reference

Components in React Native are styled using JavaScript. Color properties usually match how CSS works on the web.

Red Green Blue (RGB)

React Native supports rgb() and rgba() in both hexadecimal and functional notation:

  • '#f0f' (#rgb)
  • '#ff00ff' (#rrggbb)
  • '#f0ff' (#rgba)
  • '#ff00ff00' (#rrggbbaa)
  • 'rgb(255, 0, 255)'
  • 'rgba(255, 0, 255, 1.0)'

Hue Saturation Lightness (HSL)

React Native supports hsl() and hsla() in functional notation:

  • 'hsl(360, 100%, 100%)'
  • 'hsla(360, 100%, 100%, 1.0)'

Color ints

React Native supports also colors as an int values (in RGB color mode):

  • 0xff00ff00 (0xrrggbbaa)

Note: This might appear similar to the Android Color ints representation but on Android values are stored in SRGB color mode (0xaarrggbb).

Named colors

In React Native you can also use color name strings as values.

Note: React Native only supports lowercase color names. Uppercase color names are not supported.

transparent

This is a shortcut for rgba(0,0,0,0), same like in CSS3.

Color keywords

Named colors implementation follows the CSS3/SVG 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 (`#fafad2`)
  • 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 (`#00fa9a`)
  • 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`)
Edit this page
Last updated on
- + diff --git a/docs/0.62/colors/index.html b/docs/0.62/colors/index.html index 8900a92e74d..e18baa84713 100644 --- a/docs/0.62/colors/index.html +++ b/docs/0.62/colors/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Color Reference

Components in React Native are styled using JavaScript. Color properties usually match how CSS works on the web.

Red Green Blue (RGB)

React Native supports rgb() and rgba() in both hexadecimal and functional notation:

  • '#f0f' (#rgb)
  • '#ff00ff' (#rrggbb)
  • '#f0ff' (#rgba)
  • '#ff00ff00' (#rrggbbaa)
  • 'rgb(255, 0, 255)'
  • 'rgba(255, 0, 255, 1.0)'

Hue Saturation Lightness (HSL)

React Native supports hsl() and hsla() in functional notation:

  • 'hsl(360, 100%, 100%)'
  • 'hsla(360, 100%, 100%, 1.0)'

Color ints

React Native supports also colors as an int values (in RGB color mode):

  • 0xff00ff00 (0xrrggbbaa)

Note: This might appear similar to the Android Color ints representation but on Android values are stored in SRGB color mode (0xaarrggbb).

Named colors

In React Native you can also use color name strings as values.

Note: React Native only supports lowercase color names. Uppercase color names are not supported.

transparent

This is a shortcut for rgba(0,0,0,0), same like in CSS3.

Color keywords

Named colors implementation follows the CSS3/SVG 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 (`#fafad2`)
  • 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 (`#00fa9a`)
  • 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`)
Edit this page
Last updated on
- + diff --git a/docs/0.62/communication-android.html b/docs/0.62/communication-android.html index 370ff4aaff8..77e3325feba 100644 --- a/docs/0.62/communication-android.html +++ b/docs/0.62/communication-android.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
mReactRootView.setAppProperties(updatedProps);

It is fine to update properties anytime. However, updates have to be performed on the main thread. You use the getter on any thread.

There is no way to update only a few properties at a time. We suggest that you build it into your own wrapper instead.

Note: Currently, JS function componentWillUpdateProps of the top level RN component will not be called after a prop update. However, you can access the new props in componentDidMount function.

Passing properties from React Native to native

The problem exposing properties of native components is covered in detail in this article. In short, properties that are to be reflected in JavaScript needs to be exposed as setter method annotated with @ReactProp, then use them in React Native as if the component was an ordinary React Native component.

Limits of properties

The main drawback of cross-language properties is that they do not support callbacks, which would allow us to handle bottom-up data bindings. Imagine you have a small RN view that you want to be removed from the native parent view as a result of a JS action. There is no way to do that with props, as the information would need to go bottom-up.

Although we have a flavor of cross-language callbacks (described here), these callbacks are not always the thing we need. The main problem is that they are not intended to be passed as properties. Rather, this mechanism allows us to trigger a native action from JS, and handle the result of that action in JS.

Other ways of cross-language interaction (events and native modules)

As stated in the previous chapter, using properties comes with some limitations. Sometimes properties are not enough to drive the logic of our app and we need a solution that gives more flexibility. This chapter covers other communication techniques available in React Native. They can be used for internal communication (between JS and native layers in RN) as well as for external communication (between RN and the 'pure native' part of your app).

React Native enables you to perform cross-language function calls. You can execute custom native code from JS and vice versa. Unfortunately, depending on the side we are working on, we achieve the same goal in different ways. For native - we use events mechanism to schedule an execution of a handler function in JS, while for React Native we directly call methods exported by native modules.

Calling React Native functions from native (events)

Events are described in detail in this article. Note that using events gives us no guarantees about execution time, as the event is handled on a separate thread.

Events are powerful, because they allow us to change React Native components without needing a reference to them. However, there are some pitfalls that you can fall into while using them:

Calling native functions from React Native (native modules)

Native modules are Java classes that are available in JS. Typically one instance of each module is created per JS bridge. They can export arbitrary functions and constants to React Native. They have been covered in detail in this article.

Warning: All native modules share the same namespace. Watch out for name collisions when creating new ones.

Edit this page
Last updated on
- + diff --git a/docs/0.62/communication-android/index.html b/docs/0.62/communication-android/index.html index 370ff4aaff8..77e3325feba 100644 --- a/docs/0.62/communication-android/index.html +++ b/docs/0.62/communication-android/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
mReactRootView.setAppProperties(updatedProps);

It is fine to update properties anytime. However, updates have to be performed on the main thread. You use the getter on any thread.

There is no way to update only a few properties at a time. We suggest that you build it into your own wrapper instead.

Note: Currently, JS function componentWillUpdateProps of the top level RN component will not be called after a prop update. However, you can access the new props in componentDidMount function.

Passing properties from React Native to native

The problem exposing properties of native components is covered in detail in this article. In short, properties that are to be reflected in JavaScript needs to be exposed as setter method annotated with @ReactProp, then use them in React Native as if the component was an ordinary React Native component.

Limits of properties

The main drawback of cross-language properties is that they do not support callbacks, which would allow us to handle bottom-up data bindings. Imagine you have a small RN view that you want to be removed from the native parent view as a result of a JS action. There is no way to do that with props, as the information would need to go bottom-up.

Although we have a flavor of cross-language callbacks (described here), these callbacks are not always the thing we need. The main problem is that they are not intended to be passed as properties. Rather, this mechanism allows us to trigger a native action from JS, and handle the result of that action in JS.

Other ways of cross-language interaction (events and native modules)

As stated in the previous chapter, using properties comes with some limitations. Sometimes properties are not enough to drive the logic of our app and we need a solution that gives more flexibility. This chapter covers other communication techniques available in React Native. They can be used for internal communication (between JS and native layers in RN) as well as for external communication (between RN and the 'pure native' part of your app).

React Native enables you to perform cross-language function calls. You can execute custom native code from JS and vice versa. Unfortunately, depending on the side we are working on, we achieve the same goal in different ways. For native - we use events mechanism to schedule an execution of a handler function in JS, while for React Native we directly call methods exported by native modules.

Calling React Native functions from native (events)

Events are described in detail in this article. Note that using events gives us no guarantees about execution time, as the event is handled on a separate thread.

Events are powerful, because they allow us to change React Native components without needing a reference to them. However, there are some pitfalls that you can fall into while using them:

Calling native functions from React Native (native modules)

Native modules are Java classes that are available in JS. Typically one instance of each module is created per JS bridge. They can export arbitrary functions and constants to React Native. They have been covered in detail in this article.

Warning: All native modules share the same namespace. Watch out for name collisions when creating new ones.

Edit this page
Last updated on
- + diff --git a/docs/0.62/communication-ios.html b/docs/0.62/communication-ios.html index e17a963ba0e..b0f9ddc2d3b 100644 --- a/docs/0.62/communication-ios.html +++ b/docs/0.62/communication-ios.html @@ -19,7 +19,7 @@ - + @@ -44,7 +44,7 @@
rootView.frame = newFrame;
}

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 example 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 separate 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's hidden property). Then change its visibility in the delegate method.

Edit this page
Last updated on
- + diff --git a/docs/0.62/communication-ios/index.html b/docs/0.62/communication-ios/index.html index e17a963ba0e..b0f9ddc2d3b 100644 --- a/docs/0.62/communication-ios/index.html +++ b/docs/0.62/communication-ios/index.html @@ -19,7 +19,7 @@ - + @@ -44,7 +44,7 @@
rootView.frame = newFrame;
}

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 example 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 separate 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's hidden property). Then change its visibility in the delegate method.

Edit this page
Last updated on
- + diff --git a/docs/0.62/components-and-apis.html b/docs/0.62/components-and-apis.html index 61d1d43d5c4..9a5484af4e7 100644 --- a/docs/0.62/components-and-apis.html +++ b/docs/0.62/components-and-apis.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Core Components and APIs

React Native provides a number of built-in Core Components ready for you to use in your app. You can find them all in the left sidebar (or menu above, if you are on a narrow screen). 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 has a community of thousands of developers. If you're looking for a library that does something specific, please refer to this guide about finding libraries.

Basic Components

Most apps will end up using one of these basic components.

View

The most fundamental component for building a UI.

Text

A component for displaying text.

Image

A component for displaying images.

TextInput

A component for inputting text into the app via a keyboard.

ScrollView

Provides a scrolling container that can host multiple components and views.

StyleSheet

Provides an abstraction layer similar to CSS stylesheets.

User Interface

These common user interface controls will render on any platform.

Button

A basic button component for handling touches that should render nicely on any platform.

Picker

Renders the native picker component on Android and iOS.

Switch

Renders a boolean input.

List Views

Unlike the more generic ScrollView, the following list view components only render elements that are currently showing on the screen. This makes them a performant choice for displaying long lists of data.

FlatList

A component for rendering performant scrollable lists.

SectionList

Like FlatList, but for sectioned lists.

iOS Components and APIs

Many of the following components provide wrappers for commonly used UIKit classes.

ActionSheetIOS

API to display an iOS action sheet or share sheet.

Android Components and APIs

Many of the following components provide wrappers for commonly used Android classes.

BackHandler

Detect hardware button presses for back navigation.

DrawerLayoutAndroid

Renders a DrawerLayout on Android.

PermissionsAndroid

Provides access to the permissions model introduced in Android M.

ToastAndroid

Create an Android Toast alert.

Others

These components may be useful for certain applications. For an exhaustive list of components and APIs, check out the sidebar to the left (or menu above, if you are on a narrow screen).

ActivityIndicator

Displays a circular loading indicator.

Alert

Launches an alert dialog with the specified title and message.

Animated

A library for creating fluid, powerful animations that are easy to build and maintain.

Dimensions

Provides an interface for getting device dimensions.

KeyboardAvoidingView

Provides a view that moves out of the way of the virtual keyboard automatically.

Linking

Provides a general interface to interact with both incoming and outgoing app links.

Modal

Provides a simple way to present content above an enclosing view.

PixelRatio

Provides access to the device pixel density.

RefreshControl

This component is used inside a ScrollView to add pull to refresh functionality.

StatusBar

Component to control the app status bar.

Edit this page
Last updated on
- + diff --git a/docs/0.62/components-and-apis/index.html b/docs/0.62/components-and-apis/index.html index 61d1d43d5c4..9a5484af4e7 100644 --- a/docs/0.62/components-and-apis/index.html +++ b/docs/0.62/components-and-apis/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Core Components and APIs

React Native provides a number of built-in Core Components ready for you to use in your app. You can find them all in the left sidebar (or menu above, if you are on a narrow screen). 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 has a community of thousands of developers. If you're looking for a library that does something specific, please refer to this guide about finding libraries.

Basic Components

Most apps will end up using one of these basic components.

View

The most fundamental component for building a UI.

Text

A component for displaying text.

Image

A component for displaying images.

TextInput

A component for inputting text into the app via a keyboard.

ScrollView

Provides a scrolling container that can host multiple components and views.

StyleSheet

Provides an abstraction layer similar to CSS stylesheets.

User Interface

These common user interface controls will render on any platform.

Button

A basic button component for handling touches that should render nicely on any platform.

Picker

Renders the native picker component on Android and iOS.

Switch

Renders a boolean input.

List Views

Unlike the more generic ScrollView, the following list view components only render elements that are currently showing on the screen. This makes them a performant choice for displaying long lists of data.

FlatList

A component for rendering performant scrollable lists.

SectionList

Like FlatList, but for sectioned lists.

iOS Components and APIs

Many of the following components provide wrappers for commonly used UIKit classes.

ActionSheetIOS

API to display an iOS action sheet or share sheet.

Android Components and APIs

Many of the following components provide wrappers for commonly used Android classes.

BackHandler

Detect hardware button presses for back navigation.

DrawerLayoutAndroid

Renders a DrawerLayout on Android.

PermissionsAndroid

Provides access to the permissions model introduced in Android M.

ToastAndroid

Create an Android Toast alert.

Others

These components may be useful for certain applications. For an exhaustive list of components and APIs, check out the sidebar to the left (or menu above, if you are on a narrow screen).

ActivityIndicator

Displays a circular loading indicator.

Alert

Launches an alert dialog with the specified title and message.

Animated

A library for creating fluid, powerful animations that are easy to build and maintain.

Dimensions

Provides an interface for getting device dimensions.

KeyboardAvoidingView

Provides a view that moves out of the way of the virtual keyboard automatically.

Linking

Provides a general interface to interact with both incoming and outgoing app links.

Modal

Provides a simple way to present content above an enclosing view.

PixelRatio

Provides access to the device pixel density.

RefreshControl

This component is used inside a ScrollView to add pull to refresh functionality.

StatusBar

Component to control the app status bar.

Edit this page
Last updated on
- + diff --git a/docs/0.62/custom-webview-android.html b/docs/0.62/custom-webview-android.html index 0c05bc5a79e..cea5a2ac86e 100644 --- a/docs/0.62/custom-webview-android.html +++ b/docs/0.62/custom-webview-android.html @@ -19,7 +19,7 @@ - + @@ -60,7 +60,7 @@
render() {
return (
<WebView
{...this.props}
nativeConfig={{
component: RCTCustomWebView,
props: {
finalUrl: this.props.finalUrl,
onNavigationCompleted: this._onNavigationCompleted
}
}}
/>
);
}
}

Similar to regular native components, you must provide all your prop types in the component to have them forwarded on to the native component. However, if you have some prop types that are only used internally in component, you can add them to the nativeOnly property of the third argument previously mentioned. For event handlers, you have to use the value true instead of a regular prop type.

For example, if you wanted to add an internal event handler called onScrollToBottom, you would use,

const RCTCustomWebView = requireNativeComponent(
'RCTCustomWebView',
CustomWebView,
{
...WebView.extraNativeComponentConfig,
nativeOnly: {
...WebView.extraNativeComponentConfig.nativeOnly,
onScrollToBottom: true
}
}
);
Edit this page
Last updated on
- + diff --git a/docs/0.62/custom-webview-android/index.html b/docs/0.62/custom-webview-android/index.html index 0c05bc5a79e..cea5a2ac86e 100644 --- a/docs/0.62/custom-webview-android/index.html +++ b/docs/0.62/custom-webview-android/index.html @@ -19,7 +19,7 @@ - + @@ -60,7 +60,7 @@
render() {
return (
<WebView
{...this.props}
nativeConfig={{
component: RCTCustomWebView,
props: {
finalUrl: this.props.finalUrl,
onNavigationCompleted: this._onNavigationCompleted
}
}}
/>
);
}
}

Similar to regular native components, you must provide all your prop types in the component to have them forwarded on to the native component. However, if you have some prop types that are only used internally in component, you can add them to the nativeOnly property of the third argument previously mentioned. For event handlers, you have to use the value true instead of a regular prop type.

For example, if you wanted to add an internal event handler called onScrollToBottom, you would use,

const RCTCustomWebView = requireNativeComponent(
'RCTCustomWebView',
CustomWebView,
{
...WebView.extraNativeComponentConfig,
nativeOnly: {
...WebView.extraNativeComponentConfig.nativeOnly,
onScrollToBottom: true
}
}
);
Edit this page
Last updated on
- + diff --git a/docs/0.62/custom-webview-ios.html b/docs/0.62/custom-webview-ios.html index 28619c766e7..e95a3538bd8 100644 --- a/docs/0.62/custom-webview-ios.html +++ b/docs/0.62/custom-webview-ios.html @@ -19,7 +19,7 @@ - + @@ -63,7 +63,7 @@
render() {
return (
<WebView
{...this.props}
nativeConfig={{
component: RCTCustomWebView,
props: {
finalUrl: this.props.finalUrl,
onNavigationCompleted: this._onNavigationCompleted
},
viewManager: CustomWebViewManager
}}
/>
);
}
}

Similar to regular native components, you must provide all your prop types in the component to have them forwarded on to the native component. However, if you have some prop types that are only used internally in component, you can add them to the nativeOnly property of the third argument previously mentioned. For event handlers, you have to use the value true instead of a regular prop type.

For example, if you wanted to add an internal event handler called onScrollToBottom, you would use,

const RCTCustomWebView = requireNativeComponent(
'RCTCustomWebView',
CustomWebView,
{
...WebView.extraNativeComponentConfig,
nativeOnly: {
...WebView.extraNativeComponentConfig.nativeOnly,
onScrollToBottom: true
}
}
);
Edit this page
Last updated on
- + diff --git a/docs/0.62/custom-webview-ios/index.html b/docs/0.62/custom-webview-ios/index.html index 28619c766e7..e95a3538bd8 100644 --- a/docs/0.62/custom-webview-ios/index.html +++ b/docs/0.62/custom-webview-ios/index.html @@ -19,7 +19,7 @@ - + @@ -63,7 +63,7 @@
render() {
return (
<WebView
{...this.props}
nativeConfig={{
component: RCTCustomWebView,
props: {
finalUrl: this.props.finalUrl,
onNavigationCompleted: this._onNavigationCompleted
},
viewManager: CustomWebViewManager
}}
/>
);
}
}

Similar to regular native components, you must provide all your prop types in the component to have them forwarded on to the native component. However, if you have some prop types that are only used internally in component, you can add them to the nativeOnly property of the third argument previously mentioned. For event handlers, you have to use the value true instead of a regular prop type.

For example, if you wanted to add an internal event handler called onScrollToBottom, you would use,

const RCTCustomWebView = requireNativeComponent(
'RCTCustomWebView',
CustomWebView,
{
...WebView.extraNativeComponentConfig,
nativeOnly: {
...WebView.extraNativeComponentConfig.nativeOnly,
onScrollToBottom: true
}
}
);
Edit this page
Last updated on
- + diff --git a/docs/0.62/datepickerandroid.html b/docs/0.62/datepickerandroid.html index cf7ed51d5ef..83c96b839d3 100644 --- a/docs/0.62/datepickerandroid.html +++ b/docs/0.62/datepickerandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 DatePickerAndroid

Deprecated. Use @react-native-community/datetimepicker instead.

Opens the standard Android date picker dialog.

Example

try {
const {
action,
year,
month,
day
} = await DatePickerAndroid.open({
// Use `new Date()` for current date.
// May 25 2020. Month 0 is January.
date: new Date(2020, 4, 25)
});
if (action !== DatePickerAndroid.dismissedAction) {
// Selected year, month (0-11), day
}
} catch ({ code, message }) {
console.warn('Cannot open date picker', message);
}

Reference

Methods

open()

static open(options)

Opens the standard Android date picker dialog.

The available keys for the options object are:

  • date (Date object or timestamp in milliseconds) - date to show by default
  • minDate (Date or timestamp in milliseconds) - minimum date that can be selected
  • maxDate (Date object or timestamp in milliseconds) - maximum date that can be selected
  • mode (enum('calendar', 'spinner', 'default')) - To set the date-picker mode to calendar/spinner/default
    • 'calendar': Show a date picker in calendar mode.
    • 'spinner': Show a date picker in spinner mode.
    • 'default': Show a default native date picker(spinner/calendar) based on android versions.

Returns a Promise which will be invoked an object containing action, year, month (0-11), 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 is equal to DatePickerAndroid.dateSetAction 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.

dateSetAction()

static dateSetAction()

A date has been selected.

dismissedAction()

static dismissedAction()

The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/0.62/datepickerandroid/index.html b/docs/0.62/datepickerandroid/index.html index cf7ed51d5ef..83c96b839d3 100644 --- a/docs/0.62/datepickerandroid/index.html +++ b/docs/0.62/datepickerandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 DatePickerAndroid

Deprecated. Use @react-native-community/datetimepicker instead.

Opens the standard Android date picker dialog.

Example

try {
const {
action,
year,
month,
day
} = await DatePickerAndroid.open({
// Use `new Date()` for current date.
// May 25 2020. Month 0 is January.
date: new Date(2020, 4, 25)
});
if (action !== DatePickerAndroid.dismissedAction) {
// Selected year, month (0-11), day
}
} catch ({ code, message }) {
console.warn('Cannot open date picker', message);
}

Reference

Methods

open()

static open(options)

Opens the standard Android date picker dialog.

The available keys for the options object are:

  • date (Date object or timestamp in milliseconds) - date to show by default
  • minDate (Date or timestamp in milliseconds) - minimum date that can be selected
  • maxDate (Date object or timestamp in milliseconds) - maximum date that can be selected
  • mode (enum('calendar', 'spinner', 'default')) - To set the date-picker mode to calendar/spinner/default
    • 'calendar': Show a date picker in calendar mode.
    • 'spinner': Show a date picker in spinner mode.
    • 'default': Show a default native date picker(spinner/calendar) based on android versions.

Returns a Promise which will be invoked an object containing action, year, month (0-11), 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 is equal to DatePickerAndroid.dateSetAction 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.

dateSetAction()

static dateSetAction()

A date has been selected.

dismissedAction()

static dismissedAction()

The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/0.62/datepickerios.html b/docs/0.62/datepickerios.html index 8861619dc36..6b3dee84432 100644 --- a/docs/0.62/datepickerios.html +++ b/docs/0.62/datepickerios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 DatePickerIOS

Deprecated. Use @react-native-community/datetimepicker instead.

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 source of truth.

Example

Reference

Props

Inherits View Props.

date

The currently selected date.

TypeRequired
DateYes

onChange

Date change handler.

This is called when the user changes the date or time in the UI. The first and only argument is an Event. For getting the date the picker was changed to, use onDateChange instead.

TypeRequired
functionNo

onDateChange

Date change handler.

This is called when the user changes the date or time in the UI. The first and only argument is a Date object representing the new date and time.

TypeRequired
functionYes

maximumDate

Maximum date.

Restricts the range of possible date/time values.

TypeRequired
DateNo

Example with maximumDate set to December 31, 2017:

minimumDate

Minimum date.

Restricts the range of possible date/time values.

TypeRequired
DateNo

See maximumDate for an example image.

minuteInterval

The interval at which minutes can be selected.

TypeRequired
enum(1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30)No

Example with minuteInterval set to 10:

mode

The date picker mode.

TypeRequired
enum('date', 'time', 'datetime', 'countdown')No

Example with mode set to date, time, and datetime:

locale

The locale for the date picker. Value needs to be a Locale ID.

TypeRequired
StringNo

timeZoneOffsetInMinutes

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.

TypeRequired
numberNo

initialDate

Provides an initial value that will change when the user starts selecting a date. It is useful for use-cases where you do not want to deal with listening to events and updating the date prop to keep the controlled state in sync. The controlled state has known bugs which causes it to go out of sync with native. The initialDate prop is intended to allow you to have native be source of truth.

TypeRequired
DateNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/datepickerios/index.html b/docs/0.62/datepickerios/index.html index 8861619dc36..6b3dee84432 100644 --- a/docs/0.62/datepickerios/index.html +++ b/docs/0.62/datepickerios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 DatePickerIOS

Deprecated. Use @react-native-community/datetimepicker instead.

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 source of truth.

Example

Reference

Props

Inherits View Props.

date

The currently selected date.

TypeRequired
DateYes

onChange

Date change handler.

This is called when the user changes the date or time in the UI. The first and only argument is an Event. For getting the date the picker was changed to, use onDateChange instead.

TypeRequired
functionNo

onDateChange

Date change handler.

This is called when the user changes the date or time in the UI. The first and only argument is a Date object representing the new date and time.

TypeRequired
functionYes

maximumDate

Maximum date.

Restricts the range of possible date/time values.

TypeRequired
DateNo

Example with maximumDate set to December 31, 2017:

minimumDate

Minimum date.

Restricts the range of possible date/time values.

TypeRequired
DateNo

See maximumDate for an example image.

minuteInterval

The interval at which minutes can be selected.

TypeRequired
enum(1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30)No

Example with minuteInterval set to 10:

mode

The date picker mode.

TypeRequired
enum('date', 'time', 'datetime', 'countdown')No

Example with mode set to date, time, and datetime:

locale

The locale for the date picker. Value needs to be a Locale ID.

TypeRequired
StringNo

timeZoneOffsetInMinutes

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.

TypeRequired
numberNo

initialDate

Provides an initial value that will change when the user starts selecting a date. It is useful for use-cases where you do not want to deal with listening to events and updating the date prop to keep the controlled state in sync. The controlled state has known bugs which causes it to go out of sync with native. The initialDate prop is intended to allow you to have native be source of truth.

TypeRequired
DateNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/debugging.html b/docs/0.62/debugging.html index fbb1c8c81b6..6e0aa559352 100644 --- a/docs/0.62/debugging.html +++ b/docs/0.62/debugging.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Debugging

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 on Mac OS and Ctrl+M on Windows and Linux. Alternatively for Android, you can run the command adb shell input keyevent 82 to open the dev menu (82 being the Menu key code).

The Developer Menu is disabled in release (production) builds.

Enabling Fast Refresh

Fast Refresh is a React Native feature that allows you to get near-instant feedback for changes in your React components. While debugging, it can help to have Fast Refresh enabled. Fast Refresh is enabled by default, and you can toggle "Enable Fast Refresh" in the React Native developer menu. When enabled, most of your edits should be visible within a second or two.

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.

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:

import { YellowBox } from 'react-native';
YellowBox.ignoreWarnings(['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.

Safari Developer Tools

You can use Safari to debug the iOS version of your app without having to enable "Debug JS Remotely".

  • Enable Develop menu in Safari: Preferences → Advanced → Select "Show Develop menu in menu bar"
  • Select your app's JSContext: Develop → Simulator → JSContext
  • Safari's Web Inspector should open which has a Console and a Debugger

While sourcemaps may not be enabled by default, you can follow this guide or video to enable them and set break points at the right places in the source code.

However, every time the app is reloaded (using live reload, or by manually reloading), a new JSContext is created. Choosing "Automatically Show Web Inspectors for JSContexts" saves you from having to select the latest JSContext manually.

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:

Note: Version 4 of react-devtools requires react-native version 0.62 or higher to work properly.

npm install -g react-devtools

Now run react-devtools from the terminal to launch the standalone DevTools app:

react-devtools

React DevTools

It should connect to your simulator within a few seconds.

Note: if you prefer to avoid global installations, you can add react-devtools as a project dependency. Add the react-devtools package to your project using npm install --save-dev react-devtools, then add "react-devtools": "react-devtools" to the scripts section in your package.json, and then run npm run react-devtools from your project folder to open the DevTools.

Integration with React Native Inspector

Open the in-app developer menu and choose "Toggle Inspector". It will bring up an overlay that lets you tap on any UI element and see information about it:

React Native Inspector

However, when react-devtools is running, Inspector will enter a 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:

React DevTools Inspector Integration

You can choose "Toggle 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.

React DevTools Chrome Console Integration

Performance Monitor

You can enable a performance overlay to help you debug performance problems by selecting "Perf Monitor" in the Developer Menu.

Debugging Application State

Reactotron is an open-source desktop app that allows you to inspect Redux or MobX-State-Tree application state as well as view custom logs, run custom commands such as resetting state, store and restore state snapshots, and other helpful debugging features for React Native apps.

You can view installation instructions in the README. If you're using Expo, here is an article detailing how to install on Expo.

Native Debugging

Accessing console logs

You can display the console logs for an iOS or Android app by using the following commands in a terminal while the app is running:

$ npx react-native log-ios
$ npx react-native log-android

You may also access these through Debug → Open System Log... in the iOS Simulator or by running adb logcat *:S ReactNative:V ReactNativeJS:V in a terminal while an Android app is running on a device or emulator.

If you're using Create React Native App or Expo CLI, console logs already appear in the same terminal output as the bundler.

Debugging on a device with Chrome Developer Tools

If you're using Create React Native App or Expo CLI, this is configured for you already.

On iOS devices, open the file RCTWebSocketExecutor.m and change "localhost" to the IP address of your computer, then select "Debug JS Remotely" from the Developer Menu.

On Android 5.0+ devices connected via USB, you can use the adb command line tool to setup port forwarding from the device to your computer:

adb reverse tcp:8081 tcp:8081

Alternatively, select "Dev Settings" from the Developer Menu, then update the "Debug server host for device" setting to match the IP address of your computer.

If you run into any issues, it may be possible that one of your Chrome extensions is interacting in unexpected ways with the debugger. Try disabling all of your extensions and re-enabling them one-by-one until you find the problematic extension.

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.

Edit this page
Last updated on
- + diff --git a/docs/0.62/debugging/index.html b/docs/0.62/debugging/index.html index fbb1c8c81b6..6e0aa559352 100644 --- a/docs/0.62/debugging/index.html +++ b/docs/0.62/debugging/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Debugging

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 on Mac OS and Ctrl+M on Windows and Linux. Alternatively for Android, you can run the command adb shell input keyevent 82 to open the dev menu (82 being the Menu key code).

The Developer Menu is disabled in release (production) builds.

Enabling Fast Refresh

Fast Refresh is a React Native feature that allows you to get near-instant feedback for changes in your React components. While debugging, it can help to have Fast Refresh enabled. Fast Refresh is enabled by default, and you can toggle "Enable Fast Refresh" in the React Native developer menu. When enabled, most of your edits should be visible within a second or two.

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.

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:

import { YellowBox } from 'react-native';
YellowBox.ignoreWarnings(['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.

Safari Developer Tools

You can use Safari to debug the iOS version of your app without having to enable "Debug JS Remotely".

  • Enable Develop menu in Safari: Preferences → Advanced → Select "Show Develop menu in menu bar"
  • Select your app's JSContext: Develop → Simulator → JSContext
  • Safari's Web Inspector should open which has a Console and a Debugger

While sourcemaps may not be enabled by default, you can follow this guide or video to enable them and set break points at the right places in the source code.

However, every time the app is reloaded (using live reload, or by manually reloading), a new JSContext is created. Choosing "Automatically Show Web Inspectors for JSContexts" saves you from having to select the latest JSContext manually.

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:

Note: Version 4 of react-devtools requires react-native version 0.62 or higher to work properly.

npm install -g react-devtools

Now run react-devtools from the terminal to launch the standalone DevTools app:

react-devtools

React DevTools

It should connect to your simulator within a few seconds.

Note: if you prefer to avoid global installations, you can add react-devtools as a project dependency. Add the react-devtools package to your project using npm install --save-dev react-devtools, then add "react-devtools": "react-devtools" to the scripts section in your package.json, and then run npm run react-devtools from your project folder to open the DevTools.

Integration with React Native Inspector

Open the in-app developer menu and choose "Toggle Inspector". It will bring up an overlay that lets you tap on any UI element and see information about it:

React Native Inspector

However, when react-devtools is running, Inspector will enter a 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:

React DevTools Inspector Integration

You can choose "Toggle 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.

React DevTools Chrome Console Integration

Performance Monitor

You can enable a performance overlay to help you debug performance problems by selecting "Perf Monitor" in the Developer Menu.

Debugging Application State

Reactotron is an open-source desktop app that allows you to inspect Redux or MobX-State-Tree application state as well as view custom logs, run custom commands such as resetting state, store and restore state snapshots, and other helpful debugging features for React Native apps.

You can view installation instructions in the README. If you're using Expo, here is an article detailing how to install on Expo.

Native Debugging

Accessing console logs

You can display the console logs for an iOS or Android app by using the following commands in a terminal while the app is running:

$ npx react-native log-ios
$ npx react-native log-android

You may also access these through Debug → Open System Log... in the iOS Simulator or by running adb logcat *:S ReactNative:V ReactNativeJS:V in a terminal while an Android app is running on a device or emulator.

If you're using Create React Native App or Expo CLI, console logs already appear in the same terminal output as the bundler.

Debugging on a device with Chrome Developer Tools

If you're using Create React Native App or Expo CLI, this is configured for you already.

On iOS devices, open the file RCTWebSocketExecutor.m and change "localhost" to the IP address of your computer, then select "Debug JS Remotely" from the Developer Menu.

On Android 5.0+ devices connected via USB, you can use the adb command line tool to setup port forwarding from the device to your computer:

adb reverse tcp:8081 tcp:8081

Alternatively, select "Dev Settings" from the Developer Menu, then update the "Debug server host for device" setting to match the IP address of your computer.

If you run into any issues, it may be possible that one of your Chrome extensions is interacting in unexpected ways with the debugger. Try disabling all of your extensions and re-enabling them one-by-one until you find the problematic extension.

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.

Edit this page
Last updated on
- + diff --git a/docs/0.62/devsettings.html b/docs/0.62/devsettings.html index dfb19c34615..d4badb94cd2 100644 --- a/docs/0.62/devsettings.html +++ b/docs/0.62/devsettings.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

DevSettings

The DevSettings module exposes methods for customizing settings for developers in development.

Reference

Methods

addMenuItem()

static addMenuItem(title: string, handler: function)

Add a custom menu item to the developer menu:

DevSettings.addMenuItem('Show Secret Dev Screen', () => {
Alert.alert('Showing secret dev screen!');
});

reload()

static reload()

Reload the application. Can be invoked directly or on user interaction:

<Button title="Reload" onPress={() => DevSettings.reload()} />
Edit this page
Last updated on
- + diff --git a/docs/0.62/devsettings/index.html b/docs/0.62/devsettings/index.html index dfb19c34615..d4badb94cd2 100644 --- a/docs/0.62/devsettings/index.html +++ b/docs/0.62/devsettings/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

DevSettings

The DevSettings module exposes methods for customizing settings for developers in development.

Reference

Methods

addMenuItem()

static addMenuItem(title: string, handler: function)

Add a custom menu item to the developer menu:

DevSettings.addMenuItem('Show Secret Dev Screen', () => {
Alert.alert('Showing secret dev screen!');
});

reload()

static reload()

Reload the application. Can be invoked directly or on user interaction:

<Button title="Reload" onPress={() => DevSettings.reload()} />
Edit this page
Last updated on
- + diff --git a/docs/0.62/dimensions.html b/docs/0.62/dimensions.html index 65a71e6585a..cb1dc8fc8b8 100644 --- a/docs/0.62/dimensions.html +++ b/docs/0.62/dimensions.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Dimensions

useWindowDimensions is the preferred API for React components. Unlike Dimensions, it updates as the window's dimensions update. This works nicely with the React paradigm.

import { Dimensions } from 'react-native';

You can get the application window's width and height using the following code:

const windowWidth = Dimensions.get('window').width;
const windowHeight = Dimensions.get('window').height;

Although dimensions are available immediately, they may change (e.g due to device rotation, foldable devices etc) so any rendering logic or styles that depend on these constants should try to call this function on every render, rather than caching the value (for example, using inline styles rather than setting a value in a StyleSheet).

If you are targeting foldable devices or devices which can change the screen size or app window size, you can use the event listener available in the Dimensions module as shown in the below example.

Example

Reference

Methods

addEventListener()

static addEventListener(type, handler)

Add an event handler. Supported events:

  • change: Fires when a property within the Dimensions object changes. The argument to the event handler is an object with window and screen properties whose values are the same as the return values of Dimensions.get('window') and Dimensions.get('screen'), respectively.
    • window - Size of the visible Application window
    • screen - Size of the device's screen

get()

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.

Example: const {height, width} = Dimensions.get('window');

Parameters:

NameTypeRequiredDescription
dimstringYesName of dimension as defined when calling set. @returns {Object?} Value for the dimension.

For Android the window dimension will exclude the size used by the status bar (if not translucent) and bottom navigation bar

removeEventListener()

static removeEventListener(type, handler)

Remove an event handler.

set()

static set(dims)

This should only be called from native code by sending the didUpdateDimensions event.

Parameters:

NameTypeRequiredDescription
dimsobjectYesstring-keyed object of dimensions to set
Edit this page
Last updated on
- + diff --git a/docs/0.62/dimensions/index.html b/docs/0.62/dimensions/index.html index 65a71e6585a..cb1dc8fc8b8 100644 --- a/docs/0.62/dimensions/index.html +++ b/docs/0.62/dimensions/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Dimensions

useWindowDimensions is the preferred API for React components. Unlike Dimensions, it updates as the window's dimensions update. This works nicely with the React paradigm.

import { Dimensions } from 'react-native';

You can get the application window's width and height using the following code:

const windowWidth = Dimensions.get('window').width;
const windowHeight = Dimensions.get('window').height;

Although dimensions are available immediately, they may change (e.g due to device rotation, foldable devices etc) so any rendering logic or styles that depend on these constants should try to call this function on every render, rather than caching the value (for example, using inline styles rather than setting a value in a StyleSheet).

If you are targeting foldable devices or devices which can change the screen size or app window size, you can use the event listener available in the Dimensions module as shown in the below example.

Example

Reference

Methods

addEventListener()

static addEventListener(type, handler)

Add an event handler. Supported events:

  • change: Fires when a property within the Dimensions object changes. The argument to the event handler is an object with window and screen properties whose values are the same as the return values of Dimensions.get('window') and Dimensions.get('screen'), respectively.
    • window - Size of the visible Application window
    • screen - Size of the device's screen

get()

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.

Example: const {height, width} = Dimensions.get('window');

Parameters:

NameTypeRequiredDescription
dimstringYesName of dimension as defined when calling set. @returns {Object?} Value for the dimension.

For Android the window dimension will exclude the size used by the status bar (if not translucent) and bottom navigation bar

removeEventListener()

static removeEventListener(type, handler)

Remove an event handler.

set()

static set(dims)

This should only be called from native code by sending the didUpdateDimensions event.

Parameters:

NameTypeRequiredDescription
dimsobjectYesstring-keyed object of dimensions to set
Edit this page
Last updated on
- + diff --git a/docs/0.62/direct-manipulation.html b/docs/0.62/direct-manipulation.html index 4d6cf881c64..45884454da8 100644 --- a/docs/0.62/direct-manipulation.html +++ b/docs/0.62/direct-manipulation.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
render() {
return (
<TouchableOpacity onPress={() => this.setState({myButtonOpacity: 0.5})}
onPressOut={() => this.setState({myButtonOpacity: 1})}>
<View style={[styles.button, {opacity: this.state.myButtonOpacity}]}>
<Text>Press me!</Text>
</View>
</TouchableOpacity>
)
}

This is computationally intensive compared to the original example - React needs to re-render the component hierarchy each time the opacity changes, even though other properties of the view and its children haven't changed. Usually this overhead isn't a concern but when performing continuous animations and responding to gestures, judiciously optimizing your components can improve your animations' fidelity.

If you look at the implementation of setNativeProps in NativeMethodsMixin you will notice that it is a wrapper around RCTUIManager.updateView - this is the exact same function call that results from re-rendering - see receiveComponent in ReactNativeBaseComponent.

Composite components and setNativeProps

Composite components are not backed by a native view, so you cannot call setNativeProps on them. Consider this example:

If you run this you will immediately see this error: Touchable child must either be native or forward setNativeProps to a native component. This occurs because MyButton isn't directly backed by a native view whose opacity should be set. You can think about it like this: if you define a component with createReactClass you would not expect to be able to set a style prop on it and have that work - you would need to pass the style prop down to a child, unless you are wrapping a native component. Similarly, we are going to forward setNativeProps to a native-backed child component.

Forward setNativeProps to a child

All we need to do is provide a setNativeProps method on our component that calls setNativeProps on the appropriate child with the given arguments.

You can now use MyButton inside of TouchableOpacity! A sidenote for clarity: we used the ref callback syntax here, rather than the traditional string-based ref.

You may have noticed that we passed all of the props down to the child view using {...this.props}. The reason for this is that TouchableOpacity is actually a composite component, and so in addition to depending on setNativeProps on its child, it also requires that the child perform touch handling. To do this, it passes on various props that call back to the TouchableOpacity component. TouchableHighlight, in contrast, is backed by a native view and only requires that we implement setNativeProps.

setNativeProps to clear TextInput value

Another very common use case of setNativeProps is to clear the value of a TextInput. The controlled prop of TextInput can sometimes drop characters when the bufferDelay is low and the user types very quickly. Some developers prefer to skip this prop entirely and instead use setNativeProps to directly manipulate the TextInput value when necessary. For example, the following code demonstrates clearing the input when you tap a button:

Avoiding conflicts with the render function

If you update a property that is also managed by the render function, you might end up with some unpredictable and confusing bugs because anytime the component re-renders and that property changes, whatever value was previously set from setNativeProps will be completely ignored and overridden.

setNativeProps & shouldComponentUpdate

By intelligently applying shouldComponentUpdate you can avoid the unnecessary overhead involved in reconciling unchanged component subtrees, to the point where it may be performant enough to use setState instead of setNativeProps.

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:

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 and you don't need pageX and pageY, 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:

measureLayout(relativeToNativeNode, onSuccess, onFail)

Like measure(), but measures the view relative to 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 findNodeHandle(component).

import { findNodeHandle } from 'react-native';

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().

Edit this page
Last updated on
- + diff --git a/docs/0.62/direct-manipulation/index.html b/docs/0.62/direct-manipulation/index.html index 4d6cf881c64..45884454da8 100644 --- a/docs/0.62/direct-manipulation/index.html +++ b/docs/0.62/direct-manipulation/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
render() {
return (
<TouchableOpacity onPress={() => this.setState({myButtonOpacity: 0.5})}
onPressOut={() => this.setState({myButtonOpacity: 1})}>
<View style={[styles.button, {opacity: this.state.myButtonOpacity}]}>
<Text>Press me!</Text>
</View>
</TouchableOpacity>
)
}

This is computationally intensive compared to the original example - React needs to re-render the component hierarchy each time the opacity changes, even though other properties of the view and its children haven't changed. Usually this overhead isn't a concern but when performing continuous animations and responding to gestures, judiciously optimizing your components can improve your animations' fidelity.

If you look at the implementation of setNativeProps in NativeMethodsMixin you will notice that it is a wrapper around RCTUIManager.updateView - this is the exact same function call that results from re-rendering - see receiveComponent in ReactNativeBaseComponent.

Composite components and setNativeProps

Composite components are not backed by a native view, so you cannot call setNativeProps on them. Consider this example:

If you run this you will immediately see this error: Touchable child must either be native or forward setNativeProps to a native component. This occurs because MyButton isn't directly backed by a native view whose opacity should be set. You can think about it like this: if you define a component with createReactClass you would not expect to be able to set a style prop on it and have that work - you would need to pass the style prop down to a child, unless you are wrapping a native component. Similarly, we are going to forward setNativeProps to a native-backed child component.

Forward setNativeProps to a child

All we need to do is provide a setNativeProps method on our component that calls setNativeProps on the appropriate child with the given arguments.

You can now use MyButton inside of TouchableOpacity! A sidenote for clarity: we used the ref callback syntax here, rather than the traditional string-based ref.

You may have noticed that we passed all of the props down to the child view using {...this.props}. The reason for this is that TouchableOpacity is actually a composite component, and so in addition to depending on setNativeProps on its child, it also requires that the child perform touch handling. To do this, it passes on various props that call back to the TouchableOpacity component. TouchableHighlight, in contrast, is backed by a native view and only requires that we implement setNativeProps.

setNativeProps to clear TextInput value

Another very common use case of setNativeProps is to clear the value of a TextInput. The controlled prop of TextInput can sometimes drop characters when the bufferDelay is low and the user types very quickly. Some developers prefer to skip this prop entirely and instead use setNativeProps to directly manipulate the TextInput value when necessary. For example, the following code demonstrates clearing the input when you tap a button:

Avoiding conflicts with the render function

If you update a property that is also managed by the render function, you might end up with some unpredictable and confusing bugs because anytime the component re-renders and that property changes, whatever value was previously set from setNativeProps will be completely ignored and overridden.

setNativeProps & shouldComponentUpdate

By intelligently applying shouldComponentUpdate you can avoid the unnecessary overhead involved in reconciling unchanged component subtrees, to the point where it may be performant enough to use setState instead of setNativeProps.

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:

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 and you don't need pageX and pageY, 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:

measureLayout(relativeToNativeNode, onSuccess, onFail)

Like measure(), but measures the view relative to 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 findNodeHandle(component).

import { findNodeHandle } from 'react-native';

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().

Edit this page
Last updated on
- + diff --git a/docs/0.62/drawerlayoutandroid.html b/docs/0.62/drawerlayoutandroid.html index bbecf2f1042..59154500ce6 100644 --- a/docs/0.62/drawerlayoutandroid.html +++ b/docs/0.62/drawerlayoutandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

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 side of the window specified by the drawerPosition prop and its width can be set by the drawerWidth prop.

Example

Reference

Props

Inherits View Props.

drawerBackgroundColor

Specifies the background color of the drawer. The default value is white. If you want to set the opacity of the drawer, use rgba. Example:

return (
<DrawerLayoutAndroid drawerBackgroundColor="rgba(0,0,0,0.5)" />
);
TypeRequired
colorNo

drawerLockMode

Specifies the lock mode of the drawer. The drawer can be locked in 3 states:

  • unlocked (default), meaning that the drawer will respond (open/close) to touch gestures.
  • locked-closed, meaning that the drawer will stay closed and not respond to gestures.
  • locked-open, meaning that the drawer will stay opened and not respond to gestures. The drawer may still be opened and closed programmatically (openDrawer/closeDrawer).
TypeRequired
enum('unlocked', 'locked-closed', 'locked-open')No

drawerPosition

Specifies the side of the screen from which the drawer will slide in. By default it is set to left.

TypeRequired
enum('left', 'right')No

drawerWidth

Specifies the width of the drawer, more precisely the width of the view that be pulled in from the edge of the window.

TypeRequired
numberNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

  • 'none' (the default), drags do not dismiss the keyboard.
  • 'on-drag', the keyboard is dismissed when a drag begins.
TypeRequired
enum('none', 'on-drag')No

onDrawerClose

Function called whenever the navigation view has been closed.

TypeRequired
functionNo

onDrawerOpen

Function called whenever the navigation view has been opened.

TypeRequired
functionNo

onDrawerSlide

Function called whenever there is an interaction with the navigation view.

TypeRequired
functionNo

onDrawerStateChanged

Function called when the drawer state has changed. The drawer can be in 3 states:

  • idle, meaning there is no interaction with the navigation view happening at the time
  • dragging, meaning there is currently an interaction with the navigation view
  • settling, meaning that there was an interaction with the navigation view, and the navigation view is now finishing its closing or opening animation
TypeRequired
functionNo

renderNavigationView

The navigation view that will be rendered to the side of the screen and can be pulled in.

TypeRequired
functionYes

statusBarBackgroundColor

Make the drawer take the entire screen and draw the background of the status bar to allow it to open over the status bar. It will only have an effect on API 21+.

TypeRequired
colorNo

Methods

closeDrawer()

closeDrawer();

Closes the drawer.

openDrawer()

openDrawer();

Opens the drawer.

Edit this page
Last updated on
- + diff --git a/docs/0.62/drawerlayoutandroid/index.html b/docs/0.62/drawerlayoutandroid/index.html index bbecf2f1042..59154500ce6 100644 --- a/docs/0.62/drawerlayoutandroid/index.html +++ b/docs/0.62/drawerlayoutandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

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 side of the window specified by the drawerPosition prop and its width can be set by the drawerWidth prop.

Example

Reference

Props

Inherits View Props.

drawerBackgroundColor

Specifies the background color of the drawer. The default value is white. If you want to set the opacity of the drawer, use rgba. Example:

return (
<DrawerLayoutAndroid drawerBackgroundColor="rgba(0,0,0,0.5)" />
);
TypeRequired
colorNo

drawerLockMode

Specifies the lock mode of the drawer. The drawer can be locked in 3 states:

  • unlocked (default), meaning that the drawer will respond (open/close) to touch gestures.
  • locked-closed, meaning that the drawer will stay closed and not respond to gestures.
  • locked-open, meaning that the drawer will stay opened and not respond to gestures. The drawer may still be opened and closed programmatically (openDrawer/closeDrawer).
TypeRequired
enum('unlocked', 'locked-closed', 'locked-open')No

drawerPosition

Specifies the side of the screen from which the drawer will slide in. By default it is set to left.

TypeRequired
enum('left', 'right')No

drawerWidth

Specifies the width of the drawer, more precisely the width of the view that be pulled in from the edge of the window.

TypeRequired
numberNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

  • 'none' (the default), drags do not dismiss the keyboard.
  • 'on-drag', the keyboard is dismissed when a drag begins.
TypeRequired
enum('none', 'on-drag')No

onDrawerClose

Function called whenever the navigation view has been closed.

TypeRequired
functionNo

onDrawerOpen

Function called whenever the navigation view has been opened.

TypeRequired
functionNo

onDrawerSlide

Function called whenever there is an interaction with the navigation view.

TypeRequired
functionNo

onDrawerStateChanged

Function called when the drawer state has changed. The drawer can be in 3 states:

  • idle, meaning there is no interaction with the navigation view happening at the time
  • dragging, meaning there is currently an interaction with the navigation view
  • settling, meaning that there was an interaction with the navigation view, and the navigation view is now finishing its closing or opening animation
TypeRequired
functionNo

renderNavigationView

The navigation view that will be rendered to the side of the screen and can be pulled in.

TypeRequired
functionYes

statusBarBackgroundColor

Make the drawer take the entire screen and draw the background of the status bar to allow it to open over the status bar. It will only have an effect on API 21+.

TypeRequired
colorNo

Methods

closeDrawer()

closeDrawer();

Closes the drawer.

openDrawer()

openDrawer();

Opens the drawer.

Edit this page
Last updated on
- + diff --git a/docs/0.62/easing.html b/docs/0.62/easing.html index eaded7ff44e..a20ebae46f8 100644 --- a/docs/0.62/easing.html +++ b/docs/0.62/easing.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Easing

The Easing module implements common easing functions. This module is used by Animated.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 following methods:

  • back provides a basic animation where the object goes slightly back before moving forward
  • bounce provides a bouncing animation
  • ease provides a basic inertial animation
  • elastic provides a basic spring interaction

Standard functions

Three standard easing functions are provided:

The poly function can be used to implement quartic, quintic, and other higher power functions.

Additional functions

Additional mathematical functions are provided by the following methods:

  • bezier provides a cubic bezier curve
  • circle provides a circular function
  • sin provides a sinusoidal function
  • exp provides an exponential function

The following helpers are used to modify other easing functions.

  • in runs an easing function forwards
  • inOut makes any easing function symmetrical
  • out runs an easing function backwards

Example

Reference

Methods

step0()

static step0(n)

A stepping function, returns 1 for any positive value of n.

step1()

static step1(n)

A stepping function, returns 1 if n is greater than or equal to 1.

linear()

static linear(t)

A linear function, f(t) = t. Position correlates to elapsed time one to one.

http://cubic-bezier.com/#0,0,1,1

ease()

static ease(t)

A basic inertial interaction, similar to an object slowly accelerating to speed.

http://cubic-bezier.com/#.42,0,1,1

quad()

static quad(t)

A quadratic function, f(t) = t * t. Position equals the square of elapsed time.

http://easings.net/#easeInQuad

cubic()

static cubic(t)

A cubic function, f(t) = t * t * t. Position equals the cube of elapsed time.

http://easings.net/#easeInCubic

poly()

static poly(n)

A power function. Position is equal to the Nth power of elapsed time.

n = 4: http://easings.net/#easeInQuart n = 5: http://easings.net/#easeInQuint

sin()

static sin(t)

A sinusoidal function.

http://easings.net/#easeInSine

circle()

static circle(t)

A circular function.

http://easings.net/#easeInCirc

exp()

static exp(t)

An exponential function.

http://easings.net/#easeInExpo

elastic()

static elastic(bounciness)

A basic elastic interaction, similar to a spring oscillating back and forth.

Default bounciness is 1, which overshoots a little bit once. 0 bounciness doesn't overshoot at all, and bounciness of N > 1 will overshoot about N times.

http://easings.net/#easeInElastic

back()

static back(s)

Use with Animated.parallel() to create a basic effect where the object animates back slightly as the animation starts.

bounce()

static bounce(t)

Provides a basic bouncing effect.

http://easings.net/#easeInBounce

bezier()

static bezier(x1, y1, x2, y2)

Provides a cubic bezier curve, equivalent to CSS Transitions' transition-timing-function.

A useful tool to visualize cubic bezier curves can be found at http://cubic-bezier.com/

in()

static in easing;

Runs an easing function forwards.

out()

static out(easing)

Runs an easing function backwards.

inOut()

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.

Edit this page
Last updated on
- + diff --git a/docs/0.62/easing/index.html b/docs/0.62/easing/index.html index eaded7ff44e..a20ebae46f8 100644 --- a/docs/0.62/easing/index.html +++ b/docs/0.62/easing/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Easing

The Easing module implements common easing functions. This module is used by Animated.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 following methods:

  • back provides a basic animation where the object goes slightly back before moving forward
  • bounce provides a bouncing animation
  • ease provides a basic inertial animation
  • elastic provides a basic spring interaction

Standard functions

Three standard easing functions are provided:

The poly function can be used to implement quartic, quintic, and other higher power functions.

Additional functions

Additional mathematical functions are provided by the following methods:

  • bezier provides a cubic bezier curve
  • circle provides a circular function
  • sin provides a sinusoidal function
  • exp provides an exponential function

The following helpers are used to modify other easing functions.

  • in runs an easing function forwards
  • inOut makes any easing function symmetrical
  • out runs an easing function backwards

Example

Reference

Methods

step0()

static step0(n)

A stepping function, returns 1 for any positive value of n.

step1()

static step1(n)

A stepping function, returns 1 if n is greater than or equal to 1.

linear()

static linear(t)

A linear function, f(t) = t. Position correlates to elapsed time one to one.

http://cubic-bezier.com/#0,0,1,1

ease()

static ease(t)

A basic inertial interaction, similar to an object slowly accelerating to speed.

http://cubic-bezier.com/#.42,0,1,1

quad()

static quad(t)

A quadratic function, f(t) = t * t. Position equals the square of elapsed time.

http://easings.net/#easeInQuad

cubic()

static cubic(t)

A cubic function, f(t) = t * t * t. Position equals the cube of elapsed time.

http://easings.net/#easeInCubic

poly()

static poly(n)

A power function. Position is equal to the Nth power of elapsed time.

n = 4: http://easings.net/#easeInQuart n = 5: http://easings.net/#easeInQuint

sin()

static sin(t)

A sinusoidal function.

http://easings.net/#easeInSine

circle()

static circle(t)

A circular function.

http://easings.net/#easeInCirc

exp()

static exp(t)

An exponential function.

http://easings.net/#easeInExpo

elastic()

static elastic(bounciness)

A basic elastic interaction, similar to a spring oscillating back and forth.

Default bounciness is 1, which overshoots a little bit once. 0 bounciness doesn't overshoot at all, and bounciness of N > 1 will overshoot about N times.

http://easings.net/#easeInElastic

back()

static back(s)

Use with Animated.parallel() to create a basic effect where the object animates back slightly as the animation starts.

bounce()

static bounce(t)

Provides a basic bouncing effect.

http://easings.net/#easeInBounce

bezier()

static bezier(x1, y1, x2, y2)

Provides a cubic bezier curve, equivalent to CSS Transitions' transition-timing-function.

A useful tool to visualize cubic bezier curves can be found at http://cubic-bezier.com/

in()

static in easing;

Runs an easing function forwards.

out()

static out(easing)

Runs an easing function backwards.

inOut()

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.

Edit this page
Last updated on
- + diff --git a/docs/0.62/environment-setup.html b/docs/0.62/environment-setup.html index 4f043a8aa67..83b9808848f 100644 --- a/docs/0.62/environment-setup.html +++ b/docs/0.62/environment-setup.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
cd AwesomeProject
npm start # you can also use: expo start

This will start a development server for you.

Running your React Native application

Install the Expo client app on your iOS or Android phone and connect to the same wireless network as your computer. On Android, use the Expo app to scan the QR code from your terminal to open your project. On iOS, use the built-in QR code scanner of the Camera app.

Modifying your app

Now that you have successfully run the app, let's modify it. Open App.js in your text editor of choice and edit some lines. The application should reload automatically once you save your changes.

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

Expo also has docs you can reference if you have questions specific to the tool. You can also ask for help at Expo forums.

These tools help you get started quickly, but before committing to building your app with Expo CLI, read about the limitations.

If you have a problem with Expo, before creating a new issue, please see if there's an existing issue about it:

If you're curious to learn more about React Native, check out the Introduction to React Native.

Running your app on a simulator or virtual device

Expo CLI allows you to run your React Native app on a physical device without setting up a development environment. If you want to run your app on the iOS Simulator or an Android Virtual Device, please refer to the instructions for "React Native CLI Quickstart" to learn how to install Xcode or set up your Android development environment.

Once you've set these up, you can launch your app on an Android Virtual Device by running npm run android, or on the iOS Simulator by running npm run ios (macOS only).

Caveats

Because you don't build any native code when using Expo to create a project, it's not possible to include custom native modules beyond the React Native APIs and components that are available in the Expo client app.

If you know that you'll eventually need to include your own native code, Expo is still a good way to get started. In that case you'll need to "eject" eventually to create your own native builds. If you do eject, the "React Native CLI Quickstart" instructions will be required to continue working on your project.

Expo CLI configures your project to use the most recent React Native version that is supported by the Expo client app. The Expo client app usually gains support for a given React Native version about a week after the React Native version is released as stable. You can check this document to find out what versions are supported.

If you're integrating React Native into an existing project, you'll want to skip Expo CLI and go directly to setting up the native build environment. Select "React Native CLI Quickstart" above for instructions on configuring a native build environment for React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.62/environment-setup/index.html b/docs/0.62/environment-setup/index.html index 4f043a8aa67..83b9808848f 100644 --- a/docs/0.62/environment-setup/index.html +++ b/docs/0.62/environment-setup/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
cd AwesomeProject
npm start # you can also use: expo start

This will start a development server for you.

Running your React Native application

Install the Expo client app on your iOS or Android phone and connect to the same wireless network as your computer. On Android, use the Expo app to scan the QR code from your terminal to open your project. On iOS, use the built-in QR code scanner of the Camera app.

Modifying your app

Now that you have successfully run the app, let's modify it. Open App.js in your text editor of choice and edit some lines. The application should reload automatically once you save your changes.

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

Expo also has docs you can reference if you have questions specific to the tool. You can also ask for help at Expo forums.

These tools help you get started quickly, but before committing to building your app with Expo CLI, read about the limitations.

If you have a problem with Expo, before creating a new issue, please see if there's an existing issue about it:

If you're curious to learn more about React Native, check out the Introduction to React Native.

Running your app on a simulator or virtual device

Expo CLI allows you to run your React Native app on a physical device without setting up a development environment. If you want to run your app on the iOS Simulator or an Android Virtual Device, please refer to the instructions for "React Native CLI Quickstart" to learn how to install Xcode or set up your Android development environment.

Once you've set these up, you can launch your app on an Android Virtual Device by running npm run android, or on the iOS Simulator by running npm run ios (macOS only).

Caveats

Because you don't build any native code when using Expo to create a project, it's not possible to include custom native modules beyond the React Native APIs and components that are available in the Expo client app.

If you know that you'll eventually need to include your own native code, Expo is still a good way to get started. In that case you'll need to "eject" eventually to create your own native builds. If you do eject, the "React Native CLI Quickstart" instructions will be required to continue working on your project.

Expo CLI configures your project to use the most recent React Native version that is supported by the Expo client app. The Expo client app usually gains support for a given React Native version about a week after the React Native version is released as stable. You can check this document to find out what versions are supported.

If you're integrating React Native into an existing project, you'll want to skip Expo CLI and go directly to setting up the native build environment. Select "React Native CLI Quickstart" above for instructions on configuring a native build environment for React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.62/fast-refresh.html b/docs/0.62/fast-refresh.html index 2e8165eccbd..cede3b535ba 100644 --- a/docs/0.62/fast-refresh.html +++ b/docs/0.62/fast-refresh.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Fast Refresh

Fast Refresh is a React Native feature that allows you to get near-instant feedback for changes in your React components. Fast Refresh is enabled by default, and you can toggle "Enable Fast Refresh" in the React Native developer menu. With Fast Refresh enabled, most edits should be visible within a second or two.

How It Works

  • If you edit a module that only exports React component(s), Fast Refresh will update the code only for that module, and re-render your component. You can edit anything in that file, including styles, rendering logic, event handlers, or effects.
  • If you edit a module with exports that aren't React components, Fast Refresh will re-run both that module, and the other modules importing it. So if both Button.js and Modal.js import Theme.js, editing Theme.js will update both components.
  • Finally, if you edit a file that's imported by modules outside of the React tree, Fast Refresh will fall back to doing a full reload. You might have a file which renders a React component but also exports a value that is imported by a non-React component. For example, maybe your component also exports a constant, and a non-React utility module imports it. In that case, consider migrating the query to a separate file and importing it into both files. This will re-enable Fast Refresh to work. Other cases can usually be solved in a similar way.

Error Resilience

If you make a syntax error during a Fast Refresh session, you can fix it and save the file again. The redbox will disappear. Modules with syntax errors are prevented from running, so you won't need to reload the app.

If you make a runtime error during the module initialization (for example, typing Style.create instead of StyleSheet.create), the Fast Refresh session will continue once you fix the error. The redbox will disappear, and the module will be updated.

If you make a mistake that leads to a runtime error inside your component, the Fast Refresh session will also continue after you fix the error. In that case, React will remount your application using the updated code.

If you have error boundaries in your app (which is a good idea for graceful failures in production), they will retry rendering on the next edit after a redbox. In that sense, having an error boundary can prevent you from always getting kicked out to the root app screen. However, keep in mind that error boundaries shouldn't be too granular. They are used by React in production, and should always be designed intentionally.

Limitations

Fast Refresh tries to preserve local React state in the component you're editing, but only if it's safe to do so. Here's a few reasons why you might see local state being reset on every edit to a file:

  • Local state is not preserved for class components (only function components and Hooks preserve state).
  • The module you're editing might have other exports in addition to a React component.
  • Sometimes, a module would export the result of calling higher-order component like createNavigationContainer(MyScreen). If the returned component is a class, state will be reset.

In the longer term, as more of your codebase moves to function components and Hooks, you can expect state to be preserved in more cases.

Tips

  • Fast Refresh preserves React local state in function components (and Hooks) by default.
  • Sometimes you might want to force the state to be reset, and a component to be remounted. For example, this can be handy if you're tweaking an animation that only happens on mount. To do this, you can add // @refresh reset anywhere in the file you're editing. This directive is local to the file, and instructs Fast Refresh to remount components defined in that file on every edit.

Fast Refresh and Hooks

When possible, Fast Refresh attempts to preserve the state of your component between edits. In particular, useState and useRef preserve their previous values as long as you don't change their arguments or the order of the Hook calls.

Hooks with dependencies—such as useEffect, useMemo, and useCallback—will always update during Fast Refresh. Their list of dependencies will be ignored while Fast Refresh is happening.

For example, when you edit useMemo(() => x * 2, [x]) to useMemo(() => x * 10, [x]), it will re-run even though x (the dependency) has not changed. If React didn't do that, your edit wouldn't reflect on the screen!

Sometimes, this can lead to unexpected results. For example, even a useEffect with an empty array of dependencies would still re-run once during Fast Refresh. However, writing code resilient to an occasional re-running of useEffect is a good practice even without Fast Refresh. This makes it easier for you to later introduce new dependencies to it.

Edit this page
Last updated on
- + diff --git a/docs/0.62/fast-refresh/index.html b/docs/0.62/fast-refresh/index.html index 2e8165eccbd..cede3b535ba 100644 --- a/docs/0.62/fast-refresh/index.html +++ b/docs/0.62/fast-refresh/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Fast Refresh

Fast Refresh is a React Native feature that allows you to get near-instant feedback for changes in your React components. Fast Refresh is enabled by default, and you can toggle "Enable Fast Refresh" in the React Native developer menu. With Fast Refresh enabled, most edits should be visible within a second or two.

How It Works

  • If you edit a module that only exports React component(s), Fast Refresh will update the code only for that module, and re-render your component. You can edit anything in that file, including styles, rendering logic, event handlers, or effects.
  • If you edit a module with exports that aren't React components, Fast Refresh will re-run both that module, and the other modules importing it. So if both Button.js and Modal.js import Theme.js, editing Theme.js will update both components.
  • Finally, if you edit a file that's imported by modules outside of the React tree, Fast Refresh will fall back to doing a full reload. You might have a file which renders a React component but also exports a value that is imported by a non-React component. For example, maybe your component also exports a constant, and a non-React utility module imports it. In that case, consider migrating the query to a separate file and importing it into both files. This will re-enable Fast Refresh to work. Other cases can usually be solved in a similar way.

Error Resilience

If you make a syntax error during a Fast Refresh session, you can fix it and save the file again. The redbox will disappear. Modules with syntax errors are prevented from running, so you won't need to reload the app.

If you make a runtime error during the module initialization (for example, typing Style.create instead of StyleSheet.create), the Fast Refresh session will continue once you fix the error. The redbox will disappear, and the module will be updated.

If you make a mistake that leads to a runtime error inside your component, the Fast Refresh session will also continue after you fix the error. In that case, React will remount your application using the updated code.

If you have error boundaries in your app (which is a good idea for graceful failures in production), they will retry rendering on the next edit after a redbox. In that sense, having an error boundary can prevent you from always getting kicked out to the root app screen. However, keep in mind that error boundaries shouldn't be too granular. They are used by React in production, and should always be designed intentionally.

Limitations

Fast Refresh tries to preserve local React state in the component you're editing, but only if it's safe to do so. Here's a few reasons why you might see local state being reset on every edit to a file:

  • Local state is not preserved for class components (only function components and Hooks preserve state).
  • The module you're editing might have other exports in addition to a React component.
  • Sometimes, a module would export the result of calling higher-order component like createNavigationContainer(MyScreen). If the returned component is a class, state will be reset.

In the longer term, as more of your codebase moves to function components and Hooks, you can expect state to be preserved in more cases.

Tips

  • Fast Refresh preserves React local state in function components (and Hooks) by default.
  • Sometimes you might want to force the state to be reset, and a component to be remounted. For example, this can be handy if you're tweaking an animation that only happens on mount. To do this, you can add // @refresh reset anywhere in the file you're editing. This directive is local to the file, and instructs Fast Refresh to remount components defined in that file on every edit.

Fast Refresh and Hooks

When possible, Fast Refresh attempts to preserve the state of your component between edits. In particular, useState and useRef preserve their previous values as long as you don't change their arguments or the order of the Hook calls.

Hooks with dependencies—such as useEffect, useMemo, and useCallback—will always update during Fast Refresh. Their list of dependencies will be ignored while Fast Refresh is happening.

For example, when you edit useMemo(() => x * 2, [x]) to useMemo(() => x * 10, [x]), it will re-run even though x (the dependency) has not changed. If React didn't do that, your edit wouldn't reflect on the screen!

Sometimes, this can lead to unexpected results. For example, even a useEffect with an empty array of dependencies would still re-run once during Fast Refresh. However, writing code resilient to an occasional re-running of useEffect is a good practice even without Fast Refresh. This makes it easier for you to later introduce new dependencies to it.

Edit this page
Last updated on
- + diff --git a/docs/0.62/flatlist.html b/docs/0.62/flatlist.html index 262d0a8601e..ae0d8cded24 100644 --- a/docs/0.62/flatlist.html +++ b/docs/0.62/flatlist.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
this.viewabilityConfig = {
waitForInteraction: true,
viewAreaCoveragePercentThreshold: 95
}
}
<FlatList
viewabilityConfig={this.viewabilityConfig}
...

minimumViewTime

Minimum amount of time (in milliseconds) that an item must be physically viewable before the viewability callback will be fired. A high number means that scrolling through content without stopping will not mark the content as viewable.

viewAreaCoveragePercentThreshold

Percent of viewport that must be covered for a partially occluded item to count as "viewable", 0-100. Fully visible items are always considered viewable. A value of 0 means that a single pixel in the viewport makes the item viewable, and a value of 100 means that an item must be either entirely visible or cover the entire viewport to count as viewable.

itemVisiblePercentThreshold

Similar to viewAreaCoveragePercentThreshold, but considers the percent of the item that is visible, rather than the fraction of the viewable area it covers.

waitForInteraction

Nothing is considered viewable until the user scrolls or recordInteraction is called after render.

viewabilityConfigCallbackPairs

List of ViewabilityConfig/onViewableItemsChanged pairs. A specific onViewableItemsChanged will be called when its corresponding ViewabilityConfig's conditions are met. See ViewabilityHelper.js for flow type and further documentation.

TypeRequired
array of ViewabilityConfigCallbackPairNo

Methods

scrollToEnd()

scrollToEnd([params]);

Scrolls to the end of the content. May be janky without getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectNoSee below.

Valid params keys are:

scrollToIndex()

scrollToIndex(params);

Scrolls to the item at the specified index such that it is positioned in the viewable area such that viewPosition 0 places it at the top, 1 at the bottom, and 0.5 centered in the middle.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

scrollToItem()

scrollToItem(params);

Requires linear scan through data - use scrollToIndex instead if possible.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

scrollToOffset()

scrollToOffset(params);

Scroll to a specific content pixel offset in the list.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

recordInteraction()

recordInteraction();

Tells the list an interaction has occurred, 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()

flashScrollIndicators();

Displays the scroll indicators momentarily.

getNativeScrollRef()

getNativeScrollRef();

Provides a reference to the underlying scroll component

getScrollResponder()

getScrollResponder();

Provides a handle to the underlying scroll responder.

getScrollableNode()

getScrollableNode();

Provides a handle to the underlying scroll node.

Edit this page
Last updated on
- + diff --git a/docs/0.62/flatlist/index.html b/docs/0.62/flatlist/index.html index 262d0a8601e..ae0d8cded24 100644 --- a/docs/0.62/flatlist/index.html +++ b/docs/0.62/flatlist/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
this.viewabilityConfig = {
waitForInteraction: true,
viewAreaCoveragePercentThreshold: 95
}
}
<FlatList
viewabilityConfig={this.viewabilityConfig}
...

minimumViewTime

Minimum amount of time (in milliseconds) that an item must be physically viewable before the viewability callback will be fired. A high number means that scrolling through content without stopping will not mark the content as viewable.

viewAreaCoveragePercentThreshold

Percent of viewport that must be covered for a partially occluded item to count as "viewable", 0-100. Fully visible items are always considered viewable. A value of 0 means that a single pixel in the viewport makes the item viewable, and a value of 100 means that an item must be either entirely visible or cover the entire viewport to count as viewable.

itemVisiblePercentThreshold

Similar to viewAreaCoveragePercentThreshold, but considers the percent of the item that is visible, rather than the fraction of the viewable area it covers.

waitForInteraction

Nothing is considered viewable until the user scrolls or recordInteraction is called after render.

viewabilityConfigCallbackPairs

List of ViewabilityConfig/onViewableItemsChanged pairs. A specific onViewableItemsChanged will be called when its corresponding ViewabilityConfig's conditions are met. See ViewabilityHelper.js for flow type and further documentation.

TypeRequired
array of ViewabilityConfigCallbackPairNo

Methods

scrollToEnd()

scrollToEnd([params]);

Scrolls to the end of the content. May be janky without getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectNoSee below.

Valid params keys are:

scrollToIndex()

scrollToIndex(params);

Scrolls to the item at the specified index such that it is positioned in the viewable area such that viewPosition 0 places it at the top, 1 at the bottom, and 0.5 centered in the middle.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

scrollToItem()

scrollToItem(params);

Requires linear scan through data - use scrollToIndex instead if possible.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

scrollToOffset()

scrollToOffset(params);

Scroll to a specific content pixel offset in the list.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

recordInteraction()

recordInteraction();

Tells the list an interaction has occurred, 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()

flashScrollIndicators();

Displays the scroll indicators momentarily.

getNativeScrollRef()

getNativeScrollRef();

Provides a reference to the underlying scroll component

getScrollResponder()

getScrollResponder();

Provides a handle to the underlying scroll responder.

getScrollableNode()

getScrollableNode();

Provides a handle to the underlying scroll node.

Edit this page
Last updated on
- + diff --git a/docs/0.62/flexbox.html b/docs/0.62/flexbox.html index 5246bb08040..5d0b7e01d6e 100644 --- a/docs/0.62/flexbox.html +++ b/docs/0.62/flexbox.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

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 flexDirection defaulting to column instead of row, and the flex parameter only supporting a single number.

Flex

flex will define how your items are going to “fill” over the available space along your main axis. Space will be divided according to each element's flex property.

In the following example, the red, yellow, and green views are all children in the container view that has flex: 1 set. The red view uses flex: 1 , the yellow view uses flex: 2, and the green view uses flex: 3 . 1+2+3 = 6, which means that the red view will get 1/6 of the space, the yellow 2/6 of the space, and the green 3/6 of the space.

Flex

Flex Direction

flexDirection controls the direction in which the children of a node are laid out. This is also referred to as the main axis. The cross axis is the axis perpendicular to the main axis, or the axis which the wrapping lines are laid out in.

  • row Align children from left to right. If wrapping is enabled, then the next line will start under the first item on the left of the container.

  • column (default value) Align children from top to bottom. If wrapping is enabled, then the next line will start to the right of the first item on the top of the container.

  • row-reverse Align children from right to left. If wrapping is enabled, then the next line will start under the first item on the right of the container.

  • column-reverse Align children from bottom to top. If wrapping is enabled, then the next line will start to the right of the first item on the bottom of the container.

You can learn more here.

Flex Direction

Layout Direction

Layout direction specifies the direction in which children and text in a hierarchy should be laid out. Layout direction also affects what edge start and end refer to. By default, React Native lays out with LTR layout direction. In this mode start refers to left and end refers to right.

  • LTR (default value) Text and children are laid out from left to right. Margin and padding applied to the start of an element are applied on the left side.

  • RTL Text and children are laid out from right to left. Margin and padding applied to the start of an element are applied on the right side.

Justify Content

justifyContent describes how to align children within the main axis of their container. For example, you can use this property to center a child horizontally within a container with flexDirection set to row or vertically within a container with flexDirection set to column.

  • flex-start(default value) Align children of a container to the start of the container's main axis.

  • flex-end Align children of a container to the end of the container's main axis.

  • center Align children of a container in the center of the container's main axis.

  • space-between Evenly space off children across the container's main axis, distributing the remaining space between the children.

  • space-around Evenly space off children across the container's main axis, distributing the remaining space around the children. Compared to space-between, using space-around will result in space being distributed to the beginning of the first child and end of the last child.

  • space-evenly Evenly distribute children within the alignment container along the main axis. The spacing between each pair of adjacent items, the main-start edge and the first item, and the main-end edge and the last item, are all exactly the same.

You can learn more here.

Justify Content

Align Items

alignItems describes how to align children along the cross axis of their container. Align items is very similar to justifyContent but instead of applying to the main axis, alignItems applies to the cross axis.

  • stretch (default value) Stretch children of a container to match the height of the container's cross axis.

  • flex-start Align children of a container to the start of the container's cross axis.

  • flex-end Align children of a container to the end of the container's cross axis.

  • center Align children of a container in the center of the container's cross axis.

  • baseline Align children of a container along a common baseline. Individual children can be set to be the reference baseline for their parents.

For stretch to have an effect, children must not have a fixed dimension along the secondary axis. In the following example, setting alignItems: stretch does nothing until the width: 50 is removed from the children.

You can learn more here.

Align Items

Align Self

alignSelf has the same options and effect as alignItems but instead of affecting the children within a container, you can apply this property to a single child to change its alignment within its parent. alignSelf overrides any option set by the parent with alignItems.

Align Self

Align Content

alignContent defines the distribution of lines along the cross-axis. This only has effect when items are wrapped to multiple lines using flexWrap.

  • flex-start (default value) Align wrapped lines to the start of the container's cross axis.

  • flex-end Align wrapped lines to the end of the container's cross axis.

  • stretch Stretch wrapped lines to match the height of the container's cross axis.

  • center Align wrapped lines in the center of the container's cross axis.

  • space-between Evenly space wrapped lines across the container's main axis, distributing the remaining space between the lines.

  • space-around Evenly space wrapped lines across the container's main axis, distributing the remaining space around the lines. Compared to space-between, using space-around will result in space being distributed to the beginning of the first line and the end of the last line.

You can learn more here.

Align Content

Flex Wrap

The flexWrap property is set on containers and it controls what happens when children overflow the size of the container along the main axis. By default, children are forced into a single line (which can shrink elements). If wrapping is allowed, items are wrapped into multiple lines along the main axis if needed.

When wrapping lines, alignContent can be used to specify how the lines are placed in the container. Learn more here.

Flex Wrap

Flex Basis, Grow, and Shrink

  • flexGrow describes how any space within a container should be distributed among its children along the main axis. After laying out its children, a container will distribute any remaining space according to the flex grow values specified by its children.

    flexGrow accepts any floating point value >= 0, with 0 being the default value. A container will distribute any remaining space among its children weighted by the children’s flexGrow values.

  • flexShrink describes how to shrink children along the main axis in the case in which the total size of the children overflows the size of the container on the main axis. flexShrink is very similar to flexGrow and can be thought of in the same way if any overflowing size is considered to be negative remaining space. These two properties also work well together by allowing children to grow and shrink as needed.

    flexShrink accepts any floating point value >= 0, with 1 being the default value. A container will shrink its children weighted by the children’s flexShrink values.

  • flexBasis is an axis-independent way of providing the default size of an item along the main axis. Setting the flexBasis of a child is similar to setting the width of that child if its parent is a container with flexDirection: row or setting the height of a child if its parent is a container with flexDirection: column. The flexBasis of an item is the default size of that item, the size of the item before any flexGrow and flexShrink calculations are performed.

You can learn more here.

Width and Height

The width property specifies the width of an element's content area. Similarly, the height property specifies the height of an element's content area.

Both width and height can take the following values:

  • auto (default value) React Native calculates the width/height for the element based on its content, whether that is other children, text, or an image.

  • pixels Defines the width/height in absolute pixels. Depending on other styles set on the component, this may or may not be the final dimension of the node.

  • percentage Defines the width or height in percentage of its parent's width or height, respectively.

Absolute & Relative Layout

The position type of an element defines how it is positioned within its parent.

  • relative (default value) By default, an element is positioned relatively. This means an element is positioned according to the normal flow of the layout, and then offset relative to that position based on the values of top, right, bottom, and left. The offset does not affect the position of any sibling or parent elements.

  • absolute When positioned absolutely, an element doesn't take part in the normal layout flow. It is instead laid out independent of its siblings. The position is determined based on the top, right, bottom, and left values.

Absolute & Relative Layoutp

Going Deeper

Check out the interactive yoga playground that you can use to get a better understanding of flexbox.

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.

Additionally, you can see some examples from Wix Engineers.

Edit this page
Last updated on
- + diff --git a/docs/0.62/flexbox/index.html b/docs/0.62/flexbox/index.html index 5246bb08040..5d0b7e01d6e 100644 --- a/docs/0.62/flexbox/index.html +++ b/docs/0.62/flexbox/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

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 flexDirection defaulting to column instead of row, and the flex parameter only supporting a single number.

Flex

flex will define how your items are going to “fill” over the available space along your main axis. Space will be divided according to each element's flex property.

In the following example, the red, yellow, and green views are all children in the container view that has flex: 1 set. The red view uses flex: 1 , the yellow view uses flex: 2, and the green view uses flex: 3 . 1+2+3 = 6, which means that the red view will get 1/6 of the space, the yellow 2/6 of the space, and the green 3/6 of the space.

Flex

Flex Direction

flexDirection controls the direction in which the children of a node are laid out. This is also referred to as the main axis. The cross axis is the axis perpendicular to the main axis, or the axis which the wrapping lines are laid out in.

  • row Align children from left to right. If wrapping is enabled, then the next line will start under the first item on the left of the container.

  • column (default value) Align children from top to bottom. If wrapping is enabled, then the next line will start to the right of the first item on the top of the container.

  • row-reverse Align children from right to left. If wrapping is enabled, then the next line will start under the first item on the right of the container.

  • column-reverse Align children from bottom to top. If wrapping is enabled, then the next line will start to the right of the first item on the bottom of the container.

You can learn more here.

Flex Direction

Layout Direction

Layout direction specifies the direction in which children and text in a hierarchy should be laid out. Layout direction also affects what edge start and end refer to. By default, React Native lays out with LTR layout direction. In this mode start refers to left and end refers to right.

  • LTR (default value) Text and children are laid out from left to right. Margin and padding applied to the start of an element are applied on the left side.

  • RTL Text and children are laid out from right to left. Margin and padding applied to the start of an element are applied on the right side.

Justify Content

justifyContent describes how to align children within the main axis of their container. For example, you can use this property to center a child horizontally within a container with flexDirection set to row or vertically within a container with flexDirection set to column.

  • flex-start(default value) Align children of a container to the start of the container's main axis.

  • flex-end Align children of a container to the end of the container's main axis.

  • center Align children of a container in the center of the container's main axis.

  • space-between Evenly space off children across the container's main axis, distributing the remaining space between the children.

  • space-around Evenly space off children across the container's main axis, distributing the remaining space around the children. Compared to space-between, using space-around will result in space being distributed to the beginning of the first child and end of the last child.

  • space-evenly Evenly distribute children within the alignment container along the main axis. The spacing between each pair of adjacent items, the main-start edge and the first item, and the main-end edge and the last item, are all exactly the same.

You can learn more here.

Justify Content

Align Items

alignItems describes how to align children along the cross axis of their container. Align items is very similar to justifyContent but instead of applying to the main axis, alignItems applies to the cross axis.

  • stretch (default value) Stretch children of a container to match the height of the container's cross axis.

  • flex-start Align children of a container to the start of the container's cross axis.

  • flex-end Align children of a container to the end of the container's cross axis.

  • center Align children of a container in the center of the container's cross axis.

  • baseline Align children of a container along a common baseline. Individual children can be set to be the reference baseline for their parents.

For stretch to have an effect, children must not have a fixed dimension along the secondary axis. In the following example, setting alignItems: stretch does nothing until the width: 50 is removed from the children.

You can learn more here.

Align Items

Align Self

alignSelf has the same options and effect as alignItems but instead of affecting the children within a container, you can apply this property to a single child to change its alignment within its parent. alignSelf overrides any option set by the parent with alignItems.

Align Self

Align Content

alignContent defines the distribution of lines along the cross-axis. This only has effect when items are wrapped to multiple lines using flexWrap.

  • flex-start (default value) Align wrapped lines to the start of the container's cross axis.

  • flex-end Align wrapped lines to the end of the container's cross axis.

  • stretch Stretch wrapped lines to match the height of the container's cross axis.

  • center Align wrapped lines in the center of the container's cross axis.

  • space-between Evenly space wrapped lines across the container's main axis, distributing the remaining space between the lines.

  • space-around Evenly space wrapped lines across the container's main axis, distributing the remaining space around the lines. Compared to space-between, using space-around will result in space being distributed to the beginning of the first line and the end of the last line.

You can learn more here.

Align Content

Flex Wrap

The flexWrap property is set on containers and it controls what happens when children overflow the size of the container along the main axis. By default, children are forced into a single line (which can shrink elements). If wrapping is allowed, items are wrapped into multiple lines along the main axis if needed.

When wrapping lines, alignContent can be used to specify how the lines are placed in the container. Learn more here.

Flex Wrap

Flex Basis, Grow, and Shrink

  • flexGrow describes how any space within a container should be distributed among its children along the main axis. After laying out its children, a container will distribute any remaining space according to the flex grow values specified by its children.

    flexGrow accepts any floating point value >= 0, with 0 being the default value. A container will distribute any remaining space among its children weighted by the children’s flexGrow values.

  • flexShrink describes how to shrink children along the main axis in the case in which the total size of the children overflows the size of the container on the main axis. flexShrink is very similar to flexGrow and can be thought of in the same way if any overflowing size is considered to be negative remaining space. These two properties also work well together by allowing children to grow and shrink as needed.

    flexShrink accepts any floating point value >= 0, with 1 being the default value. A container will shrink its children weighted by the children’s flexShrink values.

  • flexBasis is an axis-independent way of providing the default size of an item along the main axis. Setting the flexBasis of a child is similar to setting the width of that child if its parent is a container with flexDirection: row or setting the height of a child if its parent is a container with flexDirection: column. The flexBasis of an item is the default size of that item, the size of the item before any flexGrow and flexShrink calculations are performed.

You can learn more here.

Width and Height

The width property specifies the width of an element's content area. Similarly, the height property specifies the height of an element's content area.

Both width and height can take the following values:

  • auto (default value) React Native calculates the width/height for the element based on its content, whether that is other children, text, or an image.

  • pixels Defines the width/height in absolute pixels. Depending on other styles set on the component, this may or may not be the final dimension of the node.

  • percentage Defines the width or height in percentage of its parent's width or height, respectively.

Absolute & Relative Layout

The position type of an element defines how it is positioned within its parent.

  • relative (default value) By default, an element is positioned relatively. This means an element is positioned according to the normal flow of the layout, and then offset relative to that position based on the values of top, right, bottom, and left. The offset does not affect the position of any sibling or parent elements.

  • absolute When positioned absolutely, an element doesn't take part in the normal layout flow. It is instead laid out independent of its siblings. The position is determined based on the top, right, bottom, and left values.

Absolute & Relative Layoutp

Going Deeper

Check out the interactive yoga playground that you can use to get a better understanding of flexbox.

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.

Additionally, you can see some examples from Wix Engineers.

Edit this page
Last updated on
- + diff --git a/docs/0.62/geolocation.html b/docs/0.62/geolocation.html index 48fc7f60b40..7d687270963 100644 --- a/docs/0.62/geolocation.html +++ b/docs/0.62/geolocation.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 Geolocation

Deprecated. Use @react-native-community/geolocation instead.

The Geolocation API extends the Geolocation web spec.

As a browser polyfill, this API is available through the navigator.geolocation global - you do not need to import it.

On Android, this uses the android.location API. This API is not recommended by Google because it is less accurate and slower than the recommended Google Location Services API. In order to use it with React Native, use the react-native-geolocation-service module.

Configuration and Permissions

iOS

You need to include the NSLocationWhenInUseUsageDescription key in Info.plist to enable geolocation when using the app. Geolocation is enabled by default when you create a project with react-native init.

In order to enable geolocation in the background, you need to include the 'NSLocationAlwaysUsageDescription' key in Info.plist and add location as a background mode in the 'Capabilities' tab in Xcode.

If you are using CocoaPods for React Native, make sure to include the RCTGeolocation sub-podspec.

Android

To request access to location, you need to add the following line to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Android API >= 18 Positions will also contain a mocked boolean to indicate if position was created from a mock provider.

Android API >= 23 Requires an additional step to check for, and request the ACCESS_FINE_LOCATION permission using the PermissionsAndroid API. Failure to do so may result in a hard crash.

Methods

Reference

Methods

setRNConfiguration()

geolocation.setRNConfiguration(config);

Sets configuration options that will be used in all location requests.

Parameters:

NameTypeRequiredDescription
configobjectYesSee below.

Supported options:

  • skipPermissionRequests (boolean, iOS-only) - Defaults to false. If true, you must request permissions before using Geolocation APIs.

requestAuthorization()

geolocation.requestAuthorization();

Request suitable Location permission based on the key configured on pList. If NSLocationAlwaysUsageDescription is set, it will request Always authorization, although if NSLocationWhenInUseUsageDescription is set, it will request InUse authorization.

getCurrentPosition()

geolocation.getCurrentPosition(
geo_success,
[geo_error],
[geo_options]
);

Invokes the success callback once with the latest location info.

Parameters:

NameTypeRequiredDescription
geo_successfunctionYesInvoked with latest location info.
geo_errorfunctionNoInvoked whenever an error is encountered.
geo_optionsobjectNoSee below.

Supported options:

  • timeout (ms) - Is a positive value representing the maximum length of time (in milliseconds) the device is allowed to take in order to return a position. Defaults to INFINITY.
  • maximumAge (ms) - Is a positive value indicating the maximum age in milliseconds of a possible cached position that is acceptable to return. If set to 0, it means that the device cannot use a cached position and must attempt to retrieve the real current position. If set to Infinity the device will always return a cached position regardless of its age. Defaults to INFINITY.
  • enableHighAccuracy (bool) - Is a boolean representing if to use GPS or not. If set to true, a GPS position will be requested. If set to false, a WIFI location will be requested.

watchPosition()

geolocation.watchPosition(success, [error], [options]);

Invokes the success callback whenever the location changes. Returns a watchId (number).

Parameters:

NameTypeRequiredDescription
successfunctionYesInvoked whenever the location changes.
errorfunctionNoInvoked whenever an error is encountered.
optionsobjectNoSee below.

Supported options:

  • timeout (ms) - Is a positive value representing the maximum length of time (in milliseconds) the device is allowed to take in order to return a position. Defaults to INFINITY.
  • maximumAge (ms) - Is a positive value indicating the maximum age in milliseconds of a possible cached position that is acceptable to return. If set to 0, it means that the device cannot use a cached position and must attempt to retrieve the real current position. If set to Infinity the device will always return a cached position regardless of its age. Defaults to INFINITY.
  • enableHighAccuracy (bool) - Is a boolean representing if to use GPS or not. If set to true, a GPS position will be requested. If set to false, a WIFI location will be requested.
  • distanceFilter (m) - The minimum distance from the previous location to exceed before returning a new location. Set to 0 to not filter locations. Defaults to 100m.
  • useSignificantChanges (bool) - Uses the battery-efficient native significant changes APIs to return locations. Locations will only be returned when the device detects a significant distance has been breached. Defaults to FALSE.

clearWatch()

geolocation.clearWatch(watchID);

Parameters:

NameTypeRequiredDescription
watchIDnumberYesId as returned by watchPosition().

stopObserving()

geolocation.stopObserving();

Stops observing for device location changes. In addition, it removes all listeners previously registered.

Notice that this method has only effect if the geolocation.watchPosition(successCallback, errorCallback) method was previously invoked.

Edit this page
Last updated on
- + diff --git a/docs/0.62/geolocation/index.html b/docs/0.62/geolocation/index.html index 48fc7f60b40..7d687270963 100644 --- a/docs/0.62/geolocation/index.html +++ b/docs/0.62/geolocation/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 Geolocation

Deprecated. Use @react-native-community/geolocation instead.

The Geolocation API extends the Geolocation web spec.

As a browser polyfill, this API is available through the navigator.geolocation global - you do not need to import it.

On Android, this uses the android.location API. This API is not recommended by Google because it is less accurate and slower than the recommended Google Location Services API. In order to use it with React Native, use the react-native-geolocation-service module.

Configuration and Permissions

iOS

You need to include the NSLocationWhenInUseUsageDescription key in Info.plist to enable geolocation when using the app. Geolocation is enabled by default when you create a project with react-native init.

In order to enable geolocation in the background, you need to include the 'NSLocationAlwaysUsageDescription' key in Info.plist and add location as a background mode in the 'Capabilities' tab in Xcode.

If you are using CocoaPods for React Native, make sure to include the RCTGeolocation sub-podspec.

Android

To request access to location, you need to add the following line to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Android API >= 18 Positions will also contain a mocked boolean to indicate if position was created from a mock provider.

Android API >= 23 Requires an additional step to check for, and request the ACCESS_FINE_LOCATION permission using the PermissionsAndroid API. Failure to do so may result in a hard crash.

Methods

Reference

Methods

setRNConfiguration()

geolocation.setRNConfiguration(config);

Sets configuration options that will be used in all location requests.

Parameters:

NameTypeRequiredDescription
configobjectYesSee below.

Supported options:

  • skipPermissionRequests (boolean, iOS-only) - Defaults to false. If true, you must request permissions before using Geolocation APIs.

requestAuthorization()

geolocation.requestAuthorization();

Request suitable Location permission based on the key configured on pList. If NSLocationAlwaysUsageDescription is set, it will request Always authorization, although if NSLocationWhenInUseUsageDescription is set, it will request InUse authorization.

getCurrentPosition()

geolocation.getCurrentPosition(
geo_success,
[geo_error],
[geo_options]
);

Invokes the success callback once with the latest location info.

Parameters:

NameTypeRequiredDescription
geo_successfunctionYesInvoked with latest location info.
geo_errorfunctionNoInvoked whenever an error is encountered.
geo_optionsobjectNoSee below.

Supported options:

  • timeout (ms) - Is a positive value representing the maximum length of time (in milliseconds) the device is allowed to take in order to return a position. Defaults to INFINITY.
  • maximumAge (ms) - Is a positive value indicating the maximum age in milliseconds of a possible cached position that is acceptable to return. If set to 0, it means that the device cannot use a cached position and must attempt to retrieve the real current position. If set to Infinity the device will always return a cached position regardless of its age. Defaults to INFINITY.
  • enableHighAccuracy (bool) - Is a boolean representing if to use GPS or not. If set to true, a GPS position will be requested. If set to false, a WIFI location will be requested.

watchPosition()

geolocation.watchPosition(success, [error], [options]);

Invokes the success callback whenever the location changes. Returns a watchId (number).

Parameters:

NameTypeRequiredDescription
successfunctionYesInvoked whenever the location changes.
errorfunctionNoInvoked whenever an error is encountered.
optionsobjectNoSee below.

Supported options:

  • timeout (ms) - Is a positive value representing the maximum length of time (in milliseconds) the device is allowed to take in order to return a position. Defaults to INFINITY.
  • maximumAge (ms) - Is a positive value indicating the maximum age in milliseconds of a possible cached position that is acceptable to return. If set to 0, it means that the device cannot use a cached position and must attempt to retrieve the real current position. If set to Infinity the device will always return a cached position regardless of its age. Defaults to INFINITY.
  • enableHighAccuracy (bool) - Is a boolean representing if to use GPS or not. If set to true, a GPS position will be requested. If set to false, a WIFI location will be requested.
  • distanceFilter (m) - The minimum distance from the previous location to exceed before returning a new location. Set to 0 to not filter locations. Defaults to 100m.
  • useSignificantChanges (bool) - Uses the battery-efficient native significant changes APIs to return locations. Locations will only be returned when the device detects a significant distance has been breached. Defaults to FALSE.

clearWatch()

geolocation.clearWatch(watchID);

Parameters:

NameTypeRequiredDescription
watchIDnumberYesId as returned by watchPosition().

stopObserving()

geolocation.stopObserving();

Stops observing for device location changes. In addition, it removes all listeners previously registered.

Notice that this method has only effect if the geolocation.watchPosition(successCallback, errorCallback) method was previously invoked.

Edit this page
Last updated on
- + diff --git a/docs/0.62/gesture-responder-system.html b/docs/0.62/gesture-responder-system.html index 94d0e565c05..c1e08087379 100644 --- a/docs/0.62/gesture-responder-system.html +++ b/docs/0.62/gesture-responder-system.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

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.

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 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 happening
  • View.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 finger
  • View.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 release
  • View.props.onResponderTerminate: (evt) => {} - The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, 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:

  • nativeEvent
    • changedTouches - Array of all touch events that have changed since the last event
    • identifier - The ID of the touch
    • locationX - The X position of the touch, relative to the element
    • locationY - The Y position of the touch, relative to the element
    • pageX - The X position of the touch, relative to the root element
    • pageY - The Y position of the touch, relative to the root element
    • target - The node id of the element receiving the touch event
    • timestamp - A time identifier for the touch, useful for velocity calculation
    • touches - 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.

Edit this page
Last updated on
- + diff --git a/docs/0.62/gesture-responder-system/index.html b/docs/0.62/gesture-responder-system/index.html index 94d0e565c05..c1e08087379 100644 --- a/docs/0.62/gesture-responder-system/index.html +++ b/docs/0.62/gesture-responder-system/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

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.

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 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 happening
  • View.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 finger
  • View.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 release
  • View.props.onResponderTerminate: (evt) => {} - The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, 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:

  • nativeEvent
    • changedTouches - Array of all touch events that have changed since the last event
    • identifier - The ID of the touch
    • locationX - The X position of the touch, relative to the element
    • locationY - The Y position of the touch, relative to the element
    • pageX - The X position of the touch, relative to the root element
    • pageY - The Y position of the touch, relative to the root element
    • target - The node id of the element receiving the touch event
    • timestamp - A time identifier for the touch, useful for velocity calculation
    • touches - 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.

Edit this page
Last updated on
- + diff --git a/docs/0.62/getting-started.html b/docs/0.62/getting-started.html index 80177fad046..f3ce74deb05 100644 --- a/docs/0.62/getting-started.html +++ b/docs/0.62/getting-started.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Introduction

Welcome to the very start of your React Native journey! If you're looking for environment setup instructions, they've moved to their own section. Continue reading for an introduction to the documentation, Native Components, React, and more!

Many different kinds of people use React Native: from advanced iOS developers to React beginners, to people getting started programming for the first time in their career. These docs were written for all learners, no matter their experience level or background.

How to use these docs

You can start here and read through these docs linearly like a book; or you can read the specific sections you need. Already familiar with React? You can skip that section—or read it for a light refresher.

Prerequisites

To work with React Native, you will need to have an understanding of JavaScript fundamentals. If you’re new to JavaScript or need a refresher, you can dive in or brush up at Mozilla Developer Network.

While we do our best to assume no prior knowledge of React, Android, or iOS development, these are valuable topics of study for the aspiring React Native developer. Where sensible, we have linked to resources and articles that go more in depth.

Interactive examples

This introduction lets you get started immediately in your browser with interactive examples like this one:

The above is a Snack Player. It’s a handy tool created by Expo to embed and run React Native projects and share how they render in platforms like Android and iOS. The code is live and editable, so you can play directly with it in your browser. Go ahead and try changing the "Try editing me!" text above to "Hello, world!"

Optionally, if you want to setup a local development environment, you can follow our guide to setting up your environment on your local machine and paste the code examples into your App.js file there. (If you are a web developer, you may already have a local environment set up for mobile browser testing!)

Function Components and Class Components

With React, you can make components using either classes or functions. Originally, class components were the only components that could have state. But since the introduction of React's Hooks API, you can add state and more to function components.

Hooks were introduced in React Native 0.59., and because Hooks are the future-facing way to write your React components, we wrote this introduction using function component examples. Where useful, we also cover class components under a toggle like so:

You can find more examples of class components in previous versions of this documentation.

Developer Notes

People from many different development backgrounds are learning React Native. You may have experience with a range of technologies, from web to Android to iOS and more. We try to write for developers from all backgrounds. Sometimes we provide explanations specific to one platform or another like so:

Web developers may be familiar with this concept.

Formatting

Menu paths are written in bold and use carets to navigate submenus. Example: Android Studio > Preferences

Now that you know how this guide works, it's time to get to know the foundation of React Native: Native Components.

Edit this page
Last updated on
- + diff --git a/docs/0.62/getting-started/index.html b/docs/0.62/getting-started/index.html index 80177fad046..f3ce74deb05 100644 --- a/docs/0.62/getting-started/index.html +++ b/docs/0.62/getting-started/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Introduction

Welcome to the very start of your React Native journey! If you're looking for environment setup instructions, they've moved to their own section. Continue reading for an introduction to the documentation, Native Components, React, and more!

Many different kinds of people use React Native: from advanced iOS developers to React beginners, to people getting started programming for the first time in their career. These docs were written for all learners, no matter their experience level or background.

How to use these docs

You can start here and read through these docs linearly like a book; or you can read the specific sections you need. Already familiar with React? You can skip that section—or read it for a light refresher.

Prerequisites

To work with React Native, you will need to have an understanding of JavaScript fundamentals. If you’re new to JavaScript or need a refresher, you can dive in or brush up at Mozilla Developer Network.

While we do our best to assume no prior knowledge of React, Android, or iOS development, these are valuable topics of study for the aspiring React Native developer. Where sensible, we have linked to resources and articles that go more in depth.

Interactive examples

This introduction lets you get started immediately in your browser with interactive examples like this one:

The above is a Snack Player. It’s a handy tool created by Expo to embed and run React Native projects and share how they render in platforms like Android and iOS. The code is live and editable, so you can play directly with it in your browser. Go ahead and try changing the "Try editing me!" text above to "Hello, world!"

Optionally, if you want to setup a local development environment, you can follow our guide to setting up your environment on your local machine and paste the code examples into your App.js file there. (If you are a web developer, you may already have a local environment set up for mobile browser testing!)

Function Components and Class Components

With React, you can make components using either classes or functions. Originally, class components were the only components that could have state. But since the introduction of React's Hooks API, you can add state and more to function components.

Hooks were introduced in React Native 0.59., and because Hooks are the future-facing way to write your React components, we wrote this introduction using function component examples. Where useful, we also cover class components under a toggle like so:

You can find more examples of class components in previous versions of this documentation.

Developer Notes

People from many different development backgrounds are learning React Native. You may have experience with a range of technologies, from web to Android to iOS and more. We try to write for developers from all backgrounds. Sometimes we provide explanations specific to one platform or another like so:

Web developers may be familiar with this concept.

Formatting

Menu paths are written in bold and use carets to navigate submenus. Example: Android Studio > Preferences

Now that you know how this guide works, it's time to get to know the foundation of React Native: Native Components.

Edit this page
Last updated on
- + diff --git a/docs/0.62/handling-text-input.html b/docs/0.62/handling-text-input.html index dac055a0a42..f8ed9b67d12 100644 --- a/docs/0.62/handling-text-input.html +++ b/docs/0.62/handling-text-input.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Handling Text Input

TextInput is a Core Component that allows the user to enter text. It has an onChangeText prop that takes a function to be called every time the text changed, and an onSubmitEditing prop that takes a function to be called when the text is submitted.

For example, let's say that as the user types, you're translating their words into a different language. In this new language, every single word is written the same way: 🍕. So the sentence "Hello there Bob" would be translated as "🍕🍕🍕".

In this example, we store text in the state, because it changes over time.

There are a lot more things you might want to do with a text input. For example, you could validate the text inside while the user types. For more detailed examples, see the React docs on controlled components, or the reference docs for TextInput.

Text input is one of the ways the user interacts with the app. Next, let's look at another type of input and learn how to handle touches.

Edit this page
Last updated on
- + diff --git a/docs/0.62/handling-text-input/index.html b/docs/0.62/handling-text-input/index.html index dac055a0a42..f8ed9b67d12 100644 --- a/docs/0.62/handling-text-input/index.html +++ b/docs/0.62/handling-text-input/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Handling Text Input

TextInput is a Core Component that allows the user to enter text. It has an onChangeText prop that takes a function to be called every time the text changed, and an onSubmitEditing prop that takes a function to be called when the text is submitted.

For example, let's say that as the user types, you're translating their words into a different language. In this new language, every single word is written the same way: 🍕. So the sentence "Hello there Bob" would be translated as "🍕🍕🍕".

In this example, we store text in the state, because it changes over time.

There are a lot more things you might want to do with a text input. For example, you could validate the text inside while the user types. For more detailed examples, see the React docs on controlled components, or the reference docs for TextInput.

Text input is one of the ways the user interacts with the app. Next, let's look at another type of input and learn how to handle touches.

Edit this page
Last updated on
- + diff --git a/docs/0.62/handling-touches.html b/docs/0.62/handling-touches.html index 8e248cad1aa..54449f3d7b4 100644 --- a/docs/0.62/handling-touches.html +++ b/docs/0.62/handling-touches.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Handling Touches

Users interact with mobile apps mainly through touch. They can use a combination of gestures, such as tapping on a button, scrolling a list, or zooming on a map. React Native provides components to handle all sorts of common gestures, as well as a comprehensive gesture responder system to allow for more advanced gesture recognition, but the one component you will most likely be interested in is the basic Button.

Displaying a basic button

Button provides a basic button component that is rendered nicely on all platforms. The minimal example to display a button looks like this:

<Button
onPress={() => {
alert('You tapped the button!');
}}
title="Press Me"
/>

This will render a blue label on iOS, and a blue rounded rectangle with light text on Android. Pressing the button will call the "onPress" function, which in this case displays an alert popup. If you like, you can specify a "color" prop to change the color of your button.

Go ahead and play around with the Button component using the example below. You can select which platform your app is previewed in by clicking on the toggle in the bottom right, then click on "Tap to Play" to preview the app.

Touchables

If the basic button doesn't look right for your app, you can build your own button using any of the "Touchable" components provided by React Native. The "Touchable" components provide the capability to capture tapping gestures, and can display feedback when a gesture is recognized. These components do not provide any default styling, however, so you will need to do a bit of work to get them looking nicely in your app.

Which "Touchable" component you use will depend on what kind of feedback you want to provide:

  • Generally, you can use TouchableHighlight anywhere you would use a button or link on web. The view's background will be darkened when the user presses down on the button.

  • You may consider using TouchableNativeFeedback on Android to display ink surface reaction ripples that respond to the user's touch.

  • TouchableOpacity can be used to provide feedback by reducing the opacity of the button, allowing the background to be seen through while the user is pressing down.

  • If you need to handle a tap gesture but you don't want any feedback to be displayed, use TouchableWithoutFeedback.

In some cases, you may want to detect when a user presses and holds a view for a set amount of time. These long presses can be handled by passing a function to the onLongPress props of any of the "Touchable" components.

Let's see all of these in action:

Scrolling and swiping

Gestures commonly used on devices with touchable screens include swipes and pans. These allow the user to scroll through a list of items, or swipe through pages of content. For these, check out the ScrollView Core Component.

Edit this page
Last updated on
- + diff --git a/docs/0.62/handling-touches/index.html b/docs/0.62/handling-touches/index.html index 8e248cad1aa..54449f3d7b4 100644 --- a/docs/0.62/handling-touches/index.html +++ b/docs/0.62/handling-touches/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Handling Touches

Users interact with mobile apps mainly through touch. They can use a combination of gestures, such as tapping on a button, scrolling a list, or zooming on a map. React Native provides components to handle all sorts of common gestures, as well as a comprehensive gesture responder system to allow for more advanced gesture recognition, but the one component you will most likely be interested in is the basic Button.

Displaying a basic button

Button provides a basic button component that is rendered nicely on all platforms. The minimal example to display a button looks like this:

<Button
onPress={() => {
alert('You tapped the button!');
}}
title="Press Me"
/>

This will render a blue label on iOS, and a blue rounded rectangle with light text on Android. Pressing the button will call the "onPress" function, which in this case displays an alert popup. If you like, you can specify a "color" prop to change the color of your button.

Go ahead and play around with the Button component using the example below. You can select which platform your app is previewed in by clicking on the toggle in the bottom right, then click on "Tap to Play" to preview the app.

Touchables

If the basic button doesn't look right for your app, you can build your own button using any of the "Touchable" components provided by React Native. The "Touchable" components provide the capability to capture tapping gestures, and can display feedback when a gesture is recognized. These components do not provide any default styling, however, so you will need to do a bit of work to get them looking nicely in your app.

Which "Touchable" component you use will depend on what kind of feedback you want to provide:

  • Generally, you can use TouchableHighlight anywhere you would use a button or link on web. The view's background will be darkened when the user presses down on the button.

  • You may consider using TouchableNativeFeedback on Android to display ink surface reaction ripples that respond to the user's touch.

  • TouchableOpacity can be used to provide feedback by reducing the opacity of the button, allowing the background to be seen through while the user is pressing down.

  • If you need to handle a tap gesture but you don't want any feedback to be displayed, use TouchableWithoutFeedback.

In some cases, you may want to detect when a user presses and holds a view for a set amount of time. These long presses can be handled by passing a function to the onLongPress props of any of the "Touchable" components.

Let's see all of these in action:

Scrolling and swiping

Gestures commonly used on devices with touchable screens include swipes and pans. These allow the user to scroll through a list of items, or swipe through pages of content. For these, check out the ScrollView Core Component.

Edit this page
Last updated on
- + diff --git a/docs/0.62/headless-js-android.html b/docs/0.62/headless-js-android.html index 40f7b92b099..255c32fdcb0 100644 --- a/docs/0.62/headless-js-android.html +++ b/docs/0.62/headless-js-android.html @@ -19,7 +19,7 @@ - + @@ -44,7 +44,7 @@
}
Edit this page
Last updated on
- + diff --git a/docs/0.62/headless-js-android/index.html b/docs/0.62/headless-js-android/index.html index 40f7b92b099..255c32fdcb0 100644 --- a/docs/0.62/headless-js-android/index.html +++ b/docs/0.62/headless-js-android/index.html @@ -19,7 +19,7 @@ - + @@ -44,7 +44,7 @@
}
Edit this page
Last updated on
- + diff --git a/docs/0.62/height-and-width.html b/docs/0.62/height-and-width.html index 077314158fb..4750b68e116 100644 --- a/docs/0.62/height-and-width.html +++ b/docs/0.62/height-and-width.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Height and Width

A component's height and width determine its size on the screen.

Fixed Dimensions

The general way to set the dimensions of a component is by adding a fixed width and height to style. All dimensions in React Native are unitless, and represent density-independent pixels.

Setting dimensions this way is common for components that should always render at exactly the same size, regardless of screen dimensions.

Flex Dimensions

Use flex in a component's style to have the component expand and shrink dynamically based on available space. Normally you will use flex: 1, which tells a component to fill all available space, shared evenly amongst other components with the same parent. The larger the flex given, the higher the ratio of space a component will take compared to its siblings.

A component can only expand to fill available space if its parent has dimensions greater than 0. If a parent does not have either a fixed width and height or flex, the parent will have dimensions of 0 and the flex children will not be visible.

After you can control a component's size, the next step is to learn how to lay it out on the screen.

Edit this page
Last updated on
- + diff --git a/docs/0.62/height-and-width/index.html b/docs/0.62/height-and-width/index.html index 077314158fb..4750b68e116 100644 --- a/docs/0.62/height-and-width/index.html +++ b/docs/0.62/height-and-width/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Height and Width

A component's height and width determine its size on the screen.

Fixed Dimensions

The general way to set the dimensions of a component is by adding a fixed width and height to style. All dimensions in React Native are unitless, and represent density-independent pixels.

Setting dimensions this way is common for components that should always render at exactly the same size, regardless of screen dimensions.

Flex Dimensions

Use flex in a component's style to have the component expand and shrink dynamically based on available space. Normally you will use flex: 1, which tells a component to fill all available space, shared evenly amongst other components with the same parent. The larger the flex given, the higher the ratio of space a component will take compared to its siblings.

A component can only expand to fill available space if its parent has dimensions greater than 0. If a parent does not have either a fixed width and height or flex, the parent will have dimensions of 0 and the flex children will not be visible.

After you can control a component's size, the next step is to learn how to lay it out on the screen.

Edit this page
Last updated on
- + diff --git a/docs/0.62/hermes.html b/docs/0.62/hermes.html index 9cbef582009..d1cbddfcc4b 100644 --- a/docs/0.62/hermes.html +++ b/docs/0.62/hermes.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Using Hermes

Hermes is an open-source JavaScript engine optimized for running React Native apps on Android. For many apps, enabling Hermes will result in improved start-up time, decreased memory usage, and smaller app size. At this time Hermes is an opt-in React Native feature, and this guide explains how to enable it.

First, ensure you're using at least version 0.60.4 of React Native.

If you have an existing app based on an earlier version of React Native, you will have to upgrade it first. See Upgrading to new React Native Versions for how to do this. Make especially sure that all changes to android/app/build.gradle have been applied, as detailed by the React Native upgrade helper. After upgrading the app, make sure everything works before trying to switch to Hermes.

Note for Windows users.

Hermes requires Microsoft Visual C++ 2015 Redistributable

Edit your android/app/build.gradle file and make the change illustrated below:

project.ext.react = [
entryFile: "index.js",
- enableHermes: false // clean and rebuild if changing
+ enableHermes: true // clean and rebuild if changing
]

Also, if you're using ProGuard, you will need to add these rules in proguard-rules.pro :

-keep class com.facebook.hermes.unicode.** { *; }
-keep class com.facebook.jni.** { *; }

Next, if you've already built your app at least once, clean the build:

$ cd android && ./gradlew clean

That's it! You should now be able to develop and deploy your app as normal:

$ npx react-native run-android

Confirming Hermes is in use

If you've recently created a new app from scratch, you should see if Hermes is enabled in the welcome view:

Where to find JS engine status in AwesomeProject

A HermesInternal global variable will be available in JavaScript that can be used to verify that Hermes is in use:

const isHermes = () => global.HermesInternal !== null;

To see the benefits of Hermes, try making a release build/deployment of your app to compare. For example:

$ npx react-native run-android --variant release

This will compile JavaScript to bytecode during build time which will improve your app's startup speed on device.

Debugging Hermes using Google Chrome's DevTools

Hermes supports the Chrome debugger by implementing the Chrome inspector protocol. This means Chrome's tools can be used to directly debug JavaScript running on Hermes, on an emulator or device.

Chrome connects to Hermes running on device via Metro, so you'll need to know where Metro is listening. Typically this will be on localhost:8081, but this is configurable. When running yarn start the address is written to stdout on startup.

Once you know where the Metro server is listening, you can connect with Chrome using the following steps:

  1. Navigate to chrome://inspect in a Chrome browser instance.

  2. Use the Configure... button to add the Metro server address (typically localhost:8081 as described above).

Configure button in Chrome DevTools devices page

Dialog for adding Chrome DevTools network targets

  1. You should now see a "Hermes React Native" target with an "inspect" link which can be used to bring up debugger. If you don't see the "inspect" link, make sure the Metro server is running. Target inspect link

  2. You can now use the Chrome debug tools. For example, to breakpoint the next time some JavaScript is run, click on the pause button and trigger an action in your app which would cause JavaScript to execute. Pause button in debug tools

Edit this page
Last updated on
- + diff --git a/docs/0.62/hermes/index.html b/docs/0.62/hermes/index.html index 9cbef582009..d1cbddfcc4b 100644 --- a/docs/0.62/hermes/index.html +++ b/docs/0.62/hermes/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Using Hermes

Hermes is an open-source JavaScript engine optimized for running React Native apps on Android. For many apps, enabling Hermes will result in improved start-up time, decreased memory usage, and smaller app size. At this time Hermes is an opt-in React Native feature, and this guide explains how to enable it.

First, ensure you're using at least version 0.60.4 of React Native.

If you have an existing app based on an earlier version of React Native, you will have to upgrade it first. See Upgrading to new React Native Versions for how to do this. Make especially sure that all changes to android/app/build.gradle have been applied, as detailed by the React Native upgrade helper. After upgrading the app, make sure everything works before trying to switch to Hermes.

Note for Windows users.

Hermes requires Microsoft Visual C++ 2015 Redistributable

Edit your android/app/build.gradle file and make the change illustrated below:

project.ext.react = [
entryFile: "index.js",
- enableHermes: false // clean and rebuild if changing
+ enableHermes: true // clean and rebuild if changing
]

Also, if you're using ProGuard, you will need to add these rules in proguard-rules.pro :

-keep class com.facebook.hermes.unicode.** { *; }
-keep class com.facebook.jni.** { *; }

Next, if you've already built your app at least once, clean the build:

$ cd android && ./gradlew clean

That's it! You should now be able to develop and deploy your app as normal:

$ npx react-native run-android

Confirming Hermes is in use

If you've recently created a new app from scratch, you should see if Hermes is enabled in the welcome view:

Where to find JS engine status in AwesomeProject

A HermesInternal global variable will be available in JavaScript that can be used to verify that Hermes is in use:

const isHermes = () => global.HermesInternal !== null;

To see the benefits of Hermes, try making a release build/deployment of your app to compare. For example:

$ npx react-native run-android --variant release

This will compile JavaScript to bytecode during build time which will improve your app's startup speed on device.

Debugging Hermes using Google Chrome's DevTools

Hermes supports the Chrome debugger by implementing the Chrome inspector protocol. This means Chrome's tools can be used to directly debug JavaScript running on Hermes, on an emulator or device.

Chrome connects to Hermes running on device via Metro, so you'll need to know where Metro is listening. Typically this will be on localhost:8081, but this is configurable. When running yarn start the address is written to stdout on startup.

Once you know where the Metro server is listening, you can connect with Chrome using the following steps:

  1. Navigate to chrome://inspect in a Chrome browser instance.

  2. Use the Configure... button to add the Metro server address (typically localhost:8081 as described above).

Configure button in Chrome DevTools devices page

Dialog for adding Chrome DevTools network targets

  1. You should now see a "Hermes React Native" target with an "inspect" link which can be used to bring up debugger. If you don't see the "inspect" link, make sure the Metro server is running. Target inspect link

  2. You can now use the Chrome debug tools. For example, to breakpoint the next time some JavaScript is run, click on the pause button and trigger an action in your app which would cause JavaScript to execute. Pause button in debug tools

Edit this page
Last updated on
- + diff --git a/docs/0.62/image-style-props.html b/docs/0.62/image-style-props.html index b732bd55755..844875f4e5d 100644 --- a/docs/0.62/image-style-props.html +++ b/docs/0.62/image-style-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Image Style Props

Examples

Reference

Props

borderTopRightRadius

TypeRequired
numberNo

backfaceVisibility

TypeRequired
enum('visible', 'hidden')No

borderBottomLeftRadius

TypeRequired
numberNo

borderBottomRightRadius

TypeRequired
numberNo

borderColor

TypeRequired
colorNo

borderRadius

TypeRequired
numberNo

borderTopLeftRadius

TypeRequired
numberNo

backgroundColor

TypeRequired
colorNo

borderWidth

TypeRequired
numberNo

opacity

TypeRequired
numberNo

overflow

TypeRequired
enum('visible', 'hidden')No

resizeMode

TypeRequired
enum('cover', 'contain', 'stretch', 'repeat', 'center')No

tintColor

Changes the color of all the non-transparent pixels to the tintColor.

TypeRequired
colorNo

overlayColor

When the image has rounded corners, specifying an overlayColor will cause the remaining space in the corners to be filled with a solid color. This is useful in cases which are not supported by the Android implementation of rounded corners:

  • Certain resize modes, such as 'contain'
  • Animated GIFs

A typical way to use this prop is with images displayed on a solid background and setting the overlayColor to the same color as the background.

For details of how this works under the hood, see https://frescolib.org/docs/rounded-corners-and-circles.html

TypeRequiredPlatform
stringNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.62/image-style-props/index.html b/docs/0.62/image-style-props/index.html index b732bd55755..844875f4e5d 100644 --- a/docs/0.62/image-style-props/index.html +++ b/docs/0.62/image-style-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Image Style Props

Examples

Reference

Props

borderTopRightRadius

TypeRequired
numberNo

backfaceVisibility

TypeRequired
enum('visible', 'hidden')No

borderBottomLeftRadius

TypeRequired
numberNo

borderBottomRightRadius

TypeRequired
numberNo

borderColor

TypeRequired
colorNo

borderRadius

TypeRequired
numberNo

borderTopLeftRadius

TypeRequired
numberNo

backgroundColor

TypeRequired
colorNo

borderWidth

TypeRequired
numberNo

opacity

TypeRequired
numberNo

overflow

TypeRequired
enum('visible', 'hidden')No

resizeMode

TypeRequired
enum('cover', 'contain', 'stretch', 'repeat', 'center')No

tintColor

Changes the color of all the non-transparent pixels to the tintColor.

TypeRequired
colorNo

overlayColor

When the image has rounded corners, specifying an overlayColor will cause the remaining space in the corners to be filled with a solid color. This is useful in cases which are not supported by the Android implementation of rounded corners:

  • Certain resize modes, such as 'contain'
  • Animated GIFs

A typical way to use this prop is with images displayed on a solid background and setting the overlayColor to the same color as the background.

For details of how this works under the hood, see https://frescolib.org/docs/rounded-corners-and-circles.html

TypeRequiredPlatform
stringNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.62/image.html b/docs/0.62/image.html index 212f11006a0..65bec699304 100644 --- a/docs/0.62/image.html +++ b/docs/0.62/image.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// For WebP support, without animations
implementation 'com.facebook.fresco:webpsupport:2.0.0'
}

Reference

Props

style

ImageResizeMode is an Enum for different image resizing modes, set via the resizeMode style property on Image components. The values are contain, cover, stretch, center, repeat.

TypeRequired
styleNo

accessible

When true, indicates the image is an accessibility element.

TypeRequiredPlatform
boolNoiOS

accessibilityLabel

The text that's read by the screen reader when the user interacts with the image.

TypeRequiredPlatform
stringNoiOS

blurRadius

blurRadius: the blur radius of the blur filter added to the image

TypeRequired
numberNo

Tip : IOS you will need to increase blurRadius more than 5

capInsets

When the image is resized, the corners of the size specified by capInsets will stay a fixed size, but the center content and borders of the image will be stretched. This is useful for creating resizable rounded buttons, shadows, and other resizable assets. More info in the official Apple documentation.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

defaultSource

A static image to display while loading the image source.

TypeRequiredPlatform
object, numberNoiOS
numberNoAndroid

If passing an object, the general shape is {uri: string, width: number, height: number, scale: number}:

If passing a number:

Note: On Android, the default source prop is ignored on debug builds.

fadeDuration

Android only. By default, it is 300ms.

TypeRequiredPlatform
numberNoAndroid

loadingIndicatorSource

Similarly to source, this property represents the resource used to render the loading indicator for the image, displayed until image is ready to be displayed, typically after when it got downloaded from network.

TypeRequired
array of ImageSourcePropTypes, numberNo

Can accept a number as returned by require('./image.jpg')

onError

Invoked on load error with {nativeEvent: {error}}.

TypeRequired
functionNo

onLayout

Invoked on mount and layout changes with {nativeEvent: {layout: {x, y, width, height}}}.

TypeRequired
functionNo

onLoad

Invoked when load completes successfully.

TypeRequired
functionNo

onLoadEnd

Invoked when load either succeeds or fails.

TypeRequired
functionNo

onLoadStart

Invoked on load start.

e.g., onLoadStart={(e) => this.setState({loading: true})}

TypeRequired
functionNo

onPartialLoad

Invoked when a partial load of the image is complete. The definition of what constitutes a "partial load" is loader specific though this is meant for progressive JPEG loads.

TypeRequiredPlatform
functionNoiOS

onProgress

Invoked on download progress with {nativeEvent: {loaded, total}}.

TypeRequiredPlatform
functionNoiOS

progressiveRenderingEnabled

Android only. When true, enables progressive jpeg streaming. https://frescolib.org/docs/progressive-jpegs.html

TypeRequiredPlatform
boolNoAndroid

resizeMethod

The mechanism that should be used to resize the image when the image's dimensions differ from the image view's dimensions. Defaults to auto.

More details about resize and scale can be found at http://frescolib.org/docs/resizing.html.

TypeRequiredPlatform
enum('auto', 'resize', 'scale')NoAndroid

resizeMode

Determines how to resize the image when the frame doesn't match the raw image dimensions. Defaults to cover.

TypeRequired
enum('cover', 'contain', 'stretch', 'repeat', 'center')No

source

The image source (either a remote URL or a local file resource).

This prop can also contain several remote URLs, specified together with their width and height and potentially with scale/other URI arguments. The native side will then choose the best uri to display based on the measured size of the image container. A cache property can be added to control how networked request interacts with the local cache. (For more information see Cache Control for Images).

The currently supported formats are png, jpg, jpeg, bmp, gif, webp (Android only), psd (iOS only). In addition, iOS supports several RAW image formats. Refer to Apple's documentation for the current list of supported camera models (for iOS 12, see https://support.apple.com/en-ca/HT208967).

TypeRequired
ImageSourcePropTypeNo

testID

A unique identifier for this element to be used in UI Automation testing scripts.

TypeRequired
stringNo

Methods

getSize()

Image.getSize(uri, success, [failure]);

Retrieve the width and height (in pixels) of an image prior to displaying it. This method can fail if the image cannot be found, or fails to download.

In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API.

Parameters:

NameTypeRequiredDescription
uristringYesThe location of the image.
successfunctionYesThe function that will be called if the image was successfully found and width and height retrieved.
failurefunctionNoThe function that will be called if there was an error, such as failing to retrieve the image.

getSizeWithHeaders()

Image.getSizeWithHeaders(uri, headers, success, [failure]);

Retrieve the width and height (in pixels) of an image prior to displaying it with the ability to provide the headers for the request. This method can fail if the image cannot be found, or fails to download.

In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API.

Does not work for static image resources.

Parameters:

NameTypeRequiredDescription
uristringYesThe location of the image.
headersobjectYesThe headers for the request.
successfunctionYesThe function that will be called if the image was successfully found and width and height retrieved.
failurefunctionNoThe function that will be called if there was an error, such as failing toto retrieve the image.

prefetch()

Image.prefetch(url);

Prefetches a remote image for later use by downloading it to the disk cache

Parameters:

NameTypeRequiredDescription
urlstringYesThe remote location of the image.

abortPrefetch()

Image.abortPrefetch(requestId);

Abort prefetch request. Android-only.

Parameters:

NameTypeRequiredDescription
requestIdnumberYesId as returned by prefetch()

queryCache()

Image.queryCache(urls);

Perform cache interrogation. Returns a mapping from URL to cache status, such as "disk" or "memory". If a requested URL is not in the mapping, it means it's not in the cache.

Parameters:

NameTypeRequiredDescription
urlsarrayYesList of image URLs to check the cache for.

resolveAssetSource()

Image.resolveAssetSource(source);

Resolves an asset reference into an object which has the properties uri, width, and height.

Parameters:

NameTypeRequiredDescription
sourcenumber, objectYesA number (opaque type returned by require('./foo.png')) or an ImageSource.

ImageSource is an object like { uri: '<http location || file path>' }

Edit this page
Last updated on
- + diff --git a/docs/0.62/image/index.html b/docs/0.62/image/index.html index 212f11006a0..65bec699304 100644 --- a/docs/0.62/image/index.html +++ b/docs/0.62/image/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// For WebP support, without animations
implementation 'com.facebook.fresco:webpsupport:2.0.0'
}

Reference

Props

style

ImageResizeMode is an Enum for different image resizing modes, set via the resizeMode style property on Image components. The values are contain, cover, stretch, center, repeat.

TypeRequired
styleNo

accessible

When true, indicates the image is an accessibility element.

TypeRequiredPlatform
boolNoiOS

accessibilityLabel

The text that's read by the screen reader when the user interacts with the image.

TypeRequiredPlatform
stringNoiOS

blurRadius

blurRadius: the blur radius of the blur filter added to the image

TypeRequired
numberNo

Tip : IOS you will need to increase blurRadius more than 5

capInsets

When the image is resized, the corners of the size specified by capInsets will stay a fixed size, but the center content and borders of the image will be stretched. This is useful for creating resizable rounded buttons, shadows, and other resizable assets. More info in the official Apple documentation.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

defaultSource

A static image to display while loading the image source.

TypeRequiredPlatform
object, numberNoiOS
numberNoAndroid

If passing an object, the general shape is {uri: string, width: number, height: number, scale: number}:

If passing a number:

Note: On Android, the default source prop is ignored on debug builds.

fadeDuration

Android only. By default, it is 300ms.

TypeRequiredPlatform
numberNoAndroid

loadingIndicatorSource

Similarly to source, this property represents the resource used to render the loading indicator for the image, displayed until image is ready to be displayed, typically after when it got downloaded from network.

TypeRequired
array of ImageSourcePropTypes, numberNo

Can accept a number as returned by require('./image.jpg')

onError

Invoked on load error with {nativeEvent: {error}}.

TypeRequired
functionNo

onLayout

Invoked on mount and layout changes with {nativeEvent: {layout: {x, y, width, height}}}.

TypeRequired
functionNo

onLoad

Invoked when load completes successfully.

TypeRequired
functionNo

onLoadEnd

Invoked when load either succeeds or fails.

TypeRequired
functionNo

onLoadStart

Invoked on load start.

e.g., onLoadStart={(e) => this.setState({loading: true})}

TypeRequired
functionNo

onPartialLoad

Invoked when a partial load of the image is complete. The definition of what constitutes a "partial load" is loader specific though this is meant for progressive JPEG loads.

TypeRequiredPlatform
functionNoiOS

onProgress

Invoked on download progress with {nativeEvent: {loaded, total}}.

TypeRequiredPlatform
functionNoiOS

progressiveRenderingEnabled

Android only. When true, enables progressive jpeg streaming. https://frescolib.org/docs/progressive-jpegs.html

TypeRequiredPlatform
boolNoAndroid

resizeMethod

The mechanism that should be used to resize the image when the image's dimensions differ from the image view's dimensions. Defaults to auto.

More details about resize and scale can be found at http://frescolib.org/docs/resizing.html.

TypeRequiredPlatform
enum('auto', 'resize', 'scale')NoAndroid

resizeMode

Determines how to resize the image when the frame doesn't match the raw image dimensions. Defaults to cover.

TypeRequired
enum('cover', 'contain', 'stretch', 'repeat', 'center')No

source

The image source (either a remote URL or a local file resource).

This prop can also contain several remote URLs, specified together with their width and height and potentially with scale/other URI arguments. The native side will then choose the best uri to display based on the measured size of the image container. A cache property can be added to control how networked request interacts with the local cache. (For more information see Cache Control for Images).

The currently supported formats are png, jpg, jpeg, bmp, gif, webp (Android only), psd (iOS only). In addition, iOS supports several RAW image formats. Refer to Apple's documentation for the current list of supported camera models (for iOS 12, see https://support.apple.com/en-ca/HT208967).

TypeRequired
ImageSourcePropTypeNo

testID

A unique identifier for this element to be used in UI Automation testing scripts.

TypeRequired
stringNo

Methods

getSize()

Image.getSize(uri, success, [failure]);

Retrieve the width and height (in pixels) of an image prior to displaying it. This method can fail if the image cannot be found, or fails to download.

In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API.

Parameters:

NameTypeRequiredDescription
uristringYesThe location of the image.
successfunctionYesThe function that will be called if the image was successfully found and width and height retrieved.
failurefunctionNoThe function that will be called if there was an error, such as failing to retrieve the image.

getSizeWithHeaders()

Image.getSizeWithHeaders(uri, headers, success, [failure]);

Retrieve the width and height (in pixels) of an image prior to displaying it with the ability to provide the headers for the request. This method can fail if the image cannot be found, or fails to download.

In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API.

Does not work for static image resources.

Parameters:

NameTypeRequiredDescription
uristringYesThe location of the image.
headersobjectYesThe headers for the request.
successfunctionYesThe function that will be called if the image was successfully found and width and height retrieved.
failurefunctionNoThe function that will be called if there was an error, such as failing toto retrieve the image.

prefetch()

Image.prefetch(url);

Prefetches a remote image for later use by downloading it to the disk cache

Parameters:

NameTypeRequiredDescription
urlstringYesThe remote location of the image.

abortPrefetch()

Image.abortPrefetch(requestId);

Abort prefetch request. Android-only.

Parameters:

NameTypeRequiredDescription
requestIdnumberYesId as returned by prefetch()

queryCache()

Image.queryCache(urls);

Perform cache interrogation. Returns a mapping from URL to cache status, such as "disk" or "memory". If a requested URL is not in the mapping, it means it's not in the cache.

Parameters:

NameTypeRequiredDescription
urlsarrayYesList of image URLs to check the cache for.

resolveAssetSource()

Image.resolveAssetSource(source);

Resolves an asset reference into an object which has the properties uri, width, and height.

Parameters:

NameTypeRequiredDescription
sourcenumber, objectYesA number (opaque type returned by require('./foo.png')) or an ImageSource.

ImageSource is an object like { uri: '<http location || file path>' }

Edit this page
Last updated on
- + diff --git a/docs/0.62/imagebackground.html b/docs/0.62/imagebackground.html index 51068ea62da..54b97a5b937 100644 --- a/docs/0.62/imagebackground.html +++ b/docs/0.62/imagebackground.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

ImageBackground

A common feature request from developers familiar with the web is background-image. To handle this use case, you can use the <ImageBackground> component, which has the same props as <Image>, and add whatever children to it you would like to layer on top of it.

You might not want to use <ImageBackground> in some cases, since the implementation is basic. Refer to <ImageBackground>'s source code for more insight, and create your own custom component when needed.

Note that you must specify some width and height style attributes.

Example

Reference

Props

Inherits Image Props.

style

TypeRequired
view stylesNo

imageStyle

TypeRequired
image stylesNo

imageRef

Allows to set a reference to the inner Image component

TypeRequired
RefNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/imagebackground/index.html b/docs/0.62/imagebackground/index.html index 51068ea62da..54b97a5b937 100644 --- a/docs/0.62/imagebackground/index.html +++ b/docs/0.62/imagebackground/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

ImageBackground

A common feature request from developers familiar with the web is background-image. To handle this use case, you can use the <ImageBackground> component, which has the same props as <Image>, and add whatever children to it you would like to layer on top of it.

You might not want to use <ImageBackground> in some cases, since the implementation is basic. Refer to <ImageBackground>'s source code for more insight, and create your own custom component when needed.

Note that you must specify some width and height style attributes.

Example

Reference

Props

Inherits Image Props.

style

TypeRequired
view stylesNo

imageStyle

TypeRequired
image stylesNo

imageRef

Allows to set a reference to the inner Image component

TypeRequired
RefNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/imageeditor.html b/docs/0.62/imageeditor.html index faf84da1b44..1ae8723dc47 100644 --- a/docs/0.62/imageeditor.html +++ b/docs/0.62/imageeditor.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 ImageEditor

Deprecated. Use @react-native-community/image-editor instead.

Reference

Methods

cropImage()

static cropImage(uri, cropData, success, failure)

Crop the image specified by the URI param. If URI points to a remote image, it will be downloaded automatically. If the image cannot be loaded/downloaded, the failure callback will be called.

If the cropping process is successful, the resultant cropped image will be stored in the ImageStore, and the URI returned in the success callback will point to the image in the store. Remember to delete the cropped image from the ImageStore when you are done with it.

cropData

  • offset - The top-left corner of the cropped image, specified in the original image's coordinate space
  • size - Size (dimensions) of the cropped image
  • displaySize (optional) - Size to which you want to scale the cropped image
  • resizeMode (optional) - Resizing mode to use when scaling the image
cropData = {
offset: { x: number, y: number },
size: { width: number, height: number },
displaySize: { width: number, height: number },
resizeMode: 'contain/cover/stretch'
};
Edit this page
Last updated on
- + diff --git a/docs/0.62/imageeditor/index.html b/docs/0.62/imageeditor/index.html index faf84da1b44..1ae8723dc47 100644 --- a/docs/0.62/imageeditor/index.html +++ b/docs/0.62/imageeditor/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 ImageEditor

Deprecated. Use @react-native-community/image-editor instead.

Reference

Methods

cropImage()

static cropImage(uri, cropData, success, failure)

Crop the image specified by the URI param. If URI points to a remote image, it will be downloaded automatically. If the image cannot be loaded/downloaded, the failure callback will be called.

If the cropping process is successful, the resultant cropped image will be stored in the ImageStore, and the URI returned in the success callback will point to the image in the store. Remember to delete the cropped image from the ImageStore when you are done with it.

cropData

  • offset - The top-left corner of the cropped image, specified in the original image's coordinate space
  • size - Size (dimensions) of the cropped image
  • displaySize (optional) - Size to which you want to scale the cropped image
  • resizeMode (optional) - Resizing mode to use when scaling the image
cropData = {
offset: { x: number, y: number },
size: { width: number, height: number },
displaySize: { width: number, height: number },
resizeMode: 'contain/cover/stretch'
};
Edit this page
Last updated on
- + diff --git a/docs/0.62/imagepickerios.html b/docs/0.62/imagepickerios.html index 7385859bd0a..ecfda5889ce 100644 --- a/docs/0.62/imagepickerios.html +++ b/docs/0.62/imagepickerios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 ImagePickerIOS

Deprecated. Use @react-native-community/image-picker-ios instead.

Reference

Methods

canRecordVideos()

static canRecordVideos(callback)

canUseCamera()

static canUseCamera(callback)

openCameraDialog()

static openCameraDialog(config, successCallback, cancelCallback)

Parameters:

NameTypeRequiredDescription
configobjectNoSee below.
successCallbackfunctionNoSee below.
cancelCallbackfunctionNoSee below.

config is an object containing:

  • videoMode : An optional boolean value that defaults to false.

successCallback is an optional callback function that's invoked when the select dialog is opened successfully. It will include the following data:

  • [string, number, number]

cancelCallback is an optional callback function that's invoked when the camera dialog is canceled.

openSelectDialog()

static openSelectDialog(config, successCallback, cancelCallback)

Parameters:

NameTypeRequiredDescription
configobjectNoSee below.
successCallbackfunctionNoSee below.
cancelCallbackfunctionNoSee below.

config is an object containing:

  • showImages : An optional boolean value that defaults to false.
  • showVideos: An optional boolean value that defaults to false.

successCallback is an optional callback function that's invoked when the select dialog is opened successfully. It will include the following data:

  • [string, number, number]

cancelCallback is an optional callback function that's invoked when the select dialog is canceled.

Edit this page
Last updated on
- + diff --git a/docs/0.62/imagepickerios/index.html b/docs/0.62/imagepickerios/index.html index 7385859bd0a..ecfda5889ce 100644 --- a/docs/0.62/imagepickerios/index.html +++ b/docs/0.62/imagepickerios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 ImagePickerIOS

Deprecated. Use @react-native-community/image-picker-ios instead.

Reference

Methods

canRecordVideos()

static canRecordVideos(callback)

canUseCamera()

static canUseCamera(callback)

openCameraDialog()

static openCameraDialog(config, successCallback, cancelCallback)

Parameters:

NameTypeRequiredDescription
configobjectNoSee below.
successCallbackfunctionNoSee below.
cancelCallbackfunctionNoSee below.

config is an object containing:

  • videoMode : An optional boolean value that defaults to false.

successCallback is an optional callback function that's invoked when the select dialog is opened successfully. It will include the following data:

  • [string, number, number]

cancelCallback is an optional callback function that's invoked when the camera dialog is canceled.

openSelectDialog()

static openSelectDialog(config, successCallback, cancelCallback)

Parameters:

NameTypeRequiredDescription
configobjectNoSee below.
successCallbackfunctionNoSee below.
cancelCallbackfunctionNoSee below.

config is an object containing:

  • showImages : An optional boolean value that defaults to false.
  • showVideos: An optional boolean value that defaults to false.

successCallback is an optional callback function that's invoked when the select dialog is opened successfully. It will include the following data:

  • [string, number, number]

cancelCallback is an optional callback function that's invoked when the select dialog is canceled.

Edit this page
Last updated on
- + diff --git a/docs/0.62/images.html b/docs/0.62/images.html index 635762fe24c..b48b30d2df8 100644 --- a/docs/0.62/images.html +++ b/docs/0.62/images.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// BAD
<Image source={{uri: 'https://reactjs.org/logo-og.png'}} />

Network Requests for Images

If you would like to set such things as the HTTP-Verb, Headers or a Body along with the image request, you may do this by defining these properties on the source object:

<Image
source={{
uri: 'https://reactjs.org/logo-og.png',
method: 'POST',
headers: {
Pragma: 'no-cache'
},
body: 'Your Body goes here'
}}
style={{ width: 400, height: 400 }}
/>

Uri Data Images

Sometimes, you might be getting encoded image data from a REST API call. You can use the 'data:' uri scheme to use these images. Same as for network resources, you will need to manually specify the dimensions of your image.

This is recommended for very small and dynamic images only, like icons in a list from a DB.

// include at least width and height!
<Image
style={{
width: 51,
height: 51,
resizeMode: 'contain'
}}
source={{
uri:
'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADMAAAAzCAYAAAA6oTAqAAAAEXRFWHRTb2Z0d2FyZQBwbmdjcnVzaEB1SfMAAABQSURBVGje7dSxCQBACARB+2/ab8BEeQNhFi6WSYzYLYudDQYGBgYGBgYGBgYGBgYGBgZmcvDqYGBgmhivGQYGBgYGBgYGBgYGBgYGBgbmQw+P/eMrC5UTVAAAAABJRU5ErkJggg=='
}}
/>

Cache Control (iOS Only)

In some cases you might only want to display an image if it is already in the local cache, i.e. a low resolution placeholder until a higher resolution is available. In other cases you do not care if the image is outdated and are willing to display an outdated image to save bandwidth. The cache source property gives you control over how the network layer interacts with the cache.

<Image
source={{
uri: 'https://reactjs.org/logo-og.png',
cache: 'only-if-cached'
}}
style={{ width: 400, height: 400 }}
/>

Local Filesystem Images

See CameraRoll for an example of using local resources that are outside of Images.xcassets.

Best Camera Roll Image

iOS saves multiple sizes for the same image in your Camera Roll, it is very important to pick the one that's as close as possible for performance reasons. You wouldn't want to use the full quality 3264x2448 image as source when displaying a 200x200 thumbnail. If there's an exact match, React Native will pick it, otherwise it's going to use the first one that's at least 50% bigger in order to avoid blur when resizing from a close size. All of this is done by default so you don't have to worry about writing the tedious (and error prone) code to do it yourself.

Why Not Automatically Size Everything?

In the browser if you don't give a size to an image, the browser is going to render a 0x0 element, download the image, and then render the image based with the correct size. The big issue with this behavior is that your UI is going to jump all around as images load, this makes for a very bad user experience.

In React Native this behavior is intentionally not implemented. It is more work for the developer to know the dimensions (or aspect ratio) of the remote image in advance, but we believe that it leads to a better user experience. Static images loaded from the app bundle via the require('./my-icon.png') syntax can be automatically sized because their dimensions are available immediately at the time of mounting.

For example, the result of require('./my-icon.png') might be:

{"__packager_asset":true,"uri":"my-icon.png","width":591,"height":573}

Source as an object

In React Native, one interesting decision is that the src attribute is named source and doesn't take a string but an object with a uri attribute.

<Image source={{ uri: 'something.jpg' }} />

On the infrastructure side, the reason is that it allows us to attach metadata to this object. For example if you are using require('./my-icon.png'), then we add information about its actual location and size (don't rely on this fact, it might change in the future!). This is also future proofing, for example we may want to support sprites at some point, instead of outputting {uri: ...}, we can output {uri: ..., crop: {left: 10, top: 50, width: 20, height: 40}} and transparently support spriting on all the existing call sites.

On the user side, this lets you annotate the object with useful attributes such as the dimension of the image in order to compute the size it's going to be displayed in. Feel free to use it as your data structure to store more information about your image.

Background Image via Nesting

A common feature request from developers familiar with the web is background-image. To handle this use case, you can use the <ImageBackground> component, which has the same props as <Image>, and add whatever children to it you would like to layer on top of it.

You might not want to use <ImageBackground> in some cases, since the implementation is basic. Refer to <ImageBackground>'s documentation for more insight, and create your own custom component when needed.

return (
<ImageBackground source={...} style={{width: '100%', height: '100%'}}>
<Text>Inside</Text>
</ImageBackground>
);

Note that you must specify some width and height style attributes.

iOS Border Radius Styles

Please note that the following corner specific, border radius style properties are currently ignored by iOS's image component:

Off-thread Decoding

Image decoding can take more than a frame-worth of time. This is one of the major sources of frame drops on the web because decoding is done in the main thread. In React Native, image decoding is done in a different thread. In practice, you already need to handle the case when the image is not downloaded yet, so displaying the placeholder for a few more frames while it is decoding does not require any code change.

Edit this page
Last updated on
- + diff --git a/docs/0.62/images/index.html b/docs/0.62/images/index.html index 635762fe24c..b48b30d2df8 100644 --- a/docs/0.62/images/index.html +++ b/docs/0.62/images/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// BAD
<Image source={{uri: 'https://reactjs.org/logo-og.png'}} />

Network Requests for Images

If you would like to set such things as the HTTP-Verb, Headers or a Body along with the image request, you may do this by defining these properties on the source object:

<Image
source={{
uri: 'https://reactjs.org/logo-og.png',
method: 'POST',
headers: {
Pragma: 'no-cache'
},
body: 'Your Body goes here'
}}
style={{ width: 400, height: 400 }}
/>

Uri Data Images

Sometimes, you might be getting encoded image data from a REST API call. You can use the 'data:' uri scheme to use these images. Same as for network resources, you will need to manually specify the dimensions of your image.

This is recommended for very small and dynamic images only, like icons in a list from a DB.

// include at least width and height!
<Image
style={{
width: 51,
height: 51,
resizeMode: 'contain'
}}
source={{
uri:
'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADMAAAAzCAYAAAA6oTAqAAAAEXRFWHRTb2Z0d2FyZQBwbmdjcnVzaEB1SfMAAABQSURBVGje7dSxCQBACARB+2/ab8BEeQNhFi6WSYzYLYudDQYGBgYGBgYGBgYGBgYGBgZmcvDqYGBgmhivGQYGBgYGBgYGBgYGBgYGBgbmQw+P/eMrC5UTVAAAAABJRU5ErkJggg=='
}}
/>

Cache Control (iOS Only)

In some cases you might only want to display an image if it is already in the local cache, i.e. a low resolution placeholder until a higher resolution is available. In other cases you do not care if the image is outdated and are willing to display an outdated image to save bandwidth. The cache source property gives you control over how the network layer interacts with the cache.

<Image
source={{
uri: 'https://reactjs.org/logo-og.png',
cache: 'only-if-cached'
}}
style={{ width: 400, height: 400 }}
/>

Local Filesystem Images

See CameraRoll for an example of using local resources that are outside of Images.xcassets.

Best Camera Roll Image

iOS saves multiple sizes for the same image in your Camera Roll, it is very important to pick the one that's as close as possible for performance reasons. You wouldn't want to use the full quality 3264x2448 image as source when displaying a 200x200 thumbnail. If there's an exact match, React Native will pick it, otherwise it's going to use the first one that's at least 50% bigger in order to avoid blur when resizing from a close size. All of this is done by default so you don't have to worry about writing the tedious (and error prone) code to do it yourself.

Why Not Automatically Size Everything?

In the browser if you don't give a size to an image, the browser is going to render a 0x0 element, download the image, and then render the image based with the correct size. The big issue with this behavior is that your UI is going to jump all around as images load, this makes for a very bad user experience.

In React Native this behavior is intentionally not implemented. It is more work for the developer to know the dimensions (or aspect ratio) of the remote image in advance, but we believe that it leads to a better user experience. Static images loaded from the app bundle via the require('./my-icon.png') syntax can be automatically sized because their dimensions are available immediately at the time of mounting.

For example, the result of require('./my-icon.png') might be:

{"__packager_asset":true,"uri":"my-icon.png","width":591,"height":573}

Source as an object

In React Native, one interesting decision is that the src attribute is named source and doesn't take a string but an object with a uri attribute.

<Image source={{ uri: 'something.jpg' }} />

On the infrastructure side, the reason is that it allows us to attach metadata to this object. For example if you are using require('./my-icon.png'), then we add information about its actual location and size (don't rely on this fact, it might change in the future!). This is also future proofing, for example we may want to support sprites at some point, instead of outputting {uri: ...}, we can output {uri: ..., crop: {left: 10, top: 50, width: 20, height: 40}} and transparently support spriting on all the existing call sites.

On the user side, this lets you annotate the object with useful attributes such as the dimension of the image in order to compute the size it's going to be displayed in. Feel free to use it as your data structure to store more information about your image.

Background Image via Nesting

A common feature request from developers familiar with the web is background-image. To handle this use case, you can use the <ImageBackground> component, which has the same props as <Image>, and add whatever children to it you would like to layer on top of it.

You might not want to use <ImageBackground> in some cases, since the implementation is basic. Refer to <ImageBackground>'s documentation for more insight, and create your own custom component when needed.

return (
<ImageBackground source={...} style={{width: '100%', height: '100%'}}>
<Text>Inside</Text>
</ImageBackground>
);

Note that you must specify some width and height style attributes.

iOS Border Radius Styles

Please note that the following corner specific, border radius style properties are currently ignored by iOS's image component:

Off-thread Decoding

Image decoding can take more than a frame-worth of time. This is one of the major sources of frame drops on the web because decoding is done in the main thread. In React Native, image decoding is done in a different thread. In practice, you already need to handle the case when the image is not downloaded yet, so displaying the placeholder for a few more frames while it is decoding does not require any code change.

Edit this page
Last updated on
- + diff --git a/docs/0.62/imagestore.html b/docs/0.62/imagestore.html index 26a5ab8fa45..ccba96dd4cf 100644 --- a/docs/0.62/imagestore.html +++ b/docs/0.62/imagestore.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

ImageStore

Deprecated. Use expo-file-system or react-native-fs instead.

Methods

Reference

Methods

hasImageForTag()

static hasImageForTag(uri, callback)

Check if the ImageStore contains image data for the specified URI. @platform ios

removeImageForTag()

static removeImageForTag(uri)

Delete an image from the ImageStore. Images are stored in memory and must be manually removed when you are finished with them, otherwise they will continue to use up RAM until the app is terminated. It is safe to call removeImageForTag() without first calling hasImageForTag(), it will fail silently. @platform ios

addImageFromBase64()

static addImageFromBase64(base64ImageData, success, failure)

Stores a base64-encoded image in the ImageStore, and returns a URI that can be used to access or display the image later. Images are stored in memory only, and must be manually deleted when you are finished with them by calling removeImageForTag().

Note that it is very inefficient to transfer large quantities of binary data between JS and native code, so you should avoid calling this more than necessary. @platform ios

getBase64ForTag()

static getBase64ForTag(uri, success, failure)

Retrieves the base64-encoded data for an image in the ImageStore. If the specified URI does not match an image in the store, the failure callback will be called.

Note that it is very inefficient to transfer large quantities of binary data between JS and native code, so you should avoid calling this more than necessary. To display an image in the ImageStore, you can pass the URI to an <Image/> component; there is no need to retrieve the base64 data.

Edit this page
Last updated on
- + diff --git a/docs/0.62/imagestore/index.html b/docs/0.62/imagestore/index.html index 26a5ab8fa45..ccba96dd4cf 100644 --- a/docs/0.62/imagestore/index.html +++ b/docs/0.62/imagestore/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

ImageStore

Deprecated. Use expo-file-system or react-native-fs instead.

Methods

Reference

Methods

hasImageForTag()

static hasImageForTag(uri, callback)

Check if the ImageStore contains image data for the specified URI. @platform ios

removeImageForTag()

static removeImageForTag(uri)

Delete an image from the ImageStore. Images are stored in memory and must be manually removed when you are finished with them, otherwise they will continue to use up RAM until the app is terminated. It is safe to call removeImageForTag() without first calling hasImageForTag(), it will fail silently. @platform ios

addImageFromBase64()

static addImageFromBase64(base64ImageData, success, failure)

Stores a base64-encoded image in the ImageStore, and returns a URI that can be used to access or display the image later. Images are stored in memory only, and must be manually deleted when you are finished with them by calling removeImageForTag().

Note that it is very inefficient to transfer large quantities of binary data between JS and native code, so you should avoid calling this more than necessary. @platform ios

getBase64ForTag()

static getBase64ForTag(uri, success, failure)

Retrieves the base64-encoded data for an image in the ImageStore. If the specified URI does not match an image in the store, the failure callback will be called.

Note that it is very inefficient to transfer large quantities of binary data between JS and native code, so you should avoid calling this more than necessary. To display an image in the ImageStore, you can pass the URI to an <Image/> component; there is no need to retrieve the base64 data.

Edit this page
Last updated on
- + diff --git a/docs/0.62/improvingux.html b/docs/0.62/improvingux.html index cea02e94f32..c912c64ab1a 100644 --- a/docs/0.62/improvingux.html +++ b/docs/0.62/improvingux.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Improving User Experience

Configure text inputs

Entering text on touch phone is a challenge - small screen, software keyboard. But based on what kind of data you need, you can make it easier by properly configuring the text inputs:

  • Focus the first field automatically
  • Use placeholder text as an example of expected data format
  • Enable or disable autocapitalization and autocorrect
  • Choose keyboard type (e.g. email, numeric)
  • Make sure the return button focuses the next field or submits the form

Check out TextInput docs for more configuration options.

Try it on your phone

Manage layout when keyboard is visible

Software keyboard takes almost half of the screen. If you have interactive elements that can get covered by the keyboard, make sure they are still accessible by using the KeyboardAvoidingView component.

Try it on your phone

Make tappable areas larger

On mobile phones it's hard to be very precise when pressing buttons. Make sure all interactive elements are 44x44 or larger. One way to do this is to leave enough space for the element, padding, minWidth and minHeight style values can be useful for that. Alternatively, you can use hitSlop prop to increase interactive area without affecting the layout. Here's a demo:

Try it on your phone

Use Android Ripple

Android API 21+ uses the material design ripple to provide user with feedback when they touch an interactable area on the screen. React Native exposes this through the TouchableNativeFeedback component. Using this touchable effect instead of opacity or highlight will often make your app feel much more fitting on the platform. That said, you need to be careful when using it because it doesn't work on iOS or on Android API < 21, so you will need to fallback to using one of the other Touchable components on iOS. You can use a library like react-native-platform-touchable to handle the platform differences for you.

Try it on your phone

Screen orientation lock

Multiple screen orientations should work fine by default unless you're using Dimensions API and don't handle orientation changes. If you don't want to support multiple screen orientations, you can lock the screen orientation to either portrait or landscape.

On iOS, in the General tab and Deployment Info section of Xcode enable the Device Orientation you want to support (ensure you have selected iPhone from the Devices menu when making the changes). For Android, open the AndroidManifest.xml file and within the activity element add 'android:screenOrientation="portrait"' to lock to portrait or 'android:screenOrientation="landscape"' to lock to landscape.

Learn more

Material Design and Human Interface Guidelines are great resources for learning more about designing for mobile platforms.

Edit this page
Last updated on
- + diff --git a/docs/0.62/improvingux/index.html b/docs/0.62/improvingux/index.html index cea02e94f32..c912c64ab1a 100644 --- a/docs/0.62/improvingux/index.html +++ b/docs/0.62/improvingux/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Improving User Experience

Configure text inputs

Entering text on touch phone is a challenge - small screen, software keyboard. But based on what kind of data you need, you can make it easier by properly configuring the text inputs:

  • Focus the first field automatically
  • Use placeholder text as an example of expected data format
  • Enable or disable autocapitalization and autocorrect
  • Choose keyboard type (e.g. email, numeric)
  • Make sure the return button focuses the next field or submits the form

Check out TextInput docs for more configuration options.

Try it on your phone

Manage layout when keyboard is visible

Software keyboard takes almost half of the screen. If you have interactive elements that can get covered by the keyboard, make sure they are still accessible by using the KeyboardAvoidingView component.

Try it on your phone

Make tappable areas larger

On mobile phones it's hard to be very precise when pressing buttons. Make sure all interactive elements are 44x44 or larger. One way to do this is to leave enough space for the element, padding, minWidth and minHeight style values can be useful for that. Alternatively, you can use hitSlop prop to increase interactive area without affecting the layout. Here's a demo:

Try it on your phone

Use Android Ripple

Android API 21+ uses the material design ripple to provide user with feedback when they touch an interactable area on the screen. React Native exposes this through the TouchableNativeFeedback component. Using this touchable effect instead of opacity or highlight will often make your app feel much more fitting on the platform. That said, you need to be careful when using it because it doesn't work on iOS or on Android API < 21, so you will need to fallback to using one of the other Touchable components on iOS. You can use a library like react-native-platform-touchable to handle the platform differences for you.

Try it on your phone

Screen orientation lock

Multiple screen orientations should work fine by default unless you're using Dimensions API and don't handle orientation changes. If you don't want to support multiple screen orientations, you can lock the screen orientation to either portrait or landscape.

On iOS, in the General tab and Deployment Info section of Xcode enable the Device Orientation you want to support (ensure you have selected iPhone from the Devices menu when making the changes). For Android, open the AndroidManifest.xml file and within the activity element add 'android:screenOrientation="portrait"' to lock to portrait or 'android:screenOrientation="landscape"' to lock to landscape.

Learn more

Material Design and Human Interface Guidelines are great resources for learning more about designing for mobile platforms.

Edit this page
Last updated on
- + diff --git a/docs/0.62/inputaccessoryview.html b/docs/0.62/inputaccessoryview.html index 1a14fda4303..7bb6e42e8ad 100644 --- a/docs/0.62/inputaccessoryview.html +++ b/docs/0.62/inputaccessoryview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

InputAccessoryView

A component which enables customization of the keyboard input accessory view on iOS. The input accessory view is displayed above the keyboard whenever a TextInput has focus. This component can be used to create custom toolbars.

To use this component wrap your custom toolbar with the InputAccessoryView component, and set a nativeID. Then, pass that nativeID as the inputAccessoryViewID of whatever TextInput you desire. A basic example:

This component can also be used to create sticky text inputs (text inputs which are anchored to the top of the keyboard). To do this, wrap a TextInput with the InputAccessoryView component, and don't set a nativeID. For an example, look at InputAccessoryViewExample.js.

Reference

Props

backgroundColor

TypeRequired
colorNo

nativeID

An ID which is used to associate this InputAccessoryView to specified TextInput(s).

TypeRequired
stringNo

style

TypeRequired
styleNo

Known issues

Edit this page
Last updated on
- + diff --git a/docs/0.62/inputaccessoryview/index.html b/docs/0.62/inputaccessoryview/index.html index 1a14fda4303..7bb6e42e8ad 100644 --- a/docs/0.62/inputaccessoryview/index.html +++ b/docs/0.62/inputaccessoryview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

InputAccessoryView

A component which enables customization of the keyboard input accessory view on iOS. The input accessory view is displayed above the keyboard whenever a TextInput has focus. This component can be used to create custom toolbars.

To use this component wrap your custom toolbar with the InputAccessoryView component, and set a nativeID. Then, pass that nativeID as the inputAccessoryViewID of whatever TextInput you desire. A basic example:

This component can also be used to create sticky text inputs (text inputs which are anchored to the top of the keyboard). To do this, wrap a TextInput with the InputAccessoryView component, and don't set a nativeID. For an example, look at InputAccessoryViewExample.js.

Reference

Props

backgroundColor

TypeRequired
colorNo

nativeID

An ID which is used to associate this InputAccessoryView to specified TextInput(s).

TypeRequired
stringNo

style

TypeRequired
styleNo

Known issues

Edit this page
Last updated on
- + diff --git a/docs/0.62/integration-with-existing-apps.html b/docs/0.62/integration-with-existing-apps.html index 0b39e1adf1b..f33ae8a7de3 100644 --- a/docs/0.62/integration-with-existing-apps.html +++ b/docs/0.62/integration-with-existing-apps.html @@ -19,7 +19,7 @@ - + @@ -48,7 +48,7 @@
if (mReactInstanceManager != null) {
mReactInstanceManager.onHostDestroy(this);
}
if (mReactRootView != null) {
mReactRootView.unmountReactApplication();
}
}

We also need to pass back button events to React Native:

@Override
public void onBackPressed() {
if (mReactInstanceManager != null) {
mReactInstanceManager.onBackPressed();
} else {
super.onBackPressed();
}
}

This allows JavaScript to control what happens when the user presses the hardware back button (e.g. to implement navigation). When JavaScript doesn't handle the back button press, your invokeDefaultOnBackPressed method will be called. By default this finishes your Activity.

Finally, we need to hook up the dev menu. By default, this is activated by (rage) shaking the device, but this is not very useful in emulators. So we make it show when you press the hardware menu button (use Ctrl + M if you're using Android Studio emulator):

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
if (keyCode == KeyEvent.KEYCODE_MENU && mReactInstanceManager != null) {
mReactInstanceManager.showDevOptionsDialog();
return true;
}
return super.onKeyUp(keyCode, event);
}

Now your activity is ready to run some JavaScript code.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ yarn start
2. Run the app

Now build and run your Android app as normal.

Once you reach your React-powered activity inside the app, it should load the JavaScript code from the development server and display:

Screenshot

Creating a release build in Android Studio

You can use Android Studio to create your release builds too! It’s as quick as creating release builds of your previously-existing native Android app. There’s one additional step, which you’ll have to do before every release build. You need to execute the following to create a React Native bundle, which will be included with your native Android app:

$ npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/com/your-company-name/app-package-name/src/main/assets/index.android.bundle --assets-dest android/com/your-company-name/app-package-name/src/main/res/

Don’t forget to replace the paths with correct ones and create the assets folder if it doesn’t exist.

Now, create a release build of your native app from within Android Studio as usual and you should be good to go!

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.62/integration-with-existing-apps/index.html b/docs/0.62/integration-with-existing-apps/index.html index 0b39e1adf1b..f33ae8a7de3 100644 --- a/docs/0.62/integration-with-existing-apps/index.html +++ b/docs/0.62/integration-with-existing-apps/index.html @@ -19,7 +19,7 @@ - + @@ -48,7 +48,7 @@
if (mReactInstanceManager != null) {
mReactInstanceManager.onHostDestroy(this);
}
if (mReactRootView != null) {
mReactRootView.unmountReactApplication();
}
}

We also need to pass back button events to React Native:

@Override
public void onBackPressed() {
if (mReactInstanceManager != null) {
mReactInstanceManager.onBackPressed();
} else {
super.onBackPressed();
}
}

This allows JavaScript to control what happens when the user presses the hardware back button (e.g. to implement navigation). When JavaScript doesn't handle the back button press, your invokeDefaultOnBackPressed method will be called. By default this finishes your Activity.

Finally, we need to hook up the dev menu. By default, this is activated by (rage) shaking the device, but this is not very useful in emulators. So we make it show when you press the hardware menu button (use Ctrl + M if you're using Android Studio emulator):

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
if (keyCode == KeyEvent.KEYCODE_MENU && mReactInstanceManager != null) {
mReactInstanceManager.showDevOptionsDialog();
return true;
}
return super.onKeyUp(keyCode, event);
}

Now your activity is ready to run some JavaScript code.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ yarn start
2. Run the app

Now build and run your Android app as normal.

Once you reach your React-powered activity inside the app, it should load the JavaScript code from the development server and display:

Screenshot

Creating a release build in Android Studio

You can use Android Studio to create your release builds too! It’s as quick as creating release builds of your previously-existing native Android app. There’s one additional step, which you’ll have to do before every release build. You need to execute the following to create a React Native bundle, which will be included with your native Android app:

$ npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/com/your-company-name/app-package-name/src/main/assets/index.android.bundle --assets-dest android/com/your-company-name/app-package-name/src/main/res/

Don’t forget to replace the paths with correct ones and create the assets folder if it doesn’t exist.

Now, create a release build of your native app from within Android Studio as usual and you should be good to go!

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.62/interactionmanager.html b/docs/0.62/interactionmanager.html index 28f43a6bbdf..c82dc8428f1 100644 --- a/docs/0.62/interactionmanager.html +++ b/docs/0.62/interactionmanager.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

InteractionManager

InteractionManager allows long-running work to be scheduled after any interactions/animations have completed. In particular, this allows JavaScript animations to run smoothly.

Applications can schedule tasks to run after interactions with the following:

InteractionManager.runAfterInteractions(() => {
// ...long-running synchronous task...
});

Compare this to other scheduling alternatives:

  • requestAnimationFrame(): for code that animates a view over time.
  • setImmediate/setTimeout(): run code later, note this may delay animations.
  • runAfterInteractions(): run code later, without delaying active animations.

The touch handling system considers one or more active touches to be an 'interaction' and will delay runAfterInteractions() callbacks until all touches have ended or been cancelled.

InteractionManager also allows applications to register animations by creating an interaction 'handle' on animation start, and clearing it upon completion:

var handle = InteractionManager.createInteractionHandle();
// run animation... (`runAfterInteractions` tasks are queued)
// later, on animation completion:
InteractionManager.clearInteractionHandle(handle);
// queued tasks run if all handles were cleared

runAfterInteractions takes either a plain callback function, or a PromiseTask object with a gen method that returns a Promise. If a PromiseTask is supplied, then it is fully resolved (including asynchronous dependencies that also schedule more tasks via runAfterInteractions) before starting on the next task that might have been queued up synchronously earlier.

By default, queued tasks are executed together in a loop in one setImmediate batch. If setDeadline is called with a positive number, then tasks will only be executed until the deadline (in terms of js event loop run time) approaches, at which point execution will yield via setTimeout, allowing events such as touches to start interactions and block queued tasks from executing, making apps more responsive.

Example

Basic

Advanced

Note: InteractionManager.runAfterInteractions() is not working properly on web. It triggers immediately without waiting until the interaction is finished.

Reference

Methods

runAfterInteractions()

static runAfterInteractions(task)

Schedule a function to run after all interactions have completed. Returns a cancellable "promise".

createInteractionHandle()

static createInteractionHandle()

Notify manager that an interaction has started.

clearInteractionHandle()

static clearInteractionHandle(handle)

Notify manager that an interaction has completed.

setDeadline()

static setDeadline(deadline)

A positive number will use setTimeout to schedule any tasks after the eventLoopRunningTime hits the deadline value, otherwise all tasks will be executed in one setImmediate batch (default).

Properties

Edit this page
Last updated on
- + diff --git a/docs/0.62/interactionmanager/index.html b/docs/0.62/interactionmanager/index.html index 28f43a6bbdf..c82dc8428f1 100644 --- a/docs/0.62/interactionmanager/index.html +++ b/docs/0.62/interactionmanager/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

InteractionManager

InteractionManager allows long-running work to be scheduled after any interactions/animations have completed. In particular, this allows JavaScript animations to run smoothly.

Applications can schedule tasks to run after interactions with the following:

InteractionManager.runAfterInteractions(() => {
// ...long-running synchronous task...
});

Compare this to other scheduling alternatives:

  • requestAnimationFrame(): for code that animates a view over time.
  • setImmediate/setTimeout(): run code later, note this may delay animations.
  • runAfterInteractions(): run code later, without delaying active animations.

The touch handling system considers one or more active touches to be an 'interaction' and will delay runAfterInteractions() callbacks until all touches have ended or been cancelled.

InteractionManager also allows applications to register animations by creating an interaction 'handle' on animation start, and clearing it upon completion:

var handle = InteractionManager.createInteractionHandle();
// run animation... (`runAfterInteractions` tasks are queued)
// later, on animation completion:
InteractionManager.clearInteractionHandle(handle);
// queued tasks run if all handles were cleared

runAfterInteractions takes either a plain callback function, or a PromiseTask object with a gen method that returns a Promise. If a PromiseTask is supplied, then it is fully resolved (including asynchronous dependencies that also schedule more tasks via runAfterInteractions) before starting on the next task that might have been queued up synchronously earlier.

By default, queued tasks are executed together in a loop in one setImmediate batch. If setDeadline is called with a positive number, then tasks will only be executed until the deadline (in terms of js event loop run time) approaches, at which point execution will yield via setTimeout, allowing events such as touches to start interactions and block queued tasks from executing, making apps more responsive.

Example

Basic

Advanced

Note: InteractionManager.runAfterInteractions() is not working properly on web. It triggers immediately without waiting until the interaction is finished.

Reference

Methods

runAfterInteractions()

static runAfterInteractions(task)

Schedule a function to run after all interactions have completed. Returns a cancellable "promise".

createInteractionHandle()

static createInteractionHandle()

Notify manager that an interaction has started.

clearInteractionHandle()

static clearInteractionHandle(handle)

Notify manager that an interaction has completed.

setDeadline()

static setDeadline(deadline)

A positive number will use setTimeout to schedule any tasks after the eventLoopRunningTime hits the deadline value, otherwise all tasks will be executed in one setImmediate batch (default).

Properties

Edit this page
Last updated on
- + diff --git a/docs/0.62/intro-react-native-components.html b/docs/0.62/intro-react-native-components.html index c8db93039c2..d38cb9a3861 100644 --- a/docs/0.62/intro-react-native-components.html +++ b/docs/0.62/intro-react-native-components.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Core Components and Native Components

React Native is an open source framework for building Android and iOS applications using React and the app platform’s native capabilities. With React Native, you use JavaScript to access your platform’s APIs as well as to describe the appearance and behavior of your UI using React components: bundles of reusable, nestable code. You can learn more about React in the next section. But first, let’s cover how components work in React Native.

Views and mobile development

In Android and iOS development, a view is the basic building block of UI: a small rectangular element on the screen which can be used to display text, images, or respond to user input. Even the smallest visual elements of an app, like a line of text or a button, are kinds of views. Some kinds of views can contain other views. It’s views all the way down!

Diagram of Android and iOS app showing them both built on top of atomic elements called views.
Just a sampling of the many views used in Android and iOS apps.

Native Components

In Android development, you write views in Kotlin or Java; in iOS development, you use Swift or Objective-C. With React Native, you can invoke these views with JavaScript using React components. At runtime, React Native creates the corresponding Android and iOS views for those components. Because React Native components are backed by the same views as Android and iOS, React Native apps look, feel, and perform like any other apps. We call these platform-backed components Native Components.

React Native lets you to build your own Native Components for Android and iOS to suit your app’s unique needs. We also have a thriving ecosystem of these community-contributed components. Check out React Native Directory to find what the community has been creating.

React Native also includes a set of essential, ready-to-use Native Components you can use to start building your app today. These are React Native's Core Components.

Core Components

React Native has many Core Components for everything from form controls to activity indicators. You can find them all documented in the API section. You will mostly work with the following Core Components:

React Native UI ComponentAndroid ViewiOS ViewWeb AnalogDescription
<View><ViewGroup><UIView>A non-scrollling <div>A container that supports layout with flexbox, style, some touch handling, and accessibility controls
<Text><TextView><UITextView><p>Displays, styles, and nests strings of text and even handles touch events
<Image><ImageView><UIImageView><img>Displays different types of images
<ScrollView><ScrollView><UIScrollView><div>A generic scrolling container that can contain multiple components and views
<TextInput><EditText><UITextField><input type="text">Allows the user to enter text

In the next section, you will start combining these Core Components to learn about how React works. Have a play with them here now!

Because React Native uses the same API structure as React components, you’ll need to understand React component APIs to get started. The next section makes for a quick introduction or refresher on the topic. However, if you’re already familiar with React, feel free to skip ahead.

A diagram showing React Native's Core Components are a subset of React Components that ship with React Native.
Edit this page
Last updated on
- + diff --git a/docs/0.62/intro-react-native-components/index.html b/docs/0.62/intro-react-native-components/index.html index c8db93039c2..d38cb9a3861 100644 --- a/docs/0.62/intro-react-native-components/index.html +++ b/docs/0.62/intro-react-native-components/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Core Components and Native Components

React Native is an open source framework for building Android and iOS applications using React and the app platform’s native capabilities. With React Native, you use JavaScript to access your platform’s APIs as well as to describe the appearance and behavior of your UI using React components: bundles of reusable, nestable code. You can learn more about React in the next section. But first, let’s cover how components work in React Native.

Views and mobile development

In Android and iOS development, a view is the basic building block of UI: a small rectangular element on the screen which can be used to display text, images, or respond to user input. Even the smallest visual elements of an app, like a line of text or a button, are kinds of views. Some kinds of views can contain other views. It’s views all the way down!

Diagram of Android and iOS app showing them both built on top of atomic elements called views.
Just a sampling of the many views used in Android and iOS apps.

Native Components

In Android development, you write views in Kotlin or Java; in iOS development, you use Swift or Objective-C. With React Native, you can invoke these views with JavaScript using React components. At runtime, React Native creates the corresponding Android and iOS views for those components. Because React Native components are backed by the same views as Android and iOS, React Native apps look, feel, and perform like any other apps. We call these platform-backed components Native Components.

React Native lets you to build your own Native Components for Android and iOS to suit your app’s unique needs. We also have a thriving ecosystem of these community-contributed components. Check out React Native Directory to find what the community has been creating.

React Native also includes a set of essential, ready-to-use Native Components you can use to start building your app today. These are React Native's Core Components.

Core Components

React Native has many Core Components for everything from form controls to activity indicators. You can find them all documented in the API section. You will mostly work with the following Core Components:

React Native UI ComponentAndroid ViewiOS ViewWeb AnalogDescription
<View><ViewGroup><UIView>A non-scrollling <div>A container that supports layout with flexbox, style, some touch handling, and accessibility controls
<Text><TextView><UITextView><p>Displays, styles, and nests strings of text and even handles touch events
<Image><ImageView><UIImageView><img>Displays different types of images
<ScrollView><ScrollView><UIScrollView><div>A generic scrolling container that can contain multiple components and views
<TextInput><EditText><UITextField><input type="text">Allows the user to enter text

In the next section, you will start combining these Core Components to learn about how React works. Have a play with them here now!

Because React Native uses the same API structure as React components, you’ll need to understand React component APIs to get started. The next section makes for a quick introduction or refresher on the topic. However, if you’re already familiar with React, feel free to skip ahead.

A diagram showing React Native's Core Components are a subset of React Components that ship with React Native.
Edit this page
Last updated on
- + diff --git a/docs/0.62/intro-react.html b/docs/0.62/intro-react.html index 976db09c1a9..05e801dd345 100644 --- a/docs/0.62/intro-react.html +++ b/docs/0.62/intro-react.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

React Fundamentals

React Native runs on React, a popular open source library for building user interfaces with JavaScript. To make the most of React Native, it helps to understand React itself. This section can get you started or can serve as a refresher course.

We’re going to cover the core concepts behind React:

  • components
  • JSX
  • props
  • state

If you want to dig deeper, we encourage you to check out React’s official documentation.

Your first component

The rest of this introduction to React uses cats in its examples: friendly, approachable creatures that need names and a cafe to work in. Here is your very first Cat component:

Here is how you do it: To define your Cat component, first use JavaScript’s import to import React and React Native’s Text Core Component:

import React from 'react';
import { Text } from 'react-native';

Your component starts as a function:

function Cat() {}

You can think of components as blueprints. Whatever a function component returns is rendered as a React element. React elements let you describe what you want to see on the screen.

Here the Cat component will render a <Text> element:

function Cat() {
return <Text>Hello, I am your cat!</Text>;
}

You can export your function component with JavaScript’s export default for use throughout your app like so:

export default function Cat() {
return <Text>Hello, I am your cat!</Text>;
}

This is one of many ways to export your component. This kind of export works well with the Snack Player. However, depending on your app’s file structure, you might need to use a different convention. This handy cheatsheet on JavaScript imports and exports can help.

Now take a closer look at that return statement. <Text>Hello, I am your cat!</Text> is using a kind of JavaScript syntax that makes writing elements convenient: JSX.

JSX

React and React Native use JSX, a syntax that lets you write elements inside JavaScript like so: <Text>Hello, I am your cat!</Text>. The React docs have a comprehensive guide to JSX you can reference to learn even more. Because JSX is JavaScript, you can use variables inside it. Here you are declaring a name for the cat, name, and embedding it with curly braces inside <Text>.

Any JavaScript expression will work between curly braces, including function calls like {getFullName("Rum", Tum", "Tugger")}:

You can think of curly braces as creating a portal into JS functionality in your JSX!

Because JSX is included in the React library, it won’t work if you don’t have import React from 'react' at the top of your file!

Custom Components

You’ve already met React Native’s Core Components. React lets you nest these components inside each other to create new components. These nestable, reusable components are at the heart of the React paradigm.

For example, you can nest Text and TextInput inside a View below, and React Native will render them together:

Developer notes

If you’re familiar with web development, <View> and <Text> might remind you of HTML! You can think of them as the <div> and <p> tags of application development.

You can render this component multiple times and multiple places without repeating your code by using <Cat>:

Any component that renders other components is a parent component. Here, Cafe is the parent component and each Cat is a child component.

You can put as many cats in your cafe as you like. Each <Cat> renders a unique element—which you can customize with props.

Props

Props is short for “properties.” Props let you customize React components. For example, here you pass each <Cat> a different name for Cat to render:

Most of React Native’s Core Components can be customized with props, too. For example, when using Image, you pass it a prop named source to define what image it shows:

Image has many different props, including style, which accepts a JS object of design and layout related property-value pairs.

Notice the double curly braces {{ }} surrounding style‘s width and height. In JSX, JavaScript values are referenced with {}. This is handy if you are passing something other than a string as props, like an array or number: <Cat food={["fish", "kibble"]} /> age={2}. However, JS objects are also denoted with curly braces: {width: 200, height: 200}. Therefore, to pass a JS object in JSX, you must wrap the object in another pair of curly braces: {{width: 200, height: 200}}

You can build many things with props and the Core Components Text, Image, and View! But to build something interactive, you’ll need state.

State

While you can think of props as arguments you use to configure how components render, state is like a component’s personal data storage. State is useful for handling data that changes over time or that comes from user interaction. State gives your components memory!

As a general rule, use props to configure a component when it renders. Use state to keep track of any component data that you expect to change over time.

The following example takes place in a cat cafe where two hungry cats are waiting to be fed. Their hunger, which we expect to change over time (unlike their names), is stored as state. To feed the cats, press their buttons—which will update their state.

You can add state to a component by calling React’s useState Hook. A Hook is a kind of function that lets you “hook into” React features. For example, useState is a Hook that lets you add state to function components. You can learn more about other kinds of Hooks in the React documentation.

First, you will want to import useState from React like so:

import React, { useState } from 'react';

Then you declare the component’s state by calling useState inside its function. In this example, useState creates an isHungry state variable:

function Cat(props) {
const [isHungry, setIsHungry] = useState(true);
// ...
}

You can use useState to track any kind of data: strings, numbers, Booleans, arrays, objects. For example, you can track the number of times a cat has been petted with const [timesPetted, setTimesPetted] = useState(0)!

Calling useState does two things:

  • it creates a “state variable” with an initial value—in this case the state variable is isHungry and its initial value is true
  • it creates a function to set that state variable’s value—setIsHungry

It doesn’t matter what names you use. But it can be handy to think of the pattern as [<getter>, <setter>] = useState(<initialValue>).

Next you add the Button Core Component and give it an onPress prop:

<Button
onPress={() => {
setIsHungry(false);
}}
//..
/>

Now, when someone presses the button, onPress will fire, calling the setIsHungry(false). This sets the state variable isHungry to false. When isHungry is false, the Button’s disabled prop is set to true and its title also changes:

<Button
//..
disabled={!isHungry}
title={isHungry ? 'Pour me some milk, please!' : 'Thank you!'}
/>

You might’ve noticed that although isHungry is a const, it is seemingly reassignable! What is happening is when a state-setting function like setIsHungry is called, its component will re-render. In this case the Cat function will run again—and this time, useState will give us the next value of isHungry.

Finally, put your cats inside a Cafe component:

export default function Cafe() {
return (
<>
<Cat name="Munkustrap" />
<Cat name="Spot" />
</>
);
}

See the <> and </> above? These bits of JSX are fragments. Adjacent JSX elements must be wrapped in an enclosing tag. Fragments let you do that without nesting an extra, unnecessary wrapping element like View.

Now that you’ve covered both React and React Native’s Core Components, let’s dive deeper on some of these core components by looking at handling <TextInput>.

Edit this page
Last updated on
- + diff --git a/docs/0.62/intro-react/index.html b/docs/0.62/intro-react/index.html index 976db09c1a9..05e801dd345 100644 --- a/docs/0.62/intro-react/index.html +++ b/docs/0.62/intro-react/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

React Fundamentals

React Native runs on React, a popular open source library for building user interfaces with JavaScript. To make the most of React Native, it helps to understand React itself. This section can get you started or can serve as a refresher course.

We’re going to cover the core concepts behind React:

  • components
  • JSX
  • props
  • state

If you want to dig deeper, we encourage you to check out React’s official documentation.

Your first component

The rest of this introduction to React uses cats in its examples: friendly, approachable creatures that need names and a cafe to work in. Here is your very first Cat component:

Here is how you do it: To define your Cat component, first use JavaScript’s import to import React and React Native’s Text Core Component:

import React from 'react';
import { Text } from 'react-native';

Your component starts as a function:

function Cat() {}

You can think of components as blueprints. Whatever a function component returns is rendered as a React element. React elements let you describe what you want to see on the screen.

Here the Cat component will render a <Text> element:

function Cat() {
return <Text>Hello, I am your cat!</Text>;
}

You can export your function component with JavaScript’s export default for use throughout your app like so:

export default function Cat() {
return <Text>Hello, I am your cat!</Text>;
}

This is one of many ways to export your component. This kind of export works well with the Snack Player. However, depending on your app’s file structure, you might need to use a different convention. This handy cheatsheet on JavaScript imports and exports can help.

Now take a closer look at that return statement. <Text>Hello, I am your cat!</Text> is using a kind of JavaScript syntax that makes writing elements convenient: JSX.

JSX

React and React Native use JSX, a syntax that lets you write elements inside JavaScript like so: <Text>Hello, I am your cat!</Text>. The React docs have a comprehensive guide to JSX you can reference to learn even more. Because JSX is JavaScript, you can use variables inside it. Here you are declaring a name for the cat, name, and embedding it with curly braces inside <Text>.

Any JavaScript expression will work between curly braces, including function calls like {getFullName("Rum", Tum", "Tugger")}:

You can think of curly braces as creating a portal into JS functionality in your JSX!

Because JSX is included in the React library, it won’t work if you don’t have import React from 'react' at the top of your file!

Custom Components

You’ve already met React Native’s Core Components. React lets you nest these components inside each other to create new components. These nestable, reusable components are at the heart of the React paradigm.

For example, you can nest Text and TextInput inside a View below, and React Native will render them together:

Developer notes

If you’re familiar with web development, <View> and <Text> might remind you of HTML! You can think of them as the <div> and <p> tags of application development.

You can render this component multiple times and multiple places without repeating your code by using <Cat>:

Any component that renders other components is a parent component. Here, Cafe is the parent component and each Cat is a child component.

You can put as many cats in your cafe as you like. Each <Cat> renders a unique element—which you can customize with props.

Props

Props is short for “properties.” Props let you customize React components. For example, here you pass each <Cat> a different name for Cat to render:

Most of React Native’s Core Components can be customized with props, too. For example, when using Image, you pass it a prop named source to define what image it shows:

Image has many different props, including style, which accepts a JS object of design and layout related property-value pairs.

Notice the double curly braces {{ }} surrounding style‘s width and height. In JSX, JavaScript values are referenced with {}. This is handy if you are passing something other than a string as props, like an array or number: <Cat food={["fish", "kibble"]} /> age={2}. However, JS objects are also denoted with curly braces: {width: 200, height: 200}. Therefore, to pass a JS object in JSX, you must wrap the object in another pair of curly braces: {{width: 200, height: 200}}

You can build many things with props and the Core Components Text, Image, and View! But to build something interactive, you’ll need state.

State

While you can think of props as arguments you use to configure how components render, state is like a component’s personal data storage. State is useful for handling data that changes over time or that comes from user interaction. State gives your components memory!

As a general rule, use props to configure a component when it renders. Use state to keep track of any component data that you expect to change over time.

The following example takes place in a cat cafe where two hungry cats are waiting to be fed. Their hunger, which we expect to change over time (unlike their names), is stored as state. To feed the cats, press their buttons—which will update their state.

You can add state to a component by calling React’s useState Hook. A Hook is a kind of function that lets you “hook into” React features. For example, useState is a Hook that lets you add state to function components. You can learn more about other kinds of Hooks in the React documentation.

First, you will want to import useState from React like so:

import React, { useState } from 'react';

Then you declare the component’s state by calling useState inside its function. In this example, useState creates an isHungry state variable:

function Cat(props) {
const [isHungry, setIsHungry] = useState(true);
// ...
}

You can use useState to track any kind of data: strings, numbers, Booleans, arrays, objects. For example, you can track the number of times a cat has been petted with const [timesPetted, setTimesPetted] = useState(0)!

Calling useState does two things:

  • it creates a “state variable” with an initial value—in this case the state variable is isHungry and its initial value is true
  • it creates a function to set that state variable’s value—setIsHungry

It doesn’t matter what names you use. But it can be handy to think of the pattern as [<getter>, <setter>] = useState(<initialValue>).

Next you add the Button Core Component and give it an onPress prop:

<Button
onPress={() => {
setIsHungry(false);
}}
//..
/>

Now, when someone presses the button, onPress will fire, calling the setIsHungry(false). This sets the state variable isHungry to false. When isHungry is false, the Button’s disabled prop is set to true and its title also changes:

<Button
//..
disabled={!isHungry}
title={isHungry ? 'Pour me some milk, please!' : 'Thank you!'}
/>

You might’ve noticed that although isHungry is a const, it is seemingly reassignable! What is happening is when a state-setting function like setIsHungry is called, its component will re-render. In this case the Cat function will run again—and this time, useState will give us the next value of isHungry.

Finally, put your cats inside a Cafe component:

export default function Cafe() {
return (
<>
<Cat name="Munkustrap" />
<Cat name="Spot" />
</>
);
}

See the <> and </> above? These bits of JSX are fragments. Adjacent JSX elements must be wrapped in an enclosing tag. Fragments let you do that without nesting an extra, unnecessary wrapping element like View.

Now that you’ve covered both React and React Native’s Core Components, let’s dive deeper on some of these core components by looking at handling <TextInput>.

Edit this page
Last updated on
- + diff --git a/docs/0.62/javascript-environment.html b/docs/0.62/javascript-environment.html index 0fbc1702fce..8e02c0697c0 100644 --- a/docs/0.62/javascript-environment.html +++ b/docs/0.62/javascript-environment.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

JavaScript Environment

JavaScript Runtime

When using React Native, you're going to be running your JavaScript code in two environments:

  • In most cases, React Native will use JavaScriptCore, the JavaScript engine that powers Safari. Note that on iOS, JavaScriptCore does not use JIT due to the absence of writable executable memory in iOS apps.
  • When using Chrome debugging, all JavaScript code runs within Chrome itself, communicating with native code via WebSockets. Chrome uses V8 as its JavaScript engine.

While both environments are very similar, you may end up hitting some inconsistencies. We're likely going to experiment with other JavaScript engines in the future, so it's best to avoid relying on specifics of any runtime.

JavaScript Syntax Transformers

Syntax transformers make writing code more enjoyable by allowing you to use new JavaScript syntax without having to wait for support on all interpreters.

React Native ships with the Babel JavaScript compiler. Check Babel documentation on its supported transformations for more details.

A full list of React Native's enabled transformations can be found in metro-react-native-babel-preset.

ES5

  • Reserved Words: promise.catch(function() { });

ES6

ES8

Stage 3

Specific

  • JSX: <View style={{color: 'red'}} />
  • Flow: function foo(x: ?number): string {};
  • TypeScript: function foo(x: number | undefined): string {};
  • Babel Template: allows AST templating

Polyfills

Many standards functions are also available on all the supported JavaScript runtimes.

Browser

ES6

ES7

ES8

Specific

  • __DEV__
Edit this page
Last updated on
- + diff --git a/docs/0.62/javascript-environment/index.html b/docs/0.62/javascript-environment/index.html index 0fbc1702fce..8e02c0697c0 100644 --- a/docs/0.62/javascript-environment/index.html +++ b/docs/0.62/javascript-environment/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

JavaScript Environment

JavaScript Runtime

When using React Native, you're going to be running your JavaScript code in two environments:

  • In most cases, React Native will use JavaScriptCore, the JavaScript engine that powers Safari. Note that on iOS, JavaScriptCore does not use JIT due to the absence of writable executable memory in iOS apps.
  • When using Chrome debugging, all JavaScript code runs within Chrome itself, communicating with native code via WebSockets. Chrome uses V8 as its JavaScript engine.

While both environments are very similar, you may end up hitting some inconsistencies. We're likely going to experiment with other JavaScript engines in the future, so it's best to avoid relying on specifics of any runtime.

JavaScript Syntax Transformers

Syntax transformers make writing code more enjoyable by allowing you to use new JavaScript syntax without having to wait for support on all interpreters.

React Native ships with the Babel JavaScript compiler. Check Babel documentation on its supported transformations for more details.

A full list of React Native's enabled transformations can be found in metro-react-native-babel-preset.

ES5

  • Reserved Words: promise.catch(function() { });

ES6

ES8

Stage 3

Specific

  • JSX: <View style={{color: 'red'}} />
  • Flow: function foo(x: ?number): string {};
  • TypeScript: function foo(x: number | undefined): string {};
  • Babel Template: allows AST templating

Polyfills

Many standards functions are also available on all the supported JavaScript runtimes.

Browser

ES6

ES7

ES8

Specific

  • __DEV__
Edit this page
Last updated on
- + diff --git a/docs/0.62/keyboard.html b/docs/0.62/keyboard.html index c1c0fa18aee..15cdecb75ca 100644 --- a/docs/0.62/keyboard.html +++ b/docs/0.62/keyboard.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Keyboard

Keyboard module to control keyboard events.

Usage

The Keyboard module allows you to listen for native events and react to them, as well as make changes to the keyboard, like dismissing it.

Reference

Methods

addListener()

static addListener(eventName, callback)

The addListener function connects a JavaScript function to an identified native keyboard notification event.

This function then returns the reference to the listener.

Parameters:

NameTypeRequiredDescription
eventNamestringYesThe nativeEvent is the string that identifies the event you're listening for. See below
callbackfunctionYesThe function to be called when the event fires

nativeEvent

This can be any of the following

  • keyboardWillShow
  • keyboardDidShow
  • keyboardWillHide
  • keyboardDidHide
  • keyboardWillChangeFrame
  • keyboardDidChangeFrame

Note that if you set android:windowSoftInputMode to adjustResize or adjustPan, only keyboardDidShow and keyboardDidHide events will be available on Android. If you set android:windowSoftInputMode to adjustNothing, no events will be available on Android. keyboardWillShow as well as keyboardWillHide are generally not available on Android since there is no native corresponding event.

removeListener()

static removeListener(eventName, callback)

Removes a specific listener.

Parameters:

NameTypeRequiredDescription
eventNamestringYesThe nativeEvent is the string that identifies the event you're listening for
callbackfunctionYesThe function to be called when the event fires

removeAllListeners()

static removeAllListeners(eventName)

Removes all listeners for a specific event type.

Parameters:

NameTypeRequiredDescription
eventTypestringYesThe native event string listeners are watching which will be removed

dismiss()

static dismiss()

Dismisses the active keyboard and removes focus.

scheduleLayoutAnimation

static scheduleLayoutAnimation(event)

Useful for syncing TextInput (or other keyboard accessory view) size of position changes with keyboard movements.

Edit this page
Last updated on
- + diff --git a/docs/0.62/keyboard/index.html b/docs/0.62/keyboard/index.html index c1c0fa18aee..15cdecb75ca 100644 --- a/docs/0.62/keyboard/index.html +++ b/docs/0.62/keyboard/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Keyboard

Keyboard module to control keyboard events.

Usage

The Keyboard module allows you to listen for native events and react to them, as well as make changes to the keyboard, like dismissing it.

Reference

Methods

addListener()

static addListener(eventName, callback)

The addListener function connects a JavaScript function to an identified native keyboard notification event.

This function then returns the reference to the listener.

Parameters:

NameTypeRequiredDescription
eventNamestringYesThe nativeEvent is the string that identifies the event you're listening for. See below
callbackfunctionYesThe function to be called when the event fires

nativeEvent

This can be any of the following

  • keyboardWillShow
  • keyboardDidShow
  • keyboardWillHide
  • keyboardDidHide
  • keyboardWillChangeFrame
  • keyboardDidChangeFrame

Note that if you set android:windowSoftInputMode to adjustResize or adjustPan, only keyboardDidShow and keyboardDidHide events will be available on Android. If you set android:windowSoftInputMode to adjustNothing, no events will be available on Android. keyboardWillShow as well as keyboardWillHide are generally not available on Android since there is no native corresponding event.

removeListener()

static removeListener(eventName, callback)

Removes a specific listener.

Parameters:

NameTypeRequiredDescription
eventNamestringYesThe nativeEvent is the string that identifies the event you're listening for
callbackfunctionYesThe function to be called when the event fires

removeAllListeners()

static removeAllListeners(eventName)

Removes all listeners for a specific event type.

Parameters:

NameTypeRequiredDescription
eventTypestringYesThe native event string listeners are watching which will be removed

dismiss()

static dismiss()

Dismisses the active keyboard and removes focus.

scheduleLayoutAnimation

static scheduleLayoutAnimation(event)

Useful for syncing TextInput (or other keyboard accessory view) size of position changes with keyboard movements.

Edit this page
Last updated on
- + diff --git a/docs/0.62/keyboardavoidingview.html b/docs/0.62/keyboardavoidingview.html index a60a8ed0809..6ab03bcb5d4 100644 --- a/docs/0.62/keyboardavoidingview.html +++ b/docs/0.62/keyboardavoidingview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

KeyboardAvoidingView

It is a component to solve the common problem of views that need to move out of the way of the virtual keyboard. It can automatically adjust either its height, position, or bottom padding based on the keyboard height.

Example

Reference

Props

Inherits View Props.

behavior

Specify how to react to the presence of the keyboard.

Android and iOS both interact with this prop differently. On both iOS and Android, setting behavior is recommended.

TypeRequired
enum('height', 'position', 'padding')No

contentContainerStyle

The style of the content container(View) when behavior is 'position'.

TypeRequired
View.styleNo

enabled

Enabled or disabled KeyboardAvoidingView. The default is true.

TypeRequired
booleanNo

keyboardVerticalOffset

This is the distance between the top of the user screen and the react native view, may be non-zero in some use cases. Defaults to 0.

TypeRequired
numberNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/keyboardavoidingview/index.html b/docs/0.62/keyboardavoidingview/index.html index a60a8ed0809..6ab03bcb5d4 100644 --- a/docs/0.62/keyboardavoidingview/index.html +++ b/docs/0.62/keyboardavoidingview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

KeyboardAvoidingView

It is a component to solve the common problem of views that need to move out of the way of the virtual keyboard. It can automatically adjust either its height, position, or bottom padding based on the keyboard height.

Example

Reference

Props

Inherits View Props.

behavior

Specify how to react to the presence of the keyboard.

Android and iOS both interact with this prop differently. On both iOS and Android, setting behavior is recommended.

TypeRequired
enum('height', 'position', 'padding')No

contentContainerStyle

The style of the content container(View) when behavior is 'position'.

TypeRequired
View.styleNo

enabled

Enabled or disabled KeyboardAvoidingView. The default is true.

TypeRequired
booleanNo

keyboardVerticalOffset

This is the distance between the top of the user screen and the react native view, may be non-zero in some use cases. Defaults to 0.

TypeRequired
numberNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/layout-props.html b/docs/0.62/layout-props.html index 76e8fdb2226..347032424f2 100644 --- a/docs/0.62/layout-props.html +++ b/docs/0.62/layout-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Layout Props

Example

The following example shows how different properties can affect or shape a React Native layout. You can try for example to add or remove squares from the UI while changing the values of the property flexWrap. Find more detailed examples about this properties in the Layout with Flexbox docs page.

Reference

Props

alignContent

alignContent controls how rows align in the cross direction, overriding the alignContent of the parent. See https://developer.mozilla.org/en-US/docs/Web/CSS/align-content for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'stretch', 'space-between', 'space-around')No

alignItems

alignItems aligns children in the cross direction. For example, if children are flowing vertically, alignItems controls how they align horizontally. It works like align-items in CSS (default: stretch). See https://developer.mozilla.org/en-US/docs/Web/CSS/align-items for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'stretch', 'baseline')No

alignSelf

alignSelf controls how a child aligns in the cross direction, overriding the alignItems of the parent. It works like align-self in CSS (default: auto). See https://developer.mozilla.org/en-US/docs/Web/CSS/align-self for more details.

TypeRequired
enum('auto', 'flex-start', 'flex-end', 'center', 'stretch', 'baseline')No

aspectRatio

Aspect ratio controls the size of the undefined dimension of a node. Aspect ratio is a non-standard property only available in React Native and not CSS.

  • On a node with a set width/height, aspect ratio controls the size of the unset dimension
  • On a node with a set flex basis, aspect ratio controls the size of the node in the cross axis if unset
  • On a node with a measure function, aspect ratio works as though the measure function measures the flex basis
  • On a node with flex grow/shrink, aspect ratio controls the size of the node in the cross axis if unset
  • Aspect ratio takes min/max dimensions into account
TypeRequired
numberNo

borderBottomWidth

borderBottomWidth works like border-bottom-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-width for more details.

TypeRequired
numberNo

borderEndWidth

When direction is ltr, borderEndWidth is equivalent to borderRightWidth. When direction is rtl, borderEndWidth is equivalent to borderLeftWidth.

TypeRequired
numberNo

borderLeftWidth

borderLeftWidth works like border-left-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-left-width for more details.

TypeRequired
numberNo

borderRightWidth

borderRightWidth works like border-right-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-right-width for more details.

TypeRequired
numberNo

borderStartWidth

When direction is ltr, borderStartWidth is equivalent to borderLeftWidth. When direction is rtl, borderStartWidth is equivalent to borderRightWidth.

TypeRequired
numberNo

borderTopWidth

borderTopWidth works like border-top-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-top-width for more details.

TypeRequired
numberNo

borderWidth

borderWidth works like border-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-width for more details.

TypeRequired
numberNo

bottom

bottom is the number of logical pixels to offset the bottom edge of this component.

It works similarly to bottom in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/bottom for more details of how bottom affects layout.

TypeRequired
number, stringNo

direction

direction specifies the directional flow of the user interface. The default is inherit, except for root node which will have value based on the current locale. See https://yogalayout.com/docs/layout-direction for more details.

TypeRequiredPlatform
enum('inherit', 'ltr', 'rtl')NoiOS

display

display sets the display type of this component.

It works similarly to display in CSS but only supports 'flex' and 'none'. 'flex' is the default.

TypeRequired
enum('none', 'flex')No

end

When the direction is ltr, end is equivalent to right. When the direction is rtl, end is equivalent to left.

This style takes precedence over the left and right styles.

TypeRequired
number, stringNo

flex

In React Native flex does not work the same way that it does in CSS. flex is a number rather than a string, and it works according to the Yoga.

When flex is a positive number, it makes the component flexible, and it will be sized proportional to its flex value. So a component with flex set to 2 will take twice the space as a component with flex set to 1. flex: <positive number> equates to flexGrow: <positive number>, flexShrink: 1, flexBasis: 0.

When flex is 0, the component is sized according to width and height, and it is inflexible.

When flex is -1, the component is normally sized according to width and height. However, if there's not enough space, the component will shrink to its minWidth and minHeight.

flexGrow, flexShrink, and flexBasis work the same as in CSS.

TypeRequired
numberNo

flexBasis

TypeRequired
number, stringNo

flexDirection

flexDirection controls which directions children of a container go. row goes left to right, column goes top to bottom, and you may be able to guess what the other two do. It works like flex-direction in CSS, except the default is column. See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction for more details.

TypeRequired
enum('row', 'row-reverse', 'column', 'column-reverse')No

flexGrow

TypeRequired
numberNo

flexShrink

TypeRequired
numberNo

flexWrap

flexWrap controls whether children can wrap around after they hit the end of a flex container. It works like flex-wrap in CSS (default: nowrap). See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-wrap for more details. Note it does not work anymore with alignItems: stretch (the default), so you may want to use alignItems: flex-start for example (breaking change details: https://github.com/facebook/react-native/releases/tag/v0.28.0).

TypeRequired
enum('wrap', 'nowrap', 'wrap-reverse')No

height

height sets the height of this component.

It works similarly to height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported. See https://developer.mozilla.org/en-US/docs/Web/CSS/height for more details.

TypeRequired
number, stringNo

justifyContent

justifyContent aligns children in the main direction. For example, if children are flowing vertically, justifyContent controls how they align vertically. It works like justify-content in CSS (default: flex-start). See https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'space-between', 'space-around', 'space-evenly')No

left

left is the number of logical pixels to offset the left edge of this component.

It works similarly to left in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/left for more details of how left affects layout.

TypeRequired
number, stringNo

margin

Setting margin has the same effect as setting each of marginTop, marginLeft, marginBottom, and marginRight. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin for more details.

TypeRequired
number, stringNo

marginBottom

marginBottom works like margin-bottom in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-bottom for more details.

TypeRequired
number, stringNo

marginEnd

When direction is ltr, marginEnd is equivalent to marginRight. When direction is rtl, marginEnd is equivalent to marginLeft.

TypeRequired
number, stringNo

marginHorizontal

Setting marginHorizontal has the same effect as setting both marginLeft and marginRight.

TypeRequired
number, stringNo

marginLeft

marginLeft works like margin-left in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-left for more details.

TypeRequired
number, stringNo

marginRight

marginRight works like margin-right in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-right for more details.

TypeRequired
number, stringNo

marginStart

When direction is ltr, marginStart is equivalent to marginLeft. When direction is rtl, marginStart is equivalent to marginRight.

TypeRequired
number, stringNo

marginTop

marginTop works like margin-top in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-top for more details.

TypeRequired
number, stringNo

marginVertical

Setting marginVertical has the same effect as setting both marginTop and marginBottom.

TypeRequired
number, stringNo

maxHeight

maxHeight is the maximum height for this component, in logical pixels.

It works similarly to max-height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/max-height for more details.

TypeRequired
number, stringNo

maxWidth

maxWidth is the maximum width for this component, in logical pixels.

It works similarly to max-width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/max-width for more details.

TypeRequired
number, stringNo

minHeight

minHeight is the minimum height for this component, in logical pixels.

It works similarly to min-height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/min-height for more details.

TypeRequired
number, stringNo

minWidth

minWidth is the minimum width for this component, in logical pixels.

It works similarly to min-width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/min-width for more details.

TypeRequired
number, stringNo

overflow

overflow controls how children are measured and displayed. overflow: hidden causes views to be clipped while overflow: scroll causes views to be measured independently of their parents' main axis. It works like overflow in CSS (default: visible). See https://developer.mozilla.org/en/docs/Web/CSS/overflow for more details.

TypeRequired
enum('visible', 'hidden', 'scroll')No

padding

Setting padding has the same effect as setting each of paddingTop, paddingBottom, paddingLeft, and paddingRight. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding for more details.

TypeRequired
number, stringNo

paddingBottom

paddingBottom works like padding-bottom in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-bottom for more details.

TypeRequired
number, stringNo

paddingEnd

When direction is ltr, paddingEnd is equivalent to paddingRight. When direction is rtl, paddingEnd is equivalent to paddingLeft.

TypeRequired
number, stringNo

paddingHorizontal

Setting paddingHorizontal is like setting both of paddingLeft and paddingRight.

TypeRequired
number, stringNo

paddingLeft

paddingLeft works like padding-left in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-left for more details.

TypeRequired
number, stringNo

paddingRight

paddingRight works like padding-right in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-right for more details.

TypeRequired
number, stringNo

paddingStart

When direction is ltr, paddingStart is equivalent to paddingLeft. When direction is rtl, paddingStart is equivalent to paddingRight.

TypeRequired
number, stringNo

paddingTop

paddingTop works like padding-top in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-top for more details.

TypeRequired
number, ,stringNo

paddingVertical

Setting paddingVertical is like setting both of paddingTop and paddingBottom.

TypeRequired
number, stringNo

position

position in React Native is similar to regular CSS, but everything is set to relative by default, so absolute positioning is always relative to the parent.

If you want to position a child using specific numbers of logical pixels relative to its parent, set the child to have absolute position.

If you want to position a child relative to something that is not its parent, don't use styles for that. Use the component tree.

See https://github.com/facebook/yoga for more details on how position differs between React Native and CSS.

TypeRequired
enum('absolute', 'relative')No

right

right is the number of logical pixels to offset the right edge of this component.

It works similarly to right in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/right for more details of how right affects layout.

TypeRequired
number, stringNo

start

When the direction is ltr, start is equivalent to left. When the direction is rtl, start is equivalent to right.

This style takes precedence over the left, right, and end styles.

TypeRequired
number, stringNo

top

top is the number of logical pixels to offset the top edge of this component.

It works similarly to top in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/top for more details of how top affects layout.

TypeRequired
number, stringNo

width

width sets the width of this component.

It works similarly to width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported. See https://developer.mozilla.org/en-US/docs/Web/CSS/width for more details.

TypeRequired
number, stringNo

zIndex

zIndex controls which components display on top of others. Normally, you don't use zIndex. Components render according to their order in the document tree, so later components draw over earlier ones. zIndex may be useful if you have animations or custom modal interfaces where you don't want this behavior.

It works like the CSS z-index property - components with a larger zIndex will render on top. Think of the z-direction like it's pointing from the phone into your eyeball. See https://developer.mozilla.org/en-US/docs/Web/CSS/z-index for more details.

On iOS, zIndex may require Views to be siblings of each other for it to work as expected.

TypeRequired
numberNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/layout-props/index.html b/docs/0.62/layout-props/index.html index 76e8fdb2226..347032424f2 100644 --- a/docs/0.62/layout-props/index.html +++ b/docs/0.62/layout-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Layout Props

Example

The following example shows how different properties can affect or shape a React Native layout. You can try for example to add or remove squares from the UI while changing the values of the property flexWrap. Find more detailed examples about this properties in the Layout with Flexbox docs page.

Reference

Props

alignContent

alignContent controls how rows align in the cross direction, overriding the alignContent of the parent. See https://developer.mozilla.org/en-US/docs/Web/CSS/align-content for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'stretch', 'space-between', 'space-around')No

alignItems

alignItems aligns children in the cross direction. For example, if children are flowing vertically, alignItems controls how they align horizontally. It works like align-items in CSS (default: stretch). See https://developer.mozilla.org/en-US/docs/Web/CSS/align-items for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'stretch', 'baseline')No

alignSelf

alignSelf controls how a child aligns in the cross direction, overriding the alignItems of the parent. It works like align-self in CSS (default: auto). See https://developer.mozilla.org/en-US/docs/Web/CSS/align-self for more details.

TypeRequired
enum('auto', 'flex-start', 'flex-end', 'center', 'stretch', 'baseline')No

aspectRatio

Aspect ratio controls the size of the undefined dimension of a node. Aspect ratio is a non-standard property only available in React Native and not CSS.

  • On a node with a set width/height, aspect ratio controls the size of the unset dimension
  • On a node with a set flex basis, aspect ratio controls the size of the node in the cross axis if unset
  • On a node with a measure function, aspect ratio works as though the measure function measures the flex basis
  • On a node with flex grow/shrink, aspect ratio controls the size of the node in the cross axis if unset
  • Aspect ratio takes min/max dimensions into account
TypeRequired
numberNo

borderBottomWidth

borderBottomWidth works like border-bottom-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-width for more details.

TypeRequired
numberNo

borderEndWidth

When direction is ltr, borderEndWidth is equivalent to borderRightWidth. When direction is rtl, borderEndWidth is equivalent to borderLeftWidth.

TypeRequired
numberNo

borderLeftWidth

borderLeftWidth works like border-left-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-left-width for more details.

TypeRequired
numberNo

borderRightWidth

borderRightWidth works like border-right-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-right-width for more details.

TypeRequired
numberNo

borderStartWidth

When direction is ltr, borderStartWidth is equivalent to borderLeftWidth. When direction is rtl, borderStartWidth is equivalent to borderRightWidth.

TypeRequired
numberNo

borderTopWidth

borderTopWidth works like border-top-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-top-width for more details.

TypeRequired
numberNo

borderWidth

borderWidth works like border-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-width for more details.

TypeRequired
numberNo

bottom

bottom is the number of logical pixels to offset the bottom edge of this component.

It works similarly to bottom in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/bottom for more details of how bottom affects layout.

TypeRequired
number, stringNo

direction

direction specifies the directional flow of the user interface. The default is inherit, except for root node which will have value based on the current locale. See https://yogalayout.com/docs/layout-direction for more details.

TypeRequiredPlatform
enum('inherit', 'ltr', 'rtl')NoiOS

display

display sets the display type of this component.

It works similarly to display in CSS but only supports 'flex' and 'none'. 'flex' is the default.

TypeRequired
enum('none', 'flex')No

end

When the direction is ltr, end is equivalent to right. When the direction is rtl, end is equivalent to left.

This style takes precedence over the left and right styles.

TypeRequired
number, stringNo

flex

In React Native flex does not work the same way that it does in CSS. flex is a number rather than a string, and it works according to the Yoga.

When flex is a positive number, it makes the component flexible, and it will be sized proportional to its flex value. So a component with flex set to 2 will take twice the space as a component with flex set to 1. flex: <positive number> equates to flexGrow: <positive number>, flexShrink: 1, flexBasis: 0.

When flex is 0, the component is sized according to width and height, and it is inflexible.

When flex is -1, the component is normally sized according to width and height. However, if there's not enough space, the component will shrink to its minWidth and minHeight.

flexGrow, flexShrink, and flexBasis work the same as in CSS.

TypeRequired
numberNo

flexBasis

TypeRequired
number, stringNo

flexDirection

flexDirection controls which directions children of a container go. row goes left to right, column goes top to bottom, and you may be able to guess what the other two do. It works like flex-direction in CSS, except the default is column. See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction for more details.

TypeRequired
enum('row', 'row-reverse', 'column', 'column-reverse')No

flexGrow

TypeRequired
numberNo

flexShrink

TypeRequired
numberNo

flexWrap

flexWrap controls whether children can wrap around after they hit the end of a flex container. It works like flex-wrap in CSS (default: nowrap). See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-wrap for more details. Note it does not work anymore with alignItems: stretch (the default), so you may want to use alignItems: flex-start for example (breaking change details: https://github.com/facebook/react-native/releases/tag/v0.28.0).

TypeRequired
enum('wrap', 'nowrap', 'wrap-reverse')No

height

height sets the height of this component.

It works similarly to height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported. See https://developer.mozilla.org/en-US/docs/Web/CSS/height for more details.

TypeRequired
number, stringNo

justifyContent

justifyContent aligns children in the main direction. For example, if children are flowing vertically, justifyContent controls how they align vertically. It works like justify-content in CSS (default: flex-start). See https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'space-between', 'space-around', 'space-evenly')No

left

left is the number of logical pixels to offset the left edge of this component.

It works similarly to left in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/left for more details of how left affects layout.

TypeRequired
number, stringNo

margin

Setting margin has the same effect as setting each of marginTop, marginLeft, marginBottom, and marginRight. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin for more details.

TypeRequired
number, stringNo

marginBottom

marginBottom works like margin-bottom in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-bottom for more details.

TypeRequired
number, stringNo

marginEnd

When direction is ltr, marginEnd is equivalent to marginRight. When direction is rtl, marginEnd is equivalent to marginLeft.

TypeRequired
number, stringNo

marginHorizontal

Setting marginHorizontal has the same effect as setting both marginLeft and marginRight.

TypeRequired
number, stringNo

marginLeft

marginLeft works like margin-left in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-left for more details.

TypeRequired
number, stringNo

marginRight

marginRight works like margin-right in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-right for more details.

TypeRequired
number, stringNo

marginStart

When direction is ltr, marginStart is equivalent to marginLeft. When direction is rtl, marginStart is equivalent to marginRight.

TypeRequired
number, stringNo

marginTop

marginTop works like margin-top in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-top for more details.

TypeRequired
number, stringNo

marginVertical

Setting marginVertical has the same effect as setting both marginTop and marginBottom.

TypeRequired
number, stringNo

maxHeight

maxHeight is the maximum height for this component, in logical pixels.

It works similarly to max-height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/max-height for more details.

TypeRequired
number, stringNo

maxWidth

maxWidth is the maximum width for this component, in logical pixels.

It works similarly to max-width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/max-width for more details.

TypeRequired
number, stringNo

minHeight

minHeight is the minimum height for this component, in logical pixels.

It works similarly to min-height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/min-height for more details.

TypeRequired
number, stringNo

minWidth

minWidth is the minimum width for this component, in logical pixels.

It works similarly to min-width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/min-width for more details.

TypeRequired
number, stringNo

overflow

overflow controls how children are measured and displayed. overflow: hidden causes views to be clipped while overflow: scroll causes views to be measured independently of their parents' main axis. It works like overflow in CSS (default: visible). See https://developer.mozilla.org/en/docs/Web/CSS/overflow for more details.

TypeRequired
enum('visible', 'hidden', 'scroll')No

padding

Setting padding has the same effect as setting each of paddingTop, paddingBottom, paddingLeft, and paddingRight. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding for more details.

TypeRequired
number, stringNo

paddingBottom

paddingBottom works like padding-bottom in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-bottom for more details.

TypeRequired
number, stringNo

paddingEnd

When direction is ltr, paddingEnd is equivalent to paddingRight. When direction is rtl, paddingEnd is equivalent to paddingLeft.

TypeRequired
number, stringNo

paddingHorizontal

Setting paddingHorizontal is like setting both of paddingLeft and paddingRight.

TypeRequired
number, stringNo

paddingLeft

paddingLeft works like padding-left in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-left for more details.

TypeRequired
number, stringNo

paddingRight

paddingRight works like padding-right in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-right for more details.

TypeRequired
number, stringNo

paddingStart

When direction is ltr, paddingStart is equivalent to paddingLeft. When direction is rtl, paddingStart is equivalent to paddingRight.

TypeRequired
number, stringNo

paddingTop

paddingTop works like padding-top in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-top for more details.

TypeRequired
number, ,stringNo

paddingVertical

Setting paddingVertical is like setting both of paddingTop and paddingBottom.

TypeRequired
number, stringNo

position

position in React Native is similar to regular CSS, but everything is set to relative by default, so absolute positioning is always relative to the parent.

If you want to position a child using specific numbers of logical pixels relative to its parent, set the child to have absolute position.

If you want to position a child relative to something that is not its parent, don't use styles for that. Use the component tree.

See https://github.com/facebook/yoga for more details on how position differs between React Native and CSS.

TypeRequired
enum('absolute', 'relative')No

right

right is the number of logical pixels to offset the right edge of this component.

It works similarly to right in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/right for more details of how right affects layout.

TypeRequired
number, stringNo

start

When the direction is ltr, start is equivalent to left. When the direction is rtl, start is equivalent to right.

This style takes precedence over the left, right, and end styles.

TypeRequired
number, stringNo

top

top is the number of logical pixels to offset the top edge of this component.

It works similarly to top in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/top for more details of how top affects layout.

TypeRequired
number, stringNo

width

width sets the width of this component.

It works similarly to width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported. See https://developer.mozilla.org/en-US/docs/Web/CSS/width for more details.

TypeRequired
number, stringNo

zIndex

zIndex controls which components display on top of others. Normally, you don't use zIndex. Components render according to their order in the document tree, so later components draw over earlier ones. zIndex may be useful if you have animations or custom modal interfaces where you don't want this behavior.

It works like the CSS z-index property - components with a larger zIndex will render on top. Think of the z-direction like it's pointing from the phone into your eyeball. See https://developer.mozilla.org/en-US/docs/Web/CSS/z-index for more details.

On iOS, zIndex may require Views to be siblings of each other for it to work as expected.

TypeRequired
numberNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/layoutanimation.html b/docs/0.62/layoutanimation.html index 1f69d63af47..a4cf43d1227 100644 --- a/docs/0.62/layoutanimation.html +++ b/docs/0.62/layoutanimation.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

LayoutAnimation

Automatically animates views to their new positions when the next layout happens.

A common way to use this API is to call it before updating the state hook in functional components and calling setState in class components.

Note that in order to get this to work on Android you need to set the following flags via UIManager:

if (Platform.OS === 'android') {
if (UIManager.setLayoutAnimationEnabledExperimental) {
UIManager.setLayoutAnimationEnabledExperimental(true);
}
}

Example

Reference

Methods

configureNext()

static configureNext(config, onAnimationDidEnd?)

Schedules an animation to happen on the next layout.

Parameters:

NameTypeRequiredDescription
configobjectYesSee config description below.
onAnimationDidEndfunctionNoCalled when the animation finished. Only supported on iOS.

The config parameter is an object with the keys below. create returns a valid object for config, and the Presets objects can also all be passed as the config.

  • duration in milliseconds
  • create, optional config for animating in new views
  • update, optional config for animating views that have been updated
  • delete, optional config for animating views as they are removed

The config that's passed to create, update, or delete has the following keys:

  • type, the animation type to use
  • property, the layout property to animate (optional, but recommended for create and delete)
  • springDamping (number, optional and only for use with type: Type.spring)
  • initialVelocity (number, optional)
  • delay (number, optional)
  • duration (number, optional)

create()

static create(duration, type, creationProp)

Helper that creates an object (with create, update, and delete fields) to pass into configureNext. The type parameter is an animation type, and the creationProp parameter is a layout property.

Example usage:

Properties

Types

An enumeration of animation types to be used in the create method, or in the create/update/delete configs for configureNext. (example usage: LayoutAnimation.Types.easeIn)

Types
spring
linear
easeInEaseOut
easeIn
easeOut
keyboard

Properties

An enumeration of layout properties to be animated to be used in the create method, or in the create/update/delete configs for configureNext. (example usage: LayoutAnimation.Properties.opacity)

Properties
opacity
scaleX
scaleY
scaleXY

Presets

A set of predefined animation configs to pass into configureNext.

PresetsValue
easeInEaseOutcreate(300, 'easeInEaseOut', 'opacity')
linearcreate(500, 'linear', 'opacity')
spring{ duration: 700, create: { type: 'linear', property: 'opacity' }, update: { type: 'spring', springDamping: 0.4 }, delete: { type: 'linear', property: 'opacity' } }

easeInEaseOut()

Calls configureNext() with Presets.easeInEaseOut.

linear()

Calls configureNext() with Presets.linear.

spring()

Calls configureNext() with Presets.spring.

Example usage:

Edit this page
Last updated on
- + diff --git a/docs/0.62/layoutanimation/index.html b/docs/0.62/layoutanimation/index.html index 1f69d63af47..a4cf43d1227 100644 --- a/docs/0.62/layoutanimation/index.html +++ b/docs/0.62/layoutanimation/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

LayoutAnimation

Automatically animates views to their new positions when the next layout happens.

A common way to use this API is to call it before updating the state hook in functional components and calling setState in class components.

Note that in order to get this to work on Android you need to set the following flags via UIManager:

if (Platform.OS === 'android') {
if (UIManager.setLayoutAnimationEnabledExperimental) {
UIManager.setLayoutAnimationEnabledExperimental(true);
}
}

Example

Reference

Methods

configureNext()

static configureNext(config, onAnimationDidEnd?)

Schedules an animation to happen on the next layout.

Parameters:

NameTypeRequiredDescription
configobjectYesSee config description below.
onAnimationDidEndfunctionNoCalled when the animation finished. Only supported on iOS.

The config parameter is an object with the keys below. create returns a valid object for config, and the Presets objects can also all be passed as the config.

  • duration in milliseconds
  • create, optional config for animating in new views
  • update, optional config for animating views that have been updated
  • delete, optional config for animating views as they are removed

The config that's passed to create, update, or delete has the following keys:

  • type, the animation type to use
  • property, the layout property to animate (optional, but recommended for create and delete)
  • springDamping (number, optional and only for use with type: Type.spring)
  • initialVelocity (number, optional)
  • delay (number, optional)
  • duration (number, optional)

create()

static create(duration, type, creationProp)

Helper that creates an object (with create, update, and delete fields) to pass into configureNext. The type parameter is an animation type, and the creationProp parameter is a layout property.

Example usage:

Properties

Types

An enumeration of animation types to be used in the create method, or in the create/update/delete configs for configureNext. (example usage: LayoutAnimation.Types.easeIn)

Types
spring
linear
easeInEaseOut
easeIn
easeOut
keyboard

Properties

An enumeration of layout properties to be animated to be used in the create method, or in the create/update/delete configs for configureNext. (example usage: LayoutAnimation.Properties.opacity)

Properties
opacity
scaleX
scaleY
scaleXY

Presets

A set of predefined animation configs to pass into configureNext.

PresetsValue
easeInEaseOutcreate(300, 'easeInEaseOut', 'opacity')
linearcreate(500, 'linear', 'opacity')
spring{ duration: 700, create: { type: 'linear', property: 'opacity' }, update: { type: 'spring', springDamping: 0.4 }, delete: { type: 'linear', property: 'opacity' } }

easeInEaseOut()

Calls configureNext() with Presets.easeInEaseOut.

linear()

Calls configureNext() with Presets.linear.

spring()

Calls configureNext() with Presets.spring.

Example usage:

Edit this page
Last updated on
- + diff --git a/docs/0.62/libraries.html b/docs/0.62/libraries.html index 8d0358de37b..3b2b8115023 100644 --- a/docs/0.62/libraries.html +++ b/docs/0.62/libraries.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Using Libraries

React Native provides a set of built-in Core Components and APIs ready to use in your app. You're not limited to the components and APIs bundled with React Native. React Native has a community of thousands of developers. If the Core Components and APIs don't have what you are looking for, you may be able to find and install a library from the community to add the functionality to your app.

Selecting a Package Manager

React Native libraries are typically installed from the npm registry using a Node.js package manager such as npm CLI or Yarn Classic.

If you have Node.js installed on your computer then you already have the npm CLI installed. Some developers prefer to use Yarn Classic for slightly faster install times and additional advanced features like Workspaces. Both tools work great with React Native. We will assume npm for the rest of this guide for simplicity of explanation.

💡 The terms "library" and "package" are used interchangably in the JavaScript community.

Installing a Library

To install a library in your project, navigate to your project directory in your terminal and run npm install <name-of-the-library>. Let's try this with react-native-webview:

npm install react-native-webview

The library that we installed includes native code, and we need to link to our app before we use it.

Linking Native Code on iOS

React Native uses CocoaPods to manage iOS project dependencies and most React Native libraries follow this same convention. If a library you are using does not, then please refer to their README for additional instruction. In most cases, the following instructions will apply.

Run pod install in our ios directory in order to link it to our native iOS project. A shortcut for doing this without switching to the ios directory is to run npx pod-install.

npx pod-install

Once this is complete, re-build the app binary to start using your new library:

npx react-native run-ios

Linking Native Code on Android

React Native uses Gradle to manage Android project dependencies. After you install a library with native dependencies, you will need to re-build the app binary to use your new library:

npx react-native run-android

Finding Libraries

React Native Directory is a searchable database of libraries built specifically for React Native. This is the first place to look for a library for your React Native app.

Many of the libraries you will find on the directory are from React Native Community or Expo.

Libraries built by the React Native Community are driven by volunteers and individuals at companies that depend on React Native. They often support iOS, tvOS, Android, Windows, but this varies across projects. Many of the libraries in this organization were once React Native Core Components and APIs.

Libraries built by Expo are all written in TypeScript and support iOS, Android, and react-native-web wherever possible. They usually require that you first install react-native-unimodules in order to use in your React Native app.

After React Native Directory, the npm registry is the next best place if you can't find a library specifically for React Native on the directory. The npm registry is the definitive source for JavaScript libraries, but the libraries that it lists may not all be compatible with React Native. React Native is one of many JavaScript programming environments, including Node.js, web browsers, Electron, and more, and npm includes libraries that work for all of these environments.

Determining Library Compatibility

Does it work with React Native?

Usually libraries built specifically for other platforms will not work with React Native. Examples include react-select which is built for the web and specifically targets react-dom, and rimraf which is built for Node.js and interacts with your computer file system. Other libraries like lodash use only JavaScript langauge features and work in any environment. You will gain a sense for this over time, but until then the easiest way to find out is to try it yourself. You can remove packages using npm uninstall if it turns out that it does not work in React Native.

Does it work for the platforms that my app supports?

React Native Directory allows you to filter by platform compatibility, such as iOS, Android, Web, and Windows. If the library you would like to use is not currently listed there, refer to the README for the library to learn more.

Does it work with my app version of React Native?

The latest version of a library is typically compatible with the latest version of React Native. If you are using an older version, you should refer to the README to know which version of the library you should install. You can install a particular version of the library by running npm install <library-name>@<version-number>, for example: npm install @react-native-community/netinfo@^2.0.0.

Edit this page
Last updated on
- + diff --git a/docs/0.62/libraries/index.html b/docs/0.62/libraries/index.html index 8d0358de37b..3b2b8115023 100644 --- a/docs/0.62/libraries/index.html +++ b/docs/0.62/libraries/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Using Libraries

React Native provides a set of built-in Core Components and APIs ready to use in your app. You're not limited to the components and APIs bundled with React Native. React Native has a community of thousands of developers. If the Core Components and APIs don't have what you are looking for, you may be able to find and install a library from the community to add the functionality to your app.

Selecting a Package Manager

React Native libraries are typically installed from the npm registry using a Node.js package manager such as npm CLI or Yarn Classic.

If you have Node.js installed on your computer then you already have the npm CLI installed. Some developers prefer to use Yarn Classic for slightly faster install times and additional advanced features like Workspaces. Both tools work great with React Native. We will assume npm for the rest of this guide for simplicity of explanation.

💡 The terms "library" and "package" are used interchangably in the JavaScript community.

Installing a Library

To install a library in your project, navigate to your project directory in your terminal and run npm install <name-of-the-library>. Let's try this with react-native-webview:

npm install react-native-webview

The library that we installed includes native code, and we need to link to our app before we use it.

Linking Native Code on iOS

React Native uses CocoaPods to manage iOS project dependencies and most React Native libraries follow this same convention. If a library you are using does not, then please refer to their README for additional instruction. In most cases, the following instructions will apply.

Run pod install in our ios directory in order to link it to our native iOS project. A shortcut for doing this without switching to the ios directory is to run npx pod-install.

npx pod-install

Once this is complete, re-build the app binary to start using your new library:

npx react-native run-ios

Linking Native Code on Android

React Native uses Gradle to manage Android project dependencies. After you install a library with native dependencies, you will need to re-build the app binary to use your new library:

npx react-native run-android

Finding Libraries

React Native Directory is a searchable database of libraries built specifically for React Native. This is the first place to look for a library for your React Native app.

Many of the libraries you will find on the directory are from React Native Community or Expo.

Libraries built by the React Native Community are driven by volunteers and individuals at companies that depend on React Native. They often support iOS, tvOS, Android, Windows, but this varies across projects. Many of the libraries in this organization were once React Native Core Components and APIs.

Libraries built by Expo are all written in TypeScript and support iOS, Android, and react-native-web wherever possible. They usually require that you first install react-native-unimodules in order to use in your React Native app.

After React Native Directory, the npm registry is the next best place if you can't find a library specifically for React Native on the directory. The npm registry is the definitive source for JavaScript libraries, but the libraries that it lists may not all be compatible with React Native. React Native is one of many JavaScript programming environments, including Node.js, web browsers, Electron, and more, and npm includes libraries that work for all of these environments.

Determining Library Compatibility

Does it work with React Native?

Usually libraries built specifically for other platforms will not work with React Native. Examples include react-select which is built for the web and specifically targets react-dom, and rimraf which is built for Node.js and interacts with your computer file system. Other libraries like lodash use only JavaScript langauge features and work in any environment. You will gain a sense for this over time, but until then the easiest way to find out is to try it yourself. You can remove packages using npm uninstall if it turns out that it does not work in React Native.

Does it work for the platforms that my app supports?

React Native Directory allows you to filter by platform compatibility, such as iOS, Android, Web, and Windows. If the library you would like to use is not currently listed there, refer to the README for the library to learn more.

Does it work with my app version of React Native?

The latest version of a library is typically compatible with the latest version of React Native. If you are using an older version, you should refer to the README to know which version of the library you should install. You can install a particular version of the library by running npm install <library-name>@<version-number>, for example: npm install @react-native-community/netinfo@^2.0.0.

Edit this page
Last updated on
- + diff --git a/docs/0.62/linking-libraries-ios.html b/docs/0.62/linking-libraries-ios.html index c87328fc691..2e0c2359da1 100644 --- a/docs/0.62/linking-libraries-ios.html +++ b/docs/0.62/linking-libraries-ios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Linking Libraries

Not every app uses all the native capabilities, and including the code to support all those features would impact the binary size... But we still want to support adding these features whenever you need them.

With that in mind we exposed many of these features as independent static libraries.

For most of the libs it will be as quick as dragging two files, sometimes a third step will be necessary, but no more than that.

All the libraries we ship with React Native live on the Libraries folder in the root of the repository. Some of them are pure JavaScript, and you only need to require it. Other libraries also rely on some native code, in that case you'll have to add these files to your app, otherwise the app will throw an error as soon as you try to use the library.

Here are the few steps to link your libraries that contain native code

Automatic linking

Step 1

Install a library with native dependencies:

$ npm install <library-with-native-dependencies> --save

Note: --save or --save-dev flag is very important for this step. React Native will link your libs based on dependencies and devDependencies in your package.json file.

Step 2

Link your native dependencies:

$ npx react-native link

Done! All libraries with native dependencies should be successfully linked to your iOS/Android project.

Note: If your iOS project is using CocoaPods (contains Podfile) and linked library has podspec file, then npx react-native link will link library using Podfile. To support non-trivial Podfiles add # Add new pods below this line comment to places where you expect pods to be added.

Manual linking

Step 1

If the library has native code, there must be an .xcodeproj file inside its folder. Drag this file to your project on Xcode (usually under the Libraries group on Xcode);

Step 2

Click on your main project file (the one that represents the .xcodeproj) select Build Phases and drag the static library from the Products folder inside the Library you are importing to Link Binary With Libraries

Step 3

Not every library will need this step, what you need to consider is:

Do I need to know the contents of the library at compile time?

What that means is, are you using this library on the native side or only in JavaScript? If you are only using it in JavaScript, you are good to go!

If you do need to call it from native, then we need to know the library's headers. To achieve that you have to go to your project's file, select Build Settings and search for Header Search Paths. There you should include the path to your library. (This documentation used to recommend using recursive, but this is no longer recommended, as it can cause subtle build failures, especially with CocoaPods.)

Edit this page
Last updated on
- + diff --git a/docs/0.62/linking-libraries-ios/index.html b/docs/0.62/linking-libraries-ios/index.html index c87328fc691..2e0c2359da1 100644 --- a/docs/0.62/linking-libraries-ios/index.html +++ b/docs/0.62/linking-libraries-ios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Linking Libraries

Not every app uses all the native capabilities, and including the code to support all those features would impact the binary size... But we still want to support adding these features whenever you need them.

With that in mind we exposed many of these features as independent static libraries.

For most of the libs it will be as quick as dragging two files, sometimes a third step will be necessary, but no more than that.

All the libraries we ship with React Native live on the Libraries folder in the root of the repository. Some of them are pure JavaScript, and you only need to require it. Other libraries also rely on some native code, in that case you'll have to add these files to your app, otherwise the app will throw an error as soon as you try to use the library.

Here are the few steps to link your libraries that contain native code

Automatic linking

Step 1

Install a library with native dependencies:

$ npm install <library-with-native-dependencies> --save

Note: --save or --save-dev flag is very important for this step. React Native will link your libs based on dependencies and devDependencies in your package.json file.

Step 2

Link your native dependencies:

$ npx react-native link

Done! All libraries with native dependencies should be successfully linked to your iOS/Android project.

Note: If your iOS project is using CocoaPods (contains Podfile) and linked library has podspec file, then npx react-native link will link library using Podfile. To support non-trivial Podfiles add # Add new pods below this line comment to places where you expect pods to be added.

Manual linking

Step 1

If the library has native code, there must be an .xcodeproj file inside its folder. Drag this file to your project on Xcode (usually under the Libraries group on Xcode);

Step 2

Click on your main project file (the one that represents the .xcodeproj) select Build Phases and drag the static library from the Products folder inside the Library you are importing to Link Binary With Libraries

Step 3

Not every library will need this step, what you need to consider is:

Do I need to know the contents of the library at compile time?

What that means is, are you using this library on the native side or only in JavaScript? If you are only using it in JavaScript, you are good to go!

If you do need to call it from native, then we need to know the library's headers. To achieve that you have to go to your project's file, select Build Settings and search for Header Search Paths. There you should include the path to your library. (This documentation used to recommend using recursive, but this is no longer recommended, as it can cause subtle build failures, especially with CocoaPods.)

Edit this page
Last updated on
- + diff --git a/docs/0.62/linking.html b/docs/0.62/linking.html index c56cc609919..d7338bde56c 100644 --- a/docs/0.62/linking.html +++ b/docs/0.62/linking.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Linking

Linking gives you a general interface to interact with both incoming and outgoing app links.

Every Link (URL) has a URL Scheme, some websites are prefixed with https:// or http:// and the http is the URL Scheme. Let's call it scheme for short.

In addition to https, you're likely also familiar with the mailto scheme. When you open a link with the mailto scheme, your operating system will open an installed mail application. Similarly, there are schemes for making phone calls and sending SMS. Read more about built-in URL schemes below.

Like using the mailto scheme, it's possible to link to other applications by using custom url schemes. For example, when you get a Magic Link email from Slack, the Launch Slack button is an anchor tag with an href that looks something like: slack://secret/magic-login/other-secret. Like with Slack, you can tell the operating system that you want to handle a custom scheme. When the Slack app opens, it receives the URL that was used to open it. This is often referred to as deep linking. Read more about how to get the deep link into your app.

Custom URL scheme isn't the only way to open your application on mobile. You don't want to use a custom URL scheme in links in the email because then the links would be broken on desktop. Instead, you want to use a regular https links such as https://www.myapp.io/records/1234546. and on mobile you want that link open your app. Android calls it Deep Links (Universal Links - iOS).

Built-in URL Schemes

As mentioned in the introduction, there are some URL schemes for core functionality that exist on every platform. The following is a non-exhaustive list, but covers the most commonly used schemes.

SchemeDescriptioniOSAndroid
mailtoOpen mail app, eg: mailto: support@expo.io✅✅
telOpen phone app, eg: tel:+123456789✅✅
smsOpen SMS app, eg: sms:+123456789✅✅
https / httpOpen web browser app, eg: https://expo.io✅✅

Enabling Deep Links

If you want to enable deep links in your app, please the below guide:

For instructions on how to add support for deep linking on Android, refer to Enabling Deep Links for App Content - Add Intent Filters for Your Deep Links.

If you wish to receive the intent in an existing instance of MainActivity, you may set the launchMode of MainActivity to singleTask in AndroidManifest.xml. See <activity> documentation for more information.

<activity
android:name=".MainActivity"
android:launchMode="singleTask">

Handling Deep Links

There are two ways to handle URLs that open your app.

1. If the app is already open, the app is foregrounded and a Linking event is fired

You can handle these events with Linking.addEventListener('url', callback).

2. If the app is not already open, it is opened and the url is passed in as the initialURL

You can handle these events with Linking.getInitialURL() -- it returns a Promise that resolves to the url, if there is one.

Example

Open Links and Deep Links (Universal Links)

Open Custom Settings

Get the Deep Link

Send Intents (Android)

Reference

Methods

constructor()

constructor();

addEventListener()

addEventListener(type, handler);

Add a handler to Linking changes by listening to the url event type and providing the handler.

removeEventListener()

removeEventListener(type, handler);

Remove a handler by passing the url event type and the handler.

openURL()

openURL(url);

Try to open the given url with any of the installed apps.

You can use other URLs, like a location (e.g. "geo:37.484847,-122.148386" on Android or "http://maps.apple.com/?ll=37.484847,-122.148386" on iOS), a contact, or any other URL that can be opened with the installed apps.

The method returns a Promise object. If the user confirms the open dialog or the url automatically opens, the promise is resolved. If the user cancels the open dialog or there are no registered applications for the url, the promise is rejected.

Parameters:

NameTypeRequiredDescription
urlstringYesThe URL to open.

This method will fail if the system doesn't know how to open the specified URL. If you're passing in a non-http(s) URL, it's best to check {@code canOpenURL} first.

For web URLs, the protocol ("http://", "https://") must be set accordingly!

This method may behave differently in a simulator e.g. "tel:" links are not able to be handled in the iOS simulator as there's no access to the dialer app.

canOpenURL()

canOpenURL(url);

Determine whether or not an installed app can handle a given URL.

The method returns a Promise object. When it is determined whether or not the given URL can be handled, the promise is resolved and the first parameter is whether or not it can be opened.

The Promise will reject on Android if it was impossible to check if the URL can be opened, and on iOS if you didn't add the specific scheme in the LSApplicationQueriesSchemes key inside Info.plist (see bellow).

Parameters:

NameTypeRequiredDescription
urlstringYesThe URL to open.

For web URLs, the protocol ("http://", "https://") must be set accordingly!

As of iOS 9, your app needs to provide the LSApplicationQueriesSchemes key inside Info.plist or canOpenURL will always return false.

This method has limitations on iOS 9+. From the official Apple documentation:

If your app is linked against an earlier version of iOS but is running in iOS 9.0 or later, you can call this method up to 50 times. After reaching that limit, subsequent calls always return false. If the user reinstalls or upgrades the app, iOS resets the limit.

openSettings()

openSettings();

Open the Settings app and displays the app’s custom settings, if it has any.

getInitialURL()

getInitialURL();

If the app launch was triggered by an app link, it will give the link url, otherwise it will give null.

To support deep linking on Android, refer http://developer.android.com/training/app-indexing/deep-linking.html#handling-intents

sendIntent()

sendIntent(action: string, extras?: Array<{key: string, value: string | number | boolean}>)

@platform android

Android-Only. Launch an Android intent with extras (optional)

Edit this page
Last updated on
- + diff --git a/docs/0.62/linking/index.html b/docs/0.62/linking/index.html index c56cc609919..d7338bde56c 100644 --- a/docs/0.62/linking/index.html +++ b/docs/0.62/linking/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Linking

Linking gives you a general interface to interact with both incoming and outgoing app links.

Every Link (URL) has a URL Scheme, some websites are prefixed with https:// or http:// and the http is the URL Scheme. Let's call it scheme for short.

In addition to https, you're likely also familiar with the mailto scheme. When you open a link with the mailto scheme, your operating system will open an installed mail application. Similarly, there are schemes for making phone calls and sending SMS. Read more about built-in URL schemes below.

Like using the mailto scheme, it's possible to link to other applications by using custom url schemes. For example, when you get a Magic Link email from Slack, the Launch Slack button is an anchor tag with an href that looks something like: slack://secret/magic-login/other-secret. Like with Slack, you can tell the operating system that you want to handle a custom scheme. When the Slack app opens, it receives the URL that was used to open it. This is often referred to as deep linking. Read more about how to get the deep link into your app.

Custom URL scheme isn't the only way to open your application on mobile. You don't want to use a custom URL scheme in links in the email because then the links would be broken on desktop. Instead, you want to use a regular https links such as https://www.myapp.io/records/1234546. and on mobile you want that link open your app. Android calls it Deep Links (Universal Links - iOS).

Built-in URL Schemes

As mentioned in the introduction, there are some URL schemes for core functionality that exist on every platform. The following is a non-exhaustive list, but covers the most commonly used schemes.

SchemeDescriptioniOSAndroid
mailtoOpen mail app, eg: mailto: support@expo.io✅✅
telOpen phone app, eg: tel:+123456789✅✅
smsOpen SMS app, eg: sms:+123456789✅✅
https / httpOpen web browser app, eg: https://expo.io✅✅

Enabling Deep Links

If you want to enable deep links in your app, please the below guide:

For instructions on how to add support for deep linking on Android, refer to Enabling Deep Links for App Content - Add Intent Filters for Your Deep Links.

If you wish to receive the intent in an existing instance of MainActivity, you may set the launchMode of MainActivity to singleTask in AndroidManifest.xml. See <activity> documentation for more information.

<activity
android:name=".MainActivity"
android:launchMode="singleTask">

Handling Deep Links

There are two ways to handle URLs that open your app.

1. If the app is already open, the app is foregrounded and a Linking event is fired

You can handle these events with Linking.addEventListener('url', callback).

2. If the app is not already open, it is opened and the url is passed in as the initialURL

You can handle these events with Linking.getInitialURL() -- it returns a Promise that resolves to the url, if there is one.

Example

Open Links and Deep Links (Universal Links)

Open Custom Settings

Get the Deep Link

Send Intents (Android)

Reference

Methods

constructor()

constructor();

addEventListener()

addEventListener(type, handler);

Add a handler to Linking changes by listening to the url event type and providing the handler.

removeEventListener()

removeEventListener(type, handler);

Remove a handler by passing the url event type and the handler.

openURL()

openURL(url);

Try to open the given url with any of the installed apps.

You can use other URLs, like a location (e.g. "geo:37.484847,-122.148386" on Android or "http://maps.apple.com/?ll=37.484847,-122.148386" on iOS), a contact, or any other URL that can be opened with the installed apps.

The method returns a Promise object. If the user confirms the open dialog or the url automatically opens, the promise is resolved. If the user cancels the open dialog or there are no registered applications for the url, the promise is rejected.

Parameters:

NameTypeRequiredDescription
urlstringYesThe URL to open.

This method will fail if the system doesn't know how to open the specified URL. If you're passing in a non-http(s) URL, it's best to check {@code canOpenURL} first.

For web URLs, the protocol ("http://", "https://") must be set accordingly!

This method may behave differently in a simulator e.g. "tel:" links are not able to be handled in the iOS simulator as there's no access to the dialer app.

canOpenURL()

canOpenURL(url);

Determine whether or not an installed app can handle a given URL.

The method returns a Promise object. When it is determined whether or not the given URL can be handled, the promise is resolved and the first parameter is whether or not it can be opened.

The Promise will reject on Android if it was impossible to check if the URL can be opened, and on iOS if you didn't add the specific scheme in the LSApplicationQueriesSchemes key inside Info.plist (see bellow).

Parameters:

NameTypeRequiredDescription
urlstringYesThe URL to open.

For web URLs, the protocol ("http://", "https://") must be set accordingly!

As of iOS 9, your app needs to provide the LSApplicationQueriesSchemes key inside Info.plist or canOpenURL will always return false.

This method has limitations on iOS 9+. From the official Apple documentation:

If your app is linked against an earlier version of iOS but is running in iOS 9.0 or later, you can call this method up to 50 times. After reaching that limit, subsequent calls always return false. If the user reinstalls or upgrades the app, iOS resets the limit.

openSettings()

openSettings();

Open the Settings app and displays the app’s custom settings, if it has any.

getInitialURL()

getInitialURL();

If the app launch was triggered by an app link, it will give the link url, otherwise it will give null.

To support deep linking on Android, refer http://developer.android.com/training/app-indexing/deep-linking.html#handling-intents

sendIntent()

sendIntent(action: string, extras?: Array<{key: string, value: string | number | boolean}>)

@platform android

Android-Only. Launch an Android intent with extras (optional)

Edit this page
Last updated on
- + diff --git a/docs/0.62/listview.html b/docs/0.62/listview.html index e15eee1e792..ca9675fe9cc 100644 --- a/docs/0.62/listview.html +++ b/docs/0.62/listview.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
render() {
return (
<ListView
dataSource={this.state.dataSource}
renderRow={(rowData) => <Text>{rowData}</Text>}
/>
);
}
}

ListView also supports more advanced features, including sections with sticky section headers, header and footer support, callbacks on reaching the end of the available data (onEndReached) and on the set of rows that are visible in the device viewport change (onChangeVisibleRows), and several performance optimizations.

There are a few performance operations designed to make ListView scroll smoothly while dynamically loading potentially very large (or conceptually infinite) data sets:

Props

Methods

Reference

Props

dataSource

An instance of ListView.DataSource to use

TypeRequired
ListViewDataSourceYes

initialListSize

How many rows to render on initial component mount. Use this to make it so that the first screen worth of data appears at one time instead of over the course of multiple frames.

TypeRequired
numberYes

onEndReachedThreshold

Threshold in pixels (virtual, not physical) for calling onEndReached.

TypeRequired
numberYes

pageSize

Number of rows to render per event loop. Note: if your 'rows' are actually cells, i.e. they don't span the full width of your view (as in the ListViewGridLayoutExample), you should set the pageSize to be a multiple of the number of cells per row, otherwise you're likely to see gaps at the edge of the ListView as new pages are loaded.

TypeRequired
numberYes

renderRow

(rowData, sectionID, rowID, highlightRow) => renderable

Takes a data entry from the data source and its ids and should return a renderable component to be rendered as the row. By default the data is exactly what was put into the data source, but it's also possible to provide custom extractors. ListView can be notified when a row is being highlighted by calling highlightRow(sectionID, rowID). This sets a boolean value of adjacentRowHighlighted in renderSeparator, allowing you to control the separators above and below the highlighted row. The highlighted state of a row can be reset by calling highlightRow(null).

TypeRequired
functionYes

renderScrollComponent

(props) => renderable

A function that returns the scrollable component in which the list rows are rendered. Defaults to returning a ScrollView with the given props.

TypeRequired
functionYes

scrollRenderAheadDistance

How early to start rendering rows before they come on screen, in pixels.

TypeRequired
numberYes

stickyHeaderIndices

An array of child indices determining which children get docked to the top of the screen when scrolling. For example, passing stickyHeaderIndices={[0]} will cause the first child to be fixed to the top of the scroll view. This property is not supported in conjunction with horizontal={true}.

TypeRequired
array of numberYes

enableEmptySections

Flag indicating whether empty section headers should be rendered. In the future release empty section headers will be rendered by default, and the flag will be deprecated. If empty sections are not desired to be rendered their indices should be excluded from sectionID object.

TypeRequired
boolNo

renderHeader

TypeRequired
functionNo

onEndReached

Called when all rows have been rendered and the list has been scrolled to within onEndReachedThreshold of the bottom. The native scroll event is provided.

TypeRequired
functionNo

stickySectionHeadersEnabled

Makes the sections headers sticky. The sticky behavior means that it will scroll with the content at the top of the section until it reaches the top of the screen, at which point it will stick to the top until it is pushed off the screen by the next section header. This property is not supported in conjunction with horizontal={true}. Only enabled by default on iOS because of typical platform standards.

TypeRequired
boolNo

renderSectionHeader

(sectionData, sectionID) => renderable

If provided, a header is rendered for this section.

TypeRequired
functionNo

renderSeparator

(sectionID, rowID, adjacentRowHighlighted) => renderable

If provided, a renderable component to be rendered as the separator below each row but not the last row if there is a section header below. Take a sectionID and rowID of the row above and whether its adjacent row is highlighted.

TypeRequired
functionNo

onChangeVisibleRows

(visibleRows, changedRows) => void

Called when the set of visible rows changes. visibleRows maps { sectionID: { rowID: true }} for all the visible rows, and changedRows maps { sectionID: { rowID: true | false }} for the rows that have changed their visibility, with true indicating visible, and false indicating the view has moved out of view.

TypeRequired
functionNo

removeClippedSubviews

A performance optimization for improving scroll perf of large lists, used in conjunction with overflow: 'hidden' on the row containers. This is enabled by default.

TypeRequired
boolNo

renderFooter

() => renderable

The header and footer are always rendered (if these props are provided) on every render pass. If they are expensive to re-render, wrap them in StaticContainer or other mechanism as appropriate. Footer is always at the bottom of the list, and header at the top, on every render pass. In a horizontal ListView, the header is rendered on the left and the footer on the right.

TypeRequired
functionNo

Methods

getMetrics()

getMetrics();

Exports some data, e.g. for perf investigations or analytics.

scrollTo()

scrollTo((...args: Array));

Scrolls to a given x, y offset, either immediately or with a smooth animation.

See ScrollView#scrollTo.

scrollToEnd()

scrollToEnd(([options]: object));

If this is a vertical ListView scrolls to the bottom. If this is a horizontal ListView scrolls to the right.

Use scrollToEnd({animated: true}) for smooth animated scrolling, scrollToEnd({animated: false}) for immediate scrolling. If no options are passed, animated defaults to true.

See ScrollView#scrollToEnd.

flashScrollIndicators()

flashScrollIndicators();

Displays the scroll indicators momentarily.

Edit this page
Last updated on
- + diff --git a/docs/0.62/listview/index.html b/docs/0.62/listview/index.html index e15eee1e792..ca9675fe9cc 100644 --- a/docs/0.62/listview/index.html +++ b/docs/0.62/listview/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
render() {
return (
<ListView
dataSource={this.state.dataSource}
renderRow={(rowData) => <Text>{rowData}</Text>}
/>
);
}
}

ListView also supports more advanced features, including sections with sticky section headers, header and footer support, callbacks on reaching the end of the available data (onEndReached) and on the set of rows that are visible in the device viewport change (onChangeVisibleRows), and several performance optimizations.

There are a few performance operations designed to make ListView scroll smoothly while dynamically loading potentially very large (or conceptually infinite) data sets:

Props

Methods

Reference

Props

dataSource

An instance of ListView.DataSource to use

TypeRequired
ListViewDataSourceYes

initialListSize

How many rows to render on initial component mount. Use this to make it so that the first screen worth of data appears at one time instead of over the course of multiple frames.

TypeRequired
numberYes

onEndReachedThreshold

Threshold in pixels (virtual, not physical) for calling onEndReached.

TypeRequired
numberYes

pageSize

Number of rows to render per event loop. Note: if your 'rows' are actually cells, i.e. they don't span the full width of your view (as in the ListViewGridLayoutExample), you should set the pageSize to be a multiple of the number of cells per row, otherwise you're likely to see gaps at the edge of the ListView as new pages are loaded.

TypeRequired
numberYes

renderRow

(rowData, sectionID, rowID, highlightRow) => renderable

Takes a data entry from the data source and its ids and should return a renderable component to be rendered as the row. By default the data is exactly what was put into the data source, but it's also possible to provide custom extractors. ListView can be notified when a row is being highlighted by calling highlightRow(sectionID, rowID). This sets a boolean value of adjacentRowHighlighted in renderSeparator, allowing you to control the separators above and below the highlighted row. The highlighted state of a row can be reset by calling highlightRow(null).

TypeRequired
functionYes

renderScrollComponent

(props) => renderable

A function that returns the scrollable component in which the list rows are rendered. Defaults to returning a ScrollView with the given props.

TypeRequired
functionYes

scrollRenderAheadDistance

How early to start rendering rows before they come on screen, in pixels.

TypeRequired
numberYes

stickyHeaderIndices

An array of child indices determining which children get docked to the top of the screen when scrolling. For example, passing stickyHeaderIndices={[0]} will cause the first child to be fixed to the top of the scroll view. This property is not supported in conjunction with horizontal={true}.

TypeRequired
array of numberYes

enableEmptySections

Flag indicating whether empty section headers should be rendered. In the future release empty section headers will be rendered by default, and the flag will be deprecated. If empty sections are not desired to be rendered their indices should be excluded from sectionID object.

TypeRequired
boolNo

renderHeader

TypeRequired
functionNo

onEndReached

Called when all rows have been rendered and the list has been scrolled to within onEndReachedThreshold of the bottom. The native scroll event is provided.

TypeRequired
functionNo

stickySectionHeadersEnabled

Makes the sections headers sticky. The sticky behavior means that it will scroll with the content at the top of the section until it reaches the top of the screen, at which point it will stick to the top until it is pushed off the screen by the next section header. This property is not supported in conjunction with horizontal={true}. Only enabled by default on iOS because of typical platform standards.

TypeRequired
boolNo

renderSectionHeader

(sectionData, sectionID) => renderable

If provided, a header is rendered for this section.

TypeRequired
functionNo

renderSeparator

(sectionID, rowID, adjacentRowHighlighted) => renderable

If provided, a renderable component to be rendered as the separator below each row but not the last row if there is a section header below. Take a sectionID and rowID of the row above and whether its adjacent row is highlighted.

TypeRequired
functionNo

onChangeVisibleRows

(visibleRows, changedRows) => void

Called when the set of visible rows changes. visibleRows maps { sectionID: { rowID: true }} for all the visible rows, and changedRows maps { sectionID: { rowID: true | false }} for the rows that have changed their visibility, with true indicating visible, and false indicating the view has moved out of view.

TypeRequired
functionNo

removeClippedSubviews

A performance optimization for improving scroll perf of large lists, used in conjunction with overflow: 'hidden' on the row containers. This is enabled by default.

TypeRequired
boolNo

renderFooter

() => renderable

The header and footer are always rendered (if these props are provided) on every render pass. If they are expensive to re-render, wrap them in StaticContainer or other mechanism as appropriate. Footer is always at the bottom of the list, and header at the top, on every render pass. In a horizontal ListView, the header is rendered on the left and the footer on the right.

TypeRequired
functionNo

Methods

getMetrics()

getMetrics();

Exports some data, e.g. for perf investigations or analytics.

scrollTo()

scrollTo((...args: Array));

Scrolls to a given x, y offset, either immediately or with a smooth animation.

See ScrollView#scrollTo.

scrollToEnd()

scrollToEnd(([options]: object));

If this is a vertical ListView scrolls to the bottom. If this is a horizontal ListView scrolls to the right.

Use scrollToEnd({animated: true}) for smooth animated scrolling, scrollToEnd({animated: false}) for immediate scrolling. If no options are passed, animated defaults to true.

See ScrollView#scrollToEnd.

flashScrollIndicators()

flashScrollIndicators();

Displays the scroll indicators momentarily.

Edit this page
Last updated on
- + diff --git a/docs/0.62/listviewdatasource.html b/docs/0.62/listviewdatasource.html index 1ef21e41fb4..82d27575522 100644 --- a/docs/0.62/listviewdatasource.html +++ b/docs/0.62/listviewdatasource.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

ListViewDataSource

Provides efficient data processing and access to the ListView component. A ListViewDataSource is created with functions for extracting data from the input blob, and comparing elements (with default implementations for convenience). The input blob can be as flat as an array of strings, or an object with rows nested inside section objects.

To update the data in the datasource, use cloneWithRows (or cloneWithRowsAndSections if you care about sections). The data in the data source is immutable, so you can't modify it directly. The clone methods take in the new data and compute a diff for each row so ListView knows whether to re-render it or not.

In this example, a component receives data in chunks, handled by _onDataArrived, which concats the new data onto the old data and updates the data source. We use concat to create a new array - mutating this._data, e.g. with this._data.push(newRowData), would be an error. _rowHasChanged understands the shape of the row data and knows how to efficiently compare it.

getInitialState: function() {
var ds = new ListView.DataSource({rowHasChanged: this._rowHasChanged});
return {ds};
},
_onDataArrived(newData) {
this._data = this._data.concat(newData);
this.setState({
ds: this.state.ds.cloneWithRows(this._data)
});
}

Methods

Reference

Methods

constructor()

constructor(params);

You can provide custom extraction and hasChanged functions for section headers and rows. If absent, data will be extracted with the defaultGetRowData and defaultGetSectionHeaderData functions.

The default extractor expects data of one of the following forms:

{ sectionID_1: { rowID_1: <rowData1>, ... }, ... }

or

{ sectionID_1: [ <rowData1>, <rowData2>, ... ], ... }

or

[ [ <rowData1>, <rowData2>, ... ], ... ]

The constructor takes in a params argument that can contain any of the following:

  • getRowData(dataBlob, sectionID, rowID);
  • getSectionHeaderData(dataBlob, sectionID);
  • rowHasChanged(prevRowData, nextRowData);
  • sectionHeaderHasChanged(prevSectionData, nextSectionData);

cloneWithRows()

cloneWithRows(dataBlob, rowIdentities);

Clones this ListViewDataSource with the specified dataBlob and rowIdentities. The dataBlob an arbitrary blob of data. At construction an extractor to get the interesting information was defined (or the default was used).

The rowIdentities is a 2D array of identifiers for rows. ie. [['a1', 'a2'], ['b1', 'b2', 'b3'], ...]. If not provided, it's assumed that the keys of the section data are the row identities.

Note: This function does NOT clone the data in this data source. It only passes the functions defined at construction to a new data source with the data specified. If you wish to maintain the existing data you must handle merging of old and new data separately and then pass that into this function as the dataBlob.

cloneWithRowsAndSections()

cloneWithRowsAndSections(
dataBlob,
sectionIdentities,
rowIdentities
);

This performs the same function as the cloneWithRows function but here you also specify what your sectionIdentities are. If you don't care about sections you should safely be able to use cloneWithRows.

sectionIdentities is an array of identifiers for sections. ie. ['s1', 's2', ...]. The identifiers should correspond to the keys or array indexes of the data you wish to include. If not provided, it's assumed that the keys of dataBlob are the section identities.

Note: this returns a new object!

const dataSource = ds.cloneWithRowsAndSections({
addresses: ['row 1', 'row 2'],
phone_numbers: ['data 1', 'data 2'],
}, ['phone_numbers']);

getRowCount()

getRowCount();

Returns the total number of rows in the data source.

If you are specifying the rowIdentities or sectionIdentities, then getRowCount will return the number of rows in the filtered data source.

getRowAndSectionCount()

getRowAndSectionCount();

Returns the total number of rows in the data source (see getRowCount for how this is calculated) plus the number of sections in the data.

If you are specifying the rowIdentities or sectionIdentities, then getRowAndSectionCount will return the number of rows & sections in the filtered data source.

rowShouldUpdate()

rowShouldUpdate(sectionIndex, rowIndex);

Returns if the row is dirtied and needs to be rerendered

getRowData()

getRowData(sectionIndex, rowIndex);

Gets the data required to render the row.

getRowIDForFlatIndex()

getRowIDForFlatIndex(index);

Gets the rowID at index provided if the dataSource arrays were flattened, or null of out of range indexes.

getSectionIDForFlatIndex()

getSectionIDForFlatIndex(index);

Gets the sectionID at index provided if the dataSource arrays were flattened, or null for out of range indexes.

getSectionLengths()

getSectionLengths();

Returns an array containing the number of rows in each section

sectionHeaderShouldUpdate()

sectionHeaderShouldUpdate(sectionIndex);

Returns if the section header is dirtied and needs to be rerendered

getSectionHeaderData()

getSectionHeaderData(sectionIndex);

Gets the data required to render the section header

Edit this page
Last updated on
- + diff --git a/docs/0.62/listviewdatasource/index.html b/docs/0.62/listviewdatasource/index.html index 1ef21e41fb4..82d27575522 100644 --- a/docs/0.62/listviewdatasource/index.html +++ b/docs/0.62/listviewdatasource/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

ListViewDataSource

Provides efficient data processing and access to the ListView component. A ListViewDataSource is created with functions for extracting data from the input blob, and comparing elements (with default implementations for convenience). The input blob can be as flat as an array of strings, or an object with rows nested inside section objects.

To update the data in the datasource, use cloneWithRows (or cloneWithRowsAndSections if you care about sections). The data in the data source is immutable, so you can't modify it directly. The clone methods take in the new data and compute a diff for each row so ListView knows whether to re-render it or not.

In this example, a component receives data in chunks, handled by _onDataArrived, which concats the new data onto the old data and updates the data source. We use concat to create a new array - mutating this._data, e.g. with this._data.push(newRowData), would be an error. _rowHasChanged understands the shape of the row data and knows how to efficiently compare it.

getInitialState: function() {
var ds = new ListView.DataSource({rowHasChanged: this._rowHasChanged});
return {ds};
},
_onDataArrived(newData) {
this._data = this._data.concat(newData);
this.setState({
ds: this.state.ds.cloneWithRows(this._data)
});
}

Methods

Reference

Methods

constructor()

constructor(params);

You can provide custom extraction and hasChanged functions for section headers and rows. If absent, data will be extracted with the defaultGetRowData and defaultGetSectionHeaderData functions.

The default extractor expects data of one of the following forms:

{ sectionID_1: { rowID_1: <rowData1>, ... }, ... }

or

{ sectionID_1: [ <rowData1>, <rowData2>, ... ], ... }

or

[ [ <rowData1>, <rowData2>, ... ], ... ]

The constructor takes in a params argument that can contain any of the following:

  • getRowData(dataBlob, sectionID, rowID);
  • getSectionHeaderData(dataBlob, sectionID);
  • rowHasChanged(prevRowData, nextRowData);
  • sectionHeaderHasChanged(prevSectionData, nextSectionData);

cloneWithRows()

cloneWithRows(dataBlob, rowIdentities);

Clones this ListViewDataSource with the specified dataBlob and rowIdentities. The dataBlob an arbitrary blob of data. At construction an extractor to get the interesting information was defined (or the default was used).

The rowIdentities is a 2D array of identifiers for rows. ie. [['a1', 'a2'], ['b1', 'b2', 'b3'], ...]. If not provided, it's assumed that the keys of the section data are the row identities.

Note: This function does NOT clone the data in this data source. It only passes the functions defined at construction to a new data source with the data specified. If you wish to maintain the existing data you must handle merging of old and new data separately and then pass that into this function as the dataBlob.

cloneWithRowsAndSections()

cloneWithRowsAndSections(
dataBlob,
sectionIdentities,
rowIdentities
);

This performs the same function as the cloneWithRows function but here you also specify what your sectionIdentities are. If you don't care about sections you should safely be able to use cloneWithRows.

sectionIdentities is an array of identifiers for sections. ie. ['s1', 's2', ...]. The identifiers should correspond to the keys or array indexes of the data you wish to include. If not provided, it's assumed that the keys of dataBlob are the section identities.

Note: this returns a new object!

const dataSource = ds.cloneWithRowsAndSections({
addresses: ['row 1', 'row 2'],
phone_numbers: ['data 1', 'data 2'],
}, ['phone_numbers']);

getRowCount()

getRowCount();

Returns the total number of rows in the data source.

If you are specifying the rowIdentities or sectionIdentities, then getRowCount will return the number of rows in the filtered data source.

getRowAndSectionCount()

getRowAndSectionCount();

Returns the total number of rows in the data source (see getRowCount for how this is calculated) plus the number of sections in the data.

If you are specifying the rowIdentities or sectionIdentities, then getRowAndSectionCount will return the number of rows & sections in the filtered data source.

rowShouldUpdate()

rowShouldUpdate(sectionIndex, rowIndex);

Returns if the row is dirtied and needs to be rerendered

getRowData()

getRowData(sectionIndex, rowIndex);

Gets the data required to render the row.

getRowIDForFlatIndex()

getRowIDForFlatIndex(index);

Gets the rowID at index provided if the dataSource arrays were flattened, or null of out of range indexes.

getSectionIDForFlatIndex()

getSectionIDForFlatIndex(index);

Gets the sectionID at index provided if the dataSource arrays were flattened, or null for out of range indexes.

getSectionLengths()

getSectionLengths();

Returns an array containing the number of rows in each section

sectionHeaderShouldUpdate()

sectionHeaderShouldUpdate(sectionIndex);

Returns if the section header is dirtied and needs to be rerendered

getSectionHeaderData()

getSectionHeaderData(sectionIndex);

Gets the data required to render the section header

Edit this page
Last updated on
- + diff --git a/docs/0.62/maskedviewios.html b/docs/0.62/maskedviewios.html index 82926d69ad7..7303266f28f 100644 --- a/docs/0.62/maskedviewios.html +++ b/docs/0.62/maskedviewios.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
class MyMaskedView extends React.Component {
render() {
return (
// Determines shape of the mask
<MaskedViewIOS
style={{ flex: 1, flexDirection: 'row', height: '100%' }}
maskElement={
<View
style={{
// Transparent background because mask is based off alpha channel.
backgroundColor: 'transparent',
flex: 1,
justifyContent: 'center',
alignItems: 'center'
}}>
<Text
style={{
fontSize: 60,
color: 'black',
fontWeight: 'bold'
}}>
Basic Mask
</Text>
</View>
}>
{/* Shows behind the mask, you can put anything here, such as an image */}
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#324376'
}}
/>
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#F5DD90'
}}
/>
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#F76C5E'
}}
/>
</MaskedViewIOS>
);
}
}

The following image demonstrates that you can put almost anything behind the mask. The three examples shown are masked <View>, <Text>, and <Image>.

The alpha channel of the view rendered by the maskElement prop determines how much of the view's content and background shows through. Fully or partially opaque pixels allow the underlying content to show through but fully transparent pixels block that content.

Props

Reference

Props

maskElement

TypeRequired
elementYes
Edit this page
Last updated on
- + diff --git a/docs/0.62/maskedviewios/index.html b/docs/0.62/maskedviewios/index.html index 82926d69ad7..7303266f28f 100644 --- a/docs/0.62/maskedviewios/index.html +++ b/docs/0.62/maskedviewios/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
class MyMaskedView extends React.Component {
render() {
return (
// Determines shape of the mask
<MaskedViewIOS
style={{ flex: 1, flexDirection: 'row', height: '100%' }}
maskElement={
<View
style={{
// Transparent background because mask is based off alpha channel.
backgroundColor: 'transparent',
flex: 1,
justifyContent: 'center',
alignItems: 'center'
}}>
<Text
style={{
fontSize: 60,
color: 'black',
fontWeight: 'bold'
}}>
Basic Mask
</Text>
</View>
}>
{/* Shows behind the mask, you can put anything here, such as an image */}
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#324376'
}}
/>
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#F5DD90'
}}
/>
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#F76C5E'
}}
/>
</MaskedViewIOS>
);
}
}

The following image demonstrates that you can put almost anything behind the mask. The three examples shown are masked <View>, <Text>, and <Image>.

The alpha channel of the view rendered by the maskElement prop determines how much of the view's content and background shows through. Fully or partially opaque pixels allow the underlying content to show through but fully transparent pixels block that content.

Props

Reference

Props

maskElement

TypeRequired
elementYes
Edit this page
Last updated on
- + diff --git a/docs/0.62/modal.html b/docs/0.62/modal.html index cf01f81dd5d..7bff2edb805 100644 --- a/docs/0.62/modal.html +++ b/docs/0.62/modal.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Modal

The Modal component is a basic way to present content above an enclosing view.

Example

Reference

Props

animated

Deprecated. Use the animationType prop instead.

animationType

The animationType prop controls how the modal animates.

  • slide slides in from the bottom
  • fade fades into view
  • none appears without an animation

Default is set to none.

TypeRequired
enum('none', 'slide', 'fade')No

hardwareAccelerated

The hardwareAccelerated prop controls whether to force hardware acceleration for the underlying window.

TypeRequiredPlatform
boolNoAndroid

statusBarTranslucent

The statusBarTranslucent prop determines whether your modal should go under the system statusbar.

TypeRequiredPlatform
boolNoAndroid

onDismiss

The onDismiss prop allows passing a function that will be called once the modal has been dismissed.

TypeRequiredPlatform
functionNoiOS

onOrientationChange

The onOrientationChange callback is called when the orientation changes while the modal is being displayed. The orientation provided is only 'portrait' or 'landscape'. This callback is also called on initial render, regardless of the current orientation.

TypeRequiredPlatform
functionNoiOS

onRequestClose

The onRequestClose callback is called when the user taps the hardware back button on Android or the menu button on Apple TV. Because of this required prop, be aware that BackHandler events will not be emitted as long as the modal is open.

TypeRequiredPlatform
functionYesAndroid, Platform.isTVOS
functionNo(Others)

onShow

The onShow prop allows passing a function that will be called once the modal has been shown.

TypeRequired
functionNo

presentationStyle

The presentationStyle prop controls how the modal appears (generally on larger devices such as iPad or plus-sized iPhones). See https://developer.apple.com/reference/uikit/uimodalpresentationstyle for details.

  • fullScreen covers the screen completely
  • pageSheet covers portrait-width view centered (only on larger devices)
  • formSheet covers narrow-width view centered (only on larger devices)
  • overFullScreen covers the screen completely, but allows transparency

Default is set to overFullScreen or fullScreen depending on transparent property.

TypeRequiredPlatform
enum('fullScreen', 'pageSheet', 'formSheet', 'overFullScreen')NoiOS

statusBarTranslucent

The statusBarTranslucent prop determines whether your modal should go under the system statusbar.

TypeRequired
boolNo

supportedOrientations

The supportedOrientations prop allows the modal to be rotated to any of the specified orientations. On iOS, the modal is still restricted by what's specified in your app's Info.plist's UISupportedInterfaceOrientations field. When using presentationStyle of pageSheet or formSheet, this property will be ignored by iOS.

TypeRequiredPlatform
array of enum('portrait', 'portrait-upside-down', 'landscape', 'landscape-left', 'landscape-right')NoiOS

transparent

The transparent prop determines whether your modal will fill the entire view. Setting this to true will render the modal over a transparent background.

TypeRequired
boolNo

visible

The visible prop determines whether your modal is visible.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/modal/index.html b/docs/0.62/modal/index.html index cf01f81dd5d..7bff2edb805 100644 --- a/docs/0.62/modal/index.html +++ b/docs/0.62/modal/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Modal

The Modal component is a basic way to present content above an enclosing view.

Example

Reference

Props

animated

Deprecated. Use the animationType prop instead.

animationType

The animationType prop controls how the modal animates.

  • slide slides in from the bottom
  • fade fades into view
  • none appears without an animation

Default is set to none.

TypeRequired
enum('none', 'slide', 'fade')No

hardwareAccelerated

The hardwareAccelerated prop controls whether to force hardware acceleration for the underlying window.

TypeRequiredPlatform
boolNoAndroid

statusBarTranslucent

The statusBarTranslucent prop determines whether your modal should go under the system statusbar.

TypeRequiredPlatform
boolNoAndroid

onDismiss

The onDismiss prop allows passing a function that will be called once the modal has been dismissed.

TypeRequiredPlatform
functionNoiOS

onOrientationChange

The onOrientationChange callback is called when the orientation changes while the modal is being displayed. The orientation provided is only 'portrait' or 'landscape'. This callback is also called on initial render, regardless of the current orientation.

TypeRequiredPlatform
functionNoiOS

onRequestClose

The onRequestClose callback is called when the user taps the hardware back button on Android or the menu button on Apple TV. Because of this required prop, be aware that BackHandler events will not be emitted as long as the modal is open.

TypeRequiredPlatform
functionYesAndroid, Platform.isTVOS
functionNo(Others)

onShow

The onShow prop allows passing a function that will be called once the modal has been shown.

TypeRequired
functionNo

presentationStyle

The presentationStyle prop controls how the modal appears (generally on larger devices such as iPad or plus-sized iPhones). See https://developer.apple.com/reference/uikit/uimodalpresentationstyle for details.

  • fullScreen covers the screen completely
  • pageSheet covers portrait-width view centered (only on larger devices)
  • formSheet covers narrow-width view centered (only on larger devices)
  • overFullScreen covers the screen completely, but allows transparency

Default is set to overFullScreen or fullScreen depending on transparent property.

TypeRequiredPlatform
enum('fullScreen', 'pageSheet', 'formSheet', 'overFullScreen')NoiOS

statusBarTranslucent

The statusBarTranslucent prop determines whether your modal should go under the system statusbar.

TypeRequired
boolNo

supportedOrientations

The supportedOrientations prop allows the modal to be rotated to any of the specified orientations. On iOS, the modal is still restricted by what's specified in your app's Info.plist's UISupportedInterfaceOrientations field. When using presentationStyle of pageSheet or formSheet, this property will be ignored by iOS.

TypeRequiredPlatform
array of enum('portrait', 'portrait-upside-down', 'landscape', 'landscape-left', 'landscape-right')NoiOS

transparent

The transparent prop determines whether your modal will fill the entire view. Setting this to true will render the modal over a transparent background.

TypeRequired
boolNo

visible

The visible prop determines whether your modal is visible.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/more-resources.html b/docs/0.62/more-resources.html index 19136b008ec..a19ff665731 100644 --- a/docs/0.62/more-resources.html +++ b/docs/0.62/more-resources.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

More Resources

Congratulations! You built your first React Native app. But there’s more to learn: developer workflows, shipping to app stores, internationalization, security and more.

Where to go from here

Dive deep

IDEs

We recommend using the VS Code code editor and its handy React Native tools.

Platforms to try

Expo is a framework of tools and services for React Native that focuses on letting you build React Native apps without ever touching Xcode or Android Studio. If you have a web development background, this might appeal to you.

Ignite is a starter kit that uses Redux for state management and a few different common UI libraries. It has a CLI to generate apps, components, and containers. If you like all of the individual tech choices, Ignite could be perfect for you.

Example Apps

Try out apps from the Showcase to see what React Native is capable of! Looking for something more hands on? Check out this set of example apps on GitHub. You can look at their source code—try running one on a simulator or device.

Find, make, and share your own Native Components and Modules

React Native has a community of thousands of developers like you making content, tools, tutorials—and Native Components!

Can’t find what you’re looking for in the Core Components? Visit React Native Directory to find what the community has been creating.

Interested in making your own Native Component or Module? Making modules for your own use case and sharing them with others on NPM and GitHub helps grow the React Native ecosystem and community! Read the guides to making your own Native Modules (Android, iOS) and Native Components (Android, iOS).

Edit this page
Last updated on
- + diff --git a/docs/0.62/more-resources/index.html b/docs/0.62/more-resources/index.html index 19136b008ec..a19ff665731 100644 --- a/docs/0.62/more-resources/index.html +++ b/docs/0.62/more-resources/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

More Resources

Congratulations! You built your first React Native app. But there’s more to learn: developer workflows, shipping to app stores, internationalization, security and more.

Where to go from here

Dive deep

IDEs

We recommend using the VS Code code editor and its handy React Native tools.

Platforms to try

Expo is a framework of tools and services for React Native that focuses on letting you build React Native apps without ever touching Xcode or Android Studio. If you have a web development background, this might appeal to you.

Ignite is a starter kit that uses Redux for state management and a few different common UI libraries. It has a CLI to generate apps, components, and containers. If you like all of the individual tech choices, Ignite could be perfect for you.

Example Apps

Try out apps from the Showcase to see what React Native is capable of! Looking for something more hands on? Check out this set of example apps on GitHub. You can look at their source code—try running one on a simulator or device.

Find, make, and share your own Native Components and Modules

React Native has a community of thousands of developers like you making content, tools, tutorials—and Native Components!

Can’t find what you’re looking for in the Core Components? Visit React Native Directory to find what the community has been creating.

Interested in making your own Native Component or Module? Making modules for your own use case and sharing them with others on NPM and GitHub helps grow the React Native ecosystem and community! Read the guides to making your own Native Modules (Android, iOS) and Native Components (Android, iOS).

Edit this page
Last updated on
- + diff --git a/docs/0.62/native-components-android.html b/docs/0.62/native-components-android.html index 57fe6e1c0cf..3cc12e1672c 100644 --- a/docs/0.62/native-components-android.html +++ b/docs/0.62/native-components-android.html @@ -19,7 +19,7 @@ - + @@ -43,7 +43,7 @@
var RCTMyCustomView = requireNativeComponent(`RCTMyCustomView`);
Edit this page
Last updated on
- + diff --git a/docs/0.62/native-components-android/index.html b/docs/0.62/native-components-android/index.html index 57fe6e1c0cf..3cc12e1672c 100644 --- a/docs/0.62/native-components-android/index.html +++ b/docs/0.62/native-components-android/index.html @@ -19,7 +19,7 @@ - + @@ -43,7 +43,7 @@
var RCTMyCustomView = requireNativeComponent(`RCTMyCustomView`);
Edit this page
Last updated on
- + diff --git a/docs/0.62/native-components-ios.html b/docs/0.62/native-components-ios.html index 1bb73010dc4..70b72a30b85 100644 --- a/docs/0.62/native-components-ios.html +++ b/docs/0.62/native-components-ios.html @@ -19,7 +19,7 @@ - + @@ -96,7 +96,7 @@
return @{
@"ComponentHeight": @(CGRectGetHeight(dp.frame)),
@"ComponentWidth": @(CGRectGetWidth(dp.frame)),
@"DatePickerModes": @{
@"time": @(UIDatePickerModeTime),
@"date": @(UIDatePickerModeDate),
@"datetime": @(UIDatePickerModeDateAndTime),
}
};
}

This guide covered many of the aspects of bridging over custom native components, but there is even more you might need to consider, such as custom hooks for inserting and laying out subviews. If you want to go even deeper, check out the source code of some of the implemented components.

Edit this page
Last updated on
- + diff --git a/docs/0.62/native-components-ios/index.html b/docs/0.62/native-components-ios/index.html index 1bb73010dc4..70b72a30b85 100644 --- a/docs/0.62/native-components-ios/index.html +++ b/docs/0.62/native-components-ios/index.html @@ -19,7 +19,7 @@ - + @@ -96,7 +96,7 @@
return @{
@"ComponentHeight": @(CGRectGetHeight(dp.frame)),
@"ComponentWidth": @(CGRectGetWidth(dp.frame)),
@"DatePickerModes": @{
@"time": @(UIDatePickerModeTime),
@"date": @(UIDatePickerModeDate),
@"datetime": @(UIDatePickerModeDateAndTime),
}
};
}

This guide covered many of the aspects of bridging over custom native components, but there is even more you might need to consider, such as custom hooks for inserting and laying out subviews. If you want to go even deeper, check out the source code of some of the implemented components.

Edit this page
Last updated on
- + diff --git a/docs/0.62/native-modules-android.html b/docs/0.62/native-modules-android.html index 1e87de4fd94..c45c5613c74 100644 --- a/docs/0.62/native-modules-android.html +++ b/docs/0.62/native-modules-android.html @@ -19,7 +19,7 @@ - + @@ -84,7 +84,7 @@
@Override
public void onHostDestroy() {
// Activity `onDestroy`
}
Edit this page
Last updated on
- + diff --git a/docs/0.62/native-modules-android/index.html b/docs/0.62/native-modules-android/index.html index 1e87de4fd94..c45c5613c74 100644 --- a/docs/0.62/native-modules-android/index.html +++ b/docs/0.62/native-modules-android/index.html @@ -19,7 +19,7 @@ - + @@ -84,7 +84,7 @@
@Override
public void onHostDestroy() {
// Activity `onDestroy`
}
Edit this page
Last updated on
- + diff --git a/docs/0.62/native-modules-ios.html b/docs/0.62/native-modules-ios.html index 9f2717de54f..584b2b41eca 100644 --- a/docs/0.62/native-modules-ios.html +++ b/docs/0.62/native-modules-ios.html @@ -19,7 +19,7 @@ - + @@ -71,7 +71,7 @@
@end

For those of you new to Swift and Objective-C, whenever you mix the two languages in an iOS project, you will also need an additional bridging file, known as a bridging header, to expose the Objective-C files to Swift. Xcode will offer to create this header file for you if you add your Swift file to your app through the Xcode File>New File menu option. You will need to import RCTBridgeModule.h in this header file.

// CalendarManager-Bridging-Header.h
#import <React/RCTBridgeModule.h>

You can also use RCT_EXTERN_REMAP_MODULE and _RCT_EXTERN_REMAP_METHOD to alter the JavaScript name of the module or methods you are exporting. For more information see RCTBridgeModule.

Important when making third party modules: Static libraries with Swift are only supported in Xcode 9 and later. In order for the Xcode project to build when you use Swift in the iOS static library you include in the module, your main app project must contain Swift code and a bridging header itself. If your app project does not contain any Swift code, a workaround can be a single empty .swift file and an empty bridging header.

Reserved Method Names

invalidate()

Native modules can conform to the RCTInvalidating protocol on iOS by implementing the invalidate method. This method can be invoked when the native bridge is invalidated (ie: on devmode reload). You should avoid implementing this method in general, as this mechanism exists for backwards compatibility and may be removed in the future.

Edit this page
Last updated on
- + diff --git a/docs/0.62/native-modules-ios/index.html b/docs/0.62/native-modules-ios/index.html index 9f2717de54f..584b2b41eca 100644 --- a/docs/0.62/native-modules-ios/index.html +++ b/docs/0.62/native-modules-ios/index.html @@ -19,7 +19,7 @@ - + @@ -71,7 +71,7 @@
@end

For those of you new to Swift and Objective-C, whenever you mix the two languages in an iOS project, you will also need an additional bridging file, known as a bridging header, to expose the Objective-C files to Swift. Xcode will offer to create this header file for you if you add your Swift file to your app through the Xcode File>New File menu option. You will need to import RCTBridgeModule.h in this header file.

// CalendarManager-Bridging-Header.h
#import <React/RCTBridgeModule.h>

You can also use RCT_EXTERN_REMAP_MODULE and _RCT_EXTERN_REMAP_METHOD to alter the JavaScript name of the module or methods you are exporting. For more information see RCTBridgeModule.

Important when making third party modules: Static libraries with Swift are only supported in Xcode 9 and later. In order for the Xcode project to build when you use Swift in the iOS static library you include in the module, your main app project must contain Swift code and a bridging header itself. If your app project does not contain any Swift code, a workaround can be a single empty .swift file and an empty bridging header.

Reserved Method Names

invalidate()

Native modules can conform to the RCTInvalidating protocol on iOS by implementing the invalidate method. This method can be invoked when the native bridge is invalidated (ie: on devmode reload). You should avoid implementing this method in general, as this mechanism exists for backwards compatibility and may be removed in the future.

Edit this page
Last updated on
- + diff --git a/docs/0.62/native-modules-setup.html b/docs/0.62/native-modules-setup.html index b605a44392d..49f27e94342 100644 --- a/docs/0.62/native-modules-setup.html +++ b/docs/0.62/native-modules-setup.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Native Modules Setup

Native modules are usually distributed as npm packages, except that on top of the usual JavaScript they will include some native code per platform. To understand more about npm packages you may find this guide useful.

To get set up with the basic project structure for a native module we will use a third party tool create-react-native-module. You can go ahead further and dive deep into how that library works, for our needs we will only need:

$ yarn global add create-react-native-module
$ create-react-native-module MyLibrary

Where MyLibrary is the name you would like for the new module. After doing this you will navigate into MyLibrary folder and install the npm package to be locally available for your computer by doing:

$ yarn install

After this is done you can go to your main react app folder (which you created by doing npx react-native init MyApp)

  • add your newly created module as a dependency in your package.json
  • run yarn install to bring it along from your local npm repository.

After this, you will be able to continue to Native Modules (iOS) or Native Modules (Android) to add in some code. Make sure to read the README.md within your MyLibrary Directory for platform-specific instructions on how to include the project.

Edit this page
Last updated on
- + diff --git a/docs/0.62/native-modules-setup/index.html b/docs/0.62/native-modules-setup/index.html index b605a44392d..49f27e94342 100644 --- a/docs/0.62/native-modules-setup/index.html +++ b/docs/0.62/native-modules-setup/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Native Modules Setup

Native modules are usually distributed as npm packages, except that on top of the usual JavaScript they will include some native code per platform. To understand more about npm packages you may find this guide useful.

To get set up with the basic project structure for a native module we will use a third party tool create-react-native-module. You can go ahead further and dive deep into how that library works, for our needs we will only need:

$ yarn global add create-react-native-module
$ create-react-native-module MyLibrary

Where MyLibrary is the name you would like for the new module. After doing this you will navigate into MyLibrary folder and install the npm package to be locally available for your computer by doing:

$ yarn install

After this is done you can go to your main react app folder (which you created by doing npx react-native init MyApp)

  • add your newly created module as a dependency in your package.json
  • run yarn install to bring it along from your local npm repository.

After this, you will be able to continue to Native Modules (iOS) or Native Modules (Android) to add in some code. Make sure to read the README.md within your MyLibrary Directory for platform-specific instructions on how to include the project.

Edit this page
Last updated on
- + diff --git a/docs/0.62/navigation.html b/docs/0.62/navigation.html index 97d738c473a..8be708c81da 100644 --- a/docs/0.62/navigation.html +++ b/docs/0.62/navigation.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
function MyStack() {
return (
<NavigationContainer>
<Stack.Navigator>
<Stack.Screen
name="Home"
component={Home}
options={{ title: 'Welcome' }}
/>
<Stack.Screen name="Profile" component={Profile} />
</Stack.Navigator>
</NavigationContainer>
);
}

In this example, there are 2 screens (Home and Profile) defined using the Stack.Screen component. Similarly, you can define as many screens as you like.

You can set options such as the screen title for each screen in the options prop of Stack.Screen.

Each screen takes a component prop that is a React component. Those components receive a prop called navigation which has various methods to link to other screens. For example, you can use navigation.navigate to go to the Profile screen:

function HomeScreen({ navigation }) {
return (
<Button
title="Go to Jane's profile"
onPress={() =>
navigation.navigate('Profile', { name: 'Jane' })
}
/>
);
}

The views in the stack navigator use native components and the Animated library to deliver 60fps animations that are run on the native thread. Plus, the animations and gestures can be customized.

React Navigation also has packages for different kind of navigators such as tabs and drawer. You can use them to implement various patterns in your app.

For a complete intro to React Navigation, follow the React Navigation Getting Started Guide.

Edit this page
Last updated on
- + diff --git a/docs/0.62/navigation/index.html b/docs/0.62/navigation/index.html index 97d738c473a..8be708c81da 100644 --- a/docs/0.62/navigation/index.html +++ b/docs/0.62/navigation/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
function MyStack() {
return (
<NavigationContainer>
<Stack.Navigator>
<Stack.Screen
name="Home"
component={Home}
options={{ title: 'Welcome' }}
/>
<Stack.Screen name="Profile" component={Profile} />
</Stack.Navigator>
</NavigationContainer>
);
}

In this example, there are 2 screens (Home and Profile) defined using the Stack.Screen component. Similarly, you can define as many screens as you like.

You can set options such as the screen title for each screen in the options prop of Stack.Screen.

Each screen takes a component prop that is a React component. Those components receive a prop called navigation which has various methods to link to other screens. For example, you can use navigation.navigate to go to the Profile screen:

function HomeScreen({ navigation }) {
return (
<Button
title="Go to Jane's profile"
onPress={() =>
navigation.navigate('Profile', { name: 'Jane' })
}
/>
);
}

The views in the stack navigator use native components and the Animated library to deliver 60fps animations that are run on the native thread. Plus, the animations and gestures can be customized.

React Navigation also has packages for different kind of navigators such as tabs and drawer. You can use them to implement various patterns in your app.

For a complete intro to React Navigation, follow the React Navigation Getting Started Guide.

Edit this page
Last updated on
- + diff --git a/docs/0.62/netinfo.html b/docs/0.62/netinfo.html index 5a40d994a57..ea70af1e33e 100644 --- a/docs/0.62/netinfo.html +++ b/docs/0.62/netinfo.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

NetInfo

Deprecated. Use react-native-community/react-native-netinfo instead.

NetInfo exposes info about online/offline status

NetInfo.getConnectionInfo().then((connectionInfo) => {
console.log(
'Initial, type: ' +
connectionInfo.type +
', effectiveType: ' +
connectionInfo.effectiveType
);
});
function handleFirstConnectivityChange(connectionInfo) {
console.log(
'First change, type: ' +
connectionInfo.type +
', effectiveType: ' +
connectionInfo.effectiveType
);
NetInfo.removeEventListener(
'connectionChange',
handleFirstConnectivityChange
);
}
NetInfo.addEventListener(
'connectionChange',
handleFirstConnectivityChange
);

ConnectionType enum

ConnectionType describes the type of connection the device is using to communicate with the network.

Cross platform values for ConnectionType:

  • none - device is offline
  • wifi - device is online and connected via wifi, or is the iOS simulator
  • cellular - device is connected via Edge, 3G, WiMax, or LTE
  • unknown - error case and the network status is unknown

Android-only values for ConnectionType:

  • bluetooth - device is connected via Bluetooth
  • ethernet - device is connected via Ethernet
  • wimax - device is connected via WiMAX

EffectiveConnectionType enum

Cross platform values for EffectiveConnectionType:

  • 2g
  • 3g
  • 4g
  • unknown

Android

To request network info, you need to add the following line to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Methods

Properties

Reference

Methods

addEventListener()

NetInfo.addEventListener(eventName, handler);

Adds an event handler.

Parameters:

NameTypeRequiredDescription
eventNameenum(connectionChange, change)YesThe change event name.
handlerfunctionYesListener function.

Supported events:

  • connectionChange: Fires when the network status changes. The argument to the event handler is an object with keys:
    • type: A ConnectionType (listed above)
    • effectiveType: An EffectiveConnectionType (listed above)
  • change: This event is deprecated. Listen to connectionChange instead. Fires when the network status changes. The argument to the event handler is one of the deprecated connectivity types listed above.

removeEventListener()

NetInfo.removeEventListener(eventName, handler);

Removes the listener for network status changes.

Parameters:

NameTypeRequiredDescription
eventNameenum(connectionChange, change)YesThe change event name.
handlerfunctionYesListener function.

getConnectionInfo()

NetInfo.getConnectionInfo();

Returns a promise that resolves to an object with type and effectiveType keys whose values are a ConnectionType and an EffectiveConnectionType), respectively.

isConnectionExpensive()

NetInfo.isConnectionExpensive();

Available on Android. Detect if the current active connection is metered or not. A network is classified as metered when the user is sensitive to heavy data usage on that connection due to monetary costs, data limitations or battery/performance issues.

NetInfo.isConnectionExpensive()
.then(isConnectionExpensive => {
console.log('Connection is ' + (isConnectionExpensive ? 'Expensive' : 'Not Expensive'));
})
.catch(error => {
console.error(error);
});

Properties

isConnected

Available on all platforms. Asynchronously fetch a boolean to determine internet connectivity.

NetInfo.isConnected.fetch().then(isConnected => {
console.log('First, is ' + (isConnected ? 'online' : 'offline'));
});
function handleFirstConnectivityChange(isConnected) {
console.log('Then, is ' + (isConnected ? 'online' : 'offline'));
NetInfo.isConnected.removeEventListener(
'connectionChange',
handleFirstConnectivityChange
);
}
NetInfo.isConnected.addEventListener(
'connectionChange',
handleFirstConnectivityChange
);
Edit this page
Last updated on
- + diff --git a/docs/0.62/netinfo/index.html b/docs/0.62/netinfo/index.html index 5a40d994a57..ea70af1e33e 100644 --- a/docs/0.62/netinfo/index.html +++ b/docs/0.62/netinfo/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

NetInfo

Deprecated. Use react-native-community/react-native-netinfo instead.

NetInfo exposes info about online/offline status

NetInfo.getConnectionInfo().then((connectionInfo) => {
console.log(
'Initial, type: ' +
connectionInfo.type +
', effectiveType: ' +
connectionInfo.effectiveType
);
});
function handleFirstConnectivityChange(connectionInfo) {
console.log(
'First change, type: ' +
connectionInfo.type +
', effectiveType: ' +
connectionInfo.effectiveType
);
NetInfo.removeEventListener(
'connectionChange',
handleFirstConnectivityChange
);
}
NetInfo.addEventListener(
'connectionChange',
handleFirstConnectivityChange
);

ConnectionType enum

ConnectionType describes the type of connection the device is using to communicate with the network.

Cross platform values for ConnectionType:

  • none - device is offline
  • wifi - device is online and connected via wifi, or is the iOS simulator
  • cellular - device is connected via Edge, 3G, WiMax, or LTE
  • unknown - error case and the network status is unknown

Android-only values for ConnectionType:

  • bluetooth - device is connected via Bluetooth
  • ethernet - device is connected via Ethernet
  • wimax - device is connected via WiMAX

EffectiveConnectionType enum

Cross platform values for EffectiveConnectionType:

  • 2g
  • 3g
  • 4g
  • unknown

Android

To request network info, you need to add the following line to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Methods

Properties

Reference

Methods

addEventListener()

NetInfo.addEventListener(eventName, handler);

Adds an event handler.

Parameters:

NameTypeRequiredDescription
eventNameenum(connectionChange, change)YesThe change event name.
handlerfunctionYesListener function.

Supported events:

  • connectionChange: Fires when the network status changes. The argument to the event handler is an object with keys:
    • type: A ConnectionType (listed above)
    • effectiveType: An EffectiveConnectionType (listed above)
  • change: This event is deprecated. Listen to connectionChange instead. Fires when the network status changes. The argument to the event handler is one of the deprecated connectivity types listed above.

removeEventListener()

NetInfo.removeEventListener(eventName, handler);

Removes the listener for network status changes.

Parameters:

NameTypeRequiredDescription
eventNameenum(connectionChange, change)YesThe change event name.
handlerfunctionYesListener function.

getConnectionInfo()

NetInfo.getConnectionInfo();

Returns a promise that resolves to an object with type and effectiveType keys whose values are a ConnectionType and an EffectiveConnectionType), respectively.

isConnectionExpensive()

NetInfo.isConnectionExpensive();

Available on Android. Detect if the current active connection is metered or not. A network is classified as metered when the user is sensitive to heavy data usage on that connection due to monetary costs, data limitations or battery/performance issues.

NetInfo.isConnectionExpensive()
.then(isConnectionExpensive => {
console.log('Connection is ' + (isConnectionExpensive ? 'Expensive' : 'Not Expensive'));
})
.catch(error => {
console.error(error);
});

Properties

isConnected

Available on all platforms. Asynchronously fetch a boolean to determine internet connectivity.

NetInfo.isConnected.fetch().then(isConnected => {
console.log('First, is ' + (isConnected ? 'online' : 'offline'));
});
function handleFirstConnectivityChange(isConnected) {
console.log('Then, is ' + (isConnected ? 'online' : 'offline'));
NetInfo.isConnected.removeEventListener(
'connectionChange',
handleFirstConnectivityChange
);
}
NetInfo.isConnected.addEventListener(
'connectionChange',
handleFirstConnectivityChange
);
Edit this page
Last updated on
- + diff --git a/docs/0.62/network.html b/docs/0.62/network.html index 4fb33c73861..514c235e87e 100644 --- a/docs/0.62/network.html +++ b/docs/0.62/network.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
ws.onclose = (e) => {
// connection closed
console.log(e.code, e.reason);
};

Known Issues with fetch and cookie based authentication

The following options are currently not working with fetch

Edit this page
Last updated on
- + diff --git a/docs/0.62/network/index.html b/docs/0.62/network/index.html index 4fb33c73861..514c235e87e 100644 --- a/docs/0.62/network/index.html +++ b/docs/0.62/network/index.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
ws.onclose = (e) => {
// connection closed
console.log(e.code, e.reason);
};

Known Issues with fetch and cookie based authentication

The following options are currently not working with fetch

Edit this page
Last updated on
- + diff --git a/docs/0.62/optimizing-flatlist-configuration.html b/docs/0.62/optimizing-flatlist-configuration.html index 4e934105a6e..7cb3aa05241 100644 --- a/docs/0.62/optimizing-flatlist-configuration.html +++ b/docs/0.62/optimizing-flatlist-configuration.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// ...
}
Edit this page
Last updated on
- + diff --git a/docs/0.62/optimizing-flatlist-configuration/index.html b/docs/0.62/optimizing-flatlist-configuration/index.html index 4e934105a6e..7cb3aa05241 100644 --- a/docs/0.62/optimizing-flatlist-configuration/index.html +++ b/docs/0.62/optimizing-flatlist-configuration/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// ...
}
Edit this page
Last updated on
- + diff --git a/docs/0.62/out-of-tree-platforms.html b/docs/0.62/out-of-tree-platforms.html index dfbb359df7e..c172214acd7 100644 --- a/docs/0.62/out-of-tree-platforms.html +++ b/docs/0.62/out-of-tree-platforms.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Out-of-Tree Platforms

React Native is not only for Android and iOS - there are community-supported projects that bring it to other platforms, such as:

Creating your own React Native platform

Right now the process of creating a React Native platform from scratch is not very well documented - one of the goals of the upcoming re-architecture (Fabric) is to make maintaining a platform easier.

Bundling

As of React Native 0.57 you can now register your React Native platform with React Native's JavaScript bundler, Metro. This means you can pass --platform example to npx react-native bundle, and it will look for JavaScript files with the .example.js suffix.

To register your platform with RNPM, your module's name must match one of these patterns:

  • react-native-example - It will search all top-level modules that start with react-native-
  • @org/react-native-example - It will search for modules that start with react-native- under any scope
  • @react-native-example/module - It will search in all modules under scopes with names starting with @react-native-

You must also have an entry in your package.json like this:

{
"rnpm": {
"haste": {
"providesModuleNodeModules": ["react-native-example"],
"platforms": ["example"]
}
}
}

"providesModuleNodeModules" is an array of modules that will get added to the Haste module search path, and "platforms" is an array of platform suffixes that will be added as valid platforms.

Edit this page
Last updated on
- + diff --git a/docs/0.62/out-of-tree-platforms/index.html b/docs/0.62/out-of-tree-platforms/index.html index dfbb359df7e..c172214acd7 100644 --- a/docs/0.62/out-of-tree-platforms/index.html +++ b/docs/0.62/out-of-tree-platforms/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Out-of-Tree Platforms

React Native is not only for Android and iOS - there are community-supported projects that bring it to other platforms, such as:

Creating your own React Native platform

Right now the process of creating a React Native platform from scratch is not very well documented - one of the goals of the upcoming re-architecture (Fabric) is to make maintaining a platform easier.

Bundling

As of React Native 0.57 you can now register your React Native platform with React Native's JavaScript bundler, Metro. This means you can pass --platform example to npx react-native bundle, and it will look for JavaScript files with the .example.js suffix.

To register your platform with RNPM, your module's name must match one of these patterns:

  • react-native-example - It will search all top-level modules that start with react-native-
  • @org/react-native-example - It will search for modules that start with react-native- under any scope
  • @react-native-example/module - It will search in all modules under scopes with names starting with @react-native-

You must also have an entry in your package.json like this:

{
"rnpm": {
"haste": {
"providesModuleNodeModules": ["react-native-example"],
"platforms": ["example"]
}
}
}

"providesModuleNodeModules" is an array of modules that will get added to the Haste module search path, and "platforms" is an array of platform suffixes that will be added as valid platforms.

Edit this page
Last updated on
- + diff --git a/docs/0.62/panresponder.html b/docs/0.62/panresponder.html index 7ce98a7a746..d31b846a19e 100644 --- a/docs/0.62/panresponder.html +++ b/docs/0.62/panresponder.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
return <View {...panResponder.panHandlers} />;
};

Example

PanResponder works with Animated API to help build complex gestures in the UI. The following example contains an animated View component which can be dragged freely across the screen

Try the PanResponder example in RNTester.

Reference

Methods

create()

static create(config)

Parameters:

NameTypeRequiredDescription
configobjectYesRefer below

The config object provides enhanced versions of all of the responder callbacks that provide not only the typical ResponderSyntheticEvent, but also the PanResponder gesture state, by replacing the word Responder with PanResponder in each of the typical onResponder* callbacks. For example, the config object would look like:

In general, for events that have capture equivalents, we update the gestureState once in the capture phase and can use it in the bubble phase as well.

Be careful with onStartShould* callbacks. They only reflect updated gestureState for start/end events that bubble/capture to the Node. Once the node is the responder, you can rely on every start/end event being processed by the gesture and gestureState being updated accordingly. (numberActiveTouches) may not be totally accurate unless you are the responder.

Edit this page
Last updated on
- + diff --git a/docs/0.62/panresponder/index.html b/docs/0.62/panresponder/index.html index 7ce98a7a746..d31b846a19e 100644 --- a/docs/0.62/panresponder/index.html +++ b/docs/0.62/panresponder/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
return <View {...panResponder.panHandlers} />;
};

Example

PanResponder works with Animated API to help build complex gestures in the UI. The following example contains an animated View component which can be dragged freely across the screen

Try the PanResponder example in RNTester.

Reference

Methods

create()

static create(config)

Parameters:

NameTypeRequiredDescription
configobjectYesRefer below

The config object provides enhanced versions of all of the responder callbacks that provide not only the typical ResponderSyntheticEvent, but also the PanResponder gesture state, by replacing the word Responder with PanResponder in each of the typical onResponder* callbacks. For example, the config object would look like:

In general, for events that have capture equivalents, we update the gestureState once in the capture phase and can use it in the bubble phase as well.

Be careful with onStartShould* callbacks. They only reflect updated gestureState for start/end events that bubble/capture to the Node. Once the node is the responder, you can rely on every start/end event being processed by the gesture and gestureState being updated accordingly. (numberActiveTouches) may not be totally accurate unless you are the responder.

Edit this page
Last updated on
- + diff --git a/docs/0.62/performance.html b/docs/0.62/performance.html index 7a9ba99d2b6..703d2458bf6 100644 --- a/docs/0.62/performance.html +++ b/docs/0.62/performance.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Performance Overview

A compelling reason for using React Native instead of WebView-based tools is to achieve 60 frames per second and a native look and feel to your apps. Where possible, we would like for React Native to do the right thing and help you to focus on your app instead of performance optimization, but there are areas where we're not quite there yet, and others where React Native (similar to writing native code directly) cannot possibly determine the best way to optimize for you and so manual intervention will be necessary. We try our best to deliver buttery-smooth UI performance by default, but sometimes that isn't possible.

This guide is intended to teach you some basics to help you to troubleshoot performance issues, as well as discuss common sources of problems and their suggested solutions.

What you need to know about frames

Your grandparents' generation called movies "moving pictures" for a reason: realistic motion in video is an illusion created by quickly changing static images at a consistent speed. We refer to each of these images as frames. The number of frames that is displayed each second has a direct impact on how smooth and ultimately life-like a video (or user interface) seems to be. iOS devices display 60 frames per second, which gives you and the UI system about 16.67ms to do all of the work needed to generate the static image (frame) that the user will see on the screen for that interval. If you are unable to do the work necessary to generate that frame within the allotted 16.67ms, then you will "drop a frame" and the UI will appear unresponsive.

Now to confuse the matter a little bit, open up the developer menu in your app and toggle Show Perf Monitor. You will notice that there are two different frame rates.

JS frame rate (JavaScript thread)

For most React Native applications, your business logic will run on the JavaScript thread. This is where your React application lives, API calls are made, touch events are processed, etc... Updates to native-backed views are batched and sent over to the native side at the end of each iteration of the event loop, before the frame deadline (if all goes well). If the JavaScript thread is unresponsive for a frame, it will be considered a dropped frame. For example, if you were to call this.setState on the root component of a complex application and it resulted in re-rendering computationally expensive component subtrees, it's conceivable that this might take 200ms and result in 12 frames being dropped. Any animations controlled by JavaScript would appear to freeze during that time. If anything takes longer than 100ms, the user will feel it.

This often happens during Navigator transitions: when you push a new route, the JavaScript thread needs to render all of the components necessary for the scene in order to send over the proper commands to the native side to create the backing views. It's common for the work being done here to take a few frames and cause jank because the transition is controlled by the JavaScript thread. Sometimes components will do additional work on componentDidMount, which might result in a second stutter in the transition.

Another example is responding to touches: if you are doing work across multiple frames on the JavaScript thread, you might notice a delay in responding to TouchableOpacity, for example. This is because the JavaScript thread is busy and cannot process the raw touch events sent over from the main thread. As a result, TouchableOpacity cannot react to the touch events and command the native view to adjust its opacity.

UI frame rate (main thread)

Many people have noticed that performance of NavigatorIOS is better out of the box than Navigator. The reason for this is that the animations for the transitions are done entirely on the main thread, and so they are not interrupted by frame drops on the JavaScript thread.

Similarly, you can happily scroll up and down through a ScrollView when the JavaScript thread is locked up because the ScrollView lives on the main thread. The scroll events are dispatched to the JS thread, but their receipt is not necessary for the scroll to occur.

Common sources of performance problems

Running in development mode (dev=true)

JavaScript thread performance suffers greatly when running in dev mode. This is unavoidable: a lot more work needs to be done at runtime to provide you with good warnings and error messages, such as validating propTypes and various other assertions. Always make sure to test performance in release builds.

Using console.log statements

When running a bundled app, these statements can cause a big bottleneck in the JavaScript thread. This includes calls from debugging libraries such as redux-logger, so make sure to remove them before bundling. You can also use this babel plugin that removes all the console.* calls. You need to install it first with npm i babel-plugin-transform-remove-console --save-dev, and then edit the .babelrc file under your project directory like this:

{
"env": {
"production": {
"plugins": ["transform-remove-console"]
}
}
}

This will automatically remove all console.* calls in the release (production) versions of your project.

ListView initial rendering is too slow or scroll performance is bad for large lists

Use the new FlatList or SectionList component instead. Besides simplifying the API, the new list components also have significant performance enhancements, the main one being nearly constant memory usage for any number of rows.

If your FlatList is rendering slow, be sure that you've implemented getItemLayout to optimize rendering speed by skipping measurement of the rendered items.

JS FPS plunges when re-rendering a view that hardly changes

If you are using a ListView, you must provide a rowHasChanged function that can reduce a lot of work by quickly determining whether or not a row needs to be re-rendered. If you are using immutable data structures, this would only need to be a reference equality check.

Similarly, you can implement shouldComponentUpdate and indicate the exact conditions under which you would like the component to re-render. If you write pure components (where the return value of the render function is entirely dependent on props and state), you can leverage PureComponent to do this for you. Once again, immutable data structures are useful to keep this fast -- if you have to do a deep comparison of a large list of objects, it may be that re-rendering your entire component would be quicker, and it would certainly require less code.

Dropping JS thread FPS because of doing a lot of work on the JavaScript thread at the same time

"Slow Navigator transitions" is the most common manifestation of this, but there are other times this can happen. Using InteractionManager can be a good approach, but if the user experience cost is too high to delay work during an animation, then you might want to consider LayoutAnimation.

The Animated API currently calculates each keyframe on-demand on the JavaScript thread unless you set useNativeDriver: true, while LayoutAnimation leverages Core Animation and is unaffected by JS thread and main thread frame drops.

One case where I have used this is for animating in a modal (sliding down from top and fading in a translucent overlay) while initializing and perhaps receiving responses for several network requests, rendering the contents of the modal, and updating the view where the modal was opened from. See the Animations guide for more information about how to use LayoutAnimation.

Caveats:

  • LayoutAnimation only works for fire-and-forget animations ("static" animations) -- if it must be interruptible, you will need to use Animated.

Moving a view on the screen (scrolling, translating, rotating) drops UI thread FPS

This is especially true when you have text with a transparent background positioned on top of an image, or any other situation where alpha compositing would be required to re-draw the view on each frame. You will find that enabling shouldRasterizeIOS or renderToHardwareTextureAndroid can help with this significantly.

Be careful not to overuse this or your memory usage could go through the roof. Profile your performance and memory usage when using these props. If you don't plan to move a view anymore, turn this property off.

Animating the size of an image drops UI thread FPS

On iOS, each time you adjust the width or height of an Image component it is re-cropped and scaled from the original image. This can be very expensive, especially for large images. Instead, use the transform: [{scale}] style property to animate the size. An example of when you might do this is when you tap an image and zoom it in to full screen.

My TouchableX view isn't very responsive

Sometimes, if we do an action in the same frame that we are adjusting the opacity or highlight of a component that is responding to a touch, we won't see that effect until after the onPress function has returned. If onPress does a setState that results in a lot of work and a few frames dropped, this may occur. A solution to this is to wrap any action inside of your onPress handler in requestAnimationFrame:

handleOnPress() {
requestAnimationFrame(() => {
this.doExpensiveAction();
});
}

Slow navigator transitions

As mentioned above, Navigator animations are controlled by the JavaScript thread. Imagine the "push from right" scene transition: each frame, the new scene is moved from the right to left, starting offscreen (let's say at an x-offset of 320) and ultimately settling when the scene sits at an x-offset of

  1. Each frame during this transition, the JavaScript thread needs to send a new x-offset to the main thread. If the JavaScript thread is locked up, it cannot do this and so no update occurs on that frame and the animation stutters.

One solution to this is to allow for JavaScript-based animations to be offloaded to the main thread. If we were to do the same thing as in the above example with this approach, we might calculate a list of all x-offsets for the new scene when we are starting the transition and send them to the main thread to execute in an optimized way. Now that the JavaScript thread is freed of this responsibility, it's not a big deal if it drops a few frames while rendering the scene -- you probably won't even notice because you will be too distracted by the pretty transition.

Solving this is one of the main goals behind the new React Navigation library. The views in React Navigation use native components and the Animated library to deliver 60 FPS animations that are run on the native thread.

Edit this page
Last updated on
- + diff --git a/docs/0.62/performance/index.html b/docs/0.62/performance/index.html index 7a9ba99d2b6..703d2458bf6 100644 --- a/docs/0.62/performance/index.html +++ b/docs/0.62/performance/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Performance Overview

A compelling reason for using React Native instead of WebView-based tools is to achieve 60 frames per second and a native look and feel to your apps. Where possible, we would like for React Native to do the right thing and help you to focus on your app instead of performance optimization, but there are areas where we're not quite there yet, and others where React Native (similar to writing native code directly) cannot possibly determine the best way to optimize for you and so manual intervention will be necessary. We try our best to deliver buttery-smooth UI performance by default, but sometimes that isn't possible.

This guide is intended to teach you some basics to help you to troubleshoot performance issues, as well as discuss common sources of problems and their suggested solutions.

What you need to know about frames

Your grandparents' generation called movies "moving pictures" for a reason: realistic motion in video is an illusion created by quickly changing static images at a consistent speed. We refer to each of these images as frames. The number of frames that is displayed each second has a direct impact on how smooth and ultimately life-like a video (or user interface) seems to be. iOS devices display 60 frames per second, which gives you and the UI system about 16.67ms to do all of the work needed to generate the static image (frame) that the user will see on the screen for that interval. If you are unable to do the work necessary to generate that frame within the allotted 16.67ms, then you will "drop a frame" and the UI will appear unresponsive.

Now to confuse the matter a little bit, open up the developer menu in your app and toggle Show Perf Monitor. You will notice that there are two different frame rates.

JS frame rate (JavaScript thread)

For most React Native applications, your business logic will run on the JavaScript thread. This is where your React application lives, API calls are made, touch events are processed, etc... Updates to native-backed views are batched and sent over to the native side at the end of each iteration of the event loop, before the frame deadline (if all goes well). If the JavaScript thread is unresponsive for a frame, it will be considered a dropped frame. For example, if you were to call this.setState on the root component of a complex application and it resulted in re-rendering computationally expensive component subtrees, it's conceivable that this might take 200ms and result in 12 frames being dropped. Any animations controlled by JavaScript would appear to freeze during that time. If anything takes longer than 100ms, the user will feel it.

This often happens during Navigator transitions: when you push a new route, the JavaScript thread needs to render all of the components necessary for the scene in order to send over the proper commands to the native side to create the backing views. It's common for the work being done here to take a few frames and cause jank because the transition is controlled by the JavaScript thread. Sometimes components will do additional work on componentDidMount, which might result in a second stutter in the transition.

Another example is responding to touches: if you are doing work across multiple frames on the JavaScript thread, you might notice a delay in responding to TouchableOpacity, for example. This is because the JavaScript thread is busy and cannot process the raw touch events sent over from the main thread. As a result, TouchableOpacity cannot react to the touch events and command the native view to adjust its opacity.

UI frame rate (main thread)

Many people have noticed that performance of NavigatorIOS is better out of the box than Navigator. The reason for this is that the animations for the transitions are done entirely on the main thread, and so they are not interrupted by frame drops on the JavaScript thread.

Similarly, you can happily scroll up and down through a ScrollView when the JavaScript thread is locked up because the ScrollView lives on the main thread. The scroll events are dispatched to the JS thread, but their receipt is not necessary for the scroll to occur.

Common sources of performance problems

Running in development mode (dev=true)

JavaScript thread performance suffers greatly when running in dev mode. This is unavoidable: a lot more work needs to be done at runtime to provide you with good warnings and error messages, such as validating propTypes and various other assertions. Always make sure to test performance in release builds.

Using console.log statements

When running a bundled app, these statements can cause a big bottleneck in the JavaScript thread. This includes calls from debugging libraries such as redux-logger, so make sure to remove them before bundling. You can also use this babel plugin that removes all the console.* calls. You need to install it first with npm i babel-plugin-transform-remove-console --save-dev, and then edit the .babelrc file under your project directory like this:

{
"env": {
"production": {
"plugins": ["transform-remove-console"]
}
}
}

This will automatically remove all console.* calls in the release (production) versions of your project.

ListView initial rendering is too slow or scroll performance is bad for large lists

Use the new FlatList or SectionList component instead. Besides simplifying the API, the new list components also have significant performance enhancements, the main one being nearly constant memory usage for any number of rows.

If your FlatList is rendering slow, be sure that you've implemented getItemLayout to optimize rendering speed by skipping measurement of the rendered items.

JS FPS plunges when re-rendering a view that hardly changes

If you are using a ListView, you must provide a rowHasChanged function that can reduce a lot of work by quickly determining whether or not a row needs to be re-rendered. If you are using immutable data structures, this would only need to be a reference equality check.

Similarly, you can implement shouldComponentUpdate and indicate the exact conditions under which you would like the component to re-render. If you write pure components (where the return value of the render function is entirely dependent on props and state), you can leverage PureComponent to do this for you. Once again, immutable data structures are useful to keep this fast -- if you have to do a deep comparison of a large list of objects, it may be that re-rendering your entire component would be quicker, and it would certainly require less code.

Dropping JS thread FPS because of doing a lot of work on the JavaScript thread at the same time

"Slow Navigator transitions" is the most common manifestation of this, but there are other times this can happen. Using InteractionManager can be a good approach, but if the user experience cost is too high to delay work during an animation, then you might want to consider LayoutAnimation.

The Animated API currently calculates each keyframe on-demand on the JavaScript thread unless you set useNativeDriver: true, while LayoutAnimation leverages Core Animation and is unaffected by JS thread and main thread frame drops.

One case where I have used this is for animating in a modal (sliding down from top and fading in a translucent overlay) while initializing and perhaps receiving responses for several network requests, rendering the contents of the modal, and updating the view where the modal was opened from. See the Animations guide for more information about how to use LayoutAnimation.

Caveats:

  • LayoutAnimation only works for fire-and-forget animations ("static" animations) -- if it must be interruptible, you will need to use Animated.

Moving a view on the screen (scrolling, translating, rotating) drops UI thread FPS

This is especially true when you have text with a transparent background positioned on top of an image, or any other situation where alpha compositing would be required to re-draw the view on each frame. You will find that enabling shouldRasterizeIOS or renderToHardwareTextureAndroid can help with this significantly.

Be careful not to overuse this or your memory usage could go through the roof. Profile your performance and memory usage when using these props. If you don't plan to move a view anymore, turn this property off.

Animating the size of an image drops UI thread FPS

On iOS, each time you adjust the width or height of an Image component it is re-cropped and scaled from the original image. This can be very expensive, especially for large images. Instead, use the transform: [{scale}] style property to animate the size. An example of when you might do this is when you tap an image and zoom it in to full screen.

My TouchableX view isn't very responsive

Sometimes, if we do an action in the same frame that we are adjusting the opacity or highlight of a component that is responding to a touch, we won't see that effect until after the onPress function has returned. If onPress does a setState that results in a lot of work and a few frames dropped, this may occur. A solution to this is to wrap any action inside of your onPress handler in requestAnimationFrame:

handleOnPress() {
requestAnimationFrame(() => {
this.doExpensiveAction();
});
}

Slow navigator transitions

As mentioned above, Navigator animations are controlled by the JavaScript thread. Imagine the "push from right" scene transition: each frame, the new scene is moved from the right to left, starting offscreen (let's say at an x-offset of 320) and ultimately settling when the scene sits at an x-offset of

  1. Each frame during this transition, the JavaScript thread needs to send a new x-offset to the main thread. If the JavaScript thread is locked up, it cannot do this and so no update occurs on that frame and the animation stutters.

One solution to this is to allow for JavaScript-based animations to be offloaded to the main thread. If we were to do the same thing as in the above example with this approach, we might calculate a list of all x-offsets for the new scene when we are starting the transition and send them to the main thread to execute in an optimized way. Now that the JavaScript thread is freed of this responsibility, it's not a big deal if it drops a few frames while rendering the scene -- you probably won't even notice because you will be too distracted by the pretty transition.

Solving this is one of the main goals behind the new React Navigation library. The views in React Navigation use native components and the Animated library to deliver 60 FPS animations that are run on the native thread.

Edit this page
Last updated on
- + diff --git a/docs/0.62/permissionsandroid.html b/docs/0.62/permissionsandroid.html index f0e0ceefb98..64c5b153c97 100644 --- a/docs/0.62/permissionsandroid.html +++ b/docs/0.62/permissionsandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

PermissionsAndroid

PermissionsAndroid provides access to Android M's new permissions model. The so-called "normal" permissions are granted by default when the application is installed as long as they appear in AndroidManifest.xml. However, "dangerous" permissions require a dialog prompt. You should use this module for those permissions.

On devices before SDK version 23, the permissions are automatically granted if they appear in the manifest, so check should always result to true and request should always resolve to PermissionsAndroid.RESULTS.GRANTED.

If a user has previously turned off a permission that you prompt for, the OS will advise your app to show a rationale for needing the permission. The optional rationale argument will show a dialog prompt only if necessary - otherwise the normal permission prompt will appear.

Example

Permissions that require prompting the user

Available as constants under PermissionsAndroid.PERMISSIONS:

  • READ_CALENDAR: 'android.permission.READ_CALENDAR'
  • WRITE_CALENDAR: 'android.permission.WRITE_CALENDAR'
  • CAMERA: 'android.permission.CAMERA'
  • READ_CONTACTS: 'android.permission.READ_CONTACTS'
  • WRITE_CONTACTS: 'android.permission.WRITE_CONTACTS'
  • GET_ACCOUNTS: 'android.permission.GET_ACCOUNTS'
  • ACCESS_FINE_LOCATION: 'android.permission.ACCESS_FINE_LOCATION'
  • ACCESS_COARSE_LOCATION: 'android.permission.ACCESS_COARSE_LOCATION'
  • RECORD_AUDIO: 'android.permission.RECORD_AUDIO'
  • READ_PHONE_STATE: 'android.permission.READ_PHONE_STATE'
  • CALL_PHONE: 'android.permission.CALL_PHONE'
  • READ_CALL_LOG: 'android.permission.READ_CALL_LOG'
  • WRITE_CALL_LOG: 'android.permission.WRITE_CALL_LOG'
  • ADD_VOICEMAIL: 'com.android.voicemail.permission.ADD_VOICEMAIL'
  • USE_SIP: 'android.permission.USE_SIP'
  • PROCESS_OUTGOING_CALLS: 'android.permission.PROCESS_OUTGOING_CALLS'
  • BODY_SENSORS: 'android.permission.BODY_SENSORS'
  • SEND_SMS: 'android.permission.SEND_SMS'
  • RECEIVE_SMS: 'android.permission.RECEIVE_SMS'
  • READ_SMS: 'android.permission.READ_SMS'
  • RECEIVE_WAP_PUSH: 'android.permission.RECEIVE_WAP_PUSH'
  • RECEIVE_MMS: 'android.permission.RECEIVE_MMS'
  • READ_EXTERNAL_STORAGE: 'android.permission.READ_EXTERNAL_STORAGE'
  • WRITE_EXTERNAL_STORAGE: 'android.permission.WRITE_EXTERNAL_STORAGE'

Result strings for requesting permissions

Available as constants under PermissionsAndroid.RESULTS:

  • GRANTED: 'granted'
  • DENIED: 'denied'
  • NEVER_ASK_AGAIN: 'never_ask_again'

Reference

Methods

constructor()

constructor();

check()

check(permission);

Returns a promise resolving to a boolean value as to whether the specified permissions has been granted.

Parameters:

NameTypeRequiredDescription
permissionstringYesThe permission to check for.

request()

request(permission, [rationale]);

Prompts the user to enable a permission and returns a promise resolving to a string value (see result strings above) indicating whether the user allowed or denied the request or does not want to be asked again.

If rationale is provided, this function checks with the OS whether it is necessary to show a dialog explaining why the permission is needed (https://developer.android.com/training/permissions/requesting.html#explain) and then shows the system permission dialog.

Parameters:

NameTypeRequiredDescription
permissionstringYesThe permission to request.
rationaleobjectNoSee rationale below.

Rationale:

NameTypeRequiredDescription
titlestringYesThe title of the dialog.
messagestringYesThe message of the dialog.
buttonPositivestringYesThe text of the positive button.
buttonNegativestringNoThe text of the negative button.
buttonNeutralstringNoThe text of the neutral button.

requestMultiple()

requestMultiple(permissions);

Prompts the user to enable multiple permissions in the same dialog and returns an object with the permissions as keys and strings as values (see result strings above) indicating whether the user allowed or denied the request or does not want to be asked again.

Parameters:

NameTypeRequiredDescription
permissionsarrayYesArray of permissions to request.
Edit this page
Last updated on
- + diff --git a/docs/0.62/permissionsandroid/index.html b/docs/0.62/permissionsandroid/index.html index f0e0ceefb98..64c5b153c97 100644 --- a/docs/0.62/permissionsandroid/index.html +++ b/docs/0.62/permissionsandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

PermissionsAndroid

PermissionsAndroid provides access to Android M's new permissions model. The so-called "normal" permissions are granted by default when the application is installed as long as they appear in AndroidManifest.xml. However, "dangerous" permissions require a dialog prompt. You should use this module for those permissions.

On devices before SDK version 23, the permissions are automatically granted if they appear in the manifest, so check should always result to true and request should always resolve to PermissionsAndroid.RESULTS.GRANTED.

If a user has previously turned off a permission that you prompt for, the OS will advise your app to show a rationale for needing the permission. The optional rationale argument will show a dialog prompt only if necessary - otherwise the normal permission prompt will appear.

Example

Permissions that require prompting the user

Available as constants under PermissionsAndroid.PERMISSIONS:

  • READ_CALENDAR: 'android.permission.READ_CALENDAR'
  • WRITE_CALENDAR: 'android.permission.WRITE_CALENDAR'
  • CAMERA: 'android.permission.CAMERA'
  • READ_CONTACTS: 'android.permission.READ_CONTACTS'
  • WRITE_CONTACTS: 'android.permission.WRITE_CONTACTS'
  • GET_ACCOUNTS: 'android.permission.GET_ACCOUNTS'
  • ACCESS_FINE_LOCATION: 'android.permission.ACCESS_FINE_LOCATION'
  • ACCESS_COARSE_LOCATION: 'android.permission.ACCESS_COARSE_LOCATION'
  • RECORD_AUDIO: 'android.permission.RECORD_AUDIO'
  • READ_PHONE_STATE: 'android.permission.READ_PHONE_STATE'
  • CALL_PHONE: 'android.permission.CALL_PHONE'
  • READ_CALL_LOG: 'android.permission.READ_CALL_LOG'
  • WRITE_CALL_LOG: 'android.permission.WRITE_CALL_LOG'
  • ADD_VOICEMAIL: 'com.android.voicemail.permission.ADD_VOICEMAIL'
  • USE_SIP: 'android.permission.USE_SIP'
  • PROCESS_OUTGOING_CALLS: 'android.permission.PROCESS_OUTGOING_CALLS'
  • BODY_SENSORS: 'android.permission.BODY_SENSORS'
  • SEND_SMS: 'android.permission.SEND_SMS'
  • RECEIVE_SMS: 'android.permission.RECEIVE_SMS'
  • READ_SMS: 'android.permission.READ_SMS'
  • RECEIVE_WAP_PUSH: 'android.permission.RECEIVE_WAP_PUSH'
  • RECEIVE_MMS: 'android.permission.RECEIVE_MMS'
  • READ_EXTERNAL_STORAGE: 'android.permission.READ_EXTERNAL_STORAGE'
  • WRITE_EXTERNAL_STORAGE: 'android.permission.WRITE_EXTERNAL_STORAGE'

Result strings for requesting permissions

Available as constants under PermissionsAndroid.RESULTS:

  • GRANTED: 'granted'
  • DENIED: 'denied'
  • NEVER_ASK_AGAIN: 'never_ask_again'

Reference

Methods

constructor()

constructor();

check()

check(permission);

Returns a promise resolving to a boolean value as to whether the specified permissions has been granted.

Parameters:

NameTypeRequiredDescription
permissionstringYesThe permission to check for.

request()

request(permission, [rationale]);

Prompts the user to enable a permission and returns a promise resolving to a string value (see result strings above) indicating whether the user allowed or denied the request or does not want to be asked again.

If rationale is provided, this function checks with the OS whether it is necessary to show a dialog explaining why the permission is needed (https://developer.android.com/training/permissions/requesting.html#explain) and then shows the system permission dialog.

Parameters:

NameTypeRequiredDescription
permissionstringYesThe permission to request.
rationaleobjectNoSee rationale below.

Rationale:

NameTypeRequiredDescription
titlestringYesThe title of the dialog.
messagestringYesThe message of the dialog.
buttonPositivestringYesThe text of the positive button.
buttonNegativestringNoThe text of the negative button.
buttonNeutralstringNoThe text of the neutral button.

requestMultiple()

requestMultiple(permissions);

Prompts the user to enable multiple permissions in the same dialog and returns an object with the permissions as keys and strings as values (see result strings above) indicating whether the user allowed or denied the request or does not want to be asked again.

Parameters:

NameTypeRequiredDescription
permissionsarrayYesArray of permissions to request.
Edit this page
Last updated on
- + diff --git a/docs/0.62/picker-item.html b/docs/0.62/picker-item.html index 60cea32ed08..10e8ca9a294 100644 --- a/docs/0.62/picker-item.html +++ b/docs/0.62/picker-item.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Picker.Item

Individual selectable item in a Picker.

Props

Reference

Props

label

Text to display for this item.

TypeRequired
stringYes

color

Color of this item's text.

TypeRequired
colorNo

testID

Used to locate the item in end-to-end tests.

TypeRequired
stringNo

value

The value to be passed to picker's onValueChange callback when this item is selected. Can be a string or an integer.

TypeRequiredPlatform
anyNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.62/picker-item/index.html b/docs/0.62/picker-item/index.html index 60cea32ed08..10e8ca9a294 100644 --- a/docs/0.62/picker-item/index.html +++ b/docs/0.62/picker-item/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Picker.Item

Individual selectable item in a Picker.

Props

Reference

Props

label

Text to display for this item.

TypeRequired
stringYes

color

Color of this item's text.

TypeRequired
colorNo

testID

Used to locate the item in end-to-end tests.

TypeRequired
stringNo

value

The value to be passed to picker's onValueChange callback when this item is selected. Can be a string or an integer.

TypeRequiredPlatform
anyNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.62/picker-style-props.html b/docs/0.62/picker-style-props.html index 2bea8bf92a4..09ed2ea974f 100644 --- a/docs/0.62/picker-style-props.html +++ b/docs/0.62/picker-style-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.62/picker-style-props/index.html b/docs/0.62/picker-style-props/index.html index 2bea8bf92a4..09ed2ea974f 100644 --- a/docs/0.62/picker-style-props/index.html +++ b/docs/0.62/picker-style-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.62/picker.html b/docs/0.62/picker.html index a14ec0230a3..10b029ab394 100644 --- a/docs/0.62/picker.html +++ b/docs/0.62/picker.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 Picker

Deprecated. Use @react-native-community/picker instead.

Renders the native picker component on Android and iOS.

Example

Reference

Props

Inherits View Props.

enabled

If set to false, the picker will be disabled, i.e. the user will not be able to make a selection.

TypeRequiredPlatform
boolNoAndroid

itemStyle

Style to apply to each of the item labels.

TypeRequiredPlatform
text stylesNoiOS

mode

On Android, specifies how to display the selection items when the user taps on the picker:

  • 'dialog': Show a modal dialog. This is the default.
  • 'dropdown': Shows a dropdown anchored to the picker view
TypeRequiredPlatform
enum('dialog', 'dropdown')NoAndroid

onValueChange

Callback for when an item is selected. This is called with the following parameters:

  • itemValue: the value prop of the item that was selected
  • itemPosition: the index of the selected item in this picker
TypeRequired
functionNo

prompt

Prompt string for this picker, used on Android in dialog mode as the title of the dialog.

TypeRequiredPlatform
stringNoAndroid

selectedValue

Value matching value of one of the items. Can be a string or an integer.

TypeRequired
anyNo

style

TypeRequired
pickerStyleTypeNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/picker/index.html b/docs/0.62/picker/index.html index a14ec0230a3..10b029ab394 100644 --- a/docs/0.62/picker/index.html +++ b/docs/0.62/picker/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 Picker

Deprecated. Use @react-native-community/picker instead.

Renders the native picker component on Android and iOS.

Example

Reference

Props

Inherits View Props.

enabled

If set to false, the picker will be disabled, i.e. the user will not be able to make a selection.

TypeRequiredPlatform
boolNoAndroid

itemStyle

Style to apply to each of the item labels.

TypeRequiredPlatform
text stylesNoiOS

mode

On Android, specifies how to display the selection items when the user taps on the picker:

  • 'dialog': Show a modal dialog. This is the default.
  • 'dropdown': Shows a dropdown anchored to the picker view
TypeRequiredPlatform
enum('dialog', 'dropdown')NoAndroid

onValueChange

Callback for when an item is selected. This is called with the following parameters:

  • itemValue: the value prop of the item that was selected
  • itemPosition: the index of the selected item in this picker
TypeRequired
functionNo

prompt

Prompt string for this picker, used on Android in dialog mode as the title of the dialog.

TypeRequiredPlatform
stringNoAndroid

selectedValue

Value matching value of one of the items. Can be a string or an integer.

TypeRequired
anyNo

style

TypeRequired
pickerStyleTypeNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/pickerios.html b/docs/0.62/pickerios.html index 2ee504ced0c..14616664039 100644 --- a/docs/0.62/pickerios.html +++ b/docs/0.62/pickerios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.62/pickerios/index.html b/docs/0.62/pickerios/index.html index 2ee504ced0c..14616664039 100644 --- a/docs/0.62/pickerios/index.html +++ b/docs/0.62/pickerios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.62/pixelratio.html b/docs/0.62/pixelratio.html index 57b45e95c3b..2d21a97bb8c 100644 --- a/docs/0.62/pixelratio.html +++ b/docs/0.62/pixelratio.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

PixelRatio

PixelRatio gives you access to the device's pixel density and font scale.

Fetching a correctly sized image

You should get a higher resolution image if you are on a high pixel density device. A good rule of thumb is to multiply the size of the image you display by the pixel ratio.

var image = getImage({
width: PixelRatio.getPixelSizeForLayoutSize(200),
height: PixelRatio.getPixelSizeForLayoutSize(100)
});
<Image source={image} style={{ width: 200, height: 100 }} />;

Pixel grid snapping

In iOS, you can specify positions and dimensions for elements with arbitrary precision, for example 29.674825. But, ultimately the physical display only have a fixed number of pixels, for example 640×960 for iPhone 4 or 750×1334 for iPhone 6. iOS tries to be as faithful as possible to the user value by spreading one original pixel into multiple ones to trick the eye. The downside of this technique is that it makes the resulting element look blurry.

In practice, we found out that developers do not want this feature and they have to work around it by doing manual rounding in order to avoid having blurry elements. In React Native, we are rounding all the pixels automatically.

We have to be careful when to do this rounding. You never want to work with rounded and unrounded values at the same time as you're going to accumulate rounding errors. Having even one rounding error is deadly because a one pixel border may vanish or be twice as big.

In React Native, everything in JavaScript and within the layout engine works with arbitrary precision numbers. It's only when we set the position and dimensions of the native element on the main thread that we round. Also, rounding is done relative to the root rather than the parent, again to avoid accumulating rounding errors.

Example

Reference

Methods

get()

static get()

Returns the device pixel density. Some examples:

getFontScale()

static getFontScale(): number

Returns the scaling factor for font sizes. This is the ratio that is used to calculate the absolute font size, so any elements that heavily depend on that should use this to do calculations.

  • on Android value reflects the user preference set in Settings > Display > Font size
  • on iOS it will always return the default pixel ratio

If a font scale is not set, this returns the device pixel ratio.

getPixelSizeForLayoutSize()

static getPixelSizeForLayoutSize(layoutSize: number): number

Converts a layout size (dp) to pixel size (px).

Guaranteed to return an integer number.

roundToNearestPixel()

static roundToNearestPixel(layoutSize: number): number

Rounds a layout size (dp) to the nearest layout size that corresponds to an integer number of pixels. For example, on a device with a PixelRatio of 3, PixelRatio.roundToNearestPixel(8.4) = 8.33, which corresponds to exactly (8.33 * 3) = 25 pixels.

Edit this page
Last updated on
- + diff --git a/docs/0.62/pixelratio/index.html b/docs/0.62/pixelratio/index.html index 57b45e95c3b..2d21a97bb8c 100644 --- a/docs/0.62/pixelratio/index.html +++ b/docs/0.62/pixelratio/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

PixelRatio

PixelRatio gives you access to the device's pixel density and font scale.

Fetching a correctly sized image

You should get a higher resolution image if you are on a high pixel density device. A good rule of thumb is to multiply the size of the image you display by the pixel ratio.

var image = getImage({
width: PixelRatio.getPixelSizeForLayoutSize(200),
height: PixelRatio.getPixelSizeForLayoutSize(100)
});
<Image source={image} style={{ width: 200, height: 100 }} />;

Pixel grid snapping

In iOS, you can specify positions and dimensions for elements with arbitrary precision, for example 29.674825. But, ultimately the physical display only have a fixed number of pixels, for example 640×960 for iPhone 4 or 750×1334 for iPhone 6. iOS tries to be as faithful as possible to the user value by spreading one original pixel into multiple ones to trick the eye. The downside of this technique is that it makes the resulting element look blurry.

In practice, we found out that developers do not want this feature and they have to work around it by doing manual rounding in order to avoid having blurry elements. In React Native, we are rounding all the pixels automatically.

We have to be careful when to do this rounding. You never want to work with rounded and unrounded values at the same time as you're going to accumulate rounding errors. Having even one rounding error is deadly because a one pixel border may vanish or be twice as big.

In React Native, everything in JavaScript and within the layout engine works with arbitrary precision numbers. It's only when we set the position and dimensions of the native element on the main thread that we round. Also, rounding is done relative to the root rather than the parent, again to avoid accumulating rounding errors.

Example

Reference

Methods

get()

static get()

Returns the device pixel density. Some examples:

getFontScale()

static getFontScale(): number

Returns the scaling factor for font sizes. This is the ratio that is used to calculate the absolute font size, so any elements that heavily depend on that should use this to do calculations.

  • on Android value reflects the user preference set in Settings > Display > Font size
  • on iOS it will always return the default pixel ratio

If a font scale is not set, this returns the device pixel ratio.

getPixelSizeForLayoutSize()

static getPixelSizeForLayoutSize(layoutSize: number): number

Converts a layout size (dp) to pixel size (px).

Guaranteed to return an integer number.

roundToNearestPixel()

static roundToNearestPixel(layoutSize: number): number

Rounds a layout size (dp) to the nearest layout size that corresponds to an integer number of pixels. For example, on a device with a PixelRatio of 3, PixelRatio.roundToNearestPixel(8.4) = 8.33, which corresponds to exactly (8.33 * 3) = 25 pixels.

Edit this page
Last updated on
- + diff --git a/docs/0.62/platform-specific-code.html b/docs/0.62/platform-specific-code.html index dedb9045a55..404ca92146d 100644 --- a/docs/0.62/platform-specific-code.html +++ b/docs/0.62/platform-specific-code.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
const majorVersionIOS = parseInt(Platform.Version, 10);
if (majorVersionIOS <= 9) {
console.log('Work around a change in behavior');
}

Platform-specific extensions

When your platform-specific code is more complex, you should consider splitting the code out into separate files. React Native will detect when a file has a .ios. or .android. extension and load the relevant platform file when required from other components.

For example, say you have the following files in your project:

BigButton.ios.js
BigButton.android.js

You can then require the component as follows:

import BigButton from './BigButton';

React Native will automatically pick up the right file based on the running platform.

Native-specific extensions (i.e. sharing code with NodeJS and Web)

You can also use the .native.js extension when a module needs to be shared between NodeJS/Web and React Native but it has no Android/iOS differences. This is specially useful for projects that has common code shared among React Native and ReactJS.

For example, say you have the following files in your project:

Container.js # picked up by Webpack, Rollup or any other Web bundler
Container.native.js # picked up by the React Native bundler for both Android and iOS (Metro)

You can still require it without the .native extension, as follows:

import Container from './Container';

Pro tip: Configure your Web bundler to ignore .native.js extensions in order to avoid having unused code in your production bundle, thus reducing the final bundle size.

Edit this page
Last updated on
- + diff --git a/docs/0.62/platform-specific-code/index.html b/docs/0.62/platform-specific-code/index.html index dedb9045a55..404ca92146d 100644 --- a/docs/0.62/platform-specific-code/index.html +++ b/docs/0.62/platform-specific-code/index.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
const majorVersionIOS = parseInt(Platform.Version, 10);
if (majorVersionIOS <= 9) {
console.log('Work around a change in behavior');
}

Platform-specific extensions

When your platform-specific code is more complex, you should consider splitting the code out into separate files. React Native will detect when a file has a .ios. or .android. extension and load the relevant platform file when required from other components.

For example, say you have the following files in your project:

BigButton.ios.js
BigButton.android.js

You can then require the component as follows:

import BigButton from './BigButton';

React Native will automatically pick up the right file based on the running platform.

Native-specific extensions (i.e. sharing code with NodeJS and Web)

You can also use the .native.js extension when a module needs to be shared between NodeJS/Web and React Native but it has no Android/iOS differences. This is specially useful for projects that has common code shared among React Native and ReactJS.

For example, say you have the following files in your project:

Container.js # picked up by Webpack, Rollup or any other Web bundler
Container.native.js # picked up by the React Native bundler for both Android and iOS (Metro)

You can still require it without the .native extension, as follows:

import Container from './Container';

Pro tip: Configure your Web bundler to ignore .native.js extensions in order to avoid having unused code in your production bundle, thus reducing the final bundle size.

Edit this page
Last updated on
- + diff --git a/docs/0.62/profiling.html b/docs/0.62/profiling.html index 33a7ef3c3cf..8c615108a6b 100644 --- a/docs/0.62/profiling.html +++ b/docs/0.62/profiling.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Profiling

Use the built-in profiler to get detailed information about work done in the JavaScript thread and main thread side-by-side. Access it by selecting Perf Monitor from the Debug menu.

For iOS, Instruments is an invaluable tool, and on Android you should learn to use systrace.

But first, make sure that Development Mode is OFF! You should see __DEV__ === false, development-level warning are OFF, performance optimizations are ON in your application logs.

Another way to profile JavaScript is to use the Chrome profiler while debugging. This won't give you accurate results as the code is running in Chrome but will give you a general idea of where bottlenecks might be. Run the profiler under Chrome's Performance tab. A flame graph will appear under User Timing. To view more details in tabular format, click at the Bottom Up tab below and then select DedicatedWorker Thread at the top left menu.

Profiling Android UI Performance with systrace

Android supports 10k+ different phones and is generalized to support software rendering: the framework architecture and need to generalize across many hardware targets unfortunately means you get less for free relative to iOS. But sometimes, there are things you can improve -- and many times it's not native code's fault at all!

The first step for debugging this jank is to answer the fundamental question of where your time is being spent during each 16ms frame. For that, we'll be using a standard Android profiling tool called systrace.

systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.

1. Collecting a trace

First, connect a device that exhibits the stuttering you want to investigate to your computer via USB and get it to the point right before the navigation/animation you want to profile. Run systrace as follows:

$ <path_to_android_sdk>/platform-tools/systrace/systrace.py --time=10 -o trace.html sched gfx view -a <your_package_name>

A quick breakdown of this command:

  • time is the length of time the trace will be collected in seconds
  • sched, gfx, and view are the android SDK tags (collections of markers) we care about: sched gives you information about what's running on each core of your phone, gfx gives you graphics info such as frame boundaries, and view gives you information about measure, layout, and draw passes
  • -a <your_package_name> enables app-specific markers, specifically the ones built into the React Native framework. your_package_name can be found in the AndroidManifest.xml of your app and looks like com.example.app

Once the trace starts collecting, perform the animation or interaction you care about. At the end of the trace, systrace will give you a link to the trace which you can open in your browser.

2. Reading the trace

After opening the trace in your browser (preferably Chrome), you should see something like this:

Example

HINT: Use the WASD keys to strafe and zoom

If your trace .html file isn't opening correctly, check your browser console for the following:

ObjectObserveError

Since Object.observe was deprecated in recent browsers, you may have to open the file from the Google Chrome Tracing tool. You can do so by:

  • Opening tab in chrome chrome://tracing
  • Selecting load
  • Selecting the html file generated from the previous command.

Enable VSync highlighting

Check this checkbox at the top right of the screen to highlight the 16ms frame boundaries:

Enable VSync Highlighting

You should see zebra stripes as in the screenshot above. If you don't, try profiling on a different device: Samsung has been known to have issues displaying vsyncs while the Nexus series is generally pretty reliable.

3. Find your process

Scroll until you see (part of) the name of your package. In this case, I was profiling com.facebook.adsmanager, which shows up as book.adsmanager because of silly thread name limits in the kernel.

On the left side, you'll see a set of threads which correspond to the timeline rows on the right. There are a few threads we care about for our purposes: the UI thread (which has your package name or the name UI Thread), mqt_js, and mqt_native_modules. If you're running on Android 5+, we also care about the Render Thread.

  • UI Thread. This is where standard android measure/layout/draw happens. The thread name on the right will be your package name (in my case book.adsmanager) or UI Thread. The events that you see on this thread should look something like this and have to do with Choreographer, traversals, and DispatchUI:

    UI Thread Example

  • JS Thread. This is where JavaScript is executed. The thread name will be either mqt_js or <...> depending on how cooperative the kernel on your device is being. To identify it if it doesn't have a name, look for things like JSCall, Bridge.executeJSCall, etc:

    JS Thread Example

  • Native Modules Thread. This is where native module calls (e.g. the UIManager) are executed. The thread name will be either mqt_native_modules or <...>. To identify it in the latter case, look for things like NativeCall, callJavaModuleMethod, and onBatchComplete:

    Native Modules Thread Example

  • Bonus: Render Thread. If you're using Android L (5.0) and up, you will also have a render thread in your application. This thread generates the actual OpenGL commands used to draw your UI. The thread name will be either RenderThread or <...>. To identify it in the latter case, look for things like DrawFrame and queueBuffer:

    Render Thread Example

Identifying a culprit

A smooth animation should look something like the following:

Smooth Animation

Each change in color is a frame -- remember that in order to display a frame, all our UI work needs to be done by the end of that 16ms period. Notice that no thread is working close to the frame boundary. An application rendering like this is rendering at 60 FPS.

If you noticed chop, however, you might see something like this:

Choppy Animation from JS

Notice that the JS thread is executing almost all the time, and across frame boundaries! This app is not rendering at 60 FPS. In this case, the problem lies in JS.

You might also see something like this:

Choppy Animation from UI

In this case, the UI and render threads are the ones that have work crossing frame boundaries. The UI that we're trying to render on each frame is requiring too much work to be done. In this case, the problem lies in the native views being rendered.

At this point, you'll have some very helpful information to inform your next steps.

Resolving JavaScript issues

If you identified a JS problem, look for clues in the specific JS that you're executing. In the scenario above, we see RCTEventEmitter being called multiple times per frame. Here's a zoom-in of the JS thread from the trace above:

Too much JS

This doesn't seem right. Why is it being called so often? Are they actually different events? The answers to these questions will probably depend on your product code. And many times, you'll want to look into shouldComponentUpdate.

Resolving native UI Issues

If you identified a native UI problem, there are usually two scenarios:

  1. the UI you're trying to draw each frame involves too much work on the GPU, or
  2. You're constructing new UI during the animation/interaction (e.g. loading in new content during a scroll).

Too much GPU work

In the first scenario, you'll see a trace that has the UI thread and/or Render Thread looking like this:

Overloaded GPU

Notice the long amount of time spent in DrawFrame that crosses frame boundaries. This is time spent waiting for the GPU to drain its command buffer from the previous frame.

To mitigate this, you should:

  • investigate using renderToHardwareTextureAndroid for complex, static content that is being animated/transformed (e.g. the Navigator slide/alpha animations)
  • make sure that you are not using needsOffscreenAlphaCompositing, which is disabled by default, as it greatly increases the per-frame load on the GPU in most cases.

If these don't help and you want to dig deeper into what the GPU is actually doing, you can check out Tracer for OpenGL ES.

Creating new views on the UI thread

In the second scenario, you'll see something more like this:

Creating Views

Notice that first the JS thread thinks for a bit, then you see some work done on the native modules thread, followed by an expensive traversal on the UI thread.

There isn't a quick way to mitigate this unless you're able to postpone creating new UI until after the interaction, or you are able to simplify the UI you're creating. The react native team is working on an infrastructure level solution for this that will allow new UI to be created and configured off the main thread, allowing the interaction to continue smoothly.

Edit this page
Last updated on
- + diff --git a/docs/0.62/profiling/index.html b/docs/0.62/profiling/index.html index 33a7ef3c3cf..8c615108a6b 100644 --- a/docs/0.62/profiling/index.html +++ b/docs/0.62/profiling/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Profiling

Use the built-in profiler to get detailed information about work done in the JavaScript thread and main thread side-by-side. Access it by selecting Perf Monitor from the Debug menu.

For iOS, Instruments is an invaluable tool, and on Android you should learn to use systrace.

But first, make sure that Development Mode is OFF! You should see __DEV__ === false, development-level warning are OFF, performance optimizations are ON in your application logs.

Another way to profile JavaScript is to use the Chrome profiler while debugging. This won't give you accurate results as the code is running in Chrome but will give you a general idea of where bottlenecks might be. Run the profiler under Chrome's Performance tab. A flame graph will appear under User Timing. To view more details in tabular format, click at the Bottom Up tab below and then select DedicatedWorker Thread at the top left menu.

Profiling Android UI Performance with systrace

Android supports 10k+ different phones and is generalized to support software rendering: the framework architecture and need to generalize across many hardware targets unfortunately means you get less for free relative to iOS. But sometimes, there are things you can improve -- and many times it's not native code's fault at all!

The first step for debugging this jank is to answer the fundamental question of where your time is being spent during each 16ms frame. For that, we'll be using a standard Android profiling tool called systrace.

systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.

1. Collecting a trace

First, connect a device that exhibits the stuttering you want to investigate to your computer via USB and get it to the point right before the navigation/animation you want to profile. Run systrace as follows:

$ <path_to_android_sdk>/platform-tools/systrace/systrace.py --time=10 -o trace.html sched gfx view -a <your_package_name>

A quick breakdown of this command:

  • time is the length of time the trace will be collected in seconds
  • sched, gfx, and view are the android SDK tags (collections of markers) we care about: sched gives you information about what's running on each core of your phone, gfx gives you graphics info such as frame boundaries, and view gives you information about measure, layout, and draw passes
  • -a <your_package_name> enables app-specific markers, specifically the ones built into the React Native framework. your_package_name can be found in the AndroidManifest.xml of your app and looks like com.example.app

Once the trace starts collecting, perform the animation or interaction you care about. At the end of the trace, systrace will give you a link to the trace which you can open in your browser.

2. Reading the trace

After opening the trace in your browser (preferably Chrome), you should see something like this:

Example

HINT: Use the WASD keys to strafe and zoom

If your trace .html file isn't opening correctly, check your browser console for the following:

ObjectObserveError

Since Object.observe was deprecated in recent browsers, you may have to open the file from the Google Chrome Tracing tool. You can do so by:

  • Opening tab in chrome chrome://tracing
  • Selecting load
  • Selecting the html file generated from the previous command.

Enable VSync highlighting

Check this checkbox at the top right of the screen to highlight the 16ms frame boundaries:

Enable VSync Highlighting

You should see zebra stripes as in the screenshot above. If you don't, try profiling on a different device: Samsung has been known to have issues displaying vsyncs while the Nexus series is generally pretty reliable.

3. Find your process

Scroll until you see (part of) the name of your package. In this case, I was profiling com.facebook.adsmanager, which shows up as book.adsmanager because of silly thread name limits in the kernel.

On the left side, you'll see a set of threads which correspond to the timeline rows on the right. There are a few threads we care about for our purposes: the UI thread (which has your package name or the name UI Thread), mqt_js, and mqt_native_modules. If you're running on Android 5+, we also care about the Render Thread.

  • UI Thread. This is where standard android measure/layout/draw happens. The thread name on the right will be your package name (in my case book.adsmanager) or UI Thread. The events that you see on this thread should look something like this and have to do with Choreographer, traversals, and DispatchUI:

    UI Thread Example

  • JS Thread. This is where JavaScript is executed. The thread name will be either mqt_js or <...> depending on how cooperative the kernel on your device is being. To identify it if it doesn't have a name, look for things like JSCall, Bridge.executeJSCall, etc:

    JS Thread Example

  • Native Modules Thread. This is where native module calls (e.g. the UIManager) are executed. The thread name will be either mqt_native_modules or <...>. To identify it in the latter case, look for things like NativeCall, callJavaModuleMethod, and onBatchComplete:

    Native Modules Thread Example

  • Bonus: Render Thread. If you're using Android L (5.0) and up, you will also have a render thread in your application. This thread generates the actual OpenGL commands used to draw your UI. The thread name will be either RenderThread or <...>. To identify it in the latter case, look for things like DrawFrame and queueBuffer:

    Render Thread Example

Identifying a culprit

A smooth animation should look something like the following:

Smooth Animation

Each change in color is a frame -- remember that in order to display a frame, all our UI work needs to be done by the end of that 16ms period. Notice that no thread is working close to the frame boundary. An application rendering like this is rendering at 60 FPS.

If you noticed chop, however, you might see something like this:

Choppy Animation from JS

Notice that the JS thread is executing almost all the time, and across frame boundaries! This app is not rendering at 60 FPS. In this case, the problem lies in JS.

You might also see something like this:

Choppy Animation from UI

In this case, the UI and render threads are the ones that have work crossing frame boundaries. The UI that we're trying to render on each frame is requiring too much work to be done. In this case, the problem lies in the native views being rendered.

At this point, you'll have some very helpful information to inform your next steps.

Resolving JavaScript issues

If you identified a JS problem, look for clues in the specific JS that you're executing. In the scenario above, we see RCTEventEmitter being called multiple times per frame. Here's a zoom-in of the JS thread from the trace above:

Too much JS

This doesn't seem right. Why is it being called so often? Are they actually different events? The answers to these questions will probably depend on your product code. And many times, you'll want to look into shouldComponentUpdate.

Resolving native UI Issues

If you identified a native UI problem, there are usually two scenarios:

  1. the UI you're trying to draw each frame involves too much work on the GPU, or
  2. You're constructing new UI during the animation/interaction (e.g. loading in new content during a scroll).

Too much GPU work

In the first scenario, you'll see a trace that has the UI thread and/or Render Thread looking like this:

Overloaded GPU

Notice the long amount of time spent in DrawFrame that crosses frame boundaries. This is time spent waiting for the GPU to drain its command buffer from the previous frame.

To mitigate this, you should:

  • investigate using renderToHardwareTextureAndroid for complex, static content that is being animated/transformed (e.g. the Navigator slide/alpha animations)
  • make sure that you are not using needsOffscreenAlphaCompositing, which is disabled by default, as it greatly increases the per-frame load on the GPU in most cases.

If these don't help and you want to dig deeper into what the GPU is actually doing, you can check out Tracer for OpenGL ES.

Creating new views on the UI thread

In the second scenario, you'll see something more like this:

Creating Views

Notice that first the JS thread thinks for a bit, then you see some work done on the native modules thread, followed by an expensive traversal on the UI thread.

There isn't a quick way to mitigate this unless you're able to postpone creating new UI until after the interaction, or you are able to simplify the UI you're creating. The react native team is working on an infrastructure level solution for this that will allow new UI to be created and configured off the main thread, allowing the interaction to continue smoothly.

Edit this page
Last updated on
- + diff --git a/docs/0.62/progressbarandroid.html b/docs/0.62/progressbarandroid.html index 5f253dc2bb1..e07242a198f 100644 --- a/docs/0.62/progressbarandroid.html +++ b/docs/0.62/progressbarandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 ProgressBarAndroid

Deprecated. Use @react-native-community/progress-bar-android instead.

Android-only React component used to indicate that the app is loading or there is some activity in the app.

Example

Reference

Props

Inherits View Props.

animating

Whether to show the ProgressBar (true, the default) or hide it (false).

TypeRequired
boolNo

color

Color of the progress bar.

TypeRequired
colorNo

indeterminate

If the progress bar will show indeterminate progress. Note that this can only be false if styleAttr is Horizontal, and requires a progress value.

TypeRequired
indeterminateTypeNo

progress

The progress value (between 0 and 1).

TypeRequired
numberNo

styleAttr

Style of the ProgressBar. One of:

  • Horizontal
  • Normal (default)
  • Small
  • Large
  • Inverse
  • SmallInverse
  • LargeInverse
TypeRequired
enum('Horizontal', 'Normal', 'Small', 'Large', 'Inverse', 'SmallInverse', 'LargeInverse')No

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/progressbarandroid/index.html b/docs/0.62/progressbarandroid/index.html index 5f253dc2bb1..e07242a198f 100644 --- a/docs/0.62/progressbarandroid/index.html +++ b/docs/0.62/progressbarandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 ProgressBarAndroid

Deprecated. Use @react-native-community/progress-bar-android instead.

Android-only React component used to indicate that the app is loading or there is some activity in the app.

Example

Reference

Props

Inherits View Props.

animating

Whether to show the ProgressBar (true, the default) or hide it (false).

TypeRequired
boolNo

color

Color of the progress bar.

TypeRequired
colorNo

indeterminate

If the progress bar will show indeterminate progress. Note that this can only be false if styleAttr is Horizontal, and requires a progress value.

TypeRequired
indeterminateTypeNo

progress

The progress value (between 0 and 1).

TypeRequired
numberNo

styleAttr

Style of the ProgressBar. One of:

  • Horizontal
  • Normal (default)
  • Small
  • Large
  • Inverse
  • SmallInverse
  • LargeInverse
TypeRequired
enum('Horizontal', 'Normal', 'Small', 'Large', 'Inverse', 'SmallInverse', 'LargeInverse')No

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/progressviewios.html b/docs/0.62/progressviewios.html index a8482e830c9..19f0067d3e3 100644 --- a/docs/0.62/progressviewios.html +++ b/docs/0.62/progressviewios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 ProgressViewIOS

Deprecated. Use @react-native-community/progress-view instead.

Uses ProgressViewIOS to render a UIProgressView on iOS.

Example

Reference

Props

Inherits View Props.

progress

The progress value (between 0 and 1).

TypeRequired
numberNo

progressImage

A stretchable image to display as the progress bar.

TypeRequired
Image.propTypes.sourceNo

progressTintColor

The tint color of the progress bar itself.

TypeRequired
stringNo

progressViewStyle

The progress bar style.

TypeRequired
enum('default', 'bar')No

trackImage

A stretchable image to display behind the progress bar.

TypeRequired
Image.propTypes.sourceNo

trackTintColor

The tint color of the progress bar track.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/progressviewios/index.html b/docs/0.62/progressviewios/index.html index a8482e830c9..19f0067d3e3 100644 --- a/docs/0.62/progressviewios/index.html +++ b/docs/0.62/progressviewios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 ProgressViewIOS

Deprecated. Use @react-native-community/progress-view instead.

Uses ProgressViewIOS to render a UIProgressView on iOS.

Example

Reference

Props

Inherits View Props.

progress

The progress value (between 0 and 1).

TypeRequired
numberNo

progressImage

A stretchable image to display as the progress bar.

TypeRequired
Image.propTypes.sourceNo

progressTintColor

The tint color of the progress bar itself.

TypeRequired
stringNo

progressViewStyle

The progress bar style.

TypeRequired
enum('default', 'bar')No

trackImage

A stretchable image to display behind the progress bar.

TypeRequired
Image.propTypes.sourceNo

trackTintColor

The tint color of the progress bar track.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/props.html b/docs/0.62/props.html index fd77b28de40..07e9c114690 100644 --- a/docs/0.62/props.html +++ b/docs/0.62/props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Props

Most components can be customized when they are created, with different parameters. These created parameters are called props, short for properties.

For example, one basic React Native component is the Image. When you create an image, you can use a prop named source to control what image it shows.

Notice the braces surrounding {pic} - these embed the variable pic into JSX. You can put any JavaScript expression inside braces in JSX.

Your own components can also use props. This lets you make a single component that is used in many different places in your app, with slightly different properties in each place by referring to props in your render function. Here's an example:

Using name as a prop lets us customize the Greeting component, so we can reuse that component for each of our greetings. This example also uses the Greeting component in JSX, similar to the Core Components. The power to do this is what makes React so cool - if you find yourself wishing that you had a different set of UI primitives to work with, you can invent new ones.

The other new thing going on here is the View component. A View is useful as a container for other components, to help control style and layout.

With props and the basic Text, Image, and View components, you can build a wide variety of static screens. To learn how to make your app change over time, you need to learn about State.

Edit this page
Last updated on
- + diff --git a/docs/0.62/props/index.html b/docs/0.62/props/index.html index fd77b28de40..07e9c114690 100644 --- a/docs/0.62/props/index.html +++ b/docs/0.62/props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Props

Most components can be customized when they are created, with different parameters. These created parameters are called props, short for properties.

For example, one basic React Native component is the Image. When you create an image, you can use a prop named source to control what image it shows.

Notice the braces surrounding {pic} - these embed the variable pic into JSX. You can put any JavaScript expression inside braces in JSX.

Your own components can also use props. This lets you make a single component that is used in many different places in your app, with slightly different properties in each place by referring to props in your render function. Here's an example:

Using name as a prop lets us customize the Greeting component, so we can reuse that component for each of our greetings. This example also uses the Greeting component in JSX, similar to the Core Components. The power to do this is what makes React so cool - if you find yourself wishing that you had a different set of UI primitives to work with, you can invent new ones.

The other new thing going on here is the View component. A View is useful as a container for other components, to help control style and layout.

With props and the basic Text, Image, and View components, you can build a wide variety of static screens. To learn how to make your app change over time, you need to learn about State.

Edit this page
Last updated on
- + diff --git a/docs/0.62/publishing-forks.html b/docs/0.62/publishing-forks.html index 9be67978b14..328efff4d0e 100644 --- a/docs/0.62/publishing-forks.html +++ b/docs/0.62/publishing-forks.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Publish your own version of react native

TL;DR

There is a docker image that helps you build the required Android sources without installing any additional tooling (other than Docker, which can be committed to a git branch as a fully functional React Native fork release.

Run this from a fork of the React Native repo.

git checkout -d release/my-react-native-release
docker run --rm --name rn-build -v $PWD:/pwd -w /pwd reactnativecommunity/react-native-android /bin/sh -c "./gradlew installArchives"
git add android --force
git commit -a -m 'my react native forked release'
git push

Install it in your app project package.json.

"dependencies": {
...
"react-native": "myName/react-native#release/my-react-native-release"
}

Rationale

The recommended approach to working with React Native is to always update to the latest version. No support is provided on older versions and if you run into issues the contributors will always ask you to upgrade to the latest version before even looking at your particular issue. Sometimes, though, you are temporarily stuck on an older React Native version, but you require some changes from newer versions urgently (bugfixes) without having to do a full upgrade right now. This situation should be short lived by definition and once you have the time, the real solution is to upgrade to the latest version.

With this goal of a shortlived fork of React Native in mind, you can publish your own version of React Native. The facebook/react-native repository contains all the dependencies required to be used directly as a git dependency, except for the Android React Native library binary (.aar).

Building

This binary needs to become available in your project's node_modules/react-native/android folder or directly in your gradle dependency of your Android app. You can achieve this in one of two ways: Git dependency branch, Android binary dependency through Maven.

To build the .aar React Native library, you can follow the steps to build from source first to install all required tooling. Then to build the actual library, you can run the following in the root of your react-native checkout:

./gradlew :ReactAndroid:installArchives --no-daemon

If you don't want to install the required toolchain for building from source, you can use a prebuilt docker image to create a react native binary;

docker run --rm --name rn-build -v $PWD:/pwd -w /pwd reactnativecommunity/react-native-android /bin/sh -c "./gradlew installArchives"

If you haven't used the Android NDK before or if you have a NDK version not exactly matching the required version for building React Native, this is the recommended approach.

The resulting binary can be made available to app projects in one of the two ways described below.

Publishing to Maven/Nexus

Upload the binaries from the android folder to maven and point your Android app project gradle dependency for React Native to your Maven/Nexus dependency.

Publishing to a git fork dependency

Instead of uploading to Maven/Nexus, you can add the binaries built in the previous steps to git, by changing the .gitignore and committing the binaries to your forked branch. This allows you to make your fork into a functioning git dependency for React Native app projects.

If you have changes that you want to actually merge to React Native, make them on another branch first and open a PR. To start making your dependency branch, make sure you are on a 'release/my-forked-release' branch, then merge any commits that you need from yourself or others into this branch. This release branch should never be merged into any other branch.

# create .aar, then:
git add android --force
git commit -m 'my release commit'
git push

Now you can use this branch as a git dependency in your app project, by pointing your package.json dependency to this branch:

"dependencies": {
...
"react-native": "my-name/react-native#release/my-forked-release,
...
}

No other modifications to your dependencies should be necessary for your native changes to be included in your project.

Edit this page
Last updated on
- + diff --git a/docs/0.62/publishing-forks/index.html b/docs/0.62/publishing-forks/index.html index 9be67978b14..328efff4d0e 100644 --- a/docs/0.62/publishing-forks/index.html +++ b/docs/0.62/publishing-forks/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Publish your own version of react native

TL;DR

There is a docker image that helps you build the required Android sources without installing any additional tooling (other than Docker, which can be committed to a git branch as a fully functional React Native fork release.

Run this from a fork of the React Native repo.

git checkout -d release/my-react-native-release
docker run --rm --name rn-build -v $PWD:/pwd -w /pwd reactnativecommunity/react-native-android /bin/sh -c "./gradlew installArchives"
git add android --force
git commit -a -m 'my react native forked release'
git push

Install it in your app project package.json.

"dependencies": {
...
"react-native": "myName/react-native#release/my-react-native-release"
}

Rationale

The recommended approach to working with React Native is to always update to the latest version. No support is provided on older versions and if you run into issues the contributors will always ask you to upgrade to the latest version before even looking at your particular issue. Sometimes, though, you are temporarily stuck on an older React Native version, but you require some changes from newer versions urgently (bugfixes) without having to do a full upgrade right now. This situation should be short lived by definition and once you have the time, the real solution is to upgrade to the latest version.

With this goal of a shortlived fork of React Native in mind, you can publish your own version of React Native. The facebook/react-native repository contains all the dependencies required to be used directly as a git dependency, except for the Android React Native library binary (.aar).

Building

This binary needs to become available in your project's node_modules/react-native/android folder or directly in your gradle dependency of your Android app. You can achieve this in one of two ways: Git dependency branch, Android binary dependency through Maven.

To build the .aar React Native library, you can follow the steps to build from source first to install all required tooling. Then to build the actual library, you can run the following in the root of your react-native checkout:

./gradlew :ReactAndroid:installArchives --no-daemon

If you don't want to install the required toolchain for building from source, you can use a prebuilt docker image to create a react native binary;

docker run --rm --name rn-build -v $PWD:/pwd -w /pwd reactnativecommunity/react-native-android /bin/sh -c "./gradlew installArchives"

If you haven't used the Android NDK before or if you have a NDK version not exactly matching the required version for building React Native, this is the recommended approach.

The resulting binary can be made available to app projects in one of the two ways described below.

Publishing to Maven/Nexus

Upload the binaries from the android folder to maven and point your Android app project gradle dependency for React Native to your Maven/Nexus dependency.

Publishing to a git fork dependency

Instead of uploading to Maven/Nexus, you can add the binaries built in the previous steps to git, by changing the .gitignore and committing the binaries to your forked branch. This allows you to make your fork into a functioning git dependency for React Native app projects.

If you have changes that you want to actually merge to React Native, make them on another branch first and open a PR. To start making your dependency branch, make sure you are on a 'release/my-forked-release' branch, then merge any commits that you need from yourself or others into this branch. This release branch should never be merged into any other branch.

# create .aar, then:
git add android --force
git commit -m 'my release commit'
git push

Now you can use this branch as a git dependency in your app project, by pointing your package.json dependency to this branch:

"dependencies": {
...
"react-native": "my-name/react-native#release/my-forked-release,
...
}

No other modifications to your dependencies should be necessary for your native changes to be included in your project.

Edit this page
Last updated on
- + diff --git a/docs/0.62/publishing-to-app-store.html b/docs/0.62/publishing-to-app-store.html index 4b5dce0ad7a..23dfcbd159e 100644 --- a/docs/0.62/publishing-to-app-store.html +++ b/docs/0.62/publishing-to-app-store.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Publishing to Apple App Store

The publishing process is the same as any other native iOS app, with some additional considerations to take into account.

If you are using Expo then read the Expo Guide for Building Standalone Apps.

1. Enable App Transport Security

App Transport Security is a security feature introduced in iOS 9 that rejects all HTTP requests that are not sent over HTTPS. This can result in HTTP traffic being blocked, including the developer React Native server. ATS is disabled for localhost by default in React Native projects in order to make development easier.

You should re-enable ATS prior to building your app for production by removing the localhost entry from the NSExceptionDomains dictionary and setting NSAllowsArbitraryLoads to false in your Info.plist file in the ios/ folder. You can also re-enable ATS from within Xcode by opening your target properties under the Info pane and editing the App Transport Security Settings entry.

If your application needs to access HTTP resources on production, see this post to learn how to configure ATS on your project.

2. Configure release scheme

Building an app for distribution in the App Store requires using the Release scheme in Xcode. Apps built for Release will automatically disable the in-app Developer menu, which will prevent your users from inadvertently accessing the menu in production. It will also bundle the JavaScript locally, so you can put the app on a device and test whilst not connected to the computer.

To configure your app to be built using the Release scheme, go to Product → Scheme → Edit Scheme. Select the Run tab in the sidebar, then set the Build Configuration dropdown to Release.

Pro Tips

As your App Bundle grows in size, you may start to see a blank screen flash between your splash screen and the display of your root application view. If this is the case, you can add the following code to AppDelegate.m in order to keep your splash screen displayed during the transition.

// Place this code after "[self.window makeKeyAndVisible]" and before "return YES;"
UIStoryboard *sb = [UIStoryboard storyboardWithName:@"LaunchScreen" bundle:nil];
UIViewController *vc = [sb instantiateInitialViewController];
rootView.loadingView = vc.view;

The static bundle is built every time you target a physical device, even in Debug. If you want to save time, turn off bundle generation in Debug by adding the following to your shell script in the Xcode Build Phase Bundle React Native code and images:

if [ "${CONFIGURATION}" == "Debug" ]; then
export SKIP_BUNDLING=true
fi

3. Build app for release

You can now build your app for release by tapping ⌘B or selecting Product → Build from the menu bar. Once built for release, you'll be able to distribute the app to beta testers and submit the app to the App Store.

You can also use the React Native CLI to perform this operation using the option --configuration with the value Release (e.g. npx react-native run-ios --configuration Release).

Edit this page
Last updated on
- + diff --git a/docs/0.62/publishing-to-app-store/index.html b/docs/0.62/publishing-to-app-store/index.html index 4b5dce0ad7a..23dfcbd159e 100644 --- a/docs/0.62/publishing-to-app-store/index.html +++ b/docs/0.62/publishing-to-app-store/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Publishing to Apple App Store

The publishing process is the same as any other native iOS app, with some additional considerations to take into account.

If you are using Expo then read the Expo Guide for Building Standalone Apps.

1. Enable App Transport Security

App Transport Security is a security feature introduced in iOS 9 that rejects all HTTP requests that are not sent over HTTPS. This can result in HTTP traffic being blocked, including the developer React Native server. ATS is disabled for localhost by default in React Native projects in order to make development easier.

You should re-enable ATS prior to building your app for production by removing the localhost entry from the NSExceptionDomains dictionary and setting NSAllowsArbitraryLoads to false in your Info.plist file in the ios/ folder. You can also re-enable ATS from within Xcode by opening your target properties under the Info pane and editing the App Transport Security Settings entry.

If your application needs to access HTTP resources on production, see this post to learn how to configure ATS on your project.

2. Configure release scheme

Building an app for distribution in the App Store requires using the Release scheme in Xcode. Apps built for Release will automatically disable the in-app Developer menu, which will prevent your users from inadvertently accessing the menu in production. It will also bundle the JavaScript locally, so you can put the app on a device and test whilst not connected to the computer.

To configure your app to be built using the Release scheme, go to Product → Scheme → Edit Scheme. Select the Run tab in the sidebar, then set the Build Configuration dropdown to Release.

Pro Tips

As your App Bundle grows in size, you may start to see a blank screen flash between your splash screen and the display of your root application view. If this is the case, you can add the following code to AppDelegate.m in order to keep your splash screen displayed during the transition.

// Place this code after "[self.window makeKeyAndVisible]" and before "return YES;"
UIStoryboard *sb = [UIStoryboard storyboardWithName:@"LaunchScreen" bundle:nil];
UIViewController *vc = [sb instantiateInitialViewController];
rootView.loadingView = vc.view;

The static bundle is built every time you target a physical device, even in Debug. If you want to save time, turn off bundle generation in Debug by adding the following to your shell script in the Xcode Build Phase Bundle React Native code and images:

if [ "${CONFIGURATION}" == "Debug" ]; then
export SKIP_BUNDLING=true
fi

3. Build app for release

You can now build your app for release by tapping ⌘B or selecting Product → Build from the menu bar. Once built for release, you'll be able to distribute the app to beta testers and submit the app to the App Store.

You can also use the React Native CLI to perform this operation using the option --configuration with the value Release (e.g. npx react-native run-ios --configuration Release).

Edit this page
Last updated on
- + diff --git a/docs/0.62/pushnotificationios.html b/docs/0.62/pushnotificationios.html index b42877b9972..f173db44860 100644 --- a/docs/0.62/pushnotificationios.html +++ b/docs/0.62/pushnotificationios.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
//Called when a notification is delivered to a foreground app.
-(void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler
{
completionHandler(UNAuthorizationOptionSound | UNAuthorizationOptionAlert | UNAuthorizationOptionBadge);
}

Then enable Background Modes/Remote notifications to be able to use remote notifications properly. The easiest way to do this is via the project settings. Navigate to Targets -> Your App -> Capabilities -> Background Modes and check Remote notifications. This will automatically enable the required settings.

Reference

Methods

presentLocalNotification()

PushNotificationIOS.presentLocalNotification(details);

Schedules the localNotification for immediate presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

scheduleLocalNotification()

PushNotificationIOS.scheduleLocalNotification(details);

Schedules the localNotification for future presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

cancelAllLocalNotifications()

PushNotificationIOS.cancelAllLocalNotifications();

Cancels all scheduled localNotifications

removeAllDeliveredNotifications()

PushNotificationIOS.removeAllDeliveredNotifications();

Remove all delivered notifications from Notification Center

getDeliveredNotifications()

PushNotificationIOS.getDeliveredNotifications(callback);

Provides you with a list of the app’s notifications that are still displayed in Notification Center

Parameters:

NameTypeRequiredDescription
callbackfunctionYesFunction which receive an array of delivered notifications.

A delivered notification is an object containing:

removeDeliveredNotifications()

PushNotificationIOS.removeDeliveredNotifications(identifiers);

Removes the specified notifications from Notification Center

Parameters:

NameTypeRequiredDescription
identifiersarrayYesArray of notification identifiers.

setApplicationIconBadgeNumber()

PushNotificationIOS.setApplicationIconBadgeNumber(number);

Sets the badge number for the app icon on the home screen

Parameters:

NameTypeRequiredDescription
numbernumberYesBadge number for the app icon.

getApplicationIconBadgeNumber()

PushNotificationIOS.getApplicationIconBadgeNumber(callback);

Gets the current badge number for the app icon on the home screen

Parameters:

NameTypeRequiredDescription
callbackfunctionYesA function that will be passed the current badge number.

cancelLocalNotifications()

PushNotificationIOS.cancelLocalNotifications(userInfo);

Cancel local notifications.

Optionally restricts the set of canceled notifications to those notifications whose userInfo fields match the corresponding fields in the userInfo argument.

Parameters:

NameTypeRequiredDescription
userInfoobjectNo

getScheduledLocalNotifications()

PushNotificationIOS.getScheduledLocalNotifications(callback);

Gets the local notifications that are currently scheduled.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesA function that will be passed an array of objects describing local notifications.

addEventListener()

PushNotificationIOS.addEventListener(type, handler);

Attaches a listener to remote or local notification events while the app is running in the foreground or the background.

Parameters:

NameTypeRequiredDescription
typestringYesEvent type.
handlerfunctionYesListener.

Valid events are:

removeEventListener()

PushNotificationIOS.removeEventListener(type, handler);

Removes the event listener. Do this in componentWillUnmount to prevent memory leaks

Parameters:

NameTypeRequiredDescription
typestringYesEvent type.
handlerfunctionYesListener.

requestPermissions()

PushNotificationIOS.requestPermissions([permissions]);

Requests notification permissions from iOS, prompting the user's dialog box. By default, it will request all notification permissions, but a subset of these can be requested by passing a map of requested permissions. The following permissions are supported:

If a map is provided to the method, only the permissions with truthy values will be requested.

This method returns a promise that will resolve when the user accepts, rejects, or if the permissions were previously rejected. The promise resolves to the current state of the permission.

Parameters:

NameTypeRequiredDescription
permissionsarrayNoalert, badge, or sound

abandonPermissions()

PushNotificationIOS.abandonPermissions();

Unregister for all remote notifications received via Apple Push Notification service.

You should call this method in rare circumstances only, such as when a new version of the app removes support for all types of remote notifications. Users can temporarily prevent apps from receiving remote notifications through the Notifications section of the Settings app. Apps unregistered through this method can always re-register.

checkPermissions()

PushNotificationIOS.checkPermissions(callback);

See what push permissions are currently enabled.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesSee below.

callback will be invoked with a permissions object:

getInitialNotification()

PushNotificationIOS.getInitialNotification();

This method returns a promise. If the app was launched by a push notification, this promise resolves to an object of type PushNotificationIOS. Otherwise, it resolves to null.

constructor()

constructor(nativeNotif);

You will never need to instantiate PushNotificationIOS yourself. Listening to the notification event and invoking getInitialNotification is sufficient.

finish()

finish(fetchResult);

This method is available for remote notifications that have been received via: application:didReceiveRemoteNotification:fetchCompletionHandler: https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623013-application?language=objc

Call this to execute when the remote notification handling is complete. When calling this block, pass in the fetch result value that best describes the results of your operation. You must call this handler and should do so as soon as possible. For a list of possible values, see PushNotificationIOS.FetchResult.

If you do not call this method your background remote notifications could be throttled, to read more about it see the above documentation link.

getMessage()

getMessage();

An alias for getAlert to get the notification's main message string

getSound()

getSound();

Gets the sound string from the aps object

getCategory()

getCategory();

Gets the category string from the aps object

getAlert()

getAlert();

Gets the notification's main message from the aps object

getContentAvailable()

getContentAvailable();

Gets the content-available number from the aps object

getBadgeCount()

getBadgeCount();

Gets the badge count number from the aps object

getData()

getData();

Gets the data object on the notification

getThreadID()

getThreadID();

Gets the thread ID on the notification

Edit this page
Last updated on
- + diff --git a/docs/0.62/pushnotificationios/index.html b/docs/0.62/pushnotificationios/index.html index b42877b9972..f173db44860 100644 --- a/docs/0.62/pushnotificationios/index.html +++ b/docs/0.62/pushnotificationios/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
//Called when a notification is delivered to a foreground app.
-(void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler
{
completionHandler(UNAuthorizationOptionSound | UNAuthorizationOptionAlert | UNAuthorizationOptionBadge);
}

Then enable Background Modes/Remote notifications to be able to use remote notifications properly. The easiest way to do this is via the project settings. Navigate to Targets -> Your App -> Capabilities -> Background Modes and check Remote notifications. This will automatically enable the required settings.

Reference

Methods

presentLocalNotification()

PushNotificationIOS.presentLocalNotification(details);

Schedules the localNotification for immediate presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

scheduleLocalNotification()

PushNotificationIOS.scheduleLocalNotification(details);

Schedules the localNotification for future presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

cancelAllLocalNotifications()

PushNotificationIOS.cancelAllLocalNotifications();

Cancels all scheduled localNotifications

removeAllDeliveredNotifications()

PushNotificationIOS.removeAllDeliveredNotifications();

Remove all delivered notifications from Notification Center

getDeliveredNotifications()

PushNotificationIOS.getDeliveredNotifications(callback);

Provides you with a list of the app’s notifications that are still displayed in Notification Center

Parameters:

NameTypeRequiredDescription
callbackfunctionYesFunction which receive an array of delivered notifications.

A delivered notification is an object containing:

removeDeliveredNotifications()

PushNotificationIOS.removeDeliveredNotifications(identifiers);

Removes the specified notifications from Notification Center

Parameters:

NameTypeRequiredDescription
identifiersarrayYesArray of notification identifiers.

setApplicationIconBadgeNumber()

PushNotificationIOS.setApplicationIconBadgeNumber(number);

Sets the badge number for the app icon on the home screen

Parameters:

NameTypeRequiredDescription
numbernumberYesBadge number for the app icon.

getApplicationIconBadgeNumber()

PushNotificationIOS.getApplicationIconBadgeNumber(callback);

Gets the current badge number for the app icon on the home screen

Parameters:

NameTypeRequiredDescription
callbackfunctionYesA function that will be passed the current badge number.

cancelLocalNotifications()

PushNotificationIOS.cancelLocalNotifications(userInfo);

Cancel local notifications.

Optionally restricts the set of canceled notifications to those notifications whose userInfo fields match the corresponding fields in the userInfo argument.

Parameters:

NameTypeRequiredDescription
userInfoobjectNo

getScheduledLocalNotifications()

PushNotificationIOS.getScheduledLocalNotifications(callback);

Gets the local notifications that are currently scheduled.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesA function that will be passed an array of objects describing local notifications.

addEventListener()

PushNotificationIOS.addEventListener(type, handler);

Attaches a listener to remote or local notification events while the app is running in the foreground or the background.

Parameters:

NameTypeRequiredDescription
typestringYesEvent type.
handlerfunctionYesListener.

Valid events are:

removeEventListener()

PushNotificationIOS.removeEventListener(type, handler);

Removes the event listener. Do this in componentWillUnmount to prevent memory leaks

Parameters:

NameTypeRequiredDescription
typestringYesEvent type.
handlerfunctionYesListener.

requestPermissions()

PushNotificationIOS.requestPermissions([permissions]);

Requests notification permissions from iOS, prompting the user's dialog box. By default, it will request all notification permissions, but a subset of these can be requested by passing a map of requested permissions. The following permissions are supported:

If a map is provided to the method, only the permissions with truthy values will be requested.

This method returns a promise that will resolve when the user accepts, rejects, or if the permissions were previously rejected. The promise resolves to the current state of the permission.

Parameters:

NameTypeRequiredDescription
permissionsarrayNoalert, badge, or sound

abandonPermissions()

PushNotificationIOS.abandonPermissions();

Unregister for all remote notifications received via Apple Push Notification service.

You should call this method in rare circumstances only, such as when a new version of the app removes support for all types of remote notifications. Users can temporarily prevent apps from receiving remote notifications through the Notifications section of the Settings app. Apps unregistered through this method can always re-register.

checkPermissions()

PushNotificationIOS.checkPermissions(callback);

See what push permissions are currently enabled.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesSee below.

callback will be invoked with a permissions object:

getInitialNotification()

PushNotificationIOS.getInitialNotification();

This method returns a promise. If the app was launched by a push notification, this promise resolves to an object of type PushNotificationIOS. Otherwise, it resolves to null.

constructor()

constructor(nativeNotif);

You will never need to instantiate PushNotificationIOS yourself. Listening to the notification event and invoking getInitialNotification is sufficient.

finish()

finish(fetchResult);

This method is available for remote notifications that have been received via: application:didReceiveRemoteNotification:fetchCompletionHandler: https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623013-application?language=objc

Call this to execute when the remote notification handling is complete. When calling this block, pass in the fetch result value that best describes the results of your operation. You must call this handler and should do so as soon as possible. For a list of possible values, see PushNotificationIOS.FetchResult.

If you do not call this method your background remote notifications could be throttled, to read more about it see the above documentation link.

getMessage()

getMessage();

An alias for getAlert to get the notification's main message string

getSound()

getSound();

Gets the sound string from the aps object

getCategory()

getCategory();

Gets the category string from the aps object

getAlert()

getAlert();

Gets the notification's main message from the aps object

getContentAvailable()

getContentAvailable();

Gets the content-available number from the aps object

getBadgeCount()

getBadgeCount();

Gets the badge count number from the aps object

getData()

getData();

Gets the data object on the notification

getThreadID()

getThreadID();

Gets the thread ID on the notification

Edit this page
Last updated on
- + diff --git a/docs/0.62/ram-bundles-inline-requires.html b/docs/0.62/ram-bundles-inline-requires.html index 7f1ab49804b..61288ece5b0 100644 --- a/docs/0.62/ram-bundles-inline-requires.html +++ b/docs/0.62/ram-bundles-inline-requires.html @@ -19,7 +19,7 @@ - + @@ -45,7 +45,7 @@
module.exports = config;

The preloadedModules entry in the config indicates which modules should be marked as preloaded when building a RAM bundle. When the bundle is loaded, those modules are immediately loaded, before any requires have even executed. The blacklist entry indicates that those modules should not be required inline. Because they are preloaded, there is no performance benefit from using an inline require. In fact the javascript spends extra time resolving the inline require every time the imports are referenced.

Test and Measure Improvements

You should now be ready to build your app using the RAM format and inline requires. Make sure you measure the before and after startup times.

Edit this page
Last updated on
- + diff --git a/docs/0.62/ram-bundles-inline-requires/index.html b/docs/0.62/ram-bundles-inline-requires/index.html index 7f1ab49804b..61288ece5b0 100644 --- a/docs/0.62/ram-bundles-inline-requires/index.html +++ b/docs/0.62/ram-bundles-inline-requires/index.html @@ -19,7 +19,7 @@ - + @@ -45,7 +45,7 @@
module.exports = config;

The preloadedModules entry in the config indicates which modules should be marked as preloaded when building a RAM bundle. When the bundle is loaded, those modules are immediately loaded, before any requires have even executed. The blacklist entry indicates that those modules should not be required inline. Because they are preloaded, there is no performance benefit from using an inline require. In fact the javascript spends extra time resolving the inline require every time the imports are referenced.

Test and Measure Improvements

You should now be ready to build your app using the RAM format and inline requires. Make sure you measure the before and after startup times.

Edit this page
Last updated on
- + diff --git a/docs/0.62/react-node.html b/docs/0.62/react-node.html index d20873449fc..569c4a96f82 100644 --- a/docs/0.62/react-node.html +++ b/docs/0.62/react-node.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

React Node Object Type

A React Node is one of the following types:

  • Boolean (which is ignored)
  • null or undefined (which is ignored)
  • Number
  • String
  • A React element (result of JSX)
  • An array of any of the above, possibly a nested one
Edit this page
Last updated on
- + diff --git a/docs/0.62/react-node/index.html b/docs/0.62/react-node/index.html index d20873449fc..569c4a96f82 100644 --- a/docs/0.62/react-node/index.html +++ b/docs/0.62/react-node/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

React Node Object Type

A React Node is one of the following types:

  • Boolean (which is ignored)
  • null or undefined (which is ignored)
  • Number
  • String
  • A React element (result of JSX)
  • An array of any of the above, possibly a nested one
Edit this page
Last updated on
- + diff --git a/docs/0.62/refreshcontrol.html b/docs/0.62/refreshcontrol.html index 2f70b900f16..65c65b6374e 100644 --- a/docs/0.62/refreshcontrol.html +++ b/docs/0.62/refreshcontrol.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

RefreshControl

This component is used inside a ScrollView or ListView to add pull to refresh functionality. When the ScrollView is at scrollY: 0, swiping down triggers an onRefresh event.

Example

Note: refreshing is a controlled prop, this is why it needs to be set to true in the onRefresh function otherwise the refresh indicator will stop immediately.

Reference

Props

Inherits View Props.

refreshing

Whether the view should be indicating an active refresh.

TypeRequired
boolYes

onRefresh

Called when the view starts refreshing.

TypeRequired
functionNo

colors

The colors (at least one) that will be used to draw the refresh indicator.

TypeRequiredPlatform
array of colorNoAndroid

enabled

Whether the pull to refresh functionality is enabled.

TypeRequiredPlatform
boolNoAndroid

progressBackgroundColor

The background color of the refresh indicator.

TypeRequiredPlatform
colorNoAndroid

progressViewOffset

Progress view top offset

TypeRequiredPlatform
numberNoAndroid

size

Size of the refresh indicator, see RefreshControl.SIZE.

TypeRequiredPlatform
enum(RefreshLayoutConsts.SIZE.DEFAULT, RefreshLayoutConsts.SIZE.LARGE)NoAndroid

tintColor

The color of the refresh indicator.

TypeRequiredPlatform
colorNoiOS

title

The title displayed under the refresh indicator.

TypeRequiredPlatform
stringNoiOS

titleColor

Title color.

TypeRequiredPlatform
colorNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.62/refreshcontrol/index.html b/docs/0.62/refreshcontrol/index.html index 2f70b900f16..65c65b6374e 100644 --- a/docs/0.62/refreshcontrol/index.html +++ b/docs/0.62/refreshcontrol/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

RefreshControl

This component is used inside a ScrollView or ListView to add pull to refresh functionality. When the ScrollView is at scrollY: 0, swiping down triggers an onRefresh event.

Example

Note: refreshing is a controlled prop, this is why it needs to be set to true in the onRefresh function otherwise the refresh indicator will stop immediately.

Reference

Props

Inherits View Props.

refreshing

Whether the view should be indicating an active refresh.

TypeRequired
boolYes

onRefresh

Called when the view starts refreshing.

TypeRequired
functionNo

colors

The colors (at least one) that will be used to draw the refresh indicator.

TypeRequiredPlatform
array of colorNoAndroid

enabled

Whether the pull to refresh functionality is enabled.

TypeRequiredPlatform
boolNoAndroid

progressBackgroundColor

The background color of the refresh indicator.

TypeRequiredPlatform
colorNoAndroid

progressViewOffset

Progress view top offset

TypeRequiredPlatform
numberNoAndroid

size

Size of the refresh indicator, see RefreshControl.SIZE.

TypeRequiredPlatform
enum(RefreshLayoutConsts.SIZE.DEFAULT, RefreshLayoutConsts.SIZE.LARGE)NoAndroid

tintColor

The color of the refresh indicator.

TypeRequiredPlatform
colorNoiOS

title

The title displayed under the refresh indicator.

TypeRequiredPlatform
stringNoiOS

titleColor

Title color.

TypeRequiredPlatform
colorNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.62/removing-default-permissions.html b/docs/0.62/removing-default-permissions.html index e89463729c8..44331f446ee 100644 --- a/docs/0.62/removing-default-permissions.html +++ b/docs/0.62/removing-default-permissions.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Removing Default Permissions

By default, some permissions are added to your Android APK.

The default permissions that get added are:

  • android.permission.INTERNET - Required for debug mode.
  • android.permission.SYSTEM_ALERT_WINDOW - Required for debug mode.
  • android.permission.READ_PHONE_STATE - Not required for debug or production.
  • android.permission.WRITE_EXTERNAL_STORAGE - Not required for debug or production.
  • android.permission.READ_EXTERNAL_STORAGE - Not required for debug or production.

  1. Let's start by removing READ_PHONE_STATE, WRITE_EXTERNAL_STORAGE, and READ_EXTERNAL_STORAGE from both production and debug APKs, as it is not required in either. These storage permissions are still not needed if AsyncStorage module is in use, so it is safe to remove from both production and debug.

  2. Open your android/app/src/main/AndroidManifest.xml file.

  3. Even though these three permissions are not listed in the manifest they get added in. We add the three permissions with tools:node="remove" attribute, to make sure it gets removed during build. Note that the package identifier will be different, for below it is "com.myapp" because the project was created with npx react-native init myapp.

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.myappid"
    + xmlns:tools="http://schemas.android.com/tools"
    >
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
    + <uses-permission tools:node="remove" android:name="android.permission.READ_PHONE_STATE" />
    + <uses-permission tools:node="remove" android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    + <uses-permission tools:node="remove" android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <application
    android:name=".MainApplication"
    android:label="@string/app_name"
    android:icon="@mipmap/ic_launcher"
    android:allowBackup="false"
    android:theme="@style/AppTheme">
    <activity
    android:name=".MainActivity"
    android:label="@string/app_name"
    android:configChanges="keyboard|keyboardHidden|orientation|screenSize"
    android:windowSoftInputMode="adjustResize">
    <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    </activity>
    <activity android:name="com.facebook.react.devsupport.DevSettingsActivity" />
    </application>
    </manifest>

That's it. We did not remove the INTERNET permission as pretty much all apps use it. Now whenever you create a production APK, these 3 permissions will be removed. When you create a debug APK (npx react-native run-android) it will install the APK with these permissions added.

Hint

If your App is free to use in the App-Store and there is no "In-App-Purchase" possible in your App, you also can remove:

  • android.vending.CHECK_LICENSE
Edit this page
Last updated on
- + diff --git a/docs/0.62/removing-default-permissions/index.html b/docs/0.62/removing-default-permissions/index.html index e89463729c8..44331f446ee 100644 --- a/docs/0.62/removing-default-permissions/index.html +++ b/docs/0.62/removing-default-permissions/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Removing Default Permissions

By default, some permissions are added to your Android APK.

The default permissions that get added are:

  • android.permission.INTERNET - Required for debug mode.
  • android.permission.SYSTEM_ALERT_WINDOW - Required for debug mode.
  • android.permission.READ_PHONE_STATE - Not required for debug or production.
  • android.permission.WRITE_EXTERNAL_STORAGE - Not required for debug or production.
  • android.permission.READ_EXTERNAL_STORAGE - Not required for debug or production.

  1. Let's start by removing READ_PHONE_STATE, WRITE_EXTERNAL_STORAGE, and READ_EXTERNAL_STORAGE from both production and debug APKs, as it is not required in either. These storage permissions are still not needed if AsyncStorage module is in use, so it is safe to remove from both production and debug.

  2. Open your android/app/src/main/AndroidManifest.xml file.

  3. Even though these three permissions are not listed in the manifest they get added in. We add the three permissions with tools:node="remove" attribute, to make sure it gets removed during build. Note that the package identifier will be different, for below it is "com.myapp" because the project was created with npx react-native init myapp.

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.myappid"
    + xmlns:tools="http://schemas.android.com/tools"
    >
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
    + <uses-permission tools:node="remove" android:name="android.permission.READ_PHONE_STATE" />
    + <uses-permission tools:node="remove" android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    + <uses-permission tools:node="remove" android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <application
    android:name=".MainApplication"
    android:label="@string/app_name"
    android:icon="@mipmap/ic_launcher"
    android:allowBackup="false"
    android:theme="@style/AppTheme">
    <activity
    android:name=".MainActivity"
    android:label="@string/app_name"
    android:configChanges="keyboard|keyboardHidden|orientation|screenSize"
    android:windowSoftInputMode="adjustResize">
    <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    </activity>
    <activity android:name="com.facebook.react.devsupport.DevSettingsActivity" />
    </application>
    </manifest>

That's it. We did not remove the INTERNET permission as pretty much all apps use it. Now whenever you create a production APK, these 3 permissions will be removed. When you create a debug APK (npx react-native run-android) it will install the APK with these permissions added.

Hint

If your App is free to use in the App-Store and there is no "In-App-Purchase" possible in your App, you also can remove:

  • android.vending.CHECK_LICENSE
Edit this page
Last updated on
- + diff --git a/docs/0.62/running-on-device.html b/docs/0.62/running-on-device.html index cf04ff49607..33e6bf9fcc1 100644 --- a/docs/0.62/running-on-device.html +++ b/docs/0.62/running-on-device.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Running On Device

It's always a good idea to test your app on an actual device before releasing it to your users. This document will guide you through the necessary steps to run your React Native app on a device and to get it ready for production.

If you used Expo CLI or Create React Native App to set up your project, you can preview your app on a device by scanning the QR code with the Expo app—but in order to build and run your app on a device, you will need to eject and install the native code dependencies from the environment setup guide.

Running your app on Android devices

Development OS

1. Enable Debugging over USB

Most Android devices can only install and run apps downloaded from Google Play, by default. You will need to enable USB Debugging on your device in order to install your app during development.

To enable USB debugging on your device, you will first need to enable the "Developer options" menu by going to Settings → About phone → Software information and then tapping the Build number row at the bottom seven times. You can then go back to Settings → Developer options to enable "USB debugging".

2. Plug in your device via USB

Let's now set up an Android device to run our React Native projects. Go ahead and plug in your device via USB to your development machine.

Next, check the manufacturer code by using lsusb (on mac, you must first install lsusb). lsusb should output something like this:

$ lsusb
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 003: ID 22b8:2e76 Motorola PCS
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

These lines represent the USB devices currently connected to your machine.

You want the line that represents your phone. If you're in doubt, try unplugging your phone and running the command again:

$ lsusb
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

You'll see that after removing the phone, the line which has the phone model ("Motorola PCS" in this case) disappeared from the list. This is the line that we care about.

Bus 001 Device 003: ID 22b8:2e76 Motorola PCS

From the above line, you want to grab the first four digits from the device ID:

22b8:2e76

In this case, it's 22b8. That's the identifier for Motorola.

You'll need to input this into your udev rules in order to get up and running:

echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="22b8", MODE="0666", GROUP="plugdev"' | sudo tee /etc/udev/rules.d/51-android-usb.rules

Make sure that you replace 22b8 with the identifier you get in the above command.

Now check that your device is properly connecting to ADB, the Android Debug Bridge, by running adb devices.

$ adb devices
List of devices attached
emulator-5554 offline # Google emulator
14ed2fcc device # Physical device

Seeing device in the right column means the device is connected. You must have only one device connected at a time.

3. Run your app

Type the following in your command prompt to install and launch your app on the device:

$ npx react-native run-android

If you get a "bridge configuration isn't available" error, see Using adb reverse.

Hint: You can also use the React Native CLI to generate and run a Release build (e.g. npx react-native run-android --variant=release).

Connecting to the development server

You can also iterate quickly on a device by connecting to the development server running on your development machine. There are several ways of accomplishing this, depending on whether you have access to a USB cable or a Wi-Fi network.

Method 1: Using adb reverse (recommended)

You can use this method if your device is running Android 5.0 (Lollipop) or newer, it has USB debugging enabled, and it is connected via USB to your development machine.

Run the following in a command prompt:

$ adb -s <device name> reverse tcp:8081 tcp:8081

To find the device name, run the following adb command:

$ adb devices

You can now enable Live reloading from the Developer menu. Your app will reload whenever your JavaScript code has changed.

Method 2: Connect via Wi-Fi

You can also connect to the development server over Wi-Fi. You'll first need to install the app on your device using a USB cable, but once that has been done you can debug wirelessly by following these instructions. You'll need your development machine's current IP address before proceeding.

Open a terminal and type /sbin/ifconfig to find your machine's IP address.

  1. Make sure your laptop and your phone are on the same Wi-Fi network.
  2. Open your React Native app on your device.
  3. You'll see a red screen with an error. This is OK. The following steps will fix that.
  4. Open the in-app Developer menu.
  5. Go to Dev Settings → Debug server host & port for device.
  6. Type in your machine's IP address and the port of the local dev server (e.g. 10.0.1.1:8081).
  7. Go back to the Developer menu and select Reload JS.

You can now enable Live reloading from the Developer menu. Your app will reload whenever your JavaScript code has changed.

Building your app for production

You have built a great app using React Native, and you are now itching to release it in the Play Store. The process is the same as any other native Android app, with some additional considerations to take into account. Follow the guide for generating a signed APK to learn more.

Edit this page
Last updated on
- + diff --git a/docs/0.62/running-on-device/index.html b/docs/0.62/running-on-device/index.html index cf04ff49607..33e6bf9fcc1 100644 --- a/docs/0.62/running-on-device/index.html +++ b/docs/0.62/running-on-device/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Running On Device

It's always a good idea to test your app on an actual device before releasing it to your users. This document will guide you through the necessary steps to run your React Native app on a device and to get it ready for production.

If you used Expo CLI or Create React Native App to set up your project, you can preview your app on a device by scanning the QR code with the Expo app—but in order to build and run your app on a device, you will need to eject and install the native code dependencies from the environment setup guide.

Running your app on Android devices

Development OS

1. Enable Debugging over USB

Most Android devices can only install and run apps downloaded from Google Play, by default. You will need to enable USB Debugging on your device in order to install your app during development.

To enable USB debugging on your device, you will first need to enable the "Developer options" menu by going to Settings → About phone → Software information and then tapping the Build number row at the bottom seven times. You can then go back to Settings → Developer options to enable "USB debugging".

2. Plug in your device via USB

Let's now set up an Android device to run our React Native projects. Go ahead and plug in your device via USB to your development machine.

Next, check the manufacturer code by using lsusb (on mac, you must first install lsusb). lsusb should output something like this:

$ lsusb
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 003: ID 22b8:2e76 Motorola PCS
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

These lines represent the USB devices currently connected to your machine.

You want the line that represents your phone. If you're in doubt, try unplugging your phone and running the command again:

$ lsusb
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

You'll see that after removing the phone, the line which has the phone model ("Motorola PCS" in this case) disappeared from the list. This is the line that we care about.

Bus 001 Device 003: ID 22b8:2e76 Motorola PCS

From the above line, you want to grab the first four digits from the device ID:

22b8:2e76

In this case, it's 22b8. That's the identifier for Motorola.

You'll need to input this into your udev rules in order to get up and running:

echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="22b8", MODE="0666", GROUP="plugdev"' | sudo tee /etc/udev/rules.d/51-android-usb.rules

Make sure that you replace 22b8 with the identifier you get in the above command.

Now check that your device is properly connecting to ADB, the Android Debug Bridge, by running adb devices.

$ adb devices
List of devices attached
emulator-5554 offline # Google emulator
14ed2fcc device # Physical device

Seeing device in the right column means the device is connected. You must have only one device connected at a time.

3. Run your app

Type the following in your command prompt to install and launch your app on the device:

$ npx react-native run-android

If you get a "bridge configuration isn't available" error, see Using adb reverse.

Hint: You can also use the React Native CLI to generate and run a Release build (e.g. npx react-native run-android --variant=release).

Connecting to the development server

You can also iterate quickly on a device by connecting to the development server running on your development machine. There are several ways of accomplishing this, depending on whether you have access to a USB cable or a Wi-Fi network.

Method 1: Using adb reverse (recommended)

You can use this method if your device is running Android 5.0 (Lollipop) or newer, it has USB debugging enabled, and it is connected via USB to your development machine.

Run the following in a command prompt:

$ adb -s <device name> reverse tcp:8081 tcp:8081

To find the device name, run the following adb command:

$ adb devices

You can now enable Live reloading from the Developer menu. Your app will reload whenever your JavaScript code has changed.

Method 2: Connect via Wi-Fi

You can also connect to the development server over Wi-Fi. You'll first need to install the app on your device using a USB cable, but once that has been done you can debug wirelessly by following these instructions. You'll need your development machine's current IP address before proceeding.

Open a terminal and type /sbin/ifconfig to find your machine's IP address.

  1. Make sure your laptop and your phone are on the same Wi-Fi network.
  2. Open your React Native app on your device.
  3. You'll see a red screen with an error. This is OK. The following steps will fix that.
  4. Open the in-app Developer menu.
  5. Go to Dev Settings → Debug server host & port for device.
  6. Type in your machine's IP address and the port of the local dev server (e.g. 10.0.1.1:8081).
  7. Go back to the Developer menu and select Reload JS.

You can now enable Live reloading from the Developer menu. Your app will reload whenever your JavaScript code has changed.

Building your app for production

You have built a great app using React Native, and you are now itching to release it in the Play Store. The process is the same as any other native Android app, with some additional considerations to take into account. Follow the guide for generating a signed APK to learn more.

Edit this page
Last updated on
- + diff --git a/docs/0.62/running-on-simulator-ios.html b/docs/0.62/running-on-simulator-ios.html index aec23c3d433..81da316b139 100644 --- a/docs/0.62/running-on-simulator-ios.html +++ b/docs/0.62/running-on-simulator-ios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Running On Simulator

Starting the simulator

Once you have your React Native project initialized, you can run npx react-native run-ios inside the newly created project directory. If everything is set up correctly, you should see your new app running in the iOS Simulator shortly.

Specifying a device

You can specify the device the simulator should run with the --simulator flag, followed by the device name as a string. The default is "iPhone X". If you wish to run your app on an iPhone 5s, run npx react-native run-ios --simulator="iPhone 5s".

The device names correspond to the list of devices available in Xcode. You can check your available devices by running xcrun simctl list devices from the console.

Edit this page
Last updated on
- + diff --git a/docs/0.62/running-on-simulator-ios/index.html b/docs/0.62/running-on-simulator-ios/index.html index aec23c3d433..81da316b139 100644 --- a/docs/0.62/running-on-simulator-ios/index.html +++ b/docs/0.62/running-on-simulator-ios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Running On Simulator

Starting the simulator

Once you have your React Native project initialized, you can run npx react-native run-ios inside the newly created project directory. If everything is set up correctly, you should see your new app running in the iOS Simulator shortly.

Specifying a device

You can specify the device the simulator should run with the --simulator flag, followed by the device name as a string. The default is "iPhone X". If you wish to run your app on an iPhone 5s, run npx react-native run-ios --simulator="iPhone 5s".

The device names correspond to the list of devices available in Xcode. You can check your available devices by running xcrun simctl list devices from the console.

Edit this page
Last updated on
- + diff --git a/docs/0.62/safeareaview.html b/docs/0.62/safeareaview.html index f5f29cbabd3..d20cc93da6a 100644 --- a/docs/0.62/safeareaview.html +++ b/docs/0.62/safeareaview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

SafeAreaView

The purpose of SafeAreaView is to render content within the safe area boundaries of a device. It is currently only applicable to iOS devices with iOS version 11 or later.

SafeAreaView renders nested content and automatically applies padding to reflect the portion of the view that is not covered by navigation bars, tab bars, toolbars, and other ancestor views. Moreover, and most importantly, Safe Area's paddings reflect the physical limitation of the screen, such as rounded corners or camera notches (i.e. the sensor housing area on iPhone X).

Example

To use, wrap your top level view with a SafeAreaView with a flex: 1 style applied to it. You may also want to use a background color that matches your application's design.

Reference

Props

Inherits View Props.

emulateUnlessSupported

TypeRequiredDefault
boolNotrue
Edit this page
Last updated on
- + diff --git a/docs/0.62/safeareaview/index.html b/docs/0.62/safeareaview/index.html index f5f29cbabd3..d20cc93da6a 100644 --- a/docs/0.62/safeareaview/index.html +++ b/docs/0.62/safeareaview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

SafeAreaView

The purpose of SafeAreaView is to render content within the safe area boundaries of a device. It is currently only applicable to iOS devices with iOS version 11 or later.

SafeAreaView renders nested content and automatically applies padding to reflect the portion of the view that is not covered by navigation bars, tab bars, toolbars, and other ancestor views. Moreover, and most importantly, Safe Area's paddings reflect the physical limitation of the screen, such as rounded corners or camera notches (i.e. the sensor housing area on iPhone X).

Example

To use, wrap your top level view with a SafeAreaView with a flex: 1 style applied to it. You may also want to use a background color that matches your application's design.

Reference

Props

Inherits View Props.

emulateUnlessSupported

TypeRequiredDefault
boolNotrue
Edit this page
Last updated on
- + diff --git a/docs/0.62/scrollview.html b/docs/0.62/scrollview.html index 5a1193a6786..57976592770 100644 --- a/docs/0.62/scrollview.html +++ b/docs/0.62/scrollview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

ScrollView

Component that wraps platform ScrollView while providing integration with touch locking "responder" system.

Keep in mind that ScrollViews must have a bounded height in order to work, since they contain unbounded-height children into a bounded container (via a scroll interaction). In order to bound the height of a ScrollView, either set the height of the view directly (discouraged) or make sure all parent views have bounded height. Forgetting to transfer {flex: 1} down the view stack can lead to errors here, which the element inspector makes quick to debug.

Doesn't yet support other contained responders from blocking this scroll view from becoming the responder.

<ScrollView> vs <FlatList> - which one to use?

ScrollView renders all its react child components at once, but this has a performance downside.

Imagine you have a very long list of items you want to display, maybe several screens worth of content. Creating JS components and native views for everything all at once, much of which may not even be shown, will contribute to slow rendering and increased memory usage.

This is where FlatList comes into play. FlatList renders items lazily, when they are about to appear, and removes items that scroll way off screen to save memory and processing time.

FlatList is also handy if you want to render separators between your items, multiple columns, infinite scroll loading, or any number of other features it supports out of the box.

Example

Reference

Props

Inherits View Props.

alwaysBounceHorizontal

When true, the scroll view bounces horizontally when it reaches the end even if the content is smaller than the scroll view itself. The default value is true when horizontal={true} and false otherwise.

TypeRequiredPlatform
boolNoiOS

alwaysBounceVertical

When true, the scroll view bounces vertically when it reaches the end even if the content is smaller than the scroll view itself. The default value is false when horizontal={true} and true otherwise.

TypeRequiredPlatform
boolNoiOS

automaticallyAdjustContentInsets

Controls whether iOS should automatically adjust the content inset for scroll views that are placed behind a navigation bar or tab bar/ toolbar. The default value is true.

TypeRequiredPlatform
boolNoiOS

bounces

When true, the scroll view bounces when it reaches the end of the content if the content is larger then the scroll view along the axis of the scroll direction. When false, it disables all bouncing even if the alwaysBounce* props are true. The default value is true.

TypeRequiredPlatform
boolNoiOS

bouncesZoom

When true, gestures can drive zoom past min/max and the zoom will animate to the min/max value at gesture end, otherwise the zoom will not exceed the limits.

TypeRequiredPlatform
boolNoiOS

canCancelContentTouches

When false, once tracking starts, won't try to drag if the touch moves. The default value is true.

TypeRequiredPlatform
boolNoiOS

centerContent

When true, the scroll view automatically centers the content when the content is smaller than the scroll view bounds; when the content is larger than the scroll view, this property has no effect. The default value is false.

TypeRequiredPlatform
boolNoiOS

contentContainerStyle

These styles will be applied to the scroll view content container which wraps all of the child views. Example:

return (
<ScrollView contentContainerStyle={styles.contentContainer}>
</ScrollView>
);
...
const styles = StyleSheet.create({
contentContainer: {
paddingVertical: 20
}
});
TypeRequired
StyleSheetPropType(View Style props)No

contentInset

The amount by which the scroll view content is inset from the edges of the scroll view. Defaults to {top: 0, left: 0, bottom: 0, right: 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

contentInsetAdjustmentBehavior

This property specifies how the safe area insets are used to modify the content area of the scroll view. The default value of this property is "never". Available on iOS 11 and later.

TypeRequiredPlatform
enum('automatic', 'scrollableAxes', 'never', 'always')NoiOS

contentOffset

Used to manually set the starting scroll offset. The default value is {x: 0, y: 0}.

TypeRequiredPlatform
PointPropTypeNoiOS

decelerationRate

A floating-point number that determines how quickly the scroll view decelerates after the user lifts their finger. You may also use string shortcuts "normal" and "fast" which match the underlying iOS settings for UIScrollViewDecelerationRateNormal and UIScrollViewDecelerationRateFast respectively.

  • 'normal' (the default), 0.998 on iOS, 0.985 on Android.
  • 'fast', 0.99 on iOS, 0.9 on Android.
TypeRequired
enum('fast', 'normal'), ,numberNo

directionalLockEnabled

When true, the ScrollView will try to lock to only vertical or horizontal scrolling while dragging. The default value is false.

TypeRequiredPlatform
boolNoiOS

disableIntervalMomentum

When true, the scroll view stops on the next index (in relation to scroll position at release) regardless of how fast the gesture is. This can be used for horizontal pagination when the page is less than the width of the ScrollView. The default value is false.

TypeRequired
boolNo

disableScrollViewPanResponder

When true, the default JS pan responder on the ScrollView is disabled, and full control over touches inside the ScrollView is left to its child components. This is particularly useful if snapToInterval is enabled, since it does not follow typical touch patterns. Do not use this on regular ScrollView use cases without snapToInterval as it may cause unexpected touches to occur while scrolling. The default value is false.

TypeRequired
boolNo

endFillColor

Sometimes a scrollview takes up more space than its content fills. When this is the case, this prop will fill the rest of the scrollview with a color to avoid setting a background and creating unnecessary overdraw. This is an advanced optimization that is not needed in the general case.

TypeRequiredPlatform
colorNoAndroid

fadingEdgeLength

Fades out the edges of the the scroll content.

If the value is greater than 0, the fading edges will be set accordingly to the current scroll direction and position, indicating if there is more content to show.

TypeRequiredDefaultPlatform
numberNo0Android

horizontal

When true, the scroll view's children are arranged horizontally in a row instead of vertically in a column. The default value is false.

TypeRequired
boolNo

indicatorStyle

The style of the scroll indicators.

  • 'default' (the default), same as black.
  • 'black', scroll indicator is black. This style is good against a light background.
  • 'white', scroll indicator is white. This style is good against a dark background.
TypeRequiredPlatform
enum('default', 'black', 'white')NoiOS

invertStickyHeaders

If sticky headers should stick at the bottom instead of the top of the ScrollView. This is usually used with inverted ScrollViews.

TypeRequired
boolNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

Cross platform

  • 'none' (the default), drags do not dismiss the keyboard.
  • 'on-drag', the keyboard is dismissed when a drag begins.

iOS Only

  • 'interactive', the keyboard is dismissed interactively with the drag and moves in synchrony with the touch; dragging upwards cancels the dismissal. On android this is not supported and it will have the same behavior as 'none'.
TypeRequired
enum('none', 'on-drag', 'interactive')No

keyboardShouldPersistTaps

Determines when the keyboard should stay visible after a tap.

  • 'never' (the default), tapping outside of the focused text input when the keyboard is up dismisses the keyboard. When this happens, children won't receive the tap.
  • 'always', the keyboard will not dismiss automatically, and the scroll view will not catch taps, but children of the scroll view can catch taps.
  • 'handled', the keyboard will not dismiss automatically when the tap was handled by children of the scroll view (or captured by an ancestor).
  • false, deprecated, use 'never' instead
  • true, deprecated, use 'always' instead
TypeRequired
enum('always', 'never', 'handled', false, true)No

maintainVisibleContentPosition

When set, the scroll view will adjust the scroll position so that the first child that is currently visible and at or beyond minIndexForVisible will not change position. This is useful for lists that are loading content in both directions, e.g. a chat thread, where new messages coming in might otherwise cause the scroll position to jump. A value of 0 is common, but other values such as 1 can be used to skip loading spinners or other content that should not maintain position.

The optional autoscrollToTopThreshold can be used to make the content automatically scroll to the top after making the adjustment if the user was within the threshold of the top before the adjustment was made. This is also useful for chat-like applications where you want to see new messages scroll into place, but not if the user has scrolled up a ways and it would be disruptive to scroll a bunch.

Caveat 1: Reordering elements in the scrollview with this enabled will probably cause jumpiness and jank. It can be fixed, but there are currently no plans to do so. For now, don't re-order the content of any ScrollViews or Lists that use this feature.

Caveat 2: This uses contentOffset and frame.origin in native code to compute visibility. Occlusion, transforms, and other complexity won't be taken into account as to whether content is "visible" or not.

TypeRequiredPlatform
object: { minIndexForVisible: number, autoscrollToTopThreshold: number }NoiOS

maximumZoomScale

The maximum allowed zoom scale. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

minimumZoomScale

The minimum allowed zoom scale. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

nestedScrollEnabled

Enables nested scrolling for Android API level 21+. Nested scrolling is supported by default on iOS.

TypeRequiredPlatform
boolNoAndroid

onContentSizeChange

Called when scrollable content view of the ScrollView changes.

Handler function is passed the content width and content height as parameters: (contentWidth, contentHeight)

It's implemented using onLayout handler attached to the content container which this ScrollView renders.

TypeRequired
functionNo

onMomentumScrollBegin

Called when the momentum scroll starts (scroll which occurs as the ScrollView starts gliding).

TypeRequired
functionNo

onMomentumScrollEnd

Called when the momentum scroll ends (scroll which occurs as the ScrollView glides to a stop).

TypeRequired
functionNo

onScroll

Fires at most once per frame during scrolling. The frequency of the events can be controlled using the scrollEventThrottle prop. The event has the following shape (all values are numbers):

{
nativeEvent: {
contentInset: {bottom, left, right, top},
contentOffset: {x, y},
contentSize: {height, width},
layoutMeasurement: {height, width},
zoomScale
}
}
TypeRequired
functionNo

onScrollBeginDrag

Called when the user begins to drag the scroll view.

TypeRequired
functionNo

onScrollEndDrag

Called when the user stops dragging the scroll view and it either stops or begins to glide.

TypeRequired
functionNo

onScrollToTop

Fires when the scroll view scrolls to top after the status bar has been tapped.

TypeRequiredPlatform
functionNoiOS

overScrollMode

Used to override default value of overScroll mode.

Possible values:

  • 'auto' - Default value, allow a user to over-scroll this view only if the content is large enough to meaningfully scroll.
  • 'always' - Always allow a user to over-scroll this view.
  • 'never' - Never allow a user to over-scroll this view.
TypeRequiredPlatform
enum('auto', 'always', 'never')NoAndroid

pagingEnabled

When true, the scroll view stops on multiples of the scroll view's size when scrolling. This can be used for horizontal pagination. The default value is false.

Note: Vertical pagination is not supported on Android.

TypeRequired
boolNo

persistentScrollbar

Causes the scrollbars not to turn transparent when they are not in use. The default value is false.

TypeRequiredPlatform
boolNoAndroid

pinchGestureEnabled

When true, ScrollView allows use of pinch gestures to zoom in and out. The default value is true.

TypeRequiredPlatform
boolNoiOS

refreshControl

A RefreshControl component, used to provide pull-to-refresh functionality for the ScrollView. Only works for vertical ScrollViews (horizontal prop must be false).

See RefreshControl.

TypeRequired
elementNo

removeClippedSubviews

Experimental: When true, offscreen child views (whose overflow value is hidden) are removed from their native backing superview when offscreen. This can improve scrolling performance on long lists.

TypeRequired
boolNo

scrollBarThumbImage

Optionally an image can be used for the scroll bar thumb. This will override the color. While the image is loading or the image fails to load the color will be used instead. Use an alpha of 0 in the color to avoid seeing it while the image is loading.

  • uri, a string representing the resource identifier for the image, which should be either a local file path or the name of a static image resource.
  • number, opaque type returned by something like import IMAGE from './image.jpg'.
TypeRequiredPlatform
numberNoVR

scrollEnabled

When false, the view cannot be scrolled via touch interaction. The default value is true.

Note that the view can always be scrolled by calling scrollTo.

TypeRequired
boolNo

scrollEventThrottle

This controls how often the scroll event will be fired while scrolling (as a time interval in ms). A lower number yields better accuracy for code that is tracking the scroll position, but can lead to scroll performance problems due to the volume of information being sent over the bridge. You will not notice a difference between values set between 1-16 as the JS run loop is synced to the screen refresh rate. If you do not need precise scroll position tracking, set this value higher to limit the information being sent across the bridge. The default value is zero, which results in the scroll event being sent only once each time the view is scrolled.

TypeRequiredPlatform
numberNoiOS

scrollIndicatorInsets

The amount by which the scroll view indicators are inset from the edges of the scroll view. This should normally be set to the same value as the contentInset. Defaults to {0, 0, 0, 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

scrollPerfTag

Tag used to log scroll performance on this scroll view. Will force momentum events to be turned on (see sendMomentumEvents). This doesn't do anything out of the box and you need to implement a custom native FpsListener for it to be useful.

TypeRequiredPlatform
stringNoAndroid

scrollToOverflowEnabled

When true, the scroll view can be programmatically scrolled beyond its content size. The default value is false.

TypeRequiredPlatform
boolNoiOS

scrollsToTop

When true, the scroll view scrolls to top when the status bar is tapped. The default value is true.

TypeRequiredPlatform
boolNoiOS

DEPRECATED_sendUpdatedChildFrames

When true, ScrollView will emit updateChildFrames data in scroll events, otherwise will not compute or emit child frame data. This only exists to support legacy issues, onLayout should be used instead to retrieve frame data. The default value is false.

TypeRequiredPlatform
boolNoiOS

showsHorizontalScrollIndicator

When true, shows a horizontal scroll indicator. The default value is true.

TypeRequired
boolNo

showsVerticalScrollIndicator

When true, shows a vertical scroll indicator. The default value is true.

TypeRequired
boolNo

snapToAlignment

When snapToInterval is set, snapToAlignment will define the relationship of the snapping to the scroll view.

  • 'start' (the default) will align the snap at the left (horizontal) or top (vertical).
  • 'center' will align the snap in the center.
  • 'end' will align the snap at the right (horizontal) or bottom (vertical).
TypeRequiredPlatform
enum('start', 'center', 'end')NoiOS

snapToEnd

Use in conjunction with snapToOffsets. By default, the end of the list counts as a snap offset. Set snapToEnd to false to disable this behavior and allow the list to scroll freely between its end and the last snapToOffsets offset. The default value is true.

TypeRequired
booleanNo

snapToInterval

When set, causes the scroll view to stop at multiples of the value of snapToInterval. This can be used for paginating through children that have lengths smaller than the scroll view. Typically used in combination with snapToAlignment and decelerationRate="fast". Overrides less configurable pagingEnabled prop.

TypeRequired
numberNo

snapToOffsets

When set, causes the scroll view to stop at the defined offsets. This can be used for paginating through variously sized children that have lengths smaller than the scroll view. Typically used in combination with decelerationRate="fast". Overrides less configurable pagingEnabled and snapToInterval props.

TypeRequired
array of numberNo

snapToStart

Use in conjunction with snapToOffsets. By default, the beginning of the list counts as a snap offset. Set snapToStart to false to disable this behavior and allow the list to scroll freely between its start and the first snapToOffsets offset. The default value is true.

TypeRequired
booleanNo

stickyHeaderIndices

An array of child indices determining which children get docked to the top of the screen when scrolling. For example, passing stickyHeaderIndices={[0]} will cause the first child to be fixed to the top of the scroll view. This property is not supported in conjunction with horizontal={true}.

TypeRequired
array of numberNo

zoomScale

The current scale of the scroll view content. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

Methods

flashScrollIndicators()

flashScrollIndicators();

Displays the scroll indicators momentarily.

scrollTo()

scrollTo(
options?: {x?: number, y?: number, animated?: boolean} | number,
deprecatedX?: number,
deprecatedAnimated?: boolean,
);

Scrolls to a given x, y offset, either immediately, with a smooth animation.

Example:

scrollTo({x: 0, y: 0, animated: true})

Note: The weird function signature is due to the fact that, for historical reasons, the function also accepts separate arguments as an alternative to the options object. This is deprecated due to ambiguity (y before x), and SHOULD NOT BE USED.

scrollToEnd()

scrollToEnd(([options]: { animated: boolean, duration: number }));

If this is a vertical ScrollView scrolls to the bottom. If this is a horizontal ScrollView scrolls to the right.

Use scrollToEnd({animated: true}) for smooth animated scrolling, scrollToEnd({animated: false}) for immediate scrolling. For Android, you may specify a duration, e.g. scrollToEnd({duration: 500}) for a controlled duration scroll. If no options are passed, animated defaults to true.

scrollWithoutAnimationTo()

scrollWithoutAnimationTo(y, x);

Deprecated, use scrollTo instead.

Edit this page
Last updated on
- + diff --git a/docs/0.62/scrollview/index.html b/docs/0.62/scrollview/index.html index 5a1193a6786..57976592770 100644 --- a/docs/0.62/scrollview/index.html +++ b/docs/0.62/scrollview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

ScrollView

Component that wraps platform ScrollView while providing integration with touch locking "responder" system.

Keep in mind that ScrollViews must have a bounded height in order to work, since they contain unbounded-height children into a bounded container (via a scroll interaction). In order to bound the height of a ScrollView, either set the height of the view directly (discouraged) or make sure all parent views have bounded height. Forgetting to transfer {flex: 1} down the view stack can lead to errors here, which the element inspector makes quick to debug.

Doesn't yet support other contained responders from blocking this scroll view from becoming the responder.

<ScrollView> vs <FlatList> - which one to use?

ScrollView renders all its react child components at once, but this has a performance downside.

Imagine you have a very long list of items you want to display, maybe several screens worth of content. Creating JS components and native views for everything all at once, much of which may not even be shown, will contribute to slow rendering and increased memory usage.

This is where FlatList comes into play. FlatList renders items lazily, when they are about to appear, and removes items that scroll way off screen to save memory and processing time.

FlatList is also handy if you want to render separators between your items, multiple columns, infinite scroll loading, or any number of other features it supports out of the box.

Example

Reference

Props

Inherits View Props.

alwaysBounceHorizontal

When true, the scroll view bounces horizontally when it reaches the end even if the content is smaller than the scroll view itself. The default value is true when horizontal={true} and false otherwise.

TypeRequiredPlatform
boolNoiOS

alwaysBounceVertical

When true, the scroll view bounces vertically when it reaches the end even if the content is smaller than the scroll view itself. The default value is false when horizontal={true} and true otherwise.

TypeRequiredPlatform
boolNoiOS

automaticallyAdjustContentInsets

Controls whether iOS should automatically adjust the content inset for scroll views that are placed behind a navigation bar or tab bar/ toolbar. The default value is true.

TypeRequiredPlatform
boolNoiOS

bounces

When true, the scroll view bounces when it reaches the end of the content if the content is larger then the scroll view along the axis of the scroll direction. When false, it disables all bouncing even if the alwaysBounce* props are true. The default value is true.

TypeRequiredPlatform
boolNoiOS

bouncesZoom

When true, gestures can drive zoom past min/max and the zoom will animate to the min/max value at gesture end, otherwise the zoom will not exceed the limits.

TypeRequiredPlatform
boolNoiOS

canCancelContentTouches

When false, once tracking starts, won't try to drag if the touch moves. The default value is true.

TypeRequiredPlatform
boolNoiOS

centerContent

When true, the scroll view automatically centers the content when the content is smaller than the scroll view bounds; when the content is larger than the scroll view, this property has no effect. The default value is false.

TypeRequiredPlatform
boolNoiOS

contentContainerStyle

These styles will be applied to the scroll view content container which wraps all of the child views. Example:

return (
<ScrollView contentContainerStyle={styles.contentContainer}>
</ScrollView>
);
...
const styles = StyleSheet.create({
contentContainer: {
paddingVertical: 20
}
});
TypeRequired
StyleSheetPropType(View Style props)No

contentInset

The amount by which the scroll view content is inset from the edges of the scroll view. Defaults to {top: 0, left: 0, bottom: 0, right: 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

contentInsetAdjustmentBehavior

This property specifies how the safe area insets are used to modify the content area of the scroll view. The default value of this property is "never". Available on iOS 11 and later.

TypeRequiredPlatform
enum('automatic', 'scrollableAxes', 'never', 'always')NoiOS

contentOffset

Used to manually set the starting scroll offset. The default value is {x: 0, y: 0}.

TypeRequiredPlatform
PointPropTypeNoiOS

decelerationRate

A floating-point number that determines how quickly the scroll view decelerates after the user lifts their finger. You may also use string shortcuts "normal" and "fast" which match the underlying iOS settings for UIScrollViewDecelerationRateNormal and UIScrollViewDecelerationRateFast respectively.

  • 'normal' (the default), 0.998 on iOS, 0.985 on Android.
  • 'fast', 0.99 on iOS, 0.9 on Android.
TypeRequired
enum('fast', 'normal'), ,numberNo

directionalLockEnabled

When true, the ScrollView will try to lock to only vertical or horizontal scrolling while dragging. The default value is false.

TypeRequiredPlatform
boolNoiOS

disableIntervalMomentum

When true, the scroll view stops on the next index (in relation to scroll position at release) regardless of how fast the gesture is. This can be used for horizontal pagination when the page is less than the width of the ScrollView. The default value is false.

TypeRequired
boolNo

disableScrollViewPanResponder

When true, the default JS pan responder on the ScrollView is disabled, and full control over touches inside the ScrollView is left to its child components. This is particularly useful if snapToInterval is enabled, since it does not follow typical touch patterns. Do not use this on regular ScrollView use cases without snapToInterval as it may cause unexpected touches to occur while scrolling. The default value is false.

TypeRequired
boolNo

endFillColor

Sometimes a scrollview takes up more space than its content fills. When this is the case, this prop will fill the rest of the scrollview with a color to avoid setting a background and creating unnecessary overdraw. This is an advanced optimization that is not needed in the general case.

TypeRequiredPlatform
colorNoAndroid

fadingEdgeLength

Fades out the edges of the the scroll content.

If the value is greater than 0, the fading edges will be set accordingly to the current scroll direction and position, indicating if there is more content to show.

TypeRequiredDefaultPlatform
numberNo0Android

horizontal

When true, the scroll view's children are arranged horizontally in a row instead of vertically in a column. The default value is false.

TypeRequired
boolNo

indicatorStyle

The style of the scroll indicators.

  • 'default' (the default), same as black.
  • 'black', scroll indicator is black. This style is good against a light background.
  • 'white', scroll indicator is white. This style is good against a dark background.
TypeRequiredPlatform
enum('default', 'black', 'white')NoiOS

invertStickyHeaders

If sticky headers should stick at the bottom instead of the top of the ScrollView. This is usually used with inverted ScrollViews.

TypeRequired
boolNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

Cross platform

  • 'none' (the default), drags do not dismiss the keyboard.
  • 'on-drag', the keyboard is dismissed when a drag begins.

iOS Only

  • 'interactive', the keyboard is dismissed interactively with the drag and moves in synchrony with the touch; dragging upwards cancels the dismissal. On android this is not supported and it will have the same behavior as 'none'.
TypeRequired
enum('none', 'on-drag', 'interactive')No

keyboardShouldPersistTaps

Determines when the keyboard should stay visible after a tap.

  • 'never' (the default), tapping outside of the focused text input when the keyboard is up dismisses the keyboard. When this happens, children won't receive the tap.
  • 'always', the keyboard will not dismiss automatically, and the scroll view will not catch taps, but children of the scroll view can catch taps.
  • 'handled', the keyboard will not dismiss automatically when the tap was handled by children of the scroll view (or captured by an ancestor).
  • false, deprecated, use 'never' instead
  • true, deprecated, use 'always' instead
TypeRequired
enum('always', 'never', 'handled', false, true)No

maintainVisibleContentPosition

When set, the scroll view will adjust the scroll position so that the first child that is currently visible and at or beyond minIndexForVisible will not change position. This is useful for lists that are loading content in both directions, e.g. a chat thread, where new messages coming in might otherwise cause the scroll position to jump. A value of 0 is common, but other values such as 1 can be used to skip loading spinners or other content that should not maintain position.

The optional autoscrollToTopThreshold can be used to make the content automatically scroll to the top after making the adjustment if the user was within the threshold of the top before the adjustment was made. This is also useful for chat-like applications where you want to see new messages scroll into place, but not if the user has scrolled up a ways and it would be disruptive to scroll a bunch.

Caveat 1: Reordering elements in the scrollview with this enabled will probably cause jumpiness and jank. It can be fixed, but there are currently no plans to do so. For now, don't re-order the content of any ScrollViews or Lists that use this feature.

Caveat 2: This uses contentOffset and frame.origin in native code to compute visibility. Occlusion, transforms, and other complexity won't be taken into account as to whether content is "visible" or not.

TypeRequiredPlatform
object: { minIndexForVisible: number, autoscrollToTopThreshold: number }NoiOS

maximumZoomScale

The maximum allowed zoom scale. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

minimumZoomScale

The minimum allowed zoom scale. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

nestedScrollEnabled

Enables nested scrolling for Android API level 21+. Nested scrolling is supported by default on iOS.

TypeRequiredPlatform
boolNoAndroid

onContentSizeChange

Called when scrollable content view of the ScrollView changes.

Handler function is passed the content width and content height as parameters: (contentWidth, contentHeight)

It's implemented using onLayout handler attached to the content container which this ScrollView renders.

TypeRequired
functionNo

onMomentumScrollBegin

Called when the momentum scroll starts (scroll which occurs as the ScrollView starts gliding).

TypeRequired
functionNo

onMomentumScrollEnd

Called when the momentum scroll ends (scroll which occurs as the ScrollView glides to a stop).

TypeRequired
functionNo

onScroll

Fires at most once per frame during scrolling. The frequency of the events can be controlled using the scrollEventThrottle prop. The event has the following shape (all values are numbers):

{
nativeEvent: {
contentInset: {bottom, left, right, top},
contentOffset: {x, y},
contentSize: {height, width},
layoutMeasurement: {height, width},
zoomScale
}
}
TypeRequired
functionNo

onScrollBeginDrag

Called when the user begins to drag the scroll view.

TypeRequired
functionNo

onScrollEndDrag

Called when the user stops dragging the scroll view and it either stops or begins to glide.

TypeRequired
functionNo

onScrollToTop

Fires when the scroll view scrolls to top after the status bar has been tapped.

TypeRequiredPlatform
functionNoiOS

overScrollMode

Used to override default value of overScroll mode.

Possible values:

  • 'auto' - Default value, allow a user to over-scroll this view only if the content is large enough to meaningfully scroll.
  • 'always' - Always allow a user to over-scroll this view.
  • 'never' - Never allow a user to over-scroll this view.
TypeRequiredPlatform
enum('auto', 'always', 'never')NoAndroid

pagingEnabled

When true, the scroll view stops on multiples of the scroll view's size when scrolling. This can be used for horizontal pagination. The default value is false.

Note: Vertical pagination is not supported on Android.

TypeRequired
boolNo

persistentScrollbar

Causes the scrollbars not to turn transparent when they are not in use. The default value is false.

TypeRequiredPlatform
boolNoAndroid

pinchGestureEnabled

When true, ScrollView allows use of pinch gestures to zoom in and out. The default value is true.

TypeRequiredPlatform
boolNoiOS

refreshControl

A RefreshControl component, used to provide pull-to-refresh functionality for the ScrollView. Only works for vertical ScrollViews (horizontal prop must be false).

See RefreshControl.

TypeRequired
elementNo

removeClippedSubviews

Experimental: When true, offscreen child views (whose overflow value is hidden) are removed from their native backing superview when offscreen. This can improve scrolling performance on long lists.

TypeRequired
boolNo

scrollBarThumbImage

Optionally an image can be used for the scroll bar thumb. This will override the color. While the image is loading or the image fails to load the color will be used instead. Use an alpha of 0 in the color to avoid seeing it while the image is loading.

  • uri, a string representing the resource identifier for the image, which should be either a local file path or the name of a static image resource.
  • number, opaque type returned by something like import IMAGE from './image.jpg'.
TypeRequiredPlatform
numberNoVR

scrollEnabled

When false, the view cannot be scrolled via touch interaction. The default value is true.

Note that the view can always be scrolled by calling scrollTo.

TypeRequired
boolNo

scrollEventThrottle

This controls how often the scroll event will be fired while scrolling (as a time interval in ms). A lower number yields better accuracy for code that is tracking the scroll position, but can lead to scroll performance problems due to the volume of information being sent over the bridge. You will not notice a difference between values set between 1-16 as the JS run loop is synced to the screen refresh rate. If you do not need precise scroll position tracking, set this value higher to limit the information being sent across the bridge. The default value is zero, which results in the scroll event being sent only once each time the view is scrolled.

TypeRequiredPlatform
numberNoiOS

scrollIndicatorInsets

The amount by which the scroll view indicators are inset from the edges of the scroll view. This should normally be set to the same value as the contentInset. Defaults to {0, 0, 0, 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

scrollPerfTag

Tag used to log scroll performance on this scroll view. Will force momentum events to be turned on (see sendMomentumEvents). This doesn't do anything out of the box and you need to implement a custom native FpsListener for it to be useful.

TypeRequiredPlatform
stringNoAndroid

scrollToOverflowEnabled

When true, the scroll view can be programmatically scrolled beyond its content size. The default value is false.

TypeRequiredPlatform
boolNoiOS

scrollsToTop

When true, the scroll view scrolls to top when the status bar is tapped. The default value is true.

TypeRequiredPlatform
boolNoiOS

DEPRECATED_sendUpdatedChildFrames

When true, ScrollView will emit updateChildFrames data in scroll events, otherwise will not compute or emit child frame data. This only exists to support legacy issues, onLayout should be used instead to retrieve frame data. The default value is false.

TypeRequiredPlatform
boolNoiOS

showsHorizontalScrollIndicator

When true, shows a horizontal scroll indicator. The default value is true.

TypeRequired
boolNo

showsVerticalScrollIndicator

When true, shows a vertical scroll indicator. The default value is true.

TypeRequired
boolNo

snapToAlignment

When snapToInterval is set, snapToAlignment will define the relationship of the snapping to the scroll view.

  • 'start' (the default) will align the snap at the left (horizontal) or top (vertical).
  • 'center' will align the snap in the center.
  • 'end' will align the snap at the right (horizontal) or bottom (vertical).
TypeRequiredPlatform
enum('start', 'center', 'end')NoiOS

snapToEnd

Use in conjunction with snapToOffsets. By default, the end of the list counts as a snap offset. Set snapToEnd to false to disable this behavior and allow the list to scroll freely between its end and the last snapToOffsets offset. The default value is true.

TypeRequired
booleanNo

snapToInterval

When set, causes the scroll view to stop at multiples of the value of snapToInterval. This can be used for paginating through children that have lengths smaller than the scroll view. Typically used in combination with snapToAlignment and decelerationRate="fast". Overrides less configurable pagingEnabled prop.

TypeRequired
numberNo

snapToOffsets

When set, causes the scroll view to stop at the defined offsets. This can be used for paginating through variously sized children that have lengths smaller than the scroll view. Typically used in combination with decelerationRate="fast". Overrides less configurable pagingEnabled and snapToInterval props.

TypeRequired
array of numberNo

snapToStart

Use in conjunction with snapToOffsets. By default, the beginning of the list counts as a snap offset. Set snapToStart to false to disable this behavior and allow the list to scroll freely between its start and the first snapToOffsets offset. The default value is true.

TypeRequired
booleanNo

stickyHeaderIndices

An array of child indices determining which children get docked to the top of the screen when scrolling. For example, passing stickyHeaderIndices={[0]} will cause the first child to be fixed to the top of the scroll view. This property is not supported in conjunction with horizontal={true}.

TypeRequired
array of numberNo

zoomScale

The current scale of the scroll view content. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

Methods

flashScrollIndicators()

flashScrollIndicators();

Displays the scroll indicators momentarily.

scrollTo()

scrollTo(
options?: {x?: number, y?: number, animated?: boolean} | number,
deprecatedX?: number,
deprecatedAnimated?: boolean,
);

Scrolls to a given x, y offset, either immediately, with a smooth animation.

Example:

scrollTo({x: 0, y: 0, animated: true})

Note: The weird function signature is due to the fact that, for historical reasons, the function also accepts separate arguments as an alternative to the options object. This is deprecated due to ambiguity (y before x), and SHOULD NOT BE USED.

scrollToEnd()

scrollToEnd(([options]: { animated: boolean, duration: number }));

If this is a vertical ScrollView scrolls to the bottom. If this is a horizontal ScrollView scrolls to the right.

Use scrollToEnd({animated: true}) for smooth animated scrolling, scrollToEnd({animated: false}) for immediate scrolling. For Android, you may specify a duration, e.g. scrollToEnd({duration: 500}) for a controlled duration scroll. If no options are passed, animated defaults to true.

scrollWithoutAnimationTo()

scrollWithoutAnimationTo(y, x);

Deprecated, use scrollTo instead.

Edit this page
Last updated on
- + diff --git a/docs/0.62/sectionlist.html b/docs/0.62/sectionlist.html index c78b97b2581..2e938dba317 100644 --- a/docs/0.62/sectionlist.html +++ b/docs/0.62/sectionlist.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

SectionList

A performant interface for rendering sectioned lists, supporting the most handy features:

  • Fully cross-platform.
  • Configurable viewability callbacks.
  • List header support.
  • List footer support.
  • Item separator support.
  • Section header support.
  • Section separator support.
  • Heterogeneous data and item rendering support.
  • Pull to Refresh.
  • Scroll loading.

If you don't need section support and want a simpler interface, use <FlatList>.

Example

This is a convenience wrapper around <VirtualizedList>, and thus inherits its props (as well as those of <ScrollView> that aren't explicitly listed here, along with the following caveats:

  • Internal state is not preserved when content scrolls out of the render window. Make sure all your data is captured in the item data or external stores like Flux, Redux, or Relay.
  • This is a PureComponent which means that it will not re-render if props remain shallow-equal. Make sure that everything your renderItem function depends on is passed as a prop (e.g. extraData) that is not === after updates, otherwise your UI may not update on changes. This includes the data prop and parent component state.
  • In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate and momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application, and we are working on improving it behind the scenes.
  • By default, the list looks for a key prop on each item and uses that for the React key. Alternatively, you can provide a custom keyExtractor prop.

Reference

Props

Inherits ScrollView Props.

renderItem

Default renderer for every item in every section. Can be over-ridden on a per-section basis. Should return a React element.

TypeRequired
functionYes

The render function will be passed an object with the following keys:

  • 'item' (object) - the item object as specified in this section's data key
  • 'index' (number) - Item's index within the section.
  • 'section' (object) - The full section object as specified in sections.
  • 'separators' (object) - An object with the following keys:
    • 'highlight' (function) - () => void
    • 'unhighlight' (function) - () => void
    • 'updateProps' (function) - (select, newProps) => void
      • 'select' (enum) - possible values are 'leading', 'trailing'
      • 'newProps' (object)

sections

The actual data to render, akin to the data prop in FlatList.

TypeRequired
array of SectionsYes

extraData

A marker property for telling the list to re-render (since it implements PureComponent). If any of your renderItem, Header, Footer, etc. functions depend on anything outside of the data prop, stick it here and treat it immutably.

TypeRequired
anyNo

initialNumToRender

How many items to render in the initial batch. This should be enough to fill the screen but not much more. Note these items will never be unmounted as part of the windowed rendering in order to improve perceived performance of scroll-to-top actions.

TypeRequired
numberYes

inverted

Reverses the direction of scroll. Uses scale transforms of -1.

TypeRequired
[boolean]No

ItemSeparatorComponent

Rendered in between each item, but not at the top or bottom. By default, highlighted, section, and [leading/trailing][Item/Section] props are provided. renderItem provides separators.highlight/unhighlight which will update the highlighted prop, but you can also add custom props with separators.updateProps.

TypeRequired
[component, element]No

keyExtractor

Used to extract a unique key for a given item at the specified index. Key is used for caching and as the React key to track item re-ordering. The default extractor checks item.key, then falls back to using the index, like React does. Note that this sets keys for each item, but each overall section still needs its own key.

TypeRequired
(item: Item, index: number) => stringYes

ListEmptyComponent

Rendered when the list is empty. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
[component, element]No

ListFooterComponent

Rendered at the very end of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
[component, element]No

ListHeaderComponent

Rendered at the very beginning of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
component, elementNo

onEndReached

Called once when the scroll position gets within onEndReachedThreshold of the rendered content.

TypeRequired
[(info: {distanceFromEnd: number}) => void]No

onEndReachedThreshold

How far from the end (in units of visible length of the list) the bottom edge of the list must be from the end of the content to trigger the onEndReached callback. Thus a value of 0.5 will trigger onEndReached when the end of the content is within half the visible length of the list.

TypeRequired
[number]No

onRefresh

If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the refreshing prop correctly. To offset the RefreshControl from the top (e.g. by 100 pts), use progressViewOffset={100}.

TypeRequired
[() => void]No

onViewableItemsChanged

Called when the viewability of rows changes, as defined by the viewabilityConfig prop.

TypeRequired
functionNo

The function will be passed an object with the following keys:

  • 'viewableItems' (array of ViewTokens)
  • 'changed' (array of ViewTokens)

The ViewToken type is exported by ViewabilityHelper.js:

NameTypeRequired
itemanyYes
keystringYes
indexnumberNo
isViewablebooleanYes
sectionanyNo

refreshing

Set this true while waiting for new data from a refresh.

TypeRequired
[boolean]No

removeClippedSubviews

Note: may have bugs (missing content) in some circumstances - use at your own risk.

This may improve scroll performance for large lists.

TypeRequired
booleanNo

renderSectionFooter

Rendered at the bottom of each section.

TypeRequired
[(info: {section: SectionT}) => ?React.Element<any>]No

renderSectionHeader

Rendered at the top of each section. These stick to the top of the ScrollView by default on iOS. See stickySectionHeadersEnabled.

TypeRequired
[(info: {section: SectionT}) => ?React.Element<any>]No

SectionSeparatorComponent

Rendered at the top and bottom of each section (note this is different from ItemSeparatorComponent which is only rendered between items). These are intended to separate sections from the headers above and below and typically have the same highlight response as ItemSeparatorComponent. Also receives highlighted, [leading/trailing][Item/Section], and any custom props from separators.updateProps.

TypeRequired
[ReactClass<any>]No

stickySectionHeadersEnabled

Makes section headers stick to the top of the screen until the next one pushes it off. Only enabled by default on iOS because that is the platform standard there.

TypeRequired
booleanNo

Methods

scrollToLocation()

scrollToLocation(params);

Scrolls to the item at the specified sectionIndex and itemIndex (within the section) positioned in the viewable area such that viewPosition 0 places it at the top (and may be covered by a sticky header), 1 at the bottom, and 0.5 centered in the middle.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout or onScrollToIndexFailed prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.
  • 'itemIndex' (number) - Index within section for the item to scroll to. Required.
  • 'sectionIndex' (number) - Index for section that contains the item to scroll to. Required.
  • 'viewOffset' (number) - A fixed number of pixels to offset the final target position, e.g. to compensate for sticky headers.
  • 'viewPosition' (number) - A value of 0 places the item specified by index at the top, 1 at the bottom, and 0.5 centered in the middle.

recordInteraction()

recordInteraction();

Tells the list an interaction has occurred, 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()

flashScrollIndicators();

Displays the scroll indicators momentarily.

Platform
iOS

Type Definitions

Section

An object that identifies the data to be rendered for a given section.

Type
any

Properties:

NameTypeDescription
dataarrayThe data for rendering items in this section. Array of objects, much like FlatList's data prop.
[key]stringOptional key to keep track of section re-ordering. If you don't plan on re-ordering sections, the array index will be used by default.
[renderItem]functionOptionally define an arbitrary item renderer for this section, overriding the default renderItem for the list.
[ItemSeparatorComponent]component, elementOptionally define an arbitrary item separator for this section, overriding the default ItemSeparatorComponent for the list.
[keyExtractor]functionOptionally define an arbitrary key extractor for this section, overriding the default keyExtractor.
Edit this page
Last updated on
- + diff --git a/docs/0.62/sectionlist/index.html b/docs/0.62/sectionlist/index.html index c78b97b2581..2e938dba317 100644 --- a/docs/0.62/sectionlist/index.html +++ b/docs/0.62/sectionlist/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

SectionList

A performant interface for rendering sectioned lists, supporting the most handy features:

  • Fully cross-platform.
  • Configurable viewability callbacks.
  • List header support.
  • List footer support.
  • Item separator support.
  • Section header support.
  • Section separator support.
  • Heterogeneous data and item rendering support.
  • Pull to Refresh.
  • Scroll loading.

If you don't need section support and want a simpler interface, use <FlatList>.

Example

This is a convenience wrapper around <VirtualizedList>, and thus inherits its props (as well as those of <ScrollView> that aren't explicitly listed here, along with the following caveats:

  • Internal state is not preserved when content scrolls out of the render window. Make sure all your data is captured in the item data or external stores like Flux, Redux, or Relay.
  • This is a PureComponent which means that it will not re-render if props remain shallow-equal. Make sure that everything your renderItem function depends on is passed as a prop (e.g. extraData) that is not === after updates, otherwise your UI may not update on changes. This includes the data prop and parent component state.
  • In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate and momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application, and we are working on improving it behind the scenes.
  • By default, the list looks for a key prop on each item and uses that for the React key. Alternatively, you can provide a custom keyExtractor prop.

Reference

Props

Inherits ScrollView Props.

renderItem

Default renderer for every item in every section. Can be over-ridden on a per-section basis. Should return a React element.

TypeRequired
functionYes

The render function will be passed an object with the following keys:

  • 'item' (object) - the item object as specified in this section's data key
  • 'index' (number) - Item's index within the section.
  • 'section' (object) - The full section object as specified in sections.
  • 'separators' (object) - An object with the following keys:
    • 'highlight' (function) - () => void
    • 'unhighlight' (function) - () => void
    • 'updateProps' (function) - (select, newProps) => void
      • 'select' (enum) - possible values are 'leading', 'trailing'
      • 'newProps' (object)

sections

The actual data to render, akin to the data prop in FlatList.

TypeRequired
array of SectionsYes

extraData

A marker property for telling the list to re-render (since it implements PureComponent). If any of your renderItem, Header, Footer, etc. functions depend on anything outside of the data prop, stick it here and treat it immutably.

TypeRequired
anyNo

initialNumToRender

How many items to render in the initial batch. This should be enough to fill the screen but not much more. Note these items will never be unmounted as part of the windowed rendering in order to improve perceived performance of scroll-to-top actions.

TypeRequired
numberYes

inverted

Reverses the direction of scroll. Uses scale transforms of -1.

TypeRequired
[boolean]No

ItemSeparatorComponent

Rendered in between each item, but not at the top or bottom. By default, highlighted, section, and [leading/trailing][Item/Section] props are provided. renderItem provides separators.highlight/unhighlight which will update the highlighted prop, but you can also add custom props with separators.updateProps.

TypeRequired
[component, element]No

keyExtractor

Used to extract a unique key for a given item at the specified index. Key is used for caching and as the React key to track item re-ordering. The default extractor checks item.key, then falls back to using the index, like React does. Note that this sets keys for each item, but each overall section still needs its own key.

TypeRequired
(item: Item, index: number) => stringYes

ListEmptyComponent

Rendered when the list is empty. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
[component, element]No

ListFooterComponent

Rendered at the very end of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
[component, element]No

ListHeaderComponent

Rendered at the very beginning of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
component, elementNo

onEndReached

Called once when the scroll position gets within onEndReachedThreshold of the rendered content.

TypeRequired
[(info: {distanceFromEnd: number}) => void]No

onEndReachedThreshold

How far from the end (in units of visible length of the list) the bottom edge of the list must be from the end of the content to trigger the onEndReached callback. Thus a value of 0.5 will trigger onEndReached when the end of the content is within half the visible length of the list.

TypeRequired
[number]No

onRefresh

If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the refreshing prop correctly. To offset the RefreshControl from the top (e.g. by 100 pts), use progressViewOffset={100}.

TypeRequired
[() => void]No

onViewableItemsChanged

Called when the viewability of rows changes, as defined by the viewabilityConfig prop.

TypeRequired
functionNo

The function will be passed an object with the following keys:

  • 'viewableItems' (array of ViewTokens)
  • 'changed' (array of ViewTokens)

The ViewToken type is exported by ViewabilityHelper.js:

NameTypeRequired
itemanyYes
keystringYes
indexnumberNo
isViewablebooleanYes
sectionanyNo

refreshing

Set this true while waiting for new data from a refresh.

TypeRequired
[boolean]No

removeClippedSubviews

Note: may have bugs (missing content) in some circumstances - use at your own risk.

This may improve scroll performance for large lists.

TypeRequired
booleanNo

renderSectionFooter

Rendered at the bottom of each section.

TypeRequired
[(info: {section: SectionT}) => ?React.Element<any>]No

renderSectionHeader

Rendered at the top of each section. These stick to the top of the ScrollView by default on iOS. See stickySectionHeadersEnabled.

TypeRequired
[(info: {section: SectionT}) => ?React.Element<any>]No

SectionSeparatorComponent

Rendered at the top and bottom of each section (note this is different from ItemSeparatorComponent which is only rendered between items). These are intended to separate sections from the headers above and below and typically have the same highlight response as ItemSeparatorComponent. Also receives highlighted, [leading/trailing][Item/Section], and any custom props from separators.updateProps.

TypeRequired
[ReactClass<any>]No

stickySectionHeadersEnabled

Makes section headers stick to the top of the screen until the next one pushes it off. Only enabled by default on iOS because that is the platform standard there.

TypeRequired
booleanNo

Methods

scrollToLocation()

scrollToLocation(params);

Scrolls to the item at the specified sectionIndex and itemIndex (within the section) positioned in the viewable area such that viewPosition 0 places it at the top (and may be covered by a sticky header), 1 at the bottom, and 0.5 centered in the middle.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout or onScrollToIndexFailed prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.
  • 'itemIndex' (number) - Index within section for the item to scroll to. Required.
  • 'sectionIndex' (number) - Index for section that contains the item to scroll to. Required.
  • 'viewOffset' (number) - A fixed number of pixels to offset the final target position, e.g. to compensate for sticky headers.
  • 'viewPosition' (number) - A value of 0 places the item specified by index at the top, 1 at the bottom, and 0.5 centered in the middle.

recordInteraction()

recordInteraction();

Tells the list an interaction has occurred, 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()

flashScrollIndicators();

Displays the scroll indicators momentarily.

Platform
iOS

Type Definitions

Section

An object that identifies the data to be rendered for a given section.

Type
any

Properties:

NameTypeDescription
dataarrayThe data for rendering items in this section. Array of objects, much like FlatList's data prop.
[key]stringOptional key to keep track of section re-ordering. If you don't plan on re-ordering sections, the array index will be used by default.
[renderItem]functionOptionally define an arbitrary item renderer for this section, overriding the default renderItem for the list.
[ItemSeparatorComponent]component, elementOptionally define an arbitrary item separator for this section, overriding the default ItemSeparatorComponent for the list.
[keyExtractor]functionOptionally define an arbitrary key extractor for this section, overriding the default keyExtractor.
Edit this page
Last updated on
- + diff --git a/docs/0.62/security.html b/docs/0.62/security.html index 381010a8473..08fa252b29d 100644 --- a/docs/0.62/security.html +++ b/docs/0.62/security.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Security

Security is often overlooked when building apps. It is true that it is impossible to build software that is completely impenetrable—we’ve yet to invent a completely impenetrable lock (bank vaults do, after all, still get broken into). However, the probability of falling victim to a malicious attack or being exposed for a security vulnerability is inversely proportional to the effort you’re willing to put in to protecting your application against any such eventuality. Although an ordinary padlock is pickable, it is still much harder to get past than a cabinet hook!

In this guide, you will learn about best practices for storing sensitive information, authentication, network security, and tools that will help you secure your app. This is not a preflight checklist—it is a catalogue of options, each of which will help further protect your app and users.

Storing Sensitive Info

Never store sensitive API keys in your app code. Anything included in your code could be accessed in plain text by anyone inspecting the app bundle. Tools like react-native-dotenv and react-native-config are great for adding environment-specific variables like API endpoints, but they should not be confused with server-side environment variables, which can often contain secrets and api keys.

If you must have an API key or a secret to access some resource from your app, the most secure way to handle this would be to build an orchestration layer between your app and the resource. This could be a serverless function (e.g. using AWS Lambda or Google Cloud Functions) which can forward the request with the required API key or secret. Secrets in server side code cannot be accessed by the API consumers the same way secrets in your app code can.

For persisted user data, choose the right type of storage based on its sensitivity. As your app is used, you’ll often find the need to save data on the device, whether to support your app being used offline, cut down on network requests or save your user’s access token between sessions so they wouldn’t have to re-authenticate each time they use the app.

Persisted vs unpersisted — persisted data is written to the device’s memory, which lets the data be read by your app across application launches without having to do another network request to fetch it or asking the user to re-enter it. But this also can make that data more vulnerable to being accessed by attackers. Unpersisted data is never written to memory—so there's no data to access!

Async Storage

Async Storage is a community-maintained module for React Native that provides an asynchronous, unencrypted, key-value store. Async Storage is not shared between apps: every app has its own sandbox environment and has no access to data from other apps.

Do use asynch storage when...Don't use asynch storage for...
Persisting non-sensitive data across app runsToken storage
Persisting Redux stateSecrets
Persisting GraphQL state
Storing global app-wide variables

Developer Notes

Async Storage is the React Native equivalent of Local Storage from the web

Secure Storage

React Native does not come bundled with any way of storing sensitive data. However, there are pre-existing solutions for Android and iOS platforms.

iOS - Keychain Services

Keychain Services allows you to securely store small chunks of sensitive info for the user. This is an ideal place to store certificates, tokens, passwords, and any other sensitive information that doesn’t belong in Async Storage.

Android - Secure Shared Preferences

Shared Preferences is the Android equivalent for a persistent key-value data store. Data in Shared Preferences is not encrypted by default, but Encrypted Shared Preferences wraps the Shared Preferences class for Android, and automatically encrypts keys and values.

Android - Keystore

The Android Keystore system lets you store cryptographic keys in a container to make it more difficult to extract from the device.

In order to use iOS Keychain services or Android Secure Shared Preferences, you can either write a bridge yourself or use a library which wraps them for you and provides a unified API at your own risk. Some libraries to consider:

Be mindful of unintentionally storing or exposing sensitive info. This could happen accidentally, for example saving sensitive form data in redux state and persisting the whole state tree in Async Storage. Or sending user tokens and personal info to an application monitoring service such as Sentry or Crashlytics.

Authentication and Deep Linking

Mobile apps have a unique vulnerability that is non-existent in the web: deep linking. Deep linking is a way of sending data directly to a native application from an outside source. A deep link looks like app:// where app is your app scheme and anything following the // could be used internally to handle the request.

For example, if you were building an ecommerce app, you could use app://products/1 to deep link to your app and open the product detail page for a product with id 1. You can think of these kind of like URLs on the web, but with one crucial distinction:

Deep links are not secure and you should never send any sensitive information in them.

The reason deep links are not secure is because there is no centralized method of registering URL schemes. As an application developer, you can use almost any url scheme you choose by configuring it in Xcode for iOS or adding an intent on Android.

There is nothing stopping a malicious application from hijacking your deep link by also registering to the same scheme and then obtaining access to the data your link contains. Sending something like app://products/1 is not harmful, but sending tokens is a security concern.

When the operating system has two or more applications to choose from when opening a link, Android will show the user a modal and ask them to choose which application to use to open the link. On iOS however, the operating system will make the choice for you, so the user will be blissfully unaware. Apple has made steps to address this issue in later iOS versions (iOS 11) where the instituted a first-come-first-served principle, although this vulnerability could still be exploited in different ways which you can read more about here. Using universal links will allow linking to content within your app securely in iOS.

OAuth2 and Redirects

The OAuth2 authentication protocol is incredibly popular nowadays, prided as the most complete and secure protocol around. The OpenID Connect protocol is also based on this. In OAuth2, the user is asked to authenticate via a third party. On successful completion, this third party redirects back to the requesting application with a verification code which can be exchanged for a JWT — a JSON Web Token. JWT is an open standard for securely transmitting information between parties on the web.

On the web, this redirect step is secure, because URLs on the web are guaranteed to be unique. This is not true for apps because, as mentioned earlier, there is no centralized method of registering URL schemes! In order to address this security concern, an additional check must be added in the form of PKCE.

PKCE, pronounced “Pixy” stands for Proof of Key Code Exchange, and is an extension to the OAuth 2 spec. This involves adding an additional layer of security which verifies that the authentication and token exchange requests come from the same client. PKCE uses the SHA 265 Cryptographic Hash Algorithm. SHA 265 creates a unique “signature” for a text or file of any size, but it is:

  • Always the same length regardless of the input file
  • Guaranteed to be always produce the same result for the same input
  • One way (that is, you can’t reverse engineer it to reveal the original input)

Now you have two values:

  • code_verifier - a large random string generated by the client
  • code_challenge - the SHA 265 of the code_verifier

During the initial /authorize request, the client also sends the code_challenge for the code_verifier it keeps in memory. After the authorize request has returned correctly, the client also sends the code_verifier that was used to generate the code_challenge. The IDP will then calculate the code_challenge, see if it matches what was set on the very first /authorize request, and only send the access token if the values match.

This guarantees that only the application that triggered the initial authorization flow would be able to successfully exchange the verification code for a JWT. So even if a malicious application gets access to the verification code, it will be useless on its own. To see this in action, check out this example.

A library to consider for native OAuth is react-native-app-auth. React-native-app-auth is an SDK for communicating with OAuth2 providers. It wraps the native AppAuth-iOS and AppAuth-Android libraries and can support PKCE.

React-native-app-auth can support PKCE only if your Identity Provider supports it.

OAuth2 with PKCE

Network Security

Your APIs should always use SSL encryption. SSL encryption protects against the requested data being read in plain text between when it leaves the server and before it reaches the client. You’ll know the endpoint is secure, because it starts with https:// instead of http://.

SSL Pinning

Using https endpoints could still leave your data vulnerable to interception. With https, the client will only trust the server if it can provide a valid certificate that is signed by a trusted Certificate Authority that is pre-installed on the client. An attacker could take advantage of this by installing a malicious root CA certificate to the user’s device, so the client would trust all certificates that are signed by the attacker. Thus, relying on certificates alone could still leave you vulnerable to a man-in-the-middle attack.

SSL pinning is a technique that can be used on the client side to avoid this attack. It works by embedding (or pinning) a list of trusted certificates to the client during development, so that only the requests signed with one of the trusted certificates will be accepted, and any self-signed certificates will not be.

When using SSL pinning, you should be mindful of certificate expiry. Certificates expire every 1-2 years and when one does, it’ll need to be updated in the app as well as on the server. As soon as the certificate on the server has been updated, any apps with the old certificate embedded in them will cease to work.

Summary

There is no bulletproof way to handle security, but with conscious effort and diligence, it is possible to significantly reduce the likelihood of a security breach in your application. Invest in security proportional to the sensitivity of the data stored in your application, the number of users, and the damage a hacker could do when gaining access to their account. And remember: it’s significantly harder to access information that was never requested in the first place.

Edit this page
Last updated on
- + diff --git a/docs/0.62/security/index.html b/docs/0.62/security/index.html index 381010a8473..08fa252b29d 100644 --- a/docs/0.62/security/index.html +++ b/docs/0.62/security/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Security

Security is often overlooked when building apps. It is true that it is impossible to build software that is completely impenetrable—we’ve yet to invent a completely impenetrable lock (bank vaults do, after all, still get broken into). However, the probability of falling victim to a malicious attack or being exposed for a security vulnerability is inversely proportional to the effort you’re willing to put in to protecting your application against any such eventuality. Although an ordinary padlock is pickable, it is still much harder to get past than a cabinet hook!

In this guide, you will learn about best practices for storing sensitive information, authentication, network security, and tools that will help you secure your app. This is not a preflight checklist—it is a catalogue of options, each of which will help further protect your app and users.

Storing Sensitive Info

Never store sensitive API keys in your app code. Anything included in your code could be accessed in plain text by anyone inspecting the app bundle. Tools like react-native-dotenv and react-native-config are great for adding environment-specific variables like API endpoints, but they should not be confused with server-side environment variables, which can often contain secrets and api keys.

If you must have an API key or a secret to access some resource from your app, the most secure way to handle this would be to build an orchestration layer between your app and the resource. This could be a serverless function (e.g. using AWS Lambda or Google Cloud Functions) which can forward the request with the required API key or secret. Secrets in server side code cannot be accessed by the API consumers the same way secrets in your app code can.

For persisted user data, choose the right type of storage based on its sensitivity. As your app is used, you’ll often find the need to save data on the device, whether to support your app being used offline, cut down on network requests or save your user’s access token between sessions so they wouldn’t have to re-authenticate each time they use the app.

Persisted vs unpersisted — persisted data is written to the device’s memory, which lets the data be read by your app across application launches without having to do another network request to fetch it or asking the user to re-enter it. But this also can make that data more vulnerable to being accessed by attackers. Unpersisted data is never written to memory—so there's no data to access!

Async Storage

Async Storage is a community-maintained module for React Native that provides an asynchronous, unencrypted, key-value store. Async Storage is not shared between apps: every app has its own sandbox environment and has no access to data from other apps.

Do use asynch storage when...Don't use asynch storage for...
Persisting non-sensitive data across app runsToken storage
Persisting Redux stateSecrets
Persisting GraphQL state
Storing global app-wide variables

Developer Notes

Async Storage is the React Native equivalent of Local Storage from the web

Secure Storage

React Native does not come bundled with any way of storing sensitive data. However, there are pre-existing solutions for Android and iOS platforms.

iOS - Keychain Services

Keychain Services allows you to securely store small chunks of sensitive info for the user. This is an ideal place to store certificates, tokens, passwords, and any other sensitive information that doesn’t belong in Async Storage.

Android - Secure Shared Preferences

Shared Preferences is the Android equivalent for a persistent key-value data store. Data in Shared Preferences is not encrypted by default, but Encrypted Shared Preferences wraps the Shared Preferences class for Android, and automatically encrypts keys and values.

Android - Keystore

The Android Keystore system lets you store cryptographic keys in a container to make it more difficult to extract from the device.

In order to use iOS Keychain services or Android Secure Shared Preferences, you can either write a bridge yourself or use a library which wraps them for you and provides a unified API at your own risk. Some libraries to consider:

Be mindful of unintentionally storing or exposing sensitive info. This could happen accidentally, for example saving sensitive form data in redux state and persisting the whole state tree in Async Storage. Or sending user tokens and personal info to an application monitoring service such as Sentry or Crashlytics.

Authentication and Deep Linking

Mobile apps have a unique vulnerability that is non-existent in the web: deep linking. Deep linking is a way of sending data directly to a native application from an outside source. A deep link looks like app:// where app is your app scheme and anything following the // could be used internally to handle the request.

For example, if you were building an ecommerce app, you could use app://products/1 to deep link to your app and open the product detail page for a product with id 1. You can think of these kind of like URLs on the web, but with one crucial distinction:

Deep links are not secure and you should never send any sensitive information in them.

The reason deep links are not secure is because there is no centralized method of registering URL schemes. As an application developer, you can use almost any url scheme you choose by configuring it in Xcode for iOS or adding an intent on Android.

There is nothing stopping a malicious application from hijacking your deep link by also registering to the same scheme and then obtaining access to the data your link contains. Sending something like app://products/1 is not harmful, but sending tokens is a security concern.

When the operating system has two or more applications to choose from when opening a link, Android will show the user a modal and ask them to choose which application to use to open the link. On iOS however, the operating system will make the choice for you, so the user will be blissfully unaware. Apple has made steps to address this issue in later iOS versions (iOS 11) where the instituted a first-come-first-served principle, although this vulnerability could still be exploited in different ways which you can read more about here. Using universal links will allow linking to content within your app securely in iOS.

OAuth2 and Redirects

The OAuth2 authentication protocol is incredibly popular nowadays, prided as the most complete and secure protocol around. The OpenID Connect protocol is also based on this. In OAuth2, the user is asked to authenticate via a third party. On successful completion, this third party redirects back to the requesting application with a verification code which can be exchanged for a JWT — a JSON Web Token. JWT is an open standard for securely transmitting information between parties on the web.

On the web, this redirect step is secure, because URLs on the web are guaranteed to be unique. This is not true for apps because, as mentioned earlier, there is no centralized method of registering URL schemes! In order to address this security concern, an additional check must be added in the form of PKCE.

PKCE, pronounced “Pixy” stands for Proof of Key Code Exchange, and is an extension to the OAuth 2 spec. This involves adding an additional layer of security which verifies that the authentication and token exchange requests come from the same client. PKCE uses the SHA 265 Cryptographic Hash Algorithm. SHA 265 creates a unique “signature” for a text or file of any size, but it is:

  • Always the same length regardless of the input file
  • Guaranteed to be always produce the same result for the same input
  • One way (that is, you can’t reverse engineer it to reveal the original input)

Now you have two values:

  • code_verifier - a large random string generated by the client
  • code_challenge - the SHA 265 of the code_verifier

During the initial /authorize request, the client also sends the code_challenge for the code_verifier it keeps in memory. After the authorize request has returned correctly, the client also sends the code_verifier that was used to generate the code_challenge. The IDP will then calculate the code_challenge, see if it matches what was set on the very first /authorize request, and only send the access token if the values match.

This guarantees that only the application that triggered the initial authorization flow would be able to successfully exchange the verification code for a JWT. So even if a malicious application gets access to the verification code, it will be useless on its own. To see this in action, check out this example.

A library to consider for native OAuth is react-native-app-auth. React-native-app-auth is an SDK for communicating with OAuth2 providers. It wraps the native AppAuth-iOS and AppAuth-Android libraries and can support PKCE.

React-native-app-auth can support PKCE only if your Identity Provider supports it.

OAuth2 with PKCE

Network Security

Your APIs should always use SSL encryption. SSL encryption protects against the requested data being read in plain text between when it leaves the server and before it reaches the client. You’ll know the endpoint is secure, because it starts with https:// instead of http://.

SSL Pinning

Using https endpoints could still leave your data vulnerable to interception. With https, the client will only trust the server if it can provide a valid certificate that is signed by a trusted Certificate Authority that is pre-installed on the client. An attacker could take advantage of this by installing a malicious root CA certificate to the user’s device, so the client would trust all certificates that are signed by the attacker. Thus, relying on certificates alone could still leave you vulnerable to a man-in-the-middle attack.

SSL pinning is a technique that can be used on the client side to avoid this attack. It works by embedding (or pinning) a list of trusted certificates to the client during development, so that only the requests signed with one of the trusted certificates will be accepted, and any self-signed certificates will not be.

When using SSL pinning, you should be mindful of certificate expiry. Certificates expire every 1-2 years and when one does, it’ll need to be updated in the app as well as on the server. As soon as the certificate on the server has been updated, any apps with the old certificate embedded in them will cease to work.

Summary

There is no bulletproof way to handle security, but with conscious effort and diligence, it is possible to significantly reduce the likelihood of a security breach in your application. Invest in security proportional to the sensitivity of the data stored in your application, the number of users, and the damage a hacker could do when gaining access to their account. And remember: it’s significantly harder to access information that was never requested in the first place.

Edit this page
Last updated on
- + diff --git a/docs/0.62/segmentedcontrolios.html b/docs/0.62/segmentedcontrolios.html index 38643651eff..2e825cf1e75 100644 --- a/docs/0.62/segmentedcontrolios.html +++ b/docs/0.62/segmentedcontrolios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 SegmentedControlIOS

Deprecated. Use @react-native-community/segmented-control instead.

Uses SegmentedControlIOS to render a UISegmentedControl iOS.

Programmatically changing selected index

The selected index can be changed on the fly by assigning the selectedIndex prop to a state variable, then changing that variable. Note that the state variable would need to be updated as the user selects a value and changes the index, as shown in the example below.

Example

Reference

Props

Inherits View Props.

enabled

If false the user won't be able to interact with the control. Default value is true.

TypeRequired
boolNo

momentary

If true, then selecting a segment won't persist visually. The onValueChange callback will still work as expected.

TypeRequired
boolNo

onChange

Callback that is called when the user taps a segment; passes the event as an argument

TypeRequired
functionNo

onValueChange

Callback that is called when the user taps a segment; passes the segment's value as an argument

TypeRequired
functionNo

selectedIndex

The index in props.values of the segment to be (pre)selected.

TypeRequired
numberNo

tintColor

Accent color of the control.

TypeRequired
stringNo

values

The labels for the control's segment buttons, in order.

TypeRequired
array of stringNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/segmentedcontrolios/index.html b/docs/0.62/segmentedcontrolios/index.html index 38643651eff..2e825cf1e75 100644 --- a/docs/0.62/segmentedcontrolios/index.html +++ b/docs/0.62/segmentedcontrolios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 SegmentedControlIOS

Deprecated. Use @react-native-community/segmented-control instead.

Uses SegmentedControlIOS to render a UISegmentedControl iOS.

Programmatically changing selected index

The selected index can be changed on the fly by assigning the selectedIndex prop to a state variable, then changing that variable. Note that the state variable would need to be updated as the user selects a value and changes the index, as shown in the example below.

Example

Reference

Props

Inherits View Props.

enabled

If false the user won't be able to interact with the control. Default value is true.

TypeRequired
boolNo

momentary

If true, then selecting a segment won't persist visually. The onValueChange callback will still work as expected.

TypeRequired
boolNo

onChange

Callback that is called when the user taps a segment; passes the event as an argument

TypeRequired
functionNo

onValueChange

Callback that is called when the user taps a segment; passes the segment's value as an argument

TypeRequired
functionNo

selectedIndex

The index in props.values of the segment to be (pre)selected.

TypeRequired
numberNo

tintColor

Accent color of the control.

TypeRequired
stringNo

values

The labels for the control's segment buttons, in order.

TypeRequired
array of stringNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/settings.html b/docs/0.62/settings.html index ef910dc0ef0..138f0195a17 100644 --- a/docs/0.62/settings.html +++ b/docs/0.62/settings.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Settings

Settings serves as a wrapper for NSUserDefaults, a persistent key-value store available only on iOS.

Example

Reference

Methods

clearWatch()

static clearWatch(watchId: number)

watchId is the number returned by watchKeys() when the subscription was originally configured.

get()

static get(key: string): mixed

Get the current value for a given key in NSUserDefaults.

set()

static set(settings: object)

Set one or more values in NSUserDefaults.

watchKeys()

static watchKeys(keys: string | array<string>, callback: function): number

Subscribe to be notified when the value for any of the keys specified by the keys parameter has been changed in NSUserDefaults. Returns a watchId number that may be used with clearWatch() to unsubscribe.

Note: watchKeys() by design ignores internal set() calls and fires callback only on changes preformed outside of React Native code.

Edit this page
Last updated on
- + diff --git a/docs/0.62/settings/index.html b/docs/0.62/settings/index.html index ef910dc0ef0..138f0195a17 100644 --- a/docs/0.62/settings/index.html +++ b/docs/0.62/settings/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Settings

Settings serves as a wrapper for NSUserDefaults, a persistent key-value store available only on iOS.

Example

Reference

Methods

clearWatch()

static clearWatch(watchId: number)

watchId is the number returned by watchKeys() when the subscription was originally configured.

get()

static get(key: string): mixed

Get the current value for a given key in NSUserDefaults.

set()

static set(settings: object)

Set one or more values in NSUserDefaults.

watchKeys()

static watchKeys(keys: string | array<string>, callback: function): number

Subscribe to be notified when the value for any of the keys specified by the keys parameter has been changed in NSUserDefaults. Returns a watchId number that may be used with clearWatch() to unsubscribe.

Note: watchKeys() by design ignores internal set() calls and fires callback only on changes preformed outside of React Native code.

Edit this page
Last updated on
- + diff --git a/docs/0.62/shadow-props.html b/docs/0.62/shadow-props.html index ac6e4135d94..40df9428eea 100644 --- a/docs/0.62/shadow-props.html +++ b/docs/0.62/shadow-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Shadow Props

Reference

These properties are iOS only - for similar functionality on Android, use the elevation property.

Props

shadowColor

Sets the drop shadow color

TypeRequiredPlatform
colorNoiOS

shadowOffset

Sets the drop shadow offset

TypeRequiredPlatform
object: {width: number,height: number}NoiOS

shadowOpacity

Sets the drop shadow opacity (multiplied by the color's alpha component)

TypeRequiredPlatform
numberNoiOS

shadowRadius

Sets the drop shadow blur radius

TypeRequiredPlatform
numberNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.62/shadow-props/index.html b/docs/0.62/shadow-props/index.html index ac6e4135d94..40df9428eea 100644 --- a/docs/0.62/shadow-props/index.html +++ b/docs/0.62/shadow-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Shadow Props

Reference

These properties are iOS only - for similar functionality on Android, use the elevation property.

Props

shadowColor

Sets the drop shadow color

TypeRequiredPlatform
colorNoiOS

shadowOffset

Sets the drop shadow offset

TypeRequiredPlatform
object: {width: number,height: number}NoiOS

shadowOpacity

Sets the drop shadow opacity (multiplied by the color's alpha component)

TypeRequiredPlatform
numberNoiOS

shadowRadius

Sets the drop shadow blur radius

TypeRequiredPlatform
numberNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.62/share.html b/docs/0.62/share.html index ddc02ffe041..24e1aff159c 100644 --- a/docs/0.62/share.html +++ b/docs/0.62/share.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Share

Example

Reference

Methods

share()

static share(content, options)

Open a dialog to share text content.

In iOS, returns a Promise which will be invoked with an object containing action and activityType. If the user dismissed the dialog, the Promise will still be resolved with action being Share.dismissedAction and all the other keys being undefined. Note that some share options will not appear or work on the iOS simulator.

In Android, returns a Promise which will always be resolved with action being Share.sharedAction.

Content

  • message - a message to share

iOS

  • url - an URL to share

At least one of URL and message is required.

Android

  • title - title of the message

Options

iOS

  • subject - a subject to share via email
  • excludedActivityTypes
  • tintColor

Android

  • dialogTitle

sharedAction()

static sharedAction()

The content was successfully shared.

dismissedAction()

static dismissedAction()

iOS Only. The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/0.62/share/index.html b/docs/0.62/share/index.html index ddc02ffe041..24e1aff159c 100644 --- a/docs/0.62/share/index.html +++ b/docs/0.62/share/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Share

Example

Reference

Methods

share()

static share(content, options)

Open a dialog to share text content.

In iOS, returns a Promise which will be invoked with an object containing action and activityType. If the user dismissed the dialog, the Promise will still be resolved with action being Share.dismissedAction and all the other keys being undefined. Note that some share options will not appear or work on the iOS simulator.

In Android, returns a Promise which will always be resolved with action being Share.sharedAction.

Content

  • message - a message to share

iOS

  • url - an URL to share

At least one of URL and message is required.

Android

  • title - title of the message

Options

iOS

  • subject - a subject to share via email
  • excludedActivityTypes
  • tintColor

Android

  • dialogTitle

sharedAction()

static sharedAction()

The content was successfully shared.

dismissedAction()

static dismissedAction()

iOS Only. The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/0.62/signed-apk-android.html b/docs/0.62/signed-apk-android.html index eab9fc2637b..02110738b85 100644 --- a/docs/0.62/signed-apk-android.html +++ b/docs/0.62/signed-apk-android.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Publishing to Google Play Store

Android requires that all apps be digitally signed with a certificate before they can be installed. In order to distribute your Android application via Google Play store it needs to be signed with a release key that then needs to be used for all future updates. Since 2017 it is possible for Google Play to manage signing releases automatically thanks to App Signing by Google Play functionality. However, before your application binary is uploaded to Google Play it needs to be signed with an upload key. The Signing Your Applications page on Android Developers documentation describes the topic in detail. This guide covers the process in brief, as well as lists the steps required to package the JavaScript bundle.

Generating an upload key

You can generate a private signing key using keytool. On Windows keytool must be run from C:\Program Files\Java\jdkx.x.x_x\bin.

$ keytool -genkeypair -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

This command prompts you for passwords for the keystore and key and for the Distinguished Name fields for your key. It then generates the keystore as a file called my-upload-key.keystore.

The keystore contains a single key, valid for 10000 days. The alias is a name that you will use later when signing your app, so remember to take note of the alias.

On Mac, if you're not sure where your JDK bin folder is, then perform the following command to find it:

$ /usr/libexec/java_home

It will output the directory of the JDK, which will look something like this:

/Library/Java/JavaVirtualMachines/jdkX.X.X_XXX.jdk/Contents/Home

Navigate to that directory by using the command $ cd /your/jdk/path and use the keytool command with sudo permission as shown below.

$ sudo keytool -genkey -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

Note: Remember to keep the keystore file private. In case you've lost upload key or it's been compromised you should follow these instructions.

Setting up Gradle variables

  1. Place the my-upload-key.keystore file under the android/app directory in your project folder.
  2. Edit the file ~/.gradle/gradle.properties or android/gradle.properties, and add the following (replace ***** with the correct keystore password, alias and key password),
MYAPP_UPLOAD_STORE_FILE=my-upload-key.keystore
MYAPP_UPLOAD_KEY_ALIAS=my-key-alias
MYAPP_UPLOAD_STORE_PASSWORD=*****
MYAPP_UPLOAD_KEY_PASSWORD=*****

These are going to be global Gradle variables, which we can later use in our Gradle config to sign our app.

Note about security: If you are not keen on storing your passwords in plaintext, and you are running OSX, you can also store your credentials in the Keychain Access app. Then you can skip the two last rows in ~/.gradle/gradle.properties.

Adding signing config to your app's Gradle config

The last configuration step that needs to be done is to setup release builds to be signed using upload key. Edit the file android/app/build.gradle in your project folder, and add the signing config,

...
android {
...
defaultConfig { ... }
signingConfigs {
release {
if (project.hasProperty('MYAPP_UPLOAD_STORE_FILE')) {
storeFile file(MYAPP_UPLOAD_STORE_FILE)
storePassword MYAPP_UPLOAD_STORE_PASSWORD
keyAlias MYAPP_UPLOAD_KEY_ALIAS
keyPassword MYAPP_UPLOAD_KEY_PASSWORD
}
}
}
buildTypes {
release {
...
signingConfig signingConfigs.release
}
}
}
...

Generating the release APK

Run the following in a terminal:

$ cd android
$ ./gradlew bundleRelease

Gradle's bundleRelease will bundle all the JavaScript needed to run your app into the AAB (Android App Bundle). If you need to change the way the JavaScript bundle and/or drawable resources are bundled (e.g. if you changed the default file/folder names or the general structure of the project), have a look at android/app/build.gradle to see how you can update it to reflect these changes.

Note: Make sure gradle.properties does not include org.gradle.configureondemand=true as that will make the release build skip bundling JS and assets into the app binary.

The generated AAB can be found under android/app/build/outputs/bundle/release/app.aab, and is ready to be uploaded to Google Play.

Note: In order for Google Play to accept AAB format the App Signing by Google Play needs to be configured for your application on the Google Play Console. If you are updating an existing app that doesn't use App Signing by Google Play, please check our migration section to learn how to perform that configuration change.

Testing the release build of your app

Before uploading the release build to the Play Store, make sure you test it thoroughly. First uninstall any previous version of the app you already have installed. Install it on the device using:

$ npx react-native run-android --variant=release

Note that --variant=release is only available if you've set up signing as described above.

You can terminate any running bundler instances, since all your framework and JavaScript code is bundled in the APK's assets.

Publishing to other stores

By default, the generated APK has the native code for both x86 and ARMv7a CPU architectures. This makes it easier to share APKs that run on almost all Android devices. However, this has the downside that there will be some unused native code on any device, leading to unnecessarily bigger APKs.

You can create an APK for each CPU by changing the following line in android/app/build.gradle:

- ndk {
- abiFilters "armeabi-v7a", "x86"
- }
- def enableSeparateBuildPerCPUArchitecture = false
+ def enableSeparateBuildPerCPUArchitecture = true

Upload both these files to markets which support device targeting, such as Google Play and Amazon AppStore, and the users will automatically get the appropriate APK. If you want to upload to other markets, such as APKFiles, which do not support multiple APKs for a single app, change the following line as well to create the default universal APK with binaries for both CPUs.

- universalApk false // If true, also generate a universal APK
+ universalApk true // If true, also generate a universal APK

Enabling Proguard to reduce the size of the APK (optional)

Proguard is a tool that can slightly reduce the size of the APK. It does this by stripping parts of the React Native Java bytecode (and its dependencies) that your app is not using.

IMPORTANT: Make sure to thoroughly test your app if you've enabled Proguard. Proguard often requires configuration specific to each native library you're using. See app/proguard-rules.pro.

To enable Proguard, edit android/app/build.gradle:

/**
* Run Proguard to shrink the Java bytecode in release builds.
*/
def enableProguardInReleaseBuilds = true

Migrating old Android React Native apps to use App Signing by Google Play

If you are migrating from previous version of React Native chances are your app does not use App Signing by Google Play feature. We recommend you enable that in order to take advantage from things like automatic app splitting. In order to migrate from the old way of signing you need to start by generating new upload key and then replacing release signing config in android/app/build.gradle to use the upload key instead of the release one (see section about adding signing config to gradle). Once that's done you should follow the instructions from Google Play Help website in order to send your original release key to Google Play.

Edit this page
Last updated on
- + diff --git a/docs/0.62/signed-apk-android/index.html b/docs/0.62/signed-apk-android/index.html index eab9fc2637b..02110738b85 100644 --- a/docs/0.62/signed-apk-android/index.html +++ b/docs/0.62/signed-apk-android/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Publishing to Google Play Store

Android requires that all apps be digitally signed with a certificate before they can be installed. In order to distribute your Android application via Google Play store it needs to be signed with a release key that then needs to be used for all future updates. Since 2017 it is possible for Google Play to manage signing releases automatically thanks to App Signing by Google Play functionality. However, before your application binary is uploaded to Google Play it needs to be signed with an upload key. The Signing Your Applications page on Android Developers documentation describes the topic in detail. This guide covers the process in brief, as well as lists the steps required to package the JavaScript bundle.

Generating an upload key

You can generate a private signing key using keytool. On Windows keytool must be run from C:\Program Files\Java\jdkx.x.x_x\bin.

$ keytool -genkeypair -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

This command prompts you for passwords for the keystore and key and for the Distinguished Name fields for your key. It then generates the keystore as a file called my-upload-key.keystore.

The keystore contains a single key, valid for 10000 days. The alias is a name that you will use later when signing your app, so remember to take note of the alias.

On Mac, if you're not sure where your JDK bin folder is, then perform the following command to find it:

$ /usr/libexec/java_home

It will output the directory of the JDK, which will look something like this:

/Library/Java/JavaVirtualMachines/jdkX.X.X_XXX.jdk/Contents/Home

Navigate to that directory by using the command $ cd /your/jdk/path and use the keytool command with sudo permission as shown below.

$ sudo keytool -genkey -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

Note: Remember to keep the keystore file private. In case you've lost upload key or it's been compromised you should follow these instructions.

Setting up Gradle variables

  1. Place the my-upload-key.keystore file under the android/app directory in your project folder.
  2. Edit the file ~/.gradle/gradle.properties or android/gradle.properties, and add the following (replace ***** with the correct keystore password, alias and key password),
MYAPP_UPLOAD_STORE_FILE=my-upload-key.keystore
MYAPP_UPLOAD_KEY_ALIAS=my-key-alias
MYAPP_UPLOAD_STORE_PASSWORD=*****
MYAPP_UPLOAD_KEY_PASSWORD=*****

These are going to be global Gradle variables, which we can later use in our Gradle config to sign our app.

Note about security: If you are not keen on storing your passwords in plaintext, and you are running OSX, you can also store your credentials in the Keychain Access app. Then you can skip the two last rows in ~/.gradle/gradle.properties.

Adding signing config to your app's Gradle config

The last configuration step that needs to be done is to setup release builds to be signed using upload key. Edit the file android/app/build.gradle in your project folder, and add the signing config,

...
android {
...
defaultConfig { ... }
signingConfigs {
release {
if (project.hasProperty('MYAPP_UPLOAD_STORE_FILE')) {
storeFile file(MYAPP_UPLOAD_STORE_FILE)
storePassword MYAPP_UPLOAD_STORE_PASSWORD
keyAlias MYAPP_UPLOAD_KEY_ALIAS
keyPassword MYAPP_UPLOAD_KEY_PASSWORD
}
}
}
buildTypes {
release {
...
signingConfig signingConfigs.release
}
}
}
...

Generating the release APK

Run the following in a terminal:

$ cd android
$ ./gradlew bundleRelease

Gradle's bundleRelease will bundle all the JavaScript needed to run your app into the AAB (Android App Bundle). If you need to change the way the JavaScript bundle and/or drawable resources are bundled (e.g. if you changed the default file/folder names or the general structure of the project), have a look at android/app/build.gradle to see how you can update it to reflect these changes.

Note: Make sure gradle.properties does not include org.gradle.configureondemand=true as that will make the release build skip bundling JS and assets into the app binary.

The generated AAB can be found under android/app/build/outputs/bundle/release/app.aab, and is ready to be uploaded to Google Play.

Note: In order for Google Play to accept AAB format the App Signing by Google Play needs to be configured for your application on the Google Play Console. If you are updating an existing app that doesn't use App Signing by Google Play, please check our migration section to learn how to perform that configuration change.

Testing the release build of your app

Before uploading the release build to the Play Store, make sure you test it thoroughly. First uninstall any previous version of the app you already have installed. Install it on the device using:

$ npx react-native run-android --variant=release

Note that --variant=release is only available if you've set up signing as described above.

You can terminate any running bundler instances, since all your framework and JavaScript code is bundled in the APK's assets.

Publishing to other stores

By default, the generated APK has the native code for both x86 and ARMv7a CPU architectures. This makes it easier to share APKs that run on almost all Android devices. However, this has the downside that there will be some unused native code on any device, leading to unnecessarily bigger APKs.

You can create an APK for each CPU by changing the following line in android/app/build.gradle:

- ndk {
- abiFilters "armeabi-v7a", "x86"
- }
- def enableSeparateBuildPerCPUArchitecture = false
+ def enableSeparateBuildPerCPUArchitecture = true

Upload both these files to markets which support device targeting, such as Google Play and Amazon AppStore, and the users will automatically get the appropriate APK. If you want to upload to other markets, such as APKFiles, which do not support multiple APKs for a single app, change the following line as well to create the default universal APK with binaries for both CPUs.

- universalApk false // If true, also generate a universal APK
+ universalApk true // If true, also generate a universal APK

Enabling Proguard to reduce the size of the APK (optional)

Proguard is a tool that can slightly reduce the size of the APK. It does this by stripping parts of the React Native Java bytecode (and its dependencies) that your app is not using.

IMPORTANT: Make sure to thoroughly test your app if you've enabled Proguard. Proguard often requires configuration specific to each native library you're using. See app/proguard-rules.pro.

To enable Proguard, edit android/app/build.gradle:

/**
* Run Proguard to shrink the Java bytecode in release builds.
*/
def enableProguardInReleaseBuilds = true

Migrating old Android React Native apps to use App Signing by Google Play

If you are migrating from previous version of React Native chances are your app does not use App Signing by Google Play feature. We recommend you enable that in order to take advantage from things like automatic app splitting. In order to migrate from the old way of signing you need to start by generating new upload key and then replacing release signing config in android/app/build.gradle to use the upload key instead of the release one (see section about adding signing config to gradle). Once that's done you should follow the instructions from Google Play Help website in order to send your original release key to Google Play.

Edit this page
Last updated on
- + diff --git a/docs/0.62/slider.html b/docs/0.62/slider.html index a8766d949bf..dcd3d0a6c87 100644 --- a/docs/0.62/slider.html +++ b/docs/0.62/slider.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 Slider

Deprecated. Use @react-native-community/slider instead.

A component used to select a single value from a range of values.

Reference

Props

Inherits View Props.

style

Used to style and layout the Slider. See StyleSheet.js and ViewStylePropTypes.js for more info.

TypeRequired
View.styleNo

disabled

If true the user won't be able to move the slider. Default value is false.

TypeRequired
boolNo

maximumValue

Initial maximum value of the slider. Default value is 1.

TypeRequired
numberNo

minimumTrackTintColor

The color used for the track to the left of the button. Overrides the default blue gradient image on iOS.

TypeRequired
colorNo

minimumValue

Initial minimum value of the slider. Default value is 0.

TypeRequired
numberNo

onSlidingComplete

Callback that is called when the user releases the slider, regardless if the value has changed. The current value is passed as an argument to the callback handler.

TypeRequired
functionNo

onValueChange

Callback continuously called while the user is dragging the slider.

TypeRequired
functionNo

step

Step value of the slider. The value should be between 0 and (maximumValue - minimumValue). Default value is 0.

TypeRequired
numberNo

maximumTrackTintColor

The color used for the track to the right of the button. Overrides the default gray gradient image on iOS.

TypeRequired
colorNo

testID

Used to locate this view in UI automation tests.

TypeRequired
stringNo

value

Initial value of the slider. The value should be between minimumValue and maximumValue, which default to 0 and 1 respectively. Default value is 0.

This is not a controlled component, you don't need to update the value during dragging.

TypeRequired
numberNo

thumbTintColor

The color used to tint the default thumb images on iOS, or the color of the foreground switch grip on Android.

TypeRequired
colorNo

maximumTrackImage

Assigns a maximum track image. Only static images are supported. The leftmost pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

minimumTrackImage

Assigns a minimum track image. Only static images are supported. The rightmost pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

thumbImage

Sets an image for the thumb. Only static images are supported.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

trackImage

Assigns a single image for the track. Only static images are supported. The center pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.62/slider/index.html b/docs/0.62/slider/index.html index a8766d949bf..dcd3d0a6c87 100644 --- a/docs/0.62/slider/index.html +++ b/docs/0.62/slider/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 Slider

Deprecated. Use @react-native-community/slider instead.

A component used to select a single value from a range of values.

Reference

Props

Inherits View Props.

style

Used to style and layout the Slider. See StyleSheet.js and ViewStylePropTypes.js for more info.

TypeRequired
View.styleNo

disabled

If true the user won't be able to move the slider. Default value is false.

TypeRequired
boolNo

maximumValue

Initial maximum value of the slider. Default value is 1.

TypeRequired
numberNo

minimumTrackTintColor

The color used for the track to the left of the button. Overrides the default blue gradient image on iOS.

TypeRequired
colorNo

minimumValue

Initial minimum value of the slider. Default value is 0.

TypeRequired
numberNo

onSlidingComplete

Callback that is called when the user releases the slider, regardless if the value has changed. The current value is passed as an argument to the callback handler.

TypeRequired
functionNo

onValueChange

Callback continuously called while the user is dragging the slider.

TypeRequired
functionNo

step

Step value of the slider. The value should be between 0 and (maximumValue - minimumValue). Default value is 0.

TypeRequired
numberNo

maximumTrackTintColor

The color used for the track to the right of the button. Overrides the default gray gradient image on iOS.

TypeRequired
colorNo

testID

Used to locate this view in UI automation tests.

TypeRequired
stringNo

value

Initial value of the slider. The value should be between minimumValue and maximumValue, which default to 0 and 1 respectively. Default value is 0.

This is not a controlled component, you don't need to update the value during dragging.

TypeRequired
numberNo

thumbTintColor

The color used to tint the default thumb images on iOS, or the color of the foreground switch grip on Android.

TypeRequired
colorNo

maximumTrackImage

Assigns a maximum track image. Only static images are supported. The leftmost pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

minimumTrackImage

Assigns a minimum track image. Only static images are supported. The rightmost pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

thumbImage

Sets an image for the thumb. Only static images are supported.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

trackImage

Assigns a single image for the track. Only static images are supported. The center pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.62/snapshotviewios.html b/docs/0.62/snapshotviewios.html index c7241d960fe..e7b703b8556 100644 --- a/docs/0.62/snapshotviewios.html +++ b/docs/0.62/snapshotviewios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.62/snapshotviewios/index.html b/docs/0.62/snapshotviewios/index.html index c7241d960fe..e7b703b8556 100644 --- a/docs/0.62/snapshotviewios/index.html +++ b/docs/0.62/snapshotviewios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Edit this page
Last updated on
- + diff --git a/docs/0.62/state.html b/docs/0.62/state.html index 419e1c9f1d1..6669547b372 100644 --- a/docs/0.62/state.html +++ b/docs/0.62/state.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

State

There are two types of data that control a component: props and state. props are set by the parent and they are fixed throughout the lifetime of a component. For data that is going to change, we have to use state.

In general, you should initialize state in the constructor, and then call setState when you want to change it.

For example, let's say we want to make text that blinks all the time. The text itself gets set once when the blinking component gets created, so the text itself is a prop. The "whether the text is currently on or off" changes over time, so that should be kept in state.

In a real application, you probably won't be setting state with a timer. You might set state when you have new data from the server, or from user input. You can also use a state container like Redux or Mobx to control your data flow. In that case you would use Redux or Mobx to modify your state rather than calling setState directly.

When setState is called, BlinkApp will re-render its Component. By calling setState within the Timer, the component will re-render every time the Timer ticks.

State works the same way as it does in React, so for more details on handling state, you can look at the React.Component API. At this point, you may have noticed that most of our examples use the default text color. To customize the text color, you will have to learn about Style.

Edit this page
Last updated on
- + diff --git a/docs/0.62/state/index.html b/docs/0.62/state/index.html index 419e1c9f1d1..6669547b372 100644 --- a/docs/0.62/state/index.html +++ b/docs/0.62/state/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

State

There are two types of data that control a component: props and state. props are set by the parent and they are fixed throughout the lifetime of a component. For data that is going to change, we have to use state.

In general, you should initialize state in the constructor, and then call setState when you want to change it.

For example, let's say we want to make text that blinks all the time. The text itself gets set once when the blinking component gets created, so the text itself is a prop. The "whether the text is currently on or off" changes over time, so that should be kept in state.

In a real application, you probably won't be setting state with a timer. You might set state when you have new data from the server, or from user input. You can also use a state container like Redux or Mobx to control your data flow. In that case you would use Redux or Mobx to modify your state rather than calling setState directly.

When setState is called, BlinkApp will re-render its Component. By calling setState within the Timer, the component will re-render every time the Timer ticks.

State works the same way as it does in React, so for more details on handling state, you can look at the React.Component API. At this point, you may have noticed that most of our examples use the default text color. To customize the text color, you will have to learn about Style.

Edit this page
Last updated on
- + diff --git a/docs/0.62/statusbar.html b/docs/0.62/statusbar.html index 8a6daecb78c..c1aa9d0229b 100644 --- a/docs/0.62/statusbar.html +++ b/docs/0.62/statusbar.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

StatusBar

Component to control the app status bar.

Usage with Navigator

It is possible to have multiple StatusBar components mounted at the same time. The props will be merged in the order the StatusBar components were mounted.

Imperative API

For cases where using a component is not ideal, there is also an imperative API exposed as static functions on the component. It is however not recommended to use the static API and the component for the same prop because any value set by the static API will get overridden by the one set by the component in the next render.

Reference

Constants

currentHeight (Android only) The height of the status bar.

Props

animated

If the transition between status bar property changes should be animated. Supported for backgroundColor, barStyle and hidden.

TypeRequired
boolNo

backgroundColor

The background color of the status bar.

TypeRequiredPlatform
colorNoAndroid

barStyle

Sets the color of the status bar text.

TypeRequired
enum('default', 'light-content', 'dark-content')No

hidden

If the status bar is hidden.

TypeRequired
boolNo

networkActivityIndicatorVisible

If the network activity indicator should be visible.

TypeRequiredPlatform
boolNoiOS

showHideTransition

The transition effect when showing and hiding the status bar using the hidden prop. Defaults to 'fade'.

TypeRequiredPlatform
enum('fade', 'slide')NoiOS

translucent

If the status bar is translucent. When translucent is set to true, the app will draw under the status bar. This is useful when using a semi transparent status bar color.

TypeRequiredPlatform
boolNoAndroid

Methods

popStackEntry()

static popStackEntry(entry: any)

Get and remove the last StatusBar entry from the stack.

Parameters:

NameTypeRequiredDescription
entryanyYesEntry returned from pushStackEntry.

pushStackEntry()

static pushStackEntry(props: any)

Push a StatusBar entry onto the stack. The return value should be passed to popStackEntry when complete.

Parameters:

NameTypeRequiredDescription
propsanyYesObject containing the StatusBar props to use in the stack entry.

replaceStackEntry()

static replaceStackEntry(entry: any, props: any)

Replace an existing StatusBar stack entry with new props.

Parameters:

NameTypeRequiredDescription
entryanyYesEntry returned from pushStackEntry to replace.
propsanyYesObject containing the StatusBar props to use in the replacement stack entry.

setBackgroundColor()

static setBackgroundColor(color: string, [animated]: boolean)

Set the background color for the status bar. Android-only

Parameters:

NameTypeRequiredDescription
colorstringYesBackground color.
animatedbooleanNoAnimate the style change.

setBarStyle()

static setBarStyle(style: StatusBarStyle, [animated]: boolean)

Set the status bar style

Parameters:

NameTypeRequiredDescription
styleStatusBarStyleYesStatus bar style to set
animatedbooleanNoAnimate the style change.

setHidden()

static setHidden(hidden: boolean, [animation]: StatusBarAnimation)

Show or hide the status bar

Parameters:

NameTypeRequiredDescription
hiddenbooleanYesHide the status bar.
animationStatusBarAnimationNoOptional animation when changing the status bar hidden property.

setNetworkActivityIndicatorVisible()

static setNetworkActivityIndicatorVisible(visible: boolean)

Control the visibility of the network activity indicator. iOS-only.

Parameters:

NameTypeRequiredDescription
visiblebooleanYesShow the indicator.

setTranslucent()

static setTranslucent(translucent: boolean)

Control the translucency of the status bar. Android-only.

Parameters:

NameTypeRequiredDescription
translucentbooleanYesSet as translucent.

Type Definitions

StatusBarAnimation

Status bar animation

Type
\$Enum

Constants:

ValueDescription
noneNo animation
fadeFade animation
slideSlide animation

StatusBarStyle

Status bar style

Type
\$Enum

Constants:

ValueDescription
defaultDefault status bar style (dark for iOS, light for Android)
light-contentDark background, white texts and icons
dark-contentLight background, dark texts and icons (requires API>=23 on Android)
Edit this page
Last updated on
- + diff --git a/docs/0.62/statusbar/index.html b/docs/0.62/statusbar/index.html index 8a6daecb78c..c1aa9d0229b 100644 --- a/docs/0.62/statusbar/index.html +++ b/docs/0.62/statusbar/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

StatusBar

Component to control the app status bar.

Usage with Navigator

It is possible to have multiple StatusBar components mounted at the same time. The props will be merged in the order the StatusBar components were mounted.

Imperative API

For cases where using a component is not ideal, there is also an imperative API exposed as static functions on the component. It is however not recommended to use the static API and the component for the same prop because any value set by the static API will get overridden by the one set by the component in the next render.

Reference

Constants

currentHeight (Android only) The height of the status bar.

Props

animated

If the transition between status bar property changes should be animated. Supported for backgroundColor, barStyle and hidden.

TypeRequired
boolNo

backgroundColor

The background color of the status bar.

TypeRequiredPlatform
colorNoAndroid

barStyle

Sets the color of the status bar text.

TypeRequired
enum('default', 'light-content', 'dark-content')No

hidden

If the status bar is hidden.

TypeRequired
boolNo

networkActivityIndicatorVisible

If the network activity indicator should be visible.

TypeRequiredPlatform
boolNoiOS

showHideTransition

The transition effect when showing and hiding the status bar using the hidden prop. Defaults to 'fade'.

TypeRequiredPlatform
enum('fade', 'slide')NoiOS

translucent

If the status bar is translucent. When translucent is set to true, the app will draw under the status bar. This is useful when using a semi transparent status bar color.

TypeRequiredPlatform
boolNoAndroid

Methods

popStackEntry()

static popStackEntry(entry: any)

Get and remove the last StatusBar entry from the stack.

Parameters:

NameTypeRequiredDescription
entryanyYesEntry returned from pushStackEntry.

pushStackEntry()

static pushStackEntry(props: any)

Push a StatusBar entry onto the stack. The return value should be passed to popStackEntry when complete.

Parameters:

NameTypeRequiredDescription
propsanyYesObject containing the StatusBar props to use in the stack entry.

replaceStackEntry()

static replaceStackEntry(entry: any, props: any)

Replace an existing StatusBar stack entry with new props.

Parameters:

NameTypeRequiredDescription
entryanyYesEntry returned from pushStackEntry to replace.
propsanyYesObject containing the StatusBar props to use in the replacement stack entry.

setBackgroundColor()

static setBackgroundColor(color: string, [animated]: boolean)

Set the background color for the status bar. Android-only

Parameters:

NameTypeRequiredDescription
colorstringYesBackground color.
animatedbooleanNoAnimate the style change.

setBarStyle()

static setBarStyle(style: StatusBarStyle, [animated]: boolean)

Set the status bar style

Parameters:

NameTypeRequiredDescription
styleStatusBarStyleYesStatus bar style to set
animatedbooleanNoAnimate the style change.

setHidden()

static setHidden(hidden: boolean, [animation]: StatusBarAnimation)

Show or hide the status bar

Parameters:

NameTypeRequiredDescription
hiddenbooleanYesHide the status bar.
animationStatusBarAnimationNoOptional animation when changing the status bar hidden property.

setNetworkActivityIndicatorVisible()

static setNetworkActivityIndicatorVisible(visible: boolean)

Control the visibility of the network activity indicator. iOS-only.

Parameters:

NameTypeRequiredDescription
visiblebooleanYesShow the indicator.

setTranslucent()

static setTranslucent(translucent: boolean)

Control the translucency of the status bar. Android-only.

Parameters:

NameTypeRequiredDescription
translucentbooleanYesSet as translucent.

Type Definitions

StatusBarAnimation

Status bar animation

Type
\$Enum

Constants:

ValueDescription
noneNo animation
fadeFade animation
slideSlide animation

StatusBarStyle

Status bar style

Type
\$Enum

Constants:

ValueDescription
defaultDefault status bar style (dark for iOS, light for Android)
light-contentDark background, white texts and icons
dark-contentLight background, dark texts and icons (requires API>=23 on Android)
Edit this page
Last updated on
- + diff --git a/docs/0.62/statusbarios.html b/docs/0.62/statusbarios.html index ae02867494a..9ee8b4677c2 100644 --- a/docs/0.62/statusbarios.html +++ b/docs/0.62/statusbarios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 StatusBarIOS

Deprecated. Use StatusBar for mutating the status bar.

Edit this page
Last updated on
- + diff --git a/docs/0.62/statusbarios/index.html b/docs/0.62/statusbarios/index.html index ae02867494a..9ee8b4677c2 100644 --- a/docs/0.62/statusbarios/index.html +++ b/docs/0.62/statusbarios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 StatusBarIOS

Deprecated. Use StatusBar for mutating the status bar.

Edit this page
Last updated on
- + diff --git a/docs/0.62/style.html b/docs/0.62/style.html index f682142f73c..d5c7ebf3aff 100644 --- a/docs/0.62/style.html +++ b/docs/0.62/style.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Style

With React Native, you style your application using JavaScript. All of the core components accept a prop named style. The style names and values usually match how CSS works on the web, except names are written using camel casing, e.g. backgroundColor rather than background-color.

The style prop can be a plain old JavaScript object. That's what we usually use for example code. You can also pass an array of styles - the last style in the array has precedence, so you can use this to inherit styles.

As a component grows in complexity, it is often cleaner to use StyleSheet.create to define several styles in one place. Here's an example:

One common pattern is to make your component accept a style prop which in turn is used to style subcomponents. You can use this to make styles "cascade" the way they do in CSS.

There are a lot more ways to customize text style. Check out the Text component reference for a complete list.

Now you can make your text beautiful. The next step in becoming a style expert is to learn how to control component size.

Edit this page
Last updated on
- + diff --git a/docs/0.62/style/index.html b/docs/0.62/style/index.html index f682142f73c..d5c7ebf3aff 100644 --- a/docs/0.62/style/index.html +++ b/docs/0.62/style/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Style

With React Native, you style your application using JavaScript. All of the core components accept a prop named style. The style names and values usually match how CSS works on the web, except names are written using camel casing, e.g. backgroundColor rather than background-color.

The style prop can be a plain old JavaScript object. That's what we usually use for example code. You can also pass an array of styles - the last style in the array has precedence, so you can use this to inherit styles.

As a component grows in complexity, it is often cleaner to use StyleSheet.create to define several styles in one place. Here's an example:

One common pattern is to make your component accept a style prop which in turn is used to style subcomponents. You can use this to make styles "cascade" the way they do in CSS.

There are a lot more ways to customize text style. Check out the Text component reference for a complete list.

Now you can make your text beautiful. The next step in becoming a style expert is to learn how to control component size.

Edit this page
Last updated on
- + diff --git a/docs/0.62/stylesheet.html b/docs/0.62/stylesheet.html index 0842272a3fe..f5e0fa544a1 100644 --- a/docs/0.62/stylesheet.html +++ b/docs/0.62/stylesheet.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

StyleSheet

A StyleSheet is an abstraction similar to CSS StyleSheets

Code quality tips:

  • By moving styles away from the render function, you're making the code easier to understand.
  • Naming the styles is a good way to add meaning to the low level components in the render function.

Reference

Methods

compose()

static compose(style1: object, style2: object): object | array<object>

Combines two styles such that style2 will override any styles in style1. If either style is falsy, the other one is returned without allocating an array, saving allocations and maintaining reference equality for PureComponent checks.

create()

static create(obj: object): object

Creates a StyleSheet style reference from the given object.

flatten()

static flatten(style: array<object>): object

Flattens an array of style objects, into one aggregated style object. Alternatively, this method can be used to lookup IDs, returned by StyleSheet.register.

NOTE: Exercise caution as abusing this can tax you in terms of optimizations. IDs enable optimizations through the bridge and memory in general. Referring to style objects directly will deprive you of these optimizations.

This method internally uses StyleSheetRegistry.getStyleByID(style) to resolve style objects represented by IDs. Thus, an array of style objects (instances of StyleSheet.create()), are individually resolved to, their respective objects, merged as one and then returned. This also explains the alternative use.

setStyleAttributePreprocessor()

WARNING: EXPERIMENTAL. Breaking changes will probably happen a lot and will not be reliably announced. The whole thing might be deleted, who knows? Use at your own risk.

static setStyleAttributePreprocessor(property: string, process: (propValue: any) => any)

Sets a function to use to pre-process a style property value. This is used internally to process color and transform values. You should not use this unless you really know what you are doing and have exhausted other options.

Properties

absoluteFill

A very common pattern is to create overlays with position absolute and zero positioning (position: 'absolute', left: 0, right: 0, top: 0, bottom: 0), so absoluteFill can be used for convenience and to reduce duplication of these repeated styles. If you want, absoluteFill can be used to create a customized entry in a StyleSheet, e.g.:

absoluteFillObject

Sometimes you may want absoluteFill but with a couple tweaks - absoluteFillObject can be used to create a customized entry in a StyleSheet, e.g.:

hairlineWidth

This is defined as the width of a thin line on the platform. It can be used as the thickness of a border or division between two elements. Example:

This constant will always be a round number of pixels (so a line defined by it can look crisp) and will try to match the standard width of a thin line on the underlying platform. However, you should not rely on it being a constant size, because on different platforms and screen densities its value may be calculated differently.

A line with hairline width may not be visible if your simulator is downscaled.

absoluteFill vs. absoluteFillObject

Currently, there is no difference between using absoluteFill vs. absoluteFillObject.

Edit this page
Last updated on
- + diff --git a/docs/0.62/stylesheet/index.html b/docs/0.62/stylesheet/index.html index 0842272a3fe..f5e0fa544a1 100644 --- a/docs/0.62/stylesheet/index.html +++ b/docs/0.62/stylesheet/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

StyleSheet

A StyleSheet is an abstraction similar to CSS StyleSheets

Code quality tips:

  • By moving styles away from the render function, you're making the code easier to understand.
  • Naming the styles is a good way to add meaning to the low level components in the render function.

Reference

Methods

compose()

static compose(style1: object, style2: object): object | array<object>

Combines two styles such that style2 will override any styles in style1. If either style is falsy, the other one is returned without allocating an array, saving allocations and maintaining reference equality for PureComponent checks.

create()

static create(obj: object): object

Creates a StyleSheet style reference from the given object.

flatten()

static flatten(style: array<object>): object

Flattens an array of style objects, into one aggregated style object. Alternatively, this method can be used to lookup IDs, returned by StyleSheet.register.

NOTE: Exercise caution as abusing this can tax you in terms of optimizations. IDs enable optimizations through the bridge and memory in general. Referring to style objects directly will deprive you of these optimizations.

This method internally uses StyleSheetRegistry.getStyleByID(style) to resolve style objects represented by IDs. Thus, an array of style objects (instances of StyleSheet.create()), are individually resolved to, their respective objects, merged as one and then returned. This also explains the alternative use.

setStyleAttributePreprocessor()

WARNING: EXPERIMENTAL. Breaking changes will probably happen a lot and will not be reliably announced. The whole thing might be deleted, who knows? Use at your own risk.

static setStyleAttributePreprocessor(property: string, process: (propValue: any) => any)

Sets a function to use to pre-process a style property value. This is used internally to process color and transform values. You should not use this unless you really know what you are doing and have exhausted other options.

Properties

absoluteFill

A very common pattern is to create overlays with position absolute and zero positioning (position: 'absolute', left: 0, right: 0, top: 0, bottom: 0), so absoluteFill can be used for convenience and to reduce duplication of these repeated styles. If you want, absoluteFill can be used to create a customized entry in a StyleSheet, e.g.:

absoluteFillObject

Sometimes you may want absoluteFill but with a couple tweaks - absoluteFillObject can be used to create a customized entry in a StyleSheet, e.g.:

hairlineWidth

This is defined as the width of a thin line on the platform. It can be used as the thickness of a border or division between two elements. Example:

This constant will always be a round number of pixels (so a line defined by it can look crisp) and will try to match the standard width of a thin line on the underlying platform. However, you should not rely on it being a constant size, because on different platforms and screen densities its value may be calculated differently.

A line with hairline width may not be visible if your simulator is downscaled.

absoluteFill vs. absoluteFillObject

Currently, there is no difference between using absoluteFill vs. absoluteFillObject.

Edit this page
Last updated on
- + diff --git a/docs/0.62/switch.html b/docs/0.62/switch.html index 77a834f3ba6..4986fb1e85f 100644 --- a/docs/0.62/switch.html +++ b/docs/0.62/switch.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Switch

Renders a boolean input.

This is a controlled component that requires an onValueChange callback that updates the value prop in order for the component to reflect user actions. If the value prop is not updated, the component will continue to render the supplied value prop instead of the expected result of any user actions.

Example

Reference

Props

Inherits View Props.

disabled

If true the user won't be able to toggle the switch. Default value is false.

TypeRequired
boolNo

ios_backgroundColor

On iOS, custom color for the background. This background color can be seen either when the switch value is false or when the switch is disabled (and the switch is translucent).

TypeRequired
colorNo

onChange

Invoked when the user tries to change the value of the switch. Receives the change event as an argument. If you want to only receive the new value, use onValueChange instead.

TypeRequired
functionNo

onValueChange

Invoked when the user tries to change the value of the switch. Receives the new value as an argument. If you want to instead receive an event, use onChange.

TypeRequired
functionNo

thumbColor

Color of the foreground switch grip. If this is set on iOS, the switch grip will lose its drop shadow.

TypeRequired
colorNo

trackColor

Custom colors for the switch track.

iOS: When the switch value is false, the track shrinks into the border. If you want to change the color of the background exposed by the shrunken track, use ios_backgroundColor.

TypeRequired
object: {false: color, true: color}No

value

The value of the switch. If true the switch will be turned on. Default value is false.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/switch/index.html b/docs/0.62/switch/index.html index 77a834f3ba6..4986fb1e85f 100644 --- a/docs/0.62/switch/index.html +++ b/docs/0.62/switch/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Switch

Renders a boolean input.

This is a controlled component that requires an onValueChange callback that updates the value prop in order for the component to reflect user actions. If the value prop is not updated, the component will continue to render the supplied value prop instead of the expected result of any user actions.

Example

Reference

Props

Inherits View Props.

disabled

If true the user won't be able to toggle the switch. Default value is false.

TypeRequired
boolNo

ios_backgroundColor

On iOS, custom color for the background. This background color can be seen either when the switch value is false or when the switch is disabled (and the switch is translucent).

TypeRequired
colorNo

onChange

Invoked when the user tries to change the value of the switch. Receives the change event as an argument. If you want to only receive the new value, use onValueChange instead.

TypeRequired
functionNo

onValueChange

Invoked when the user tries to change the value of the switch. Receives the new value as an argument. If you want to instead receive an event, use onChange.

TypeRequired
functionNo

thumbColor

Color of the foreground switch grip. If this is set on iOS, the switch grip will lose its drop shadow.

TypeRequired
colorNo

trackColor

Custom colors for the switch track.

iOS: When the switch value is false, the track shrinks into the border. If you want to change the color of the background exposed by the shrunken track, use ios_backgroundColor.

TypeRequired
object: {false: color, true: color}No

value

The value of the switch. If true the switch will be turned on. Default value is false.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/symbolication.html b/docs/0.62/symbolication.html index 20f898291b1..f985483ad93 100644 --- a/docs/0.62/symbolication.html +++ b/docs/0.62/symbolication.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Symbolicating a stack trace

If a React Native app throws an unhandled exception in a release build, the output may be obfuscated and hard to read:

07-15 10:58:25.820 18979 18998 E AndroidRuntime: FATAL EXCEPTION: mqt_native_modules
07-15 10:58:25.820 18979 18998 E AndroidRuntime: Process: com.awesomeproject, PID: 18979 07-15 10:58:25.820 18979 18998 E AndroidRuntime: com.facebook.react.common.JavascriptException: Failed, js engine: hermes, stack:
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132161
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132084
07-15 10:58:25.820 18979 18998 E AndroidRuntime: f@1:131854
07-15 10:58:25.820 18979 18998 E AndroidRuntime: anonymous@1:131119

The sections like p@1:132161 are minified function names and bytecode offsets. To debug the problem, you would instead want to translate it into file, line and function name: AwesomeProject/App.js:54:initializeMap. This is known as symbolication. You can symbolicate minified function names and bytecode like the above by passing metro-symbolicate a generated source map and the stack trace.

The metro-symbolicate package is installed by default in the React Native template project from setting up your development environment.

From a file containing the stacktrace:

npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map < stacktrace.txt

From adb logcatdirectly:

adb logcat -d | npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map

This will turn each minified function name and offset like p@1:132161 into the actual file- and function name AwesomeProject/App.js:54:initializeMap.

Notes on Sourcemaps

  • Multiple source maps may be generated by the build process. Make sure to used the one in the location shown in the examples.
  • Make sure that the source map you use corresponds to the exact commit of the crashing app. Small changes in source code can cause large differences in offsets.
  • If metro-symbolicate exits immediately with success, make sure the input comes from a pipe or redirection and not from a terminal.
Edit this page
Last updated on
- + diff --git a/docs/0.62/symbolication/index.html b/docs/0.62/symbolication/index.html index 20f898291b1..f985483ad93 100644 --- a/docs/0.62/symbolication/index.html +++ b/docs/0.62/symbolication/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Symbolicating a stack trace

If a React Native app throws an unhandled exception in a release build, the output may be obfuscated and hard to read:

07-15 10:58:25.820 18979 18998 E AndroidRuntime: FATAL EXCEPTION: mqt_native_modules
07-15 10:58:25.820 18979 18998 E AndroidRuntime: Process: com.awesomeproject, PID: 18979 07-15 10:58:25.820 18979 18998 E AndroidRuntime: com.facebook.react.common.JavascriptException: Failed, js engine: hermes, stack:
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132161
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132084
07-15 10:58:25.820 18979 18998 E AndroidRuntime: f@1:131854
07-15 10:58:25.820 18979 18998 E AndroidRuntime: anonymous@1:131119

The sections like p@1:132161 are minified function names and bytecode offsets. To debug the problem, you would instead want to translate it into file, line and function name: AwesomeProject/App.js:54:initializeMap. This is known as symbolication. You can symbolicate minified function names and bytecode like the above by passing metro-symbolicate a generated source map and the stack trace.

The metro-symbolicate package is installed by default in the React Native template project from setting up your development environment.

From a file containing the stacktrace:

npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map < stacktrace.txt

From adb logcatdirectly:

adb logcat -d | npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map

This will turn each minified function name and offset like p@1:132161 into the actual file- and function name AwesomeProject/App.js:54:initializeMap.

Notes on Sourcemaps

  • Multiple source maps may be generated by the build process. Make sure to used the one in the location shown in the examples.
  • Make sure that the source map you use corresponds to the exact commit of the crashing app. Small changes in source code can cause large differences in offsets.
  • If metro-symbolicate exits immediately with success, make sure the input comes from a pipe or redirection and not from a terminal.
Edit this page
Last updated on
- + diff --git a/docs/0.62/systrace.html b/docs/0.62/systrace.html index 641ed5a93d4..7b076fec244 100644 --- a/docs/0.62/systrace.html +++ b/docs/0.62/systrace.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Systrace

Systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.

Example

Systrace allows you to mark JavaScript (JS) events with a tag and an integer value. Capture the non-Timed JS events in EasyProfiler.

Reference

Methods

installReactHook()

static installReactHook(useFiber)

setEnabled()

static setEnabled(enabled)

isEnabled()

static isEnabled()

beginEvent()

static beginEvent(profileName?, args?)

beginEvent/endEvent for starting and then ending a profile within the same call stack frame.

endEvent()

static endEvent()

beginAsyncEvent()

static beginAsyncEvent(profileName?)

beginAsyncEvent/endAsyncEvent for starting and then ending a profile where the end can either occur on another thread or out of the current stack frame, eg await the returned cookie variable should be used as input into the endAsyncEvent call to end the profile.

endAsyncEvent()

static endAsyncEvent(profileName?, cookie?)

counterEvent()

static counterEvent(profileName?, value?)

Register the value to the profileName on the systrace timeline.

Edit this page
Last updated on
- + diff --git a/docs/0.62/systrace/index.html b/docs/0.62/systrace/index.html index 641ed5a93d4..7b076fec244 100644 --- a/docs/0.62/systrace/index.html +++ b/docs/0.62/systrace/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Systrace

Systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.

Example

Systrace allows you to mark JavaScript (JS) events with a tag and an integer value. Capture the non-Timed JS events in EasyProfiler.

Reference

Methods

installReactHook()

static installReactHook(useFiber)

setEnabled()

static setEnabled(enabled)

isEnabled()

static isEnabled()

beginEvent()

static beginEvent(profileName?, args?)

beginEvent/endEvent for starting and then ending a profile within the same call stack frame.

endEvent()

static endEvent()

beginAsyncEvent()

static beginAsyncEvent(profileName?)

beginAsyncEvent/endAsyncEvent for starting and then ending a profile where the end can either occur on another thread or out of the current stack frame, eg await the returned cookie variable should be used as input into the endAsyncEvent call to end the profile.

endAsyncEvent()

static endAsyncEvent(profileName?, cookie?)

counterEvent()

static counterEvent(profileName?, value?)

Register the value to the profileName on the systrace timeline.

Edit this page
Last updated on
- + diff --git a/docs/0.62/tabbarios-item.html b/docs/0.62/tabbarios-item.html index cf06495beff..da9932df284 100644 --- a/docs/0.62/tabbarios-item.html +++ b/docs/0.62/tabbarios-item.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

TabBarIOS.Item

Props

Reference

Props

selected

It specifies whether the children are visible or not. If you see a blank content, you probably forgot to add a selected one.

TypeRequired
boolNo

badge

Little red bubble that sits at the top right of the icon.

TypeRequired
string, ,numberNo

icon

A custom icon for the tab. It is ignored when a system icon is defined.

TypeRequired
Image.propTypes.sourceNo

onPress

Callback when this tab is being selected, you should change the state of your component to set selected={true}.

TypeRequired
functionNo

renderAsOriginal

If set to true it renders the image as original, it defaults to being displayed as a template

TypeRequired
boolNo

badgeColor

Background color for the badge. Available since iOS 10.

TypeRequired
colorNo

selectedIcon

A custom icon when the tab is selected. It is ignored when a system icon is defined. If left empty, the icon will be tinted in blue.

TypeRequired
Image.propTypes.sourceNo

style

React style object.

TypeRequired
View.styleNo

systemIcon

Items comes with a few predefined system icons. Note that if you are using them, the title and selectedIcon will be overridden with the system ones.

TypeRequired
enum('bookmarks', 'contacts', 'downloads', 'favorites', 'featured', 'history', 'more', 'most-recent', 'most-viewed', 'recents', 'search', 'top-rated')No

title

Text that appears under the icon. It is ignored when a system icon is defined.

TypeRequired
stringNo

isTVSelectable

(Apple TV only)* When set to true, this view will be focusable and navigable using the Apple TV remote.

TypeRequiredPlatform
boolNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.62/tabbarios-item/index.html b/docs/0.62/tabbarios-item/index.html index cf06495beff..da9932df284 100644 --- a/docs/0.62/tabbarios-item/index.html +++ b/docs/0.62/tabbarios-item/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

TabBarIOS.Item

Props

Reference

Props

selected

It specifies whether the children are visible or not. If you see a blank content, you probably forgot to add a selected one.

TypeRequired
boolNo

badge

Little red bubble that sits at the top right of the icon.

TypeRequired
string, ,numberNo

icon

A custom icon for the tab. It is ignored when a system icon is defined.

TypeRequired
Image.propTypes.sourceNo

onPress

Callback when this tab is being selected, you should change the state of your component to set selected={true}.

TypeRequired
functionNo

renderAsOriginal

If set to true it renders the image as original, it defaults to being displayed as a template

TypeRequired
boolNo

badgeColor

Background color for the badge. Available since iOS 10.

TypeRequired
colorNo

selectedIcon

A custom icon when the tab is selected. It is ignored when a system icon is defined. If left empty, the icon will be tinted in blue.

TypeRequired
Image.propTypes.sourceNo

style

React style object.

TypeRequired
View.styleNo

systemIcon

Items comes with a few predefined system icons. Note that if you are using them, the title and selectedIcon will be overridden with the system ones.

TypeRequired
enum('bookmarks', 'contacts', 'downloads', 'favorites', 'featured', 'history', 'more', 'most-recent', 'most-viewed', 'recents', 'search', 'top-rated')No

title

Text that appears under the icon. It is ignored when a system icon is defined.

TypeRequired
stringNo

isTVSelectable

(Apple TV only)* When set to true, this view will be focusable and navigable using the Apple TV remote.

TypeRequiredPlatform
boolNoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.62/tabbarios.html b/docs/0.62/tabbarios.html index 8298a53393b..5dc397725f0 100644 --- a/docs/0.62/tabbarios.html +++ b/docs/0.62/tabbarios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

TabBarIOS

Props

Reference

Props

barStyle

The style of the tab bar. Supported values are 'default', 'black'. Use 'black' instead of setting barTintColor to black. This produces a tab bar with the native iOS style with higher translucency.

TypeRequired
enum('default', 'black')No

barTintColor

Background color of the tab bar

TypeRequired
colorNo

itemPositioning

Specifies tab bar item positioning. Available values are:

  • fill - distributes items across the entire width of the tab bar
  • center - centers item in the available tab bar space
  • auto (default) - distributes items dynamically according to the user interface idiom. In a horizontally compact environment (e.g. iPhone 5) this value defaults to fill, in a horizontally regular one (e.g. iPad) it defaults to center.
TypeRequired
enum('fill', 'center', 'auto')No

style

TypeRequired
View.styleNo

tintColor

Color of the currently selected tab icon

TypeRequired
colorNo

translucent

A Boolean value that indicates whether the tab bar is translucent

TypeRequired
boolNo

unselectedItemTintColor

Color of unselected tab icons. Available since iOS 10.

TypeRequired
colorNo

unselectedTintColor

Color of text on unselected tabs

TypeRequired
colorNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/tabbarios/index.html b/docs/0.62/tabbarios/index.html index 8298a53393b..5dc397725f0 100644 --- a/docs/0.62/tabbarios/index.html +++ b/docs/0.62/tabbarios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

TabBarIOS

Props

Reference

Props

barStyle

The style of the tab bar. Supported values are 'default', 'black'. Use 'black' instead of setting barTintColor to black. This produces a tab bar with the native iOS style with higher translucency.

TypeRequired
enum('default', 'black')No

barTintColor

Background color of the tab bar

TypeRequired
colorNo

itemPositioning

Specifies tab bar item positioning. Available values are:

  • fill - distributes items across the entire width of the tab bar
  • center - centers item in the available tab bar space
  • auto (default) - distributes items dynamically according to the user interface idiom. In a horizontally compact environment (e.g. iPhone 5) this value defaults to fill, in a horizontally regular one (e.g. iPad) it defaults to center.
TypeRequired
enum('fill', 'center', 'auto')No

style

TypeRequired
View.styleNo

tintColor

Color of the currently selected tab icon

TypeRequired
colorNo

translucent

A Boolean value that indicates whether the tab bar is translucent

TypeRequired
boolNo

unselectedItemTintColor

Color of unselected tab icons. Available since iOS 10.

TypeRequired
colorNo

unselectedTintColor

Color of text on unselected tabs

TypeRequired
colorNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/testing-overview.html b/docs/0.62/testing-overview.html index 4efb4459084..36a8ccbb2ff 100644 --- a/docs/0.62/testing-overview.html +++ b/docs/0.62/testing-overview.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
const bananaElements = getAllByText('banana');
expect(bananaElements).toHaveLength(1); // expect 'banana' to be on the list
});

This example is not testing how some state changes when you call a function. It tests what happens when a user changes text in the TextInput and presses the Button!

Testing Rendered Output

Snapshot testing is an advanced kind of testing enabled by Jest. It is a very powerful and low-level tool, so extra attention is advised when using it.

A "component snapshot" is a JSX-like string created by a custom React serializer built into Jest. This serializer lets Jest translate React component trees to string that's human-readable. Put another way: a component snapshot is a textual representation of your component’s render output generated during a test run. It may look like this:

<Text
style={
Object {
"fontSize": 20,
"textAlign": "center",
}
}>
Welcome to React Native!
</Text>

With snapshot testing, you typically first implement your component and then run the snapshot test. The snapshot test then creates a snapshot and saves it to a file in your repo as a reference snapshot. The file is then committed and checked during code review. Any future changes to the component render output will change its snapshot, which will cause the test to fail. You then need to update the stored reference snapshot for the test to pass. That change again needs to be committed and reviewed.

Snapshots have several weak points:

Snapshots themselves do not ensure that your component render logic is correct, they are merely good at guarding against unexpected changes and for checking that the components in the React tree under test receive the expected props (styles and etc.).

We recommend that you only use small snapshots (see no-large-snapshots rule). If you want to test a change between two React component states, use snapshot-diff. When in doubt, prefer explicit expectations as described in the previous paragraph.

End-to-End Tests

In end-to-end (E2E) tests, you verify your app is working as expected on a device (or a simulator / emulator) from the user perspective.

This is done by building your app in the release configuration and running the tests against it. In E2E tests, you no longer think about React components, React Native APIs, Redux stores or any business logic. That is not the purpose of E2E tests and those are not even accessible to you during E2E testing.

Instead, E2E testing libraries allow you to find and control elements in the screen of your app: for example, you can actually tap buttons or insert text into TextInputs the same way a real user would. Then you can make assertions about whether or not a certain element exists in the app’s screen, whether or not it’s visible, what text it contains, and so on.

E2E tests give you the highest possible confidence that part of your app is working. The tradeoffs include:

Try to cover the vital parts of your app with E2E tests: authentication flow, core functionalities, payments, etc. Use faster JS tests for the non-vital parts of your app. The more tests you add, the higher your confidence, but also, the more time you'll spend maintaining and running them. Consider the tradeoffs and decide what's best for you.

There are several E2E testing tools available: in the React Native community, Detox is a popular framework because it’s tailored for React Native apps. Another popular library in the space of iOS and Android apps is Appium.

Summary

We hope you enjoyed reading and learned something from this guide. There are many ways you can test your apps. It may be hard to decide what to use at first. However, we believe it all will make sense once you start adding tests to your awesome React Native app. So what are you waiting for? Get your coverage up!

Links

This guide originally authored and contributed in full by Vojtech Novak.

Edit this page
Last updated on
- + diff --git a/docs/0.62/testing-overview/index.html b/docs/0.62/testing-overview/index.html index 4efb4459084..36a8ccbb2ff 100644 --- a/docs/0.62/testing-overview/index.html +++ b/docs/0.62/testing-overview/index.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
const bananaElements = getAllByText('banana');
expect(bananaElements).toHaveLength(1); // expect 'banana' to be on the list
});

This example is not testing how some state changes when you call a function. It tests what happens when a user changes text in the TextInput and presses the Button!

Testing Rendered Output

Snapshot testing is an advanced kind of testing enabled by Jest. It is a very powerful and low-level tool, so extra attention is advised when using it.

A "component snapshot" is a JSX-like string created by a custom React serializer built into Jest. This serializer lets Jest translate React component trees to string that's human-readable. Put another way: a component snapshot is a textual representation of your component’s render output generated during a test run. It may look like this:

<Text
style={
Object {
"fontSize": 20,
"textAlign": "center",
}
}>
Welcome to React Native!
</Text>

With snapshot testing, you typically first implement your component and then run the snapshot test. The snapshot test then creates a snapshot and saves it to a file in your repo as a reference snapshot. The file is then committed and checked during code review. Any future changes to the component render output will change its snapshot, which will cause the test to fail. You then need to update the stored reference snapshot for the test to pass. That change again needs to be committed and reviewed.

Snapshots have several weak points:

Snapshots themselves do not ensure that your component render logic is correct, they are merely good at guarding against unexpected changes and for checking that the components in the React tree under test receive the expected props (styles and etc.).

We recommend that you only use small snapshots (see no-large-snapshots rule). If you want to test a change between two React component states, use snapshot-diff. When in doubt, prefer explicit expectations as described in the previous paragraph.

End-to-End Tests

In end-to-end (E2E) tests, you verify your app is working as expected on a device (or a simulator / emulator) from the user perspective.

This is done by building your app in the release configuration and running the tests against it. In E2E tests, you no longer think about React components, React Native APIs, Redux stores or any business logic. That is not the purpose of E2E tests and those are not even accessible to you during E2E testing.

Instead, E2E testing libraries allow you to find and control elements in the screen of your app: for example, you can actually tap buttons or insert text into TextInputs the same way a real user would. Then you can make assertions about whether or not a certain element exists in the app’s screen, whether or not it’s visible, what text it contains, and so on.

E2E tests give you the highest possible confidence that part of your app is working. The tradeoffs include:

Try to cover the vital parts of your app with E2E tests: authentication flow, core functionalities, payments, etc. Use faster JS tests for the non-vital parts of your app. The more tests you add, the higher your confidence, but also, the more time you'll spend maintaining and running them. Consider the tradeoffs and decide what's best for you.

There are several E2E testing tools available: in the React Native community, Detox is a popular framework because it’s tailored for React Native apps. Another popular library in the space of iOS and Android apps is Appium.

Summary

We hope you enjoyed reading and learned something from this guide. There are many ways you can test your apps. It may be hard to decide what to use at first. However, we believe it all will make sense once you start adding tests to your awesome React Native app. So what are you waiting for? Get your coverage up!

Links

This guide originally authored and contributed in full by Vojtech Novak.

Edit this page
Last updated on
- + diff --git a/docs/0.62/text-style-props.html b/docs/0.62/text-style-props.html index 5778323de87..0adf7c7aa92 100644 --- a/docs/0.62/text-style-props.html +++ b/docs/0.62/text-style-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Text Style Props

Example

Reference

Props

textShadowOffset

TypeRequired
object: {width: number,height: number}No

color

TypeRequired
colorNo

fontSize

TypeRequired
numberNo

fontStyle

TypeRequired
enum('normal', 'italic')No

fontWeight

Specifies font weight. The values 'normal' and 'bold' are supported for most fonts. Not all fonts have a variant for each of the numeric values, in that case the closest one is chosen.

TypeRequired
enum('normal', 'bold', '100', '200', '300', '400', '500', '600', '700', '800', '900')No

lineHeight

TypeRequired
numberNo

textAlign

Specifies text alignment. The value 'justify' is only supported on iOS and fallbacks to left on Android.

TypeRequired
enum('auto', 'left', 'right', 'center', 'justify')No

textDecorationLine

TypeRequired
enum('none', 'underline', 'line-through', 'underline line-through')No

textShadowColor

TypeRequired
colorNo

fontFamily

TypeRequired
stringNo

textShadowRadius

TypeRequired
numberNo

includeFontPadding

Set to false to remove extra font padding intended to make space for certain ascenders / descenders. With some fonts, this padding can make text look slightly misaligned when centered vertically. For best results also set textAlignVertical to center. Default is true.

TypeRequiredPlatform
boolNoAndroid

textAlignVertical

TypeRequiredPlatform
enum('auto', 'top', 'bottom', 'center')NoAndroid

fontVariant

TypeRequiredPlatform
array of enum('small-caps', 'oldstyle-nums', 'lining-nums', 'tabular-nums', 'proportional-nums')NoiOS, Android >= 5.0

letterSpacing

TypeRequiredPlatform
numberNoiOS, Android >= 5.0

textDecorationColor

TypeRequiredPlatform
colorNoiOS

textDecorationStyle

TypeRequiredPlatform
enum('solid', 'double', 'dotted', 'dashed')NoiOS

textTransform

TypeRequired
enum('none', 'uppercase', 'lowercase', 'capitalize')No

writingDirection

TypeRequiredPlatform
enum('auto', 'ltr', 'rtl')NoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.62/text-style-props/index.html b/docs/0.62/text-style-props/index.html index 5778323de87..0adf7c7aa92 100644 --- a/docs/0.62/text-style-props/index.html +++ b/docs/0.62/text-style-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Text Style Props

Example

Reference

Props

textShadowOffset

TypeRequired
object: {width: number,height: number}No

color

TypeRequired
colorNo

fontSize

TypeRequired
numberNo

fontStyle

TypeRequired
enum('normal', 'italic')No

fontWeight

Specifies font weight. The values 'normal' and 'bold' are supported for most fonts. Not all fonts have a variant for each of the numeric values, in that case the closest one is chosen.

TypeRequired
enum('normal', 'bold', '100', '200', '300', '400', '500', '600', '700', '800', '900')No

lineHeight

TypeRequired
numberNo

textAlign

Specifies text alignment. The value 'justify' is only supported on iOS and fallbacks to left on Android.

TypeRequired
enum('auto', 'left', 'right', 'center', 'justify')No

textDecorationLine

TypeRequired
enum('none', 'underline', 'line-through', 'underline line-through')No

textShadowColor

TypeRequired
colorNo

fontFamily

TypeRequired
stringNo

textShadowRadius

TypeRequired
numberNo

includeFontPadding

Set to false to remove extra font padding intended to make space for certain ascenders / descenders. With some fonts, this padding can make text look slightly misaligned when centered vertically. For best results also set textAlignVertical to center. Default is true.

TypeRequiredPlatform
boolNoAndroid

textAlignVertical

TypeRequiredPlatform
enum('auto', 'top', 'bottom', 'center')NoAndroid

fontVariant

TypeRequiredPlatform
array of enum('small-caps', 'oldstyle-nums', 'lining-nums', 'tabular-nums', 'proportional-nums')NoiOS, Android >= 5.0

letterSpacing

TypeRequiredPlatform
numberNoiOS, Android >= 5.0

textDecorationColor

TypeRequiredPlatform
colorNoiOS

textDecorationStyle

TypeRequiredPlatform
enum('solid', 'double', 'dotted', 'dashed')NoiOS

textTransform

TypeRequired
enum('none', 'uppercase', 'lowercase', 'capitalize')No

writingDirection

TypeRequiredPlatform
enum('auto', 'ltr', 'rtl')NoiOS
Edit this page
Last updated on
- + diff --git a/docs/0.62/text.html b/docs/0.62/text.html index cd625cdade5..d2e6038dbfa 100644 --- a/docs/0.62/text.html +++ b/docs/0.62/text.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
// GOOD
<View>
<Text>
Some text
</Text>
</View>

You also lose the ability to set up a default font for an entire subtree. Meanwhile, fontFamily only accepts a single font name, which is different from font-family in CSS. The recommended way to use consistent fonts and sizes across your application is to create a component MyAppText that includes them and use this component across your app. You can also use this component to make more specific components like MyAppHeaderText for other kinds of text.

<View>
<MyAppText>
Text styled with the default font for the entire application
</MyAppText>
<MyAppHeaderText>Text styled as a header</MyAppHeaderText>
</View>

Assuming that MyAppText is a component that only renders out its children into a Text component with styling, then MyAppHeaderText can be defined as follows:

class MyAppHeaderText extends Component {
render() {
return (
<MyAppText>
<Text style={{ fontSize: 20 }}>
{this.props.children}
</Text>
</MyAppText>
);
}
}

Composing MyAppText in this way ensures that we get the styles from a top-level component, but leaves us the ability to add / override them in specific use cases.

React Native still has the concept of style inheritance, but limited to text subtrees. In this case, the second part will be both bold and red.

<Text style={{ fontWeight: 'bold' }}>
I am bold
<Text style={{ color: 'red' }}>and red</Text>
</Text>

We believe that this more constrained way to style text will yield better apps:

Reference

Props

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityRole

Tells the screen reader to treat the currently focused on element as having a specific role.

Possible values for AccessibilityRole is one of:

On iOS, these roles map to corresponding Accessibility Traits. Image button has the same functionality as if the trait was set to both 'image' and 'button'. See the Accessibility guide for more information.

On Android, these roles have similar functionality on TalkBack as adding Accessibility Traits does on Voiceover in iOS

TypeRequired
AccessibilityRoleNo

accessibilityState

Tells the screen reader to treat the currently focused on element as being in a specific state.

You can provide one state, no state, or multiple states. The states must be passed in through an object. Ex: {selected: true, disabled: true}.

Possible values for AccessibilityState are:

TypeRequired
objectNo

accessible

When set to true, indicates that the view is an accessibility element. The default value for a Text element is true.

See the Accessibility guide for more information.

TypeRequired
boolNo

adjustsFontSizeToFit

Specifies whether fonts should be scaled down automatically to fit given style constraints.

TypeRequired
boolNo

allowFontScaling

Specifies whether fonts should scale to respect Text Size accessibility settings. The default is true.

TypeRequired
boolNo

dataDetectorType

Determines the types of data converted to clickable URLs in the text element. By default no data types are detected.

You can provide only one type.

Possible values for dataDetectorType are:

TypeRequiredPlatform
enum('phoneNumber', 'link', 'email', 'none', 'all')NoAndroid

disabled

Specifies the disabled state of the text view for testing purposes

TypeRequiredPlatform
boolNoAndroid

ellipsizeMode

When numberOfLines is set, this prop defines how text will be truncated. numberOfLines must be set in conjunction with this prop.

This can be one of the following values:

The default is tail.

TypeRequired
enum('head', 'middle', 'tail', 'clip')No

maxFontSizeMultiplier

Specifies largest possible scale a font can reach when allowFontScaling is enabled. Possible values:

TypeRequired
numberNo

minimumFontScale

Specifies smallest possible scale a font can reach when adjustsFontSizeToFit is enabled. (values 0.01-1.0).

TypeRequiredPlatform
numberNoiOS

nativeID

Used to locate this view from native code.

TypeRequired
stringNo

numberOfLines

Used to truncate the text with an ellipsis after computing the text layout, including line wrapping, such that the total number of lines does not exceed this number.

This prop is commonly used with ellipsizeMode.

TypeRequired
numberNo

onLayout

Invoked on mount and layout changes with

{nativeEvent: {layout: {x, y, width, height}}}

TypeRequired
functionNo

onLongPress

This function is called on long press.

e.g., onLongPress={this.increaseSize}>

TypeRequired
functionNo

onMoveShouldSetResponder

Does this view want to "claim" touch responsiveness? This is called for every touch move on the View when it is not the responder.

View.props.onMoveShouldSetResponder: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onPress

This function is called on press.

e.g., onPress={() => console.log('1st')}

TypeRequired
functionNo

onResponderGrant

The View is now responding for touch events. This is the time to highlight and show the user what is happening.

View.props.onResponderGrant: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderMove

The user is moving their finger.

View.props.onResponderMove: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderRelease

Fired at the end of the touch.

View.props.onResponderRelease: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminate

The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS)

View.props.onResponderTerminate: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminationRequest

Some other View wants to become responder and is asking this View to release its responder. Returning true allows its release.

View.props.onResponderTerminationRequest: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onStartShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a touch start, it should have this handler which returns true.

View.props.onStartShouldSetResponderCapture: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onTextLayout

Invoked on Text layout

TypeRequired
function: (event: TextLayoutEvent) => mixedNo

pressRetentionOffset

When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

selectable

Lets the user select text, to use the native copy and paste functionality.

TypeRequired
boolNo

selectionColor

The highlight color of the text.

TypeRequiredPlatform
colorNoAndroid

style

TypeRequired
Text Style Props, View Style PropsNo

suppressHighlighting

When true, no visual change is made when text is pressed down. By default, a gray oval highlights the text on press down.

TypeRequiredPlatform
boolNoiOS

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

textBreakStrategy

Set text break strategy on Android API Level 23+, possible values are simple, highQuality, balanced The default value is highQuality.

TypeRequiredPlatform
enum('simple', 'highQuality', 'balanced')NoAndroid

Known issues

Edit this page
Last updated on
- + diff --git a/docs/0.62/text/index.html b/docs/0.62/text/index.html index cd625cdade5..d2e6038dbfa 100644 --- a/docs/0.62/text/index.html +++ b/docs/0.62/text/index.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
// GOOD
<View>
<Text>
Some text
</Text>
</View>

You also lose the ability to set up a default font for an entire subtree. Meanwhile, fontFamily only accepts a single font name, which is different from font-family in CSS. The recommended way to use consistent fonts and sizes across your application is to create a component MyAppText that includes them and use this component across your app. You can also use this component to make more specific components like MyAppHeaderText for other kinds of text.

<View>
<MyAppText>
Text styled with the default font for the entire application
</MyAppText>
<MyAppHeaderText>Text styled as a header</MyAppHeaderText>
</View>

Assuming that MyAppText is a component that only renders out its children into a Text component with styling, then MyAppHeaderText can be defined as follows:

class MyAppHeaderText extends Component {
render() {
return (
<MyAppText>
<Text style={{ fontSize: 20 }}>
{this.props.children}
</Text>
</MyAppText>
);
}
}

Composing MyAppText in this way ensures that we get the styles from a top-level component, but leaves us the ability to add / override them in specific use cases.

React Native still has the concept of style inheritance, but limited to text subtrees. In this case, the second part will be both bold and red.

<Text style={{ fontWeight: 'bold' }}>
I am bold
<Text style={{ color: 'red' }}>and red</Text>
</Text>

We believe that this more constrained way to style text will yield better apps:

Reference

Props

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityRole

Tells the screen reader to treat the currently focused on element as having a specific role.

Possible values for AccessibilityRole is one of:

On iOS, these roles map to corresponding Accessibility Traits. Image button has the same functionality as if the trait was set to both 'image' and 'button'. See the Accessibility guide for more information.

On Android, these roles have similar functionality on TalkBack as adding Accessibility Traits does on Voiceover in iOS

TypeRequired
AccessibilityRoleNo

accessibilityState

Tells the screen reader to treat the currently focused on element as being in a specific state.

You can provide one state, no state, or multiple states. The states must be passed in through an object. Ex: {selected: true, disabled: true}.

Possible values for AccessibilityState are:

TypeRequired
objectNo

accessible

When set to true, indicates that the view is an accessibility element. The default value for a Text element is true.

See the Accessibility guide for more information.

TypeRequired
boolNo

adjustsFontSizeToFit

Specifies whether fonts should be scaled down automatically to fit given style constraints.

TypeRequired
boolNo

allowFontScaling

Specifies whether fonts should scale to respect Text Size accessibility settings. The default is true.

TypeRequired
boolNo

dataDetectorType

Determines the types of data converted to clickable URLs in the text element. By default no data types are detected.

You can provide only one type.

Possible values for dataDetectorType are:

TypeRequiredPlatform
enum('phoneNumber', 'link', 'email', 'none', 'all')NoAndroid

disabled

Specifies the disabled state of the text view for testing purposes

TypeRequiredPlatform
boolNoAndroid

ellipsizeMode

When numberOfLines is set, this prop defines how text will be truncated. numberOfLines must be set in conjunction with this prop.

This can be one of the following values:

The default is tail.

TypeRequired
enum('head', 'middle', 'tail', 'clip')No

maxFontSizeMultiplier

Specifies largest possible scale a font can reach when allowFontScaling is enabled. Possible values:

TypeRequired
numberNo

minimumFontScale

Specifies smallest possible scale a font can reach when adjustsFontSizeToFit is enabled. (values 0.01-1.0).

TypeRequiredPlatform
numberNoiOS

nativeID

Used to locate this view from native code.

TypeRequired
stringNo

numberOfLines

Used to truncate the text with an ellipsis after computing the text layout, including line wrapping, such that the total number of lines does not exceed this number.

This prop is commonly used with ellipsizeMode.

TypeRequired
numberNo

onLayout

Invoked on mount and layout changes with

{nativeEvent: {layout: {x, y, width, height}}}

TypeRequired
functionNo

onLongPress

This function is called on long press.

e.g., onLongPress={this.increaseSize}>

TypeRequired
functionNo

onMoveShouldSetResponder

Does this view want to "claim" touch responsiveness? This is called for every touch move on the View when it is not the responder.

View.props.onMoveShouldSetResponder: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onPress

This function is called on press.

e.g., onPress={() => console.log('1st')}

TypeRequired
functionNo

onResponderGrant

The View is now responding for touch events. This is the time to highlight and show the user what is happening.

View.props.onResponderGrant: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderMove

The user is moving their finger.

View.props.onResponderMove: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderRelease

Fired at the end of the touch.

View.props.onResponderRelease: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminate

The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS)

View.props.onResponderTerminate: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminationRequest

Some other View wants to become responder and is asking this View to release its responder. Returning true allows its release.

View.props.onResponderTerminationRequest: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onStartShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a touch start, it should have this handler which returns true.

View.props.onStartShouldSetResponderCapture: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onTextLayout

Invoked on Text layout

TypeRequired
function: (event: TextLayoutEvent) => mixedNo

pressRetentionOffset

When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

selectable

Lets the user select text, to use the native copy and paste functionality.

TypeRequired
boolNo

selectionColor

The highlight color of the text.

TypeRequiredPlatform
colorNoAndroid

style

TypeRequired
Text Style Props, View Style PropsNo

suppressHighlighting

When true, no visual change is made when text is pressed down. By default, a gray oval highlights the text on press down.

TypeRequiredPlatform
boolNoiOS

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

textBreakStrategy

Set text break strategy on Android API Level 23+, possible values are simple, highQuality, balanced The default value is highQuality.

TypeRequiredPlatform
enum('simple', 'highQuality', 'balanced')NoAndroid

Known issues

Edit this page
Last updated on
- + diff --git a/docs/0.62/textinput.html b/docs/0.62/textinput.html index 1928ded68f3..569f8e1ee15 100644 --- a/docs/0.62/textinput.html +++ b/docs/0.62/textinput.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

TextInput

A foundational component for inputting text into the app via a keyboard. Props provide configurability for several features, such as auto-correction, auto-capitalization, placeholder text, and different keyboard types, such as a numeric keypad.

The most basic use case is to plop down a TextInput and subscribe to the onChangeText events to read the user input. There are also other events, such as onSubmitEditing and onFocus that can be subscribed to. A minimal example:

Two methods exposed via the native element are .focus() and .blur() that will focus or blur the TextInput programmatically.

Note that some props are only available with multiline={true/false}. Additionally, border styles that apply to only one side of the element (e.g., borderBottomColor, borderLeftWidth, etc.) will not be applied if multiline=false. To achieve the same effect, you can wrap your TextInput in a View:

TextInput has by default a border at the bottom of its view. This border has its padding set by the background image provided by the system, and it cannot be changed. Solutions to avoid this is to either not set height explicitly, case in which the system will take care of displaying the border in the correct position, or to not display the border by setting underlineColorAndroid to transparent.

Note that on Android performing text selection in input can change app's activity windowSoftInputMode param to adjustResize. This may cause issues with components that have position: 'absolute' while keyboard is active. To avoid this behavior either specify windowSoftInputMode in AndroidManifest.xml ( https://developer.android.com/guide/topics/manifest/activity-element.html ) or control this param programmatically with native code.

Reference

Props

Inherits View Props.

allowFontScaling

Specifies whether fonts should scale to respect Text Size accessibility settings. The default is true.

TypeRequired
boolNo

autoCapitalize

Can tell TextInput to automatically capitalize certain characters. This property is not supported by some keyboard types such as name-phone-pad.

  • characters: all characters.
  • words: first letter of each word.
  • sentences: first letter of each sentence (default).
  • none: don't auto capitalize anything.
TypeRequired
enum('none', 'sentences', 'words', 'characters')No

autoCompleteType

Specifies autocomplete hints for the system, so it can provide autofill. On Android, the system will always attempt to offer autofill by using heuristics to identify the type of content. To disable autocomplete, set autoCompleteType to off.

Possible values for autoCompleteType are:

  • off
  • username
  • password
  • email
  • name
  • tel
  • street-address
  • postal-code
  • cc-number
  • cc-csc
  • cc-exp
  • cc-exp-month
  • cc-exp-year
TypeRequiredPlatform
enum('off', 'username', 'password', 'email', 'name', 'tel', 'street-address', 'postal-code', 'cc-number', 'cc-csc', 'cc-exp', 'cc-exp-month', 'cc-exp-year')NoAndroid

autoCorrect

If false, disables auto-correct. The default value is true.

TypeRequired
boolNo

autoFocus

If true, focuses the input on componentDidMount. The default value is false.

TypeRequired
boolNo

blurOnSubmit

If true, the text field will blur when submitted. The default value is true for single-line fields and false for multiline fields. Note that for multiline fields, setting blurOnSubmit to true means that pressing return will blur the field and trigger the onSubmitEditing event instead of inserting a newline into the field.

TypeRequired
boolNo

caretHidden

If true, caret is hidden. The default value is false.

TypeRequired
boolNo

clearButtonMode

When the clear button should appear on the right side of the text view. This property is supported only for single-line TextInput component. The default value is never.

TypeRequiredPlatform
enum('never', 'while-editing', 'unless-editing', 'always')NoiOS

clearTextOnFocus

If true, clears the text field automatically when editing begins.

TypeRequiredPlatform
boolNoiOS

contextMenuHidden

If true, context menu is hidden. The default value is false.

TypeRequired
boolNo

dataDetectorTypes

Determines the types of data converted to clickable URLs in the text input. Only valid if multiline={true} and editable={false}. By default no data types are detected.

You can provide one type or an array of many types.

Possible values for dataDetectorTypes are:

  • 'phoneNumber'
  • 'link'
  • 'address'
  • 'calendarEvent'
  • 'none'
  • 'all'
TypeRequiredPlatform
enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all'), ,array of enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all')NoiOS

defaultValue

Provides an initial value that will change when the user starts typing. Useful for use-cases where you do not want to deal with listening to events and updating the value prop to keep the controlled state in sync.

TypeRequired
stringNo

disableFullscreenUI

When false, if there is a small amount of space available around a text input (e.g. landscape orientation on a phone), the OS may choose to have the user edit the text inside of a full screen text input mode. When true, this feature is disabled and users will always edit the text directly inside of the text input. Defaults to false.

TypeRequiredPlatform
boolNoAndroid

editable

If false, text is not editable. The default value is true.

TypeRequired
boolNo

enablesReturnKeyAutomatically

If true, the keyboard disables the return key when there is no text and automatically enables it when there is text. The default value is false.

TypeRequiredPlatform
boolNoiOS

importantForAutofill

Say the system whether the individual fields in your app should be included in a view structure for autofill purposes on Android API Level 26+, possible values are auto, no, noExcludeDescendants, yes, yesExcludeDescendants. The default value is auto.

  • auto: Let the Android System use its heuristics to determine if the view is important for autofill.
  • no: This view isn't important for autofill.
  • noExcludeDescendants: This view and its children aren't important for autofill.
  • yes: This view is important for autofill.
  • yesExcludeDescendants: This view is important for autofill, but its children aren't important for autofill.
TypeRequiredPlatform
enum('auto', 'no', 'noExcludeDescendants', 'yes', 'yesExcludeDescendants')NoAndroid

inlineImageLeft

If defined, the provided image resource will be rendered on the left. The image resource must be inside /android/app/src/main/res/drawable and referenced like

<TextInput
inlineImageLeft='search_icon'
/>
TypeRequiredPlatform
stringNoAndroid

inlineImagePadding

Padding between the inline image, if any, and the text input itself.

TypeRequiredPlatform
numberNoAndroid

inputAccessoryViewID

An optional identifier which links a custom InputAccessoryView to this text input. The InputAccessoryView is rendered above the keyboard when this text input is focused.

TypeRequiredPlatform
stringNoiOS

keyboardAppearance

Determines the color of the keyboard.

TypeRequiredPlatform
enum('default', 'light', 'dark')NoiOS

keyboardType

Determines which keyboard to open, e.g.numeric.

See screenshots of all the types here.

The following values work across platforms:

  • default
  • number-pad
  • decimal-pad
  • numeric
  • email-address
  • phone-pad

iOS Only

The following values work on iOS only:

  • ascii-capable
  • numbers-and-punctuation
  • url
  • name-phone-pad
  • twitter
  • web-search

Android Only

The following values work on Android only:

  • visible-password
TypeRequired
enum('default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter', 'web-search', 'visible-password')No

maxFontSizeMultiplier

Specifies largest possible scale a font can reach when allowFontScaling is enabled. Possible values:

  • null/undefined (default): inherit from the parent node or the global default (0)
  • 0: no max, ignore parent/global default
  • >= 1: sets the maxFontSizeMultiplier of this node to this value
TypeRequired
numberNo

maxLength

Limits the maximum number of characters that can be entered. Use this instead of implementing the logic in JS to avoid flicker.

TypeRequired
numberNo

multiline

If true, the text input can be multiple lines. The default value is false. It is important to note that this aligns the text to the top on iOS, and centers it on Android. Use with textAlignVertical set to top for the same behavior in both platforms.

TypeRequired
boolNo

numberOfLines

Sets the number of lines for a TextInput. Use it with multiline set to true to be able to fill the lines.

TypeRequiredPlatform
numberNoAndroid

onBlur

Callback that is called when the text input is blurred.

TypeRequired
functionNo

onChange

Callback that is called when the text input's text changes. This will be called with { nativeEvent: { eventCount, target, text} }

TypeRequired
functionNo

onChangeText

Callback that is called when the text input's text changes. Changed text is passed as a single string argument to the callback handler.

TypeRequired
functionNo

onContentSizeChange

Callback that is called when the text input's content size changes. This will be called with { nativeEvent: { contentSize: { width, height } } }.

Only called for multiline text inputs.

TypeRequired
functionNo

onEndEditing

Callback that is called when text input ends.

TypeRequired
functionNo

onFocus

Callback that is called when the text input is focused. This is called with { nativeEvent: { target } }.

TypeRequired
functionNo

onKeyPress

Callback that is called when a key is pressed. This will be called with { nativeEvent: { key: keyValue } } where keyValue is 'Enter' or 'Backspace' for respective keys and the typed-in character otherwise including ' ' for space. Fires before onChange callbacks. Note: on Android only the inputs from soft keyboard are handled, not the hardware keyboard inputs.

TypeRequired
functionNo

onLayout

Invoked on mount and layout changes with { nativeEvent: {layout: {x, y, width, height}, target } }.

TypeRequired
functionNo

onScroll

Invoked on content scroll with { nativeEvent: { contentOffset: { x, y } } }. May also contain other properties from ScrollEvent but on Android contentSize is not provided for performance reasons.

TypeRequired
functionNo

onSelectionChange

Callback that is called when the text input selection is changed. This will be called with { nativeEvent: { selection: { start, end } } }. This prop requires multiline={true} to be set.

TypeRequired
functionNo

onSubmitEditing

Callback that is called when the text input's submit button is pressed with the argument {nativeEvent: {text, eventCount, target}}.

TypeRequired
functionNo

Note that on iOS this method isn't called when using keyboardType="phone-pad".

placeholder

The string that will be rendered before text input has been entered.

TypeRequired
stringNo

placeholderTextColor

The text color of the placeholder string.

TypeRequired
colorNo

returnKeyLabel

Sets the return key to the label. Use it instead of returnKeyType.

TypeRequiredPlatform
stringNoAndroid

returnKeyType

Determines how the return key should look. On Android you can also use returnKeyLabel.

Cross platform

The following values work across platforms:

  • done
  • go
  • next
  • search
  • send

Android Only

The following values work on Android only:

  • none
  • previous

iOS Only

The following values work on iOS only:

  • default
  • emergency-call
  • google
  • join
  • route
  • yahoo
TypeRequired
enum('done', 'go', 'next', 'search', 'send', 'none', 'previous', 'default', 'emergency-call', 'google', 'join', 'route', 'yahoo')No

rejectResponderTermination

iOS Only

If true, allows TextInput to pass touch events to the parent component. This allows components such as SwipeableListView to be swipeable from the TextInput on iOS, as is the case on Android by default. If false, TextInput always asks to handle the input (except when disabled). The default value is true.

TypeRequiredPlatform
boolNoiOS

scrollEnabled

If false, scrolling of the text view will be disabled. The default value is true. Only works with multiline={true}.

TypeRequiredPlatform
boolNoiOS

secureTextEntry

If true, the text input obscures the text entered so that sensitive text like passwords stay secure. The default value is false. Does not work with multiline={true}.

TypeRequired
boolNo

selection

The start and end of the text input's selection. Set start and end to the same value to position the cursor.

TypeRequired
object: {start: number,end: number}No

selectionColor

The highlight and cursor color of the text input.

TypeRequired
colorNo

selectTextOnFocus

If true, all text will automatically be selected on focus.

TypeRequired
boolNo

showSoftInputOnFocus

When false, it will prevent the soft keyboard from showing when the field is focused. The default value is true.

TypeRequiredPlatform
boolNoAndroid

spellCheck

If false, disables spell-check style (i.e. red underlines). The default value is inherited from autoCorrect.

TypeRequiredPlatform
boolNoiOS

textAlign

Align the input text to the left, center, or right sides of the input field.

Possible values for textAlign are:

  • left
  • center
  • right
TypeRequired
enum('left', 'center', 'right')No

textContentType

Give the keyboard and the system information about the expected semantic meaning for the content that users enter.

For iOS 11+ you can set textContentType to username or password to enable autofill of login details from the device keychain.

For iOS 12+ newPassword can be used to indicate a new password input the user may want to save in the keychain, and oneTimeCode can be used to indicate that a field can be autofilled by a code arriving in an SMS.

To disable autofill, set textContentType to none.

Possible values for textContentType are:

  • none
  • URL
  • addressCity
  • addressCityAndState
  • addressState
  • countryName
  • creditCardNumber
  • emailAddress
  • familyName
  • fullStreetAddress
  • givenName
  • jobTitle
  • location
  • middleName
  • name
  • namePrefix
  • nameSuffix
  • nickname
  • organizationName
  • postalCode
  • streetAddressLine1
  • streetAddressLine2
  • sublocality
  • telephoneNumber
  • username
  • password
  • newPassword
  • oneTimeCode
TypeRequiredPlatform
enum('none', 'URL', 'addressCity', 'addressCityAndState', 'addressState', 'countryName', 'creditCardNumber', 'emailAddress', 'familyName', 'fullStreetAddress', 'givenName', 'jobTitle', 'location', 'middleName', 'name', 'namePrefix', 'nameSuffix', 'nickname', 'organizationName', 'postalCode', 'streetAddressLine1', 'streetAddressLine2', 'sublocality', 'telephoneNumber', 'username', 'password')NoiOS

passwordRules

When using textContentType as newPassword on iOS we can let the OS know the minimum requirements of the password so that it can generate one that will satisfy them. In order to create a valid string for PasswordRules take a look to the Apple Docs.

TypeRequiredPlatform
stringNoiOS

style

Note that not all Text styles are supported, an incomplete list of what is not supported includes:

  • borderLeftWidth
  • borderTopWidth
  • borderRightWidth
  • borderBottomWidth
  • borderTopLeftRadius
  • borderTopRightRadius
  • borderBottomRightRadius
  • borderBottomLeftRadius

see Issue#7070 for more detail.

Styles

TypeRequired
TextNo

textBreakStrategy

Set text break strategy on Android API Level 23+, possible values are simple, highQuality, balanced The default value is simple.

TypeRequiredPlatform
enum('simple', 'highQuality', 'balanced')NoAndroid

underlineColorAndroid

The color of the TextInput underline.

TypeRequiredPlatform
colorNoAndroid

value

The value to show for the text input. TextInput is a controlled component, which means the native value will be forced to match this value prop if provided. For most uses, this works great, but in some cases this may cause flickering - one common cause is preventing edits by keeping value the same. In addition to setting the same value, either set editable={false}, or set/update maxLength to prevent unwanted edits without flicker.

TypeRequired
stringNo

Methods

.focus()

focus();

Makes the native input request focus.

.blur()

blur();

Makes the native input lose focus.

clear()

clear();

Removes all text from the TextInput.

isFocused()

isFocused();

Returns true if the input is currently focused; false otherwise.

Known issues

  • react-native#19096: Doesn't support Android's onKeyPreIme.
  • react-native#19366: Calling .focus() after closing Android's keyboard via back button doesn't bring keyboard up again.
  • react-native#26799: Doesn't support Android's secureTextEntry when keyboardType="email-address" or keyboardType="phone-pad".
Edit this page
Last updated on
- + diff --git a/docs/0.62/textinput/index.html b/docs/0.62/textinput/index.html index 1928ded68f3..569f8e1ee15 100644 --- a/docs/0.62/textinput/index.html +++ b/docs/0.62/textinput/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

TextInput

A foundational component for inputting text into the app via a keyboard. Props provide configurability for several features, such as auto-correction, auto-capitalization, placeholder text, and different keyboard types, such as a numeric keypad.

The most basic use case is to plop down a TextInput and subscribe to the onChangeText events to read the user input. There are also other events, such as onSubmitEditing and onFocus that can be subscribed to. A minimal example:

Two methods exposed via the native element are .focus() and .blur() that will focus or blur the TextInput programmatically.

Note that some props are only available with multiline={true/false}. Additionally, border styles that apply to only one side of the element (e.g., borderBottomColor, borderLeftWidth, etc.) will not be applied if multiline=false. To achieve the same effect, you can wrap your TextInput in a View:

TextInput has by default a border at the bottom of its view. This border has its padding set by the background image provided by the system, and it cannot be changed. Solutions to avoid this is to either not set height explicitly, case in which the system will take care of displaying the border in the correct position, or to not display the border by setting underlineColorAndroid to transparent.

Note that on Android performing text selection in input can change app's activity windowSoftInputMode param to adjustResize. This may cause issues with components that have position: 'absolute' while keyboard is active. To avoid this behavior either specify windowSoftInputMode in AndroidManifest.xml ( https://developer.android.com/guide/topics/manifest/activity-element.html ) or control this param programmatically with native code.

Reference

Props

Inherits View Props.

allowFontScaling

Specifies whether fonts should scale to respect Text Size accessibility settings. The default is true.

TypeRequired
boolNo

autoCapitalize

Can tell TextInput to automatically capitalize certain characters. This property is not supported by some keyboard types such as name-phone-pad.

  • characters: all characters.
  • words: first letter of each word.
  • sentences: first letter of each sentence (default).
  • none: don't auto capitalize anything.
TypeRequired
enum('none', 'sentences', 'words', 'characters')No

autoCompleteType

Specifies autocomplete hints for the system, so it can provide autofill. On Android, the system will always attempt to offer autofill by using heuristics to identify the type of content. To disable autocomplete, set autoCompleteType to off.

Possible values for autoCompleteType are:

  • off
  • username
  • password
  • email
  • name
  • tel
  • street-address
  • postal-code
  • cc-number
  • cc-csc
  • cc-exp
  • cc-exp-month
  • cc-exp-year
TypeRequiredPlatform
enum('off', 'username', 'password', 'email', 'name', 'tel', 'street-address', 'postal-code', 'cc-number', 'cc-csc', 'cc-exp', 'cc-exp-month', 'cc-exp-year')NoAndroid

autoCorrect

If false, disables auto-correct. The default value is true.

TypeRequired
boolNo

autoFocus

If true, focuses the input on componentDidMount. The default value is false.

TypeRequired
boolNo

blurOnSubmit

If true, the text field will blur when submitted. The default value is true for single-line fields and false for multiline fields. Note that for multiline fields, setting blurOnSubmit to true means that pressing return will blur the field and trigger the onSubmitEditing event instead of inserting a newline into the field.

TypeRequired
boolNo

caretHidden

If true, caret is hidden. The default value is false.

TypeRequired
boolNo

clearButtonMode

When the clear button should appear on the right side of the text view. This property is supported only for single-line TextInput component. The default value is never.

TypeRequiredPlatform
enum('never', 'while-editing', 'unless-editing', 'always')NoiOS

clearTextOnFocus

If true, clears the text field automatically when editing begins.

TypeRequiredPlatform
boolNoiOS

contextMenuHidden

If true, context menu is hidden. The default value is false.

TypeRequired
boolNo

dataDetectorTypes

Determines the types of data converted to clickable URLs in the text input. Only valid if multiline={true} and editable={false}. By default no data types are detected.

You can provide one type or an array of many types.

Possible values for dataDetectorTypes are:

  • 'phoneNumber'
  • 'link'
  • 'address'
  • 'calendarEvent'
  • 'none'
  • 'all'
TypeRequiredPlatform
enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all'), ,array of enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all')NoiOS

defaultValue

Provides an initial value that will change when the user starts typing. Useful for use-cases where you do not want to deal with listening to events and updating the value prop to keep the controlled state in sync.

TypeRequired
stringNo

disableFullscreenUI

When false, if there is a small amount of space available around a text input (e.g. landscape orientation on a phone), the OS may choose to have the user edit the text inside of a full screen text input mode. When true, this feature is disabled and users will always edit the text directly inside of the text input. Defaults to false.

TypeRequiredPlatform
boolNoAndroid

editable

If false, text is not editable. The default value is true.

TypeRequired
boolNo

enablesReturnKeyAutomatically

If true, the keyboard disables the return key when there is no text and automatically enables it when there is text. The default value is false.

TypeRequiredPlatform
boolNoiOS

importantForAutofill

Say the system whether the individual fields in your app should be included in a view structure for autofill purposes on Android API Level 26+, possible values are auto, no, noExcludeDescendants, yes, yesExcludeDescendants. The default value is auto.

  • auto: Let the Android System use its heuristics to determine if the view is important for autofill.
  • no: This view isn't important for autofill.
  • noExcludeDescendants: This view and its children aren't important for autofill.
  • yes: This view is important for autofill.
  • yesExcludeDescendants: This view is important for autofill, but its children aren't important for autofill.
TypeRequiredPlatform
enum('auto', 'no', 'noExcludeDescendants', 'yes', 'yesExcludeDescendants')NoAndroid

inlineImageLeft

If defined, the provided image resource will be rendered on the left. The image resource must be inside /android/app/src/main/res/drawable and referenced like

<TextInput
inlineImageLeft='search_icon'
/>
TypeRequiredPlatform
stringNoAndroid

inlineImagePadding

Padding between the inline image, if any, and the text input itself.

TypeRequiredPlatform
numberNoAndroid

inputAccessoryViewID

An optional identifier which links a custom InputAccessoryView to this text input. The InputAccessoryView is rendered above the keyboard when this text input is focused.

TypeRequiredPlatform
stringNoiOS

keyboardAppearance

Determines the color of the keyboard.

TypeRequiredPlatform
enum('default', 'light', 'dark')NoiOS

keyboardType

Determines which keyboard to open, e.g.numeric.

See screenshots of all the types here.

The following values work across platforms:

  • default
  • number-pad
  • decimal-pad
  • numeric
  • email-address
  • phone-pad

iOS Only

The following values work on iOS only:

  • ascii-capable
  • numbers-and-punctuation
  • url
  • name-phone-pad
  • twitter
  • web-search

Android Only

The following values work on Android only:

  • visible-password
TypeRequired
enum('default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter', 'web-search', 'visible-password')No

maxFontSizeMultiplier

Specifies largest possible scale a font can reach when allowFontScaling is enabled. Possible values:

  • null/undefined (default): inherit from the parent node or the global default (0)
  • 0: no max, ignore parent/global default
  • >= 1: sets the maxFontSizeMultiplier of this node to this value
TypeRequired
numberNo

maxLength

Limits the maximum number of characters that can be entered. Use this instead of implementing the logic in JS to avoid flicker.

TypeRequired
numberNo

multiline

If true, the text input can be multiple lines. The default value is false. It is important to note that this aligns the text to the top on iOS, and centers it on Android. Use with textAlignVertical set to top for the same behavior in both platforms.

TypeRequired
boolNo

numberOfLines

Sets the number of lines for a TextInput. Use it with multiline set to true to be able to fill the lines.

TypeRequiredPlatform
numberNoAndroid

onBlur

Callback that is called when the text input is blurred.

TypeRequired
functionNo

onChange

Callback that is called when the text input's text changes. This will be called with { nativeEvent: { eventCount, target, text} }

TypeRequired
functionNo

onChangeText

Callback that is called when the text input's text changes. Changed text is passed as a single string argument to the callback handler.

TypeRequired
functionNo

onContentSizeChange

Callback that is called when the text input's content size changes. This will be called with { nativeEvent: { contentSize: { width, height } } }.

Only called for multiline text inputs.

TypeRequired
functionNo

onEndEditing

Callback that is called when text input ends.

TypeRequired
functionNo

onFocus

Callback that is called when the text input is focused. This is called with { nativeEvent: { target } }.

TypeRequired
functionNo

onKeyPress

Callback that is called when a key is pressed. This will be called with { nativeEvent: { key: keyValue } } where keyValue is 'Enter' or 'Backspace' for respective keys and the typed-in character otherwise including ' ' for space. Fires before onChange callbacks. Note: on Android only the inputs from soft keyboard are handled, not the hardware keyboard inputs.

TypeRequired
functionNo

onLayout

Invoked on mount and layout changes with { nativeEvent: {layout: {x, y, width, height}, target } }.

TypeRequired
functionNo

onScroll

Invoked on content scroll with { nativeEvent: { contentOffset: { x, y } } }. May also contain other properties from ScrollEvent but on Android contentSize is not provided for performance reasons.

TypeRequired
functionNo

onSelectionChange

Callback that is called when the text input selection is changed. This will be called with { nativeEvent: { selection: { start, end } } }. This prop requires multiline={true} to be set.

TypeRequired
functionNo

onSubmitEditing

Callback that is called when the text input's submit button is pressed with the argument {nativeEvent: {text, eventCount, target}}.

TypeRequired
functionNo

Note that on iOS this method isn't called when using keyboardType="phone-pad".

placeholder

The string that will be rendered before text input has been entered.

TypeRequired
stringNo

placeholderTextColor

The text color of the placeholder string.

TypeRequired
colorNo

returnKeyLabel

Sets the return key to the label. Use it instead of returnKeyType.

TypeRequiredPlatform
stringNoAndroid

returnKeyType

Determines how the return key should look. On Android you can also use returnKeyLabel.

Cross platform

The following values work across platforms:

  • done
  • go
  • next
  • search
  • send

Android Only

The following values work on Android only:

  • none
  • previous

iOS Only

The following values work on iOS only:

  • default
  • emergency-call
  • google
  • join
  • route
  • yahoo
TypeRequired
enum('done', 'go', 'next', 'search', 'send', 'none', 'previous', 'default', 'emergency-call', 'google', 'join', 'route', 'yahoo')No

rejectResponderTermination

iOS Only

If true, allows TextInput to pass touch events to the parent component. This allows components such as SwipeableListView to be swipeable from the TextInput on iOS, as is the case on Android by default. If false, TextInput always asks to handle the input (except when disabled). The default value is true.

TypeRequiredPlatform
boolNoiOS

scrollEnabled

If false, scrolling of the text view will be disabled. The default value is true. Only works with multiline={true}.

TypeRequiredPlatform
boolNoiOS

secureTextEntry

If true, the text input obscures the text entered so that sensitive text like passwords stay secure. The default value is false. Does not work with multiline={true}.

TypeRequired
boolNo

selection

The start and end of the text input's selection. Set start and end to the same value to position the cursor.

TypeRequired
object: {start: number,end: number}No

selectionColor

The highlight and cursor color of the text input.

TypeRequired
colorNo

selectTextOnFocus

If true, all text will automatically be selected on focus.

TypeRequired
boolNo

showSoftInputOnFocus

When false, it will prevent the soft keyboard from showing when the field is focused. The default value is true.

TypeRequiredPlatform
boolNoAndroid

spellCheck

If false, disables spell-check style (i.e. red underlines). The default value is inherited from autoCorrect.

TypeRequiredPlatform
boolNoiOS

textAlign

Align the input text to the left, center, or right sides of the input field.

Possible values for textAlign are:

  • left
  • center
  • right
TypeRequired
enum('left', 'center', 'right')No

textContentType

Give the keyboard and the system information about the expected semantic meaning for the content that users enter.

For iOS 11+ you can set textContentType to username or password to enable autofill of login details from the device keychain.

For iOS 12+ newPassword can be used to indicate a new password input the user may want to save in the keychain, and oneTimeCode can be used to indicate that a field can be autofilled by a code arriving in an SMS.

To disable autofill, set textContentType to none.

Possible values for textContentType are:

  • none
  • URL
  • addressCity
  • addressCityAndState
  • addressState
  • countryName
  • creditCardNumber
  • emailAddress
  • familyName
  • fullStreetAddress
  • givenName
  • jobTitle
  • location
  • middleName
  • name
  • namePrefix
  • nameSuffix
  • nickname
  • organizationName
  • postalCode
  • streetAddressLine1
  • streetAddressLine2
  • sublocality
  • telephoneNumber
  • username
  • password
  • newPassword
  • oneTimeCode
TypeRequiredPlatform
enum('none', 'URL', 'addressCity', 'addressCityAndState', 'addressState', 'countryName', 'creditCardNumber', 'emailAddress', 'familyName', 'fullStreetAddress', 'givenName', 'jobTitle', 'location', 'middleName', 'name', 'namePrefix', 'nameSuffix', 'nickname', 'organizationName', 'postalCode', 'streetAddressLine1', 'streetAddressLine2', 'sublocality', 'telephoneNumber', 'username', 'password')NoiOS

passwordRules

When using textContentType as newPassword on iOS we can let the OS know the minimum requirements of the password so that it can generate one that will satisfy them. In order to create a valid string for PasswordRules take a look to the Apple Docs.

TypeRequiredPlatform
stringNoiOS

style

Note that not all Text styles are supported, an incomplete list of what is not supported includes:

  • borderLeftWidth
  • borderTopWidth
  • borderRightWidth
  • borderBottomWidth
  • borderTopLeftRadius
  • borderTopRightRadius
  • borderBottomRightRadius
  • borderBottomLeftRadius

see Issue#7070 for more detail.

Styles

TypeRequired
TextNo

textBreakStrategy

Set text break strategy on Android API Level 23+, possible values are simple, highQuality, balanced The default value is simple.

TypeRequiredPlatform
enum('simple', 'highQuality', 'balanced')NoAndroid

underlineColorAndroid

The color of the TextInput underline.

TypeRequiredPlatform
colorNoAndroid

value

The value to show for the text input. TextInput is a controlled component, which means the native value will be forced to match this value prop if provided. For most uses, this works great, but in some cases this may cause flickering - one common cause is preventing edits by keeping value the same. In addition to setting the same value, either set editable={false}, or set/update maxLength to prevent unwanted edits without flicker.

TypeRequired
stringNo

Methods

.focus()

focus();

Makes the native input request focus.

.blur()

blur();

Makes the native input lose focus.

clear()

clear();

Removes all text from the TextInput.

isFocused()

isFocused();

Returns true if the input is currently focused; false otherwise.

Known issues

  • react-native#19096: Doesn't support Android's onKeyPreIme.
  • react-native#19366: Calling .focus() after closing Android's keyboard via back button doesn't bring keyboard up again.
  • react-native#26799: Doesn't support Android's secureTextEntry when keyboardType="email-address" or keyboardType="phone-pad".
Edit this page
Last updated on
- + diff --git a/docs/0.62/timepickerandroid.html b/docs/0.62/timepickerandroid.html index 3b223f62e24..1140ec23db1 100644 --- a/docs/0.62/timepickerandroid.html +++ b/docs/0.62/timepickerandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 TimePickerAndroid

Deprecated. Use @react-native-community/datetimepicker instead.

Opens the standard Android time picker dialog.

Example

try {
const { action, hour, minute } = await TimePickerAndroid.open({
hour: 14,
minute: 0,
is24Hour: false // Will display '2 PM'
});
if (action !== TimePickerAndroid.dismissedAction) {
// Selected hour (0-23), minute (0-59)
}
} catch ({ code, message }) {
console.warn('Cannot open time picker', message);
}

Reference

Methods

open()

static open(options)

Opens the standard Android time picker dialog.

The available keys for the options object are:

  • hour (0-23) - the hour to show, defaults to the current time
  • minute (0-59) - the minute to show, defaults to the current time
  • is24Hour (boolean) - If true, the picker uses the 24-hour format. If false, the picker shows an AM/PM chooser. If undefined, the default for the current locale is used.
  • mode (enum('clock', 'spinner', 'default')) - set the time picker mode
    • 'clock': Show a time picker in clock mode.
    • 'spinner': Show a time picker in spinner mode.
    • 'default': Show a default time picker based on Android versions.

Returns a Promise which will be invoked an object containing action, hour (0-23), minute (0-59) if the user picked a time. If the user dismissed the dialog, the Promise will still be resolved with action being TimePickerAndroid.dismissedAction and all the other keys being undefined. Always check whether the action before reading the values.

timeSetAction()

static timeSetAction()

A time has been selected.

dismissedAction()

static dismissedAction()

The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/0.62/timepickerandroid/index.html b/docs/0.62/timepickerandroid/index.html index 3b223f62e24..1140ec23db1 100644 --- a/docs/0.62/timepickerandroid/index.html +++ b/docs/0.62/timepickerandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

🚧 TimePickerAndroid

Deprecated. Use @react-native-community/datetimepicker instead.

Opens the standard Android time picker dialog.

Example

try {
const { action, hour, minute } = await TimePickerAndroid.open({
hour: 14,
minute: 0,
is24Hour: false // Will display '2 PM'
});
if (action !== TimePickerAndroid.dismissedAction) {
// Selected hour (0-23), minute (0-59)
}
} catch ({ code, message }) {
console.warn('Cannot open time picker', message);
}

Reference

Methods

open()

static open(options)

Opens the standard Android time picker dialog.

The available keys for the options object are:

  • hour (0-23) - the hour to show, defaults to the current time
  • minute (0-59) - the minute to show, defaults to the current time
  • is24Hour (boolean) - If true, the picker uses the 24-hour format. If false, the picker shows an AM/PM chooser. If undefined, the default for the current locale is used.
  • mode (enum('clock', 'spinner', 'default')) - set the time picker mode
    • 'clock': Show a time picker in clock mode.
    • 'spinner': Show a time picker in spinner mode.
    • 'default': Show a default time picker based on Android versions.

Returns a Promise which will be invoked an object containing action, hour (0-23), minute (0-59) if the user picked a time. If the user dismissed the dialog, the Promise will still be resolved with action being TimePickerAndroid.dismissedAction and all the other keys being undefined. Always check whether the action before reading the values.

timeSetAction()

static timeSetAction()

A time has been selected.

dismissedAction()

static dismissedAction()

The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/0.62/timers.html b/docs/0.62/timers.html index 924bb7def1d..5c0e4c6ed31 100644 --- a/docs/0.62/timers.html +++ b/docs/0.62/timers.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Timers

Timers are an important part of an application and React Native implements the browser timers.

Timers

  • setTimeout, clearTimeout
  • setInterval, clearInterval
  • setImmediate, clearImmediate
  • requestAnimationFrame, cancelAnimationFrame

requestAnimationFrame(fn) is not the same as setTimeout(fn, 0) - the former will fire after all the frame has flushed, whereas the latter will fire as quickly as possible (over 1000x per second on a iPhone 5S).

setImmediate is executed at the end of the current JavaScript execution block, right before sending the batched response back to native. Note that if you call setImmediate within a setImmediate callback, it will be executed right away, it won't yield back to native in between.

The Promise implementation uses setImmediate as its asynchronicity implementation.

InteractionManager

One reason why well-built native apps feel so smooth is by avoiding expensive operations during interactions and animations. In React Native, we currently have a limitation that there is only a single JS execution thread, but you can use InteractionManager to make sure long-running work is scheduled to start after any interactions/animations have completed.

Applications can schedule tasks to run after interactions with the following:

InteractionManager.runAfterInteractions(() => {
// ...long-running synchronous task...
});

Compare this to other scheduling alternatives:

  • requestAnimationFrame(): for code that animates a view over time.
  • setImmediate/setTimeout/setInterval(): run code later, note this may delay animations.
  • runAfterInteractions(): run code later, without delaying active animations.

The touch handling system considers one or more active touches to be an 'interaction' and will delay runAfterInteractions() callbacks until all touches have ended or been cancelled.

InteractionManager also allows applications to register animations by creating an interaction 'handle' on animation start, and clearing it upon completion:

var handle = InteractionManager.createInteractionHandle();
// run animation... (`runAfterInteractions` tasks are queued)
// later, on animation completion:
InteractionManager.clearInteractionHandle(handle);
// queued tasks run if all handles were cleared
Edit this page
Last updated on
- + diff --git a/docs/0.62/timers/index.html b/docs/0.62/timers/index.html index 924bb7def1d..5c0e4c6ed31 100644 --- a/docs/0.62/timers/index.html +++ b/docs/0.62/timers/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Timers

Timers are an important part of an application and React Native implements the browser timers.

Timers

  • setTimeout, clearTimeout
  • setInterval, clearInterval
  • setImmediate, clearImmediate
  • requestAnimationFrame, cancelAnimationFrame

requestAnimationFrame(fn) is not the same as setTimeout(fn, 0) - the former will fire after all the frame has flushed, whereas the latter will fire as quickly as possible (over 1000x per second on a iPhone 5S).

setImmediate is executed at the end of the current JavaScript execution block, right before sending the batched response back to native. Note that if you call setImmediate within a setImmediate callback, it will be executed right away, it won't yield back to native in between.

The Promise implementation uses setImmediate as its asynchronicity implementation.

InteractionManager

One reason why well-built native apps feel so smooth is by avoiding expensive operations during interactions and animations. In React Native, we currently have a limitation that there is only a single JS execution thread, but you can use InteractionManager to make sure long-running work is scheduled to start after any interactions/animations have completed.

Applications can schedule tasks to run after interactions with the following:

InteractionManager.runAfterInteractions(() => {
// ...long-running synchronous task...
});

Compare this to other scheduling alternatives:

  • requestAnimationFrame(): for code that animates a view over time.
  • setImmediate/setTimeout/setInterval(): run code later, note this may delay animations.
  • runAfterInteractions(): run code later, without delaying active animations.

The touch handling system considers one or more active touches to be an 'interaction' and will delay runAfterInteractions() callbacks until all touches have ended or been cancelled.

InteractionManager also allows applications to register animations by creating an interaction 'handle' on animation start, and clearing it upon completion:

var handle = InteractionManager.createInteractionHandle();
// run animation... (`runAfterInteractions` tasks are queued)
// later, on animation completion:
InteractionManager.clearInteractionHandle(handle);
// queued tasks run if all handles were cleared
Edit this page
Last updated on
- + diff --git a/docs/0.62/toastandroid.html b/docs/0.62/toastandroid.html index 835db1aa081..66005717c7b 100644 --- a/docs/0.62/toastandroid.html +++ b/docs/0.62/toastandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

ToastAndroid

React Native's ToastAndroid API exposes the Android platform's ToastAndroid module as a JS module. It provides the method show(message, duration) which takes the following parameters:

  • message A string with the text to toast
  • duration The duration of the toast—either ToastAndroid.SHORT or ToastAndroid.LONG

You can alternatively use showWithGravity(message, duration, gravity) to specify where the toast appears in the screen's layout. May be ToastAndroid.TOP, ToastAndroid.BOTTOM or ToastAndroid.CENTER.

The 'showWithGravityAndOffset(message, duration, gravity, xOffset, yOffset)' method adds the ability to specify an offset with in pixels.

Imperative hack

The ToastAndroid API is imperative, but there is a way to expose a declarative component from it as in this example:

Reference

Methods

show()

static show(message, duration)

showWithGravity()

static showWithGravity(message, duration, gravity)

showWithGravityAndOffset()

static showWithGravityAndOffset(message, duration, gravity, xOffset, yOffset)

Properties

SHORT

Indicates the duration on the screen.

ToastAndroid.SHORT;

LONG

Indicates the duration on the screen.

ToastAndroid.LONG;

TOP

Indicates the position on the screen.

ToastAndroid.TOP;

BOTTOM

Indicates the position on the screen.

ToastAndroid.BOTTOM;

CENTER

Indicates the position on the screen.

ToastAndroid.CENTER;
Edit this page
Last updated on
- + diff --git a/docs/0.62/toastandroid/index.html b/docs/0.62/toastandroid/index.html index 835db1aa081..66005717c7b 100644 --- a/docs/0.62/toastandroid/index.html +++ b/docs/0.62/toastandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

ToastAndroid

React Native's ToastAndroid API exposes the Android platform's ToastAndroid module as a JS module. It provides the method show(message, duration) which takes the following parameters:

  • message A string with the text to toast
  • duration The duration of the toast—either ToastAndroid.SHORT or ToastAndroid.LONG

You can alternatively use showWithGravity(message, duration, gravity) to specify where the toast appears in the screen's layout. May be ToastAndroid.TOP, ToastAndroid.BOTTOM or ToastAndroid.CENTER.

The 'showWithGravityAndOffset(message, duration, gravity, xOffset, yOffset)' method adds the ability to specify an offset with in pixels.

Imperative hack

The ToastAndroid API is imperative, but there is a way to expose a declarative component from it as in this example:

Reference

Methods

show()

static show(message, duration)

showWithGravity()

static showWithGravity(message, duration, gravity)

showWithGravityAndOffset()

static showWithGravityAndOffset(message, duration, gravity, xOffset, yOffset)

Properties

SHORT

Indicates the duration on the screen.

ToastAndroid.SHORT;

LONG

Indicates the duration on the screen.

ToastAndroid.LONG;

TOP

Indicates the position on the screen.

ToastAndroid.TOP;

BOTTOM

Indicates the position on the screen.

ToastAndroid.BOTTOM;

CENTER

Indicates the position on the screen.

ToastAndroid.CENTER;
Edit this page
Last updated on
- + diff --git a/docs/0.62/toolbarandroid.html b/docs/0.62/toolbarandroid.html index 97ac997b0f9..ae1d1693527 100644 --- a/docs/0.62/toolbarandroid.html +++ b/docs/0.62/toolbarandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

ToolbarAndroid

NOTE: Toolbar Android has been deprecated and removed from the package since React Native v0.61.0. Use @react-native-community/toolbar-android instead.

React component that wraps the Android-only Toolbar widget. A Toolbar can display a logo, navigation icon (e.g. hamburger menu), a title & subtitle and a list of actions. The title and subtitle are expanded so the logo and navigation icons are displayed on the left, title and subtitle in the middle and the actions on the right.

If the toolbar has an only child, it will be displayed between the title and actions.

Although the Toolbar supports remote images for the logo, navigation and action icons, this should only be used in DEV mode where require('./some_icon.png') translates into a bundler URL. In release mode you should always use a drawable resource for these icons. Using require('./some_icon.png') will do this automatically for you, so as long as you don't explicitly use e.g. {uri: 'http://...'}, you will be good.

Example:

render: function() {
return (
<ToolbarAndroid
logo={require('./app_logo.png')}
title="AwesomeApp"
actions={[{title: 'Settings', icon: require('./icon_settings.png'), show: 'always'}]}
onActionSelected={this.onActionSelected} />
)
},
onActionSelected: function(position) {
if (position === 0) { // index of 'Settings'
showSettings();
}
}

Reference

Props

Inherits View Props.

actions

Sets possible actions on the toolbar as part of the action menu. These are displayed as icons or text on the right side of the widget. If they don't fit they are placed in an 'overflow' menu.

This property takes an array of objects, where each object has the following keys:

  • title: required, the title of this action
  • icon: the icon for this action, e.g. require('./some_icon.png')
  • show: when to show this action as an icon or hide it in the overflow menu: always, ifRoom or never
  • showWithText: boolean, whether to show text alongside the icon or not
TypeRequired
array of object: {title: string,icon: optionalImageSource,show: enum('always', 'ifRoom', 'never'),showWithText: bool}No

contentInsetStart

Sets the content inset for the toolbar starting edge.

The content inset affects the valid area for Toolbar content other than the navigation button and menu. Insets define the minimum margin for these components and can be used to effectively align Toolbar content along well-known gridlines.

TypeRequired
numberNo

contentInsetEnd

Sets the content inset for the toolbar ending edge.

The content inset affects the valid area for Toolbar content other than the navigation button and menu. Insets define the minimum margin for these components and can be used to effectively align Toolbar content along well-known gridlines.

TypeRequired
numberNo

logo

Sets the toolbar logo.

TypeRequired
optionalImageSourceNo

navIcon

Sets the navigation icon.

TypeRequired
optionalImageSourceNo

onActionSelected

Callback that is called when an action is selected. The only argument that is passed to the callback is the position of the action in the actions array.

TypeRequired
functionNo

onIconClicked

Callback called when the icon is selected.

TypeRequired
functionNo

overflowIcon

Sets the overflow icon.

TypeRequired
optionalImageSourceNo

rtl

Used to set the toolbar direction to RTL. In addition to this property you need to add

android:supportsRtl="true"

to your application AndroidManifest.xml and then call setLayoutDirection(LayoutDirection.RTL) in your MainActivity onCreate method.

TypeRequired
boolNo

subtitle

Sets the toolbar subtitle.

TypeRequired
stringNo

subtitleColor

Sets the toolbar subtitle color.

TypeRequired
colorNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

title

Sets the toolbar title.

TypeRequired
stringNo

titleColor

Sets the toolbar title color.

TypeRequired
colorNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/toolbarandroid/index.html b/docs/0.62/toolbarandroid/index.html index 97ac997b0f9..ae1d1693527 100644 --- a/docs/0.62/toolbarandroid/index.html +++ b/docs/0.62/toolbarandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

ToolbarAndroid

NOTE: Toolbar Android has been deprecated and removed from the package since React Native v0.61.0. Use @react-native-community/toolbar-android instead.

React component that wraps the Android-only Toolbar widget. A Toolbar can display a logo, navigation icon (e.g. hamburger menu), a title & subtitle and a list of actions. The title and subtitle are expanded so the logo and navigation icons are displayed on the left, title and subtitle in the middle and the actions on the right.

If the toolbar has an only child, it will be displayed between the title and actions.

Although the Toolbar supports remote images for the logo, navigation and action icons, this should only be used in DEV mode where require('./some_icon.png') translates into a bundler URL. In release mode you should always use a drawable resource for these icons. Using require('./some_icon.png') will do this automatically for you, so as long as you don't explicitly use e.g. {uri: 'http://...'}, you will be good.

Example:

render: function() {
return (
<ToolbarAndroid
logo={require('./app_logo.png')}
title="AwesomeApp"
actions={[{title: 'Settings', icon: require('./icon_settings.png'), show: 'always'}]}
onActionSelected={this.onActionSelected} />
)
},
onActionSelected: function(position) {
if (position === 0) { // index of 'Settings'
showSettings();
}
}

Reference

Props

Inherits View Props.

actions

Sets possible actions on the toolbar as part of the action menu. These are displayed as icons or text on the right side of the widget. If they don't fit they are placed in an 'overflow' menu.

This property takes an array of objects, where each object has the following keys:

  • title: required, the title of this action
  • icon: the icon for this action, e.g. require('./some_icon.png')
  • show: when to show this action as an icon or hide it in the overflow menu: always, ifRoom or never
  • showWithText: boolean, whether to show text alongside the icon or not
TypeRequired
array of object: {title: string,icon: optionalImageSource,show: enum('always', 'ifRoom', 'never'),showWithText: bool}No

contentInsetStart

Sets the content inset for the toolbar starting edge.

The content inset affects the valid area for Toolbar content other than the navigation button and menu. Insets define the minimum margin for these components and can be used to effectively align Toolbar content along well-known gridlines.

TypeRequired
numberNo

contentInsetEnd

Sets the content inset for the toolbar ending edge.

The content inset affects the valid area for Toolbar content other than the navigation button and menu. Insets define the minimum margin for these components and can be used to effectively align Toolbar content along well-known gridlines.

TypeRequired
numberNo

logo

Sets the toolbar logo.

TypeRequired
optionalImageSourceNo

navIcon

Sets the navigation icon.

TypeRequired
optionalImageSourceNo

onActionSelected

Callback that is called when an action is selected. The only argument that is passed to the callback is the position of the action in the actions array.

TypeRequired
functionNo

onIconClicked

Callback called when the icon is selected.

TypeRequired
functionNo

overflowIcon

Sets the overflow icon.

TypeRequired
optionalImageSourceNo

rtl

Used to set the toolbar direction to RTL. In addition to this property you need to add

android:supportsRtl="true"

to your application AndroidManifest.xml and then call setLayoutDirection(LayoutDirection.RTL) in your MainActivity onCreate method.

TypeRequired
boolNo

subtitle

Sets the toolbar subtitle.

TypeRequired
stringNo

subtitleColor

Sets the toolbar subtitle color.

TypeRequired
colorNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

title

Sets the toolbar title.

TypeRequired
stringNo

titleColor

Sets the toolbar title color.

TypeRequired
colorNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/touchablehighlight.html b/docs/0.62/touchablehighlight.html index cda7f242aad..f1d0a3e16e5 100644 --- a/docs/0.62/touchablehighlight.html +++ b/docs/0.62/touchablehighlight.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
<TouchableHighlight
activeOpacity={0.6}
underlayColor="#DDDDDD"
onPress={() => alert('Pressed!')}>
<MyComponent />
</TouchableHighlight>;

Example

Reference

Props

Inherits TouchableWithoutFeedback Props.

activeOpacity

Determines what the opacity of the wrapped view should be when touch is active. The value should be between 0 and 1. Defaults to 0.85. Requires underlayColor to be set.

TypeRequired
numberNo

onHideUnderlay

Called immediately after the underlay is hidden.

TypeRequired
functionNo

onShowUnderlay

Called immediately after the underlay is shown.

TypeRequired
functionNo

style

TypeRequired
View.styleNo

underlayColor

The color of the underlay that will show through when the touch is active.

TypeRequired
colorNo

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

testOnly_pressed

Handy for snapshot tests.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/touchablehighlight/index.html b/docs/0.62/touchablehighlight/index.html index cda7f242aad..f1d0a3e16e5 100644 --- a/docs/0.62/touchablehighlight/index.html +++ b/docs/0.62/touchablehighlight/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
<TouchableHighlight
activeOpacity={0.6}
underlayColor="#DDDDDD"
onPress={() => alert('Pressed!')}>
<MyComponent />
</TouchableHighlight>;

Example

Reference

Props

Inherits TouchableWithoutFeedback Props.

activeOpacity

Determines what the opacity of the wrapped view should be when touch is active. The value should be between 0 and 1. Defaults to 0.85. Requires underlayColor to be set.

TypeRequired
numberNo

onHideUnderlay

Called immediately after the underlay is hidden.

TypeRequired
functionNo

onShowUnderlay

Called immediately after the underlay is shown.

TypeRequired
functionNo

style

TypeRequired
View.styleNo

underlayColor

The color of the underlay that will show through when the touch is active.

TypeRequired
colorNo

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

testOnly_pressed

Handy for snapshot tests.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/0.62/touchablenativefeedback.html b/docs/0.62/touchablenativefeedback.html index f83bca5e91a..ff876c57569 100644 --- a/docs/0.62/touchablenativefeedback.html +++ b/docs/0.62/touchablenativefeedback.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

TouchableNativeFeedback

A wrapper for making views respond properly to touches (Android only). On Android this component uses native state drawable to display touch feedback.

At the moment it only supports having a single View instance as a child node, as it's implemented by replacing that View with another instance of RCTView node with some additional properties set.

Background drawable of native feedback touchable can be customized with background property.

Example

Reference

Props

Inherits TouchableWithoutFeedback Props.

background

Determines the type of background drawable that's going to be used to display feedback. It takes an object with type property and extra data depending on the type. It's recommended to use one of the static methods to generate that dictionary.

TypeRequired
backgroundPropTypeNo

useForeground

Set to true to add the ripple effect to the foreground of the view, instead of the background. This is useful if one of your child views has a background of its own, or you're e.g. displaying images, and you don't want the ripple to be covered by them.

Check TouchableNativeFeedback.canUseNativeForeground() first, as this is only available on Android 6.0 and above. If you try to use this on older versions you will get a warning and fallback to background.

TypeRequired
boolNo

hasTVPreferredFocus

TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

Methods

SelectableBackground()

static SelectableBackground()

Creates an object that represents android theme's default background for selectable elements (?android:attr/selectableItemBackground).

SelectableBackgroundBorderless()

static SelectableBackgroundBorderless()

Creates an object that represent android theme's default background for borderless selectable elements (?android:attr/selectableItemBackgroundBorderless). Available on android API level 21+.

Ripple()

static Ripple(color: string, borderless: boolean)

Creates an object that represents ripple drawable with specified color (as a string). If property borderless evaluates to true the ripple will render outside of the view bounds (see native actionbar buttons as an example of that behavior). This background type is available on Android API level 21+.

Parameters:

NameTypeRequiredDescription
colorstringYesThe ripple color
borderlessbooleanYesIf the ripple can render outside its bounds

canUseNativeForeground()

static canUseNativeForeground()
Edit this page
Last updated on
- + diff --git a/docs/0.62/touchablenativefeedback/index.html b/docs/0.62/touchablenativefeedback/index.html index f83bca5e91a..ff876c57569 100644 --- a/docs/0.62/touchablenativefeedback/index.html +++ b/docs/0.62/touchablenativefeedback/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

TouchableNativeFeedback

A wrapper for making views respond properly to touches (Android only). On Android this component uses native state drawable to display touch feedback.

At the moment it only supports having a single View instance as a child node, as it's implemented by replacing that View with another instance of RCTView node with some additional properties set.

Background drawable of native feedback touchable can be customized with background property.

Example

Reference

Props

Inherits TouchableWithoutFeedback Props.

background

Determines the type of background drawable that's going to be used to display feedback. It takes an object with type property and extra data depending on the type. It's recommended to use one of the static methods to generate that dictionary.

TypeRequired
backgroundPropTypeNo

useForeground

Set to true to add the ripple effect to the foreground of the view, instead of the background. This is useful if one of your child views has a background of its own, or you're e.g. displaying images, and you don't want the ripple to be covered by them.

Check TouchableNativeFeedback.canUseNativeForeground() first, as this is only available on Android 6.0 and above. If you try to use this on older versions you will get a warning and fallback to background.

TypeRequired
boolNo

hasTVPreferredFocus

TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

Methods

SelectableBackground()

static SelectableBackground()

Creates an object that represents android theme's default background for selectable elements (?android:attr/selectableItemBackground).

SelectableBackgroundBorderless()

static SelectableBackgroundBorderless()

Creates an object that represent android theme's default background for borderless selectable elements (?android:attr/selectableItemBackgroundBorderless). Available on android API level 21+.

Ripple()

static Ripple(color: string, borderless: boolean)

Creates an object that represents ripple drawable with specified color (as a string). If property borderless evaluates to true the ripple will render outside of the view bounds (see native actionbar buttons as an example of that behavior). This background type is available on Android API level 21+.

Parameters:

NameTypeRequiredDescription
colorstringYesThe ripple color
borderlessbooleanYesIf the ripple can render outside its bounds

canUseNativeForeground()

static canUseNativeForeground()
Edit this page
Last updated on
- + diff --git a/docs/0.62/touchableopacity.html b/docs/0.62/touchableopacity.html index 3f52633e659..1f0cf13fae7 100644 --- a/docs/0.62/touchableopacity.html +++ b/docs/0.62/touchableopacity.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

TouchableOpacity

A wrapper for making views respond properly to touches. On press down, the opacity of the wrapped view is decreased, dimming it.

Opacity is controlled by wrapping the children in an Animated.View, which is added to the view hierarchy. Be aware that this can affect layout.

Example

Reference

Props

Inherits TouchableWithoutFeedback Props.

style

TypeRequired
View.styleNo

activeOpacity

Determines what the opacity of the wrapped view should be when touch is active. Defaults to 0.2.

TypeRequired
numberNo

tvParallaxProperties

(Apple TV only) Object with properties to control Apple TV parallax effects.

  • enabled: If true, parallax effects are enabled. Defaults to true.
  • shiftDistanceX: Defaults to 2.0.
  • shiftDistanceY: Defaults to 2.0.
  • tiltAngle: Defaults to 0.05.
  • magnification: Defaults to 1.0.
  • pressMagnification: Defaults to 1.0.
  • pressDuration: Defaults to 0.3.
  • pressDelay: Defaults to 0.0.
TypeRequiredPlatform
objectNoiOS

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.62/touchableopacity/index.html b/docs/0.62/touchableopacity/index.html index 3f52633e659..1f0cf13fae7 100644 --- a/docs/0.62/touchableopacity/index.html +++ b/docs/0.62/touchableopacity/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

TouchableOpacity

A wrapper for making views respond properly to touches. On press down, the opacity of the wrapped view is decreased, dimming it.

Opacity is controlled by wrapping the children in an Animated.View, which is added to the view hierarchy. Be aware that this can affect layout.

Example

Reference

Props

Inherits TouchableWithoutFeedback Props.

style

TypeRequired
View.styleNo

activeOpacity

Determines what the opacity of the wrapped view should be when touch is active. Defaults to 0.2.

TypeRequired
numberNo

tvParallaxProperties

(Apple TV only) Object with properties to control Apple TV parallax effects.

  • enabled: If true, parallax effects are enabled. Defaults to true.
  • shiftDistanceX: Defaults to 2.0.
  • shiftDistanceY: Defaults to 2.0.
  • tiltAngle: Defaults to 0.05.
  • magnification: Defaults to 1.0.
  • pressMagnification: Defaults to 1.0.
  • pressDuration: Defaults to 0.3.
  • pressDelay: Defaults to 0.0.
TypeRequiredPlatform
objectNoiOS

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.62/touchablewithoutfeedback.html b/docs/0.62/touchablewithoutfeedback.html index 19b86e4710b..bd18f3c8dd3 100644 --- a/docs/0.62/touchablewithoutfeedback.html +++ b/docs/0.62/touchablewithoutfeedback.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
<TouchableWithoutFeedback onPress={() => alert('Pressed!')}>
<MyComponent />
</TouchableWithoutFeedback>;

Example

Reference

Props

accessibilityIgnoresInvertColors

TypeRequired
BooleanNo

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

accessibilityActions

Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The accessibilityActions property should contain a list of action objects. Each action object should contain the field name and label.

See the Accessibility guide for more information.

TypeRequired
arrayNo

onAccessibilityAction

Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform.

See the Accessibility guide for more information.

TypeRequired
functionNo

accessibilityValue

Represents the current value of a component. It can be a textual description of a component's value, or for range-based components, such as sliders and progress bars, it contains range information (minimum, current, and maximum).

See the Accessibility guide for more information.

TypeRequired
object: {min: number, max: number, now: number, text: string}No

delayLongPress

Delay in ms, from onPressIn, before onLongPress is called.

TypeRequired
numberNo

delayPressIn

Delay in ms, from the start of the touch, before onPressIn is called.

TypeRequired
numberNo

delayPressOut

Delay in ms, from the release of the touch, before onPressOut is called.

TypeRequired
numberNo

disabled

If true, disable all interactions for this component.

TypeRequired
boolNo

hitSlop

This defines how far your touch can start away from the button. This is added to pressRetentionOffset when moving off of the button. NOTE The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

onBlur

Invoked when the item loses focus.

TypeRequired
functionNo

onFocus

Invoked when the item receives focus.

TypeRequired
functionNo

onLayout

Invoked on mount and layout changes with

{nativeEvent: {layout: {x, y, width, height}}}

TypeRequired
functionNo

onLongPress

TypeRequired
functionNo

onPress

Called when the touch is released, but not if cancelled (e.g. by a scroll that steals the responder lock).

TypeRequired
functionNo

onPressIn

Called as soon as the touchable element is pressed and invoked even before onPress. This can be useful when making network requests.

TypeRequired
functionNo

onPressOut

Called as soon as the touch is released even before onPress.

TypeRequired
functionNo

pressRetentionOffset

When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

nativeID

TypeRequired
stringNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

touchSoundDisabled

If true, doesn't play a system sound on touch.

TypeRequiredPlatform
BooleanNoAndroid

Type Definitions

Event

Type
Object
Edit this page
Last updated on
- + diff --git a/docs/0.62/touchablewithoutfeedback/index.html b/docs/0.62/touchablewithoutfeedback/index.html index 19b86e4710b..bd18f3c8dd3 100644 --- a/docs/0.62/touchablewithoutfeedback/index.html +++ b/docs/0.62/touchablewithoutfeedback/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
<TouchableWithoutFeedback onPress={() => alert('Pressed!')}>
<MyComponent />
</TouchableWithoutFeedback>;

Example

Reference

Props

accessibilityIgnoresInvertColors

TypeRequired
BooleanNo

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

accessibilityActions

Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The accessibilityActions property should contain a list of action objects. Each action object should contain the field name and label.

See the Accessibility guide for more information.

TypeRequired
arrayNo

onAccessibilityAction

Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform.

See the Accessibility guide for more information.

TypeRequired
functionNo

accessibilityValue

Represents the current value of a component. It can be a textual description of a component's value, or for range-based components, such as sliders and progress bars, it contains range information (minimum, current, and maximum).

See the Accessibility guide for more information.

TypeRequired
object: {min: number, max: number, now: number, text: string}No

delayLongPress

Delay in ms, from onPressIn, before onLongPress is called.

TypeRequired
numberNo

delayPressIn

Delay in ms, from the start of the touch, before onPressIn is called.

TypeRequired
numberNo

delayPressOut

Delay in ms, from the release of the touch, before onPressOut is called.

TypeRequired
numberNo

disabled

If true, disable all interactions for this component.

TypeRequired
boolNo

hitSlop

This defines how far your touch can start away from the button. This is added to pressRetentionOffset when moving off of the button. NOTE The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

onBlur

Invoked when the item loses focus.

TypeRequired
functionNo

onFocus

Invoked when the item receives focus.

TypeRequired
functionNo

onLayout

Invoked on mount and layout changes with

{nativeEvent: {layout: {x, y, width, height}}}

TypeRequired
functionNo

onLongPress

TypeRequired
functionNo

onPress

Called when the touch is released, but not if cancelled (e.g. by a scroll that steals the responder lock).

TypeRequired
functionNo

onPressIn

Called as soon as the touchable element is pressed and invoked even before onPress. This can be useful when making network requests.

TypeRequired
functionNo

onPressOut

Called as soon as the touch is released even before onPress.

TypeRequired
functionNo

pressRetentionOffset

When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

nativeID

TypeRequired
stringNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

touchSoundDisabled

If true, doesn't play a system sound on touch.

TypeRequiredPlatform
BooleanNoAndroid

Type Definitions

Event

Type
Object
Edit this page
Last updated on
- + diff --git a/docs/0.62/transforms.html b/docs/0.62/transforms.html index c347a2858d8..1298ce687c4 100644 --- a/docs/0.62/transforms.html +++ b/docs/0.62/transforms.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Transforms

Transforms are style properties that will help you modify the appearance and position of your components using 2D or 3D transformations. However, once you apply transforms, the layouts remain the same around the transformed component hence it might overlap with the nearby components. You can apply margin to the transformed component, the nearby components or padding to the container to prevent such overlaps.

Example

Reference

Methods

transform()

transform accepts an array of transformation objects. Each object specifies the property that will be transformed as the key, and the value to use in the transformation. Objects should not be combined. Use a single key/value pair per object.

The rotate transformations require a string so that the transform may be expressed in degrees (deg) or radians (rad). For example:

transform([{ rotateX: '45deg' }, { rotateZ: '0.785398rad' }]);

The skew transformations require a string so that the transform may be expressed in degrees (deg). For example:

transform([{ skewX: '45deg' }]);
TypeRequired
array of objects: {matrix: number[]}, {perspective: number}, {rotate: string}, {rotateX: string}, {rotateY: string}, {rotateZ: string}, {scale: number}, {scaleX: number}, {scaleY: number}, {translateX: number}, {translateY: number}, {skewX: string}, {skewY: string}No

decomposedMatrix, rotation, scaleX, scaleY, transformMatrix, translateX, translateY

Deprecated. Use the transform prop instead.

Edit this page
Last updated on
- + diff --git a/docs/0.62/transforms/index.html b/docs/0.62/transforms/index.html index c347a2858d8..1298ce687c4 100644 --- a/docs/0.62/transforms/index.html +++ b/docs/0.62/transforms/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Transforms

Transforms are style properties that will help you modify the appearance and position of your components using 2D or 3D transformations. However, once you apply transforms, the layouts remain the same around the transformed component hence it might overlap with the nearby components. You can apply margin to the transformed component, the nearby components or padding to the container to prevent such overlaps.

Example

Reference

Methods

transform()

transform accepts an array of transformation objects. Each object specifies the property that will be transformed as the key, and the value to use in the transformation. Objects should not be combined. Use a single key/value pair per object.

The rotate transformations require a string so that the transform may be expressed in degrees (deg) or radians (rad). For example:

transform([{ rotateX: '45deg' }, { rotateZ: '0.785398rad' }]);

The skew transformations require a string so that the transform may be expressed in degrees (deg). For example:

transform([{ skewX: '45deg' }]);
TypeRequired
array of objects: {matrix: number[]}, {perspective: number}, {rotate: string}, {rotateX: string}, {rotateY: string}, {rotateZ: string}, {scale: number}, {scaleX: number}, {scaleY: number}, {translateX: number}, {translateY: number}, {skewX: string}, {skewY: string}No

decomposedMatrix, rotation, scaleX, scaleY, transformMatrix, translateX, translateY

Deprecated. Use the transform prop instead.

Edit this page
Last updated on
- + diff --git a/docs/0.62/troubleshooting.html b/docs/0.62/troubleshooting.html index dd6716c1b86..7068a04ea04 100644 --- a/docs/0.62/troubleshooting.html +++ b/docs/0.62/troubleshooting.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Troubleshooting

These are some common issues you may run into while setting up React Native. If you encounter something that is not listed here, try searching for the issue in GitHub.

Port already in use

The Metro bundler runs on port 8081. If another process is already using that port, you can either terminate that process, or change the port that the bundler uses.

Terminating a process on port 8081

Run the following command to find the id for the process that is listening on port 8081:

$ sudo lsof -i :8081

Then run the following to terminate the process:

$ kill -9 <PID>

On Windows you can find the process using port 8081 using Resource Monitor and stop it using Task Manager.

Using a port other than 8081

You can configure the bundler to use a port other than 8081 by using the port parameter:

$ npx react-native start --port=8088

You will also need to update your applications to load the JavaScript bundle from the new port. If running on device from Xcode, you can do this by updating occurrences of 8081 to your chosen port in the node_modules/react-native/React/React.xcodeproj/project.pbxproj file.

NPM locking error

If you encounter an error such as npm WARN locking Error: EACCES while using the React Native CLI, try running the following:

sudo chown -R $USER ~/.npm
sudo chown -R $USER /usr/local/lib/node_modules

Missing libraries for React

If you added React Native manually to your project, make sure you have included all the relevant dependencies that you are using, like RCTText.xcodeproj, RCTImage.xcodeproj. Next, the binaries built by these dependencies have to be linked to your app binary. Use the Linked Frameworks and Binaries section in the Xcode project settings. More detailed steps are here: Linking Libraries.

If you are using CocoaPods, verify that you have added React along with the subspecs to the Podfile. For example, if you were using the <Text />, <Image /> and fetch() APIs, you would need to add these in your Podfile:

pod 'React', :path => '../node_modules/react-native', :subspecs => [
'RCTText',
'RCTImage',
'RCTNetwork',
'RCTWebSocket',
]

Next, make sure you have run pod install and that a Pods/ directory has been created in your project with React installed. CocoaPods will instruct you to use the generated .xcworkspace file henceforth to be able to use these installed dependencies.

React Native does not compile when being used as a CocoaPod

There is a CocoaPods plugin called cocoapods-fix-react-native which handles any potential post-fixing of the source code due to differences when using a dependency manager.

Argument list too long: recursive header expansion failed

In the project's build settings, User Search Header Paths and Header Search Paths are two configs that specify where Xcode should look for #import header files specified in the code. For Pods, CocoaPods uses a default array of specific folders to look in. Verify that this particular config is not overwritten, and that none of the folders configured are too large. If one of the folders is a large folder, Xcode will attempt to recursively search the entire directory and throw above error at some point.

To revert the User Search Header Paths and Header Search Paths build settings to their defaults set by CocoaPods - select the entry in the Build Settings panel, and hit delete. It will remove the custom override and return to the CocoaPod defaults.

No transports available

React Native implements a polyfill for WebSockets. These polyfills are initialized as part of the react-native module that you include in your application through import React from 'react'. If you load another module that requires WebSockets, such as Firebase, be sure to load/require it after react-native:

import React from 'react';
import Firebase from 'firebase';

Shell Command Unresponsive Exception

If you encounter a ShellCommandUnresponsiveException exception such as:

Execution failed for task ':app:installDebug'.
com.android.builder.testing.api.DeviceException: com.android.ddmlib.ShellCommandUnresponsiveException

Try downgrading your Gradle version to 1.2.3 in android/build.gradle.

react-native init hangs

If you run into issues where running npx react-native init hangs in your system, try running it again in verbose mode and referring to #2797 for common causes:

npx react-native init --verbose

Unable to start react-native package manager (on Linux)

Case 1: Error "code":"ENOSPC","errno":"ENOSPC"

Issue caused by the number of directories inotify (used by watchman on Linux) can monitor. To solve it, run this command in your terminal window

echo fs.inotify.max_user_watches=582222 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
Edit this page
Last updated on
- + diff --git a/docs/0.62/troubleshooting/index.html b/docs/0.62/troubleshooting/index.html index dd6716c1b86..7068a04ea04 100644 --- a/docs/0.62/troubleshooting/index.html +++ b/docs/0.62/troubleshooting/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Troubleshooting

These are some common issues you may run into while setting up React Native. If you encounter something that is not listed here, try searching for the issue in GitHub.

Port already in use

The Metro bundler runs on port 8081. If another process is already using that port, you can either terminate that process, or change the port that the bundler uses.

Terminating a process on port 8081

Run the following command to find the id for the process that is listening on port 8081:

$ sudo lsof -i :8081

Then run the following to terminate the process:

$ kill -9 <PID>

On Windows you can find the process using port 8081 using Resource Monitor and stop it using Task Manager.

Using a port other than 8081

You can configure the bundler to use a port other than 8081 by using the port parameter:

$ npx react-native start --port=8088

You will also need to update your applications to load the JavaScript bundle from the new port. If running on device from Xcode, you can do this by updating occurrences of 8081 to your chosen port in the node_modules/react-native/React/React.xcodeproj/project.pbxproj file.

NPM locking error

If you encounter an error such as npm WARN locking Error: EACCES while using the React Native CLI, try running the following:

sudo chown -R $USER ~/.npm
sudo chown -R $USER /usr/local/lib/node_modules

Missing libraries for React

If you added React Native manually to your project, make sure you have included all the relevant dependencies that you are using, like RCTText.xcodeproj, RCTImage.xcodeproj. Next, the binaries built by these dependencies have to be linked to your app binary. Use the Linked Frameworks and Binaries section in the Xcode project settings. More detailed steps are here: Linking Libraries.

If you are using CocoaPods, verify that you have added React along with the subspecs to the Podfile. For example, if you were using the <Text />, <Image /> and fetch() APIs, you would need to add these in your Podfile:

pod 'React', :path => '../node_modules/react-native', :subspecs => [
'RCTText',
'RCTImage',
'RCTNetwork',
'RCTWebSocket',
]

Next, make sure you have run pod install and that a Pods/ directory has been created in your project with React installed. CocoaPods will instruct you to use the generated .xcworkspace file henceforth to be able to use these installed dependencies.

React Native does not compile when being used as a CocoaPod

There is a CocoaPods plugin called cocoapods-fix-react-native which handles any potential post-fixing of the source code due to differences when using a dependency manager.

Argument list too long: recursive header expansion failed

In the project's build settings, User Search Header Paths and Header Search Paths are two configs that specify where Xcode should look for #import header files specified in the code. For Pods, CocoaPods uses a default array of specific folders to look in. Verify that this particular config is not overwritten, and that none of the folders configured are too large. If one of the folders is a large folder, Xcode will attempt to recursively search the entire directory and throw above error at some point.

To revert the User Search Header Paths and Header Search Paths build settings to their defaults set by CocoaPods - select the entry in the Build Settings panel, and hit delete. It will remove the custom override and return to the CocoaPod defaults.

No transports available

React Native implements a polyfill for WebSockets. These polyfills are initialized as part of the react-native module that you include in your application through import React from 'react'. If you load another module that requires WebSockets, such as Firebase, be sure to load/require it after react-native:

import React from 'react';
import Firebase from 'firebase';

Shell Command Unresponsive Exception

If you encounter a ShellCommandUnresponsiveException exception such as:

Execution failed for task ':app:installDebug'.
com.android.builder.testing.api.DeviceException: com.android.ddmlib.ShellCommandUnresponsiveException

Try downgrading your Gradle version to 1.2.3 in android/build.gradle.

react-native init hangs

If you run into issues where running npx react-native init hangs in your system, try running it again in verbose mode and referring to #2797 for common causes:

npx react-native init --verbose

Unable to start react-native package manager (on Linux)

Case 1: Error "code":"ENOSPC","errno":"ENOSPC"

Issue caused by the number of directories inotify (used by watchman on Linux) can monitor. To solve it, run this command in your terminal window

echo fs.inotify.max_user_watches=582222 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
Edit this page
Last updated on
- + diff --git a/docs/0.62/tutorial.html b/docs/0.62/tutorial.html index 8c80e98df3c..4f5451c34bd 100644 --- a/docs/0.62/tutorial.html +++ b/docs/0.62/tutorial.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Learn the Basics

React Native is like React, but it uses native components instead of web components as building blocks. So to understand the basic structure of a React Native app, you need to understand some of the basic React concepts, like JSX, components, state, and props. If you already know React, you still need to learn some React-Native-specific stuff, like the native components. This tutorial is aimed at all audiences, whether you have React experience or not.

Let's do this thing.

Hello World

In accordance with the ancient traditions of our people, we must first build an app that does nothing except say "Hello, world!". Here it is:

If you are feeling curious, you can play around with sample code directly in the web simulators. You can also paste it into your App.js file to create a real app on your local machine.

What's going on here?

  1. First of all, we need to import React to be able to use JSX, which will then be transformed to the native components of each platform.
  2. On line 2, we import the Text and View components from react-native

Then we find the HelloWorldApp function, which is a functional component and behaves in the same way as in React for the web. This function returns a View component with some styles and aText as its child.

The Text component allows us to render a text, while the View component renders a container. This container has several styles applied, let's analyze what each one is doing.

The first style that we find is flex: 1, the flex prop will define how your items are going to "fill" over the available space along your main axis. Since we only have one container, it will take all the available space of the parent component. In this case, it is the only component, so it will take all the available screen space.

The following style is justifyContent: "center". This align children of a container in the center of the container's main axis and finally we have alignItems: "center", which align children of a container in the center of the container's cross axis.

Some of the things in here might not look like JavaScript to you. Don't panic. This is the future.

First of all, ES2015 (also known as ES6) is a set of improvements to JavaScript that is now part of the official standard, but not yet supported by all browsers, so often it isn't used yet in web development. React Native ships with ES2015 support, so you can use this stuff without worrying about compatibility. import, from, class, and extends in the example above are all ES2015 features. If you aren't familiar with ES2015, you can probably pick it up by reading through sample code like this tutorial has. If you want, this page has a good overview of ES2015 features.

The other unusual thing in this code example is <View><Text>Hello world!</Text></View>. This is JSX - a syntax for embedding XML within JavaScript. Many frameworks use a specialized templating language which lets you embed code inside markup language. In React, this is reversed. JSX lets you write your markup language inside code. It looks like HTML on the web, except instead of web things like <div> or <span>, you use React components. In this case, <Text> is a Core Component that displays some text and View is like the <div> or <span>.

Components

So this code is defining HelloWorldApp, a new Component. When you're building a React Native app, you'll be making new components a lot. Anything you see on the screen is some sort of component.

Props

Most components can be customized when they are created, with different parameters. These creation parameters are called props.

Your own components can also use props. This lets you make a single component that is used in many different places in your app, with slightly different properties in each place. Refer to props.{NAME} in your functional components or this.props.{NAME} in your class components. Here's an example:

Using name as a prop lets us customize the Greeting component, so we can reuse that component for each of our greetings. This example also uses the Greeting component in JSX. The power to do this is what makes React so cool.

The other new thing going on here is the View component. A View is useful as a container for other components, to help control style and layout.

With props and the basic Text, Image, and View components, you can build a wide variety of static screens. To learn how to make your app change over time, you need to learn about State.

State

Unlike props that are read-only and should not be modified, the state allows React components to change their output over time in response to user actions, network responses and anything else.

What's the difference between state and props in React?

In a React component, the props are the variables that we pass from a parent component to a child component. Similarly, the state are also variables, with the difference that they are not passed as parameters, but rather that the component initializes and manages them internally.

Are there differences between React and React Native to handle the state?

image

As shown in the image, there is no difference in handling the state between React and React Native. You can use the state of your components both in classes and in functional components using hooks!

In the following example we will show the same above counter example using classes.

Edit this page
Last updated on
- + diff --git a/docs/0.62/tutorial/index.html b/docs/0.62/tutorial/index.html index 8c80e98df3c..4f5451c34bd 100644 --- a/docs/0.62/tutorial/index.html +++ b/docs/0.62/tutorial/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Learn the Basics

React Native is like React, but it uses native components instead of web components as building blocks. So to understand the basic structure of a React Native app, you need to understand some of the basic React concepts, like JSX, components, state, and props. If you already know React, you still need to learn some React-Native-specific stuff, like the native components. This tutorial is aimed at all audiences, whether you have React experience or not.

Let's do this thing.

Hello World

In accordance with the ancient traditions of our people, we must first build an app that does nothing except say "Hello, world!". Here it is:

If you are feeling curious, you can play around with sample code directly in the web simulators. You can also paste it into your App.js file to create a real app on your local machine.

What's going on here?

  1. First of all, we need to import React to be able to use JSX, which will then be transformed to the native components of each platform.
  2. On line 2, we import the Text and View components from react-native

Then we find the HelloWorldApp function, which is a functional component and behaves in the same way as in React for the web. This function returns a View component with some styles and aText as its child.

The Text component allows us to render a text, while the View component renders a container. This container has several styles applied, let's analyze what each one is doing.

The first style that we find is flex: 1, the flex prop will define how your items are going to "fill" over the available space along your main axis. Since we only have one container, it will take all the available space of the parent component. In this case, it is the only component, so it will take all the available screen space.

The following style is justifyContent: "center". This align children of a container in the center of the container's main axis and finally we have alignItems: "center", which align children of a container in the center of the container's cross axis.

Some of the things in here might not look like JavaScript to you. Don't panic. This is the future.

First of all, ES2015 (also known as ES6) is a set of improvements to JavaScript that is now part of the official standard, but not yet supported by all browsers, so often it isn't used yet in web development. React Native ships with ES2015 support, so you can use this stuff without worrying about compatibility. import, from, class, and extends in the example above are all ES2015 features. If you aren't familiar with ES2015, you can probably pick it up by reading through sample code like this tutorial has. If you want, this page has a good overview of ES2015 features.

The other unusual thing in this code example is <View><Text>Hello world!</Text></View>. This is JSX - a syntax for embedding XML within JavaScript. Many frameworks use a specialized templating language which lets you embed code inside markup language. In React, this is reversed. JSX lets you write your markup language inside code. It looks like HTML on the web, except instead of web things like <div> or <span>, you use React components. In this case, <Text> is a Core Component that displays some text and View is like the <div> or <span>.

Components

So this code is defining HelloWorldApp, a new Component. When you're building a React Native app, you'll be making new components a lot. Anything you see on the screen is some sort of component.

Props

Most components can be customized when they are created, with different parameters. These creation parameters are called props.

Your own components can also use props. This lets you make a single component that is used in many different places in your app, with slightly different properties in each place. Refer to props.{NAME} in your functional components or this.props.{NAME} in your class components. Here's an example:

Using name as a prop lets us customize the Greeting component, so we can reuse that component for each of our greetings. This example also uses the Greeting component in JSX. The power to do this is what makes React so cool.

The other new thing going on here is the View component. A View is useful as a container for other components, to help control style and layout.

With props and the basic Text, Image, and View components, you can build a wide variety of static screens. To learn how to make your app change over time, you need to learn about State.

State

Unlike props that are read-only and should not be modified, the state allows React components to change their output over time in response to user actions, network responses and anything else.

What's the difference between state and props in React?

In a React component, the props are the variables that we pass from a parent component to a child component. Similarly, the state are also variables, with the difference that they are not passed as parameters, but rather that the component initializes and manages them internally.

Are there differences between React and React Native to handle the state?

image

As shown in the image, there is no difference in handling the state between React and React Native. You can use the state of your components both in classes and in functional components using hooks!

In the following example we will show the same above counter example using classes.

Edit this page
Last updated on
- + diff --git a/docs/0.62/typescript.html b/docs/0.62/typescript.html index ba29151fe7e..21cc04cdb18 100644 --- a/docs/0.62/typescript.html +++ b/docs/0.62/typescript.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@
export default Hello;

You can explore the syntax more in the TypeScript playground.

Where to Find Useful Advice

Using Custom Path Aliases with TypeScript

To use custom path aliases with TypeScript, you need to set the path aliases to work from both Babel and TypeScript. Here's how:

  1. Edit your tsconfig.json to have your custom path mappings. Set anything in the root of src to be available with no preceding path reference, and allow any test file to be accessed by using test/File.tsx:
"target": "esnext",
+ "baseUrl": ".",
+ "paths": {
+ "*": ["src/*"],
+ "tests": ["tests/*"],
+ "@components/*": ["src/components/*"],
+ },
}
  1. Configure the Babel side done by adding a new dependency, babel-plugin-module-resolver:
yarn add --dev babel-plugin-module-resolver
# or
npm install --save-dev babel-plugin-module-resolver
  1. Finally, configure your babel.config.js (note that the syntax for your babel.config.js is different from your tsconfig.json):
{
plugins: [
+ [
+ 'module-resolver',
+ {
+ root: ['./src'],
+ extensions: ['.ios.js', '.android.js', '.js', '.ts', '.tsx', '.json'],
+ alias: {
+ "tests": ["./tests/"],
+ "@components": "./src/components",
+ }
+ }
+ ]
]
}
Edit this page
Last updated on
- + diff --git a/docs/0.62/typescript/index.html b/docs/0.62/typescript/index.html index ba29151fe7e..21cc04cdb18 100644 --- a/docs/0.62/typescript/index.html +++ b/docs/0.62/typescript/index.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@
export default Hello;

You can explore the syntax more in the TypeScript playground.

Where to Find Useful Advice

Using Custom Path Aliases with TypeScript

To use custom path aliases with TypeScript, you need to set the path aliases to work from both Babel and TypeScript. Here's how:

  1. Edit your tsconfig.json to have your custom path mappings. Set anything in the root of src to be available with no preceding path reference, and allow any test file to be accessed by using test/File.tsx:
"target": "esnext",
+ "baseUrl": ".",
+ "paths": {
+ "*": ["src/*"],
+ "tests": ["tests/*"],
+ "@components/*": ["src/components/*"],
+ },
}
  1. Configure the Babel side done by adding a new dependency, babel-plugin-module-resolver:
yarn add --dev babel-plugin-module-resolver
# or
npm install --save-dev babel-plugin-module-resolver
  1. Finally, configure your babel.config.js (note that the syntax for your babel.config.js is different from your tsconfig.json):
{
plugins: [
+ [
+ 'module-resolver',
+ {
+ root: ['./src'],
+ extensions: ['.ios.js', '.android.js', '.js', '.ts', '.tsx', '.json'],
+ alias: {
+ "tests": ["./tests/"],
+ "@components": "./src/components",
+ }
+ }
+ ]
]
}
Edit this page
Last updated on
- + diff --git a/docs/0.62/upgrading.html b/docs/0.62/upgrading.html index 222c6e898d5..2931c5c8552 100644 --- a/docs/0.62/upgrading.html +++ b/docs/0.62/upgrading.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Upgrading to new React Native versions

Upgrading to new versions of React Native will give you access to more APIs, views, developer tools and other goodies. Upgrading requires a small amount of effort, but we try to make it straightforward for you.

Expo projects

Upgrading your Expo project to a new version of React Native requires updating the react-native, react, and expo package versions in your package.json file. Please refer to this list to find out what versions are supported. You will also need to set the correct sdkVersion in your app.json file.

See the Upgrading Expo SDK Walkthrough for up-to-date information about upgrading your project.

React Native projects

Because typical React Native projects are essentially made up of an Android project, an iOS project, and a JavaScript project, upgrading can be rather tricky. There's currently two ways for upgrading your React Native project: by using React Native CLI or manually with Upgrade Helper.

React Native CLI

The React Native CLI comes with upgrade command that provides a one-step operation to upgrade the source files with a minimum of conflicts, it internally uses rn-diff-purge project to find out which files need to be created, removed or modified.

1. Run the upgrade command

The upgrade command works on top of Git by using git apply with 3-way merge, therefore it's required to use Git in order for this to work, if you don't use Git but still want to use this solution then you can check out how to do it in the Troubleshooting section.

Run the following command to start the process of upgrading to the latest version:

npx react-native upgrade

You may specify a React Native version by passing an argument, e.g. to upgrade to 0.61.0-rc.0 run:

npx react-native upgrade 0.61.0-rc.0

The project is upgraded using git apply with 3-way merge, it may happen that you'll need to resolve a few conflicts after it's finished.

2. Resolve the conflicts

Conflicted files include delimiters which make very clear where the changes come from. For example:

13B07F951A680F5B00A75B9A /* Release */ = {
isa = XCBuildConfiguration;
buildSettings = {
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
<<<<<<< ours
CODE_SIGN_IDENTITY = "iPhone Developer";
FRAMEWORK_SEARCH_PATHS = (
"$(inherited)",
"$(PROJECT_DIR)/HockeySDK.embeddedframework",
"$(PROJECT_DIR)/HockeySDK-iOS/HockeySDK.embeddedframework",
);
=======
CURRENT_PROJECT_VERSION = 1;
>>>>>>> theirs
HEADER_SEARCH_PATHS = (
"$(inherited)",
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include,
"$(SRCROOT)/../node_modules/react-native/React/**",
"$(SRCROOT)/../node_modules/react-native-code-push/ios/CodePush/**",
);

You can think of "ours" as "your team" and "theirs" as "the React Native development team".

Upgrade Helper

The Upgrade Helper is a web tool to help you out when upgrading your apps by providing the full set of changes happening between any two versions. It also shows comments on specific files to help understanding why that change is needed.

1. Select the versions

You first need to select from and to which version you wish to upgrade, by default the latest major versions are selected. After selecting you can click the button "Show me how to upgrade".

💡 Major updates will show an "useful content" section on the top with links to help you out when upgrading.

2. Upgrade dependencies

The first file that is shown is the package.json, it's good to update the dependencies that are showing in there. For example, if react-native and react appears as changes then you can install it in your project by running yarn add:

# {{VERSION}} and {{REACT_VERSION}} are the release versions showing in the diff
yarn add react-native@{{VERSION}}
yarn add react@{{REACT_VERSION}}

3. Upgrade your project files

The new release may contain updates to other files that are generated when you run npx react-native init, those files are listed after the package.json in the Upgrade Helper page. If there aren't other changes then you only need to rebuild the project to continue developing.

In case there are changes then you can either update them manually by copying and pasting from the changes in the page or you can do it with the React Native CLI upgrade command by running:

npx react-native upgrade

This will check your files against the latest template and perform the following:

  • If there is a new file in the template, it is created.
  • If a file in the template is identical to your file, it is skipped.
  • If a file is different in your project than the template, you will be prompted; you have options to keep your file or overwrite it with the template version.

Some upgrades won't be done automatically with the React Native CLI and require manual work, e.g. 0.28 to 0.29, or 0.56 to 0.57. Make sure to check the release notes when upgrading so that you can identify any manual changes your particular project may require.

Troubleshooting

I want to upgrade with React Native CLI but I don't use Git

While your project does not have to be handled by the Git versioning system -- you can use Mercurial, SVN, or nothing -- you will still need to install Git on your system in order to use npx react-native upgrade. Git will also need to be available in the PATH. If your project doesn't use Git, initialize it and commit:

git init # Initialize a Git repository
git add . # Stage all the current files
git commit -m "Upgrade react-native" # Save the current files in a commit

After you finish upgrading you may remove the .git directory.

I have done all the changes but my app is still using an old version

These sort of errors are usually related to caching, it's recommended to install react-native-clean-project to clear all your project's cache and then you can run it again.

Edit this page
Last updated on
- + diff --git a/docs/0.62/upgrading/index.html b/docs/0.62/upgrading/index.html index 222c6e898d5..2931c5c8552 100644 --- a/docs/0.62/upgrading/index.html +++ b/docs/0.62/upgrading/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Upgrading to new React Native versions

Upgrading to new versions of React Native will give you access to more APIs, views, developer tools and other goodies. Upgrading requires a small amount of effort, but we try to make it straightforward for you.

Expo projects

Upgrading your Expo project to a new version of React Native requires updating the react-native, react, and expo package versions in your package.json file. Please refer to this list to find out what versions are supported. You will also need to set the correct sdkVersion in your app.json file.

See the Upgrading Expo SDK Walkthrough for up-to-date information about upgrading your project.

React Native projects

Because typical React Native projects are essentially made up of an Android project, an iOS project, and a JavaScript project, upgrading can be rather tricky. There's currently two ways for upgrading your React Native project: by using React Native CLI or manually with Upgrade Helper.

React Native CLI

The React Native CLI comes with upgrade command that provides a one-step operation to upgrade the source files with a minimum of conflicts, it internally uses rn-diff-purge project to find out which files need to be created, removed or modified.

1. Run the upgrade command

The upgrade command works on top of Git by using git apply with 3-way merge, therefore it's required to use Git in order for this to work, if you don't use Git but still want to use this solution then you can check out how to do it in the Troubleshooting section.

Run the following command to start the process of upgrading to the latest version:

npx react-native upgrade

You may specify a React Native version by passing an argument, e.g. to upgrade to 0.61.0-rc.0 run:

npx react-native upgrade 0.61.0-rc.0

The project is upgraded using git apply with 3-way merge, it may happen that you'll need to resolve a few conflicts after it's finished.

2. Resolve the conflicts

Conflicted files include delimiters which make very clear where the changes come from. For example:

13B07F951A680F5B00A75B9A /* Release */ = {
isa = XCBuildConfiguration;
buildSettings = {
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
<<<<<<< ours
CODE_SIGN_IDENTITY = "iPhone Developer";
FRAMEWORK_SEARCH_PATHS = (
"$(inherited)",
"$(PROJECT_DIR)/HockeySDK.embeddedframework",
"$(PROJECT_DIR)/HockeySDK-iOS/HockeySDK.embeddedframework",
);
=======
CURRENT_PROJECT_VERSION = 1;
>>>>>>> theirs
HEADER_SEARCH_PATHS = (
"$(inherited)",
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include,
"$(SRCROOT)/../node_modules/react-native/React/**",
"$(SRCROOT)/../node_modules/react-native-code-push/ios/CodePush/**",
);

You can think of "ours" as "your team" and "theirs" as "the React Native development team".

Upgrade Helper

The Upgrade Helper is a web tool to help you out when upgrading your apps by providing the full set of changes happening between any two versions. It also shows comments on specific files to help understanding why that change is needed.

1. Select the versions

You first need to select from and to which version you wish to upgrade, by default the latest major versions are selected. After selecting you can click the button "Show me how to upgrade".

💡 Major updates will show an "useful content" section on the top with links to help you out when upgrading.

2. Upgrade dependencies

The first file that is shown is the package.json, it's good to update the dependencies that are showing in there. For example, if react-native and react appears as changes then you can install it in your project by running yarn add:

# {{VERSION}} and {{REACT_VERSION}} are the release versions showing in the diff
yarn add react-native@{{VERSION}}
yarn add react@{{REACT_VERSION}}

3. Upgrade your project files

The new release may contain updates to other files that are generated when you run npx react-native init, those files are listed after the package.json in the Upgrade Helper page. If there aren't other changes then you only need to rebuild the project to continue developing.

In case there are changes then you can either update them manually by copying and pasting from the changes in the page or you can do it with the React Native CLI upgrade command by running:

npx react-native upgrade

This will check your files against the latest template and perform the following:

  • If there is a new file in the template, it is created.
  • If a file in the template is identical to your file, it is skipped.
  • If a file is different in your project than the template, you will be prompted; you have options to keep your file or overwrite it with the template version.

Some upgrades won't be done automatically with the React Native CLI and require manual work, e.g. 0.28 to 0.29, or 0.56 to 0.57. Make sure to check the release notes when upgrading so that you can identify any manual changes your particular project may require.

Troubleshooting

I want to upgrade with React Native CLI but I don't use Git

While your project does not have to be handled by the Git versioning system -- you can use Mercurial, SVN, or nothing -- you will still need to install Git on your system in order to use npx react-native upgrade. Git will also need to be available in the PATH. If your project doesn't use Git, initialize it and commit:

git init # Initialize a Git repository
git add . # Stage all the current files
git commit -m "Upgrade react-native" # Save the current files in a commit

After you finish upgrading you may remove the .git directory.

I have done all the changes but my app is still using an old version

These sort of errors are usually related to caching, it's recommended to install react-native-clean-project to clear all your project's cache and then you can run it again.

Edit this page
Last updated on
- + diff --git a/docs/0.62/usecolorscheme.html b/docs/0.62/usecolorscheme.html index df1a396dbde..a9d246db5fd 100644 --- a/docs/0.62/usecolorscheme.html +++ b/docs/0.62/usecolorscheme.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
const MyComponent = () => {
const colorScheme = useColorScheme();
return <Text>useColorScheme(): {colorScheme}</Text>;
};

You can find a complete example that demonstrates the use of this hook alongside a React context to add support for light and dark themes to your application in AppearanceExample.js.

Edit this page
Last updated on
- + diff --git a/docs/0.62/usecolorscheme/index.html b/docs/0.62/usecolorscheme/index.html index df1a396dbde..a9d246db5fd 100644 --- a/docs/0.62/usecolorscheme/index.html +++ b/docs/0.62/usecolorscheme/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
const MyComponent = () => {
const colorScheme = useColorScheme();
return <Text>useColorScheme(): {colorScheme}</Text>;
};

You can find a complete example that demonstrates the use of this hook alongside a React context to add support for light and dark themes to your application in AppearanceExample.js.

Edit this page
Last updated on
- + diff --git a/docs/0.62/usewindowdimensions.html b/docs/0.62/usewindowdimensions.html index 4e852ae563f..766a1e047ab 100644 --- a/docs/0.62/usewindowdimensions.html +++ b/docs/0.62/usewindowdimensions.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

useWindowDimensions

import { useWindowDimensions } from 'react-native';

useWindowDimensions automatically updates width and height values when screen size changes. You can get your application window's width and height like so:

const windowWidth = useWindowDimensions().width;
const windowHeight = useWindowDimensions().height;

Example

Properties

fontScale

The scale of the font currently used. Some operating systems allow users to scale their font sizes larger or smaller for reading comfort. This property will let you know what is in effect.

useWindowDimensions().fontScale;

height

The height in pixels of the window or screen your app occupies.

useWindowDimensions().height;

scale

The pixel ratio of the device your app is running on.

useWindowDimensions().scale;

A value of 1 indicates PPI/DPI of 96 (76 on some platforms). 2 indicates a Retina or high DPI display.

width

The width in pixels of the window or screen your app occupies.

useWindowDimensions().width;
Edit this page
Last updated on
- + diff --git a/docs/0.62/usewindowdimensions/index.html b/docs/0.62/usewindowdimensions/index.html index 4e852ae563f..766a1e047ab 100644 --- a/docs/0.62/usewindowdimensions/index.html +++ b/docs/0.62/usewindowdimensions/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

useWindowDimensions

import { useWindowDimensions } from 'react-native';

useWindowDimensions automatically updates width and height values when screen size changes. You can get your application window's width and height like so:

const windowWidth = useWindowDimensions().width;
const windowHeight = useWindowDimensions().height;

Example

Properties

fontScale

The scale of the font currently used. Some operating systems allow users to scale their font sizes larger or smaller for reading comfort. This property will let you know what is in effect.

useWindowDimensions().fontScale;

height

The height in pixels of the window or screen your app occupies.

useWindowDimensions().height;

scale

The pixel ratio of the device your app is running on.

useWindowDimensions().scale;

A value of 1 indicates PPI/DPI of 96 (76 on some platforms). 2 indicates a Retina or high DPI display.

width

The width in pixels of the window or screen your app occupies.

useWindowDimensions().width;
Edit this page
Last updated on
- + diff --git a/docs/0.62/using-a-listview.html b/docs/0.62/using-a-listview.html index 0c1d0c9f461..6e2315d8a89 100644 --- a/docs/0.62/using-a-listview.html +++ b/docs/0.62/using-a-listview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Using List Views

React Native provides a suite of components for presenting lists of data. Generally, you'll want to use either FlatList or SectionList.

The FlatList component displays a scrolling list of changing, but similarly structured, data. FlatList works well for long lists of data, where the number of items might change over time. Unlike the more generic ScrollView, the FlatList only renders elements that are currently showing on the screen, not all the elements at once.

The FlatList component requires two props: data and renderItem. data is the source of information for the list. renderItem takes one item from the source and returns a formatted component to render.

This example creates a basic FlatList of hardcoded data. Each item in the data props is rendered as a Text component. The FlatListBasics component then renders the FlatList and all Text components.

If you want to render a set of data broken into logical sections, maybe with section headers, similar to UITableViews on iOS, then a SectionList is the way to go.

One of the most common uses for a list view is displaying data that you fetch from a server. To do that, you will need to learn about networking in React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.62/using-a-listview/index.html b/docs/0.62/using-a-listview/index.html index 0c1d0c9f461..6e2315d8a89 100644 --- a/docs/0.62/using-a-listview/index.html +++ b/docs/0.62/using-a-listview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Using List Views

React Native provides a suite of components for presenting lists of data. Generally, you'll want to use either FlatList or SectionList.

The FlatList component displays a scrolling list of changing, but similarly structured, data. FlatList works well for long lists of data, where the number of items might change over time. Unlike the more generic ScrollView, the FlatList only renders elements that are currently showing on the screen, not all the elements at once.

The FlatList component requires two props: data and renderItem. data is the source of information for the list. renderItem takes one item from the source and returns a formatted component to render.

This example creates a basic FlatList of hardcoded data. Each item in the data props is rendered as a Text component. The FlatListBasics component then renders the FlatList and all Text components.

If you want to render a set of data broken into logical sections, maybe with section headers, similar to UITableViews on iOS, then a SectionList is the way to go.

One of the most common uses for a list view is displaying data that you fetch from a server. To do that, you will need to learn about networking in React Native.

Edit this page
Last updated on
- + diff --git a/docs/0.62/using-a-scrollview.html b/docs/0.62/using-a-scrollview.html index 2e1c7d55455..70fad54e58c 100644 --- a/docs/0.62/using-a-scrollview.html +++ b/docs/0.62/using-a-scrollview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Using a ScrollView

The ScrollView is a generic scrolling container that can contain multiple components and views. The scrollable items need not be homogeneous, and you can scroll both vertically and horizontally (by setting the horizontal property).

This example creates a vertical ScrollView with both images and text mixed together.

ScrollViews can be configured to allow paging through views using swiping gestures by using the pagingEnabled props. Swiping horizontally between views can also be implemented on Android using the ViewPager component.

On iOS a ScrollView with a single item can be used to allow the user to zoom content. Set up the maximumZoomScale and minimumZoomScale props and your user will be able to use pinch and expand gestures to zoom in and out.

The ScrollView works best to present a small amount of things of a limited size. All the elements and views of a ScrollView are rendered, even if they are not currently shown on the screen. If you have a long list of more items than can fit on the screen, you should use a FlatList instead. So let's learn about list views next.

Edit this page
Last updated on
- + diff --git a/docs/0.62/using-a-scrollview/index.html b/docs/0.62/using-a-scrollview/index.html index 2e1c7d55455..70fad54e58c 100644 --- a/docs/0.62/using-a-scrollview/index.html +++ b/docs/0.62/using-a-scrollview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Using a ScrollView

The ScrollView is a generic scrolling container that can contain multiple components and views. The scrollable items need not be homogeneous, and you can scroll both vertically and horizontally (by setting the horizontal property).

This example creates a vertical ScrollView with both images and text mixed together.

ScrollViews can be configured to allow paging through views using swiping gestures by using the pagingEnabled props. Swiping horizontally between views can also be implemented on Android using the ViewPager component.

On iOS a ScrollView with a single item can be used to allow the user to zoom content. Set up the maximumZoomScale and minimumZoomScale props and your user will be able to use pinch and expand gestures to zoom in and out.

The ScrollView works best to present a small amount of things of a limited size. All the elements and views of a ScrollView are rendered, even if they are not currently shown on the screen. If you have a long list of more items than can fit on the screen, you should use a FlatList instead. So let's learn about list views next.

Edit this page
Last updated on
- + diff --git a/docs/0.62/vibration.html b/docs/0.62/vibration.html index ce7151a0136..792a47cf233 100644 --- a/docs/0.62/vibration.html +++ b/docs/0.62/vibration.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Vibration

Vibrates the device.

Example

Android apps should request the android.permission.VIBRATE permission by adding <uses-permission android:name="android.permission.VIBRATE"/> to AndroidManifest.xml.

The Vibration API is implemented as a AudioServicesPlaySystemSound(kSystemSoundID_Vibrate) call on iOS.

Reference

Methods

vibrate()

Vibration.vibrate(?pattern: number | Array<number>, ?repeat: boolean)

Triggers a vibration with a fixed duration.

On Android, the vibration duration defaults to 400 milliseconds, and an arbitrary vibration duration can be specified by passing a number as the value for the pattern argument. On iOS, the vibration duration is fixed at roughly 400 milliseconds.

The vibrate() method can take a pattern argument with an array of numbers that represent time in milliseconds. You may set repeat to true to run through the vibration pattern in a loop until cancel() is called.

On Android, the odd indices of the pattern array represent the vibration duration, while the even ones represent the separation time. On iOS, the numbers in the pattern array represent the separation time, as the vibration duration is fixed.

Parameters:

NameTypeRequiredDescriptionPlatform
patternnumberNoVibration duration in milliseconds. Defaults to 400 ms.Android
patternArray of numbersNoVibration pattern as an array of numbers in milliseconds.Android, iOS
repeatbooleanNoRepeat vibration pattern until cancel(), default to false.Android, iOS

cancel()

Vibration.cancel();

Call this to stop vibrating after having invoked vibrate() with repetition enabled.

Edit this page
Last updated on
- + diff --git a/docs/0.62/vibration/index.html b/docs/0.62/vibration/index.html index ce7151a0136..792a47cf233 100644 --- a/docs/0.62/vibration/index.html +++ b/docs/0.62/vibration/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

Vibration

Vibrates the device.

Example

Android apps should request the android.permission.VIBRATE permission by adding <uses-permission android:name="android.permission.VIBRATE"/> to AndroidManifest.xml.

The Vibration API is implemented as a AudioServicesPlaySystemSound(kSystemSoundID_Vibrate) call on iOS.

Reference

Methods

vibrate()

Vibration.vibrate(?pattern: number | Array<number>, ?repeat: boolean)

Triggers a vibration with a fixed duration.

On Android, the vibration duration defaults to 400 milliseconds, and an arbitrary vibration duration can be specified by passing a number as the value for the pattern argument. On iOS, the vibration duration is fixed at roughly 400 milliseconds.

The vibrate() method can take a pattern argument with an array of numbers that represent time in milliseconds. You may set repeat to true to run through the vibration pattern in a loop until cancel() is called.

On Android, the odd indices of the pattern array represent the vibration duration, while the even ones represent the separation time. On iOS, the numbers in the pattern array represent the separation time, as the vibration duration is fixed.

Parameters:

NameTypeRequiredDescriptionPlatform
patternnumberNoVibration duration in milliseconds. Defaults to 400 ms.Android
patternArray of numbersNoVibration pattern as an array of numbers in milliseconds.Android, iOS
repeatbooleanNoRepeat vibration pattern until cancel(), default to false.Android, iOS

cancel()

Vibration.cancel();

Call this to stop vibrating after having invoked vibrate() with repetition enabled.

Edit this page
Last updated on
- + diff --git a/docs/0.62/vibrationios.html b/docs/0.62/vibrationios.html index 0ed4e256ae3..a62f0372c4e 100644 --- a/docs/0.62/vibrationios.html +++ b/docs/0.62/vibrationios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

VibrationIOS

NOTE: VibrationIOS is being deprecated. Use Vibration instead.

The Vibration API is exposed at VibrationIOS.vibrate(). On iOS, calling this function will trigger a one second vibration. The vibration is synchronous so this method will return immediately.

There will be no effect on devices that do not support Vibration, eg. the iOS simulator.

Vibration patterns are currently unsupported.

Methods

Reference

Methods

vibrate()

static vibrate()

@deprecated

Edit this page
Last updated on
- + diff --git a/docs/0.62/vibrationios/index.html b/docs/0.62/vibrationios/index.html index 0ed4e256ae3..a62f0372c4e 100644 --- a/docs/0.62/vibrationios/index.html +++ b/docs/0.62/vibrationios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

VibrationIOS

NOTE: VibrationIOS is being deprecated. Use Vibration instead.

The Vibration API is exposed at VibrationIOS.vibrate(). On iOS, calling this function will trigger a one second vibration. The vibration is synchronous so this method will return immediately.

There will be no effect on devices that do not support Vibration, eg. the iOS simulator.

Vibration patterns are currently unsupported.

Methods

Reference

Methods

vibrate()

static vibrate()

@deprecated

Edit this page
Last updated on
- + diff --git a/docs/0.62/view-style-props.html b/docs/0.62/view-style-props.html index fdc4e4a80c4..14eb0882f15 100644 --- a/docs/0.62/view-style-props.html +++ b/docs/0.62/view-style-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

View Style Props

Example

Reference

Props

borderRightColor

TypeRequired
colorNo

backfaceVisibility

TypeRequired
enum('visible', 'hidden')No

borderBottomColor

TypeRequired
colorNo

borderBottomEndRadius

TypeRequired
numberNo

borderBottomLeftRadius

TypeRequired
numberNo

borderBottomRightRadius

TypeRequired
numberNo

borderBottomStartRadius

TypeRequired
numberNo

borderBottomWidth

TypeRequired
numberNo

borderColor

TypeRequired
colorNo

borderEndColor

TypeRequired
colorNo

borderLeftColor

TypeRequired
colorNo

borderLeftWidth

TypeRequired
numberNo

borderRadius

If the rounded border is not visible, try applying overflow: 'hidden' as well.

TypeRequired
numberNo

backgroundColor

TypeRequired
colorNo

borderRightWidth

TypeRequired
numberNo

borderStartColor

TypeRequired
colorNo

borderStyle

TypeRequired
enum('solid', 'dotted', 'dashed')No

borderTopColor

TypeRequired
colorNo

borderTopEndRadius

TypeRequired
numberNo

borderTopLeftRadius

TypeRequired
numberNo

borderTopRightRadius

TypeRequired
numberNo

borderTopStartRadius

TypeRequired
numberNo

borderTopWidth

TypeRequired
numberNo

borderWidth

TypeRequired
numberNo

opacity

TypeRequired
numberNo

elevation

(Android-only) Sets the elevation of a view, using Android's underlying elevation API. This adds a drop shadow to the item and affects z-order for overlapping views. Only supported on Android 5.0+, has no effect on earlier versions.

TypeRequiredPlatform
numberNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.62/view-style-props/index.html b/docs/0.62/view-style-props/index.html index fdc4e4a80c4..14eb0882f15 100644 --- a/docs/0.62/view-style-props/index.html +++ b/docs/0.62/view-style-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

View Style Props

Example

Reference

Props

borderRightColor

TypeRequired
colorNo

backfaceVisibility

TypeRequired
enum('visible', 'hidden')No

borderBottomColor

TypeRequired
colorNo

borderBottomEndRadius

TypeRequired
numberNo

borderBottomLeftRadius

TypeRequired
numberNo

borderBottomRightRadius

TypeRequired
numberNo

borderBottomStartRadius

TypeRequired
numberNo

borderBottomWidth

TypeRequired
numberNo

borderColor

TypeRequired
colorNo

borderEndColor

TypeRequired
colorNo

borderLeftColor

TypeRequired
colorNo

borderLeftWidth

TypeRequired
numberNo

borderRadius

If the rounded border is not visible, try applying overflow: 'hidden' as well.

TypeRequired
numberNo

backgroundColor

TypeRequired
colorNo

borderRightWidth

TypeRequired
numberNo

borderStartColor

TypeRequired
colorNo

borderStyle

TypeRequired
enum('solid', 'dotted', 'dashed')No

borderTopColor

TypeRequired
colorNo

borderTopEndRadius

TypeRequired
numberNo

borderTopLeftRadius

TypeRequired
numberNo

borderTopRightRadius

TypeRequired
numberNo

borderTopStartRadius

TypeRequired
numberNo

borderTopWidth

TypeRequired
numberNo

borderWidth

TypeRequired
numberNo

opacity

TypeRequired
numberNo

elevation

(Android-only) Sets the elevation of a view, using Android's underlying elevation API. This adds a drop shadow to the item and affects z-order for overlapping views. Only supported on Android 5.0+, has no effect on earlier versions.

TypeRequiredPlatform
numberNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.62/view.html b/docs/0.62/view.html index 696554422a7..85d0a63a158 100644 --- a/docs/0.62/view.html +++ b/docs/0.62/view.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

View

The most fundamental component for building a UI, View is a container that supports layout with flexbox, style, some touch handling, and accessibility controls. View maps directly to the native view equivalent on whatever platform React Native is running on, whether that is a UIView, <div>, android.view, etc.

View is designed to be nested inside other views and can have 0 to many children of any type.

This example creates a View that wraps two boxes with color and a text component in a row with padding.

Views are designed to be used with StyleSheet for clarity and performance, although inline styles are also supported.

Synthetic Touch Events

For View responder props (e.g., onResponderMove), the synthetic touch event passed to them are of the following form:

  • nativeEvent
    • changedTouches - Array of all touch events that have changed since the last event.
    • identifier - The ID of the touch.
    • locationX - The X position of the touch, relative to the element.
    • locationY - The Y position of the touch, relative to the element.
    • pageX - The X position of the touch, relative to the root element.
    • pageY - The Y position of the touch, relative to the root element.
    • target - The node id of the element receiving the touch event.
    • timestamp - A time identifier for the touch, useful for velocity calculation.
    • touches - Array of all current touches on the screen.

Reference

Props

onStartShouldSetResponder

Does this view want to become responder on the start of a touch?

View.props.onStartShouldSetResponder: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

  • 'none' - Used when the element has no role.
  • 'button' - Used when the element should be treated as a button.
  • 'link' - Used when the element should be treated as a link.
  • 'search' - Used when the text field element should also be treated as a search field.
  • 'image' - Used when the element should be treated as an image. Can be combined with button or link, for example.
  • 'keyboardkey' - Used when the element acts as a keyboard key.
  • 'text' - Used when the element should be treated as static text that cannot change.
  • 'adjustable' - Used when an element can be "adjusted" (e.g. a slider).
  • 'imagebutton' - Used when the element should be treated as a button and is also an image.
  • 'header' - Used when an element acts as a header for a content section (e.g. the title of a navigation bar).
  • 'summary' - Used when an element can be used to provide a quick summary of current conditions in the app when the app first launches.
  • 'alert' - Used when an element contains important text to be presented to the user.
  • 'checkbox' - Used when an element represents a checkbox which can be checked, unchecked, or have mixed checked state.
  • 'combobox' - Used when an element represents a combo box, which allows the user to select among several choices.
  • 'menu' - Used when the component is a menu of choices.
  • 'menubar' - Used when a component is a container of multiple menus.
  • 'menuitem' - Used to represent an item within a menu.
  • 'progressbar' - Used to represent a component which indicates progress of a task.
  • 'radio' - Used to represent a radio button.
  • 'radiogroup' - Used to represent a group of radio buttons.
  • 'scrollbar' - Used to represent a scroll bar.
  • 'spinbutton' - Used to represent a button which opens a list of choices.
  • 'switch' - Used to represent a switch which can be turned on and off.
  • 'tab' - Used to represent a tab.
  • 'tablist' - Used to represent a list of tabs.
  • 'timer' - Used to represent a timer.
  • 'toolbar' - Used to represent a tool bar (a container of action buttons or components).
TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

accessibilityValue

Represents the current value of a component. It can be a textual description of a component's value, or for range-based components, such as sliders and progress bars, it contains range information (minimum, current, and maximum).

See the Accessibility guide for more information.

TypeRequired
object: {min: number, max: number, now: number, text: string}No

accessibilityActions

Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The accessibilityActions property should contain a list of action objects. Each action object should contain the field name and label.

See the Accessibility guide for more information.

TypeRequired
arrayNo

onAccessibilityAction

Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform.

See the Accessibility guide for more information.

TypeRequired
functionNo

onAccessibilityTap

When accessible is true, the system will try to invoke this function when the user performs accessibility tap gesture.

TypeRequired
functionNo

onMagicTap

When accessible is true, the system will invoke this function when the user performs the magic tap gesture.

TypeRequiredPlatform
functionNoiOS

onAccessibilityEscape

When accessible is true, the system will invoke this function when the user performs the escape gesture.

TypeRequiredPlatform
functionNoiOS

accessibilityViewIsModal

A value indicating whether VoiceOver should ignore the elements within views that are siblings of the receiver. Default is false.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityElementsHidden

A value indicating whether the accessibility elements contained within this accessibility element are hidden. Default is false.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityIgnoresInvertColors

A value indicating this view should or should not be inverted when color inversion is turned on. A value of true will tell the view to not be inverted even if color inversion is turned on.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityLiveRegion

Indicates to accessibility services whether the user should be notified when this view changes. Works for Android API >= 19 only. Possible values:

  • 'none' - Accessibility services should not announce changes to this view.
  • 'polite'- Accessibility services should announce changes to this view.
  • 'assertive' - Accessibility services should interrupt ongoing speech to immediately announce changes to this view.

See the Android View docs for reference.

TypeRequiredPlatform
enum('none', 'polite', 'assertive')NoAndroid

importantForAccessibility

Controls how view is important for accessibility which is if it fires accessibility events and if it is reported to accessibility services that query the screen. Works for Android only.

Possible values:

  • 'auto' - The system determines whether the view is important for accessibility - default (recommended).
  • 'yes' - The view is important for accessibility.
  • 'no' - The view is not important for accessibility.
  • 'no-hide-descendants' - The view is not important for accessibility, nor are any of its descendant views.

See the Android importantForAccessibility docs for reference.

TypeRequiredPlatform
enum('auto', 'yes', 'no', 'no-hide-descendants')NoAndroid

hitSlop

This defines how far a touch event can start away from the view. Typical interface guidelines recommend touch targets that are at least 30 - 40 points/density-independent pixels.

For example, if a touchable view has a height of 20 the touchable height can be extended to 40 with hitSlop={{top: 10, bottom: 10, left: 0, right: 0}}

The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

nativeID

Used to locate this view from native classes.

This disables the 'layout-only view removal' optimization for this view!

TypeRequired
stringNo

onLayout

Invoked on mount and layout changes with:

{nativeEvent: { layout: {x, y, width, height}}}

This event is fired immediately once the layout has been calculated, but the new layout may not yet be reflected on the screen at the time the event is received, especially if a layout animation is in progress.

TypeRequired
functionNo

onMoveShouldSetResponder

Does this view want to "claim" touch responsiveness? This is called for every touch move on the View when it is not the responder.

View.props.onMoveShouldSetResponder: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onMoveShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a move, it should have this handler which returns true.

View.props.onMoveShouldSetResponderCapture: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderGrant

The View is now responding for touch events. This is the time to highlight and show the user what is happening.

View.props.onResponderGrant: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderMove

The user is moving their finger.

View.props.onResponderMove: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderReject

Another responder is already active and will not release it to that View asking to be the responder.

View.props.onResponderReject: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderRelease

Fired at the end of the touch.

View.props.onResponderRelease: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminate

The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS)

View.props.onResponderTerminate: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminationRequest

Some other View wants to become responder and is asking this View to release its responder. Returning true allows its release.

View.props.onResponderTerminationRequest: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onStartShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a touch start, it should have this handler which returns true.

View.props.onStartShouldSetResponderCapture: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

pointerEvents

Controls whether the View can be the target of touch events.

  • 'auto': The View can be the target of touch events.
  • 'none': The View is never the target of touch events.
  • 'box-none': The View is never the target of touch events but its subviews can be. It behaves like if the view had the following classes in CSS:
.box-none {
pointer-events: none;
}
.box-none * {
pointer-events: auto;
}
  • 'box-only': The view can be the target of touch events but its subviews cannot be. It behaves like if the view had the following classes in CSS:
.box-only {
pointer-events: auto;
}
.box-only * {
pointer-events: none;
}

Since pointerEvents does not affect layout/appearance, and we are already deviating from the spec by adding additional modes, we opt to not include pointerEvents on style. On some platforms, we would need to implement it as a className anyways. Using style or not is an implementation detail of the platform.

TypeRequired
enum('box-none', 'none', 'box-only', 'auto')No

removeClippedSubviews

This is a reserved performance property exposed by RCTView and is useful for scrolling content when there are many subviews, most of which are offscreen. For this property to be effective, it must be applied to a view that contains many subviews that extend outside its bound. The subviews must also have overflow: hidden, as should the containing view (or one of its superviews).

TypeRequired
boolNo

style

TypeRequired
view stylesNo

testID

Used to locate this view in end-to-end tests.

This disables the 'layout-only view removal' optimization for this view!

TypeRequired
stringNo

collapsable

Views that are only used to layout their children or otherwise don't draw anything may be automatically removed from the native hierarchy as an optimization. Set this property to false to disable this optimization and ensure that this View exists in the native view hierarchy.

TypeRequiredPlatform
boolNoAndroid

needsOffscreenAlphaCompositing

Whether this View needs to rendered offscreen and composited with an alpha in order to preserve 100% correct colors and blending behavior. The default (false) falls back to drawing the component and its children with an alpha applied to the paint used to draw each element instead of rendering the full component offscreen and compositing it back with an alpha value. This default may be noticeable and undesired in the case where the View you are setting an opacity on has multiple overlapping elements (e.g. multiple overlapping Views, or text and a background).

Rendering offscreen to preserve correct alpha behavior is extremely expensive and hard to debug for non-native developers, which is why it is not turned on by default. If you do need to enable this property for an animation, consider combining it with renderToHardwareTextureAndroid if the view contents are static (i.e. it doesn't need to be redrawn each frame). If that property is enabled, this View will be rendered off-screen once, saved in a hardware texture, and then composited onto the screen with an alpha each frame without having to switch rendering targets on the GPU.

TypeRequired
boolNo

renderToHardwareTextureAndroid

Whether this View should render itself (and all of its children) into a single hardware texture on the GPU.

On Android, this is useful for animations and interactions that only modify opacity, rotation, translation, and/or scale: in those cases, the view doesn't have to be redrawn and display lists don't need to be re-executed. The texture can be re-used and re-composited with different parameters. The downside is that this can use up limited video memory, so this prop should be set back to false at the end of the interaction/animation.

TypeRequiredPlatform
boolNoAndroid

shouldRasterizeIOS

Whether this View should be rendered as a bitmap before compositing.

On iOS, this is useful for animations and interactions that do not modify this component's dimensions nor its children; for example, when translating the position of a static view, rasterization allows the renderer to reuse a cached bitmap of a static view and quickly composite it during each frame.

Rasterization incurs an off-screen drawing pass and the bitmap consumes memory. Test and measure when using this property.

TypeRequiredPlatform
boolNoiOS

nextFocusDown

Designates the next view to receive focus when the user navigates down. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusForward

Designates the next view to receive focus when the user navigates forward. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusLeft

Designates the next view to receive focus when the user navigates left. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusRight

Designates the next view to receive focus when the user navigates right. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusUp

Designates the next view to receive focus when the user navigates up. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

focusable

Whether this View should be focusable with a non-touch input device, eg. receive focus with a hardware keyboard.

TypeRequiredPlatform
booleanNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.62/view/index.html b/docs/0.62/view/index.html index 696554422a7..85d0a63a158 100644 --- a/docs/0.62/view/index.html +++ b/docs/0.62/view/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: 0.62

View

The most fundamental component for building a UI, View is a container that supports layout with flexbox, style, some touch handling, and accessibility controls. View maps directly to the native view equivalent on whatever platform React Native is running on, whether that is a UIView, <div>, android.view, etc.

View is designed to be nested inside other views and can have 0 to many children of any type.

This example creates a View that wraps two boxes with color and a text component in a row with padding.

Views are designed to be used with StyleSheet for clarity and performance, although inline styles are also supported.

Synthetic Touch Events

For View responder props (e.g., onResponderMove), the synthetic touch event passed to them are of the following form:

  • nativeEvent
    • changedTouches - Array of all touch events that have changed since the last event.
    • identifier - The ID of the touch.
    • locationX - The X position of the touch, relative to the element.
    • locationY - The Y position of the touch, relative to the element.
    • pageX - The X position of the touch, relative to the root element.
    • pageY - The Y position of the touch, relative to the root element.
    • target - The node id of the element receiving the touch event.
    • timestamp - A time identifier for the touch, useful for velocity calculation.
    • touches - Array of all current touches on the screen.

Reference

Props

onStartShouldSetResponder

Does this view want to become responder on the start of a touch?

View.props.onStartShouldSetResponder: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

  • 'none' - Used when the element has no role.
  • 'button' - Used when the element should be treated as a button.
  • 'link' - Used when the element should be treated as a link.
  • 'search' - Used when the text field element should also be treated as a search field.
  • 'image' - Used when the element should be treated as an image. Can be combined with button or link, for example.
  • 'keyboardkey' - Used when the element acts as a keyboard key.
  • 'text' - Used when the element should be treated as static text that cannot change.
  • 'adjustable' - Used when an element can be "adjusted" (e.g. a slider).
  • 'imagebutton' - Used when the element should be treated as a button and is also an image.
  • 'header' - Used when an element acts as a header for a content section (e.g. the title of a navigation bar).
  • 'summary' - Used when an element can be used to provide a quick summary of current conditions in the app when the app first launches.
  • 'alert' - Used when an element contains important text to be presented to the user.
  • 'checkbox' - Used when an element represents a checkbox which can be checked, unchecked, or have mixed checked state.
  • 'combobox' - Used when an element represents a combo box, which allows the user to select among several choices.
  • 'menu' - Used when the component is a menu of choices.
  • 'menubar' - Used when a component is a container of multiple menus.
  • 'menuitem' - Used to represent an item within a menu.
  • 'progressbar' - Used to represent a component which indicates progress of a task.
  • 'radio' - Used to represent a radio button.
  • 'radiogroup' - Used to represent a group of radio buttons.
  • 'scrollbar' - Used to represent a scroll bar.
  • 'spinbutton' - Used to represent a button which opens a list of choices.
  • 'switch' - Used to represent a switch which can be turned on and off.
  • 'tab' - Used to represent a tab.
  • 'tablist' - Used to represent a list of tabs.
  • 'timer' - Used to represent a timer.
  • 'toolbar' - Used to represent a tool bar (a container of action buttons or components).
TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

accessibilityValue

Represents the current value of a component. It can be a textual description of a component's value, or for range-based components, such as sliders and progress bars, it contains range information (minimum, current, and maximum).

See the Accessibility guide for more information.

TypeRequired
object: {min: number, max: number, now: number, text: string}No

accessibilityActions

Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The accessibilityActions property should contain a list of action objects. Each action object should contain the field name and label.

See the Accessibility guide for more information.

TypeRequired
arrayNo

onAccessibilityAction

Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform.

See the Accessibility guide for more information.

TypeRequired
functionNo

onAccessibilityTap

When accessible is true, the system will try to invoke this function when the user performs accessibility tap gesture.

TypeRequired
functionNo

onMagicTap

When accessible is true, the system will invoke this function when the user performs the magic tap gesture.

TypeRequiredPlatform
functionNoiOS

onAccessibilityEscape

When accessible is true, the system will invoke this function when the user performs the escape gesture.

TypeRequiredPlatform
functionNoiOS

accessibilityViewIsModal

A value indicating whether VoiceOver should ignore the elements within views that are siblings of the receiver. Default is false.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityElementsHidden

A value indicating whether the accessibility elements contained within this accessibility element are hidden. Default is false.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityIgnoresInvertColors

A value indicating this view should or should not be inverted when color inversion is turned on. A value of true will tell the view to not be inverted even if color inversion is turned on.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityLiveRegion

Indicates to accessibility services whether the user should be notified when this view changes. Works for Android API >= 19 only. Possible values:

  • 'none' - Accessibility services should not announce changes to this view.
  • 'polite'- Accessibility services should announce changes to this view.
  • 'assertive' - Accessibility services should interrupt ongoing speech to immediately announce changes to this view.

See the Android View docs for reference.

TypeRequiredPlatform
enum('none', 'polite', 'assertive')NoAndroid

importantForAccessibility

Controls how view is important for accessibility which is if it fires accessibility events and if it is reported to accessibility services that query the screen. Works for Android only.

Possible values:

  • 'auto' - The system determines whether the view is important for accessibility - default (recommended).
  • 'yes' - The view is important for accessibility.
  • 'no' - The view is not important for accessibility.
  • 'no-hide-descendants' - The view is not important for accessibility, nor are any of its descendant views.

See the Android importantForAccessibility docs for reference.

TypeRequiredPlatform
enum('auto', 'yes', 'no', 'no-hide-descendants')NoAndroid

hitSlop

This defines how far a touch event can start away from the view. Typical interface guidelines recommend touch targets that are at least 30 - 40 points/density-independent pixels.

For example, if a touchable view has a height of 20 the touchable height can be extended to 40 with hitSlop={{top: 10, bottom: 10, left: 0, right: 0}}

The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

nativeID

Used to locate this view from native classes.

This disables the 'layout-only view removal' optimization for this view!

TypeRequired
stringNo

onLayout

Invoked on mount and layout changes with:

{nativeEvent: { layout: {x, y, width, height}}}

This event is fired immediately once the layout has been calculated, but the new layout may not yet be reflected on the screen at the time the event is received, especially if a layout animation is in progress.

TypeRequired
functionNo

onMoveShouldSetResponder

Does this view want to "claim" touch responsiveness? This is called for every touch move on the View when it is not the responder.

View.props.onMoveShouldSetResponder: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onMoveShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a move, it should have this handler which returns true.

View.props.onMoveShouldSetResponderCapture: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderGrant

The View is now responding for touch events. This is the time to highlight and show the user what is happening.

View.props.onResponderGrant: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderMove

The user is moving their finger.

View.props.onResponderMove: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderReject

Another responder is already active and will not release it to that View asking to be the responder.

View.props.onResponderReject: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderRelease

Fired at the end of the touch.

View.props.onResponderRelease: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminate

The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS)

View.props.onResponderTerminate: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onResponderTerminationRequest

Some other View wants to become responder and is asking this View to release its responder. Returning true allows its release.

View.props.onResponderTerminationRequest: (event) => {}, where event is a synthetic touch event as described above.

TypeRequired
functionNo

onStartShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a touch start, it should have this handler which returns true.

View.props.onStartShouldSetResponderCapture: (event) => [true | false], where event is a synthetic touch event as described above.

TypeRequired
functionNo

pointerEvents

Controls whether the View can be the target of touch events.

  • 'auto': The View can be the target of touch events.
  • 'none': The View is never the target of touch events.
  • 'box-none': The View is never the target of touch events but its subviews can be. It behaves like if the view had the following classes in CSS:
.box-none {
pointer-events: none;
}
.box-none * {
pointer-events: auto;
}
  • 'box-only': The view can be the target of touch events but its subviews cannot be. It behaves like if the view had the following classes in CSS:
.box-only {
pointer-events: auto;
}
.box-only * {
pointer-events: none;
}

Since pointerEvents does not affect layout/appearance, and we are already deviating from the spec by adding additional modes, we opt to not include pointerEvents on style. On some platforms, we would need to implement it as a className anyways. Using style or not is an implementation detail of the platform.

TypeRequired
enum('box-none', 'none', 'box-only', 'auto')No

removeClippedSubviews

This is a reserved performance property exposed by RCTView and is useful for scrolling content when there are many subviews, most of which are offscreen. For this property to be effective, it must be applied to a view that contains many subviews that extend outside its bound. The subviews must also have overflow: hidden, as should the containing view (or one of its superviews).

TypeRequired
boolNo

style

TypeRequired
view stylesNo

testID

Used to locate this view in end-to-end tests.

This disables the 'layout-only view removal' optimization for this view!

TypeRequired
stringNo

collapsable

Views that are only used to layout their children or otherwise don't draw anything may be automatically removed from the native hierarchy as an optimization. Set this property to false to disable this optimization and ensure that this View exists in the native view hierarchy.

TypeRequiredPlatform
boolNoAndroid

needsOffscreenAlphaCompositing

Whether this View needs to rendered offscreen and composited with an alpha in order to preserve 100% correct colors and blending behavior. The default (false) falls back to drawing the component and its children with an alpha applied to the paint used to draw each element instead of rendering the full component offscreen and compositing it back with an alpha value. This default may be noticeable and undesired in the case where the View you are setting an opacity on has multiple overlapping elements (e.g. multiple overlapping Views, or text and a background).

Rendering offscreen to preserve correct alpha behavior is extremely expensive and hard to debug for non-native developers, which is why it is not turned on by default. If you do need to enable this property for an animation, consider combining it with renderToHardwareTextureAndroid if the view contents are static (i.e. it doesn't need to be redrawn each frame). If that property is enabled, this View will be rendered off-screen once, saved in a hardware texture, and then composited onto the screen with an alpha each frame without having to switch rendering targets on the GPU.

TypeRequired
boolNo

renderToHardwareTextureAndroid

Whether this View should render itself (and all of its children) into a single hardware texture on the GPU.

On Android, this is useful for animations and interactions that only modify opacity, rotation, translation, and/or scale: in those cases, the view doesn't have to be redrawn and display lists don't need to be re-executed. The texture can be re-used and re-composited with different parameters. The downside is that this can use up limited video memory, so this prop should be set back to false at the end of the interaction/animation.

TypeRequiredPlatform
boolNoAndroid

shouldRasterizeIOS

Whether this View should be rendered as a bitmap before compositing.

On iOS, this is useful for animations and interactions that do not modify this component's dimensions nor its children; for example, when translating the position of a static view, rasterization allows the renderer to reuse a cached bitmap of a static view and quickly composite it during each frame.

Rasterization incurs an off-screen drawing pass and the bitmap consumes memory. Test and measure when using this property.

TypeRequiredPlatform
boolNoiOS

nextFocusDown

Designates the next view to receive focus when the user navigates down. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusForward

Designates the next view to receive focus when the user navigates forward. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusLeft

Designates the next view to receive focus when the user navigates left. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusRight

Designates the next view to receive focus when the user navigates right. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusUp

Designates the next view to receive focus when the user navigates up. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

focusable

Whether this View should be focusable with a non-touch input device, eg. receive focus with a hardware keyboard.

TypeRequiredPlatform
booleanNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/0.62/viewpagerandroid.html b/docs/0.62/viewpagerandroid.html index 4ed91902318..03088f61669 100644 --- a/docs/0.62/viewpagerandroid.html +++ b/docs/0.62/viewpagerandroid.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
const styles = {
...
viewPager: {
flex: 1
},
pageStyle: {
alignItems: 'center',
padding: 20,
}
}

Reference

Props

Inherits View Props.

initialPage

Index of initial page that should be selected. Use setPage method to update the page, and onPageSelected to monitor page changes

TypeRequired
numberNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

TypeRequired
enum('none', 'on-drag')No

onPageScroll

Executed when transitioning between pages (either because of animation for the requested page change or when user is swiping/dragging between pages) The event.nativeEvent object for this callback will carry following data:

TypeRequired
functionNo

onPageScrollStateChanged

Function called when the page scrolling state has changed. The page scrolling state can be in 3 states:

TypeRequired
functionNo

onPageSelected

This callback will be called once ViewPager finish navigating to selected page (when user swipes between pages). The event.nativeEvent object passed to this callback will have following fields:

TypeRequired
functionNo

pageMargin

Blank space to show between pages. This is only visible while scrolling, pages are still edge-to-edge.

TypeRequired
numberNo

peekEnabled

Whether enable showing peekFraction or not. If this is true, the preview of last and next page will show in current screen. Defaults to false.

TypeRequired
boolNo

scrollEnabled

When false, the content does not scroll. The default value is true.

TypeRequired
boolNo

setPage

A helper function to scroll to a specific page in the ViewPager. The transition between pages will be animated.

TypeRequired
NumberYes

setPageWithoutAnimation

A helper function to scroll to a specific page in the ViewPager. The transition between pages will not be animated.

TypeRequired
NumberYes

Type Definitions

ViewPagerScrollState

Type
\$Enum

Constants:

ValueDescription
idle
dragging
settling
Edit this page
Last updated on
- + diff --git a/docs/0.62/viewpagerandroid/index.html b/docs/0.62/viewpagerandroid/index.html index 4ed91902318..03088f61669 100644 --- a/docs/0.62/viewpagerandroid/index.html +++ b/docs/0.62/viewpagerandroid/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
const styles = {
...
viewPager: {
flex: 1
},
pageStyle: {
alignItems: 'center',
padding: 20,
}
}

Reference

Props

Inherits View Props.

initialPage

Index of initial page that should be selected. Use setPage method to update the page, and onPageSelected to monitor page changes

TypeRequired
numberNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

TypeRequired
enum('none', 'on-drag')No

onPageScroll

Executed when transitioning between pages (either because of animation for the requested page change or when user is swiping/dragging between pages) The event.nativeEvent object for this callback will carry following data:

TypeRequired
functionNo

onPageScrollStateChanged

Function called when the page scrolling state has changed. The page scrolling state can be in 3 states:

TypeRequired
functionNo

onPageSelected

This callback will be called once ViewPager finish navigating to selected page (when user swipes between pages). The event.nativeEvent object passed to this callback will have following fields:

TypeRequired
functionNo

pageMargin

Blank space to show between pages. This is only visible while scrolling, pages are still edge-to-edge.

TypeRequired
numberNo

peekEnabled

Whether enable showing peekFraction or not. If this is true, the preview of last and next page will show in current screen. Defaults to false.

TypeRequired
boolNo

scrollEnabled

When false, the content does not scroll. The default value is true.

TypeRequired
boolNo

setPage

A helper function to scroll to a specific page in the ViewPager. The transition between pages will be animated.

TypeRequired
NumberYes

setPageWithoutAnimation

A helper function to scroll to a specific page in the ViewPager. The transition between pages will not be animated.

TypeRequired
NumberYes

Type Definitions

ViewPagerScrollState

Type
\$Enum

Constants:

ValueDescription
idle
dragging
settling
Edit this page
Last updated on
- + diff --git a/docs/0.62/virtualizedlist.html b/docs/0.62/virtualizedlist.html index 634333dbc94..d09e01e3374 100644 --- a/docs/0.62/virtualizedlist.html +++ b/docs/0.62/virtualizedlist.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@

scrollToIndex()

scrollToIndex((params: object));

Valid params consist of:

scrollToItem()

scrollToItem((params: object));

Valid params consist of:

scrollToOffset()

scrollToOffset((params: object));

Scroll to a specific content pixel offset in the list.

Param offset expects the offset to scroll to. In case of horizontal is true, the offset is the x-value, in any other case the offset is the y-value.

Param animated (true by default) defines whether the list should do an animation while scrolling.

recordInteraction()

recordInteraction();

flashScrollIndicators()

flashScrollIndicators();

getScrollResponder()

getScrollResponder () => ?ScrollResponderType;

Provides a handle to the underlying scroll responder. Note that this._scrollRef might not be a ScrollView, so we need to check that it responds to getScrollResponder before calling it.

getScrollableNode()

getScrollableNode () => ?number;

getScrollRef()

getScrollRef () => | ?React.ElementRef<typeof ScrollView>
| ?React.ElementRef<typeof View>;

setNativeProps()

setNativeProps((props: Object));

getChildContext()

getChildContext () => Object;

The Object returned consist of:

hasMore()

hasMore () => boolean;
Edit this page
Last updated on
- + diff --git a/docs/0.62/virtualizedlist/index.html b/docs/0.62/virtualizedlist/index.html index 634333dbc94..d09e01e3374 100644 --- a/docs/0.62/virtualizedlist/index.html +++ b/docs/0.62/virtualizedlist/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@

scrollToIndex()

scrollToIndex((params: object));

Valid params consist of:

scrollToItem()

scrollToItem((params: object));

Valid params consist of:

scrollToOffset()

scrollToOffset((params: object));

Scroll to a specific content pixel offset in the list.

Param offset expects the offset to scroll to. In case of horizontal is true, the offset is the x-value, in any other case the offset is the y-value.

Param animated (true by default) defines whether the list should do an animation while scrolling.

recordInteraction()

recordInteraction();

flashScrollIndicators()

flashScrollIndicators();

getScrollResponder()

getScrollResponder () => ?ScrollResponderType;

Provides a handle to the underlying scroll responder. Note that this._scrollRef might not be a ScrollView, so we need to check that it responds to getScrollResponder before calling it.

getScrollableNode()

getScrollableNode () => ?number;

getScrollRef()

getScrollRef () => | ?React.ElementRef<typeof ScrollView>
| ?React.ElementRef<typeof View>;

setNativeProps()

setNativeProps((props: Object));

getChildContext()

getChildContext () => Object;

The Object returned consist of:

hasMore()

hasMore () => boolean;
Edit this page
Last updated on
- + diff --git a/docs/0.62/webview.html b/docs/0.62/webview.html index 3aa16049efa..bf91e84a11d 100644 --- a/docs/0.62/webview.html +++ b/docs/0.62/webview.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
class MyInlineWeb extends Component {
render() {
return (
<WebView
originWhitelist={['*']}
source={{ html: '<h1>Hello world</h1>' }}
/>
);
}
}

You can use this component to navigate back and forth in the web view's history and configure various properties for the web content.

On iOS, the useWebKit prop can be used to opt into a WKWebView-backed implementation.

Security Warning: Currently, onMessage and postMessage do not allow specifying an origin. This can lead to cross-site scripting attacks if an unexpected document is loaded within a WebView instance. Please refer to the MDN documentation for Window.postMessage() for more details on the security implications of this.

Reference

Props

Inherits View Props.

source

Loads static HTML or a URI (with optional headers) in the WebView. Note that static HTML will require setting originWhitelist to ["*"].

The object passed to source can have either of the following shapes:

Load uri

Static HTML

TypeRequired
objectNo

automaticallyAdjustContentInsets

Controls whether to adjust the content inset for web views that are placed behind a navigation bar, tab bar, or toolbar. The default value is true.

TypeRequired
boolNo

injectJavaScript

Function that accepts a string that will be passed to the WebView and executed immediately as JavaScript.

TypeRequired
functionNo

injectedJavaScript

Set this to provide JavaScript that will be injected into the web page when the view loads.

TypeRequired
stringNo

mediaPlaybackRequiresUserAction

Boolean that determines whether HTML5 audio and video requires the user to tap them before they start playing. The default value is true.

TypeRequired
boolNo

nativeConfig

Override the native component used to render the WebView. Enables a custom native WebView which uses the same JavaScript as the original WebView.

The nativeConfig prop expects an object with the following keys:

TypeRequired
objectNo

onError

Function that is invoked when the WebView load fails.

TypeRequired
functionNo

onLoad

Function that is invoked when the WebView has finished loading.

TypeRequired
functionNo

onLoadEnd

Function that is invoked when the WebView load succeeds or fails.

TypeRequired
functionNo

onLoadStart

Function that is invoked when the WebView starts loading.

TypeRequired
functionNo

onMessage

A function that is invoked when the webview calls window.postMessage. Setting this property will inject a postMessage global into your webview, but will still call pre-existing values of postMessage.

window.postMessage accepts one argument, data, which will be available on the event object, event.nativeEvent.data. data must be a string.

TypeRequired
functionNo

onNavigationStateChange

Function that is invoked when the WebView loading starts or ends.

TypeRequired
functionNo

originWhitelist

List of origin strings to allow being navigated to. The strings allow wildcards and get matched against only the origin (not the full URL). If the user taps to navigate to a new page but the new page is not in this safelist, the URL will be handled by the OS. The default safelistlisted origins are "http://*" and "https://*".

TypeRequired
array of stringsNo

renderError

Function that returns a view to show if there's an error.

TypeRequired
functionNo

renderLoading

Function that returns a loading indicator. The startInLoadingState prop must be set to true in order to use this prop.

TypeRequired
functionNo

scalesPageToFit

Boolean that controls whether the web content is scaled to fit the view and enables the user to change the scale. The default value is true.

On iOS, when useWebKit=true, this prop will not work.

TypeRequired
boolNo

onShouldStartLoadWithRequest

Function that allows custom handling of any web view requests. Return true from the function to continue loading the request and false to stop loading.

TypeRequiredPlatform
functionNoiOS

startInLoadingState

Boolean value that forces the WebView to show the loading view on the first load. This prop must be set to true in order for the renderLoading prop to work.

TypeRequired
boolNo

decelerationRate

A floating-point number that determines how quickly the scroll view decelerates after the user lifts their finger. You may also use the string shortcuts "normal" and "fast" which match the underlying iOS settings for UIScrollViewDecelerationRateNormal and UIScrollViewDecelerationRateFast respectively:

TypeRequiredPlatform
numberNoiOS

domStorageEnabled

Boolean value to control whether DOM Storage is enabled. Used only in Android.

TypeRequiredPlatform
boolNoAndroid

javaScriptEnabled

Boolean value to enable JavaScript in the WebView. Used on Android only as JavaScript is enabled by default on iOS. The default value is true.

TypeRequiredPlatform
boolNoAndroid

mixedContentMode

Specifies the mixed content mode. i.e WebView will allow a secure origin to load content from any other origin.

Possible values for mixedContentMode are:

TypeRequiredPlatform
stringNoAndroid

thirdPartyCookiesEnabled

Boolean value to enable third party cookies in the WebView. Used on Android Lollipop and above only as third party cookies are enabled by default on Android Kitkat and below and on iOS. The default value is true.

TypeRequiredPlatform
boolNoAndroid

userAgent

Sets the user-agent for the WebView.

TypeRequiredPlatform
stringNoAndroid

allowsInlineMediaPlayback

Boolean that determines whether HTML5 videos play inline or use the native full-screen controller. The default value is false.

NOTE

In order for video to play inline, not only does this property need to be set to true, but the video element in the HTML document must also include the webkit-playsinline attribute.

TypeRequiredPlatform
boolNoiOS

bounces

Boolean value that determines whether the web view bounces when it reaches the edge of the content. The default value is true.

TypeRequiredPlatform
boolNoiOS

contentInset

The amount by which the web view content is inset from the edges of the scroll view. Defaults to {top: 0, left: 0, bottom: 0, right: 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

dataDetectorTypes

Determines the types of data converted to clickable URLs in the web view's content. By default only phone numbers are detected.

You can provide one type or an array of many types.

Possible values for dataDetectorTypes are:

With the new WebKit implementation, we have three new values:

TypeRequiredPlatform
string, or arrayNoiOS

scrollEnabled

Boolean value that determines whether scrolling is enabled in the WebView. The default value is true.

TypeRequiredPlatform
boolNoiOS

geolocationEnabled

Set whether Geolocation is enabled in the WebView. The default value is false. Used only in Android.

TypeRequiredPlatform
boolNoAndroid

allowUniversalAccessFromFileURLs

Boolean that sets whether JavaScript running in the context of a file scheme URL should be allowed to access content from any origin. Including accessing content from other file scheme URLs. The default value is false.

TypeRequiredPlatform
boolNoAndroid

allowFileAccess

Boolean that sets whether the WebView has access to the file system. The default value is false.

TypeRequiredPlatform
boolNoAndroid

useWebKit

If true, use WKWebView instead of UIWebView.

TypeRequiredPlatform
booleanNoiOS

url

Deprecated. Use the source prop instead.

TypeRequired
stringNo

html

Deprecated. Use the source prop instead.

TypeRequired
stringNo

Methods

extraNativeComponentConfig()

static extraNativeComponentConfig()

goForward()

goForward();

Go forward one page in the web view's history.

goBack()

goBack();

Go back one page in the web view's history.

reload()

reload();

Reloads the current page.

stopLoading()

stopLoading();

Stop loading the current page.

Edit this page
Last updated on
- + diff --git a/docs/0.62/webview/index.html b/docs/0.62/webview/index.html index 3aa16049efa..bf91e84a11d 100644 --- a/docs/0.62/webview/index.html +++ b/docs/0.62/webview/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
class MyInlineWeb extends Component {
render() {
return (
<WebView
originWhitelist={['*']}
source={{ html: '<h1>Hello world</h1>' }}
/>
);
}
}

You can use this component to navigate back and forth in the web view's history and configure various properties for the web content.

On iOS, the useWebKit prop can be used to opt into a WKWebView-backed implementation.

Security Warning: Currently, onMessage and postMessage do not allow specifying an origin. This can lead to cross-site scripting attacks if an unexpected document is loaded within a WebView instance. Please refer to the MDN documentation for Window.postMessage() for more details on the security implications of this.

Reference

Props

Inherits View Props.

source

Loads static HTML or a URI (with optional headers) in the WebView. Note that static HTML will require setting originWhitelist to ["*"].

The object passed to source can have either of the following shapes:

Load uri

Static HTML

TypeRequired
objectNo

automaticallyAdjustContentInsets

Controls whether to adjust the content inset for web views that are placed behind a navigation bar, tab bar, or toolbar. The default value is true.

TypeRequired
boolNo

injectJavaScript

Function that accepts a string that will be passed to the WebView and executed immediately as JavaScript.

TypeRequired
functionNo

injectedJavaScript

Set this to provide JavaScript that will be injected into the web page when the view loads.

TypeRequired
stringNo

mediaPlaybackRequiresUserAction

Boolean that determines whether HTML5 audio and video requires the user to tap them before they start playing. The default value is true.

TypeRequired
boolNo

nativeConfig

Override the native component used to render the WebView. Enables a custom native WebView which uses the same JavaScript as the original WebView.

The nativeConfig prop expects an object with the following keys:

TypeRequired
objectNo

onError

Function that is invoked when the WebView load fails.

TypeRequired
functionNo

onLoad

Function that is invoked when the WebView has finished loading.

TypeRequired
functionNo

onLoadEnd

Function that is invoked when the WebView load succeeds or fails.

TypeRequired
functionNo

onLoadStart

Function that is invoked when the WebView starts loading.

TypeRequired
functionNo

onMessage

A function that is invoked when the webview calls window.postMessage. Setting this property will inject a postMessage global into your webview, but will still call pre-existing values of postMessage.

window.postMessage accepts one argument, data, which will be available on the event object, event.nativeEvent.data. data must be a string.

TypeRequired
functionNo

onNavigationStateChange

Function that is invoked when the WebView loading starts or ends.

TypeRequired
functionNo

originWhitelist

List of origin strings to allow being navigated to. The strings allow wildcards and get matched against only the origin (not the full URL). If the user taps to navigate to a new page but the new page is not in this safelist, the URL will be handled by the OS. The default safelistlisted origins are "http://*" and "https://*".

TypeRequired
array of stringsNo

renderError

Function that returns a view to show if there's an error.

TypeRequired
functionNo

renderLoading

Function that returns a loading indicator. The startInLoadingState prop must be set to true in order to use this prop.

TypeRequired
functionNo

scalesPageToFit

Boolean that controls whether the web content is scaled to fit the view and enables the user to change the scale. The default value is true.

On iOS, when useWebKit=true, this prop will not work.

TypeRequired
boolNo

onShouldStartLoadWithRequest

Function that allows custom handling of any web view requests. Return true from the function to continue loading the request and false to stop loading.

TypeRequiredPlatform
functionNoiOS

startInLoadingState

Boolean value that forces the WebView to show the loading view on the first load. This prop must be set to true in order for the renderLoading prop to work.

TypeRequired
boolNo

decelerationRate

A floating-point number that determines how quickly the scroll view decelerates after the user lifts their finger. You may also use the string shortcuts "normal" and "fast" which match the underlying iOS settings for UIScrollViewDecelerationRateNormal and UIScrollViewDecelerationRateFast respectively:

TypeRequiredPlatform
numberNoiOS

domStorageEnabled

Boolean value to control whether DOM Storage is enabled. Used only in Android.

TypeRequiredPlatform
boolNoAndroid

javaScriptEnabled

Boolean value to enable JavaScript in the WebView. Used on Android only as JavaScript is enabled by default on iOS. The default value is true.

TypeRequiredPlatform
boolNoAndroid

mixedContentMode

Specifies the mixed content mode. i.e WebView will allow a secure origin to load content from any other origin.

Possible values for mixedContentMode are:

TypeRequiredPlatform
stringNoAndroid

thirdPartyCookiesEnabled

Boolean value to enable third party cookies in the WebView. Used on Android Lollipop and above only as third party cookies are enabled by default on Android Kitkat and below and on iOS. The default value is true.

TypeRequiredPlatform
boolNoAndroid

userAgent

Sets the user-agent for the WebView.

TypeRequiredPlatform
stringNoAndroid

allowsInlineMediaPlayback

Boolean that determines whether HTML5 videos play inline or use the native full-screen controller. The default value is false.

NOTE

In order for video to play inline, not only does this property need to be set to true, but the video element in the HTML document must also include the webkit-playsinline attribute.

TypeRequiredPlatform
boolNoiOS

bounces

Boolean value that determines whether the web view bounces when it reaches the edge of the content. The default value is true.

TypeRequiredPlatform
boolNoiOS

contentInset

The amount by which the web view content is inset from the edges of the scroll view. Defaults to {top: 0, left: 0, bottom: 0, right: 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

dataDetectorTypes

Determines the types of data converted to clickable URLs in the web view's content. By default only phone numbers are detected.

You can provide one type or an array of many types.

Possible values for dataDetectorTypes are:

With the new WebKit implementation, we have three new values:

TypeRequiredPlatform
string, or arrayNoiOS

scrollEnabled

Boolean value that determines whether scrolling is enabled in the WebView. The default value is true.

TypeRequiredPlatform
boolNoiOS

geolocationEnabled

Set whether Geolocation is enabled in the WebView. The default value is false. Used only in Android.

TypeRequiredPlatform
boolNoAndroid

allowUniversalAccessFromFileURLs

Boolean that sets whether JavaScript running in the context of a file scheme URL should be allowed to access content from any origin. Including accessing content from other file scheme URLs. The default value is false.

TypeRequiredPlatform
boolNoAndroid

allowFileAccess

Boolean that sets whether the WebView has access to the file system. The default value is false.

TypeRequiredPlatform
boolNoAndroid

useWebKit

If true, use WKWebView instead of UIWebView.

TypeRequiredPlatform
booleanNoiOS

url

Deprecated. Use the source prop instead.

TypeRequired
stringNo

html

Deprecated. Use the source prop instead.

TypeRequired
stringNo

Methods

extraNativeComponentConfig()

static extraNativeComponentConfig()

goForward()

goForward();

Go forward one page in the web view's history.

goBack()

goBack();

Go back one page in the web view's history.

reload()

reload();

Reloads the current page.

stopLoading()

stopLoading();

Stop loading the current page.

Edit this page
Last updated on
- + diff --git a/docs/_getting-started-linux-android.html b/docs/_getting-started-linux-android.html index ca9ff4475a8..ba73f4f1ebc 100644 --- a/docs/_getting-started-linux-android.html +++ b/docs/_getting-started-linux-android.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@

_getting-started-linux-android

Installing dependencies

You will need Node, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node

Follow the installation instructions for your Linux distribution to install Node 10 or newer.

Java Development Kit

React Native requires at least the version 8 of the Java SE Development Kit (JDK). You may download and install OpenJDK from AdoptOpenJDK or your system packager. You may also Download and install Oracle JDK 14 if desired.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

Add the following lines to your $HOME/.bash_profile or $HOME/.bashrc (if you are using zsh then ~/.zprofile or ~/.zshrc) config file:

export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

.bash_profile is specific to bash. If you're using another shell, you will need to edit the appropriate shell-specific config file.

Type source $HOME/.bash_profile for bash or source $HOME/.zprofile to load the config into your current shell. Verify that ANDROID_HOME has been set by running echo $ANDROID_HOME and the appropriate directories have been added to your path by running echo $PATH.

Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Watchman

Follow the Watchman installation guide to compile and install Watchman from source.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance and increased compatibility in certain edge cases (translation: you may be able to get by without installing this, but your mileage may vary; installing this now may save you from a headache later).

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

We recommend configuring VM acceleration on your system to improve performance. Once you've followed those instructions, go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (Ctrl + M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/_getting-started-linux-android/index.html b/docs/_getting-started-linux-android/index.html index ca9ff4475a8..ba73f4f1ebc 100644 --- a/docs/_getting-started-linux-android/index.html +++ b/docs/_getting-started-linux-android/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@

_getting-started-linux-android

Installing dependencies

You will need Node, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node

Follow the installation instructions for your Linux distribution to install Node 10 or newer.

Java Development Kit

React Native requires at least the version 8 of the Java SE Development Kit (JDK). You may download and install OpenJDK from AdoptOpenJDK or your system packager. You may also Download and install Oracle JDK 14 if desired.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

Add the following lines to your $HOME/.bash_profile or $HOME/.bashrc (if you are using zsh then ~/.zprofile or ~/.zshrc) config file:

export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

.bash_profile is specific to bash. If you're using another shell, you will need to edit the appropriate shell-specific config file.

Type source $HOME/.bash_profile for bash or source $HOME/.zprofile to load the config into your current shell. Verify that ANDROID_HOME has been set by running echo $ANDROID_HOME and the appropriate directories have been added to your path by running echo $PATH.

Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Watchman

Follow the Watchman installation guide to compile and install Watchman from source.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance and increased compatibility in certain edge cases (translation: you may be able to get by without installing this, but your mileage may vary; installing this now may save you from a headache later).

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

We recommend configuring VM acceleration on your system to improve performance. Once you've followed those instructions, go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (Ctrl + M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/_getting-started-macos-android.html b/docs/_getting-started-macos-android.html index d1716acbdeb..f396135cc83 100644 --- a/docs/_getting-started-macos-android.html +++ b/docs/_getting-started-macos-android.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@

_getting-started-macos-android

Installing dependencies

You will need Node, Watchman, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node & Watchman

We recommend installing Node and Watchman using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install node
brew install watchman

If you have already installed Node on your system, make sure it is Node 10 or newer.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

Java Development Kit

We recommend installing JDK using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install --cask adoptopenjdk/openjdk/adoptopenjdk8

If you have already installed JDK on your system, make sure it is JDK 8 or newer.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device
  • If you are not already using Hyper-V: Performance (Intel ® HAXM) (See here for AMD or Hyper-V)

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

Android Studio Welcome

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

Add the following lines to your $HOME/.bash_profile or $HOME/.bashrc (if you are using zsh then ~/.zprofile or ~/.zshrc) config file:

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

.bash_profile is specific to bash. If you're using another shell, you will need to edit the appropriate shell-specific config file.

Type source $HOME/.bash_profile for bash or source $HOME/.zprofile to load the config into your current shell. Verify that ANDROID_HOME has been set by running echo $ANDROID_HOME and the appropriate directories have been added to your path by running echo $PATH.

Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

If you don't have HAXM installed, follow these instructions to set it up, then go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

AwesomeProject on Android

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (⌘M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/_getting-started-macos-android/index.html b/docs/_getting-started-macos-android/index.html index d1716acbdeb..f396135cc83 100644 --- a/docs/_getting-started-macos-android/index.html +++ b/docs/_getting-started-macos-android/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@

_getting-started-macos-android

Installing dependencies

You will need Node, Watchman, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node & Watchman

We recommend installing Node and Watchman using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install node
brew install watchman

If you have already installed Node on your system, make sure it is Node 10 or newer.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

Java Development Kit

We recommend installing JDK using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install --cask adoptopenjdk/openjdk/adoptopenjdk8

If you have already installed JDK on your system, make sure it is JDK 8 or newer.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device
  • If you are not already using Hyper-V: Performance (Intel ® HAXM) (See here for AMD or Hyper-V)

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

Android Studio Welcome

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

Add the following lines to your $HOME/.bash_profile or $HOME/.bashrc (if you are using zsh then ~/.zprofile or ~/.zshrc) config file:

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

.bash_profile is specific to bash. If you're using another shell, you will need to edit the appropriate shell-specific config file.

Type source $HOME/.bash_profile for bash or source $HOME/.zprofile to load the config into your current shell. Verify that ANDROID_HOME has been set by running echo $ANDROID_HOME and the appropriate directories have been added to your path by running echo $PATH.

Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

If you don't have HAXM installed, follow these instructions to set it up, then go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

AwesomeProject on Android

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (⌘M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/_getting-started-macos-ios.html b/docs/_getting-started-macos-ios.html index 73032d3cdc3..b8f5d50a8e1 100644 --- a/docs/_getting-started-macos-ios.html +++ b/docs/_getting-started-macos-ios.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@

_getting-started-macos-ios

Installing dependencies

You will need Node, Watchman, the React Native command line interface, and Xcode.

While you can use any editor of your choice to develop your app, you will need to install Xcode in order to set up the necessary tooling to build your React Native app for iOS.

Node & Watchman

We recommend installing Node and Watchman using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install node
brew install watchman

If you have already installed Node on your system, make sure it is Node 10 or newer.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

Xcode & CocoaPods

The easiest way to install Xcode is via the Mac App Store. Installing Xcode will also install the iOS Simulator and all the necessary tools to build your iOS app.

If you have already installed Xcode on your system, make sure it is version 9.4 or newer.

Command Line Tools

You will also need to install the Xcode Command Line Tools. Open Xcode, then choose "Preferences..." from the Xcode menu. Go to the Locations panel and install the tools by selecting the most recent version in the Command Line Tools dropdown.

Xcode Command Line Tools

Installing an iOS Simulator in Xcode

To install a simulator, open Xcode > Preferences... and select the Components tab. Select a simulator with the corresponding version of iOS you wish to use.

CocoaPods

CocoaPods is built with Ruby and it will be installable with the default Ruby available on macOS. You can use a Ruby Version manager, however we recommend that you use the standard Ruby available on macOS unless you know what you're doing.

Using the default Ruby install will require you to use sudo when installing gems. (This is only an issue for the duration of the gem installation, though.)

sudo gem install cocoapods

For more information, please visit CocoaPods Getting Started guide.

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

You can use React Native's built-in command line interface to generate a new project. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding iOS support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Note If the above command is failing, you may have old version of react-native or react-native-cli installed globally on your pc. Try uninstalling the cli and run the cli using npx.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-ios

You should see your new app running in the iOS Simulator shortly.

AwesomeProject on iOS

npx react-native run-ios is one way to run your app. You can also run it directly from within Xcode.

If you can't get this to work, see the Troubleshooting page.

Running on a device

The above command will automatically run your app on the iOS Simulator by default. If you want to run the app on an actual physical iOS device, please follow the instructions here.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Hit ⌘R in your iOS Simulator to reload the app and see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/_getting-started-macos-ios/index.html b/docs/_getting-started-macos-ios/index.html index 73032d3cdc3..b8f5d50a8e1 100644 --- a/docs/_getting-started-macos-ios/index.html +++ b/docs/_getting-started-macos-ios/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@

_getting-started-macos-ios

Installing dependencies

You will need Node, Watchman, the React Native command line interface, and Xcode.

While you can use any editor of your choice to develop your app, you will need to install Xcode in order to set up the necessary tooling to build your React Native app for iOS.

Node & Watchman

We recommend installing Node and Watchman using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install node
brew install watchman

If you have already installed Node on your system, make sure it is Node 10 or newer.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

Xcode & CocoaPods

The easiest way to install Xcode is via the Mac App Store. Installing Xcode will also install the iOS Simulator and all the necessary tools to build your iOS app.

If you have already installed Xcode on your system, make sure it is version 9.4 or newer.

Command Line Tools

You will also need to install the Xcode Command Line Tools. Open Xcode, then choose "Preferences..." from the Xcode menu. Go to the Locations panel and install the tools by selecting the most recent version in the Command Line Tools dropdown.

Xcode Command Line Tools

Installing an iOS Simulator in Xcode

To install a simulator, open Xcode > Preferences... and select the Components tab. Select a simulator with the corresponding version of iOS you wish to use.

CocoaPods

CocoaPods is built with Ruby and it will be installable with the default Ruby available on macOS. You can use a Ruby Version manager, however we recommend that you use the standard Ruby available on macOS unless you know what you're doing.

Using the default Ruby install will require you to use sudo when installing gems. (This is only an issue for the duration of the gem installation, though.)

sudo gem install cocoapods

For more information, please visit CocoaPods Getting Started guide.

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

You can use React Native's built-in command line interface to generate a new project. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding iOS support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Note If the above command is failing, you may have old version of react-native or react-native-cli installed globally on your pc. Try uninstalling the cli and run the cli using npx.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-ios

You should see your new app running in the iOS Simulator shortly.

AwesomeProject on iOS

npx react-native run-ios is one way to run your app. You can also run it directly from within Xcode.

If you can't get this to work, see the Troubleshooting page.

Running on a device

The above command will automatically run your app on the iOS Simulator by default. If you want to run the app on an actual physical iOS device, please follow the instructions here.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Hit ⌘R in your iOS Simulator to reload the app and see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/_getting-started-windows-android.html b/docs/_getting-started-windows-android.html index bb579149d77..5ca700f7405 100644 --- a/docs/_getting-started-windows-android.html +++ b/docs/_getting-started-windows-android.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@

_getting-started-windows-android

Installing dependencies

You will need Node, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node, JDK

We recommend installing Node via Chocolatey, a popular package manager for Windows.

If you want to be able to switch between different Node versions, you might want to install Node via nvm-windows, a Node version manager for Windows.

React Native also requires Java SE Development Kit (JDK), which can be installed using Chocolatey as well.

Open an Administrator Command Prompt (right click Command Prompt and select "Run as Administrator"), then run the following command:

choco install -y nodejs.install openjdk8

If you have already installed Node on your system, make sure it is Node 10 or newer. If you already have a JDK on your system, make sure it is version 8 or newer.

You can find additional installation options on Node's Downloads page.

If you're using the latest version of Java Development Kit, you'll need to change the Gradle version of your project so it can recognize the JDK. You can do that by going to {project root folder}\android\gradle\wrapper\gradle-wrapper.properties and changing the distributionUrl value to upgrade the Gradle version. You can check out here the lastest releases of Gradle.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device
  • If you are not already using Hyper-V: Performance (Intel ® HAXM) (See here for AMD or Hyper-V)

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

Android Studio Welcome

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

  1. Open the Windows Control Panel.
  2. Click on User Accounts, then click User Accounts again
  3. Click on Change my environment variables
  4. Click on New... to create a new ANDROID_HOME user variable that points to the path to your Android SDK:

ANDROID_HOME Environment Variable

The SDK is installed, by default, at the following location:

%LOCALAPPDATA%\Android\Sdk

You can find the actual location of the SDK in the Android Studio "Settings" dialog, under Appearance & Behavior → System Settings → Android SDK.

Open a new Command Prompt window to ensure the new environment variable is loaded before proceeding to the next step.

  1. Open powershell
  2. Copy and paste Get-ChildItem -Path Env:\ into powershell
  3. Verify ANDROID_HOME has been added

4. Add platform-tools to Path

  1. Open the Windows Control Panel.
  2. Click on User Accounts, then click User Accounts again
  3. Click on Change my environment variables
  4. Select the Path variable.
  5. Click Edit.
  6. Click New and add the path to platform-tools to the list.

The default location for this folder is:

%LOCALAPPDATA%\Android\Sdk\platform-tools

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

If you don't have HAXM installed, click on "Install HAXM" or follow these instructions to set it up, then go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

AwesomeProject on Android

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (Ctrl + M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/_getting-started-windows-android/index.html b/docs/_getting-started-windows-android/index.html index bb579149d77..5ca700f7405 100644 --- a/docs/_getting-started-windows-android/index.html +++ b/docs/_getting-started-windows-android/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@

_getting-started-windows-android

Installing dependencies

You will need Node, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node, JDK

We recommend installing Node via Chocolatey, a popular package manager for Windows.

If you want to be able to switch between different Node versions, you might want to install Node via nvm-windows, a Node version manager for Windows.

React Native also requires Java SE Development Kit (JDK), which can be installed using Chocolatey as well.

Open an Administrator Command Prompt (right click Command Prompt and select "Run as Administrator"), then run the following command:

choco install -y nodejs.install openjdk8

If you have already installed Node on your system, make sure it is Node 10 or newer. If you already have a JDK on your system, make sure it is version 8 or newer.

You can find additional installation options on Node's Downloads page.

If you're using the latest version of Java Development Kit, you'll need to change the Gradle version of your project so it can recognize the JDK. You can do that by going to {project root folder}\android\gradle\wrapper\gradle-wrapper.properties and changing the distributionUrl value to upgrade the Gradle version. You can check out here the lastest releases of Gradle.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device
  • If you are not already using Hyper-V: Performance (Intel ® HAXM) (See here for AMD or Hyper-V)

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

Android Studio Welcome

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

  1. Open the Windows Control Panel.
  2. Click on User Accounts, then click User Accounts again
  3. Click on Change my environment variables
  4. Click on New... to create a new ANDROID_HOME user variable that points to the path to your Android SDK:

ANDROID_HOME Environment Variable

The SDK is installed, by default, at the following location:

%LOCALAPPDATA%\Android\Sdk

You can find the actual location of the SDK in the Android Studio "Settings" dialog, under Appearance & Behavior → System Settings → Android SDK.

Open a new Command Prompt window to ensure the new environment variable is loaded before proceeding to the next step.

  1. Open powershell
  2. Copy and paste Get-ChildItem -Path Env:\ into powershell
  3. Verify ANDROID_HOME has been added

4. Add platform-tools to Path

  1. Open the Windows Control Panel.
  2. Click on User Accounts, then click User Accounts again
  3. Click on Change my environment variables
  4. Select the Path variable.
  5. Click Edit.
  6. Click New and add the path to platform-tools to the list.

The default location for this folder is:

%LOCALAPPDATA%\Android\Sdk\platform-tools

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Platform Specific Code). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

If you don't have HAXM installed, click on "Install HAXM" or follow these instructions to set it up, then go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

AwesomeProject on Android

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (Ctrl + M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/_integration-with-exisiting-apps-java.html b/docs/_integration-with-exisiting-apps-java.html index 493ffa50763..562b6b0c2b4 100644 --- a/docs/_integration-with-exisiting-apps-java.html +++ b/docs/_integration-with-exisiting-apps-java.html @@ -19,7 +19,7 @@ - + @@ -48,7 +48,7 @@
if (mReactInstanceManager != null) {
mReactInstanceManager.onHostDestroy(this);
}
if (mReactRootView != null) {
mReactRootView.unmountReactApplication();
}
}

We also need to pass back button events to React Native:

@Override
public void onBackPressed() {
if (mReactInstanceManager != null) {
mReactInstanceManager.onBackPressed();
} else {
super.onBackPressed();
}
}

This allows JavaScript to control what happens when the user presses the hardware back button (e.g. to implement navigation). When JavaScript doesn't handle the back button press, your invokeDefaultOnBackPressed method will be called. By default this finishes your Activity.

Finally, we need to hook up the dev menu. By default, this is activated by (rage) shaking the device, but this is not very useful in emulators. So we make it show when you press the hardware menu button (use Ctrl + M if you're using Android Studio emulator):

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
if (keyCode == KeyEvent.KEYCODE_MENU && mReactInstanceManager != null) {
mReactInstanceManager.showDevOptionsDialog();
return true;
}
return super.onKeyUp(keyCode, event);
}

Now your activity is ready to run some JavaScript code.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ yarn start
2. Run the app

Now build and run your Android app as normal.

Once you reach your React-powered activity inside the app, it should load the JavaScript code from the development server and display:

Screenshot

Creating a release build in Android Studio

You can use Android Studio to create your release builds too! It’s as quick as creating release builds of your previously-existing native Android app. There’s one additional step, which you’ll have to do before every release build. You need to execute the following to create a React Native bundle, which will be included with your native Android app:

$ npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/com/your-company-name/app-package-name/src/main/assets/index.android.bundle --assets-dest android/com/your-company-name/app-package-name/src/main/res/

Don’t forget to replace the paths with correct ones and create the assets folder if it doesn’t exist.

Now, create a release build of your native app from within Android Studio as usual and you should be good to go!

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/_integration-with-exisiting-apps-java/index.html b/docs/_integration-with-exisiting-apps-java/index.html index 493ffa50763..562b6b0c2b4 100644 --- a/docs/_integration-with-exisiting-apps-java/index.html +++ b/docs/_integration-with-exisiting-apps-java/index.html @@ -19,7 +19,7 @@ - + @@ -48,7 +48,7 @@
if (mReactInstanceManager != null) {
mReactInstanceManager.onHostDestroy(this);
}
if (mReactRootView != null) {
mReactRootView.unmountReactApplication();
}
}

We also need to pass back button events to React Native:

@Override
public void onBackPressed() {
if (mReactInstanceManager != null) {
mReactInstanceManager.onBackPressed();
} else {
super.onBackPressed();
}
}

This allows JavaScript to control what happens when the user presses the hardware back button (e.g. to implement navigation). When JavaScript doesn't handle the back button press, your invokeDefaultOnBackPressed method will be called. By default this finishes your Activity.

Finally, we need to hook up the dev menu. By default, this is activated by (rage) shaking the device, but this is not very useful in emulators. So we make it show when you press the hardware menu button (use Ctrl + M if you're using Android Studio emulator):

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
if (keyCode == KeyEvent.KEYCODE_MENU && mReactInstanceManager != null) {
mReactInstanceManager.showDevOptionsDialog();
return true;
}
return super.onKeyUp(keyCode, event);
}

Now your activity is ready to run some JavaScript code.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ yarn start
2. Run the app

Now build and run your Android app as normal.

Once you reach your React-powered activity inside the app, it should load the JavaScript code from the development server and display:

Screenshot

Creating a release build in Android Studio

You can use Android Studio to create your release builds too! It’s as quick as creating release builds of your previously-existing native Android app. There’s one additional step, which you’ll have to do before every release build. You need to execute the following to create a React Native bundle, which will be included with your native Android app:

$ npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/com/your-company-name/app-package-name/src/main/assets/index.android.bundle --assets-dest android/com/your-company-name/app-package-name/src/main/res/

Don’t forget to replace the paths with correct ones and create the assets folder if it doesn’t exist.

Now, create a release build of your native app from within Android Studio as usual and you should be good to go!

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/_integration-with-exisiting-apps-objc.html b/docs/_integration-with-exisiting-apps-objc.html index 7c54c1b09a1..ae71e63dbeb 100644 --- a/docs/_integration-with-exisiting-apps-objc.html +++ b/docs/_integration-with-exisiting-apps-objc.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
RCTRootView *rootView =
[[RCTRootView alloc] initWithBundleURL: jsCodeLocation
moduleName: @"RNHighScores"
initialProperties:
@{
@"scores" : @[
@{
@"name" : @"Alex",
@"value": @"42"
},
@{
@"name" : @"Joel",
@"value": @"10"
}
]
}
launchOptions: nil];
UIViewController *vc = [[UIViewController alloc] init];
vc.view = rootView;
[self presentViewController:vc animated:YES completion:nil];
}

Note that RCTRootView initWithURL starts up a new JSC VM. To save resources and simplify the communication between RN views in different parts of your native app, you can have multiple views powered by React Native that are associated with a single JS runtime. To do that, instead of using [RCTRootView alloc] initWithURL, use RCTBridge initWithBundleURL to create a bridge and then use RCTRootView initWithBridge.

When moving your app to production, the NSURL can point to a pre-bundled file on disk via something like [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];. You can use the react-native-xcode.sh script in node_modules/react-native/scripts/ to generate that pre-bundled file.

3. Wire Up

Wire up the new link in the main menu to the newly added event handler method.

Event Path

One of the easier ways to do this is to open the view in the storyboard and right click on the new link. Select something such as the Touch Up Inside event, drag that to the storyboard and then select the created method from the list provided.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Add App Transport Security exception

Apple has blocked implicit cleartext HTTP resource loading. So we need to add the following our project's Info.plist (or equivalent) file.

<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>localhost</key>
<dict>
<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
</dict>

App Transport Security is good for your users. Make sure to re-enable it prior to releasing your app for production.

2. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ npm start
3. Run the app

If you are using Xcode or your favorite editor, build and run your native iOS application as normal. Alternatively, you can run the app from the command line using:

# From the root of your project
$ npx react-native run-ios

In our sample application, you should see the link to the "High Scores" and then when you click on that you will see the rendering of your React Native component.

Here is the native application home screen:

Home Screen

Here is the React Native high score screen:

High Scores

If you are getting module resolution issues when running your application please see this GitHub issue for information and possible resolution. This comment seemed to be the latest possible resolution.

See the Code

You can examine the code that added the React Native screen to our sample app on GitHub.

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/_integration-with-exisiting-apps-objc/index.html b/docs/_integration-with-exisiting-apps-objc/index.html index 7c54c1b09a1..ae71e63dbeb 100644 --- a/docs/_integration-with-exisiting-apps-objc/index.html +++ b/docs/_integration-with-exisiting-apps-objc/index.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
RCTRootView *rootView =
[[RCTRootView alloc] initWithBundleURL: jsCodeLocation
moduleName: @"RNHighScores"
initialProperties:
@{
@"scores" : @[
@{
@"name" : @"Alex",
@"value": @"42"
},
@{
@"name" : @"Joel",
@"value": @"10"
}
]
}
launchOptions: nil];
UIViewController *vc = [[UIViewController alloc] init];
vc.view = rootView;
[self presentViewController:vc animated:YES completion:nil];
}

Note that RCTRootView initWithURL starts up a new JSC VM. To save resources and simplify the communication between RN views in different parts of your native app, you can have multiple views powered by React Native that are associated with a single JS runtime. To do that, instead of using [RCTRootView alloc] initWithURL, use RCTBridge initWithBundleURL to create a bridge and then use RCTRootView initWithBridge.

When moving your app to production, the NSURL can point to a pre-bundled file on disk via something like [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];. You can use the react-native-xcode.sh script in node_modules/react-native/scripts/ to generate that pre-bundled file.

3. Wire Up

Wire up the new link in the main menu to the newly added event handler method.

Event Path

One of the easier ways to do this is to open the view in the storyboard and right click on the new link. Select something such as the Touch Up Inside event, drag that to the storyboard and then select the created method from the list provided.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Add App Transport Security exception

Apple has blocked implicit cleartext HTTP resource loading. So we need to add the following our project's Info.plist (or equivalent) file.

<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>localhost</key>
<dict>
<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
</dict>

App Transport Security is good for your users. Make sure to re-enable it prior to releasing your app for production.

2. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ npm start
3. Run the app

If you are using Xcode or your favorite editor, build and run your native iOS application as normal. Alternatively, you can run the app from the command line using:

# From the root of your project
$ npx react-native run-ios

In our sample application, you should see the link to the "High Scores" and then when you click on that you will see the rendering of your React Native component.

Here is the native application home screen:

Home Screen

Here is the React Native high score screen:

High Scores

If you are getting module resolution issues when running your application please see this GitHub issue for information and possible resolution. This comment seemed to be the latest possible resolution.

See the Code

You can examine the code that added the React Native screen to our sample app on GitHub.

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/_integration-with-exisiting-apps-swift.html b/docs/_integration-with-exisiting-apps-swift.html index 3add96a6d95..e7a407dd7b9 100644 --- a/docs/_integration-with-exisiting-apps-swift.html +++ b/docs/_integration-with-exisiting-apps-swift.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
let rootView = RCTRootView(
bundleURL: jsCodeLocation,
moduleName: "RNHighScores",
initialProperties: mockData as [NSObject : AnyObject],
launchOptions: nil
)
let vc = UIViewController()
vc.view = rootView
self.present(vc, animated: true, completion: nil)
}

Note that RCTRootView bundleURL starts up a new JSC VM. To save resources and simplify the communication between RN views in different parts of your native app, you can have multiple views powered by React Native that are associated with a single JS runtime. To do that, instead of using RCTRootView bundleURL, use RCTBridge initWithBundleURL to create a bridge and then use RCTRootView initWithBridge.

When moving your app to production, the NSURL can point to a pre-bundled file on disk via something like let mainBundle = NSBundle(URLForResource: "main" withExtension:"jsbundle"). You can use the react-native-xcode.sh script in node_modules/react-native/scripts/ to generate that pre-bundled file.

3. Wire Up

Wire up the new link in the main menu to the newly added event handler method.

Event Path

One of the easier ways to do this is to open the view in the storyboard and right click on the new link. Select something such as the Touch Up Inside event, drag that to the storyboard and then select the created method from the list provided.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Add App Transport Security exception

Apple has blocked implicit cleartext HTTP resource loading. So we need to add the following our project's Info.plist (or equivalent) file.

<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>localhost</key>
<dict>
<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
</dict>

App Transport Security is good for your users. Make sure to re-enable it prior to releasing your app for production.

2. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ npm start
3. Run the app

If you are using Xcode or your favorite editor, build and run your native iOS application as normal. Alternatively, you can run the app from the command line using:

# From the root of your project
$ npx react-native run-ios

In our sample application, you should see the link to the "High Scores" and then when you click on that you will see the rendering of your React Native component.

Here is the native application home screen:

Home Screen

Here is the React Native high score screen:

High Scores

If you are getting module resolution issues when running your application please see this GitHub issue for information and possible resolution. This comment seemed to be the latest possible resolution.

See the Code

You can examine the code that added the React Native screen to our sample app on GitHub.

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/_integration-with-exisiting-apps-swift/index.html b/docs/_integration-with-exisiting-apps-swift/index.html index 3add96a6d95..e7a407dd7b9 100644 --- a/docs/_integration-with-exisiting-apps-swift/index.html +++ b/docs/_integration-with-exisiting-apps-swift/index.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
let rootView = RCTRootView(
bundleURL: jsCodeLocation,
moduleName: "RNHighScores",
initialProperties: mockData as [NSObject : AnyObject],
launchOptions: nil
)
let vc = UIViewController()
vc.view = rootView
self.present(vc, animated: true, completion: nil)
}

Note that RCTRootView bundleURL starts up a new JSC VM. To save resources and simplify the communication between RN views in different parts of your native app, you can have multiple views powered by React Native that are associated with a single JS runtime. To do that, instead of using RCTRootView bundleURL, use RCTBridge initWithBundleURL to create a bridge and then use RCTRootView initWithBridge.

When moving your app to production, the NSURL can point to a pre-bundled file on disk via something like let mainBundle = NSBundle(URLForResource: "main" withExtension:"jsbundle"). You can use the react-native-xcode.sh script in node_modules/react-native/scripts/ to generate that pre-bundled file.

3. Wire Up

Wire up the new link in the main menu to the newly added event handler method.

Event Path

One of the easier ways to do this is to open the view in the storyboard and right click on the new link. Select something such as the Touch Up Inside event, drag that to the storyboard and then select the created method from the list provided.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Add App Transport Security exception

Apple has blocked implicit cleartext HTTP resource loading. So we need to add the following our project's Info.plist (or equivalent) file.

<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>localhost</key>
<dict>
<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
</dict>

App Transport Security is good for your users. Make sure to re-enable it prior to releasing your app for production.

2. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ npm start
3. Run the app

If you are using Xcode or your favorite editor, build and run your native iOS application as normal. Alternatively, you can run the app from the command line using:

# From the root of your project
$ npx react-native run-ios

In our sample application, you should see the link to the "High Scores" and then when you click on that you will see the rendering of your React Native component.

Here is the native application home screen:

Home Screen

Here is the React Native high score screen:

High Scores

If you are getting module resolution issues when running your application please see this GitHub issue for information and possible resolution. This comment seemed to be the latest possible resolution.

See the Code

You can examine the code that added the React Native screen to our sample app on GitHub.

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/accessibility.html b/docs/accessibility.html index f14d54be631..7974ff176e5 100644 --- a/docs/accessibility.html +++ b/docs/accessibility.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
# enable
adb shell settings put secure enabled_accessibility_services com.google.android.marvin.talkback/com.google.android.marvin.talkback.TalkBackService

Testing VoiceOver Support
iOS

To enable VoiceOver, go to the Settings app on your iOS device (it's not available for simulator). 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.

Additional Resources

Edit this page
Last updated on
- + diff --git a/docs/accessibility/index.html b/docs/accessibility/index.html index f14d54be631..7974ff176e5 100644 --- a/docs/accessibility/index.html +++ b/docs/accessibility/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
# enable
adb shell settings put secure enabled_accessibility_services com.google.android.marvin.talkback/com.google.android.marvin.talkback.TalkBackService

Testing VoiceOver Support
iOS

To enable VoiceOver, go to the Settings app on your iOS device (it's not available for simulator). 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.

Additional Resources

Edit this page
Last updated on
- + diff --git a/docs/accessibilityinfo.html b/docs/accessibilityinfo.html index 60859c01866..abd219faf40 100644 --- a/docs/accessibilityinfo.html +++ b/docs/accessibilityinfo.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

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.

Example

Reference

Methods

isBoldTextEnabled()

static isBoldTextEnabled()

iOS-Only. Query whether a bold text is currently enabled. Returns a promise which resolves to a boolean. The result is true when bold text is enabled and false otherwise.

isGrayscaleEnabled()

static isGrayscaleEnabled()

iOS-Only. Query whether grayscale is currently enabled. Returns a promise which resolves to a boolean. The result is true when grayscale is enabled and false otherwise.

isInvertColorsEnabled()

static isInvertColorsEnabled()

iOS-Only. Query whether invert colors is currently enabled. Returns a promise which resolves to a boolean. The result is true when invert colors is enabled and false otherwise.

isReduceMotionEnabled()

static isReduceMotionEnabled()

Query whether reduce motion is currently enabled. Returns a promise which resolves to a boolean. The result is true when reduce motion is enabled and false otherwise.

isReduceTransparencyEnabled()

static isReduceTransparencyEnabled()

iOS-Only. Query whether reduce transparency is currently enabled. Returns a promise which resolves to a boolean. The result is true when a reduce transparency is enabled and false otherwise.

isScreenReaderEnabled()

static isScreenReaderEnabled()

Query whether a screen reader is currently enabled. Returns a promise which resolves to a boolean. The result is true when a screen reader is enabled and false otherwise.

addEventListener()

static addEventListener(eventName, handler)

Add an event handler. Supported events:

  • boldTextChanged: iOS-only event. Fires when the state of the bold text toggle changes. The argument to the event handler is a boolean. The boolean is true when bold text is enabled and false otherwise.
  • grayscaleChanged: iOS-only event. Fires when the state of the gray scale toggle changes. The argument to the event handler is a boolean. The boolean is true when a gray scale is enabled and false otherwise.
  • invertColorsChanged: iOS-only event. Fires when the state of the invert colors toggle changes. The argument to the event handler is a boolean. The boolean is true when invert colors is enabled and false otherwise.
  • reduceMotionChanged: Fires when the state of the reduce motion toggle changes. The argument to the event handler is a boolean. The boolean is true when a reduce motion is enabled (or when "Transition Animation Scale" in "Developer options" is "Animation off") and false otherwise.
  • screenReaderChanged: Fires when the state of the screen reader changes. The argument to the event handler is a boolean. The boolean is true when a screen reader is enabled and false otherwise.
  • reduceTransparencyChanged: iOS-only event. Fires when the state of the reduce transparency toggle changes. The argument to the event handler is a boolean. The boolean is true when reduce transparency is enabled and false otherwise.
  • announcementFinished: iOS-only event. Fires when the screen reader has finished making an announcement. The argument to the event handler is a dictionary with these keys:
    • announcement: The string announced by the screen reader.
    • success: A boolean indicating whether the announcement was successfully made.

setAccessibilityFocus()

static setAccessibilityFocus(reactTag)

Set accessibility focus to a React component. On Android, this calls UIManager.sendAccessibilityEvent(reactTag, UIManager.AccessibilityEventTypes.typeViewFocused);.

Note: Make sure that any View you want to receive the accessibility focus has accessible={true}.

announceForAccessibility()

static announceForAccessibility(announcement)

Post a string to be announced by the screen reader.

removeEventListener()

static removeEventListener(eventName, handler)

Remove an event handler.

Edit this page
Last updated on
- + diff --git a/docs/accessibilityinfo/index.html b/docs/accessibilityinfo/index.html index 60859c01866..abd219faf40 100644 --- a/docs/accessibilityinfo/index.html +++ b/docs/accessibilityinfo/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

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.

Example

Reference

Methods

isBoldTextEnabled()

static isBoldTextEnabled()

iOS-Only. Query whether a bold text is currently enabled. Returns a promise which resolves to a boolean. The result is true when bold text is enabled and false otherwise.

isGrayscaleEnabled()

static isGrayscaleEnabled()

iOS-Only. Query whether grayscale is currently enabled. Returns a promise which resolves to a boolean. The result is true when grayscale is enabled and false otherwise.

isInvertColorsEnabled()

static isInvertColorsEnabled()

iOS-Only. Query whether invert colors is currently enabled. Returns a promise which resolves to a boolean. The result is true when invert colors is enabled and false otherwise.

isReduceMotionEnabled()

static isReduceMotionEnabled()

Query whether reduce motion is currently enabled. Returns a promise which resolves to a boolean. The result is true when reduce motion is enabled and false otherwise.

isReduceTransparencyEnabled()

static isReduceTransparencyEnabled()

iOS-Only. Query whether reduce transparency is currently enabled. Returns a promise which resolves to a boolean. The result is true when a reduce transparency is enabled and false otherwise.

isScreenReaderEnabled()

static isScreenReaderEnabled()

Query whether a screen reader is currently enabled. Returns a promise which resolves to a boolean. The result is true when a screen reader is enabled and false otherwise.

addEventListener()

static addEventListener(eventName, handler)

Add an event handler. Supported events:

  • boldTextChanged: iOS-only event. Fires when the state of the bold text toggle changes. The argument to the event handler is a boolean. The boolean is true when bold text is enabled and false otherwise.
  • grayscaleChanged: iOS-only event. Fires when the state of the gray scale toggle changes. The argument to the event handler is a boolean. The boolean is true when a gray scale is enabled and false otherwise.
  • invertColorsChanged: iOS-only event. Fires when the state of the invert colors toggle changes. The argument to the event handler is a boolean. The boolean is true when invert colors is enabled and false otherwise.
  • reduceMotionChanged: Fires when the state of the reduce motion toggle changes. The argument to the event handler is a boolean. The boolean is true when a reduce motion is enabled (or when "Transition Animation Scale" in "Developer options" is "Animation off") and false otherwise.
  • screenReaderChanged: Fires when the state of the screen reader changes. The argument to the event handler is a boolean. The boolean is true when a screen reader is enabled and false otherwise.
  • reduceTransparencyChanged: iOS-only event. Fires when the state of the reduce transparency toggle changes. The argument to the event handler is a boolean. The boolean is true when reduce transparency is enabled and false otherwise.
  • announcementFinished: iOS-only event. Fires when the screen reader has finished making an announcement. The argument to the event handler is a dictionary with these keys:
    • announcement: The string announced by the screen reader.
    • success: A boolean indicating whether the announcement was successfully made.

setAccessibilityFocus()

static setAccessibilityFocus(reactTag)

Set accessibility focus to a React component. On Android, this calls UIManager.sendAccessibilityEvent(reactTag, UIManager.AccessibilityEventTypes.typeViewFocused);.

Note: Make sure that any View you want to receive the accessibility focus has accessible={true}.

announceForAccessibility()

static announceForAccessibility(announcement)

Post a string to be announced by the screen reader.

removeEventListener()

static removeEventListener(eventName, handler)

Remove an event handler.

Edit this page
Last updated on
- + diff --git a/docs/actionsheetios.html b/docs/actionsheetios.html index d7a9b4c0dff..923b9598b32 100644 --- a/docs/actionsheetios.html +++ b/docs/actionsheetios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

ActionSheetIOS

Displays native to iOS Action Sheet component.

Example

Reference

Methods

showActionSheetWithOptions()

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 in options
  • destructiveButtonIndex (int) - index of destructive button in options
  • title (string) - a title to show above the action sheet
  • message (string) - a message to show below the title
  • anchor (number) - the node to which the action sheet should be anchored (used for iPad)
  • tintColor (string) - the color used for non-destructive button titles
  • userInterfaceStyle (string) - the interface style used for the action sheet, can be set to light or dark, otherwise the default system style will be used

The 'callback' function takes one parameter, the zero-based index of the selected item.

Minimal example:

ActionSheetIOS.showActionSheetWithOptions(
{
options: ['Cancel', 'Remove'],
destructiveButtonIndex: 1,
cancelButtonIndex: 0
},
(buttonIndex) => {
if (buttonIndex === 1) {
/* destructive action */
}
}
);

showShareActionSheetWithOptions()

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 share
  • message (string) - a message to share
  • subject (string) - a subject for the message
  • excludedActivityTypes (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.

The 'failureCallback' function takes one parameter, an error object. The only property defined on this object is an optional stack property of type string.

The 'successCallback' function takes two parameters:

  • a boolean value signifying success or failure
  • a string that, in the case of success, indicates the method of sharing
Edit this page
Last updated on
- + diff --git a/docs/actionsheetios/index.html b/docs/actionsheetios/index.html index d7a9b4c0dff..923b9598b32 100644 --- a/docs/actionsheetios/index.html +++ b/docs/actionsheetios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

ActionSheetIOS

Displays native to iOS Action Sheet component.

Example

Reference

Methods

showActionSheetWithOptions()

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 in options
  • destructiveButtonIndex (int) - index of destructive button in options
  • title (string) - a title to show above the action sheet
  • message (string) - a message to show below the title
  • anchor (number) - the node to which the action sheet should be anchored (used for iPad)
  • tintColor (string) - the color used for non-destructive button titles
  • userInterfaceStyle (string) - the interface style used for the action sheet, can be set to light or dark, otherwise the default system style will be used

The 'callback' function takes one parameter, the zero-based index of the selected item.

Minimal example:

ActionSheetIOS.showActionSheetWithOptions(
{
options: ['Cancel', 'Remove'],
destructiveButtonIndex: 1,
cancelButtonIndex: 0
},
(buttonIndex) => {
if (buttonIndex === 1) {
/* destructive action */
}
}
);

showShareActionSheetWithOptions()

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 share
  • message (string) - a message to share
  • subject (string) - a subject for the message
  • excludedActivityTypes (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.

The 'failureCallback' function takes one parameter, an error object. The only property defined on this object is an optional stack property of type string.

The 'successCallback' function takes two parameters:

  • a boolean value signifying success or failure
  • a string that, in the case of success, indicates the method of sharing
Edit this page
Last updated on
- + diff --git a/docs/activityindicator.html b/docs/activityindicator.html index 45776e08311..dea02bba736 100644 --- a/docs/activityindicator.html +++ b/docs/activityindicator.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

ActivityIndicator

Displays a circular loading indicator.

Example

Reference

Props

Inherits View Props.

animating

Whether to show the indicator (true) or hide it (false).

TypeRequiredDefault
boolNotrue

color

The foreground color of the spinner.

TypeRequiredDefault
colorNonull (system accent default color)
Android
'#999999'
iOS

hidesWhenStopped
iOS

Whether the indicator should hide when not animating.

TypeRequiredDefault
boolNotrue

size

Size of the indicator.

TypeRequiredDefault
enum('small', 'large')
number
Android
No'small'
Edit this page
Last updated on
- + diff --git a/docs/activityindicator/index.html b/docs/activityindicator/index.html index 45776e08311..dea02bba736 100644 --- a/docs/activityindicator/index.html +++ b/docs/activityindicator/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

ActivityIndicator

Displays a circular loading indicator.

Example

Reference

Props

Inherits View Props.

animating

Whether to show the indicator (true) or hide it (false).

TypeRequiredDefault
boolNotrue

color

The foreground color of the spinner.

TypeRequiredDefault
colorNonull (system accent default color)
Android
'#999999'
iOS

hidesWhenStopped
iOS

Whether the indicator should hide when not animating.

TypeRequiredDefault
boolNotrue

size

Size of the indicator.

TypeRequiredDefault
enum('small', 'large')
number
Android
No'small'
Edit this page
Last updated on
- + diff --git a/docs/alert.html b/docs/alert.html index 80c26725539..6c68627600b 100644 --- a/docs/alert.html +++ b/docs/alert.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

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 Android and iOS and can show static alerts. To show an alert that prompts the user to enter some information, see AlertIOS; entering text in an alert is common on iOS only.

Example

iOS

On iOS you can specify any number of buttons. Each button can optionally specify a style, which is one of 'default', 'cancel', or 'destructive'.

Android

On Android at most three buttons can be specified. Android has a concept of a neutral, negative and a positive button:

  • If you specify one button, it will be the 'positive' one (such as 'OK')
  • Two buttons mean 'negative', 'positive' (such as 'Cancel', 'OK')
  • Three buttons mean 'neutral', 'negative', 'positive' (such as 'Later', 'Cancel', 'OK')

By default alerts on Android can be dismissed by tapping outside of the alert box. This event can be handled by providing an optional options parameter, with an onDismiss callback property { onDismiss: () => {} }.

Alternatively, the dismissing behavior can be disabled altogether by providing an optional options parameter with the cancelable property set to false i.e. { cancelable: false }.

Example usage:

// Works on both Android and iOS
Alert.alert(
'Alert Title',
'My Alert Msg',
[
{
text: 'Ask me later',
onPress: () => console.log('Ask me later pressed')
},
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{ text: 'OK', onPress: () => console.log('OK Pressed') }
],
{ cancelable: false }
);

Reference

Methods

alert()

static alert(title, message?, buttons?, options?)
Edit this page
Last updated on
- + diff --git a/docs/alert/index.html b/docs/alert/index.html index 80c26725539..6c68627600b 100644 --- a/docs/alert/index.html +++ b/docs/alert/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

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 Android and iOS and can show static alerts. To show an alert that prompts the user to enter some information, see AlertIOS; entering text in an alert is common on iOS only.

Example

iOS

On iOS you can specify any number of buttons. Each button can optionally specify a style, which is one of 'default', 'cancel', or 'destructive'.

Android

On Android at most three buttons can be specified. Android has a concept of a neutral, negative and a positive button:

  • If you specify one button, it will be the 'positive' one (such as 'OK')
  • Two buttons mean 'negative', 'positive' (such as 'Cancel', 'OK')
  • Three buttons mean 'neutral', 'negative', 'positive' (such as 'Later', 'Cancel', 'OK')

By default alerts on Android can be dismissed by tapping outside of the alert box. This event can be handled by providing an optional options parameter, with an onDismiss callback property { onDismiss: () => {} }.

Alternatively, the dismissing behavior can be disabled altogether by providing an optional options parameter with the cancelable property set to false i.e. { cancelable: false }.

Example usage:

// Works on both Android and iOS
Alert.alert(
'Alert Title',
'My Alert Msg',
[
{
text: 'Ask me later',
onPress: () => console.log('Ask me later pressed')
},
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{ text: 'OK', onPress: () => console.log('OK Pressed') }
],
{ cancelable: false }
);

Reference

Methods

alert()

static alert(title, message?, buttons?, options?)
Edit this page
Last updated on
- + diff --git a/docs/alertios.html b/docs/alertios.html index f16bf6907ba..10888fac1fc 100644 --- a/docs/alertios.html +++ b/docs/alertios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 AlertIOS

Deprecated. Use Alert instead.

AlertIOS provides functionality to create an iOS alert dialog with a message or create a prompt for user input.

Creating an iOS alert:

AlertIOS.alert(
'Sync Complete',
'All your data are belong to us.'
);

Creating an iOS prompt:

AlertIOS.prompt('Enter a value', null, (text) =>
console.log('You entered ' + text)
);

We recommend using the Alert.alert method for cross-platform support if you don't need to create iOS-only prompts.

Reference

Methods

alert()

static alert(title: string, [message]: string, [callbackOrButtons]: ?(() => void), ButtonsArray, [type]: AlertType): [object Object]

Create and display a popup alert.

Parameters:

NameTypeRequiredDescription
titlestringYesThe dialog's title. Passing null or '' will hide the title.
messagestringNoAn optional message that appears below the dialog's title.
callbackOrButtons?(() => void),ButtonsArrayNoThis optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called when the user taps 'OK'. If passed an array of button configurations, each button should include a text key, as well as optional onPress and style keys. style should be one of 'default', 'cancel' or 'destructive'.
typeAlertTypeNoDeprecated, do not use.

Example with custom buttons:

AlertIOS.alert(
'Update available',
'Keep your app up to date to enjoy the latest features',
[
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{
text: 'Install',
onPress: () => console.log('Install Pressed')
}
]
);

prompt()

static prompt(title: string, [message]: string, [callbackOrButtons]: ?((text: string) => void), ButtonsArray, [type]: AlertType, [defaultValue]: string, [keyboardType]: string): [object Object]

Create and display a prompt to enter some text.

Parameters:

NameTypeRequiredDescription
titlestringYesThe dialog's title.
messagestringNoAn optional message that appears above the text input.
callbackOrButtons?((text: string) => void),ButtonsArrayNoThis optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called with the prompt's value when the user taps 'OK'. If passed an array of button configurations, each button should include a text key, as well as optional onPress and style keys (see example). style should be one of 'default', 'cancel' or 'destructive'.
typeAlertTypeNoThis configures the text input. One of 'plain-text', 'secure-text' or 'login-password'.
defaultValuestringNoThe default text in text input.
keyboardTypestringNoThe keyboard type of first text field(if exists). One of 'default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter' or 'web-search'.

Example with custom buttons:

AlertIOS.prompt(
'Enter password',
'Enter your password to claim your $1.5B in lottery winnings',
[
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{
text: 'OK',
onPress: (password) =>
console.log('OK Pressed, password: ' + password)
}
],
'secure-text'
);

,

Example with the default button and a custom callback:

AlertIOS.prompt(
'Update username',
null,
(text) => console.log('Your username is ' + text),
null,
'default'
);

Type Definitions

AlertType

An Alert button type

Type
\$Enum

Constants:

ValueDescription
defaultDefault alert with no inputs
plain-textPlain text input alert
secure-textSecure text input alert
login-passwordLogin and password alert

AlertButtonStyle

An Alert button style

Type
\$Enum

Constants:

ValueDescription
defaultDefault button style
cancelCancel button style
destructiveDestructive button style

ButtonsArray

Array or buttons

Type
Array

Properties:

NameTypeDescription
[text]stringButton label
[onPress]functionCallback function when button pressed
[style]AlertButtonStyleButton style

Constants:

ValueDescription
textButton label
onPressCallback function when button pressed
styleButton style
Edit this page
Last updated on
- + diff --git a/docs/alertios/index.html b/docs/alertios/index.html index f16bf6907ba..10888fac1fc 100644 --- a/docs/alertios/index.html +++ b/docs/alertios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 AlertIOS

Deprecated. Use Alert instead.

AlertIOS provides functionality to create an iOS alert dialog with a message or create a prompt for user input.

Creating an iOS alert:

AlertIOS.alert(
'Sync Complete',
'All your data are belong to us.'
);

Creating an iOS prompt:

AlertIOS.prompt('Enter a value', null, (text) =>
console.log('You entered ' + text)
);

We recommend using the Alert.alert method for cross-platform support if you don't need to create iOS-only prompts.

Reference

Methods

alert()

static alert(title: string, [message]: string, [callbackOrButtons]: ?(() => void), ButtonsArray, [type]: AlertType): [object Object]

Create and display a popup alert.

Parameters:

NameTypeRequiredDescription
titlestringYesThe dialog's title. Passing null or '' will hide the title.
messagestringNoAn optional message that appears below the dialog's title.
callbackOrButtons?(() => void),ButtonsArrayNoThis optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called when the user taps 'OK'. If passed an array of button configurations, each button should include a text key, as well as optional onPress and style keys. style should be one of 'default', 'cancel' or 'destructive'.
typeAlertTypeNoDeprecated, do not use.

Example with custom buttons:

AlertIOS.alert(
'Update available',
'Keep your app up to date to enjoy the latest features',
[
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{
text: 'Install',
onPress: () => console.log('Install Pressed')
}
]
);

prompt()

static prompt(title: string, [message]: string, [callbackOrButtons]: ?((text: string) => void), ButtonsArray, [type]: AlertType, [defaultValue]: string, [keyboardType]: string): [object Object]

Create and display a prompt to enter some text.

Parameters:

NameTypeRequiredDescription
titlestringYesThe dialog's title.
messagestringNoAn optional message that appears above the text input.
callbackOrButtons?((text: string) => void),ButtonsArrayNoThis optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called with the prompt's value when the user taps 'OK'. If passed an array of button configurations, each button should include a text key, as well as optional onPress and style keys (see example). style should be one of 'default', 'cancel' or 'destructive'.
typeAlertTypeNoThis configures the text input. One of 'plain-text', 'secure-text' or 'login-password'.
defaultValuestringNoThe default text in text input.
keyboardTypestringNoThe keyboard type of first text field(if exists). One of 'default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter' or 'web-search'.

Example with custom buttons:

AlertIOS.prompt(
'Enter password',
'Enter your password to claim your $1.5B in lottery winnings',
[
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{
text: 'OK',
onPress: (password) =>
console.log('OK Pressed, password: ' + password)
}
],
'secure-text'
);

,

Example with the default button and a custom callback:

AlertIOS.prompt(
'Update username',
null,
(text) => console.log('Your username is ' + text),
null,
'default'
);

Type Definitions

AlertType

An Alert button type

Type
\$Enum

Constants:

ValueDescription
defaultDefault alert with no inputs
plain-textPlain text input alert
secure-textSecure text input alert
login-passwordLogin and password alert

AlertButtonStyle

An Alert button style

Type
\$Enum

Constants:

ValueDescription
defaultDefault button style
cancelCancel button style
destructiveDestructive button style

ButtonsArray

Array or buttons

Type
Array

Properties:

NameTypeDescription
[text]stringButton label
[onPress]functionCallback function when button pressed
[style]AlertButtonStyleButton style

Constants:

ValueDescription
textButton label
onPressCallback function when button pressed
styleButton style
Edit this page
Last updated on
- + diff --git a/docs/animated.html b/docs/animated.html index e7c606f8e1a..0f427e059a8 100644 --- a/docs/animated.html +++ b/docs/animated.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Animated

The Animated library is designed to make animations fluid, powerful, and painless to build and maintain. Animated focuses on declarative relationships between inputs and outputs, configurable transforms in between, and start/stop methods to control time-based animation execution.

The core workflow for creating an animation is to create an Animated.Value, hook it up to one or more style attributes of an animated component, and then drive updates via animations using Animated.timing().

Don't modify the animated value directly. You can use the useRef Hook to return a mutable ref object. This ref object's current property is initialized as the given argument and persists throughout the component lifecycle.

Example

The following example contains a View which will fade in and fade out based on the animated value fadeAnim

Refer to the Animations guide to see additional examples of Animated in action.

Overview

There are two value types you can use with Animated:

Animated.Value can bind to style properties or other props, and can be interpolated as well. A single Animated.Value can drive any number of properties.

Configuring animations

Animated provides three types of animation types. Each animation type provides a particular animation curve that controls how your values animate from their initial value to the final value:

In most cases, you will be using timing(). By default, it uses a symmetric easeInOut curve that conveys the gradual acceleration of an object to full speed and concludes by gradually decelerating to a stop.

Working with animations

Animations are started by calling start() on your animation. start() takes a completion callback that will be called when the animation is done. If the animation finished running normally, the completion callback will be invoked with {finished: true}. If the animation is done because stop() was called on it before it could finish (e.g. because it was interrupted by a gesture or another animation), then it will receive {finished: false}.

Animated.timing({}).start(({ finished }) => {
/* completion callback */
});

Using the native driver

By using the native driver, we send everything about the animation to native before starting the animation, allowing native code to perform the animation on the UI thread without having to go through the bridge on every frame. Once the animation has started, the JS thread can be blocked without affecting the animation.

You can use the native driver by specifying useNativeDriver: true in your animation configuration. See the Animations guide to learn more.

Animatable components

Only animatable components can be animated. These unique components do the magic of binding the animated values to the properties, and do targeted native updates to avoid the cost of the React render and reconciliation process on every frame. They also handle cleanup on unmount so they are safe by default.

Animated exports the following animatable components using the above wrapper:

  • Animated.Image
  • Animated.ScrollView
  • Animated.Text
  • Animated.View
  • Animated.FlatList
  • Animated.SectionList

Composing animations

Animations can also be combined in complex ways using composition functions:

Animations can also be chained together by setting the toValue of one animation to be another Animated.Value. See Tracking dynamic values in the Animations guide.

By default, if one animation is stopped or interrupted, then all other animations in the group are also stopped.

Combining animated values

You can combine two animated values via addition, subtraction, multiplication, division, or modulo to make a new animated value:

Interpolation

The interpolate() function allows input ranges to map to different output ranges. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value. It uses linear interpolation by default but also supports easing functions.

Read more about interpolation in the Animation guide.

Handling gestures and other events

Gestures, like panning or scrolling, and other events can map directly to animated values using Animated.event(). This is done with a structured map syntax so that values can be extracted from complex event objects. The first level is an array to allow mapping across multiple args, and that array contains nested objects.

For example, when working with horizontal scrolling gestures, you would do the following in order to map event.nativeEvent.contentOffset.x to scrollX (an Animated.Value):

onScroll={Animated.event(
// scrollX = e.nativeEvent.contentOffset.x
[{ nativeEvent: {
contentOffset: {
x: scrollX
}
}
}]
)}

Reference

Methods

When the given value is a ValueXY instead of a Value, each config option may be a vector of the form {x: ..., y: ...} instead of a scalar.

decay()

static decay(value, config)

Animates a value from an initial velocity to zero based on a decay coefficient.

Config is an object that may have the following options:

  • velocity: Initial velocity. Required.
  • deceleration: Rate of decay. Default 0.997.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

timing()

static timing(value, config)

Animates a value along a timed easing curve. The Easing module has tons of predefined curves, or you can use your own function.

Config is an object that may have the following options:

  • duration: Length of animation (milliseconds). Default 500.
  • easing: Easing function to define curve. Default is Easing.inOut(Easing.ease).
  • delay: Start the animation after delay (milliseconds). Default 0.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

spring()

static spring(value, config)

Animates a value according to an analytical spring model based on damped harmonic oscillation. Tracks velocity state to create fluid motions as the toValue updates, and can be chained together.

Config is an object that may have the following options.

Note that you can only define one of bounciness/speed, tension/friction, or stiffness/damping/mass, but not more than one:

The friction/tension or bounciness/speed options match the spring model in Facebook Pop, Rebound, and Origami.

  • friction: Controls "bounciness"/overshoot. Default 7.
  • tension: Controls speed. Default 40.
  • speed: Controls speed of the animation. Default 12.
  • bounciness: Controls bounciness. Default 8.

Specifying stiffness/damping/mass as parameters makes Animated.spring use an analytical spring model based on the motion equations of a damped harmonic oscillator. This behavior is slightly more precise and faithful to the physics behind spring dynamics, and closely mimics the implementation in iOS's CASpringAnimation.

  • stiffness: The spring stiffness coefficient. Default 100.
  • damping: Defines how the spring’s motion should be damped due to the forces of friction. Default 10.
  • mass: The mass of the object attached to the end of the spring. Default 1.

Other configuration options are as follows:

  • velocity: The initial velocity of the object attached to the spring. Default 0 (object is at rest).
  • overshootClamping: Boolean indicating whether the spring should be clamped and not bounce. Default false.
  • restDisplacementThreshold: The threshold of displacement from rest below which the spring should be considered at rest. Default 0.001.
  • restSpeedThreshold: The speed at which the spring should be considered at rest in pixels per second. Default 0.001.
  • delay: Start the animation after delay (milliseconds). Default 0.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

add()

static add(a, b)

Creates a new Animated value composed from two Animated values added together.

subtract()

static subtract(a, b)

Creates a new Animated value composed by subtracting the second Animated value from the first Animated value.

divide()

static divide(a, b)

Creates a new Animated value composed by dividing the first Animated value by the second Animated value.

multiply()

static multiply(a, b)

Creates a new Animated value composed from two Animated values multiplied together.

modulo()

static modulo(a, modulus)

Creates a new Animated value that is the (non-negative) modulo of the provided Animated value

diffClamp()

static diffClamp(a, min, max)

Create a new Animated value that is limited between 2 values. It uses the difference between the last value so even if the value is far from the bounds it will start changing when the value starts getting closer again. (value = clamp(value + diff, min, max)).

This is useful with scroll events, for example, to show the navbar when scrolling up and to hide it when scrolling down.

delay()

static delay(time)

Starts an animation after the given delay.

sequence()

static sequence(animations)

Starts an array of animations in order, waiting for each to complete before starting the next. If the current running animation is stopped, no following animations will be started.

parallel()

static parallel(animations, config?)

Starts an array of animations all at the same time. By default, if one of the animations is stopped, they will all be stopped. You can override this with the stopTogether flag.

stagger()

static stagger(time, animations)

Array of animations may run in parallel (overlap), but are started in sequence with successive delays. Nice for doing trailing effects.

loop()

static loop(animation, config?)

Loops a given animation continuously, so that each time it reaches the end, it resets and begins again from the start. Will loop without blocking the JS thread if the child animation is set to useNativeDriver: true. In addition, loops can prevent VirtualizedList-based components from rendering more rows while the animation is running. You can pass isInteraction: false in the child animation config to fix this.

Config is an object that may have the following options:

  • iterations: Number of times the animation should loop. Default -1 (infinite).

event()

static event(argMapping, config?)

Takes an array of mappings and extracts values from each arg accordingly, then calls setValue on the mapped outputs. e.g.

onScroll={Animated.event(
[{nativeEvent: {contentOffset: {x: this._scrollX}}}],
{listener: (event) => console.log(event)}, // Optional async listener
)}
...
onPanResponderMove: Animated.event([
null, // raw event arg ignored
{dx: this._panX}], // gestureState arg
{listener: (event, gestureState) => console.log(event, gestureState)}, // Optional async listener
),

Config is an object that may have the following options:

  • listener: Optional async listener.
  • useNativeDriver: Uses the native driver when true. Default false.

forkEvent()

static forkEvent(event, listener)

Advanced imperative API for snooping on animated events that are passed in through props. It permits to add a new javascript listener to an existing AnimatedEvent. If animatedEvent is a javascript listener, it will merge the 2 listeners into a single one, and if animatedEvent is null/undefined, it will assign the javascript listener directly. Use values directly where possible.

unforkEvent()

static unforkEvent(event, listener)

start()

static start([callback]: ?(result?: {finished: boolean}) => void)

Animations are started by calling start() on your animation. start() takes a completion callback that will be called when the animation is done or when the animation is done because stop() was called on it before it could finish.

Parameters:

NameTypeRequiredDescription
callback?(result?: {finished: boolean})NoFunction that will be called after the animation finished running normally or when the animation is done because stop() was called on it before it could finish

Start example with callback:

Animated.timing({}).start(({ finished }) => {
/* completion callback */
});

stop()

static stop()

Stops any running animation.

reset()

static reset()

Stops any running animation and resets the value to its original.

Properties

Value

Standard value class for driving animations. Typically initialized with new Animated.Value(0);

You can read more about Animated.Value API on the separate page.

ValueXY

2D value class for driving 2D animations, such as pan gestures.

You can read more about Animated.ValueXY API on the separate page.

Interpolation

Exported to use the Interpolation type in flow.

Node

Exported for ease of type checking. All animated values derive from this class.

createAnimatedComponent

Make any React component Animatable. Used to create Animated.View, etc.

attachNativeEvent

Imperative API to attach an animated value to an event on a view. Prefer using Animated.event with useNativeDrive: true if possible.

Edit this page
Last updated on
- + diff --git a/docs/animated/index.html b/docs/animated/index.html index e7c606f8e1a..0f427e059a8 100644 --- a/docs/animated/index.html +++ b/docs/animated/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Animated

The Animated library is designed to make animations fluid, powerful, and painless to build and maintain. Animated focuses on declarative relationships between inputs and outputs, configurable transforms in between, and start/stop methods to control time-based animation execution.

The core workflow for creating an animation is to create an Animated.Value, hook it up to one or more style attributes of an animated component, and then drive updates via animations using Animated.timing().

Don't modify the animated value directly. You can use the useRef Hook to return a mutable ref object. This ref object's current property is initialized as the given argument and persists throughout the component lifecycle.

Example

The following example contains a View which will fade in and fade out based on the animated value fadeAnim

Refer to the Animations guide to see additional examples of Animated in action.

Overview

There are two value types you can use with Animated:

Animated.Value can bind to style properties or other props, and can be interpolated as well. A single Animated.Value can drive any number of properties.

Configuring animations

Animated provides three types of animation types. Each animation type provides a particular animation curve that controls how your values animate from their initial value to the final value:

In most cases, you will be using timing(). By default, it uses a symmetric easeInOut curve that conveys the gradual acceleration of an object to full speed and concludes by gradually decelerating to a stop.

Working with animations

Animations are started by calling start() on your animation. start() takes a completion callback that will be called when the animation is done. If the animation finished running normally, the completion callback will be invoked with {finished: true}. If the animation is done because stop() was called on it before it could finish (e.g. because it was interrupted by a gesture or another animation), then it will receive {finished: false}.

Animated.timing({}).start(({ finished }) => {
/* completion callback */
});

Using the native driver

By using the native driver, we send everything about the animation to native before starting the animation, allowing native code to perform the animation on the UI thread without having to go through the bridge on every frame. Once the animation has started, the JS thread can be blocked without affecting the animation.

You can use the native driver by specifying useNativeDriver: true in your animation configuration. See the Animations guide to learn more.

Animatable components

Only animatable components can be animated. These unique components do the magic of binding the animated values to the properties, and do targeted native updates to avoid the cost of the React render and reconciliation process on every frame. They also handle cleanup on unmount so they are safe by default.

Animated exports the following animatable components using the above wrapper:

  • Animated.Image
  • Animated.ScrollView
  • Animated.Text
  • Animated.View
  • Animated.FlatList
  • Animated.SectionList

Composing animations

Animations can also be combined in complex ways using composition functions:

Animations can also be chained together by setting the toValue of one animation to be another Animated.Value. See Tracking dynamic values in the Animations guide.

By default, if one animation is stopped or interrupted, then all other animations in the group are also stopped.

Combining animated values

You can combine two animated values via addition, subtraction, multiplication, division, or modulo to make a new animated value:

Interpolation

The interpolate() function allows input ranges to map to different output ranges. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value. It uses linear interpolation by default but also supports easing functions.

Read more about interpolation in the Animation guide.

Handling gestures and other events

Gestures, like panning or scrolling, and other events can map directly to animated values using Animated.event(). This is done with a structured map syntax so that values can be extracted from complex event objects. The first level is an array to allow mapping across multiple args, and that array contains nested objects.

For example, when working with horizontal scrolling gestures, you would do the following in order to map event.nativeEvent.contentOffset.x to scrollX (an Animated.Value):

onScroll={Animated.event(
// scrollX = e.nativeEvent.contentOffset.x
[{ nativeEvent: {
contentOffset: {
x: scrollX
}
}
}]
)}

Reference

Methods

When the given value is a ValueXY instead of a Value, each config option may be a vector of the form {x: ..., y: ...} instead of a scalar.

decay()

static decay(value, config)

Animates a value from an initial velocity to zero based on a decay coefficient.

Config is an object that may have the following options:

  • velocity: Initial velocity. Required.
  • deceleration: Rate of decay. Default 0.997.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

timing()

static timing(value, config)

Animates a value along a timed easing curve. The Easing module has tons of predefined curves, or you can use your own function.

Config is an object that may have the following options:

  • duration: Length of animation (milliseconds). Default 500.
  • easing: Easing function to define curve. Default is Easing.inOut(Easing.ease).
  • delay: Start the animation after delay (milliseconds). Default 0.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

spring()

static spring(value, config)

Animates a value according to an analytical spring model based on damped harmonic oscillation. Tracks velocity state to create fluid motions as the toValue updates, and can be chained together.

Config is an object that may have the following options.

Note that you can only define one of bounciness/speed, tension/friction, or stiffness/damping/mass, but not more than one:

The friction/tension or bounciness/speed options match the spring model in Facebook Pop, Rebound, and Origami.

  • friction: Controls "bounciness"/overshoot. Default 7.
  • tension: Controls speed. Default 40.
  • speed: Controls speed of the animation. Default 12.
  • bounciness: Controls bounciness. Default 8.

Specifying stiffness/damping/mass as parameters makes Animated.spring use an analytical spring model based on the motion equations of a damped harmonic oscillator. This behavior is slightly more precise and faithful to the physics behind spring dynamics, and closely mimics the implementation in iOS's CASpringAnimation.

  • stiffness: The spring stiffness coefficient. Default 100.
  • damping: Defines how the spring’s motion should be damped due to the forces of friction. Default 10.
  • mass: The mass of the object attached to the end of the spring. Default 1.

Other configuration options are as follows:

  • velocity: The initial velocity of the object attached to the spring. Default 0 (object is at rest).
  • overshootClamping: Boolean indicating whether the spring should be clamped and not bounce. Default false.
  • restDisplacementThreshold: The threshold of displacement from rest below which the spring should be considered at rest. Default 0.001.
  • restSpeedThreshold: The speed at which the spring should be considered at rest in pixels per second. Default 0.001.
  • delay: Start the animation after delay (milliseconds). Default 0.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

add()

static add(a, b)

Creates a new Animated value composed from two Animated values added together.

subtract()

static subtract(a, b)

Creates a new Animated value composed by subtracting the second Animated value from the first Animated value.

divide()

static divide(a, b)

Creates a new Animated value composed by dividing the first Animated value by the second Animated value.

multiply()

static multiply(a, b)

Creates a new Animated value composed from two Animated values multiplied together.

modulo()

static modulo(a, modulus)

Creates a new Animated value that is the (non-negative) modulo of the provided Animated value

diffClamp()

static diffClamp(a, min, max)

Create a new Animated value that is limited between 2 values. It uses the difference between the last value so even if the value is far from the bounds it will start changing when the value starts getting closer again. (value = clamp(value + diff, min, max)).

This is useful with scroll events, for example, to show the navbar when scrolling up and to hide it when scrolling down.

delay()

static delay(time)

Starts an animation after the given delay.

sequence()

static sequence(animations)

Starts an array of animations in order, waiting for each to complete before starting the next. If the current running animation is stopped, no following animations will be started.

parallel()

static parallel(animations, config?)

Starts an array of animations all at the same time. By default, if one of the animations is stopped, they will all be stopped. You can override this with the stopTogether flag.

stagger()

static stagger(time, animations)

Array of animations may run in parallel (overlap), but are started in sequence with successive delays. Nice for doing trailing effects.

loop()

static loop(animation, config?)

Loops a given animation continuously, so that each time it reaches the end, it resets and begins again from the start. Will loop without blocking the JS thread if the child animation is set to useNativeDriver: true. In addition, loops can prevent VirtualizedList-based components from rendering more rows while the animation is running. You can pass isInteraction: false in the child animation config to fix this.

Config is an object that may have the following options:

  • iterations: Number of times the animation should loop. Default -1 (infinite).

event()

static event(argMapping, config?)

Takes an array of mappings and extracts values from each arg accordingly, then calls setValue on the mapped outputs. e.g.

onScroll={Animated.event(
[{nativeEvent: {contentOffset: {x: this._scrollX}}}],
{listener: (event) => console.log(event)}, // Optional async listener
)}
...
onPanResponderMove: Animated.event([
null, // raw event arg ignored
{dx: this._panX}], // gestureState arg
{listener: (event, gestureState) => console.log(event, gestureState)}, // Optional async listener
),

Config is an object that may have the following options:

  • listener: Optional async listener.
  • useNativeDriver: Uses the native driver when true. Default false.

forkEvent()

static forkEvent(event, listener)

Advanced imperative API for snooping on animated events that are passed in through props. It permits to add a new javascript listener to an existing AnimatedEvent. If animatedEvent is a javascript listener, it will merge the 2 listeners into a single one, and if animatedEvent is null/undefined, it will assign the javascript listener directly. Use values directly where possible.

unforkEvent()

static unforkEvent(event, listener)

start()

static start([callback]: ?(result?: {finished: boolean}) => void)

Animations are started by calling start() on your animation. start() takes a completion callback that will be called when the animation is done or when the animation is done because stop() was called on it before it could finish.

Parameters:

NameTypeRequiredDescription
callback?(result?: {finished: boolean})NoFunction that will be called after the animation finished running normally or when the animation is done because stop() was called on it before it could finish

Start example with callback:

Animated.timing({}).start(({ finished }) => {
/* completion callback */
});

stop()

static stop()

Stops any running animation.

reset()

static reset()

Stops any running animation and resets the value to its original.

Properties

Value

Standard value class for driving animations. Typically initialized with new Animated.Value(0);

You can read more about Animated.Value API on the separate page.

ValueXY

2D value class for driving 2D animations, such as pan gestures.

You can read more about Animated.ValueXY API on the separate page.

Interpolation

Exported to use the Interpolation type in flow.

Node

Exported for ease of type checking. All animated values derive from this class.

createAnimatedComponent

Make any React component Animatable. Used to create Animated.View, etc.

attachNativeEvent

Imperative API to attach an animated value to an event on a view. Prefer using Animated.event with useNativeDrive: true if possible.

Edit this page
Last updated on
- + diff --git a/docs/animatedvalue.html b/docs/animatedvalue.html index 2e71613a6e2..1d1d6f6e97f 100644 --- a/docs/animatedvalue.html +++ b/docs/animatedvalue.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Animated.Value

Standard value for driving animations. One Animated.Value can drive multiple properties in a synchronized fashion, but can only be driven by one mechanism at a time. Using a new mechanism (e.g. starting a new animation, or calling setValue) will stop any previous ones.

Typically initialized with new Animated.Value(0);

Reference

Methods

setValue()

setValue(value);

Directly set the value. This will stop any animations running on the value and update all the bound properties.

Parameters:

NameTypeRequiredDescription
valuenumberYesValue

setOffset()

setOffset(offset);

Sets an offset that is applied on top of whatever value is set, whether via setValue, an animation, or Animated.event. Useful for compensating things like the start of a pan gesture.

Parameters:

NameTypeRequiredDescription
offsetnumberYesOffset value

flattenOffset()

flattenOffset();

Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.

extractOffset()

extractOffset();

Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.

addListener()

addListener(callback);

Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.

Returns a string that serves as an identifier for the listener.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesThe callback function which will receive an object with a value key set to the new value.

removeListener()

removeListener(id);

Unregister a listener. The id param shall match the identifier previously returned by addListener().

Parameters:

NameTypeRequiredDescription
idstringYesId for the listener being removed.

removeAllListeners()

removeAllListeners();

Remove all registered listeners.

stopAnimation()

stopAnimation([callback]);

Stops any running animation or tracking. callback is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the final value.

resetAnimation()

resetAnimation([callback]);

Stops any animation and resets the value to its original.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the original value.

interpolate()

interpolate(config);

Interpolates the value before updating the property, e.g. mapping 0-1 to 0-10.

See AnimatedInterpolation.js

Parameters:

NameTypeRequiredDescription
configobjectYesSee below.

The config object is composed of the following keys:

  • inputRange: an array of numbers
  • outputRange: an array of numbers or strings
  • easing (optional): a function that returns a number, given an input number
  • extrapolate (optional): a string such as 'extend', 'identity', or 'clamp'
  • extrapolateLeft (optional): a string such as 'extend', 'identity', or 'clamp'
  • extrapolateRight (optional): a string such as 'extend', 'identity', or 'clamp'

animate()

animate(animation, callback);

Typically only used internally, but could be used by a custom Animation class.

Parameters:

NameTypeRequiredDescription
animationAnimationYesSee Animation.js.
callbackfunctionYesCallback function.

stopTracking()

stopTracking();

Typically only used internally.

track()

track(tracking);

Typically only used internally.

Parameters:

NameTypeRequiredDescription
trackingAnimatedNodeYesSee AnimatedNode.js
Edit this page
Last updated on
- + diff --git a/docs/animatedvalue/index.html b/docs/animatedvalue/index.html index 2e71613a6e2..1d1d6f6e97f 100644 --- a/docs/animatedvalue/index.html +++ b/docs/animatedvalue/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Animated.Value

Standard value for driving animations. One Animated.Value can drive multiple properties in a synchronized fashion, but can only be driven by one mechanism at a time. Using a new mechanism (e.g. starting a new animation, or calling setValue) will stop any previous ones.

Typically initialized with new Animated.Value(0);

Reference

Methods

setValue()

setValue(value);

Directly set the value. This will stop any animations running on the value and update all the bound properties.

Parameters:

NameTypeRequiredDescription
valuenumberYesValue

setOffset()

setOffset(offset);

Sets an offset that is applied on top of whatever value is set, whether via setValue, an animation, or Animated.event. Useful for compensating things like the start of a pan gesture.

Parameters:

NameTypeRequiredDescription
offsetnumberYesOffset value

flattenOffset()

flattenOffset();

Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.

extractOffset()

extractOffset();

Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.

addListener()

addListener(callback);

Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.

Returns a string that serves as an identifier for the listener.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesThe callback function which will receive an object with a value key set to the new value.

removeListener()

removeListener(id);

Unregister a listener. The id param shall match the identifier previously returned by addListener().

Parameters:

NameTypeRequiredDescription
idstringYesId for the listener being removed.

removeAllListeners()

removeAllListeners();

Remove all registered listeners.

stopAnimation()

stopAnimation([callback]);

Stops any running animation or tracking. callback is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the final value.

resetAnimation()

resetAnimation([callback]);

Stops any animation and resets the value to its original.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the original value.

interpolate()

interpolate(config);

Interpolates the value before updating the property, e.g. mapping 0-1 to 0-10.

See AnimatedInterpolation.js

Parameters:

NameTypeRequiredDescription
configobjectYesSee below.

The config object is composed of the following keys:

  • inputRange: an array of numbers
  • outputRange: an array of numbers or strings
  • easing (optional): a function that returns a number, given an input number
  • extrapolate (optional): a string such as 'extend', 'identity', or 'clamp'
  • extrapolateLeft (optional): a string such as 'extend', 'identity', or 'clamp'
  • extrapolateRight (optional): a string such as 'extend', 'identity', or 'clamp'

animate()

animate(animation, callback);

Typically only used internally, but could be used by a custom Animation class.

Parameters:

NameTypeRequiredDescription
animationAnimationYesSee Animation.js.
callbackfunctionYesCallback function.

stopTracking()

stopTracking();

Typically only used internally.

track()

track(tracking);

Typically only used internally.

Parameters:

NameTypeRequiredDescription
trackingAnimatedNodeYesSee AnimatedNode.js
Edit this page
Last updated on
- + diff --git a/docs/animatedvaluexy.html b/docs/animatedvaluexy.html index 856f456b8d7..e00ec4ab000 100644 --- a/docs/animatedvaluexy.html +++ b/docs/animatedvaluexy.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Animated.ValueXY

2D Value for driving 2D animations, such as pan gestures. Almost identical API to normal Animated.Value, but multiplexed. Contains two regular Animated.Values under the hood.

Example

Reference

Methods

setValue()

setValue(value);

Directly set the value. This will stop any animations running on the value and update all the bound properties.

Parameters:

NameTypeRequiredDescription
valuenumberYesValue

setOffset()

setOffset(offset);

Sets an offset that is applied on top of whatever value is set, whether via setValue, an animation, or Animated.event. Useful for compensating things like the start of a pan gesture.

Parameters:

NameTypeRequiredDescription
offsetnumberYesOffset value

flattenOffset()

flattenOffset();

Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.

extractOffset()

extractOffset();

Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.

addListener()

addListener(callback);

Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.

Returns a string that serves as an identifier for the listener.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesThe callback function which will receive an object with a value key set to the new value.

removeListener()

removeListener(id);

Unregister a listener. The id param shall match the identifier previously returned by addListener().

Parameters:

NameTypeRequiredDescription
idstringYesId for the listener being removed.

removeAllListeners()

removeAllListeners();

Remove all registered listeners.

stopAnimation()

stopAnimation([callback]);

Stops any running animation or tracking. callback is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the final value.

resetAnimation()

resetAnimation([callback]);

Stops any animation and resets the value to its original.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the original value.

getLayout()

getLayout();

Converts {x, y} into {left, top} for use in style, e.g.

style={this.state.anim.getLayout()}

getTranslateTransform()

getTranslateTransform();

Converts {x, y} into a useable translation transform, e.g.

style={{
transform: this.state.anim.getTranslateTransform()
}}
Edit this page
Last updated on
- + diff --git a/docs/animatedvaluexy/index.html b/docs/animatedvaluexy/index.html index 856f456b8d7..e00ec4ab000 100644 --- a/docs/animatedvaluexy/index.html +++ b/docs/animatedvaluexy/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Animated.ValueXY

2D Value for driving 2D animations, such as pan gestures. Almost identical API to normal Animated.Value, but multiplexed. Contains two regular Animated.Values under the hood.

Example

Reference

Methods

setValue()

setValue(value);

Directly set the value. This will stop any animations running on the value and update all the bound properties.

Parameters:

NameTypeRequiredDescription
valuenumberYesValue

setOffset()

setOffset(offset);

Sets an offset that is applied on top of whatever value is set, whether via setValue, an animation, or Animated.event. Useful for compensating things like the start of a pan gesture.

Parameters:

NameTypeRequiredDescription
offsetnumberYesOffset value

flattenOffset()

flattenOffset();

Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.

extractOffset()

extractOffset();

Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.

addListener()

addListener(callback);

Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.

Returns a string that serves as an identifier for the listener.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesThe callback function which will receive an object with a value key set to the new value.

removeListener()

removeListener(id);

Unregister a listener. The id param shall match the identifier previously returned by addListener().

Parameters:

NameTypeRequiredDescription
idstringYesId for the listener being removed.

removeAllListeners()

removeAllListeners();

Remove all registered listeners.

stopAnimation()

stopAnimation([callback]);

Stops any running animation or tracking. callback is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the final value.

resetAnimation()

resetAnimation([callback]);

Stops any animation and resets the value to its original.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the original value.

getLayout()

getLayout();

Converts {x, y} into {left, top} for use in style, e.g.

style={this.state.anim.getLayout()}

getTranslateTransform()

getTranslateTransform();

Converts {x, y} into a useable translation transform, e.g.

style={{
transform: this.state.anim.getTranslateTransform()
}}
Edit this page
Last updated on
- + diff --git a/docs/animations.html b/docs/animations.html index 7c76c20c026..8c353dc287c 100644 --- a/docs/animations.html +++ b/docs/animations.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Animated.spring(a, {
toValue: 2
}).start();

Interpolation

Each property can be run through an interpolation first. An interpolation maps input ranges to output ranges, typically using a linear interpolation but also supports easing functions. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value.

A basic mapping to convert a 0-1 range to a 0-100 range would be:

value.interpolate({
inputRange: [0, 1],
outputRange: [0, 100]
});

For example, you may want to think about your Animated.Value as going from 0 to 1, but animate the position from 150px to 0px and the opacity from 0 to 1. This can be done by modifying style from the example above like so:

style={{
opacity: this.state.fadeAnim, // Binds directly
transform: [{
translateY: this.state.fadeAnim.interpolate({
inputRange: [0, 1],
outputRange: [150, 0] // 0 : 150, 0.5 : 75, 1 : 0
}),
}],
}}

interpolate() supports multiple range segments as well, which is handy for defining dead zones and other handy tricks. For example, to get a negation relationship at -300 that goes to 0 at -100, then back up to 1 at 0, and then back down to zero at 100 followed by a dead-zone that remains at 0 for everything beyond that, you could do:

value.interpolate({
inputRange: [-300, -100, 0, 100, 101],
outputRange: [300, 0, 1, 0, 0]
});

Which would map like so:

Input | Output
------|-------
-400| 450
-300| 300
-200| 150
-100| 0
-50| 0.5
0| 1
50| 0.5
100| 0
101| 0
200| 0

interpolate() also supports mapping to strings, allowing you to animate colors as well as values with units. For example, if you wanted to animate a rotation you could do:

value.interpolate({
inputRange: [0, 360],
outputRange: ['0deg', '360deg']
});

interpolate() also supports arbitrary easing functions, many of which are already implemented in the Easing module. interpolate() also has configurable behavior for extrapolating the outputRange. You can set the extrapolation by setting the extrapolate, extrapolateLeft, or extrapolateRight options. The default value is extend but you can use clamp to prevent the output value from exceeding outputRange.

Tracking dynamic values

Animated values can also track other values by setting the toValue of an animation to another animated value instead of a plain number. For example, a "Chat Heads" animation like the one used by Messenger on Android could be implemented with a spring() pinned on another animated value, or with timing() and a duration of 0 for rigid tracking. They can also be composed with interpolations:

Animated.spring(follower, { toValue: leader }).start();
Animated.timing(opacity, {
toValue: pan.x.interpolate({
inputRange: [0, 300],
outputRange: [1, 0]
})
}).start();

The leader and follower animated values would be implemented using Animated.ValueXY(). ValueXY is a handy way to deal with 2D interactions, such as panning or dragging. It is a basic wrapper that contains two Animated.Value instances and some helper functions that call through to them, making ValueXY a drop-in replacement for Value in many cases. It allows us to track both x and y values in the example above.

Tracking gestures

Gestures, like panning or scrolling, and other events can map directly to animated values using Animated.event. This is done with a structured map syntax so that values can be extracted from complex event objects. The first level is an array to allow mapping across multiple args, and that array contains nested objects.

For example, when working with horizontal scrolling gestures, you would do the following in order to map event.nativeEvent.contentOffset.x to scrollX (an Animated.Value):

onScroll={Animated.event(
// scrollX = e.nativeEvent.contentOffset.x
[{ nativeEvent: {
contentOffset: {
x: scrollX
}
}
}]
)}

The following example implements a horizontal scrolling carousel where the scroll position indicators are animated using the Animated.event used in the ScrollView

ScrollView with Animated Event Example

When using PanResponder, you could use the following code to extract the x and y positions from gestureState.dx and gestureState.dy. We use a null in the first position of the array, as we are only interested in the second argument passed to the PanResponder handler, which is the gestureState.

onPanResponderMove={Animated.event(
[null, // ignore the native event
// extract dx and dy from gestureState
// like 'pan.x = gestureState.dx, pan.y = gestureState.dy'
{dx: pan.x, dy: pan.y}
])}

PanResponder with Animated Event Example

Responding to the current animation value

You may notice that there is no clear way to read the current value while animating. This is because the value may only be known in the native runtime due to optimizations. If you need to run JavaScript in response to the current value, there are two approaches:

Animated is designed to be fully serializable so that animations can be run in a high performance way, independent of the normal JavaScript event loop. This does influence the API, so keep that in mind when it seems a little trickier to do something compared to a fully synchronous system. Check out Animated.Value.addListener as a way to work around some of these limitations, but use it sparingly since it might have performance implications in the future.

Using the native driver

The Animated API is designed to be serializable. By using the native driver, we send everything about the animation to native before starting the animation, allowing native code to perform the animation on the UI thread without having to go through the bridge on every frame. Once the animation has started, the JS thread can be blocked without affecting the animation.

Using the native driver for normal animations is straightforward. You can add useNativeDriver: true to the animation config when starting it.

Animated.timing(this.state.animatedValue, {
toValue: 1,
duration: 500,
useNativeDriver: true // <-- Add this
}).start();

Animated values are only compatible with one driver so if you use native driver when starting an animation on a value, make sure every animation on that value also uses the native driver.

The native driver also works with Animated.event. This is especially useful for animations that follow the scroll position as without the native driver, the animation will always run a frame behind the gesture due to the async nature of React Native.

<Animated.ScrollView // <-- Use the Animated ScrollView wrapper
scrollEventThrottle={1} // <-- Use 1 here to make sure no events are ever missed
onScroll={Animated.event(
[
{
nativeEvent: {
contentOffset: { y: this.state.animatedValue }
}
}
],
{ useNativeDriver: true } // <-- Add this
)}>
{content}
</Animated.ScrollView>

You can see the native driver in action by running the RNTester app, then loading the Native Animated Example. You can also take a look at the source code to learn how these examples were produced.

Caveats

Not everything you can do with Animated is currently supported by the native driver. The main limitation is that you can only animate non-layout properties: things like transform and opacity will work, but Flexbox and position properties will not. When using Animated.event, it will only work with direct events and not bubbling events. This means it does not work with PanResponder but does work with things like ScrollView#onScroll.

When an animation is running, it can prevent VirtualizedList components from rendering more rows. If you need to run a long or looping animation while the user is scrolling through a list, you can use isInteraction: false in your animation's config to prevent this issue.

Bear in mind

While using transform styles such as rotateY, rotateX, and others ensure the transform style perspective is in place. At this time some animations may not render on Android without it. Example below.

<Animated.View
style={{
transform: [
{ scale: this.state.scale },
{ rotateY: this.state.rotateY },
{ perspective: 1000 } // without this line this Animation will not render on Android while working fine on iOS
]
}}
/>

Additional examples

The RNTester app has various examples of Animated in use:

LayoutAnimation API

LayoutAnimation allows you to globally configure create and update animations that will be used for all views in the next render/layout cycle. This is useful for doing Flexbox layout updates without bothering to measure or calculate specific properties in order to animate them directly, and is especially useful when layout changes may affect ancestors, for example a "see more" expansion that also increases the size of the parent and pushes down the row below which would otherwise require explicit coordination between the components in order to animate them all in sync.

Note that although LayoutAnimation is very powerful and can be quite useful, it provides much less control than Animated and other animation libraries, so you may need to use another approach if you can't get LayoutAnimation to do what you want.

Note that in order to get this to work on Android you need to set the following flags via UIManager:

UIManager.setLayoutAnimationEnabledExperimental &&
UIManager.setLayoutAnimationEnabledExperimental(true);

This example uses a preset value, you can customize the animations as you need, see LayoutAnimation.js for more information.

Additional notes

requestAnimationFrame

requestAnimationFrame is a polyfill from the browser that you might be familiar with. It accepts a function as its only argument and calls that function before the next repaint. It is an essential building block for animations that underlies all of the JavaScript-based animation APIs. In general, you shouldn't need to call this yourself - the animation APIs will manage frame updates for you.

setNativeProps

As mentioned in the Direct Manipulation section, setNativeProps allows us to modify properties of native-backed components (components that are actually backed by native views, unlike composite components) directly, without having to setState and re-render the component hierarchy.

We could use this in the Rebound example to update the scale - this might be helpful if the component that we are updating is deeply nested and hasn't been optimized with shouldComponentUpdate.

If you find your animations with dropping frames (performing below 60 frames per second), look into using setNativeProps or shouldComponentUpdate to optimize them. Or you could run the animations on the UI thread rather than the JavaScript thread with the useNativeDriver 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.

Edit this page
Last updated on
- + diff --git a/docs/animations/index.html b/docs/animations/index.html index 7c76c20c026..8c353dc287c 100644 --- a/docs/animations/index.html +++ b/docs/animations/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Animated.spring(a, {
toValue: 2
}).start();

Interpolation

Each property can be run through an interpolation first. An interpolation maps input ranges to output ranges, typically using a linear interpolation but also supports easing functions. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value.

A basic mapping to convert a 0-1 range to a 0-100 range would be:

value.interpolate({
inputRange: [0, 1],
outputRange: [0, 100]
});

For example, you may want to think about your Animated.Value as going from 0 to 1, but animate the position from 150px to 0px and the opacity from 0 to 1. This can be done by modifying style from the example above like so:

style={{
opacity: this.state.fadeAnim, // Binds directly
transform: [{
translateY: this.state.fadeAnim.interpolate({
inputRange: [0, 1],
outputRange: [150, 0] // 0 : 150, 0.5 : 75, 1 : 0
}),
}],
}}

interpolate() supports multiple range segments as well, which is handy for defining dead zones and other handy tricks. For example, to get a negation relationship at -300 that goes to 0 at -100, then back up to 1 at 0, and then back down to zero at 100 followed by a dead-zone that remains at 0 for everything beyond that, you could do:

value.interpolate({
inputRange: [-300, -100, 0, 100, 101],
outputRange: [300, 0, 1, 0, 0]
});

Which would map like so:

Input | Output
------|-------
-400| 450
-300| 300
-200| 150
-100| 0
-50| 0.5
0| 1
50| 0.5
100| 0
101| 0
200| 0

interpolate() also supports mapping to strings, allowing you to animate colors as well as values with units. For example, if you wanted to animate a rotation you could do:

value.interpolate({
inputRange: [0, 360],
outputRange: ['0deg', '360deg']
});

interpolate() also supports arbitrary easing functions, many of which are already implemented in the Easing module. interpolate() also has configurable behavior for extrapolating the outputRange. You can set the extrapolation by setting the extrapolate, extrapolateLeft, or extrapolateRight options. The default value is extend but you can use clamp to prevent the output value from exceeding outputRange.

Tracking dynamic values

Animated values can also track other values by setting the toValue of an animation to another animated value instead of a plain number. For example, a "Chat Heads" animation like the one used by Messenger on Android could be implemented with a spring() pinned on another animated value, or with timing() and a duration of 0 for rigid tracking. They can also be composed with interpolations:

Animated.spring(follower, { toValue: leader }).start();
Animated.timing(opacity, {
toValue: pan.x.interpolate({
inputRange: [0, 300],
outputRange: [1, 0]
})
}).start();

The leader and follower animated values would be implemented using Animated.ValueXY(). ValueXY is a handy way to deal with 2D interactions, such as panning or dragging. It is a basic wrapper that contains two Animated.Value instances and some helper functions that call through to them, making ValueXY a drop-in replacement for Value in many cases. It allows us to track both x and y values in the example above.

Tracking gestures

Gestures, like panning or scrolling, and other events can map directly to animated values using Animated.event. This is done with a structured map syntax so that values can be extracted from complex event objects. The first level is an array to allow mapping across multiple args, and that array contains nested objects.

For example, when working with horizontal scrolling gestures, you would do the following in order to map event.nativeEvent.contentOffset.x to scrollX (an Animated.Value):

onScroll={Animated.event(
// scrollX = e.nativeEvent.contentOffset.x
[{ nativeEvent: {
contentOffset: {
x: scrollX
}
}
}]
)}

The following example implements a horizontal scrolling carousel where the scroll position indicators are animated using the Animated.event used in the ScrollView

ScrollView with Animated Event Example

When using PanResponder, you could use the following code to extract the x and y positions from gestureState.dx and gestureState.dy. We use a null in the first position of the array, as we are only interested in the second argument passed to the PanResponder handler, which is the gestureState.

onPanResponderMove={Animated.event(
[null, // ignore the native event
// extract dx and dy from gestureState
// like 'pan.x = gestureState.dx, pan.y = gestureState.dy'
{dx: pan.x, dy: pan.y}
])}

PanResponder with Animated Event Example

Responding to the current animation value

You may notice that there is no clear way to read the current value while animating. This is because the value may only be known in the native runtime due to optimizations. If you need to run JavaScript in response to the current value, there are two approaches:

Animated is designed to be fully serializable so that animations can be run in a high performance way, independent of the normal JavaScript event loop. This does influence the API, so keep that in mind when it seems a little trickier to do something compared to a fully synchronous system. Check out Animated.Value.addListener as a way to work around some of these limitations, but use it sparingly since it might have performance implications in the future.

Using the native driver

The Animated API is designed to be serializable. By using the native driver, we send everything about the animation to native before starting the animation, allowing native code to perform the animation on the UI thread without having to go through the bridge on every frame. Once the animation has started, the JS thread can be blocked without affecting the animation.

Using the native driver for normal animations is straightforward. You can add useNativeDriver: true to the animation config when starting it.

Animated.timing(this.state.animatedValue, {
toValue: 1,
duration: 500,
useNativeDriver: true // <-- Add this
}).start();

Animated values are only compatible with one driver so if you use native driver when starting an animation on a value, make sure every animation on that value also uses the native driver.

The native driver also works with Animated.event. This is especially useful for animations that follow the scroll position as without the native driver, the animation will always run a frame behind the gesture due to the async nature of React Native.

<Animated.ScrollView // <-- Use the Animated ScrollView wrapper
scrollEventThrottle={1} // <-- Use 1 here to make sure no events are ever missed
onScroll={Animated.event(
[
{
nativeEvent: {
contentOffset: { y: this.state.animatedValue }
}
}
],
{ useNativeDriver: true } // <-- Add this
)}>
{content}
</Animated.ScrollView>

You can see the native driver in action by running the RNTester app, then loading the Native Animated Example. You can also take a look at the source code to learn how these examples were produced.

Caveats

Not everything you can do with Animated is currently supported by the native driver. The main limitation is that you can only animate non-layout properties: things like transform and opacity will work, but Flexbox and position properties will not. When using Animated.event, it will only work with direct events and not bubbling events. This means it does not work with PanResponder but does work with things like ScrollView#onScroll.

When an animation is running, it can prevent VirtualizedList components from rendering more rows. If you need to run a long or looping animation while the user is scrolling through a list, you can use isInteraction: false in your animation's config to prevent this issue.

Bear in mind

While using transform styles such as rotateY, rotateX, and others ensure the transform style perspective is in place. At this time some animations may not render on Android without it. Example below.

<Animated.View
style={{
transform: [
{ scale: this.state.scale },
{ rotateY: this.state.rotateY },
{ perspective: 1000 } // without this line this Animation will not render on Android while working fine on iOS
]
}}
/>

Additional examples

The RNTester app has various examples of Animated in use:

LayoutAnimation API

LayoutAnimation allows you to globally configure create and update animations that will be used for all views in the next render/layout cycle. This is useful for doing Flexbox layout updates without bothering to measure or calculate specific properties in order to animate them directly, and is especially useful when layout changes may affect ancestors, for example a "see more" expansion that also increases the size of the parent and pushes down the row below which would otherwise require explicit coordination between the components in order to animate them all in sync.

Note that although LayoutAnimation is very powerful and can be quite useful, it provides much less control than Animated and other animation libraries, so you may need to use another approach if you can't get LayoutAnimation to do what you want.

Note that in order to get this to work on Android you need to set the following flags via UIManager:

UIManager.setLayoutAnimationEnabledExperimental &&
UIManager.setLayoutAnimationEnabledExperimental(true);

This example uses a preset value, you can customize the animations as you need, see LayoutAnimation.js for more information.

Additional notes

requestAnimationFrame

requestAnimationFrame is a polyfill from the browser that you might be familiar with. It accepts a function as its only argument and calls that function before the next repaint. It is an essential building block for animations that underlies all of the JavaScript-based animation APIs. In general, you shouldn't need to call this yourself - the animation APIs will manage frame updates for you.

setNativeProps

As mentioned in the Direct Manipulation section, setNativeProps allows us to modify properties of native-backed components (components that are actually backed by native views, unlike composite components) directly, without having to setState and re-render the component hierarchy.

We could use this in the Rebound example to update the scale - this might be helpful if the component that we are updating is deeply nested and hasn't been optimized with shouldComponentUpdate.

If you find your animations with dropping frames (performing below 60 frames per second), look into using setNativeProps or shouldComponentUpdate to optimize them. Or you could run the animations on the UI thread rather than the JavaScript thread with the useNativeDriver 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.

Edit this page
Last updated on
- + diff --git a/docs/app-extensions.html b/docs/app-extensions.html index 90749d32d04..48152df7d7b 100644 --- a/docs/app-extensions.html +++ b/docs/app-extensions.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

App Extensions

App extensions let you provide custom functionality and content outside of your main app. There are different types of app extensions on iOS, and they are all covered in the App Extension Programming Guide. In this guide, we'll briefly cover how you may take advantage of app extensions on iOS.

Memory use in extensions

As these extensions are loaded outside of the regular app sandbox, it's highly likely that several of these app extensions will be loaded simultaneously. As you might expect, these extensions have small memory usage limits. Keep these in mind when developing your app extensions. It's always highly recommended to test your application on an actual device, and more so when developing app extensions: too frequently, developers find that their extension works fine in the iOS Simulator, only to get user reports that their extension is not loading on actual devices.

We highly recommend that you watch Conrad Kramer's talk on Memory Use in Extensions to learn more about this topic.

Today widget

The memory limit of a Today widget is 16 MB. As it happens, Today widget implementations using React Native may work unreliably because the memory usage tends to be too high. You can tell if your Today widget is exceeding the memory limit if it yields the message 'Unable to Load':

Always make sure to test your app extensions in a real device, but be aware that this may not be sufficient, especially when dealing with Today widgets. Debug-configured builds are more likely to exceed the memory limits, while release-configured builds don't fail right away. We highly recommend that you use Xcode's Instruments to analyze your real world memory usage, as it's very likely that your release-configured build is very close to the 16 MB limit. In situations like these, you can quickly go over the 16 MB limit by performing common operations, such as fetching data from an API.

To experiment with the limits of React Native Today widget implementations, try extending the example project in react-native-today-widget.

Other app extensions

Other types of app extensions have greater memory limits than the Today widget. For instance, Custom Keyboard extensions are limited to 48 MB, and Share extensions are limited to 120 MB. Implementing such app extensions with React Native is more viable. One proof of concept example is react-native-ios-share-extension.

Edit this page
Last updated on
- + diff --git a/docs/app-extensions/index.html b/docs/app-extensions/index.html index 90749d32d04..48152df7d7b 100644 --- a/docs/app-extensions/index.html +++ b/docs/app-extensions/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

App Extensions

App extensions let you provide custom functionality and content outside of your main app. There are different types of app extensions on iOS, and they are all covered in the App Extension Programming Guide. In this guide, we'll briefly cover how you may take advantage of app extensions on iOS.

Memory use in extensions

As these extensions are loaded outside of the regular app sandbox, it's highly likely that several of these app extensions will be loaded simultaneously. As you might expect, these extensions have small memory usage limits. Keep these in mind when developing your app extensions. It's always highly recommended to test your application on an actual device, and more so when developing app extensions: too frequently, developers find that their extension works fine in the iOS Simulator, only to get user reports that their extension is not loading on actual devices.

We highly recommend that you watch Conrad Kramer's talk on Memory Use in Extensions to learn more about this topic.

Today widget

The memory limit of a Today widget is 16 MB. As it happens, Today widget implementations using React Native may work unreliably because the memory usage tends to be too high. You can tell if your Today widget is exceeding the memory limit if it yields the message 'Unable to Load':

Always make sure to test your app extensions in a real device, but be aware that this may not be sufficient, especially when dealing with Today widgets. Debug-configured builds are more likely to exceed the memory limits, while release-configured builds don't fail right away. We highly recommend that you use Xcode's Instruments to analyze your real world memory usage, as it's very likely that your release-configured build is very close to the 16 MB limit. In situations like these, you can quickly go over the 16 MB limit by performing common operations, such as fetching data from an API.

To experiment with the limits of React Native Today widget implementations, try extending the example project in react-native-today-widget.

Other app extensions

Other types of app extensions have greater memory limits than the Today widget. For instance, Custom Keyboard extensions are limited to 48 MB, and Share extensions are limited to 120 MB. Implementing such app extensions with React Native is more viable. One proof of concept example is react-native-ios-share-extension.

Edit this page
Last updated on
- + diff --git a/docs/appearance.html b/docs/appearance.html index b2d89da8812..4d0a862d4d9 100644 --- a/docs/appearance.html +++ b/docs/appearance.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Appearance

import { Appearance } from 'react-native';

Developer notes

The Appearance module exposes information about the user's appearance preferences, such as their preferred color scheme (light or dark).

The Appearance API is inspired by the Media Queries draft from the W3C. The color scheme preference is modeled after the prefers-color-scheme CSS media feature.

Example

You can use the Appearance module to determine if the user prefers a dark color scheme:

const colorScheme = Appearance.getColorScheme();
if (colorScheme === 'dark') {
// Use dark color scheme
}

Although the color scheme is available immediately, this may change (e.g. scheduled color scheme change at sunrise or sunset). Any rendering logic or styles that depend on the user preferred color scheme should try to call this function on every render, rather than caching the value. For example, you may use the useColorScheme React hook as it provides and subscribes to color scheme updates, or you may use inline styles rather than setting a value in a StyleSheet.

Reference

Methods

getColorScheme()

static getColorScheme()

Indicates the current user preferred color scheme. The value may be updated later, either through direct user action (e.g. theme selection in device settings) or on a schedule (e.g. light and dark themes that follow the day/night cycle).

Supported color schemes:

  • light: The user prefers a light color theme.
  • dark: The user prefers a dark color theme.
  • null: The user has not indicated a preferred color theme.

See also: useColorScheme hook.

Note: getColorScheme() will always return light when debugging with Chrome.

addChangeListener()

static addChangeListener(listener)

Add an event handler that is fired when appearance preferences change.

removeChangeListener()

static removeChangeListener(listener)

Remove an event handler.

Edit this page
Last updated on
- + diff --git a/docs/appearance/index.html b/docs/appearance/index.html index b2d89da8812..4d0a862d4d9 100644 --- a/docs/appearance/index.html +++ b/docs/appearance/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Appearance

import { Appearance } from 'react-native';

Developer notes

The Appearance module exposes information about the user's appearance preferences, such as their preferred color scheme (light or dark).

The Appearance API is inspired by the Media Queries draft from the W3C. The color scheme preference is modeled after the prefers-color-scheme CSS media feature.

Example

You can use the Appearance module to determine if the user prefers a dark color scheme:

const colorScheme = Appearance.getColorScheme();
if (colorScheme === 'dark') {
// Use dark color scheme
}

Although the color scheme is available immediately, this may change (e.g. scheduled color scheme change at sunrise or sunset). Any rendering logic or styles that depend on the user preferred color scheme should try to call this function on every render, rather than caching the value. For example, you may use the useColorScheme React hook as it provides and subscribes to color scheme updates, or you may use inline styles rather than setting a value in a StyleSheet.

Reference

Methods

getColorScheme()

static getColorScheme()

Indicates the current user preferred color scheme. The value may be updated later, either through direct user action (e.g. theme selection in device settings) or on a schedule (e.g. light and dark themes that follow the day/night cycle).

Supported color schemes:

  • light: The user prefers a light color theme.
  • dark: The user prefers a dark color theme.
  • null: The user has not indicated a preferred color theme.

See also: useColorScheme hook.

Note: getColorScheme() will always return light when debugging with Chrome.

addChangeListener()

static addChangeListener(listener)

Add an event handler that is fired when appearance preferences change.

removeChangeListener()

static removeChangeListener(listener)

Remove an event handler.

Edit this page
Last updated on
- + diff --git a/docs/appregistry.html b/docs/appregistry.html index f7f145623ac..7fb97b2a409 100644 --- a/docs/appregistry.html +++ b/docs/appregistry.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
AppRegistry.registerComponent('Appname', () => App);

To "stop" an application when a view should be destroyed, call AppRegistry.unmountApplicationComponentAtRootTag with the tag that was passed into runApplication. These should always be used as a pair.

AppRegistry should be required early in the require sequence to make sure the JS execution environment is setup before other modules are required.

Reference

Methods

setWrapperComponentProvider()

static setWrapperComponentProvider(provider)

Parameters:

NameTypeRequired
providerComponentProvideryes

enableArchitectureIndicator()

static enableArchitectureIndicator(enabled)

Parameters:

NameTypeRequired
enabledbooleanyes

registerConfig()

static registerConfig([config])

Parameters:

NameTypeRequiredDescription
configAppConfigyesSee below.

Valid AppConfig keys are:

registerComponent()

static registerComponent(appKey, componentProvider, section?)

Parameters:

NameTypeRequired
appKeystringyes
componentProviderComponentProvideryes
sectionbooleanno

registerRunnable()

static registerRunnable(appKey, run)

Parameters:

NameTypeRequired
appKeystringyes
runFunctionyes

registerSection()

static registerSection(appKey, component)

Parameters:

NameTypeRequired
appKeystringyes
componentComponentProvideryes

getAppKeys()

static getAppKeys()

Returns an Array of AppKeys

getSectionKeys()

static getSectionKeys()

Returns an Array of SectionKeys

getSections()

static getSections()

Returns all Runnables which is an object with key of AppKeys and value of type of Runnable which consist of:

getRunnable()

static getRunnable(appKey)

Returns a Runnable object which consist of:

getRegistry()

static getRegistry()

Returns a type Registry which consist of:

setComponentProviderInstrumentationHook()

static setComponentProviderInstrumentationHook(hook)

Parameters:

NameTypeRequiredDescription
hookFunctionyesSee below.

A valid hook accepts the following as arguments:

The hook function returns a React Component

runApplication()

static runApplication(appKey, appParameters)

Loads the JavaScript bundle and runs the app.

Parameters:

NameTypeRequired
appKeystringyes
appParametersanyyes

unmountApplicationComponentAtRootTag()

static unmountApplicationComponentAtRootTag(rootTag)

Stops an application when a view should be destroyed.

Parameters:

NameTypeRequired
rootTagnumberyes

registerHeadlessTask()

static registerHeadlessTask(taskKey, taskProvider)

Register a headless task. A headless task is a bit of code that runs without a UI. @param taskKey the key associated with this task @param taskProvider a promise returning function that takes some data passed from the native side as the only argument; when the promise is resolved or rejected the native side is notified of this event and it may decide to destroy the JS context.

This is a way to run tasks in JavaScript while your app is in the background. It can be used, for example, to sync fresh data, handle push notifications, or play music.

Parameters:

NameTypeRequiredDescription
taskKeyStringyesSee below.
taskProviderTaskProvideryesSee below.

registerCancellableHeadlessTask()

static registerCancellableHeadlessTask(taskKey, taskProvider, taskCancelProvider)

Register a headless task which can be cancelled. A headless task is a bit of code that runs without a UI. @param taskKey the key associated with this task @param taskProvider a promise returning function that takes some data passed from the native side as the only argument; when the promise is resolved or rejected the native side is notified of this event and it may decide to destroy the JS context. @param taskCancelProvider a void returning function that takes no arguments; when a cancellation is requested, the function being executed by taskProvider should wrap up and return ASAP.

Parameters:

NameTypeRequiredDescription
taskKeyStringyesSee below.
taskProviderTaskProvideryesSee below.
taskCancelProviderTaskCancelProvideryesSee below.

startHeadlessTask()

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

Parameters:

NameTypeRequired
taskIdnumberyes
taskKeystringyes
dataanyyes

cancelHeadlessTask()

static cancelHeadlessTask(taskId, taskKey)

Only called from native code. Cancels a headless task.

@param taskId the native id for this task instance that was used when startHeadlessTask was called @param taskKey the key for the task that was used when startHeadlessTask was called

Parameters:

NameTypeRequired
taskIdnumberyes
taskKeystringyes
Edit this page
Last updated on
- + diff --git a/docs/appregistry/index.html b/docs/appregistry/index.html index f7f145623ac..7fb97b2a409 100644 --- a/docs/appregistry/index.html +++ b/docs/appregistry/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
AppRegistry.registerComponent('Appname', () => App);

To "stop" an application when a view should be destroyed, call AppRegistry.unmountApplicationComponentAtRootTag with the tag that was passed into runApplication. These should always be used as a pair.

AppRegistry should be required early in the require sequence to make sure the JS execution environment is setup before other modules are required.

Reference

Methods

setWrapperComponentProvider()

static setWrapperComponentProvider(provider)

Parameters:

NameTypeRequired
providerComponentProvideryes

enableArchitectureIndicator()

static enableArchitectureIndicator(enabled)

Parameters:

NameTypeRequired
enabledbooleanyes

registerConfig()

static registerConfig([config])

Parameters:

NameTypeRequiredDescription
configAppConfigyesSee below.

Valid AppConfig keys are:

registerComponent()

static registerComponent(appKey, componentProvider, section?)

Parameters:

NameTypeRequired
appKeystringyes
componentProviderComponentProvideryes
sectionbooleanno

registerRunnable()

static registerRunnable(appKey, run)

Parameters:

NameTypeRequired
appKeystringyes
runFunctionyes

registerSection()

static registerSection(appKey, component)

Parameters:

NameTypeRequired
appKeystringyes
componentComponentProvideryes

getAppKeys()

static getAppKeys()

Returns an Array of AppKeys

getSectionKeys()

static getSectionKeys()

Returns an Array of SectionKeys

getSections()

static getSections()

Returns all Runnables which is an object with key of AppKeys and value of type of Runnable which consist of:

getRunnable()

static getRunnable(appKey)

Returns a Runnable object which consist of:

getRegistry()

static getRegistry()

Returns a type Registry which consist of:

setComponentProviderInstrumentationHook()

static setComponentProviderInstrumentationHook(hook)

Parameters:

NameTypeRequiredDescription
hookFunctionyesSee below.

A valid hook accepts the following as arguments:

The hook function returns a React Component

runApplication()

static runApplication(appKey, appParameters)

Loads the JavaScript bundle and runs the app.

Parameters:

NameTypeRequired
appKeystringyes
appParametersanyyes

unmountApplicationComponentAtRootTag()

static unmountApplicationComponentAtRootTag(rootTag)

Stops an application when a view should be destroyed.

Parameters:

NameTypeRequired
rootTagnumberyes

registerHeadlessTask()

static registerHeadlessTask(taskKey, taskProvider)

Register a headless task. A headless task is a bit of code that runs without a UI. @param taskKey the key associated with this task @param taskProvider a promise returning function that takes some data passed from the native side as the only argument; when the promise is resolved or rejected the native side is notified of this event and it may decide to destroy the JS context.

This is a way to run tasks in JavaScript while your app is in the background. It can be used, for example, to sync fresh data, handle push notifications, or play music.

Parameters:

NameTypeRequiredDescription
taskKeyStringyesSee below.
taskProviderTaskProvideryesSee below.

registerCancellableHeadlessTask()

static registerCancellableHeadlessTask(taskKey, taskProvider, taskCancelProvider)

Register a headless task which can be cancelled. A headless task is a bit of code that runs without a UI. @param taskKey the key associated with this task @param taskProvider a promise returning function that takes some data passed from the native side as the only argument; when the promise is resolved or rejected the native side is notified of this event and it may decide to destroy the JS context. @param taskCancelProvider a void returning function that takes no arguments; when a cancellation is requested, the function being executed by taskProvider should wrap up and return ASAP.

Parameters:

NameTypeRequiredDescription
taskKeyStringyesSee below.
taskProviderTaskProvideryesSee below.
taskCancelProviderTaskCancelProvideryesSee below.

startHeadlessTask()

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

Parameters:

NameTypeRequired
taskIdnumberyes
taskKeystringyes
dataanyyes

cancelHeadlessTask()

static cancelHeadlessTask(taskId, taskKey)

Only called from native code. Cancels a headless task.

@param taskId the native id for this task instance that was used when startHeadlessTask was called @param taskKey the key for the task that was used when startHeadlessTask was called

Parameters:

NameTypeRequired
taskIdnumberyes
taskKeystringyes
Edit this page
Last updated on
- + diff --git a/docs/appstate.html b/docs/appstate.html index c4ebd550a9c..fa57487d97a 100644 --- a/docs/appstate.html +++ b/docs/appstate.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

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 foreground
  • background - The app is running in the background. The user is either:
    • in another app
    • on the home screen
    • [Android] on another Activity (even if it was launched by your app)
  • [iOS] inactive - This is a state that occurs when transitioning between foreground & background, and during periods of inactivity such as entering the Multitasking view or in the event of an incoming call

For more information, see Apple's documentation

Basic Usage

To see the current state, you can check AppState.currentState, which will be kept up-to-date. However, currentState will be null at launch while AppState retrieves it over the bridge.

If you don't want to see the AppState update from active to inactive on iOS you can remove the state variable and use the appState.current value.

This example will only ever appear to say "Current state is: active" because the app is only visible to the user when in the active state, and the null state will happen only momentarily. If you want to experiment with the code we recommend to use your own device instead of embedded preview.

Reference

Events

change

This event is received when the app state has changed. The listener is called with one of the current app state values.

memoryWarning

This event is used in the need of throwing memory warning or releasing it.

focus

[Android only] Received when the app gains focus (the user is interacting with the app).

blur

[Android only] Received when the user is not actively interacting with the app. Useful in situations when the user pulls down the notification drawer. AppState won't change but the blur event will get fired.

Methods

addEventListener()

addEventListener(type, handler);

Add a handler to AppState changes by listening to the change event type and providing the handler

TODO: now that AppState is a subclass of NativeEventEmitter, we could deprecate addEventListener and removeEventListener and use addListener and listener.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()

removeEventListener(type, handler);

Remove a handler by passing the change event type and the handler

Properties

currentState

AppState.currentState;
Edit this page
Last updated on
- + diff --git a/docs/appstate/index.html b/docs/appstate/index.html index c4ebd550a9c..fa57487d97a 100644 --- a/docs/appstate/index.html +++ b/docs/appstate/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

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 foreground
  • background - The app is running in the background. The user is either:
    • in another app
    • on the home screen
    • [Android] on another Activity (even if it was launched by your app)
  • [iOS] inactive - This is a state that occurs when transitioning between foreground & background, and during periods of inactivity such as entering the Multitasking view or in the event of an incoming call

For more information, see Apple's documentation

Basic Usage

To see the current state, you can check AppState.currentState, which will be kept up-to-date. However, currentState will be null at launch while AppState retrieves it over the bridge.

If you don't want to see the AppState update from active to inactive on iOS you can remove the state variable and use the appState.current value.

This example will only ever appear to say "Current state is: active" because the app is only visible to the user when in the active state, and the null state will happen only momentarily. If you want to experiment with the code we recommend to use your own device instead of embedded preview.

Reference

Events

change

This event is received when the app state has changed. The listener is called with one of the current app state values.

memoryWarning

This event is used in the need of throwing memory warning or releasing it.

focus

[Android only] Received when the app gains focus (the user is interacting with the app).

blur

[Android only] Received when the user is not actively interacting with the app. Useful in situations when the user pulls down the notification drawer. AppState won't change but the blur event will get fired.

Methods

addEventListener()

addEventListener(type, handler);

Add a handler to AppState changes by listening to the change event type and providing the handler

TODO: now that AppState is a subclass of NativeEventEmitter, we could deprecate addEventListener and removeEventListener and use addListener and listener.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()

removeEventListener(type, handler);

Remove a handler by passing the change event type and the handler

Properties

currentState

AppState.currentState;
Edit this page
Last updated on
- + diff --git a/docs/asyncstorage.html b/docs/asyncstorage.html index 54b5d29863b..aa03967392a 100644 --- a/docs/asyncstorage.html +++ b/docs/asyncstorage.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@
// 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"}}
Edit this page
Last updated on
- + diff --git a/docs/asyncstorage/index.html b/docs/asyncstorage/index.html index 54b5d29863b..aa03967392a 100644 --- a/docs/asyncstorage/index.html +++ b/docs/asyncstorage/index.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@
// 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"}}
Edit this page
Last updated on
- + diff --git a/docs/backandroid.html b/docs/backandroid.html index 1acb4a57640..f22c8e393f5 100644 --- a/docs/backandroid.html +++ b/docs/backandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

BackAndroid

Deprecated. Use BackHandler instead.

Methods

Reference

Methods

exitApp()

static exitApp()

addEventListener()

static addEventListener(eventName, handler)

removeEventListener()

static removeEventListener(eventName, handler)
Edit this page
Last updated on
- + diff --git a/docs/backandroid/index.html b/docs/backandroid/index.html index 1acb4a57640..f22c8e393f5 100644 --- a/docs/backandroid/index.html +++ b/docs/backandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

BackAndroid

Deprecated. Use BackHandler instead.

Methods

Reference

Methods

exitApp()

static exitApp()

addEventListener()

static addEventListener(eventName, handler)

removeEventListener()

static removeEventListener(eventName, handler)
Edit this page
Last updated on
- + diff --git a/docs/backhandler.html b/docs/backhandler.html index fe56d899f11..69568390ce1 100644 --- a/docs/backhandler.html +++ b/docs/backhandler.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
if (!this.onMainScreen()) {
this.goBack();
/**
* When true is returned the event will not be bubbled up
* & no other back action will execute
*/
return true;
}
/**
* Returning false will let the event to bubble up & let other event listeners
* or the system's default back action to be executed.
*/
return false;
});

Example

The following example implements a scenario where you confirm if the user wants to exit the app:

BackHandler.addEventListener creates an event listener & returns a NativeEventSubscription object which should be cleared using NativeEventSubscription.remove method.

Additionally BackHandler.removeEventListener can also be used to clear the event listener. Ensure the callback has the reference to the same function used in the addEventListener call as shown the following example ﹣

Usage with React Navigation

If you are using React Navigation to navigate across different screens, you can follow their guide on Custom Android back button behaviour

Backhandler hook

React Native Hooks has a nice useBackHandler hook which will simplify the process of setting up event listeners.

Reference

Methods

addEventListener()

static addEventListener(eventName, handler)

exitApp()

static exitApp()

removeEventListener()

static removeEventListener(eventName, handler)
Edit this page
Last updated on
- + diff --git a/docs/backhandler/index.html b/docs/backhandler/index.html index fe56d899f11..69568390ce1 100644 --- a/docs/backhandler/index.html +++ b/docs/backhandler/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
if (!this.onMainScreen()) {
this.goBack();
/**
* When true is returned the event will not be bubbled up
* & no other back action will execute
*/
return true;
}
/**
* Returning false will let the event to bubble up & let other event listeners
* or the system's default back action to be executed.
*/
return false;
});

Example

The following example implements a scenario where you confirm if the user wants to exit the app:

BackHandler.addEventListener creates an event listener & returns a NativeEventSubscription object which should be cleared using NativeEventSubscription.remove method.

Additionally BackHandler.removeEventListener can also be used to clear the event listener. Ensure the callback has the reference to the same function used in the addEventListener call as shown the following example ﹣

Usage with React Navigation

If you are using React Navigation to navigate across different screens, you can follow their guide on Custom Android back button behaviour

Backhandler hook

React Native Hooks has a nice useBackHandler hook which will simplify the process of setting up event listeners.

Reference

Methods

addEventListener()

static addEventListener(eventName, handler)

exitApp()

static exitApp()

removeEventListener()

static removeEventListener(eventName, handler)
Edit this page
Last updated on
- + diff --git a/docs/building-for-tv.html b/docs/building-for-tv.html index 26d3dca7741..dc0859d66e5 100644 --- a/docs/building-for-tv.html +++ b/docs/building-for-tv.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
componentWillUnmount() {
this._disableTVEventHandler();
}
}
Edit this page
Last updated on
- + diff --git a/docs/building-for-tv/index.html b/docs/building-for-tv/index.html index 26d3dca7741..dc0859d66e5 100644 --- a/docs/building-for-tv/index.html +++ b/docs/building-for-tv/index.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
componentWillUnmount() {
this._disableTVEventHandler();
}
}
Edit this page
Last updated on
- + diff --git a/docs/button.html b/docs/button.html index 6c3d16b6fa0..9084d628801 100644 --- a/docs/button.html +++ b/docs/button.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

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 button using TouchableOpacity or TouchableWithoutFeedback. For inspiration, look at the source code for this button component. Or, take a look at the wide variety of button components built by the community.

<Button
onPress={onPressLearnMore}
title="Learn More"
color="#841584"
accessibilityLabel="Learn more about this purple button"
/>

Example

Reference

Props

onPress

Handler to be called when the user taps the button. The first function argument is an event in form of PressEvent.

TypeRequired
functionYes

title

Text to display inside the button. On Android the given title will be converted to the uppercased form.

TypeRequired
stringYes

accessibilityLabel

Text to display for blindness accessibility features.

TypeRequired
stringNo

color

Color of the text (iOS), or background color of the button (Android).

TypeRequiredDefault
colorNo`'#2196F3'`
Android
'#007AFF'
iOS

disabled

If true, disable all interactions for this component.

TypeRequiredDefault
boolNofalse

hasTVPreferredFocus
TV

TV preferred focus.

TypeRequiredDefault
boolNofalse

nextFocusDown
Android
TV

Designates the next view to receive focus when the user navigates down. See the Android documentation.

TypeRequired
numberNo

nextFocusForward
Android
TV

Designates the next view to receive focus when the user navigates forward. See the Android documentation.

TypeRequired
numberNo

nextFocusLeft
Android
TV

Designates the next view to receive focus when the user navigates left. See the Android documentation.

TypeRequired
numberNo

nextFocusRight
Android
TV

Designates the next view to receive focus when the user navigates right. See the Android documentation.

TypeRequired
numberNo

nextFocusUp
Android
TV

Designates the next view to receive focus when the user navigates up. See the Android documentation.

TypeRequired
numberNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

touchSoundDisabled
Android

If true, doesn't play system sound on touch.

TypeRequiredDefault
booleanNofalse
Edit this page
Last updated on
- + diff --git a/docs/button/index.html b/docs/button/index.html index 6c3d16b6fa0..9084d628801 100644 --- a/docs/button/index.html +++ b/docs/button/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

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 button using TouchableOpacity or TouchableWithoutFeedback. For inspiration, look at the source code for this button component. Or, take a look at the wide variety of button components built by the community.

<Button
onPress={onPressLearnMore}
title="Learn More"
color="#841584"
accessibilityLabel="Learn more about this purple button"
/>

Example

Reference

Props

onPress

Handler to be called when the user taps the button. The first function argument is an event in form of PressEvent.

TypeRequired
functionYes

title

Text to display inside the button. On Android the given title will be converted to the uppercased form.

TypeRequired
stringYes

accessibilityLabel

Text to display for blindness accessibility features.

TypeRequired
stringNo

color

Color of the text (iOS), or background color of the button (Android).

TypeRequiredDefault
colorNo`'#2196F3'`
Android
'#007AFF'
iOS

disabled

If true, disable all interactions for this component.

TypeRequiredDefault
boolNofalse

hasTVPreferredFocus
TV

TV preferred focus.

TypeRequiredDefault
boolNofalse

nextFocusDown
Android
TV

Designates the next view to receive focus when the user navigates down. See the Android documentation.

TypeRequired
numberNo

nextFocusForward
Android
TV

Designates the next view to receive focus when the user navigates forward. See the Android documentation.

TypeRequired
numberNo

nextFocusLeft
Android
TV

Designates the next view to receive focus when the user navigates left. See the Android documentation.

TypeRequired
numberNo

nextFocusRight
Android
TV

Designates the next view to receive focus when the user navigates right. See the Android documentation.

TypeRequired
numberNo

nextFocusUp
Android
TV

Designates the next view to receive focus when the user navigates up. See the Android documentation.

TypeRequired
numberNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

touchSoundDisabled
Android

If true, doesn't play system sound on touch.

TypeRequiredDefault
booleanNofalse
Edit this page
Last updated on
- + diff --git a/docs/cameraroll.html b/docs/cameraroll.html index f6ee4867564..ddcc7eabb53 100644 --- a/docs/cameraroll.html +++ b/docs/cameraroll.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 CameraRoll

Deprecated. Use one of the community packages instead.

CameraRoll provides access to the local camera roll or photo library.

On iOS, the CameraRoll API requires the RCTCameraRoll library to be linked. You can refer to Linking Libraries (iOS) to learn more.

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 app will use this data. This key will appear as Privacy - Photo Library Usage Description in Xcode.

If you are targeting devices running iOS 11 or later, you will also need to add the NSPhotoLibraryAddUsageDescription key in your Info.plist. Use this key to define a string that describes how your app will use this data. By adding this key to your Info.plist, you will be able to request write-only access permission from the user. If you try to save to the camera roll without this permission, your app will exit.

Reference

Methods

saveToCameraRoll()

CameraRoll.saveToCameraRoll(tag, [type]);

Saves the photo or video to the camera roll or photo library.

On Android, the tag must be a local image or video URI, such as "file:///sdcard/img.png".

On iOS, the tag can be any image URI (including local, remote asset-library and base64 data URIs) 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.

Parameters:

NameTypeRequiredDescription
tagstringYesSee above.
typeenum('photo', 'video')NoOverrides automatic detection based on the file extension.

getPhotos()

CameraRoll.getPhotos(params);

Returns a Promise with photo identifier objects from the local camera roll of the device matching shape defined by getPhotosReturnChecker.

Parameters:

NameTypeRequiredDescription
paramsobjectYesExpects a params with the shape described below.
  • 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 matches page_info { end_cursor } returned from a previous call to getPhotos.
  • groupTypes : {string} : Specifies which group types to filter the results to. Valid values are:
    • Album
    • All
    • Event
    • Faces
    • Library
    • PhotoStream
    • SavedPhotos // 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:
    • All
    • Videos
    • Photos // default
  • mimeTypes : {Array} : 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 objects
    • node: {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}
        • playableDuration: {number}
      • 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: {string}
    • end_cursor: {string}

Example

Loading images:

_handleButtonPress = () => {
CameraRoll.getPhotos({
first: 20,
assetType: 'Photos',
})
.then(r => {
this.setState({ photos: r.edges });
})
.catch((err) => {
//Error Loading Images
});
};
render() {
return (
<View>
<Button title="Load Images" onPress={this._handleButtonPress} />
<ScrollView>
{this.state.photos.map((p, i) => {
return (
<Image
key={i}
style={{
width: 300,
height: 100,
}}
source={{ uri: p.node.image.uri }}
/>
);
})}
</ScrollView>
</View>
);
}
Edit this page
Last updated on
- + diff --git a/docs/cameraroll/index.html b/docs/cameraroll/index.html index f6ee4867564..ddcc7eabb53 100644 --- a/docs/cameraroll/index.html +++ b/docs/cameraroll/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 CameraRoll

Deprecated. Use one of the community packages instead.

CameraRoll provides access to the local camera roll or photo library.

On iOS, the CameraRoll API requires the RCTCameraRoll library to be linked. You can refer to Linking Libraries (iOS) to learn more.

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 app will use this data. This key will appear as Privacy - Photo Library Usage Description in Xcode.

If you are targeting devices running iOS 11 or later, you will also need to add the NSPhotoLibraryAddUsageDescription key in your Info.plist. Use this key to define a string that describes how your app will use this data. By adding this key to your Info.plist, you will be able to request write-only access permission from the user. If you try to save to the camera roll without this permission, your app will exit.

Reference

Methods

saveToCameraRoll()

CameraRoll.saveToCameraRoll(tag, [type]);

Saves the photo or video to the camera roll or photo library.

On Android, the tag must be a local image or video URI, such as "file:///sdcard/img.png".

On iOS, the tag can be any image URI (including local, remote asset-library and base64 data URIs) 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.

Parameters:

NameTypeRequiredDescription
tagstringYesSee above.
typeenum('photo', 'video')NoOverrides automatic detection based on the file extension.

getPhotos()

CameraRoll.getPhotos(params);

Returns a Promise with photo identifier objects from the local camera roll of the device matching shape defined by getPhotosReturnChecker.

Parameters:

NameTypeRequiredDescription
paramsobjectYesExpects a params with the shape described below.
  • 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 matches page_info { end_cursor } returned from a previous call to getPhotos.
  • groupTypes : {string} : Specifies which group types to filter the results to. Valid values are:
    • Album
    • All
    • Event
    • Faces
    • Library
    • PhotoStream
    • SavedPhotos // 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:
    • All
    • Videos
    • Photos // default
  • mimeTypes : {Array} : 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 objects
    • node: {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}
        • playableDuration: {number}
      • 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: {string}
    • end_cursor: {string}

Example

Loading images:

_handleButtonPress = () => {
CameraRoll.getPhotos({
first: 20,
assetType: 'Photos',
})
.then(r => {
this.setState({ photos: r.edges });
})
.catch((err) => {
//Error Loading Images
});
};
render() {
return (
<View>
<Button title="Load Images" onPress={this._handleButtonPress} />
<ScrollView>
{this.state.photos.map((p, i) => {
return (
<Image
key={i}
style={{
width: 300,
height: 100,
}}
source={{ uri: p.node.image.uri }}
/>
);
})}
</ScrollView>
</View>
);
}
Edit this page
Last updated on
- + diff --git a/docs/checkbox.html b/docs/checkbox.html index c4ceadeff49..003ffd09973 100644 --- a/docs/checkbox.html +++ b/docs/checkbox.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 CheckBox

Deprecated. Use one of the community packages instead.

Renders a boolean input (Android only).

This is a controlled component that requires an onValueChange callback that updates the value prop in order for the component to reflect user actions. If the value prop is not updated, the component will continue to render the supplied value prop instead of the expected result of any user actions.

Example

Reference

Props

Inherits View Props.

disabled

If true the user won't be able to toggle the checkbox. Default value is false.

TypeRequired
boolNo

onChange

Used in case the props change removes the component.

TypeRequired
functionNo

onValueChange

Invoked with the new value when the value changes.

TypeRequired
functionNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

value

The value of the checkbox. If true the checkbox will be turned on. Default value is false.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/checkbox/index.html b/docs/checkbox/index.html index c4ceadeff49..003ffd09973 100644 --- a/docs/checkbox/index.html +++ b/docs/checkbox/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 CheckBox

Deprecated. Use one of the community packages instead.

Renders a boolean input (Android only).

This is a controlled component that requires an onValueChange callback that updates the value prop in order for the component to reflect user actions. If the value prop is not updated, the component will continue to render the supplied value prop instead of the expected result of any user actions.

Example

Reference

Props

Inherits View Props.

disabled

If true the user won't be able to toggle the checkbox. Default value is false.

TypeRequired
boolNo

onChange

Used in case the props change removes the component.

TypeRequired
functionNo

onValueChange

Invoked with the new value when the value changes.

TypeRequired
functionNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

value

The value of the checkbox. If true the checkbox will be turned on. Default value is false.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/clipboard.html b/docs/clipboard.html index 8cd76e80c58..53f2118debd 100644 --- a/docs/clipboard.html +++ b/docs/clipboard.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 Clipboard

Deprecated. Use one of the community packages instead.

Clipboard gives you an interface for setting and getting content from Clipboard on both Android and iOS

Example

Reference

Methods

getString()

static getString()

Get content of string type, this method returns a Promise, so you can use following code to get clipboard content

async _getContent() {
var content = await Clipboard.getString();
}

setString()

static setString(content)

Set content of string type. You can use following code to set clipboard content

_setContent() {
Clipboard.setString('hello world');
}

Parameters:

NameTypeRequiredDescription
contentstringYesThe content to be stored in the clipboard

Notice

Be careful when you're trying to copy to clipboard any data except string and number, some data need additional stringification. For example, if you will try to copy array - Android will raise an exception, but iOS will not.

Edit this page
Last updated on
- + diff --git a/docs/clipboard/index.html b/docs/clipboard/index.html index 8cd76e80c58..53f2118debd 100644 --- a/docs/clipboard/index.html +++ b/docs/clipboard/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 Clipboard

Deprecated. Use one of the community packages instead.

Clipboard gives you an interface for setting and getting content from Clipboard on both Android and iOS

Example

Reference

Methods

getString()

static getString()

Get content of string type, this method returns a Promise, so you can use following code to get clipboard content

async _getContent() {
var content = await Clipboard.getString();
}

setString()

static setString(content)

Set content of string type. You can use following code to set clipboard content

_setContent() {
Clipboard.setString('hello world');
}

Parameters:

NameTypeRequiredDescription
contentstringYesThe content to be stored in the clipboard

Notice

Be careful when you're trying to copy to clipboard any data except string and number, some data need additional stringification. For example, if you will try to copy array - Android will raise an exception, but iOS will not.

Edit this page
Last updated on
- + diff --git a/docs/colors.html b/docs/colors.html index 240e963545b..a6990c78fce 100644 --- a/docs/colors.html +++ b/docs/colors.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Color Reference

Components in React Native are styled using JavaScript. Color properties usually match how CSS works on the web. General guides on the color usage on each platform could be found below:

Color APIs

React Native has several color APIs designed to allow you to take full advantage of your platform's design and user preferences.

  • PlatformColor lets you reference the platform's color system.
  • DynamicColorIOS is iOS specific and allows you to specify which colors should be used in light or Dark Mode.

Color representations

Red Green Blue (RGB)

React Native supports rgb() and rgba() in both hexadecimal and functional notation:

  • '#f0f' (#rgb)
  • '#ff00ff' (#rrggbb)
  • '#f0ff' (#rgba)
  • '#ff00ff00' (#rrggbbaa)
  • 'rgb(255, 0, 255)'
  • 'rgba(255, 0, 255, 1.0)'

Hue Saturation Lightness (HSL)

React Native supports hsl() and hsla() in functional notation:

  • 'hsl(360, 100%, 100%)'
  • 'hsla(360, 100%, 100%, 1.0)'

Color ints

React Native supports also colors as an int values (in RGB color mode):

  • 0xff00ff00 (0xrrggbbaa)

Note: This might appear similar to the Android Color ints representation but on Android values are stored in SRGB color mode (0xaarrggbb).

Named colors

In React Native you can also use color name strings as values.

Note: React Native only supports lowercase color names. Uppercase color names are not supported.

transparent

This is a shortcut for rgba(0,0,0,0), same like in CSS3.

Color keywords

Named colors implementation follows the CSS3/SVG 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`)
Edit this page
Last updated on
- + diff --git a/docs/colors/index.html b/docs/colors/index.html index 240e963545b..a6990c78fce 100644 --- a/docs/colors/index.html +++ b/docs/colors/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Color Reference

Components in React Native are styled using JavaScript. Color properties usually match how CSS works on the web. General guides on the color usage on each platform could be found below:

Color APIs

React Native has several color APIs designed to allow you to take full advantage of your platform's design and user preferences.

  • PlatformColor lets you reference the platform's color system.
  • DynamicColorIOS is iOS specific and allows you to specify which colors should be used in light or Dark Mode.

Color representations

Red Green Blue (RGB)

React Native supports rgb() and rgba() in both hexadecimal and functional notation:

  • '#f0f' (#rgb)
  • '#ff00ff' (#rrggbb)
  • '#f0ff' (#rgba)
  • '#ff00ff00' (#rrggbbaa)
  • 'rgb(255, 0, 255)'
  • 'rgba(255, 0, 255, 1.0)'

Hue Saturation Lightness (HSL)

React Native supports hsl() and hsla() in functional notation:

  • 'hsl(360, 100%, 100%)'
  • 'hsla(360, 100%, 100%, 1.0)'

Color ints

React Native supports also colors as an int values (in RGB color mode):

  • 0xff00ff00 (0xrrggbbaa)

Note: This might appear similar to the Android Color ints representation but on Android values are stored in SRGB color mode (0xaarrggbb).

Named colors

In React Native you can also use color name strings as values.

Note: React Native only supports lowercase color names. Uppercase color names are not supported.

transparent

This is a shortcut for rgba(0,0,0,0), same like in CSS3.

Color keywords

Named colors implementation follows the CSS3/SVG 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`)
Edit this page
Last updated on
- + diff --git a/docs/communication-android.html b/docs/communication-android.html index 3759a42f7f0..06648c9fc62 100644 --- a/docs/communication-android.html +++ b/docs/communication-android.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
mReactRootView.setAppProperties(updatedProps);

It is fine to update properties anytime. However, updates have to be performed on the main thread. You use the getter on any thread.

There is no way to update only a few properties at a time. We suggest that you build it into your own wrapper instead.

Note: Currently, JS function componentWillUpdateProps of the top level RN component will not be called after a prop update. However, you can access the new props in componentDidMount function.

Passing properties from React Native to native

The problem exposing properties of native components is covered in detail in this article. In short, properties that are to be reflected in JavaScript needs to be exposed as setter method annotated with @ReactProp, then use them in React Native as if the component was an ordinary React Native component.

Limits of properties

The main drawback of cross-language properties is that they do not support callbacks, which would allow us to handle bottom-up data bindings. Imagine you have a small RN view that you want to be removed from the native parent view as a result of a JS action. There is no way to do that with props, as the information would need to go bottom-up.

Although we have a flavor of cross-language callbacks (described here), these callbacks are not always the thing we need. The main problem is that they are not intended to be passed as properties. Rather, this mechanism allows us to trigger a native action from JS, and handle the result of that action in JS.

Other ways of cross-language interaction (events and native modules)

As stated in the previous chapter, using properties comes with some limitations. Sometimes properties are not enough to drive the logic of our app and we need a solution that gives more flexibility. This chapter covers other communication techniques available in React Native. They can be used for internal communication (between JS and native layers in RN) as well as for external communication (between RN and the 'pure native' part of your app).

React Native enables you to perform cross-language function calls. You can execute custom native code from JS and vice versa. Unfortunately, depending on the side we are working on, we achieve the same goal in different ways. For native - we use events mechanism to schedule an execution of a handler function in JS, while for React Native we directly call methods exported by native modules.

Calling React Native functions from native (events)

Events are described in detail in this article. Note that using events gives us no guarantees about execution time, as the event is handled on a separate thread.

Events are powerful, because they allow us to change React Native components without needing a reference to them. However, there are some pitfalls that you can fall into while using them:

Calling native functions from React Native (native modules)

Native modules are Java classes that are available in JS. Typically one instance of each module is created per JS bridge. They can export arbitrary functions and constants to React Native. They have been covered in detail in this article.

Warning: All native modules share the same namespace. Watch out for name collisions when creating new ones.

Edit this page
Last updated on
- + diff --git a/docs/communication-android/index.html b/docs/communication-android/index.html index 3759a42f7f0..06648c9fc62 100644 --- a/docs/communication-android/index.html +++ b/docs/communication-android/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
mReactRootView.setAppProperties(updatedProps);

It is fine to update properties anytime. However, updates have to be performed on the main thread. You use the getter on any thread.

There is no way to update only a few properties at a time. We suggest that you build it into your own wrapper instead.

Note: Currently, JS function componentWillUpdateProps of the top level RN component will not be called after a prop update. However, you can access the new props in componentDidMount function.

Passing properties from React Native to native

The problem exposing properties of native components is covered in detail in this article. In short, properties that are to be reflected in JavaScript needs to be exposed as setter method annotated with @ReactProp, then use them in React Native as if the component was an ordinary React Native component.

Limits of properties

The main drawback of cross-language properties is that they do not support callbacks, which would allow us to handle bottom-up data bindings. Imagine you have a small RN view that you want to be removed from the native parent view as a result of a JS action. There is no way to do that with props, as the information would need to go bottom-up.

Although we have a flavor of cross-language callbacks (described here), these callbacks are not always the thing we need. The main problem is that they are not intended to be passed as properties. Rather, this mechanism allows us to trigger a native action from JS, and handle the result of that action in JS.

Other ways of cross-language interaction (events and native modules)

As stated in the previous chapter, using properties comes with some limitations. Sometimes properties are not enough to drive the logic of our app and we need a solution that gives more flexibility. This chapter covers other communication techniques available in React Native. They can be used for internal communication (between JS and native layers in RN) as well as for external communication (between RN and the 'pure native' part of your app).

React Native enables you to perform cross-language function calls. You can execute custom native code from JS and vice versa. Unfortunately, depending on the side we are working on, we achieve the same goal in different ways. For native - we use events mechanism to schedule an execution of a handler function in JS, while for React Native we directly call methods exported by native modules.

Calling React Native functions from native (events)

Events are described in detail in this article. Note that using events gives us no guarantees about execution time, as the event is handled on a separate thread.

Events are powerful, because they allow us to change React Native components without needing a reference to them. However, there are some pitfalls that you can fall into while using them:

Calling native functions from React Native (native modules)

Native modules are Java classes that are available in JS. Typically one instance of each module is created per JS bridge. They can export arbitrary functions and constants to React Native. They have been covered in detail in this article.

Warning: All native modules share the same namespace. Watch out for name collisions when creating new ones.

Edit this page
Last updated on
- + diff --git a/docs/communication-ios.html b/docs/communication-ios.html index ef81d8e99bd..1c80d59d9de 100644 --- a/docs/communication-ios.html +++ b/docs/communication-ios.html @@ -19,7 +19,7 @@ - + @@ -44,7 +44,7 @@
rootView.frame = newFrame;
}

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 example 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 separate 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's hidden property). Then change its visibility in the delegate method.

Edit this page
Last updated on
- + diff --git a/docs/communication-ios/index.html b/docs/communication-ios/index.html index ef81d8e99bd..1c80d59d9de 100644 --- a/docs/communication-ios/index.html +++ b/docs/communication-ios/index.html @@ -19,7 +19,7 @@ - + @@ -44,7 +44,7 @@
rootView.frame = newFrame;
}

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 example 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 separate 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's hidden property). Then change its visibility in the delegate method.

Edit this page
Last updated on
- + diff --git a/docs/components-and-apis.html b/docs/components-and-apis.html index 26765821513..e76b9729bce 100644 --- a/docs/components-and-apis.html +++ b/docs/components-and-apis.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Core Components and APIs

React Native provides a number of built-in Core Components ready for you to use in your app. You can find them all in the left sidebar (or menu above, if you are on a narrow screen). 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 has a community of thousands of developers. If you're looking for a library that does something specific, please refer to this guide about finding libraries.

Basic Components

Most apps will end up using one of these basic components.

View

The most fundamental component for building a UI.

Text

A component for displaying text.

Image

A component for displaying images.

TextInput

A component for inputting text into the app via a keyboard.

ScrollView

Provides a scrolling container that can host multiple components and views.

StyleSheet

Provides an abstraction layer similar to CSS stylesheets.

User Interface

These common user interface controls will render on any platform.

Button

A basic button component for handling touches that should render nicely on any platform.

Switch

Renders a boolean input.

List Views

Unlike the more generic ScrollView, the following list view components only render elements that are currently showing on the screen. This makes them a performant choice for displaying long lists of data.

FlatList

A component for rendering performant scrollable lists.

SectionList

Like FlatList, but for sectioned lists.

Android Components and APIs

Many of the following components provide wrappers for commonly used Android classes.

BackHandler

Detect hardware button presses for back navigation.

DrawerLayoutAndroid

Renders a DrawerLayout on Android.

PermissionsAndroid

Provides access to the permissions model introduced in Android M.

ToastAndroid

Create an Android Toast alert.

iOS Components and APIs

Many of the following components provide wrappers for commonly used UIKit classes.

ActionSheetIOS

API to display an iOS action sheet or share sheet.

Others

These components may be useful for certain applications. For an exhaustive list of components and APIs, check out the sidebar to the left (or menu above, if you are on a narrow screen).

ActivityIndicator

Displays a circular loading indicator.

Alert

Launches an alert dialog with the specified title and message.

Animated

A library for creating fluid, powerful animations that are easy to build and maintain.

Dimensions

Provides an interface for getting device dimensions.

KeyboardAvoidingView

Provides a view that moves out of the way of the virtual keyboard automatically.

Linking

Provides a general interface to interact with both incoming and outgoing app links.

Modal

Provides a simple way to present content above an enclosing view.

PixelRatio

Provides access to the device pixel density.

RefreshControl

This component is used inside a ScrollView to add pull to refresh functionality.

StatusBar

Component to control the app status bar.

Edit this page
Last updated on
- + diff --git a/docs/components-and-apis/index.html b/docs/components-and-apis/index.html index 26765821513..e76b9729bce 100644 --- a/docs/components-and-apis/index.html +++ b/docs/components-and-apis/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Core Components and APIs

React Native provides a number of built-in Core Components ready for you to use in your app. You can find them all in the left sidebar (or menu above, if you are on a narrow screen). 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 has a community of thousands of developers. If you're looking for a library that does something specific, please refer to this guide about finding libraries.

Basic Components

Most apps will end up using one of these basic components.

View

The most fundamental component for building a UI.

Text

A component for displaying text.

Image

A component for displaying images.

TextInput

A component for inputting text into the app via a keyboard.

ScrollView

Provides a scrolling container that can host multiple components and views.

StyleSheet

Provides an abstraction layer similar to CSS stylesheets.

User Interface

These common user interface controls will render on any platform.

Button

A basic button component for handling touches that should render nicely on any platform.

Switch

Renders a boolean input.

List Views

Unlike the more generic ScrollView, the following list view components only render elements that are currently showing on the screen. This makes them a performant choice for displaying long lists of data.

FlatList

A component for rendering performant scrollable lists.

SectionList

Like FlatList, but for sectioned lists.

Android Components and APIs

Many of the following components provide wrappers for commonly used Android classes.

BackHandler

Detect hardware button presses for back navigation.

DrawerLayoutAndroid

Renders a DrawerLayout on Android.

PermissionsAndroid

Provides access to the permissions model introduced in Android M.

ToastAndroid

Create an Android Toast alert.

iOS Components and APIs

Many of the following components provide wrappers for commonly used UIKit classes.

ActionSheetIOS

API to display an iOS action sheet or share sheet.

Others

These components may be useful for certain applications. For an exhaustive list of components and APIs, check out the sidebar to the left (or menu above, if you are on a narrow screen).

ActivityIndicator

Displays a circular loading indicator.

Alert

Launches an alert dialog with the specified title and message.

Animated

A library for creating fluid, powerful animations that are easy to build and maintain.

Dimensions

Provides an interface for getting device dimensions.

KeyboardAvoidingView

Provides a view that moves out of the way of the virtual keyboard automatically.

Linking

Provides a general interface to interact with both incoming and outgoing app links.

Modal

Provides a simple way to present content above an enclosing view.

PixelRatio

Provides access to the device pixel density.

RefreshControl

This component is used inside a ScrollView to add pull to refresh functionality.

StatusBar

Component to control the app status bar.

Edit this page
Last updated on
- + diff --git a/docs/custom-webview-android.html b/docs/custom-webview-android.html index abe2b597b3c..045a77be91b 100644 --- a/docs/custom-webview-android.html +++ b/docs/custom-webview-android.html @@ -19,7 +19,7 @@ - + @@ -60,7 +60,7 @@
render() {
return (
<WebView
{...this.props}
nativeConfig={{
component: RCTCustomWebView,
props: {
finalUrl: this.props.finalUrl,
onNavigationCompleted: this._onNavigationCompleted
}
}}
/>
);
}
}

Similar to regular native components, you must provide all your prop types in the component to have them forwarded on to the native component. However, if you have some prop types that are only used internally in component, you can add them to the nativeOnly property of the third argument previously mentioned. For event handlers, you have to use the value true instead of a regular prop type.

For example, if you wanted to add an internal event handler called onScrollToBottom, you would use,

const RCTCustomWebView = requireNativeComponent(
'RCTCustomWebView',
CustomWebView,
{
...WebView.extraNativeComponentConfig,
nativeOnly: {
...WebView.extraNativeComponentConfig.nativeOnly,
onScrollToBottom: true
}
}
);
Edit this page
Last updated on
- + diff --git a/docs/custom-webview-android/index.html b/docs/custom-webview-android/index.html index abe2b597b3c..045a77be91b 100644 --- a/docs/custom-webview-android/index.html +++ b/docs/custom-webview-android/index.html @@ -19,7 +19,7 @@ - + @@ -60,7 +60,7 @@
render() {
return (
<WebView
{...this.props}
nativeConfig={{
component: RCTCustomWebView,
props: {
finalUrl: this.props.finalUrl,
onNavigationCompleted: this._onNavigationCompleted
}
}}
/>
);
}
}

Similar to regular native components, you must provide all your prop types in the component to have them forwarded on to the native component. However, if you have some prop types that are only used internally in component, you can add them to the nativeOnly property of the third argument previously mentioned. For event handlers, you have to use the value true instead of a regular prop type.

For example, if you wanted to add an internal event handler called onScrollToBottom, you would use,

const RCTCustomWebView = requireNativeComponent(
'RCTCustomWebView',
CustomWebView,
{
...WebView.extraNativeComponentConfig,
nativeOnly: {
...WebView.extraNativeComponentConfig.nativeOnly,
onScrollToBottom: true
}
}
);
Edit this page
Last updated on
- + diff --git a/docs/custom-webview-ios.html b/docs/custom-webview-ios.html index aeafcdc3c2b..4263d162d5d 100644 --- a/docs/custom-webview-ios.html +++ b/docs/custom-webview-ios.html @@ -19,7 +19,7 @@ - + @@ -63,7 +63,7 @@
render() {
return (
<WebView
{...this.props}
nativeConfig={{
component: RCTCustomWebView,
props: {
finalUrl: this.props.finalUrl,
onNavigationCompleted: this._onNavigationCompleted
},
viewManager: CustomWebViewManager
}}
/>
);
}
}

Similar to regular native components, you must provide all your prop types in the component to have them forwarded on to the native component. However, if you have some prop types that are only used internally in component, you can add them to the nativeOnly property of the third argument previously mentioned. For event handlers, you have to use the value true instead of a regular prop type.

For example, if you wanted to add an internal event handler called onScrollToBottom, you would use,

const RCTCustomWebView = requireNativeComponent(
'RCTCustomWebView',
CustomWebView,
{
...WebView.extraNativeComponentConfig,
nativeOnly: {
...WebView.extraNativeComponentConfig.nativeOnly,
onScrollToBottom: true
}
}
);
Edit this page
Last updated on
- + diff --git a/docs/custom-webview-ios/index.html b/docs/custom-webview-ios/index.html index aeafcdc3c2b..4263d162d5d 100644 --- a/docs/custom-webview-ios/index.html +++ b/docs/custom-webview-ios/index.html @@ -19,7 +19,7 @@ - + @@ -63,7 +63,7 @@
render() {
return (
<WebView
{...this.props}
nativeConfig={{
component: RCTCustomWebView,
props: {
finalUrl: this.props.finalUrl,
onNavigationCompleted: this._onNavigationCompleted
},
viewManager: CustomWebViewManager
}}
/>
);
}
}

Similar to regular native components, you must provide all your prop types in the component to have them forwarded on to the native component. However, if you have some prop types that are only used internally in component, you can add them to the nativeOnly property of the third argument previously mentioned. For event handlers, you have to use the value true instead of a regular prop type.

For example, if you wanted to add an internal event handler called onScrollToBottom, you would use,

const RCTCustomWebView = requireNativeComponent(
'RCTCustomWebView',
CustomWebView,
{
...WebView.extraNativeComponentConfig,
nativeOnly: {
...WebView.extraNativeComponentConfig.nativeOnly,
onScrollToBottom: true
}
}
);
Edit this page
Last updated on
- + diff --git a/docs/datepickerandroid.html b/docs/datepickerandroid.html index 65fbb75d671..12a7f208e63 100644 --- a/docs/datepickerandroid.html +++ b/docs/datepickerandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 DatePickerAndroid

Deprecated. Use one of the community packages instead.

Opens the standard Android date picker dialog.

Example

try {
const {
action,
year,
month,
day
} = await DatePickerAndroid.open({
// Use `new Date()` for current date.
// May 25 2020. Month 0 is January.
date: new Date(2020, 4, 25)
});
if (action !== DatePickerAndroid.dismissedAction) {
// Selected year, month (0-11), day
}
} catch ({ code, message }) {
console.warn('Cannot open date picker', message);
}

Reference

Methods

open()

static open(options)

Opens the standard Android date picker dialog.

The available keys for the options object are:

  • date (Date object or timestamp in milliseconds) - date to show by default
  • minDate (Date or timestamp in milliseconds) - minimum date that can be selected
  • maxDate (Date object or timestamp in milliseconds) - maximum date that can be selected
  • mode (enum('calendar', 'spinner', 'default')) - To set the date-picker mode to calendar/spinner/default
    • 'calendar': Show a date picker in calendar mode.
    • 'spinner': Show a date picker in spinner mode.
    • 'default': Show a default native date picker(spinner/calendar) based on android versions.

Returns a Promise which will be invoked an object containing action, year, month (0-11), 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 is equal to DatePickerAndroid.dateSetAction 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.

dateSetAction()

static dateSetAction()

A date has been selected.

dismissedAction()

static dismissedAction()

The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/datepickerandroid/index.html b/docs/datepickerandroid/index.html index 65fbb75d671..12a7f208e63 100644 --- a/docs/datepickerandroid/index.html +++ b/docs/datepickerandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 DatePickerAndroid

Deprecated. Use one of the community packages instead.

Opens the standard Android date picker dialog.

Example

try {
const {
action,
year,
month,
day
} = await DatePickerAndroid.open({
// Use `new Date()` for current date.
// May 25 2020. Month 0 is January.
date: new Date(2020, 4, 25)
});
if (action !== DatePickerAndroid.dismissedAction) {
// Selected year, month (0-11), day
}
} catch ({ code, message }) {
console.warn('Cannot open date picker', message);
}

Reference

Methods

open()

static open(options)

Opens the standard Android date picker dialog.

The available keys for the options object are:

  • date (Date object or timestamp in milliseconds) - date to show by default
  • minDate (Date or timestamp in milliseconds) - minimum date that can be selected
  • maxDate (Date object or timestamp in milliseconds) - maximum date that can be selected
  • mode (enum('calendar', 'spinner', 'default')) - To set the date-picker mode to calendar/spinner/default
    • 'calendar': Show a date picker in calendar mode.
    • 'spinner': Show a date picker in spinner mode.
    • 'default': Show a default native date picker(spinner/calendar) based on android versions.

Returns a Promise which will be invoked an object containing action, year, month (0-11), 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 is equal to DatePickerAndroid.dateSetAction 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.

dateSetAction()

static dateSetAction()

A date has been selected.

dismissedAction()

static dismissedAction()

The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/datepickerios.html b/docs/datepickerios.html index 8614cc2c11a..a07b160124b 100644 --- a/docs/datepickerios.html +++ b/docs/datepickerios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 DatePickerIOS

Deprecated. Use one of the community packages instead.

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 source of truth.

Example

Reference

Props

Inherits View Props.

date

The currently selected date.

TypeRequired
DateYes

onChange

Date change handler.

This is called when the user changes the date or time in the UI. The first and only argument is an Event. For getting the date the picker was changed to, use onDateChange instead.

TypeRequired
functionNo

onDateChange

Date change handler.

This is called when the user changes the date or time in the UI. The first and only argument is a Date object representing the new date and time.

TypeRequired
functionYes

maximumDate

Maximum date.

Restricts the range of possible date/time values.

TypeRequired
DateNo

Example with maximumDate set to December 31, 2017:

minimumDate

Minimum date.

Restricts the range of possible date/time values.

TypeRequired
DateNo

See maximumDate for an example image.

minuteInterval

The interval at which minutes can be selected.

TypeRequired
enum(1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30)No

Example with minuteInterval set to 10:

mode

The date picker mode.

TypeRequired
enum('date', 'time', 'datetime', 'countdown')No

Example with mode set to date, time, and datetime:

locale

The locale for the date picker. Value needs to be a Locale ID.

TypeRequired
StringNo

timeZoneOffsetInMinutes

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.

TypeRequired
numberNo

initialDate

Provides an initial value that will change when the user starts selecting a date. It is useful for use-cases where you do not want to deal with listening to events and updating the date prop to keep the controlled state in sync. The controlled state has known bugs which causes it to go out of sync with native. The initialDate prop is intended to allow you to have native be source of truth.

TypeRequired
DateNo
Edit this page
Last updated on
- + diff --git a/docs/datepickerios/index.html b/docs/datepickerios/index.html index 8614cc2c11a..a07b160124b 100644 --- a/docs/datepickerios/index.html +++ b/docs/datepickerios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 DatePickerIOS

Deprecated. Use one of the community packages instead.

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 source of truth.

Example

Reference

Props

Inherits View Props.

date

The currently selected date.

TypeRequired
DateYes

onChange

Date change handler.

This is called when the user changes the date or time in the UI. The first and only argument is an Event. For getting the date the picker was changed to, use onDateChange instead.

TypeRequired
functionNo

onDateChange

Date change handler.

This is called when the user changes the date or time in the UI. The first and only argument is a Date object representing the new date and time.

TypeRequired
functionYes

maximumDate

Maximum date.

Restricts the range of possible date/time values.

TypeRequired
DateNo

Example with maximumDate set to December 31, 2017:

minimumDate

Minimum date.

Restricts the range of possible date/time values.

TypeRequired
DateNo

See maximumDate for an example image.

minuteInterval

The interval at which minutes can be selected.

TypeRequired
enum(1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30)No

Example with minuteInterval set to 10:

mode

The date picker mode.

TypeRequired
enum('date', 'time', 'datetime', 'countdown')No

Example with mode set to date, time, and datetime:

locale

The locale for the date picker. Value needs to be a Locale ID.

TypeRequired
StringNo

timeZoneOffsetInMinutes

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.

TypeRequired
numberNo

initialDate

Provides an initial value that will change when the user starts selecting a date. It is useful for use-cases where you do not want to deal with listening to events and updating the date prop to keep the controlled state in sync. The controlled state has known bugs which causes it to go out of sync with native. The initialDate prop is intended to allow you to have native be source of truth.

TypeRequired
DateNo
Edit this page
Last updated on
- + diff --git a/docs/debugging.html b/docs/debugging.html index 871cf38dbc2..5271320f06b 100644 --- a/docs/debugging.html +++ b/docs/debugging.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
// Ignore all log notifications:
LogBox.ignoreAllLogs();

Unhandled Errors

Unhanded JavaScript errors such as undefined is not a function will automatically open a full screen LogBox error with the source of the error. These errors are dismissable and minimizable so that you can see the state of your app when these errors occur, but should always be addressed.

Syntax Errors

Syntax errors will automatically open a full screen LogBox error with the source of the syntax error. This error is not dismissable because it represents invalid JavaScript execution that must be fixed before continuing with your app. To dismiss these errors, fix the syntax error and either save to automatically dismiss (with Fast Refresh enabled) or cmd+r to reload (with Fast Refresh disabled).

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.

Safari Developer Tools

You can use Safari to debug the iOS version of your app without having to enable "Debug JS Remotely".

While sourcemaps may not be enabled by default, you can follow this guide or video to enable them and set break points at the right places in the source code.

However, every time the app is reloaded (using live reload, or by manually reloading), a new JSContext is created. Choosing "Automatically Show Web Inspectors for JSContexts" saves you from having to select the latest JSContext manually.

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:

Note: Version 4 of react-devtools requires react-native version 0.62 or higher to work properly.

npm install -g react-devtools

Now run react-devtools from the terminal to launch the standalone DevTools app:

react-devtools

React DevTools

It should connect to your simulator within a few seconds.

Note: if you prefer to avoid global installations, you can add react-devtools as a project dependency. Add the react-devtools package to your project using npm install --save-dev react-devtools, then add "react-devtools": "react-devtools" to the scripts section in your package.json, and then run npm run react-devtools from your project folder to open the DevTools.

Integration with React Native Inspector

Open the in-app developer menu and choose "Toggle Inspector". It will bring up an overlay that lets you tap on any UI element and see information about it:

React Native Inspector

However, when react-devtools is running, Inspector will enter a 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:

React DevTools Inspector Integration

You can choose "Toggle 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.

React DevTools Chrome Console Integration

Performance Monitor

You can enable a performance overlay to help you debug performance problems by selecting "Perf Monitor" in the Developer Menu.

Debugging Application State

Reactotron is an open-source desktop app that allows you to inspect Redux or MobX-State-Tree application state as well as view custom logs, run custom commands such as resetting state, store and restore state snapshots, and other helpful debugging features for React Native apps.

You can view installation instructions in the README. If you're using Expo, here is an article detailing how to install on Expo.

Native Debugging

Accessing console logs

You can display the console logs for an iOS or Android app by using the following commands in a terminal while the app is running:

$ npx react-native log-ios
$ npx react-native log-android

You may also access these through Debug → Open System Log... in the iOS Simulator or by running adb logcat *:S ReactNative:V ReactNativeJS:V in a terminal while an Android app is running on a device or emulator.

If you're using Create React Native App or Expo CLI, console logs already appear in the same terminal output as the bundler.

Debugging on a device with Chrome Developer Tools

If you're using Create React Native App or Expo CLI, this is configured for you already.

On iOS devices, open the file RCTWebSocketExecutor.m and change "localhost" to the IP address of your computer, then select "Debug JS Remotely" from the Developer Menu.

On Android 5.0+ devices connected via USB, you can use the adb command line tool to setup port forwarding from the device to your computer:

adb reverse tcp:8081 tcp:8081

Alternatively, select "Dev Settings" from the Developer Menu, then update the "Debug server host for device" setting to match the IP address of your computer.

If you run into any issues, it may be possible that one of your Chrome extensions is interacting in unexpected ways with the debugger. Try disabling all of your extensions and re-enabling them one-by-one until you find the problematic extension.

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.

Edit this page
Last updated on
- + diff --git a/docs/debugging/index.html b/docs/debugging/index.html index 871cf38dbc2..5271320f06b 100644 --- a/docs/debugging/index.html +++ b/docs/debugging/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
// Ignore all log notifications:
LogBox.ignoreAllLogs();

Unhandled Errors

Unhanded JavaScript errors such as undefined is not a function will automatically open a full screen LogBox error with the source of the error. These errors are dismissable and minimizable so that you can see the state of your app when these errors occur, but should always be addressed.

Syntax Errors

Syntax errors will automatically open a full screen LogBox error with the source of the syntax error. This error is not dismissable because it represents invalid JavaScript execution that must be fixed before continuing with your app. To dismiss these errors, fix the syntax error and either save to automatically dismiss (with Fast Refresh enabled) or cmd+r to reload (with Fast Refresh disabled).

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.

Safari Developer Tools

You can use Safari to debug the iOS version of your app without having to enable "Debug JS Remotely".

While sourcemaps may not be enabled by default, you can follow this guide or video to enable them and set break points at the right places in the source code.

However, every time the app is reloaded (using live reload, or by manually reloading), a new JSContext is created. Choosing "Automatically Show Web Inspectors for JSContexts" saves you from having to select the latest JSContext manually.

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:

Note: Version 4 of react-devtools requires react-native version 0.62 or higher to work properly.

npm install -g react-devtools

Now run react-devtools from the terminal to launch the standalone DevTools app:

react-devtools

React DevTools

It should connect to your simulator within a few seconds.

Note: if you prefer to avoid global installations, you can add react-devtools as a project dependency. Add the react-devtools package to your project using npm install --save-dev react-devtools, then add "react-devtools": "react-devtools" to the scripts section in your package.json, and then run npm run react-devtools from your project folder to open the DevTools.

Integration with React Native Inspector

Open the in-app developer menu and choose "Toggle Inspector". It will bring up an overlay that lets you tap on any UI element and see information about it:

React Native Inspector

However, when react-devtools is running, Inspector will enter a 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:

React DevTools Inspector Integration

You can choose "Toggle 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.

React DevTools Chrome Console Integration

Performance Monitor

You can enable a performance overlay to help you debug performance problems by selecting "Perf Monitor" in the Developer Menu.

Debugging Application State

Reactotron is an open-source desktop app that allows you to inspect Redux or MobX-State-Tree application state as well as view custom logs, run custom commands such as resetting state, store and restore state snapshots, and other helpful debugging features for React Native apps.

You can view installation instructions in the README. If you're using Expo, here is an article detailing how to install on Expo.

Native Debugging

Accessing console logs

You can display the console logs for an iOS or Android app by using the following commands in a terminal while the app is running:

$ npx react-native log-ios
$ npx react-native log-android

You may also access these through Debug → Open System Log... in the iOS Simulator or by running adb logcat *:S ReactNative:V ReactNativeJS:V in a terminal while an Android app is running on a device or emulator.

If you're using Create React Native App or Expo CLI, console logs already appear in the same terminal output as the bundler.

Debugging on a device with Chrome Developer Tools

If you're using Create React Native App or Expo CLI, this is configured for you already.

On iOS devices, open the file RCTWebSocketExecutor.m and change "localhost" to the IP address of your computer, then select "Debug JS Remotely" from the Developer Menu.

On Android 5.0+ devices connected via USB, you can use the adb command line tool to setup port forwarding from the device to your computer:

adb reverse tcp:8081 tcp:8081

Alternatively, select "Dev Settings" from the Developer Menu, then update the "Debug server host for device" setting to match the IP address of your computer.

If you run into any issues, it may be possible that one of your Chrome extensions is interacting in unexpected ways with the debugger. Try disabling all of your extensions and re-enabling them one-by-one until you find the problematic extension.

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.

Edit this page
Last updated on
- + diff --git a/docs/devsettings.html b/docs/devsettings.html index e8c0e7db689..c13d5a820ce 100644 --- a/docs/devsettings.html +++ b/docs/devsettings.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

DevSettings

The DevSettings module exposes methods for customizing settings for developers in development.

Reference

Methods

addMenuItem()

static addMenuItem(title: string, handler: function)

Add a custom menu item to the developer menu:

DevSettings.addMenuItem('Show Secret Dev Screen', () => {
Alert.alert('Showing secret dev screen!');
});

reload()

static reload()

Reload the application. Can be invoked directly or on user interaction:

<Button title="Reload" onPress={() => DevSettings.reload()} />
Edit this page
Last updated on
- + diff --git a/docs/devsettings/index.html b/docs/devsettings/index.html index e8c0e7db689..c13d5a820ce 100644 --- a/docs/devsettings/index.html +++ b/docs/devsettings/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

DevSettings

The DevSettings module exposes methods for customizing settings for developers in development.

Reference

Methods

addMenuItem()

static addMenuItem(title: string, handler: function)

Add a custom menu item to the developer menu:

DevSettings.addMenuItem('Show Secret Dev Screen', () => {
Alert.alert('Showing secret dev screen!');
});

reload()

static reload()

Reload the application. Can be invoked directly or on user interaction:

<Button title="Reload" onPress={() => DevSettings.reload()} />
Edit this page
Last updated on
- + diff --git a/docs/dimensions.html b/docs/dimensions.html index 1026ac2d759..4c5024966bb 100644 --- a/docs/dimensions.html +++ b/docs/dimensions.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Dimensions

useWindowDimensions is the preferred API for React components. Unlike Dimensions, it updates as the window's dimensions update. This works nicely with the React paradigm.

import { Dimensions } from 'react-native';

You can get the application window's width and height using the following code:

const windowWidth = Dimensions.get('window').width;
const windowHeight = Dimensions.get('window').height;

Although dimensions are available immediately, they may change (e.g due to device rotation, foldable devices etc) so any rendering logic or styles that depend on these constants should try to call this function on every render, rather than caching the value (for example, using inline styles rather than setting a value in a StyleSheet).

If you are targeting foldable devices or devices which can change the screen size or app window size, you can use the event listener available in the Dimensions module as shown in the below example.

Example

Reference

Methods

addEventListener()

static addEventListener(type, handler)

Add an event handler. Supported events:

  • change: Fires when a property within the Dimensions object changes. The argument to the event handler is an object with window and screen properties whose values are the same as the return values of Dimensions.get('window') and Dimensions.get('screen'), respectively.
    • window - Size of the visible Application window
    • screen - Size of the device's screen

get()

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.

Example: const {height, width} = Dimensions.get('window');

Parameters:

NameTypeRequiredDescription
dimstringYesName of dimension as defined when calling set. @returns {Object?} Value for the dimension.

For Android the window dimension will exclude the size used by the status bar (if not translucent) and bottom navigation bar

removeEventListener()

static removeEventListener(type, handler)

Remove an event handler.

set()

static set(dims)

This should only be called from native code by sending the didUpdateDimensions event.

Parameters:

NameTypeRequiredDescription
dimsobjectYesstring-keyed object of dimensions to set
Edit this page
Last updated on
- + diff --git a/docs/dimensions/index.html b/docs/dimensions/index.html index 1026ac2d759..4c5024966bb 100644 --- a/docs/dimensions/index.html +++ b/docs/dimensions/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Dimensions

useWindowDimensions is the preferred API for React components. Unlike Dimensions, it updates as the window's dimensions update. This works nicely with the React paradigm.

import { Dimensions } from 'react-native';

You can get the application window's width and height using the following code:

const windowWidth = Dimensions.get('window').width;
const windowHeight = Dimensions.get('window').height;

Although dimensions are available immediately, they may change (e.g due to device rotation, foldable devices etc) so any rendering logic or styles that depend on these constants should try to call this function on every render, rather than caching the value (for example, using inline styles rather than setting a value in a StyleSheet).

If you are targeting foldable devices or devices which can change the screen size or app window size, you can use the event listener available in the Dimensions module as shown in the below example.

Example

Reference

Methods

addEventListener()

static addEventListener(type, handler)

Add an event handler. Supported events:

  • change: Fires when a property within the Dimensions object changes. The argument to the event handler is an object with window and screen properties whose values are the same as the return values of Dimensions.get('window') and Dimensions.get('screen'), respectively.
    • window - Size of the visible Application window
    • screen - Size of the device's screen

get()

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.

Example: const {height, width} = Dimensions.get('window');

Parameters:

NameTypeRequiredDescription
dimstringYesName of dimension as defined when calling set. @returns {Object?} Value for the dimension.

For Android the window dimension will exclude the size used by the status bar (if not translucent) and bottom navigation bar

removeEventListener()

static removeEventListener(type, handler)

Remove an event handler.

set()

static set(dims)

This should only be called from native code by sending the didUpdateDimensions event.

Parameters:

NameTypeRequiredDescription
dimsobjectYesstring-keyed object of dimensions to set
Edit this page
Last updated on
- + diff --git a/docs/direct-manipulation.html b/docs/direct-manipulation.html index e13b628e2f2..5304748eb34 100644 --- a/docs/direct-manipulation.html +++ b/docs/direct-manipulation.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
render() {
return (
<TouchableOpacity onPress={() => this.setState({myButtonOpacity: 0.5})}
onPressOut={() => this.setState({myButtonOpacity: 1})}>
<View style={[styles.button, {opacity: this.state.myButtonOpacity}]}>
<Text>Press me!</Text>
</View>
</TouchableOpacity>
)
}

This is computationally intensive compared to the original example - React needs to re-render the component hierarchy each time the opacity changes, even though other properties of the view and its children haven't changed. Usually this overhead isn't a concern but when performing continuous animations and responding to gestures, judiciously optimizing your components can improve your animations' fidelity.

If you look at the implementation of setNativeProps in NativeMethodsMixin you will notice that it is a wrapper around RCTUIManager.updateView - this is the exact same function call that results from re-rendering - see receiveComponent in ReactNativeBaseComponent.

Composite components and setNativeProps

Composite components are not backed by a native view, so you cannot call setNativeProps on them. Consider this example:

If you run this you will immediately see this error: Touchable child must either be native or forward setNativeProps to a native component. This occurs because MyButton isn't directly backed by a native view whose opacity should be set. You can think about it like this: if you define a component with createReactClass you would not expect to be able to set a style prop on it and have that work - you would need to pass the style prop down to a child, unless you are wrapping a native component. Similarly, we are going to forward setNativeProps to a native-backed child component.

Forward setNativeProps to a child

All we need to do is provide a setNativeProps method on our component that calls setNativeProps on the appropriate child with the given arguments.

You can now use MyButton inside of TouchableOpacity! A sidenote for clarity: we used the ref callback syntax here, rather than the traditional string-based ref.

You may have noticed that we passed all of the props down to the child view using {...this.props}. The reason for this is that TouchableOpacity is actually a composite component, and so in addition to depending on setNativeProps on its child, it also requires that the child perform touch handling. To do this, it passes on various props that call back to the TouchableOpacity component. TouchableHighlight, in contrast, is backed by a native view and only requires that we implement setNativeProps.

setNativeProps to clear TextInput value

Another very common use case of setNativeProps is to clear the value of a TextInput. The controlled prop of TextInput can sometimes drop characters when the bufferDelay is low and the user types very quickly. Some developers prefer to skip this prop entirely and instead use setNativeProps to directly manipulate the TextInput value when necessary. For example, the following code demonstrates clearing the input when you tap a button:

Avoiding conflicts with the render function

If you update a property that is also managed by the render function, you might end up with some unpredictable and confusing bugs because anytime the component re-renders and that property changes, whatever value was previously set from setNativeProps will be completely ignored and overridden.

setNativeProps & shouldComponentUpdate

By intelligently applying shouldComponentUpdate you can avoid the unnecessary overhead involved in reconciling unchanged component subtrees, to the point where it may be performant enough to use setState instead of setNativeProps.

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:

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 and you don't need pageX and pageY, 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:

measureLayout(relativeToNativeNode, onSuccess, onFail)

Like measure(), but measures the view relative to 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 findNodeHandle(component).

import { findNodeHandle } from 'react-native';

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().

Edit this page
Last updated on
- + diff --git a/docs/direct-manipulation/index.html b/docs/direct-manipulation/index.html index e13b628e2f2..5304748eb34 100644 --- a/docs/direct-manipulation/index.html +++ b/docs/direct-manipulation/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
render() {
return (
<TouchableOpacity onPress={() => this.setState({myButtonOpacity: 0.5})}
onPressOut={() => this.setState({myButtonOpacity: 1})}>
<View style={[styles.button, {opacity: this.state.myButtonOpacity}]}>
<Text>Press me!</Text>
</View>
</TouchableOpacity>
)
}

This is computationally intensive compared to the original example - React needs to re-render the component hierarchy each time the opacity changes, even though other properties of the view and its children haven't changed. Usually this overhead isn't a concern but when performing continuous animations and responding to gestures, judiciously optimizing your components can improve your animations' fidelity.

If you look at the implementation of setNativeProps in NativeMethodsMixin you will notice that it is a wrapper around RCTUIManager.updateView - this is the exact same function call that results from re-rendering - see receiveComponent in ReactNativeBaseComponent.

Composite components and setNativeProps

Composite components are not backed by a native view, so you cannot call setNativeProps on them. Consider this example:

If you run this you will immediately see this error: Touchable child must either be native or forward setNativeProps to a native component. This occurs because MyButton isn't directly backed by a native view whose opacity should be set. You can think about it like this: if you define a component with createReactClass you would not expect to be able to set a style prop on it and have that work - you would need to pass the style prop down to a child, unless you are wrapping a native component. Similarly, we are going to forward setNativeProps to a native-backed child component.

Forward setNativeProps to a child

All we need to do is provide a setNativeProps method on our component that calls setNativeProps on the appropriate child with the given arguments.

You can now use MyButton inside of TouchableOpacity! A sidenote for clarity: we used the ref callback syntax here, rather than the traditional string-based ref.

You may have noticed that we passed all of the props down to the child view using {...this.props}. The reason for this is that TouchableOpacity is actually a composite component, and so in addition to depending on setNativeProps on its child, it also requires that the child perform touch handling. To do this, it passes on various props that call back to the TouchableOpacity component. TouchableHighlight, in contrast, is backed by a native view and only requires that we implement setNativeProps.

setNativeProps to clear TextInput value

Another very common use case of setNativeProps is to clear the value of a TextInput. The controlled prop of TextInput can sometimes drop characters when the bufferDelay is low and the user types very quickly. Some developers prefer to skip this prop entirely and instead use setNativeProps to directly manipulate the TextInput value when necessary. For example, the following code demonstrates clearing the input when you tap a button:

Avoiding conflicts with the render function

If you update a property that is also managed by the render function, you might end up with some unpredictable and confusing bugs because anytime the component re-renders and that property changes, whatever value was previously set from setNativeProps will be completely ignored and overridden.

setNativeProps & shouldComponentUpdate

By intelligently applying shouldComponentUpdate you can avoid the unnecessary overhead involved in reconciling unchanged component subtrees, to the point where it may be performant enough to use setState instead of setNativeProps.

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:

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 and you don't need pageX and pageY, 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:

measureLayout(relativeToNativeNode, onSuccess, onFail)

Like measure(), but measures the view relative to 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 findNodeHandle(component).

import { findNodeHandle } from 'react-native';

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().

Edit this page
Last updated on
- + diff --git a/docs/drawerlayoutandroid.html b/docs/drawerlayoutandroid.html index 9ee836248c0..e0009929033 100644 --- a/docs/drawerlayoutandroid.html +++ b/docs/drawerlayoutandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

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 side of the window specified by the drawerPosition prop and its width can be set by the drawerWidth prop.

Example

Reference

Props

Inherits View Props.

drawerBackgroundColor

Specifies the background color of the drawer. The default value is white. If you want to set the opacity of the drawer, use rgba. Example:

return (
<DrawerLayoutAndroid drawerBackgroundColor="rgba(0,0,0,0.5)" />
);
TypeRequired
colorNo

drawerLockMode

Specifies the lock mode of the drawer. The drawer can be locked in 3 states:

  • unlocked (default), meaning that the drawer will respond (open/close) to touch gestures.
  • locked-closed, meaning that the drawer will stay closed and not respond to gestures.
  • locked-open, meaning that the drawer will stay opened and not respond to gestures. The drawer may still be opened and closed programmatically (openDrawer/closeDrawer).
TypeRequired
enum('unlocked', 'locked-closed', 'locked-open')No

drawerPosition

Specifies the side of the screen from which the drawer will slide in. By default it is set to left.

TypeRequired
enum('left', 'right')No

drawerWidth

Specifies the width of the drawer, more precisely the width of the view that be pulled in from the edge of the window.

TypeRequired
numberNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

  • 'none' (the default), drags do not dismiss the keyboard.
  • 'on-drag', the keyboard is dismissed when a drag begins.
TypeRequired
enum('none', 'on-drag')No

onDrawerClose

Function called whenever the navigation view has been closed.

TypeRequired
functionNo

onDrawerOpen

Function called whenever the navigation view has been opened.

TypeRequired
functionNo

onDrawerSlide

Function called whenever there is an interaction with the navigation view.

TypeRequired
functionNo

onDrawerStateChanged

Function called when the drawer state has changed. The drawer can be in 3 states:

  • idle, meaning there is no interaction with the navigation view happening at the time
  • dragging, meaning there is currently an interaction with the navigation view
  • settling, meaning that there was an interaction with the navigation view, and the navigation view is now finishing its closing or opening animation
TypeRequired
functionNo

renderNavigationView

The navigation view that will be rendered to the side of the screen and can be pulled in.

TypeRequired
functionYes

statusBarBackgroundColor

Make the drawer take the entire screen and draw the background of the status bar to allow it to open over the status bar. It will only have an effect on API 21+.

TypeRequired
colorNo

Methods

closeDrawer()

closeDrawer();

Closes the drawer.

openDrawer()

openDrawer();

Opens the drawer.

Edit this page
Last updated on
- + diff --git a/docs/drawerlayoutandroid/index.html b/docs/drawerlayoutandroid/index.html index 9ee836248c0..e0009929033 100644 --- a/docs/drawerlayoutandroid/index.html +++ b/docs/drawerlayoutandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

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 side of the window specified by the drawerPosition prop and its width can be set by the drawerWidth prop.

Example

Reference

Props

Inherits View Props.

drawerBackgroundColor

Specifies the background color of the drawer. The default value is white. If you want to set the opacity of the drawer, use rgba. Example:

return (
<DrawerLayoutAndroid drawerBackgroundColor="rgba(0,0,0,0.5)" />
);
TypeRequired
colorNo

drawerLockMode

Specifies the lock mode of the drawer. The drawer can be locked in 3 states:

  • unlocked (default), meaning that the drawer will respond (open/close) to touch gestures.
  • locked-closed, meaning that the drawer will stay closed and not respond to gestures.
  • locked-open, meaning that the drawer will stay opened and not respond to gestures. The drawer may still be opened and closed programmatically (openDrawer/closeDrawer).
TypeRequired
enum('unlocked', 'locked-closed', 'locked-open')No

drawerPosition

Specifies the side of the screen from which the drawer will slide in. By default it is set to left.

TypeRequired
enum('left', 'right')No

drawerWidth

Specifies the width of the drawer, more precisely the width of the view that be pulled in from the edge of the window.

TypeRequired
numberNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

  • 'none' (the default), drags do not dismiss the keyboard.
  • 'on-drag', the keyboard is dismissed when a drag begins.
TypeRequired
enum('none', 'on-drag')No

onDrawerClose

Function called whenever the navigation view has been closed.

TypeRequired
functionNo

onDrawerOpen

Function called whenever the navigation view has been opened.

TypeRequired
functionNo

onDrawerSlide

Function called whenever there is an interaction with the navigation view.

TypeRequired
functionNo

onDrawerStateChanged

Function called when the drawer state has changed. The drawer can be in 3 states:

  • idle, meaning there is no interaction with the navigation view happening at the time
  • dragging, meaning there is currently an interaction with the navigation view
  • settling, meaning that there was an interaction with the navigation view, and the navigation view is now finishing its closing or opening animation
TypeRequired
functionNo

renderNavigationView

The navigation view that will be rendered to the side of the screen and can be pulled in.

TypeRequired
functionYes

statusBarBackgroundColor

Make the drawer take the entire screen and draw the background of the status bar to allow it to open over the status bar. It will only have an effect on API 21+.

TypeRequired
colorNo

Methods

closeDrawer()

closeDrawer();

Closes the drawer.

openDrawer()

openDrawer();

Opens the drawer.

Edit this page
Last updated on
- + diff --git a/docs/dynamiccolorios.html b/docs/dynamiccolorios.html index a23f3d3570b..833e5aa5612 100644 --- a/docs/dynamiccolorios.html +++ b/docs/dynamiccolorios.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
const customDynamicTextColor = DynamicColorIOS({
dark: 'lightskyblue',
light: 'midnightblue'
});
Edit this page
Last updated on
- + diff --git a/docs/dynamiccolorios/index.html b/docs/dynamiccolorios/index.html index a23f3d3570b..833e5aa5612 100644 --- a/docs/dynamiccolorios/index.html +++ b/docs/dynamiccolorios/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
const customDynamicTextColor = DynamicColorIOS({
dark: 'lightskyblue',
light: 'midnightblue'
});
Edit this page
Last updated on
- + diff --git a/docs/easing.html b/docs/easing.html index 17e680dd0d0..21128ecc0c5 100644 --- a/docs/easing.html +++ b/docs/easing.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Easing

The Easing module implements common easing functions. This module is used by Animated.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 following methods:

  • back provides a basic animation where the object goes slightly back before moving forward
  • bounce provides a bouncing animation
  • ease provides a basic inertial animation
  • elastic provides a basic spring interaction

Standard functions

Three standard easing functions are provided:

The poly function can be used to implement quartic, quintic, and other higher power functions.

Additional functions

Additional mathematical functions are provided by the following methods:

  • bezier provides a cubic bezier curve
  • circle provides a circular function
  • sin provides a sinusoidal function
  • exp provides an exponential function

The following helpers are used to modify other easing functions.

  • in runs an easing function forwards
  • inOut makes any easing function symmetrical
  • out runs an easing function backwards

Example

Reference

Methods

step0()

static step0(n)

A stepping function, returns 1 for any positive value of n.

step1()

static step1(n)

A stepping function, returns 1 if n is greater than or equal to 1.

linear()

static linear(t)

A linear function, f(t) = t. Position correlates to elapsed time one to one.

http://cubic-bezier.com/#0,0,1,1

ease()

static ease(t)

A basic inertial interaction, similar to an object slowly accelerating to speed.

http://cubic-bezier.com/#.42,0,1,1

quad()

static quad(t)

A quadratic function, f(t) = t * t. Position equals the square of elapsed time.

http://easings.net/#easeInQuad

cubic()

static cubic(t)

A cubic function, f(t) = t * t * t. Position equals the cube of elapsed time.

http://easings.net/#easeInCubic

poly()

static poly(n)

A power function. Position is equal to the Nth power of elapsed time.

n = 4: http://easings.net/#easeInQuart n = 5: http://easings.net/#easeInQuint

sin()

static sin(t)

A sinusoidal function.

http://easings.net/#easeInSine

circle()

static circle(t)

A circular function.

http://easings.net/#easeInCirc

exp()

static exp(t)

An exponential function.

http://easings.net/#easeInExpo

elastic()

static elastic(bounciness)

A basic elastic interaction, similar to a spring oscillating back and forth.

Default bounciness is 1, which overshoots a little bit once. 0 bounciness doesn't overshoot at all, and bounciness of N > 1 will overshoot about N times.

http://easings.net/#easeInElastic

back()

static back(s)

Use with Animated.parallel() to create a basic effect where the object animates back slightly as the animation starts.

bounce()

static bounce(t)

Provides a basic bouncing effect.

http://easings.net/#easeInBounce

bezier()

static bezier(x1, y1, x2, y2)

Provides a cubic bezier curve, equivalent to CSS Transitions' transition-timing-function.

A useful tool to visualize cubic bezier curves can be found at http://cubic-bezier.com/

in()

static in(easing);

Runs an easing function forwards.

out()

static out(easing)

Runs an easing function backwards.

inOut()

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.

Edit this page
Last updated on
- + diff --git a/docs/easing/index.html b/docs/easing/index.html index 17e680dd0d0..21128ecc0c5 100644 --- a/docs/easing/index.html +++ b/docs/easing/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Easing

The Easing module implements common easing functions. This module is used by Animated.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 following methods:

  • back provides a basic animation where the object goes slightly back before moving forward
  • bounce provides a bouncing animation
  • ease provides a basic inertial animation
  • elastic provides a basic spring interaction

Standard functions

Three standard easing functions are provided:

The poly function can be used to implement quartic, quintic, and other higher power functions.

Additional functions

Additional mathematical functions are provided by the following methods:

  • bezier provides a cubic bezier curve
  • circle provides a circular function
  • sin provides a sinusoidal function
  • exp provides an exponential function

The following helpers are used to modify other easing functions.

  • in runs an easing function forwards
  • inOut makes any easing function symmetrical
  • out runs an easing function backwards

Example

Reference

Methods

step0()

static step0(n)

A stepping function, returns 1 for any positive value of n.

step1()

static step1(n)

A stepping function, returns 1 if n is greater than or equal to 1.

linear()

static linear(t)

A linear function, f(t) = t. Position correlates to elapsed time one to one.

http://cubic-bezier.com/#0,0,1,1

ease()

static ease(t)

A basic inertial interaction, similar to an object slowly accelerating to speed.

http://cubic-bezier.com/#.42,0,1,1

quad()

static quad(t)

A quadratic function, f(t) = t * t. Position equals the square of elapsed time.

http://easings.net/#easeInQuad

cubic()

static cubic(t)

A cubic function, f(t) = t * t * t. Position equals the cube of elapsed time.

http://easings.net/#easeInCubic

poly()

static poly(n)

A power function. Position is equal to the Nth power of elapsed time.

n = 4: http://easings.net/#easeInQuart n = 5: http://easings.net/#easeInQuint

sin()

static sin(t)

A sinusoidal function.

http://easings.net/#easeInSine

circle()

static circle(t)

A circular function.

http://easings.net/#easeInCirc

exp()

static exp(t)

An exponential function.

http://easings.net/#easeInExpo

elastic()

static elastic(bounciness)

A basic elastic interaction, similar to a spring oscillating back and forth.

Default bounciness is 1, which overshoots a little bit once. 0 bounciness doesn't overshoot at all, and bounciness of N > 1 will overshoot about N times.

http://easings.net/#easeInElastic

back()

static back(s)

Use with Animated.parallel() to create a basic effect where the object animates back slightly as the animation starts.

bounce()

static bounce(t)

Provides a basic bouncing effect.

http://easings.net/#easeInBounce

bezier()

static bezier(x1, y1, x2, y2)

Provides a cubic bezier curve, equivalent to CSS Transitions' transition-timing-function.

A useful tool to visualize cubic bezier curves can be found at http://cubic-bezier.com/

in()

static in(easing);

Runs an easing function forwards.

out()

static out(easing)

Runs an easing function backwards.

inOut()

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.

Edit this page
Last updated on
- + diff --git a/docs/environment-setup.html b/docs/environment-setup.html index 453bff738e4..4d74c66d071 100644 --- a/docs/environment-setup.html +++ b/docs/environment-setup.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
cd AwesomeProject
npm start # you can also use: expo start

This will start a development server for you.

Running your React Native application

Install the Expo client app on your iOS or Android phone and connect to the same wireless network as your computer. On Android, use the Expo app to scan the QR code from your terminal to open your project. On iOS, use the built-in QR code scanner of the Camera app.

Modifying your app

Now that you have successfully run the app, let's modify it. Open App.js in your text editor of choice and edit some lines. The application should reload automatically once you save your changes.

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

Expo also has docs you can reference if you have questions specific to the tool. You can also ask for help at Expo forums.

These tools help you get started quickly, but before committing to building your app with Expo CLI, read about the limitations.

If you have a problem with Expo, before creating a new issue, please see if there's an existing issue about it:

If you're curious to learn more about React Native, check out the Introduction to React Native.

Running your app on a simulator or virtual device

Expo CLI allows you to run your React Native app on a physical device without setting up a development environment. If you want to run your app on the iOS Simulator or an Android Virtual Device, please refer to the instructions for "React Native CLI Quickstart" to learn how to install Xcode or set up your Android development environment.

Once you've set these up, you can launch your app on an Android Virtual Device by running npm run android, or on the iOS Simulator by running npm run ios (macOS only).

Caveats

Because you don't build any native code when using Expo to create a project, it's not possible to include custom native modules beyond the React Native APIs and components that are available in the Expo client app.

If you know that you'll eventually need to include your own native code, Expo is still a good way to get started. In that case you'll need to "eject" eventually to create your own native builds. If you do eject, the "React Native CLI Quickstart" instructions will be required to continue working on your project.

Expo CLI configures your project to use the most recent React Native version that is supported by the Expo client app. The Expo client app usually gains support for a given React Native version about a week after the React Native version is released as stable. You can check this document to find out what versions are supported.

If you're integrating React Native into an existing project, you'll want to skip Expo CLI and go directly to setting up the native build environment. Select "React Native CLI Quickstart" above for instructions on configuring a native build environment for React Native.

Edit this page
Last updated on
- + diff --git a/docs/environment-setup/index.html b/docs/environment-setup/index.html index 453bff738e4..4d74c66d071 100644 --- a/docs/environment-setup/index.html +++ b/docs/environment-setup/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
cd AwesomeProject
npm start # you can also use: expo start

This will start a development server for you.

Running your React Native application

Install the Expo client app on your iOS or Android phone and connect to the same wireless network as your computer. On Android, use the Expo app to scan the QR code from your terminal to open your project. On iOS, use the built-in QR code scanner of the Camera app.

Modifying your app

Now that you have successfully run the app, let's modify it. Open App.js in your text editor of choice and edit some lines. The application should reload automatically once you save your changes.

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

Expo also has docs you can reference if you have questions specific to the tool. You can also ask for help at Expo forums.

These tools help you get started quickly, but before committing to building your app with Expo CLI, read about the limitations.

If you have a problem with Expo, before creating a new issue, please see if there's an existing issue about it:

If you're curious to learn more about React Native, check out the Introduction to React Native.

Running your app on a simulator or virtual device

Expo CLI allows you to run your React Native app on a physical device without setting up a development environment. If you want to run your app on the iOS Simulator or an Android Virtual Device, please refer to the instructions for "React Native CLI Quickstart" to learn how to install Xcode or set up your Android development environment.

Once you've set these up, you can launch your app on an Android Virtual Device by running npm run android, or on the iOS Simulator by running npm run ios (macOS only).

Caveats

Because you don't build any native code when using Expo to create a project, it's not possible to include custom native modules beyond the React Native APIs and components that are available in the Expo client app.

If you know that you'll eventually need to include your own native code, Expo is still a good way to get started. In that case you'll need to "eject" eventually to create your own native builds. If you do eject, the "React Native CLI Quickstart" instructions will be required to continue working on your project.

Expo CLI configures your project to use the most recent React Native version that is supported by the Expo client app. The Expo client app usually gains support for a given React Native version about a week after the React Native version is released as stable. You can check this document to find out what versions are supported.

If you're integrating React Native into an existing project, you'll want to skip Expo CLI and go directly to setting up the native build environment. Select "React Native CLI Quickstart" above for instructions on configuring a native build environment for React Native.

Edit this page
Last updated on
- + diff --git a/docs/fast-refresh.html b/docs/fast-refresh.html index 0fd84d764a9..5f5beda6a53 100644 --- a/docs/fast-refresh.html +++ b/docs/fast-refresh.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Fast Refresh

Fast Refresh is a React Native feature that allows you to get near-instant feedback for changes in your React components. Fast Refresh is enabled by default, and you can toggle "Enable Fast Refresh" in the React Native developer menu. With Fast Refresh enabled, most edits should be visible within a second or two.

How It Works

  • If you edit a module that only exports React component(s), Fast Refresh will update the code only for that module, and re-render your component. You can edit anything in that file, including styles, rendering logic, event handlers, or effects.
  • If you edit a module with exports that aren't React components, Fast Refresh will re-run both that module, and the other modules importing it. So if both Button.js and Modal.js import Theme.js, editing Theme.js will update both components.
  • Finally, if you edit a file that's imported by modules outside of the React tree, Fast Refresh will fall back to doing a full reload. You might have a file which renders a React component but also exports a value that is imported by a non-React component. For example, maybe your component also exports a constant, and a non-React utility module imports it. In that case, consider migrating the query to a separate file and importing it into both files. This will re-enable Fast Refresh to work. Other cases can usually be solved in a similar way.

Error Resilience

If you make a syntax error during a Fast Refresh session, you can fix it and save the file again. The redbox will disappear. Modules with syntax errors are prevented from running, so you won't need to reload the app.

If you make a runtime error during the module initialization (for example, typing Style.create instead of StyleSheet.create), the Fast Refresh session will continue once you fix the error. The redbox will disappear, and the module will be updated.

If you make a mistake that leads to a runtime error inside your component, the Fast Refresh session will also continue after you fix the error. In that case, React will remount your application using the updated code.

If you have error boundaries in your app (which is a good idea for graceful failures in production), they will retry rendering on the next edit after a redbox. In that sense, having an error boundary can prevent you from always getting kicked out to the root app screen. However, keep in mind that error boundaries shouldn't be too granular. They are used by React in production, and should always be designed intentionally.

Limitations

Fast Refresh tries to preserve local React state in the component you're editing, but only if it's safe to do so. Here's a few reasons why you might see local state being reset on every edit to a file:

  • Local state is not preserved for class components (only function components and Hooks preserve state).
  • The module you're editing might have other exports in addition to a React component.
  • Sometimes, a module would export the result of calling higher-order component like createNavigationContainer(MyScreen). If the returned component is a class, state will be reset.

In the longer term, as more of your codebase moves to function components and Hooks, you can expect state to be preserved in more cases.

Tips

  • Fast Refresh preserves React local state in function components (and Hooks) by default.
  • Sometimes you might want to force the state to be reset, and a component to be remounted. For example, this can be handy if you're tweaking an animation that only happens on mount. To do this, you can add // @refresh reset anywhere in the file you're editing. This directive is local to the file, and instructs Fast Refresh to remount components defined in that file on every edit.

Fast Refresh and Hooks

When possible, Fast Refresh attempts to preserve the state of your component between edits. In particular, useState and useRef preserve their previous values as long as you don't change their arguments or the order of the Hook calls.

Hooks with dependencies—such as useEffect, useMemo, and useCallback—will always update during Fast Refresh. Their list of dependencies will be ignored while Fast Refresh is happening.

For example, when you edit useMemo(() => x * 2, [x]) to useMemo(() => x * 10, [x]), it will re-run even though x (the dependency) has not changed. If React didn't do that, your edit wouldn't reflect on the screen!

Sometimes, this can lead to unexpected results. For example, even a useEffect with an empty array of dependencies would still re-run once during Fast Refresh. However, writing code resilient to an occasional re-running of useEffect is a good practice even without Fast Refresh. This makes it easier for you to later introduce new dependencies to it.

Edit this page
Last updated on
- + diff --git a/docs/fast-refresh/index.html b/docs/fast-refresh/index.html index 0fd84d764a9..5f5beda6a53 100644 --- a/docs/fast-refresh/index.html +++ b/docs/fast-refresh/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Fast Refresh

Fast Refresh is a React Native feature that allows you to get near-instant feedback for changes in your React components. Fast Refresh is enabled by default, and you can toggle "Enable Fast Refresh" in the React Native developer menu. With Fast Refresh enabled, most edits should be visible within a second or two.

How It Works

  • If you edit a module that only exports React component(s), Fast Refresh will update the code only for that module, and re-render your component. You can edit anything in that file, including styles, rendering logic, event handlers, or effects.
  • If you edit a module with exports that aren't React components, Fast Refresh will re-run both that module, and the other modules importing it. So if both Button.js and Modal.js import Theme.js, editing Theme.js will update both components.
  • Finally, if you edit a file that's imported by modules outside of the React tree, Fast Refresh will fall back to doing a full reload. You might have a file which renders a React component but also exports a value that is imported by a non-React component. For example, maybe your component also exports a constant, and a non-React utility module imports it. In that case, consider migrating the query to a separate file and importing it into both files. This will re-enable Fast Refresh to work. Other cases can usually be solved in a similar way.

Error Resilience

If you make a syntax error during a Fast Refresh session, you can fix it and save the file again. The redbox will disappear. Modules with syntax errors are prevented from running, so you won't need to reload the app.

If you make a runtime error during the module initialization (for example, typing Style.create instead of StyleSheet.create), the Fast Refresh session will continue once you fix the error. The redbox will disappear, and the module will be updated.

If you make a mistake that leads to a runtime error inside your component, the Fast Refresh session will also continue after you fix the error. In that case, React will remount your application using the updated code.

If you have error boundaries in your app (which is a good idea for graceful failures in production), they will retry rendering on the next edit after a redbox. In that sense, having an error boundary can prevent you from always getting kicked out to the root app screen. However, keep in mind that error boundaries shouldn't be too granular. They are used by React in production, and should always be designed intentionally.

Limitations

Fast Refresh tries to preserve local React state in the component you're editing, but only if it's safe to do so. Here's a few reasons why you might see local state being reset on every edit to a file:

  • Local state is not preserved for class components (only function components and Hooks preserve state).
  • The module you're editing might have other exports in addition to a React component.
  • Sometimes, a module would export the result of calling higher-order component like createNavigationContainer(MyScreen). If the returned component is a class, state will be reset.

In the longer term, as more of your codebase moves to function components and Hooks, you can expect state to be preserved in more cases.

Tips

  • Fast Refresh preserves React local state in function components (and Hooks) by default.
  • Sometimes you might want to force the state to be reset, and a component to be remounted. For example, this can be handy if you're tweaking an animation that only happens on mount. To do this, you can add // @refresh reset anywhere in the file you're editing. This directive is local to the file, and instructs Fast Refresh to remount components defined in that file on every edit.

Fast Refresh and Hooks

When possible, Fast Refresh attempts to preserve the state of your component between edits. In particular, useState and useRef preserve their previous values as long as you don't change their arguments or the order of the Hook calls.

Hooks with dependencies—such as useEffect, useMemo, and useCallback—will always update during Fast Refresh. Their list of dependencies will be ignored while Fast Refresh is happening.

For example, when you edit useMemo(() => x * 2, [x]) to useMemo(() => x * 10, [x]), it will re-run even though x (the dependency) has not changed. If React didn't do that, your edit wouldn't reflect on the screen!

Sometimes, this can lead to unexpected results. For example, even a useEffect with an empty array of dependencies would still re-run once during Fast Refresh. However, writing code resilient to an occasional re-running of useEffect is a good practice even without Fast Refresh. This makes it easier for you to later introduce new dependencies to it.

Edit this page
Last updated on
- + diff --git a/docs/flatlist.html b/docs/flatlist.html index b8a42e91a05..415befbba2d 100644 --- a/docs/flatlist.html +++ b/docs/flatlist.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
this.viewabilityConfig = {
waitForInteraction: true,
viewAreaCoveragePercentThreshold: 95
}
}
<FlatList
viewabilityConfig={this.viewabilityConfig}
...

minimumViewTime

Minimum amount of time (in milliseconds) that an item must be physically viewable before the viewability callback will be fired. A high number means that scrolling through content without stopping will not mark the content as viewable.

viewAreaCoveragePercentThreshold

Percent of viewport that must be covered for a partially occluded item to count as "viewable", 0-100. Fully visible items are always considered viewable. A value of 0 means that a single pixel in the viewport makes the item viewable, and a value of 100 means that an item must be either entirely visible or cover the entire viewport to count as viewable.

itemVisiblePercentThreshold

Similar to viewAreaCoveragePercentThreshold, but considers the percent of the item that is visible, rather than the fraction of the viewable area it covers.

waitForInteraction

Nothing is considered viewable until the user scrolls or recordInteraction is called after render.

viewabilityConfigCallbackPairs

List of ViewabilityConfig/onViewableItemsChanged pairs. A specific onViewableItemsChanged will be called when its corresponding ViewabilityConfig's conditions are met. See ViewabilityHelper.js for flow type and further documentation.

TypeRequired
array of ViewabilityConfigCallbackPairNo

Methods

scrollToEnd()

scrollToEnd([params]);

Scrolls to the end of the content. May be janky without getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectNoSee below.

Valid params keys are:

scrollToIndex()

scrollToIndex(params);

Scrolls to the item at the specified index such that it is positioned in the viewable area such that viewPosition 0 places it at the top, 1 at the bottom, and 0.5 centered in the middle.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

scrollToItem()

scrollToItem(params);

Requires linear scan through data - use scrollToIndex instead if possible.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

scrollToOffset()

scrollToOffset(params);

Scroll to a specific content pixel offset in the list.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

recordInteraction()

recordInteraction();

Tells the list an interaction has occurred, 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()

flashScrollIndicators();

Displays the scroll indicators momentarily.

getNativeScrollRef()

getNativeScrollRef();

Provides a reference to the underlying scroll component

getScrollResponder()

getScrollResponder();

Provides a handle to the underlying scroll responder.

getScrollableNode()

getScrollableNode();

Provides a handle to the underlying scroll node.

Edit this page
Last updated on
- + diff --git a/docs/flatlist/index.html b/docs/flatlist/index.html index b8a42e91a05..415befbba2d 100644 --- a/docs/flatlist/index.html +++ b/docs/flatlist/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
this.viewabilityConfig = {
waitForInteraction: true,
viewAreaCoveragePercentThreshold: 95
}
}
<FlatList
viewabilityConfig={this.viewabilityConfig}
...

minimumViewTime

Minimum amount of time (in milliseconds) that an item must be physically viewable before the viewability callback will be fired. A high number means that scrolling through content without stopping will not mark the content as viewable.

viewAreaCoveragePercentThreshold

Percent of viewport that must be covered for a partially occluded item to count as "viewable", 0-100. Fully visible items are always considered viewable. A value of 0 means that a single pixel in the viewport makes the item viewable, and a value of 100 means that an item must be either entirely visible or cover the entire viewport to count as viewable.

itemVisiblePercentThreshold

Similar to viewAreaCoveragePercentThreshold, but considers the percent of the item that is visible, rather than the fraction of the viewable area it covers.

waitForInteraction

Nothing is considered viewable until the user scrolls or recordInteraction is called after render.

viewabilityConfigCallbackPairs

List of ViewabilityConfig/onViewableItemsChanged pairs. A specific onViewableItemsChanged will be called when its corresponding ViewabilityConfig's conditions are met. See ViewabilityHelper.js for flow type and further documentation.

TypeRequired
array of ViewabilityConfigCallbackPairNo

Methods

scrollToEnd()

scrollToEnd([params]);

Scrolls to the end of the content. May be janky without getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectNoSee below.

Valid params keys are:

scrollToIndex()

scrollToIndex(params);

Scrolls to the item at the specified index such that it is positioned in the viewable area such that viewPosition 0 places it at the top, 1 at the bottom, and 0.5 centered in the middle.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

scrollToItem()

scrollToItem(params);

Requires linear scan through data - use scrollToIndex instead if possible.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

scrollToOffset()

scrollToOffset(params);

Scroll to a specific content pixel offset in the list.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

recordInteraction()

recordInteraction();

Tells the list an interaction has occurred, 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()

flashScrollIndicators();

Displays the scroll indicators momentarily.

getNativeScrollRef()

getNativeScrollRef();

Provides a reference to the underlying scroll component

getScrollResponder()

getScrollResponder();

Provides a handle to the underlying scroll responder.

getScrollableNode()

getScrollableNode();

Provides a handle to the underlying scroll node.

Edit this page
Last updated on
- + diff --git a/docs/flexbox.html b/docs/flexbox.html index 666606db726..edd57f28e19 100644 --- a/docs/flexbox.html +++ b/docs/flexbox.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

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 flexDirection defaulting to column instead of row, alignContent defaulting to flex-start instead of stretch, flexShrink defaulting to 0 instead of 1, the flex parameter only supporting a single number.

Flex

flex will define how your items are going to “fill” over the available space along your main axis. Space will be divided according to each element's flex property.

In the following example, the red, yellow, and green views are all children in the container view that has flex: 1 set. The red view uses flex: 1 , the yellow view uses flex: 2, and the green view uses flex: 3 . 1+2+3 = 6, which means that the red view will get 1/6 of the space, the yellow 2/6 of the space, and the green 3/6 of the space.

Flex

Flex Direction

flexDirection controls the direction in which the children of a node are laid out. This is also referred to as the main axis. The cross axis is the axis perpendicular to the main axis, or the axis which the wrapping lines are laid out in.

  • row Align children from left to right. If wrapping is enabled, then the next line will start under the first item on the left of the container.

  • column (default value) Align children from top to bottom. If wrapping is enabled, then the next line will start to the right of the first item on the top of the container.

  • row-reverse Align children from right to left. If wrapping is enabled, then the next line will start under the first item on the right of the container.

  • column-reverse Align children from bottom to top. If wrapping is enabled, then the next line will start to the right of the first item on the bottom of the container.

You can learn more here.

Flex Direction

Layout Direction

Layout direction specifies the direction in which children and text in a hierarchy should be laid out. Layout direction also affects what edge start and end refer to. By default, React Native lays out with LTR layout direction. In this mode start refers to left and end refers to right.

  • LTR (default value) Text and children are laid out from left to right. Margin and padding applied to the start of an element are applied on the left side.

  • RTL Text and children are laid out from right to left. Margin and padding applied to the start of an element are applied on the right side.

Justify Content

justifyContent describes how to align children within the main axis of their container. For example, you can use this property to center a child horizontally within a container with flexDirection set to row or vertically within a container with flexDirection set to column.

  • flex-start(default value) Align children of a container to the start of the container's main axis.

  • flex-end Align children of a container to the end of the container's main axis.

  • center Align children of a container in the center of the container's main axis.

  • space-between Evenly space off children across the container's main axis, distributing the remaining space between the children.

  • space-around Evenly space off children across the container's main axis, distributing the remaining space around the children. Compared to space-between, using space-around will result in space being distributed to the beginning of the first child and end of the last child.

  • space-evenly Evenly distribute children within the alignment container along the main axis. The spacing between each pair of adjacent items, the main-start edge and the first item, and the main-end edge and the last item, are all exactly the same.

You can learn more here.

Justify Content

Align Items

alignItems describes how to align children along the cross axis of their container. Align items is very similar to justifyContent but instead of applying to the main axis, alignItems applies to the cross axis.

  • stretch (default value) Stretch children of a container to match the height of the container's cross axis.

  • flex-start Align children of a container to the start of the container's cross axis.

  • flex-end Align children of a container to the end of the container's cross axis.

  • center Align children of a container in the center of the container's cross axis.

  • baseline Align children of a container along a common baseline. Individual children can be set to be the reference baseline for their parents.

For stretch to have an effect, children must not have a fixed dimension along the secondary axis. In the following example, setting alignItems: stretch does nothing until the width: 50 is removed from the children.

You can learn more here.

Align Items

Align Self

alignSelf has the same options and effect as alignItems but instead of affecting the children within a container, you can apply this property to a single child to change its alignment within its parent. alignSelf overrides any option set by the parent with alignItems.

Align Self

Align Content

alignContent defines the distribution of lines along the cross-axis. This only has effect when items are wrapped to multiple lines using flexWrap.

  • flex-start (default value) Align wrapped lines to the start of the container's cross axis.

  • flex-end Align wrapped lines to the end of the container's cross axis.

  • stretch (default value when using Yoga on the web) Stretch wrapped lines to match the height of the container's cross axis.

  • center Align wrapped lines in the center of the container's cross axis.

  • space-between Evenly space wrapped lines across the container's main axis, distributing the remaining space between the lines.

  • space-around Evenly space wrapped lines across the container's main axis, distributing the remaining space around the lines. Compared to space-between, using space-around will result in space being distributed to the beginning of the first line and the end of the last line.

You can learn more here.

Align Content

Flex Wrap

The flexWrap property is set on containers and it controls what happens when children overflow the size of the container along the main axis. By default, children are forced into a single line (which can shrink elements). If wrapping is allowed, items are wrapped into multiple lines along the main axis if needed.

When wrapping lines, alignContent can be used to specify how the lines are placed in the container. Learn more here.

Flex Wrap

Flex Basis, Grow, and Shrink

  • flexBasis is an axis-independent way of providing the default size of an item along the main axis. Setting the flexBasis of a child is similar to setting the width of that child if its parent is a container with flexDirection: row or setting the height of a child if its parent is a container with flexDirection: column. The flexBasis of an item is the default size of that item, the size of the item before any flexGrow and flexShrink calculations are performed.

  • flexGrow describes how any space within a container should be distributed among its children along the main axis. After laying out its children, a container will distribute any remaining space according to the flex grow values specified by its children.

    flexGrow accepts any floating point value >= 0, with 0 being the default value. A container will distribute any remaining space among its children weighted by the children’s flexGrow values.

  • flexShrink describes how to shrink children along the main axis in the case in which the total size of the children overflows the size of the container on the main axis. flexShrink is very similar to flexGrow and can be thought of in the same way if any overflowing size is considered to be negative remaining space. These two properties also work well together by allowing children to grow and shrink as needed.

    flexShrink accepts any floating point value >= 0, with 0 being the default value (on the web, the default is 1). A container will shrink its children weighted by the children’s flexShrink values.

You can learn more here.

Width and Height

The width property specifies the width of an element's content area. Similarly, the height property specifies the height of an element's content area.

Both width and height can take the following values:

  • auto (default value) React Native calculates the width/height for the element based on its content, whether that is other children, text, or an image.

  • pixels Defines the width/height in absolute pixels. Depending on other styles set on the component, this may or may not be the final dimension of the node.

  • percentage Defines the width or height in percentage of its parent's width or height, respectively.

Absolute & Relative Layout

The position type of an element defines how it is positioned within its parent.

  • relative (default value) By default, an element is positioned relatively. This means an element is positioned according to the normal flow of the layout, and then offset relative to that position based on the values of top, right, bottom, and left. The offset does not affect the position of any sibling or parent elements.

  • absolute When positioned absolutely, an element doesn't take part in the normal layout flow. It is instead laid out independent of its siblings. The position is determined based on the top, right, bottom, and left values.

Absolute & Relative Layoutp

Going Deeper

Check out the interactive yoga playground that you can use to get a better understanding of flexbox.

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.

Additionally, you can see some examples from Wix Engineers.

Edit this page
Last updated on
- + diff --git a/docs/flexbox/index.html b/docs/flexbox/index.html index 666606db726..edd57f28e19 100644 --- a/docs/flexbox/index.html +++ b/docs/flexbox/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

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 flexDirection defaulting to column instead of row, alignContent defaulting to flex-start instead of stretch, flexShrink defaulting to 0 instead of 1, the flex parameter only supporting a single number.

Flex

flex will define how your items are going to “fill” over the available space along your main axis. Space will be divided according to each element's flex property.

In the following example, the red, yellow, and green views are all children in the container view that has flex: 1 set. The red view uses flex: 1 , the yellow view uses flex: 2, and the green view uses flex: 3 . 1+2+3 = 6, which means that the red view will get 1/6 of the space, the yellow 2/6 of the space, and the green 3/6 of the space.

Flex

Flex Direction

flexDirection controls the direction in which the children of a node are laid out. This is also referred to as the main axis. The cross axis is the axis perpendicular to the main axis, or the axis which the wrapping lines are laid out in.

  • row Align children from left to right. If wrapping is enabled, then the next line will start under the first item on the left of the container.

  • column (default value) Align children from top to bottom. If wrapping is enabled, then the next line will start to the right of the first item on the top of the container.

  • row-reverse Align children from right to left. If wrapping is enabled, then the next line will start under the first item on the right of the container.

  • column-reverse Align children from bottom to top. If wrapping is enabled, then the next line will start to the right of the first item on the bottom of the container.

You can learn more here.

Flex Direction

Layout Direction

Layout direction specifies the direction in which children and text in a hierarchy should be laid out. Layout direction also affects what edge start and end refer to. By default, React Native lays out with LTR layout direction. In this mode start refers to left and end refers to right.

  • LTR (default value) Text and children are laid out from left to right. Margin and padding applied to the start of an element are applied on the left side.

  • RTL Text and children are laid out from right to left. Margin and padding applied to the start of an element are applied on the right side.

Justify Content

justifyContent describes how to align children within the main axis of their container. For example, you can use this property to center a child horizontally within a container with flexDirection set to row or vertically within a container with flexDirection set to column.

  • flex-start(default value) Align children of a container to the start of the container's main axis.

  • flex-end Align children of a container to the end of the container's main axis.

  • center Align children of a container in the center of the container's main axis.

  • space-between Evenly space off children across the container's main axis, distributing the remaining space between the children.

  • space-around Evenly space off children across the container's main axis, distributing the remaining space around the children. Compared to space-between, using space-around will result in space being distributed to the beginning of the first child and end of the last child.

  • space-evenly Evenly distribute children within the alignment container along the main axis. The spacing between each pair of adjacent items, the main-start edge and the first item, and the main-end edge and the last item, are all exactly the same.

You can learn more here.

Justify Content

Align Items

alignItems describes how to align children along the cross axis of their container. Align items is very similar to justifyContent but instead of applying to the main axis, alignItems applies to the cross axis.

  • stretch (default value) Stretch children of a container to match the height of the container's cross axis.

  • flex-start Align children of a container to the start of the container's cross axis.

  • flex-end Align children of a container to the end of the container's cross axis.

  • center Align children of a container in the center of the container's cross axis.

  • baseline Align children of a container along a common baseline. Individual children can be set to be the reference baseline for their parents.

For stretch to have an effect, children must not have a fixed dimension along the secondary axis. In the following example, setting alignItems: stretch does nothing until the width: 50 is removed from the children.

You can learn more here.

Align Items

Align Self

alignSelf has the same options and effect as alignItems but instead of affecting the children within a container, you can apply this property to a single child to change its alignment within its parent. alignSelf overrides any option set by the parent with alignItems.

Align Self

Align Content

alignContent defines the distribution of lines along the cross-axis. This only has effect when items are wrapped to multiple lines using flexWrap.

  • flex-start (default value) Align wrapped lines to the start of the container's cross axis.

  • flex-end Align wrapped lines to the end of the container's cross axis.

  • stretch (default value when using Yoga on the web) Stretch wrapped lines to match the height of the container's cross axis.

  • center Align wrapped lines in the center of the container's cross axis.

  • space-between Evenly space wrapped lines across the container's main axis, distributing the remaining space between the lines.

  • space-around Evenly space wrapped lines across the container's main axis, distributing the remaining space around the lines. Compared to space-between, using space-around will result in space being distributed to the beginning of the first line and the end of the last line.

You can learn more here.

Align Content

Flex Wrap

The flexWrap property is set on containers and it controls what happens when children overflow the size of the container along the main axis. By default, children are forced into a single line (which can shrink elements). If wrapping is allowed, items are wrapped into multiple lines along the main axis if needed.

When wrapping lines, alignContent can be used to specify how the lines are placed in the container. Learn more here.

Flex Wrap

Flex Basis, Grow, and Shrink

  • flexBasis is an axis-independent way of providing the default size of an item along the main axis. Setting the flexBasis of a child is similar to setting the width of that child if its parent is a container with flexDirection: row or setting the height of a child if its parent is a container with flexDirection: column. The flexBasis of an item is the default size of that item, the size of the item before any flexGrow and flexShrink calculations are performed.

  • flexGrow describes how any space within a container should be distributed among its children along the main axis. After laying out its children, a container will distribute any remaining space according to the flex grow values specified by its children.

    flexGrow accepts any floating point value >= 0, with 0 being the default value. A container will distribute any remaining space among its children weighted by the children’s flexGrow values.

  • flexShrink describes how to shrink children along the main axis in the case in which the total size of the children overflows the size of the container on the main axis. flexShrink is very similar to flexGrow and can be thought of in the same way if any overflowing size is considered to be negative remaining space. These two properties also work well together by allowing children to grow and shrink as needed.

    flexShrink accepts any floating point value >= 0, with 0 being the default value (on the web, the default is 1). A container will shrink its children weighted by the children’s flexShrink values.

You can learn more here.

Width and Height

The width property specifies the width of an element's content area. Similarly, the height property specifies the height of an element's content area.

Both width and height can take the following values:

  • auto (default value) React Native calculates the width/height for the element based on its content, whether that is other children, text, or an image.

  • pixels Defines the width/height in absolute pixels. Depending on other styles set on the component, this may or may not be the final dimension of the node.

  • percentage Defines the width or height in percentage of its parent's width or height, respectively.

Absolute & Relative Layout

The position type of an element defines how it is positioned within its parent.

  • relative (default value) By default, an element is positioned relatively. This means an element is positioned according to the normal flow of the layout, and then offset relative to that position based on the values of top, right, bottom, and left. The offset does not affect the position of any sibling or parent elements.

  • absolute When positioned absolutely, an element doesn't take part in the normal layout flow. It is instead laid out independent of its siblings. The position is determined based on the top, right, bottom, and left values.

Absolute & Relative Layoutp

Going Deeper

Check out the interactive yoga playground that you can use to get a better understanding of flexbox.

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.

Additionally, you can see some examples from Wix Engineers.

Edit this page
Last updated on
- + diff --git a/docs/geolocation.html b/docs/geolocation.html index c3cd95ed60b..48961616436 100644 --- a/docs/geolocation.html +++ b/docs/geolocation.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 Geolocation

Deprecated. Use one of the community packages instead.

The Geolocation API extends the Geolocation web spec.

As a browser polyfill, this API is available through the navigator.geolocation global - you do not need to import it.

On Android, this uses the android.location API. This API is not recommended by Google because it is less accurate and slower than the recommended Google Location Services API. In order to use it with React Native, use the react-native-geolocation-service module.

Configuration and Permissions

iOS

You need to include the NSLocationWhenInUseUsageDescription key in Info.plist to enable geolocation when using the app. Geolocation is enabled by default when you create a project with react-native init.

In order to enable geolocation in the background, you need to include the 'NSLocationAlwaysUsageDescription' key in Info.plist and add location as a background mode in the 'Capabilities' tab in Xcode.

If you are using CocoaPods for React Native, make sure to include the RCTGeolocation sub-podspec.

Android

To request access to location, you need to add the following line to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Android API >= 18 Positions will also contain a mocked boolean to indicate if position was created from a mock provider.

Android API >= 23 Requires an additional step to check for, and request the ACCESS_FINE_LOCATION permission using the PermissionsAndroid API. Failure to do so may result in a hard crash.

Methods

Reference

Methods

setRNConfiguration()

geolocation.setRNConfiguration(config);

Sets configuration options that will be used in all location requests.

Parameters:

NameTypeRequiredDescription
configobjectYesSee below.

Supported options:

  • skipPermissionRequests (boolean, iOS-only) - Defaults to false. If true, you must request permissions before using Geolocation APIs.

requestAuthorization()

geolocation.requestAuthorization();

Request suitable Location permission based on the key configured on pList. If NSLocationAlwaysUsageDescription is set, it will request Always authorization, although if NSLocationWhenInUseUsageDescription is set, it will request InUse authorization.

getCurrentPosition()

geolocation.getCurrentPosition(
geo_success,
[geo_error],
[geo_options]
);

Invokes the success callback once with the latest location info.

Parameters:

NameTypeRequiredDescription
geo_successfunctionYesInvoked with latest location info.
geo_errorfunctionNoInvoked whenever an error is encountered.
geo_optionsobjectNoSee below.

Supported options:

  • timeout (ms) - Is a positive value representing the maximum length of time (in milliseconds) the device is allowed to take in order to return a position. Defaults to INFINITY.
  • maximumAge (ms) - Is a positive value indicating the maximum age in milliseconds of a possible cached position that is acceptable to return. If set to 0, it means that the device cannot use a cached position and must attempt to retrieve the real current position. If set to Infinity the device will always return a cached position regardless of its age. Defaults to INFINITY.
  • enableHighAccuracy (bool) - Is a boolean representing if to use GPS or not. If set to true, a GPS position will be requested. If set to false, a WIFI location will be requested.

watchPosition()

geolocation.watchPosition(success, [error], [options]);

Invokes the success callback whenever the location changes. Returns a watchId (number).

Parameters:

NameTypeRequiredDescription
successfunctionYesInvoked whenever the location changes.
errorfunctionNoInvoked whenever an error is encountered.
optionsobjectNoSee below.

Supported options:

  • timeout (ms) - Is a positive value representing the maximum length of time (in milliseconds) the device is allowed to take in order to return a position. Defaults to INFINITY.
  • maximumAge (ms) - Is a positive value indicating the maximum age in milliseconds of a possible cached position that is acceptable to return. If set to 0, it means that the device cannot use a cached position and must attempt to retrieve the real current position. If set to Infinity the device will always return a cached position regardless of its age. Defaults to INFINITY.
  • enableHighAccuracy (bool) - Is a boolean representing if to use GPS or not. If set to true, a GPS position will be requested. If set to false, a WIFI location will be requested.
  • distanceFilter (m) - The minimum distance from the previous location to exceed before returning a new location. Set to 0 to not filter locations. Defaults to 100m.
  • useSignificantChanges (bool) - Uses the battery-efficient native significant changes APIs to return locations. Locations will only be returned when the device detects a significant distance has been breached. Defaults to FALSE.

clearWatch()

geolocation.clearWatch(watchID);

Parameters:

NameTypeRequiredDescription
watchIDnumberYesId as returned by watchPosition().

stopObserving()

geolocation.stopObserving();

Stops observing for device location changes. In addition, it removes all listeners previously registered.

Notice that this method has only effect if the geolocation.watchPosition(successCallback, errorCallback) method was previously invoked.

Edit this page
Last updated on
- + diff --git a/docs/geolocation/index.html b/docs/geolocation/index.html index c3cd95ed60b..48961616436 100644 --- a/docs/geolocation/index.html +++ b/docs/geolocation/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 Geolocation

Deprecated. Use one of the community packages instead.

The Geolocation API extends the Geolocation web spec.

As a browser polyfill, this API is available through the navigator.geolocation global - you do not need to import it.

On Android, this uses the android.location API. This API is not recommended by Google because it is less accurate and slower than the recommended Google Location Services API. In order to use it with React Native, use the react-native-geolocation-service module.

Configuration and Permissions

iOS

You need to include the NSLocationWhenInUseUsageDescription key in Info.plist to enable geolocation when using the app. Geolocation is enabled by default when you create a project with react-native init.

In order to enable geolocation in the background, you need to include the 'NSLocationAlwaysUsageDescription' key in Info.plist and add location as a background mode in the 'Capabilities' tab in Xcode.

If you are using CocoaPods for React Native, make sure to include the RCTGeolocation sub-podspec.

Android

To request access to location, you need to add the following line to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Android API >= 18 Positions will also contain a mocked boolean to indicate if position was created from a mock provider.

Android API >= 23 Requires an additional step to check for, and request the ACCESS_FINE_LOCATION permission using the PermissionsAndroid API. Failure to do so may result in a hard crash.

Methods

Reference

Methods

setRNConfiguration()

geolocation.setRNConfiguration(config);

Sets configuration options that will be used in all location requests.

Parameters:

NameTypeRequiredDescription
configobjectYesSee below.

Supported options:

  • skipPermissionRequests (boolean, iOS-only) - Defaults to false. If true, you must request permissions before using Geolocation APIs.

requestAuthorization()

geolocation.requestAuthorization();

Request suitable Location permission based on the key configured on pList. If NSLocationAlwaysUsageDescription is set, it will request Always authorization, although if NSLocationWhenInUseUsageDescription is set, it will request InUse authorization.

getCurrentPosition()

geolocation.getCurrentPosition(
geo_success,
[geo_error],
[geo_options]
);

Invokes the success callback once with the latest location info.

Parameters:

NameTypeRequiredDescription
geo_successfunctionYesInvoked with latest location info.
geo_errorfunctionNoInvoked whenever an error is encountered.
geo_optionsobjectNoSee below.

Supported options:

  • timeout (ms) - Is a positive value representing the maximum length of time (in milliseconds) the device is allowed to take in order to return a position. Defaults to INFINITY.
  • maximumAge (ms) - Is a positive value indicating the maximum age in milliseconds of a possible cached position that is acceptable to return. If set to 0, it means that the device cannot use a cached position and must attempt to retrieve the real current position. If set to Infinity the device will always return a cached position regardless of its age. Defaults to INFINITY.
  • enableHighAccuracy (bool) - Is a boolean representing if to use GPS or not. If set to true, a GPS position will be requested. If set to false, a WIFI location will be requested.

watchPosition()

geolocation.watchPosition(success, [error], [options]);

Invokes the success callback whenever the location changes. Returns a watchId (number).

Parameters:

NameTypeRequiredDescription
successfunctionYesInvoked whenever the location changes.
errorfunctionNoInvoked whenever an error is encountered.
optionsobjectNoSee below.

Supported options:

  • timeout (ms) - Is a positive value representing the maximum length of time (in milliseconds) the device is allowed to take in order to return a position. Defaults to INFINITY.
  • maximumAge (ms) - Is a positive value indicating the maximum age in milliseconds of a possible cached position that is acceptable to return. If set to 0, it means that the device cannot use a cached position and must attempt to retrieve the real current position. If set to Infinity the device will always return a cached position regardless of its age. Defaults to INFINITY.
  • enableHighAccuracy (bool) - Is a boolean representing if to use GPS or not. If set to true, a GPS position will be requested. If set to false, a WIFI location will be requested.
  • distanceFilter (m) - The minimum distance from the previous location to exceed before returning a new location. Set to 0 to not filter locations. Defaults to 100m.
  • useSignificantChanges (bool) - Uses the battery-efficient native significant changes APIs to return locations. Locations will only be returned when the device detects a significant distance has been breached. Defaults to FALSE.

clearWatch()

geolocation.clearWatch(watchID);

Parameters:

NameTypeRequiredDescription
watchIDnumberYesId as returned by watchPosition().

stopObserving()

geolocation.stopObserving();

Stops observing for device location changes. In addition, it removes all listeners previously registered.

Notice that this method has only effect if the geolocation.watchPosition(successCallback, errorCallback) method was previously invoked.

Edit this page
Last updated on
- + diff --git a/docs/gesture-responder-system.html b/docs/gesture-responder-system.html index 81b32efdeac..fd62069a8ea 100644 --- a/docs/gesture-responder-system.html +++ b/docs/gesture-responder-system.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

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.

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 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 happening
  • View.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 finger
  • View.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 release
  • View.props.onResponderTerminate: (evt) => {} - The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, 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:

  • nativeEvent
    • changedTouches - Array of all touch events that have changed since the last event
    • identifier - The ID of the touch
    • locationX - The X position of the touch, relative to the element
    • locationY - The Y position of the touch, relative to the element
    • pageX - The X position of the touch, relative to the root element
    • pageY - The Y position of the touch, relative to the root element
    • target - The node id of the element receiving the touch event
    • timestamp - A time identifier for the touch, useful for velocity calculation
    • touches - 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.

Edit this page
Last updated on
- + diff --git a/docs/gesture-responder-system/index.html b/docs/gesture-responder-system/index.html index 81b32efdeac..fd62069a8ea 100644 --- a/docs/gesture-responder-system/index.html +++ b/docs/gesture-responder-system/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

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.

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 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 happening
  • View.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 finger
  • View.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 release
  • View.props.onResponderTerminate: (evt) => {} - The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, 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:

  • nativeEvent
    • changedTouches - Array of all touch events that have changed since the last event
    • identifier - The ID of the touch
    • locationX - The X position of the touch, relative to the element
    • locationY - The Y position of the touch, relative to the element
    • pageX - The X position of the touch, relative to the root element
    • pageY - The Y position of the touch, relative to the root element
    • target - The node id of the element receiving the touch event
    • timestamp - A time identifier for the touch, useful for velocity calculation
    • touches - 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.

Edit this page
Last updated on
- + diff --git a/docs/getting-started.html b/docs/getting-started.html index 5260ff78654..1c7dde73e68 100644 --- a/docs/getting-started.html +++ b/docs/getting-started.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Introduction

Welcome to the very start of your React Native journey! If you're looking for environment setup instructions, they've moved to their own section. Continue reading for an introduction to the documentation, Native Components, React, and more!

Many different kinds of people use React Native: from advanced iOS developers to React beginners, to people getting started programming for the first time in their career. These docs were written for all learners, no matter their experience level or background.

How to use these docs

You can start here and read through these docs linearly like a book; or you can read the specific sections you need. Already familiar with React? You can skip that section—or read it for a light refresher.

Prerequisites

To work with React Native, you will need to have an understanding of JavaScript fundamentals. If you’re new to JavaScript or need a refresher, you can dive in or brush up at Mozilla Developer Network.

While we do our best to assume no prior knowledge of React, Android, or iOS development, these are valuable topics of study for the aspiring React Native developer. Where sensible, we have linked to resources and articles that go more in depth.

Interactive examples

This introduction lets you get started immediately in your browser with interactive examples like this one:

The above is a Snack Player. It’s a handy tool created by Expo to embed and run React Native projects and share how they render in platforms like Android and iOS. The code is live and editable, so you can play directly with it in your browser. Go ahead and try changing the "Try editing me!" text above to "Hello, world!"

Optionally, if you want to setup a local development environment, you can follow our guide to setting up your environment on your local machine and paste the code examples into your App.js file there. (If you are a web developer, you may already have a local environment set up for mobile browser testing!)

Function Components and Class Components

With React, you can make components using either classes or functions. Originally, class components were the only components that could have state. But since the introduction of React's Hooks API, you can add state and more to function components.

Hooks were introduced in React Native 0.59., and because Hooks are the future-facing way to write your React components, we wrote this introduction using function component examples. Where useful, we also cover class components under a toggle like so:

You can find more examples of class components in previous versions of this documentation.

Developer Notes

People from many different development backgrounds are learning React Native. You may have experience with a range of technologies, from web to Android to iOS and more. We try to write for developers from all backgrounds. Sometimes we provide explanations specific to one platform or another like so:

Web developers may be familiar with this concept.

Formatting

Menu paths are written in bold and use carets to navigate submenus. Example: Android Studio > Preferences

Now that you know how this guide works, it's time to get to know the foundation of React Native: Native Components.

Edit this page
Last updated on
- + diff --git a/docs/getting-started/index.html b/docs/getting-started/index.html index 5260ff78654..1c7dde73e68 100644 --- a/docs/getting-started/index.html +++ b/docs/getting-started/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Introduction

Welcome to the very start of your React Native journey! If you're looking for environment setup instructions, they've moved to their own section. Continue reading for an introduction to the documentation, Native Components, React, and more!

Many different kinds of people use React Native: from advanced iOS developers to React beginners, to people getting started programming for the first time in their career. These docs were written for all learners, no matter their experience level or background.

How to use these docs

You can start here and read through these docs linearly like a book; or you can read the specific sections you need. Already familiar with React? You can skip that section—or read it for a light refresher.

Prerequisites

To work with React Native, you will need to have an understanding of JavaScript fundamentals. If you’re new to JavaScript or need a refresher, you can dive in or brush up at Mozilla Developer Network.

While we do our best to assume no prior knowledge of React, Android, or iOS development, these are valuable topics of study for the aspiring React Native developer. Where sensible, we have linked to resources and articles that go more in depth.

Interactive examples

This introduction lets you get started immediately in your browser with interactive examples like this one:

The above is a Snack Player. It’s a handy tool created by Expo to embed and run React Native projects and share how they render in platforms like Android and iOS. The code is live and editable, so you can play directly with it in your browser. Go ahead and try changing the "Try editing me!" text above to "Hello, world!"

Optionally, if you want to setup a local development environment, you can follow our guide to setting up your environment on your local machine and paste the code examples into your App.js file there. (If you are a web developer, you may already have a local environment set up for mobile browser testing!)

Function Components and Class Components

With React, you can make components using either classes or functions. Originally, class components were the only components that could have state. But since the introduction of React's Hooks API, you can add state and more to function components.

Hooks were introduced in React Native 0.59., and because Hooks are the future-facing way to write your React components, we wrote this introduction using function component examples. Where useful, we also cover class components under a toggle like so:

You can find more examples of class components in previous versions of this documentation.

Developer Notes

People from many different development backgrounds are learning React Native. You may have experience with a range of technologies, from web to Android to iOS and more. We try to write for developers from all backgrounds. Sometimes we provide explanations specific to one platform or another like so:

Web developers may be familiar with this concept.

Formatting

Menu paths are written in bold and use carets to navigate submenus. Example: Android Studio > Preferences

Now that you know how this guide works, it's time to get to know the foundation of React Native: Native Components.

Edit this page
Last updated on
- + diff --git a/docs/handling-text-input.html b/docs/handling-text-input.html index b446064463f..07381885142 100644 --- a/docs/handling-text-input.html +++ b/docs/handling-text-input.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Handling Text Input

TextInput is a Core Component that allows the user to enter text. It has an onChangeText prop that takes a function to be called every time the text changed, and an onSubmitEditing prop that takes a function to be called when the text is submitted.

For example, let's say that as the user types, you're translating their words into a different language. In this new language, every single word is written the same way: 🍕. So the sentence "Hello there Bob" would be translated as "🍕🍕🍕".

In this example, we store text in the state, because it changes over time.

There are a lot more things you might want to do with a text input. For example, you could validate the text inside while the user types. For more detailed examples, see the React docs on controlled components, or the reference docs for TextInput.

Text input is one of the ways the user interacts with the app. Next, let's look at another type of input and learn how to handle touches.

Edit this page
Last updated on
- + diff --git a/docs/handling-text-input/index.html b/docs/handling-text-input/index.html index b446064463f..07381885142 100644 --- a/docs/handling-text-input/index.html +++ b/docs/handling-text-input/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Handling Text Input

TextInput is a Core Component that allows the user to enter text. It has an onChangeText prop that takes a function to be called every time the text changed, and an onSubmitEditing prop that takes a function to be called when the text is submitted.

For example, let's say that as the user types, you're translating their words into a different language. In this new language, every single word is written the same way: 🍕. So the sentence "Hello there Bob" would be translated as "🍕🍕🍕".

In this example, we store text in the state, because it changes over time.

There are a lot more things you might want to do with a text input. For example, you could validate the text inside while the user types. For more detailed examples, see the React docs on controlled components, or the reference docs for TextInput.

Text input is one of the ways the user interacts with the app. Next, let's look at another type of input and learn how to handle touches.

Edit this page
Last updated on
- + diff --git a/docs/handling-touches.html b/docs/handling-touches.html index c313af4ea4a..51d0d4081a7 100644 --- a/docs/handling-touches.html +++ b/docs/handling-touches.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Handling Touches

Users interact with mobile apps mainly through touch. They can use a combination of gestures, such as tapping on a button, scrolling a list, or zooming on a map. React Native provides components to handle all sorts of common gestures, as well as a comprehensive gesture responder system to allow for more advanced gesture recognition, but the one component you will most likely be interested in is the basic Button.

Displaying a basic button

Button provides a basic button component that is rendered nicely on all platforms. The minimal example to display a button looks like this:

<Button
onPress={() => {
alert('You tapped the button!');
}}
title="Press Me"
/>

This will render a blue label on iOS, and a blue rounded rectangle with light text on Android. Pressing the button will call the "onPress" function, which in this case displays an alert popup. If you like, you can specify a "color" prop to change the color of your button.

Go ahead and play around with the Button component using the example below. You can select which platform your app is previewed in by clicking on the toggle in the bottom right and then clicking on "Tap to Play" to preview the app.

Touchables

If the basic button doesn't look right for your app, you can build your own button using any of the "Touchable" components provided by React Native. The "Touchable" components provide the capability to capture tapping gestures, and can display feedback when a gesture is recognized. These components do not provide any default styling, however, so you will need to do a bit of work to get them looking nicely in your app.

Which "Touchable" component you use will depend on what kind of feedback you want to provide:

  • Generally, you can use TouchableHighlight anywhere you would use a button or link on web. The view's background will be darkened when the user presses down on the button.

  • You may consider using TouchableNativeFeedback on Android to display ink surface reaction ripples that respond to the user's touch.

  • TouchableOpacity can be used to provide feedback by reducing the opacity of the button, allowing the background to be seen through while the user is pressing down.

  • If you need to handle a tap gesture but you don't want any feedback to be displayed, use TouchableWithoutFeedback.

In some cases, you may want to detect when a user presses and holds a view for a set amount of time. These long presses can be handled by passing a function to the onLongPress props of any of the "Touchable" components.

Let's see all of these in action:

Scrolling and swiping

Gestures commonly used on devices with touchable screens include swipes and pans. These allow the user to scroll through a list of items, or swipe through pages of content. For these, check out the ScrollView Core Component.

Edit this page
Last updated on
- + diff --git a/docs/handling-touches/index.html b/docs/handling-touches/index.html index c313af4ea4a..51d0d4081a7 100644 --- a/docs/handling-touches/index.html +++ b/docs/handling-touches/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Handling Touches

Users interact with mobile apps mainly through touch. They can use a combination of gestures, such as tapping on a button, scrolling a list, or zooming on a map. React Native provides components to handle all sorts of common gestures, as well as a comprehensive gesture responder system to allow for more advanced gesture recognition, but the one component you will most likely be interested in is the basic Button.

Displaying a basic button

Button provides a basic button component that is rendered nicely on all platforms. The minimal example to display a button looks like this:

<Button
onPress={() => {
alert('You tapped the button!');
}}
title="Press Me"
/>

This will render a blue label on iOS, and a blue rounded rectangle with light text on Android. Pressing the button will call the "onPress" function, which in this case displays an alert popup. If you like, you can specify a "color" prop to change the color of your button.

Go ahead and play around with the Button component using the example below. You can select which platform your app is previewed in by clicking on the toggle in the bottom right and then clicking on "Tap to Play" to preview the app.

Touchables

If the basic button doesn't look right for your app, you can build your own button using any of the "Touchable" components provided by React Native. The "Touchable" components provide the capability to capture tapping gestures, and can display feedback when a gesture is recognized. These components do not provide any default styling, however, so you will need to do a bit of work to get them looking nicely in your app.

Which "Touchable" component you use will depend on what kind of feedback you want to provide:

  • Generally, you can use TouchableHighlight anywhere you would use a button or link on web. The view's background will be darkened when the user presses down on the button.

  • You may consider using TouchableNativeFeedback on Android to display ink surface reaction ripples that respond to the user's touch.

  • TouchableOpacity can be used to provide feedback by reducing the opacity of the button, allowing the background to be seen through while the user is pressing down.

  • If you need to handle a tap gesture but you don't want any feedback to be displayed, use TouchableWithoutFeedback.

In some cases, you may want to detect when a user presses and holds a view for a set amount of time. These long presses can be handled by passing a function to the onLongPress props of any of the "Touchable" components.

Let's see all of these in action:

Scrolling and swiping

Gestures commonly used on devices with touchable screens include swipes and pans. These allow the user to scroll through a list of items, or swipe through pages of content. For these, check out the ScrollView Core Component.

Edit this page
Last updated on
- + diff --git a/docs/headless-js-android.html b/docs/headless-js-android.html index 7af2af9028b..be8e60108a1 100644 --- a/docs/headless-js-android.html +++ b/docs/headless-js-android.html @@ -19,7 +19,7 @@ - + @@ -44,7 +44,7 @@
}
Edit this page
Last updated on
- + diff --git a/docs/headless-js-android/index.html b/docs/headless-js-android/index.html index 7af2af9028b..be8e60108a1 100644 --- a/docs/headless-js-android/index.html +++ b/docs/headless-js-android/index.html @@ -19,7 +19,7 @@ - + @@ -44,7 +44,7 @@
}
Edit this page
Last updated on
- + diff --git a/docs/height-and-width.html b/docs/height-and-width.html index 753c4c65397..6ffc6615b45 100644 --- a/docs/height-and-width.html +++ b/docs/height-and-width.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Height and Width

A component's height and width determine its size on the screen.

Fixed Dimensions

The general way to set the dimensions of a component is by adding a fixed width and height to style. All dimensions in React Native are unitless, and represent density-independent pixels.

Setting dimensions this way is common for components that should always render at exactly the same size, regardless of screen dimensions.

Flex Dimensions

Use flex in a component's style to have the component expand and shrink dynamically based on available space. Normally you will use flex: 1, which tells a component to fill all available space, shared evenly amongst other components with the same parent. The larger the flex given, the higher the ratio of space a component will take compared to its siblings.

A component can only expand to fill available space if its parent has dimensions greater than 0. If a parent does not have either a fixed width and height or flex, the parent will have dimensions of 0 and the flex children will not be visible.

After you can control a component's size, the next step is to learn how to lay it out on the screen.

Edit this page
Last updated on
- + diff --git a/docs/height-and-width/index.html b/docs/height-and-width/index.html index 753c4c65397..6ffc6615b45 100644 --- a/docs/height-and-width/index.html +++ b/docs/height-and-width/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Height and Width

A component's height and width determine its size on the screen.

Fixed Dimensions

The general way to set the dimensions of a component is by adding a fixed width and height to style. All dimensions in React Native are unitless, and represent density-independent pixels.

Setting dimensions this way is common for components that should always render at exactly the same size, regardless of screen dimensions.

Flex Dimensions

Use flex in a component's style to have the component expand and shrink dynamically based on available space. Normally you will use flex: 1, which tells a component to fill all available space, shared evenly amongst other components with the same parent. The larger the flex given, the higher the ratio of space a component will take compared to its siblings.

A component can only expand to fill available space if its parent has dimensions greater than 0. If a parent does not have either a fixed width and height or flex, the parent will have dimensions of 0 and the flex children will not be visible.

After you can control a component's size, the next step is to learn how to lay it out on the screen.

Edit this page
Last updated on
- + diff --git a/docs/hermes.html b/docs/hermes.html index 3a2cd7f5303..bb6d24fdabf 100644 --- a/docs/hermes.html +++ b/docs/hermes.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Using Hermes

Hermes is an open-source JavaScript engine optimized for running React Native apps on Android. For many apps, enabling Hermes will result in improved start-up time, decreased memory usage, and smaller app size. At this time Hermes is an opt-in React Native feature, and this guide explains how to enable it.

First, ensure you're using at least version 0.60.4 of React Native.

If you have an existing app based on an earlier version of React Native, you will have to upgrade it first. See Upgrading to new React Native Versions for how to do this. Make especially sure that all changes to android/app/build.gradle have been applied, as detailed by the React Native upgrade helper. After upgrading the app, make sure everything works before trying to switch to Hermes.

Note for RN compatibility.

Each Hermes release is aimed at a specific RN version. The rule of thumb is to always follow Hermes releases strictly. Version mismatch can result in instant crash of your apps in the worst case scenario.

Note for Windows users.

Hermes requires Microsoft Visual C++ 2015 Redistributable

Edit your android/app/build.gradle file and make the change illustrated below:

project.ext.react = [
entryFile: "index.js",
- enableHermes: false // clean and rebuild if changing
+ enableHermes: true // clean and rebuild if changing
]

Also, if you're using ProGuard, you will need to add these rules in proguard-rules.pro :

-keep class com.facebook.hermes.unicode.** { *; }
-keep class com.facebook.jni.** { *; }

Next, if you've already built your app at least once, clean the build:

$ cd android && ./gradlew clean

That's it! You should now be able to develop and deploy your app as normal:

$ npx react-native run-android

Note about Android App Bundles

Android app bundles are supported from react-native 0.62.0 and up.

Confirming Hermes is in use

If you've recently created a new app from scratch, you should see if Hermes is enabled in the welcome view:

Where to find JS engine status in AwesomeProject

A HermesInternal global variable will be available in JavaScript that can be used to verify that Hermes is in use:

const isHermes = () => !!global.HermesInternal;

To see the benefits of Hermes, try making a release build/deployment of your app to compare. For example:

$ npx react-native run-android --variant release

This will compile JavaScript to bytecode during build time which will improve your app's startup speed on device.

Debugging JS on Hermes using Google Chrome's DevTools

Hermes supports the Chrome debugger by implementing the Chrome inspector protocol. This means Chrome's tools can be used to directly debug JavaScript running on Hermes, on an emulator or on a real, physical, device.

Note that this is very different with the "Remote JS Debugging" from the In-App Developer Menu documented in the Debugging section, which actually runs the JS code on Chrome's V8 on your development machine (laptop or desktop).

Chrome connects to Hermes running on device via Metro, so you'll need to know where Metro is listening. Typically this will be on localhost:8081, but this is configurable. When running yarn start the address is written to stdout on startup.

Once you know where the Metro server is listening, you can connect with Chrome using the following steps:

  1. Navigate to chrome://inspect in a Chrome browser instance.

  2. Use the Configure... button to add the Metro server address (typically localhost:8081 as described above).

Configure button in Chrome DevTools devices page

Dialog for adding Chrome DevTools network targets

  1. You should now see a "Hermes React Native" target with an "inspect" link which can be used to bring up debugger. If you don't see the "inspect" link, make sure the Metro server is running. Target inspect link

  2. You can now use the Chrome debug tools. For example, to breakpoint the next time some JavaScript is run, click on the pause button and trigger an action in your app which would cause JavaScript to execute. Pause button in debug tools

Edit this page
Last updated on
- + diff --git a/docs/hermes/index.html b/docs/hermes/index.html index 3a2cd7f5303..bb6d24fdabf 100644 --- a/docs/hermes/index.html +++ b/docs/hermes/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Using Hermes

Hermes is an open-source JavaScript engine optimized for running React Native apps on Android. For many apps, enabling Hermes will result in improved start-up time, decreased memory usage, and smaller app size. At this time Hermes is an opt-in React Native feature, and this guide explains how to enable it.

First, ensure you're using at least version 0.60.4 of React Native.

If you have an existing app based on an earlier version of React Native, you will have to upgrade it first. See Upgrading to new React Native Versions for how to do this. Make especially sure that all changes to android/app/build.gradle have been applied, as detailed by the React Native upgrade helper. After upgrading the app, make sure everything works before trying to switch to Hermes.

Note for RN compatibility.

Each Hermes release is aimed at a specific RN version. The rule of thumb is to always follow Hermes releases strictly. Version mismatch can result in instant crash of your apps in the worst case scenario.

Note for Windows users.

Hermes requires Microsoft Visual C++ 2015 Redistributable

Edit your android/app/build.gradle file and make the change illustrated below:

project.ext.react = [
entryFile: "index.js",
- enableHermes: false // clean and rebuild if changing
+ enableHermes: true // clean and rebuild if changing
]

Also, if you're using ProGuard, you will need to add these rules in proguard-rules.pro :

-keep class com.facebook.hermes.unicode.** { *; }
-keep class com.facebook.jni.** { *; }

Next, if you've already built your app at least once, clean the build:

$ cd android && ./gradlew clean

That's it! You should now be able to develop and deploy your app as normal:

$ npx react-native run-android

Note about Android App Bundles

Android app bundles are supported from react-native 0.62.0 and up.

Confirming Hermes is in use

If you've recently created a new app from scratch, you should see if Hermes is enabled in the welcome view:

Where to find JS engine status in AwesomeProject

A HermesInternal global variable will be available in JavaScript that can be used to verify that Hermes is in use:

const isHermes = () => !!global.HermesInternal;

To see the benefits of Hermes, try making a release build/deployment of your app to compare. For example:

$ npx react-native run-android --variant release

This will compile JavaScript to bytecode during build time which will improve your app's startup speed on device.

Debugging JS on Hermes using Google Chrome's DevTools

Hermes supports the Chrome debugger by implementing the Chrome inspector protocol. This means Chrome's tools can be used to directly debug JavaScript running on Hermes, on an emulator or on a real, physical, device.

Note that this is very different with the "Remote JS Debugging" from the In-App Developer Menu documented in the Debugging section, which actually runs the JS code on Chrome's V8 on your development machine (laptop or desktop).

Chrome connects to Hermes running on device via Metro, so you'll need to know where Metro is listening. Typically this will be on localhost:8081, but this is configurable. When running yarn start the address is written to stdout on startup.

Once you know where the Metro server is listening, you can connect with Chrome using the following steps:

  1. Navigate to chrome://inspect in a Chrome browser instance.

  2. Use the Configure... button to add the Metro server address (typically localhost:8081 as described above).

Configure button in Chrome DevTools devices page

Dialog for adding Chrome DevTools network targets

  1. You should now see a "Hermes React Native" target with an "inspect" link which can be used to bring up debugger. If you don't see the "inspect" link, make sure the Metro server is running. Target inspect link

  2. You can now use the Chrome debug tools. For example, to breakpoint the next time some JavaScript is run, click on the pause button and trigger an action in your app which would cause JavaScript to execute. Pause button in debug tools

Edit this page
Last updated on
- + diff --git a/docs/image-style-props.html b/docs/image-style-props.html index c1f6e928d06..81aea89107c 100644 --- a/docs/image-style-props.html +++ b/docs/image-style-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Image Style Props

Examples

Reference

Props

borderTopRightRadius

TypeRequired
numberNo

backfaceVisibility

TypeRequired
enum('visible', 'hidden')No

borderBottomLeftRadius

TypeRequired
numberNo

borderBottomRightRadius

TypeRequired
numberNo

borderColor

TypeRequired
colorNo

borderRadius

TypeRequired
numberNo

borderTopLeftRadius

TypeRequired
numberNo

backgroundColor

TypeRequired
colorNo

borderWidth

TypeRequired
numberNo

opacity

TypeRequired
numberNo

overflow

TypeRequired
enum('visible', 'hidden')No

resizeMode

TypeRequired
enum('cover', 'contain', 'stretch', 'repeat', 'center')No

tintColor

Changes the color of all the non-transparent pixels to the tintColor.

TypeRequired
colorNo

overlayColor

When the image has rounded corners, specifying an overlayColor will cause the remaining space in the corners to be filled with a solid color. This is useful in cases which are not supported by the Android implementation of rounded corners:

  • Certain resize modes, such as 'contain'
  • Animated GIFs

A typical way to use this prop is with images displayed on a solid background and setting the overlayColor to the same color as the background.

For details of how this works under the hood, see https://frescolib.org/docs/rounded-corners-and-circles.html

TypeRequiredPlatform
stringNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/image-style-props/index.html b/docs/image-style-props/index.html index c1f6e928d06..81aea89107c 100644 --- a/docs/image-style-props/index.html +++ b/docs/image-style-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Image Style Props

Examples

Reference

Props

borderTopRightRadius

TypeRequired
numberNo

backfaceVisibility

TypeRequired
enum('visible', 'hidden')No

borderBottomLeftRadius

TypeRequired
numberNo

borderBottomRightRadius

TypeRequired
numberNo

borderColor

TypeRequired
colorNo

borderRadius

TypeRequired
numberNo

borderTopLeftRadius

TypeRequired
numberNo

backgroundColor

TypeRequired
colorNo

borderWidth

TypeRequired
numberNo

opacity

TypeRequired
numberNo

overflow

TypeRequired
enum('visible', 'hidden')No

resizeMode

TypeRequired
enum('cover', 'contain', 'stretch', 'repeat', 'center')No

tintColor

Changes the color of all the non-transparent pixels to the tintColor.

TypeRequired
colorNo

overlayColor

When the image has rounded corners, specifying an overlayColor will cause the remaining space in the corners to be filled with a solid color. This is useful in cases which are not supported by the Android implementation of rounded corners:

  • Certain resize modes, such as 'contain'
  • Animated GIFs

A typical way to use this prop is with images displayed on a solid background and setting the overlayColor to the same color as the background.

For details of how this works under the hood, see https://frescolib.org/docs/rounded-corners-and-circles.html

TypeRequiredPlatform
stringNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/image.html b/docs/image.html index 9ac6728f2e0..71f0f817ef2 100644 --- a/docs/image.html +++ b/docs/image.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// For WebP support, without animations
implementation 'com.facebook.fresco:webpsupport:2.0.0'
}

Reference

Props

style

ImageResizeMode is an Enum for different image resizing modes, set via the resizeMode style property on Image components. The values are contain, cover, stretch, center, repeat.

TypeRequired
styleNo

accessible

When true, indicates the image is an accessibility element.

TypeRequiredPlatform
boolNoiOS

accessibilityLabel

The text that's read by the screen reader when the user interacts with the image.

TypeRequiredPlatform
stringNoiOS

blurRadius

blurRadius: the blur radius of the blur filter added to the image

TypeRequired
numberNo

Tip : IOS you will need to increase blurRadius more than 5

capInsets

When the image is resized, the corners of the size specified by capInsets will stay a fixed size, but the center content and borders of the image will be stretched. This is useful for creating resizable rounded buttons, shadows, and other resizable assets. More info in the official Apple documentation.

TypeRequiredPlatform
RectNoiOS

defaultSource

A static image to display while loading the image source.

TypeRequiredPlatform
object, numberNoiOS
numberNoAndroid

If passing an object, the general shape is {uri: string, width: number, height: number, scale: number}:

If passing a number:

Note: On Android, the default source prop is ignored on debug builds.

fadeDuration

Android only. By default, it is 300ms.

TypeRequiredPlatform
numberNoAndroid

loadingIndicatorSource

Similarly to source, this property represents the resource used to render the loading indicator for the image, displayed until image is ready to be displayed, typically after when it got downloaded from network.

TypeRequired
array of ImageSourcePropTypes, numberNo

Can accept a number as returned by require('./image.jpg')

onError

Invoked on load error with {nativeEvent: {error}}.

TypeRequired
functionNo

onLayout

Invoked on mount and layout changes with {nativeEvent: {layout: {x, y, width, height}}}.

TypeRequired
functionNo

onLoad

Invoked when load completes successfully.

TypeRequired
functionNo

onLoadEnd

Invoked when load either succeeds or fails.

TypeRequired
functionNo

onLoadStart

Invoked on load start.

e.g., onLoadStart={(e) => this.setState({loading: true})}

TypeRequired
functionNo

onPartialLoad

Invoked when a partial load of the image is complete. The definition of what constitutes a "partial load" is loader specific though this is meant for progressive JPEG loads.

TypeRequiredPlatform
functionNoiOS

onProgress

Invoked on download progress with {nativeEvent: {loaded, total}}.

TypeRequiredPlatform
functionNoiOS

progressiveRenderingEnabled

Android only. When true, enables progressive jpeg streaming. https://frescolib.org/docs/progressive-jpegs.html

TypeRequiredPlatform
boolNoAndroid

resizeMethod

The mechanism that should be used to resize the image when the image's dimensions differ from the image view's dimensions. Defaults to auto.

More details about resize and scale can be found at http://frescolib.org/docs/resizing.html.

TypeRequiredPlatform
enum('auto', 'resize', 'scale')NoAndroid

resizeMode

Determines how to resize the image when the frame doesn't match the raw image dimensions. Defaults to cover.

TypeRequired
enum('cover', 'contain', 'stretch', 'repeat', 'center')No

source

The image source (either a remote URL or a local file resource).

This prop can also contain several remote URLs, specified together with their width and height and potentially with scale/other URI arguments. The native side will then choose the best uri to display based on the measured size of the image container. A cache property can be added to control how networked request interacts with the local cache. (For more information see Cache Control for Images).

The currently supported formats are png, jpg, jpeg, bmp, gif, webp, psd (iOS only). In addition, iOS supports several RAW image formats. Refer to Apple's documentation for the current list of supported camera models (for iOS 12, see https://support.apple.com/en-ca/HT208967).

TypeRequired
ImageSourcePropTypeNo

testID

A unique identifier for this element to be used in UI Automation testing scripts.

TypeRequired
stringNo

Methods

getSize()

Image.getSize(uri, success, [failure]);

Retrieve the width and height (in pixels) of an image prior to displaying it. This method can fail if the image cannot be found, or fails to download.

In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API.

Parameters:

NameTypeRequiredDescription
uristringYesThe location of the image.
successfunctionYesThe function that will be called if the image was successfully found and width and height retrieved.
failurefunctionNoThe function that will be called if there was an error, such as failing to retrieve the image.

getSizeWithHeaders()

Image.getSizeWithHeaders(uri, headers, success, [failure]);

Retrieve the width and height (in pixels) of an image prior to displaying it with the ability to provide the headers for the request. This method can fail if the image cannot be found, or fails to download.

In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API.

Does not work for static image resources.

Parameters:

NameTypeRequiredDescription
uristringYesThe location of the image.
headersobjectYesThe headers for the request.
successfunctionYesThe function that will be called if the image was successfully found and width and height retrieved.
failurefunctionNoThe function that will be called if there was an error, such as failing toto retrieve the image.

prefetch()

Image.prefetch(url);

Prefetches a remote image for later use by downloading it to the disk cache

Parameters:

NameTypeRequiredDescription
urlstringYesThe remote location of the image.

abortPrefetch()

Image.abortPrefetch(requestId);

Abort prefetch request. Android-only.

Parameters:

NameTypeRequiredDescription
requestIdnumberYesId as returned by prefetch()

queryCache()

Image.queryCache(urls);

Perform cache interrogation. Returns a mapping from URL to cache status, such as "disk" or "memory". If a requested URL is not in the mapping, it means it's not in the cache.

Parameters:

NameTypeRequiredDescription
urlsarrayYesList of image URLs to check the cache for.

resolveAssetSource()

Image.resolveAssetSource(source);

Resolves an asset reference into an object which has the properties uri, width, and height.

Parameters:

NameTypeRequiredDescription
sourcenumber, objectYesA number (opaque type returned by require('./foo.png')) or an ImageSource.

ImageSource is an object like { uri: '<http location || file path>' }

Edit this page
Last updated on
- + diff --git a/docs/image/index.html b/docs/image/index.html index 9ac6728f2e0..71f0f817ef2 100644 --- a/docs/image/index.html +++ b/docs/image/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// For WebP support, without animations
implementation 'com.facebook.fresco:webpsupport:2.0.0'
}

Reference

Props

style

ImageResizeMode is an Enum for different image resizing modes, set via the resizeMode style property on Image components. The values are contain, cover, stretch, center, repeat.

TypeRequired
styleNo

accessible

When true, indicates the image is an accessibility element.

TypeRequiredPlatform
boolNoiOS

accessibilityLabel

The text that's read by the screen reader when the user interacts with the image.

TypeRequiredPlatform
stringNoiOS

blurRadius

blurRadius: the blur radius of the blur filter added to the image

TypeRequired
numberNo

Tip : IOS you will need to increase blurRadius more than 5

capInsets

When the image is resized, the corners of the size specified by capInsets will stay a fixed size, but the center content and borders of the image will be stretched. This is useful for creating resizable rounded buttons, shadows, and other resizable assets. More info in the official Apple documentation.

TypeRequiredPlatform
RectNoiOS

defaultSource

A static image to display while loading the image source.

TypeRequiredPlatform
object, numberNoiOS
numberNoAndroid

If passing an object, the general shape is {uri: string, width: number, height: number, scale: number}:

If passing a number:

Note: On Android, the default source prop is ignored on debug builds.

fadeDuration

Android only. By default, it is 300ms.

TypeRequiredPlatform
numberNoAndroid

loadingIndicatorSource

Similarly to source, this property represents the resource used to render the loading indicator for the image, displayed until image is ready to be displayed, typically after when it got downloaded from network.

TypeRequired
array of ImageSourcePropTypes, numberNo

Can accept a number as returned by require('./image.jpg')

onError

Invoked on load error with {nativeEvent: {error}}.

TypeRequired
functionNo

onLayout

Invoked on mount and layout changes with {nativeEvent: {layout: {x, y, width, height}}}.

TypeRequired
functionNo

onLoad

Invoked when load completes successfully.

TypeRequired
functionNo

onLoadEnd

Invoked when load either succeeds or fails.

TypeRequired
functionNo

onLoadStart

Invoked on load start.

e.g., onLoadStart={(e) => this.setState({loading: true})}

TypeRequired
functionNo

onPartialLoad

Invoked when a partial load of the image is complete. The definition of what constitutes a "partial load" is loader specific though this is meant for progressive JPEG loads.

TypeRequiredPlatform
functionNoiOS

onProgress

Invoked on download progress with {nativeEvent: {loaded, total}}.

TypeRequiredPlatform
functionNoiOS

progressiveRenderingEnabled

Android only. When true, enables progressive jpeg streaming. https://frescolib.org/docs/progressive-jpegs.html

TypeRequiredPlatform
boolNoAndroid

resizeMethod

The mechanism that should be used to resize the image when the image's dimensions differ from the image view's dimensions. Defaults to auto.

More details about resize and scale can be found at http://frescolib.org/docs/resizing.html.

TypeRequiredPlatform
enum('auto', 'resize', 'scale')NoAndroid

resizeMode

Determines how to resize the image when the frame doesn't match the raw image dimensions. Defaults to cover.

TypeRequired
enum('cover', 'contain', 'stretch', 'repeat', 'center')No

source

The image source (either a remote URL or a local file resource).

This prop can also contain several remote URLs, specified together with their width and height and potentially with scale/other URI arguments. The native side will then choose the best uri to display based on the measured size of the image container. A cache property can be added to control how networked request interacts with the local cache. (For more information see Cache Control for Images).

The currently supported formats are png, jpg, jpeg, bmp, gif, webp, psd (iOS only). In addition, iOS supports several RAW image formats. Refer to Apple's documentation for the current list of supported camera models (for iOS 12, see https://support.apple.com/en-ca/HT208967).

TypeRequired
ImageSourcePropTypeNo

testID

A unique identifier for this element to be used in UI Automation testing scripts.

TypeRequired
stringNo

Methods

getSize()

Image.getSize(uri, success, [failure]);

Retrieve the width and height (in pixels) of an image prior to displaying it. This method can fail if the image cannot be found, or fails to download.

In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API.

Parameters:

NameTypeRequiredDescription
uristringYesThe location of the image.
successfunctionYesThe function that will be called if the image was successfully found and width and height retrieved.
failurefunctionNoThe function that will be called if there was an error, such as failing to retrieve the image.

getSizeWithHeaders()

Image.getSizeWithHeaders(uri, headers, success, [failure]);

Retrieve the width and height (in pixels) of an image prior to displaying it with the ability to provide the headers for the request. This method can fail if the image cannot be found, or fails to download.

In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API.

Does not work for static image resources.

Parameters:

NameTypeRequiredDescription
uristringYesThe location of the image.
headersobjectYesThe headers for the request.
successfunctionYesThe function that will be called if the image was successfully found and width and height retrieved.
failurefunctionNoThe function that will be called if there was an error, such as failing toto retrieve the image.

prefetch()

Image.prefetch(url);

Prefetches a remote image for later use by downloading it to the disk cache

Parameters:

NameTypeRequiredDescription
urlstringYesThe remote location of the image.

abortPrefetch()

Image.abortPrefetch(requestId);

Abort prefetch request. Android-only.

Parameters:

NameTypeRequiredDescription
requestIdnumberYesId as returned by prefetch()

queryCache()

Image.queryCache(urls);

Perform cache interrogation. Returns a mapping from URL to cache status, such as "disk" or "memory". If a requested URL is not in the mapping, it means it's not in the cache.

Parameters:

NameTypeRequiredDescription
urlsarrayYesList of image URLs to check the cache for.

resolveAssetSource()

Image.resolveAssetSource(source);

Resolves an asset reference into an object which has the properties uri, width, and height.

Parameters:

NameTypeRequiredDescription
sourcenumber, objectYesA number (opaque type returned by require('./foo.png')) or an ImageSource.

ImageSource is an object like { uri: '<http location || file path>' }

Edit this page
Last updated on
- + diff --git a/docs/imagebackground.html b/docs/imagebackground.html index ef328580616..f863c9633dc 100644 --- a/docs/imagebackground.html +++ b/docs/imagebackground.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

ImageBackground

A common feature request from developers familiar with the web is background-image. To handle this use case, you can use the <ImageBackground> component, which has the same props as <Image>, and add whatever children to it you would like to layer on top of it.

You might not want to use <ImageBackground> in some cases, since the implementation is basic. Refer to <ImageBackground>'s source code for more insight, and create your own custom component when needed.

Note that you must specify some width and height style attributes.

Example

Reference

Props

Inherits Image Props.

style

TypeRequired
view stylesNo

imageStyle

TypeRequired
image stylesNo

imageRef

Allows to set a reference to the inner Image component

TypeRequired
RefNo
Edit this page
Last updated on
- + diff --git a/docs/imagebackground/index.html b/docs/imagebackground/index.html index ef328580616..f863c9633dc 100644 --- a/docs/imagebackground/index.html +++ b/docs/imagebackground/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

ImageBackground

A common feature request from developers familiar with the web is background-image. To handle this use case, you can use the <ImageBackground> component, which has the same props as <Image>, and add whatever children to it you would like to layer on top of it.

You might not want to use <ImageBackground> in some cases, since the implementation is basic. Refer to <ImageBackground>'s source code for more insight, and create your own custom component when needed.

Note that you must specify some width and height style attributes.

Example

Reference

Props

Inherits Image Props.

style

TypeRequired
view stylesNo

imageStyle

TypeRequired
image stylesNo

imageRef

Allows to set a reference to the inner Image component

TypeRequired
RefNo
Edit this page
Last updated on
- + diff --git a/docs/imageeditor.html b/docs/imageeditor.html index fe47d8d8c28..44f6cca5e2a 100644 --- a/docs/imageeditor.html +++ b/docs/imageeditor.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 ImageEditor

Deprecated. Use one of the community packages instead.

Reference

Methods

cropImage()

static cropImage(uri, cropData, success, failure)

Crop the image specified by the URI param. If URI points to a remote image, it will be downloaded automatically. If the image cannot be loaded/downloaded, the failure callback will be called.

If the cropping process is successful, the resultant cropped image will be stored in the ImageStore, and the URI returned in the success callback will point to the image in the store. Remember to delete the cropped image from the ImageStore when you are done with it.

cropData

  • offset - The top-left corner of the cropped image, specified in the original image's coordinate space
  • size - Size (dimensions) of the cropped image
  • displaySize (optional) - Size to which you want to scale the cropped image
  • resizeMode (optional) - Resizing mode to use when scaling the image
cropData = {
offset: { x: number, y: number },
size: { width: number, height: number },
displaySize: { width: number, height: number },
resizeMode: 'contain/cover/stretch'
};
Edit this page
Last updated on
- + diff --git a/docs/imageeditor/index.html b/docs/imageeditor/index.html index fe47d8d8c28..44f6cca5e2a 100644 --- a/docs/imageeditor/index.html +++ b/docs/imageeditor/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 ImageEditor

Deprecated. Use one of the community packages instead.

Reference

Methods

cropImage()

static cropImage(uri, cropData, success, failure)

Crop the image specified by the URI param. If URI points to a remote image, it will be downloaded automatically. If the image cannot be loaded/downloaded, the failure callback will be called.

If the cropping process is successful, the resultant cropped image will be stored in the ImageStore, and the URI returned in the success callback will point to the image in the store. Remember to delete the cropped image from the ImageStore when you are done with it.

cropData

  • offset - The top-left corner of the cropped image, specified in the original image's coordinate space
  • size - Size (dimensions) of the cropped image
  • displaySize (optional) - Size to which you want to scale the cropped image
  • resizeMode (optional) - Resizing mode to use when scaling the image
cropData = {
offset: { x: number, y: number },
size: { width: number, height: number },
displaySize: { width: number, height: number },
resizeMode: 'contain/cover/stretch'
};
Edit this page
Last updated on
- + diff --git a/docs/imagepickerios.html b/docs/imagepickerios.html index 80caa8e2a6e..c20e9b2cba7 100644 --- a/docs/imagepickerios.html +++ b/docs/imagepickerios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 ImagePickerIOS

Deprecated. Use one of the community packages instead.

Reference

Methods

canRecordVideos()

static canRecordVideos(callback)

canUseCamera()

static canUseCamera(callback)

openCameraDialog()

static openCameraDialog(config, successCallback, cancelCallback)

Parameters:

NameTypeRequiredDescription
configobjectNoSee below.
successCallbackfunctionNoSee below.
cancelCallbackfunctionNoSee below.

config is an object containing:

  • videoMode : An optional boolean value that defaults to false.

successCallback is an optional callback function that's invoked when the select dialog is opened successfully. It will include the following data:

  • [string, number, number]

cancelCallback is an optional callback function that's invoked when the camera dialog is canceled.

openSelectDialog()

static openSelectDialog(config, successCallback, cancelCallback)

Parameters:

NameTypeRequiredDescription
configobjectNoSee below.
successCallbackfunctionNoSee below.
cancelCallbackfunctionNoSee below.

config is an object containing:

  • showImages : An optional boolean value that defaults to false.
  • showVideos: An optional boolean value that defaults to false.

successCallback is an optional callback function that's invoked when the select dialog is opened successfully. It will include the following data:

  • [string, number, number]

cancelCallback is an optional callback function that's invoked when the select dialog is canceled.

Edit this page
Last updated on
- + diff --git a/docs/imagepickerios/index.html b/docs/imagepickerios/index.html index 80caa8e2a6e..c20e9b2cba7 100644 --- a/docs/imagepickerios/index.html +++ b/docs/imagepickerios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 ImagePickerIOS

Deprecated. Use one of the community packages instead.

Reference

Methods

canRecordVideos()

static canRecordVideos(callback)

canUseCamera()

static canUseCamera(callback)

openCameraDialog()

static openCameraDialog(config, successCallback, cancelCallback)

Parameters:

NameTypeRequiredDescription
configobjectNoSee below.
successCallbackfunctionNoSee below.
cancelCallbackfunctionNoSee below.

config is an object containing:

  • videoMode : An optional boolean value that defaults to false.

successCallback is an optional callback function that's invoked when the select dialog is opened successfully. It will include the following data:

  • [string, number, number]

cancelCallback is an optional callback function that's invoked when the camera dialog is canceled.

openSelectDialog()

static openSelectDialog(config, successCallback, cancelCallback)

Parameters:

NameTypeRequiredDescription
configobjectNoSee below.
successCallbackfunctionNoSee below.
cancelCallbackfunctionNoSee below.

config is an object containing:

  • showImages : An optional boolean value that defaults to false.
  • showVideos: An optional boolean value that defaults to false.

successCallback is an optional callback function that's invoked when the select dialog is opened successfully. It will include the following data:

  • [string, number, number]

cancelCallback is an optional callback function that's invoked when the select dialog is canceled.

Edit this page
Last updated on
- + diff --git a/docs/images.html b/docs/images.html index 2fb9130682c..d115a63d781 100644 --- a/docs/images.html +++ b/docs/images.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// BAD
<Image source={{uri: 'https://reactjs.org/logo-og.png'}} />

Network Requests for Images

If you would like to set such things as the HTTP-Verb, Headers or a Body along with the image request, you may do this by defining these properties on the source object:

<Image
source={{
uri: 'https://reactjs.org/logo-og.png',
method: 'POST',
headers: {
Pragma: 'no-cache'
},
body: 'Your Body goes here'
}}
style={{ width: 400, height: 400 }}
/>

Uri Data Images

Sometimes, you might be getting encoded image data from a REST API call. You can use the 'data:' uri scheme to use these images. Same as for network resources, you will need to manually specify the dimensions of your image.

This is recommended for very small and dynamic images only, like icons in a list from a DB.

// include at least width and height!
<Image
style={{
width: 51,
height: 51,
resizeMode: 'contain'
}}
source={{
uri:
'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADMAAAAzCAYAAAA6oTAqAAAAEXRFWHRTb2Z0d2FyZQBwbmdjcnVzaEB1SfMAAABQSURBVGje7dSxCQBACARB+2/ab8BEeQNhFi6WSYzYLYudDQYGBgYGBgYGBgYGBgYGBgZmcvDqYGBgmhivGQYGBgYGBgYGBgYGBgYGBgbmQw+P/eMrC5UTVAAAAABJRU5ErkJggg=='
}}
/>

Cache Control (iOS Only)

In some cases you might only want to display an image if it is already in the local cache, i.e. a low resolution placeholder until a higher resolution is available. In other cases you do not care if the image is outdated and are willing to display an outdated image to save bandwidth. The cache source property gives you control over how the network layer interacts with the cache.

<Image
source={{
uri: 'https://reactjs.org/logo-og.png',
cache: 'only-if-cached'
}}
style={{ width: 400, height: 400 }}
/>

Local Filesystem Images

See CameraRoll for an example of using local resources that are outside of Images.xcassets.

Best Camera Roll Image

iOS saves multiple sizes for the same image in your Camera Roll, it is very important to pick the one that's as close as possible for performance reasons. You wouldn't want to use the full quality 3264x2448 image as source when displaying a 200x200 thumbnail. If there's an exact match, React Native will pick it, otherwise it's going to use the first one that's at least 50% bigger in order to avoid blur when resizing from a close size. All of this is done by default so you don't have to worry about writing the tedious (and error prone) code to do it yourself.

Why Not Automatically Size Everything?

In the browser if you don't give a size to an image, the browser is going to render a 0x0 element, download the image, and then render the image based with the correct size. The big issue with this behavior is that your UI is going to jump all around as images load, this makes for a very bad user experience.

In React Native this behavior is intentionally not implemented. It is more work for the developer to know the dimensions (or aspect ratio) of the remote image in advance, but we believe that it leads to a better user experience. Static images loaded from the app bundle via the require('./my-icon.png') syntax can be automatically sized because their dimensions are available immediately at the time of mounting.

For example, the result of require('./my-icon.png') might be:

{"__packager_asset":true,"uri":"my-icon.png","width":591,"height":573}

Source as an object

In React Native, one interesting decision is that the src attribute is named source and doesn't take a string but an object with a uri attribute.

<Image source={{ uri: 'something.jpg' }} />

On the infrastructure side, the reason is that it allows us to attach metadata to this object. For example if you are using require('./my-icon.png'), then we add information about its actual location and size (don't rely on this fact, it might change in the future!). This is also future proofing, for example we may want to support sprites at some point, instead of outputting {uri: ...}, we can output {uri: ..., crop: {left: 10, top: 50, width: 20, height: 40}} and transparently support spriting on all the existing call sites.

On the user side, this lets you annotate the object with useful attributes such as the dimension of the image in order to compute the size it's going to be displayed in. Feel free to use it as your data structure to store more information about your image.

Background Image via Nesting

A common feature request from developers familiar with the web is background-image. To handle this use case, you can use the <ImageBackground> component, which has the same props as <Image>, and add whatever children to it you would like to layer on top of it.

You might not want to use <ImageBackground> in some cases, since the implementation is basic. Refer to <ImageBackground>'s documentation for more insight, and create your own custom component when needed.

return (
<ImageBackground source={...} style={{width: '100%', height: '100%'}}>
<Text>Inside</Text>
</ImageBackground>
);

Note that you must specify some width and height style attributes.

iOS Border Radius Styles

Please note that the following corner specific, border radius style properties are currently ignored by iOS's image component:

Off-thread Decoding

Image decoding can take more than a frame-worth of time. This is one of the major sources of frame drops on the web because decoding is done in the main thread. In React Native, image decoding is done in a different thread. In practice, you already need to handle the case when the image is not downloaded yet, so displaying the placeholder for a few more frames while it is decoding does not require any code change.

Edit this page
Last updated on
- + diff --git a/docs/images/index.html b/docs/images/index.html index 2fb9130682c..d115a63d781 100644 --- a/docs/images/index.html +++ b/docs/images/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// BAD
<Image source={{uri: 'https://reactjs.org/logo-og.png'}} />

Network Requests for Images

If you would like to set such things as the HTTP-Verb, Headers or a Body along with the image request, you may do this by defining these properties on the source object:

<Image
source={{
uri: 'https://reactjs.org/logo-og.png',
method: 'POST',
headers: {
Pragma: 'no-cache'
},
body: 'Your Body goes here'
}}
style={{ width: 400, height: 400 }}
/>

Uri Data Images

Sometimes, you might be getting encoded image data from a REST API call. You can use the 'data:' uri scheme to use these images. Same as for network resources, you will need to manually specify the dimensions of your image.

This is recommended for very small and dynamic images only, like icons in a list from a DB.

// include at least width and height!
<Image
style={{
width: 51,
height: 51,
resizeMode: 'contain'
}}
source={{
uri:
'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADMAAAAzCAYAAAA6oTAqAAAAEXRFWHRTb2Z0d2FyZQBwbmdjcnVzaEB1SfMAAABQSURBVGje7dSxCQBACARB+2/ab8BEeQNhFi6WSYzYLYudDQYGBgYGBgYGBgYGBgYGBgZmcvDqYGBgmhivGQYGBgYGBgYGBgYGBgYGBgbmQw+P/eMrC5UTVAAAAABJRU5ErkJggg=='
}}
/>

Cache Control (iOS Only)

In some cases you might only want to display an image if it is already in the local cache, i.e. a low resolution placeholder until a higher resolution is available. In other cases you do not care if the image is outdated and are willing to display an outdated image to save bandwidth. The cache source property gives you control over how the network layer interacts with the cache.

<Image
source={{
uri: 'https://reactjs.org/logo-og.png',
cache: 'only-if-cached'
}}
style={{ width: 400, height: 400 }}
/>

Local Filesystem Images

See CameraRoll for an example of using local resources that are outside of Images.xcassets.

Best Camera Roll Image

iOS saves multiple sizes for the same image in your Camera Roll, it is very important to pick the one that's as close as possible for performance reasons. You wouldn't want to use the full quality 3264x2448 image as source when displaying a 200x200 thumbnail. If there's an exact match, React Native will pick it, otherwise it's going to use the first one that's at least 50% bigger in order to avoid blur when resizing from a close size. All of this is done by default so you don't have to worry about writing the tedious (and error prone) code to do it yourself.

Why Not Automatically Size Everything?

In the browser if you don't give a size to an image, the browser is going to render a 0x0 element, download the image, and then render the image based with the correct size. The big issue with this behavior is that your UI is going to jump all around as images load, this makes for a very bad user experience.

In React Native this behavior is intentionally not implemented. It is more work for the developer to know the dimensions (or aspect ratio) of the remote image in advance, but we believe that it leads to a better user experience. Static images loaded from the app bundle via the require('./my-icon.png') syntax can be automatically sized because their dimensions are available immediately at the time of mounting.

For example, the result of require('./my-icon.png') might be:

{"__packager_asset":true,"uri":"my-icon.png","width":591,"height":573}

Source as an object

In React Native, one interesting decision is that the src attribute is named source and doesn't take a string but an object with a uri attribute.

<Image source={{ uri: 'something.jpg' }} />

On the infrastructure side, the reason is that it allows us to attach metadata to this object. For example if you are using require('./my-icon.png'), then we add information about its actual location and size (don't rely on this fact, it might change in the future!). This is also future proofing, for example we may want to support sprites at some point, instead of outputting {uri: ...}, we can output {uri: ..., crop: {left: 10, top: 50, width: 20, height: 40}} and transparently support spriting on all the existing call sites.

On the user side, this lets you annotate the object with useful attributes such as the dimension of the image in order to compute the size it's going to be displayed in. Feel free to use it as your data structure to store more information about your image.

Background Image via Nesting

A common feature request from developers familiar with the web is background-image. To handle this use case, you can use the <ImageBackground> component, which has the same props as <Image>, and add whatever children to it you would like to layer on top of it.

You might not want to use <ImageBackground> in some cases, since the implementation is basic. Refer to <ImageBackground>'s documentation for more insight, and create your own custom component when needed.

return (
<ImageBackground source={...} style={{width: '100%', height: '100%'}}>
<Text>Inside</Text>
</ImageBackground>
);

Note that you must specify some width and height style attributes.

iOS Border Radius Styles

Please note that the following corner specific, border radius style properties are currently ignored by iOS's image component:

Off-thread Decoding

Image decoding can take more than a frame-worth of time. This is one of the major sources of frame drops on the web because decoding is done in the main thread. In React Native, image decoding is done in a different thread. In practice, you already need to handle the case when the image is not downloaded yet, so displaying the placeholder for a few more frames while it is decoding does not require any code change.

Edit this page
Last updated on
- + diff --git a/docs/imagestore.html b/docs/imagestore.html index ac6ee9fd143..4ce4e3877c4 100644 --- a/docs/imagestore.html +++ b/docs/imagestore.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

ImageStore

Deprecated. Use one of the community packages instead.

Methods

Reference

Methods

hasImageForTag()

static hasImageForTag(uri, callback)

Check if the ImageStore contains image data for the specified URI. @platform ios

removeImageForTag()

static removeImageForTag(uri)

Delete an image from the ImageStore. Images are stored in memory and must be manually removed when you are finished with them, otherwise they will continue to use up RAM until the app is terminated. It is safe to call removeImageForTag() without first calling hasImageForTag(), it will fail silently. @platform ios

addImageFromBase64()

static addImageFromBase64(base64ImageData, success, failure)

Stores a base64-encoded image in the ImageStore, and returns a URI that can be used to access or display the image later. Images are stored in memory only, and must be manually deleted when you are finished with them by calling removeImageForTag().

Note that it is very inefficient to transfer large quantities of binary data between JS and native code, so you should avoid calling this more than necessary. @platform ios

getBase64ForTag()

static getBase64ForTag(uri, success, failure)

Retrieves the base64-encoded data for an image in the ImageStore. If the specified URI does not match an image in the store, the failure callback will be called.

Note that it is very inefficient to transfer large quantities of binary data between JS and native code, so you should avoid calling this more than necessary. To display an image in the ImageStore, you can pass the URI to an <Image/> component; there is no need to retrieve the base64 data.

Edit this page
Last updated on
- + diff --git a/docs/imagestore/index.html b/docs/imagestore/index.html index ac6ee9fd143..4ce4e3877c4 100644 --- a/docs/imagestore/index.html +++ b/docs/imagestore/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

ImageStore

Deprecated. Use one of the community packages instead.

Methods

Reference

Methods

hasImageForTag()

static hasImageForTag(uri, callback)

Check if the ImageStore contains image data for the specified URI. @platform ios

removeImageForTag()

static removeImageForTag(uri)

Delete an image from the ImageStore. Images are stored in memory and must be manually removed when you are finished with them, otherwise they will continue to use up RAM until the app is terminated. It is safe to call removeImageForTag() without first calling hasImageForTag(), it will fail silently. @platform ios

addImageFromBase64()

static addImageFromBase64(base64ImageData, success, failure)

Stores a base64-encoded image in the ImageStore, and returns a URI that can be used to access or display the image later. Images are stored in memory only, and must be manually deleted when you are finished with them by calling removeImageForTag().

Note that it is very inefficient to transfer large quantities of binary data between JS and native code, so you should avoid calling this more than necessary. @platform ios

getBase64ForTag()

static getBase64ForTag(uri, success, failure)

Retrieves the base64-encoded data for an image in the ImageStore. If the specified URI does not match an image in the store, the failure callback will be called.

Note that it is very inefficient to transfer large quantities of binary data between JS and native code, so you should avoid calling this more than necessary. To display an image in the ImageStore, you can pass the URI to an <Image/> component; there is no need to retrieve the base64 data.

Edit this page
Last updated on
- + diff --git a/docs/improvingux.html b/docs/improvingux.html index 27cb19ccb62..73a88a5167b 100644 --- a/docs/improvingux.html +++ b/docs/improvingux.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Improving User Experience

Configure text inputs

Entering text on touch phone is a challenge - small screen, software keyboard. But based on what kind of data you need, you can make it easier by properly configuring the text inputs:

  • Focus the first field automatically
  • Use placeholder text as an example of expected data format
  • Enable or disable autocapitalization and autocorrect
  • Choose keyboard type (e.g. email, numeric)
  • Make sure the return button focuses the next field or submits the form

Check out TextInput docs for more configuration options.

Try it on your phone

Manage layout when keyboard is visible

Software keyboard takes almost half of the screen. If you have interactive elements that can get covered by the keyboard, make sure they are still accessible by using the KeyboardAvoidingView component.

Try it on your phone

Make tappable areas larger

On mobile phones it's hard to be very precise when pressing buttons. Make sure all interactive elements are 44x44 or larger. One way to do this is to leave enough space for the element, padding, minWidth and minHeight style values can be useful for that. Alternatively, you can use hitSlop prop to increase interactive area without affecting the layout. Here's a demo:

Try it on your phone

Use Android Ripple

Android API 21+ uses the material design ripple to provide user with feedback when they touch an interactable area on the screen. React Native exposes this through the TouchableNativeFeedback component. Using this touchable effect instead of opacity or highlight will often make your app feel much more fitting on the platform. That said, you need to be careful when using it because it doesn't work on iOS or on Android API < 21, so you will need to fallback to using one of the other Touchable components on iOS. You can use a library like react-native-platform-touchable to handle the platform differences for you.

Try it on your phone

Screen orientation lock

Multiple screen orientations should work fine by default unless you're using Dimensions API and don't handle orientation changes. If you don't want to support multiple screen orientations, you can lock the screen orientation to either portrait or landscape.

On iOS, in the General tab and Deployment Info section of Xcode enable the Device Orientation you want to support (ensure you have selected iPhone from the Devices menu when making the changes). For Android, open the AndroidManifest.xml file and within the activity element add 'android:screenOrientation="portrait"' to lock to portrait or 'android:screenOrientation="landscape"' to lock to landscape.

Learn more

Material Design and Human Interface Guidelines are great resources for learning more about designing for mobile platforms.

Edit this page
Last updated on
- + diff --git a/docs/improvingux/index.html b/docs/improvingux/index.html index 27cb19ccb62..73a88a5167b 100644 --- a/docs/improvingux/index.html +++ b/docs/improvingux/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Improving User Experience

Configure text inputs

Entering text on touch phone is a challenge - small screen, software keyboard. But based on what kind of data you need, you can make it easier by properly configuring the text inputs:

  • Focus the first field automatically
  • Use placeholder text as an example of expected data format
  • Enable or disable autocapitalization and autocorrect
  • Choose keyboard type (e.g. email, numeric)
  • Make sure the return button focuses the next field or submits the form

Check out TextInput docs for more configuration options.

Try it on your phone

Manage layout when keyboard is visible

Software keyboard takes almost half of the screen. If you have interactive elements that can get covered by the keyboard, make sure they are still accessible by using the KeyboardAvoidingView component.

Try it on your phone

Make tappable areas larger

On mobile phones it's hard to be very precise when pressing buttons. Make sure all interactive elements are 44x44 or larger. One way to do this is to leave enough space for the element, padding, minWidth and minHeight style values can be useful for that. Alternatively, you can use hitSlop prop to increase interactive area without affecting the layout. Here's a demo:

Try it on your phone

Use Android Ripple

Android API 21+ uses the material design ripple to provide user with feedback when they touch an interactable area on the screen. React Native exposes this through the TouchableNativeFeedback component. Using this touchable effect instead of opacity or highlight will often make your app feel much more fitting on the platform. That said, you need to be careful when using it because it doesn't work on iOS or on Android API < 21, so you will need to fallback to using one of the other Touchable components on iOS. You can use a library like react-native-platform-touchable to handle the platform differences for you.

Try it on your phone

Screen orientation lock

Multiple screen orientations should work fine by default unless you're using Dimensions API and don't handle orientation changes. If you don't want to support multiple screen orientations, you can lock the screen orientation to either portrait or landscape.

On iOS, in the General tab and Deployment Info section of Xcode enable the Device Orientation you want to support (ensure you have selected iPhone from the Devices menu when making the changes). For Android, open the AndroidManifest.xml file and within the activity element add 'android:screenOrientation="portrait"' to lock to portrait or 'android:screenOrientation="landscape"' to lock to landscape.

Learn more

Material Design and Human Interface Guidelines are great resources for learning more about designing for mobile platforms.

Edit this page
Last updated on
- + diff --git a/docs/inputaccessoryview.html b/docs/inputaccessoryview.html index 509766171ea..0862e555998 100644 --- a/docs/inputaccessoryview.html +++ b/docs/inputaccessoryview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

InputAccessoryView

A component which enables customization of the keyboard input accessory view on iOS. The input accessory view is displayed above the keyboard whenever a TextInput has focus. This component can be used to create custom toolbars.

To use this component wrap your custom toolbar with the InputAccessoryView component, and set a nativeID. Then, pass that nativeID as the inputAccessoryViewID of whatever TextInput you desire. A basic example:

This component can also be used to create sticky text inputs (text inputs which are anchored to the top of the keyboard). To do this, wrap a TextInput with the InputAccessoryView component, and don't set a nativeID. For an example, look at InputAccessoryViewExample.js.

Reference

Props

backgroundColor

TypeRequired
colorNo

nativeID

An ID which is used to associate this InputAccessoryView to specified TextInput(s).

TypeRequired
stringNo

style

TypeRequired
styleNo

Known issues

Edit this page
Last updated on
- + diff --git a/docs/inputaccessoryview/index.html b/docs/inputaccessoryview/index.html index 509766171ea..0862e555998 100644 --- a/docs/inputaccessoryview/index.html +++ b/docs/inputaccessoryview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

InputAccessoryView

A component which enables customization of the keyboard input accessory view on iOS. The input accessory view is displayed above the keyboard whenever a TextInput has focus. This component can be used to create custom toolbars.

To use this component wrap your custom toolbar with the InputAccessoryView component, and set a nativeID. Then, pass that nativeID as the inputAccessoryViewID of whatever TextInput you desire. A basic example:

This component can also be used to create sticky text inputs (text inputs which are anchored to the top of the keyboard). To do this, wrap a TextInput with the InputAccessoryView component, and don't set a nativeID. For an example, look at InputAccessoryViewExample.js.

Reference

Props

backgroundColor

TypeRequired
colorNo

nativeID

An ID which is used to associate this InputAccessoryView to specified TextInput(s).

TypeRequired
stringNo

style

TypeRequired
styleNo

Known issues

Edit this page
Last updated on
- + diff --git a/docs/integration-with-existing-apps.html b/docs/integration-with-existing-apps.html index 586804f4452..6b79ed1d906 100644 --- a/docs/integration-with-existing-apps.html +++ b/docs/integration-with-existing-apps.html @@ -19,7 +19,7 @@ - + @@ -48,7 +48,7 @@
if (mReactInstanceManager != null) {
mReactInstanceManager.onHostDestroy(this);
}
if (mReactRootView != null) {
mReactRootView.unmountReactApplication();
}
}

We also need to pass back button events to React Native:

@Override
public void onBackPressed() {
if (mReactInstanceManager != null) {
mReactInstanceManager.onBackPressed();
} else {
super.onBackPressed();
}
}

This allows JavaScript to control what happens when the user presses the hardware back button (e.g. to implement navigation). When JavaScript doesn't handle the back button press, your invokeDefaultOnBackPressed method will be called. By default this finishes your Activity.

Finally, we need to hook up the dev menu. By default, this is activated by (rage) shaking the device, but this is not very useful in emulators. So we make it show when you press the hardware menu button (use Ctrl + M if you're using Android Studio emulator):

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
if (keyCode == KeyEvent.KEYCODE_MENU && mReactInstanceManager != null) {
mReactInstanceManager.showDevOptionsDialog();
return true;
}
return super.onKeyUp(keyCode, event);
}

Now your activity is ready to run some JavaScript code.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ yarn start
2. Run the app

Now build and run your Android app as normal.

Once you reach your React-powered activity inside the app, it should load the JavaScript code from the development server and display:

Screenshot

Creating a release build in Android Studio

You can use Android Studio to create your release builds too! It’s as quick as creating release builds of your previously-existing native Android app. There’s one additional step, which you’ll have to do before every release build. You need to execute the following to create a React Native bundle, which will be included with your native Android app:

$ npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/com/your-company-name/app-package-name/src/main/assets/index.android.bundle --assets-dest android/com/your-company-name/app-package-name/src/main/res/

Don’t forget to replace the paths with correct ones and create the assets folder if it doesn’t exist.

Now, create a release build of your native app from within Android Studio as usual and you should be good to go!

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/integration-with-existing-apps/index.html b/docs/integration-with-existing-apps/index.html index 586804f4452..6b79ed1d906 100644 --- a/docs/integration-with-existing-apps/index.html +++ b/docs/integration-with-existing-apps/index.html @@ -19,7 +19,7 @@ - + @@ -48,7 +48,7 @@
if (mReactInstanceManager != null) {
mReactInstanceManager.onHostDestroy(this);
}
if (mReactRootView != null) {
mReactRootView.unmountReactApplication();
}
}

We also need to pass back button events to React Native:

@Override
public void onBackPressed() {
if (mReactInstanceManager != null) {
mReactInstanceManager.onBackPressed();
} else {
super.onBackPressed();
}
}

This allows JavaScript to control what happens when the user presses the hardware back button (e.g. to implement navigation). When JavaScript doesn't handle the back button press, your invokeDefaultOnBackPressed method will be called. By default this finishes your Activity.

Finally, we need to hook up the dev menu. By default, this is activated by (rage) shaking the device, but this is not very useful in emulators. So we make it show when you press the hardware menu button (use Ctrl + M if you're using Android Studio emulator):

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
if (keyCode == KeyEvent.KEYCODE_MENU && mReactInstanceManager != null) {
mReactInstanceManager.showDevOptionsDialog();
return true;
}
return super.onKeyUp(keyCode, event);
}

Now your activity is ready to run some JavaScript code.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ yarn start
2. Run the app

Now build and run your Android app as normal.

Once you reach your React-powered activity inside the app, it should load the JavaScript code from the development server and display:

Screenshot

Creating a release build in Android Studio

You can use Android Studio to create your release builds too! It’s as quick as creating release builds of your previously-existing native Android app. There’s one additional step, which you’ll have to do before every release build. You need to execute the following to create a React Native bundle, which will be included with your native Android app:

$ npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/com/your-company-name/app-package-name/src/main/assets/index.android.bundle --assets-dest android/com/your-company-name/app-package-name/src/main/res/

Don’t forget to replace the paths with correct ones and create the assets folder if it doesn’t exist.

Now, create a release build of your native app from within Android Studio as usual and you should be good to go!

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/interactionmanager.html b/docs/interactionmanager.html index 6b3a8f58823..39b2ec62cdf 100644 --- a/docs/interactionmanager.html +++ b/docs/interactionmanager.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

InteractionManager

InteractionManager allows long-running work to be scheduled after any interactions/animations have completed. In particular, this allows JavaScript animations to run smoothly.

Applications can schedule tasks to run after interactions with the following:

InteractionManager.runAfterInteractions(() => {
// ...long-running synchronous task...
});

Compare this to other scheduling alternatives:

  • requestAnimationFrame(): for code that animates a view over time.
  • setImmediate/setTimeout(): run code later, note this may delay animations.
  • runAfterInteractions(): run code later, without delaying active animations.

The touch handling system considers one or more active touches to be an 'interaction' and will delay runAfterInteractions() callbacks until all touches have ended or been cancelled.

InteractionManager also allows applications to register animations by creating an interaction 'handle' on animation start, and clearing it upon completion:

var handle = InteractionManager.createInteractionHandle();
// run animation... (`runAfterInteractions` tasks are queued)
// later, on animation completion:
InteractionManager.clearInteractionHandle(handle);
// queued tasks run if all handles were cleared

runAfterInteractions takes either a plain callback function, or a PromiseTask object with a gen method that returns a Promise. If a PromiseTask is supplied, then it is fully resolved (including asynchronous dependencies that also schedule more tasks via runAfterInteractions) before starting on the next task that might have been queued up synchronously earlier.

By default, queued tasks are executed together in a loop in one setImmediate batch. If setDeadline is called with a positive number, then tasks will only be executed until the deadline (in terms of js event loop run time) approaches, at which point execution will yield via setTimeout, allowing events such as touches to start interactions and block queued tasks from executing, making apps more responsive.

Example

Basic

Advanced

Note: InteractionManager.runAfterInteractions() is not working properly on web. It triggers immediately without waiting until the interaction is finished.

Reference

Methods

runAfterInteractions()

static runAfterInteractions(task)

Schedule a function to run after all interactions have completed. Returns a cancellable "promise".

createInteractionHandle()

static createInteractionHandle()

Notify manager that an interaction has started.

clearInteractionHandle()

static clearInteractionHandle(handle)

Notify manager that an interaction has completed.

setDeadline()

static setDeadline(deadline)

A positive number will use setTimeout to schedule any tasks after the eventLoopRunningTime hits the deadline value, otherwise all tasks will be executed in one setImmediate batch (default).

Properties

Edit this page
Last updated on
- + diff --git a/docs/interactionmanager/index.html b/docs/interactionmanager/index.html index 6b3a8f58823..39b2ec62cdf 100644 --- a/docs/interactionmanager/index.html +++ b/docs/interactionmanager/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

InteractionManager

InteractionManager allows long-running work to be scheduled after any interactions/animations have completed. In particular, this allows JavaScript animations to run smoothly.

Applications can schedule tasks to run after interactions with the following:

InteractionManager.runAfterInteractions(() => {
// ...long-running synchronous task...
});

Compare this to other scheduling alternatives:

  • requestAnimationFrame(): for code that animates a view over time.
  • setImmediate/setTimeout(): run code later, note this may delay animations.
  • runAfterInteractions(): run code later, without delaying active animations.

The touch handling system considers one or more active touches to be an 'interaction' and will delay runAfterInteractions() callbacks until all touches have ended or been cancelled.

InteractionManager also allows applications to register animations by creating an interaction 'handle' on animation start, and clearing it upon completion:

var handle = InteractionManager.createInteractionHandle();
// run animation... (`runAfterInteractions` tasks are queued)
// later, on animation completion:
InteractionManager.clearInteractionHandle(handle);
// queued tasks run if all handles were cleared

runAfterInteractions takes either a plain callback function, or a PromiseTask object with a gen method that returns a Promise. If a PromiseTask is supplied, then it is fully resolved (including asynchronous dependencies that also schedule more tasks via runAfterInteractions) before starting on the next task that might have been queued up synchronously earlier.

By default, queued tasks are executed together in a loop in one setImmediate batch. If setDeadline is called with a positive number, then tasks will only be executed until the deadline (in terms of js event loop run time) approaches, at which point execution will yield via setTimeout, allowing events such as touches to start interactions and block queued tasks from executing, making apps more responsive.

Example

Basic

Advanced

Note: InteractionManager.runAfterInteractions() is not working properly on web. It triggers immediately without waiting until the interaction is finished.

Reference

Methods

runAfterInteractions()

static runAfterInteractions(task)

Schedule a function to run after all interactions have completed. Returns a cancellable "promise".

createInteractionHandle()

static createInteractionHandle()

Notify manager that an interaction has started.

clearInteractionHandle()

static clearInteractionHandle(handle)

Notify manager that an interaction has completed.

setDeadline()

static setDeadline(deadline)

A positive number will use setTimeout to schedule any tasks after the eventLoopRunningTime hits the deadline value, otherwise all tasks will be executed in one setImmediate batch (default).

Properties

Edit this page
Last updated on
- + diff --git a/docs/intro-react-native-components.html b/docs/intro-react-native-components.html index 1bbe718fb1b..6a3baf8bf15 100644 --- a/docs/intro-react-native-components.html +++ b/docs/intro-react-native-components.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Core Components and Native Components

React Native is an open source framework for building Android and iOS applications using React and the app platform’s native capabilities. With React Native, you use JavaScript to access your platform’s APIs as well as to describe the appearance and behavior of your UI using React components: bundles of reusable, nestable code. You can learn more about React in the next section. But first, let’s cover how components work in React Native.

Views and mobile development

In Android and iOS development, a view is the basic building block of UI: a small rectangular element on the screen which can be used to display text, images, or respond to user input. Even the smallest visual elements of an app, like a line of text or a button, are kinds of views. Some kinds of views can contain other views. It’s views all the way down!

Diagram of Android and iOS app showing them both built on top of atomic elements called views.
Just a sampling of the many views used in Android and iOS apps.

Native Components

In Android development, you write views in Kotlin or Java; in iOS development, you use Swift or Objective-C. With React Native, you can invoke these views with JavaScript using React components. At runtime, React Native creates the corresponding Android and iOS views for those components. Because React Native components are backed by the same views as Android and iOS, React Native apps look, feel, and perform like any other apps. We call these platform-backed components Native Components.

React Native lets you build your own Native Components for Android and iOS to suit your app’s unique needs. We also have a thriving ecosystem of these community-contributed components. Check out Native Directory to find what the community has been creating.

React Native also includes a set of essential, ready-to-use Native Components you can use to start building your app today. These are React Native's Core Components.

Core Components

React Native has many Core Components for everything from form controls to activity indicators. You can find them all documented in the API section. You will mostly work with the following Core Components:

React Native UI ComponentAndroid ViewiOS ViewWeb AnalogDescription
<View><ViewGroup><UIView>A non-scrollling <div>A container that supports layout with flexbox, style, some touch handling, and accessibility controls
<Text><TextView><UITextView><p>Displays, styles, and nests strings of text and even handles touch events
<Image><ImageView><UIImageView><img>Displays different types of images
<ScrollView><ScrollView><UIScrollView><div>A generic scrolling container that can contain multiple components and views
<TextInput><EditText><UITextField><input type="text">Allows the user to enter text

In the next section, you will start combining these Core Components to learn about how React works. Have a play with them here now!

Because React Native uses the same API structure as React components, you’ll need to understand React component APIs to get started. The next section makes for a quick introduction or refresher on the topic. However, if you’re already familiar with React, feel free to skip ahead.

A diagram showing React Native's Core Components are a subset of React Components that ship with React Native.
Edit this page
Last updated on
- + diff --git a/docs/intro-react-native-components/index.html b/docs/intro-react-native-components/index.html index 1bbe718fb1b..6a3baf8bf15 100644 --- a/docs/intro-react-native-components/index.html +++ b/docs/intro-react-native-components/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Core Components and Native Components

React Native is an open source framework for building Android and iOS applications using React and the app platform’s native capabilities. With React Native, you use JavaScript to access your platform’s APIs as well as to describe the appearance and behavior of your UI using React components: bundles of reusable, nestable code. You can learn more about React in the next section. But first, let’s cover how components work in React Native.

Views and mobile development

In Android and iOS development, a view is the basic building block of UI: a small rectangular element on the screen which can be used to display text, images, or respond to user input. Even the smallest visual elements of an app, like a line of text or a button, are kinds of views. Some kinds of views can contain other views. It’s views all the way down!

Diagram of Android and iOS app showing them both built on top of atomic elements called views.
Just a sampling of the many views used in Android and iOS apps.

Native Components

In Android development, you write views in Kotlin or Java; in iOS development, you use Swift or Objective-C. With React Native, you can invoke these views with JavaScript using React components. At runtime, React Native creates the corresponding Android and iOS views for those components. Because React Native components are backed by the same views as Android and iOS, React Native apps look, feel, and perform like any other apps. We call these platform-backed components Native Components.

React Native lets you build your own Native Components for Android and iOS to suit your app’s unique needs. We also have a thriving ecosystem of these community-contributed components. Check out Native Directory to find what the community has been creating.

React Native also includes a set of essential, ready-to-use Native Components you can use to start building your app today. These are React Native's Core Components.

Core Components

React Native has many Core Components for everything from form controls to activity indicators. You can find them all documented in the API section. You will mostly work with the following Core Components:

React Native UI ComponentAndroid ViewiOS ViewWeb AnalogDescription
<View><ViewGroup><UIView>A non-scrollling <div>A container that supports layout with flexbox, style, some touch handling, and accessibility controls
<Text><TextView><UITextView><p>Displays, styles, and nests strings of text and even handles touch events
<Image><ImageView><UIImageView><img>Displays different types of images
<ScrollView><ScrollView><UIScrollView><div>A generic scrolling container that can contain multiple components and views
<TextInput><EditText><UITextField><input type="text">Allows the user to enter text

In the next section, you will start combining these Core Components to learn about how React works. Have a play with them here now!

Because React Native uses the same API structure as React components, you’ll need to understand React component APIs to get started. The next section makes for a quick introduction or refresher on the topic. However, if you’re already familiar with React, feel free to skip ahead.

A diagram showing React Native's Core Components are a subset of React Components that ship with React Native.
Edit this page
Last updated on
- + diff --git a/docs/intro-react.html b/docs/intro-react.html index ebc1690dd6e..e55311617c8 100644 --- a/docs/intro-react.html +++ b/docs/intro-react.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
export default Cat;

This is one of many ways to export your component. This kind of export works well with the Snack Player. However, depending on your app’s file structure, you might need to use a different convention. This handy cheatsheet on JavaScript imports and exports can help.

Now take a closer look at that return statement. <Text>Hello, I am your cat!</Text> is using a kind of JavaScript syntax that makes writing elements convenient: JSX.

JSX

React and React Native use JSX, a syntax that lets you write elements inside JavaScript like so: <Text>Hello, I am your cat!</Text>. The React docs have a comprehensive guide to JSX you can reference to learn even more. Because JSX is JavaScript, you can use variables inside it. Here you are declaring a name for the cat, name, and embedding it with curly braces inside <Text>.

Any JavaScript expression will work between curly braces, including function calls like {getFullName("Rum", "Tum", "Tugger")}:

You can think of curly braces as creating a portal into JS functionality in your JSX!

Because JSX is included in the React library, it won’t work if you don’t have import React from 'react' at the top of your file!

Custom Components

You’ve already met React Native’s Core Components. React lets you nest these components inside each other to create new components. These nestable, reusable components are at the heart of the React paradigm.

For example, you can nest Text and TextInput inside a View below, and React Native will render them together:

If you’re familiar with web development, <View> and <Text> might remind you of HTML! You can think of them as the <div> and <p> tags of application development.

You can render this component multiple times and multiple places without repeating your code by using <Cat>:

Any component that renders other components is a parent component. Here, Cafe is the parent component and each Cat is a child component.

You can put as many cats in your cafe as you like. Each <Cat> renders a unique element—which you can customize with props.

Props

Props is short for “properties.” Props let you customize React components. For example, here you pass each <Cat> a different name for Cat to render:

Most of React Native’s Core Components can be customized with props, too. For example, when using Image, you pass it a prop named source to define what image it shows:

Image has many different props, including style, which accepts a JS object of design and layout related property-value pairs.

Notice the double curly braces {{ }} surrounding style‘s width and height. In JSX, JavaScript values are referenced with {}. This is handy if you are passing something other than a string as props, like an array or number: <Cat food={["fish", "kibble"]} age={2} />. However, JS objects are also denoted with curly braces: {width: 200, height: 200}. Therefore, to pass a JS object in JSX, you must wrap the object in another pair of curly braces: {{width: 200, height: 200}}

You can build many things with props and the Core Components Text, Image, and View! But to build something interactive, you’ll need state.

State

While you can think of props as arguments you use to configure how components render, state is like a component’s personal data storage. State is useful for handling data that changes over time or that comes from user interaction. State gives your components memory!

As a general rule, use props to configure a component when it renders. Use state to keep track of any component data that you expect to change over time.

The following example takes place in a cat cafe where two hungry cats are waiting to be fed. Their hunger, which we expect to change over time (unlike their names), is stored as state. To feed the cats, press their buttons—which will update their state.

You can add state to a component by calling React’s useState Hook. A Hook is a kind of function that lets you “hook into” React features. For example, useState is a Hook that lets you add state to function components. You can learn more about other kinds of Hooks in the React documentation.

First, you will want to import useState from React like so:

import React, { useState } from 'react';

Then you declare the component’s state by calling useState inside its function. In this example, useState creates an isHungry state variable:

const Cat = (props) => {
const [isHungry, setIsHungry] = useState(true);
// ...
};

You can use useState to track any kind of data: strings, numbers, Booleans, arrays, objects. For example, you can track the number of times a cat has been petted with const [timesPetted, setTimesPetted] = useState(0)!

Calling useState does two things:

  • it creates a “state variable” with an initial value—in this case the state variable is isHungry and its initial value is true
  • it creates a function to set that state variable’s value—setIsHungry

It doesn’t matter what names you use. But it can be handy to think of the pattern as [<getter>, <setter>] = useState(<initialValue>).

Next you add the Button Core Component and give it an onPress prop:

<Button
onPress={() => {
setIsHungry(false);
}}
//..
/>

Now, when someone presses the button, onPress will fire, calling the setIsHungry(false). This sets the state variable isHungry to false. When isHungry is false, the Button’s disabled prop is set to true and its title also changes:

<Button
//..
disabled={!isHungry}
title={isHungry ? 'Pour me some milk, please!' : 'Thank you!'}
/>

You might’ve noticed that although isHungry is a const, it is seemingly reassignable! What is happening is when a state-setting function like setIsHungry is called, its component will re-render. In this case the Cat function will run again—and this time, useState will give us the next value of isHungry.

Finally, put your cats inside a Cafe component:

const Cafe = () => {
return (
<>
<Cat name="Munkustrap" />
<Cat name="Spot" />
</>
);
};

See the <> and </> above? These bits of JSX are fragments. Adjacent JSX elements must be wrapped in an enclosing tag. Fragments let you do that without nesting an extra, unnecessary wrapping element like View.

Now that you’ve covered both React and React Native’s Core Components, let’s dive deeper on some of these core components by looking at handling <TextInput>.

Edit this page
Last updated on
- + diff --git a/docs/intro-react/index.html b/docs/intro-react/index.html index ebc1690dd6e..e55311617c8 100644 --- a/docs/intro-react/index.html +++ b/docs/intro-react/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
export default Cat;

This is one of many ways to export your component. This kind of export works well with the Snack Player. However, depending on your app’s file structure, you might need to use a different convention. This handy cheatsheet on JavaScript imports and exports can help.

Now take a closer look at that return statement. <Text>Hello, I am your cat!</Text> is using a kind of JavaScript syntax that makes writing elements convenient: JSX.

JSX

React and React Native use JSX, a syntax that lets you write elements inside JavaScript like so: <Text>Hello, I am your cat!</Text>. The React docs have a comprehensive guide to JSX you can reference to learn even more. Because JSX is JavaScript, you can use variables inside it. Here you are declaring a name for the cat, name, and embedding it with curly braces inside <Text>.

Any JavaScript expression will work between curly braces, including function calls like {getFullName("Rum", "Tum", "Tugger")}:

You can think of curly braces as creating a portal into JS functionality in your JSX!

Because JSX is included in the React library, it won’t work if you don’t have import React from 'react' at the top of your file!

Custom Components

You’ve already met React Native’s Core Components. React lets you nest these components inside each other to create new components. These nestable, reusable components are at the heart of the React paradigm.

For example, you can nest Text and TextInput inside a View below, and React Native will render them together:

If you’re familiar with web development, <View> and <Text> might remind you of HTML! You can think of them as the <div> and <p> tags of application development.

You can render this component multiple times and multiple places without repeating your code by using <Cat>:

Any component that renders other components is a parent component. Here, Cafe is the parent component and each Cat is a child component.

You can put as many cats in your cafe as you like. Each <Cat> renders a unique element—which you can customize with props.

Props

Props is short for “properties.” Props let you customize React components. For example, here you pass each <Cat> a different name for Cat to render:

Most of React Native’s Core Components can be customized with props, too. For example, when using Image, you pass it a prop named source to define what image it shows:

Image has many different props, including style, which accepts a JS object of design and layout related property-value pairs.

Notice the double curly braces {{ }} surrounding style‘s width and height. In JSX, JavaScript values are referenced with {}. This is handy if you are passing something other than a string as props, like an array or number: <Cat food={["fish", "kibble"]} age={2} />. However, JS objects are also denoted with curly braces: {width: 200, height: 200}. Therefore, to pass a JS object in JSX, you must wrap the object in another pair of curly braces: {{width: 200, height: 200}}

You can build many things with props and the Core Components Text, Image, and View! But to build something interactive, you’ll need state.

State

While you can think of props as arguments you use to configure how components render, state is like a component’s personal data storage. State is useful for handling data that changes over time or that comes from user interaction. State gives your components memory!

As a general rule, use props to configure a component when it renders. Use state to keep track of any component data that you expect to change over time.

The following example takes place in a cat cafe where two hungry cats are waiting to be fed. Their hunger, which we expect to change over time (unlike their names), is stored as state. To feed the cats, press their buttons—which will update their state.

You can add state to a component by calling React’s useState Hook. A Hook is a kind of function that lets you “hook into” React features. For example, useState is a Hook that lets you add state to function components. You can learn more about other kinds of Hooks in the React documentation.

First, you will want to import useState from React like so:

import React, { useState } from 'react';

Then you declare the component’s state by calling useState inside its function. In this example, useState creates an isHungry state variable:

const Cat = (props) => {
const [isHungry, setIsHungry] = useState(true);
// ...
};

You can use useState to track any kind of data: strings, numbers, Booleans, arrays, objects. For example, you can track the number of times a cat has been petted with const [timesPetted, setTimesPetted] = useState(0)!

Calling useState does two things:

  • it creates a “state variable” with an initial value—in this case the state variable is isHungry and its initial value is true
  • it creates a function to set that state variable’s value—setIsHungry

It doesn’t matter what names you use. But it can be handy to think of the pattern as [<getter>, <setter>] = useState(<initialValue>).

Next you add the Button Core Component and give it an onPress prop:

<Button
onPress={() => {
setIsHungry(false);
}}
//..
/>

Now, when someone presses the button, onPress will fire, calling the setIsHungry(false). This sets the state variable isHungry to false. When isHungry is false, the Button’s disabled prop is set to true and its title also changes:

<Button
//..
disabled={!isHungry}
title={isHungry ? 'Pour me some milk, please!' : 'Thank you!'}
/>

You might’ve noticed that although isHungry is a const, it is seemingly reassignable! What is happening is when a state-setting function like setIsHungry is called, its component will re-render. In this case the Cat function will run again—and this time, useState will give us the next value of isHungry.

Finally, put your cats inside a Cafe component:

const Cafe = () => {
return (
<>
<Cat name="Munkustrap" />
<Cat name="Spot" />
</>
);
};

See the <> and </> above? These bits of JSX are fragments. Adjacent JSX elements must be wrapped in an enclosing tag. Fragments let you do that without nesting an extra, unnecessary wrapping element like View.

Now that you’ve covered both React and React Native’s Core Components, let’s dive deeper on some of these core components by looking at handling <TextInput>.

Edit this page
Last updated on
- + diff --git a/docs/javascript-environment.html b/docs/javascript-environment.html index a5db6e76cf5..0a3de144fbb 100644 --- a/docs/javascript-environment.html +++ b/docs/javascript-environment.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

JavaScript Environment

JavaScript Runtime

When using React Native, you're going to be running your JavaScript code in two environments:

  • In most cases, React Native will use JavaScriptCore, the JavaScript engine that powers Safari. Note that on iOS, JavaScriptCore does not use JIT due to the absence of writable executable memory in iOS apps.
  • When using Chrome debugging, all JavaScript code runs within Chrome itself, communicating with native code via WebSockets. Chrome uses V8 as its JavaScript engine.

While both environments are very similar, you may end up hitting some inconsistencies. We're likely going to experiment with other JavaScript engines in the future, so it's best to avoid relying on specifics of any runtime.

JavaScript Syntax Transformers

Syntax transformers make writing code more enjoyable by allowing you to use new JavaScript syntax without having to wait for support on all interpreters.

React Native ships with the Babel JavaScript compiler. Check Babel documentation on its supported transformations for more details.

A full list of React Native's enabled transformations can be found in metro-react-native-babel-preset.

ES5

  • Reserved Words: promise.catch(function() { });

ES6

ES8

Stage 3

Specific

  • JSX: <View style={{color: 'red'}} />
  • Flow: function foo(x: ?number): string {};
  • TypeScript: function foo(x: number | undefined): string {};
  • Babel Template: allows AST templating

Polyfills

Many standards functions are also available on all the supported JavaScript runtimes.

Browser

ES6

ES7

ES8

Specific

  • __DEV__
Edit this page
Last updated on
- + diff --git a/docs/javascript-environment/index.html b/docs/javascript-environment/index.html index a5db6e76cf5..0a3de144fbb 100644 --- a/docs/javascript-environment/index.html +++ b/docs/javascript-environment/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

JavaScript Environment

JavaScript Runtime

When using React Native, you're going to be running your JavaScript code in two environments:

  • In most cases, React Native will use JavaScriptCore, the JavaScript engine that powers Safari. Note that on iOS, JavaScriptCore does not use JIT due to the absence of writable executable memory in iOS apps.
  • When using Chrome debugging, all JavaScript code runs within Chrome itself, communicating with native code via WebSockets. Chrome uses V8 as its JavaScript engine.

While both environments are very similar, you may end up hitting some inconsistencies. We're likely going to experiment with other JavaScript engines in the future, so it's best to avoid relying on specifics of any runtime.

JavaScript Syntax Transformers

Syntax transformers make writing code more enjoyable by allowing you to use new JavaScript syntax without having to wait for support on all interpreters.

React Native ships with the Babel JavaScript compiler. Check Babel documentation on its supported transformations for more details.

A full list of React Native's enabled transformations can be found in metro-react-native-babel-preset.

ES5

  • Reserved Words: promise.catch(function() { });

ES6

ES8

Stage 3

Specific

  • JSX: <View style={{color: 'red'}} />
  • Flow: function foo(x: ?number): string {};
  • TypeScript: function foo(x: number | undefined): string {};
  • Babel Template: allows AST templating

Polyfills

Many standards functions are also available on all the supported JavaScript runtimes.

Browser

ES6

ES7

ES8

Specific

  • __DEV__
Edit this page
Last updated on
- + diff --git a/docs/keyboard.html b/docs/keyboard.html index e0fc091f285..4449e4b9eac 100644 --- a/docs/keyboard.html +++ b/docs/keyboard.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Keyboard

Keyboard module to control keyboard events.

Usage

The Keyboard module allows you to listen for native events and react to them, as well as make changes to the keyboard, like dismissing it.

Reference

Methods

addListener()

static addListener(eventName, callback)

The addListener function connects a JavaScript function to an identified native keyboard notification event.

This function then returns the reference to the listener.

Parameters:

NameTypeRequiredDescription
eventNamestringYesThe nativeEvent is the string that identifies the event you're listening for. See below
callbackfunctionYesThe function to be called when the event fires

nativeEvent

This can be any of the following

  • keyboardWillShow
  • keyboardDidShow
  • keyboardWillHide
  • keyboardDidHide
  • keyboardWillChangeFrame
  • keyboardDidChangeFrame

Note that if you set android:windowSoftInputMode to adjustResize or adjustPan, only keyboardDidShow and keyboardDidHide events will be available on Android. If you set android:windowSoftInputMode to adjustNothing, no events will be available on Android. keyboardWillShow as well as keyboardWillHide are generally not available on Android since there is no native corresponding event.

removeListener()

static removeListener(eventName, callback)

Removes a specific listener.

Parameters:

NameTypeRequiredDescription
eventNamestringYesThe nativeEvent is the string that identifies the event you're listening for
callbackfunctionYesThe function to be called when the event fires

removeAllListeners()

static removeAllListeners(eventName)

Removes all listeners for a specific event type.

Parameters:

NameTypeRequiredDescription
eventTypestringYesThe native event string listeners are watching which will be removed

dismiss()

static dismiss()

Dismisses the active keyboard and removes focus.

scheduleLayoutAnimation

static scheduleLayoutAnimation(event)

Useful for syncing TextInput (or other keyboard accessory view) size of position changes with keyboard movements.

Edit this page
Last updated on
- + diff --git a/docs/keyboard/index.html b/docs/keyboard/index.html index e0fc091f285..4449e4b9eac 100644 --- a/docs/keyboard/index.html +++ b/docs/keyboard/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Keyboard

Keyboard module to control keyboard events.

Usage

The Keyboard module allows you to listen for native events and react to them, as well as make changes to the keyboard, like dismissing it.

Reference

Methods

addListener()

static addListener(eventName, callback)

The addListener function connects a JavaScript function to an identified native keyboard notification event.

This function then returns the reference to the listener.

Parameters:

NameTypeRequiredDescription
eventNamestringYesThe nativeEvent is the string that identifies the event you're listening for. See below
callbackfunctionYesThe function to be called when the event fires

nativeEvent

This can be any of the following

  • keyboardWillShow
  • keyboardDidShow
  • keyboardWillHide
  • keyboardDidHide
  • keyboardWillChangeFrame
  • keyboardDidChangeFrame

Note that if you set android:windowSoftInputMode to adjustResize or adjustPan, only keyboardDidShow and keyboardDidHide events will be available on Android. If you set android:windowSoftInputMode to adjustNothing, no events will be available on Android. keyboardWillShow as well as keyboardWillHide are generally not available on Android since there is no native corresponding event.

removeListener()

static removeListener(eventName, callback)

Removes a specific listener.

Parameters:

NameTypeRequiredDescription
eventNamestringYesThe nativeEvent is the string that identifies the event you're listening for
callbackfunctionYesThe function to be called when the event fires

removeAllListeners()

static removeAllListeners(eventName)

Removes all listeners for a specific event type.

Parameters:

NameTypeRequiredDescription
eventTypestringYesThe native event string listeners are watching which will be removed

dismiss()

static dismiss()

Dismisses the active keyboard and removes focus.

scheduleLayoutAnimation

static scheduleLayoutAnimation(event)

Useful for syncing TextInput (or other keyboard accessory view) size of position changes with keyboard movements.

Edit this page
Last updated on
- + diff --git a/docs/keyboardavoidingview.html b/docs/keyboardavoidingview.html index 342cf0f96b5..7b4a7ca04ea 100644 --- a/docs/keyboardavoidingview.html +++ b/docs/keyboardavoidingview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

KeyboardAvoidingView

It is a component to solve the common problem of views that need to move out of the way of the virtual keyboard. It can automatically adjust either its height, position, or bottom padding based on the keyboard height.

Example

Reference

Props

Inherits View Props.

behavior

Specify how to react to the presence of the keyboard.

Android and iOS both interact with this prop differently. On both iOS and Android, setting behavior is recommended.

TypeRequired
enum('height', 'position', 'padding')No

contentContainerStyle

The style of the content container(View) when behavior is 'position'.

TypeRequired
View.styleNo

enabled

Enabled or disabled KeyboardAvoidingView. The default is true.

TypeRequired
booleanNo

keyboardVerticalOffset

This is the distance between the top of the user screen and the react native view, may be non-zero in some use cases. Defaults to 0.

TypeRequired
numberNo
Edit this page
Last updated on
- + diff --git a/docs/keyboardavoidingview/index.html b/docs/keyboardavoidingview/index.html index 342cf0f96b5..7b4a7ca04ea 100644 --- a/docs/keyboardavoidingview/index.html +++ b/docs/keyboardavoidingview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

KeyboardAvoidingView

It is a component to solve the common problem of views that need to move out of the way of the virtual keyboard. It can automatically adjust either its height, position, or bottom padding based on the keyboard height.

Example

Reference

Props

Inherits View Props.

behavior

Specify how to react to the presence of the keyboard.

Android and iOS both interact with this prop differently. On both iOS and Android, setting behavior is recommended.

TypeRequired
enum('height', 'position', 'padding')No

contentContainerStyle

The style of the content container(View) when behavior is 'position'.

TypeRequired
View.styleNo

enabled

Enabled or disabled KeyboardAvoidingView. The default is true.

TypeRequired
booleanNo

keyboardVerticalOffset

This is the distance between the top of the user screen and the react native view, may be non-zero in some use cases. Defaults to 0.

TypeRequired
numberNo
Edit this page
Last updated on
- + diff --git a/docs/layout-props.html b/docs/layout-props.html index 64077e61f25..11076b4312c 100644 --- a/docs/layout-props.html +++ b/docs/layout-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Layout Props

More detailed examples about those properties can be found on the Layout with Flexbox page.

Example

The following example shows how different properties can affect or shape a React Native layout. You can try for example to add or remove squares from the UI while changing the values of the property flexWrap.

Reference

Props

alignContent

alignContent controls how rows align in the cross direction, overriding the alignContent of the parent. See https://developer.mozilla.org/en-US/docs/Web/CSS/align-content for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'stretch', 'space-between', 'space-around')No

alignItems

alignItems aligns children in the cross direction. For example, if children are flowing vertically, alignItems controls how they align horizontally. It works like align-items in CSS (default: stretch). See https://developer.mozilla.org/en-US/docs/Web/CSS/align-items for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'stretch', 'baseline')No

alignSelf

alignSelf controls how a child aligns in the cross direction, overriding the alignItems of the parent. It works like align-self in CSS (default: auto). See https://developer.mozilla.org/en-US/docs/Web/CSS/align-self for more details.

TypeRequired
enum('auto', 'flex-start', 'flex-end', 'center', 'stretch', 'baseline')No

aspectRatio

Aspect ratio controls the size of the undefined dimension of a node. Aspect ratio is a non-standard property only available in React Native and not CSS.

  • On a node with a set width/height, aspect ratio controls the size of the unset dimension
  • On a node with a set flex basis, aspect ratio controls the size of the node in the cross axis if unset
  • On a node with a measure function, aspect ratio works as though the measure function measures the flex basis
  • On a node with flex grow/shrink, aspect ratio controls the size of the node in the cross axis if unset
  • Aspect ratio takes min/max dimensions into account
TypeRequired
numberNo

borderBottomWidth

borderBottomWidth works like border-bottom-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-width for more details.

TypeRequired
numberNo

borderEndWidth

When direction is ltr, borderEndWidth is equivalent to borderRightWidth. When direction is rtl, borderEndWidth is equivalent to borderLeftWidth.

TypeRequired
numberNo

borderLeftWidth

borderLeftWidth works like border-left-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-left-width for more details.

TypeRequired
numberNo

borderRightWidth

borderRightWidth works like border-right-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-right-width for more details.

TypeRequired
numberNo

borderStartWidth

When direction is ltr, borderStartWidth is equivalent to borderLeftWidth. When direction is rtl, borderStartWidth is equivalent to borderRightWidth.

TypeRequired
numberNo

borderTopWidth

borderTopWidth works like border-top-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-top-width for more details.

TypeRequired
numberNo

borderWidth

borderWidth works like border-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-width for more details.

TypeRequired
numberNo

bottom

bottom is the number of logical pixels to offset the bottom edge of this component.

It works similarly to bottom in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/bottom for more details of how bottom affects layout.

TypeRequired
number, stringNo

direction

direction specifies the directional flow of the user interface. The default is inherit, except for root node which will have value based on the current locale. See https://yogalayout.com/docs/layout-direction for more details.

TypeRequiredPlatform
enum('inherit', 'ltr', 'rtl')NoiOS

display

display sets the display type of this component.

It works similarly to display in CSS but only supports 'flex' and 'none'. 'flex' is the default.

TypeRequired
enum('none', 'flex')No

end

When the direction is ltr, end is equivalent to right. When the direction is rtl, end is equivalent to left.

This style takes precedence over the left and right styles.

TypeRequired
number, stringNo

flex

In React Native flex does not work the same way that it does in CSS. flex is a number rather than a string, and it works according to the Yoga layout engine.

When flex is a positive number, it makes the component flexible, and it will be sized proportional to its flex value. So a component with flex set to 2 will take twice the space as a component with flex set to 1. flex: <positive number> equates to flexGrow: <positive number>, flexShrink: 1, flexBasis: 0.

When flex is 0, the component is sized according to width and height, and it is inflexible.

When flex is -1, the component is normally sized according to width and height. However, if there's not enough space, the component will shrink to its minWidth and minHeight.

flexGrow, flexShrink, and flexBasis work the same as in CSS.

TypeRequired
numberNo

flexBasis

flexBasis is an axis-independent way of providing the default size of an item along the main axis. Setting the flexBasis of a child is similar to setting the width of that child if its parent is a container with flexDirection: row or setting the height of a child if its parent is a container with flexDirection: column. The flexBasis of an item is the default size of that item, the size of the item before any flexGrow and flexShrink calculations are performed.

TypeRequired
number, stringNo

flexDirection

flexDirection controls which directions children of a container go. row goes left to right, column goes top to bottom, and you may be able to guess what the other two do. It works like flex-direction in CSS, except the default is column. See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction for more details.

TypeRequired
enum('row', 'row-reverse', 'column', 'column-reverse')No

flexGrow

flexGrow describes how any space within a container should be distributed among its children along the main axis. After laying out its children, a container will distribute any remaining space according to the flex grow values specified by its children.

flexGrow accepts any floating point value >= 0, with 0 being the default value. A container will distribute any remaining space among its children weighted by the children’s flexGrow values.

TypeRequired
numberNo

flexShrink

flexShrink describes how to shrink children along the main axis in the case in which the total size of the children overflows the size of the container on the main axis. flexShrink is very similar to flexGrow and can be thought of in the same way if any overflowing size is considered to be negative remaining space. These two properties also work well together by allowing children to grow and shrink as needed.

flexShrink accepts any floating point value >= 0, with 1 being the default value. A container will shrink its children weighted by the children’s flexShrink values.

TypeRequired
numberNo

flexWrap

flexWrap controls whether children can wrap around after they hit the end of a flex container. It works like flex-wrap in CSS (default: nowrap). See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-wrap for more details. Note it does not work anymore with alignItems: stretch (the default), so you may want to use alignItems: flex-start for example (breaking change details: https://github.com/facebook/react-native/releases/tag/v0.28.0).

TypeRequired
enum('wrap', 'nowrap', 'wrap-reverse')No

height

height sets the height of this component.

It works similarly to height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported. See https://developer.mozilla.org/en-US/docs/Web/CSS/height for more details.

TypeRequired
number, stringNo

justifyContent

justifyContent aligns children in the main direction. For example, if children are flowing vertically, justifyContent controls how they align vertically. It works like justify-content in CSS (default: flex-start). See https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'space-between', 'space-around', 'space-evenly')No

left

left is the number of logical pixels to offset the left edge of this component.

It works similarly to left in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/left for more details of how left affects layout.

TypeRequired
number, stringNo

margin

Setting margin has the same effect as setting each of marginTop, marginLeft, marginBottom, and marginRight. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin for more details.

TypeRequired
number, stringNo

marginBottom

marginBottom works like margin-bottom in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-bottom for more details.

TypeRequired
number, stringNo

marginEnd

When direction is ltr, marginEnd is equivalent to marginRight. When direction is rtl, marginEnd is equivalent to marginLeft.

TypeRequired
number, stringNo

marginHorizontal

Setting marginHorizontal has the same effect as setting both marginLeft and marginRight.

TypeRequired
number, stringNo

marginLeft

marginLeft works like margin-left in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-left for more details.

TypeRequired
number, stringNo

marginRight

marginRight works like margin-right in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-right for more details.

TypeRequired
number, stringNo

marginStart

When direction is ltr, marginStart is equivalent to marginLeft. When direction is rtl, marginStart is equivalent to marginRight.

TypeRequired
number, stringNo

marginTop

marginTop works like margin-top in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-top for more details.

TypeRequired
number, stringNo

marginVertical

Setting marginVertical has the same effect as setting both marginTop and marginBottom.

TypeRequired
number, stringNo

maxHeight

maxHeight is the maximum height for this component, in logical pixels.

It works similarly to max-height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/max-height for more details.

TypeRequired
number, stringNo

maxWidth

maxWidth is the maximum width for this component, in logical pixels.

It works similarly to max-width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/max-width for more details.

TypeRequired
number, stringNo

minHeight

minHeight is the minimum height for this component, in logical pixels.

It works similarly to min-height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/min-height for more details.

TypeRequired
number, stringNo

minWidth

minWidth is the minimum width for this component, in logical pixels.

It works similarly to min-width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/min-width for more details.

TypeRequired
number, stringNo

overflow

overflow controls how children are measured and displayed. overflow: hidden causes views to be clipped while overflow: scroll causes views to be measured independently of their parents' main axis. It works like overflow in CSS (default: visible). See https://developer.mozilla.org/en/docs/Web/CSS/overflow for more details.

TypeRequired
enum('visible', 'hidden', 'scroll')No

padding

Setting padding has the same effect as setting each of paddingTop, paddingBottom, paddingLeft, and paddingRight. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding for more details.

TypeRequired
number, stringNo

paddingBottom

paddingBottom works like padding-bottom in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-bottom for more details.

TypeRequired
number, stringNo

paddingEnd

When direction is ltr, paddingEnd is equivalent to paddingRight. When direction is rtl, paddingEnd is equivalent to paddingLeft.

TypeRequired
number, stringNo

paddingHorizontal

Setting paddingHorizontal is like setting both of paddingLeft and paddingRight.

TypeRequired
number, stringNo

paddingLeft

paddingLeft works like padding-left in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-left for more details.

TypeRequired
number, stringNo

paddingRight

paddingRight works like padding-right in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-right for more details.

TypeRequired
number, stringNo

paddingStart

When direction is ltr, paddingStart is equivalent to paddingLeft. When direction is rtl, paddingStart is equivalent to paddingRight.

TypeRequired
number, stringNo

paddingTop

paddingTop works like padding-top in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-top for more details.

TypeRequired
number, ,stringNo

paddingVertical

Setting paddingVertical is like setting both of paddingTop and paddingBottom.

TypeRequired
number, stringNo

position

position in React Native is similar to regular CSS, but everything is set to relative by default, so absolute positioning is always relative to the parent.

If you want to position a child using specific numbers of logical pixels relative to its parent, set the child to have absolute position.

If you want to position a child relative to something that is not its parent, don't use styles for that. Use the component tree.

See https://github.com/facebook/yoga for more details on how position differs between React Native and CSS.

TypeRequired
enum('absolute', 'relative')No

right

right is the number of logical pixels to offset the right edge of this component.

It works similarly to right in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/right for more details of how right affects layout.

TypeRequired
number, stringNo

start

When the direction is ltr, start is equivalent to left. When the direction is rtl, start is equivalent to right.

This style takes precedence over the left, right, and end styles.

TypeRequired
number, stringNo

top

top is the number of logical pixels to offset the top edge of this component.

It works similarly to top in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/top for more details of how top affects layout.

TypeRequired
number, stringNo

width

width sets the width of this component.

It works similarly to width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported. See https://developer.mozilla.org/en-US/docs/Web/CSS/width for more details.

TypeRequired
number, stringNo

zIndex

zIndex controls which components display on top of others. Normally, you don't use zIndex. Components render according to their order in the document tree, so later components draw over earlier ones. zIndex may be useful if you have animations or custom modal interfaces where you don't want this behavior.

It works like the CSS z-index property - components with a larger zIndex will render on top. Think of the z-direction like it's pointing from the phone into your eyeball. See https://developer.mozilla.org/en-US/docs/Web/CSS/z-index for more details.

On iOS, zIndex may require Views to be siblings of each other for it to work as expected.

TypeRequired
numberNo
Edit this page
Last updated on
- + diff --git a/docs/layout-props/index.html b/docs/layout-props/index.html index 64077e61f25..11076b4312c 100644 --- a/docs/layout-props/index.html +++ b/docs/layout-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Layout Props

More detailed examples about those properties can be found on the Layout with Flexbox page.

Example

The following example shows how different properties can affect or shape a React Native layout. You can try for example to add or remove squares from the UI while changing the values of the property flexWrap.

Reference

Props

alignContent

alignContent controls how rows align in the cross direction, overriding the alignContent of the parent. See https://developer.mozilla.org/en-US/docs/Web/CSS/align-content for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'stretch', 'space-between', 'space-around')No

alignItems

alignItems aligns children in the cross direction. For example, if children are flowing vertically, alignItems controls how they align horizontally. It works like align-items in CSS (default: stretch). See https://developer.mozilla.org/en-US/docs/Web/CSS/align-items for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'stretch', 'baseline')No

alignSelf

alignSelf controls how a child aligns in the cross direction, overriding the alignItems of the parent. It works like align-self in CSS (default: auto). See https://developer.mozilla.org/en-US/docs/Web/CSS/align-self for more details.

TypeRequired
enum('auto', 'flex-start', 'flex-end', 'center', 'stretch', 'baseline')No

aspectRatio

Aspect ratio controls the size of the undefined dimension of a node. Aspect ratio is a non-standard property only available in React Native and not CSS.

  • On a node with a set width/height, aspect ratio controls the size of the unset dimension
  • On a node with a set flex basis, aspect ratio controls the size of the node in the cross axis if unset
  • On a node with a measure function, aspect ratio works as though the measure function measures the flex basis
  • On a node with flex grow/shrink, aspect ratio controls the size of the node in the cross axis if unset
  • Aspect ratio takes min/max dimensions into account
TypeRequired
numberNo

borderBottomWidth

borderBottomWidth works like border-bottom-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-width for more details.

TypeRequired
numberNo

borderEndWidth

When direction is ltr, borderEndWidth is equivalent to borderRightWidth. When direction is rtl, borderEndWidth is equivalent to borderLeftWidth.

TypeRequired
numberNo

borderLeftWidth

borderLeftWidth works like border-left-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-left-width for more details.

TypeRequired
numberNo

borderRightWidth

borderRightWidth works like border-right-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-right-width for more details.

TypeRequired
numberNo

borderStartWidth

When direction is ltr, borderStartWidth is equivalent to borderLeftWidth. When direction is rtl, borderStartWidth is equivalent to borderRightWidth.

TypeRequired
numberNo

borderTopWidth

borderTopWidth works like border-top-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-top-width for more details.

TypeRequired
numberNo

borderWidth

borderWidth works like border-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-width for more details.

TypeRequired
numberNo

bottom

bottom is the number of logical pixels to offset the bottom edge of this component.

It works similarly to bottom in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/bottom for more details of how bottom affects layout.

TypeRequired
number, stringNo

direction

direction specifies the directional flow of the user interface. The default is inherit, except for root node which will have value based on the current locale. See https://yogalayout.com/docs/layout-direction for more details.

TypeRequiredPlatform
enum('inherit', 'ltr', 'rtl')NoiOS

display

display sets the display type of this component.

It works similarly to display in CSS but only supports 'flex' and 'none'. 'flex' is the default.

TypeRequired
enum('none', 'flex')No

end

When the direction is ltr, end is equivalent to right. When the direction is rtl, end is equivalent to left.

This style takes precedence over the left and right styles.

TypeRequired
number, stringNo

flex

In React Native flex does not work the same way that it does in CSS. flex is a number rather than a string, and it works according to the Yoga layout engine.

When flex is a positive number, it makes the component flexible, and it will be sized proportional to its flex value. So a component with flex set to 2 will take twice the space as a component with flex set to 1. flex: <positive number> equates to flexGrow: <positive number>, flexShrink: 1, flexBasis: 0.

When flex is 0, the component is sized according to width and height, and it is inflexible.

When flex is -1, the component is normally sized according to width and height. However, if there's not enough space, the component will shrink to its minWidth and minHeight.

flexGrow, flexShrink, and flexBasis work the same as in CSS.

TypeRequired
numberNo

flexBasis

flexBasis is an axis-independent way of providing the default size of an item along the main axis. Setting the flexBasis of a child is similar to setting the width of that child if its parent is a container with flexDirection: row or setting the height of a child if its parent is a container with flexDirection: column. The flexBasis of an item is the default size of that item, the size of the item before any flexGrow and flexShrink calculations are performed.

TypeRequired
number, stringNo

flexDirection

flexDirection controls which directions children of a container go. row goes left to right, column goes top to bottom, and you may be able to guess what the other two do. It works like flex-direction in CSS, except the default is column. See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction for more details.

TypeRequired
enum('row', 'row-reverse', 'column', 'column-reverse')No

flexGrow

flexGrow describes how any space within a container should be distributed among its children along the main axis. After laying out its children, a container will distribute any remaining space according to the flex grow values specified by its children.

flexGrow accepts any floating point value >= 0, with 0 being the default value. A container will distribute any remaining space among its children weighted by the children’s flexGrow values.

TypeRequired
numberNo

flexShrink

flexShrink describes how to shrink children along the main axis in the case in which the total size of the children overflows the size of the container on the main axis. flexShrink is very similar to flexGrow and can be thought of in the same way if any overflowing size is considered to be negative remaining space. These two properties also work well together by allowing children to grow and shrink as needed.

flexShrink accepts any floating point value >= 0, with 1 being the default value. A container will shrink its children weighted by the children’s flexShrink values.

TypeRequired
numberNo

flexWrap

flexWrap controls whether children can wrap around after they hit the end of a flex container. It works like flex-wrap in CSS (default: nowrap). See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-wrap for more details. Note it does not work anymore with alignItems: stretch (the default), so you may want to use alignItems: flex-start for example (breaking change details: https://github.com/facebook/react-native/releases/tag/v0.28.0).

TypeRequired
enum('wrap', 'nowrap', 'wrap-reverse')No

height

height sets the height of this component.

It works similarly to height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported. See https://developer.mozilla.org/en-US/docs/Web/CSS/height for more details.

TypeRequired
number, stringNo

justifyContent

justifyContent aligns children in the main direction. For example, if children are flowing vertically, justifyContent controls how they align vertically. It works like justify-content in CSS (default: flex-start). See https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'space-between', 'space-around', 'space-evenly')No

left

left is the number of logical pixels to offset the left edge of this component.

It works similarly to left in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/left for more details of how left affects layout.

TypeRequired
number, stringNo

margin

Setting margin has the same effect as setting each of marginTop, marginLeft, marginBottom, and marginRight. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin for more details.

TypeRequired
number, stringNo

marginBottom

marginBottom works like margin-bottom in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-bottom for more details.

TypeRequired
number, stringNo

marginEnd

When direction is ltr, marginEnd is equivalent to marginRight. When direction is rtl, marginEnd is equivalent to marginLeft.

TypeRequired
number, stringNo

marginHorizontal

Setting marginHorizontal has the same effect as setting both marginLeft and marginRight.

TypeRequired
number, stringNo

marginLeft

marginLeft works like margin-left in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-left for more details.

TypeRequired
number, stringNo

marginRight

marginRight works like margin-right in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-right for more details.

TypeRequired
number, stringNo

marginStart

When direction is ltr, marginStart is equivalent to marginLeft. When direction is rtl, marginStart is equivalent to marginRight.

TypeRequired
number, stringNo

marginTop

marginTop works like margin-top in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-top for more details.

TypeRequired
number, stringNo

marginVertical

Setting marginVertical has the same effect as setting both marginTop and marginBottom.

TypeRequired
number, stringNo

maxHeight

maxHeight is the maximum height for this component, in logical pixels.

It works similarly to max-height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/max-height for more details.

TypeRequired
number, stringNo

maxWidth

maxWidth is the maximum width for this component, in logical pixels.

It works similarly to max-width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/max-width for more details.

TypeRequired
number, stringNo

minHeight

minHeight is the minimum height for this component, in logical pixels.

It works similarly to min-height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/min-height for more details.

TypeRequired
number, stringNo

minWidth

minWidth is the minimum width for this component, in logical pixels.

It works similarly to min-width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/min-width for more details.

TypeRequired
number, stringNo

overflow

overflow controls how children are measured and displayed. overflow: hidden causes views to be clipped while overflow: scroll causes views to be measured independently of their parents' main axis. It works like overflow in CSS (default: visible). See https://developer.mozilla.org/en/docs/Web/CSS/overflow for more details.

TypeRequired
enum('visible', 'hidden', 'scroll')No

padding

Setting padding has the same effect as setting each of paddingTop, paddingBottom, paddingLeft, and paddingRight. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding for more details.

TypeRequired
number, stringNo

paddingBottom

paddingBottom works like padding-bottom in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-bottom for more details.

TypeRequired
number, stringNo

paddingEnd

When direction is ltr, paddingEnd is equivalent to paddingRight. When direction is rtl, paddingEnd is equivalent to paddingLeft.

TypeRequired
number, stringNo

paddingHorizontal

Setting paddingHorizontal is like setting both of paddingLeft and paddingRight.

TypeRequired
number, stringNo

paddingLeft

paddingLeft works like padding-left in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-left for more details.

TypeRequired
number, stringNo

paddingRight

paddingRight works like padding-right in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-right for more details.

TypeRequired
number, stringNo

paddingStart

When direction is ltr, paddingStart is equivalent to paddingLeft. When direction is rtl, paddingStart is equivalent to paddingRight.

TypeRequired
number, stringNo

paddingTop

paddingTop works like padding-top in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-top for more details.

TypeRequired
number, ,stringNo

paddingVertical

Setting paddingVertical is like setting both of paddingTop and paddingBottom.

TypeRequired
number, stringNo

position

position in React Native is similar to regular CSS, but everything is set to relative by default, so absolute positioning is always relative to the parent.

If you want to position a child using specific numbers of logical pixels relative to its parent, set the child to have absolute position.

If you want to position a child relative to something that is not its parent, don't use styles for that. Use the component tree.

See https://github.com/facebook/yoga for more details on how position differs between React Native and CSS.

TypeRequired
enum('absolute', 'relative')No

right

right is the number of logical pixels to offset the right edge of this component.

It works similarly to right in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/right for more details of how right affects layout.

TypeRequired
number, stringNo

start

When the direction is ltr, start is equivalent to left. When the direction is rtl, start is equivalent to right.

This style takes precedence over the left, right, and end styles.

TypeRequired
number, stringNo

top

top is the number of logical pixels to offset the top edge of this component.

It works similarly to top in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/top for more details of how top affects layout.

TypeRequired
number, stringNo

width

width sets the width of this component.

It works similarly to width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported. See https://developer.mozilla.org/en-US/docs/Web/CSS/width for more details.

TypeRequired
number, stringNo

zIndex

zIndex controls which components display on top of others. Normally, you don't use zIndex. Components render according to their order in the document tree, so later components draw over earlier ones. zIndex may be useful if you have animations or custom modal interfaces where you don't want this behavior.

It works like the CSS z-index property - components with a larger zIndex will render on top. Think of the z-direction like it's pointing from the phone into your eyeball. See https://developer.mozilla.org/en-US/docs/Web/CSS/z-index for more details.

On iOS, zIndex may require Views to be siblings of each other for it to work as expected.

TypeRequired
numberNo
Edit this page
Last updated on
- + diff --git a/docs/layoutanimation.html b/docs/layoutanimation.html index 04ba3f46692..5fc0df5e58d 100644 --- a/docs/layoutanimation.html +++ b/docs/layoutanimation.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

LayoutAnimation

Automatically animates views to their new positions when the next layout happens.

A common way to use this API is to call it before updating the state hook in functional components and calling setState in class components.

Note that in order to get this to work on Android you need to set the following flags via UIManager:

if (Platform.OS === 'android') {
if (UIManager.setLayoutAnimationEnabledExperimental) {
UIManager.setLayoutAnimationEnabledExperimental(true);
}
}

Example

Reference

Methods

configureNext()

static configureNext(config, onAnimationDidEnd?)

Schedules an animation to happen on the next layout.

Parameters:

NameTypeRequiredDescription
configobjectYesSee config description below.
onAnimationDidEndfunctionNoCalled when the animation finished. Only supported on iOS.

The config parameter is an object with the keys below. create returns a valid object for config, and the Presets objects can also all be passed as the config.

  • duration in milliseconds
  • create, optional config for animating in new views
  • update, optional config for animating views that have been updated
  • delete, optional config for animating views as they are removed

The config that's passed to create, update, or delete has the following keys:

  • type, the animation type to use
  • property, the layout property to animate (optional, but recommended for create and delete)
  • springDamping (number, optional and only for use with type: Type.spring)
  • initialVelocity (number, optional)
  • delay (number, optional)
  • duration (number, optional)

create()

static create(duration, type, creationProp)

Helper that creates an object (with create, update, and delete fields) to pass into configureNext. The type parameter is an animation type, and the creationProp parameter is a layout property.

Example usage:

Properties

Types

An enumeration of animation types to be used in the create method, or in the create/update/delete configs for configureNext. (example usage: LayoutAnimation.Types.easeIn)

Types
spring
linear
easeInEaseOut
easeIn
easeOut
keyboard

Properties

An enumeration of layout properties to be animated to be used in the create method, or in the create/update/delete configs for configureNext. (example usage: LayoutAnimation.Properties.opacity)

Properties
opacity
scaleX
scaleY
scaleXY

Presets

A set of predefined animation configs to pass into configureNext.

PresetsValue
easeInEaseOutcreate(300, 'easeInEaseOut', 'opacity')
linearcreate(500, 'linear', 'opacity')
spring{ duration: 700, create: { type: 'linear', property: 'opacity' }, update: { type: 'spring', springDamping: 0.4 }, delete: { type: 'linear', property: 'opacity' } }

easeInEaseOut()

Calls configureNext() with Presets.easeInEaseOut.

linear()

Calls configureNext() with Presets.linear.

spring()

Calls configureNext() with Presets.spring.

Example usage:

Edit this page
Last updated on
- + diff --git a/docs/layoutanimation/index.html b/docs/layoutanimation/index.html index 04ba3f46692..5fc0df5e58d 100644 --- a/docs/layoutanimation/index.html +++ b/docs/layoutanimation/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

LayoutAnimation

Automatically animates views to their new positions when the next layout happens.

A common way to use this API is to call it before updating the state hook in functional components and calling setState in class components.

Note that in order to get this to work on Android you need to set the following flags via UIManager:

if (Platform.OS === 'android') {
if (UIManager.setLayoutAnimationEnabledExperimental) {
UIManager.setLayoutAnimationEnabledExperimental(true);
}
}

Example

Reference

Methods

configureNext()

static configureNext(config, onAnimationDidEnd?)

Schedules an animation to happen on the next layout.

Parameters:

NameTypeRequiredDescription
configobjectYesSee config description below.
onAnimationDidEndfunctionNoCalled when the animation finished. Only supported on iOS.

The config parameter is an object with the keys below. create returns a valid object for config, and the Presets objects can also all be passed as the config.

  • duration in milliseconds
  • create, optional config for animating in new views
  • update, optional config for animating views that have been updated
  • delete, optional config for animating views as they are removed

The config that's passed to create, update, or delete has the following keys:

  • type, the animation type to use
  • property, the layout property to animate (optional, but recommended for create and delete)
  • springDamping (number, optional and only for use with type: Type.spring)
  • initialVelocity (number, optional)
  • delay (number, optional)
  • duration (number, optional)

create()

static create(duration, type, creationProp)

Helper that creates an object (with create, update, and delete fields) to pass into configureNext. The type parameter is an animation type, and the creationProp parameter is a layout property.

Example usage:

Properties

Types

An enumeration of animation types to be used in the create method, or in the create/update/delete configs for configureNext. (example usage: LayoutAnimation.Types.easeIn)

Types
spring
linear
easeInEaseOut
easeIn
easeOut
keyboard

Properties

An enumeration of layout properties to be animated to be used in the create method, or in the create/update/delete configs for configureNext. (example usage: LayoutAnimation.Properties.opacity)

Properties
opacity
scaleX
scaleY
scaleXY

Presets

A set of predefined animation configs to pass into configureNext.

PresetsValue
easeInEaseOutcreate(300, 'easeInEaseOut', 'opacity')
linearcreate(500, 'linear', 'opacity')
spring{ duration: 700, create: { type: 'linear', property: 'opacity' }, update: { type: 'spring', springDamping: 0.4 }, delete: { type: 'linear', property: 'opacity' } }

easeInEaseOut()

Calls configureNext() with Presets.easeInEaseOut.

linear()

Calls configureNext() with Presets.linear.

spring()

Calls configureNext() with Presets.spring.

Example usage:

Edit this page
Last updated on
- + diff --git a/docs/libraries.html b/docs/libraries.html index c8562682352..853250fbe4d 100644 --- a/docs/libraries.html +++ b/docs/libraries.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Using Libraries

React Native provides a set of built-in Core Components and APIs ready to use in your app. You're not limited to the components and APIs bundled with React Native. React Native has a community of thousands of developers. If the Core Components and APIs don't have what you are looking for, you may be able to find and install a library from the community to add the functionality to your app.

Selecting a Package Manager

React Native libraries are typically installed from the npm registry using a Node.js package manager such as npm CLI or Yarn Classic.

If you have Node.js installed on your computer then you already have the npm CLI installed. Some developers prefer to use Yarn Classic for slightly faster install times and additional advanced features like Workspaces. Both tools work great with React Native. We will assume npm for the rest of this guide for simplicity of explanation.

💡 The terms "library" and "package" are used interchangably in the JavaScript community.

Installing a Library

To install a library in your project, navigate to your project directory in your terminal and run npm install <name-of-the-library>. Let's try this with react-native-webview:

npm install react-native-webview

The library that we installed includes native code, and we need to link to our app before we use it.

Linking Native Code on iOS

React Native uses CocoaPods to manage iOS project dependencies and most React Native libraries follow this same convention. If a library you are using does not, then please refer to their README for additional instruction. In most cases, the following instructions will apply.

Run pod install in our ios directory in order to link it to our native iOS project. A shortcut for doing this without switching to the ios directory is to run npx pod-install.

npx pod-install

Once this is complete, re-build the app binary to start using your new library:

npx react-native run-ios

Linking Native Code on Android

React Native uses Gradle to manage Android project dependencies. After you install a library with native dependencies, you will need to re-build the app binary to use your new library:

npx react-native run-android

Finding Libraries

React Native Directory is a searchable database of libraries built specifically for React Native. This is the first place to look for a library for your React Native app.

Many of the libraries you will find on the directory are from React Native Community or Expo.

Libraries built by the React Native Community are driven by volunteers and individuals at companies that depend on React Native. They often support iOS, tvOS, Android, Windows, but this varies across projects. Many of the libraries in this organization were once React Native Core Components and APIs.

Libraries built by Expo are all written in TypeScript and support iOS, Android, and react-native-web wherever possible. They usually require that you first install react-native-unimodules in order to use in your React Native app.

After React Native Directory, the npm registry is the next best place if you can't find a library specifically for React Native on the directory. The npm registry is the definitive source for JavaScript libraries, but the libraries that it lists may not all be compatible with React Native. React Native is one of many JavaScript programming environments, including Node.js, web browsers, Electron, and more, and npm includes libraries that work for all of these environments.

Determining Library Compatibility

Does it work with React Native?

Usually libraries built specifically for other platforms will not work with React Native. Examples include react-select which is built for the web and specifically targets react-dom, and rimraf which is built for Node.js and interacts with your computer file system. Other libraries like lodash use only JavaScript language features and work in any environment. You will gain a sense for this over time, but until then the easiest way to find out is to try it yourself. You can remove packages using npm uninstall if it turns out that it does not work in React Native.

Does it work for the platforms that my app supports?

React Native Directory allows you to filter by platform compatibility, such as iOS, Android, Web, and Windows. If the library you would like to use is not currently listed there, refer to the README for the library to learn more.

Does it work with my app version of React Native?

The latest version of a library is typically compatible with the latest version of React Native. If you are using an older version, you should refer to the README to know which version of the library you should install. You can install a particular version of the library by running npm install <library-name>@<version-number>, for example: npm install @react-native-community/netinfo@^2.0.0.

Edit this page
Last updated on
- + diff --git a/docs/libraries/index.html b/docs/libraries/index.html index c8562682352..853250fbe4d 100644 --- a/docs/libraries/index.html +++ b/docs/libraries/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Using Libraries

React Native provides a set of built-in Core Components and APIs ready to use in your app. You're not limited to the components and APIs bundled with React Native. React Native has a community of thousands of developers. If the Core Components and APIs don't have what you are looking for, you may be able to find and install a library from the community to add the functionality to your app.

Selecting a Package Manager

React Native libraries are typically installed from the npm registry using a Node.js package manager such as npm CLI or Yarn Classic.

If you have Node.js installed on your computer then you already have the npm CLI installed. Some developers prefer to use Yarn Classic for slightly faster install times and additional advanced features like Workspaces. Both tools work great with React Native. We will assume npm for the rest of this guide for simplicity of explanation.

💡 The terms "library" and "package" are used interchangably in the JavaScript community.

Installing a Library

To install a library in your project, navigate to your project directory in your terminal and run npm install <name-of-the-library>. Let's try this with react-native-webview:

npm install react-native-webview

The library that we installed includes native code, and we need to link to our app before we use it.

Linking Native Code on iOS

React Native uses CocoaPods to manage iOS project dependencies and most React Native libraries follow this same convention. If a library you are using does not, then please refer to their README for additional instruction. In most cases, the following instructions will apply.

Run pod install in our ios directory in order to link it to our native iOS project. A shortcut for doing this without switching to the ios directory is to run npx pod-install.

npx pod-install

Once this is complete, re-build the app binary to start using your new library:

npx react-native run-ios

Linking Native Code on Android

React Native uses Gradle to manage Android project dependencies. After you install a library with native dependencies, you will need to re-build the app binary to use your new library:

npx react-native run-android

Finding Libraries

React Native Directory is a searchable database of libraries built specifically for React Native. This is the first place to look for a library for your React Native app.

Many of the libraries you will find on the directory are from React Native Community or Expo.

Libraries built by the React Native Community are driven by volunteers and individuals at companies that depend on React Native. They often support iOS, tvOS, Android, Windows, but this varies across projects. Many of the libraries in this organization were once React Native Core Components and APIs.

Libraries built by Expo are all written in TypeScript and support iOS, Android, and react-native-web wherever possible. They usually require that you first install react-native-unimodules in order to use in your React Native app.

After React Native Directory, the npm registry is the next best place if you can't find a library specifically for React Native on the directory. The npm registry is the definitive source for JavaScript libraries, but the libraries that it lists may not all be compatible with React Native. React Native is one of many JavaScript programming environments, including Node.js, web browsers, Electron, and more, and npm includes libraries that work for all of these environments.

Determining Library Compatibility

Does it work with React Native?

Usually libraries built specifically for other platforms will not work with React Native. Examples include react-select which is built for the web and specifically targets react-dom, and rimraf which is built for Node.js and interacts with your computer file system. Other libraries like lodash use only JavaScript language features and work in any environment. You will gain a sense for this over time, but until then the easiest way to find out is to try it yourself. You can remove packages using npm uninstall if it turns out that it does not work in React Native.

Does it work for the platforms that my app supports?

React Native Directory allows you to filter by platform compatibility, such as iOS, Android, Web, and Windows. If the library you would like to use is not currently listed there, refer to the README for the library to learn more.

Does it work with my app version of React Native?

The latest version of a library is typically compatible with the latest version of React Native. If you are using an older version, you should refer to the README to know which version of the library you should install. You can install a particular version of the library by running npm install <library-name>@<version-number>, for example: npm install @react-native-community/netinfo@^2.0.0.

Edit this page
Last updated on
- + diff --git a/docs/linking-libraries-ios.html b/docs/linking-libraries-ios.html index 03307e7d58e..b58ee18ba67 100644 --- a/docs/linking-libraries-ios.html +++ b/docs/linking-libraries-ios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Linking Libraries

Not every app uses all the native capabilities, and including the code to support all those features would impact the binary size... But we still want to support adding these features whenever you need them.

With that in mind we exposed many of these features as independent static libraries.

For most of the libs it will be as quick as dragging two files, sometimes a third step will be necessary, but no more than that.

All the libraries we ship with React Native live on the Libraries folder in the root of the repository. Some of them are pure JavaScript, and you only need to require it. Other libraries also rely on some native code, in that case you'll have to add these files to your app, otherwise the app will throw an error as soon as you try to use the library.

Here are the few steps to link your libraries that contain native code

Automatic linking

Step 1

Install a library with native dependencies:

$ npm install <library-with-native-dependencies> --save

Note: --save or --save-dev flag is very important for this step. React Native will link your libs based on dependencies and devDependencies in your package.json file.

Step 2

Link your native dependencies:

$ npx react-native link

Done! All libraries with native dependencies should be successfully linked to your iOS/Android project.

Note: If your iOS project is using CocoaPods (contains Podfile) and linked library has podspec file, then npx react-native link will link library using Podfile. To support non-trivial Podfiles add # Add new pods below this line comment to places where you expect pods to be added.

Manual linking

Step 1

If the library has native code, there must be an .xcodeproj file inside its folder. Drag this file to your project on Xcode (usually under the Libraries group on Xcode);

Step 2

Click on your main project file (the one that represents the .xcodeproj) select Build Phases and drag the static library from the Products folder inside the Library you are importing to Link Binary With Libraries

Step 3

Not every library will need this step, what you need to consider is:

Do I need to know the contents of the library at compile time?

What that means is, are you using this library on the native side or only in JavaScript? If you are only using it in JavaScript, you are good to go!

If you do need to call it from native, then we need to know the library's headers. To achieve that you have to go to your project's file, select Build Settings and search for Header Search Paths. There you should include the path to your library. (This documentation used to recommend using recursive, but this is no longer recommended, as it can cause subtle build failures, especially with CocoaPods.)

Edit this page
Last updated on
- + diff --git a/docs/linking-libraries-ios/index.html b/docs/linking-libraries-ios/index.html index 03307e7d58e..b58ee18ba67 100644 --- a/docs/linking-libraries-ios/index.html +++ b/docs/linking-libraries-ios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Linking Libraries

Not every app uses all the native capabilities, and including the code to support all those features would impact the binary size... But we still want to support adding these features whenever you need them.

With that in mind we exposed many of these features as independent static libraries.

For most of the libs it will be as quick as dragging two files, sometimes a third step will be necessary, but no more than that.

All the libraries we ship with React Native live on the Libraries folder in the root of the repository. Some of them are pure JavaScript, and you only need to require it. Other libraries also rely on some native code, in that case you'll have to add these files to your app, otherwise the app will throw an error as soon as you try to use the library.

Here are the few steps to link your libraries that contain native code

Automatic linking

Step 1

Install a library with native dependencies:

$ npm install <library-with-native-dependencies> --save

Note: --save or --save-dev flag is very important for this step. React Native will link your libs based on dependencies and devDependencies in your package.json file.

Step 2

Link your native dependencies:

$ npx react-native link

Done! All libraries with native dependencies should be successfully linked to your iOS/Android project.

Note: If your iOS project is using CocoaPods (contains Podfile) and linked library has podspec file, then npx react-native link will link library using Podfile. To support non-trivial Podfiles add # Add new pods below this line comment to places where you expect pods to be added.

Manual linking

Step 1

If the library has native code, there must be an .xcodeproj file inside its folder. Drag this file to your project on Xcode (usually under the Libraries group on Xcode);

Step 2

Click on your main project file (the one that represents the .xcodeproj) select Build Phases and drag the static library from the Products folder inside the Library you are importing to Link Binary With Libraries

Step 3

Not every library will need this step, what you need to consider is:

Do I need to know the contents of the library at compile time?

What that means is, are you using this library on the native side or only in JavaScript? If you are only using it in JavaScript, you are good to go!

If you do need to call it from native, then we need to know the library's headers. To achieve that you have to go to your project's file, select Build Settings and search for Header Search Paths. There you should include the path to your library. (This documentation used to recommend using recursive, but this is no longer recommended, as it can cause subtle build failures, especially with CocoaPods.)

Edit this page
Last updated on
- + diff --git a/docs/linking.html b/docs/linking.html index 98bd54315e0..27f1a6f71cf 100644 --- a/docs/linking.html +++ b/docs/linking.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Linking

Linking gives you a general interface to interact with both incoming and outgoing app links.

Every Link (URL) has a URL Scheme, some websites are prefixed with https:// or http:// and the http is the URL Scheme. Let's call it scheme for short.

In addition to https, you're likely also familiar with the mailto scheme. When you open a link with the mailto scheme, your operating system will open an installed mail application. Similarly, there are schemes for making phone calls and sending SMS. Read more about built-in URL schemes below.

Like using the mailto scheme, it's possible to link to other applications by using custom url schemes. For example, when you get a Magic Link email from Slack, the Launch Slack button is an anchor tag with an href that looks something like: slack://secret/magic-login/other-secret. Like with Slack, you can tell the operating system that you want to handle a custom scheme. When the Slack app opens, it receives the URL that was used to open it. This is often referred to as deep linking. Read more about how to get the deep link into your app.

Custom URL scheme isn't the only way to open your application on mobile. You don't want to use a custom URL scheme in links in the email because then the links would be broken on desktop. Instead, you want to use a regular https links such as https://www.myapp.io/records/1234546. and on mobile you want that link open your app. Android calls it Deep Links (Universal Links - iOS).

Built-in URL Schemes

As mentioned in the introduction, there are some URL schemes for core functionality that exist on every platform. The following is a non-exhaustive list, but covers the most commonly used schemes.

SchemeDescriptioniOSAndroid
mailtoOpen mail app, eg: mailto: support@expo.io✅✅
telOpen phone app, eg: tel:+123456789✅✅
smsOpen SMS app, eg: sms:+123456789✅✅
https / httpOpen web browser app, eg: https://expo.io✅✅

Enabling Deep Links

If you want to enable deep links in your app, please read the below guide:

For instructions on how to add support for deep linking on Android, refer to Enabling Deep Links for App Content - Add Intent Filters for Your Deep Links.

If you wish to receive the intent in an existing instance of MainActivity, you may set the launchMode of MainActivity to singleTask in AndroidManifest.xml. See <activity> documentation for more information.

<activity
android:name=".MainActivity"
android:launchMode="singleTask">

Handling Deep Links

There are two ways to handle URLs that open your app.

1. If the app is already open, the app is foregrounded and a Linking event is fired

You can handle these events with Linking.addEventListener('url', callback).

2. If the app is not already open, it is opened and the url is passed in as the initialURL

You can handle these events with Linking.getInitialURL() -- it returns a Promise that resolves to the url, if there is one.

Example

Open Links and Deep Links (Universal Links)

Open Custom Settings

Get the Deep Link

Send Intents (Android)

Reference

Methods

constructor()

constructor();

addEventListener()

addEventListener(type, handler);

Add a handler to Linking changes by listening to the url event type and providing the handler.

removeEventListener()

removeEventListener(type, handler);

Remove a handler by passing the url event type and the handler.

openURL()

openURL(url);

Try to open the given url with any of the installed apps.

You can use other URLs, like a location (e.g. "geo:37.484847,-122.148386" on Android or "http://maps.apple.com/?ll=37.484847,-122.148386" on iOS), a contact, or any other URL that can be opened with the installed apps.

The method returns a Promise object. If the user confirms the open dialog or the url automatically opens, the promise is resolved. If the user cancels the open dialog or there are no registered applications for the url, the promise is rejected.

Parameters:

NameTypeRequiredDescription
urlstringYesThe URL to open.

This method will fail if the system doesn't know how to open the specified URL. If you're passing in a non-http(s) URL, it's best to check {@code canOpenURL} first.

For web URLs, the protocol ("http://", "https://") must be set accordingly!

This method may behave differently in a simulator e.g. "tel:" links are not able to be handled in the iOS simulator as there's no access to the dialer app.

canOpenURL()

canOpenURL(url);

Determine whether or not an installed app can handle a given URL.

The method returns a Promise object. When it is determined whether or not the given URL can be handled, the promise is resolved and the first parameter is whether or not it can be opened.

The Promise will reject on Android if it was impossible to check if the URL can be opened, and on iOS if you didn't add the specific scheme in the LSApplicationQueriesSchemes key inside Info.plist (see bellow).

Parameters:

NameTypeRequiredDescription
urlstringYesThe URL to open.

For web URLs, the protocol ("http://", "https://") must be set accordingly!

As of iOS 9, your app needs to provide the LSApplicationQueriesSchemes key inside Info.plist or canOpenURL will always return false.

This method has limitations on iOS 9+. From the official Apple documentation:

If your app is linked against an earlier version of iOS but is running in iOS 9.0 or later, you can call this method up to 50 times. After reaching that limit, subsequent calls always return false. If the user reinstalls or upgrades the app, iOS resets the limit.

openSettings()

openSettings();

Open the Settings app and displays the app’s custom settings, if it has any.

getInitialURL()

getInitialURL();

If the app launch was triggered by an app link, it will give the link url, otherwise it will give null.

To support deep linking on Android, refer http://developer.android.com/training/app-indexing/deep-linking.html#handling-intents

sendIntent()

sendIntent(action: string, extras?: Array<{key: string, value: string | number | boolean}>)

@platform android

Android-Only. Launch an Android intent with extras (optional)

Edit this page
Last updated on
- + diff --git a/docs/linking/index.html b/docs/linking/index.html index 98bd54315e0..27f1a6f71cf 100644 --- a/docs/linking/index.html +++ b/docs/linking/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Linking

Linking gives you a general interface to interact with both incoming and outgoing app links.

Every Link (URL) has a URL Scheme, some websites are prefixed with https:// or http:// and the http is the URL Scheme. Let's call it scheme for short.

In addition to https, you're likely also familiar with the mailto scheme. When you open a link with the mailto scheme, your operating system will open an installed mail application. Similarly, there are schemes for making phone calls and sending SMS. Read more about built-in URL schemes below.

Like using the mailto scheme, it's possible to link to other applications by using custom url schemes. For example, when you get a Magic Link email from Slack, the Launch Slack button is an anchor tag with an href that looks something like: slack://secret/magic-login/other-secret. Like with Slack, you can tell the operating system that you want to handle a custom scheme. When the Slack app opens, it receives the URL that was used to open it. This is often referred to as deep linking. Read more about how to get the deep link into your app.

Custom URL scheme isn't the only way to open your application on mobile. You don't want to use a custom URL scheme in links in the email because then the links would be broken on desktop. Instead, you want to use a regular https links such as https://www.myapp.io/records/1234546. and on mobile you want that link open your app. Android calls it Deep Links (Universal Links - iOS).

Built-in URL Schemes

As mentioned in the introduction, there are some URL schemes for core functionality that exist on every platform. The following is a non-exhaustive list, but covers the most commonly used schemes.

SchemeDescriptioniOSAndroid
mailtoOpen mail app, eg: mailto: support@expo.io✅✅
telOpen phone app, eg: tel:+123456789✅✅
smsOpen SMS app, eg: sms:+123456789✅✅
https / httpOpen web browser app, eg: https://expo.io✅✅

Enabling Deep Links

If you want to enable deep links in your app, please read the below guide:

For instructions on how to add support for deep linking on Android, refer to Enabling Deep Links for App Content - Add Intent Filters for Your Deep Links.

If you wish to receive the intent in an existing instance of MainActivity, you may set the launchMode of MainActivity to singleTask in AndroidManifest.xml. See <activity> documentation for more information.

<activity
android:name=".MainActivity"
android:launchMode="singleTask">

Handling Deep Links

There are two ways to handle URLs that open your app.

1. If the app is already open, the app is foregrounded and a Linking event is fired

You can handle these events with Linking.addEventListener('url', callback).

2. If the app is not already open, it is opened and the url is passed in as the initialURL

You can handle these events with Linking.getInitialURL() -- it returns a Promise that resolves to the url, if there is one.

Example

Open Links and Deep Links (Universal Links)

Open Custom Settings

Get the Deep Link

Send Intents (Android)

Reference

Methods

constructor()

constructor();

addEventListener()

addEventListener(type, handler);

Add a handler to Linking changes by listening to the url event type and providing the handler.

removeEventListener()

removeEventListener(type, handler);

Remove a handler by passing the url event type and the handler.

openURL()

openURL(url);

Try to open the given url with any of the installed apps.

You can use other URLs, like a location (e.g. "geo:37.484847,-122.148386" on Android or "http://maps.apple.com/?ll=37.484847,-122.148386" on iOS), a contact, or any other URL that can be opened with the installed apps.

The method returns a Promise object. If the user confirms the open dialog or the url automatically opens, the promise is resolved. If the user cancels the open dialog or there are no registered applications for the url, the promise is rejected.

Parameters:

NameTypeRequiredDescription
urlstringYesThe URL to open.

This method will fail if the system doesn't know how to open the specified URL. If you're passing in a non-http(s) URL, it's best to check {@code canOpenURL} first.

For web URLs, the protocol ("http://", "https://") must be set accordingly!

This method may behave differently in a simulator e.g. "tel:" links are not able to be handled in the iOS simulator as there's no access to the dialer app.

canOpenURL()

canOpenURL(url);

Determine whether or not an installed app can handle a given URL.

The method returns a Promise object. When it is determined whether or not the given URL can be handled, the promise is resolved and the first parameter is whether or not it can be opened.

The Promise will reject on Android if it was impossible to check if the URL can be opened, and on iOS if you didn't add the specific scheme in the LSApplicationQueriesSchemes key inside Info.plist (see bellow).

Parameters:

NameTypeRequiredDescription
urlstringYesThe URL to open.

For web URLs, the protocol ("http://", "https://") must be set accordingly!

As of iOS 9, your app needs to provide the LSApplicationQueriesSchemes key inside Info.plist or canOpenURL will always return false.

This method has limitations on iOS 9+. From the official Apple documentation:

If your app is linked against an earlier version of iOS but is running in iOS 9.0 or later, you can call this method up to 50 times. After reaching that limit, subsequent calls always return false. If the user reinstalls or upgrades the app, iOS resets the limit.

openSettings()

openSettings();

Open the Settings app and displays the app’s custom settings, if it has any.

getInitialURL()

getInitialURL();

If the app launch was triggered by an app link, it will give the link url, otherwise it will give null.

To support deep linking on Android, refer http://developer.android.com/training/app-indexing/deep-linking.html#handling-intents

sendIntent()

sendIntent(action: string, extras?: Array<{key: string, value: string | number | boolean}>)

@platform android

Android-Only. Launch an Android intent with extras (optional)

Edit this page
Last updated on
- + diff --git a/docs/listview.html b/docs/listview.html index 5771a204656..c08d597d311 100644 --- a/docs/listview.html +++ b/docs/listview.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
render() {
return (
<ListView
dataSource={this.state.dataSource}
renderRow={(rowData) => <Text>{rowData}</Text>}
/>
);
}
}

ListView also supports more advanced features, including sections with sticky section headers, header and footer support, callbacks on reaching the end of the available data (onEndReached) and on the set of rows that are visible in the device viewport change (onChangeVisibleRows), and several performance optimizations.

There are a few performance operations designed to make ListView scroll smoothly while dynamically loading potentially very large (or conceptually infinite) data sets:

Props

Methods

Reference

Props

dataSource

An instance of ListView.DataSource to use

TypeRequired
ListViewDataSourceYes

initialListSize

How many rows to render on initial component mount. Use this to make it so that the first screen worth of data appears at one time instead of over the course of multiple frames.

TypeRequired
numberYes

onEndReachedThreshold

Threshold in pixels (virtual, not physical) for calling onEndReached.

TypeRequired
numberYes

pageSize

Number of rows to render per event loop. Note: if your 'rows' are actually cells, i.e. they don't span the full width of your view (as in the ListViewGridLayoutExample), you should set the pageSize to be a multiple of the number of cells per row, otherwise you're likely to see gaps at the edge of the ListView as new pages are loaded.

TypeRequired
numberYes

renderRow

(rowData, sectionID, rowID, highlightRow) => renderable

Takes a data entry from the data source and its ids and should return a renderable component to be rendered as the row. By default the data is exactly what was put into the data source, but it's also possible to provide custom extractors. ListView can be notified when a row is being highlighted by calling highlightRow(sectionID, rowID). This sets a boolean value of adjacentRowHighlighted in renderSeparator, allowing you to control the separators above and below the highlighted row. The highlighted state of a row can be reset by calling highlightRow(null).

TypeRequired
functionYes

renderScrollComponent

(props) => renderable

A function that returns the scrollable component in which the list rows are rendered. Defaults to returning a ScrollView with the given props.

TypeRequired
functionYes

scrollRenderAheadDistance

How early to start rendering rows before they come on screen, in pixels.

TypeRequired
numberYes

stickyHeaderIndices

An array of child indices determining which children get docked to the top of the screen when scrolling. For example, passing stickyHeaderIndices={[0]} will cause the first child to be fixed to the top of the scroll view. This property is not supported in conjunction with horizontal={true}.

TypeRequired
array of numberYes

enableEmptySections

Flag indicating whether empty section headers should be rendered. In the future release empty section headers will be rendered by default, and the flag will be deprecated. If empty sections are not desired to be rendered their indices should be excluded from sectionID object.

TypeRequired
boolNo

renderHeader

TypeRequired
functionNo

onEndReached

Called when all rows have been rendered and the list has been scrolled to within onEndReachedThreshold of the bottom. The native scroll event is provided.

TypeRequired
functionNo

stickySectionHeadersEnabled

Makes the sections headers sticky. The sticky behavior means that it will scroll with the content at the top of the section until it reaches the top of the screen, at which point it will stick to the top until it is pushed off the screen by the next section header. This property is not supported in conjunction with horizontal={true}. Only enabled by default on iOS because of typical platform standards.

TypeRequired
boolNo

renderSectionHeader

(sectionData, sectionID) => renderable

If provided, a header is rendered for this section.

TypeRequired
functionNo

renderSeparator

(sectionID, rowID, adjacentRowHighlighted) => renderable

If provided, a renderable component to be rendered as the separator below each row but not the last row if there is a section header below. Take a sectionID and rowID of the row above and whether its adjacent row is highlighted.

TypeRequired
functionNo

onChangeVisibleRows

(visibleRows, changedRows) => void

Called when the set of visible rows changes. visibleRows maps { sectionID: { rowID: true }} for all the visible rows, and changedRows maps { sectionID: { rowID: true | false }} for the rows that have changed their visibility, with true indicating visible, and false indicating the view has moved out of view.

TypeRequired
functionNo

removeClippedSubviews

A performance optimization for improving scroll perf of large lists, used in conjunction with overflow: 'hidden' on the row containers. This is enabled by default.

TypeRequired
boolNo

renderFooter

() => renderable

The header and footer are always rendered (if these props are provided) on every render pass. If they are expensive to re-render, wrap them in StaticContainer or other mechanism as appropriate. Footer is always at the bottom of the list, and header at the top, on every render pass. In a horizontal ListView, the header is rendered on the left and the footer on the right.

TypeRequired
functionNo

Methods

getMetrics()

getMetrics();

Exports some data, e.g. for perf investigations or analytics.

scrollTo()

scrollTo((...args: Array));

Scrolls to a given x, y offset, either immediately or with a smooth animation.

See ScrollView#scrollTo.

scrollToEnd()

scrollToEnd(([options]: object));

If this is a vertical ListView scrolls to the bottom. If this is a horizontal ListView scrolls to the right.

Use scrollToEnd({animated: true}) for smooth animated scrolling, scrollToEnd({animated: false}) for immediate scrolling. If no options are passed, animated defaults to true.

See ScrollView#scrollToEnd.

flashScrollIndicators()

flashScrollIndicators();

Displays the scroll indicators momentarily.

Edit this page
Last updated on
- + diff --git a/docs/listview/index.html b/docs/listview/index.html index 5771a204656..c08d597d311 100644 --- a/docs/listview/index.html +++ b/docs/listview/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
render() {
return (
<ListView
dataSource={this.state.dataSource}
renderRow={(rowData) => <Text>{rowData}</Text>}
/>
);
}
}

ListView also supports more advanced features, including sections with sticky section headers, header and footer support, callbacks on reaching the end of the available data (onEndReached) and on the set of rows that are visible in the device viewport change (onChangeVisibleRows), and several performance optimizations.

There are a few performance operations designed to make ListView scroll smoothly while dynamically loading potentially very large (or conceptually infinite) data sets:

Props

Methods

Reference

Props

dataSource

An instance of ListView.DataSource to use

TypeRequired
ListViewDataSourceYes

initialListSize

How many rows to render on initial component mount. Use this to make it so that the first screen worth of data appears at one time instead of over the course of multiple frames.

TypeRequired
numberYes

onEndReachedThreshold

Threshold in pixels (virtual, not physical) for calling onEndReached.

TypeRequired
numberYes

pageSize

Number of rows to render per event loop. Note: if your 'rows' are actually cells, i.e. they don't span the full width of your view (as in the ListViewGridLayoutExample), you should set the pageSize to be a multiple of the number of cells per row, otherwise you're likely to see gaps at the edge of the ListView as new pages are loaded.

TypeRequired
numberYes

renderRow

(rowData, sectionID, rowID, highlightRow) => renderable

Takes a data entry from the data source and its ids and should return a renderable component to be rendered as the row. By default the data is exactly what was put into the data source, but it's also possible to provide custom extractors. ListView can be notified when a row is being highlighted by calling highlightRow(sectionID, rowID). This sets a boolean value of adjacentRowHighlighted in renderSeparator, allowing you to control the separators above and below the highlighted row. The highlighted state of a row can be reset by calling highlightRow(null).

TypeRequired
functionYes

renderScrollComponent

(props) => renderable

A function that returns the scrollable component in which the list rows are rendered. Defaults to returning a ScrollView with the given props.

TypeRequired
functionYes

scrollRenderAheadDistance

How early to start rendering rows before they come on screen, in pixels.

TypeRequired
numberYes

stickyHeaderIndices

An array of child indices determining which children get docked to the top of the screen when scrolling. For example, passing stickyHeaderIndices={[0]} will cause the first child to be fixed to the top of the scroll view. This property is not supported in conjunction with horizontal={true}.

TypeRequired
array of numberYes

enableEmptySections

Flag indicating whether empty section headers should be rendered. In the future release empty section headers will be rendered by default, and the flag will be deprecated. If empty sections are not desired to be rendered their indices should be excluded from sectionID object.

TypeRequired
boolNo

renderHeader

TypeRequired
functionNo

onEndReached

Called when all rows have been rendered and the list has been scrolled to within onEndReachedThreshold of the bottom. The native scroll event is provided.

TypeRequired
functionNo

stickySectionHeadersEnabled

Makes the sections headers sticky. The sticky behavior means that it will scroll with the content at the top of the section until it reaches the top of the screen, at which point it will stick to the top until it is pushed off the screen by the next section header. This property is not supported in conjunction with horizontal={true}. Only enabled by default on iOS because of typical platform standards.

TypeRequired
boolNo

renderSectionHeader

(sectionData, sectionID) => renderable

If provided, a header is rendered for this section.

TypeRequired
functionNo

renderSeparator

(sectionID, rowID, adjacentRowHighlighted) => renderable

If provided, a renderable component to be rendered as the separator below each row but not the last row if there is a section header below. Take a sectionID and rowID of the row above and whether its adjacent row is highlighted.

TypeRequired
functionNo

onChangeVisibleRows

(visibleRows, changedRows) => void

Called when the set of visible rows changes. visibleRows maps { sectionID: { rowID: true }} for all the visible rows, and changedRows maps { sectionID: { rowID: true | false }} for the rows that have changed their visibility, with true indicating visible, and false indicating the view has moved out of view.

TypeRequired
functionNo

removeClippedSubviews

A performance optimization for improving scroll perf of large lists, used in conjunction with overflow: 'hidden' on the row containers. This is enabled by default.

TypeRequired
boolNo

renderFooter

() => renderable

The header and footer are always rendered (if these props are provided) on every render pass. If they are expensive to re-render, wrap them in StaticContainer or other mechanism as appropriate. Footer is always at the bottom of the list, and header at the top, on every render pass. In a horizontal ListView, the header is rendered on the left and the footer on the right.

TypeRequired
functionNo

Methods

getMetrics()

getMetrics();

Exports some data, e.g. for perf investigations or analytics.

scrollTo()

scrollTo((...args: Array));

Scrolls to a given x, y offset, either immediately or with a smooth animation.

See ScrollView#scrollTo.

scrollToEnd()

scrollToEnd(([options]: object));

If this is a vertical ListView scrolls to the bottom. If this is a horizontal ListView scrolls to the right.

Use scrollToEnd({animated: true}) for smooth animated scrolling, scrollToEnd({animated: false}) for immediate scrolling. If no options are passed, animated defaults to true.

See ScrollView#scrollToEnd.

flashScrollIndicators()

flashScrollIndicators();

Displays the scroll indicators momentarily.

Edit this page
Last updated on
- + diff --git a/docs/listviewdatasource.html b/docs/listviewdatasource.html index 982c21855b7..455d1860d68 100644 --- a/docs/listviewdatasource.html +++ b/docs/listviewdatasource.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

ListViewDataSource

Provides efficient data processing and access to the ListView component. A ListViewDataSource is created with functions for extracting data from the input blob, and comparing elements (with default implementations for convenience). The input blob can be as flat as an array of strings, or an object with rows nested inside section objects.

To update the data in the datasource, use cloneWithRows (or cloneWithRowsAndSections if you care about sections). The data in the data source is immutable, so you can't modify it directly. The clone methods take in the new data and compute a diff for each row so ListView knows whether to re-render it or not.

In this example, a component receives data in chunks, handled by _onDataArrived, which concats the new data onto the old data and updates the data source. We use concat to create a new array - mutating this._data, e.g. with this._data.push(newRowData), would be an error. _rowHasChanged understands the shape of the row data and knows how to efficiently compare it.

getInitialState: function() {
var ds = new ListView.DataSource({rowHasChanged: this._rowHasChanged});
return {ds};
},
_onDataArrived(newData) {
this._data = this._data.concat(newData);
this.setState({
ds: this.state.ds.cloneWithRows(this._data)
});
}

Methods

Reference

Methods

constructor()

constructor(params);

You can provide custom extraction and hasChanged functions for section headers and rows. If absent, data will be extracted with the defaultGetRowData and defaultGetSectionHeaderData functions.

The default extractor expects data of one of the following forms:

{ sectionID_1: { rowID_1: <rowData1>, ... }, ... }

or

{ sectionID_1: [ <rowData1>, <rowData2>, ... ], ... }

or

[ [ <rowData1>, <rowData2>, ... ], ... ]

The constructor takes in a params argument that can contain any of the following:

  • getRowData(dataBlob, sectionID, rowID);
  • getSectionHeaderData(dataBlob, sectionID);
  • rowHasChanged(prevRowData, nextRowData);
  • sectionHeaderHasChanged(prevSectionData, nextSectionData);

cloneWithRows()

cloneWithRows(dataBlob, rowIdentities);

Clones this ListViewDataSource with the specified dataBlob and rowIdentities. The dataBlob an arbitrary blob of data. At construction an extractor to get the interesting information was defined (or the default was used).

The rowIdentities is a 2D array of identifiers for rows. ie. [['a1', 'a2'], ['b1', 'b2', 'b3'], ...]. If not provided, it's assumed that the keys of the section data are the row identities.

Note: This function does NOT clone the data in this data source. It only passes the functions defined at construction to a new data source with the data specified. If you wish to maintain the existing data you must handle merging of old and new data separately and then pass that into this function as the dataBlob.

cloneWithRowsAndSections()

cloneWithRowsAndSections(
dataBlob,
sectionIdentities,
rowIdentities
);

This performs the same function as the cloneWithRows function but here you also specify what your sectionIdentities are. If you don't care about sections you should safely be able to use cloneWithRows.

sectionIdentities is an array of identifiers for sections. ie. ['s1', 's2', ...]. The identifiers should correspond to the keys or array indexes of the data you wish to include. If not provided, it's assumed that the keys of dataBlob are the section identities.

Note: this returns a new object!

const dataSource = ds.cloneWithRowsAndSections({
addresses: ['row 1', 'row 2'],
phone_numbers: ['data 1', 'data 2'],
}, ['phone_numbers']);

getRowCount()

getRowCount();

Returns the total number of rows in the data source.

If you are specifying the rowIdentities or sectionIdentities, then getRowCount will return the number of rows in the filtered data source.

getRowAndSectionCount()

getRowAndSectionCount();

Returns the total number of rows in the data source (see getRowCount for how this is calculated) plus the number of sections in the data.

If you are specifying the rowIdentities or sectionIdentities, then getRowAndSectionCount will return the number of rows & sections in the filtered data source.

rowShouldUpdate()

rowShouldUpdate(sectionIndex, rowIndex);

Returns if the row is dirtied and needs to be rerendered

getRowData()

getRowData(sectionIndex, rowIndex);

Gets the data required to render the row.

getRowIDForFlatIndex()

getRowIDForFlatIndex(index);

Gets the rowID at index provided if the dataSource arrays were flattened, or null of out of range indexes.

getSectionIDForFlatIndex()

getSectionIDForFlatIndex(index);

Gets the sectionID at index provided if the dataSource arrays were flattened, or null for out of range indexes.

getSectionLengths()

getSectionLengths();

Returns an array containing the number of rows in each section

sectionHeaderShouldUpdate()

sectionHeaderShouldUpdate(sectionIndex);

Returns if the section header is dirtied and needs to be rerendered

getSectionHeaderData()

getSectionHeaderData(sectionIndex);

Gets the data required to render the section header

Edit this page
Last updated on
- + diff --git a/docs/listviewdatasource/index.html b/docs/listviewdatasource/index.html index 982c21855b7..455d1860d68 100644 --- a/docs/listviewdatasource/index.html +++ b/docs/listviewdatasource/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

ListViewDataSource

Provides efficient data processing and access to the ListView component. A ListViewDataSource is created with functions for extracting data from the input blob, and comparing elements (with default implementations for convenience). The input blob can be as flat as an array of strings, or an object with rows nested inside section objects.

To update the data in the datasource, use cloneWithRows (or cloneWithRowsAndSections if you care about sections). The data in the data source is immutable, so you can't modify it directly. The clone methods take in the new data and compute a diff for each row so ListView knows whether to re-render it or not.

In this example, a component receives data in chunks, handled by _onDataArrived, which concats the new data onto the old data and updates the data source. We use concat to create a new array - mutating this._data, e.g. with this._data.push(newRowData), would be an error. _rowHasChanged understands the shape of the row data and knows how to efficiently compare it.

getInitialState: function() {
var ds = new ListView.DataSource({rowHasChanged: this._rowHasChanged});
return {ds};
},
_onDataArrived(newData) {
this._data = this._data.concat(newData);
this.setState({
ds: this.state.ds.cloneWithRows(this._data)
});
}

Methods

Reference

Methods

constructor()

constructor(params);

You can provide custom extraction and hasChanged functions for section headers and rows. If absent, data will be extracted with the defaultGetRowData and defaultGetSectionHeaderData functions.

The default extractor expects data of one of the following forms:

{ sectionID_1: { rowID_1: <rowData1>, ... }, ... }

or

{ sectionID_1: [ <rowData1>, <rowData2>, ... ], ... }

or

[ [ <rowData1>, <rowData2>, ... ], ... ]

The constructor takes in a params argument that can contain any of the following:

  • getRowData(dataBlob, sectionID, rowID);
  • getSectionHeaderData(dataBlob, sectionID);
  • rowHasChanged(prevRowData, nextRowData);
  • sectionHeaderHasChanged(prevSectionData, nextSectionData);

cloneWithRows()

cloneWithRows(dataBlob, rowIdentities);

Clones this ListViewDataSource with the specified dataBlob and rowIdentities. The dataBlob an arbitrary blob of data. At construction an extractor to get the interesting information was defined (or the default was used).

The rowIdentities is a 2D array of identifiers for rows. ie. [['a1', 'a2'], ['b1', 'b2', 'b3'], ...]. If not provided, it's assumed that the keys of the section data are the row identities.

Note: This function does NOT clone the data in this data source. It only passes the functions defined at construction to a new data source with the data specified. If you wish to maintain the existing data you must handle merging of old and new data separately and then pass that into this function as the dataBlob.

cloneWithRowsAndSections()

cloneWithRowsAndSections(
dataBlob,
sectionIdentities,
rowIdentities
);

This performs the same function as the cloneWithRows function but here you also specify what your sectionIdentities are. If you don't care about sections you should safely be able to use cloneWithRows.

sectionIdentities is an array of identifiers for sections. ie. ['s1', 's2', ...]. The identifiers should correspond to the keys or array indexes of the data you wish to include. If not provided, it's assumed that the keys of dataBlob are the section identities.

Note: this returns a new object!

const dataSource = ds.cloneWithRowsAndSections({
addresses: ['row 1', 'row 2'],
phone_numbers: ['data 1', 'data 2'],
}, ['phone_numbers']);

getRowCount()

getRowCount();

Returns the total number of rows in the data source.

If you are specifying the rowIdentities or sectionIdentities, then getRowCount will return the number of rows in the filtered data source.

getRowAndSectionCount()

getRowAndSectionCount();

Returns the total number of rows in the data source (see getRowCount for how this is calculated) plus the number of sections in the data.

If you are specifying the rowIdentities or sectionIdentities, then getRowAndSectionCount will return the number of rows & sections in the filtered data source.

rowShouldUpdate()

rowShouldUpdate(sectionIndex, rowIndex);

Returns if the row is dirtied and needs to be rerendered

getRowData()

getRowData(sectionIndex, rowIndex);

Gets the data required to render the row.

getRowIDForFlatIndex()

getRowIDForFlatIndex(index);

Gets the rowID at index provided if the dataSource arrays were flattened, or null of out of range indexes.

getSectionIDForFlatIndex()

getSectionIDForFlatIndex(index);

Gets the sectionID at index provided if the dataSource arrays were flattened, or null for out of range indexes.

getSectionLengths()

getSectionLengths();

Returns an array containing the number of rows in each section

sectionHeaderShouldUpdate()

sectionHeaderShouldUpdate(sectionIndex);

Returns if the section header is dirtied and needs to be rerendered

getSectionHeaderData()

getSectionHeaderData(sectionIndex);

Gets the data required to render the section header

Edit this page
Last updated on
- + diff --git a/docs/maskedviewios.html b/docs/maskedviewios.html index cfd09c29019..f5a3624cfde 100644 --- a/docs/maskedviewios.html +++ b/docs/maskedviewios.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
class MyMaskedView extends React.Component {
render() {
return (
// Determines shape of the mask
<MaskedViewIOS
style={{ flex: 1, flexDirection: 'row', height: '100%' }}
maskElement={
<View
style={{
// Transparent background because mask is based off alpha channel.
backgroundColor: 'transparent',
flex: 1,
justifyContent: 'center',
alignItems: 'center'
}}>
<Text
style={{
fontSize: 60,
color: 'black',
fontWeight: 'bold'
}}>
Basic Mask
</Text>
</View>
}>
{/* Shows behind the mask, you can put anything here, such as an image */}
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#324376'
}}
/>
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#F5DD90'
}}
/>
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#F76C5E'
}}
/>
</MaskedViewIOS>
);
}
}

The following image demonstrates that you can put almost anything behind the mask. The three examples shown are masked <View>, <Text>, and <Image>.

The alpha channel of the view rendered by the maskElement prop determines how much of the view's content and background shows through. Fully or partially opaque pixels allow the underlying content to show through but fully transparent pixels block that content.

Props

Reference

Props

maskElement

TypeRequired
elementYes
Edit this page
Last updated on
- + diff --git a/docs/maskedviewios/index.html b/docs/maskedviewios/index.html index cfd09c29019..f5a3624cfde 100644 --- a/docs/maskedviewios/index.html +++ b/docs/maskedviewios/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
class MyMaskedView extends React.Component {
render() {
return (
// Determines shape of the mask
<MaskedViewIOS
style={{ flex: 1, flexDirection: 'row', height: '100%' }}
maskElement={
<View
style={{
// Transparent background because mask is based off alpha channel.
backgroundColor: 'transparent',
flex: 1,
justifyContent: 'center',
alignItems: 'center'
}}>
<Text
style={{
fontSize: 60,
color: 'black',
fontWeight: 'bold'
}}>
Basic Mask
</Text>
</View>
}>
{/* Shows behind the mask, you can put anything here, such as an image */}
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#324376'
}}
/>
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#F5DD90'
}}
/>
<View
style={{
flex: 1,
height: '100%',
backgroundColor: '#F76C5E'
}}
/>
</MaskedViewIOS>
);
}
}

The following image demonstrates that you can put almost anything behind the mask. The three examples shown are masked <View>, <Text>, and <Image>.

The alpha channel of the view rendered by the maskElement prop determines how much of the view's content and background shows through. Fully or partially opaque pixels allow the underlying content to show through but fully transparent pixels block that content.

Props

Reference

Props

maskElement

TypeRequired
elementYes
Edit this page
Last updated on
- + diff --git a/docs/modal.html b/docs/modal.html index 623b26f998f..78e50ced265 100644 --- a/docs/modal.html +++ b/docs/modal.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Modal

The Modal component is a basic way to present content above an enclosing view.

Example

Reference

Props

animated

Deprecated. Use the animationType prop instead.

animationType

The animationType prop controls how the modal animates.

  • slide slides in from the bottom
  • fade fades into view
  • none appears without an animation

Default is set to none.

TypeRequired
enum('none', 'slide', 'fade')No

hardwareAccelerated

The hardwareAccelerated prop controls whether to force hardware acceleration for the underlying window.

TypeRequiredPlatform
boolNoAndroid

onDismiss

The onDismiss prop allows passing a function that will be called once the modal has been dismissed.

TypeRequiredPlatform
functionNoiOS

onOrientationChange

The onOrientationChange callback is called when the orientation changes while the modal is being displayed. The orientation provided is only 'portrait' or 'landscape'. This callback is also called on initial render, regardless of the current orientation.

TypeRequiredPlatform
functionNoiOS

onRequestClose

The onRequestClose callback is called when the user taps the hardware back button on Android or the menu button on Apple TV. Because of this required prop, be aware that BackHandler events will not be emitted as long as the modal is open.

TypeRequiredPlatform
functionYesAndroid, Platform.isTVOS
functionNo(Others)

onShow

The onShow prop allows passing a function that will be called once the modal has been shown.

TypeRequired
functionNo

presentationStyle

The presentationStyle prop controls how the modal appears (generally on larger devices such as iPad or plus-sized iPhones). See https://developer.apple.com/reference/uikit/uimodalpresentationstyle for details.

  • fullScreen covers the screen completely
  • pageSheet covers portrait-width view centered (only on larger devices)
  • formSheet covers narrow-width view centered (only on larger devices)
  • overFullScreen covers the screen completely, but allows transparency

Default is set to overFullScreen or fullScreen depending on transparent property.

TypeRequiredPlatform
enum('fullScreen', 'pageSheet', 'formSheet', 'overFullScreen')NoiOS

statusBarTranslucent

The statusBarTranslucent prop determines whether your modal should go under the system statusbar.

TypeRequiredPlatform
boolNoAndroid

supportedOrientations

The supportedOrientations prop allows the modal to be rotated to any of the specified orientations. On iOS, the modal is still restricted by what's specified in your app's Info.plist's UISupportedInterfaceOrientations field. When using presentationStyle of pageSheet or formSheet, this property will be ignored by iOS.

TypeRequiredPlatform
array of enum('portrait', 'portrait-upside-down', 'landscape', 'landscape-left', 'landscape-right')NoiOS

transparent

The transparent prop determines whether your modal will fill the entire view. Setting this to true will render the modal over a transparent background.

TypeRequired
boolNo

visible

The visible prop determines whether your modal is visible.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/modal/index.html b/docs/modal/index.html index 623b26f998f..78e50ced265 100644 --- a/docs/modal/index.html +++ b/docs/modal/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Modal

The Modal component is a basic way to present content above an enclosing view.

Example

Reference

Props

animated

Deprecated. Use the animationType prop instead.

animationType

The animationType prop controls how the modal animates.

  • slide slides in from the bottom
  • fade fades into view
  • none appears without an animation

Default is set to none.

TypeRequired
enum('none', 'slide', 'fade')No

hardwareAccelerated

The hardwareAccelerated prop controls whether to force hardware acceleration for the underlying window.

TypeRequiredPlatform
boolNoAndroid

onDismiss

The onDismiss prop allows passing a function that will be called once the modal has been dismissed.

TypeRequiredPlatform
functionNoiOS

onOrientationChange

The onOrientationChange callback is called when the orientation changes while the modal is being displayed. The orientation provided is only 'portrait' or 'landscape'. This callback is also called on initial render, regardless of the current orientation.

TypeRequiredPlatform
functionNoiOS

onRequestClose

The onRequestClose callback is called when the user taps the hardware back button on Android or the menu button on Apple TV. Because of this required prop, be aware that BackHandler events will not be emitted as long as the modal is open.

TypeRequiredPlatform
functionYesAndroid, Platform.isTVOS
functionNo(Others)

onShow

The onShow prop allows passing a function that will be called once the modal has been shown.

TypeRequired
functionNo

presentationStyle

The presentationStyle prop controls how the modal appears (generally on larger devices such as iPad or plus-sized iPhones). See https://developer.apple.com/reference/uikit/uimodalpresentationstyle for details.

  • fullScreen covers the screen completely
  • pageSheet covers portrait-width view centered (only on larger devices)
  • formSheet covers narrow-width view centered (only on larger devices)
  • overFullScreen covers the screen completely, but allows transparency

Default is set to overFullScreen or fullScreen depending on transparent property.

TypeRequiredPlatform
enum('fullScreen', 'pageSheet', 'formSheet', 'overFullScreen')NoiOS

statusBarTranslucent

The statusBarTranslucent prop determines whether your modal should go under the system statusbar.

TypeRequiredPlatform
boolNoAndroid

supportedOrientations

The supportedOrientations prop allows the modal to be rotated to any of the specified orientations. On iOS, the modal is still restricted by what's specified in your app's Info.plist's UISupportedInterfaceOrientations field. When using presentationStyle of pageSheet or formSheet, this property will be ignored by iOS.

TypeRequiredPlatform
array of enum('portrait', 'portrait-upside-down', 'landscape', 'landscape-left', 'landscape-right')NoiOS

transparent

The transparent prop determines whether your modal will fill the entire view. Setting this to true will render the modal over a transparent background.

TypeRequired
boolNo

visible

The visible prop determines whether your modal is visible.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/more-resources.html b/docs/more-resources.html index 49dd76791c3..acf83bad2c4 100644 --- a/docs/more-resources.html +++ b/docs/more-resources.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

More Resources

There’s always more to learn: developer workflows, shipping to app stores, internationalization, security and more.

Where to go from here

Dive deep

IDEs

We recommend using the VS Code code editor and its handy React Native tools.

Platforms to try

Expo is a framework of tools and services for React Native that focuses on letting you build React Native apps without ever touching Xcode or Android Studio. If you have a web development background, this might appeal to you.

Ignite is a starter kit that uses Redux for state management and a few different common UI libraries. It has a CLI to generate apps, components, and containers. If you like all of the individual tech choices, Ignite could be perfect for you.

Example Apps

Try out apps from the Showcase to see what React Native is capable of! Looking for something more hands on? Check out this set of example apps on GitHub. You can look at their source code—try running one on a simulator or device.

Find, make, and share your own Native Components and Modules

React Native has a community of thousands of developers like you making content, tools, tutorials—and Native Components!

Can’t find what you’re looking for in the Core Components? Visit React Native Directory to find what the community has been creating.

Interested in making your own Native Component or Module? Making modules for your own use case and sharing them with others on NPM and GitHub helps grow the React Native ecosystem and community! Read the guides to making your own Native Modules (Android, iOS) and Native Components (Android, iOS).

Edit this page
Last updated on
- + diff --git a/docs/more-resources/index.html b/docs/more-resources/index.html index 49dd76791c3..acf83bad2c4 100644 --- a/docs/more-resources/index.html +++ b/docs/more-resources/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

More Resources

There’s always more to learn: developer workflows, shipping to app stores, internationalization, security and more.

Where to go from here

Dive deep

IDEs

We recommend using the VS Code code editor and its handy React Native tools.

Platforms to try

Expo is a framework of tools and services for React Native that focuses on letting you build React Native apps without ever touching Xcode or Android Studio. If you have a web development background, this might appeal to you.

Ignite is a starter kit that uses Redux for state management and a few different common UI libraries. It has a CLI to generate apps, components, and containers. If you like all of the individual tech choices, Ignite could be perfect for you.

Example Apps

Try out apps from the Showcase to see what React Native is capable of! Looking for something more hands on? Check out this set of example apps on GitHub. You can look at their source code—try running one on a simulator or device.

Find, make, and share your own Native Components and Modules

React Native has a community of thousands of developers like you making content, tools, tutorials—and Native Components!

Can’t find what you’re looking for in the Core Components? Visit React Native Directory to find what the community has been creating.

Interested in making your own Native Component or Module? Making modules for your own use case and sharing them with others on NPM and GitHub helps grow the React Native ecosystem and community! Read the guides to making your own Native Modules (Android, iOS) and Native Components (Android, iOS).

Edit this page
Last updated on
- + diff --git a/docs/native-components-android.html b/docs/native-components-android.html index bde6665bdc3..6e247bda658 100644 --- a/docs/native-components-android.html +++ b/docs/native-components-android.html @@ -19,7 +19,7 @@ - + @@ -43,7 +43,7 @@
var RCTMyCustomView = requireNativeComponent(`RCTMyCustomView`);
Edit this page
Last updated on
- + diff --git a/docs/native-components-android/index.html b/docs/native-components-android/index.html index bde6665bdc3..6e247bda658 100644 --- a/docs/native-components-android/index.html +++ b/docs/native-components-android/index.html @@ -19,7 +19,7 @@ - + @@ -43,7 +43,7 @@
var RCTMyCustomView = requireNativeComponent(`RCTMyCustomView`);
Edit this page
Last updated on
- + diff --git a/docs/native-components-ios.html b/docs/native-components-ios.html index 8591e5d7a34..c85e4274e5f 100644 --- a/docs/native-components-ios.html +++ b/docs/native-components-ios.html @@ -19,7 +19,7 @@ - + @@ -96,7 +96,7 @@
return @{
@"ComponentHeight": @(CGRectGetHeight(dp.frame)),
@"ComponentWidth": @(CGRectGetWidth(dp.frame)),
@"DatePickerModes": @{
@"time": @(UIDatePickerModeTime),
@"date": @(UIDatePickerModeDate),
@"datetime": @(UIDatePickerModeDateAndTime),
}
};
}

This guide covered many of the aspects of bridging over custom native components, but there is even more you might need to consider, such as custom hooks for inserting and laying out subviews. If you want to go even deeper, check out the source code of some of the implemented components.

Edit this page
Last updated on
- + diff --git a/docs/native-components-ios/index.html b/docs/native-components-ios/index.html index 8591e5d7a34..c85e4274e5f 100644 --- a/docs/native-components-ios/index.html +++ b/docs/native-components-ios/index.html @@ -19,7 +19,7 @@ - + @@ -96,7 +96,7 @@
return @{
@"ComponentHeight": @(CGRectGetHeight(dp.frame)),
@"ComponentWidth": @(CGRectGetWidth(dp.frame)),
@"DatePickerModes": @{
@"time": @(UIDatePickerModeTime),
@"date": @(UIDatePickerModeDate),
@"datetime": @(UIDatePickerModeDateAndTime),
}
};
}

This guide covered many of the aspects of bridging over custom native components, but there is even more you might need to consider, such as custom hooks for inserting and laying out subviews. If you want to go even deeper, check out the source code of some of the implemented components.

Edit this page
Last updated on
- + diff --git a/docs/native-modules-android.html b/docs/native-modules-android.html index a97b717c738..27953e0bb62 100644 --- a/docs/native-modules-android.html +++ b/docs/native-modules-android.html @@ -19,7 +19,7 @@ - + @@ -67,7 +67,7 @@
currentActivity.startActivityForResult(chooserIntent, IMAGE_PICKER_REQUEST);
} catch (Exception e) {
mPickerPromise.reject(E_FAILED_TO_SHOW_PICKER, e);
mPickerPromise = null;
}
}
}

Listening to Lifecycle Events

Listening to the activity's LifeCycle events such as onResume, onPause etc. is very similar to how ActivityEventListener was implemented. The module must implement LifecycleEventListener. Then, you need to register a listener in the module's constructor like so:

reactContext.addLifecycleEventListener(this);

Now you can listen to the activity's LifeCycle events by implementing the following methods:

@Override
public void onHostResume() {
// Activity `onResume`
}
@Override
public void onHostPause() {
// Activity `onPause`
}
@Override
public void onHostDestroy() {
// Activity `onDestroy`
}

Threading

To date, on Android, all native module async methods execute on one thread. Native modules should not have any assumptions about what thread they are being called on, as the current assignment is subject to change in the future. If a blocking call is required, the heavy work should be dispatched to an internally managed worker thread, and any callbacks distributed from there.

Edit this page
Last updated on
- + diff --git a/docs/native-modules-android/index.html b/docs/native-modules-android/index.html index a97b717c738..27953e0bb62 100644 --- a/docs/native-modules-android/index.html +++ b/docs/native-modules-android/index.html @@ -19,7 +19,7 @@ - + @@ -67,7 +67,7 @@
currentActivity.startActivityForResult(chooserIntent, IMAGE_PICKER_REQUEST);
} catch (Exception e) {
mPickerPromise.reject(E_FAILED_TO_SHOW_PICKER, e);
mPickerPromise = null;
}
}
}

Listening to Lifecycle Events

Listening to the activity's LifeCycle events such as onResume, onPause etc. is very similar to how ActivityEventListener was implemented. The module must implement LifecycleEventListener. Then, you need to register a listener in the module's constructor like so:

reactContext.addLifecycleEventListener(this);

Now you can listen to the activity's LifeCycle events by implementing the following methods:

@Override
public void onHostResume() {
// Activity `onResume`
}
@Override
public void onHostPause() {
// Activity `onPause`
}
@Override
public void onHostDestroy() {
// Activity `onDestroy`
}

Threading

To date, on Android, all native module async methods execute on one thread. Native modules should not have any assumptions about what thread they are being called on, as the current assignment is subject to change in the future. If a blocking call is required, the heavy work should be dispatched to an internally managed worker thread, and any callbacks distributed from there.

Edit this page
Last updated on
- + diff --git a/docs/native-modules-intro.html b/docs/native-modules-intro.html index 25301b5c692..ee2d2ed82ca 100644 --- a/docs/native-modules-intro.html +++ b/docs/native-modules-intro.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Native Modules Intro

Sometimes a React Native app needs to access a native platform API that is not available by default in JavaScript, for example the native APIs to access Apple or Google Pay. Maybe you want to reuse some existing Objective-C, Swift, Java or C++ libraries without having to reimplement it in JavaScript, or write some high performance, multi-threaded code for things like image processing.

The NativeModule system exposes instances of Java/Objective-C/C++ (native) classes to JavaScript (JS) as JS objects, thereby allowing you to execute arbitrary native code from within JS. While we don't expect this feature to be part of the usual development process, it is essential that it exists. If React Native doesn't export a native API that your JS app needs you should be able to export it yourself!

Native Module Setup

There are two ways to write a native module for your React Native application:

  1. Directly within your React Native application’s iOS/Android projects
  2. As a NPM package that can be installed as a dependency by your/other React Native applications

This guide will first walk you through implementing a native module directly within a React Native application. However the native module you build in the following guide can be distributed as an NPM package. Check out the Setting Up a Native Module as a NPM Package guide if you are interested in doing so.

Getting Started

In the following sections we will walk you through guides on how to build a native module directly within a React Native application. As a prerequisite, you will need a React Native application to work within. You can follow the steps here to setup a React Native application if you do not already have one.

Imagine that you want to access the iOS/Android native calendar APIs from JavaScript within a React Native application in order to create calendar events. React Native does not expose a JavaScript API to communicate with the native calendar libraries. However, through native modules, you can write native code that communicates with native calendar APIs. Then you can invoke that native code through JavaScript in your React Native application.

In the following sections you will create such a Calendar native module for both Android and iOS.

Edit this page
Last updated on
- + diff --git a/docs/native-modules-intro/index.html b/docs/native-modules-intro/index.html index 25301b5c692..ee2d2ed82ca 100644 --- a/docs/native-modules-intro/index.html +++ b/docs/native-modules-intro/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Native Modules Intro

Sometimes a React Native app needs to access a native platform API that is not available by default in JavaScript, for example the native APIs to access Apple or Google Pay. Maybe you want to reuse some existing Objective-C, Swift, Java or C++ libraries without having to reimplement it in JavaScript, or write some high performance, multi-threaded code for things like image processing.

The NativeModule system exposes instances of Java/Objective-C/C++ (native) classes to JavaScript (JS) as JS objects, thereby allowing you to execute arbitrary native code from within JS. While we don't expect this feature to be part of the usual development process, it is essential that it exists. If React Native doesn't export a native API that your JS app needs you should be able to export it yourself!

Native Module Setup

There are two ways to write a native module for your React Native application:

  1. Directly within your React Native application’s iOS/Android projects
  2. As a NPM package that can be installed as a dependency by your/other React Native applications

This guide will first walk you through implementing a native module directly within a React Native application. However the native module you build in the following guide can be distributed as an NPM package. Check out the Setting Up a Native Module as a NPM Package guide if you are interested in doing so.

Getting Started

In the following sections we will walk you through guides on how to build a native module directly within a React Native application. As a prerequisite, you will need a React Native application to work within. You can follow the steps here to setup a React Native application if you do not already have one.

Imagine that you want to access the iOS/Android native calendar APIs from JavaScript within a React Native application in order to create calendar events. React Native does not expose a JavaScript API to communicate with the native calendar libraries. However, through native modules, you can write native code that communicates with native calendar APIs. Then you can invoke that native code through JavaScript in your React Native application.

In the following sections you will create such a Calendar native module for both Android and iOS.

Edit this page
Last updated on
- + diff --git a/docs/native-modules-ios.html b/docs/native-modules-ios.html index 96ad2c18c3a..e9987b08ea4 100644 --- a/docs/native-modules-ios.html +++ b/docs/native-modules-ios.html @@ -19,7 +19,7 @@ - + @@ -64,7 +64,7 @@
@end

For those of you new to Swift and Objective-C, whenever you mix the two languages in an iOS project, you will also need an additional bridging file, known as a bridging header, to expose the Objective-C files to Swift. Xcode will offer to create this header file for you if you add your Swift file to your app through the Xcode File>New File menu option. You will need to import RCTBridgeModule.h in this header file.

// CalendarManager-Bridging-Header.h
#import <React/RCTBridgeModule.h>

You can also use RCT_EXTERN_REMAP_MODULE and _RCT_EXTERN_REMAP_METHOD to alter the JavaScript name of the module or methods you are exporting. For more information see RCTBridgeModule.

Important when making third party modules: Static libraries with Swift are only supported in Xcode 9 and later. In order for the Xcode project to build when you use Swift in the iOS static library you include in the module, your main app project must contain Swift code and a bridging header itself. If your app project does not contain any Swift code, a workaround can be a single empty .swift file and an empty bridging header.

Reserved Method Names

invalidate()

Native modules can conform to the RCTInvalidating protocol on iOS by implementing the invalidate() method. This method can be invoked when the native bridge is invalidated (ie: on devmode reload). Please use this mechanism as necessary to do the required cleanup for your native module.

Edit this page
Last updated on
- + diff --git a/docs/native-modules-ios/index.html b/docs/native-modules-ios/index.html index 96ad2c18c3a..e9987b08ea4 100644 --- a/docs/native-modules-ios/index.html +++ b/docs/native-modules-ios/index.html @@ -19,7 +19,7 @@ - + @@ -64,7 +64,7 @@
@end

For those of you new to Swift and Objective-C, whenever you mix the two languages in an iOS project, you will also need an additional bridging file, known as a bridging header, to expose the Objective-C files to Swift. Xcode will offer to create this header file for you if you add your Swift file to your app through the Xcode File>New File menu option. You will need to import RCTBridgeModule.h in this header file.

// CalendarManager-Bridging-Header.h
#import <React/RCTBridgeModule.h>

You can also use RCT_EXTERN_REMAP_MODULE and _RCT_EXTERN_REMAP_METHOD to alter the JavaScript name of the module or methods you are exporting. For more information see RCTBridgeModule.

Important when making third party modules: Static libraries with Swift are only supported in Xcode 9 and later. In order for the Xcode project to build when you use Swift in the iOS static library you include in the module, your main app project must contain Swift code and a bridging header itself. If your app project does not contain any Swift code, a workaround can be a single empty .swift file and an empty bridging header.

Reserved Method Names

invalidate()

Native modules can conform to the RCTInvalidating protocol on iOS by implementing the invalidate() method. This method can be invoked when the native bridge is invalidated (ie: on devmode reload). Please use this mechanism as necessary to do the required cleanup for your native module.

Edit this page
Last updated on
- + diff --git a/docs/native-modules-setup.html b/docs/native-modules-setup.html index 72a8797972c..c9b4a1a2550 100644 --- a/docs/native-modules-setup.html +++ b/docs/native-modules-setup.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Native Modules NPM Package Setup

Native modules are usually distributed as npm packages, except that on top of the usual JavaScript they will include some native code per platform. To understand more about npm packages you may find this guide useful.

To get set up with the basic project structure for a native module we will use the community tool called Bob. You can go ahead further and dive deep into how that library works, but for our needs we will only execute the basic create script:

npx @react-native-community/bob create react-native-awesome-module

Where react-native-awesome-module is the name you would like for the new module. After doing this you will navigate into react-native-awesome-module folder and bootstrap the example project by running:

yarn bootstrap

When the bootstrap is done, you will be able to start the example app by executing one of the following commands:

# Android app
yarn example android
# iOS app
yarn example ios

When all steps above are done, you will be able to continue with Android Native Modules or iOS Native Modules guides to add in some code.

For a less opinionated setup, have a look at the third party tool create-react-native-module.

Edit this page
Last updated on
- + diff --git a/docs/native-modules-setup/index.html b/docs/native-modules-setup/index.html index 72a8797972c..c9b4a1a2550 100644 --- a/docs/native-modules-setup/index.html +++ b/docs/native-modules-setup/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Native Modules NPM Package Setup

Native modules are usually distributed as npm packages, except that on top of the usual JavaScript they will include some native code per platform. To understand more about npm packages you may find this guide useful.

To get set up with the basic project structure for a native module we will use the community tool called Bob. You can go ahead further and dive deep into how that library works, but for our needs we will only execute the basic create script:

npx @react-native-community/bob create react-native-awesome-module

Where react-native-awesome-module is the name you would like for the new module. After doing this you will navigate into react-native-awesome-module folder and bootstrap the example project by running:

yarn bootstrap

When the bootstrap is done, you will be able to start the example app by executing one of the following commands:

# Android app
yarn example android
# iOS app
yarn example ios

When all steps above are done, you will be able to continue with Android Native Modules or iOS Native Modules guides to add in some code.

For a less opinionated setup, have a look at the third party tool create-react-native-module.

Edit this page
Last updated on
- + diff --git a/docs/navigation.html b/docs/navigation.html index 20b72f8f25d..d277a2faa5a 100644 --- a/docs/navigation.html +++ b/docs/navigation.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
const MyStack = () => {
return (
<NavigationContainer>
<Stack.Navigator>
<Stack.Screen
name="Home"
component={HomeScreen}
options={{ title: 'Welcome' }}
/>
<Stack.Screen name="Profile" component={ProfileScreen} />
</Stack.Navigator>
</NavigationContainer>
);
};

In this example, there are 2 screens (Home and Profile) defined using the Stack.Screen component. Similarly, you can define as many screens as you like.

You can set options such as the screen title for each screen in the options prop of Stack.Screen.

Each screen takes a component prop that is a React component. Those components receive a prop called navigation which has various methods to link to other screens. For example, you can use navigation.navigate to go to the Profile screen:

const HomeScreen = ({ navigation }) => {
return (
<Button
title="Go to Jane's profile"
onPress={() =>
navigation.navigate('Profile', { name: 'Jane' })
}
/>
);
};
const ProfileScreen = ({ navigation, route }) => {
return <Text>This is {route.params.name}'s profile</Text>;
};

The views in the stack navigator use native components and the Animated library to deliver 60fps animations that are run on the native thread. Plus, the animations and gestures can be customized.

React Navigation also has packages for different kind of navigators such as tabs and drawer. You can use them to implement various patterns in your app.

For a complete intro to React Navigation, follow the React Navigation Getting Started Guide.

Edit this page
Last updated on
- + diff --git a/docs/navigation/index.html b/docs/navigation/index.html index 20b72f8f25d..d277a2faa5a 100644 --- a/docs/navigation/index.html +++ b/docs/navigation/index.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
const MyStack = () => {
return (
<NavigationContainer>
<Stack.Navigator>
<Stack.Screen
name="Home"
component={HomeScreen}
options={{ title: 'Welcome' }}
/>
<Stack.Screen name="Profile" component={ProfileScreen} />
</Stack.Navigator>
</NavigationContainer>
);
};

In this example, there are 2 screens (Home and Profile) defined using the Stack.Screen component. Similarly, you can define as many screens as you like.

You can set options such as the screen title for each screen in the options prop of Stack.Screen.

Each screen takes a component prop that is a React component. Those components receive a prop called navigation which has various methods to link to other screens. For example, you can use navigation.navigate to go to the Profile screen:

const HomeScreen = ({ navigation }) => {
return (
<Button
title="Go to Jane's profile"
onPress={() =>
navigation.navigate('Profile', { name: 'Jane' })
}
/>
);
};
const ProfileScreen = ({ navigation, route }) => {
return <Text>This is {route.params.name}'s profile</Text>;
};

The views in the stack navigator use native components and the Animated library to deliver 60fps animations that are run on the native thread. Plus, the animations and gestures can be customized.

React Navigation also has packages for different kind of navigators such as tabs and drawer. You can use them to implement various patterns in your app.

For a complete intro to React Navigation, follow the React Navigation Getting Started Guide.

Edit this page
Last updated on
- + diff --git a/docs/netinfo.html b/docs/netinfo.html index bc10897f789..6243ef6a156 100644 --- a/docs/netinfo.html +++ b/docs/netinfo.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

NetInfo

Deprecated. Use one of the community packages instead.

NetInfo exposes info about online/offline status

NetInfo.getConnectionInfo().then((connectionInfo) => {
console.log(
'Initial, type: ' +
connectionInfo.type +
', effectiveType: ' +
connectionInfo.effectiveType
);
});
function handleFirstConnectivityChange(connectionInfo) {
console.log(
'First change, type: ' +
connectionInfo.type +
', effectiveType: ' +
connectionInfo.effectiveType
);
NetInfo.removeEventListener(
'connectionChange',
handleFirstConnectivityChange
);
}
NetInfo.addEventListener(
'connectionChange',
handleFirstConnectivityChange
);

ConnectionType enum

ConnectionType describes the type of connection the device is using to communicate with the network.

Cross platform values for ConnectionType:

  • none - device is offline
  • wifi - device is online and connected via wifi, or is the iOS simulator
  • cellular - device is connected via Edge, 3G, WiMax, or LTE
  • unknown - error case and the network status is unknown

Android-only values for ConnectionType:

  • bluetooth - device is connected via Bluetooth
  • ethernet - device is connected via Ethernet
  • wimax - device is connected via WiMAX

EffectiveConnectionType enum

Cross platform values for EffectiveConnectionType:

  • 2g
  • 3g
  • 4g
  • unknown

Android

To request network info, you need to add the following line to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Methods

Properties

Reference

Methods

addEventListener()

NetInfo.addEventListener(eventName, handler);

Adds an event handler.

Parameters:

NameTypeRequiredDescription
eventNameenum(connectionChange, change)YesThe change event name.
handlerfunctionYesListener function.

Supported events:

  • connectionChange: Fires when the network status changes. The argument to the event handler is an object with keys:
    • type: A ConnectionType (listed above)
    • effectiveType: An EffectiveConnectionType (listed above)
  • change: This event is deprecated. Listen to connectionChange instead. Fires when the network status changes. The argument to the event handler is one of the deprecated connectivity types listed above.

removeEventListener()

NetInfo.removeEventListener(eventName, handler);

Removes the listener for network status changes.

Parameters:

NameTypeRequiredDescription
eventNameenum(connectionChange, change)YesThe change event name.
handlerfunctionYesListener function.

getConnectionInfo()

NetInfo.getConnectionInfo();

Returns a promise that resolves to an object with type and effectiveType keys whose values are a ConnectionType and an EffectiveConnectionType), respectively.

isConnectionExpensive()

NetInfo.isConnectionExpensive();

Available on Android. Detect if the current active connection is metered or not. A network is classified as metered when the user is sensitive to heavy data usage on that connection due to monetary costs, data limitations or battery/performance issues.

NetInfo.isConnectionExpensive()
.then(isConnectionExpensive => {
console.log('Connection is ' + (isConnectionExpensive ? 'Expensive' : 'Not Expensive'));
})
.catch(error => {
console.error(error);
});

Properties

isConnected

Available on all platforms. Asynchronously fetch a boolean to determine internet connectivity.

NetInfo.isConnected.fetch().then(isConnected => {
console.log('First, is ' + (isConnected ? 'online' : 'offline'));
});
function handleFirstConnectivityChange(isConnected) {
console.log('Then, is ' + (isConnected ? 'online' : 'offline'));
NetInfo.isConnected.removeEventListener(
'connectionChange',
handleFirstConnectivityChange
);
}
NetInfo.isConnected.addEventListener(
'connectionChange',
handleFirstConnectivityChange
);
Edit this page
Last updated on
- + diff --git a/docs/netinfo/index.html b/docs/netinfo/index.html index bc10897f789..6243ef6a156 100644 --- a/docs/netinfo/index.html +++ b/docs/netinfo/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

NetInfo

Deprecated. Use one of the community packages instead.

NetInfo exposes info about online/offline status

NetInfo.getConnectionInfo().then((connectionInfo) => {
console.log(
'Initial, type: ' +
connectionInfo.type +
', effectiveType: ' +
connectionInfo.effectiveType
);
});
function handleFirstConnectivityChange(connectionInfo) {
console.log(
'First change, type: ' +
connectionInfo.type +
', effectiveType: ' +
connectionInfo.effectiveType
);
NetInfo.removeEventListener(
'connectionChange',
handleFirstConnectivityChange
);
}
NetInfo.addEventListener(
'connectionChange',
handleFirstConnectivityChange
);

ConnectionType enum

ConnectionType describes the type of connection the device is using to communicate with the network.

Cross platform values for ConnectionType:

  • none - device is offline
  • wifi - device is online and connected via wifi, or is the iOS simulator
  • cellular - device is connected via Edge, 3G, WiMax, or LTE
  • unknown - error case and the network status is unknown

Android-only values for ConnectionType:

  • bluetooth - device is connected via Bluetooth
  • ethernet - device is connected via Ethernet
  • wimax - device is connected via WiMAX

EffectiveConnectionType enum

Cross platform values for EffectiveConnectionType:

  • 2g
  • 3g
  • 4g
  • unknown

Android

To request network info, you need to add the following line to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Methods

Properties

Reference

Methods

addEventListener()

NetInfo.addEventListener(eventName, handler);

Adds an event handler.

Parameters:

NameTypeRequiredDescription
eventNameenum(connectionChange, change)YesThe change event name.
handlerfunctionYesListener function.

Supported events:

  • connectionChange: Fires when the network status changes. The argument to the event handler is an object with keys:
    • type: A ConnectionType (listed above)
    • effectiveType: An EffectiveConnectionType (listed above)
  • change: This event is deprecated. Listen to connectionChange instead. Fires when the network status changes. The argument to the event handler is one of the deprecated connectivity types listed above.

removeEventListener()

NetInfo.removeEventListener(eventName, handler);

Removes the listener for network status changes.

Parameters:

NameTypeRequiredDescription
eventNameenum(connectionChange, change)YesThe change event name.
handlerfunctionYesListener function.

getConnectionInfo()

NetInfo.getConnectionInfo();

Returns a promise that resolves to an object with type and effectiveType keys whose values are a ConnectionType and an EffectiveConnectionType), respectively.

isConnectionExpensive()

NetInfo.isConnectionExpensive();

Available on Android. Detect if the current active connection is metered or not. A network is classified as metered when the user is sensitive to heavy data usage on that connection due to monetary costs, data limitations or battery/performance issues.

NetInfo.isConnectionExpensive()
.then(isConnectionExpensive => {
console.log('Connection is ' + (isConnectionExpensive ? 'Expensive' : 'Not Expensive'));
})
.catch(error => {
console.error(error);
});

Properties

isConnected

Available on all platforms. Asynchronously fetch a boolean to determine internet connectivity.

NetInfo.isConnected.fetch().then(isConnected => {
console.log('First, is ' + (isConnected ? 'online' : 'offline'));
});
function handleFirstConnectivityChange(isConnected) {
console.log('Then, is ' + (isConnected ? 'online' : 'offline'));
NetInfo.isConnected.removeEventListener(
'connectionChange',
handleFirstConnectivityChange
);
}
NetInfo.isConnected.addEventListener(
'connectionChange',
handleFirstConnectivityChange
);
Edit this page
Last updated on
- + diff --git a/docs/network.html b/docs/network.html index e62899a932b..3fcb83947a8 100644 --- a/docs/network.html +++ b/docs/network.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
ws.onclose = (e) => {
// connection closed
console.log(e.code, e.reason);
};

Known Issues with fetch and cookie based authentication

The following options are currently not working with fetch

Edit this page
Last updated on
- + diff --git a/docs/network/index.html b/docs/network/index.html index e62899a932b..3fcb83947a8 100644 --- a/docs/network/index.html +++ b/docs/network/index.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
ws.onclose = (e) => {
// connection closed
console.log(e.code, e.reason);
};

Known Issues with fetch and cookie based authentication

The following options are currently not working with fetch

Edit this page
Last updated on
- + diff --git a/docs/next/_getting-started-linux-android.html b/docs/next/_getting-started-linux-android.html index 0137a72058a..4a5444117f5 100644 --- a/docs/next/_getting-started-linux-android.html +++ b/docs/next/_getting-started-linux-android.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: Next

_getting-started-linux-android

Installing dependencies

You will need Node, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node

Follow the installation instructions for your Linux distribution to install Node 12 or newer.

Java Development Kit

React Native requires at least the version 8 of the Java SE Development Kit (JDK). You may download and install OpenJDK from AdoptOpenJDK or your system packager. You may also Download and install Oracle JDK 14 if desired.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

Add the following lines to your $HOME/.bash_profile or $HOME/.bashrc (if you are using zsh then ~/.zprofile or ~/.zshrc) config file:

export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

.bash_profile is specific to bash. If you're using another shell, you will need to edit the appropriate shell-specific config file.

Type source $HOME/.bash_profile for bash or source $HOME/.zprofile to load the config into your current shell. Verify that ANDROID_HOME has been set by running echo $ANDROID_HOME and the appropriate directories have been added to your path by running echo $PATH.

Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Watchman

Follow the Watchman installation guide to compile and install Watchman from source.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance and increased compatibility in certain edge cases (translation: you may be able to get by without installing this, but your mileage may vary; installing this now may save you from a headache later).

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Integration with Existing Apps). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

We recommend configuring VM acceleration on your system to improve performance. Once you've followed those instructions, go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (Ctrl + M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/next/_getting-started-linux-android/index.html b/docs/next/_getting-started-linux-android/index.html index 0137a72058a..4a5444117f5 100644 --- a/docs/next/_getting-started-linux-android/index.html +++ b/docs/next/_getting-started-linux-android/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: Next

_getting-started-linux-android

Installing dependencies

You will need Node, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node

Follow the installation instructions for your Linux distribution to install Node 12 or newer.

Java Development Kit

React Native requires at least the version 8 of the Java SE Development Kit (JDK). You may download and install OpenJDK from AdoptOpenJDK or your system packager. You may also Download and install Oracle JDK 14 if desired.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

Add the following lines to your $HOME/.bash_profile or $HOME/.bashrc (if you are using zsh then ~/.zprofile or ~/.zshrc) config file:

export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

.bash_profile is specific to bash. If you're using another shell, you will need to edit the appropriate shell-specific config file.

Type source $HOME/.bash_profile for bash or source $HOME/.zprofile to load the config into your current shell. Verify that ANDROID_HOME has been set by running echo $ANDROID_HOME and the appropriate directories have been added to your path by running echo $PATH.

Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Watchman

Follow the Watchman installation guide to compile and install Watchman from source.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance and increased compatibility in certain edge cases (translation: you may be able to get by without installing this, but your mileage may vary; installing this now may save you from a headache later).

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Integration with Existing Apps). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

We recommend configuring VM acceleration on your system to improve performance. Once you've followed those instructions, go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (Ctrl + M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/next/_getting-started-macos-android.html b/docs/next/_getting-started-macos-android.html index 5557ad102d3..9a98231624b 100644 --- a/docs/next/_getting-started-macos-android.html +++ b/docs/next/_getting-started-macos-android.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: Next

_getting-started-macos-android

Installing dependencies

You will need Node, Watchman, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node & Watchman

We recommend installing Node and Watchman using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install node
brew install watchman

If you have already installed Node on your system, make sure it is Node 12 or newer.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

Java Development Kit

We recommend installing JDK using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install --cask adoptopenjdk/openjdk/adoptopenjdk8

If you have already installed JDK on your system, make sure it is JDK 8 or newer.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

Android Studio Welcome

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

Add the following lines to your $HOME/.bash_profile or $HOME/.bashrc (if you are using zsh then ~/.zprofile or ~/.zshrc) config file:

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

.bash_profile is specific to bash. If you're using another shell, you will need to edit the appropriate shell-specific config file.

Type source $HOME/.bash_profile for bash or source $HOME/.zprofile to load the config into your current shell. Verify that ANDROID_HOME has been set by running echo $ANDROID_HOME and the appropriate directories have been added to your path by running echo $PATH.

Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Integration with Existing Apps). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

AwesomeProject on Android

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (⌘M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/next/_getting-started-macos-android/index.html b/docs/next/_getting-started-macos-android/index.html index 5557ad102d3..9a98231624b 100644 --- a/docs/next/_getting-started-macos-android/index.html +++ b/docs/next/_getting-started-macos-android/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: Next

_getting-started-macos-android

Installing dependencies

You will need Node, Watchman, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node & Watchman

We recommend installing Node and Watchman using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install node
brew install watchman

If you have already installed Node on your system, make sure it is Node 12 or newer.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

Java Development Kit

We recommend installing JDK using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install --cask adoptopenjdk/openjdk/adoptopenjdk8

If you have already installed JDK on your system, make sure it is JDK 8 or newer.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

Android Studio Welcome

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

Add the following lines to your $HOME/.bash_profile or $HOME/.bashrc (if you are using zsh then ~/.zprofile or ~/.zshrc) config file:

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

.bash_profile is specific to bash. If you're using another shell, you will need to edit the appropriate shell-specific config file.

Type source $HOME/.bash_profile for bash or source $HOME/.zprofile to load the config into your current shell. Verify that ANDROID_HOME has been set by running echo $ANDROID_HOME and the appropriate directories have been added to your path by running echo $PATH.

Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Integration with Existing Apps). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

AwesomeProject on Android

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (⌘M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/next/_getting-started-macos-ios.html b/docs/next/_getting-started-macos-ios.html index d43ca88830f..e4faf2bfdf2 100644 --- a/docs/next/_getting-started-macos-ios.html +++ b/docs/next/_getting-started-macos-ios.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: Next

_getting-started-macos-ios

Installing dependencies

You will need Node, Watchman, the React Native command line interface, Xcode and CocoaPods.

While you can use any editor of your choice to develop your app, you will need to install Xcode in order to set up the necessary tooling to build your React Native app for iOS.

Node & Watchman

We recommend installing Node and Watchman using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install node
brew install watchman

If you have already installed Node on your system, make sure it is Node 12 or newer.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

Xcode

The easiest way to install Xcode is via the Mac App Store. Installing Xcode will also install the iOS Simulator and all the necessary tools to build your iOS app.

If you have already installed Xcode on your system, make sure it is version 10 or newer.

Command Line Tools

You will also need to install the Xcode Command Line Tools. Open Xcode, then choose "Preferences..." from the Xcode menu. Go to the Locations panel and install the tools by selecting the most recent version in the Command Line Tools dropdown.

Xcode Command Line Tools

Installing an iOS Simulator in Xcode

To install a simulator, open Xcode > Preferences... and select the Components tab. Select a simulator with the corresponding version of iOS you wish to use.

CocoaPods

CocoaPods is built with Ruby and it will be installable with the default Ruby available on macOS. You can use a Ruby Version manager, however we recommend that you use the standard Ruby available on macOS unless you know what you're doing.

Using the default Ruby install will require you to use sudo when installing gems. (This is only an issue for the duration of the gem installation, though.)

sudo gem install cocoapods

For more information, please visit CocoaPods Getting Started guide.

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

You can use React Native's built-in command line interface to generate a new project. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding iOS support to an existing React Native project (see Integration with Existing Apps). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Note If the above command is failing, you may have old version of react-native or react-native-cli installed globally on your pc. Try uninstalling the cli and run the cli using npx.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-ios

You should see your new app running in the iOS Simulator shortly.

AwesomeProject on iOS

npx react-native run-ios is one way to run your app. You can also run it directly from within Xcode.

If you can't get this to work, see the Troubleshooting page.

Running on a device

The above command will automatically run your app on the iOS Simulator by default. If you want to run the app on an actual physical iOS device, please follow the instructions here.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Hit ⌘R in your iOS Simulator to reload the app and see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/next/_getting-started-macos-ios/index.html b/docs/next/_getting-started-macos-ios/index.html index d43ca88830f..e4faf2bfdf2 100644 --- a/docs/next/_getting-started-macos-ios/index.html +++ b/docs/next/_getting-started-macos-ios/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: Next

_getting-started-macos-ios

Installing dependencies

You will need Node, Watchman, the React Native command line interface, Xcode and CocoaPods.

While you can use any editor of your choice to develop your app, you will need to install Xcode in order to set up the necessary tooling to build your React Native app for iOS.

Node & Watchman

We recommend installing Node and Watchman using Homebrew. Run the following commands in a Terminal after installing Homebrew:

brew install node
brew install watchman

If you have already installed Node on your system, make sure it is Node 12 or newer.

Watchman is a tool by Facebook for watching changes in the filesystem. It is highly recommended you install it for better performance.

Xcode

The easiest way to install Xcode is via the Mac App Store. Installing Xcode will also install the iOS Simulator and all the necessary tools to build your iOS app.

If you have already installed Xcode on your system, make sure it is version 10 or newer.

Command Line Tools

You will also need to install the Xcode Command Line Tools. Open Xcode, then choose "Preferences..." from the Xcode menu. Go to the Locations panel and install the tools by selecting the most recent version in the Command Line Tools dropdown.

Xcode Command Line Tools

Installing an iOS Simulator in Xcode

To install a simulator, open Xcode > Preferences... and select the Components tab. Select a simulator with the corresponding version of iOS you wish to use.

CocoaPods

CocoaPods is built with Ruby and it will be installable with the default Ruby available on macOS. You can use a Ruby Version manager, however we recommend that you use the standard Ruby available on macOS unless you know what you're doing.

Using the default Ruby install will require you to use sudo when installing gems. (This is only an issue for the duration of the gem installation, though.)

sudo gem install cocoapods

For more information, please visit CocoaPods Getting Started guide.

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

You can use React Native's built-in command line interface to generate a new project. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding iOS support to an existing React Native project (see Integration with Existing Apps). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Note If the above command is failing, you may have old version of react-native or react-native-cli installed globally on your pc. Try uninstalling the cli and run the cli using npx.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-ios

You should see your new app running in the iOS Simulator shortly.

AwesomeProject on iOS

npx react-native run-ios is one way to run your app. You can also run it directly from within Xcode.

If you can't get this to work, see the Troubleshooting page.

Running on a device

The above command will automatically run your app on the iOS Simulator by default. If you want to run the app on an actual physical iOS device, please follow the instructions here.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Hit ⌘R in your iOS Simulator to reload the app and see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/next/_getting-started-windows-android.html b/docs/next/_getting-started-windows-android.html index cf6e60b2180..d1d4c0b06d9 100644 --- a/docs/next/_getting-started-windows-android.html +++ b/docs/next/_getting-started-windows-android.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: Next

_getting-started-windows-android

Installing dependencies

You will need Node, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node, JDK

We recommend installing Node via Chocolatey, a popular package manager for Windows.

If you want to be able to switch between different Node versions, you might want to install Node via nvm-windows, a Node version manager for Windows.

React Native also requires Java SE Development Kit (JDK), which can be installed using Chocolatey as well.

Open an Administrator Command Prompt (right click Command Prompt and select "Run as Administrator"), then run the following command:

choco install -y nodejs.install openjdk8

If you have already installed Node on your system, make sure it is Node 12 or newer. If you already have a JDK on your system, make sure it is version 8 or newer.

You can find additional installation options on Node's Downloads page.

If you're using the latest version of Java Development Kit, you'll need to change the Gradle version of your project so it can recognize the JDK. You can do that by going to {project root folder}\android\gradle\wrapper\gradle-wrapper.properties and changing the distributionUrl value to upgrade the Gradle version. You can check out here the lastest releases of Gradle.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device
  • If you are not already using Hyper-V: Performance (Intel ® HAXM) (See here for AMD or Hyper-V)

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

Android Studio Welcome

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

  1. Open the Windows Control Panel.
  2. Click on User Accounts, then click User Accounts again
  3. Click on Change my environment variables
  4. Click on New... to create a new ANDROID_HOME user variable that points to the path to your Android SDK:

ANDROID_HOME Environment Variable

The SDK is installed, by default, at the following location:

%LOCALAPPDATA%\Android\Sdk

You can find the actual location of the SDK in the Android Studio "Settings" dialog, under Appearance & Behavior → System Settings → Android SDK.

Open a new Command Prompt window to ensure the new environment variable is loaded before proceeding to the next step.

  1. Open powershell
  2. Copy and paste Get-ChildItem -Path Env:\ into powershell
  3. Verify ANDROID_HOME has been added

4. Add platform-tools to Path

  1. Open the Windows Control Panel.
  2. Click on User Accounts, then click User Accounts again
  3. Click on Change my environment variables
  4. Select the Path variable.
  5. Click Edit.
  6. Click New and add the path to platform-tools to the list.

The default location for this folder is:

%LOCALAPPDATA%\Android\Sdk\platform-tools

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Integration with Existing Apps). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

If you don't have HAXM installed, click on "Install HAXM" or follow these instructions to set it up, then go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

AwesomeProject on Android

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (Ctrl + M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/next/_getting-started-windows-android/index.html b/docs/next/_getting-started-windows-android/index.html index cf6e60b2180..d1d4c0b06d9 100644 --- a/docs/next/_getting-started-windows-android/index.html +++ b/docs/next/_getting-started-windows-android/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Version: Next

_getting-started-windows-android

Installing dependencies

You will need Node, the React Native command line interface, a JDK, and Android Studio.

While you can use any editor of your choice to develop your app, you will need to install Android Studio in order to set up the necessary tooling to build your React Native app for Android.

Node, JDK

We recommend installing Node via Chocolatey, a popular package manager for Windows.

If you want to be able to switch between different Node versions, you might want to install Node via nvm-windows, a Node version manager for Windows.

React Native also requires Java SE Development Kit (JDK), which can be installed using Chocolatey as well.

Open an Administrator Command Prompt (right click Command Prompt and select "Run as Administrator"), then run the following command:

choco install -y nodejs.install openjdk8

If you have already installed Node on your system, make sure it is Node 12 or newer. If you already have a JDK on your system, make sure it is version 8 or newer.

You can find additional installation options on Node's Downloads page.

If you're using the latest version of Java Development Kit, you'll need to change the Gradle version of your project so it can recognize the JDK. You can do that by going to {project root folder}\android\gradle\wrapper\gradle-wrapper.properties and changing the distributionUrl value to upgrade the Gradle version. You can check out here the lastest releases of Gradle.

Android development environment

Setting up your development environment can be somewhat tedious if you're new to Android development. If you're already familiar with Android development, there are a few things you may need to configure. In either case, please make sure to carefully follow the next few steps.

1. Install Android Studio

Download and install Android Studio. While on Android Studio installation wizard, make sure the boxes next to all of the following items are checked:

  • Android SDK
  • Android SDK Platform
  • Android Virtual Device
  • If you are not already using Hyper-V: Performance (Intel ® HAXM) (See here for AMD or Hyper-V)

Then, click "Next" to install all of these components.

If the checkboxes are grayed out, you will have a chance to install these components later on.

Once setup has finalized and you're presented with the Welcome screen, proceed to the next step.

2. Install the Android SDK

Android Studio installs the latest Android SDK by default. Building a React Native app with native code, however, requires the Android 10 (Q) SDK in particular. Additional Android SDKs can be installed through the SDK Manager in Android Studio.

To do that, open Android Studio, click on "Configure" button and select "SDK Manager".

Android Studio Welcome

The SDK Manager can also be found within the Android Studio "Preferences" dialog, under Appearance & Behavior → System Settings → Android SDK.

Select the "SDK Platforms" tab from within the SDK Manager, then check the box next to "Show Package Details" in the bottom right corner. Look for and expand the Android 10 (Q) entry, then make sure the following items are checked:

  • Android SDK Platform 29
  • Intel x86 Atom_64 System Image or Google APIs Intel x86 Atom System Image

Next, select the "SDK Tools" tab and check the box next to "Show Package Details" here as well. Look for and expand the "Android SDK Build-Tools" entry, then make sure that 29.0.2 is selected.

Finally, click "Apply" to download and install the Android SDK and related build tools.

3. Configure the ANDROID_HOME environment variable

The React Native tools require some environment variables to be set up in order to build apps with native code.

  1. Open the Windows Control Panel.
  2. Click on User Accounts, then click User Accounts again
  3. Click on Change my environment variables
  4. Click on New... to create a new ANDROID_HOME user variable that points to the path to your Android SDK:

ANDROID_HOME Environment Variable

The SDK is installed, by default, at the following location:

%LOCALAPPDATA%\Android\Sdk

You can find the actual location of the SDK in the Android Studio "Settings" dialog, under Appearance & Behavior → System Settings → Android SDK.

Open a new Command Prompt window to ensure the new environment variable is loaded before proceeding to the next step.

  1. Open powershell
  2. Copy and paste Get-ChildItem -Path Env:\ into powershell
  3. Verify ANDROID_HOME has been added

4. Add platform-tools to Path

  1. Open the Windows Control Panel.
  2. Click on User Accounts, then click User Accounts again
  3. Click on Change my environment variables
  4. Select the Path variable.
  5. Click Edit.
  6. Click New and add the path to platform-tools to the list.

The default location for this folder is:

%LOCALAPPDATA%\Android\Sdk\platform-tools

React Native Command Line Interface

React Native has a built-in command line interface. Rather than install and manage a specific version of the CLI globally, we recommend you access the current version at runtime using npx, which ships with Node.js. With npx react-native <command>, the current stable version of the CLI will be downloaded and executed at the time the command is run.

Creating a new application

If you previously installed a global react-native-cli package, please remove it as it may cause unexpected issues.

React Native has a built-in command line interface, which you can use to generate a new project. You can access it without installing anything globally using npx, which ships with Node.js. Let's create a new React Native project called "AwesomeProject":

npx react-native init AwesomeProject

This is not necessary if you are integrating React Native into an existing application, if you "ejected" from Expo, or if you're adding Android support to an existing React Native project (see Integration with Existing Apps). You can also use a third-party CLI to init your React Native app, such as Ignite CLI.

[Optional] Using a specific version or template

If you want to start a new project with a specific React Native version, you can use the --version argument:

npx react-native init AwesomeProject --version X.XX.X

You can also start a project with a custom React Native template, like TypeScript, with --template argument:

npx react-native init AwesomeTSProject --template react-native-template-typescript

Preparing the Android device

You will need an Android device to run your React Native Android app. This can be either a physical Android device, or more commonly, you can use an Android Virtual Device which allows you to emulate an Android device on your computer.

Either way, you will need to prepare the device to run Android apps for development.

Using a physical device

If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions here.

Using a virtual device

If you use Android Studio to open ./AwesomeProject/android, you can see the list of available Android Virtual Devices (AVDs) by opening the "AVD Manager" from within Android Studio. Look for an icon that looks like this:

Android Studio AVD Manager

If you have recently installed Android Studio, you will likely need to create a new AVD. Select "Create Virtual Device...", then pick any Phone from the list and click "Next", then select the Q API Level 29 image.

If you don't have HAXM installed, click on "Install HAXM" or follow these instructions to set it up, then go back to the AVD Manager.

Click "Next" then "Finish" to create your AVD. At this point you should be able to click on the green triangle button next to your AVD to launch it, then proceed to the next step.

Running your React Native application

Step 1: Start Metro

First, you will need to start Metro, the JavaScript bundler that ships with React Native. Metro "takes in an entry file and various options, and returns a single JavaScript file that includes all your code and its dependencies."—Metro Docs

To start Metro, run npx react-native start inside your React Native project folder:

npx react-native start

react-native start starts Metro Bundler.

If you use the Yarn package manager, you can use yarn instead of npx when running React Native commands inside an existing project.

If you're familiar with web development, Metro is a lot like webpack—for React Native apps. Unlike Kotlin or Java, JavaScript isn't compiled—and neither is React Native. Bundling isn't the same as compiling, but it can help improve startup performance and translate some platform-specific JavaScript into more JavaScript.

Step 2: Start your application

Let Metro Bundler run in its own terminal. Open a new terminal inside your React Native project folder. Run the following:

npx react-native run-android

If everything is set up correctly, you should see your new app running in your Android emulator shortly.

AwesomeProject on Android

npx react-native run-android is one way to run your app - you can also run it directly from within Android Studio.

If you can't get this to work, see the Troubleshooting page.

Modifying your app

Now that you have successfully run the app, let's modify it.

  • Open App.js in your text editor of choice and edit some lines.
  • Press the R key twice or select Reload from the Developer Menu (Ctrl + M) to see your changes!

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.

If you're curious to learn more about React Native, check out the Introduction to React Native.

Edit this page
Last updated on
- + diff --git a/docs/next/_integration-with-exisiting-apps-java.html b/docs/next/_integration-with-exisiting-apps-java.html index ce7b596238a..8a3fd3c3af1 100644 --- a/docs/next/_integration-with-exisiting-apps-java.html +++ b/docs/next/_integration-with-exisiting-apps-java.html @@ -19,7 +19,7 @@ - + @@ -48,7 +48,7 @@
if (mReactInstanceManager != null) {
mReactInstanceManager.onHostDestroy(this);
}
if (mReactRootView != null) {
mReactRootView.unmountReactApplication();
}
}

We also need to pass back button events to React Native:

@Override
public void onBackPressed() {
if (mReactInstanceManager != null) {
mReactInstanceManager.onBackPressed();
} else {
super.onBackPressed();
}
}

This allows JavaScript to control what happens when the user presses the hardware back button (e.g. to implement navigation). When JavaScript doesn't handle the back button press, your invokeDefaultOnBackPressed method will be called. By default this finishes your Activity.

Finally, we need to hook up the dev menu. By default, this is activated by (rage) shaking the device, but this is not very useful in emulators. So we make it show when you press the hardware menu button (use Ctrl + M if you're using Android Studio emulator):

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
if (keyCode == KeyEvent.KEYCODE_MENU && mReactInstanceManager != null) {
mReactInstanceManager.showDevOptionsDialog();
return true;
}
return super.onKeyUp(keyCode, event);
}

Now your activity is ready to run some JavaScript code.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ yarn start
2. Run the app

Now build and run your Android app as normal.

Once you reach your React-powered activity inside the app, it should load the JavaScript code from the development server and display:

Screenshot

Creating a release build in Android Studio

You can use Android Studio to create your release builds too! It’s as quick as creating release builds of your previously-existing native Android app. There’s one additional step, which you’ll have to do before every release build. You need to execute the following to create a React Native bundle, which will be included with your native Android app:

$ npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/com/your-company-name/app-package-name/src/main/assets/index.android.bundle --assets-dest android/com/your-company-name/app-package-name/src/main/res/

Don’t forget to replace the paths with correct ones and create the assets folder if it doesn’t exist.

Now, create a release build of your native app from within Android Studio as usual and you should be good to go!

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/next/_integration-with-exisiting-apps-java/index.html b/docs/next/_integration-with-exisiting-apps-java/index.html index ce7b596238a..8a3fd3c3af1 100644 --- a/docs/next/_integration-with-exisiting-apps-java/index.html +++ b/docs/next/_integration-with-exisiting-apps-java/index.html @@ -19,7 +19,7 @@ - + @@ -48,7 +48,7 @@
if (mReactInstanceManager != null) {
mReactInstanceManager.onHostDestroy(this);
}
if (mReactRootView != null) {
mReactRootView.unmountReactApplication();
}
}

We also need to pass back button events to React Native:

@Override
public void onBackPressed() {
if (mReactInstanceManager != null) {
mReactInstanceManager.onBackPressed();
} else {
super.onBackPressed();
}
}

This allows JavaScript to control what happens when the user presses the hardware back button (e.g. to implement navigation). When JavaScript doesn't handle the back button press, your invokeDefaultOnBackPressed method will be called. By default this finishes your Activity.

Finally, we need to hook up the dev menu. By default, this is activated by (rage) shaking the device, but this is not very useful in emulators. So we make it show when you press the hardware menu button (use Ctrl + M if you're using Android Studio emulator):

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
if (keyCode == KeyEvent.KEYCODE_MENU && mReactInstanceManager != null) {
mReactInstanceManager.showDevOptionsDialog();
return true;
}
return super.onKeyUp(keyCode, event);
}

Now your activity is ready to run some JavaScript code.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ yarn start
2. Run the app

Now build and run your Android app as normal.

Once you reach your React-powered activity inside the app, it should load the JavaScript code from the development server and display:

Screenshot

Creating a release build in Android Studio

You can use Android Studio to create your release builds too! It’s as quick as creating release builds of your previously-existing native Android app. There’s one additional step, which you’ll have to do before every release build. You need to execute the following to create a React Native bundle, which will be included with your native Android app:

$ npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/com/your-company-name/app-package-name/src/main/assets/index.android.bundle --assets-dest android/com/your-company-name/app-package-name/src/main/res/

Don’t forget to replace the paths with correct ones and create the assets folder if it doesn’t exist.

Now, create a release build of your native app from within Android Studio as usual and you should be good to go!

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/next/_integration-with-exisiting-apps-objc.html b/docs/next/_integration-with-exisiting-apps-objc.html index 2b8876d0bcf..54a12878669 100644 --- a/docs/next/_integration-with-exisiting-apps-objc.html +++ b/docs/next/_integration-with-exisiting-apps-objc.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
RCTRootView *rootView =
[[RCTRootView alloc] initWithBundleURL: jsCodeLocation
moduleName: @"RNHighScores"
initialProperties:
@{
@"scores" : @[
@{
@"name" : @"Alex",
@"value": @"42"
},
@{
@"name" : @"Joel",
@"value": @"10"
}
]
}
launchOptions: nil];
UIViewController *vc = [[UIViewController alloc] init];
vc.view = rootView;
[self presentViewController:vc animated:YES completion:nil];
}

Note that RCTRootView initWithURL starts up a new JSC VM. To save resources and simplify the communication between RN views in different parts of your native app, you can have multiple views powered by React Native that are associated with a single JS runtime. To do that, instead of using [RCTRootView alloc] initWithURL, use RCTBridge initWithBundleURL to create a bridge and then use RCTRootView initWithBridge.

When moving your app to production, the NSURL can point to a pre-bundled file on disk via something like [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];. You can use the react-native-xcode.sh script in node_modules/react-native/scripts/ to generate that pre-bundled file.

3. Wire Up

Wire up the new link in the main menu to the newly added event handler method.

Event Path

One of the easier ways to do this is to open the view in the storyboard and right click on the new link. Select something such as the Touch Up Inside event, drag that to the storyboard and then select the created method from the list provided.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Add App Transport Security exception

Apple has blocked implicit cleartext HTTP resource loading. So we need to add the following our project's Info.plist (or equivalent) file.

<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>localhost</key>
<dict>
<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
</dict>

App Transport Security is good for your users. Make sure to re-enable it prior to releasing your app for production.

2. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

npm start
3. Run the app

If you are using Xcode or your favorite editor, build and run your native iOS application as normal. Alternatively, you can run the app from the command line using:

# From the root of your project
$ npx react-native run-ios

In our sample application, you should see the link to the "High Scores" and then when you click on that you will see the rendering of your React Native component.

Here is the native application home screen:

Home Screen

Here is the React Native high score screen:

High Scores

If you are getting module resolution issues when running your application please see this GitHub issue for information and possible resolution. This comment seemed to be the latest possible resolution.

See the Code

You can examine the code that added the React Native screen to our sample app on GitHub.

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/next/_integration-with-exisiting-apps-objc/index.html b/docs/next/_integration-with-exisiting-apps-objc/index.html index 2b8876d0bcf..54a12878669 100644 --- a/docs/next/_integration-with-exisiting-apps-objc/index.html +++ b/docs/next/_integration-with-exisiting-apps-objc/index.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
RCTRootView *rootView =
[[RCTRootView alloc] initWithBundleURL: jsCodeLocation
moduleName: @"RNHighScores"
initialProperties:
@{
@"scores" : @[
@{
@"name" : @"Alex",
@"value": @"42"
},
@{
@"name" : @"Joel",
@"value": @"10"
}
]
}
launchOptions: nil];
UIViewController *vc = [[UIViewController alloc] init];
vc.view = rootView;
[self presentViewController:vc animated:YES completion:nil];
}

Note that RCTRootView initWithURL starts up a new JSC VM. To save resources and simplify the communication between RN views in different parts of your native app, you can have multiple views powered by React Native that are associated with a single JS runtime. To do that, instead of using [RCTRootView alloc] initWithURL, use RCTBridge initWithBundleURL to create a bridge and then use RCTRootView initWithBridge.

When moving your app to production, the NSURL can point to a pre-bundled file on disk via something like [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];. You can use the react-native-xcode.sh script in node_modules/react-native/scripts/ to generate that pre-bundled file.

3. Wire Up

Wire up the new link in the main menu to the newly added event handler method.

Event Path

One of the easier ways to do this is to open the view in the storyboard and right click on the new link. Select something such as the Touch Up Inside event, drag that to the storyboard and then select the created method from the list provided.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Add App Transport Security exception

Apple has blocked implicit cleartext HTTP resource loading. So we need to add the following our project's Info.plist (or equivalent) file.

<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>localhost</key>
<dict>
<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
</dict>

App Transport Security is good for your users. Make sure to re-enable it prior to releasing your app for production.

2. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

npm start
3. Run the app

If you are using Xcode or your favorite editor, build and run your native iOS application as normal. Alternatively, you can run the app from the command line using:

# From the root of your project
$ npx react-native run-ios

In our sample application, you should see the link to the "High Scores" and then when you click on that you will see the rendering of your React Native component.

Here is the native application home screen:

Home Screen

Here is the React Native high score screen:

High Scores

If you are getting module resolution issues when running your application please see this GitHub issue for information and possible resolution. This comment seemed to be the latest possible resolution.

See the Code

You can examine the code that added the React Native screen to our sample app on GitHub.

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/next/_integration-with-exisiting-apps-swift.html b/docs/next/_integration-with-exisiting-apps-swift.html index feea08a7b36..133b237e840 100644 --- a/docs/next/_integration-with-exisiting-apps-swift.html +++ b/docs/next/_integration-with-exisiting-apps-swift.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
let rootView = RCTRootView(
bundleURL: jsCodeLocation,
moduleName: "RNHighScores",
initialProperties: mockData as [NSObject : AnyObject],
launchOptions: nil
)
let vc = UIViewController()
vc.view = rootView
self.present(vc, animated: true, completion: nil)
}

Note that RCTRootView bundleURL starts up a new JSC VM. To save resources and simplify the communication between RN views in different parts of your native app, you can have multiple views powered by React Native that are associated with a single JS runtime. To do that, instead of using RCTRootView bundleURL, use RCTBridge initWithBundleURL to create a bridge and then use RCTRootView initWithBridge.

When moving your app to production, the NSURL can point to a pre-bundled file on disk via something like let mainBundle = NSBundle(URLForResource: "main" withExtension:"jsbundle"). You can use the react-native-xcode.sh script in node_modules/react-native/scripts/ to generate that pre-bundled file.

3. Wire Up

Wire up the new link in the main menu to the newly added event handler method.

Event Path

One of the easier ways to do this is to open the view in the storyboard and right click on the new link. Select something such as the Touch Up Inside event, drag that to the storyboard and then select the created method from the list provided.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Add App Transport Security exception

Apple has blocked implicit cleartext HTTP resource loading. So we need to add the following our project's Info.plist (or equivalent) file.

<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>localhost</key>
<dict>
<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
</dict>

App Transport Security is good for your users. Make sure to re-enable it prior to releasing your app for production.

2. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ npm start
3. Run the app

If you are using Xcode or your favorite editor, build and run your native iOS application as normal. Alternatively, you can run the app from the command line using:

# From the root of your project
$ npx react-native run-ios

In our sample application, you should see the link to the "High Scores" and then when you click on that you will see the rendering of your React Native component.

Here is the native application home screen:

Home Screen

Here is the React Native high score screen:

High Scores

If you are getting module resolution issues when running your application please see this GitHub issue for information and possible resolution. This comment seemed to be the latest possible resolution.

See the Code

You can examine the code that added the React Native screen to our sample app on GitHub.

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/next/_integration-with-exisiting-apps-swift/index.html b/docs/next/_integration-with-exisiting-apps-swift/index.html index feea08a7b36..133b237e840 100644 --- a/docs/next/_integration-with-exisiting-apps-swift/index.html +++ b/docs/next/_integration-with-exisiting-apps-swift/index.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
let rootView = RCTRootView(
bundleURL: jsCodeLocation,
moduleName: "RNHighScores",
initialProperties: mockData as [NSObject : AnyObject],
launchOptions: nil
)
let vc = UIViewController()
vc.view = rootView
self.present(vc, animated: true, completion: nil)
}

Note that RCTRootView bundleURL starts up a new JSC VM. To save resources and simplify the communication between RN views in different parts of your native app, you can have multiple views powered by React Native that are associated with a single JS runtime. To do that, instead of using RCTRootView bundleURL, use RCTBridge initWithBundleURL to create a bridge and then use RCTRootView initWithBridge.

When moving your app to production, the NSURL can point to a pre-bundled file on disk via something like let mainBundle = NSBundle(URLForResource: "main" withExtension:"jsbundle"). You can use the react-native-xcode.sh script in node_modules/react-native/scripts/ to generate that pre-bundled file.

3. Wire Up

Wire up the new link in the main menu to the newly added event handler method.

Event Path

One of the easier ways to do this is to open the view in the storyboard and right click on the new link. Select something such as the Touch Up Inside event, drag that to the storyboard and then select the created method from the list provided.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Add App Transport Security exception

Apple has blocked implicit cleartext HTTP resource loading. So we need to add the following our project's Info.plist (or equivalent) file.

<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>localhost</key>
<dict>
<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
</dict>

App Transport Security is good for your users. Make sure to re-enable it prior to releasing your app for production.

2. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ npm start
3. Run the app

If you are using Xcode or your favorite editor, build and run your native iOS application as normal. Alternatively, you can run the app from the command line using:

# From the root of your project
$ npx react-native run-ios

In our sample application, you should see the link to the "High Scores" and then when you click on that you will see the rendering of your React Native component.

Here is the native application home screen:

Home Screen

Here is the React Native high score screen:

High Scores

If you are getting module resolution issues when running your application please see this GitHub issue for information and possible resolution. This comment seemed to be the latest possible resolution.

See the Code

You can examine the code that added the React Native screen to our sample app on GitHub.

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/next/accessibility.html b/docs/next/accessibility.html index bceb33ecfe2..861c3b24f03 100644 --- a/docs/next/accessibility.html +++ b/docs/next/accessibility.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
# enable
adb shell settings put secure enabled_accessibility_services com.google.android.marvin.talkback/com.google.android.marvin.talkback.TalkBackService

Testing VoiceOver Support
iOS

To enable VoiceOver, go to the Settings app on your iOS device (it's not available for simulator). 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.

Additional Resources

Edit this page
Last updated on
- + diff --git a/docs/next/accessibility/index.html b/docs/next/accessibility/index.html index bceb33ecfe2..861c3b24f03 100644 --- a/docs/next/accessibility/index.html +++ b/docs/next/accessibility/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
# enable
adb shell settings put secure enabled_accessibility_services com.google.android.marvin.talkback/com.google.android.marvin.talkback.TalkBackService

Testing VoiceOver Support
iOS

To enable VoiceOver, go to the Settings app on your iOS device (it's not available for simulator). 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.

Additional Resources

Edit this page
Last updated on
- + diff --git a/docs/next/accessibilityinfo.html b/docs/next/accessibilityinfo.html index 1b4f4fb1a0d..d894d2bc9d0 100644 --- a/docs/next/accessibilityinfo.html +++ b/docs/next/accessibilityinfo.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

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.

Example

Reference

Methods

addEventListener()

static addEventListener(eventName, handler)

Add an event handler. Supported events:

Event nameDescription
announcementFinished
iOS
Fires when the screen reader has finished making an announcement. The argument to the event handler is a dictionary with these keys:
  • announcement: The string announced by the screen reader.
  • success: A boolean indicating whether the announcement was successfully made.
boldTextChanged
iOS
Fires when the state of the bold text toggle changes. The argument to the event handler is a boolean. The boolean is true when bold text is enabled and false otherwise.
grayscaleChanged
iOS
Fires when the state of the gray scale toggle changes. The argument to the event handler is a boolean. The boolean is true when a gray scale is enabled and false otherwise.
invertColorsChanged
iOS
Fires when the state of the invert colors toggle changes. The argument to the event handler is a boolean. The boolean is true when invert colors is enabled and false otherwise.
reduceMotionChangedFires when the state of the reduce motion toggle changes. The argument to the event handler is a boolean. The boolean is true when a reduce motion is enabled (or when "Transition Animation Scale" in "Developer options" is "Animation off") and false otherwise.
reduceTransparencyChanged
iOS
Fires when the state of the reduce transparency toggle changes. The argument to the event handler is a boolean. The boolean is true when reduce transparency is enabled and false otherwise.
screenReaderChangedFires when the state of the screen reader changes. The argument to the event handler is a boolean. The boolean is true when a screen reader is enabled and false otherwise.

announceForAccessibility()

static announceForAccessibility(announcement)

Post a string to be announced by the screen reader.

isBoldTextEnabled()
iOS

static isBoldTextEnabled()

Query whether a bold text is currently enabled. Returns a promise which resolves to a boolean. The result is true when bold text is enabled and false otherwise.

isGrayscaleEnabled()
iOS

static isGrayscaleEnabled()

Query whether grayscale is currently enabled. Returns a promise which resolves to a boolean. The result is true when grayscale is enabled and false otherwise.

isInvertColorsEnabled()
iOS

static isInvertColorsEnabled()

Query whether invert colors is currently enabled. Returns a promise which resolves to a boolean. The result is true when invert colors is enabled and false otherwise.

isReduceMotionEnabled()

static isReduceMotionEnabled()

Query whether reduce motion is currently enabled. Returns a promise which resolves to a boolean. The result is true when reduce motion is enabled and false otherwise.

isReduceTransparencyEnabled()
iOS

static isReduceTransparencyEnabled()

Query whether reduce transparency is currently enabled. Returns a promise which resolves to a boolean. The result is true when a reduce transparency is enabled and false otherwise.

isScreenReaderEnabled()

static isScreenReaderEnabled()

Query whether a screen reader is currently enabled. Returns a promise which resolves to a boolean. The result is true when a screen reader is enabled and false otherwise.

removeEventListener()

static removeEventListener(eventName, handler)

Remove an event handler.

setAccessibilityFocus()

static setAccessibilityFocus(reactTag)

Set accessibility focus to a React component.

On Android, this calls UIManager.sendAccessibilityEvent method with passed reactTag and UIManager.AccessibilityEventTypes.typeViewFocused arguments.

Note: Make sure that any View you want to receive the accessibility focus has accessible={true}.

Edit this page
Last updated on
- + diff --git a/docs/next/accessibilityinfo/index.html b/docs/next/accessibilityinfo/index.html index 1b4f4fb1a0d..d894d2bc9d0 100644 --- a/docs/next/accessibilityinfo/index.html +++ b/docs/next/accessibilityinfo/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

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.

Example

Reference

Methods

addEventListener()

static addEventListener(eventName, handler)

Add an event handler. Supported events:

Event nameDescription
announcementFinished
iOS
Fires when the screen reader has finished making an announcement. The argument to the event handler is a dictionary with these keys:
  • announcement: The string announced by the screen reader.
  • success: A boolean indicating whether the announcement was successfully made.
boldTextChanged
iOS
Fires when the state of the bold text toggle changes. The argument to the event handler is a boolean. The boolean is true when bold text is enabled and false otherwise.
grayscaleChanged
iOS
Fires when the state of the gray scale toggle changes. The argument to the event handler is a boolean. The boolean is true when a gray scale is enabled and false otherwise.
invertColorsChanged
iOS
Fires when the state of the invert colors toggle changes. The argument to the event handler is a boolean. The boolean is true when invert colors is enabled and false otherwise.
reduceMotionChangedFires when the state of the reduce motion toggle changes. The argument to the event handler is a boolean. The boolean is true when a reduce motion is enabled (or when "Transition Animation Scale" in "Developer options" is "Animation off") and false otherwise.
reduceTransparencyChanged
iOS
Fires when the state of the reduce transparency toggle changes. The argument to the event handler is a boolean. The boolean is true when reduce transparency is enabled and false otherwise.
screenReaderChangedFires when the state of the screen reader changes. The argument to the event handler is a boolean. The boolean is true when a screen reader is enabled and false otherwise.

announceForAccessibility()

static announceForAccessibility(announcement)

Post a string to be announced by the screen reader.

isBoldTextEnabled()
iOS

static isBoldTextEnabled()

Query whether a bold text is currently enabled. Returns a promise which resolves to a boolean. The result is true when bold text is enabled and false otherwise.

isGrayscaleEnabled()
iOS

static isGrayscaleEnabled()

Query whether grayscale is currently enabled. Returns a promise which resolves to a boolean. The result is true when grayscale is enabled and false otherwise.

isInvertColorsEnabled()
iOS

static isInvertColorsEnabled()

Query whether invert colors is currently enabled. Returns a promise which resolves to a boolean. The result is true when invert colors is enabled and false otherwise.

isReduceMotionEnabled()

static isReduceMotionEnabled()

Query whether reduce motion is currently enabled. Returns a promise which resolves to a boolean. The result is true when reduce motion is enabled and false otherwise.

isReduceTransparencyEnabled()
iOS

static isReduceTransparencyEnabled()

Query whether reduce transparency is currently enabled. Returns a promise which resolves to a boolean. The result is true when a reduce transparency is enabled and false otherwise.

isScreenReaderEnabled()

static isScreenReaderEnabled()

Query whether a screen reader is currently enabled. Returns a promise which resolves to a boolean. The result is true when a screen reader is enabled and false otherwise.

removeEventListener()

static removeEventListener(eventName, handler)

Remove an event handler.

setAccessibilityFocus()

static setAccessibilityFocus(reactTag)

Set accessibility focus to a React component.

On Android, this calls UIManager.sendAccessibilityEvent method with passed reactTag and UIManager.AccessibilityEventTypes.typeViewFocused arguments.

Note: Make sure that any View you want to receive the accessibility focus has accessible={true}.

Edit this page
Last updated on
- + diff --git a/docs/next/actionsheetios.html b/docs/next/actionsheetios.html index a4e46ff6ed7..6fced6aeec2 100644 --- a/docs/next/actionsheetios.html +++ b/docs/next/actionsheetios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

ActionSheetIOS

Displays native to iOS Action Sheet component.

Example

Reference

Methods

showActionSheetWithOptions()

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 in options
  • destructiveButtonIndex (int) - index of destructive button in options
  • title (string) - a title to show above the action sheet
  • message (string) - a message to show below the title
  • anchor (number) - the node to which the action sheet should be anchored (used for iPad)
  • tintColor (string) - the color used for non-destructive button titles
  • disabledButtonIndices (array of numbers) - a list of button indices which should be disabled
  • userInterfaceStyle (string) - the interface style used for the action sheet, can be set to light or dark, otherwise the default system style will be used

The 'callback' function takes one parameter, the zero-based index of the selected item.

Minimal example:

ActionSheetIOS.showActionSheetWithOptions(
{
options: ['Cancel', 'Remove'],
destructiveButtonIndex: 1,
cancelButtonIndex: 0
},
(buttonIndex) => {
if (buttonIndex === 1) {
/* destructive action */
}
}
);

showShareActionSheetWithOptions()

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 share
  • message (string) - a message to share
  • subject (string) - a subject for the message
  • excludedActivityTypes (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. If url points to a remote file or address it must conform to URL format as described in RFC 2396. For example, a web URL without a proper protocol (HTTP/HTTPS) will not be shared.

The 'failureCallback' function takes one parameter, an error object. The only property defined on this object is an optional stack property of type string.

The 'successCallback' function takes two parameters:

  • a boolean value signifying success or failure
  • a string that, in the case of success, indicates the method of sharing
Edit this page
Last updated on
- + diff --git a/docs/next/actionsheetios/index.html b/docs/next/actionsheetios/index.html index a4e46ff6ed7..6fced6aeec2 100644 --- a/docs/next/actionsheetios/index.html +++ b/docs/next/actionsheetios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

ActionSheetIOS

Displays native to iOS Action Sheet component.

Example

Reference

Methods

showActionSheetWithOptions()

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 in options
  • destructiveButtonIndex (int) - index of destructive button in options
  • title (string) - a title to show above the action sheet
  • message (string) - a message to show below the title
  • anchor (number) - the node to which the action sheet should be anchored (used for iPad)
  • tintColor (string) - the color used for non-destructive button titles
  • disabledButtonIndices (array of numbers) - a list of button indices which should be disabled
  • userInterfaceStyle (string) - the interface style used for the action sheet, can be set to light or dark, otherwise the default system style will be used

The 'callback' function takes one parameter, the zero-based index of the selected item.

Minimal example:

ActionSheetIOS.showActionSheetWithOptions(
{
options: ['Cancel', 'Remove'],
destructiveButtonIndex: 1,
cancelButtonIndex: 0
},
(buttonIndex) => {
if (buttonIndex === 1) {
/* destructive action */
}
}
);

showShareActionSheetWithOptions()

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 share
  • message (string) - a message to share
  • subject (string) - a subject for the message
  • excludedActivityTypes (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. If url points to a remote file or address it must conform to URL format as described in RFC 2396. For example, a web URL without a proper protocol (HTTP/HTTPS) will not be shared.

The 'failureCallback' function takes one parameter, an error object. The only property defined on this object is an optional stack property of type string.

The 'successCallback' function takes two parameters:

  • a boolean value signifying success or failure
  • a string that, in the case of success, indicates the method of sharing
Edit this page
Last updated on
- + diff --git a/docs/next/activityindicator.html b/docs/next/activityindicator.html index 9ecc1e543a8..622c8e455c2 100644 --- a/docs/next/activityindicator.html +++ b/docs/next/activityindicator.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

ActivityIndicator

Displays a circular loading indicator.

Example

Reference

Props

View Props

Inherits View Props.

animating

Whether to show the indicator (true) or hide it (false).

TypeDefault
booltrue

color

The foreground color of the spinner.

TypeDefault
colornull (system accent default color)
Android
'#999999'
iOS

hidesWhenStopped
iOS

Whether the indicator should hide when not animating.

TypeDefault
booltrue

size

Size of the indicator.

TypeDefault
enum('small', 'large')
number
Android
'small'
Edit this page
Last updated on
- + diff --git a/docs/next/activityindicator/index.html b/docs/next/activityindicator/index.html index 9ecc1e543a8..622c8e455c2 100644 --- a/docs/next/activityindicator/index.html +++ b/docs/next/activityindicator/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

ActivityIndicator

Displays a circular loading indicator.

Example

Reference

Props

View Props

Inherits View Props.

animating

Whether to show the indicator (true) or hide it (false).

TypeDefault
booltrue

color

The foreground color of the spinner.

TypeDefault
colornull (system accent default color)
Android
'#999999'
iOS

hidesWhenStopped
iOS

Whether the indicator should hide when not animating.

TypeDefault
booltrue

size

Size of the indicator.

TypeDefault
enum('small', 'large')
number
Android
'small'
Edit this page
Last updated on
- + diff --git a/docs/next/alert.html b/docs/next/alert.html index c1eedaf9bdb..0a54f05ee71 100644 --- a/docs/next/alert.html +++ b/docs/next/alert.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

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 Android and iOS and can show static alerts. Alert that prompts the user to enter some information is available on iOS only.

Example

iOS

On iOS you can specify any number of buttons. Each button can optionally specify a style, available options are represented by the AlertButtonStyle enum.

Android

On Android at most three buttons can be specified. Android has a concept of a neutral, negative and a positive button:

  • If you specify one button, it will be the 'positive' one (such as 'OK')
  • Two buttons mean 'negative', 'positive' (such as 'Cancel', 'OK')
  • Three buttons mean 'neutral', 'negative', 'positive' (such as 'Later', 'Cancel', 'OK')

Alerts on Android can be dismissed by tapping outside of the alert box. It is disabled by default and can be enabled by providing an optional Options parameter with the cancelable property set to true i.e.
{ cancelable: true }.

The cancel event can be handled by providing an onDismiss callback property inside the options parameter.

Example
Android

Reference

Methods

alert()

static alert(title, message?, buttons?, options?)

Parameters:

NameTypeDescription
title
Required
stringThe dialog's title. Passing null or empty string will hide the title.
messagestringAn optional message that appears below the dialog's title.
buttonsButtonsAn optional array containing buttons configuration.
options
Android
OptionsAn optional Alert configuration for the Android.

prompt()
iOS

static prompt(title, message?, callbackOrButtons?, type?, defaultValue?, keyboardType?)

Create and display a prompt to enter some text in form of Alert.

Parameters:

NameTypeDescription
title
Required
stringThe dialog's title.
messagestringAn optional message that appears above the text input.
callbackOrButtonsfunction
Buttons		If passed a function, it will be called with the prompt's value
(text: string) => void, when the user taps 'OK'.
If passed an array, buttons will be configured based on the array content.
typeAlertTypeThis configures the text input.
defaultValuestringThe default text in text input.
keyboardTypestringThe keyboard type of first text field (if exists). One of TextInput keyboardTypes.

Type Definitions

AlertButtonStyle
iOS

An iOS Alert button style.

Type
enum

Constants:

ValueDescription
'default'Default button style.
'cancel'Cancel button style.
'destructive'Destructive button style.

AlertType
iOS

An iOS Alert type.

Type
enum

Constants:

ValueDescription
'default'Default alert with no inputs
'plain-text'Plain text input alert
'secure-text'Secure text input alert
'login-password'Login and password alert

Buttons

Array of objects containg Alert buttons configuration.

Type
array of objects

Objects properties:

NameTypeDescription
textstringButton label.
onPressfunctionCallback function when button is pressed.
style
iOS
AlertButtonStyleButton style, on Android this property will be ignored.

Options
Android

Type
object

Properties:

NameTypeDescription
cancelablebooleanDefines if alert can be dismissed by tapping outside of the alert box.
onDismissfunctionCallback function fired when alert has been dismissed.
Edit this page
Last updated on
- + diff --git a/docs/next/alert/index.html b/docs/next/alert/index.html index c1eedaf9bdb..0a54f05ee71 100644 --- a/docs/next/alert/index.html +++ b/docs/next/alert/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

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 Android and iOS and can show static alerts. Alert that prompts the user to enter some information is available on iOS only.

Example

iOS

On iOS you can specify any number of buttons. Each button can optionally specify a style, available options are represented by the AlertButtonStyle enum.

Android

On Android at most three buttons can be specified. Android has a concept of a neutral, negative and a positive button:

  • If you specify one button, it will be the 'positive' one (such as 'OK')
  • Two buttons mean 'negative', 'positive' (such as 'Cancel', 'OK')
  • Three buttons mean 'neutral', 'negative', 'positive' (such as 'Later', 'Cancel', 'OK')

Alerts on Android can be dismissed by tapping outside of the alert box. It is disabled by default and can be enabled by providing an optional Options parameter with the cancelable property set to true i.e.
{ cancelable: true }.

The cancel event can be handled by providing an onDismiss callback property inside the options parameter.

Example
Android

Reference

Methods

alert()

static alert(title, message?, buttons?, options?)

Parameters:

NameTypeDescription
title
Required
stringThe dialog's title. Passing null or empty string will hide the title.
messagestringAn optional message that appears below the dialog's title.
buttonsButtonsAn optional array containing buttons configuration.
options
Android
OptionsAn optional Alert configuration for the Android.

prompt()
iOS

static prompt(title, message?, callbackOrButtons?, type?, defaultValue?, keyboardType?)

Create and display a prompt to enter some text in form of Alert.

Parameters:

NameTypeDescription
title
Required
stringThe dialog's title.
messagestringAn optional message that appears above the text input.
callbackOrButtonsfunction
Buttons		If passed a function, it will be called with the prompt's value
(text: string) => void, when the user taps 'OK'.
If passed an array, buttons will be configured based on the array content.
typeAlertTypeThis configures the text input.
defaultValuestringThe default text in text input.
keyboardTypestringThe keyboard type of first text field (if exists). One of TextInput keyboardTypes.

Type Definitions

AlertButtonStyle
iOS

An iOS Alert button style.

Type
enum

Constants:

ValueDescription
'default'Default button style.
'cancel'Cancel button style.
'destructive'Destructive button style.

AlertType
iOS

An iOS Alert type.

Type
enum

Constants:

ValueDescription
'default'Default alert with no inputs
'plain-text'Plain text input alert
'secure-text'Secure text input alert
'login-password'Login and password alert

Buttons

Array of objects containg Alert buttons configuration.

Type
array of objects

Objects properties:

NameTypeDescription
textstringButton label.
onPressfunctionCallback function when button is pressed.
style
iOS
AlertButtonStyleButton style, on Android this property will be ignored.

Options
Android

Type
object

Properties:

NameTypeDescription
cancelablebooleanDefines if alert can be dismissed by tapping outside of the alert box.
onDismissfunctionCallback function fired when alert has been dismissed.
Edit this page
Last updated on
- + diff --git a/docs/next/alertios.html b/docs/next/alertios.html index 642f47e35ce..ff0ca6216db 100644 --- a/docs/next/alertios.html +++ b/docs/next/alertios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 AlertIOS

Deprecated. Use Alert instead.

AlertIOS provides functionality to create an iOS alert dialog with a message or create a prompt for user input.

Creating an iOS alert:

AlertIOS.alert(
'Sync Complete',
'All your data are belong to us.'
);

Creating an iOS prompt:

AlertIOS.prompt('Enter a value', null, (text) =>
console.log('You entered ' + text)
);

We recommend using the Alert.alert method for cross-platform support if you don't need to create iOS-only prompts.

Reference

Methods

alert()

static alert(title: string, [message]: string, [callbackOrButtons]: ?(() => void), ButtonsArray, [type]: AlertType): [object Object]

Create and display a popup alert.

Parameters:

NameTypeRequiredDescription
titlestringYesThe dialog's title. Passing null or '' will hide the title.
messagestringNoAn optional message that appears below the dialog's title.
callbackOrButtons?(() => void),ButtonsArrayNoThis optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called when the user taps 'OK'. If passed an array of button configurations, each button should include a text key, as well as optional onPress and style keys. style should be one of 'default', 'cancel' or 'destructive'.
typeAlertTypeNoDeprecated, do not use.

Example with custom buttons:

AlertIOS.alert(
'Update available',
'Keep your app up to date to enjoy the latest features',
[
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{
text: 'Install',
onPress: () => console.log('Install Pressed')
}
]
);

prompt()

static prompt(title: string, [message]: string, [callbackOrButtons]: ?((text: string) => void), ButtonsArray, [type]: AlertType, [defaultValue]: string, [keyboardType]: string): [object Object]

Create and display a prompt to enter some text.

Parameters:

NameTypeRequiredDescription
titlestringYesThe dialog's title.
messagestringNoAn optional message that appears above the text input.
callbackOrButtons?((text: string) => void),ButtonsArrayNoThis optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called with the prompt's value when the user taps 'OK'. If passed an array of button configurations, each button should include a text key, as well as optional onPress and style keys (see example). style should be one of 'default', 'cancel' or 'destructive'.
typeAlertTypeNoThis configures the text input. One of 'plain-text', 'secure-text' or 'login-password'.
defaultValuestringNoThe default text in text input.
keyboardTypestringNoThe keyboard type of first text field(if exists). One of 'default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter' or 'web-search'.

Example with custom buttons:

AlertIOS.prompt(
'Enter password',
'Enter your password to claim your $1.5B in lottery winnings',
[
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{
text: 'OK',
onPress: (password) =>
console.log('OK Pressed, password: ' + password)
}
],
'secure-text'
);

,

Example with the default button and a custom callback:

AlertIOS.prompt(
'Update username',
null,
(text) => console.log('Your username is ' + text),
null,
'default'
);

Type Definitions

AlertType

An Alert button type

Type
\$Enum

Constants:

ValueDescription
defaultDefault alert with no inputs
plain-textPlain text input alert
secure-textSecure text input alert
login-passwordLogin and password alert

AlertButtonStyle

An Alert button style

Type
\$Enum

Constants:

ValueDescription
defaultDefault button style
cancelCancel button style
destructiveDestructive button style

ButtonsArray

Array or buttons

Type
Array

Properties:

NameTypeDescription
[text]stringButton label
[onPress]functionCallback function when button pressed
[style]AlertButtonStyleButton style

Constants:

ValueDescription
textButton label
onPressCallback function when button pressed
styleButton style
Edit this page
Last updated on
- + diff --git a/docs/next/alertios/index.html b/docs/next/alertios/index.html index 642f47e35ce..ff0ca6216db 100644 --- a/docs/next/alertios/index.html +++ b/docs/next/alertios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 AlertIOS

Deprecated. Use Alert instead.

AlertIOS provides functionality to create an iOS alert dialog with a message or create a prompt for user input.

Creating an iOS alert:

AlertIOS.alert(
'Sync Complete',
'All your data are belong to us.'
);

Creating an iOS prompt:

AlertIOS.prompt('Enter a value', null, (text) =>
console.log('You entered ' + text)
);

We recommend using the Alert.alert method for cross-platform support if you don't need to create iOS-only prompts.

Reference

Methods

alert()

static alert(title: string, [message]: string, [callbackOrButtons]: ?(() => void), ButtonsArray, [type]: AlertType): [object Object]

Create and display a popup alert.

Parameters:

NameTypeRequiredDescription
titlestringYesThe dialog's title. Passing null or '' will hide the title.
messagestringNoAn optional message that appears below the dialog's title.
callbackOrButtons?(() => void),ButtonsArrayNoThis optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called when the user taps 'OK'. If passed an array of button configurations, each button should include a text key, as well as optional onPress and style keys. style should be one of 'default', 'cancel' or 'destructive'.
typeAlertTypeNoDeprecated, do not use.

Example with custom buttons:

AlertIOS.alert(
'Update available',
'Keep your app up to date to enjoy the latest features',
[
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{
text: 'Install',
onPress: () => console.log('Install Pressed')
}
]
);

prompt()

static prompt(title: string, [message]: string, [callbackOrButtons]: ?((text: string) => void), ButtonsArray, [type]: AlertType, [defaultValue]: string, [keyboardType]: string): [object Object]

Create and display a prompt to enter some text.

Parameters:

NameTypeRequiredDescription
titlestringYesThe dialog's title.
messagestringNoAn optional message that appears above the text input.
callbackOrButtons?((text: string) => void),ButtonsArrayNoThis optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called with the prompt's value when the user taps 'OK'. If passed an array of button configurations, each button should include a text key, as well as optional onPress and style keys (see example). style should be one of 'default', 'cancel' or 'destructive'.
typeAlertTypeNoThis configures the text input. One of 'plain-text', 'secure-text' or 'login-password'.
defaultValuestringNoThe default text in text input.
keyboardTypestringNoThe keyboard type of first text field(if exists). One of 'default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter' or 'web-search'.

Example with custom buttons:

AlertIOS.prompt(
'Enter password',
'Enter your password to claim your $1.5B in lottery winnings',
[
{
text: 'Cancel',
onPress: () => console.log('Cancel Pressed'),
style: 'cancel'
},
{
text: 'OK',
onPress: (password) =>
console.log('OK Pressed, password: ' + password)
}
],
'secure-text'
);

,

Example with the default button and a custom callback:

AlertIOS.prompt(
'Update username',
null,
(text) => console.log('Your username is ' + text),
null,
'default'
);

Type Definitions

AlertType

An Alert button type

Type
\$Enum

Constants:

ValueDescription
defaultDefault alert with no inputs
plain-textPlain text input alert
secure-textSecure text input alert
login-passwordLogin and password alert

AlertButtonStyle

An Alert button style

Type
\$Enum

Constants:

ValueDescription
defaultDefault button style
cancelCancel button style
destructiveDestructive button style

ButtonsArray

Array or buttons

Type
Array

Properties:

NameTypeDescription
[text]stringButton label
[onPress]functionCallback function when button pressed
[style]AlertButtonStyleButton style

Constants:

ValueDescription
textButton label
onPressCallback function when button pressed
styleButton style
Edit this page
Last updated on
- + diff --git a/docs/next/animated.html b/docs/next/animated.html index e96f1eb7bd9..59c9b6190bb 100644 --- a/docs/next/animated.html +++ b/docs/next/animated.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Animated

The Animated library is designed to make animations fluid, powerful, and painless to build and maintain. Animated focuses on declarative relationships between inputs and outputs, configurable transforms in between, and start/stop methods to control time-based animation execution.

The core workflow for creating an animation is to create an Animated.Value, hook it up to one or more style attributes of an animated component, and then drive updates via animations using Animated.timing().

Don't modify the animated value directly. You can use the useRef Hook to return a mutable ref object. This ref object's current property is initialized as the given argument and persists throughout the component lifecycle.

Example

The following example contains a View which will fade in and fade out based on the animated value fadeAnim

Refer to the Animations guide to see additional examples of Animated in action.

Overview

There are two value types you can use with Animated:

Animated.Value can bind to style properties or other props, and can be interpolated as well. A single Animated.Value can drive any number of properties.

Configuring animations

Animated provides three types of animation types. Each animation type provides a particular animation curve that controls how your values animate from their initial value to the final value:

In most cases, you will be using timing(). By default, it uses a symmetric easeInOut curve that conveys the gradual acceleration of an object to full speed and concludes by gradually decelerating to a stop.

Working with animations

Animations are started by calling start() on your animation. start() takes a completion callback that will be called when the animation is done. If the animation finished running normally, the completion callback will be invoked with {finished: true}. If the animation is done because stop() was called on it before it could finish (e.g. because it was interrupted by a gesture or another animation), then it will receive {finished: false}.

Animated.timing({}).start(({ finished }) => {
/* completion callback */
});

Using the native driver

By using the native driver, we send everything about the animation to native before starting the animation, allowing native code to perform the animation on the UI thread without having to go through the bridge on every frame. Once the animation has started, the JS thread can be blocked without affecting the animation.

You can use the native driver by specifying useNativeDriver: true in your animation configuration. See the Animations guide to learn more.

Animatable components

Only animatable components can be animated. These unique components do the magic of binding the animated values to the properties, and do targeted native updates to avoid the cost of the React render and reconciliation process on every frame. They also handle cleanup on unmount so they are safe by default.

Animated exports the following animatable components using the above wrapper:

  • Animated.Image
  • Animated.ScrollView
  • Animated.Text
  • Animated.View
  • Animated.FlatList
  • Animated.SectionList

Composing animations

Animations can also be combined in complex ways using composition functions:

Animations can also be chained together by setting the toValue of one animation to be another Animated.Value. See Tracking dynamic values in the Animations guide.

By default, if one animation is stopped or interrupted, then all other animations in the group are also stopped.

Combining animated values

You can combine two animated values via addition, subtraction, multiplication, division, or modulo to make a new animated value:

Interpolation

The interpolate() function allows input ranges to map to different output ranges. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value. It uses linear interpolation by default but also supports easing functions.

Read more about interpolation in the Animation guide.

Handling gestures and other events

Gestures, like panning or scrolling, and other events can map directly to animated values using Animated.event(). This is done with a structured map syntax so that values can be extracted from complex event objects. The first level is an array to allow mapping across multiple args, and that array contains nested objects.

For example, when working with horizontal scrolling gestures, you would do the following in order to map event.nativeEvent.contentOffset.x to scrollX (an Animated.Value):

onScroll={Animated.event(
// scrollX = e.nativeEvent.contentOffset.x
[{ nativeEvent: {
contentOffset: {
x: scrollX
}
}
}]
)}

Reference

Methods

When the given value is a ValueXY instead of a Value, each config option may be a vector of the form {x: ..., y: ...} instead of a scalar.

decay()

static decay(value, config)

Animates a value from an initial velocity to zero based on a decay coefficient.

Config is an object that may have the following options:

  • velocity: Initial velocity. Required.
  • deceleration: Rate of decay. Default 0.997.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

timing()

static timing(value, config)

Animates a value along a timed easing curve. The Easing module has tons of predefined curves, or you can use your own function.

Config is an object that may have the following options:

  • duration: Length of animation (milliseconds). Default 500.
  • easing: Easing function to define curve. Default is Easing.inOut(Easing.ease).
  • delay: Start the animation after delay (milliseconds). Default 0.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

spring()

static spring(value, config)

Animates a value according to an analytical spring model based on damped harmonic oscillation. Tracks velocity state to create fluid motions as the toValue updates, and can be chained together.

Config is an object that may have the following options.

Note that you can only define one of bounciness/speed, tension/friction, or stiffness/damping/mass, but not more than one:

The friction/tension or bounciness/speed options match the spring model in Facebook Pop, Rebound, and Origami.

  • friction: Controls "bounciness"/overshoot. Default 7.
  • tension: Controls speed. Default 40.
  • speed: Controls speed of the animation. Default 12.
  • bounciness: Controls bounciness. Default 8.

Specifying stiffness/damping/mass as parameters makes Animated.spring use an analytical spring model based on the motion equations of a damped harmonic oscillator. This behavior is slightly more precise and faithful to the physics behind spring dynamics, and closely mimics the implementation in iOS's CASpringAnimation.

  • stiffness: The spring stiffness coefficient. Default 100.
  • damping: Defines how the spring’s motion should be damped due to the forces of friction. Default 10.
  • mass: The mass of the object attached to the end of the spring. Default 1.

Other configuration options are as follows:

  • velocity: The initial velocity of the object attached to the spring. Default 0 (object is at rest).
  • overshootClamping: Boolean indicating whether the spring should be clamped and not bounce. Default false.
  • restDisplacementThreshold: The threshold of displacement from rest below which the spring should be considered at rest. Default 0.001.
  • restSpeedThreshold: The speed at which the spring should be considered at rest in pixels per second. Default 0.001.
  • delay: Start the animation after delay (milliseconds). Default 0.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

add()

static add(a, b)

Creates a new Animated value composed from two Animated values added together.

subtract()

static subtract(a, b)

Creates a new Animated value composed by subtracting the second Animated value from the first Animated value.

divide()

static divide(a, b)

Creates a new Animated value composed by dividing the first Animated value by the second Animated value.

multiply()

static multiply(a, b)

Creates a new Animated value composed from two Animated values multiplied together.

modulo()

static modulo(a, modulus)

Creates a new Animated value that is the (non-negative) modulo of the provided Animated value

diffClamp()

static diffClamp(a, min, max)

Create a new Animated value that is limited between 2 values. It uses the difference between the last value so even if the value is far from the bounds it will start changing when the value starts getting closer again. (value = clamp(value + diff, min, max)).

This is useful with scroll events, for example, to show the navbar when scrolling up and to hide it when scrolling down.

delay()

static delay(time)

Starts an animation after the given delay.

sequence()

static sequence(animations)

Starts an array of animations in order, waiting for each to complete before starting the next. If the current running animation is stopped, no following animations will be started.

parallel()

static parallel(animations, config?)

Starts an array of animations all at the same time. By default, if one of the animations is stopped, they will all be stopped. You can override this with the stopTogether flag.

stagger()

static stagger(time, animations)

Array of animations may run in parallel (overlap), but are started in sequence with successive delays. Nice for doing trailing effects.

loop()

static loop(animation, config?)

Loops a given animation continuously, so that each time it reaches the end, it resets and begins again from the start. Will loop without blocking the JS thread if the child animation is set to useNativeDriver: true. In addition, loops can prevent VirtualizedList-based components from rendering more rows while the animation is running. You can pass isInteraction: false in the child animation config to fix this.

Config is an object that may have the following options:

  • iterations: Number of times the animation should loop. Default -1 (infinite).

event()

static event(argMapping, config?)

Takes an array of mappings and extracts values from each arg accordingly, then calls setValue on the mapped outputs. e.g.

onScroll={Animated.event(
[{nativeEvent: {contentOffset: {x: this._scrollX}}}],
{listener: (event) => console.log(event)}, // Optional async listener
)}
...
onPanResponderMove: Animated.event([
null, // raw event arg ignored
{dx: this._panX}], // gestureState arg
{listener: (event, gestureState) => console.log(event, gestureState)}, // Optional async listener
),

Config is an object that may have the following options:

  • listener: Optional async listener.
  • useNativeDriver: Uses the native driver when true. Default false.

forkEvent()

static forkEvent(event, listener)

Advanced imperative API for snooping on animated events that are passed in through props. It permits to add a new javascript listener to an existing AnimatedEvent. If animatedEvent is a javascript listener, it will merge the 2 listeners into a single one, and if animatedEvent is null/undefined, it will assign the javascript listener directly. Use values directly where possible.

unforkEvent()

static unforkEvent(event, listener)

start()

static start([callback]: ?(result?: {finished: boolean}) => void)

Animations are started by calling start() on your animation. start() takes a completion callback that will be called when the animation is done or when the animation is done because stop() was called on it before it could finish.

Parameters:

NameTypeRequiredDescription
callback?(result?: {finished: boolean})NoFunction that will be called after the animation finished running normally or when the animation is done because stop() was called on it before it could finish

Start example with callback:

Animated.timing({}).start(({ finished }) => {
/* completion callback */
});

stop()

static stop()

Stops any running animation.

reset()

static reset()

Stops any running animation and resets the value to its original.

Properties

Value

Standard value class for driving animations. Typically initialized with new Animated.Value(0);

You can read more about Animated.Value API on the separate page.

ValueXY

2D value class for driving 2D animations, such as pan gestures.

You can read more about Animated.ValueXY API on the separate page.

Interpolation

Exported to use the Interpolation type in flow.

Node

Exported for ease of type checking. All animated values derive from this class.

createAnimatedComponent

Make any React component Animatable. Used to create Animated.View, etc.

attachNativeEvent

Imperative API to attach an animated value to an event on a view. Prefer using Animated.event with useNativeDrive: true if possible.

Edit this page
Last updated on
- + diff --git a/docs/next/animated/index.html b/docs/next/animated/index.html index e96f1eb7bd9..59c9b6190bb 100644 --- a/docs/next/animated/index.html +++ b/docs/next/animated/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Animated

The Animated library is designed to make animations fluid, powerful, and painless to build and maintain. Animated focuses on declarative relationships between inputs and outputs, configurable transforms in between, and start/stop methods to control time-based animation execution.

The core workflow for creating an animation is to create an Animated.Value, hook it up to one or more style attributes of an animated component, and then drive updates via animations using Animated.timing().

Don't modify the animated value directly. You can use the useRef Hook to return a mutable ref object. This ref object's current property is initialized as the given argument and persists throughout the component lifecycle.

Example

The following example contains a View which will fade in and fade out based on the animated value fadeAnim

Refer to the Animations guide to see additional examples of Animated in action.

Overview

There are two value types you can use with Animated:

Animated.Value can bind to style properties or other props, and can be interpolated as well. A single Animated.Value can drive any number of properties.

Configuring animations

Animated provides three types of animation types. Each animation type provides a particular animation curve that controls how your values animate from their initial value to the final value:

In most cases, you will be using timing(). By default, it uses a symmetric easeInOut curve that conveys the gradual acceleration of an object to full speed and concludes by gradually decelerating to a stop.

Working with animations

Animations are started by calling start() on your animation. start() takes a completion callback that will be called when the animation is done. If the animation finished running normally, the completion callback will be invoked with {finished: true}. If the animation is done because stop() was called on it before it could finish (e.g. because it was interrupted by a gesture or another animation), then it will receive {finished: false}.

Animated.timing({}).start(({ finished }) => {
/* completion callback */
});

Using the native driver

By using the native driver, we send everything about the animation to native before starting the animation, allowing native code to perform the animation on the UI thread without having to go through the bridge on every frame. Once the animation has started, the JS thread can be blocked without affecting the animation.

You can use the native driver by specifying useNativeDriver: true in your animation configuration. See the Animations guide to learn more.

Animatable components

Only animatable components can be animated. These unique components do the magic of binding the animated values to the properties, and do targeted native updates to avoid the cost of the React render and reconciliation process on every frame. They also handle cleanup on unmount so they are safe by default.

Animated exports the following animatable components using the above wrapper:

  • Animated.Image
  • Animated.ScrollView
  • Animated.Text
  • Animated.View
  • Animated.FlatList
  • Animated.SectionList

Composing animations

Animations can also be combined in complex ways using composition functions:

Animations can also be chained together by setting the toValue of one animation to be another Animated.Value. See Tracking dynamic values in the Animations guide.

By default, if one animation is stopped or interrupted, then all other animations in the group are also stopped.

Combining animated values

You can combine two animated values via addition, subtraction, multiplication, division, or modulo to make a new animated value:

Interpolation

The interpolate() function allows input ranges to map to different output ranges. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value. It uses linear interpolation by default but also supports easing functions.

Read more about interpolation in the Animation guide.

Handling gestures and other events

Gestures, like panning or scrolling, and other events can map directly to animated values using Animated.event(). This is done with a structured map syntax so that values can be extracted from complex event objects. The first level is an array to allow mapping across multiple args, and that array contains nested objects.

For example, when working with horizontal scrolling gestures, you would do the following in order to map event.nativeEvent.contentOffset.x to scrollX (an Animated.Value):

onScroll={Animated.event(
// scrollX = e.nativeEvent.contentOffset.x
[{ nativeEvent: {
contentOffset: {
x: scrollX
}
}
}]
)}

Reference

Methods

When the given value is a ValueXY instead of a Value, each config option may be a vector of the form {x: ..., y: ...} instead of a scalar.

decay()

static decay(value, config)

Animates a value from an initial velocity to zero based on a decay coefficient.

Config is an object that may have the following options:

  • velocity: Initial velocity. Required.
  • deceleration: Rate of decay. Default 0.997.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

timing()

static timing(value, config)

Animates a value along a timed easing curve. The Easing module has tons of predefined curves, or you can use your own function.

Config is an object that may have the following options:

  • duration: Length of animation (milliseconds). Default 500.
  • easing: Easing function to define curve. Default is Easing.inOut(Easing.ease).
  • delay: Start the animation after delay (milliseconds). Default 0.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

spring()

static spring(value, config)

Animates a value according to an analytical spring model based on damped harmonic oscillation. Tracks velocity state to create fluid motions as the toValue updates, and can be chained together.

Config is an object that may have the following options.

Note that you can only define one of bounciness/speed, tension/friction, or stiffness/damping/mass, but not more than one:

The friction/tension or bounciness/speed options match the spring model in Facebook Pop, Rebound, and Origami.

  • friction: Controls "bounciness"/overshoot. Default 7.
  • tension: Controls speed. Default 40.
  • speed: Controls speed of the animation. Default 12.
  • bounciness: Controls bounciness. Default 8.

Specifying stiffness/damping/mass as parameters makes Animated.spring use an analytical spring model based on the motion equations of a damped harmonic oscillator. This behavior is slightly more precise and faithful to the physics behind spring dynamics, and closely mimics the implementation in iOS's CASpringAnimation.

  • stiffness: The spring stiffness coefficient. Default 100.
  • damping: Defines how the spring’s motion should be damped due to the forces of friction. Default 10.
  • mass: The mass of the object attached to the end of the spring. Default 1.

Other configuration options are as follows:

  • velocity: The initial velocity of the object attached to the spring. Default 0 (object is at rest).
  • overshootClamping: Boolean indicating whether the spring should be clamped and not bounce. Default false.
  • restDisplacementThreshold: The threshold of displacement from rest below which the spring should be considered at rest. Default 0.001.
  • restSpeedThreshold: The speed at which the spring should be considered at rest in pixels per second. Default 0.001.
  • delay: Start the animation after delay (milliseconds). Default 0.
  • isInteraction: Whether or not this animation creates an "interaction handle" on the InteractionManager. Default true.
  • useNativeDriver: Uses the native driver when true. Default false.

add()

static add(a, b)

Creates a new Animated value composed from two Animated values added together.

subtract()

static subtract(a, b)

Creates a new Animated value composed by subtracting the second Animated value from the first Animated value.

divide()

static divide(a, b)

Creates a new Animated value composed by dividing the first Animated value by the second Animated value.

multiply()

static multiply(a, b)

Creates a new Animated value composed from two Animated values multiplied together.

modulo()

static modulo(a, modulus)

Creates a new Animated value that is the (non-negative) modulo of the provided Animated value

diffClamp()

static diffClamp(a, min, max)

Create a new Animated value that is limited between 2 values. It uses the difference between the last value so even if the value is far from the bounds it will start changing when the value starts getting closer again. (value = clamp(value + diff, min, max)).

This is useful with scroll events, for example, to show the navbar when scrolling up and to hide it when scrolling down.

delay()

static delay(time)

Starts an animation after the given delay.

sequence()

static sequence(animations)

Starts an array of animations in order, waiting for each to complete before starting the next. If the current running animation is stopped, no following animations will be started.

parallel()

static parallel(animations, config?)

Starts an array of animations all at the same time. By default, if one of the animations is stopped, they will all be stopped. You can override this with the stopTogether flag.

stagger()

static stagger(time, animations)

Array of animations may run in parallel (overlap), but are started in sequence with successive delays. Nice for doing trailing effects.

loop()

static loop(animation, config?)

Loops a given animation continuously, so that each time it reaches the end, it resets and begins again from the start. Will loop without blocking the JS thread if the child animation is set to useNativeDriver: true. In addition, loops can prevent VirtualizedList-based components from rendering more rows while the animation is running. You can pass isInteraction: false in the child animation config to fix this.

Config is an object that may have the following options:

  • iterations: Number of times the animation should loop. Default -1 (infinite).

event()

static event(argMapping, config?)

Takes an array of mappings and extracts values from each arg accordingly, then calls setValue on the mapped outputs. e.g.

onScroll={Animated.event(
[{nativeEvent: {contentOffset: {x: this._scrollX}}}],
{listener: (event) => console.log(event)}, // Optional async listener
)}
...
onPanResponderMove: Animated.event([
null, // raw event arg ignored
{dx: this._panX}], // gestureState arg
{listener: (event, gestureState) => console.log(event, gestureState)}, // Optional async listener
),

Config is an object that may have the following options:

  • listener: Optional async listener.
  • useNativeDriver: Uses the native driver when true. Default false.

forkEvent()

static forkEvent(event, listener)

Advanced imperative API for snooping on animated events that are passed in through props. It permits to add a new javascript listener to an existing AnimatedEvent. If animatedEvent is a javascript listener, it will merge the 2 listeners into a single one, and if animatedEvent is null/undefined, it will assign the javascript listener directly. Use values directly where possible.

unforkEvent()

static unforkEvent(event, listener)

start()

static start([callback]: ?(result?: {finished: boolean}) => void)

Animations are started by calling start() on your animation. start() takes a completion callback that will be called when the animation is done or when the animation is done because stop() was called on it before it could finish.

Parameters:

NameTypeRequiredDescription
callback?(result?: {finished: boolean})NoFunction that will be called after the animation finished running normally or when the animation is done because stop() was called on it before it could finish

Start example with callback:

Animated.timing({}).start(({ finished }) => {
/* completion callback */
});

stop()

static stop()

Stops any running animation.

reset()

static reset()

Stops any running animation and resets the value to its original.

Properties

Value

Standard value class for driving animations. Typically initialized with new Animated.Value(0);

You can read more about Animated.Value API on the separate page.

ValueXY

2D value class for driving 2D animations, such as pan gestures.

You can read more about Animated.ValueXY API on the separate page.

Interpolation

Exported to use the Interpolation type in flow.

Node

Exported for ease of type checking. All animated values derive from this class.

createAnimatedComponent

Make any React component Animatable. Used to create Animated.View, etc.

attachNativeEvent

Imperative API to attach an animated value to an event on a view. Prefer using Animated.event with useNativeDrive: true if possible.

Edit this page
Last updated on
- + diff --git a/docs/next/animatedvalue.html b/docs/next/animatedvalue.html index 32d886cdf35..fe2dcffcc25 100644 --- a/docs/next/animatedvalue.html +++ b/docs/next/animatedvalue.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Animated.Value

Standard value for driving animations. One Animated.Value can drive multiple properties in a synchronized fashion, but can only be driven by one mechanism at a time. Using a new mechanism (e.g. starting a new animation, or calling setValue) will stop any previous ones.

Typically initialized with new Animated.Value(0);

Reference

Methods

setValue()

setValue(value);

Directly set the value. This will stop any animations running on the value and update all the bound properties.

Parameters:

NameTypeRequiredDescription
valuenumberYesValue

setOffset()

setOffset(offset);

Sets an offset that is applied on top of whatever value is set, whether via setValue, an animation, or Animated.event. Useful for compensating things like the start of a pan gesture.

Parameters:

NameTypeRequiredDescription
offsetnumberYesOffset value

flattenOffset()

flattenOffset();

Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.

extractOffset()

extractOffset();

Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.

addListener()

addListener(callback);

Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.

Returns a string that serves as an identifier for the listener.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesThe callback function which will receive an object with a value key set to the new value.

removeListener()

removeListener(id);

Unregister a listener. The id param shall match the identifier previously returned by addListener().

Parameters:

NameTypeRequiredDescription
idstringYesId for the listener being removed.

removeAllListeners()

removeAllListeners();

Remove all registered listeners.

stopAnimation()

stopAnimation([callback]);

Stops any running animation or tracking. callback is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the final value.

resetAnimation()

resetAnimation([callback]);

Stops any animation and resets the value to its original.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the original value.

interpolate()

interpolate(config);

Interpolates the value before updating the property, e.g. mapping 0-1 to 0-10.

See AnimatedInterpolation.js

Parameters:

NameTypeRequiredDescription
configobjectYesSee below.

The config object is composed of the following keys:

  • inputRange: an array of numbers
  • outputRange: an array of numbers or strings
  • easing (optional): a function that returns a number, given an input number
  • extrapolate (optional): a string such as 'extend', 'identity', or 'clamp'
  • extrapolateLeft (optional): a string such as 'extend', 'identity', or 'clamp'
  • extrapolateRight (optional): a string such as 'extend', 'identity', or 'clamp'

animate()

animate(animation, callback);

Typically only used internally, but could be used by a custom Animation class.

Parameters:

NameTypeRequiredDescription
animationAnimationYesSee Animation.js.
callbackfunctionYesCallback function.

stopTracking()

stopTracking();

Typically only used internally.

track()

track(tracking);

Typically only used internally.

Parameters:

NameTypeRequiredDescription
trackingAnimatedNodeYesSee AnimatedNode.js
Edit this page
Last updated on
- + diff --git a/docs/next/animatedvalue/index.html b/docs/next/animatedvalue/index.html index 32d886cdf35..fe2dcffcc25 100644 --- a/docs/next/animatedvalue/index.html +++ b/docs/next/animatedvalue/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Animated.Value

Standard value for driving animations. One Animated.Value can drive multiple properties in a synchronized fashion, but can only be driven by one mechanism at a time. Using a new mechanism (e.g. starting a new animation, or calling setValue) will stop any previous ones.

Typically initialized with new Animated.Value(0);

Reference

Methods

setValue()

setValue(value);

Directly set the value. This will stop any animations running on the value and update all the bound properties.

Parameters:

NameTypeRequiredDescription
valuenumberYesValue

setOffset()

setOffset(offset);

Sets an offset that is applied on top of whatever value is set, whether via setValue, an animation, or Animated.event. Useful for compensating things like the start of a pan gesture.

Parameters:

NameTypeRequiredDescription
offsetnumberYesOffset value

flattenOffset()

flattenOffset();

Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.

extractOffset()

extractOffset();

Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.

addListener()

addListener(callback);

Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.

Returns a string that serves as an identifier for the listener.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesThe callback function which will receive an object with a value key set to the new value.

removeListener()

removeListener(id);

Unregister a listener. The id param shall match the identifier previously returned by addListener().

Parameters:

NameTypeRequiredDescription
idstringYesId for the listener being removed.

removeAllListeners()

removeAllListeners();

Remove all registered listeners.

stopAnimation()

stopAnimation([callback]);

Stops any running animation or tracking. callback is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the final value.

resetAnimation()

resetAnimation([callback]);

Stops any animation and resets the value to its original.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the original value.

interpolate()

interpolate(config);

Interpolates the value before updating the property, e.g. mapping 0-1 to 0-10.

See AnimatedInterpolation.js

Parameters:

NameTypeRequiredDescription
configobjectYesSee below.

The config object is composed of the following keys:

  • inputRange: an array of numbers
  • outputRange: an array of numbers or strings
  • easing (optional): a function that returns a number, given an input number
  • extrapolate (optional): a string such as 'extend', 'identity', or 'clamp'
  • extrapolateLeft (optional): a string such as 'extend', 'identity', or 'clamp'
  • extrapolateRight (optional): a string such as 'extend', 'identity', or 'clamp'

animate()

animate(animation, callback);

Typically only used internally, but could be used by a custom Animation class.

Parameters:

NameTypeRequiredDescription
animationAnimationYesSee Animation.js.
callbackfunctionYesCallback function.

stopTracking()

stopTracking();

Typically only used internally.

track()

track(tracking);

Typically only used internally.

Parameters:

NameTypeRequiredDescription
trackingAnimatedNodeYesSee AnimatedNode.js
Edit this page
Last updated on
- + diff --git a/docs/next/animatedvaluexy.html b/docs/next/animatedvaluexy.html index 4786b768ed6..1aa3dd6409a 100644 --- a/docs/next/animatedvaluexy.html +++ b/docs/next/animatedvaluexy.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Animated.ValueXY

2D Value for driving 2D animations, such as pan gestures. Almost identical API to normal Animated.Value, but multiplexed. Contains two regular Animated.Values under the hood.

Example

Reference

Methods

setValue()

setValue(value);

Directly set the value. This will stop any animations running on the value and update all the bound properties.

Parameters:

NameTypeRequiredDescription
valuenumberYesValue

setOffset()

setOffset(offset);

Sets an offset that is applied on top of whatever value is set, whether via setValue, an animation, or Animated.event. Useful for compensating things like the start of a pan gesture.

Parameters:

NameTypeRequiredDescription
offsetnumberYesOffset value

flattenOffset()

flattenOffset();

Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.

extractOffset()

extractOffset();

Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.

addListener()

addListener(callback);

Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.

Returns a string that serves as an identifier for the listener.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesThe callback function which will receive an object with a value key set to the new value.

removeListener()

removeListener(id);

Unregister a listener. The id param shall match the identifier previously returned by addListener().

Parameters:

NameTypeRequiredDescription
idstringYesId for the listener being removed.

removeAllListeners()

removeAllListeners();

Remove all registered listeners.

stopAnimation()

stopAnimation([callback]);

Stops any running animation or tracking. callback is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the final value.

resetAnimation()

resetAnimation([callback]);

Stops any animation and resets the value to its original.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the original value.

getLayout()

getLayout();

Converts {x, y} into {left, top} for use in style, e.g.

style={this.state.anim.getLayout()}

getTranslateTransform()

getTranslateTransform();

Converts {x, y} into a useable translation transform, e.g.

style={{
transform: this.state.anim.getTranslateTransform()
}}
Edit this page
Last updated on
- + diff --git a/docs/next/animatedvaluexy/index.html b/docs/next/animatedvaluexy/index.html index 4786b768ed6..1aa3dd6409a 100644 --- a/docs/next/animatedvaluexy/index.html +++ b/docs/next/animatedvaluexy/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Animated.ValueXY

2D Value for driving 2D animations, such as pan gestures. Almost identical API to normal Animated.Value, but multiplexed. Contains two regular Animated.Values under the hood.

Example

Reference

Methods

setValue()

setValue(value);

Directly set the value. This will stop any animations running on the value and update all the bound properties.

Parameters:

NameTypeRequiredDescription
valuenumberYesValue

setOffset()

setOffset(offset);

Sets an offset that is applied on top of whatever value is set, whether via setValue, an animation, or Animated.event. Useful for compensating things like the start of a pan gesture.

Parameters:

NameTypeRequiredDescription
offsetnumberYesOffset value

flattenOffset()

flattenOffset();

Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.

extractOffset()

extractOffset();

Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.

addListener()

addListener(callback);

Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.

Returns a string that serves as an identifier for the listener.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesThe callback function which will receive an object with a value key set to the new value.

removeListener()

removeListener(id);

Unregister a listener. The id param shall match the identifier previously returned by addListener().

Parameters:

NameTypeRequiredDescription
idstringYesId for the listener being removed.

removeAllListeners()

removeAllListeners();

Remove all registered listeners.

stopAnimation()

stopAnimation([callback]);

Stops any running animation or tracking. callback is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the final value.

resetAnimation()

resetAnimation([callback]);

Stops any animation and resets the value to its original.

Parameters:

NameTypeRequiredDescription
callbackfunctionNoA function that will receive the original value.

getLayout()

getLayout();

Converts {x, y} into {left, top} for use in style, e.g.

style={this.state.anim.getLayout()}

getTranslateTransform()

getTranslateTransform();

Converts {x, y} into a useable translation transform, e.g.

style={{
transform: this.state.anim.getTranslateTransform()
}}
Edit this page
Last updated on
- + diff --git a/docs/next/animations.html b/docs/next/animations.html index 385642af970..8322e61ce57 100644 --- a/docs/next/animations.html +++ b/docs/next/animations.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Animated.spring(a, {
toValue: 2
}).start();

Interpolation

Each property can be run through an interpolation first. An interpolation maps input ranges to output ranges, typically using a linear interpolation but also supports easing functions. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value.

A basic mapping to convert a 0-1 range to a 0-100 range would be:

value.interpolate({
inputRange: [0, 1],
outputRange: [0, 100]
});

For example, you may want to think about your Animated.Value as going from 0 to 1, but animate the position from 150px to 0px and the opacity from 0 to 1. This can be done by modifying style from the example above like so:

style={{
opacity: this.state.fadeAnim, // Binds directly
transform: [{
translateY: this.state.fadeAnim.interpolate({
inputRange: [0, 1],
outputRange: [150, 0] // 0 : 150, 0.5 : 75, 1 : 0
}),
}],
}}

interpolate() supports multiple range segments as well, which is handy for defining dead zones and other handy tricks. For example, to get a negation relationship at -300 that goes to 0 at -100, then back up to 1 at 0, and then back down to zero at 100 followed by a dead-zone that remains at 0 for everything beyond that, you could do:

value.interpolate({
inputRange: [-300, -100, 0, 100, 101],
outputRange: [300, 0, 1, 0, 0]
});

Which would map like so:

Input | Output
------|-------
-400| 450
-300| 300
-200| 150
-100| 0
-50| 0.5
0| 1
50| 0.5
100| 0
101| 0
200| 0

interpolate() also supports mapping to strings, allowing you to animate colors as well as values with units. For example, if you wanted to animate a rotation you could do:

value.interpolate({
inputRange: [0, 360],
outputRange: ['0deg', '360deg']
});

interpolate() also supports arbitrary easing functions, many of which are already implemented in the Easing module. interpolate() also has configurable behavior for extrapolating the outputRange. You can set the extrapolation by setting the extrapolate, extrapolateLeft, or extrapolateRight options. The default value is extend but you can use clamp to prevent the output value from exceeding outputRange.

Tracking dynamic values

Animated values can also track other values by setting the toValue of an animation to another animated value instead of a plain number. For example, a "Chat Heads" animation like the one used by Messenger on Android could be implemented with a spring() pinned on another animated value, or with timing() and a duration of 0 for rigid tracking. They can also be composed with interpolations:

Animated.spring(follower, { toValue: leader }).start();
Animated.timing(opacity, {
toValue: pan.x.interpolate({
inputRange: [0, 300],
outputRange: [1, 0]
})
}).start();

The leader and follower animated values would be implemented using Animated.ValueXY(). ValueXY is a handy way to deal with 2D interactions, such as panning or dragging. It is a basic wrapper that contains two Animated.Value instances and some helper functions that call through to them, making ValueXY a drop-in replacement for Value in many cases. It allows us to track both x and y values in the example above.

Tracking gestures

Gestures, like panning or scrolling, and other events can map directly to animated values using Animated.event. This is done with a structured map syntax so that values can be extracted from complex event objects. The first level is an array to allow mapping across multiple args, and that array contains nested objects.

For example, when working with horizontal scrolling gestures, you would do the following in order to map event.nativeEvent.contentOffset.x to scrollX (an Animated.Value):

onScroll={Animated.event(
// scrollX = e.nativeEvent.contentOffset.x
[{ nativeEvent: {
contentOffset: {
x: scrollX
}
}
}]
)}

The following example implements a horizontal scrolling carousel where the scroll position indicators are animated using the Animated.event used in the ScrollView

ScrollView with Animated Event Example

When using PanResponder, you could use the following code to extract the x and y positions from gestureState.dx and gestureState.dy. We use a null in the first position of the array, as we are only interested in the second argument passed to the PanResponder handler, which is the gestureState.

onPanResponderMove={Animated.event(
[null, // ignore the native event
// extract dx and dy from gestureState
// like 'pan.x = gestureState.dx, pan.y = gestureState.dy'
{dx: pan.x, dy: pan.y}
])}

PanResponder with Animated Event Example

Responding to the current animation value

You may notice that there is no clear way to read the current value while animating. This is because the value may only be known in the native runtime due to optimizations. If you need to run JavaScript in response to the current value, there are two approaches:

Animated is designed to be fully serializable so that animations can be run in a high performance way, independent of the normal JavaScript event loop. This does influence the API, so keep that in mind when it seems a little trickier to do something compared to a fully synchronous system. Check out Animated.Value.addListener as a way to work around some of these limitations, but use it sparingly since it might have performance implications in the future.

Using the native driver

The Animated API is designed to be serializable. By using the native driver, we send everything about the animation to native before starting the animation, allowing native code to perform the animation on the UI thread without having to go through the bridge on every frame. Once the animation has started, the JS thread can be blocked without affecting the animation.

Using the native driver for normal animations is straightforward. You can add useNativeDriver: true to the animation config when starting it.

Animated.timing(this.state.animatedValue, {
toValue: 1,
duration: 500,
useNativeDriver: true // <-- Add this
}).start();

Animated values are only compatible with one driver so if you use native driver when starting an animation on a value, make sure every animation on that value also uses the native driver.

The native driver also works with Animated.event. This is especially useful for animations that follow the scroll position as without the native driver, the animation will always run a frame behind the gesture due to the async nature of React Native.

<Animated.ScrollView // <-- Use the Animated ScrollView wrapper
scrollEventThrottle={1} // <-- Use 1 here to make sure no events are ever missed
onScroll={Animated.event(
[
{
nativeEvent: {
contentOffset: { y: this.state.animatedValue }
}
}
],
{ useNativeDriver: true } // <-- Add this
)}>
{content}
</Animated.ScrollView>

You can see the native driver in action by running the RNTester app, then loading the Native Animated Example. You can also take a look at the source code to learn how these examples were produced.

Caveats

Not everything you can do with Animated is currently supported by the native driver. The main limitation is that you can only animate non-layout properties: things like transform and opacity will work, but Flexbox and position properties will not. When using Animated.event, it will only work with direct events and not bubbling events. This means it does not work with PanResponder but does work with things like ScrollView#onScroll.

When an animation is running, it can prevent VirtualizedList components from rendering more rows. If you need to run a long or looping animation while the user is scrolling through a list, you can use isInteraction: false in your animation's config to prevent this issue.

Bear in mind

While using transform styles such as rotateY, rotateX, and others ensure the transform style perspective is in place. At this time some animations may not render on Android without it. Example below.

<Animated.View
style={{
transform: [
{ scale: this.state.scale },
{ rotateY: this.state.rotateY },
{ perspective: 1000 } // without this line this Animation will not render on Android while working fine on iOS
]
}}
/>

Additional examples

The RNTester app has various examples of Animated in use:

LayoutAnimation API

LayoutAnimation allows you to globally configure create and update animations that will be used for all views in the next render/layout cycle. This is useful for doing Flexbox layout updates without bothering to measure or calculate specific properties in order to animate them directly, and is especially useful when layout changes may affect ancestors, for example a "see more" expansion that also increases the size of the parent and pushes down the row below which would otherwise require explicit coordination between the components in order to animate them all in sync.

Note that although LayoutAnimation is very powerful and can be quite useful, it provides much less control than Animated and other animation libraries, so you may need to use another approach if you can't get LayoutAnimation to do what you want.

Note that in order to get this to work on Android you need to set the following flags via UIManager:

UIManager.setLayoutAnimationEnabledExperimental &&
UIManager.setLayoutAnimationEnabledExperimental(true);

This example uses a preset value, you can customize the animations as you need, see LayoutAnimation.js for more information.

Additional notes

requestAnimationFrame

requestAnimationFrame is a polyfill from the browser that you might be familiar with. It accepts a function as its only argument and calls that function before the next repaint. It is an essential building block for animations that underlies all of the JavaScript-based animation APIs. In general, you shouldn't need to call this yourself - the animation APIs will manage frame updates for you.

setNativeProps

As mentioned in the Direct Manipulation section, setNativeProps allows us to modify properties of native-backed components (components that are actually backed by native views, unlike composite components) directly, without having to setState and re-render the component hierarchy.

We could use this in the Rebound example to update the scale - this might be helpful if the component that we are updating is deeply nested and hasn't been optimized with shouldComponentUpdate.

If you find your animations with dropping frames (performing below 60 frames per second), look into using setNativeProps or shouldComponentUpdate to optimize them. Or you could run the animations on the UI thread rather than the JavaScript thread with the useNativeDriver 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.

Edit this page
Last updated on
- + diff --git a/docs/next/animations/index.html b/docs/next/animations/index.html index 385642af970..8322e61ce57 100644 --- a/docs/next/animations/index.html +++ b/docs/next/animations/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
Animated.spring(a, {
toValue: 2
}).start();

Interpolation

Each property can be run through an interpolation first. An interpolation maps input ranges to output ranges, typically using a linear interpolation but also supports easing functions. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value.

A basic mapping to convert a 0-1 range to a 0-100 range would be:

value.interpolate({
inputRange: [0, 1],
outputRange: [0, 100]
});

For example, you may want to think about your Animated.Value as going from 0 to 1, but animate the position from 150px to 0px and the opacity from 0 to 1. This can be done by modifying style from the example above like so:

style={{
opacity: this.state.fadeAnim, // Binds directly
transform: [{
translateY: this.state.fadeAnim.interpolate({
inputRange: [0, 1],
outputRange: [150, 0] // 0 : 150, 0.5 : 75, 1 : 0
}),
}],
}}

interpolate() supports multiple range segments as well, which is handy for defining dead zones and other handy tricks. For example, to get a negation relationship at -300 that goes to 0 at -100, then back up to 1 at 0, and then back down to zero at 100 followed by a dead-zone that remains at 0 for everything beyond that, you could do:

value.interpolate({
inputRange: [-300, -100, 0, 100, 101],
outputRange: [300, 0, 1, 0, 0]
});

Which would map like so:

Input | Output
------|-------
-400| 450
-300| 300
-200| 150
-100| 0
-50| 0.5
0| 1
50| 0.5
100| 0
101| 0
200| 0

interpolate() also supports mapping to strings, allowing you to animate colors as well as values with units. For example, if you wanted to animate a rotation you could do:

value.interpolate({
inputRange: [0, 360],
outputRange: ['0deg', '360deg']
});

interpolate() also supports arbitrary easing functions, many of which are already implemented in the Easing module. interpolate() also has configurable behavior for extrapolating the outputRange. You can set the extrapolation by setting the extrapolate, extrapolateLeft, or extrapolateRight options. The default value is extend but you can use clamp to prevent the output value from exceeding outputRange.

Tracking dynamic values

Animated values can also track other values by setting the toValue of an animation to another animated value instead of a plain number. For example, a "Chat Heads" animation like the one used by Messenger on Android could be implemented with a spring() pinned on another animated value, or with timing() and a duration of 0 for rigid tracking. They can also be composed with interpolations:

Animated.spring(follower, { toValue: leader }).start();
Animated.timing(opacity, {
toValue: pan.x.interpolate({
inputRange: [0, 300],
outputRange: [1, 0]
})
}).start();

The leader and follower animated values would be implemented using Animated.ValueXY(). ValueXY is a handy way to deal with 2D interactions, such as panning or dragging. It is a basic wrapper that contains two Animated.Value instances and some helper functions that call through to them, making ValueXY a drop-in replacement for Value in many cases. It allows us to track both x and y values in the example above.

Tracking gestures

Gestures, like panning or scrolling, and other events can map directly to animated values using Animated.event. This is done with a structured map syntax so that values can be extracted from complex event objects. The first level is an array to allow mapping across multiple args, and that array contains nested objects.

For example, when working with horizontal scrolling gestures, you would do the following in order to map event.nativeEvent.contentOffset.x to scrollX (an Animated.Value):

onScroll={Animated.event(
// scrollX = e.nativeEvent.contentOffset.x
[{ nativeEvent: {
contentOffset: {
x: scrollX
}
}
}]
)}

The following example implements a horizontal scrolling carousel where the scroll position indicators are animated using the Animated.event used in the ScrollView

ScrollView with Animated Event Example

When using PanResponder, you could use the following code to extract the x and y positions from gestureState.dx and gestureState.dy. We use a null in the first position of the array, as we are only interested in the second argument passed to the PanResponder handler, which is the gestureState.

onPanResponderMove={Animated.event(
[null, // ignore the native event
// extract dx and dy from gestureState
// like 'pan.x = gestureState.dx, pan.y = gestureState.dy'
{dx: pan.x, dy: pan.y}
])}

PanResponder with Animated Event Example

Responding to the current animation value

You may notice that there is no clear way to read the current value while animating. This is because the value may only be known in the native runtime due to optimizations. If you need to run JavaScript in response to the current value, there are two approaches:

Animated is designed to be fully serializable so that animations can be run in a high performance way, independent of the normal JavaScript event loop. This does influence the API, so keep that in mind when it seems a little trickier to do something compared to a fully synchronous system. Check out Animated.Value.addListener as a way to work around some of these limitations, but use it sparingly since it might have performance implications in the future.

Using the native driver

The Animated API is designed to be serializable. By using the native driver, we send everything about the animation to native before starting the animation, allowing native code to perform the animation on the UI thread without having to go through the bridge on every frame. Once the animation has started, the JS thread can be blocked without affecting the animation.

Using the native driver for normal animations is straightforward. You can add useNativeDriver: true to the animation config when starting it.

Animated.timing(this.state.animatedValue, {
toValue: 1,
duration: 500,
useNativeDriver: true // <-- Add this
}).start();

Animated values are only compatible with one driver so if you use native driver when starting an animation on a value, make sure every animation on that value also uses the native driver.

The native driver also works with Animated.event. This is especially useful for animations that follow the scroll position as without the native driver, the animation will always run a frame behind the gesture due to the async nature of React Native.

<Animated.ScrollView // <-- Use the Animated ScrollView wrapper
scrollEventThrottle={1} // <-- Use 1 here to make sure no events are ever missed
onScroll={Animated.event(
[
{
nativeEvent: {
contentOffset: { y: this.state.animatedValue }
}
}
],
{ useNativeDriver: true } // <-- Add this
)}>
{content}
</Animated.ScrollView>

You can see the native driver in action by running the RNTester app, then loading the Native Animated Example. You can also take a look at the source code to learn how these examples were produced.

Caveats

Not everything you can do with Animated is currently supported by the native driver. The main limitation is that you can only animate non-layout properties: things like transform and opacity will work, but Flexbox and position properties will not. When using Animated.event, it will only work with direct events and not bubbling events. This means it does not work with PanResponder but does work with things like ScrollView#onScroll.

When an animation is running, it can prevent VirtualizedList components from rendering more rows. If you need to run a long or looping animation while the user is scrolling through a list, you can use isInteraction: false in your animation's config to prevent this issue.

Bear in mind

While using transform styles such as rotateY, rotateX, and others ensure the transform style perspective is in place. At this time some animations may not render on Android without it. Example below.

<Animated.View
style={{
transform: [
{ scale: this.state.scale },
{ rotateY: this.state.rotateY },
{ perspective: 1000 } // without this line this Animation will not render on Android while working fine on iOS
]
}}
/>

Additional examples

The RNTester app has various examples of Animated in use:

LayoutAnimation API

LayoutAnimation allows you to globally configure create and update animations that will be used for all views in the next render/layout cycle. This is useful for doing Flexbox layout updates without bothering to measure or calculate specific properties in order to animate them directly, and is especially useful when layout changes may affect ancestors, for example a "see more" expansion that also increases the size of the parent and pushes down the row below which would otherwise require explicit coordination between the components in order to animate them all in sync.

Note that although LayoutAnimation is very powerful and can be quite useful, it provides much less control than Animated and other animation libraries, so you may need to use another approach if you can't get LayoutAnimation to do what you want.

Note that in order to get this to work on Android you need to set the following flags via UIManager:

UIManager.setLayoutAnimationEnabledExperimental &&
UIManager.setLayoutAnimationEnabledExperimental(true);

This example uses a preset value, you can customize the animations as you need, see LayoutAnimation.js for more information.

Additional notes

requestAnimationFrame

requestAnimationFrame is a polyfill from the browser that you might be familiar with. It accepts a function as its only argument and calls that function before the next repaint. It is an essential building block for animations that underlies all of the JavaScript-based animation APIs. In general, you shouldn't need to call this yourself - the animation APIs will manage frame updates for you.

setNativeProps

As mentioned in the Direct Manipulation section, setNativeProps allows us to modify properties of native-backed components (components that are actually backed by native views, unlike composite components) directly, without having to setState and re-render the component hierarchy.

We could use this in the Rebound example to update the scale - this might be helpful if the component that we are updating is deeply nested and hasn't been optimized with shouldComponentUpdate.

If you find your animations with dropping frames (performing below 60 frames per second), look into using setNativeProps or shouldComponentUpdate to optimize them. Or you could run the animations on the UI thread rather than the JavaScript thread with the useNativeDriver 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.

Edit this page
Last updated on
- + diff --git a/docs/next/app-extensions.html b/docs/next/app-extensions.html index c7f3afbf72f..34358e38a24 100644 --- a/docs/next/app-extensions.html +++ b/docs/next/app-extensions.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

App Extensions

App extensions let you provide custom functionality and content outside of your main app. There are different types of app extensions on iOS, and they are all covered in the App Extension Programming Guide. In this guide, we'll briefly cover how you may take advantage of app extensions on iOS.

Memory use in extensions

As these extensions are loaded outside of the regular app sandbox, it's highly likely that several of these app extensions will be loaded simultaneously. As you might expect, these extensions have small memory usage limits. Keep these in mind when developing your app extensions. It's always highly recommended to test your application on an actual device, and more so when developing app extensions: too frequently, developers find that their extension works fine in the iOS Simulator, only to get user reports that their extension is not loading on actual devices.

We highly recommend that you watch Conrad Kramer's talk on Memory Use in Extensions to learn more about this topic.

Today widget

The memory limit of a Today widget is 16 MB. As it happens, Today widget implementations using React Native may work unreliably because the memory usage tends to be too high. You can tell if your Today widget is exceeding the memory limit if it yields the message 'Unable to Load':

Always make sure to test your app extensions in a real device, but be aware that this may not be sufficient, especially when dealing with Today widgets. Debug-configured builds are more likely to exceed the memory limits, while release-configured builds don't fail right away. We highly recommend that you use Xcode's Instruments to analyze your real world memory usage, as it's very likely that your release-configured build is very close to the 16 MB limit. In situations like these, you can quickly go over the 16 MB limit by performing common operations, such as fetching data from an API.

To experiment with the limits of React Native Today widget implementations, try extending the example project in react-native-today-widget.

Other app extensions

Other types of app extensions have greater memory limits than the Today widget. For instance, Custom Keyboard extensions are limited to 48 MB, and Share extensions are limited to 120 MB. Implementing such app extensions with React Native is more viable. One proof of concept example is react-native-ios-share-extension.

Edit this page
Last updated on
- + diff --git a/docs/next/app-extensions/index.html b/docs/next/app-extensions/index.html index c7f3afbf72f..34358e38a24 100644 --- a/docs/next/app-extensions/index.html +++ b/docs/next/app-extensions/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

App Extensions

App extensions let you provide custom functionality and content outside of your main app. There are different types of app extensions on iOS, and they are all covered in the App Extension Programming Guide. In this guide, we'll briefly cover how you may take advantage of app extensions on iOS.

Memory use in extensions

As these extensions are loaded outside of the regular app sandbox, it's highly likely that several of these app extensions will be loaded simultaneously. As you might expect, these extensions have small memory usage limits. Keep these in mind when developing your app extensions. It's always highly recommended to test your application on an actual device, and more so when developing app extensions: too frequently, developers find that their extension works fine in the iOS Simulator, only to get user reports that their extension is not loading on actual devices.

We highly recommend that you watch Conrad Kramer's talk on Memory Use in Extensions to learn more about this topic.

Today widget

The memory limit of a Today widget is 16 MB. As it happens, Today widget implementations using React Native may work unreliably because the memory usage tends to be too high. You can tell if your Today widget is exceeding the memory limit if it yields the message 'Unable to Load':

Always make sure to test your app extensions in a real device, but be aware that this may not be sufficient, especially when dealing with Today widgets. Debug-configured builds are more likely to exceed the memory limits, while release-configured builds don't fail right away. We highly recommend that you use Xcode's Instruments to analyze your real world memory usage, as it's very likely that your release-configured build is very close to the 16 MB limit. In situations like these, you can quickly go over the 16 MB limit by performing common operations, such as fetching data from an API.

To experiment with the limits of React Native Today widget implementations, try extending the example project in react-native-today-widget.

Other app extensions

Other types of app extensions have greater memory limits than the Today widget. For instance, Custom Keyboard extensions are limited to 48 MB, and Share extensions are limited to 120 MB. Implementing such app extensions with React Native is more viable. One proof of concept example is react-native-ios-share-extension.

Edit this page
Last updated on
- + diff --git a/docs/next/appearance.html b/docs/next/appearance.html index 671dc00a0c5..1709d071220 100644 --- a/docs/next/appearance.html +++ b/docs/next/appearance.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Appearance

import { Appearance } from 'react-native';

The Appearance module exposes information about the user's appearance preferences, such as their preferred color scheme (light or dark).

Developer notes

The Appearance API is inspired by the Media Queries draft from the W3C. The color scheme preference is modeled after the prefers-color-scheme CSS media feature.

Example

You can use the Appearance module to determine if the user prefers a dark color scheme:

const colorScheme = Appearance.getColorScheme();
if (colorScheme === 'dark') {
// Use dark color scheme
}

Although the color scheme is available immediately, this may change (e.g. scheduled color scheme change at sunrise or sunset). Any rendering logic or styles that depend on the user preferred color scheme should try to call this function on every render, rather than caching the value. For example, you may use the useColorScheme React hook as it provides and subscribes to color scheme updates, or you may use inline styles rather than setting a value in a StyleSheet.

Reference

Methods

getColorScheme()

static getColorScheme()

Indicates the current user preferred color scheme. The value may be updated later, either through direct user action (e.g. theme selection in device settings) or on a schedule (e.g. light and dark themes that follow the day/night cycle).

Supported color schemes:

  • light: The user prefers a light color theme.
  • dark: The user prefers a dark color theme.
  • null: The user has not indicated a preferred color theme.

See also: useColorScheme hook.

Note: getColorScheme() will always return light when debugging with Chrome.

addChangeListener()

static addChangeListener(listener)

Add an event handler that is fired when appearance preferences change.

removeChangeListener()

static removeChangeListener(listener)

Remove an event handler.

Edit this page
Last updated on
- + diff --git a/docs/next/appearance/index.html b/docs/next/appearance/index.html index 671dc00a0c5..1709d071220 100644 --- a/docs/next/appearance/index.html +++ b/docs/next/appearance/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Appearance

import { Appearance } from 'react-native';

The Appearance module exposes information about the user's appearance preferences, such as their preferred color scheme (light or dark).

Developer notes

The Appearance API is inspired by the Media Queries draft from the W3C. The color scheme preference is modeled after the prefers-color-scheme CSS media feature.

Example

You can use the Appearance module to determine if the user prefers a dark color scheme:

const colorScheme = Appearance.getColorScheme();
if (colorScheme === 'dark') {
// Use dark color scheme
}

Although the color scheme is available immediately, this may change (e.g. scheduled color scheme change at sunrise or sunset). Any rendering logic or styles that depend on the user preferred color scheme should try to call this function on every render, rather than caching the value. For example, you may use the useColorScheme React hook as it provides and subscribes to color scheme updates, or you may use inline styles rather than setting a value in a StyleSheet.

Reference

Methods

getColorScheme()

static getColorScheme()

Indicates the current user preferred color scheme. The value may be updated later, either through direct user action (e.g. theme selection in device settings) or on a schedule (e.g. light and dark themes that follow the day/night cycle).

Supported color schemes:

  • light: The user prefers a light color theme.
  • dark: The user prefers a dark color theme.
  • null: The user has not indicated a preferred color theme.

See also: useColorScheme hook.

Note: getColorScheme() will always return light when debugging with Chrome.

addChangeListener()

static addChangeListener(listener)

Add an event handler that is fired when appearance preferences change.

removeChangeListener()

static removeChangeListener(listener)

Remove an event handler.

Edit this page
Last updated on
- + diff --git a/docs/next/appregistry.html b/docs/next/appregistry.html index c27cde1eae0..ff1b5b4e7a1 100644 --- a/docs/next/appregistry.html +++ b/docs/next/appregistry.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
AppRegistry.registerComponent('Appname', () => App);

To "stop" an application when a view should be destroyed, call AppRegistry.unmountApplicationComponentAtRootTag with the tag that was passed into runApplication. These should always be used as a pair.

AppRegistry should be required early in the require sequence to make sure the JS execution environment is setup before other modules are required.

Reference

Methods

cancelHeadlessTask()

static cancelHeadlessTask(taskId, taskKey)

Only called from native code. Cancels a headless task.

Parameters:

NameTypeDescription
taskId
Required
numberThe native id for this task instance that was used when startHeadlessTask was called.
taskKey
Required
stringThe key for the task that was used when startHeadlessTask was called.

enableArchitectureIndicator()

static enableArchitectureIndicator(enabled)

Parameters:

NameType
enabled
Required
boolean

getAppKeys()

static getAppKeys()

Returns an array of strings.

getRegistry()

static getRegistry()

Returns a Registry object.

getRunnable()

static getRunnable(appKey)

Returns a Runnable object.

Parameters:

NameType
appKey
Required
string

getSectionKeys()

static getSectionKeys()

Returns an array of strings.

getSections()

static getSections()

Returns a Runnables object.

registerCancellableHeadlessTask()

static registerCancellableHeadlessTask(taskKey, taskProvider, taskCancelProvider)

Register a headless task which can be cancelled. A headless task is a bit of code that runs without a UI.

Parameters:

NameTypeDescription
taskKey
Required
stringThe native id for this task instance that was used when startHeadlessTask was called.
taskProvider
Required
TaskProviderA promise returning function that takes some data passed from the native side as the only argument. When the promise is resolved or rejected the native side is notified of this event and it may decide to destroy the JS context.
taskCancelProvider
Required
TaskCancelProvidera void returning function that takes no arguments; when a cancellation is requested, the function being executed by taskProvider should wrap up and return ASAP.

registerComponent()

static registerComponent(appKey, componentProvider, section?)

Parameters:

NameType
appKey
Required
string
componentProvider
Required
ComponentProvider
sectionboolean

registerConfig()

static registerConfig(config)

Parameters:

NameType
config
Required
AppConfig

registerHeadlessTask()

static registerHeadlessTask(taskKey, taskProvider)

Register a headless task. A headless task is a bit of code that runs without a UI.

This is a way to run tasks in JavaScript while your app is in the background. It can be used, for example, to sync fresh data, handle push notifications, or play music.

Parameters:

NameTypeDescription
taskKey
Required
stringThe native id for this task instance that was used when startHeadlessTask was called.
taskProvider
Required
TaskProviderA promise returning function that takes some data passed from the native side as the only argument. When the promise is resolved or rejected the native side is notified of this event and it may decide to destroy the JS context.

registerRunnable()

static registerRunnable(appKey, run)

Parameters:

NameType
appKey
Required
string
run
Required
function

registerSection()

static registerSection(appKey, component)

Parameters:

NameType
appKey
Required
string
component
Required
ComponentProvider

runApplication()

static runApplication(appKey, appParameters)

Loads the JavaScript bundle and runs the app.

Parameters:

NameType
appKey
Required
string
appParameters
Required
any

setComponentProviderInstrumentationHook()

static setComponentProviderInstrumentationHook(hook)

Parameters:

NameType
hook
Required
function

A valid hook function accepts the following as arguments:

NameType
component
Required
ComponentProvider
scopedPerformanceLogger
Required
IPerformanceLogger

The function must also return a React Component.

setWrapperComponentProvider()

static setWrapperComponentProvider(provider)

Parameters:

NameType
provider
Required
ComponentProvider

startHeadlessTask()

static startHeadlessTask(taskId, taskKey, data)

Only called from native code. Starts a headless task.

Parameters:

NameTypeDescription
taskId
Required
numberThe native id for this task instance to keep track of its execution.
taskKey
Required
stringThe key for the task to start.
data
Required
anyThe data to pass to the task.

unmountApplicationComponentAtRootTag()

static unmountApplicationComponentAtRootTag(rootTag)

Stops an application when a view should be destroyed.

Parameters:

NameType
rootTag
Required
number

Type Definitions

AppConfig

Application configuration for the registerConfig method.

Type
object

Properties:

NameType
appKey
Required
string
componentComponentProvider
runfunction
sectionboolean

Note: Every config is expected to set either component or run function.

Registry

Type
object

Properties:

NameType
runnablesarray of Runnables
sectionsarray of strings

Runnable

Type
object

Properties:

NameType
componentComponentProvider
runfunction

Runnables

An object with key of appKey and value of type of Runnable.

Type
object

Task

A Task is a function that accepts any data as argument and returns a Promise that resolves to undefined.

Type
function

TaskCanceller

A TaskCanceller is a function that accepts no argument and returns void.

Type
function

TaskCancelProvider

A valid TaskCancelProvider is a function that returns a TaskCanceller.

Type
function

TaskProvider

A valid TaskProvider is a function that returns a Task.

Type
function
Edit this page
Last updated on
- + diff --git a/docs/next/appregistry/index.html b/docs/next/appregistry/index.html index c27cde1eae0..ff1b5b4e7a1 100644 --- a/docs/next/appregistry/index.html +++ b/docs/next/appregistry/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
AppRegistry.registerComponent('Appname', () => App);

To "stop" an application when a view should be destroyed, call AppRegistry.unmountApplicationComponentAtRootTag with the tag that was passed into runApplication. These should always be used as a pair.

AppRegistry should be required early in the require sequence to make sure the JS execution environment is setup before other modules are required.

Reference

Methods

cancelHeadlessTask()

static cancelHeadlessTask(taskId, taskKey)

Only called from native code. Cancels a headless task.

Parameters:

NameTypeDescription
taskId
Required
numberThe native id for this task instance that was used when startHeadlessTask was called.
taskKey
Required
stringThe key for the task that was used when startHeadlessTask was called.

enableArchitectureIndicator()

static enableArchitectureIndicator(enabled)

Parameters:

NameType
enabled
Required
boolean

getAppKeys()

static getAppKeys()

Returns an array of strings.

getRegistry()

static getRegistry()

Returns a Registry object.

getRunnable()

static getRunnable(appKey)

Returns a Runnable object.

Parameters:

NameType
appKey
Required
string

getSectionKeys()

static getSectionKeys()

Returns an array of strings.

getSections()

static getSections()

Returns a Runnables object.

registerCancellableHeadlessTask()

static registerCancellableHeadlessTask(taskKey, taskProvider, taskCancelProvider)

Register a headless task which can be cancelled. A headless task is a bit of code that runs without a UI.

Parameters:

NameTypeDescription
taskKey
Required
stringThe native id for this task instance that was used when startHeadlessTask was called.
taskProvider
Required
TaskProviderA promise returning function that takes some data passed from the native side as the only argument. When the promise is resolved or rejected the native side is notified of this event and it may decide to destroy the JS context.
taskCancelProvider
Required
TaskCancelProvidera void returning function that takes no arguments; when a cancellation is requested, the function being executed by taskProvider should wrap up and return ASAP.

registerComponent()

static registerComponent(appKey, componentProvider, section?)

Parameters:

NameType
appKey
Required
string
componentProvider
Required
ComponentProvider
sectionboolean

registerConfig()

static registerConfig(config)

Parameters:

NameType
config
Required
AppConfig

registerHeadlessTask()

static registerHeadlessTask(taskKey, taskProvider)

Register a headless task. A headless task is a bit of code that runs without a UI.

This is a way to run tasks in JavaScript while your app is in the background. It can be used, for example, to sync fresh data, handle push notifications, or play music.

Parameters:

NameTypeDescription
taskKey
Required
stringThe native id for this task instance that was used when startHeadlessTask was called.
taskProvider
Required
TaskProviderA promise returning function that takes some data passed from the native side as the only argument. When the promise is resolved or rejected the native side is notified of this event and it may decide to destroy the JS context.

registerRunnable()

static registerRunnable(appKey, run)

Parameters:

NameType
appKey
Required
string
run
Required
function

registerSection()

static registerSection(appKey, component)

Parameters:

NameType
appKey
Required
string
component
Required
ComponentProvider

runApplication()

static runApplication(appKey, appParameters)

Loads the JavaScript bundle and runs the app.

Parameters:

NameType
appKey
Required
string
appParameters
Required
any

setComponentProviderInstrumentationHook()

static setComponentProviderInstrumentationHook(hook)

Parameters:

NameType
hook
Required
function

A valid hook function accepts the following as arguments:

NameType
component
Required
ComponentProvider
scopedPerformanceLogger
Required
IPerformanceLogger

The function must also return a React Component.

setWrapperComponentProvider()

static setWrapperComponentProvider(provider)

Parameters:

NameType
provider
Required
ComponentProvider

startHeadlessTask()

static startHeadlessTask(taskId, taskKey, data)

Only called from native code. Starts a headless task.

Parameters:

NameTypeDescription
taskId
Required
numberThe native id for this task instance to keep track of its execution.
taskKey
Required
stringThe key for the task to start.
data
Required
anyThe data to pass to the task.

unmountApplicationComponentAtRootTag()

static unmountApplicationComponentAtRootTag(rootTag)

Stops an application when a view should be destroyed.

Parameters:

NameType
rootTag
Required
number

Type Definitions

AppConfig

Application configuration for the registerConfig method.

Type
object

Properties:

NameType
appKey
Required
string
componentComponentProvider
runfunction
sectionboolean

Note: Every config is expected to set either component or run function.

Registry

Type
object

Properties:

NameType
runnablesarray of Runnables
sectionsarray of strings

Runnable

Type
object

Properties:

NameType
componentComponentProvider
runfunction

Runnables

An object with key of appKey and value of type of Runnable.

Type
object

Task

A Task is a function that accepts any data as argument and returns a Promise that resolves to undefined.

Type
function

TaskCanceller

A TaskCanceller is a function that accepts no argument and returns void.

Type
function

TaskCancelProvider

A valid TaskCancelProvider is a function that returns a TaskCanceller.

Type
function

TaskProvider

A valid TaskProvider is a function that returns a Task.

Type
function
Edit this page
Last updated on
- + diff --git a/docs/next/appstate.html b/docs/next/appstate.html index ec47c162b20..227a174f076 100644 --- a/docs/next/appstate.html +++ b/docs/next/appstate.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

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 foreground
  • background - The app is running in the background. The user is either:
    • in another app
    • on the home screen
    • [Android] on another Activity (even if it was launched by your app)
  • [iOS] inactive - This is a state that occurs when transitioning between foreground & background, and during periods of inactivity such as entering the Multitasking view or in the event of an incoming call

For more information, see Apple's documentation

Basic Usage

To see the current state, you can check AppState.currentState, which will be kept up-to-date. However, currentState will be null at launch while AppState retrieves it over the bridge.

If you don't want to see the AppState update from active to inactive on iOS you can remove the state variable and use the appState.current value.

This example will only ever appear to say "Current state is: active" because the app is only visible to the user when in the active state, and the null state will happen only momentarily. If you want to experiment with the code we recommend to use your own device instead of embedded preview.

Reference

Events

change

This event is received when the app state has changed. The listener is called with one of the current app state values.

memoryWarning

This event is used in the need of throwing memory warning or releasing it.

focus

[Android only] Received when the app gains focus (the user is interacting with the app).

blur

[Android only] Received when the user is not actively interacting with the app. Useful in situations when the user pulls down the notification drawer. AppState won't change but the blur event will get fired.

Methods

addEventListener()

addEventListener(type, handler);

Add a handler to AppState changes by listening to the change event type and providing the handler

TODO: now that AppState is a subclass of NativeEventEmitter, we could deprecate addEventListener and removeEventListener and use addListener and listener.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()

removeEventListener(type, handler);

Remove a handler by passing the change event type and the handler

Properties

currentState

AppState.currentState;
Edit this page
Last updated on
- + diff --git a/docs/next/appstate/index.html b/docs/next/appstate/index.html index ec47c162b20..227a174f076 100644 --- a/docs/next/appstate/index.html +++ b/docs/next/appstate/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

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 foreground
  • background - The app is running in the background. The user is either:
    • in another app
    • on the home screen
    • [Android] on another Activity (even if it was launched by your app)
  • [iOS] inactive - This is a state that occurs when transitioning between foreground & background, and during periods of inactivity such as entering the Multitasking view or in the event of an incoming call

For more information, see Apple's documentation

Basic Usage

To see the current state, you can check AppState.currentState, which will be kept up-to-date. However, currentState will be null at launch while AppState retrieves it over the bridge.

If you don't want to see the AppState update from active to inactive on iOS you can remove the state variable and use the appState.current value.

This example will only ever appear to say "Current state is: active" because the app is only visible to the user when in the active state, and the null state will happen only momentarily. If you want to experiment with the code we recommend to use your own device instead of embedded preview.

Reference

Events

change

This event is received when the app state has changed. The listener is called with one of the current app state values.

memoryWarning

This event is used in the need of throwing memory warning or releasing it.

focus

[Android only] Received when the app gains focus (the user is interacting with the app).

blur

[Android only] Received when the user is not actively interacting with the app. Useful in situations when the user pulls down the notification drawer. AppState won't change but the blur event will get fired.

Methods

addEventListener()

addEventListener(type, handler);

Add a handler to AppState changes by listening to the change event type and providing the handler

TODO: now that AppState is a subclass of NativeEventEmitter, we could deprecate addEventListener and removeEventListener and use addListener and listener.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()

removeEventListener(type, handler);

Remove a handler by passing the change event type and the handler

Properties

currentState

AppState.currentState;
Edit this page
Last updated on
- + diff --git a/docs/next/asyncstorage.html b/docs/next/asyncstorage.html index 31197933ddc..2b2cb50fe04 100644 --- a/docs/next/asyncstorage.html +++ b/docs/next/asyncstorage.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@
// 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"}}
Edit this page
Last updated on
- + diff --git a/docs/next/asyncstorage/index.html b/docs/next/asyncstorage/index.html index 31197933ddc..2b2cb50fe04 100644 --- a/docs/next/asyncstorage/index.html +++ b/docs/next/asyncstorage/index.html @@ -19,7 +19,7 @@ - + @@ -41,7 +41,7 @@
// 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"}}
Edit this page
Last updated on
- + diff --git a/docs/next/backhandler.html b/docs/next/backhandler.html index cfd793ec77a..52d8c79bf26 100644 --- a/docs/next/backhandler.html +++ b/docs/next/backhandler.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
if (!this.onMainScreen()) {
this.goBack();
/**
* When true is returned the event will not be bubbled up
* & no other back action will execute
*/
return true;
}
/**
* Returning false will let the event to bubble up & let other event listeners
* or the system's default back action to be executed.
*/
return false;
});

Example

The following example implements a scenario where you confirm if the user wants to exit the app:

BackHandler.addEventListener creates an event listener & returns a NativeEventSubscription object which should be cleared using NativeEventSubscription.remove method.

Additionally BackHandler.removeEventListener can also be used to clear the event listener. Ensure the callback has the reference to the same function used in the addEventListener call as shown the following example ﹣

Usage with React Navigation

If you are using React Navigation to navigate across different screens, you can follow their guide on Custom Android back button behaviour

Backhandler hook

React Native Hooks has a nice useBackHandler hook which will simplify the process of setting up event listeners.

Reference

Methods

addEventListener()

static addEventListener(eventName, handler)

exitApp()

static exitApp()

removeEventListener()

static removeEventListener(eventName, handler)
Edit this page
Last updated on
- + diff --git a/docs/next/backhandler/index.html b/docs/next/backhandler/index.html index cfd793ec77a..52d8c79bf26 100644 --- a/docs/next/backhandler/index.html +++ b/docs/next/backhandler/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
if (!this.onMainScreen()) {
this.goBack();
/**
* When true is returned the event will not be bubbled up
* & no other back action will execute
*/
return true;
}
/**
* Returning false will let the event to bubble up & let other event listeners
* or the system's default back action to be executed.
*/
return false;
});

Example

The following example implements a scenario where you confirm if the user wants to exit the app:

BackHandler.addEventListener creates an event listener & returns a NativeEventSubscription object which should be cleared using NativeEventSubscription.remove method.

Additionally BackHandler.removeEventListener can also be used to clear the event listener. Ensure the callback has the reference to the same function used in the addEventListener call as shown the following example ﹣

Usage with React Navigation

If you are using React Navigation to navigate across different screens, you can follow their guide on Custom Android back button behaviour

Backhandler hook

React Native Hooks has a nice useBackHandler hook which will simplify the process of setting up event listeners.

Reference

Methods

addEventListener()

static addEventListener(eventName, handler)

exitApp()

static exitApp()

removeEventListener()

static removeEventListener(eventName, handler)
Edit this page
Last updated on
- + diff --git a/docs/next/building-for-tv.html b/docs/next/building-for-tv.html index 62d16b2c7dc..d1666ff48ed 100644 --- a/docs/next/building-for-tv.html +++ b/docs/next/building-for-tv.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
componentWillUnmount() {
this._disableTVEventHandler();
}
}
Edit this page
Last updated on
- + diff --git a/docs/next/building-for-tv/index.html b/docs/next/building-for-tv/index.html index 62d16b2c7dc..d1666ff48ed 100644 --- a/docs/next/building-for-tv/index.html +++ b/docs/next/building-for-tv/index.html @@ -19,7 +19,7 @@ - + @@ -38,7 +38,7 @@
componentWillUnmount() {
this._disableTVEventHandler();
}
}
Edit this page
Last updated on
- + diff --git a/docs/next/button.html b/docs/next/button.html index cb677ab769f..4d25702c3ed 100644 --- a/docs/next/button.html +++ b/docs/next/button.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

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 button using TouchableOpacity or TouchableWithoutFeedback. For inspiration, look at the source code for this button component. Or, take a look at the wide variety of button components built by the community.

<Button
onPress={onPressLearnMore}
title="Learn More"
color="#841584"
accessibilityLabel="Learn more about this purple button"
/>

Example

Reference

Props

Required
onPress

Handler to be called when the user taps the button.

Type
function(PressEvent)

Required
title

Text to display inside the button. On Android the given title will be converted to the uppercased form.

Type
string

accessibilityLabel

Text to display for blindness accessibility features.

Type
string

color

Color of the text (iOS), or background color of the button (Android).

TypeDefault
color `'#2196F3'`
Android
'#007AFF'
iOS

disabled

If true, disable all interactions for this component.

TypeDefault
boolfalse

hasTVPreferredFocus
TV

TV preferred focus.

TypeDefault
boolfalse

nextFocusDown
Android
TV

Designates the next view to receive focus when the user navigates down. See the Android documentation.

Type
number

nextFocusForward
Android
TV

Designates the next view to receive focus when the user navigates forward. See the Android documentation.

Type
number

nextFocusLeft
Android
TV

Designates the next view to receive focus when the user navigates left. See the Android documentation.

Type
number

nextFocusRight
Android
TV

Designates the next view to receive focus when the user navigates right. See the Android documentation.

Type
number

nextFocusUp
Android
TV

Designates the next view to receive focus when the user navigates up. See the Android documentation.

Type
number

testID

Used to locate this view in end-to-end tests.

Type
string

touchSoundDisabled
Android

If true, doesn't play system sound on touch.

TypeDefault
booleanfalse
Edit this page
Last updated on
- + diff --git a/docs/next/button/index.html b/docs/next/button/index.html index cb677ab769f..4d25702c3ed 100644 --- a/docs/next/button/index.html +++ b/docs/next/button/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

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 button using TouchableOpacity or TouchableWithoutFeedback. For inspiration, look at the source code for this button component. Or, take a look at the wide variety of button components built by the community.

<Button
onPress={onPressLearnMore}
title="Learn More"
color="#841584"
accessibilityLabel="Learn more about this purple button"
/>

Example

Reference

Props

Required
onPress

Handler to be called when the user taps the button.

Type
function(PressEvent)

Required
title

Text to display inside the button. On Android the given title will be converted to the uppercased form.

Type
string

accessibilityLabel

Text to display for blindness accessibility features.

Type
string

color

Color of the text (iOS), or background color of the button (Android).

TypeDefault
color `'#2196F3'`
Android
'#007AFF'
iOS

disabled

If true, disable all interactions for this component.

TypeDefault
boolfalse

hasTVPreferredFocus
TV

TV preferred focus.

TypeDefault
boolfalse

nextFocusDown
Android
TV

Designates the next view to receive focus when the user navigates down. See the Android documentation.

Type
number

nextFocusForward
Android
TV

Designates the next view to receive focus when the user navigates forward. See the Android documentation.

Type
number

nextFocusLeft
Android
TV

Designates the next view to receive focus when the user navigates left. See the Android documentation.

Type
number

nextFocusRight
Android
TV

Designates the next view to receive focus when the user navigates right. See the Android documentation.

Type
number

nextFocusUp
Android
TV

Designates the next view to receive focus when the user navigates up. See the Android documentation.

Type
number

testID

Used to locate this view in end-to-end tests.

Type
string

touchSoundDisabled
Android

If true, doesn't play system sound on touch.

TypeDefault
booleanfalse
Edit this page
Last updated on
- + diff --git a/docs/next/checkbox.html b/docs/next/checkbox.html index b8d4550e1c6..0ced35c4b8f 100644 --- a/docs/next/checkbox.html +++ b/docs/next/checkbox.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 CheckBox

Deprecated. Use one of the community packages instead.

Renders a boolean input (Android only).

This is a controlled component that requires an onValueChange callback that updates the value prop in order for the component to reflect user actions. If the value prop is not updated, the component will continue to render the supplied value prop instead of the expected result of any user actions.

Example

Reference

Props

Inherits View Props.

disabled

If true the user won't be able to toggle the checkbox. Default value is false.

TypeRequired
boolNo

onChange

Used in case the props change removes the component.

TypeRequired
functionNo

onValueChange

Invoked with the new value when the value changes.

TypeRequired
functionNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

value

The value of the checkbox. If true the checkbox will be turned on. Default value is false.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/next/checkbox/index.html b/docs/next/checkbox/index.html index b8d4550e1c6..0ced35c4b8f 100644 --- a/docs/next/checkbox/index.html +++ b/docs/next/checkbox/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 CheckBox

Deprecated. Use one of the community packages instead.

Renders a boolean input (Android only).

This is a controlled component that requires an onValueChange callback that updates the value prop in order for the component to reflect user actions. If the value prop is not updated, the component will continue to render the supplied value prop instead of the expected result of any user actions.

Example

Reference

Props

Inherits View Props.

disabled

If true the user won't be able to toggle the checkbox. Default value is false.

TypeRequired
boolNo

onChange

Used in case the props change removes the component.

TypeRequired
functionNo

onValueChange

Invoked with the new value when the value changes.

TypeRequired
functionNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

value

The value of the checkbox. If true the checkbox will be turned on. Default value is false.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/next/clipboard.html b/docs/next/clipboard.html index 6be8ac1c466..b0daab05a9a 100644 --- a/docs/next/clipboard.html +++ b/docs/next/clipboard.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 Clipboard

Deprecated. Use one of the community packages instead.

Clipboard gives you an interface for setting and getting content from Clipboard on both Android and iOS

Example

Reference

Methods

getString()

static getString()

Get content of string type, this method returns a Promise, so you can use following code to get clipboard content

async _getContent() {
var content = await Clipboard.getString();
}

setString()

static setString(content)

Set content of string type. You can use following code to set clipboard content

_setContent() {
Clipboard.setString('hello world');
}

Parameters:

NameTypeRequiredDescription
contentstringYesThe content to be stored in the clipboard

Notice

Be careful when you're trying to copy to clipboard any data except string and number, some data need additional stringification. For example, if you will try to copy array - Android will raise an exception, but iOS will not.

Edit this page
Last updated on
- + diff --git a/docs/next/clipboard/index.html b/docs/next/clipboard/index.html index 6be8ac1c466..b0daab05a9a 100644 --- a/docs/next/clipboard/index.html +++ b/docs/next/clipboard/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 Clipboard

Deprecated. Use one of the community packages instead.

Clipboard gives you an interface for setting and getting content from Clipboard on both Android and iOS

Example

Reference

Methods

getString()

static getString()

Get content of string type, this method returns a Promise, so you can use following code to get clipboard content

async _getContent() {
var content = await Clipboard.getString();
}

setString()

static setString(content)

Set content of string type. You can use following code to set clipboard content

_setContent() {
Clipboard.setString('hello world');
}

Parameters:

NameTypeRequiredDescription
contentstringYesThe content to be stored in the clipboard

Notice

Be careful when you're trying to copy to clipboard any data except string and number, some data need additional stringification. For example, if you will try to copy array - Android will raise an exception, but iOS will not.

Edit this page
Last updated on
- + diff --git a/docs/next/colors.html b/docs/next/colors.html index 4639e076f09..c22bc89efab 100644 --- a/docs/next/colors.html +++ b/docs/next/colors.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Color Reference

Components in React Native are styled using JavaScript. Color properties usually match how CSS works on the web. General guides on the color usage on each platform could be found below:

Color APIs

React Native has several color APIs designed to allow you to take full advantage of your platform's design and user preferences.

  • PlatformColor lets you reference the platform's color system.
  • DynamicColorIOS is iOS specific and allows you to specify which colors should be used in light or Dark Mode.

Color representations

Red Green Blue (RGB)

React Native supports rgb() and rgba() in both hexadecimal and functional notation:

  • '#f0f' (#rgb)
  • '#ff00ff' (#rrggbb)
  • '#f0ff' (#rgba)
  • '#ff00ff00' (#rrggbbaa)
  • 'rgb(255, 0, 255)'
  • 'rgba(255, 0, 255, 1.0)'

Hue Saturation Lightness (HSL)

React Native supports hsl() and hsla() in functional notation:

  • 'hsl(360, 100%, 100%)'
  • 'hsla(360, 100%, 100%, 1.0)'

Color ints

React Native supports also colors as an int values (in RGB color mode):

  • 0xff00ff00 (0xrrggbbaa)

Note: This might appear similar to the Android Color ints representation but on Android values are stored in SRGB color mode (0xaarrggbb).

Named colors

In React Native you can also use color name strings as values.

Note: React Native only supports lowercase color names. Uppercase color names are not supported.

transparent

This is a shortcut for rgba(0,0,0,0), same like in CSS3.

Color keywords

Named colors implementation follows the CSS3/SVG 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`)
Edit this page
Last updated on
- + diff --git a/docs/next/colors/index.html b/docs/next/colors/index.html index 4639e076f09..c22bc89efab 100644 --- a/docs/next/colors/index.html +++ b/docs/next/colors/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Color Reference

Components in React Native are styled using JavaScript. Color properties usually match how CSS works on the web. General guides on the color usage on each platform could be found below:

Color APIs

React Native has several color APIs designed to allow you to take full advantage of your platform's design and user preferences.

  • PlatformColor lets you reference the platform's color system.
  • DynamicColorIOS is iOS specific and allows you to specify which colors should be used in light or Dark Mode.

Color representations

Red Green Blue (RGB)

React Native supports rgb() and rgba() in both hexadecimal and functional notation:

  • '#f0f' (#rgb)
  • '#ff00ff' (#rrggbb)
  • '#f0ff' (#rgba)
  • '#ff00ff00' (#rrggbbaa)
  • 'rgb(255, 0, 255)'
  • 'rgba(255, 0, 255, 1.0)'

Hue Saturation Lightness (HSL)

React Native supports hsl() and hsla() in functional notation:

  • 'hsl(360, 100%, 100%)'
  • 'hsla(360, 100%, 100%, 1.0)'

Color ints

React Native supports also colors as an int values (in RGB color mode):

  • 0xff00ff00 (0xrrggbbaa)

Note: This might appear similar to the Android Color ints representation but on Android values are stored in SRGB color mode (0xaarrggbb).

Named colors

In React Native you can also use color name strings as values.

Note: React Native only supports lowercase color names. Uppercase color names are not supported.

transparent

This is a shortcut for rgba(0,0,0,0), same like in CSS3.

Color keywords

Named colors implementation follows the CSS3/SVG 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`)
Edit this page
Last updated on
- + diff --git a/docs/next/communication-android.html b/docs/next/communication-android.html index 06bf8d8b76a..f2dd1dde220 100644 --- a/docs/next/communication-android.html +++ b/docs/next/communication-android.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
mReactRootView.setAppProperties(updatedProps);

It is fine to update properties anytime. However, updates have to be performed on the main thread. You use the getter on any thread.

There is no way to update only a few properties at a time. We suggest that you build it into your own wrapper instead.

Note: Currently, JS function componentWillUpdateProps of the top level RN component will not be called after a prop update. However, you can access the new props in componentDidMount function.

Passing properties from React Native to native

The problem exposing properties of native components is covered in detail in this article. In short, properties that are to be reflected in JavaScript needs to be exposed as setter method annotated with @ReactProp, then use them in React Native as if the component was an ordinary React Native component.

Limits of properties

The main drawback of cross-language properties is that they do not support callbacks, which would allow us to handle bottom-up data bindings. Imagine you have a small RN view that you want to be removed from the native parent view as a result of a JS action. There is no way to do that with props, as the information would need to go bottom-up.

Although we have a flavor of cross-language callbacks (described here), these callbacks are not always the thing we need. The main problem is that they are not intended to be passed as properties. Rather, this mechanism allows us to trigger a native action from JS, and handle the result of that action in JS.

Other ways of cross-language interaction (events and native modules)

As stated in the previous chapter, using properties comes with some limitations. Sometimes properties are not enough to drive the logic of our app and we need a solution that gives more flexibility. This chapter covers other communication techniques available in React Native. They can be used for internal communication (between JS and native layers in RN) as well as for external communication (between RN and the 'pure native' part of your app).

React Native enables you to perform cross-language function calls. You can execute custom native code from JS and vice versa. Unfortunately, depending on the side we are working on, we achieve the same goal in different ways. For native - we use events mechanism to schedule an execution of a handler function in JS, while for React Native we directly call methods exported by native modules.

Calling React Native functions from native (events)

Events are described in detail in this article. Note that using events gives us no guarantees about execution time, as the event is handled on a separate thread.

Events are powerful, because they allow us to change React Native components without needing a reference to them. However, there are some pitfalls that you can fall into while using them:

Calling native functions from React Native (native modules)

Native modules are Java classes that are available in JS. Typically one instance of each module is created per JS bridge. They can export arbitrary functions and constants to React Native. They have been covered in detail in this article.

Warning: All native modules share the same namespace. Watch out for name collisions when creating new ones.

Edit this page
Last updated on
- + diff --git a/docs/next/communication-android/index.html b/docs/next/communication-android/index.html index 06bf8d8b76a..f2dd1dde220 100644 --- a/docs/next/communication-android/index.html +++ b/docs/next/communication-android/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
mReactRootView.setAppProperties(updatedProps);

It is fine to update properties anytime. However, updates have to be performed on the main thread. You use the getter on any thread.

There is no way to update only a few properties at a time. We suggest that you build it into your own wrapper instead.

Note: Currently, JS function componentWillUpdateProps of the top level RN component will not be called after a prop update. However, you can access the new props in componentDidMount function.

Passing properties from React Native to native

The problem exposing properties of native components is covered in detail in this article. In short, properties that are to be reflected in JavaScript needs to be exposed as setter method annotated with @ReactProp, then use them in React Native as if the component was an ordinary React Native component.

Limits of properties

The main drawback of cross-language properties is that they do not support callbacks, which would allow us to handle bottom-up data bindings. Imagine you have a small RN view that you want to be removed from the native parent view as a result of a JS action. There is no way to do that with props, as the information would need to go bottom-up.

Although we have a flavor of cross-language callbacks (described here), these callbacks are not always the thing we need. The main problem is that they are not intended to be passed as properties. Rather, this mechanism allows us to trigger a native action from JS, and handle the result of that action in JS.

Other ways of cross-language interaction (events and native modules)

As stated in the previous chapter, using properties comes with some limitations. Sometimes properties are not enough to drive the logic of our app and we need a solution that gives more flexibility. This chapter covers other communication techniques available in React Native. They can be used for internal communication (between JS and native layers in RN) as well as for external communication (between RN and the 'pure native' part of your app).

React Native enables you to perform cross-language function calls. You can execute custom native code from JS and vice versa. Unfortunately, depending on the side we are working on, we achieve the same goal in different ways. For native - we use events mechanism to schedule an execution of a handler function in JS, while for React Native we directly call methods exported by native modules.

Calling React Native functions from native (events)

Events are described in detail in this article. Note that using events gives us no guarantees about execution time, as the event is handled on a separate thread.

Events are powerful, because they allow us to change React Native components without needing a reference to them. However, there are some pitfalls that you can fall into while using them:

Calling native functions from React Native (native modules)

Native modules are Java classes that are available in JS. Typically one instance of each module is created per JS bridge. They can export arbitrary functions and constants to React Native. They have been covered in detail in this article.

Warning: All native modules share the same namespace. Watch out for name collisions when creating new ones.

Edit this page
Last updated on
- + diff --git a/docs/next/communication-ios.html b/docs/next/communication-ios.html index 6b0053968fd..1b1e7fcb511 100644 --- a/docs/next/communication-ios.html +++ b/docs/next/communication-ios.html @@ -19,7 +19,7 @@ - + @@ -44,7 +44,7 @@
rootView.frame = newFrame;
}

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 example 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 separate 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's hidden property). Then change its visibility in the delegate method.

Edit this page
Last updated on
- + diff --git a/docs/next/communication-ios/index.html b/docs/next/communication-ios/index.html index 6b0053968fd..1b1e7fcb511 100644 --- a/docs/next/communication-ios/index.html +++ b/docs/next/communication-ios/index.html @@ -19,7 +19,7 @@ - + @@ -44,7 +44,7 @@
rootView.frame = newFrame;
}

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 example 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 separate 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's hidden property). Then change its visibility in the delegate method.

Edit this page
Last updated on
- + diff --git a/docs/next/components-and-apis.html b/docs/next/components-and-apis.html index 336e1cbaeee..bebd6d96fe4 100644 --- a/docs/next/components-and-apis.html +++ b/docs/next/components-and-apis.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Core Components and APIs

React Native provides a number of built-in Core Components ready for you to use in your app. You can find them all in the left sidebar (or menu above, if you are on a narrow screen). 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 has a community of thousands of developers. If you're looking for a library that does something specific, please refer to this guide about finding libraries.

Basic Components

Most apps will end up using one of these basic components.

View

The most fundamental component for building a UI.

Text

A component for displaying text.

Image

A component for displaying images.

TextInput

A component for inputting text into the app via a keyboard.

ScrollView

Provides a scrolling container that can host multiple components and views.

StyleSheet

Provides an abstraction layer similar to CSS stylesheets.

User Interface

These common user interface controls will render on any platform.

Button

A basic button component for handling touches that should render nicely on any platform.

Switch

Renders a boolean input.

List Views

Unlike the more generic ScrollView, the following list view components only render elements that are currently showing on the screen. This makes them a performant choice for displaying long lists of data.

FlatList

A component for rendering performant scrollable lists.

SectionList

Like FlatList, but for sectioned lists.

Android Components and APIs

Many of the following components provide wrappers for commonly used Android classes.

BackHandler

Detect hardware button presses for back navigation.

DrawerLayoutAndroid

Renders a DrawerLayout on Android.

PermissionsAndroid

Provides access to the permissions model introduced in Android M.

ToastAndroid

Create an Android Toast alert.

iOS Components and APIs

Many of the following components provide wrappers for commonly used UIKit classes.

ActionSheetIOS

API to display an iOS action sheet or share sheet.

Others

These components may be useful for certain applications. For an exhaustive list of components and APIs, check out the sidebar to the left (or menu above, if you are on a narrow screen).

ActivityIndicator

Displays a circular loading indicator.

Alert

Launches an alert dialog with the specified title and message.

Animated

A library for creating fluid, powerful animations that are easy to build and maintain.

Dimensions

Provides an interface for getting device dimensions.

KeyboardAvoidingView

Provides a view that moves out of the way of the virtual keyboard automatically.

Linking

Provides a general interface to interact with both incoming and outgoing app links.

Modal

Provides a simple way to present content above an enclosing view.

PixelRatio

Provides access to the device pixel density.

RefreshControl

This component is used inside a ScrollView to add pull to refresh functionality.

StatusBar

Component to control the app status bar.

Edit this page
Last updated on
- + diff --git a/docs/next/components-and-apis/index.html b/docs/next/components-and-apis/index.html index 336e1cbaeee..bebd6d96fe4 100644 --- a/docs/next/components-and-apis/index.html +++ b/docs/next/components-and-apis/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Core Components and APIs

React Native provides a number of built-in Core Components ready for you to use in your app. You can find them all in the left sidebar (or menu above, if you are on a narrow screen). 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 has a community of thousands of developers. If you're looking for a library that does something specific, please refer to this guide about finding libraries.

Basic Components

Most apps will end up using one of these basic components.

View

The most fundamental component for building a UI.

Text

A component for displaying text.

Image

A component for displaying images.

TextInput

A component for inputting text into the app via a keyboard.

ScrollView

Provides a scrolling container that can host multiple components and views.

StyleSheet

Provides an abstraction layer similar to CSS stylesheets.

User Interface

These common user interface controls will render on any platform.

Button

A basic button component for handling touches that should render nicely on any platform.

Switch

Renders a boolean input.

List Views

Unlike the more generic ScrollView, the following list view components only render elements that are currently showing on the screen. This makes them a performant choice for displaying long lists of data.

FlatList

A component for rendering performant scrollable lists.

SectionList

Like FlatList, but for sectioned lists.

Android Components and APIs

Many of the following components provide wrappers for commonly used Android classes.

BackHandler

Detect hardware button presses for back navigation.

DrawerLayoutAndroid

Renders a DrawerLayout on Android.

PermissionsAndroid

Provides access to the permissions model introduced in Android M.

ToastAndroid

Create an Android Toast alert.

iOS Components and APIs

Many of the following components provide wrappers for commonly used UIKit classes.

ActionSheetIOS

API to display an iOS action sheet or share sheet.

Others

These components may be useful for certain applications. For an exhaustive list of components and APIs, check out the sidebar to the left (or menu above, if you are on a narrow screen).

ActivityIndicator

Displays a circular loading indicator.

Alert

Launches an alert dialog with the specified title and message.

Animated

A library for creating fluid, powerful animations that are easy to build and maintain.

Dimensions

Provides an interface for getting device dimensions.

KeyboardAvoidingView

Provides a view that moves out of the way of the virtual keyboard automatically.

Linking

Provides a general interface to interact with both incoming and outgoing app links.

Modal

Provides a simple way to present content above an enclosing view.

PixelRatio

Provides access to the device pixel density.

RefreshControl

This component is used inside a ScrollView to add pull to refresh functionality.

StatusBar

Component to control the app status bar.

Edit this page
Last updated on
- + diff --git a/docs/next/custom-webview-android.html b/docs/next/custom-webview-android.html index 01808a61fbb..423c742ca2a 100644 --- a/docs/next/custom-webview-android.html +++ b/docs/next/custom-webview-android.html @@ -19,7 +19,7 @@ - + @@ -60,7 +60,7 @@
render() {
return (
<WebView
{...this.props}
nativeConfig={{
component: RCTCustomWebView,
props: {
finalUrl: this.props.finalUrl,
onNavigationCompleted: this._onNavigationCompleted
}
}}
/>
);
}
}

Similar to regular native components, you must provide all your prop types in the component to have them forwarded on to the native component. However, if you have some prop types that are only used internally in component, you can add them to the nativeOnly property of the third argument previously mentioned. For event handlers, you have to use the value true instead of a regular prop type.

For example, if you wanted to add an internal event handler called onScrollToBottom, you would use,

const RCTCustomWebView = requireNativeComponent(
'RCTCustomWebView',
CustomWebView,
{
...WebView.extraNativeComponentConfig,
nativeOnly: {
...WebView.extraNativeComponentConfig.nativeOnly,
onScrollToBottom: true
}
}
);
Edit this page
Last updated on
- + diff --git a/docs/next/custom-webview-android/index.html b/docs/next/custom-webview-android/index.html index 01808a61fbb..423c742ca2a 100644 --- a/docs/next/custom-webview-android/index.html +++ b/docs/next/custom-webview-android/index.html @@ -19,7 +19,7 @@ - + @@ -60,7 +60,7 @@
render() {
return (
<WebView
{...this.props}
nativeConfig={{
component: RCTCustomWebView,
props: {
finalUrl: this.props.finalUrl,
onNavigationCompleted: this._onNavigationCompleted
}
}}
/>
);
}
}

Similar to regular native components, you must provide all your prop types in the component to have them forwarded on to the native component. However, if you have some prop types that are only used internally in component, you can add them to the nativeOnly property of the third argument previously mentioned. For event handlers, you have to use the value true instead of a regular prop type.

For example, if you wanted to add an internal event handler called onScrollToBottom, you would use,

const RCTCustomWebView = requireNativeComponent(
'RCTCustomWebView',
CustomWebView,
{
...WebView.extraNativeComponentConfig,
nativeOnly: {
...WebView.extraNativeComponentConfig.nativeOnly,
onScrollToBottom: true
}
}
);
Edit this page
Last updated on
- + diff --git a/docs/next/custom-webview-ios.html b/docs/next/custom-webview-ios.html index ccc575f0a38..96856d0631a 100644 --- a/docs/next/custom-webview-ios.html +++ b/docs/next/custom-webview-ios.html @@ -19,7 +19,7 @@ - + @@ -63,7 +63,7 @@
render() {
return (
<WebView
{...this.props}
nativeConfig={{
component: RCTCustomWebView,
props: {
finalUrl: this.props.finalUrl,
onNavigationCompleted: this._onNavigationCompleted
},
viewManager: CustomWebViewManager
}}
/>
);
}
}

Similar to regular native components, you must provide all your prop types in the component to have them forwarded on to the native component. However, if you have some prop types that are only used internally in component, you can add them to the nativeOnly property of the third argument previously mentioned. For event handlers, you have to use the value true instead of a regular prop type.

For example, if you wanted to add an internal event handler called onScrollToBottom, you would use,

const RCTCustomWebView = requireNativeComponent(
'RCTCustomWebView',
CustomWebView,
{
...WebView.extraNativeComponentConfig,
nativeOnly: {
...WebView.extraNativeComponentConfig.nativeOnly,
onScrollToBottom: true
}
}
);
Edit this page
Last updated on
- + diff --git a/docs/next/custom-webview-ios/index.html b/docs/next/custom-webview-ios/index.html index ccc575f0a38..96856d0631a 100644 --- a/docs/next/custom-webview-ios/index.html +++ b/docs/next/custom-webview-ios/index.html @@ -19,7 +19,7 @@ - + @@ -63,7 +63,7 @@
render() {
return (
<WebView
{...this.props}
nativeConfig={{
component: RCTCustomWebView,
props: {
finalUrl: this.props.finalUrl,
onNavigationCompleted: this._onNavigationCompleted
},
viewManager: CustomWebViewManager
}}
/>
);
}
}

Similar to regular native components, you must provide all your prop types in the component to have them forwarded on to the native component. However, if you have some prop types that are only used internally in component, you can add them to the nativeOnly property of the third argument previously mentioned. For event handlers, you have to use the value true instead of a regular prop type.

For example, if you wanted to add an internal event handler called onScrollToBottom, you would use,

const RCTCustomWebView = requireNativeComponent(
'RCTCustomWebView',
CustomWebView,
{
...WebView.extraNativeComponentConfig,
nativeOnly: {
...WebView.extraNativeComponentConfig.nativeOnly,
onScrollToBottom: true
}
}
);
Edit this page
Last updated on
- + diff --git a/docs/next/datepickerandroid.html b/docs/next/datepickerandroid.html index 904e33416c1..6c76f4c1a41 100644 --- a/docs/next/datepickerandroid.html +++ b/docs/next/datepickerandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 DatePickerAndroid

Deprecated. Use one of the community packages instead.

Opens the standard Android date picker dialog.

Example

try {
const {
action,
year,
month,
day
} = await DatePickerAndroid.open({
// Use `new Date()` for current date.
// May 25 2020. Month 0 is January.
date: new Date(2020, 4, 25)
});
if (action !== DatePickerAndroid.dismissedAction) {
// Selected year, month (0-11), day
}
} catch ({ code, message }) {
console.warn('Cannot open date picker', message);
}

Reference

Methods

open()

static open(options)

Opens the standard Android date picker dialog.

The available keys for the options object are:

  • date (Date object or timestamp in milliseconds) - date to show by default
  • minDate (Date or timestamp in milliseconds) - minimum date that can be selected
  • maxDate (Date object or timestamp in milliseconds) - maximum date that can be selected
  • mode (enum('calendar', 'spinner', 'default')) - To set the date-picker mode to calendar/spinner/default
    • 'calendar': Show a date picker in calendar mode.
    • 'spinner': Show a date picker in spinner mode.
    • 'default': Show a default native date picker(spinner/calendar) based on android versions.

Returns a Promise which will be invoked an object containing action, year, month (0-11), 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 is equal to DatePickerAndroid.dateSetAction 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.

dateSetAction()

static dateSetAction()

A date has been selected.

dismissedAction()

static dismissedAction()

The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/next/datepickerandroid/index.html b/docs/next/datepickerandroid/index.html index 904e33416c1..6c76f4c1a41 100644 --- a/docs/next/datepickerandroid/index.html +++ b/docs/next/datepickerandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 DatePickerAndroid

Deprecated. Use one of the community packages instead.

Opens the standard Android date picker dialog.

Example

try {
const {
action,
year,
month,
day
} = await DatePickerAndroid.open({
// Use `new Date()` for current date.
// May 25 2020. Month 0 is January.
date: new Date(2020, 4, 25)
});
if (action !== DatePickerAndroid.dismissedAction) {
// Selected year, month (0-11), day
}
} catch ({ code, message }) {
console.warn('Cannot open date picker', message);
}

Reference

Methods

open()

static open(options)

Opens the standard Android date picker dialog.

The available keys for the options object are:

  • date (Date object or timestamp in milliseconds) - date to show by default
  • minDate (Date or timestamp in milliseconds) - minimum date that can be selected
  • maxDate (Date object or timestamp in milliseconds) - maximum date that can be selected
  • mode (enum('calendar', 'spinner', 'default')) - To set the date-picker mode to calendar/spinner/default
    • 'calendar': Show a date picker in calendar mode.
    • 'spinner': Show a date picker in spinner mode.
    • 'default': Show a default native date picker(spinner/calendar) based on android versions.

Returns a Promise which will be invoked an object containing action, year, month (0-11), 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 is equal to DatePickerAndroid.dateSetAction 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.

dateSetAction()

static dateSetAction()

A date has been selected.

dismissedAction()

static dismissedAction()

The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/next/datepickerios.html b/docs/next/datepickerios.html index 71476722e0f..a5611deb9d9 100644 --- a/docs/next/datepickerios.html +++ b/docs/next/datepickerios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 DatePickerIOS

Deprecated. Use one of the community packages instead.

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 source of truth.

Example

Reference

Props

Inherits View Props.

date

The currently selected date.

TypeRequired
DateYes

onChange

Date change handler.

This is called when the user changes the date or time in the UI. The first and only argument is an Event. For getting the date the picker was changed to, use onDateChange instead.

TypeRequired
functionNo

onDateChange

Date change handler.

This is called when the user changes the date or time in the UI. The first and only argument is a Date object representing the new date and time.

TypeRequired
functionYes

maximumDate

Maximum date.

Restricts the range of possible date/time values.

TypeRequired
DateNo

Example with maximumDate set to December 31, 2017:

minimumDate

Minimum date.

Restricts the range of possible date/time values.

TypeRequired
DateNo

See maximumDate for an example image.

minuteInterval

The interval at which minutes can be selected.

TypeRequired
enum(1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30)No

Example with minuteInterval set to 10:

mode

The date picker mode.

TypeRequired
enum('date', 'time', 'datetime', 'countdown')No

Example with mode set to date, time, and datetime:

locale

The locale for the date picker. Value needs to be a Locale ID.

TypeRequired
StringNo

timeZoneOffsetInMinutes

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.

TypeRequired
numberNo

initialDate

Provides an initial value that will change when the user starts selecting a date. It is useful for use-cases where you do not want to deal with listening to events and updating the date prop to keep the controlled state in sync. The controlled state has known bugs which causes it to go out of sync with native. The initialDate prop is intended to allow you to have native be source of truth.

TypeRequired
DateNo
Edit this page
Last updated on
- + diff --git a/docs/next/datepickerios/index.html b/docs/next/datepickerios/index.html index 71476722e0f..a5611deb9d9 100644 --- a/docs/next/datepickerios/index.html +++ b/docs/next/datepickerios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 DatePickerIOS

Deprecated. Use one of the community packages instead.

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 source of truth.

Example

Reference

Props

Inherits View Props.

date

The currently selected date.

TypeRequired
DateYes

onChange

Date change handler.

This is called when the user changes the date or time in the UI. The first and only argument is an Event. For getting the date the picker was changed to, use onDateChange instead.

TypeRequired
functionNo

onDateChange

Date change handler.

This is called when the user changes the date or time in the UI. The first and only argument is a Date object representing the new date and time.

TypeRequired
functionYes

maximumDate

Maximum date.

Restricts the range of possible date/time values.

TypeRequired
DateNo

Example with maximumDate set to December 31, 2017:

minimumDate

Minimum date.

Restricts the range of possible date/time values.

TypeRequired
DateNo

See maximumDate for an example image.

minuteInterval

The interval at which minutes can be selected.

TypeRequired
enum(1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30)No

Example with minuteInterval set to 10:

mode

The date picker mode.

TypeRequired
enum('date', 'time', 'datetime', 'countdown')No

Example with mode set to date, time, and datetime:

locale

The locale for the date picker. Value needs to be a Locale ID.

TypeRequired
StringNo

timeZoneOffsetInMinutes

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.

TypeRequired
numberNo

initialDate

Provides an initial value that will change when the user starts selecting a date. It is useful for use-cases where you do not want to deal with listening to events and updating the date prop to keep the controlled state in sync. The controlled state has known bugs which causes it to go out of sync with native. The initialDate prop is intended to allow you to have native be source of truth.

TypeRequired
DateNo
Edit this page
Last updated on
- + diff --git a/docs/next/debugging.html b/docs/next/debugging.html index 8f55d28957e..bf1b6de8748 100644 --- a/docs/next/debugging.html +++ b/docs/next/debugging.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
// Ignore all log notifications:
LogBox.ignoreAllLogs();

Unhandled Errors

Unhandled JavaScript errors such as undefined is not a function will automatically open a full screen LogBox error with the source of the error. These errors are dismissable and minimizable so that you can see the state of your app when these errors occur, but should always be addressed.

Syntax Errors

When syntax error occurs the full screen LogBox error will automatically open with the stack trace and location of the syntax error. This error is not dismissable because it represents invalid JavaScript execution that must be fixed before continuing with your app. To dismiss these errors, fix the syntax error and either save to automatically dismiss (with Fast Refresh enabled) or cmd+r to reload (with Fast Refresh disabled).

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: on Android, if the times between the debugger and device have drifted; things such as animation, event behavior, etc., might not work properly or the results may not be accurate. Please correct this by running adb shell "date `date +%m%d%H%M%Y.%S%3N`" on your debugger machine. Root access is required for the use in real device.

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.

Safari Developer Tools

You can use Safari to debug the iOS version of your app without having to enable "Debug JS Remotely".

While sourcemaps may not be enabled by default, you can follow this guide or video to enable them and set break points at the right places in the source code.

However, every time the app is reloaded (using live reload, or by manually reloading), a new JSContext is created. Choosing "Automatically Show Web Inspectors for JSContexts" saves you from having to select the latest JSContext manually.

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:

Note: Version 4 of react-devtools requires react-native version 0.62 or higher to work properly.

npm install -g react-devtools

Now run react-devtools from the terminal to launch the standalone DevTools app:

react-devtools

React DevTools

It should connect to your simulator within a few seconds.

Note: if you prefer to avoid global installations, you can add react-devtools as a project dependency. Add the react-devtools package to your project using npm install --save-dev react-devtools, then add "react-devtools": "react-devtools" to the scripts section in your package.json, and then run npm run react-devtools from your project folder to open the DevTools.

Integration with React Native Inspector

Open the in-app developer menu and choose "Toggle Inspector". It will bring up an overlay that lets you tap on any UI element and see information about it:

React Native Inspector

However, when react-devtools is running, Inspector will enter a 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:

React DevTools Inspector Integration

You can choose "Toggle 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.

React DevTools Chrome Console Integration

Performance Monitor

You can enable a performance overlay to help you debug performance problems by selecting "Perf Monitor" in the Developer Menu.

Debugging Application State

Reactotron is an open-source desktop app that allows you to inspect Redux or MobX-State-Tree application state as well as view custom logs, run custom commands such as resetting state, store and restore state snapshots, and other helpful debugging features for React Native apps.

You can view installation instructions in the README. If you're using Expo, here is an article detailing how to install on Expo.

Native Debugging

Accessing console logs

You can display the console logs for an iOS or Android app by using the following commands in a terminal while the app is running:

npx react-native log-ios
npx react-native log-android

You may also access these through Debug → Open System Log... in the iOS Simulator or by running adb logcat *:S ReactNative:V ReactNativeJS:V in a terminal while an Android app is running on a device or emulator.

If you're using Create React Native App or Expo CLI, console logs already appear in the same terminal output as the bundler.

Debugging on a device with Chrome Developer Tools

If you're using Create React Native App or Expo CLI, this is configured for you already.

On iOS devices, open the file RCTWebSocketExecutor.m and change "localhost" to the IP address of your computer, then select "Debug JS Remotely" from the Developer Menu.

On Android 5.0+ devices connected via USB, you can use the adb command line tool to setup port forwarding from the device to your computer:

adb reverse tcp:8081 tcp:8081

Alternatively, select "Dev Settings" from the Developer Menu, then update the "Debug server host for device" setting to match the IP address of your computer.

If you run into any issues, it may be possible that one of your Chrome extensions is interacting in unexpected ways with the debugger. Try disabling all of your extensions and re-enabling them one-by-one until you find the problematic extension.

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.

Edit this page
Last updated on
- + diff --git a/docs/next/debugging/index.html b/docs/next/debugging/index.html index 8f55d28957e..bf1b6de8748 100644 --- a/docs/next/debugging/index.html +++ b/docs/next/debugging/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
// Ignore all log notifications:
LogBox.ignoreAllLogs();

Unhandled Errors

Unhandled JavaScript errors such as undefined is not a function will automatically open a full screen LogBox error with the source of the error. These errors are dismissable and minimizable so that you can see the state of your app when these errors occur, but should always be addressed.

Syntax Errors

When syntax error occurs the full screen LogBox error will automatically open with the stack trace and location of the syntax error. This error is not dismissable because it represents invalid JavaScript execution that must be fixed before continuing with your app. To dismiss these errors, fix the syntax error and either save to automatically dismiss (with Fast Refresh enabled) or cmd+r to reload (with Fast Refresh disabled).

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: on Android, if the times between the debugger and device have drifted; things such as animation, event behavior, etc., might not work properly or the results may not be accurate. Please correct this by running adb shell "date `date +%m%d%H%M%Y.%S%3N`" on your debugger machine. Root access is required for the use in real device.

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.

Safari Developer Tools

You can use Safari to debug the iOS version of your app without having to enable "Debug JS Remotely".

While sourcemaps may not be enabled by default, you can follow this guide or video to enable them and set break points at the right places in the source code.

However, every time the app is reloaded (using live reload, or by manually reloading), a new JSContext is created. Choosing "Automatically Show Web Inspectors for JSContexts" saves you from having to select the latest JSContext manually.

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:

Note: Version 4 of react-devtools requires react-native version 0.62 or higher to work properly.

npm install -g react-devtools

Now run react-devtools from the terminal to launch the standalone DevTools app:

react-devtools

React DevTools

It should connect to your simulator within a few seconds.

Note: if you prefer to avoid global installations, you can add react-devtools as a project dependency. Add the react-devtools package to your project using npm install --save-dev react-devtools, then add "react-devtools": "react-devtools" to the scripts section in your package.json, and then run npm run react-devtools from your project folder to open the DevTools.

Integration with React Native Inspector

Open the in-app developer menu and choose "Toggle Inspector". It will bring up an overlay that lets you tap on any UI element and see information about it:

React Native Inspector

However, when react-devtools is running, Inspector will enter a 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:

React DevTools Inspector Integration

You can choose "Toggle 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.

React DevTools Chrome Console Integration

Performance Monitor

You can enable a performance overlay to help you debug performance problems by selecting "Perf Monitor" in the Developer Menu.

Debugging Application State

Reactotron is an open-source desktop app that allows you to inspect Redux or MobX-State-Tree application state as well as view custom logs, run custom commands such as resetting state, store and restore state snapshots, and other helpful debugging features for React Native apps.

You can view installation instructions in the README. If you're using Expo, here is an article detailing how to install on Expo.

Native Debugging

Accessing console logs

You can display the console logs for an iOS or Android app by using the following commands in a terminal while the app is running:

npx react-native log-ios
npx react-native log-android

You may also access these through Debug → Open System Log... in the iOS Simulator or by running adb logcat *:S ReactNative:V ReactNativeJS:V in a terminal while an Android app is running on a device or emulator.

If you're using Create React Native App or Expo CLI, console logs already appear in the same terminal output as the bundler.

Debugging on a device with Chrome Developer Tools

If you're using Create React Native App or Expo CLI, this is configured for you already.

On iOS devices, open the file RCTWebSocketExecutor.m and change "localhost" to the IP address of your computer, then select "Debug JS Remotely" from the Developer Menu.

On Android 5.0+ devices connected via USB, you can use the adb command line tool to setup port forwarding from the device to your computer:

adb reverse tcp:8081 tcp:8081

Alternatively, select "Dev Settings" from the Developer Menu, then update the "Debug server host for device" setting to match the IP address of your computer.

If you run into any issues, it may be possible that one of your Chrome extensions is interacting in unexpected ways with the debugger. Try disabling all of your extensions and re-enabling them one-by-one until you find the problematic extension.

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.

Edit this page
Last updated on
- + diff --git a/docs/next/devsettings.html b/docs/next/devsettings.html index 0ce65056464..c73449b8940 100644 --- a/docs/next/devsettings.html +++ b/docs/next/devsettings.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

DevSettings

The DevSettings module exposes methods for customizing settings for developers in development.

Reference

Methods

addMenuItem()

static addMenuItem(title, handler)

Add a custom menu item to the developer menu.

Parameters:

NameType
title
Required
string
component
Required
function

Example:

DevSettings.addMenuItem('Show Secret Dev Screen', () => {
Alert.alert('Showing secret dev screen!');
});

reload()

static reload()

Reload the application. Can be invoked directly or on user interaction.

Example:

<Button title="Reload" onPress={() => DevSettings.reload()} />
Edit this page
Last updated on
- + diff --git a/docs/next/devsettings/index.html b/docs/next/devsettings/index.html index 0ce65056464..c73449b8940 100644 --- a/docs/next/devsettings/index.html +++ b/docs/next/devsettings/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

DevSettings

The DevSettings module exposes methods for customizing settings for developers in development.

Reference

Methods

addMenuItem()

static addMenuItem(title, handler)

Add a custom menu item to the developer menu.

Parameters:

NameType
title
Required
string
component
Required
function

Example:

DevSettings.addMenuItem('Show Secret Dev Screen', () => {
Alert.alert('Showing secret dev screen!');
});

reload()

static reload()

Reload the application. Can be invoked directly or on user interaction.

Example:

<Button title="Reload" onPress={() => DevSettings.reload()} />
Edit this page
Last updated on
- + diff --git a/docs/next/dimensions.html b/docs/next/dimensions.html index 99698d17d3f..5303426ace3 100644 --- a/docs/next/dimensions.html +++ b/docs/next/dimensions.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Dimensions

useWindowDimensions is the preferred API for React components. Unlike Dimensions, it updates as the window's dimensions update. This works nicely with the React paradigm.

import { Dimensions } from 'react-native';

You can get the application window's width and height using the following code:

const windowWidth = Dimensions.get('window').width;
const windowHeight = Dimensions.get('window').height;

Although dimensions are available immediately, they may change (e.g due to device rotation, foldable devices etc) so any rendering logic or styles that depend on these constants should try to call this function on every render, rather than caching the value (for example, using inline styles rather than setting a value in a StyleSheet).

If you are targeting foldable devices or devices which can change the screen size or app window size, you can use the event listener available in the Dimensions module as shown in the below example.

Example

Reference

Methods

addEventListener()

static addEventListener(type, handler)

Add an event handler. Supported events:

  • change: Fires when a property within the Dimensions object changes. The argument to the event handler is an object with window and screen properties whose values are the same as the return values of Dimensions.get('window') and Dimensions.get('screen'), respectively.
    • window - Size of the visible Application window
    • screen - Size of the device's screen

get()

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.

Example: const {height, width} = Dimensions.get('window');

Parameters:

NameTypeRequiredDescription
dimstringYesName of dimension as defined when calling set. @returns {Object?} Value for the dimension.

For Android the window dimension will exclude the size used by the status bar (if not translucent) and bottom navigation bar

removeEventListener()

static removeEventListener(type, handler)

Remove an event handler.

set()

static set(dims)

This should only be called from native code by sending the didUpdateDimensions event.

Parameters:

NameTypeRequiredDescription
dimsobjectYesstring-keyed object of dimensions to set
Edit this page
Last updated on
- + diff --git a/docs/next/dimensions/index.html b/docs/next/dimensions/index.html index 99698d17d3f..5303426ace3 100644 --- a/docs/next/dimensions/index.html +++ b/docs/next/dimensions/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Dimensions

useWindowDimensions is the preferred API for React components. Unlike Dimensions, it updates as the window's dimensions update. This works nicely with the React paradigm.

import { Dimensions } from 'react-native';

You can get the application window's width and height using the following code:

const windowWidth = Dimensions.get('window').width;
const windowHeight = Dimensions.get('window').height;

Although dimensions are available immediately, they may change (e.g due to device rotation, foldable devices etc) so any rendering logic or styles that depend on these constants should try to call this function on every render, rather than caching the value (for example, using inline styles rather than setting a value in a StyleSheet).

If you are targeting foldable devices or devices which can change the screen size or app window size, you can use the event listener available in the Dimensions module as shown in the below example.

Example

Reference

Methods

addEventListener()

static addEventListener(type, handler)

Add an event handler. Supported events:

  • change: Fires when a property within the Dimensions object changes. The argument to the event handler is an object with window and screen properties whose values are the same as the return values of Dimensions.get('window') and Dimensions.get('screen'), respectively.
    • window - Size of the visible Application window
    • screen - Size of the device's screen

get()

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.

Example: const {height, width} = Dimensions.get('window');

Parameters:

NameTypeRequiredDescription
dimstringYesName of dimension as defined when calling set. @returns {Object?} Value for the dimension.

For Android the window dimension will exclude the size used by the status bar (if not translucent) and bottom navigation bar

removeEventListener()

static removeEventListener(type, handler)

Remove an event handler.

set()

static set(dims)

This should only be called from native code by sending the didUpdateDimensions event.

Parameters:

NameTypeRequiredDescription
dimsobjectYesstring-keyed object of dimensions to set
Edit this page
Last updated on
- + diff --git a/docs/next/direct-manipulation.html b/docs/next/direct-manipulation.html index 48f24ce01a0..b39c40c6c49 100644 --- a/docs/next/direct-manipulation.html +++ b/docs/next/direct-manipulation.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

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 apps. setNativeProps is the React Native equivalent to setting properties directly on a DOM node.

Use setNativeProps when frequent re-rendering creates a performance bottleneck

Direct manipulation will not be a tool that you reach for frequently; you will typically only be using it for creating continuous animations to avoid the overhead of rendering the component hierarchy and reconciling many views. setNativeProps is imperative and stores state in the native layer (DOM, UIView, etc.) and not within your React components, which makes your code more difficult to reason about. Before you use it, try to solve your problem with setState and shouldComponentUpdate.

setNativeProps with TouchableOpacity

TouchableOpacity uses setNativeProps internally to update the opacity of its child component:

const viewRef = useRef();
const setOpacityTo = useCallback((value) => {
// Redacted: animation related code
viewRef.current.setNativeProps({
opacity: value
});
}, []);

This allows us to write the following code and know that the child will have its opacity updated in response to taps, without the child having any knowledge of that fact or requiring any changes to its implementation:

<TouchableOpacity onPress={handlePress}>
<View>
<Text>Press me!</Text>
</View>
</TouchableOpacity>

Let's imagine that setNativeProps was not available. One way that we might implement it with that constraint is to store the opacity value in the state, then update that value whenever onPress is fired:

const [buttonOpacity, setButtonOpacity] = useState(1);
return (
<TouchableOpacity
onPressIn={() => setButtonOpacity(0.5)}
onPressOut={() => setButtonOpacity(1)}>
<View style={{ opacity: buttonOpacity }}>
<Text>Press me!</Text>
</View>
</TouchableOpacity>
);

This is computationally intensive compared to the original example - React needs to re-render the component hierarchy each time the opacity changes, even though other properties of the view and its children haven't changed. Usually this overhead isn't a concern but when performing continuous animations and responding to gestures, judiciously optimizing your components can improve your animations' fidelity.

If you look at the implementation of setNativeProps in NativeMethodsMixin you will notice that it is a wrapper around RCTUIManager.updateView - this is the exact same function call that results from re-rendering - see receiveComponent in ReactNativeBaseComponent.

Composite components and setNativeProps

Composite components are not backed by a native view, so you cannot call setNativeProps on them. Consider this example:

If you run this you will immediately see this error: Touchable child must either be native or forward setNativeProps to a native component. This occurs because MyButton isn't directly backed by a native view whose opacity should be set. You can think about it like this: if you define a component with createReactClass you would not expect to be able to set a style prop on it and have that work - you would need to pass the style prop down to a child, unless you are wrapping a native component. Similarly, we are going to forward setNativeProps to a native-backed child component.

Forward setNativeProps to a child

Since the setNativeProps method exists on any ref to a View component, it is enough to forward a ref on your custom component to one of the <View /> components that it renders. This means that a call to setNativeProps on the custom component will have the same effect as if you called setNativeProps on the wrapped View component itself.

You can now use MyButton inside of TouchableOpacity!

You may have noticed that we passed all of the props down to the child view using {...props}. The reason for this is that TouchableOpacity is actually a composite component, and so in addition to depending on setNativeProps on its child, it also requires that the child perform touch handling. To do this, it passes on various props that call back to the TouchableOpacity component. TouchableHighlight, in contrast, is backed by a native view and only requires that we implement setNativeProps.

setNativeProps to clear TextInput value

Another very common use case of setNativeProps is to clear the value of a TextInput. The controlled prop of TextInput can sometimes drop characters when the bufferDelay is low and the user types very quickly. Some developers prefer to skip this prop entirely and instead use setNativeProps to directly manipulate the TextInput value when necessary. For example, the following code demonstrates clearing the input when you tap a button:

Avoiding conflicts with the render function

If you update a property that is also managed by the render function, you might end up with some unpredictable and confusing bugs because anytime the component re-renders and that property changes, whatever value was previously set from setNativeProps will be completely ignored and overridden.

setNativeProps & shouldComponentUpdate

By intelligently applying shouldComponentUpdate you can avoid the unnecessary overhead involved in reconciling unchanged component subtrees, to the point where it may be performant enough to use setState instead of setNativeProps.

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 in the viewport 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 and you don't need pageX and pageY, consider using the onLayout property instead.

Also the width and height returned by measure() are the width and height of the component in the viewport. If you need the actual size of the component, consider using the onLayout property 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(relativeToNativeComponentRef, onSuccess, onFail)

Like measure(), but measures the view relative to an ancestor, specified with relativeToNativeComponentRef reference. This means that the returned coordinates are relative to the origin x, y of the ancestor view.

Note: This method can also be called with a relativeToNativeNode handler (instead of reference), but this variant is deprecated.

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().

Edit this page
Last updated on
- + diff --git a/docs/next/direct-manipulation/index.html b/docs/next/direct-manipulation/index.html index 48f24ce01a0..b39c40c6c49 100644 --- a/docs/next/direct-manipulation/index.html +++ b/docs/next/direct-manipulation/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

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 apps. setNativeProps is the React Native equivalent to setting properties directly on a DOM node.

Use setNativeProps when frequent re-rendering creates a performance bottleneck

Direct manipulation will not be a tool that you reach for frequently; you will typically only be using it for creating continuous animations to avoid the overhead of rendering the component hierarchy and reconciling many views. setNativeProps is imperative and stores state in the native layer (DOM, UIView, etc.) and not within your React components, which makes your code more difficult to reason about. Before you use it, try to solve your problem with setState and shouldComponentUpdate.

setNativeProps with TouchableOpacity

TouchableOpacity uses setNativeProps internally to update the opacity of its child component:

const viewRef = useRef();
const setOpacityTo = useCallback((value) => {
// Redacted: animation related code
viewRef.current.setNativeProps({
opacity: value
});
}, []);

This allows us to write the following code and know that the child will have its opacity updated in response to taps, without the child having any knowledge of that fact or requiring any changes to its implementation:

<TouchableOpacity onPress={handlePress}>
<View>
<Text>Press me!</Text>
</View>
</TouchableOpacity>

Let's imagine that setNativeProps was not available. One way that we might implement it with that constraint is to store the opacity value in the state, then update that value whenever onPress is fired:

const [buttonOpacity, setButtonOpacity] = useState(1);
return (
<TouchableOpacity
onPressIn={() => setButtonOpacity(0.5)}
onPressOut={() => setButtonOpacity(1)}>
<View style={{ opacity: buttonOpacity }}>
<Text>Press me!</Text>
</View>
</TouchableOpacity>
);

This is computationally intensive compared to the original example - React needs to re-render the component hierarchy each time the opacity changes, even though other properties of the view and its children haven't changed. Usually this overhead isn't a concern but when performing continuous animations and responding to gestures, judiciously optimizing your components can improve your animations' fidelity.

If you look at the implementation of setNativeProps in NativeMethodsMixin you will notice that it is a wrapper around RCTUIManager.updateView - this is the exact same function call that results from re-rendering - see receiveComponent in ReactNativeBaseComponent.

Composite components and setNativeProps

Composite components are not backed by a native view, so you cannot call setNativeProps on them. Consider this example:

If you run this you will immediately see this error: Touchable child must either be native or forward setNativeProps to a native component. This occurs because MyButton isn't directly backed by a native view whose opacity should be set. You can think about it like this: if you define a component with createReactClass you would not expect to be able to set a style prop on it and have that work - you would need to pass the style prop down to a child, unless you are wrapping a native component. Similarly, we are going to forward setNativeProps to a native-backed child component.

Forward setNativeProps to a child

Since the setNativeProps method exists on any ref to a View component, it is enough to forward a ref on your custom component to one of the <View /> components that it renders. This means that a call to setNativeProps on the custom component will have the same effect as if you called setNativeProps on the wrapped View component itself.

You can now use MyButton inside of TouchableOpacity!

You may have noticed that we passed all of the props down to the child view using {...props}. The reason for this is that TouchableOpacity is actually a composite component, and so in addition to depending on setNativeProps on its child, it also requires that the child perform touch handling. To do this, it passes on various props that call back to the TouchableOpacity component. TouchableHighlight, in contrast, is backed by a native view and only requires that we implement setNativeProps.

setNativeProps to clear TextInput value

Another very common use case of setNativeProps is to clear the value of a TextInput. The controlled prop of TextInput can sometimes drop characters when the bufferDelay is low and the user types very quickly. Some developers prefer to skip this prop entirely and instead use setNativeProps to directly manipulate the TextInput value when necessary. For example, the following code demonstrates clearing the input when you tap a button:

Avoiding conflicts with the render function

If you update a property that is also managed by the render function, you might end up with some unpredictable and confusing bugs because anytime the component re-renders and that property changes, whatever value was previously set from setNativeProps will be completely ignored and overridden.

setNativeProps & shouldComponentUpdate

By intelligently applying shouldComponentUpdate you can avoid the unnecessary overhead involved in reconciling unchanged component subtrees, to the point where it may be performant enough to use setState instead of setNativeProps.

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 in the viewport 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 and you don't need pageX and pageY, consider using the onLayout property instead.

Also the width and height returned by measure() are the width and height of the component in the viewport. If you need the actual size of the component, consider using the onLayout property 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(relativeToNativeComponentRef, onSuccess, onFail)

Like measure(), but measures the view relative to an ancestor, specified with relativeToNativeComponentRef reference. This means that the returned coordinates are relative to the origin x, y of the ancestor view.

Note: This method can also be called with a relativeToNativeNode handler (instead of reference), but this variant is deprecated.

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().

Edit this page
Last updated on
- + diff --git a/docs/next/drawerlayoutandroid.html b/docs/next/drawerlayoutandroid.html index 35d2df4893e..a345727821b 100644 --- a/docs/next/drawerlayoutandroid.html +++ b/docs/next/drawerlayoutandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

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 side of the window specified by the drawerPosition prop and its width can be set by the drawerWidth prop.

Example

Reference

Props

View Props

Inherits View Props.

drawerBackgroundColor

Specifies the background color of the drawer. The default value is white. If you want to set the opacity of the drawer, use rgba. Example:

return (
<DrawerLayoutAndroid drawerBackgroundColor="rgba(0,0,0,0.5)" />
);
TypeRequired
colorNo

drawerLockMode

Specifies the lock mode of the drawer. The drawer can be locked in 3 states:

  • unlocked (default), meaning that the drawer will respond (open/close) to touch gestures.
  • locked-closed, meaning that the drawer will stay closed and not respond to gestures.
  • locked-open, meaning that the drawer will stay opened and not respond to gestures. The drawer may still be opened and closed programmatically (openDrawer/closeDrawer).
TypeRequired
enum('unlocked', 'locked-closed', 'locked-open')No

drawerPosition

Specifies the side of the screen from which the drawer will slide in. By default it is set to left.

TypeRequired
enum('left', 'right')No

drawerWidth

Specifies the width of the drawer, more precisely the width of the view that be pulled in from the edge of the window.

TypeRequired
numberNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

  • 'none' (the default), drags do not dismiss the keyboard.
  • 'on-drag', the keyboard is dismissed when a drag begins.
TypeRequired
enum('none', 'on-drag')No

onDrawerClose

Function called whenever the navigation view has been closed.

TypeRequired
functionNo

onDrawerOpen

Function called whenever the navigation view has been opened.

TypeRequired
functionNo

onDrawerSlide

Function called whenever there is an interaction with the navigation view.

TypeRequired
functionNo

onDrawerStateChanged

Function called when the drawer state has changed. The drawer can be in 3 states:

  • idle, meaning there is no interaction with the navigation view happening at the time
  • dragging, meaning there is currently an interaction with the navigation view
  • settling, meaning that there was an interaction with the navigation view, and the navigation view is now finishing its closing or opening animation
TypeRequired
functionNo

renderNavigationView

The navigation view that will be rendered to the side of the screen and can be pulled in.

TypeRequired
functionYes

statusBarBackgroundColor

Make the drawer take the entire screen and draw the background of the status bar to allow it to open over the status bar. It will only have an effect on API 21+.

TypeRequired
colorNo

Methods

closeDrawer()

closeDrawer();

Closes the drawer.

openDrawer()

openDrawer();

Opens the drawer.

Edit this page
Last updated on
- + diff --git a/docs/next/drawerlayoutandroid/index.html b/docs/next/drawerlayoutandroid/index.html index 35d2df4893e..a345727821b 100644 --- a/docs/next/drawerlayoutandroid/index.html +++ b/docs/next/drawerlayoutandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

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 side of the window specified by the drawerPosition prop and its width can be set by the drawerWidth prop.

Example

Reference

Props

View Props

Inherits View Props.

drawerBackgroundColor

Specifies the background color of the drawer. The default value is white. If you want to set the opacity of the drawer, use rgba. Example:

return (
<DrawerLayoutAndroid drawerBackgroundColor="rgba(0,0,0,0.5)" />
);
TypeRequired
colorNo

drawerLockMode

Specifies the lock mode of the drawer. The drawer can be locked in 3 states:

  • unlocked (default), meaning that the drawer will respond (open/close) to touch gestures.
  • locked-closed, meaning that the drawer will stay closed and not respond to gestures.
  • locked-open, meaning that the drawer will stay opened and not respond to gestures. The drawer may still be opened and closed programmatically (openDrawer/closeDrawer).
TypeRequired
enum('unlocked', 'locked-closed', 'locked-open')No

drawerPosition

Specifies the side of the screen from which the drawer will slide in. By default it is set to left.

TypeRequired
enum('left', 'right')No

drawerWidth

Specifies the width of the drawer, more precisely the width of the view that be pulled in from the edge of the window.

TypeRequired
numberNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

  • 'none' (the default), drags do not dismiss the keyboard.
  • 'on-drag', the keyboard is dismissed when a drag begins.
TypeRequired
enum('none', 'on-drag')No

onDrawerClose

Function called whenever the navigation view has been closed.

TypeRequired
functionNo

onDrawerOpen

Function called whenever the navigation view has been opened.

TypeRequired
functionNo

onDrawerSlide

Function called whenever there is an interaction with the navigation view.

TypeRequired
functionNo

onDrawerStateChanged

Function called when the drawer state has changed. The drawer can be in 3 states:

  • idle, meaning there is no interaction with the navigation view happening at the time
  • dragging, meaning there is currently an interaction with the navigation view
  • settling, meaning that there was an interaction with the navigation view, and the navigation view is now finishing its closing or opening animation
TypeRequired
functionNo

renderNavigationView

The navigation view that will be rendered to the side of the screen and can be pulled in.

TypeRequired
functionYes

statusBarBackgroundColor

Make the drawer take the entire screen and draw the background of the status bar to allow it to open over the status bar. It will only have an effect on API 21+.

TypeRequired
colorNo

Methods

closeDrawer()

closeDrawer();

Closes the drawer.

openDrawer()

openDrawer();

Opens the drawer.

Edit this page
Last updated on
- + diff --git a/docs/next/dynamiccolorios.html b/docs/next/dynamiccolorios.html index f5da0c196ee..fae65a831bd 100644 --- a/docs/next/dynamiccolorios.html +++ b/docs/next/dynamiccolorios.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
const customDynamicTextColor = DynamicColorIOS({
dark: 'lightskyblue',
light: 'midnightblue'
});
Edit this page
Last updated on
- + diff --git a/docs/next/dynamiccolorios/index.html b/docs/next/dynamiccolorios/index.html index f5da0c196ee..fae65a831bd 100644 --- a/docs/next/dynamiccolorios/index.html +++ b/docs/next/dynamiccolorios/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
const customDynamicTextColor = DynamicColorIOS({
dark: 'lightskyblue',
light: 'midnightblue'
});
Edit this page
Last updated on
- + diff --git a/docs/next/easing.html b/docs/next/easing.html index 604f116c4e6..36fa5dae6de 100644 --- a/docs/next/easing.html +++ b/docs/next/easing.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Easing

The Easing module implements common easing functions. This module is used by Animated.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 following methods:

  • back provides a basic animation where the object goes slightly back before moving forward
  • bounce provides a bouncing animation
  • ease provides a basic inertial animation
  • elastic provides a basic spring interaction

Standard functions

Three standard easing functions are provided:

The poly function can be used to implement quartic, quintic, and other higher power functions.

Additional functions

Additional mathematical functions are provided by the following methods:

  • bezier provides a cubic bezier curve
  • circle provides a circular function
  • sin provides a sinusoidal function
  • exp provides an exponential function

The following helpers are used to modify other easing functions.

  • in runs an easing function forwards
  • inOut makes any easing function symmetrical
  • out runs an easing function backwards

Example

Reference

Methods

step0()

static step0(n)

A stepping function, returns 1 for any positive value of n.

step1()

static step1(n)

A stepping function, returns 1 if n is greater than or equal to 1.

linear()

static linear(t)

A linear function, f(t) = t. Position correlates to elapsed time one to one.

http://cubic-bezier.com/#0,0,1,1

ease()

static ease(t)

A basic inertial interaction, similar to an object slowly accelerating to speed.

http://cubic-bezier.com/#.42,0,1,1

quad()

static quad(t)

A quadratic function, f(t) = t * t. Position equals the square of elapsed time.

http://easings.net/#easeInQuad

cubic()

static cubic(t)

A cubic function, f(t) = t * t * t. Position equals the cube of elapsed time.

http://easings.net/#easeInCubic

poly()

static poly(n)

A power function. Position is equal to the Nth power of elapsed time.

n = 4: http://easings.net/#easeInQuart n = 5: http://easings.net/#easeInQuint

sin()

static sin(t)

A sinusoidal function.

http://easings.net/#easeInSine

circle()

static circle(t)

A circular function.

http://easings.net/#easeInCirc

exp()

static exp(t)

An exponential function.

http://easings.net/#easeInExpo

elastic()

static elastic(bounciness)

A basic elastic interaction, similar to a spring oscillating back and forth.

Default bounciness is 1, which overshoots a little bit once. 0 bounciness doesn't overshoot at all, and bounciness of N > 1 will overshoot about N times.

http://easings.net/#easeInElastic

back()

static back(s)

Use with Animated.parallel() to create a basic effect where the object animates back slightly as the animation starts.

bounce()

static bounce(t)

Provides a basic bouncing effect.

http://easings.net/#easeInBounce

bezier()

static bezier(x1, y1, x2, y2)

Provides a cubic bezier curve, equivalent to CSS Transitions' transition-timing-function.

A useful tool to visualize cubic bezier curves can be found at http://cubic-bezier.com/

in()

static in(easing);

Runs an easing function forwards.

out()

static out(easing)

Runs an easing function backwards.

inOut()

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.

Edit this page
Last updated on
- + diff --git a/docs/next/easing/index.html b/docs/next/easing/index.html index 604f116c4e6..36fa5dae6de 100644 --- a/docs/next/easing/index.html +++ b/docs/next/easing/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Easing

The Easing module implements common easing functions. This module is used by Animated.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 following methods:

  • back provides a basic animation where the object goes slightly back before moving forward
  • bounce provides a bouncing animation
  • ease provides a basic inertial animation
  • elastic provides a basic spring interaction

Standard functions

Three standard easing functions are provided:

The poly function can be used to implement quartic, quintic, and other higher power functions.

Additional functions

Additional mathematical functions are provided by the following methods:

  • bezier provides a cubic bezier curve
  • circle provides a circular function
  • sin provides a sinusoidal function
  • exp provides an exponential function

The following helpers are used to modify other easing functions.

  • in runs an easing function forwards
  • inOut makes any easing function symmetrical
  • out runs an easing function backwards

Example

Reference

Methods

step0()

static step0(n)

A stepping function, returns 1 for any positive value of n.

step1()

static step1(n)

A stepping function, returns 1 if n is greater than or equal to 1.

linear()

static linear(t)

A linear function, f(t) = t. Position correlates to elapsed time one to one.

http://cubic-bezier.com/#0,0,1,1

ease()

static ease(t)

A basic inertial interaction, similar to an object slowly accelerating to speed.

http://cubic-bezier.com/#.42,0,1,1

quad()

static quad(t)

A quadratic function, f(t) = t * t. Position equals the square of elapsed time.

http://easings.net/#easeInQuad

cubic()

static cubic(t)

A cubic function, f(t) = t * t * t. Position equals the cube of elapsed time.

http://easings.net/#easeInCubic

poly()

static poly(n)

A power function. Position is equal to the Nth power of elapsed time.

n = 4: http://easings.net/#easeInQuart n = 5: http://easings.net/#easeInQuint

sin()

static sin(t)

A sinusoidal function.

http://easings.net/#easeInSine

circle()

static circle(t)

A circular function.

http://easings.net/#easeInCirc

exp()

static exp(t)

An exponential function.

http://easings.net/#easeInExpo

elastic()

static elastic(bounciness)

A basic elastic interaction, similar to a spring oscillating back and forth.

Default bounciness is 1, which overshoots a little bit once. 0 bounciness doesn't overshoot at all, and bounciness of N > 1 will overshoot about N times.

http://easings.net/#easeInElastic

back()

static back(s)

Use with Animated.parallel() to create a basic effect where the object animates back slightly as the animation starts.

bounce()

static bounce(t)

Provides a basic bouncing effect.

http://easings.net/#easeInBounce

bezier()

static bezier(x1, y1, x2, y2)

Provides a cubic bezier curve, equivalent to CSS Transitions' transition-timing-function.

A useful tool to visualize cubic bezier curves can be found at http://cubic-bezier.com/

in()

static in(easing);

Runs an easing function forwards.

out()

static out(easing)

Runs an easing function backwards.

inOut()

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.

Edit this page
Last updated on
- + diff --git a/docs/next/environment-setup.html b/docs/next/environment-setup.html index 318846c867a..33279f5c843 100644 --- a/docs/next/environment-setup.html +++ b/docs/next/environment-setup.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
cd AwesomeProject
npm start # you can also use: expo start

This will start a development server for you.

Running your React Native application

Install the Expo client app on your iOS or Android phone and connect to the same wireless network as your computer. On Android, use the Expo app to scan the QR code from your terminal to open your project. On iOS, use the built-in QR code scanner of the Camera app.

Modifying your app

Now that you have successfully run the app, let's modify it. Open App.js in your text editor of choice and edit some lines. The application should reload automatically once you save your changes.

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

Expo also has docs you can reference if you have questions specific to the tool. You can also ask for help at Expo forums.

These tools help you get started quickly, but before committing to building your app with Expo CLI, read about the limitations.

If you have a problem with Expo, before creating a new issue, please see if there's an existing issue about it:

If you're curious to learn more about React Native, check out the Introduction to React Native.

Running your app on a simulator or virtual device

Expo CLI allows you to run your React Native app on a physical device without setting up a development environment. If you want to run your app on the iOS Simulator or an Android Virtual Device, please refer to the instructions for "React Native CLI Quickstart" to learn how to install Xcode or set up your Android development environment.

Once you've set these up, you can launch your app on an Android Virtual Device by running npm run android, or on the iOS Simulator by running npm run ios (macOS only).

Caveats

Because you don't build any native code when using Expo to create a project, it's not possible to include custom native modules beyond the React Native APIs and components that are available in the Expo client app.

If you know that you'll eventually need to include your own native code, Expo is still a good way to get started. In that case you'll need to "eject" eventually to create your own native builds. If you do eject, the "React Native CLI Quickstart" instructions will be required to continue working on your project.

Expo CLI configures your project to use the most recent React Native version that is supported by the Expo client app. The Expo client app usually gains support for a given React Native version about a week after the React Native version is released as stable. You can check this document to find out what versions are supported.

If you're integrating React Native into an existing project, you'll want to skip Expo CLI and go directly to setting up the native build environment. Select "React Native CLI Quickstart" above for instructions on configuring a native build environment for React Native.

Edit this page
Last updated on
- + diff --git a/docs/next/environment-setup/index.html b/docs/next/environment-setup/index.html index 318846c867a..33279f5c843 100644 --- a/docs/next/environment-setup/index.html +++ b/docs/next/environment-setup/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
cd AwesomeProject
npm start # you can also use: expo start

This will start a development server for you.

Running your React Native application

Install the Expo client app on your iOS or Android phone and connect to the same wireless network as your computer. On Android, use the Expo app to scan the QR code from your terminal to open your project. On iOS, use the built-in QR code scanner of the Camera app.

Modifying your app

Now that you have successfully run the app, let's modify it. Open App.js in your text editor of choice and edit some lines. The application should reload automatically once you save your changes.

That's it!

Congratulations! You've successfully run and modified your first React Native app.

Now what?

Expo also has docs you can reference if you have questions specific to the tool. You can also ask for help at Expo forums.

These tools help you get started quickly, but before committing to building your app with Expo CLI, read about the limitations.

If you have a problem with Expo, before creating a new issue, please see if there's an existing issue about it:

If you're curious to learn more about React Native, check out the Introduction to React Native.

Running your app on a simulator or virtual device

Expo CLI allows you to run your React Native app on a physical device without setting up a development environment. If you want to run your app on the iOS Simulator or an Android Virtual Device, please refer to the instructions for "React Native CLI Quickstart" to learn how to install Xcode or set up your Android development environment.

Once you've set these up, you can launch your app on an Android Virtual Device by running npm run android, or on the iOS Simulator by running npm run ios (macOS only).

Caveats

Because you don't build any native code when using Expo to create a project, it's not possible to include custom native modules beyond the React Native APIs and components that are available in the Expo client app.

If you know that you'll eventually need to include your own native code, Expo is still a good way to get started. In that case you'll need to "eject" eventually to create your own native builds. If you do eject, the "React Native CLI Quickstart" instructions will be required to continue working on your project.

Expo CLI configures your project to use the most recent React Native version that is supported by the Expo client app. The Expo client app usually gains support for a given React Native version about a week after the React Native version is released as stable. You can check this document to find out what versions are supported.

If you're integrating React Native into an existing project, you'll want to skip Expo CLI and go directly to setting up the native build environment. Select "React Native CLI Quickstart" above for instructions on configuring a native build environment for React Native.

Edit this page
Last updated on
- + diff --git a/docs/next/fast-refresh.html b/docs/next/fast-refresh.html index 125302c1b48..5880d33adbb 100644 --- a/docs/next/fast-refresh.html +++ b/docs/next/fast-refresh.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Fast Refresh

Fast Refresh is a React Native feature that allows you to get near-instant feedback for changes in your React components. Fast Refresh is enabled by default, and you can toggle "Enable Fast Refresh" in the React Native developer menu. With Fast Refresh enabled, most edits should be visible within a second or two.

How It Works

  • If you edit a module that only exports React component(s), Fast Refresh will update the code only for that module, and re-render your component. You can edit anything in that file, including styles, rendering logic, event handlers, or effects.
  • If you edit a module with exports that aren't React components, Fast Refresh will re-run both that module, and the other modules importing it. So if both Button.js and Modal.js import Theme.js, editing Theme.js will update both components.
  • Finally, if you edit a file that's imported by modules outside of the React tree, Fast Refresh will fall back to doing a full reload. You might have a file which renders a React component but also exports a value that is imported by a non-React component. For example, maybe your component also exports a constant, and a non-React utility module imports it. In that case, consider migrating the query to a separate file and importing it into both files. This will re-enable Fast Refresh to work. Other cases can usually be solved in a similar way.

Error Resilience

If you make a syntax error during a Fast Refresh session, you can fix it and save the file again. The redbox will disappear. Modules with syntax errors are prevented from running, so you won't need to reload the app.

If you make a runtime error during the module initialization (for example, typing Style.create instead of StyleSheet.create), the Fast Refresh session will continue once you fix the error. The redbox will disappear, and the module will be updated.

If you make a mistake that leads to a runtime error inside your component, the Fast Refresh session will also continue after you fix the error. In that case, React will remount your application using the updated code.

If you have error boundaries in your app (which is a good idea for graceful failures in production), they will retry rendering on the next edit after a redbox. In that sense, having an error boundary can prevent you from always getting kicked out to the root app screen. However, keep in mind that error boundaries shouldn't be too granular. They are used by React in production, and should always be designed intentionally.

Limitations

Fast Refresh tries to preserve local React state in the component you're editing, but only if it's safe to do so. Here's a few reasons why you might see local state being reset on every edit to a file:

  • Local state is not preserved for class components (only function components and Hooks preserve state).
  • The module you're editing might have other exports in addition to a React component.
  • Sometimes, a module would export the result of calling higher-order component like createNavigationContainer(MyScreen). If the returned component is a class, state will be reset.

In the longer term, as more of your codebase moves to function components and Hooks, you can expect state to be preserved in more cases.

Tips

  • Fast Refresh preserves React local state in function components (and Hooks) by default.
  • Sometimes you might want to force the state to be reset, and a component to be remounted. For example, this can be handy if you're tweaking an animation that only happens on mount. To do this, you can add // @refresh reset anywhere in the file you're editing. This directive is local to the file, and instructs Fast Refresh to remount components defined in that file on every edit.

Fast Refresh and Hooks

When possible, Fast Refresh attempts to preserve the state of your component between edits. In particular, useState and useRef preserve their previous values as long as you don't change their arguments or the order of the Hook calls.

Hooks with dependencies—such as useEffect, useMemo, and useCallback—will always update during Fast Refresh. Their list of dependencies will be ignored while Fast Refresh is happening.

For example, when you edit useMemo(() => x * 2, [x]) to useMemo(() => x * 10, [x]), it will re-run even though x (the dependency) has not changed. If React didn't do that, your edit wouldn't reflect on the screen!

Sometimes, this can lead to unexpected results. For example, even a useEffect with an empty array of dependencies would still re-run once during Fast Refresh. However, writing code resilient to an occasional re-running of useEffect is a good practice even without Fast Refresh. This makes it easier for you to later introduce new dependencies to it.

Edit this page
Last updated on
- + diff --git a/docs/next/fast-refresh/index.html b/docs/next/fast-refresh/index.html index 125302c1b48..5880d33adbb 100644 --- a/docs/next/fast-refresh/index.html +++ b/docs/next/fast-refresh/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Fast Refresh

Fast Refresh is a React Native feature that allows you to get near-instant feedback for changes in your React components. Fast Refresh is enabled by default, and you can toggle "Enable Fast Refresh" in the React Native developer menu. With Fast Refresh enabled, most edits should be visible within a second or two.

How It Works

  • If you edit a module that only exports React component(s), Fast Refresh will update the code only for that module, and re-render your component. You can edit anything in that file, including styles, rendering logic, event handlers, or effects.
  • If you edit a module with exports that aren't React components, Fast Refresh will re-run both that module, and the other modules importing it. So if both Button.js and Modal.js import Theme.js, editing Theme.js will update both components.
  • Finally, if you edit a file that's imported by modules outside of the React tree, Fast Refresh will fall back to doing a full reload. You might have a file which renders a React component but also exports a value that is imported by a non-React component. For example, maybe your component also exports a constant, and a non-React utility module imports it. In that case, consider migrating the query to a separate file and importing it into both files. This will re-enable Fast Refresh to work. Other cases can usually be solved in a similar way.

Error Resilience

If you make a syntax error during a Fast Refresh session, you can fix it and save the file again. The redbox will disappear. Modules with syntax errors are prevented from running, so you won't need to reload the app.

If you make a runtime error during the module initialization (for example, typing Style.create instead of StyleSheet.create), the Fast Refresh session will continue once you fix the error. The redbox will disappear, and the module will be updated.

If you make a mistake that leads to a runtime error inside your component, the Fast Refresh session will also continue after you fix the error. In that case, React will remount your application using the updated code.

If you have error boundaries in your app (which is a good idea for graceful failures in production), they will retry rendering on the next edit after a redbox. In that sense, having an error boundary can prevent you from always getting kicked out to the root app screen. However, keep in mind that error boundaries shouldn't be too granular. They are used by React in production, and should always be designed intentionally.

Limitations

Fast Refresh tries to preserve local React state in the component you're editing, but only if it's safe to do so. Here's a few reasons why you might see local state being reset on every edit to a file:

  • Local state is not preserved for class components (only function components and Hooks preserve state).
  • The module you're editing might have other exports in addition to a React component.
  • Sometimes, a module would export the result of calling higher-order component like createNavigationContainer(MyScreen). If the returned component is a class, state will be reset.

In the longer term, as more of your codebase moves to function components and Hooks, you can expect state to be preserved in more cases.

Tips

  • Fast Refresh preserves React local state in function components (and Hooks) by default.
  • Sometimes you might want to force the state to be reset, and a component to be remounted. For example, this can be handy if you're tweaking an animation that only happens on mount. To do this, you can add // @refresh reset anywhere in the file you're editing. This directive is local to the file, and instructs Fast Refresh to remount components defined in that file on every edit.

Fast Refresh and Hooks

When possible, Fast Refresh attempts to preserve the state of your component between edits. In particular, useState and useRef preserve their previous values as long as you don't change their arguments or the order of the Hook calls.

Hooks with dependencies—such as useEffect, useMemo, and useCallback—will always update during Fast Refresh. Their list of dependencies will be ignored while Fast Refresh is happening.

For example, when you edit useMemo(() => x * 2, [x]) to useMemo(() => x * 10, [x]), it will re-run even though x (the dependency) has not changed. If React didn't do that, your edit wouldn't reflect on the screen!

Sometimes, this can lead to unexpected results. For example, even a useEffect with an empty array of dependencies would still re-run once during Fast Refresh. However, writing code resilient to an occasional re-running of useEffect is a good practice even without Fast Refresh. This makes it easier for you to later introduce new dependencies to it.

Edit this page
Last updated on
- + diff --git a/docs/next/flatlist.html b/docs/next/flatlist.html index 894db45b092..ee5be057322 100644 --- a/docs/next/flatlist.html +++ b/docs/next/flatlist.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
this.viewabilityConfig = {
waitForInteraction: true,
viewAreaCoveragePercentThreshold: 95
}
}
<FlatList
viewabilityConfig={this.viewabilityConfig}
...

minimumViewTime

Minimum amount of time (in milliseconds) that an item must be physically viewable before the viewability callback will be fired. A high number means that scrolling through content without stopping will not mark the content as viewable.

viewAreaCoveragePercentThreshold

Percent of viewport that must be covered for a partially occluded item to count as "viewable", 0-100. Fully visible items are always considered viewable. A value of 0 means that a single pixel in the viewport makes the item viewable, and a value of 100 means that an item must be either entirely visible or cover the entire viewport to count as viewable.

itemVisiblePercentThreshold

Similar to viewAreaCoveragePercentThreshold, but considers the percent of the item that is visible, rather than the fraction of the viewable area it covers.

waitForInteraction

Nothing is considered viewable until the user scrolls or recordInteraction is called after render.

viewabilityConfigCallbackPairs

List of ViewabilityConfig/onViewableItemsChanged pairs. A specific onViewableItemsChanged will be called when its corresponding ViewabilityConfig's conditions are met. See ViewabilityHelper.js for flow type and further documentation.

Type
array of ViewabilityConfigCallbackPair

Methods

flashScrollIndicators()

flashScrollIndicators();

Displays the scroll indicators momentarily.

getNativeScrollRef()

getNativeScrollRef();

Provides a reference to the underlying scroll component

getScrollResponder()

getScrollResponder();

Provides a handle to the underlying scroll responder.

getScrollableNode()

getScrollableNode();

Provides a handle to the underlying scroll node.

recordInteraction()

recordInteraction();

Tells the list an interaction has occurred, 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.

scrollToEnd()

scrollToEnd(params);

Scrolls to the end of the content. May be janky without getItemLayout prop.

Parameters:

NameType
paramsobject

Valid params keys are:

scrollToIndex()

scrollToIndex(params);

Scrolls to the item at the specified index such that it is positioned in the viewable area such that viewPosition 0 places it at the top, 1 at the bottom, and 0.5 centered in the middle.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout prop.

Parameters:

NameType
params
Required
object

Valid params keys are:

scrollToItem()

scrollToItem(params);

Requires linear scan through data - use scrollToIndex instead if possible.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout prop.

Parameters:

NameType
params
Required
object

Valid params keys are:

scrollToOffset()

scrollToOffset(params);

Scroll to a specific content pixel offset in the list.

Parameters:

NameType
params
Required
object

Valid params keys are:

Edit this page
Last updated on
- + diff --git a/docs/next/flatlist/index.html b/docs/next/flatlist/index.html index 894db45b092..ee5be057322 100644 --- a/docs/next/flatlist/index.html +++ b/docs/next/flatlist/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
this.viewabilityConfig = {
waitForInteraction: true,
viewAreaCoveragePercentThreshold: 95
}
}
<FlatList
viewabilityConfig={this.viewabilityConfig}
...

minimumViewTime

Minimum amount of time (in milliseconds) that an item must be physically viewable before the viewability callback will be fired. A high number means that scrolling through content without stopping will not mark the content as viewable.

viewAreaCoveragePercentThreshold

Percent of viewport that must be covered for a partially occluded item to count as "viewable", 0-100. Fully visible items are always considered viewable. A value of 0 means that a single pixel in the viewport makes the item viewable, and a value of 100 means that an item must be either entirely visible or cover the entire viewport to count as viewable.

itemVisiblePercentThreshold

Similar to viewAreaCoveragePercentThreshold, but considers the percent of the item that is visible, rather than the fraction of the viewable area it covers.

waitForInteraction

Nothing is considered viewable until the user scrolls or recordInteraction is called after render.

viewabilityConfigCallbackPairs

List of ViewabilityConfig/onViewableItemsChanged pairs. A specific onViewableItemsChanged will be called when its corresponding ViewabilityConfig's conditions are met. See ViewabilityHelper.js for flow type and further documentation.

Type
array of ViewabilityConfigCallbackPair

Methods

flashScrollIndicators()

flashScrollIndicators();

Displays the scroll indicators momentarily.

getNativeScrollRef()

getNativeScrollRef();

Provides a reference to the underlying scroll component

getScrollResponder()

getScrollResponder();

Provides a handle to the underlying scroll responder.

getScrollableNode()

getScrollableNode();

Provides a handle to the underlying scroll node.

recordInteraction()

recordInteraction();

Tells the list an interaction has occurred, 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.

scrollToEnd()

scrollToEnd(params);

Scrolls to the end of the content. May be janky without getItemLayout prop.

Parameters:

NameType
paramsobject

Valid params keys are:

scrollToIndex()

scrollToIndex(params);

Scrolls to the item at the specified index such that it is positioned in the viewable area such that viewPosition 0 places it at the top, 1 at the bottom, and 0.5 centered in the middle.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout prop.

Parameters:

NameType
params
Required
object

Valid params keys are:

scrollToItem()

scrollToItem(params);

Requires linear scan through data - use scrollToIndex instead if possible.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout prop.

Parameters:

NameType
params
Required
object

Valid params keys are:

scrollToOffset()

scrollToOffset(params);

Scroll to a specific content pixel offset in the list.

Parameters:

NameType
params
Required
object

Valid params keys are:

Edit this page
Last updated on
- + diff --git a/docs/next/flexbox.html b/docs/next/flexbox.html index 502db113018..399d2e13538 100644 --- a/docs/next/flexbox.html +++ b/docs/next/flexbox.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

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 flexDirection defaulting to column instead of row, alignContent defaulting to flex-start instead of stretch, flexShrink defaulting to 0 instead of 1, the flex parameter only supporting a single number.

Flex

flex will define how your items are going to “fill” over the available space along your main axis. Space will be divided according to each element's flex property.

In the following example, the red, yellow, and green views are all children in the container view that has flex: 1 set. The red view uses flex: 1 , the yellow view uses flex: 2, and the green view uses flex: 3 . 1+2+3 = 6, which means that the red view will get 1/6 of the space, the yellow 2/6 of the space, and the green 3/6 of the space.

Flex Direction

flexDirection controls the direction in which the children of a node are laid out. This is also referred to as the main axis. The cross axis is the axis perpendicular to the main axis, or the axis which the wrapping lines are laid out in.

  • column (default value) Align children from top to bottom. If wrapping is enabled, then the next line will start to the right of the first item on the top of the container.

  • row Align children from left to right. If wrapping is enabled, then the next line will start under the first item on the left of the container.

  • column-reverse Align children from bottom to top. If wrapping is enabled, then the next line will start to the right of the first item on the bottom of the container.

  • row-reverse Align children from right to left. If wrapping is enabled, then the next line will start under the first item on the right of the container.

You can learn more here.

Layout Direction

Layout direction specifies the direction in which children and text in a hierarchy should be laid out. Layout direction also affects what edge start and end refer to. By default, React Native lays out with LTR layout direction. In this mode start refers to left and end refers to right.

  • LTR (default value) Text and children are laid out from left to right. Margin and padding applied to the start of an element are applied on the left side.

  • RTL Text and children are laid out from right to left. Margin and padding applied to the start of an element are applied on the right side.

Justify Content

justifyContent describes how to align children within the main axis of their container. For example, you can use this property to center a child horizontally within a container with flexDirection set to row or vertically within a container with flexDirection set to column.

  • flex-start(default value) Align children of a container to the start of the container's main axis.

  • flex-end Align children of a container to the end of the container's main axis.

  • center Align children of a container in the center of the container's main axis.

  • space-between Evenly space off children across the container's main axis, distributing the remaining space between the children.

  • space-around Evenly space off children across the container's main axis, distributing the remaining space around the children. Compared to space-between, using space-around will result in space being distributed to the beginning of the first child and end of the last child.

  • space-evenly Evenly distribute children within the alignment container along the main axis. The spacing between each pair of adjacent items, the main-start edge and the first item, and the main-end edge and the last item, are all exactly the same.

You can learn more here.

Align Items

alignItems describes how to align children along the cross axis of their container. Align items is very similar to justifyContent but instead of applying to the main axis, alignItems applies to the cross axis.

  • stretch (default value) Stretch children of a container to match the height of the container's cross axis.

  • flex-start Align children of a container to the start of the container's cross axis.

  • flex-end Align children of a container to the end of the container's cross axis.

  • center Align children of a container in the center of the container's cross axis.

  • baseline Align children of a container along a common baseline. Individual children can be set to be the reference baseline for their parents.

For stretch to have an effect, children must not have a fixed dimension along the secondary axis. In the following example, setting alignItems: stretch does nothing until the width: 50 is removed from the children.

You can learn more here.

Align Self

alignSelf has the same options and effect as alignItems but instead of affecting the children within a container, you can apply this property to a single child to change its alignment within its parent. alignSelf overrides any option set by the parent with alignItems.

Align Content

alignContent defines the distribution of lines along the cross-axis. This only has effect when items are wrapped to multiple lines using flexWrap.

  • flex-start (default value) Align wrapped lines to the start of the container's cross axis.

  • flex-end Align wrapped lines to the end of the container's cross axis.

  • stretch (default value when using Yoga on the web) Stretch wrapped lines to match the height of the container's cross axis.

  • center Align wrapped lines in the center of the container's cross axis.

  • space-between Evenly space wrapped lines across the container's cross axis, distributing the remaining space between the lines.

  • space-around Evenly space wrapped lines across the container's cross axis, distributing the remaining space around the lines. Compared to space-between, using space-around will result in space being distributed to the beginning of the first line and the end of the last line.

You can learn more here.

Flex Wrap

The flexWrap property is set on containers and it controls what happens when children overflow the size of the container along the main axis. By default, children are forced into a single line (which can shrink elements). If wrapping is allowed, items are wrapped into multiple lines along the main axis if needed.

When wrapping lines, alignContent can be used to specify how the lines are placed in the container. Learn more here.

Flex Basis, Grow, and Shrink

  • flexBasis is an axis-independent way of providing the default size of an item along the main axis. Setting the flexBasis of a child is similar to setting the width of that child if its parent is a container with flexDirection: row or setting the height of a child if its parent is a container with flexDirection: column. The flexBasis of an item is the default size of that item, the size of the item before any flexGrow and flexShrink calculations are performed.

  • flexGrow describes how any space within a container should be distributed among its children along the main axis. After laying out its children, a container will distribute any remaining space according to the flex grow values specified by its children.

    flexGrow accepts any floating point value >= 0, with 0 being the default value. A container will distribute any remaining space among its children weighted by the children’s flexGrow values.

  • flexShrink describes how to shrink children along the main axis in the case in which the total size of the children overflows the size of the container on the main axis. flexShrink is very similar to flexGrow and can be thought of in the same way if any overflowing size is considered to be negative remaining space. These two properties also work well together by allowing children to grow and shrink as needed.

    flexShrink accepts any floating point value >= 0, with 0 being the default value (on the web, the default is 1). A container will shrink its children weighted by the children’s flexShrink values.

You can learn more here.

Width and Height

The width property specifies the width of an element's content area. Similarly, the height property specifies the height of an element's content area.

Both width and height can take the following values:

  • auto (default value) React Native calculates the width/height for the element based on its content, whether that is other children, text, or an image.

  • pixels Defines the width/height in absolute pixels. Depending on other styles set on the component, this may or may not be the final dimension of the node.

  • percentage Defines the width or height in percentage of its parent's width or height, respectively.

Absolute & Relative Layout

The position type of an element defines how it is positioned within its parent.

  • relative (default value) By default, an element is positioned relatively. This means an element is positioned according to the normal flow of the layout, and then offset relative to that position based on the values of top, right, bottom, and left. The offset does not affect the position of any sibling or parent elements.

  • absolute When positioned absolutely, an element doesn't take part in the normal layout flow. It is instead laid out independent of its siblings. The position is determined based on the top, right, bottom, and left values.

Going Deeper

Check out the interactive yoga playground that you can use to get a better understanding of flexbox.

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.

Additionally, you can see some examples from Wix Engineers.

Edit this page
Last updated on
- + diff --git a/docs/next/flexbox/index.html b/docs/next/flexbox/index.html index 502db113018..399d2e13538 100644 --- a/docs/next/flexbox/index.html +++ b/docs/next/flexbox/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

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 flexDirection defaulting to column instead of row, alignContent defaulting to flex-start instead of stretch, flexShrink defaulting to 0 instead of 1, the flex parameter only supporting a single number.

Flex

flex will define how your items are going to “fill” over the available space along your main axis. Space will be divided according to each element's flex property.

In the following example, the red, yellow, and green views are all children in the container view that has flex: 1 set. The red view uses flex: 1 , the yellow view uses flex: 2, and the green view uses flex: 3 . 1+2+3 = 6, which means that the red view will get 1/6 of the space, the yellow 2/6 of the space, and the green 3/6 of the space.

Flex Direction

flexDirection controls the direction in which the children of a node are laid out. This is also referred to as the main axis. The cross axis is the axis perpendicular to the main axis, or the axis which the wrapping lines are laid out in.

  • column (default value) Align children from top to bottom. If wrapping is enabled, then the next line will start to the right of the first item on the top of the container.

  • row Align children from left to right. If wrapping is enabled, then the next line will start under the first item on the left of the container.

  • column-reverse Align children from bottom to top. If wrapping is enabled, then the next line will start to the right of the first item on the bottom of the container.

  • row-reverse Align children from right to left. If wrapping is enabled, then the next line will start under the first item on the right of the container.

You can learn more here.

Layout Direction

Layout direction specifies the direction in which children and text in a hierarchy should be laid out. Layout direction also affects what edge start and end refer to. By default, React Native lays out with LTR layout direction. In this mode start refers to left and end refers to right.

  • LTR (default value) Text and children are laid out from left to right. Margin and padding applied to the start of an element are applied on the left side.

  • RTL Text and children are laid out from right to left. Margin and padding applied to the start of an element are applied on the right side.

Justify Content

justifyContent describes how to align children within the main axis of their container. For example, you can use this property to center a child horizontally within a container with flexDirection set to row or vertically within a container with flexDirection set to column.

  • flex-start(default value) Align children of a container to the start of the container's main axis.

  • flex-end Align children of a container to the end of the container's main axis.

  • center Align children of a container in the center of the container's main axis.

  • space-between Evenly space off children across the container's main axis, distributing the remaining space between the children.

  • space-around Evenly space off children across the container's main axis, distributing the remaining space around the children. Compared to space-between, using space-around will result in space being distributed to the beginning of the first child and end of the last child.

  • space-evenly Evenly distribute children within the alignment container along the main axis. The spacing between each pair of adjacent items, the main-start edge and the first item, and the main-end edge and the last item, are all exactly the same.

You can learn more here.

Align Items

alignItems describes how to align children along the cross axis of their container. Align items is very similar to justifyContent but instead of applying to the main axis, alignItems applies to the cross axis.

  • stretch (default value) Stretch children of a container to match the height of the container's cross axis.

  • flex-start Align children of a container to the start of the container's cross axis.

  • flex-end Align children of a container to the end of the container's cross axis.

  • center Align children of a container in the center of the container's cross axis.

  • baseline Align children of a container along a common baseline. Individual children can be set to be the reference baseline for their parents.

For stretch to have an effect, children must not have a fixed dimension along the secondary axis. In the following example, setting alignItems: stretch does nothing until the width: 50 is removed from the children.

You can learn more here.

Align Self

alignSelf has the same options and effect as alignItems but instead of affecting the children within a container, you can apply this property to a single child to change its alignment within its parent. alignSelf overrides any option set by the parent with alignItems.

Align Content

alignContent defines the distribution of lines along the cross-axis. This only has effect when items are wrapped to multiple lines using flexWrap.

  • flex-start (default value) Align wrapped lines to the start of the container's cross axis.

  • flex-end Align wrapped lines to the end of the container's cross axis.

  • stretch (default value when using Yoga on the web) Stretch wrapped lines to match the height of the container's cross axis.

  • center Align wrapped lines in the center of the container's cross axis.

  • space-between Evenly space wrapped lines across the container's cross axis, distributing the remaining space between the lines.

  • space-around Evenly space wrapped lines across the container's cross axis, distributing the remaining space around the lines. Compared to space-between, using space-around will result in space being distributed to the beginning of the first line and the end of the last line.

You can learn more here.

Flex Wrap

The flexWrap property is set on containers and it controls what happens when children overflow the size of the container along the main axis. By default, children are forced into a single line (which can shrink elements). If wrapping is allowed, items are wrapped into multiple lines along the main axis if needed.

When wrapping lines, alignContent can be used to specify how the lines are placed in the container. Learn more here.

Flex Basis, Grow, and Shrink

  • flexBasis is an axis-independent way of providing the default size of an item along the main axis. Setting the flexBasis of a child is similar to setting the width of that child if its parent is a container with flexDirection: row or setting the height of a child if its parent is a container with flexDirection: column. The flexBasis of an item is the default size of that item, the size of the item before any flexGrow and flexShrink calculations are performed.

  • flexGrow describes how any space within a container should be distributed among its children along the main axis. After laying out its children, a container will distribute any remaining space according to the flex grow values specified by its children.

    flexGrow accepts any floating point value >= 0, with 0 being the default value. A container will distribute any remaining space among its children weighted by the children’s flexGrow values.

  • flexShrink describes how to shrink children along the main axis in the case in which the total size of the children overflows the size of the container on the main axis. flexShrink is very similar to flexGrow and can be thought of in the same way if any overflowing size is considered to be negative remaining space. These two properties also work well together by allowing children to grow and shrink as needed.

    flexShrink accepts any floating point value >= 0, with 0 being the default value (on the web, the default is 1). A container will shrink its children weighted by the children’s flexShrink values.

You can learn more here.

Width and Height

The width property specifies the width of an element's content area. Similarly, the height property specifies the height of an element's content area.

Both width and height can take the following values:

  • auto (default value) React Native calculates the width/height for the element based on its content, whether that is other children, text, or an image.

  • pixels Defines the width/height in absolute pixels. Depending on other styles set on the component, this may or may not be the final dimension of the node.

  • percentage Defines the width or height in percentage of its parent's width or height, respectively.

Absolute & Relative Layout

The position type of an element defines how it is positioned within its parent.

  • relative (default value) By default, an element is positioned relatively. This means an element is positioned according to the normal flow of the layout, and then offset relative to that position based on the values of top, right, bottom, and left. The offset does not affect the position of any sibling or parent elements.

  • absolute When positioned absolutely, an element doesn't take part in the normal layout flow. It is instead laid out independent of its siblings. The position is determined based on the top, right, bottom, and left values.

Going Deeper

Check out the interactive yoga playground that you can use to get a better understanding of flexbox.

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.

Additionally, you can see some examples from Wix Engineers.

Edit this page
Last updated on
- + diff --git a/docs/next/gesture-responder-system.html b/docs/next/gesture-responder-system.html index 4f969c80c96..4bbc2858ba6 100644 --- a/docs/next/gesture-responder-system.html +++ b/docs/next/gesture-responder-system.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

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.

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 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 happening
  • View.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 finger
  • View.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 release
  • View.props.onResponderTerminate: (evt) => {} - The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, 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:

  • nativeEvent
    • changedTouches - Array of all touch events that have changed since the last event
    • identifier - The ID of the touch
    • locationX - The X position of the touch, relative to the element
    • locationY - The Y position of the touch, relative to the element
    • pageX - The X position of the touch, relative to the root element
    • pageY - The Y position of the touch, relative to the root element
    • target - The node id of the element receiving the touch event
    • timestamp - A time identifier for the touch, useful for velocity calculation
    • touches - 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.

Edit this page
Last updated on
- + diff --git a/docs/next/gesture-responder-system/index.html b/docs/next/gesture-responder-system/index.html index 4f969c80c96..4bbc2858ba6 100644 --- a/docs/next/gesture-responder-system/index.html +++ b/docs/next/gesture-responder-system/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

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.

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 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 happening
  • View.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 finger
  • View.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 release
  • View.props.onResponderTerminate: (evt) => {} - The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, 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:

  • nativeEvent
    • changedTouches - Array of all touch events that have changed since the last event
    • identifier - The ID of the touch
    • locationX - The X position of the touch, relative to the element
    • locationY - The Y position of the touch, relative to the element
    • pageX - The X position of the touch, relative to the root element
    • pageY - The Y position of the touch, relative to the root element
    • target - The node id of the element receiving the touch event
    • timestamp - A time identifier for the touch, useful for velocity calculation
    • touches - 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.

Edit this page
Last updated on
- + diff --git a/docs/next/getting-started.html b/docs/next/getting-started.html index 1c3dc88fa03..c87bf3a2758 100644 --- a/docs/next/getting-started.html +++ b/docs/next/getting-started.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Introduction

Welcome to the very start of your React Native journey! If you're looking for environment setup instructions, they've moved to their own section. Continue reading for an introduction to the documentation, Native Components, React, and more!

Many different kinds of people use React Native: from advanced iOS developers to React beginners, to people getting started programming for the first time in their career. These docs were written for all learners, no matter their experience level or background.

How to use these docs

You can start here and read through these docs linearly like a book; or you can read the specific sections you need. Already familiar with React? You can skip that section—or read it for a light refresher.

Prerequisites

To work with React Native, you will need to have an understanding of JavaScript fundamentals. If you’re new to JavaScript or need a refresher, you can dive in or brush up at Mozilla Developer Network.

While we do our best to assume no prior knowledge of React, Android, or iOS development, these are valuable topics of study for the aspiring React Native developer. Where sensible, we have linked to resources and articles that go more in depth.

Interactive examples

This introduction lets you get started immediately in your browser with interactive examples like this one:

The above is a Snack Player. It’s a handy tool created by Expo to embed and run React Native projects and share how they render in platforms like Android and iOS. The code is live and editable, so you can play directly with it in your browser. Go ahead and try changing the "Try editing me!" text above to "Hello, world!"

Optionally, if you want to setup a local development environment, you can follow our guide to setting up your environment on your local machine and paste the code examples into your App.js file there. (If you are a web developer, you may already have a local environment set up for mobile browser testing!)

Function Components and Class Components

With React, you can make components using either classes or functions. Originally, class components were the only components that could have state. But since the introduction of React's Hooks API, you can add state and more to function components.

Hooks were introduced in React Native 0.59., and because Hooks are the future-facing way to write your React components, we wrote this introduction using function component examples. Where useful, we also cover class components under a toggle like so:

You can find more examples of class components in previous versions of this documentation.

Developer Notes

People from many different development backgrounds are learning React Native. You may have experience with a range of technologies, from web to Android to iOS and more. We try to write for developers from all backgrounds. Sometimes we provide explanations specific to one platform or another like so:

Web developers may be familiar with this concept.

Formatting

Menu paths are written in bold and use carets to navigate submenus. Example: Android Studio > Preferences

Now that you know how this guide works, it's time to get to know the foundation of React Native: Native Components.

Edit this page
Last updated on
- + diff --git a/docs/next/getting-started/index.html b/docs/next/getting-started/index.html index 1c3dc88fa03..c87bf3a2758 100644 --- a/docs/next/getting-started/index.html +++ b/docs/next/getting-started/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Introduction

Welcome to the very start of your React Native journey! If you're looking for environment setup instructions, they've moved to their own section. Continue reading for an introduction to the documentation, Native Components, React, and more!

Many different kinds of people use React Native: from advanced iOS developers to React beginners, to people getting started programming for the first time in their career. These docs were written for all learners, no matter their experience level or background.

How to use these docs

You can start here and read through these docs linearly like a book; or you can read the specific sections you need. Already familiar with React? You can skip that section—or read it for a light refresher.

Prerequisites

To work with React Native, you will need to have an understanding of JavaScript fundamentals. If you’re new to JavaScript or need a refresher, you can dive in or brush up at Mozilla Developer Network.

While we do our best to assume no prior knowledge of React, Android, or iOS development, these are valuable topics of study for the aspiring React Native developer. Where sensible, we have linked to resources and articles that go more in depth.

Interactive examples

This introduction lets you get started immediately in your browser with interactive examples like this one:

The above is a Snack Player. It’s a handy tool created by Expo to embed and run React Native projects and share how they render in platforms like Android and iOS. The code is live and editable, so you can play directly with it in your browser. Go ahead and try changing the "Try editing me!" text above to "Hello, world!"

Optionally, if you want to setup a local development environment, you can follow our guide to setting up your environment on your local machine and paste the code examples into your App.js file there. (If you are a web developer, you may already have a local environment set up for mobile browser testing!)

Function Components and Class Components

With React, you can make components using either classes or functions. Originally, class components were the only components that could have state. But since the introduction of React's Hooks API, you can add state and more to function components.

Hooks were introduced in React Native 0.59., and because Hooks are the future-facing way to write your React components, we wrote this introduction using function component examples. Where useful, we also cover class components under a toggle like so:

You can find more examples of class components in previous versions of this documentation.

Developer Notes

People from many different development backgrounds are learning React Native. You may have experience with a range of technologies, from web to Android to iOS and more. We try to write for developers from all backgrounds. Sometimes we provide explanations specific to one platform or another like so:

Web developers may be familiar with this concept.

Formatting

Menu paths are written in bold and use carets to navigate submenus. Example: Android Studio > Preferences

Now that you know how this guide works, it's time to get to know the foundation of React Native: Native Components.

Edit this page
Last updated on
- + diff --git a/docs/next/handling-text-input.html b/docs/next/handling-text-input.html index 7cc2e195289..9adf149da35 100644 --- a/docs/next/handling-text-input.html +++ b/docs/next/handling-text-input.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Handling Text Input

TextInput is a Core Component that allows the user to enter text. It has an onChangeText prop that takes a function to be called every time the text changed, and an onSubmitEditing prop that takes a function to be called when the text is submitted.

For example, let's say that as the user types, you're translating their words into a different language. In this new language, every single word is written the same way: 🍕. So the sentence "Hello there Bob" would be translated as "🍕🍕🍕".

In this example, we store text in the state, because it changes over time.

There are a lot more things you might want to do with a text input. For example, you could validate the text inside while the user types. For more detailed examples, see the React docs on controlled components, or the reference docs for TextInput.

Text input is one of the ways the user interacts with the app. Next, let's look at another type of input and learn how to handle touches.

Edit this page
Last updated on
- + diff --git a/docs/next/handling-text-input/index.html b/docs/next/handling-text-input/index.html index 7cc2e195289..9adf149da35 100644 --- a/docs/next/handling-text-input/index.html +++ b/docs/next/handling-text-input/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Handling Text Input

TextInput is a Core Component that allows the user to enter text. It has an onChangeText prop that takes a function to be called every time the text changed, and an onSubmitEditing prop that takes a function to be called when the text is submitted.

For example, let's say that as the user types, you're translating their words into a different language. In this new language, every single word is written the same way: 🍕. So the sentence "Hello there Bob" would be translated as "🍕🍕🍕".

In this example, we store text in the state, because it changes over time.

There are a lot more things you might want to do with a text input. For example, you could validate the text inside while the user types. For more detailed examples, see the React docs on controlled components, or the reference docs for TextInput.

Text input is one of the ways the user interacts with the app. Next, let's look at another type of input and learn how to handle touches.

Edit this page
Last updated on
- + diff --git a/docs/next/handling-touches.html b/docs/next/handling-touches.html index 4cfe5e287d9..dce62a31e3f 100644 --- a/docs/next/handling-touches.html +++ b/docs/next/handling-touches.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Handling Touches

Users interact with mobile apps mainly through touch. They can use a combination of gestures, such as tapping on a button, scrolling a list, or zooming on a map. React Native provides components to handle all sorts of common gestures, as well as a comprehensive gesture responder system to allow for more advanced gesture recognition, but the one component you will most likely be interested in is the basic Button.

Displaying a basic button

Button provides a basic button component that is rendered nicely on all platforms. The minimal example to display a button looks like this:

<Button
onPress={() => {
alert('You tapped the button!');
}}
title="Press Me"
/>

This will render a blue label on iOS, and a blue rounded rectangle with light text on Android. Pressing the button will call the "onPress" function, which in this case displays an alert popup. If you like, you can specify a "color" prop to change the color of your button.

Go ahead and play around with the Button component using the example below. You can select which platform your app is previewed in by clicking on the toggle in the bottom right and then clicking on "Tap to Play" to preview the app.

Touchables

If the basic button doesn't look right for your app, you can build your own button using any of the "Touchable" components provided by React Native. The "Touchable" components provide the capability to capture tapping gestures, and can display feedback when a gesture is recognized. These components do not provide any default styling, however, so you will need to do a bit of work to get them looking nicely in your app.

Which "Touchable" component you use will depend on what kind of feedback you want to provide:

  • Generally, you can use TouchableHighlight anywhere you would use a button or link on web. The view's background will be darkened when the user presses down on the button.

  • You may consider using TouchableNativeFeedback on Android to display ink surface reaction ripples that respond to the user's touch.

  • TouchableOpacity can be used to provide feedback by reducing the opacity of the button, allowing the background to be seen through while the user is pressing down.

  • If you need to handle a tap gesture but you don't want any feedback to be displayed, use TouchableWithoutFeedback.

In some cases, you may want to detect when a user presses and holds a view for a set amount of time. These long presses can be handled by passing a function to the onLongPress props of any of the "Touchable" components.

Let's see all of these in action:

Scrolling and swiping

Gestures commonly used on devices with touchable screens include swipes and pans. These allow the user to scroll through a list of items, or swipe through pages of content. For these, check out the ScrollView Core Component.

Edit this page
Last updated on
- + diff --git a/docs/next/handling-touches/index.html b/docs/next/handling-touches/index.html index 4cfe5e287d9..dce62a31e3f 100644 --- a/docs/next/handling-touches/index.html +++ b/docs/next/handling-touches/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Handling Touches

Users interact with mobile apps mainly through touch. They can use a combination of gestures, such as tapping on a button, scrolling a list, or zooming on a map. React Native provides components to handle all sorts of common gestures, as well as a comprehensive gesture responder system to allow for more advanced gesture recognition, but the one component you will most likely be interested in is the basic Button.

Displaying a basic button

Button provides a basic button component that is rendered nicely on all platforms. The minimal example to display a button looks like this:

<Button
onPress={() => {
alert('You tapped the button!');
}}
title="Press Me"
/>

This will render a blue label on iOS, and a blue rounded rectangle with light text on Android. Pressing the button will call the "onPress" function, which in this case displays an alert popup. If you like, you can specify a "color" prop to change the color of your button.

Go ahead and play around with the Button component using the example below. You can select which platform your app is previewed in by clicking on the toggle in the bottom right and then clicking on "Tap to Play" to preview the app.

Touchables

If the basic button doesn't look right for your app, you can build your own button using any of the "Touchable" components provided by React Native. The "Touchable" components provide the capability to capture tapping gestures, and can display feedback when a gesture is recognized. These components do not provide any default styling, however, so you will need to do a bit of work to get them looking nicely in your app.

Which "Touchable" component you use will depend on what kind of feedback you want to provide:

  • Generally, you can use TouchableHighlight anywhere you would use a button or link on web. The view's background will be darkened when the user presses down on the button.

  • You may consider using TouchableNativeFeedback on Android to display ink surface reaction ripples that respond to the user's touch.

  • TouchableOpacity can be used to provide feedback by reducing the opacity of the button, allowing the background to be seen through while the user is pressing down.

  • If you need to handle a tap gesture but you don't want any feedback to be displayed, use TouchableWithoutFeedback.

In some cases, you may want to detect when a user presses and holds a view for a set amount of time. These long presses can be handled by passing a function to the onLongPress props of any of the "Touchable" components.

Let's see all of these in action:

Scrolling and swiping

Gestures commonly used on devices with touchable screens include swipes and pans. These allow the user to scroll through a list of items, or swipe through pages of content. For these, check out the ScrollView Core Component.

Edit this page
Last updated on
- + diff --git a/docs/next/headless-js-android.html b/docs/next/headless-js-android.html index 545d56a8c40..b5a7dfbcbc2 100644 --- a/docs/next/headless-js-android.html +++ b/docs/next/headless-js-android.html @@ -19,7 +19,7 @@ - + @@ -44,7 +44,7 @@
}
Edit this page
Last updated on
- + diff --git a/docs/next/headless-js-android/index.html b/docs/next/headless-js-android/index.html index 545d56a8c40..b5a7dfbcbc2 100644 --- a/docs/next/headless-js-android/index.html +++ b/docs/next/headless-js-android/index.html @@ -19,7 +19,7 @@ - + @@ -44,7 +44,7 @@
}
Edit this page
Last updated on
- + diff --git a/docs/next/height-and-width.html b/docs/next/height-and-width.html index 0d3b6e64f20..632ad6b8926 100644 --- a/docs/next/height-and-width.html +++ b/docs/next/height-and-width.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Height and Width

A component's height and width determine its size on the screen.

Fixed Dimensions

The general way to set the dimensions of a component is by adding a fixed width and height to style. All dimensions in React Native are unitless, and represent density-independent pixels.

Setting dimensions this way is common for components that should always render at exactly the same size, regardless of screen dimensions.

Flex Dimensions

Use flex in a component's style to have the component expand and shrink dynamically based on available space. Normally you will use flex: 1, which tells a component to fill all available space, shared evenly amongst other components with the same parent. The larger the flex given, the higher the ratio of space a component will take compared to its siblings.

A component can only expand to fill available space if its parent has dimensions greater than 0. If a parent does not have either a fixed width and height or flex, the parent will have dimensions of 0 and the flex children will not be visible.

After you can control a component's size, the next step is to learn how to lay it out on the screen.

Percentage Dimensions

If you want to fill a certain portion of the screen, but you don't want to use the flex layout, you can use percentage values in the component's style. Similar to flex dimensions, percentage dimensions require parent with a defined size.

Edit this page
Last updated on
- + diff --git a/docs/next/height-and-width/index.html b/docs/next/height-and-width/index.html index 0d3b6e64f20..632ad6b8926 100644 --- a/docs/next/height-and-width/index.html +++ b/docs/next/height-and-width/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Height and Width

A component's height and width determine its size on the screen.

Fixed Dimensions

The general way to set the dimensions of a component is by adding a fixed width and height to style. All dimensions in React Native are unitless, and represent density-independent pixels.

Setting dimensions this way is common for components that should always render at exactly the same size, regardless of screen dimensions.

Flex Dimensions

Use flex in a component's style to have the component expand and shrink dynamically based on available space. Normally you will use flex: 1, which tells a component to fill all available space, shared evenly amongst other components with the same parent. The larger the flex given, the higher the ratio of space a component will take compared to its siblings.

A component can only expand to fill available space if its parent has dimensions greater than 0. If a parent does not have either a fixed width and height or flex, the parent will have dimensions of 0 and the flex children will not be visible.

After you can control a component's size, the next step is to learn how to lay it out on the screen.

Percentage Dimensions

If you want to fill a certain portion of the screen, but you don't want to use the flex layout, you can use percentage values in the component's style. Similar to flex dimensions, percentage dimensions require parent with a defined size.

Edit this page
Last updated on
- + diff --git a/docs/next/hermes.html b/docs/next/hermes.html index c75867a1198..56b033b960b 100644 --- a/docs/next/hermes.html +++ b/docs/next/hermes.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Using Hermes

Hermes is an open-source JavaScript engine optimized for running React Native apps on Android. For many apps, enabling Hermes will result in improved start-up time, decreased memory usage, and smaller app size. At this time Hermes is an opt-in React Native feature, and this guide explains how to enable it.

First, ensure you're using at least version 0.60.4 of React Native.

If you have an existing app based on an earlier version of React Native, you will have to upgrade it first. See Upgrading to new React Native Versions for how to do this. Make especially sure that all changes to android/app/build.gradle have been applied, as detailed by the React Native upgrade helper. After upgrading the app, make sure everything works before trying to switch to Hermes.

Note for RN compatibility.

Each Hermes release is aimed at a specific RN version. The rule of thumb is to always follow Hermes releases strictly. Version mismatch can result in instant crash of your apps in the worst case scenario.

Note for Windows users.

Hermes requires Microsoft Visual C++ 2015 Redistributable

Edit your android/app/build.gradle file and make the change illustrated below:

project.ext.react = [
entryFile: "index.js",
- enableHermes: false // clean and rebuild if changing
+ enableHermes: true // clean and rebuild if changing
]

Also, if you're using ProGuard, you will need to add these rules in proguard-rules.pro :

-keep class com.facebook.hermes.unicode.** { *; }
-keep class com.facebook.jni.** { *; }

Next, if you've already built your app at least once, clean the build:

$ cd android && ./gradlew clean

That's it! You should now be able to develop and deploy your app as normal:

$ npx react-native run-android

Note about Android App Bundles

Android app bundles are supported from react-native 0.62.0 and up.

Confirming Hermes is in use

If you've recently created a new app from scratch, you should see if Hermes is enabled in the welcome view:

Where to find JS engine status in AwesomeProject

A HermesInternal global variable will be available in JavaScript that can be used to verify that Hermes is in use:

const isHermes = () => !!global.HermesInternal;

To see the benefits of Hermes, try making a release build/deployment of your app to compare. For example:

$ npx react-native run-android --variant release

This will compile JavaScript to bytecode during build time which will improve your app's startup speed on device.

Debugging JS on Hermes using Google Chrome's DevTools

Hermes supports the Chrome debugger by implementing the Chrome inspector protocol. This means Chrome's tools can be used to directly debug JavaScript running on Hermes, on an emulator or on a real, physical, device.

Note that this is very different with the "Remote JS Debugging" from the In-App Developer Menu documented in the Debugging section, which actually runs the JS code on Chrome's V8 on your development machine (laptop or desktop).

Chrome connects to Hermes running on device via Metro, so you'll need to know where Metro is listening. Typically this will be on localhost:8081, but this is configurable. When running yarn start the address is written to stdout on startup.

Once you know where the Metro server is listening, you can connect with Chrome using the following steps:

  1. Navigate to chrome://inspect in a Chrome browser instance.

  2. Use the Configure... button to add the Metro server address (typically localhost:8081 as described above).

Configure button in Chrome DevTools devices page

Dialog for adding Chrome DevTools network targets

  1. You should now see a "Hermes React Native" target with an "inspect" link which can be used to bring up debugger. If you don't see the "inspect" link, make sure the Metro server is running. Target inspect link

  2. You can now use the Chrome debug tools. For example, to breakpoint the next time some JavaScript is run, click on the pause button and trigger an action in your app which would cause JavaScript to execute. Pause button in debug tools

Edit this page
Last updated on
- + diff --git a/docs/next/hermes/index.html b/docs/next/hermes/index.html index c75867a1198..56b033b960b 100644 --- a/docs/next/hermes/index.html +++ b/docs/next/hermes/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Using Hermes

Hermes is an open-source JavaScript engine optimized for running React Native apps on Android. For many apps, enabling Hermes will result in improved start-up time, decreased memory usage, and smaller app size. At this time Hermes is an opt-in React Native feature, and this guide explains how to enable it.

First, ensure you're using at least version 0.60.4 of React Native.

If you have an existing app based on an earlier version of React Native, you will have to upgrade it first. See Upgrading to new React Native Versions for how to do this. Make especially sure that all changes to android/app/build.gradle have been applied, as detailed by the React Native upgrade helper. After upgrading the app, make sure everything works before trying to switch to Hermes.

Note for RN compatibility.

Each Hermes release is aimed at a specific RN version. The rule of thumb is to always follow Hermes releases strictly. Version mismatch can result in instant crash of your apps in the worst case scenario.

Note for Windows users.

Hermes requires Microsoft Visual C++ 2015 Redistributable

Edit your android/app/build.gradle file and make the change illustrated below:

project.ext.react = [
entryFile: "index.js",
- enableHermes: false // clean and rebuild if changing
+ enableHermes: true // clean and rebuild if changing
]

Also, if you're using ProGuard, you will need to add these rules in proguard-rules.pro :

-keep class com.facebook.hermes.unicode.** { *; }
-keep class com.facebook.jni.** { *; }

Next, if you've already built your app at least once, clean the build:

$ cd android && ./gradlew clean

That's it! You should now be able to develop and deploy your app as normal:

$ npx react-native run-android

Note about Android App Bundles

Android app bundles are supported from react-native 0.62.0 and up.

Confirming Hermes is in use

If you've recently created a new app from scratch, you should see if Hermes is enabled in the welcome view:

Where to find JS engine status in AwesomeProject

A HermesInternal global variable will be available in JavaScript that can be used to verify that Hermes is in use:

const isHermes = () => !!global.HermesInternal;

To see the benefits of Hermes, try making a release build/deployment of your app to compare. For example:

$ npx react-native run-android --variant release

This will compile JavaScript to bytecode during build time which will improve your app's startup speed on device.

Debugging JS on Hermes using Google Chrome's DevTools

Hermes supports the Chrome debugger by implementing the Chrome inspector protocol. This means Chrome's tools can be used to directly debug JavaScript running on Hermes, on an emulator or on a real, physical, device.

Note that this is very different with the "Remote JS Debugging" from the In-App Developer Menu documented in the Debugging section, which actually runs the JS code on Chrome's V8 on your development machine (laptop or desktop).

Chrome connects to Hermes running on device via Metro, so you'll need to know where Metro is listening. Typically this will be on localhost:8081, but this is configurable. When running yarn start the address is written to stdout on startup.

Once you know where the Metro server is listening, you can connect with Chrome using the following steps:

  1. Navigate to chrome://inspect in a Chrome browser instance.

  2. Use the Configure... button to add the Metro server address (typically localhost:8081 as described above).

Configure button in Chrome DevTools devices page

Dialog for adding Chrome DevTools network targets

  1. You should now see a "Hermes React Native" target with an "inspect" link which can be used to bring up debugger. If you don't see the "inspect" link, make sure the Metro server is running. Target inspect link

  2. You can now use the Chrome debug tools. For example, to breakpoint the next time some JavaScript is run, click on the pause button and trigger an action in your app which would cause JavaScript to execute. Pause button in debug tools

Edit this page
Last updated on
- + diff --git a/docs/next/image-style-props.html b/docs/next/image-style-props.html index 53f035104fc..113643f8eed 100644 --- a/docs/next/image-style-props.html +++ b/docs/next/image-style-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Image Style Props

Examples

Image Resize Mode

Image Border

Image Border Radius

Image Tint

Reference

Props

backfaceVisibility

The property defines whether or not the back face of a rotated image should be visible.

TypeDefault
enum('visible', 'hidden')'visible'

backgroundColor

Type
color

borderBottomLeftRadius

Type
number

borderBottomRightRadius

Type
number

borderColor

Type
color

borderRadius

Type
number

borderTopLeftRadius

Type
number

borderTopRightRadius

Type
number

borderWidth

Type
number

opacity

Set an opacity value for the image. The number should be in the range from 0.0 to 1.0.

TypeDefault
number1.0

overflow

TypeDefault
enum('visible', 'hidden')'visible'

overlayColor
Android

When the image has rounded corners, specifying an overlayColor will cause the remaining space in the corners to be filled with a solid color. This is useful in cases which are not supported by the Android implementation of rounded corners:

  • Certain resize modes, such as 'contain'
  • Animated GIFs

A typical way to use this prop is with images displayed on a solid background and setting the overlayColor to the same color as the background.

For details of how this works under the hood, see Fresco documentation.

Type
string

resizeMode

TypeDefault
enum('cover', 'contain', 'stretch', 'repeat', 'center')'cover'

tintColor

Changes the color of all the non-transparent pixels to the tintColor.

Type
color
Edit this page
Last updated on
- + diff --git a/docs/next/image-style-props/index.html b/docs/next/image-style-props/index.html index 53f035104fc..113643f8eed 100644 --- a/docs/next/image-style-props/index.html +++ b/docs/next/image-style-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Image Style Props

Examples

Image Resize Mode

Image Border

Image Border Radius

Image Tint

Reference

Props

backfaceVisibility

The property defines whether or not the back face of a rotated image should be visible.

TypeDefault
enum('visible', 'hidden')'visible'

backgroundColor

Type
color

borderBottomLeftRadius

Type
number

borderBottomRightRadius

Type
number

borderColor

Type
color

borderRadius

Type
number

borderTopLeftRadius

Type
number

borderTopRightRadius

Type
number

borderWidth

Type
number

opacity

Set an opacity value for the image. The number should be in the range from 0.0 to 1.0.

TypeDefault
number1.0

overflow

TypeDefault
enum('visible', 'hidden')'visible'

overlayColor
Android

When the image has rounded corners, specifying an overlayColor will cause the remaining space in the corners to be filled with a solid color. This is useful in cases which are not supported by the Android implementation of rounded corners:

  • Certain resize modes, such as 'contain'
  • Animated GIFs

A typical way to use this prop is with images displayed on a solid background and setting the overlayColor to the same color as the background.

For details of how this works under the hood, see Fresco documentation.

Type
string

resizeMode

TypeDefault
enum('cover', 'contain', 'stretch', 'repeat', 'center')'cover'

tintColor

Changes the color of all the non-transparent pixels to the tintColor.

Type
color
Edit this page
Last updated on
- + diff --git a/docs/next/image.html b/docs/next/image.html index 81245215879..4a62154c980 100644 --- a/docs/next/image.html +++ b/docs/next/image.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// For WebP support, without animations
implementation 'com.facebook.fresco:webpsupport:2.0.0'
}

Reference

Props

accessible

When true, indicates the image is an accessibility element.

TypeDefault
boolfalse

accessibilityLabel

The text that's read by the screen reader when the user interacts with the image.

Type
string

blurRadius

blurRadius: the blur radius of the blur filter added to the image.

Type
number

Tip : IOS you will need to increase blurRadius more than 5

capInsets
iOS

When the image is resized, the corners of the size specified by capInsets will stay a fixed size, but the center content and borders of the image will be stretched. This is useful for creating resizable rounded buttons, shadows, and other resizable assets. More info in the official Apple documentation.

Type
Rect

defaultSource

A static image to display while loading the image source.

Type
ImageSource

Note: On Android, the default source prop is ignored on debug builds.

fadeDuration
Android

Fade animation duration in miliseconds.

TypeDefault
number300

loadingIndicatorSource

Similarly to source, this property represents the resource used to render the loading indicator for the image, displayed until image is ready to be displayed, typically after when it got downloaded from network.

Type
ImageSource (uri only), number

onError

Invoked on load error.

Type
function({ nativeEvent: { error } }) => void

onLayout

Invoked on mount and on layout changes.

Type
function(LayoutEvent) => void

onLoad

Invoked when load completes successfully.

Type
function(ImageLoadEvent) => void

onLoadEnd

Invoked when load either succeeds or fails.

Type
function() => void

onLoadStart

Invoked on load start.

Example: onLoadStart={() => this.setState({loading: true})}

Type
function() => void

onPartialLoad
iOS

Invoked when a partial load of the image is complete. The definition of what constitutes a "partial load" is loader specific though this is meant for progressive JPEG loads.

Type
function() => void

onProgress

Invoked on download progress.

Type
function({ nativeEvent: { loaded, total } }) => void

progressiveRenderingEnabled
Android

When true, enables progressive jpeg streaming - https://frescolib.org/docs/progressive-jpegs.

TypeDefault
boolfalse

resizeMethod
Android

The mechanism that should be used to resize the image when the image's dimensions differ from the image view's dimensions. Defaults to auto.

More details about resize and scale can be found at http://frescolib.org/docs/resizing.

TypeDefault
enum('auto', 'resize', 'scale')'auto'

resizeMode

Determines how to resize the image when the frame doesn't match the raw image dimensions. Defaults to cover.

TypeDefault
enum('cover', 'contain', 'stretch', 'repeat', 'center')'cover'

source

The image source (either a remote URL or a local file resource).

This prop can also contain several remote URLs, specified together with their width and height and potentially with scale/other URI arguments. The native side will then choose the best uri to display based on the measured size of the image container. A cache property can be added to control how networked request interacts with the local cache. (For more information see Cache Control for Images).

The currently supported formats are png, jpg, jpeg, bmp, gif, webp, psd (iOS only). In addition, iOS supports several RAW image formats. Refer to Apple's documentation for the current list of supported camera models (for iOS 12, see https://support.apple.com/en-ca/HT208967).

Type
ImageSource

style

Type
Image Style Props, Layout Props, Shadow Props, Transforms

testID

A unique identifier for this element to be used in UI Automation testing scripts.

Type
string

Methods

abortPrefetch()
Android

Image.abortPrefetch(requestId);

Abort prefetch request.

Parameters:

NameTypeDescription
requestId
Required
numberRequest id as returned by prefetch().

getSize()

Image.getSize(uri, success, [failure]);

Retrieve the width and height (in pixels) of an image prior to displaying it. This method can fail if the image cannot be found, or fails to download.

In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API.

Parameters:

Name
TypeDescription
uri
Required
stringThe location of the image.
success
Required
functionThe function that will be called if the image was successfully found and width and height retrieved.
failurefunctionThe function that will be called if there was an error, such as failing to retrieve the image.

getSizeWithHeaders()

Image.getSizeWithHeaders(uri, headers, success, [failure]);

Retrieve the width and height (in pixels) of an image prior to displaying it with the ability to provide the headers for the request. This method can fail if the image cannot be found, or fails to download. It also does not work for static image resources.

In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API.

Parameters:

Name
TypeDescription
uri
Required
stringThe location of the image.
headers
Required
objectThe headers for the request.
success
Required
functionThe function that will be called if the image was successfully found and width and height retrieved.
failurefunctionThe function that will be called if there was an error, such as failing to retrieve the image.

prefetch()

await Image.prefetch(url);

Prefetches a remote image for later use by downloading it to the disk cache. Returns a promise which resolves to a boolean.

Parameters:

NameTypeDescription
url
Required
stringThe remote location of the image.
callbackfunction
Android
The function that will be called with the requestId.

queryCache()

await Image.queryCache(urls);

Perform cache interrogation. Returns a promise which resolves to a mapping from URL to cache status, such as "disk", "memory" or "disk/memory". If a requested URL is not in the mapping, it means it's not in the cache.

Parameters:

NameTypeDescription
urls
Required
arrayList of image URLs to check the cache for.

resolveAssetSource()

Image.resolveAssetSource(source);

Resolves an asset reference into an object which has the properties uri, width, and height.

Parameters:

Name
TypeDescription
source
Required
ImageSource, numberA number (opaque type returned by require('./foo.png')) or an ImageSource.

Type Definitions

ImageCacheEnum
iOS

Enum which can be used to set the cache handling or stategy for the potentially cached responses.

TypeDefault
enum('default', 'reload', 'force-cache', 'only-if-cached')'default'

ImageLoadEvent

Object returned in the onLoad callback.

Type
object

Properties:

NameTypeDescription
widthnumberThe width of loaded image.
heightnumberThe height of loaded image.
uristringA string representing the resource identifier for the image.

ImageSource

Type
object, array of objects, number

Properties (if passing as object or array of objects):

Name
TypeDescription
uristringA string representing the resource identifier for the image, which could be an http address, a local file path, or the name of a static image resource.
widthnumberCan be specified if known at build time, in which case the value will be used to set the default <Image/> component dimension.
heightnumberCan be specified if known at build time, in which case the value will be used to set the default <Image/> component dimension.
scalenumberUsed to indicate the scale factor of the image. Defaults to 1.0 if unspecified, meaning that one image pixel equates to one display point / DIP.
bundle
iOS
stringThe iOS asset bundle which the image is included in. This will default to [NSBundle mainBundle] if not set.
methodstringThe HTTP Method to use. Defaults to 'GET' if not specified.
headersobjectAn object representing the HTTP headers to send along with the request for a remote image.
bodystringThe HTTP body to send with the request. This must be a valid UTF-8 string, and will be sent exactly as specified, with no additional encoding (e.g. URL-escaping or base64) applied.
cache
iOS
ImageCacheEnumDetermines how the requests handles potentially cached responses.

If passing a number:

Edit this page
Last updated on
- + diff --git a/docs/next/image/index.html b/docs/next/image/index.html index 81245215879..4a62154c980 100644 --- a/docs/next/image/index.html +++ b/docs/next/image/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// For WebP support, without animations
implementation 'com.facebook.fresco:webpsupport:2.0.0'
}

Reference

Props

accessible

When true, indicates the image is an accessibility element.

TypeDefault
boolfalse

accessibilityLabel

The text that's read by the screen reader when the user interacts with the image.

Type
string

blurRadius

blurRadius: the blur radius of the blur filter added to the image.

Type
number

Tip : IOS you will need to increase blurRadius more than 5

capInsets
iOS

When the image is resized, the corners of the size specified by capInsets will stay a fixed size, but the center content and borders of the image will be stretched. This is useful for creating resizable rounded buttons, shadows, and other resizable assets. More info in the official Apple documentation.

Type
Rect

defaultSource

A static image to display while loading the image source.

Type
ImageSource

Note: On Android, the default source prop is ignored on debug builds.

fadeDuration
Android

Fade animation duration in miliseconds.

TypeDefault
number300

loadingIndicatorSource

Similarly to source, this property represents the resource used to render the loading indicator for the image, displayed until image is ready to be displayed, typically after when it got downloaded from network.

Type
ImageSource (uri only), number

onError

Invoked on load error.

Type
function({ nativeEvent: { error } }) => void

onLayout

Invoked on mount and on layout changes.

Type
function(LayoutEvent) => void

onLoad

Invoked when load completes successfully.

Type
function(ImageLoadEvent) => void

onLoadEnd

Invoked when load either succeeds or fails.

Type
function() => void

onLoadStart

Invoked on load start.

Example: onLoadStart={() => this.setState({loading: true})}

Type
function() => void

onPartialLoad
iOS

Invoked when a partial load of the image is complete. The definition of what constitutes a "partial load" is loader specific though this is meant for progressive JPEG loads.

Type
function() => void

onProgress

Invoked on download progress.

Type
function({ nativeEvent: { loaded, total } }) => void

progressiveRenderingEnabled
Android

When true, enables progressive jpeg streaming - https://frescolib.org/docs/progressive-jpegs.

TypeDefault
boolfalse

resizeMethod
Android

The mechanism that should be used to resize the image when the image's dimensions differ from the image view's dimensions. Defaults to auto.

More details about resize and scale can be found at http://frescolib.org/docs/resizing.

TypeDefault
enum('auto', 'resize', 'scale')'auto'

resizeMode

Determines how to resize the image when the frame doesn't match the raw image dimensions. Defaults to cover.

TypeDefault
enum('cover', 'contain', 'stretch', 'repeat', 'center')'cover'

source

The image source (either a remote URL or a local file resource).

This prop can also contain several remote URLs, specified together with their width and height and potentially with scale/other URI arguments. The native side will then choose the best uri to display based on the measured size of the image container. A cache property can be added to control how networked request interacts with the local cache. (For more information see Cache Control for Images).

The currently supported formats are png, jpg, jpeg, bmp, gif, webp, psd (iOS only). In addition, iOS supports several RAW image formats. Refer to Apple's documentation for the current list of supported camera models (for iOS 12, see https://support.apple.com/en-ca/HT208967).

Type
ImageSource

style

Type
Image Style Props, Layout Props, Shadow Props, Transforms

testID

A unique identifier for this element to be used in UI Automation testing scripts.

Type
string

Methods

abortPrefetch()
Android

Image.abortPrefetch(requestId);

Abort prefetch request.

Parameters:

NameTypeDescription
requestId
Required
numberRequest id as returned by prefetch().

getSize()

Image.getSize(uri, success, [failure]);

Retrieve the width and height (in pixels) of an image prior to displaying it. This method can fail if the image cannot be found, or fails to download.

In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API.

Parameters:

Name
TypeDescription
uri
Required
stringThe location of the image.
success
Required
functionThe function that will be called if the image was successfully found and width and height retrieved.
failurefunctionThe function that will be called if there was an error, such as failing to retrieve the image.

getSizeWithHeaders()

Image.getSizeWithHeaders(uri, headers, success, [failure]);

Retrieve the width and height (in pixels) of an image prior to displaying it with the ability to provide the headers for the request. This method can fail if the image cannot be found, or fails to download. It also does not work for static image resources.

In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API.

Parameters:

Name
TypeDescription
uri
Required
stringThe location of the image.
headers
Required
objectThe headers for the request.
success
Required
functionThe function that will be called if the image was successfully found and width and height retrieved.
failurefunctionThe function that will be called if there was an error, such as failing to retrieve the image.

prefetch()

await Image.prefetch(url);

Prefetches a remote image for later use by downloading it to the disk cache. Returns a promise which resolves to a boolean.

Parameters:

NameTypeDescription
url
Required
stringThe remote location of the image.
callbackfunction
Android
The function that will be called with the requestId.

queryCache()

await Image.queryCache(urls);

Perform cache interrogation. Returns a promise which resolves to a mapping from URL to cache status, such as "disk", "memory" or "disk/memory". If a requested URL is not in the mapping, it means it's not in the cache.

Parameters:

NameTypeDescription
urls
Required
arrayList of image URLs to check the cache for.

resolveAssetSource()

Image.resolveAssetSource(source);

Resolves an asset reference into an object which has the properties uri, width, and height.

Parameters:

Name
TypeDescription
source
Required
ImageSource, numberA number (opaque type returned by require('./foo.png')) or an ImageSource.

Type Definitions

ImageCacheEnum
iOS

Enum which can be used to set the cache handling or stategy for the potentially cached responses.

TypeDefault
enum('default', 'reload', 'force-cache', 'only-if-cached')'default'

ImageLoadEvent

Object returned in the onLoad callback.

Type
object

Properties:

NameTypeDescription
widthnumberThe width of loaded image.
heightnumberThe height of loaded image.
uristringA string representing the resource identifier for the image.

ImageSource

Type
object, array of objects, number

Properties (if passing as object or array of objects):

Name
TypeDescription
uristringA string representing the resource identifier for the image, which could be an http address, a local file path, or the name of a static image resource.
widthnumberCan be specified if known at build time, in which case the value will be used to set the default <Image/> component dimension.
heightnumberCan be specified if known at build time, in which case the value will be used to set the default <Image/> component dimension.
scalenumberUsed to indicate the scale factor of the image. Defaults to 1.0 if unspecified, meaning that one image pixel equates to one display point / DIP.
bundle
iOS
stringThe iOS asset bundle which the image is included in. This will default to [NSBundle mainBundle] if not set.
methodstringThe HTTP Method to use. Defaults to 'GET' if not specified.
headersobjectAn object representing the HTTP headers to send along with the request for a remote image.
bodystringThe HTTP body to send with the request. This must be a valid UTF-8 string, and will be sent exactly as specified, with no additional encoding (e.g. URL-escaping or base64) applied.
cache
iOS
ImageCacheEnumDetermines how the requests handles potentially cached responses.

If passing a number:

Edit this page
Last updated on
- + diff --git a/docs/next/imagebackground.html b/docs/next/imagebackground.html index 3a1fcb31ac0..69d400296e0 100644 --- a/docs/next/imagebackground.html +++ b/docs/next/imagebackground.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

ImageBackground

A common feature request from developers familiar with the web is background-image. To handle this use case, you can use the <ImageBackground> component, which has the same props as <Image>, and add whatever children to it you would like to layer on top of it.

You might not want to use <ImageBackground> in some cases, since the implementation is basic. Refer to <ImageBackground>'s source code for more insight, and create your own custom component when needed.

Note that you must specify some width and height style attributes.

Example

Reference

Props

Image Props

Inherits Image Props.

imageStyle

Type
Image Style

imageRef

Allows to set a reference to the inner Image component

Type
Ref

style

Type
View Style
Edit this page
Last updated on
- + diff --git a/docs/next/imagebackground/index.html b/docs/next/imagebackground/index.html index 3a1fcb31ac0..69d400296e0 100644 --- a/docs/next/imagebackground/index.html +++ b/docs/next/imagebackground/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

ImageBackground

A common feature request from developers familiar with the web is background-image. To handle this use case, you can use the <ImageBackground> component, which has the same props as <Image>, and add whatever children to it you would like to layer on top of it.

You might not want to use <ImageBackground> in some cases, since the implementation is basic. Refer to <ImageBackground>'s source code for more insight, and create your own custom component when needed.

Note that you must specify some width and height style attributes.

Example

Reference

Props

Image Props

Inherits Image Props.

imageStyle

Type
Image Style

imageRef

Allows to set a reference to the inner Image component

Type
Ref

style

Type
View Style
Edit this page
Last updated on
- + diff --git a/docs/next/imageeditor.html b/docs/next/imageeditor.html index 342209f8a93..cd7dcbeabb2 100644 --- a/docs/next/imageeditor.html +++ b/docs/next/imageeditor.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 ImageEditor

Deprecated. Use one of the community packages instead.

Reference

Methods

cropImage()

static cropImage(uri, cropData, success, failure)

Crop the image specified by the URI param. If URI points to a remote image, it will be downloaded automatically. If the image cannot be loaded/downloaded, the failure callback will be called.

If the cropping process is successful, the resultant cropped image will be stored in the ImageStore, and the URI returned in the success callback will point to the image in the store. Remember to delete the cropped image from the ImageStore when you are done with it.

cropData

  • offset - The top-left corner of the cropped image, specified in the original image's coordinate space
  • size - Size (dimensions) of the cropped image
  • displaySize (optional) - Size to which you want to scale the cropped image
  • resizeMode (optional) - Resizing mode to use when scaling the image
cropData = {
offset: { x: number, y: number },
size: { width: number, height: number },
displaySize: { width: number, height: number },
resizeMode: 'contain/cover/stretch'
};
Edit this page
Last updated on
- + diff --git a/docs/next/imageeditor/index.html b/docs/next/imageeditor/index.html index 342209f8a93..cd7dcbeabb2 100644 --- a/docs/next/imageeditor/index.html +++ b/docs/next/imageeditor/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 ImageEditor

Deprecated. Use one of the community packages instead.

Reference

Methods

cropImage()

static cropImage(uri, cropData, success, failure)

Crop the image specified by the URI param. If URI points to a remote image, it will be downloaded automatically. If the image cannot be loaded/downloaded, the failure callback will be called.

If the cropping process is successful, the resultant cropped image will be stored in the ImageStore, and the URI returned in the success callback will point to the image in the store. Remember to delete the cropped image from the ImageStore when you are done with it.

cropData

  • offset - The top-left corner of the cropped image, specified in the original image's coordinate space
  • size - Size (dimensions) of the cropped image
  • displaySize (optional) - Size to which you want to scale the cropped image
  • resizeMode (optional) - Resizing mode to use when scaling the image
cropData = {
offset: { x: number, y: number },
size: { width: number, height: number },
displaySize: { width: number, height: number },
resizeMode: 'contain/cover/stretch'
};
Edit this page
Last updated on
- + diff --git a/docs/next/imagepickerios.html b/docs/next/imagepickerios.html index 5fbd327502e..0ca1ef9da2f 100644 --- a/docs/next/imagepickerios.html +++ b/docs/next/imagepickerios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 ImagePickerIOS

Deprecated. Use one of the community packages instead.

Reference

Methods

canRecordVideos()

static canRecordVideos(callback)

canUseCamera()

static canUseCamera(callback)

openCameraDialog()

static openCameraDialog(config, successCallback, cancelCallback)

Parameters:

NameTypeRequiredDescription
configobjectNoSee below.
successCallbackfunctionNoSee below.
cancelCallbackfunctionNoSee below.

config is an object containing:

  • videoMode : An optional boolean value that defaults to false.

successCallback is an optional callback function that's invoked when the select dialog is opened successfully. It will include the following data:

  • [string, number, number]

cancelCallback is an optional callback function that's invoked when the camera dialog is canceled.

openSelectDialog()

static openSelectDialog(config, successCallback, cancelCallback)

Parameters:

NameTypeRequiredDescription
configobjectNoSee below.
successCallbackfunctionNoSee below.
cancelCallbackfunctionNoSee below.

config is an object containing:

  • showImages : An optional boolean value that defaults to false.
  • showVideos: An optional boolean value that defaults to false.

successCallback is an optional callback function that's invoked when the select dialog is opened successfully. It will include the following data:

  • [string, number, number]

cancelCallback is an optional callback function that's invoked when the select dialog is canceled.

Edit this page
Last updated on
- + diff --git a/docs/next/imagepickerios/index.html b/docs/next/imagepickerios/index.html index 5fbd327502e..0ca1ef9da2f 100644 --- a/docs/next/imagepickerios/index.html +++ b/docs/next/imagepickerios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 ImagePickerIOS

Deprecated. Use one of the community packages instead.

Reference

Methods

canRecordVideos()

static canRecordVideos(callback)

canUseCamera()

static canUseCamera(callback)

openCameraDialog()

static openCameraDialog(config, successCallback, cancelCallback)

Parameters:

NameTypeRequiredDescription
configobjectNoSee below.
successCallbackfunctionNoSee below.
cancelCallbackfunctionNoSee below.

config is an object containing:

  • videoMode : An optional boolean value that defaults to false.

successCallback is an optional callback function that's invoked when the select dialog is opened successfully. It will include the following data:

  • [string, number, number]

cancelCallback is an optional callback function that's invoked when the camera dialog is canceled.

openSelectDialog()

static openSelectDialog(config, successCallback, cancelCallback)

Parameters:

NameTypeRequiredDescription
configobjectNoSee below.
successCallbackfunctionNoSee below.
cancelCallbackfunctionNoSee below.

config is an object containing:

  • showImages : An optional boolean value that defaults to false.
  • showVideos: An optional boolean value that defaults to false.

successCallback is an optional callback function that's invoked when the select dialog is opened successfully. It will include the following data:

  • [string, number, number]

cancelCallback is an optional callback function that's invoked when the select dialog is canceled.

Edit this page
Last updated on
- + diff --git a/docs/next/images.html b/docs/next/images.html index 827abedbd87..6134ad3384b 100644 --- a/docs/next/images.html +++ b/docs/next/images.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// BAD
<Image source={{uri: 'https://reactjs.org/logo-og.png'}} />

Network Requests for Images

If you would like to set such things as the HTTP-Verb, Headers or a Body along with the image request, you may do this by defining these properties on the source object:

<Image
source={{
uri: 'https://reactjs.org/logo-og.png',
method: 'POST',
headers: {
Pragma: 'no-cache'
},
body: 'Your Body goes here'
}}
style={{ width: 400, height: 400 }}
/>

Uri Data Images

Sometimes, you might be getting encoded image data from a REST API call. You can use the 'data:' uri scheme to use these images. Same as for network resources, you will need to manually specify the dimensions of your image.

This is recommended for very small and dynamic images only, like icons in a list from a DB.

// include at least width and height!
<Image
style={{
width: 51,
height: 51,
resizeMode: 'contain'
}}
source={{
uri:
'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADMAAAAzCAYAAAA6oTAqAAAAEXRFWHRTb2Z0d2FyZQBwbmdjcnVzaEB1SfMAAABQSURBVGje7dSxCQBACARB+2/ab8BEeQNhFi6WSYzYLYudDQYGBgYGBgYGBgYGBgYGBgZmcvDqYGBgmhivGQYGBgYGBgYGBgYGBgYGBgbmQw+P/eMrC5UTVAAAAABJRU5ErkJggg=='
}}
/>

Cache Control (iOS Only)

In some cases you might only want to display an image if it is already in the local cache, i.e. a low resolution placeholder until a higher resolution is available. In other cases you do not care if the image is outdated and are willing to display an outdated image to save bandwidth. The cache source property gives you control over how the network layer interacts with the cache.

<Image
source={{
uri: 'https://reactjs.org/logo-og.png',
cache: 'only-if-cached'
}}
style={{ width: 400, height: 400 }}
/>

Local Filesystem Images

See CameraRoll for an example of using local resources that are outside of Images.xcassets.

Best Camera Roll Image

iOS saves multiple sizes for the same image in your Camera Roll, it is very important to pick the one that's as close as possible for performance reasons. You wouldn't want to use the full quality 3264x2448 image as source when displaying a 200x200 thumbnail. If there's an exact match, React Native will pick it, otherwise it's going to use the first one that's at least 50% bigger in order to avoid blur when resizing from a close size. All of this is done by default so you don't have to worry about writing the tedious (and error prone) code to do it yourself.

Why Not Automatically Size Everything?

In the browser if you don't give a size to an image, the browser is going to render a 0x0 element, download the image, and then render the image based with the correct size. The big issue with this behavior is that your UI is going to jump all around as images load, this makes for a very bad user experience.

In React Native this behavior is intentionally not implemented. It is more work for the developer to know the dimensions (or aspect ratio) of the remote image in advance, but we believe that it leads to a better user experience. Static images loaded from the app bundle via the require('./my-icon.png') syntax can be automatically sized because their dimensions are available immediately at the time of mounting.

For example, the result of require('./my-icon.png') might be:

{"__packager_asset":true,"uri":"my-icon.png","width":591,"height":573}

Source as an object

In React Native, one interesting decision is that the src attribute is named source and doesn't take a string but an object with a uri attribute.

<Image source={{ uri: 'something.jpg' }} />

On the infrastructure side, the reason is that it allows us to attach metadata to this object. For example if you are using require('./my-icon.png'), then we add information about its actual location and size (don't rely on this fact, it might change in the future!). This is also future proofing, for example we may want to support sprites at some point, instead of outputting {uri: ...}, we can output {uri: ..., crop: {left: 10, top: 50, width: 20, height: 40}} and transparently support spriting on all the existing call sites.

On the user side, this lets you annotate the object with useful attributes such as the dimension of the image in order to compute the size it's going to be displayed in. Feel free to use it as your data structure to store more information about your image.

Background Image via Nesting

A common feature request from developers familiar with the web is background-image. To handle this use case, you can use the <ImageBackground> component, which has the same props as <Image>, and add whatever children to it you would like to layer on top of it.

You might not want to use <ImageBackground> in some cases, since the implementation is basic. Refer to <ImageBackground>'s documentation for more insight, and create your own custom component when needed.

return (
<ImageBackground source={...} style={{width: '100%', height: '100%'}}>
<Text>Inside</Text>
</ImageBackground>
);

Note that you must specify some width and height style attributes.

iOS Border Radius Styles

Please note that the following corner specific, border radius style properties are currently ignored by iOS's image component:

Off-thread Decoding

Image decoding can take more than a frame-worth of time. This is one of the major sources of frame drops on the web because decoding is done in the main thread. In React Native, image decoding is done in a different thread. In practice, you already need to handle the case when the image is not downloaded yet, so displaying the placeholder for a few more frames while it is decoding does not require any code change.

Edit this page
Last updated on
- + diff --git a/docs/next/images/index.html b/docs/next/images/index.html index 827abedbd87..6134ad3384b 100644 --- a/docs/next/images/index.html +++ b/docs/next/images/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// BAD
<Image source={{uri: 'https://reactjs.org/logo-og.png'}} />

Network Requests for Images

If you would like to set such things as the HTTP-Verb, Headers or a Body along with the image request, you may do this by defining these properties on the source object:

<Image
source={{
uri: 'https://reactjs.org/logo-og.png',
method: 'POST',
headers: {
Pragma: 'no-cache'
},
body: 'Your Body goes here'
}}
style={{ width: 400, height: 400 }}
/>

Uri Data Images

Sometimes, you might be getting encoded image data from a REST API call. You can use the 'data:' uri scheme to use these images. Same as for network resources, you will need to manually specify the dimensions of your image.

This is recommended for very small and dynamic images only, like icons in a list from a DB.

// include at least width and height!
<Image
style={{
width: 51,
height: 51,
resizeMode: 'contain'
}}
source={{
uri:
'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADMAAAAzCAYAAAA6oTAqAAAAEXRFWHRTb2Z0d2FyZQBwbmdjcnVzaEB1SfMAAABQSURBVGje7dSxCQBACARB+2/ab8BEeQNhFi6WSYzYLYudDQYGBgYGBgYGBgYGBgYGBgZmcvDqYGBgmhivGQYGBgYGBgYGBgYGBgYGBgbmQw+P/eMrC5UTVAAAAABJRU5ErkJggg=='
}}
/>

Cache Control (iOS Only)

In some cases you might only want to display an image if it is already in the local cache, i.e. a low resolution placeholder until a higher resolution is available. In other cases you do not care if the image is outdated and are willing to display an outdated image to save bandwidth. The cache source property gives you control over how the network layer interacts with the cache.

<Image
source={{
uri: 'https://reactjs.org/logo-og.png',
cache: 'only-if-cached'
}}
style={{ width: 400, height: 400 }}
/>

Local Filesystem Images

See CameraRoll for an example of using local resources that are outside of Images.xcassets.

Best Camera Roll Image

iOS saves multiple sizes for the same image in your Camera Roll, it is very important to pick the one that's as close as possible for performance reasons. You wouldn't want to use the full quality 3264x2448 image as source when displaying a 200x200 thumbnail. If there's an exact match, React Native will pick it, otherwise it's going to use the first one that's at least 50% bigger in order to avoid blur when resizing from a close size. All of this is done by default so you don't have to worry about writing the tedious (and error prone) code to do it yourself.

Why Not Automatically Size Everything?

In the browser if you don't give a size to an image, the browser is going to render a 0x0 element, download the image, and then render the image based with the correct size. The big issue with this behavior is that your UI is going to jump all around as images load, this makes for a very bad user experience.

In React Native this behavior is intentionally not implemented. It is more work for the developer to know the dimensions (or aspect ratio) of the remote image in advance, but we believe that it leads to a better user experience. Static images loaded from the app bundle via the require('./my-icon.png') syntax can be automatically sized because their dimensions are available immediately at the time of mounting.

For example, the result of require('./my-icon.png') might be:

{"__packager_asset":true,"uri":"my-icon.png","width":591,"height":573}

Source as an object

In React Native, one interesting decision is that the src attribute is named source and doesn't take a string but an object with a uri attribute.

<Image source={{ uri: 'something.jpg' }} />

On the infrastructure side, the reason is that it allows us to attach metadata to this object. For example if you are using require('./my-icon.png'), then we add information about its actual location and size (don't rely on this fact, it might change in the future!). This is also future proofing, for example we may want to support sprites at some point, instead of outputting {uri: ...}, we can output {uri: ..., crop: {left: 10, top: 50, width: 20, height: 40}} and transparently support spriting on all the existing call sites.

On the user side, this lets you annotate the object with useful attributes such as the dimension of the image in order to compute the size it's going to be displayed in. Feel free to use it as your data structure to store more information about your image.

Background Image via Nesting

A common feature request from developers familiar with the web is background-image. To handle this use case, you can use the <ImageBackground> component, which has the same props as <Image>, and add whatever children to it you would like to layer on top of it.

You might not want to use <ImageBackground> in some cases, since the implementation is basic. Refer to <ImageBackground>'s documentation for more insight, and create your own custom component when needed.

return (
<ImageBackground source={...} style={{width: '100%', height: '100%'}}>
<Text>Inside</Text>
</ImageBackground>
);

Note that you must specify some width and height style attributes.

iOS Border Radius Styles

Please note that the following corner specific, border radius style properties are currently ignored by iOS's image component:

Off-thread Decoding

Image decoding can take more than a frame-worth of time. This is one of the major sources of frame drops on the web because decoding is done in the main thread. In React Native, image decoding is done in a different thread. In practice, you already need to handle the case when the image is not downloaded yet, so displaying the placeholder for a few more frames while it is decoding does not require any code change.

Edit this page
Last updated on
- + diff --git a/docs/next/improvingux.html b/docs/next/improvingux.html index c729be16011..5eeafd68475 100644 --- a/docs/next/improvingux.html +++ b/docs/next/improvingux.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Improving User Experience

Configure text inputs

Entering text on touch phone is a challenge - small screen, software keyboard. But based on what kind of data you need, you can make it easier by properly configuring the text inputs:

  • Focus the first field automatically
  • Use placeholder text as an example of expected data format
  • Enable or disable autocapitalization and autocorrect
  • Choose keyboard type (e.g. email, numeric)
  • Make sure the return button focuses the next field or submits the form

Check out TextInput docs for more configuration options.

Try it on your phone

Manage layout when keyboard is visible

Software keyboard takes almost half of the screen. If you have interactive elements that can get covered by the keyboard, make sure they are still accessible by using the KeyboardAvoidingView component.

Try it on your phone

Make tappable areas larger

On mobile phones it's hard to be very precise when pressing buttons. Make sure all interactive elements are 44x44 or larger. One way to do this is to leave enough space for the element, padding, minWidth and minHeight style values can be useful for that. Alternatively, you can use hitSlop prop to increase interactive area without affecting the layout. Here's a demo:

Try it on your phone

Use Android Ripple

Android API 21+ uses the material design ripple to provide user with feedback when they touch an interactable area on the screen. React Native exposes this through the TouchableNativeFeedback component. Using this touchable effect instead of opacity or highlight will often make your app feel much more fitting on the platform. That said, you need to be careful when using it because it doesn't work on iOS or on Android API < 21, so you will need to fallback to using one of the other Touchable components on iOS. You can use a library like react-native-platform-touchable to handle the platform differences for you.

Try it on your phone

Screen orientation lock

Multiple screen orientations should work fine by default unless you're using Dimensions API and don't handle orientation changes. If you don't want to support multiple screen orientations, you can lock the screen orientation to either portrait or landscape.

On iOS, in the General tab and Deployment Info section of Xcode enable the Device Orientation you want to support (ensure you have selected iPhone from the Devices menu when making the changes). For Android, open the AndroidManifest.xml file and within the activity element add 'android:screenOrientation="portrait"' to lock to portrait or 'android:screenOrientation="landscape"' to lock to landscape.

Learn more

Material Design and Human Interface Guidelines are great resources for learning more about designing for mobile platforms.

Edit this page
Last updated on
- + diff --git a/docs/next/improvingux/index.html b/docs/next/improvingux/index.html index c729be16011..5eeafd68475 100644 --- a/docs/next/improvingux/index.html +++ b/docs/next/improvingux/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Improving User Experience

Configure text inputs

Entering text on touch phone is a challenge - small screen, software keyboard. But based on what kind of data you need, you can make it easier by properly configuring the text inputs:

  • Focus the first field automatically
  • Use placeholder text as an example of expected data format
  • Enable or disable autocapitalization and autocorrect
  • Choose keyboard type (e.g. email, numeric)
  • Make sure the return button focuses the next field or submits the form

Check out TextInput docs for more configuration options.

Try it on your phone

Manage layout when keyboard is visible

Software keyboard takes almost half of the screen. If you have interactive elements that can get covered by the keyboard, make sure they are still accessible by using the KeyboardAvoidingView component.

Try it on your phone

Make tappable areas larger

On mobile phones it's hard to be very precise when pressing buttons. Make sure all interactive elements are 44x44 or larger. One way to do this is to leave enough space for the element, padding, minWidth and minHeight style values can be useful for that. Alternatively, you can use hitSlop prop to increase interactive area without affecting the layout. Here's a demo:

Try it on your phone

Use Android Ripple

Android API 21+ uses the material design ripple to provide user with feedback when they touch an interactable area on the screen. React Native exposes this through the TouchableNativeFeedback component. Using this touchable effect instead of opacity or highlight will often make your app feel much more fitting on the platform. That said, you need to be careful when using it because it doesn't work on iOS or on Android API < 21, so you will need to fallback to using one of the other Touchable components on iOS. You can use a library like react-native-platform-touchable to handle the platform differences for you.

Try it on your phone

Screen orientation lock

Multiple screen orientations should work fine by default unless you're using Dimensions API and don't handle orientation changes. If you don't want to support multiple screen orientations, you can lock the screen orientation to either portrait or landscape.

On iOS, in the General tab and Deployment Info section of Xcode enable the Device Orientation you want to support (ensure you have selected iPhone from the Devices menu when making the changes). For Android, open the AndroidManifest.xml file and within the activity element add 'android:screenOrientation="portrait"' to lock to portrait or 'android:screenOrientation="landscape"' to lock to landscape.

Learn more

Material Design and Human Interface Guidelines are great resources for learning more about designing for mobile platforms.

Edit this page
Last updated on
- + diff --git a/docs/next/inputaccessoryview.html b/docs/next/inputaccessoryview.html index 43c886fb70c..72352d97bb1 100644 --- a/docs/next/inputaccessoryview.html +++ b/docs/next/inputaccessoryview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

InputAccessoryView

A component which enables customization of the keyboard input accessory view on iOS. The input accessory view is displayed above the keyboard whenever a TextInput has focus. This component can be used to create custom toolbars.

To use this component wrap your custom toolbar with the InputAccessoryView component, and set a nativeID. Then, pass that nativeID as the inputAccessoryViewID of whatever TextInput you desire. A basic example:

This component can also be used to create sticky text inputs (text inputs which are anchored to the top of the keyboard). To do this, wrap a TextInput with the InputAccessoryView component, and don't set a nativeID. For an example, look at InputAccessoryViewExample.js.

Reference

Props

backgroundColor

Type
color

nativeID

An ID which is used to associate this InputAccessoryView to specified TextInput(s).

Type
string

style

Type
View Style

Known issues

Edit this page
Last updated on
- + diff --git a/docs/next/inputaccessoryview/index.html b/docs/next/inputaccessoryview/index.html index 43c886fb70c..72352d97bb1 100644 --- a/docs/next/inputaccessoryview/index.html +++ b/docs/next/inputaccessoryview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

InputAccessoryView

A component which enables customization of the keyboard input accessory view on iOS. The input accessory view is displayed above the keyboard whenever a TextInput has focus. This component can be used to create custom toolbars.

To use this component wrap your custom toolbar with the InputAccessoryView component, and set a nativeID. Then, pass that nativeID as the inputAccessoryViewID of whatever TextInput you desire. A basic example:

This component can also be used to create sticky text inputs (text inputs which are anchored to the top of the keyboard). To do this, wrap a TextInput with the InputAccessoryView component, and don't set a nativeID. For an example, look at InputAccessoryViewExample.js.

Reference

Props

backgroundColor

Type
color

nativeID

An ID which is used to associate this InputAccessoryView to specified TextInput(s).

Type
string

style

Type
View Style

Known issues

Edit this page
Last updated on
- + diff --git a/docs/next/integration-with-android-fragment.html b/docs/next/integration-with-android-fragment.html index f88a7f8e89c..f3668305de3 100644 --- a/docs/next/integration-with-android-fragment.html +++ b/docs/next/integration-with-android-fragment.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
import com.facebook.react.ReactApplication;
import com.facebook.react.ReactNativeHost;
import com.facebook.react.ReactPackage;
import com.facebook.react.shell.MainReactPackage;
import com.facebook.soloader.SoLoader;

Perform a "Sync Project files with Gradle" operation.

Step 5. Test your integration

Make sure you run yarn to install your react-native dependencies and run yarn native to start the metro bundler. Run your android app in Android Studio and it should load the JavaScript code from the development server and display it in your React Native Fragment in the Activity.

Step 6. Additional setup - Native modules

You may need to call out to existing Java code from your react component. Native modules allow you to call out to native code and run methods in your native app. Follow the setup here native-modules-android

Edit this page
Last updated on
- + diff --git a/docs/next/integration-with-android-fragment/index.html b/docs/next/integration-with-android-fragment/index.html index f88a7f8e89c..f3668305de3 100644 --- a/docs/next/integration-with-android-fragment/index.html +++ b/docs/next/integration-with-android-fragment/index.html @@ -19,7 +19,7 @@ - + @@ -42,7 +42,7 @@
import com.facebook.react.ReactApplication;
import com.facebook.react.ReactNativeHost;
import com.facebook.react.ReactPackage;
import com.facebook.react.shell.MainReactPackage;
import com.facebook.soloader.SoLoader;

Perform a "Sync Project files with Gradle" operation.

Step 5. Test your integration

Make sure you run yarn to install your react-native dependencies and run yarn native to start the metro bundler. Run your android app in Android Studio and it should load the JavaScript code from the development server and display it in your React Native Fragment in the Activity.

Step 6. Additional setup - Native modules

You may need to call out to existing Java code from your react component. Native modules allow you to call out to native code and run methods in your native app. Follow the setup here native-modules-android

Edit this page
Last updated on
- + diff --git a/docs/next/integration-with-existing-apps.html b/docs/next/integration-with-existing-apps.html index 4e9e7bb77c1..0ef1bf6999c 100644 --- a/docs/next/integration-with-existing-apps.html +++ b/docs/next/integration-with-existing-apps.html @@ -19,7 +19,7 @@ - + @@ -48,7 +48,7 @@
if (mReactInstanceManager != null) {
mReactInstanceManager.onHostDestroy(this);
}
if (mReactRootView != null) {
mReactRootView.unmountReactApplication();
}
}

We also need to pass back button events to React Native:

@Override
public void onBackPressed() {
if (mReactInstanceManager != null) {
mReactInstanceManager.onBackPressed();
} else {
super.onBackPressed();
}
}

This allows JavaScript to control what happens when the user presses the hardware back button (e.g. to implement navigation). When JavaScript doesn't handle the back button press, your invokeDefaultOnBackPressed method will be called. By default this finishes your Activity.

Finally, we need to hook up the dev menu. By default, this is activated by (rage) shaking the device, but this is not very useful in emulators. So we make it show when you press the hardware menu button (use Ctrl + M if you're using Android Studio emulator):

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
if (keyCode == KeyEvent.KEYCODE_MENU && mReactInstanceManager != null) {
mReactInstanceManager.showDevOptionsDialog();
return true;
}
return super.onKeyUp(keyCode, event);
}

Now your activity is ready to run some JavaScript code.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ yarn start
2. Run the app

Now build and run your Android app as normal.

Once you reach your React-powered activity inside the app, it should load the JavaScript code from the development server and display:

Screenshot

Creating a release build in Android Studio

You can use Android Studio to create your release builds too! It’s as quick as creating release builds of your previously-existing native Android app. There’s one additional step, which you’ll have to do before every release build. You need to execute the following to create a React Native bundle, which will be included with your native Android app:

$ npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/com/your-company-name/app-package-name/src/main/assets/index.android.bundle --assets-dest android/com/your-company-name/app-package-name/src/main/res/

Don’t forget to replace the paths with correct ones and create the assets folder if it doesn’t exist.

Now, create a release build of your native app from within Android Studio as usual and you should be good to go!

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/next/integration-with-existing-apps/index.html b/docs/next/integration-with-existing-apps/index.html index 4e9e7bb77c1..0ef1bf6999c 100644 --- a/docs/next/integration-with-existing-apps/index.html +++ b/docs/next/integration-with-existing-apps/index.html @@ -19,7 +19,7 @@ - + @@ -48,7 +48,7 @@
if (mReactInstanceManager != null) {
mReactInstanceManager.onHostDestroy(this);
}
if (mReactRootView != null) {
mReactRootView.unmountReactApplication();
}
}

We also need to pass back button events to React Native:

@Override
public void onBackPressed() {
if (mReactInstanceManager != null) {
mReactInstanceManager.onBackPressed();
} else {
super.onBackPressed();
}
}

This allows JavaScript to control what happens when the user presses the hardware back button (e.g. to implement navigation). When JavaScript doesn't handle the back button press, your invokeDefaultOnBackPressed method will be called. By default this finishes your Activity.

Finally, we need to hook up the dev menu. By default, this is activated by (rage) shaking the device, but this is not very useful in emulators. So we make it show when you press the hardware menu button (use Ctrl + M if you're using Android Studio emulator):

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
if (keyCode == KeyEvent.KEYCODE_MENU && mReactInstanceManager != null) {
mReactInstanceManager.showDevOptionsDialog();
return true;
}
return super.onKeyUp(keyCode, event);
}

Now your activity is ready to run some JavaScript code.

Test your integration

You have now done all the basic steps to integrate React Native with your current application. Now we will start the Metro bundler to build the index.bundle package and the server running on localhost to serve it.

1. Run the packager

To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:

$ yarn start
2. Run the app

Now build and run your Android app as normal.

Once you reach your React-powered activity inside the app, it should load the JavaScript code from the development server and display:

Screenshot

Creating a release build in Android Studio

You can use Android Studio to create your release builds too! It’s as quick as creating release builds of your previously-existing native Android app. There’s one additional step, which you’ll have to do before every release build. You need to execute the following to create a React Native bundle, which will be included with your native Android app:

$ npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/com/your-company-name/app-package-name/src/main/assets/index.android.bundle --assets-dest android/com/your-company-name/app-package-name/src/main/res/

Don’t forget to replace the paths with correct ones and create the assets folder if it doesn’t exist.

Now, create a release build of your native app from within Android Studio as usual and you should be good to go!

Now what?

At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.

Edit this page
Last updated on
- + diff --git a/docs/next/interactionmanager.html b/docs/next/interactionmanager.html index 061041c425e..0ea4c02bc32 100644 --- a/docs/next/interactionmanager.html +++ b/docs/next/interactionmanager.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

InteractionManager

InteractionManager allows long-running work to be scheduled after any interactions/animations have completed. In particular, this allows JavaScript animations to run smoothly.

Applications can schedule tasks to run after interactions with the following:

InteractionManager.runAfterInteractions(() => {
// ...long-running synchronous task...
});

Compare this to other scheduling alternatives:

  • requestAnimationFrame(): for code that animates a view over time.
  • setImmediate/setTimeout(): run code later, note this may delay animations.
  • runAfterInteractions(): run code later, without delaying active animations.

The touch handling system considers one or more active touches to be an 'interaction' and will delay runAfterInteractions() callbacks until all touches have ended or been cancelled.

InteractionManager also allows applications to register animations by creating an interaction 'handle' on animation start, and clearing it upon completion:

var handle = InteractionManager.createInteractionHandle();
// run animation... (`runAfterInteractions` tasks are queued)
// later, on animation completion:
InteractionManager.clearInteractionHandle(handle);
// queued tasks run if all handles were cleared

runAfterInteractions takes either a plain callback function, or a PromiseTask object with a gen method that returns a Promise. If a PromiseTask is supplied, then it is fully resolved (including asynchronous dependencies that also schedule more tasks via runAfterInteractions) before starting on the next task that might have been queued up synchronously earlier.

By default, queued tasks are executed together in a loop in one setImmediate batch. If setDeadline is called with a positive number, then tasks will only be executed until the deadline (in terms of js event loop run time) approaches, at which point execution will yield via setTimeout, allowing events such as touches to start interactions and block queued tasks from executing, making apps more responsive.

Example

Basic

Advanced

Note: InteractionManager.runAfterInteractions() is not working properly on web. It triggers immediately without waiting until the interaction is finished.

Reference

Methods

runAfterInteractions()

static runAfterInteractions(task)

Schedule a function to run after all interactions have completed. Returns a cancellable "promise".

createInteractionHandle()

static createInteractionHandle()

Notify manager that an interaction has started.

clearInteractionHandle()

static clearInteractionHandle(handle)

Notify manager that an interaction has completed.

setDeadline()

static setDeadline(deadline)

A positive number will use setTimeout to schedule any tasks after the eventLoopRunningTime hits the deadline value, otherwise all tasks will be executed in one setImmediate batch (default).

Edit this page
Last updated on
- + diff --git a/docs/next/interactionmanager/index.html b/docs/next/interactionmanager/index.html index 061041c425e..0ea4c02bc32 100644 --- a/docs/next/interactionmanager/index.html +++ b/docs/next/interactionmanager/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

InteractionManager

InteractionManager allows long-running work to be scheduled after any interactions/animations have completed. In particular, this allows JavaScript animations to run smoothly.

Applications can schedule tasks to run after interactions with the following:

InteractionManager.runAfterInteractions(() => {
// ...long-running synchronous task...
});

Compare this to other scheduling alternatives:

  • requestAnimationFrame(): for code that animates a view over time.
  • setImmediate/setTimeout(): run code later, note this may delay animations.
  • runAfterInteractions(): run code later, without delaying active animations.

The touch handling system considers one or more active touches to be an 'interaction' and will delay runAfterInteractions() callbacks until all touches have ended or been cancelled.

InteractionManager also allows applications to register animations by creating an interaction 'handle' on animation start, and clearing it upon completion:

var handle = InteractionManager.createInteractionHandle();
// run animation... (`runAfterInteractions` tasks are queued)
// later, on animation completion:
InteractionManager.clearInteractionHandle(handle);
// queued tasks run if all handles were cleared

runAfterInteractions takes either a plain callback function, or a PromiseTask object with a gen method that returns a Promise. If a PromiseTask is supplied, then it is fully resolved (including asynchronous dependencies that also schedule more tasks via runAfterInteractions) before starting on the next task that might have been queued up synchronously earlier.

By default, queued tasks are executed together in a loop in one setImmediate batch. If setDeadline is called with a positive number, then tasks will only be executed until the deadline (in terms of js event loop run time) approaches, at which point execution will yield via setTimeout, allowing events such as touches to start interactions and block queued tasks from executing, making apps more responsive.

Example

Basic

Advanced

Note: InteractionManager.runAfterInteractions() is not working properly on web. It triggers immediately without waiting until the interaction is finished.

Reference

Methods

runAfterInteractions()

static runAfterInteractions(task)

Schedule a function to run after all interactions have completed. Returns a cancellable "promise".

createInteractionHandle()

static createInteractionHandle()

Notify manager that an interaction has started.

clearInteractionHandle()

static clearInteractionHandle(handle)

Notify manager that an interaction has completed.

setDeadline()

static setDeadline(deadline)

A positive number will use setTimeout to schedule any tasks after the eventLoopRunningTime hits the deadline value, otherwise all tasks will be executed in one setImmediate batch (default).

Edit this page
Last updated on
- + diff --git a/docs/next/intro-react-native-components.html b/docs/next/intro-react-native-components.html index df5078ca168..22ef392b91a 100644 --- a/docs/next/intro-react-native-components.html +++ b/docs/next/intro-react-native-components.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Core Components and Native Components

React Native is an open source framework for building Android and iOS applications using React and the app platform’s native capabilities. With React Native, you use JavaScript to access your platform’s APIs as well as to describe the appearance and behavior of your UI using React components: bundles of reusable, nestable code. You can learn more about React in the next section. But first, let’s cover how components work in React Native.

Views and mobile development

In Android and iOS development, a view is the basic building block of UI: a small rectangular element on the screen which can be used to display text, images, or respond to user input. Even the smallest visual elements of an app, like a line of text or a button, are kinds of views. Some kinds of views can contain other views. It’s views all the way down!

Diagram of Android and iOS app showing them both built on top of atomic elements called views.
Just a sampling of the many views used in Android and iOS apps.

Native Components

In Android development, you write views in Kotlin or Java; in iOS development, you use Swift or Objective-C. With React Native, you can invoke these views with JavaScript using React components. At runtime, React Native creates the corresponding Android and iOS views for those components. Because React Native components are backed by the same views as Android and iOS, React Native apps look, feel, and perform like any other apps. We call these platform-backed components Native Components.

React Native lets you build your own Native Components for Android and iOS to suit your app’s unique needs. We also have a thriving ecosystem of these community-contributed components. Check out Native Directory to find what the community has been creating.

React Native also includes a set of essential, ready-to-use Native Components you can use to start building your app today. These are React Native's Core Components.

Core Components

React Native has many Core Components for everything from form controls to activity indicators. You can find them all documented in the API section. You will mostly work with the following Core Components:

React Native UI ComponentAndroid ViewiOS ViewWeb AnalogDescription
<View><ViewGroup><UIView>A non-scrollling <div>A container that supports layout with flexbox, style, some touch handling, and accessibility controls
<Text><TextView><UITextView><p>Displays, styles, and nests strings of text and even handles touch events
<Image><ImageView><UIImageView><img>Displays different types of images
<ScrollView><ScrollView><UIScrollView><div>A generic scrolling container that can contain multiple components and views
<TextInput><EditText><UITextField><input type="text">Allows the user to enter text

In the next section, you will start combining these Core Components to learn about how React works. Have a play with them here now!

Because React Native uses the same API structure as React components, you’ll need to understand React component APIs to get started. The next section makes for a quick introduction or refresher on the topic. However, if you’re already familiar with React, feel free to skip ahead.

A diagram showing React Native's Core Components are a subset of React Components that ship with React Native.
Edit this page
Last updated on
- + diff --git a/docs/next/intro-react-native-components/index.html b/docs/next/intro-react-native-components/index.html index df5078ca168..22ef392b91a 100644 --- a/docs/next/intro-react-native-components/index.html +++ b/docs/next/intro-react-native-components/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Core Components and Native Components

React Native is an open source framework for building Android and iOS applications using React and the app platform’s native capabilities. With React Native, you use JavaScript to access your platform’s APIs as well as to describe the appearance and behavior of your UI using React components: bundles of reusable, nestable code. You can learn more about React in the next section. But first, let’s cover how components work in React Native.

Views and mobile development

In Android and iOS development, a view is the basic building block of UI: a small rectangular element on the screen which can be used to display text, images, or respond to user input. Even the smallest visual elements of an app, like a line of text or a button, are kinds of views. Some kinds of views can contain other views. It’s views all the way down!

Diagram of Android and iOS app showing them both built on top of atomic elements called views.
Just a sampling of the many views used in Android and iOS apps.

Native Components

In Android development, you write views in Kotlin or Java; in iOS development, you use Swift or Objective-C. With React Native, you can invoke these views with JavaScript using React components. At runtime, React Native creates the corresponding Android and iOS views for those components. Because React Native components are backed by the same views as Android and iOS, React Native apps look, feel, and perform like any other apps. We call these platform-backed components Native Components.

React Native lets you build your own Native Components for Android and iOS to suit your app’s unique needs. We also have a thriving ecosystem of these community-contributed components. Check out Native Directory to find what the community has been creating.

React Native also includes a set of essential, ready-to-use Native Components you can use to start building your app today. These are React Native's Core Components.

Core Components

React Native has many Core Components for everything from form controls to activity indicators. You can find them all documented in the API section. You will mostly work with the following Core Components:

React Native UI ComponentAndroid ViewiOS ViewWeb AnalogDescription
<View><ViewGroup><UIView>A non-scrollling <div>A container that supports layout with flexbox, style, some touch handling, and accessibility controls
<Text><TextView><UITextView><p>Displays, styles, and nests strings of text and even handles touch events
<Image><ImageView><UIImageView><img>Displays different types of images
<ScrollView><ScrollView><UIScrollView><div>A generic scrolling container that can contain multiple components and views
<TextInput><EditText><UITextField><input type="text">Allows the user to enter text

In the next section, you will start combining these Core Components to learn about how React works. Have a play with them here now!

Because React Native uses the same API structure as React components, you’ll need to understand React component APIs to get started. The next section makes for a quick introduction or refresher on the topic. However, if you’re already familiar with React, feel free to skip ahead.

A diagram showing React Native's Core Components are a subset of React Components that ship with React Native.
Edit this page
Last updated on
- + diff --git a/docs/next/intro-react.html b/docs/next/intro-react.html index 38d2a78c20f..423ff8b790c 100644 --- a/docs/next/intro-react.html +++ b/docs/next/intro-react.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
export default Cat;

This is one of many ways to export your component. This kind of export works well with the Snack Player. However, depending on your app’s file structure, you might need to use a different convention. This handy cheatsheet on JavaScript imports and exports can help.

Now take a closer look at that return statement. <Text>Hello, I am your cat!</Text> is using a kind of JavaScript syntax that makes writing elements convenient: JSX.

JSX

React and React Native use JSX, a syntax that lets you write elements inside JavaScript like so: <Text>Hello, I am your cat!</Text>. The React docs have a comprehensive guide to JSX you can reference to learn even more. Because JSX is JavaScript, you can use variables inside it. Here you are declaring a name for the cat, name, and embedding it with curly braces inside <Text>.

Any JavaScript expression will work between curly braces, including function calls like {getFullName("Rum", "Tum", "Tugger")}:

You can think of curly braces as creating a portal into JS functionality in your JSX!

Because JSX is included in the React library, it won’t work if you don’t have import React from 'react' at the top of your file!

Custom Components

You’ve already met React Native’s Core Components. React lets you nest these components inside each other to create new components. These nestable, reusable components are at the heart of the React paradigm.

For example, you can nest Text and TextInput inside a View below, and React Native will render them together:

Developer notes

If you’re familiar with web development, <View> and <Text> might remind you of HTML! You can think of them as the <div> and <p> tags of application development.

You can render this component multiple times and in multiple places without repeating your code by using <Cat>:

Any component that renders other components is a parent component. Here, Cafe is the parent component and each Cat is a child component.

You can put as many cats in your cafe as you like. Each <Cat> renders a unique element—which you can customize with props.

Props

Props is short for “properties.” Props let you customize React components. For example, here you pass each <Cat> a different name for Cat to render:

Most of React Native’s Core Components can be customized with props, too. For example, when using Image, you pass it a prop named source to define what image it shows:

Image has many different props, including style, which accepts a JS object of design and layout related property-value pairs.

Notice the double curly braces {{ }} surrounding style‘s width and height. In JSX, JavaScript values are referenced with {}. This is handy if you are passing something other than a string as props, like an array or number: <Cat food={["fish", "kibble"]} age={2} />. However, JS objects are also denoted with curly braces: {width: 200, height: 200}. Therefore, to pass a JS object in JSX, you must wrap the object in another pair of curly braces: {{width: 200, height: 200}}

You can build many things with props and the Core Components Text, Image, and View! But to build something interactive, you’ll need state.

State

While you can think of props as arguments you use to configure how components render, state is like a component’s personal data storage. State is useful for handling data that changes over time or that comes from user interaction. State gives your components memory!

As a general rule, use props to configure a component when it renders. Use state to keep track of any component data that you expect to change over time.

The following example takes place in a cat cafe where two hungry cats are waiting to be fed. Their hunger, which we expect to change over time (unlike their names), is stored as state. To feed the cats, press their buttons—which will update their state.

You can add state to a component by calling React’s useState Hook. A Hook is a kind of function that lets you “hook into” React features. For example, useState is a Hook that lets you add state to function components. You can learn more about other kinds of Hooks in the React documentation.

First, you will want to import useState from React like so:

import React, { useState } from 'react';

Then you declare the component’s state by calling useState inside its function. In this example, useState creates an isHungry state variable:

const Cat = (props) => {
const [isHungry, setIsHungry] = useState(true);
// ...
};

You can use useState to track any kind of data: strings, numbers, Booleans, arrays, objects. For example, you can track the number of times a cat has been petted with const [timesPetted, setTimesPetted] = useState(0)!

Calling useState does two things:

  • it creates a “state variable” with an initial value—in this case the state variable is isHungry and its initial value is true
  • it creates a function to set that state variable’s value—setIsHungry

It doesn’t matter what names you use. But it can be handy to think of the pattern as [<getter>, <setter>] = useState(<initialValue>).

Next you add the Button Core Component and give it an onPress prop:

<Button
onPress={() => {
setIsHungry(false);
}}
//..
/>

Now, when someone presses the button, onPress will fire, calling the setIsHungry(false). This sets the state variable isHungry to false. When isHungry is false, the Button’s disabled prop is set to true and its title also changes:

<Button
//..
disabled={!isHungry}
title={isHungry ? 'Pour me some milk, please!' : 'Thank you!'}
/>

You might’ve noticed that although isHungry is a const, it is seemingly reassignable! What is happening is when a state-setting function like setIsHungry is called, its component will re-render. In this case the Cat function will run again—and this time, useState will give us the next value of isHungry.

Finally, put your cats inside a Cafe component:

const Cafe = () => {
return (
<>
<Cat name="Munkustrap" />
<Cat name="Spot" />
</>
);
};

See the <> and </> above? These bits of JSX are fragments. Adjacent JSX elements must be wrapped in an enclosing tag. Fragments let you do that without nesting an extra, unnecessary wrapping element like View.

Now that you’ve covered both React and React Native’s Core Components, let’s dive deeper on some of these core components by looking at handling <TextInput>.

Edit this page
Last updated on
- + diff --git a/docs/next/intro-react/index.html b/docs/next/intro-react/index.html index 38d2a78c20f..423ff8b790c 100644 --- a/docs/next/intro-react/index.html +++ b/docs/next/intro-react/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
export default Cat;

This is one of many ways to export your component. This kind of export works well with the Snack Player. However, depending on your app’s file structure, you might need to use a different convention. This handy cheatsheet on JavaScript imports and exports can help.

Now take a closer look at that return statement. <Text>Hello, I am your cat!</Text> is using a kind of JavaScript syntax that makes writing elements convenient: JSX.

JSX

React and React Native use JSX, a syntax that lets you write elements inside JavaScript like so: <Text>Hello, I am your cat!</Text>. The React docs have a comprehensive guide to JSX you can reference to learn even more. Because JSX is JavaScript, you can use variables inside it. Here you are declaring a name for the cat, name, and embedding it with curly braces inside <Text>.

Any JavaScript expression will work between curly braces, including function calls like {getFullName("Rum", "Tum", "Tugger")}:

You can think of curly braces as creating a portal into JS functionality in your JSX!

Because JSX is included in the React library, it won’t work if you don’t have import React from 'react' at the top of your file!

Custom Components

You’ve already met React Native’s Core Components. React lets you nest these components inside each other to create new components. These nestable, reusable components are at the heart of the React paradigm.

For example, you can nest Text and TextInput inside a View below, and React Native will render them together:

Developer notes

If you’re familiar with web development, <View> and <Text> might remind you of HTML! You can think of them as the <div> and <p> tags of application development.

You can render this component multiple times and in multiple places without repeating your code by using <Cat>:

Any component that renders other components is a parent component. Here, Cafe is the parent component and each Cat is a child component.

You can put as many cats in your cafe as you like. Each <Cat> renders a unique element—which you can customize with props.

Props

Props is short for “properties.” Props let you customize React components. For example, here you pass each <Cat> a different name for Cat to render:

Most of React Native’s Core Components can be customized with props, too. For example, when using Image, you pass it a prop named source to define what image it shows:

Image has many different props, including style, which accepts a JS object of design and layout related property-value pairs.

Notice the double curly braces {{ }} surrounding style‘s width and height. In JSX, JavaScript values are referenced with {}. This is handy if you are passing something other than a string as props, like an array or number: <Cat food={["fish", "kibble"]} age={2} />. However, JS objects are also denoted with curly braces: {width: 200, height: 200}. Therefore, to pass a JS object in JSX, you must wrap the object in another pair of curly braces: {{width: 200, height: 200}}

You can build many things with props and the Core Components Text, Image, and View! But to build something interactive, you’ll need state.

State

While you can think of props as arguments you use to configure how components render, state is like a component’s personal data storage. State is useful for handling data that changes over time or that comes from user interaction. State gives your components memory!

As a general rule, use props to configure a component when it renders. Use state to keep track of any component data that you expect to change over time.

The following example takes place in a cat cafe where two hungry cats are waiting to be fed. Their hunger, which we expect to change over time (unlike their names), is stored as state. To feed the cats, press their buttons—which will update their state.

You can add state to a component by calling React’s useState Hook. A Hook is a kind of function that lets you “hook into” React features. For example, useState is a Hook that lets you add state to function components. You can learn more about other kinds of Hooks in the React documentation.

First, you will want to import useState from React like so:

import React, { useState } from 'react';

Then you declare the component’s state by calling useState inside its function. In this example, useState creates an isHungry state variable:

const Cat = (props) => {
const [isHungry, setIsHungry] = useState(true);
// ...
};

You can use useState to track any kind of data: strings, numbers, Booleans, arrays, objects. For example, you can track the number of times a cat has been petted with const [timesPetted, setTimesPetted] = useState(0)!

Calling useState does two things:

  • it creates a “state variable” with an initial value—in this case the state variable is isHungry and its initial value is true
  • it creates a function to set that state variable’s value—setIsHungry

It doesn’t matter what names you use. But it can be handy to think of the pattern as [<getter>, <setter>] = useState(<initialValue>).

Next you add the Button Core Component and give it an onPress prop:

<Button
onPress={() => {
setIsHungry(false);
}}
//..
/>

Now, when someone presses the button, onPress will fire, calling the setIsHungry(false). This sets the state variable isHungry to false. When isHungry is false, the Button’s disabled prop is set to true and its title also changes:

<Button
//..
disabled={!isHungry}
title={isHungry ? 'Pour me some milk, please!' : 'Thank you!'}
/>

You might’ve noticed that although isHungry is a const, it is seemingly reassignable! What is happening is when a state-setting function like setIsHungry is called, its component will re-render. In this case the Cat function will run again—and this time, useState will give us the next value of isHungry.

Finally, put your cats inside a Cafe component:

const Cafe = () => {
return (
<>
<Cat name="Munkustrap" />
<Cat name="Spot" />
</>
);
};

See the <> and </> above? These bits of JSX are fragments. Adjacent JSX elements must be wrapped in an enclosing tag. Fragments let you do that without nesting an extra, unnecessary wrapping element like View.

Now that you’ve covered both React and React Native’s Core Components, let’s dive deeper on some of these core components by looking at handling <TextInput>.

Edit this page
Last updated on
- + diff --git a/docs/next/javascript-environment.html b/docs/next/javascript-environment.html index e564340dd19..022be500691 100644 --- a/docs/next/javascript-environment.html +++ b/docs/next/javascript-environment.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

JavaScript Environment

JavaScript Runtime

When using React Native, you're going to be running your JavaScript code in two environments:

  • In most cases, React Native will use JavaScriptCore, the JavaScript engine that powers Safari. Note that on iOS, JavaScriptCore does not use JIT due to the absence of writable executable memory in iOS apps.
  • When using Chrome debugging, all JavaScript code runs within Chrome itself, communicating with native code via WebSockets. Chrome uses V8 as its JavaScript engine.

While both environments are very similar, you may end up hitting some inconsistencies. We're likely going to experiment with other JavaScript engines in the future, so it's best to avoid relying on specifics of any runtime.

JavaScript Syntax Transformers

Syntax transformers make writing code more enjoyable by allowing you to use new JavaScript syntax without having to wait for support on all interpreters.

React Native ships with the Babel JavaScript compiler. Check Babel documentation on its supported transformations for more details.

A full list of React Native's enabled transformations can be found in metro-react-native-babel-preset.

ES5

  • Reserved Words: promise.catch(function() { });

ES6

ES8

Stage 3

Specific

  • JSX: <View style={{color: 'red'}} />
  • Flow: function foo(x: ?number): string {};
  • TypeScript: function foo(x: number | undefined): string {};
  • Babel Template: allows AST templating

Polyfills

Many standard functions are also available on all the supported JavaScript runtimes.

Browser

ES6

ES7

ES8

Specific

  • __DEV__
Edit this page
Last updated on
- + diff --git a/docs/next/javascript-environment/index.html b/docs/next/javascript-environment/index.html index e564340dd19..022be500691 100644 --- a/docs/next/javascript-environment/index.html +++ b/docs/next/javascript-environment/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

JavaScript Environment

JavaScript Runtime

When using React Native, you're going to be running your JavaScript code in two environments:

  • In most cases, React Native will use JavaScriptCore, the JavaScript engine that powers Safari. Note that on iOS, JavaScriptCore does not use JIT due to the absence of writable executable memory in iOS apps.
  • When using Chrome debugging, all JavaScript code runs within Chrome itself, communicating with native code via WebSockets. Chrome uses V8 as its JavaScript engine.

While both environments are very similar, you may end up hitting some inconsistencies. We're likely going to experiment with other JavaScript engines in the future, so it's best to avoid relying on specifics of any runtime.

JavaScript Syntax Transformers

Syntax transformers make writing code more enjoyable by allowing you to use new JavaScript syntax without having to wait for support on all interpreters.

React Native ships with the Babel JavaScript compiler. Check Babel documentation on its supported transformations for more details.

A full list of React Native's enabled transformations can be found in metro-react-native-babel-preset.

ES5

  • Reserved Words: promise.catch(function() { });

ES6

ES8

Stage 3

Specific

  • JSX: <View style={{color: 'red'}} />
  • Flow: function foo(x: ?number): string {};
  • TypeScript: function foo(x: number | undefined): string {};
  • Babel Template: allows AST templating

Polyfills

Many standard functions are also available on all the supported JavaScript runtimes.

Browser

ES6

ES7

ES8

Specific

  • __DEV__
Edit this page
Last updated on
- + diff --git a/docs/next/keyboard.html b/docs/next/keyboard.html index 9f28d836bbe..fa744922422 100644 --- a/docs/next/keyboard.html +++ b/docs/next/keyboard.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Keyboard

Keyboard module to control keyboard events.

Usage

The Keyboard module allows you to listen for native events and react to them, as well as make changes to the keyboard, like dismissing it.

Reference

Methods

addListener()

static addListener(eventName, callback)

The addListener function connects a JavaScript function to an identified native keyboard notification event.

This function then returns the reference to the listener.

Parameters:

NameTypeDescription
eventName
Required
stringThe string that identifies the event you're listening for. See the list below.
callback
Required
functionThe function to be called when the event fires

eventName

This can be any of the following:

  • keyboardWillShow
  • keyboardDidShow
  • keyboardWillHide
  • keyboardDidHide
  • keyboardWillChangeFrame
  • keyboardDidChangeFrame

Note that if you set android:windowSoftInputMode to adjustResize or adjustPan, only keyboardDidShow and keyboardDidHide events will be available on Android. If you set android:windowSoftInputMode to adjustNothing, no events will be available on Android. keyboardWillShow as well as keyboardWillHide are generally not available on Android since there is no native corresponding event.

removeListener()

static removeListener(eventName, callback)

Removes a specific listener.

Parameters:

NameTypeRequiredDescription
eventNamestringYesThe nativeEvent is the string that identifies the event you're listening for
callbackfunctionYesThe function to be called when the event fires

removeAllListeners()

static removeAllListeners(eventName)

Removes all listeners for a specific event type.

Parameters:

NameTypeRequiredDescription
eventTypestringYesThe native event string listeners are watching which will be removed

dismiss()

static dismiss()

Dismisses the active keyboard and removes focus.

scheduleLayoutAnimation

static scheduleLayoutAnimation(event)

Useful for syncing TextInput (or other keyboard accessory view) size of position changes with keyboard movements.

Edit this page
Last updated on
- + diff --git a/docs/next/keyboard/index.html b/docs/next/keyboard/index.html index 9f28d836bbe..fa744922422 100644 --- a/docs/next/keyboard/index.html +++ b/docs/next/keyboard/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Keyboard

Keyboard module to control keyboard events.

Usage

The Keyboard module allows you to listen for native events and react to them, as well as make changes to the keyboard, like dismissing it.

Reference

Methods

addListener()

static addListener(eventName, callback)

The addListener function connects a JavaScript function to an identified native keyboard notification event.

This function then returns the reference to the listener.

Parameters:

NameTypeDescription
eventName
Required
stringThe string that identifies the event you're listening for. See the list below.
callback
Required
functionThe function to be called when the event fires

eventName

This can be any of the following:

  • keyboardWillShow
  • keyboardDidShow
  • keyboardWillHide
  • keyboardDidHide
  • keyboardWillChangeFrame
  • keyboardDidChangeFrame

Note that if you set android:windowSoftInputMode to adjustResize or adjustPan, only keyboardDidShow and keyboardDidHide events will be available on Android. If you set android:windowSoftInputMode to adjustNothing, no events will be available on Android. keyboardWillShow as well as keyboardWillHide are generally not available on Android since there is no native corresponding event.

removeListener()

static removeListener(eventName, callback)

Removes a specific listener.

Parameters:

NameTypeRequiredDescription
eventNamestringYesThe nativeEvent is the string that identifies the event you're listening for
callbackfunctionYesThe function to be called when the event fires

removeAllListeners()

static removeAllListeners(eventName)

Removes all listeners for a specific event type.

Parameters:

NameTypeRequiredDescription
eventTypestringYesThe native event string listeners are watching which will be removed

dismiss()

static dismiss()

Dismisses the active keyboard and removes focus.

scheduleLayoutAnimation

static scheduleLayoutAnimation(event)

Useful for syncing TextInput (or other keyboard accessory view) size of position changes with keyboard movements.

Edit this page
Last updated on
- + diff --git a/docs/next/keyboardavoidingview.html b/docs/next/keyboardavoidingview.html index 14ab7468347..f138a60340a 100644 --- a/docs/next/keyboardavoidingview.html +++ b/docs/next/keyboardavoidingview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

KeyboardAvoidingView

It is a component to solve the common problem of views that need to move out of the way of the virtual keyboard. It can automatically adjust either its height, position, or bottom padding based on the keyboard height.

Example

Reference

Props

View Props

Inherits View Props.

behavior

Specify how to react to the presence of the keyboard.

Android and iOS both interact with this prop differently. On both iOS and Android, setting behavior is recommended.

Type
enum('height', 'position', 'padding')

contentContainerStyle

The style of the content container (View) when behavior is 'position'.

Type
View Style

enabled

Enabled or disabled KeyboardAvoidingView.

TypeDefault
booleantrue

keyboardVerticalOffset

This is the distance between the top of the user screen and the react native view, may be non-zero in some use cases.

TypeDefault
number0
Edit this page
Last updated on
- + diff --git a/docs/next/keyboardavoidingview/index.html b/docs/next/keyboardavoidingview/index.html index 14ab7468347..f138a60340a 100644 --- a/docs/next/keyboardavoidingview/index.html +++ b/docs/next/keyboardavoidingview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

KeyboardAvoidingView

It is a component to solve the common problem of views that need to move out of the way of the virtual keyboard. It can automatically adjust either its height, position, or bottom padding based on the keyboard height.

Example

Reference

Props

View Props

Inherits View Props.

behavior

Specify how to react to the presence of the keyboard.

Android and iOS both interact with this prop differently. On both iOS and Android, setting behavior is recommended.

Type
enum('height', 'position', 'padding')

contentContainerStyle

The style of the content container (View) when behavior is 'position'.

Type
View Style

enabled

Enabled or disabled KeyboardAvoidingView.

TypeDefault
booleantrue

keyboardVerticalOffset

This is the distance between the top of the user screen and the react native view, may be non-zero in some use cases.

TypeDefault
number0
Edit this page
Last updated on
- + diff --git a/docs/next/layout-props.html b/docs/next/layout-props.html index f88dcb337cb..dfc31c64dd1 100644 --- a/docs/next/layout-props.html +++ b/docs/next/layout-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Layout Props

More detailed examples about those properties can be found on the Layout with Flexbox page.

Example

The following example shows how different properties can affect or shape a React Native layout. You can try for example to add or remove squares from the UI while changing the values of the property flexWrap.

Reference

Props

alignContent

alignContent controls how rows align in the cross direction, overriding the alignContent of the parent. See https://developer.mozilla.org/en-US/docs/Web/CSS/align-content for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'stretch', 'space-between', 'space-around')No

alignItems

alignItems aligns children in the cross direction. For example, if children are flowing vertically, alignItems controls how they align horizontally. It works like align-items in CSS (default: stretch). See https://developer.mozilla.org/en-US/docs/Web/CSS/align-items for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'stretch', 'baseline')No

alignSelf

alignSelf controls how a child aligns in the cross direction, overriding the alignItems of the parent. It works like align-self in CSS (default: auto). See https://developer.mozilla.org/en-US/docs/Web/CSS/align-self for more details.

TypeRequired
enum('auto', 'flex-start', 'flex-end', 'center', 'stretch', 'baseline')No

aspectRatio

Aspect ratio controls the size of the undefined dimension of a node. Aspect ratio is a non-standard property only available in React Native and not CSS.

  • On a node with a set width/height, aspect ratio controls the size of the unset dimension
  • On a node with a set flex basis, aspect ratio controls the size of the node in the cross axis if unset
  • On a node with a measure function, aspect ratio works as though the measure function measures the flex basis
  • On a node with flex grow/shrink, aspect ratio controls the size of the node in the cross axis if unset
  • Aspect ratio takes min/max dimensions into account
TypeRequired
numberNo

borderBottomWidth

borderBottomWidth works like border-bottom-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-width for more details.

TypeRequired
numberNo

borderEndWidth

When direction is ltr, borderEndWidth is equivalent to borderRightWidth. When direction is rtl, borderEndWidth is equivalent to borderLeftWidth.

TypeRequired
numberNo

borderLeftWidth

borderLeftWidth works like border-left-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-left-width for more details.

TypeRequired
numberNo

borderRightWidth

borderRightWidth works like border-right-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-right-width for more details.

TypeRequired
numberNo

borderStartWidth

When direction is ltr, borderStartWidth is equivalent to borderLeftWidth. When direction is rtl, borderStartWidth is equivalent to borderRightWidth.

TypeRequired
numberNo

borderTopWidth

borderTopWidth works like border-top-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-top-width for more details.

TypeRequired
numberNo

borderWidth

borderWidth works like border-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-width for more details.

TypeRequired
numberNo

bottom

bottom is the number of logical pixels to offset the bottom edge of this component.

It works similarly to bottom in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/bottom for more details of how bottom affects layout.

TypeRequired
number, stringNo

direction

direction specifies the directional flow of the user interface. The default is inherit, except for root node which will have value based on the current locale. See https://yogalayout.com/docs/layout-direction for more details.

TypeRequiredPlatform
enum('inherit', 'ltr', 'rtl')NoiOS

display

display sets the display type of this component.

It works similarly to display in CSS but only supports 'flex' and 'none'. 'flex' is the default.

TypeRequired
enum('none', 'flex')No

end

When the direction is ltr, end is equivalent to right. When the direction is rtl, end is equivalent to left.

This style takes precedence over the left and right styles.

TypeRequired
number, stringNo

flex

In React Native flex does not work the same way that it does in CSS. flex is a number rather than a string, and it works according to the Yoga layout engine.

When flex is a positive number, it makes the component flexible, and it will be sized proportional to its flex value. So a component with flex set to 2 will take twice the space as a component with flex set to 1. flex: <positive number> equates to flexGrow: <positive number>, flexShrink: 1, flexBasis: 0.

When flex is 0, the component is sized according to width and height, and it is inflexible.

When flex is -1, the component is normally sized according to width and height. However, if there's not enough space, the component will shrink to its minWidth and minHeight.

flexGrow, flexShrink, and flexBasis work the same as in CSS.

TypeRequired
numberNo

flexBasis

flexBasis is an axis-independent way of providing the default size of an item along the main axis. Setting the flexBasis of a child is similar to setting the width of that child if its parent is a container with flexDirection: row or setting the height of a child if its parent is a container with flexDirection: column. The flexBasis of an item is the default size of that item, the size of the item before any flexGrow and flexShrink calculations are performed.

TypeRequired
number, stringNo

flexDirection

flexDirection controls which directions children of a container go. row goes left to right, column goes top to bottom, and you may be able to guess what the other two do. It works like flex-direction in CSS, except the default is column. See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction for more details.

TypeRequired
enum('row', 'row-reverse', 'column', 'column-reverse')No

flexGrow

flexGrow describes how any space within a container should be distributed among its children along the main axis. After laying out its children, a container will distribute any remaining space according to the flex grow values specified by its children.

flexGrow accepts any floating point value >= 0, with 0 being the default value. A container will distribute any remaining space among its children weighted by the children’s flexGrow values.

TypeRequired
numberNo

flexShrink

flexShrink describes how to shrink children along the main axis in the case in which the total size of the children overflows the size of the container on the main axis. flexShrink is very similar to flexGrow and can be thought of in the same way if any overflowing size is considered to be negative remaining space. These two properties also work well together by allowing children to grow and shrink as needed.

flexShrink accepts any floating point value >= 0, with 1 being the default value. A container will shrink its children weighted by the children’s flexShrink values.

TypeRequired
numberNo

flexWrap

flexWrap controls whether children can wrap around after they hit the end of a flex container. It works like flex-wrap in CSS (default: nowrap). See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-wrap for more details. Note it does not work anymore with alignItems: stretch (the default), so you may want to use alignItems: flex-start for example (breaking change details: https://github.com/facebook/react-native/releases/tag/v0.28.0).

TypeRequired
enum('wrap', 'nowrap', 'wrap-reverse')No

height

height sets the height of this component.

It works similarly to height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported. See https://developer.mozilla.org/en-US/docs/Web/CSS/height for more details.

TypeRequired
number, stringNo

justifyContent

justifyContent aligns children in the main direction. For example, if children are flowing vertically, justifyContent controls how they align vertically. It works like justify-content in CSS (default: flex-start). See https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'space-between', 'space-around', 'space-evenly')No

left

left is the number of logical pixels to offset the left edge of this component.

It works similarly to left in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/left for more details of how left affects layout.

TypeRequired
number, stringNo

margin

Setting margin has the same effect as setting each of marginTop, marginLeft, marginBottom, and marginRight. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin for more details.

TypeRequired
number, stringNo

marginBottom

marginBottom works like margin-bottom in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-bottom for more details.

TypeRequired
number, stringNo

marginEnd

When direction is ltr, marginEnd is equivalent to marginRight. When direction is rtl, marginEnd is equivalent to marginLeft.

TypeRequired
number, stringNo

marginHorizontal

Setting marginHorizontal has the same effect as setting both marginLeft and marginRight.

TypeRequired
number, stringNo

marginLeft

marginLeft works like margin-left in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-left for more details.

TypeRequired
number, stringNo

marginRight

marginRight works like margin-right in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-right for more details.

TypeRequired
number, stringNo

marginStart

When direction is ltr, marginStart is equivalent to marginLeft. When direction is rtl, marginStart is equivalent to marginRight.

TypeRequired
number, stringNo

marginTop

marginTop works like margin-top in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-top for more details.

TypeRequired
number, stringNo

marginVertical

Setting marginVertical has the same effect as setting both marginTop and marginBottom.

TypeRequired
number, stringNo

maxHeight

maxHeight is the maximum height for this component, in logical pixels.

It works similarly to max-height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/max-height for more details.

TypeRequired
number, stringNo

maxWidth

maxWidth is the maximum width for this component, in logical pixels.

It works similarly to max-width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/max-width for more details.

TypeRequired
number, stringNo

minHeight

minHeight is the minimum height for this component, in logical pixels.

It works similarly to min-height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/min-height for more details.

TypeRequired
number, stringNo

minWidth

minWidth is the minimum width for this component, in logical pixels.

It works similarly to min-width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/min-width for more details.

TypeRequired
number, stringNo

overflow

overflow controls how children are measured and displayed. overflow: hidden causes views to be clipped while overflow: scroll causes views to be measured independently of their parents' main axis. It works like overflow in CSS (default: visible). See https://developer.mozilla.org/en/docs/Web/CSS/overflow for more details.

TypeRequired
enum('visible', 'hidden', 'scroll')No

padding

Setting padding has the same effect as setting each of paddingTop, paddingBottom, paddingLeft, and paddingRight. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding for more details.

TypeRequired
number, stringNo

paddingBottom

paddingBottom works like padding-bottom in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-bottom for more details.

TypeRequired
number, stringNo

paddingEnd

When direction is ltr, paddingEnd is equivalent to paddingRight. When direction is rtl, paddingEnd is equivalent to paddingLeft.

TypeRequired
number, stringNo

paddingHorizontal

Setting paddingHorizontal is like setting both of paddingLeft and paddingRight.

TypeRequired
number, stringNo

paddingLeft

paddingLeft works like padding-left in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-left for more details.

TypeRequired
number, stringNo

paddingRight

paddingRight works like padding-right in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-right for more details.

TypeRequired
number, stringNo

paddingStart

When direction is ltr, paddingStart is equivalent to paddingLeft. When direction is rtl, paddingStart is equivalent to paddingRight.

TypeRequired
number, stringNo

paddingTop

paddingTop works like padding-top in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-top for more details.

TypeRequired
number, ,stringNo

paddingVertical

Setting paddingVertical is like setting both of paddingTop and paddingBottom.

TypeRequired
number, stringNo

position

position in React Native is similar to regular CSS, but everything is set to relative by default, so absolute positioning is always relative to the parent.

If you want to position a child using specific numbers of logical pixels relative to its parent, set the child to have absolute position.

If you want to position a child relative to something that is not its parent, don't use styles for that. Use the component tree.

See https://github.com/facebook/yoga for more details on how position differs between React Native and CSS.

TypeRequired
enum('absolute', 'relative')No

right

right is the number of logical pixels to offset the right edge of this component.

It works similarly to right in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/right for more details of how right affects layout.

TypeRequired
number, stringNo

start

When the direction is ltr, start is equivalent to left. When the direction is rtl, start is equivalent to right.

This style takes precedence over the left, right, and end styles.

TypeRequired
number, stringNo

top

top is the number of logical pixels to offset the top edge of this component.

It works similarly to top in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/top for more details of how top affects layout.

TypeRequired
number, stringNo

width

width sets the width of this component.

It works similarly to width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported. See https://developer.mozilla.org/en-US/docs/Web/CSS/width for more details.

TypeRequired
number, stringNo

zIndex

zIndex controls which components display on top of others. Normally, you don't use zIndex. Components render according to their order in the document tree, so later components draw over earlier ones. zIndex may be useful if you have animations or custom modal interfaces where you don't want this behavior.

It works like the CSS z-index property - components with a larger zIndex will render on top. Think of the z-direction like it's pointing from the phone into your eyeball. See https://developer.mozilla.org/en-US/docs/Web/CSS/z-index for more details.

On iOS, zIndex may require Views to be siblings of each other for it to work as expected.

TypeRequired
numberNo
Edit this page
Last updated on
- + diff --git a/docs/next/layout-props/index.html b/docs/next/layout-props/index.html index f88dcb337cb..dfc31c64dd1 100644 --- a/docs/next/layout-props/index.html +++ b/docs/next/layout-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Layout Props

More detailed examples about those properties can be found on the Layout with Flexbox page.

Example

The following example shows how different properties can affect or shape a React Native layout. You can try for example to add or remove squares from the UI while changing the values of the property flexWrap.

Reference

Props

alignContent

alignContent controls how rows align in the cross direction, overriding the alignContent of the parent. See https://developer.mozilla.org/en-US/docs/Web/CSS/align-content for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'stretch', 'space-between', 'space-around')No

alignItems

alignItems aligns children in the cross direction. For example, if children are flowing vertically, alignItems controls how they align horizontally. It works like align-items in CSS (default: stretch). See https://developer.mozilla.org/en-US/docs/Web/CSS/align-items for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'stretch', 'baseline')No

alignSelf

alignSelf controls how a child aligns in the cross direction, overriding the alignItems of the parent. It works like align-self in CSS (default: auto). See https://developer.mozilla.org/en-US/docs/Web/CSS/align-self for more details.

TypeRequired
enum('auto', 'flex-start', 'flex-end', 'center', 'stretch', 'baseline')No

aspectRatio

Aspect ratio controls the size of the undefined dimension of a node. Aspect ratio is a non-standard property only available in React Native and not CSS.

  • On a node with a set width/height, aspect ratio controls the size of the unset dimension
  • On a node with a set flex basis, aspect ratio controls the size of the node in the cross axis if unset
  • On a node with a measure function, aspect ratio works as though the measure function measures the flex basis
  • On a node with flex grow/shrink, aspect ratio controls the size of the node in the cross axis if unset
  • Aspect ratio takes min/max dimensions into account
TypeRequired
numberNo

borderBottomWidth

borderBottomWidth works like border-bottom-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-width for more details.

TypeRequired
numberNo

borderEndWidth

When direction is ltr, borderEndWidth is equivalent to borderRightWidth. When direction is rtl, borderEndWidth is equivalent to borderLeftWidth.

TypeRequired
numberNo

borderLeftWidth

borderLeftWidth works like border-left-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-left-width for more details.

TypeRequired
numberNo

borderRightWidth

borderRightWidth works like border-right-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-right-width for more details.

TypeRequired
numberNo

borderStartWidth

When direction is ltr, borderStartWidth is equivalent to borderLeftWidth. When direction is rtl, borderStartWidth is equivalent to borderRightWidth.

TypeRequired
numberNo

borderTopWidth

borderTopWidth works like border-top-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-top-width for more details.

TypeRequired
numberNo

borderWidth

borderWidth works like border-width in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/border-width for more details.

TypeRequired
numberNo

bottom

bottom is the number of logical pixels to offset the bottom edge of this component.

It works similarly to bottom in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/bottom for more details of how bottom affects layout.

TypeRequired
number, stringNo

direction

direction specifies the directional flow of the user interface. The default is inherit, except for root node which will have value based on the current locale. See https://yogalayout.com/docs/layout-direction for more details.

TypeRequiredPlatform
enum('inherit', 'ltr', 'rtl')NoiOS

display

display sets the display type of this component.

It works similarly to display in CSS but only supports 'flex' and 'none'. 'flex' is the default.

TypeRequired
enum('none', 'flex')No

end

When the direction is ltr, end is equivalent to right. When the direction is rtl, end is equivalent to left.

This style takes precedence over the left and right styles.

TypeRequired
number, stringNo

flex

In React Native flex does not work the same way that it does in CSS. flex is a number rather than a string, and it works according to the Yoga layout engine.

When flex is a positive number, it makes the component flexible, and it will be sized proportional to its flex value. So a component with flex set to 2 will take twice the space as a component with flex set to 1. flex: <positive number> equates to flexGrow: <positive number>, flexShrink: 1, flexBasis: 0.

When flex is 0, the component is sized according to width and height, and it is inflexible.

When flex is -1, the component is normally sized according to width and height. However, if there's not enough space, the component will shrink to its minWidth and minHeight.

flexGrow, flexShrink, and flexBasis work the same as in CSS.

TypeRequired
numberNo

flexBasis

flexBasis is an axis-independent way of providing the default size of an item along the main axis. Setting the flexBasis of a child is similar to setting the width of that child if its parent is a container with flexDirection: row or setting the height of a child if its parent is a container with flexDirection: column. The flexBasis of an item is the default size of that item, the size of the item before any flexGrow and flexShrink calculations are performed.

TypeRequired
number, stringNo

flexDirection

flexDirection controls which directions children of a container go. row goes left to right, column goes top to bottom, and you may be able to guess what the other two do. It works like flex-direction in CSS, except the default is column. See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction for more details.

TypeRequired
enum('row', 'row-reverse', 'column', 'column-reverse')No

flexGrow

flexGrow describes how any space within a container should be distributed among its children along the main axis. After laying out its children, a container will distribute any remaining space according to the flex grow values specified by its children.

flexGrow accepts any floating point value >= 0, with 0 being the default value. A container will distribute any remaining space among its children weighted by the children’s flexGrow values.

TypeRequired
numberNo

flexShrink

flexShrink describes how to shrink children along the main axis in the case in which the total size of the children overflows the size of the container on the main axis. flexShrink is very similar to flexGrow and can be thought of in the same way if any overflowing size is considered to be negative remaining space. These two properties also work well together by allowing children to grow and shrink as needed.

flexShrink accepts any floating point value >= 0, with 1 being the default value. A container will shrink its children weighted by the children’s flexShrink values.

TypeRequired
numberNo

flexWrap

flexWrap controls whether children can wrap around after they hit the end of a flex container. It works like flex-wrap in CSS (default: nowrap). See https://developer.mozilla.org/en-US/docs/Web/CSS/flex-wrap for more details. Note it does not work anymore with alignItems: stretch (the default), so you may want to use alignItems: flex-start for example (breaking change details: https://github.com/facebook/react-native/releases/tag/v0.28.0).

TypeRequired
enum('wrap', 'nowrap', 'wrap-reverse')No

height

height sets the height of this component.

It works similarly to height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported. See https://developer.mozilla.org/en-US/docs/Web/CSS/height for more details.

TypeRequired
number, stringNo

justifyContent

justifyContent aligns children in the main direction. For example, if children are flowing vertically, justifyContent controls how they align vertically. It works like justify-content in CSS (default: flex-start). See https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content for more details.

TypeRequired
enum('flex-start', 'flex-end', 'center', 'space-between', 'space-around', 'space-evenly')No

left

left is the number of logical pixels to offset the left edge of this component.

It works similarly to left in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/left for more details of how left affects layout.

TypeRequired
number, stringNo

margin

Setting margin has the same effect as setting each of marginTop, marginLeft, marginBottom, and marginRight. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin for more details.

TypeRequired
number, stringNo

marginBottom

marginBottom works like margin-bottom in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-bottom for more details.

TypeRequired
number, stringNo

marginEnd

When direction is ltr, marginEnd is equivalent to marginRight. When direction is rtl, marginEnd is equivalent to marginLeft.

TypeRequired
number, stringNo

marginHorizontal

Setting marginHorizontal has the same effect as setting both marginLeft and marginRight.

TypeRequired
number, stringNo

marginLeft

marginLeft works like margin-left in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-left for more details.

TypeRequired
number, stringNo

marginRight

marginRight works like margin-right in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-right for more details.

TypeRequired
number, stringNo

marginStart

When direction is ltr, marginStart is equivalent to marginLeft. When direction is rtl, marginStart is equivalent to marginRight.

TypeRequired
number, stringNo

marginTop

marginTop works like margin-top in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/margin-top for more details.

TypeRequired
number, stringNo

marginVertical

Setting marginVertical has the same effect as setting both marginTop and marginBottom.

TypeRequired
number, stringNo

maxHeight

maxHeight is the maximum height for this component, in logical pixels.

It works similarly to max-height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/max-height for more details.

TypeRequired
number, stringNo

maxWidth

maxWidth is the maximum width for this component, in logical pixels.

It works similarly to max-width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/max-width for more details.

TypeRequired
number, stringNo

minHeight

minHeight is the minimum height for this component, in logical pixels.

It works similarly to min-height in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/min-height for more details.

TypeRequired
number, stringNo

minWidth

minWidth is the minimum width for this component, in logical pixels.

It works similarly to min-width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/min-width for more details.

TypeRequired
number, stringNo

overflow

overflow controls how children are measured and displayed. overflow: hidden causes views to be clipped while overflow: scroll causes views to be measured independently of their parents' main axis. It works like overflow in CSS (default: visible). See https://developer.mozilla.org/en/docs/Web/CSS/overflow for more details.

TypeRequired
enum('visible', 'hidden', 'scroll')No

padding

Setting padding has the same effect as setting each of paddingTop, paddingBottom, paddingLeft, and paddingRight. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding for more details.

TypeRequired
number, stringNo

paddingBottom

paddingBottom works like padding-bottom in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-bottom for more details.

TypeRequired
number, stringNo

paddingEnd

When direction is ltr, paddingEnd is equivalent to paddingRight. When direction is rtl, paddingEnd is equivalent to paddingLeft.

TypeRequired
number, stringNo

paddingHorizontal

Setting paddingHorizontal is like setting both of paddingLeft and paddingRight.

TypeRequired
number, stringNo

paddingLeft

paddingLeft works like padding-left in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-left for more details.

TypeRequired
number, stringNo

paddingRight

paddingRight works like padding-right in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-right for more details.

TypeRequired
number, stringNo

paddingStart

When direction is ltr, paddingStart is equivalent to paddingLeft. When direction is rtl, paddingStart is equivalent to paddingRight.

TypeRequired
number, stringNo

paddingTop

paddingTop works like padding-top in CSS. See https://developer.mozilla.org/en-US/docs/Web/CSS/padding-top for more details.

TypeRequired
number, ,stringNo

paddingVertical

Setting paddingVertical is like setting both of paddingTop and paddingBottom.

TypeRequired
number, stringNo

position

position in React Native is similar to regular CSS, but everything is set to relative by default, so absolute positioning is always relative to the parent.

If you want to position a child using specific numbers of logical pixels relative to its parent, set the child to have absolute position.

If you want to position a child relative to something that is not its parent, don't use styles for that. Use the component tree.

See https://github.com/facebook/yoga for more details on how position differs between React Native and CSS.

TypeRequired
enum('absolute', 'relative')No

right

right is the number of logical pixels to offset the right edge of this component.

It works similarly to right in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/right for more details of how right affects layout.

TypeRequired
number, stringNo

start

When the direction is ltr, start is equivalent to left. When the direction is rtl, start is equivalent to right.

This style takes precedence over the left, right, and end styles.

TypeRequired
number, stringNo

top

top is the number of logical pixels to offset the top edge of this component.

It works similarly to top in CSS, but in React Native you must use points or percentages. Ems and other units are not supported.

See https://developer.mozilla.org/en-US/docs/Web/CSS/top for more details of how top affects layout.

TypeRequired
number, stringNo

width

width sets the width of this component.

It works similarly to width in CSS, but in React Native you must use points or percentages. Ems and other units are not supported. See https://developer.mozilla.org/en-US/docs/Web/CSS/width for more details.

TypeRequired
number, stringNo

zIndex

zIndex controls which components display on top of others. Normally, you don't use zIndex. Components render according to their order in the document tree, so later components draw over earlier ones. zIndex may be useful if you have animations or custom modal interfaces where you don't want this behavior.

It works like the CSS z-index property - components with a larger zIndex will render on top. Think of the z-direction like it's pointing from the phone into your eyeball. See https://developer.mozilla.org/en-US/docs/Web/CSS/z-index for more details.

On iOS, zIndex may require Views to be siblings of each other for it to work as expected.

TypeRequired
numberNo
Edit this page
Last updated on
- + diff --git a/docs/next/layoutanimation.html b/docs/next/layoutanimation.html index 51ee03a730e..0ddb2ee996d 100644 --- a/docs/next/layoutanimation.html +++ b/docs/next/layoutanimation.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

LayoutAnimation

Automatically animates views to their new positions when the next layout happens.

A common way to use this API is to call it before updating the state hook in functional components and calling setState in class components.

Note that in order to get this to work on Android you need to set the following flags via UIManager:

if (Platform.OS === 'android') {
if (UIManager.setLayoutAnimationEnabledExperimental) {
UIManager.setLayoutAnimationEnabledExperimental(true);
}
}

Example

Reference

Methods

configureNext()

static configureNext(config, onAnimationDidEnd?, onAnimationDidFail?)

Schedules an animation to happen on the next layout.

Parameters:

NameTypeRequiredDescription
configobjectYesSee config description below.
onAnimationDidEndfunctionNoCalled when the animation finished.
onAnimationDidFailfunctionNoCalled when the animation failed.

The config parameter is an object with the keys below. create returns a valid object for config, and the Presets objects can also all be passed as the config.

  • duration in milliseconds
  • create, optional config for animating in new views
  • update, optional config for animating views that have been updated
  • delete, optional config for animating views as they are removed

The config that's passed to create, update, or delete has the following keys:

  • type, the animation type to use
  • property, the layout property to animate (optional, but recommended for create and delete)
  • springDamping (number, optional and only for use with type: Type.spring)
  • initialVelocity (number, optional)
  • delay (number, optional)
  • duration (number, optional)

create()

static create(duration, type, creationProp)

Helper that creates an object (with create, update, and delete fields) to pass into configureNext. The type parameter is an animation type, and the creationProp parameter is a layout property.

Example:

Properties

Types

An enumeration of animation types to be used in the create method, or in the create/update/delete configs for configureNext. (example usage: LayoutAnimation.Types.easeIn)

Types
spring
linear
easeInEaseOut
easeIn
easeOut
keyboard

Properties

An enumeration of layout properties to be animated to be used in the create method, or in the create/update/delete configs for configureNext. (example usage: LayoutAnimation.Properties.opacity)

Properties
opacity
scaleX
scaleY
scaleXY

Presets

A set of predefined animation configs to pass into configureNext.

PresetsValue
easeInEaseOutcreate(300, 'easeInEaseOut', 'opacity')
linearcreate(500, 'linear', 'opacity')
spring{ duration: 700, create: { type: 'linear', property: 'opacity' }, update: { type: 'spring', springDamping: 0.4 }, delete: { type: 'linear', property: 'opacity' } }

easeInEaseOut

Calls configureNext() with Presets.easeInEaseOut.

linear

Calls configureNext() with Presets.linear.

spring

Calls configureNext() with Presets.spring.

Example:

Edit this page
Last updated on
- + diff --git a/docs/next/layoutanimation/index.html b/docs/next/layoutanimation/index.html index 51ee03a730e..0ddb2ee996d 100644 --- a/docs/next/layoutanimation/index.html +++ b/docs/next/layoutanimation/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

LayoutAnimation

Automatically animates views to their new positions when the next layout happens.

A common way to use this API is to call it before updating the state hook in functional components and calling setState in class components.

Note that in order to get this to work on Android you need to set the following flags via UIManager:

if (Platform.OS === 'android') {
if (UIManager.setLayoutAnimationEnabledExperimental) {
UIManager.setLayoutAnimationEnabledExperimental(true);
}
}

Example

Reference

Methods

configureNext()

static configureNext(config, onAnimationDidEnd?, onAnimationDidFail?)

Schedules an animation to happen on the next layout.

Parameters:

NameTypeRequiredDescription
configobjectYesSee config description below.
onAnimationDidEndfunctionNoCalled when the animation finished.
onAnimationDidFailfunctionNoCalled when the animation failed.

The config parameter is an object with the keys below. create returns a valid object for config, and the Presets objects can also all be passed as the config.

  • duration in milliseconds
  • create, optional config for animating in new views
  • update, optional config for animating views that have been updated
  • delete, optional config for animating views as they are removed

The config that's passed to create, update, or delete has the following keys:

  • type, the animation type to use
  • property, the layout property to animate (optional, but recommended for create and delete)
  • springDamping (number, optional and only for use with type: Type.spring)
  • initialVelocity (number, optional)
  • delay (number, optional)
  • duration (number, optional)

create()

static create(duration, type, creationProp)

Helper that creates an object (with create, update, and delete fields) to pass into configureNext. The type parameter is an animation type, and the creationProp parameter is a layout property.

Example:

Properties

Types

An enumeration of animation types to be used in the create method, or in the create/update/delete configs for configureNext. (example usage: LayoutAnimation.Types.easeIn)

Types
spring
linear
easeInEaseOut
easeIn
easeOut
keyboard

Properties

An enumeration of layout properties to be animated to be used in the create method, or in the create/update/delete configs for configureNext. (example usage: LayoutAnimation.Properties.opacity)

Properties
opacity
scaleX
scaleY
scaleXY

Presets

A set of predefined animation configs to pass into configureNext.

PresetsValue
easeInEaseOutcreate(300, 'easeInEaseOut', 'opacity')
linearcreate(500, 'linear', 'opacity')
spring{ duration: 700, create: { type: 'linear', property: 'opacity' }, update: { type: 'spring', springDamping: 0.4 }, delete: { type: 'linear', property: 'opacity' } }

easeInEaseOut

Calls configureNext() with Presets.easeInEaseOut.

linear

Calls configureNext() with Presets.linear.

spring

Calls configureNext() with Presets.spring.

Example:

Edit this page
Last updated on
- + diff --git a/docs/next/layoutevent.html b/docs/next/layoutevent.html index b8e6f9f1a69..e283c61257b 100644 --- a/docs/next/layoutevent.html +++ b/docs/next/layoutevent.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

LayoutEvent Object Type

LayoutEvent object is returned in the callback as a result of component layout change, for example onLayout in View component.

Example

{
layout: {
width: 520,
height: 70.5,
x: 0,
y: 42.5
},
target: 1127
}

Keys and values

height

Height of the component after the layout changes.

TypeOptional
numberNo

width

Width of the component after the layout changes.

TypeOptional
numberNo

x

Component X coordinate inside the parent component.

TypeOptional
numberNo

y

Component Y coordinate inside the parent component.

TypeOptional
numberNo

target

The node id of the element receiving the PressEvent.

TypeOptional
number, null, undefinedNo

Used by

Edit this page
Last updated on
- + diff --git a/docs/next/layoutevent/index.html b/docs/next/layoutevent/index.html index b8e6f9f1a69..e283c61257b 100644 --- a/docs/next/layoutevent/index.html +++ b/docs/next/layoutevent/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

LayoutEvent Object Type

LayoutEvent object is returned in the callback as a result of component layout change, for example onLayout in View component.

Example

{
layout: {
width: 520,
height: 70.5,
x: 0,
y: 42.5
},
target: 1127
}

Keys and values

height

Height of the component after the layout changes.

TypeOptional
numberNo

width

Width of the component after the layout changes.

TypeOptional
numberNo

x

Component X coordinate inside the parent component.

TypeOptional
numberNo

y

Component Y coordinate inside the parent component.

TypeOptional
numberNo

target

The node id of the element receiving the PressEvent.

TypeOptional
number, null, undefinedNo

Used by

Edit this page
Last updated on
- + diff --git a/docs/next/libraries.html b/docs/next/libraries.html index 18078640dd6..1c315d843a2 100644 --- a/docs/next/libraries.html +++ b/docs/next/libraries.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Using Libraries

React Native provides a set of built-in Core Components and APIs ready to use in your app. You're not limited to the components and APIs bundled with React Native. React Native has a community of thousands of developers. If the Core Components and APIs don't have what you are looking for, you may be able to find and install a library from the community to add the functionality to your app.

Selecting a Package Manager

React Native libraries are typically installed from the npm registry using a Node.js package manager such as npm CLI or Yarn Classic.

If you have Node.js installed on your computer then you already have the npm CLI installed. Some developers prefer to use Yarn Classic for slightly faster install times and additional advanced features like Workspaces. Both tools work great with React Native. We will assume npm for the rest of this guide for simplicity of explanation.

💡 The terms "library" and "package" are used interchangeably in the JavaScript community.

Installing a Library

To install a library in your project, navigate to your project directory in your terminal and run the installation command. Let's try this with react-native-webview:

npm install react-native-webview

The library that we installed includes native code, and we need to link to our app before we use it.

Linking Native Code on iOS

React Native uses CocoaPods to manage iOS project dependencies and most React Native libraries follow this same convention. If a library you are using does not, then please refer to their README for additional instruction. In most cases, the following instructions will apply.

Run pod install in our ios directory in order to link it to our native iOS project. A shortcut for doing this without switching to the ios directory is to run npx pod-install.

npx pod-install

Once this is complete, re-build the app binary to start using your new library:

npx react-native run-ios

Linking Native Code on Android

React Native uses Gradle to manage Android project dependencies. After you install a library with native dependencies, you will need to re-build the app binary to use your new library:

npx react-native run-android

Finding Libraries

React Native Directory is a searchable database of libraries built specifically for React Native. This is the first place to look for a library for your React Native app.

Many of the libraries you will find on the directory are from React Native Community or Expo.

Libraries built by the React Native Community are driven by volunteers and individuals at companies that depend on React Native. They often support iOS, tvOS, Android, Windows, but this varies across projects. Many of the libraries in this organization were once React Native Core Components and APIs.

Libraries built by Expo are all written in TypeScript and support iOS, Android, and react-native-web wherever possible. They usually require that you first install react-native-unimodules in order to use in your React Native app.

After React Native Directory, the npm registry is the next best place if you can't find a library specifically for React Native on the directory. The npm registry is the definitive source for JavaScript libraries, but the libraries that it lists may not all be compatible with React Native. React Native is one of many JavaScript programming environments, including Node.js, web browsers, Electron, and more, and npm includes libraries that work for all of these environments.

Determining Library Compatibility

Does it work with React Native?

Usually libraries built specifically for other platforms will not work with React Native. Examples include react-select which is built for the web and specifically targets react-dom, and rimraf which is built for Node.js and interacts with your computer file system. Other libraries like lodash use only JavaScript language features and work in any environment. You will gain a sense for this over time, but until then the easiest way to find out is to try it yourself. You can remove packages using npm uninstall if it turns out that it does not work in React Native.

Does it work for the platforms that my app supports?

React Native Directory allows you to filter by platform compatibility, such as iOS, Android, Web, and Windows. If the library you would like to use is not currently listed there, refer to the README for the library to learn more.

Does it work with my app version of React Native?

The latest version of a library is typically compatible with the latest version of React Native. If you are using an older version, you should refer to the README to know which version of the library you should install. You can install a particular version of the library by running npm install <library-name>@<version-number>, for example: npm install @react-native-community/netinfo@^2.0.0.

Edit this page
Last updated on
- + diff --git a/docs/next/libraries/index.html b/docs/next/libraries/index.html index 18078640dd6..1c315d843a2 100644 --- a/docs/next/libraries/index.html +++ b/docs/next/libraries/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Using Libraries

React Native provides a set of built-in Core Components and APIs ready to use in your app. You're not limited to the components and APIs bundled with React Native. React Native has a community of thousands of developers. If the Core Components and APIs don't have what you are looking for, you may be able to find and install a library from the community to add the functionality to your app.

Selecting a Package Manager

React Native libraries are typically installed from the npm registry using a Node.js package manager such as npm CLI or Yarn Classic.

If you have Node.js installed on your computer then you already have the npm CLI installed. Some developers prefer to use Yarn Classic for slightly faster install times and additional advanced features like Workspaces. Both tools work great with React Native. We will assume npm for the rest of this guide for simplicity of explanation.

💡 The terms "library" and "package" are used interchangeably in the JavaScript community.

Installing a Library

To install a library in your project, navigate to your project directory in your terminal and run the installation command. Let's try this with react-native-webview:

npm install react-native-webview

The library that we installed includes native code, and we need to link to our app before we use it.

Linking Native Code on iOS

React Native uses CocoaPods to manage iOS project dependencies and most React Native libraries follow this same convention. If a library you are using does not, then please refer to their README for additional instruction. In most cases, the following instructions will apply.

Run pod install in our ios directory in order to link it to our native iOS project. A shortcut for doing this without switching to the ios directory is to run npx pod-install.

npx pod-install

Once this is complete, re-build the app binary to start using your new library:

npx react-native run-ios

Linking Native Code on Android

React Native uses Gradle to manage Android project dependencies. After you install a library with native dependencies, you will need to re-build the app binary to use your new library:

npx react-native run-android

Finding Libraries

React Native Directory is a searchable database of libraries built specifically for React Native. This is the first place to look for a library for your React Native app.

Many of the libraries you will find on the directory are from React Native Community or Expo.

Libraries built by the React Native Community are driven by volunteers and individuals at companies that depend on React Native. They often support iOS, tvOS, Android, Windows, but this varies across projects. Many of the libraries in this organization were once React Native Core Components and APIs.

Libraries built by Expo are all written in TypeScript and support iOS, Android, and react-native-web wherever possible. They usually require that you first install react-native-unimodules in order to use in your React Native app.

After React Native Directory, the npm registry is the next best place if you can't find a library specifically for React Native on the directory. The npm registry is the definitive source for JavaScript libraries, but the libraries that it lists may not all be compatible with React Native. React Native is one of many JavaScript programming environments, including Node.js, web browsers, Electron, and more, and npm includes libraries that work for all of these environments.

Determining Library Compatibility

Does it work with React Native?

Usually libraries built specifically for other platforms will not work with React Native. Examples include react-select which is built for the web and specifically targets react-dom, and rimraf which is built for Node.js and interacts with your computer file system. Other libraries like lodash use only JavaScript language features and work in any environment. You will gain a sense for this over time, but until then the easiest way to find out is to try it yourself. You can remove packages using npm uninstall if it turns out that it does not work in React Native.

Does it work for the platforms that my app supports?

React Native Directory allows you to filter by platform compatibility, such as iOS, Android, Web, and Windows. If the library you would like to use is not currently listed there, refer to the README for the library to learn more.

Does it work with my app version of React Native?

The latest version of a library is typically compatible with the latest version of React Native. If you are using an older version, you should refer to the README to know which version of the library you should install. You can install a particular version of the library by running npm install <library-name>@<version-number>, for example: npm install @react-native-community/netinfo@^2.0.0.

Edit this page
Last updated on
- + diff --git a/docs/next/linking-libraries-ios.html b/docs/next/linking-libraries-ios.html index c69cdb43faa..d7a1cf5cbba 100644 --- a/docs/next/linking-libraries-ios.html +++ b/docs/next/linking-libraries-ios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Linking Libraries

Not every app uses all the native capabilities, and including the code to support all those features would impact the binary size... But we still want to support adding these features whenever you need them.

With that in mind we exposed many of these features as independent static libraries.

For most of the libs it will be as quick as dragging two files, sometimes a third step will be necessary, but no more than that.

All the libraries we ship with React Native live on the Libraries folder in the root of the repository. Some of them are pure JavaScript, and you only need to require it. Other libraries also rely on some native code, in that case you'll have to add these files to your app, otherwise the app will throw an error as soon as you try to use the library.

Here are the few steps to link your libraries that contain native code

Automatic linking

Step 1

Install a library with native dependencies:

npm install <library-with-native-dependencies> --save

Note: --save or --save-dev flag is very important for this step. React Native will link your libs based on dependencies and devDependencies in your package.json file.

Step 2

Link your native dependencies:

npx react-native link

Done! All libraries with native dependencies should be successfully linked to your iOS/Android project.

Note: If your iOS project is using CocoaPods (contains Podfile) and linked library has podspec file, then npx react-native link will link library using Podfile. To support non-trivial Podfiles add # Add new pods below this line comment to places where you expect pods to be added.

Manual linking

Step 1

If the library has native code, there must be an .xcodeproj file inside its folder. Drag this file to your project on Xcode (usually under the Libraries group on Xcode);

Step 2

Click on your main project file (the one that represents the .xcodeproj) select Build Phases and drag the static library from the Products folder inside the Library you are importing to Link Binary With Libraries

Step 3

Not every library will need this step, what you need to consider is:

Do I need to know the contents of the library at compile time?

What that means is, are you using this library on the native side or only in JavaScript? If you are only using it in JavaScript, you are good to go!

If you do need to call it from native, then we need to know the library's headers. To achieve that you have to go to your project's file, select Build Settings and search for Header Search Paths. There you should include the path to your library. (This documentation used to recommend using recursive, but this is no longer recommended, as it can cause subtle build failures, especially with CocoaPods.)

Edit this page
Last updated on
- + diff --git a/docs/next/linking-libraries-ios/index.html b/docs/next/linking-libraries-ios/index.html index c69cdb43faa..d7a1cf5cbba 100644 --- a/docs/next/linking-libraries-ios/index.html +++ b/docs/next/linking-libraries-ios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Linking Libraries

Not every app uses all the native capabilities, and including the code to support all those features would impact the binary size... But we still want to support adding these features whenever you need them.

With that in mind we exposed many of these features as independent static libraries.

For most of the libs it will be as quick as dragging two files, sometimes a third step will be necessary, but no more than that.

All the libraries we ship with React Native live on the Libraries folder in the root of the repository. Some of them are pure JavaScript, and you only need to require it. Other libraries also rely on some native code, in that case you'll have to add these files to your app, otherwise the app will throw an error as soon as you try to use the library.

Here are the few steps to link your libraries that contain native code

Automatic linking

Step 1

Install a library with native dependencies:

npm install <library-with-native-dependencies> --save

Note: --save or --save-dev flag is very important for this step. React Native will link your libs based on dependencies and devDependencies in your package.json file.

Step 2

Link your native dependencies:

npx react-native link

Done! All libraries with native dependencies should be successfully linked to your iOS/Android project.

Note: If your iOS project is using CocoaPods (contains Podfile) and linked library has podspec file, then npx react-native link will link library using Podfile. To support non-trivial Podfiles add # Add new pods below this line comment to places where you expect pods to be added.

Manual linking

Step 1

If the library has native code, there must be an .xcodeproj file inside its folder. Drag this file to your project on Xcode (usually under the Libraries group on Xcode);

Step 2

Click on your main project file (the one that represents the .xcodeproj) select Build Phases and drag the static library from the Products folder inside the Library you are importing to Link Binary With Libraries

Step 3

Not every library will need this step, what you need to consider is:

Do I need to know the contents of the library at compile time?

What that means is, are you using this library on the native side or only in JavaScript? If you are only using it in JavaScript, you are good to go!

If you do need to call it from native, then we need to know the library's headers. To achieve that you have to go to your project's file, select Build Settings and search for Header Search Paths. There you should include the path to your library. (This documentation used to recommend using recursive, but this is no longer recommended, as it can cause subtle build failures, especially with CocoaPods.)

Edit this page
Last updated on
- + diff --git a/docs/next/linking.html b/docs/next/linking.html index e62bf26c930..1b3ca79c7d6 100644 --- a/docs/next/linking.html +++ b/docs/next/linking.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Linking

Linking gives you a general interface to interact with both incoming and outgoing app links.

Every Link (URL) has a URL Scheme, some websites are prefixed with https:// or http:// and the http is the URL Scheme. Let's call it scheme for short.

In addition to https, you're likely also familiar with the mailto scheme. When you open a link with the mailto scheme, your operating system will open an installed mail application. Similarly, there are schemes for making phone calls and sending SMS. Read more about built-in URL schemes below.

Like using the mailto scheme, it's possible to link to other applications by using custom url schemes. For example, when you get a Magic Link email from Slack, the Launch Slack button is an anchor tag with an href that looks something like: slack://secret/magic-login/other-secret. Like with Slack, you can tell the operating system that you want to handle a custom scheme. When the Slack app opens, it receives the URL that was used to open it. This is often referred to as deep linking. Read more about how to get the deep link into your app.

Custom URL scheme isn't the only way to open your application on mobile. You don't want to use a custom URL scheme in links in the email because then the links would be broken on desktop. Instead, you want to use a regular https links such as https://www.myapp.io/records/1234546. and on mobile you want that link open your app. Android calls it Deep Links (Universal Links - iOS).

Built-in URL Schemes

As mentioned in the introduction, there are some URL schemes for core functionality that exist on every platform. The following is a non-exhaustive list, but covers the most commonly used schemes.

SchemeDescriptioniOSAndroid
mailtoOpen mail app, eg: mailto: support@expo.io✅✅
telOpen phone app, eg: tel:+123456789✅✅
smsOpen SMS app, eg: sms:+123456789✅✅
https / httpOpen web browser app, eg: https://expo.io✅✅

Enabling Deep Links

If you want to enable deep links in your app, please read the below guide:

For instructions on how to add support for deep linking on Android, refer to Enabling Deep Links for App Content - Add Intent Filters for Your Deep Links.

If you wish to receive the intent in an existing instance of MainActivity, you may set the launchMode of MainActivity to singleTask in AndroidManifest.xml. See <activity> documentation for more information.

<activity
android:name=".MainActivity"
android:launchMode="singleTask">

Handling Deep Links

There are two ways to handle URLs that open your app.

1. If the app is already open, the app is foregrounded and a Linking 'url' event is fired

You can handle these events with Linking.addEventListener('url', callback) - it calls callback({ url }) with the linked URL

2. If the app is not already open, it is opened and the url is passed in as the initialURL

You can handle these events with Linking.getInitialURL() - it returns a Promise that resolves to the URL, if there is one.

Example

Open Links and Deep Links (Universal Links)

Open Custom Settings

Get the Deep Link

Send Intents (Android)

Reference

Methods

addEventListener()

addEventListener(type, handler);

Add a handler to Linking changes by listening to the url event type and providing the handler.

canOpenURL()

canOpenURL(url);

Determine whether or not an installed app can handle a given URL.

The method returns a Promise object. When it is determined whether or not the given URL can be handled, the promise is resolved and the first parameter is whether or not it can be opened.

The Promise will reject on Android if it was impossible to check if the URL can be opened, and on iOS if you didn't add the specific scheme in the LSApplicationQueriesSchemes key inside Info.plist (see bellow).

Parameters:

NameTypeDescription
url
Required
stringThe URL to open.

For web URLs, the protocol ("http://", "https://") must be set accordingly!

This method has limitations on iOS 9+. From the official Apple documentation:

  • If your app is linked against an earlier version of iOS but is running in iOS 9.0 or later, you can call this method up to 50 times. After reaching that limit, subsequent calls always return false. If the user reinstalls or upgrades the app, iOS resets the limit.

As of iOS 9, your app also needs to provide the LSApplicationQueriesSchemes key inside Info.plist or canOpenURL() will always return false.

getInitialURL()

getInitialURL();

If the app launch was triggered by an app link, it will give the link url, otherwise it will give null.

To support deep linking on Android, refer http://developer.android.com/training/app-indexing/deep-linking.html#handling-intents

getInitialURL may return null while debugging is enabled. Disable the debugger to ensure it gets passed.

openSettings()

openSettings();

Open the Settings app and displays the app’s custom settings, if it has any.

openURL()

openURL(url);

Try to open the given url with any of the installed apps.

You can use other URLs, like a location (e.g. "geo:37.484847,-122.148386" on Android or "http://maps.apple.com/?ll=37.484847,-122.148386" on iOS), a contact, or any other URL that can be opened with the installed apps.

The method returns a Promise object. If the user confirms the open dialog or the url automatically opens, the promise is resolved. If the user cancels the open dialog or there are no registered applications for the url, the promise is rejected.

Parameters:

NameTypeDescription
url
Required
stringThe URL to open.

This method will fail if the system doesn't know how to open the specified URL. If you're passing in a non-http(s) URL, it's best to check canOpenURL() first.

For web URLs, the protocol ("http://", "https://") must be set accordingly!

This method may behave differently in a simulator e.g. "tel:" links are not able to be handled in the iOS simulator as there's no access to the dialer app.

removeEventListener()

removeEventListener(type, handler);

Remove a handler by passing the url event type and the handler.

sendIntent()
Android

sendIntent(action, extras);

Launch an Android intent with extras.

Parameters:

NameType
action
Required
string
extrasarray of {key: string, value: string, number, boolean}
Edit this page
Last updated on
- + diff --git a/docs/next/linking/index.html b/docs/next/linking/index.html index e62bf26c930..1b3ca79c7d6 100644 --- a/docs/next/linking/index.html +++ b/docs/next/linking/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Linking

Linking gives you a general interface to interact with both incoming and outgoing app links.

Every Link (URL) has a URL Scheme, some websites are prefixed with https:// or http:// and the http is the URL Scheme. Let's call it scheme for short.

In addition to https, you're likely also familiar with the mailto scheme. When you open a link with the mailto scheme, your operating system will open an installed mail application. Similarly, there are schemes for making phone calls and sending SMS. Read more about built-in URL schemes below.

Like using the mailto scheme, it's possible to link to other applications by using custom url schemes. For example, when you get a Magic Link email from Slack, the Launch Slack button is an anchor tag with an href that looks something like: slack://secret/magic-login/other-secret. Like with Slack, you can tell the operating system that you want to handle a custom scheme. When the Slack app opens, it receives the URL that was used to open it. This is often referred to as deep linking. Read more about how to get the deep link into your app.

Custom URL scheme isn't the only way to open your application on mobile. You don't want to use a custom URL scheme in links in the email because then the links would be broken on desktop. Instead, you want to use a regular https links such as https://www.myapp.io/records/1234546. and on mobile you want that link open your app. Android calls it Deep Links (Universal Links - iOS).

Built-in URL Schemes

As mentioned in the introduction, there are some URL schemes for core functionality that exist on every platform. The following is a non-exhaustive list, but covers the most commonly used schemes.

SchemeDescriptioniOSAndroid
mailtoOpen mail app, eg: mailto: support@expo.io✅✅
telOpen phone app, eg: tel:+123456789✅✅
smsOpen SMS app, eg: sms:+123456789✅✅
https / httpOpen web browser app, eg: https://expo.io✅✅

Enabling Deep Links

If you want to enable deep links in your app, please read the below guide:

For instructions on how to add support for deep linking on Android, refer to Enabling Deep Links for App Content - Add Intent Filters for Your Deep Links.

If you wish to receive the intent in an existing instance of MainActivity, you may set the launchMode of MainActivity to singleTask in AndroidManifest.xml. See <activity> documentation for more information.

<activity
android:name=".MainActivity"
android:launchMode="singleTask">

Handling Deep Links

There are two ways to handle URLs that open your app.

1. If the app is already open, the app is foregrounded and a Linking 'url' event is fired

You can handle these events with Linking.addEventListener('url', callback) - it calls callback({ url }) with the linked URL

2. If the app is not already open, it is opened and the url is passed in as the initialURL

You can handle these events with Linking.getInitialURL() - it returns a Promise that resolves to the URL, if there is one.

Example

Open Links and Deep Links (Universal Links)

Open Custom Settings

Get the Deep Link

Send Intents (Android)

Reference

Methods

addEventListener()

addEventListener(type, handler);

Add a handler to Linking changes by listening to the url event type and providing the handler.

canOpenURL()

canOpenURL(url);

Determine whether or not an installed app can handle a given URL.

The method returns a Promise object. When it is determined whether or not the given URL can be handled, the promise is resolved and the first parameter is whether or not it can be opened.

The Promise will reject on Android if it was impossible to check if the URL can be opened, and on iOS if you didn't add the specific scheme in the LSApplicationQueriesSchemes key inside Info.plist (see bellow).

Parameters:

NameTypeDescription
url
Required
stringThe URL to open.

For web URLs, the protocol ("http://", "https://") must be set accordingly!

This method has limitations on iOS 9+. From the official Apple documentation:

  • If your app is linked against an earlier version of iOS but is running in iOS 9.0 or later, you can call this method up to 50 times. After reaching that limit, subsequent calls always return false. If the user reinstalls or upgrades the app, iOS resets the limit.

As of iOS 9, your app also needs to provide the LSApplicationQueriesSchemes key inside Info.plist or canOpenURL() will always return false.

getInitialURL()

getInitialURL();

If the app launch was triggered by an app link, it will give the link url, otherwise it will give null.

To support deep linking on Android, refer http://developer.android.com/training/app-indexing/deep-linking.html#handling-intents

getInitialURL may return null while debugging is enabled. Disable the debugger to ensure it gets passed.

openSettings()

openSettings();

Open the Settings app and displays the app’s custom settings, if it has any.

openURL()

openURL(url);

Try to open the given url with any of the installed apps.

You can use other URLs, like a location (e.g. "geo:37.484847,-122.148386" on Android or "http://maps.apple.com/?ll=37.484847,-122.148386" on iOS), a contact, or any other URL that can be opened with the installed apps.

The method returns a Promise object. If the user confirms the open dialog or the url automatically opens, the promise is resolved. If the user cancels the open dialog or there are no registered applications for the url, the promise is rejected.

Parameters:

NameTypeDescription
url
Required
stringThe URL to open.

This method will fail if the system doesn't know how to open the specified URL. If you're passing in a non-http(s) URL, it's best to check canOpenURL() first.

For web URLs, the protocol ("http://", "https://") must be set accordingly!

This method may behave differently in a simulator e.g. "tel:" links are not able to be handled in the iOS simulator as there's no access to the dialer app.

removeEventListener()

removeEventListener(type, handler);

Remove a handler by passing the url event type and the handler.

sendIntent()
Android

sendIntent(action, extras);

Launch an Android intent with extras.

Parameters:

NameType
action
Required
string
extrasarray of {key: string, value: string, number, boolean}
Edit this page
Last updated on
- + diff --git a/docs/next/modal.html b/docs/next/modal.html index 9b505cab3c6..01443fae167 100644 --- a/docs/next/modal.html +++ b/docs/next/modal.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Modal

The Modal component is a basic way to present content above an enclosing view.

Example

Reference

Props

animated

Deprecated. Use the animationType prop instead.

animationType

The animationType prop controls how the modal animates.

Possible values:

  • slide slides in from the bottom,
  • fade fades into view,
  • none appears without an animation.
TypeDefault
enum('none', 'slide', 'fade')none

hardwareAccelerated
Android

The hardwareAccelerated prop controls whether to force hardware acceleration for the underlying window.

TypeDefault
boolfalse

onDismiss
iOS

The onDismiss prop allows passing a function that will be called once the modal has been dismissed.

Type
function

onOrientationChange
iOS

The onOrientationChange callback is called when the orientation changes while the modal is being displayed. The orientation provided is only 'portrait' or 'landscape'. This callback is also called on initial render, regardless of the current orientation.

Type
function

onRequestClose

The onRequestClose callback is called when the user taps the hardware back button on Android or the menu button on Apple TV. Because of this required prop, be aware that BackHandler events will not be emitted as long as the modal is open.

Type
function
Required
Android
TV
function
iOS

onShow

The onShow prop allows passing a function that will be called once the modal has been shown.

Type
function

presentationStyle
iOS

The presentationStyle prop controls how the modal appears (generally on larger devices such as iPad or plus-sized iPhones). See https://developer.apple.com/reference/uikit/uimodalpresentationstyle for details.

Possible values:

  • fullScreen covers the screen completely
  • pageSheet covers portrait-width view centered (only on larger devices)
  • formSheet covers narrow-width view centered (only on larger devices)
  • overFullScreen covers the screen completely, but allows transparency
TypeDefault
enum('fullScreen', 'pageSheet', 'formSheet', 'overFullScreen')fullScreen if transparent={false}
overFullScreen if transparent={true}

statusBarTranslucent
Android

The statusBarTranslucent prop determines whether your modal should go under the system statusbar.

TypeDefault
boolfalse

supportedOrientations
iOS

The supportedOrientations prop allows the modal to be rotated to any of the specified orientations. On iOS, the modal is still restricted by what's specified in your app's Info.plist's UISupportedInterfaceOrientations field.

When using presentationStyle of pageSheet or formSheet, this property will be ignored by iOS.

TypeDefault
array of enums('portrait', 'portrait-upside-down', 'landscape', 'landscape-left', 'landscape-right')['portrait']

transparent

The transparent prop determines whether your modal will fill the entire view. Setting this to true will render the modal over a transparent background.

TypeDefault
boolfalse

visible

The visible prop determines whether your modal is visible.

TypeDefault
booltrue
Edit this page
Last updated on
- + diff --git a/docs/next/modal/index.html b/docs/next/modal/index.html index 9b505cab3c6..01443fae167 100644 --- a/docs/next/modal/index.html +++ b/docs/next/modal/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Modal

The Modal component is a basic way to present content above an enclosing view.

Example

Reference

Props

animated

Deprecated. Use the animationType prop instead.

animationType

The animationType prop controls how the modal animates.

Possible values:

  • slide slides in from the bottom,
  • fade fades into view,
  • none appears without an animation.
TypeDefault
enum('none', 'slide', 'fade')none

hardwareAccelerated
Android

The hardwareAccelerated prop controls whether to force hardware acceleration for the underlying window.

TypeDefault
boolfalse

onDismiss
iOS

The onDismiss prop allows passing a function that will be called once the modal has been dismissed.

Type
function

onOrientationChange
iOS

The onOrientationChange callback is called when the orientation changes while the modal is being displayed. The orientation provided is only 'portrait' or 'landscape'. This callback is also called on initial render, regardless of the current orientation.

Type
function

onRequestClose

The onRequestClose callback is called when the user taps the hardware back button on Android or the menu button on Apple TV. Because of this required prop, be aware that BackHandler events will not be emitted as long as the modal is open.

Type
function
Required
Android
TV
function
iOS

onShow

The onShow prop allows passing a function that will be called once the modal has been shown.

Type
function

presentationStyle
iOS

The presentationStyle prop controls how the modal appears (generally on larger devices such as iPad or plus-sized iPhones). See https://developer.apple.com/reference/uikit/uimodalpresentationstyle for details.

Possible values:

  • fullScreen covers the screen completely
  • pageSheet covers portrait-width view centered (only on larger devices)
  • formSheet covers narrow-width view centered (only on larger devices)
  • overFullScreen covers the screen completely, but allows transparency
TypeDefault
enum('fullScreen', 'pageSheet', 'formSheet', 'overFullScreen')fullScreen if transparent={false}
overFullScreen if transparent={true}

statusBarTranslucent
Android

The statusBarTranslucent prop determines whether your modal should go under the system statusbar.

TypeDefault
boolfalse

supportedOrientations
iOS

The supportedOrientations prop allows the modal to be rotated to any of the specified orientations. On iOS, the modal is still restricted by what's specified in your app's Info.plist's UISupportedInterfaceOrientations field.

When using presentationStyle of pageSheet or formSheet, this property will be ignored by iOS.

TypeDefault
array of enums('portrait', 'portrait-upside-down', 'landscape', 'landscape-left', 'landscape-right')['portrait']

transparent

The transparent prop determines whether your modal will fill the entire view. Setting this to true will render the modal over a transparent background.

TypeDefault
boolfalse

visible

The visible prop determines whether your modal is visible.

TypeDefault
booltrue
Edit this page
Last updated on
- + diff --git a/docs/next/more-resources.html b/docs/next/more-resources.html index 55e7585ae6d..4c5a07db5b2 100644 --- a/docs/next/more-resources.html +++ b/docs/next/more-resources.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

More Resources

There’s always more to learn: developer workflows, shipping to app stores, internationalization, security and more.

Where to go from here

Dive deep

IDEs

We recommend using the VS Code code editor and its handy React Native tools.

Platforms to try

Expo is a framework of tools and services for React Native that focuses on letting you build React Native apps without ever touching Xcode or Android Studio. If you have a web development background, this might appeal to you.

Ignite is a starter kit CLI with several React Native boilerplates. The latest, Ignite Bowser, uses MobX-State-Tree for state management, React Navigation, and other common libraries. It has generators for components, models, and more, and supports Expo out of the box. If you are looking for a preconfigured tech stack, Ignite could be perfect for you.

Example Apps

Try out apps from the Showcase to see what React Native is capable of! Looking for something more hands on? Check out this set of example apps on GitHub. You can look at their source code—try running one on a simulator or device.

Find, make, and share your own Native Components and Modules

React Native has a community of thousands of developers like you making content, tools, tutorials—and Native Components!

Can’t find what you’re looking for in the Core Components? Visit React Native Directory to find what the community has been creating.

Interested in making your own Native Component or Module? Making modules for your own use case and sharing them with others on NPM and GitHub helps grow the React Native ecosystem and community! Read the guides to making your own Native Modules (Android, iOS) and Native Components (Android, iOS).

Edit this page
Last updated on
- + diff --git a/docs/next/more-resources/index.html b/docs/next/more-resources/index.html index 55e7585ae6d..4c5a07db5b2 100644 --- a/docs/next/more-resources/index.html +++ b/docs/next/more-resources/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

More Resources

There’s always more to learn: developer workflows, shipping to app stores, internationalization, security and more.

Where to go from here

Dive deep

IDEs

We recommend using the VS Code code editor and its handy React Native tools.

Platforms to try

Expo is a framework of tools and services for React Native that focuses on letting you build React Native apps without ever touching Xcode or Android Studio. If you have a web development background, this might appeal to you.

Ignite is a starter kit CLI with several React Native boilerplates. The latest, Ignite Bowser, uses MobX-State-Tree for state management, React Navigation, and other common libraries. It has generators for components, models, and more, and supports Expo out of the box. If you are looking for a preconfigured tech stack, Ignite could be perfect for you.

Example Apps

Try out apps from the Showcase to see what React Native is capable of! Looking for something more hands on? Check out this set of example apps on GitHub. You can look at their source code—try running one on a simulator or device.

Find, make, and share your own Native Components and Modules

React Native has a community of thousands of developers like you making content, tools, tutorials—and Native Components!

Can’t find what you’re looking for in the Core Components? Visit React Native Directory to find what the community has been creating.

Interested in making your own Native Component or Module? Making modules for your own use case and sharing them with others on NPM and GitHub helps grow the React Native ecosystem and community! Read the guides to making your own Native Modules (Android, iOS) and Native Components (Android, iOS).

Edit this page
Last updated on
- + diff --git a/docs/next/native-components-android.html b/docs/next/native-components-android.html index ea2758e6205..ead11f9e6ce 100644 --- a/docs/next/native-components-android.html +++ b/docs/next/native-components-android.html @@ -19,7 +19,7 @@ - + @@ -43,7 +43,7 @@
var RCTMyCustomView = requireNativeComponent(`RCTMyCustomView`);
Edit this page
Last updated on
- + diff --git a/docs/next/native-components-android/index.html b/docs/next/native-components-android/index.html index ea2758e6205..ead11f9e6ce 100644 --- a/docs/next/native-components-android/index.html +++ b/docs/next/native-components-android/index.html @@ -19,7 +19,7 @@ - + @@ -43,7 +43,7 @@
var RCTMyCustomView = requireNativeComponent(`RCTMyCustomView`);
Edit this page
Last updated on
- + diff --git a/docs/next/native-components-ios.html b/docs/next/native-components-ios.html index e3fe72cb252..afeed717a36 100644 --- a/docs/next/native-components-ios.html +++ b/docs/next/native-components-ios.html @@ -19,7 +19,7 @@ - + @@ -96,7 +96,7 @@
return @{
@"ComponentHeight": @(CGRectGetHeight(dp.frame)),
@"ComponentWidth": @(CGRectGetWidth(dp.frame)),
@"DatePickerModes": @{
@"time": @(UIDatePickerModeTime),
@"date": @(UIDatePickerModeDate),
@"datetime": @(UIDatePickerModeDateAndTime),
}
};
}

This guide covered many of the aspects of bridging over custom native components, but there is even more you might need to consider, such as custom hooks for inserting and laying out subviews. If you want to go even deeper, check out the source code of some of the implemented components.

Edit this page
Last updated on
- + diff --git a/docs/next/native-components-ios/index.html b/docs/next/native-components-ios/index.html index e3fe72cb252..afeed717a36 100644 --- a/docs/next/native-components-ios/index.html +++ b/docs/next/native-components-ios/index.html @@ -19,7 +19,7 @@ - + @@ -96,7 +96,7 @@
return @{
@"ComponentHeight": @(CGRectGetHeight(dp.frame)),
@"ComponentWidth": @(CGRectGetWidth(dp.frame)),
@"DatePickerModes": @{
@"time": @(UIDatePickerModeTime),
@"date": @(UIDatePickerModeDate),
@"datetime": @(UIDatePickerModeDateAndTime),
}
};
}

This guide covered many of the aspects of bridging over custom native components, but there is even more you might need to consider, such as custom hooks for inserting and laying out subviews. If you want to go even deeper, check out the source code of some of the implemented components.

Edit this page
Last updated on
- + diff --git a/docs/next/native-modules-android.html b/docs/next/native-modules-android.html index ddd0036b954..2299b0d7b12 100644 --- a/docs/next/native-modules-android.html +++ b/docs/next/native-modules-android.html @@ -19,7 +19,7 @@ - + @@ -67,7 +67,7 @@
currentActivity.startActivityForResult(chooserIntent, IMAGE_PICKER_REQUEST);
} catch (Exception e) {
mPickerPromise.reject(E_FAILED_TO_SHOW_PICKER, e);
mPickerPromise = null;
}
}
}

Listening to Lifecycle Events

Listening to the activity's LifeCycle events such as onResume, onPause etc. is very similar to how ActivityEventListener was implemented. The module must implement LifecycleEventListener. Then, you need to register a listener in the module's constructor like so:

reactContext.addLifecycleEventListener(this);

Now you can listen to the activity's LifeCycle events by implementing the following methods:

@Override
public void onHostResume() {
// Activity `onResume`
}
@Override
public void onHostPause() {
// Activity `onPause`
}
@Override
public void onHostDestroy() {
// Activity `onDestroy`
}

Threading

To date, on Android, all native module async methods execute on one thread. Native modules should not have any assumptions about what thread they are being called on, as the current assignment is subject to change in the future. If a blocking call is required, the heavy work should be dispatched to an internally managed worker thread, and any callbacks distributed from there.

Edit this page
Last updated on
- + diff --git a/docs/next/native-modules-android/index.html b/docs/next/native-modules-android/index.html index ddd0036b954..2299b0d7b12 100644 --- a/docs/next/native-modules-android/index.html +++ b/docs/next/native-modules-android/index.html @@ -19,7 +19,7 @@ - + @@ -67,7 +67,7 @@
currentActivity.startActivityForResult(chooserIntent, IMAGE_PICKER_REQUEST);
} catch (Exception e) {
mPickerPromise.reject(E_FAILED_TO_SHOW_PICKER, e);
mPickerPromise = null;
}
}
}

Listening to Lifecycle Events

Listening to the activity's LifeCycle events such as onResume, onPause etc. is very similar to how ActivityEventListener was implemented. The module must implement LifecycleEventListener. Then, you need to register a listener in the module's constructor like so:

reactContext.addLifecycleEventListener(this);

Now you can listen to the activity's LifeCycle events by implementing the following methods:

@Override
public void onHostResume() {
// Activity `onResume`
}
@Override
public void onHostPause() {
// Activity `onPause`
}
@Override
public void onHostDestroy() {
// Activity `onDestroy`
}

Threading

To date, on Android, all native module async methods execute on one thread. Native modules should not have any assumptions about what thread they are being called on, as the current assignment is subject to change in the future. If a blocking call is required, the heavy work should be dispatched to an internally managed worker thread, and any callbacks distributed from there.

Edit this page
Last updated on
- + diff --git a/docs/next/native-modules-intro.html b/docs/next/native-modules-intro.html index 493af965687..0536b09fe8e 100644 --- a/docs/next/native-modules-intro.html +++ b/docs/next/native-modules-intro.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Native Modules Intro

Sometimes a React Native app needs to access a native platform API that is not available by default in JavaScript, for example the native APIs to access Apple or Google Pay. Maybe you want to reuse some existing Objective-C, Swift, Java or C++ libraries without having to reimplement it in JavaScript, or write some high performance, multi-threaded code for things like image processing.

The NativeModule system exposes instances of Java/Objective-C/C++ (native) classes to JavaScript (JS) as JS objects, thereby allowing you to execute arbitrary native code from within JS. While we don't expect this feature to be part of the usual development process, it is essential that it exists. If React Native doesn't export a native API that your JS app needs you should be able to export it yourself!

Native Module Setup

There are two ways to write a native module for your React Native application:

  1. Directly within your React Native application’s iOS/Android projects
  2. As a NPM package that can be installed as a dependency by your/other React Native applications

This guide will first walk you through implementing a native module directly within a React Native application. However the native module you build in the following guide can be distributed as an NPM package. Check out the Setting Up a Native Module as a NPM Package guide if you are interested in doing so.

Getting Started

In the following sections we will walk you through guides on how to build a native module directly within a React Native application. As a prerequisite, you will need a React Native application to work within. You can follow the steps here to setup a React Native application if you do not already have one.

Imagine that you want to access the iOS/Android native calendar APIs from JavaScript within a React Native application in order to create calendar events. React Native does not expose a JavaScript API to communicate with the native calendar libraries. However, through native modules, you can write native code that communicates with native calendar APIs. Then you can invoke that native code through JavaScript in your React Native application.

In the following sections you will create such a Calendar native module for both Android and iOS.

Edit this page
Last updated on
- + diff --git a/docs/next/native-modules-intro/index.html b/docs/next/native-modules-intro/index.html index 493af965687..0536b09fe8e 100644 --- a/docs/next/native-modules-intro/index.html +++ b/docs/next/native-modules-intro/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Native Modules Intro

Sometimes a React Native app needs to access a native platform API that is not available by default in JavaScript, for example the native APIs to access Apple or Google Pay. Maybe you want to reuse some existing Objective-C, Swift, Java or C++ libraries without having to reimplement it in JavaScript, or write some high performance, multi-threaded code for things like image processing.

The NativeModule system exposes instances of Java/Objective-C/C++ (native) classes to JavaScript (JS) as JS objects, thereby allowing you to execute arbitrary native code from within JS. While we don't expect this feature to be part of the usual development process, it is essential that it exists. If React Native doesn't export a native API that your JS app needs you should be able to export it yourself!

Native Module Setup

There are two ways to write a native module for your React Native application:

  1. Directly within your React Native application’s iOS/Android projects
  2. As a NPM package that can be installed as a dependency by your/other React Native applications

This guide will first walk you through implementing a native module directly within a React Native application. However the native module you build in the following guide can be distributed as an NPM package. Check out the Setting Up a Native Module as a NPM Package guide if you are interested in doing so.

Getting Started

In the following sections we will walk you through guides on how to build a native module directly within a React Native application. As a prerequisite, you will need a React Native application to work within. You can follow the steps here to setup a React Native application if you do not already have one.

Imagine that you want to access the iOS/Android native calendar APIs from JavaScript within a React Native application in order to create calendar events. React Native does not expose a JavaScript API to communicate with the native calendar libraries. However, through native modules, you can write native code that communicates with native calendar APIs. Then you can invoke that native code through JavaScript in your React Native application.

In the following sections you will create such a Calendar native module for both Android and iOS.

Edit this page
Last updated on
- + diff --git a/docs/next/native-modules-ios.html b/docs/next/native-modules-ios.html index c8cabe62860..2629787c61a 100644 --- a/docs/next/native-modules-ios.html +++ b/docs/next/native-modules-ios.html @@ -19,7 +19,7 @@ - + @@ -64,7 +64,7 @@
@end

For those of you new to Swift and Objective-C, whenever you mix the two languages in an iOS project, you will also need an additional bridging file, known as a bridging header, to expose the Objective-C files to Swift. Xcode will offer to create this header file for you if you add your Swift file to your app through the Xcode File>New File menu option. You will need to import RCTBridgeModule.h in this header file.

// CalendarManager-Bridging-Header.h
#import <React/RCTBridgeModule.h>

You can also use RCT_EXTERN_REMAP_MODULE and _RCT_EXTERN_REMAP_METHOD to alter the JavaScript name of the module or methods you are exporting. For more information see RCTBridgeModule.

Important when making third party modules: Static libraries with Swift are only supported in Xcode 9 and later. In order for the Xcode project to build when you use Swift in the iOS static library you include in the module, your main app project must contain Swift code and a bridging header itself. If your app project does not contain any Swift code, a workaround can be a single empty .swift file and an empty bridging header.

Reserved Method Names

invalidate()

Native modules can conform to the RCTInvalidating protocol on iOS by implementing the invalidate() method. This method can be invoked when the native bridge is invalidated (ie: on devmode reload). Please use this mechanism as necessary to do the required cleanup for your native module.

Edit this page
Last updated on
- + diff --git a/docs/next/native-modules-ios/index.html b/docs/next/native-modules-ios/index.html index c8cabe62860..2629787c61a 100644 --- a/docs/next/native-modules-ios/index.html +++ b/docs/next/native-modules-ios/index.html @@ -19,7 +19,7 @@ - + @@ -64,7 +64,7 @@
@end

For those of you new to Swift and Objective-C, whenever you mix the two languages in an iOS project, you will also need an additional bridging file, known as a bridging header, to expose the Objective-C files to Swift. Xcode will offer to create this header file for you if you add your Swift file to your app through the Xcode File>New File menu option. You will need to import RCTBridgeModule.h in this header file.

// CalendarManager-Bridging-Header.h
#import <React/RCTBridgeModule.h>

You can also use RCT_EXTERN_REMAP_MODULE and _RCT_EXTERN_REMAP_METHOD to alter the JavaScript name of the module or methods you are exporting. For more information see RCTBridgeModule.

Important when making third party modules: Static libraries with Swift are only supported in Xcode 9 and later. In order for the Xcode project to build when you use Swift in the iOS static library you include in the module, your main app project must contain Swift code and a bridging header itself. If your app project does not contain any Swift code, a workaround can be a single empty .swift file and an empty bridging header.

Reserved Method Names

invalidate()

Native modules can conform to the RCTInvalidating protocol on iOS by implementing the invalidate() method. This method can be invoked when the native bridge is invalidated (ie: on devmode reload). Please use this mechanism as necessary to do the required cleanup for your native module.

Edit this page
Last updated on
- + diff --git a/docs/next/native-modules-setup.html b/docs/next/native-modules-setup.html index 0520eaf0c69..5a993001cf9 100644 --- a/docs/next/native-modules-setup.html +++ b/docs/next/native-modules-setup.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Native Modules NPM Package Setup

Native modules are usually distributed as npm packages, except that on top of the usual JavaScript they will include some native code per platform. To understand more about npm packages you may find this guide useful.

To get set up with the basic project structure for a native module we will use the community tool called Bob. You can go ahead further and dive deep into how that library works, but for our needs we will only execute the basic create script:

npx react-native-builder-bob create react-native-awesome-module

Where react-native-awesome-module is the name you would like for the new module. After doing this you will navigate into react-native-awesome-module folder and bootstrap the example project by running:

yarn

When the bootstrap is done, you will be able to start the example app by executing one of the following commands:

# Android app
yarn example android
# iOS app
yarn example ios

When all steps above are done, you will be able to continue with Android Native Modules or iOS Native Modules guides to add in some code.

For a less opinionated setup, have a look at the third party tool create-react-native-module.

Edit this page
Last updated on
- + diff --git a/docs/next/native-modules-setup/index.html b/docs/next/native-modules-setup/index.html index 0520eaf0c69..5a993001cf9 100644 --- a/docs/next/native-modules-setup/index.html +++ b/docs/next/native-modules-setup/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Native Modules NPM Package Setup

Native modules are usually distributed as npm packages, except that on top of the usual JavaScript they will include some native code per platform. To understand more about npm packages you may find this guide useful.

To get set up with the basic project structure for a native module we will use the community tool called Bob. You can go ahead further and dive deep into how that library works, but for our needs we will only execute the basic create script:

npx react-native-builder-bob create react-native-awesome-module

Where react-native-awesome-module is the name you would like for the new module. After doing this you will navigate into react-native-awesome-module folder and bootstrap the example project by running:

yarn

When the bootstrap is done, you will be able to start the example app by executing one of the following commands:

# Android app
yarn example android
# iOS app
yarn example ios

When all steps above are done, you will be able to continue with Android Native Modules or iOS Native Modules guides to add in some code.

For a less opinionated setup, have a look at the third party tool create-react-native-module.

Edit this page
Last updated on
- + diff --git a/docs/next/navigation.html b/docs/next/navigation.html index d1523fc1ab6..b84fc5c59fc 100644 --- a/docs/next/navigation.html +++ b/docs/next/navigation.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
const MyStack = () => {
return (
<NavigationContainer>
<Stack.Navigator>
<Stack.Screen
name="Home"
component={HomeScreen}
options={{ title: 'Welcome' }}
/>
<Stack.Screen name="Profile" component={ProfileScreen} />
</Stack.Navigator>
</NavigationContainer>
);
};

In this example, there are 2 screens (Home and Profile) defined using the Stack.Screen component. Similarly, you can define as many screens as you like.

You can set options such as the screen title for each screen in the options prop of Stack.Screen.

Each screen takes a component prop that is a React component. Those components receive a prop called navigation which has various methods to link to other screens. For example, you can use navigation.navigate to go to the Profile screen:

const HomeScreen = ({ navigation }) => {
return (
<Button
title="Go to Jane's profile"
onPress={() =>
navigation.navigate('Profile', { name: 'Jane' })
}
/>
);
};
const ProfileScreen = ({ navigation, route }) => {
return <Text>This is {route.params.name}'s profile</Text>;
};

The views in the stack navigator use native components and the Animated library to deliver 60fps animations that are run on the native thread. Plus, the animations and gestures can be customized.

React Navigation also has packages for different kind of navigators such as tabs and drawer. You can use them to implement various patterns in your app.

For a complete intro to React Navigation, follow the React Navigation Getting Started Guide.

Edit this page
Last updated on
- + diff --git a/docs/next/navigation/index.html b/docs/next/navigation/index.html index d1523fc1ab6..b84fc5c59fc 100644 --- a/docs/next/navigation/index.html +++ b/docs/next/navigation/index.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
const MyStack = () => {
return (
<NavigationContainer>
<Stack.Navigator>
<Stack.Screen
name="Home"
component={HomeScreen}
options={{ title: 'Welcome' }}
/>
<Stack.Screen name="Profile" component={ProfileScreen} />
</Stack.Navigator>
</NavigationContainer>
);
};

In this example, there are 2 screens (Home and Profile) defined using the Stack.Screen component. Similarly, you can define as many screens as you like.

You can set options such as the screen title for each screen in the options prop of Stack.Screen.

Each screen takes a component prop that is a React component. Those components receive a prop called navigation which has various methods to link to other screens. For example, you can use navigation.navigate to go to the Profile screen:

const HomeScreen = ({ navigation }) => {
return (
<Button
title="Go to Jane's profile"
onPress={() =>
navigation.navigate('Profile', { name: 'Jane' })
}
/>
);
};
const ProfileScreen = ({ navigation, route }) => {
return <Text>This is {route.params.name}'s profile</Text>;
};

The views in the stack navigator use native components and the Animated library to deliver 60fps animations that are run on the native thread. Plus, the animations and gestures can be customized.

React Navigation also has packages for different kind of navigators such as tabs and drawer. You can use them to implement various patterns in your app.

For a complete intro to React Navigation, follow the React Navigation Getting Started Guide.

Edit this page
Last updated on
- + diff --git a/docs/next/network.html b/docs/next/network.html index 992012196c1..aed23d43592 100644 --- a/docs/next/network.html +++ b/docs/next/network.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
ws.onclose = (e) => {
// connection closed
console.log(e.code, e.reason);
};

Known Issues with fetch and cookie based authentication

The following options are currently not working with fetch

Edit this page
Last updated on
- + diff --git a/docs/next/network/index.html b/docs/next/network/index.html index 992012196c1..aed23d43592 100644 --- a/docs/next/network/index.html +++ b/docs/next/network/index.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
ws.onclose = (e) => {
// connection closed
console.log(e.code, e.reason);
};

Known Issues with fetch and cookie based authentication

The following options are currently not working with fetch

Edit this page
Last updated on
- + diff --git a/docs/next/optimizing-flatlist-configuration.html b/docs/next/optimizing-flatlist-configuration.html index 5af5e54853f..b2bfd478cab 100644 --- a/docs/next/optimizing-flatlist-configuration.html +++ b/docs/next/optimizing-flatlist-configuration.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// ...
}
Edit this page
Last updated on
- + diff --git a/docs/next/optimizing-flatlist-configuration/index.html b/docs/next/optimizing-flatlist-configuration/index.html index 5af5e54853f..b2bfd478cab 100644 --- a/docs/next/optimizing-flatlist-configuration/index.html +++ b/docs/next/optimizing-flatlist-configuration/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// ...
}
Edit this page
Last updated on
- + diff --git a/docs/next/out-of-tree-platforms.html b/docs/next/out-of-tree-platforms.html index c1321c570cc..cb8b3d472e7 100644 --- a/docs/next/out-of-tree-platforms.html +++ b/docs/next/out-of-tree-platforms.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Out-of-Tree Platforms

React Native is not only for Android and iOS - there are community-supported projects that bring it to other platforms, such as:

Creating your own React Native platform

Right now the process of creating a React Native platform from scratch is not very well documented - one of the goals of the upcoming re-architecture (Fabric) is to make maintaining a platform easier.

Bundling

As of React Native 0.57 you can now register your React Native platform with React Native's JavaScript bundler, Metro. This means you can pass --platform example to npx react-native bundle, and it will look for JavaScript files with the .example.js suffix.

To register your platform with RNPM, your module's name must match one of these patterns:

  • react-native-example - It will search all top-level modules that start with react-native-
  • @org/react-native-example - It will search for modules that start with react-native- under any scope
  • @react-native-example/module - It will search in all modules under scopes with names starting with @react-native-

You must also have an entry in your package.json like this:

{
"rnpm": {
"haste": {
"providesModuleNodeModules": ["react-native-example"],
"platforms": ["example"]
}
}
}

"providesModuleNodeModules" is an array of modules that will get added to the Haste module search path, and "platforms" is an array of platform suffixes that will be added as valid platforms.

Edit this page
Last updated on
- + diff --git a/docs/next/out-of-tree-platforms/index.html b/docs/next/out-of-tree-platforms/index.html index c1321c570cc..cb8b3d472e7 100644 --- a/docs/next/out-of-tree-platforms/index.html +++ b/docs/next/out-of-tree-platforms/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Out-of-Tree Platforms

React Native is not only for Android and iOS - there are community-supported projects that bring it to other platforms, such as:

Creating your own React Native platform

Right now the process of creating a React Native platform from scratch is not very well documented - one of the goals of the upcoming re-architecture (Fabric) is to make maintaining a platform easier.

Bundling

As of React Native 0.57 you can now register your React Native platform with React Native's JavaScript bundler, Metro. This means you can pass --platform example to npx react-native bundle, and it will look for JavaScript files with the .example.js suffix.

To register your platform with RNPM, your module's name must match one of these patterns:

  • react-native-example - It will search all top-level modules that start with react-native-
  • @org/react-native-example - It will search for modules that start with react-native- under any scope
  • @react-native-example/module - It will search in all modules under scopes with names starting with @react-native-

You must also have an entry in your package.json like this:

{
"rnpm": {
"haste": {
"providesModuleNodeModules": ["react-native-example"],
"platforms": ["example"]
}
}
}

"providesModuleNodeModules" is an array of modules that will get added to the Haste module search path, and "platforms" is an array of platform suffixes that will be added as valid platforms.

Edit this page
Last updated on
- + diff --git a/docs/next/panresponder.html b/docs/next/panresponder.html index cf455b3d3c6..469999e37c3 100644 --- a/docs/next/panresponder.html +++ b/docs/next/panresponder.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
return <View {...panResponder.panHandlers} />;
};

Example

PanResponder works with Animated API to help build complex gestures in the UI. The following example contains an animated View component which can be dragged freely across the screen

Try the PanResponder example in RNTester.

Reference

Methods

create()

static create(config)

Parameters:

NameTypeDescription
config
Required
objectRefer below

The config object provides enhanced versions of all of the responder callbacks that provide not only the PressEvent, but also the PanResponder gesture state, by replacing the word Responder with PanResponder in each of the typical onResponder* callbacks. For example, the config object would look like:

In general, for events that have capture equivalents, we update the gestureState once in the capture phase and can use it in the bubble phase as well.

Be careful with onStartShould* callbacks. They only reflect updated gestureState for start/end events that bubble/capture to the Node. Once the node is the responder, you can rely on every start/end event being processed by the gesture and gestureState being updated accordingly. (numberActiveTouches) may not be totally accurate unless you are the responder.

Edit this page
Last updated on
- + diff --git a/docs/next/panresponder/index.html b/docs/next/panresponder/index.html index cf455b3d3c6..469999e37c3 100644 --- a/docs/next/panresponder/index.html +++ b/docs/next/panresponder/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
return <View {...panResponder.panHandlers} />;
};

Example

PanResponder works with Animated API to help build complex gestures in the UI. The following example contains an animated View component which can be dragged freely across the screen

Try the PanResponder example in RNTester.

Reference

Methods

create()

static create(config)

Parameters:

NameTypeDescription
config
Required
objectRefer below

The config object provides enhanced versions of all of the responder callbacks that provide not only the PressEvent, but also the PanResponder gesture state, by replacing the word Responder with PanResponder in each of the typical onResponder* callbacks. For example, the config object would look like:

In general, for events that have capture equivalents, we update the gestureState once in the capture phase and can use it in the bubble phase as well.

Be careful with onStartShould* callbacks. They only reflect updated gestureState for start/end events that bubble/capture to the Node. Once the node is the responder, you can rely on every start/end event being processed by the gesture and gestureState being updated accordingly. (numberActiveTouches) may not be totally accurate unless you are the responder.

Edit this page
Last updated on
- + diff --git a/docs/next/performance.html b/docs/next/performance.html index 626a94d82cc..9fc2cc5f18d 100644 --- a/docs/next/performance.html +++ b/docs/next/performance.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Performance Overview

A compelling reason for using React Native instead of WebView-based tools is to achieve 60 frames per second and a native look and feel to your apps. Where possible, we would like for React Native to do the right thing and help you to focus on your app instead of performance optimization, but there are areas where we're not quite there yet, and others where React Native (similar to writing native code directly) cannot possibly determine the best way to optimize for you and so manual intervention will be necessary. We try our best to deliver buttery-smooth UI performance by default, but sometimes that isn't possible.

This guide is intended to teach you some basics to help you to troubleshoot performance issues, as well as discuss common sources of problems and their suggested solutions.

What you need to know about frames

Your grandparents' generation called movies "moving pictures" for a reason: realistic motion in video is an illusion created by quickly changing static images at a consistent speed. We refer to each of these images as frames. The number of frames that is displayed each second has a direct impact on how smooth and ultimately life-like a video (or user interface) seems to be. iOS devices display 60 frames per second, which gives you and the UI system about 16.67ms to do all of the work needed to generate the static image (frame) that the user will see on the screen for that interval. If you are unable to do the work necessary to generate that frame within the allotted 16.67ms, then you will "drop a frame" and the UI will appear unresponsive.

Now to confuse the matter a little bit, open up the developer menu in your app and toggle Show Perf Monitor. You will notice that there are two different frame rates.

JS frame rate (JavaScript thread)

For most React Native applications, your business logic will run on the JavaScript thread. This is where your React application lives, API calls are made, touch events are processed, etc... Updates to native-backed views are batched and sent over to the native side at the end of each iteration of the event loop, before the frame deadline (if all goes well). If the JavaScript thread is unresponsive for a frame, it will be considered a dropped frame. For example, if you were to call this.setState on the root component of a complex application and it resulted in re-rendering computationally expensive component subtrees, it's conceivable that this might take 200ms and result in 12 frames being dropped. Any animations controlled by JavaScript would appear to freeze during that time. If anything takes longer than 100ms, the user will feel it.

This often happens during Navigator transitions: when you push a new route, the JavaScript thread needs to render all of the components necessary for the scene in order to send over the proper commands to the native side to create the backing views. It's common for the work being done here to take a few frames and cause jank because the transition is controlled by the JavaScript thread. Sometimes components will do additional work on componentDidMount, which might result in a second stutter in the transition.

Another example is responding to touches: if you are doing work across multiple frames on the JavaScript thread, you might notice a delay in responding to TouchableOpacity, for example. This is because the JavaScript thread is busy and cannot process the raw touch events sent over from the main thread. As a result, TouchableOpacity cannot react to the touch events and command the native view to adjust its opacity.

UI frame rate (main thread)

Many people have noticed that performance of NavigatorIOS is better out of the box than Navigator. The reason for this is that the animations for the transitions are done entirely on the main thread, and so they are not interrupted by frame drops on the JavaScript thread.

Similarly, you can happily scroll up and down through a ScrollView when the JavaScript thread is locked up because the ScrollView lives on the main thread. The scroll events are dispatched to the JS thread, but their receipt is not necessary for the scroll to occur.

Common sources of performance problems

Running in development mode (dev=true)

JavaScript thread performance suffers greatly when running in dev mode. This is unavoidable: a lot more work needs to be done at runtime to provide you with good warnings and error messages, such as validating propTypes and various other assertions. Always make sure to test performance in release builds.

Using console.log statements

When running a bundled app, these statements can cause a big bottleneck in the JavaScript thread. This includes calls from debugging libraries such as redux-logger, so make sure to remove them before bundling. You can also use this babel plugin that removes all the console.* calls. You need to install it first with npm i babel-plugin-transform-remove-console --save-dev, and then edit the .babelrc file under your project directory like this:

{
"env": {
"production": {
"plugins": ["transform-remove-console"]
}
}
}

This will automatically remove all console.* calls in the release (production) versions of your project.

ListView initial rendering is too slow or scroll performance is bad for large lists

Use the new FlatList or SectionList component instead. Besides simplifying the API, the new list components also have significant performance enhancements, the main one being nearly constant memory usage for any number of rows.

If your FlatList is rendering slow, be sure that you've implemented getItemLayout to optimize rendering speed by skipping measurement of the rendered items.

JS FPS plunges when re-rendering a view that hardly changes

If you are using a ListView, you must provide a rowHasChanged function that can reduce a lot of work by quickly determining whether or not a row needs to be re-rendered. If you are using immutable data structures, this would only need to be a reference equality check.

Similarly, you can implement shouldComponentUpdate and indicate the exact conditions under which you would like the component to re-render. If you write pure components (where the return value of the render function is entirely dependent on props and state), you can leverage PureComponent to do this for you. Once again, immutable data structures are useful to keep this fast -- if you have to do a deep comparison of a large list of objects, it may be that re-rendering your entire component would be quicker, and it would certainly require less code.

Dropping JS thread FPS because of doing a lot of work on the JavaScript thread at the same time

"Slow Navigator transitions" is the most common manifestation of this, but there are other times this can happen. Using InteractionManager can be a good approach, but if the user experience cost is too high to delay work during an animation, then you might want to consider LayoutAnimation.

The Animated API currently calculates each keyframe on-demand on the JavaScript thread unless you set useNativeDriver: true, while LayoutAnimation leverages Core Animation and is unaffected by JS thread and main thread frame drops.

One case where I have used this is for animating in a modal (sliding down from top and fading in a translucent overlay) while initializing and perhaps receiving responses for several network requests, rendering the contents of the modal, and updating the view where the modal was opened from. See the Animations guide for more information about how to use LayoutAnimation.

Caveats:

  • LayoutAnimation only works for fire-and-forget animations ("static" animations) -- if it must be interruptible, you will need to use Animated.

Moving a view on the screen (scrolling, translating, rotating) drops UI thread FPS

This is especially true when you have text with a transparent background positioned on top of an image, or any other situation where alpha compositing would be required to re-draw the view on each frame. You will find that enabling shouldRasterizeIOS or renderToHardwareTextureAndroid can help with this significantly.

Be careful not to overuse this or your memory usage could go through the roof. Profile your performance and memory usage when using these props. If you don't plan to move a view anymore, turn this property off.

Animating the size of an image drops UI thread FPS

On iOS, each time you adjust the width or height of an Image component it is re-cropped and scaled from the original image. This can be very expensive, especially for large images. Instead, use the transform: [{scale}] style property to animate the size. An example of when you might do this is when you tap an image and zoom it in to full screen.

My TouchableX view isn't very responsive

Sometimes, if we do an action in the same frame that we are adjusting the opacity or highlight of a component that is responding to a touch, we won't see that effect until after the onPress function has returned. If onPress does a setState that results in a lot of work and a few frames dropped, this may occur. A solution to this is to wrap any action inside of your onPress handler in requestAnimationFrame:

handleOnPress() {
requestAnimationFrame(() => {
this.doExpensiveAction();
});
}

Slow navigator transitions

As mentioned above, Navigator animations are controlled by the JavaScript thread. Imagine the "push from right" scene transition: each frame, the new scene is moved from the right to left, starting offscreen (let's say at an x-offset of 320) and ultimately settling when the scene sits at an x-offset of 0. Each frame during this transition, the JavaScript thread needs to send a new x-offset to the main thread. If the JavaScript thread is locked up, it cannot do this and so no update occurs on that frame and the animation stutters.

One solution to this is to allow for JavaScript-based animations to be offloaded to the main thread. If we were to do the same thing as in the above example with this approach, we might calculate a list of all x-offsets for the new scene when we are starting the transition and send them to the main thread to execute in an optimized way. Now that the JavaScript thread is freed of this responsibility, it's not a big deal if it drops a few frames while rendering the scene -- you probably won't even notice because you will be too distracted by the pretty transition.

Solving this is one of the main goals behind the new React Navigation library. The views in React Navigation use native components and the Animated library to deliver 60 FPS animations that are run on the native thread.

Edit this page
Last updated on
- + diff --git a/docs/next/performance/index.html b/docs/next/performance/index.html index 626a94d82cc..9fc2cc5f18d 100644 --- a/docs/next/performance/index.html +++ b/docs/next/performance/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Performance Overview

A compelling reason for using React Native instead of WebView-based tools is to achieve 60 frames per second and a native look and feel to your apps. Where possible, we would like for React Native to do the right thing and help you to focus on your app instead of performance optimization, but there are areas where we're not quite there yet, and others where React Native (similar to writing native code directly) cannot possibly determine the best way to optimize for you and so manual intervention will be necessary. We try our best to deliver buttery-smooth UI performance by default, but sometimes that isn't possible.

This guide is intended to teach you some basics to help you to troubleshoot performance issues, as well as discuss common sources of problems and their suggested solutions.

What you need to know about frames

Your grandparents' generation called movies "moving pictures" for a reason: realistic motion in video is an illusion created by quickly changing static images at a consistent speed. We refer to each of these images as frames. The number of frames that is displayed each second has a direct impact on how smooth and ultimately life-like a video (or user interface) seems to be. iOS devices display 60 frames per second, which gives you and the UI system about 16.67ms to do all of the work needed to generate the static image (frame) that the user will see on the screen for that interval. If you are unable to do the work necessary to generate that frame within the allotted 16.67ms, then you will "drop a frame" and the UI will appear unresponsive.

Now to confuse the matter a little bit, open up the developer menu in your app and toggle Show Perf Monitor. You will notice that there are two different frame rates.

JS frame rate (JavaScript thread)

For most React Native applications, your business logic will run on the JavaScript thread. This is where your React application lives, API calls are made, touch events are processed, etc... Updates to native-backed views are batched and sent over to the native side at the end of each iteration of the event loop, before the frame deadline (if all goes well). If the JavaScript thread is unresponsive for a frame, it will be considered a dropped frame. For example, if you were to call this.setState on the root component of a complex application and it resulted in re-rendering computationally expensive component subtrees, it's conceivable that this might take 200ms and result in 12 frames being dropped. Any animations controlled by JavaScript would appear to freeze during that time. If anything takes longer than 100ms, the user will feel it.

This often happens during Navigator transitions: when you push a new route, the JavaScript thread needs to render all of the components necessary for the scene in order to send over the proper commands to the native side to create the backing views. It's common for the work being done here to take a few frames and cause jank because the transition is controlled by the JavaScript thread. Sometimes components will do additional work on componentDidMount, which might result in a second stutter in the transition.

Another example is responding to touches: if you are doing work across multiple frames on the JavaScript thread, you might notice a delay in responding to TouchableOpacity, for example. This is because the JavaScript thread is busy and cannot process the raw touch events sent over from the main thread. As a result, TouchableOpacity cannot react to the touch events and command the native view to adjust its opacity.

UI frame rate (main thread)

Many people have noticed that performance of NavigatorIOS is better out of the box than Navigator. The reason for this is that the animations for the transitions are done entirely on the main thread, and so they are not interrupted by frame drops on the JavaScript thread.

Similarly, you can happily scroll up and down through a ScrollView when the JavaScript thread is locked up because the ScrollView lives on the main thread. The scroll events are dispatched to the JS thread, but their receipt is not necessary for the scroll to occur.

Common sources of performance problems

Running in development mode (dev=true)

JavaScript thread performance suffers greatly when running in dev mode. This is unavoidable: a lot more work needs to be done at runtime to provide you with good warnings and error messages, such as validating propTypes and various other assertions. Always make sure to test performance in release builds.

Using console.log statements

When running a bundled app, these statements can cause a big bottleneck in the JavaScript thread. This includes calls from debugging libraries such as redux-logger, so make sure to remove them before bundling. You can also use this babel plugin that removes all the console.* calls. You need to install it first with npm i babel-plugin-transform-remove-console --save-dev, and then edit the .babelrc file under your project directory like this:

{
"env": {
"production": {
"plugins": ["transform-remove-console"]
}
}
}

This will automatically remove all console.* calls in the release (production) versions of your project.

ListView initial rendering is too slow or scroll performance is bad for large lists

Use the new FlatList or SectionList component instead. Besides simplifying the API, the new list components also have significant performance enhancements, the main one being nearly constant memory usage for any number of rows.

If your FlatList is rendering slow, be sure that you've implemented getItemLayout to optimize rendering speed by skipping measurement of the rendered items.

JS FPS plunges when re-rendering a view that hardly changes

If you are using a ListView, you must provide a rowHasChanged function that can reduce a lot of work by quickly determining whether or not a row needs to be re-rendered. If you are using immutable data structures, this would only need to be a reference equality check.

Similarly, you can implement shouldComponentUpdate and indicate the exact conditions under which you would like the component to re-render. If you write pure components (where the return value of the render function is entirely dependent on props and state), you can leverage PureComponent to do this for you. Once again, immutable data structures are useful to keep this fast -- if you have to do a deep comparison of a large list of objects, it may be that re-rendering your entire component would be quicker, and it would certainly require less code.

Dropping JS thread FPS because of doing a lot of work on the JavaScript thread at the same time

"Slow Navigator transitions" is the most common manifestation of this, but there are other times this can happen. Using InteractionManager can be a good approach, but if the user experience cost is too high to delay work during an animation, then you might want to consider LayoutAnimation.

The Animated API currently calculates each keyframe on-demand on the JavaScript thread unless you set useNativeDriver: true, while LayoutAnimation leverages Core Animation and is unaffected by JS thread and main thread frame drops.

One case where I have used this is for animating in a modal (sliding down from top and fading in a translucent overlay) while initializing and perhaps receiving responses for several network requests, rendering the contents of the modal, and updating the view where the modal was opened from. See the Animations guide for more information about how to use LayoutAnimation.

Caveats:

  • LayoutAnimation only works for fire-and-forget animations ("static" animations) -- if it must be interruptible, you will need to use Animated.

Moving a view on the screen (scrolling, translating, rotating) drops UI thread FPS

This is especially true when you have text with a transparent background positioned on top of an image, or any other situation where alpha compositing would be required to re-draw the view on each frame. You will find that enabling shouldRasterizeIOS or renderToHardwareTextureAndroid can help with this significantly.

Be careful not to overuse this or your memory usage could go through the roof. Profile your performance and memory usage when using these props. If you don't plan to move a view anymore, turn this property off.

Animating the size of an image drops UI thread FPS

On iOS, each time you adjust the width or height of an Image component it is re-cropped and scaled from the original image. This can be very expensive, especially for large images. Instead, use the transform: [{scale}] style property to animate the size. An example of when you might do this is when you tap an image and zoom it in to full screen.

My TouchableX view isn't very responsive

Sometimes, if we do an action in the same frame that we are adjusting the opacity or highlight of a component that is responding to a touch, we won't see that effect until after the onPress function has returned. If onPress does a setState that results in a lot of work and a few frames dropped, this may occur. A solution to this is to wrap any action inside of your onPress handler in requestAnimationFrame:

handleOnPress() {
requestAnimationFrame(() => {
this.doExpensiveAction();
});
}

Slow navigator transitions

As mentioned above, Navigator animations are controlled by the JavaScript thread. Imagine the "push from right" scene transition: each frame, the new scene is moved from the right to left, starting offscreen (let's say at an x-offset of 320) and ultimately settling when the scene sits at an x-offset of 0. Each frame during this transition, the JavaScript thread needs to send a new x-offset to the main thread. If the JavaScript thread is locked up, it cannot do this and so no update occurs on that frame and the animation stutters.

One solution to this is to allow for JavaScript-based animations to be offloaded to the main thread. If we were to do the same thing as in the above example with this approach, we might calculate a list of all x-offsets for the new scene when we are starting the transition and send them to the main thread to execute in an optimized way. Now that the JavaScript thread is freed of this responsibility, it's not a big deal if it drops a few frames while rendering the scene -- you probably won't even notice because you will be too distracted by the pretty transition.

Solving this is one of the main goals behind the new React Navigation library. The views in React Navigation use native components and the Animated library to deliver 60 FPS animations that are run on the native thread.

Edit this page
Last updated on
- + diff --git a/docs/next/permissionsandroid.html b/docs/next/permissionsandroid.html index 756252bc6d4..e64b5f38a2a 100644 --- a/docs/next/permissionsandroid.html +++ b/docs/next/permissionsandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

PermissionsAndroid

PermissionsAndroid provides access to Android M's new permissions model. The so-called "normal" permissions are granted by default when the application is installed as long as they appear in AndroidManifest.xml. However, "dangerous" permissions require a dialog prompt. You should use this module for those permissions.

On devices before SDK version 23, the permissions are automatically granted if they appear in the manifest, so check should always result to true and request should always resolve to PermissionsAndroid.RESULTS.GRANTED.

If a user has previously turned off a permission that you prompt for, the OS will advise your app to show a rationale for needing the permission. The optional rationale argument will show a dialog prompt only if necessary - otherwise the normal permission prompt will appear.

Example

Permissions that require prompting the user

Available as constants under PermissionsAndroid.PERMISSIONS:

  • READ_CALENDAR: 'android.permission.READ_CALENDAR'
  • WRITE_CALENDAR: 'android.permission.WRITE_CALENDAR'
  • CAMERA: 'android.permission.CAMERA'
  • READ_CONTACTS: 'android.permission.READ_CONTACTS'
  • WRITE_CONTACTS: 'android.permission.WRITE_CONTACTS'
  • GET_ACCOUNTS: 'android.permission.GET_ACCOUNTS'
  • ACCESS_FINE_LOCATION: 'android.permission.ACCESS_FINE_LOCATION'
  • ACCESS_COARSE_LOCATION: 'android.permission.ACCESS_COARSE_LOCATION'
  • RECORD_AUDIO: 'android.permission.RECORD_AUDIO'
  • READ_PHONE_STATE: 'android.permission.READ_PHONE_STATE'
  • CALL_PHONE: 'android.permission.CALL_PHONE'
  • READ_CALL_LOG: 'android.permission.READ_CALL_LOG'
  • WRITE_CALL_LOG: 'android.permission.WRITE_CALL_LOG'
  • ADD_VOICEMAIL: 'com.android.voicemail.permission.ADD_VOICEMAIL'
  • USE_SIP: 'android.permission.USE_SIP'
  • PROCESS_OUTGOING_CALLS: 'android.permission.PROCESS_OUTGOING_CALLS'
  • BODY_SENSORS: 'android.permission.BODY_SENSORS'
  • SEND_SMS: 'android.permission.SEND_SMS'
  • RECEIVE_SMS: 'android.permission.RECEIVE_SMS'
  • READ_SMS: 'android.permission.READ_SMS'
  • RECEIVE_WAP_PUSH: 'android.permission.RECEIVE_WAP_PUSH'
  • RECEIVE_MMS: 'android.permission.RECEIVE_MMS'
  • READ_EXTERNAL_STORAGE: 'android.permission.READ_EXTERNAL_STORAGE'
  • WRITE_EXTERNAL_STORAGE: 'android.permission.WRITE_EXTERNAL_STORAGE'

Result strings for requesting permissions

Available as constants under PermissionsAndroid.RESULTS:

  • GRANTED: 'granted'
  • DENIED: 'denied'
  • NEVER_ASK_AGAIN: 'never_ask_again'

Reference

Methods

constructor()

constructor();

check()

check(permission);

Returns a promise resolving to a boolean value as to whether the specified permissions has been granted.

Parameters:

NameTypeRequiredDescription
permissionstringYesThe permission to check for.

request()

request(permission, [rationale]);

Prompts the user to enable a permission and returns a promise resolving to a string value (see result strings above) indicating whether the user allowed or denied the request or does not want to be asked again.

If rationale is provided, this function checks with the OS whether it is necessary to show a dialog explaining why the permission is needed (https://developer.android.com/training/permissions/requesting.html#explain) and then shows the system permission dialog.

Parameters:

NameTypeRequiredDescription
permissionstringYesThe permission to request.
rationaleobjectNoSee rationale below.

Rationale:

NameTypeRequiredDescription
titlestringYesThe title of the dialog.
messagestringYesThe message of the dialog.
buttonPositivestringYesThe text of the positive button.
buttonNegativestringNoThe text of the negative button.
buttonNeutralstringNoThe text of the neutral button.

requestMultiple()

requestMultiple(permissions);

Prompts the user to enable multiple permissions in the same dialog and returns an object with the permissions as keys and strings as values (see result strings above) indicating whether the user allowed or denied the request or does not want to be asked again.

Parameters:

NameTypeRequiredDescription
permissionsarrayYesArray of permissions to request.
Edit this page
Last updated on
- + diff --git a/docs/next/permissionsandroid/index.html b/docs/next/permissionsandroid/index.html index 756252bc6d4..e64b5f38a2a 100644 --- a/docs/next/permissionsandroid/index.html +++ b/docs/next/permissionsandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

PermissionsAndroid

PermissionsAndroid provides access to Android M's new permissions model. The so-called "normal" permissions are granted by default when the application is installed as long as they appear in AndroidManifest.xml. However, "dangerous" permissions require a dialog prompt. You should use this module for those permissions.

On devices before SDK version 23, the permissions are automatically granted if they appear in the manifest, so check should always result to true and request should always resolve to PermissionsAndroid.RESULTS.GRANTED.

If a user has previously turned off a permission that you prompt for, the OS will advise your app to show a rationale for needing the permission. The optional rationale argument will show a dialog prompt only if necessary - otherwise the normal permission prompt will appear.

Example

Permissions that require prompting the user

Available as constants under PermissionsAndroid.PERMISSIONS:

  • READ_CALENDAR: 'android.permission.READ_CALENDAR'
  • WRITE_CALENDAR: 'android.permission.WRITE_CALENDAR'
  • CAMERA: 'android.permission.CAMERA'
  • READ_CONTACTS: 'android.permission.READ_CONTACTS'
  • WRITE_CONTACTS: 'android.permission.WRITE_CONTACTS'
  • GET_ACCOUNTS: 'android.permission.GET_ACCOUNTS'
  • ACCESS_FINE_LOCATION: 'android.permission.ACCESS_FINE_LOCATION'
  • ACCESS_COARSE_LOCATION: 'android.permission.ACCESS_COARSE_LOCATION'
  • RECORD_AUDIO: 'android.permission.RECORD_AUDIO'
  • READ_PHONE_STATE: 'android.permission.READ_PHONE_STATE'
  • CALL_PHONE: 'android.permission.CALL_PHONE'
  • READ_CALL_LOG: 'android.permission.READ_CALL_LOG'
  • WRITE_CALL_LOG: 'android.permission.WRITE_CALL_LOG'
  • ADD_VOICEMAIL: 'com.android.voicemail.permission.ADD_VOICEMAIL'
  • USE_SIP: 'android.permission.USE_SIP'
  • PROCESS_OUTGOING_CALLS: 'android.permission.PROCESS_OUTGOING_CALLS'
  • BODY_SENSORS: 'android.permission.BODY_SENSORS'
  • SEND_SMS: 'android.permission.SEND_SMS'
  • RECEIVE_SMS: 'android.permission.RECEIVE_SMS'
  • READ_SMS: 'android.permission.READ_SMS'
  • RECEIVE_WAP_PUSH: 'android.permission.RECEIVE_WAP_PUSH'
  • RECEIVE_MMS: 'android.permission.RECEIVE_MMS'
  • READ_EXTERNAL_STORAGE: 'android.permission.READ_EXTERNAL_STORAGE'
  • WRITE_EXTERNAL_STORAGE: 'android.permission.WRITE_EXTERNAL_STORAGE'

Result strings for requesting permissions

Available as constants under PermissionsAndroid.RESULTS:

  • GRANTED: 'granted'
  • DENIED: 'denied'
  • NEVER_ASK_AGAIN: 'never_ask_again'

Reference

Methods

constructor()

constructor();

check()

check(permission);

Returns a promise resolving to a boolean value as to whether the specified permissions has been granted.

Parameters:

NameTypeRequiredDescription
permissionstringYesThe permission to check for.

request()

request(permission, [rationale]);

Prompts the user to enable a permission and returns a promise resolving to a string value (see result strings above) indicating whether the user allowed or denied the request or does not want to be asked again.

If rationale is provided, this function checks with the OS whether it is necessary to show a dialog explaining why the permission is needed (https://developer.android.com/training/permissions/requesting.html#explain) and then shows the system permission dialog.

Parameters:

NameTypeRequiredDescription
permissionstringYesThe permission to request.
rationaleobjectNoSee rationale below.

Rationale:

NameTypeRequiredDescription
titlestringYesThe title of the dialog.
messagestringYesThe message of the dialog.
buttonPositivestringYesThe text of the positive button.
buttonNegativestringNoThe text of the negative button.
buttonNeutralstringNoThe text of the neutral button.

requestMultiple()

requestMultiple(permissions);

Prompts the user to enable multiple permissions in the same dialog and returns an object with the permissions as keys and strings as values (see result strings above) indicating whether the user allowed or denied the request or does not want to be asked again.

Parameters:

NameTypeRequiredDescription
permissionsarrayYesArray of permissions to request.
Edit this page
Last updated on
- + diff --git a/docs/next/picker-item.html b/docs/next/picker-item.html index a58a0f2786d..91934efe6cc 100644 --- a/docs/next/picker-item.html +++ b/docs/next/picker-item.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Picker.Item

Individual selectable item in a Picker.

Props

Reference

Props

label

Text to display for this item.

TypeRequired
stringYes

color

Color of this item's text.

TypeRequired
colorNo

testID

Used to locate the item in end-to-end tests.

TypeRequired
stringNo

value

The value to be passed to picker's onValueChange callback when this item is selected. Can be a string or an integer.

TypeRequiredPlatform
anyNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/next/picker-item/index.html b/docs/next/picker-item/index.html index a58a0f2786d..91934efe6cc 100644 --- a/docs/next/picker-item/index.html +++ b/docs/next/picker-item/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Picker.Item

Individual selectable item in a Picker.

Props

Reference

Props

label

Text to display for this item.

TypeRequired
stringYes

color

Color of this item's text.

TypeRequired
colorNo

testID

Used to locate the item in end-to-end tests.

TypeRequired
stringNo

value

The value to be passed to picker's onValueChange callback when this item is selected. Can be a string or an integer.

TypeRequiredPlatform
anyNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/next/picker-style-props.html b/docs/next/picker-style-props.html index 16cb41feef2..a0baeb3827f 100644 --- a/docs/next/picker-style-props.html +++ b/docs/next/picker-style-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Edit this page
Last updated on
- + diff --git a/docs/next/picker-style-props/index.html b/docs/next/picker-style-props/index.html index 16cb41feef2..a0baeb3827f 100644 --- a/docs/next/picker-style-props/index.html +++ b/docs/next/picker-style-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Edit this page
Last updated on
- + diff --git a/docs/next/picker.html b/docs/next/picker.html index 4b1d9e773f4..1e7b6a72743 100644 --- a/docs/next/picker.html +++ b/docs/next/picker.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 Picker

Deprecated. Use one of the community packages instead.

Renders the native picker component on Android and iOS.

Example

Reference

Props

Inherits View Props.

enabled

If set to false, the picker will be disabled, i.e. the user will not be able to make a selection.

TypeRequiredPlatform
boolNoAndroid

itemStyle

Style to apply to each of the item labels.

TypeRequiredPlatform
text stylesNoiOS

mode

On Android, specifies how to display the selection items when the user taps on the picker:

  • 'dialog': Show a modal dialog. This is the default.
  • 'dropdown': Shows a dropdown anchored to the picker view
TypeRequiredPlatform
enum('dialog', 'dropdown')NoAndroid

onValueChange

Callback for when an item is selected. This is called with the following parameters:

  • itemValue: the value prop of the item that was selected
  • itemPosition: the index of the selected item in this picker
TypeRequired
functionNo

prompt

Prompt string for this picker, used on Android in dialog mode as the title of the dialog.

TypeRequiredPlatform
stringNoAndroid

selectedValue

Value matching value of one of the items. Can be a string or an integer.

TypeRequired
anyNo

style

TypeRequired
pickerStyleTypeNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/next/picker/index.html b/docs/next/picker/index.html index 4b1d9e773f4..1e7b6a72743 100644 --- a/docs/next/picker/index.html +++ b/docs/next/picker/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 Picker

Deprecated. Use one of the community packages instead.

Renders the native picker component on Android and iOS.

Example

Reference

Props

Inherits View Props.

enabled

If set to false, the picker will be disabled, i.e. the user will not be able to make a selection.

TypeRequiredPlatform
boolNoAndroid

itemStyle

Style to apply to each of the item labels.

TypeRequiredPlatform
text stylesNoiOS

mode

On Android, specifies how to display the selection items when the user taps on the picker:

  • 'dialog': Show a modal dialog. This is the default.
  • 'dropdown': Shows a dropdown anchored to the picker view
TypeRequiredPlatform
enum('dialog', 'dropdown')NoAndroid

onValueChange

Callback for when an item is selected. This is called with the following parameters:

  • itemValue: the value prop of the item that was selected
  • itemPosition: the index of the selected item in this picker
TypeRequired
functionNo

prompt

Prompt string for this picker, used on Android in dialog mode as the title of the dialog.

TypeRequiredPlatform
stringNoAndroid

selectedValue

Value matching value of one of the items. Can be a string or an integer.

TypeRequired
anyNo

style

TypeRequired
pickerStyleTypeNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/next/pickerios.html b/docs/next/pickerios.html index 03926ec2991..ebdd27e1834 100644 --- a/docs/next/pickerios.html +++ b/docs/next/pickerios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 PickerIOS

Deprecated. Use one of the community packages instead.

Reference

Props

Inherits View Props.

itemStyle

TypeRequired
text stylesNo

onValueChange

TypeRequired
functionNo

onChange

TypeRequired
functionNo

selectedValue

TypeRequired
number or stringNo
Edit this page
Last updated on
- + diff --git a/docs/next/pickerios/index.html b/docs/next/pickerios/index.html index 03926ec2991..ebdd27e1834 100644 --- a/docs/next/pickerios/index.html +++ b/docs/next/pickerios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 PickerIOS

Deprecated. Use one of the community packages instead.

Reference

Props

Inherits View Props.

itemStyle

TypeRequired
text stylesNo

onValueChange

TypeRequired
functionNo

onChange

TypeRequired
functionNo

selectedValue

TypeRequired
number or stringNo
Edit this page
Last updated on
- + diff --git a/docs/next/pixelratio.html b/docs/next/pixelratio.html index 7712e3a36fd..c06b69f3782 100644 --- a/docs/next/pixelratio.html +++ b/docs/next/pixelratio.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

PixelRatio

PixelRatio gives you access to the device's pixel density and font scale.

Fetching a correctly sized image

You should get a higher resolution image if you are on a high pixel density device. A good rule of thumb is to multiply the size of the image you display by the pixel ratio.

var image = getImage({
width: PixelRatio.getPixelSizeForLayoutSize(200),
height: PixelRatio.getPixelSizeForLayoutSize(100)
});
<Image source={image} style={{ width: 200, height: 100 }} />;

Pixel grid snapping

In iOS, you can specify positions and dimensions for elements with arbitrary precision, for example 29.674825. But, ultimately the physical display only have a fixed number of pixels, for example 640×1136 for iPhone SE (1st generation) or 828×1792 for iPhone 11. iOS tries to be as faithful as possible to the user value by spreading one original pixel into multiple ones to trick the eye. The downside of this technique is that it makes the resulting element look blurry.

In practice, we found out that developers do not want this feature and they have to work around it by doing manual rounding in order to avoid having blurry elements. In React Native, we are rounding all the pixels automatically.

We have to be careful when to do this rounding. You never want to work with rounded and unrounded values at the same time as you're going to accumulate rounding errors. Having even one rounding error is deadly because a one pixel border may vanish or be twice as big.

In React Native, everything in JavaScript and within the layout engine works with arbitrary precision numbers. It's only when we set the position and dimensions of the native element on the main thread that we round. Also, rounding is done relative to the root rather than the parent, again to avoid accumulating rounding errors.

Example

Reference

Methods

get()

static get()

Returns the device pixel density. Some examples:

getFontScale()

static getFontScale(): number

Returns the scaling factor for font sizes. This is the ratio that is used to calculate the absolute font size, so any elements that heavily depend on that should use this to do calculations.

  • on Android value reflects the user preference set in Settings > Display > Font size
  • on iOS value reflects the user preference set in Settings > Display & Brightness > Text Size, value can also be updated in Settings > Accessibility > Display & Test Size > Larger Text

If a font scale is not set, this returns the device pixel ratio.

getPixelSizeForLayoutSize()

static getPixelSizeForLayoutSize(layoutSize: number): number

Converts a layout size (dp) to pixel size (px).

Guaranteed to return an integer number.

roundToNearestPixel()

static roundToNearestPixel(layoutSize: number): number

Rounds a layout size (dp) to the nearest layout size that corresponds to an integer number of pixels. For example, on a device with a PixelRatio of 3, PixelRatio.roundToNearestPixel(8.4) = 8.33, which corresponds to exactly (8.33 * 3) = 25 pixels.

Edit this page
Last updated on
- + diff --git a/docs/next/pixelratio/index.html b/docs/next/pixelratio/index.html index 7712e3a36fd..c06b69f3782 100644 --- a/docs/next/pixelratio/index.html +++ b/docs/next/pixelratio/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

PixelRatio

PixelRatio gives you access to the device's pixel density and font scale.

Fetching a correctly sized image

You should get a higher resolution image if you are on a high pixel density device. A good rule of thumb is to multiply the size of the image you display by the pixel ratio.

var image = getImage({
width: PixelRatio.getPixelSizeForLayoutSize(200),
height: PixelRatio.getPixelSizeForLayoutSize(100)
});
<Image source={image} style={{ width: 200, height: 100 }} />;

Pixel grid snapping

In iOS, you can specify positions and dimensions for elements with arbitrary precision, for example 29.674825. But, ultimately the physical display only have a fixed number of pixels, for example 640×1136 for iPhone SE (1st generation) or 828×1792 for iPhone 11. iOS tries to be as faithful as possible to the user value by spreading one original pixel into multiple ones to trick the eye. The downside of this technique is that it makes the resulting element look blurry.

In practice, we found out that developers do not want this feature and they have to work around it by doing manual rounding in order to avoid having blurry elements. In React Native, we are rounding all the pixels automatically.

We have to be careful when to do this rounding. You never want to work with rounded and unrounded values at the same time as you're going to accumulate rounding errors. Having even one rounding error is deadly because a one pixel border may vanish or be twice as big.

In React Native, everything in JavaScript and within the layout engine works with arbitrary precision numbers. It's only when we set the position and dimensions of the native element on the main thread that we round. Also, rounding is done relative to the root rather than the parent, again to avoid accumulating rounding errors.

Example

Reference

Methods

get()

static get()

Returns the device pixel density. Some examples:

getFontScale()

static getFontScale(): number

Returns the scaling factor for font sizes. This is the ratio that is used to calculate the absolute font size, so any elements that heavily depend on that should use this to do calculations.

  • on Android value reflects the user preference set in Settings > Display > Font size
  • on iOS value reflects the user preference set in Settings > Display & Brightness > Text Size, value can also be updated in Settings > Accessibility > Display & Test Size > Larger Text

If a font scale is not set, this returns the device pixel ratio.

getPixelSizeForLayoutSize()

static getPixelSizeForLayoutSize(layoutSize: number): number

Converts a layout size (dp) to pixel size (px).

Guaranteed to return an integer number.

roundToNearestPixel()

static roundToNearestPixel(layoutSize: number): number

Rounds a layout size (dp) to the nearest layout size that corresponds to an integer number of pixels. For example, on a device with a PixelRatio of 3, PixelRatio.roundToNearestPixel(8.4) = 8.33, which corresponds to exactly (8.33 * 3) = 25 pixels.

Edit this page
Last updated on
- + diff --git a/docs/next/platform-specific-code.html b/docs/next/platform-specific-code.html index 744d8b5eae4..33bcf1afae5 100644 --- a/docs/next/platform-specific-code.html +++ b/docs/next/platform-specific-code.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
const majorVersionIOS = parseInt(Platform.Version, 10);
if (majorVersionIOS <= 9) {
console.log('Work around a change in behavior');
}

Platform-specific extensions

When your platform-specific code is more complex, you should consider splitting the code out into separate files. React Native will detect when a file has a .ios. or .android. extension and load the relevant platform file when required from other components.

For example, say you have the following files in your project:

BigButton.ios.js
BigButton.android.js

You can then require the component as follows:

import BigButton from './BigButton';

React Native will automatically pick up the right file based on the running platform.

Native-specific extensions (i.e. sharing code with NodeJS and Web)

You can also use the .native.js extension when a module needs to be shared between NodeJS/Web and React Native but it has no Android/iOS differences. This is especially useful for projects that have common code shared among React Native and ReactJS.

For example, say you have the following files in your project:

Container.js # picked up by Webpack, Rollup or any other Web bundler
Container.native.js # picked up by the React Native bundler for both Android and iOS (Metro)

You can still require it without the .native extension, as follows:

import Container from './Container';

Pro tip: Configure your Web bundler to ignore .native.js extensions in order to avoid having unused code in your production bundle, thus reducing the final bundle size.

Edit this page
Last updated on
- + diff --git a/docs/next/platform-specific-code/index.html b/docs/next/platform-specific-code/index.html index 744d8b5eae4..33bcf1afae5 100644 --- a/docs/next/platform-specific-code/index.html +++ b/docs/next/platform-specific-code/index.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
const majorVersionIOS = parseInt(Platform.Version, 10);
if (majorVersionIOS <= 9) {
console.log('Work around a change in behavior');
}

Platform-specific extensions

When your platform-specific code is more complex, you should consider splitting the code out into separate files. React Native will detect when a file has a .ios. or .android. extension and load the relevant platform file when required from other components.

For example, say you have the following files in your project:

BigButton.ios.js
BigButton.android.js

You can then require the component as follows:

import BigButton from './BigButton';

React Native will automatically pick up the right file based on the running platform.

Native-specific extensions (i.e. sharing code with NodeJS and Web)

You can also use the .native.js extension when a module needs to be shared between NodeJS/Web and React Native but it has no Android/iOS differences. This is especially useful for projects that have common code shared among React Native and ReactJS.

For example, say you have the following files in your project:

Container.js # picked up by Webpack, Rollup or any other Web bundler
Container.native.js # picked up by the React Native bundler for both Android and iOS (Metro)

You can still require it without the .native extension, as follows:

import Container from './Container';

Pro tip: Configure your Web bundler to ignore .native.js extensions in order to avoid having unused code in your production bundle, thus reducing the final bundle size.

Edit this page
Last updated on
- + diff --git a/docs/next/platform.html b/docs/next/platform.html index 166c7c8f2e0..a14b91d8f13 100644 --- a/docs/next/platform.html +++ b/docs/next/platform.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
<Component />;
Edit this page
Last updated on
- + diff --git a/docs/next/platform/index.html b/docs/next/platform/index.html index 166c7c8f2e0..a14b91d8f13 100644 --- a/docs/next/platform/index.html +++ b/docs/next/platform/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
<Component />;
Edit this page
Last updated on
- + diff --git a/docs/next/platformcolor.html b/docs/next/platformcolor.html index 9ec979847cd..ecda823ab64 100644 --- a/docs/next/platformcolor.html +++ b/docs/next/platformcolor.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

PlatformColor

PlatformColor(color1, [color2, ...colorN]);

You can use the PlatformColor function to access native colors on the target platform by supplying the native color’s corresponding string value. You pass a string to the PlatformColor function and, provided it exists on that platform, it will return the corresponding native color, which you can apply in any part of your application.

If you pass more than one string value to the PlatformColor function, it will treat the first value as the default and the rest as fallback.

PlatformColor('bogusName', 'linkColor');

Since native colors can be sensitive to themes and/or high contrast, this platform specific logic also translates inside your components.

Supported colors

For a full list of the types of system colors supported, see:

Developer notes

If you’re familiar with design systems, another way of thinking about this is that PlatformColor lets you tap into the local design system's color tokens so your app can blend right in!

Example

The string value provided to the PlatformColor function must match the string as it exists on the native platform where the app is running. In order to avoid runtime errors, the function should be wrapped in a platform check, either through a Platform.OS === 'platform' or a Platform.select(), as shown on the example above.

Note: You can find a complete example that demonstrates proper, intended use of PlatformColor in PlatformColorExample.js.

Edit this page
Last updated on
- + diff --git a/docs/next/platformcolor/index.html b/docs/next/platformcolor/index.html index 9ec979847cd..ecda823ab64 100644 --- a/docs/next/platformcolor/index.html +++ b/docs/next/platformcolor/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

PlatformColor

PlatformColor(color1, [color2, ...colorN]);

You can use the PlatformColor function to access native colors on the target platform by supplying the native color’s corresponding string value. You pass a string to the PlatformColor function and, provided it exists on that platform, it will return the corresponding native color, which you can apply in any part of your application.

If you pass more than one string value to the PlatformColor function, it will treat the first value as the default and the rest as fallback.

PlatformColor('bogusName', 'linkColor');

Since native colors can be sensitive to themes and/or high contrast, this platform specific logic also translates inside your components.

Supported colors

For a full list of the types of system colors supported, see:

Developer notes

If you’re familiar with design systems, another way of thinking about this is that PlatformColor lets you tap into the local design system's color tokens so your app can blend right in!

Example

The string value provided to the PlatformColor function must match the string as it exists on the native platform where the app is running. In order to avoid runtime errors, the function should be wrapped in a platform check, either through a Platform.OS === 'platform' or a Platform.select(), as shown on the example above.

Note: You can find a complete example that demonstrates proper, intended use of PlatformColor in PlatformColorExample.js.

Edit this page
Last updated on
- + diff --git a/docs/next/pressable.html b/docs/next/pressable.html index db6431de3c6..a96906abf79 100644 --- a/docs/next/pressable.html +++ b/docs/next/pressable.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Pressable

Pressable is a Core Component wrapper that can detect various stages of press interactions on any of its defined children.

<Pressable onPress={onPressFunction}>
<Text>I'm pressable!</Text>
</Pressable>

How it works

On an element wrapped by Pressable:

  • onPressIn is called when a press is activated.
  • onPressOut is called when the press gesture is deactivated.

After pressing onPressIn, one of two things will happen:

  1. The person will remove their finger, triggering onPressOut followed by onPress.
  2. If the person leaves their finger longer than 500 milliseconds before removing it, onLongPress is triggered. (onPressOut will still fire when they remove their finger.)
Diagram of the onPress events in sequence.

Fingers are not the most precise instruments, and it is common for users to accidentally activate the wrong element or miss the activation area. To help, Pressable has an optional HitRect you can use to define how far a touch can register away from the wrapped element. Presses can start anywhere within a HitRect.

PressRect allows presses to move beyond the element and its HitRect while maintaining activation and being eligible for a "press"—think of sliding your finger slowly away from a button you're pressing down on.

The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

Diagram of HitRect and PressRect and how they work.
You can set HitRect with hitSlop and set PressRect with pressRetentionOffset.

Pressable uses React Native's Pressability API. For more information around the state machine flow of Pressability and how it works, check out the implementation for Pressability.

Example

Props

android_disableSound
Android

If true, doesn't play Android system sound on press.

TypeRequiredDefault
booleanNofalse

android_ripple
Android

Enables the Android ripple effect and configures its properties.

TypeRequired
RippleConfigNo

children

Either children or a function that receives a boolean reflecting whether the component is currently pressed.

TypeRequired
React NodeNo

unstable_pressDelay

Duration (in milliseconds) to wait after press down before calling onPressIn.

TypeRequired
numberNo

delayLongPress

Duration (in milliseconds) from onPressIn before onLongPress is called.

TypeRequiredDefault
numberNo500

disabled

Whether the press behavior is disabled.

TypeRequiredDefault
booleanNofalse

hitSlop

Sets additional distance outside of element in which a press can be detected.

TypeRequired
Rect or numberNo

onLongPress

Called if the time after onPressIn lasts longer than 500 milliseconds. This time period can be customized with delayLongPress.

TypeRequired
PressEventNo

onPress

Called after onPressOut.

TypeRequired
PressEventNo

onPressIn

Called immediately when a touch is engaged, before onPressOut and onPress.

TypeRequired
PressEventNo

onPressOut

Called when a touch is released.

TypeRequired
PressEventNo

pressRetentionOffset

Additional distance outside of this view in which a touch is considered a press before onPressOut is triggered.

TypeRequiredDefault
Rect or numberNo{ bottom: 30, left: 20, right: 20, top: 20 }

style

Either view styles or a function that receives a boolean reflecting whether the component is currently pressed and returns view styles.

TypeRequired
View StyleNo

testOnly_pressed

Used only for documentation or testing (e.g. snapshot testing).

TypeRequiredDefault
booleanNofalse

Type Definitions

RippleConfig

Ripple effect configuration for the android_ripple property.

Type
object

Properties:

NameTypeRequiredDescription
colorcolorNoDefines the color of the ripple effect.
borderlessbooleanNoDefines if ripple effect should not include border.
radiusnumberNoDefines the radius of the ripple effect.
Edit this page
Last updated on
- + diff --git a/docs/next/pressable/index.html b/docs/next/pressable/index.html index db6431de3c6..a96906abf79 100644 --- a/docs/next/pressable/index.html +++ b/docs/next/pressable/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Pressable

Pressable is a Core Component wrapper that can detect various stages of press interactions on any of its defined children.

<Pressable onPress={onPressFunction}>
<Text>I'm pressable!</Text>
</Pressable>

How it works

On an element wrapped by Pressable:

  • onPressIn is called when a press is activated.
  • onPressOut is called when the press gesture is deactivated.

After pressing onPressIn, one of two things will happen:

  1. The person will remove their finger, triggering onPressOut followed by onPress.
  2. If the person leaves their finger longer than 500 milliseconds before removing it, onLongPress is triggered. (onPressOut will still fire when they remove their finger.)
Diagram of the onPress events in sequence.

Fingers are not the most precise instruments, and it is common for users to accidentally activate the wrong element or miss the activation area. To help, Pressable has an optional HitRect you can use to define how far a touch can register away from the wrapped element. Presses can start anywhere within a HitRect.

PressRect allows presses to move beyond the element and its HitRect while maintaining activation and being eligible for a "press"—think of sliding your finger slowly away from a button you're pressing down on.

The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

Diagram of HitRect and PressRect and how they work.
You can set HitRect with hitSlop and set PressRect with pressRetentionOffset.

Pressable uses React Native's Pressability API. For more information around the state machine flow of Pressability and how it works, check out the implementation for Pressability.

Example

Props

android_disableSound
Android

If true, doesn't play Android system sound on press.

TypeRequiredDefault
booleanNofalse

android_ripple
Android

Enables the Android ripple effect and configures its properties.

TypeRequired
RippleConfigNo

children

Either children or a function that receives a boolean reflecting whether the component is currently pressed.

TypeRequired
React NodeNo

unstable_pressDelay

Duration (in milliseconds) to wait after press down before calling onPressIn.

TypeRequired
numberNo

delayLongPress

Duration (in milliseconds) from onPressIn before onLongPress is called.

TypeRequiredDefault
numberNo500

disabled

Whether the press behavior is disabled.

TypeRequiredDefault
booleanNofalse

hitSlop

Sets additional distance outside of element in which a press can be detected.

TypeRequired
Rect or numberNo

onLongPress

Called if the time after onPressIn lasts longer than 500 milliseconds. This time period can be customized with delayLongPress.

TypeRequired
PressEventNo

onPress

Called after onPressOut.

TypeRequired
PressEventNo

onPressIn

Called immediately when a touch is engaged, before onPressOut and onPress.

TypeRequired
PressEventNo

onPressOut

Called when a touch is released.

TypeRequired
PressEventNo

pressRetentionOffset

Additional distance outside of this view in which a touch is considered a press before onPressOut is triggered.

TypeRequiredDefault
Rect or numberNo{ bottom: 30, left: 20, right: 20, top: 20 }

style

Either view styles or a function that receives a boolean reflecting whether the component is currently pressed and returns view styles.

TypeRequired
View StyleNo

testOnly_pressed

Used only for documentation or testing (e.g. snapshot testing).

TypeRequiredDefault
booleanNofalse

Type Definitions

RippleConfig

Ripple effect configuration for the android_ripple property.

Type
object

Properties:

NameTypeRequiredDescription
colorcolorNoDefines the color of the ripple effect.
borderlessbooleanNoDefines if ripple effect should not include border.
radiusnumberNoDefines the radius of the ripple effect.
Edit this page
Last updated on
- + diff --git a/docs/next/pressevent.html b/docs/next/pressevent.html index 09ce1bbee33..28e4cd7e8b1 100644 --- a/docs/next/pressevent.html +++ b/docs/next/pressevent.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

PressEvent Object Type

PressEvent object is returned in the callback as a result of user press interaction, for example onPress in Button component.

Example

{
changedTouches: [PressEvent],
identifier: 1,
locationX: 8,
locationY: 4.5,
pageX: 24,
pageY: 49.5,
target: 1127,
timestamp: 85131876.58868201,
touches: []
}

Keys and values

changedTouches

Array of all PressEvents that have changed since the last event.

TypeOptional
array of PressEventsNo

force
iOS

Amount of force used during the 3D Touch press. Returns the float value in range from 0.0 to 1.0.

TypeOptional
numberYes

identifier

Unique numeric identifier assigned to the event.

TypeOptional
numberNo

locationX

Touch origin X coordinate inside touchable area (relative to the element).

TypeOptional
numberNo

locationY

Touch origin Y coordinate inside touchable area (relative to the element).

TypeOptional
numberNo

pageX

Touch origin X coordinate on the screen (relative to the root view).

TypeOptional
numberNo

pageY

Touch origin Y coordinate on the screen (relative to the root view).

TypeOptional
numberNo

target

The node id of the element receiving the PressEvent.

TypeOptional
number, null, undefinedNo

timestamp

Timestamp value when a PressEvent occurred. Value is represented in milliseconds.

TypeOptional
numberNo

touches

Array of all current PressEvents on the screen.

TypeOptional
array of PressEventsNo

Used by

Edit this page
Last updated on
- + diff --git a/docs/next/pressevent/index.html b/docs/next/pressevent/index.html index 09ce1bbee33..28e4cd7e8b1 100644 --- a/docs/next/pressevent/index.html +++ b/docs/next/pressevent/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

PressEvent Object Type

PressEvent object is returned in the callback as a result of user press interaction, for example onPress in Button component.

Example

{
changedTouches: [PressEvent],
identifier: 1,
locationX: 8,
locationY: 4.5,
pageX: 24,
pageY: 49.5,
target: 1127,
timestamp: 85131876.58868201,
touches: []
}

Keys and values

changedTouches

Array of all PressEvents that have changed since the last event.

TypeOptional
array of PressEventsNo

force
iOS

Amount of force used during the 3D Touch press. Returns the float value in range from 0.0 to 1.0.

TypeOptional
numberYes

identifier

Unique numeric identifier assigned to the event.

TypeOptional
numberNo

locationX

Touch origin X coordinate inside touchable area (relative to the element).

TypeOptional
numberNo

locationY

Touch origin Y coordinate inside touchable area (relative to the element).

TypeOptional
numberNo

pageX

Touch origin X coordinate on the screen (relative to the root view).

TypeOptional
numberNo

pageY

Touch origin Y coordinate on the screen (relative to the root view).

TypeOptional
numberNo

target

The node id of the element receiving the PressEvent.

TypeOptional
number, null, undefinedNo

timestamp

Timestamp value when a PressEvent occurred. Value is represented in milliseconds.

TypeOptional
numberNo

touches

Array of all current PressEvents on the screen.

TypeOptional
array of PressEventsNo

Used by

Edit this page
Last updated on
- + diff --git a/docs/next/profile-hermes.html b/docs/next/profile-hermes.html index 7bec84d27a9..7b77787a83d 100644 --- a/docs/next/profile-hermes.html +++ b/docs/next/profile-hermes.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Profiling with Hermes

You can visualize JavaScript's performance in a React Native app using Hermes. Hermes is a small and lightweight JavaScript engine optimized for running React Native on Android (you can read more about using it with React Native here. Hermes helps improve app performance and also exposes ways to analyze the performance of the JavaScript that it runs.

In this section, you will learn how to profile your React Native app running on Hermes and how to visualize the profile using the Performance tab on Chrome DevTools

Be sure to enable hermes in your app before you get started!

Follow the instructions below to get started profiling:

  1. Record a Hermes sampling profile
  2. Execute command from CLI
  3. Open the downloaded profile on Chrome DevTools

Record a Hermes sampling profile

To record a sampling profiler from the Developer Menu:

  1. Navigate to your running Metro server terminal.
  2. Press d to open the Developer Menu.
  3. Select Enable Sampling Profiler.
  4. Execute your JavaScript by in your app (press buttons, etc.)
  5. Open the Developer Menu by pressing d again.
  6. Select Disable Sampling Profiler to stop recording and save the sampling profiler.

A toast will show the location where the sampling profiler has been saved, usually in /data/user/0/com.appName/cache/*.cpuprofile

Toast Notification of Profile saving

Execute command from CLI

You can use the React Native CLI to convert the Hermes tracing profile to Chrome tracing profile, and then pull it to your local machine using:

npx react-native profile-hermes [destinationDir]

Enabling source map

A source map is used to enhance the profile and associate trace events with the application code. You can automatically generate a source map when converting the Hermes tracing profile to a Chrome tracing profile by enabling bundleInDebug if the app is running in development mode. This allows React Native to build the bundle during its running process. Here's how:

  1. In your app's android/app/build.gradle file, add:
project.ext.react = [
bundleInDebug: true,
]

Be sure to clean the build whenever you make any changes to build.gradle

  1. Clean the build by running:
cd android && ./gradlew clean
  1. Run your app:
npx react-native run-android

Common errors

adb: no devices/emulators found or adb: device offline

  • Why this happens The CLI cannot access the device or emulator (through adb) you are using to run the app.
  • How to fix Make sure your Android device/emulator is connected and running. The command only works when it can access adb.

There is no file in the cache/ directory

  • Why this happens The CLI cannot find any .cpuprofile file in your app's cache/ directory. You might have forgotten to record a profile from the device.
  • How to fix Follow the instructions to enable/disable profiler from device.

Error: your_profile_name.cpuprofile is an empty file

  • Why this happens The profile is empty, it might be because Hermes is not running correctly.
  • How to fix Make sure your app is running on the latest version of Hermes.

Open the downloaded profile in Chrome DevTools

To open the profile in Chrome DevTools:

  1. Open Chrome DevTools.

  2. Select the Performance tab.

  3. Right click and choose Load profile...

    Loading a performance profile on Chrome DevTools

How does the Hermes Profile Transformer work?

The Hermes Sample Profile is of the JSON object format, while the format that Google's DevTools supports is JSON Array Format. (More information about the formats can be found on the Trace Event Format Document)

export interface HermesCPUProfile {
traceEvents: SharedEventProperties[];
samples: HermesSample[];
stackFrames: { [key in string]: HermesStackFrame };
}

The Hermes profile has most of its information encoded into the samples and stackFrames properties. Each sample is a snapshot of the function call stack at that particular timestamp as each sample has a sf property which corresponds to a function call.

export interface HermesSample {
cpu: string;
name: string;
ts: string;
pid: number;
tid: string;
weight: string;
/**
* Will refer to an element in the stackFrames object of the Hermes Profile
*/
sf: number;
stackFrameData?: HermesStackFrame;
}

The information about a function call can be found in stackFrames which contains key-object pairs, where the key is the sf number and the corresponding object gives us all the relevant information about the function including the sf number of its parent function. This parent-child relationship can be traced upwards to find the information of all the functions running at a particular timestamp.

export interface HermesStackFrame {
line: string;
column: string;
funcLine: string;
funcColumn: string;
name: string;
category: string;
/**
* A parent function may or may not exist
*/
parent?: number;
}

At this point, you should define a few more terms, namely:

  1. Nodes: The objects corresponding to sf numbers in stackFrames
  2. Active Nodes: The nodes which are currently running at a particular timestamp. A node is classified as running if its sf number is in the function call stack. This call stack can be obtained from the sf number of the sample and tracing upwards till parent sfs are available

The samples and the stackFrames in tandem can then be used to generate all the start and end events at the corresponding timestamps, wherein:

  1. Start Nodes/Events: Nodes absent in the previous sample's function call stack but present in the current sample's.
  2. End Nodes/Events: Nodes present in the previous sample's function call stack but absent in the current sample's.
CallStack Terms Explained

You can now construct a flamechart of function calls as you have all the function information including its start and end timestamps.

The hermes-profile-transformer can convert any profile generated using Hermes into a format that can be directly displayed in Chrome DevTools. More information about this can be found on @react-native-community/hermes-profile-transformer

Edit this page
Last updated on
- + diff --git a/docs/next/profile-hermes/index.html b/docs/next/profile-hermes/index.html index 7bec84d27a9..7b77787a83d 100644 --- a/docs/next/profile-hermes/index.html +++ b/docs/next/profile-hermes/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Profiling with Hermes

You can visualize JavaScript's performance in a React Native app using Hermes. Hermes is a small and lightweight JavaScript engine optimized for running React Native on Android (you can read more about using it with React Native here. Hermes helps improve app performance and also exposes ways to analyze the performance of the JavaScript that it runs.

In this section, you will learn how to profile your React Native app running on Hermes and how to visualize the profile using the Performance tab on Chrome DevTools

Be sure to enable hermes in your app before you get started!

Follow the instructions below to get started profiling:

  1. Record a Hermes sampling profile
  2. Execute command from CLI
  3. Open the downloaded profile on Chrome DevTools

Record a Hermes sampling profile

To record a sampling profiler from the Developer Menu:

  1. Navigate to your running Metro server terminal.
  2. Press d to open the Developer Menu.
  3. Select Enable Sampling Profiler.
  4. Execute your JavaScript by in your app (press buttons, etc.)
  5. Open the Developer Menu by pressing d again.
  6. Select Disable Sampling Profiler to stop recording and save the sampling profiler.

A toast will show the location where the sampling profiler has been saved, usually in /data/user/0/com.appName/cache/*.cpuprofile

Toast Notification of Profile saving

Execute command from CLI

You can use the React Native CLI to convert the Hermes tracing profile to Chrome tracing profile, and then pull it to your local machine using:

npx react-native profile-hermes [destinationDir]

Enabling source map

A source map is used to enhance the profile and associate trace events with the application code. You can automatically generate a source map when converting the Hermes tracing profile to a Chrome tracing profile by enabling bundleInDebug if the app is running in development mode. This allows React Native to build the bundle during its running process. Here's how:

  1. In your app's android/app/build.gradle file, add:
project.ext.react = [
bundleInDebug: true,
]

Be sure to clean the build whenever you make any changes to build.gradle

  1. Clean the build by running:
cd android && ./gradlew clean
  1. Run your app:
npx react-native run-android

Common errors

adb: no devices/emulators found or adb: device offline

  • Why this happens The CLI cannot access the device or emulator (through adb) you are using to run the app.
  • How to fix Make sure your Android device/emulator is connected and running. The command only works when it can access adb.

There is no file in the cache/ directory

  • Why this happens The CLI cannot find any .cpuprofile file in your app's cache/ directory. You might have forgotten to record a profile from the device.
  • How to fix Follow the instructions to enable/disable profiler from device.

Error: your_profile_name.cpuprofile is an empty file

  • Why this happens The profile is empty, it might be because Hermes is not running correctly.
  • How to fix Make sure your app is running on the latest version of Hermes.

Open the downloaded profile in Chrome DevTools

To open the profile in Chrome DevTools:

  1. Open Chrome DevTools.

  2. Select the Performance tab.

  3. Right click and choose Load profile...

    Loading a performance profile on Chrome DevTools

How does the Hermes Profile Transformer work?

The Hermes Sample Profile is of the JSON object format, while the format that Google's DevTools supports is JSON Array Format. (More information about the formats can be found on the Trace Event Format Document)

export interface HermesCPUProfile {
traceEvents: SharedEventProperties[];
samples: HermesSample[];
stackFrames: { [key in string]: HermesStackFrame };
}

The Hermes profile has most of its information encoded into the samples and stackFrames properties. Each sample is a snapshot of the function call stack at that particular timestamp as each sample has a sf property which corresponds to a function call.

export interface HermesSample {
cpu: string;
name: string;
ts: string;
pid: number;
tid: string;
weight: string;
/**
* Will refer to an element in the stackFrames object of the Hermes Profile
*/
sf: number;
stackFrameData?: HermesStackFrame;
}

The information about a function call can be found in stackFrames which contains key-object pairs, where the key is the sf number and the corresponding object gives us all the relevant information about the function including the sf number of its parent function. This parent-child relationship can be traced upwards to find the information of all the functions running at a particular timestamp.

export interface HermesStackFrame {
line: string;
column: string;
funcLine: string;
funcColumn: string;
name: string;
category: string;
/**
* A parent function may or may not exist
*/
parent?: number;
}

At this point, you should define a few more terms, namely:

  1. Nodes: The objects corresponding to sf numbers in stackFrames
  2. Active Nodes: The nodes which are currently running at a particular timestamp. A node is classified as running if its sf number is in the function call stack. This call stack can be obtained from the sf number of the sample and tracing upwards till parent sfs are available

The samples and the stackFrames in tandem can then be used to generate all the start and end events at the corresponding timestamps, wherein:

  1. Start Nodes/Events: Nodes absent in the previous sample's function call stack but present in the current sample's.
  2. End Nodes/Events: Nodes present in the previous sample's function call stack but absent in the current sample's.
CallStack Terms Explained

You can now construct a flamechart of function calls as you have all the function information including its start and end timestamps.

The hermes-profile-transformer can convert any profile generated using Hermes into a format that can be directly displayed in Chrome DevTools. More information about this can be found on @react-native-community/hermes-profile-transformer

Edit this page
Last updated on
- + diff --git a/docs/next/profiling.html b/docs/next/profiling.html index 646c5688cd6..3704f35abc2 100644 --- a/docs/next/profiling.html +++ b/docs/next/profiling.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Profiling

Use the built-in profiler to get detailed information about work done in the JavaScript thread and main thread side-by-side. Access it by selecting Perf Monitor from the Debug menu.

For iOS, Instruments is an invaluable tool, and on Android you should learn to use systrace.

But first, make sure that Development Mode is OFF! You should see __DEV__ === false, development-level warning are OFF, performance optimizations are ON in your application logs.

Another way to profile JavaScript is to use the Chrome profiler while debugging. This won't give you accurate results as the code is running in Chrome but will give you a general idea of where bottlenecks might be. Run the profiler under Chrome's Performance tab. A flame graph will appear under User Timing. To view more details in tabular format, click at the Bottom Up tab below and then select DedicatedWorker Thread at the top left menu.

Profiling Android UI Performance with systrace

Android supports 10k+ different phones and is generalized to support software rendering: the framework architecture and need to generalize across many hardware targets unfortunately means you get less for free relative to iOS. But sometimes, there are things you can improve -- and many times it's not native code's fault at all!

The first step for debugging this jank is to answer the fundamental question of where your time is being spent during each 16ms frame. For that, we'll be using a standard Android profiling tool called systrace.

systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.

1. Collecting a trace

First, connect a device that exhibits the stuttering you want to investigate to your computer via USB and get it to the point right before the navigation/animation you want to profile. Run systrace as follows:

$ <path_to_android_sdk>/platform-tools/systrace/systrace.py --time=10 -o trace.html sched gfx view -a <your_package_name>

A quick breakdown of this command:

  • time is the length of time the trace will be collected in seconds
  • sched, gfx, and view are the android SDK tags (collections of markers) we care about: sched gives you information about what's running on each core of your phone, gfx gives you graphics info such as frame boundaries, and view gives you information about measure, layout, and draw passes
  • -a <your_package_name> enables app-specific markers, specifically the ones built into the React Native framework. your_package_name can be found in the AndroidManifest.xml of your app and looks like com.example.app

Once the trace starts collecting, perform the animation or interaction you care about. At the end of the trace, systrace will give you a link to the trace which you can open in your browser.

2. Reading the trace

After opening the trace in your browser (preferably Chrome), you should see something like this:

Example

HINT: Use the WASD keys to strafe and zoom

If your trace .html file isn't opening correctly, check your browser console for the following:

ObjectObserveError

Since Object.observe was deprecated in recent browsers, you may have to open the file from the Google Chrome Tracing tool. You can do so by:

  • Opening tab in chrome chrome://tracing
  • Selecting load
  • Selecting the html file generated from the previous command.

Enable VSync highlighting

Check this checkbox at the top right of the screen to highlight the 16ms frame boundaries:

Enable VSync Highlighting

You should see zebra stripes as in the screenshot above. If you don't, try profiling on a different device: Samsung has been known to have issues displaying vsyncs while the Nexus series is generally pretty reliable.

3. Find your process

Scroll until you see (part of) the name of your package. In this case, I was profiling com.facebook.adsmanager, which shows up as book.adsmanager because of silly thread name limits in the kernel.

On the left side, you'll see a set of threads which correspond to the timeline rows on the right. There are a few threads we care about for our purposes: the UI thread (which has your package name or the name UI Thread), mqt_js, and mqt_native_modules. If you're running on Android 5+, we also care about the Render Thread.

  • UI Thread. This is where standard android measure/layout/draw happens. The thread name on the right will be your package name (in my case book.adsmanager) or UI Thread. The events that you see on this thread should look something like this and have to do with Choreographer, traversals, and DispatchUI:

    UI Thread Example

  • JS Thread. This is where JavaScript is executed. The thread name will be either mqt_js or <...> depending on how cooperative the kernel on your device is being. To identify it if it doesn't have a name, look for things like JSCall, Bridge.executeJSCall, etc:

    JS Thread Example

  • Native Modules Thread. This is where native module calls (e.g. the UIManager) are executed. The thread name will be either mqt_native_modules or <...>. To identify it in the latter case, look for things like NativeCall, callJavaModuleMethod, and onBatchComplete:

    Native Modules Thread Example

  • Bonus: Render Thread. If you're using Android L (5.0) and up, you will also have a render thread in your application. This thread generates the actual OpenGL commands used to draw your UI. The thread name will be either RenderThread or <...>. To identify it in the latter case, look for things like DrawFrame and queueBuffer:

    Render Thread Example

Identifying a culprit

A smooth animation should look something like the following:

Smooth Animation

Each change in color is a frame -- remember that in order to display a frame, all our UI work needs to be done by the end of that 16ms period. Notice that no thread is working close to the frame boundary. An application rendering like this is rendering at 60 FPS.

If you noticed chop, however, you might see something like this:

Choppy Animation from JS

Notice that the JS thread is executing almost all the time, and across frame boundaries! This app is not rendering at 60 FPS. In this case, the problem lies in JS.

You might also see something like this:

Choppy Animation from UI

In this case, the UI and render threads are the ones that have work crossing frame boundaries. The UI that we're trying to render on each frame is requiring too much work to be done. In this case, the problem lies in the native views being rendered.

At this point, you'll have some very helpful information to inform your next steps.

Resolving JavaScript issues

If you identified a JS problem, look for clues in the specific JS that you're executing. In the scenario above, we see RCTEventEmitter being called multiple times per frame. Here's a zoom-in of the JS thread from the trace above:

Too much JS

This doesn't seem right. Why is it being called so often? Are they actually different events? The answers to these questions will probably depend on your product code. And many times, you'll want to look into shouldComponentUpdate.

Resolving native UI Issues

If you identified a native UI problem, there are usually two scenarios:

  1. the UI you're trying to draw each frame involves too much work on the GPU, or
  2. You're constructing new UI during the animation/interaction (e.g. loading in new content during a scroll).

Too much GPU work

In the first scenario, you'll see a trace that has the UI thread and/or Render Thread looking like this:

Overloaded GPU

Notice the long amount of time spent in DrawFrame that crosses frame boundaries. This is time spent waiting for the GPU to drain its command buffer from the previous frame.

To mitigate this, you should:

  • investigate using renderToHardwareTextureAndroid for complex, static content that is being animated/transformed (e.g. the Navigator slide/alpha animations)
  • make sure that you are not using needsOffscreenAlphaCompositing, which is disabled by default, as it greatly increases the per-frame load on the GPU in most cases.

If these don't help and you want to dig deeper into what the GPU is actually doing, you can check out Tracer for OpenGL ES.

Creating new views on the UI thread

In the second scenario, you'll see something more like this:

Creating Views

Notice that first the JS thread thinks for a bit, then you see some work done on the native modules thread, followed by an expensive traversal on the UI thread.

There isn't a quick way to mitigate this unless you're able to postpone creating new UI until after the interaction, or you are able to simplify the UI you're creating. The react native team is working on an infrastructure level solution for this that will allow new UI to be created and configured off the main thread, allowing the interaction to continue smoothly.

Edit this page
Last updated on
- + diff --git a/docs/next/profiling/index.html b/docs/next/profiling/index.html index 646c5688cd6..3704f35abc2 100644 --- a/docs/next/profiling/index.html +++ b/docs/next/profiling/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Profiling

Use the built-in profiler to get detailed information about work done in the JavaScript thread and main thread side-by-side. Access it by selecting Perf Monitor from the Debug menu.

For iOS, Instruments is an invaluable tool, and on Android you should learn to use systrace.

But first, make sure that Development Mode is OFF! You should see __DEV__ === false, development-level warning are OFF, performance optimizations are ON in your application logs.

Another way to profile JavaScript is to use the Chrome profiler while debugging. This won't give you accurate results as the code is running in Chrome but will give you a general idea of where bottlenecks might be. Run the profiler under Chrome's Performance tab. A flame graph will appear under User Timing. To view more details in tabular format, click at the Bottom Up tab below and then select DedicatedWorker Thread at the top left menu.

Profiling Android UI Performance with systrace

Android supports 10k+ different phones and is generalized to support software rendering: the framework architecture and need to generalize across many hardware targets unfortunately means you get less for free relative to iOS. But sometimes, there are things you can improve -- and many times it's not native code's fault at all!

The first step for debugging this jank is to answer the fundamental question of where your time is being spent during each 16ms frame. For that, we'll be using a standard Android profiling tool called systrace.

systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.

1. Collecting a trace

First, connect a device that exhibits the stuttering you want to investigate to your computer via USB and get it to the point right before the navigation/animation you want to profile. Run systrace as follows:

$ <path_to_android_sdk>/platform-tools/systrace/systrace.py --time=10 -o trace.html sched gfx view -a <your_package_name>

A quick breakdown of this command:

  • time is the length of time the trace will be collected in seconds
  • sched, gfx, and view are the android SDK tags (collections of markers) we care about: sched gives you information about what's running on each core of your phone, gfx gives you graphics info such as frame boundaries, and view gives you information about measure, layout, and draw passes
  • -a <your_package_name> enables app-specific markers, specifically the ones built into the React Native framework. your_package_name can be found in the AndroidManifest.xml of your app and looks like com.example.app

Once the trace starts collecting, perform the animation or interaction you care about. At the end of the trace, systrace will give you a link to the trace which you can open in your browser.

2. Reading the trace

After opening the trace in your browser (preferably Chrome), you should see something like this:

Example

HINT: Use the WASD keys to strafe and zoom

If your trace .html file isn't opening correctly, check your browser console for the following:

ObjectObserveError

Since Object.observe was deprecated in recent browsers, you may have to open the file from the Google Chrome Tracing tool. You can do so by:

  • Opening tab in chrome chrome://tracing
  • Selecting load
  • Selecting the html file generated from the previous command.

Enable VSync highlighting

Check this checkbox at the top right of the screen to highlight the 16ms frame boundaries:

Enable VSync Highlighting

You should see zebra stripes as in the screenshot above. If you don't, try profiling on a different device: Samsung has been known to have issues displaying vsyncs while the Nexus series is generally pretty reliable.

3. Find your process

Scroll until you see (part of) the name of your package. In this case, I was profiling com.facebook.adsmanager, which shows up as book.adsmanager because of silly thread name limits in the kernel.

On the left side, you'll see a set of threads which correspond to the timeline rows on the right. There are a few threads we care about for our purposes: the UI thread (which has your package name or the name UI Thread), mqt_js, and mqt_native_modules. If you're running on Android 5+, we also care about the Render Thread.

  • UI Thread. This is where standard android measure/layout/draw happens. The thread name on the right will be your package name (in my case book.adsmanager) or UI Thread. The events that you see on this thread should look something like this and have to do with Choreographer, traversals, and DispatchUI:

    UI Thread Example

  • JS Thread. This is where JavaScript is executed. The thread name will be either mqt_js or <...> depending on how cooperative the kernel on your device is being. To identify it if it doesn't have a name, look for things like JSCall, Bridge.executeJSCall, etc:

    JS Thread Example

  • Native Modules Thread. This is where native module calls (e.g. the UIManager) are executed. The thread name will be either mqt_native_modules or <...>. To identify it in the latter case, look for things like NativeCall, callJavaModuleMethod, and onBatchComplete:

    Native Modules Thread Example

  • Bonus: Render Thread. If you're using Android L (5.0) and up, you will also have a render thread in your application. This thread generates the actual OpenGL commands used to draw your UI. The thread name will be either RenderThread or <...>. To identify it in the latter case, look for things like DrawFrame and queueBuffer:

    Render Thread Example

Identifying a culprit

A smooth animation should look something like the following:

Smooth Animation

Each change in color is a frame -- remember that in order to display a frame, all our UI work needs to be done by the end of that 16ms period. Notice that no thread is working close to the frame boundary. An application rendering like this is rendering at 60 FPS.

If you noticed chop, however, you might see something like this:

Choppy Animation from JS

Notice that the JS thread is executing almost all the time, and across frame boundaries! This app is not rendering at 60 FPS. In this case, the problem lies in JS.

You might also see something like this:

Choppy Animation from UI

In this case, the UI and render threads are the ones that have work crossing frame boundaries. The UI that we're trying to render on each frame is requiring too much work to be done. In this case, the problem lies in the native views being rendered.

At this point, you'll have some very helpful information to inform your next steps.

Resolving JavaScript issues

If you identified a JS problem, look for clues in the specific JS that you're executing. In the scenario above, we see RCTEventEmitter being called multiple times per frame. Here's a zoom-in of the JS thread from the trace above:

Too much JS

This doesn't seem right. Why is it being called so often? Are they actually different events? The answers to these questions will probably depend on your product code. And many times, you'll want to look into shouldComponentUpdate.

Resolving native UI Issues

If you identified a native UI problem, there are usually two scenarios:

  1. the UI you're trying to draw each frame involves too much work on the GPU, or
  2. You're constructing new UI during the animation/interaction (e.g. loading in new content during a scroll).

Too much GPU work

In the first scenario, you'll see a trace that has the UI thread and/or Render Thread looking like this:

Overloaded GPU

Notice the long amount of time spent in DrawFrame that crosses frame boundaries. This is time spent waiting for the GPU to drain its command buffer from the previous frame.

To mitigate this, you should:

  • investigate using renderToHardwareTextureAndroid for complex, static content that is being animated/transformed (e.g. the Navigator slide/alpha animations)
  • make sure that you are not using needsOffscreenAlphaCompositing, which is disabled by default, as it greatly increases the per-frame load on the GPU in most cases.

If these don't help and you want to dig deeper into what the GPU is actually doing, you can check out Tracer for OpenGL ES.

Creating new views on the UI thread

In the second scenario, you'll see something more like this:

Creating Views

Notice that first the JS thread thinks for a bit, then you see some work done on the native modules thread, followed by an expensive traversal on the UI thread.

There isn't a quick way to mitigate this unless you're able to postpone creating new UI until after the interaction, or you are able to simplify the UI you're creating. The react native team is working on an infrastructure level solution for this that will allow new UI to be created and configured off the main thread, allowing the interaction to continue smoothly.

Edit this page
Last updated on
- + diff --git a/docs/next/progressbarandroid.html b/docs/next/progressbarandroid.html index 4b070447396..23131efba4c 100644 --- a/docs/next/progressbarandroid.html +++ b/docs/next/progressbarandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 ProgressBarAndroid

Deprecated. Use one of the community packages instead.

Android-only React component used to indicate that the app is loading or there is some activity in the app.

Example

Reference

Props

Inherits View Props.

animating

Whether to show the ProgressBar (true, the default) or hide it (false).

TypeRequired
boolNo

color

Color of the progress bar.

TypeRequired
colorNo

indeterminate

If the progress bar will show indeterminate progress. Note that this can only be false if styleAttr is Horizontal, and requires a progress value.

TypeRequired
indeterminateTypeNo

progress

The progress value (between 0 and 1).

TypeRequired
numberNo

styleAttr

Style of the ProgressBar. One of:

  • Horizontal
  • Normal (default)
  • Small
  • Large
  • Inverse
  • SmallInverse
  • LargeInverse
TypeRequired
enum('Horizontal', 'Normal', 'Small', 'Large', 'Inverse', 'SmallInverse', 'LargeInverse')No

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/next/progressbarandroid/index.html b/docs/next/progressbarandroid/index.html index 4b070447396..23131efba4c 100644 --- a/docs/next/progressbarandroid/index.html +++ b/docs/next/progressbarandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 ProgressBarAndroid

Deprecated. Use one of the community packages instead.

Android-only React component used to indicate that the app is loading or there is some activity in the app.

Example

Reference

Props

Inherits View Props.

animating

Whether to show the ProgressBar (true, the default) or hide it (false).

TypeRequired
boolNo

color

Color of the progress bar.

TypeRequired
colorNo

indeterminate

If the progress bar will show indeterminate progress. Note that this can only be false if styleAttr is Horizontal, and requires a progress value.

TypeRequired
indeterminateTypeNo

progress

The progress value (between 0 and 1).

TypeRequired
numberNo

styleAttr

Style of the ProgressBar. One of:

  • Horizontal
  • Normal (default)
  • Small
  • Large
  • Inverse
  • SmallInverse
  • LargeInverse
TypeRequired
enum('Horizontal', 'Normal', 'Small', 'Large', 'Inverse', 'SmallInverse', 'LargeInverse')No

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/next/progressviewios.html b/docs/next/progressviewios.html index 54f72c93039..15d9109c09d 100644 --- a/docs/next/progressviewios.html +++ b/docs/next/progressviewios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 ProgressViewIOS

Deprecated. Use one of the community packages instead.

Uses ProgressViewIOS to render a UIProgressView on iOS.

Example

Reference

Props

Inherits View Props.

progress

The progress value (between 0 and 1).

TypeRequired
numberNo

progressImage

A stretchable image to display as the progress bar.

TypeRequired
Image.propTypes.sourceNo

progressTintColor

The tint color of the progress bar itself.

TypeRequired
stringNo

progressViewStyle

The progress bar style.

TypeRequired
enum('default', 'bar')No

trackImage

A stretchable image to display behind the progress bar.

TypeRequired
Image.propTypes.sourceNo

trackTintColor

The tint color of the progress bar track.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/next/progressviewios/index.html b/docs/next/progressviewios/index.html index 54f72c93039..15d9109c09d 100644 --- a/docs/next/progressviewios/index.html +++ b/docs/next/progressviewios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 ProgressViewIOS

Deprecated. Use one of the community packages instead.

Uses ProgressViewIOS to render a UIProgressView on iOS.

Example

Reference

Props

Inherits View Props.

progress

The progress value (between 0 and 1).

TypeRequired
numberNo

progressImage

A stretchable image to display as the progress bar.

TypeRequired
Image.propTypes.sourceNo

progressTintColor

The tint color of the progress bar itself.

TypeRequired
stringNo

progressViewStyle

The progress bar style.

TypeRequired
enum('default', 'bar')No

trackImage

A stretchable image to display behind the progress bar.

TypeRequired
Image.propTypes.sourceNo

trackTintColor

The tint color of the progress bar track.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/next/props.html b/docs/next/props.html index d64fec4378a..af9db7f1aa5 100644 --- a/docs/next/props.html +++ b/docs/next/props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Props

Most components can be customized when they are created, with different parameters. These created parameters are called props, short for properties.

For example, one basic React Native component is the Image. When you create an image, you can use a prop named source to control what image it shows.

Notice the braces surrounding {pic} - these embed the variable pic into JSX. You can put any JavaScript expression inside braces in JSX.

Your own components can also use props. This lets you make a single component that is used in many different places in your app, with slightly different properties in each place by referring to props in your render function. Here's an example:

Using name as a prop lets us customize the Greeting component, so we can reuse that component for each of our greetings. This example also uses the Greeting component in JSX, similar to the Core Components. The power to do this is what makes React so cool - if you find yourself wishing that you had a different set of UI primitives to work with, you can invent new ones.

The other new thing going on here is the View component. A View is useful as a container for other components, to help control style and layout.

With props and the basic Text, Image, and View components, you can build a wide variety of static screens. To learn how to make your app change over time, you need to learn about State.

Edit this page
Last updated on
- + diff --git a/docs/next/props/index.html b/docs/next/props/index.html index d64fec4378a..af9db7f1aa5 100644 --- a/docs/next/props/index.html +++ b/docs/next/props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Props

Most components can be customized when they are created, with different parameters. These created parameters are called props, short for properties.

For example, one basic React Native component is the Image. When you create an image, you can use a prop named source to control what image it shows.

Notice the braces surrounding {pic} - these embed the variable pic into JSX. You can put any JavaScript expression inside braces in JSX.

Your own components can also use props. This lets you make a single component that is used in many different places in your app, with slightly different properties in each place by referring to props in your render function. Here's an example:

Using name as a prop lets us customize the Greeting component, so we can reuse that component for each of our greetings. This example also uses the Greeting component in JSX, similar to the Core Components. The power to do this is what makes React so cool - if you find yourself wishing that you had a different set of UI primitives to work with, you can invent new ones.

The other new thing going on here is the View component. A View is useful as a container for other components, to help control style and layout.

With props and the basic Text, Image, and View components, you can build a wide variety of static screens. To learn how to make your app change over time, you need to learn about State.

Edit this page
Last updated on
- + diff --git a/docs/next/publishing-to-app-store.html b/docs/next/publishing-to-app-store.html index d67baf7403b..73104116b06 100644 --- a/docs/next/publishing-to-app-store.html +++ b/docs/next/publishing-to-app-store.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Publishing to Apple App Store

The publishing process is the same as any other native iOS app, with some additional considerations to take into account.

If you are using Expo then read the Expo Guide for Building Standalone Apps.

1. Enable App Transport Security

App Transport Security is a security feature introduced in iOS 9 that rejects all HTTP requests that are not sent over HTTPS. This can result in HTTP traffic being blocked, including the developer React Native server. ATS is disabled for localhost by default in React Native projects in order to make development easier.

You should re-enable ATS prior to building your app for production by removing the localhost entry from the NSExceptionDomains dictionary and setting NSAllowsArbitraryLoads to false in your Info.plist file in the ios/ folder. You can also re-enable ATS from within Xcode by opening your target properties under the Info pane and editing the App Transport Security Settings entry.

If your application needs to access HTTP resources on production, see this post to learn how to configure ATS on your project.

2. Configure release scheme

Building an app for distribution in the App Store requires using the Release scheme in Xcode. Apps built for Release will automatically disable the in-app Developer menu, which will prevent your users from inadvertently accessing the menu in production. It will also bundle the JavaScript locally, so you can put the app on a device and test whilst not connected to the computer.

To configure your app to be built using the Release scheme, go to Product → Scheme → Edit Scheme. Select the Run tab in the sidebar, then set the Build Configuration dropdown to Release.

Pro Tips

As your App Bundle grows in size, you may start to see a blank screen flash between your splash screen and the display of your root application view. If this is the case, you can add the following code to AppDelegate.m in order to keep your splash screen displayed during the transition.

// Place this code after "[self.window makeKeyAndVisible]" and before "return YES;"
UIStoryboard *sb = [UIStoryboard storyboardWithName:@"LaunchScreen" bundle:nil];
UIViewController *vc = [sb instantiateInitialViewController];
rootView.loadingView = vc.view;

The static bundle is built every time you target a physical device, even in Debug. If you want to save time, turn off bundle generation in Debug by adding the following to your shell script in the Xcode Build Phase Bundle React Native code and images:

if [ "${CONFIGURATION}" == "Debug" ]; then
export SKIP_BUNDLING=true
fi

3. Build app for release

You can now build your app for release by tapping ⌘B or selecting Product → Build from the menu bar. Once built for release, you'll be able to distribute the app to beta testers and submit the app to the App Store.

You can also use the React Native CLI to perform this operation using the option --configuration with the value Release (e.g. npx react-native run-ios --configuration Release).

Edit this page
Last updated on
- + diff --git a/docs/next/publishing-to-app-store/index.html b/docs/next/publishing-to-app-store/index.html index d67baf7403b..73104116b06 100644 --- a/docs/next/publishing-to-app-store/index.html +++ b/docs/next/publishing-to-app-store/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Publishing to Apple App Store

The publishing process is the same as any other native iOS app, with some additional considerations to take into account.

If you are using Expo then read the Expo Guide for Building Standalone Apps.

1. Enable App Transport Security

App Transport Security is a security feature introduced in iOS 9 that rejects all HTTP requests that are not sent over HTTPS. This can result in HTTP traffic being blocked, including the developer React Native server. ATS is disabled for localhost by default in React Native projects in order to make development easier.

You should re-enable ATS prior to building your app for production by removing the localhost entry from the NSExceptionDomains dictionary and setting NSAllowsArbitraryLoads to false in your Info.plist file in the ios/ folder. You can also re-enable ATS from within Xcode by opening your target properties under the Info pane and editing the App Transport Security Settings entry.

If your application needs to access HTTP resources on production, see this post to learn how to configure ATS on your project.

2. Configure release scheme

Building an app for distribution in the App Store requires using the Release scheme in Xcode. Apps built for Release will automatically disable the in-app Developer menu, which will prevent your users from inadvertently accessing the menu in production. It will also bundle the JavaScript locally, so you can put the app on a device and test whilst not connected to the computer.

To configure your app to be built using the Release scheme, go to Product → Scheme → Edit Scheme. Select the Run tab in the sidebar, then set the Build Configuration dropdown to Release.

Pro Tips

As your App Bundle grows in size, you may start to see a blank screen flash between your splash screen and the display of your root application view. If this is the case, you can add the following code to AppDelegate.m in order to keep your splash screen displayed during the transition.

// Place this code after "[self.window makeKeyAndVisible]" and before "return YES;"
UIStoryboard *sb = [UIStoryboard storyboardWithName:@"LaunchScreen" bundle:nil];
UIViewController *vc = [sb instantiateInitialViewController];
rootView.loadingView = vc.view;

The static bundle is built every time you target a physical device, even in Debug. If you want to save time, turn off bundle generation in Debug by adding the following to your shell script in the Xcode Build Phase Bundle React Native code and images:

if [ "${CONFIGURATION}" == "Debug" ]; then
export SKIP_BUNDLING=true
fi

3. Build app for release

You can now build your app for release by tapping ⌘B or selecting Product → Build from the menu bar. Once built for release, you'll be able to distribute the app to beta testers and submit the app to the App Store.

You can also use the React Native CLI to perform this operation using the option --configuration with the value Release (e.g. npx react-native run-ios --configuration Release).

Edit this page
Last updated on
- + diff --git a/docs/next/pushnotificationios.html b/docs/next/pushnotificationios.html index 7a2745a7ea7..4ce35f67eb2 100644 --- a/docs/next/pushnotificationios.html +++ b/docs/next/pushnotificationios.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
//Called when a notification is delivered to a foreground app.
-(void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler
{
completionHandler(UNAuthorizationOptionSound | UNAuthorizationOptionAlert | UNAuthorizationOptionBadge);
}

Then enable Background Modes/Remote notifications to be able to use remote notifications properly. The easiest way to do this is via the project settings. Navigate to Targets -> Your App -> Capabilities -> Background Modes and check Remote notifications. This will automatically enable the required settings.

Reference

Methods

presentLocalNotification()

PushNotificationIOS.presentLocalNotification(details);

Schedules the localNotification for immediate presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

scheduleLocalNotification()

PushNotificationIOS.scheduleLocalNotification(details);

Schedules the localNotification for future presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

cancelAllLocalNotifications()

PushNotificationIOS.cancelAllLocalNotifications();

Cancels all scheduled localNotifications

removeAllDeliveredNotifications()

PushNotificationIOS.removeAllDeliveredNotifications();

Remove all delivered notifications from Notification Center

getDeliveredNotifications()

PushNotificationIOS.getDeliveredNotifications(callback);

Provides you with a list of the app’s notifications that are still displayed in Notification Center

Parameters:

NameTypeRequiredDescription
callbackfunctionYesFunction which receive an array of delivered notifications.

A delivered notification is an object containing:

removeDeliveredNotifications()

PushNotificationIOS.removeDeliveredNotifications(identifiers);

Removes the specified notifications from Notification Center

Parameters:

NameTypeRequiredDescription
identifiersarrayYesArray of notification identifiers.

setApplicationIconBadgeNumber()

PushNotificationIOS.setApplicationIconBadgeNumber(number);

Sets the badge number for the app icon on the home screen

Parameters:

NameTypeRequiredDescription
numbernumberYesBadge number for the app icon.

getApplicationIconBadgeNumber()

PushNotificationIOS.getApplicationIconBadgeNumber(callback);

Gets the current badge number for the app icon on the home screen

Parameters:

NameTypeRequiredDescription
callbackfunctionYesA function that will be passed the current badge number.

cancelLocalNotifications()

PushNotificationIOS.cancelLocalNotifications(userInfo);

Cancel local notifications.

Optionally restricts the set of canceled notifications to those notifications whose userInfo fields match the corresponding fields in the userInfo argument.

Parameters:

NameTypeRequiredDescription
userInfoobjectNo

getScheduledLocalNotifications()

PushNotificationIOS.getScheduledLocalNotifications(callback);

Gets the local notifications that are currently scheduled.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesA function that will be passed an array of objects describing local notifications.

addEventListener()

PushNotificationIOS.addEventListener(type, handler);

Attaches a listener to remote or local notification events while the app is running in the foreground or the background.

Parameters:

NameTypeRequiredDescription
typestringYesEvent type.
handlerfunctionYesListener.

Valid events are:

removeEventListener()

PushNotificationIOS.removeEventListener(type, handler);

Removes the event listener. Do this in componentWillUnmount to prevent memory leaks

Parameters:

NameTypeRequiredDescription
typestringYesEvent type.
handlerfunctionYesListener.

requestPermissions()

PushNotificationIOS.requestPermissions([permissions]);

Requests notification permissions from iOS, prompting the user's dialog box. By default, it will request all notification permissions, but a subset of these can be requested by passing a map of requested permissions. The following permissions are supported:

If a map is provided to the method, only the permissions with truthy values will be requested.

This method returns a promise that will resolve when the user accepts, rejects, or if the permissions were previously rejected. The promise resolves to the current state of the permission.

Parameters:

NameTypeRequiredDescription
permissionsarrayNoalert, badge, or sound

abandonPermissions()

PushNotificationIOS.abandonPermissions();

Unregister for all remote notifications received via Apple Push Notification service.

You should call this method in rare circumstances only, such as when a new version of the app removes support for all types of remote notifications. Users can temporarily prevent apps from receiving remote notifications through the Notifications section of the Settings app. Apps unregistered through this method can always re-register.

checkPermissions()

PushNotificationIOS.checkPermissions(callback);

See what push permissions are currently enabled.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesSee below.

callback will be invoked with a permissions object:

getInitialNotification()

PushNotificationIOS.getInitialNotification();

This method returns a promise. If the app was launched by a push notification, this promise resolves to an object of type PushNotificationIOS. Otherwise, it resolves to null.

constructor()

constructor(nativeNotif);

You will never need to instantiate PushNotificationIOS yourself. Listening to the notification event and invoking getInitialNotification is sufficient.

finish()

finish(fetchResult);

This method is available for remote notifications that have been received via: application:didReceiveRemoteNotification:fetchCompletionHandler: https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623013-application?language=objc

Call this to execute when the remote notification handling is complete. When calling this block, pass in the fetch result value that best describes the results of your operation. You must call this handler and should do so as soon as possible. For a list of possible values, see PushNotificationIOS.FetchResult.

If you do not call this method your background remote notifications could be throttled, to read more about it see the above documentation link.

getMessage()

getMessage();

An alias for getAlert to get the notification's main message string

getSound()

getSound();

Gets the sound string from the aps object

getCategory()

getCategory();

Gets the category string from the aps object

getAlert()

getAlert();

Gets the notification's main message from the aps object

getContentAvailable()

getContentAvailable();

Gets the content-available number from the aps object

getBadgeCount()

getBadgeCount();

Gets the badge count number from the aps object

getData()

getData();

Gets the data object on the notification

getThreadID()

getThreadID();

Gets the thread ID on the notification

Edit this page
Last updated on
- + diff --git a/docs/next/pushnotificationios/index.html b/docs/next/pushnotificationios/index.html index 7a2745a7ea7..4ce35f67eb2 100644 --- a/docs/next/pushnotificationios/index.html +++ b/docs/next/pushnotificationios/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
//Called when a notification is delivered to a foreground app.
-(void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler
{
completionHandler(UNAuthorizationOptionSound | UNAuthorizationOptionAlert | UNAuthorizationOptionBadge);
}

Then enable Background Modes/Remote notifications to be able to use remote notifications properly. The easiest way to do this is via the project settings. Navigate to Targets -> Your App -> Capabilities -> Background Modes and check Remote notifications. This will automatically enable the required settings.

Reference

Methods

presentLocalNotification()

PushNotificationIOS.presentLocalNotification(details);

Schedules the localNotification for immediate presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

scheduleLocalNotification()

PushNotificationIOS.scheduleLocalNotification(details);

Schedules the localNotification for future presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

cancelAllLocalNotifications()

PushNotificationIOS.cancelAllLocalNotifications();

Cancels all scheduled localNotifications

removeAllDeliveredNotifications()

PushNotificationIOS.removeAllDeliveredNotifications();

Remove all delivered notifications from Notification Center

getDeliveredNotifications()

PushNotificationIOS.getDeliveredNotifications(callback);

Provides you with a list of the app’s notifications that are still displayed in Notification Center

Parameters:

NameTypeRequiredDescription
callbackfunctionYesFunction which receive an array of delivered notifications.

A delivered notification is an object containing:

removeDeliveredNotifications()

PushNotificationIOS.removeDeliveredNotifications(identifiers);

Removes the specified notifications from Notification Center

Parameters:

NameTypeRequiredDescription
identifiersarrayYesArray of notification identifiers.

setApplicationIconBadgeNumber()

PushNotificationIOS.setApplicationIconBadgeNumber(number);

Sets the badge number for the app icon on the home screen

Parameters:

NameTypeRequiredDescription
numbernumberYesBadge number for the app icon.

getApplicationIconBadgeNumber()

PushNotificationIOS.getApplicationIconBadgeNumber(callback);

Gets the current badge number for the app icon on the home screen

Parameters:

NameTypeRequiredDescription
callbackfunctionYesA function that will be passed the current badge number.

cancelLocalNotifications()

PushNotificationIOS.cancelLocalNotifications(userInfo);

Cancel local notifications.

Optionally restricts the set of canceled notifications to those notifications whose userInfo fields match the corresponding fields in the userInfo argument.

Parameters:

NameTypeRequiredDescription
userInfoobjectNo

getScheduledLocalNotifications()

PushNotificationIOS.getScheduledLocalNotifications(callback);

Gets the local notifications that are currently scheduled.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesA function that will be passed an array of objects describing local notifications.

addEventListener()

PushNotificationIOS.addEventListener(type, handler);

Attaches a listener to remote or local notification events while the app is running in the foreground or the background.

Parameters:

NameTypeRequiredDescription
typestringYesEvent type.
handlerfunctionYesListener.

Valid events are:

removeEventListener()

PushNotificationIOS.removeEventListener(type, handler);

Removes the event listener. Do this in componentWillUnmount to prevent memory leaks

Parameters:

NameTypeRequiredDescription
typestringYesEvent type.
handlerfunctionYesListener.

requestPermissions()

PushNotificationIOS.requestPermissions([permissions]);

Requests notification permissions from iOS, prompting the user's dialog box. By default, it will request all notification permissions, but a subset of these can be requested by passing a map of requested permissions. The following permissions are supported:

If a map is provided to the method, only the permissions with truthy values will be requested.

This method returns a promise that will resolve when the user accepts, rejects, or if the permissions were previously rejected. The promise resolves to the current state of the permission.

Parameters:

NameTypeRequiredDescription
permissionsarrayNoalert, badge, or sound

abandonPermissions()

PushNotificationIOS.abandonPermissions();

Unregister for all remote notifications received via Apple Push Notification service.

You should call this method in rare circumstances only, such as when a new version of the app removes support for all types of remote notifications. Users can temporarily prevent apps from receiving remote notifications through the Notifications section of the Settings app. Apps unregistered through this method can always re-register.

checkPermissions()

PushNotificationIOS.checkPermissions(callback);

See what push permissions are currently enabled.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesSee below.

callback will be invoked with a permissions object:

getInitialNotification()

PushNotificationIOS.getInitialNotification();

This method returns a promise. If the app was launched by a push notification, this promise resolves to an object of type PushNotificationIOS. Otherwise, it resolves to null.

constructor()

constructor(nativeNotif);

You will never need to instantiate PushNotificationIOS yourself. Listening to the notification event and invoking getInitialNotification is sufficient.

finish()

finish(fetchResult);

This method is available for remote notifications that have been received via: application:didReceiveRemoteNotification:fetchCompletionHandler: https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623013-application?language=objc

Call this to execute when the remote notification handling is complete. When calling this block, pass in the fetch result value that best describes the results of your operation. You must call this handler and should do so as soon as possible. For a list of possible values, see PushNotificationIOS.FetchResult.

If you do not call this method your background remote notifications could be throttled, to read more about it see the above documentation link.

getMessage()

getMessage();

An alias for getAlert to get the notification's main message string

getSound()

getSound();

Gets the sound string from the aps object

getCategory()

getCategory();

Gets the category string from the aps object

getAlert()

getAlert();

Gets the notification's main message from the aps object

getContentAvailable()

getContentAvailable();

Gets the content-available number from the aps object

getBadgeCount()

getBadgeCount();

Gets the badge count number from the aps object

getData()

getData();

Gets the data object on the notification

getThreadID()

getThreadID();

Gets the thread ID on the notification

Edit this page
Last updated on
- + diff --git a/docs/next/ram-bundles-inline-requires.html b/docs/next/ram-bundles-inline-requires.html index d7d2eb4f977..0c0ca8ff01a 100644 --- a/docs/next/ram-bundles-inline-requires.html +++ b/docs/next/ram-bundles-inline-requires.html @@ -19,7 +19,7 @@ - + @@ -45,7 +45,7 @@
module.exports = config;

The preloadedModules entry in the config indicates which modules should be marked as preloaded when building a RAM bundle. When the bundle is loaded, those modules are immediately loaded, before any requires have even executed. The blockList entry indicates that those modules should not be required inline. Because they are preloaded, there is no performance benefit from using an inline require. In fact the generated JavaScript spends extra time resolving the inline require every time the imports are referenced.

Test and Measure Improvements

You should now be ready to build your app using the RAM format and inline requires. Make sure you measure the before and after startup times.

Edit this page
Last updated on
- + diff --git a/docs/next/ram-bundles-inline-requires/index.html b/docs/next/ram-bundles-inline-requires/index.html index d7d2eb4f977..0c0ca8ff01a 100644 --- a/docs/next/ram-bundles-inline-requires/index.html +++ b/docs/next/ram-bundles-inline-requires/index.html @@ -19,7 +19,7 @@ - + @@ -45,7 +45,7 @@
module.exports = config;

The preloadedModules entry in the config indicates which modules should be marked as preloaded when building a RAM bundle. When the bundle is loaded, those modules are immediately loaded, before any requires have even executed. The blockList entry indicates that those modules should not be required inline. Because they are preloaded, there is no performance benefit from using an inline require. In fact the generated JavaScript spends extra time resolving the inline require every time the imports are referenced.

Test and Measure Improvements

You should now be ready to build your app using the RAM format and inline requires. Make sure you measure the before and after startup times.

Edit this page
Last updated on
- + diff --git a/docs/next/react-node.html b/docs/next/react-node.html index 9e956a78c86..b3916324f9d 100644 --- a/docs/next/react-node.html +++ b/docs/next/react-node.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

React Node Object Type

A React Node is one of the following types:

  • Boolean (which is ignored)
  • null or undefined (which is ignored)
  • Number
  • String
  • A React element (result of JSX)
  • An array of any of the above, possibly a nested one
Edit this page
Last updated on
- + diff --git a/docs/next/react-node/index.html b/docs/next/react-node/index.html index 9e956a78c86..b3916324f9d 100644 --- a/docs/next/react-node/index.html +++ b/docs/next/react-node/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

React Node Object Type

A React Node is one of the following types:

  • Boolean (which is ignored)
  • null or undefined (which is ignored)
  • Number
  • String
  • A React element (result of JSX)
  • An array of any of the above, possibly a nested one
Edit this page
Last updated on
- + diff --git a/docs/next/rect.html b/docs/next/rect.html index 04b6e2e1670..a237aac9630 100644 --- a/docs/next/rect.html +++ b/docs/next/rect.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Rect Object Type

Rect accepts numeric pixel values to describe how far to extend a rectangular area. These values are added to the original area's size to expand it.

Example

{
bottom: 20,
left: null,
right: undefined,
top: 50
}

Keys and values

bottom

TypeRequired
number, null, undefinedNo

left

TypeRequired
number, null, undefinedNo

right

TypeRequired
number, null, undefinedNo

top

TypeRequired
number, null, undefinedNo

Used by

Edit this page
Last updated on
- + diff --git a/docs/next/rect/index.html b/docs/next/rect/index.html index 04b6e2e1670..a237aac9630 100644 --- a/docs/next/rect/index.html +++ b/docs/next/rect/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Rect Object Type

Rect accepts numeric pixel values to describe how far to extend a rectangular area. These values are added to the original area's size to expand it.

Example

{
bottom: 20,
left: null,
right: undefined,
top: 50
}

Keys and values

bottom

TypeRequired
number, null, undefinedNo

left

TypeRequired
number, null, undefinedNo

right

TypeRequired
number, null, undefinedNo

top

TypeRequired
number, null, undefinedNo

Used by

Edit this page
Last updated on
- + diff --git a/docs/next/refreshcontrol.html b/docs/next/refreshcontrol.html index 22e59f2f00d..be8ebade8ff 100644 --- a/docs/next/refreshcontrol.html +++ b/docs/next/refreshcontrol.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

RefreshControl

This component is used inside a ScrollView or ListView to add pull to refresh functionality. When the ScrollView is at scrollY: 0, swiping down triggers an onRefresh event.

Example

Note: refreshing is a controlled prop, this is why it needs to be set to true in the onRefresh function otherwise the refresh indicator will stop immediately.

Reference

Props

View Props

Inherits View Props.

Required
refreshing

Whether the view should be indicating an active refresh.

Type
boolean

colors
Android

The colors (at least one) that will be used to draw the refresh indicator.

Type
array of colors

enabled
Android

Whether the pull to refresh functionality is enabled.

TypeDefault
booleantrue

onRefresh

Called when the view starts refreshing.

Type
function

progressBackgroundColor
Android

The background color of the refresh indicator.

Type
color

progressViewOffset
Android

Progress view top offset.

TypeDefault
number0

size
Android

Size of the refresh indicator.

TypeDefault
RefreshControl.SIZERefreshLayoutConsts.SIZE.DEFAULT

tintColor
iOS

The color of the refresh indicator.

Type
color

title
iOS

The title displayed under the refresh indicator.

Type
string

titleColor
iOS

The color of the refresh indicator title.

Type
color

Type Definitions

RefreshLayoutConsts.SIZE

The SwipeRefreshLayout Android component constants. The actual component size may vary between devices. You can read more about the native component in the Android documentation.

Type
enum

Constants:

NameTypeValueDescription
DEFAULTint1Default RefreshControl size
LARGEint0Large RefreshControl size
Edit this page
Last updated on
- + diff --git a/docs/next/refreshcontrol/index.html b/docs/next/refreshcontrol/index.html index 22e59f2f00d..be8ebade8ff 100644 --- a/docs/next/refreshcontrol/index.html +++ b/docs/next/refreshcontrol/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

RefreshControl

This component is used inside a ScrollView or ListView to add pull to refresh functionality. When the ScrollView is at scrollY: 0, swiping down triggers an onRefresh event.

Example

Note: refreshing is a controlled prop, this is why it needs to be set to true in the onRefresh function otherwise the refresh indicator will stop immediately.

Reference

Props

View Props

Inherits View Props.

Required
refreshing

Whether the view should be indicating an active refresh.

Type
boolean

colors
Android

The colors (at least one) that will be used to draw the refresh indicator.

Type
array of colors

enabled
Android

Whether the pull to refresh functionality is enabled.

TypeDefault
booleantrue

onRefresh

Called when the view starts refreshing.

Type
function

progressBackgroundColor
Android

The background color of the refresh indicator.

Type
color

progressViewOffset
Android

Progress view top offset.

TypeDefault
number0

size
Android

Size of the refresh indicator.

TypeDefault
RefreshControl.SIZERefreshLayoutConsts.SIZE.DEFAULT

tintColor
iOS

The color of the refresh indicator.

Type
color

title
iOS

The title displayed under the refresh indicator.

Type
string

titleColor
iOS

The color of the refresh indicator title.

Type
color

Type Definitions

RefreshLayoutConsts.SIZE

The SwipeRefreshLayout Android component constants. The actual component size may vary between devices. You can read more about the native component in the Android documentation.

Type
enum

Constants:

NameTypeValueDescription
DEFAULTint1Default RefreshControl size
LARGEint0Large RefreshControl size
Edit this page
Last updated on
- + diff --git a/docs/next/running-on-device.html b/docs/next/running-on-device.html index ac7c4101b67..a8a87736f0a 100644 --- a/docs/next/running-on-device.html +++ b/docs/next/running-on-device.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Running On Device

It's always a good idea to test your app on an actual device before releasing it to your users. This document will guide you through the necessary steps to run your React Native app on a device and to get it ready for production.

If you used Expo CLI or Create React Native App to set up your project, you can preview your app on a device by scanning the QR code with the Expo app—but in order to build and run your app on a device, you will need to eject and install the native code dependencies from the environment setup guide.

Running your app on Android devices

Development OS

1. Enable Debugging over USB

Most Android devices can only install and run apps downloaded from Google Play, by default. You will need to enable USB Debugging on your device in order to install your app during development.

To enable USB debugging on your device, you will first need to enable the "Developer options" menu by going to Settings → About phone → Software information and then tapping the Build number row at the bottom seven times. You can then go back to Settings → Developer options to enable "USB debugging".

2. Plug in your device via USB

Let's now set up an Android device to run our React Native projects. Go ahead and plug in your device via USB to your development machine.

Next, check the manufacturer code by using lsusb (on mac, you must first install lsusb). lsusb should output something like this:

$ lsusb
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 003: ID 22b8:2e76 Motorola PCS
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

These lines represent the USB devices currently connected to your machine.

You want the line that represents your phone. If you're in doubt, try unplugging your phone and running the command again:

$ lsusb
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

You'll see that after removing the phone, the line which has the phone model ("Motorola PCS" in this case) disappeared from the list. This is the line that we care about.

Bus 001 Device 003: ID 22b8:2e76 Motorola PCS

From the above line, you want to grab the first four digits from the device ID:

22b8:2e76

In this case, it's 22b8. That's the identifier for Motorola.

You'll need to input this into your udev rules in order to get up and running:

echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="22b8", MODE="0666", GROUP="plugdev"' | sudo tee /etc/udev/rules.d/51-android-usb.rules

Make sure that you replace 22b8 with the identifier you get in the above command.

Now check that your device is properly connecting to ADB, the Android Debug Bridge, by running adb devices.

$ adb devices
List of devices attached
emulator-5554 offline # Google emulator
14ed2fcc device # Physical device

Seeing device in the right column means the device is connected. You must have only one device connected at a time.

3. Run your app

Type the following in your command prompt to install and launch your app on the device:

$ npx react-native run-android

If you get a "bridge configuration isn't available" error, see Using adb reverse.

Hint: You can also use the React Native CLI to generate and run a Release build (e.g. npx react-native run-android --variant=release).

Connecting to the development server

You can also iterate quickly on a device by connecting to the development server running on your development machine. There are several ways of accomplishing this, depending on whether you have access to a USB cable or a Wi-Fi network.

Method 1: Using adb reverse (recommended)

You can use this method if your device is running Android 5.0 (Lollipop) or newer, it has USB debugging enabled, and it is connected via USB to your development machine.

Run the following in a command prompt:

$ adb -s <device name> reverse tcp:8081 tcp:8081

To find the device name, run the following adb command:

$ adb devices

You can now enable Live reloading from the Developer menu. Your app will reload whenever your JavaScript code has changed.

Method 2: Connect via Wi-Fi

You can also connect to the development server over Wi-Fi. You'll first need to install the app on your device using a USB cable, but once that has been done you can debug wirelessly by following these instructions. You'll need your development machine's current IP address before proceeding.

Open a terminal and type /sbin/ifconfig to find your machine's IP address.

  1. Make sure your laptop and your phone are on the same Wi-Fi network.
  2. Open your React Native app on your device.
  3. You'll see a red screen with an error. This is OK. The following steps will fix that.
  4. Open the in-app Developer menu.
  5. Go to Dev Settings → Debug server host & port for device.
  6. Type in your machine's IP address and the port of the local dev server (e.g. 10.0.1.1:8081).
  7. Go back to the Developer menu and select Reload JS.

You can now enable Live reloading from the Developer menu. Your app will reload whenever your JavaScript code has changed.

Building your app for production

You have built a great app using React Native, and you are now itching to release it in the Play Store. The process is the same as any other native Android app, with some additional considerations to take into account. Follow the guide for generating a signed APK to learn more.

Edit this page
Last updated on
- + diff --git a/docs/next/running-on-device/index.html b/docs/next/running-on-device/index.html index ac7c4101b67..a8a87736f0a 100644 --- a/docs/next/running-on-device/index.html +++ b/docs/next/running-on-device/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Running On Device

It's always a good idea to test your app on an actual device before releasing it to your users. This document will guide you through the necessary steps to run your React Native app on a device and to get it ready for production.

If you used Expo CLI or Create React Native App to set up your project, you can preview your app on a device by scanning the QR code with the Expo app—but in order to build and run your app on a device, you will need to eject and install the native code dependencies from the environment setup guide.

Running your app on Android devices

Development OS

1. Enable Debugging over USB

Most Android devices can only install and run apps downloaded from Google Play, by default. You will need to enable USB Debugging on your device in order to install your app during development.

To enable USB debugging on your device, you will first need to enable the "Developer options" menu by going to Settings → About phone → Software information and then tapping the Build number row at the bottom seven times. You can then go back to Settings → Developer options to enable "USB debugging".

2. Plug in your device via USB

Let's now set up an Android device to run our React Native projects. Go ahead and plug in your device via USB to your development machine.

Next, check the manufacturer code by using lsusb (on mac, you must first install lsusb). lsusb should output something like this:

$ lsusb
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 003: ID 22b8:2e76 Motorola PCS
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

These lines represent the USB devices currently connected to your machine.

You want the line that represents your phone. If you're in doubt, try unplugging your phone and running the command again:

$ lsusb
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

You'll see that after removing the phone, the line which has the phone model ("Motorola PCS" in this case) disappeared from the list. This is the line that we care about.

Bus 001 Device 003: ID 22b8:2e76 Motorola PCS

From the above line, you want to grab the first four digits from the device ID:

22b8:2e76

In this case, it's 22b8. That's the identifier for Motorola.

You'll need to input this into your udev rules in order to get up and running:

echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="22b8", MODE="0666", GROUP="plugdev"' | sudo tee /etc/udev/rules.d/51-android-usb.rules

Make sure that you replace 22b8 with the identifier you get in the above command.

Now check that your device is properly connecting to ADB, the Android Debug Bridge, by running adb devices.

$ adb devices
List of devices attached
emulator-5554 offline # Google emulator
14ed2fcc device # Physical device

Seeing device in the right column means the device is connected. You must have only one device connected at a time.

3. Run your app

Type the following in your command prompt to install and launch your app on the device:

$ npx react-native run-android

If you get a "bridge configuration isn't available" error, see Using adb reverse.

Hint: You can also use the React Native CLI to generate and run a Release build (e.g. npx react-native run-android --variant=release).

Connecting to the development server

You can also iterate quickly on a device by connecting to the development server running on your development machine. There are several ways of accomplishing this, depending on whether you have access to a USB cable or a Wi-Fi network.

Method 1: Using adb reverse (recommended)

You can use this method if your device is running Android 5.0 (Lollipop) or newer, it has USB debugging enabled, and it is connected via USB to your development machine.

Run the following in a command prompt:

$ adb -s <device name> reverse tcp:8081 tcp:8081

To find the device name, run the following adb command:

$ adb devices

You can now enable Live reloading from the Developer menu. Your app will reload whenever your JavaScript code has changed.

Method 2: Connect via Wi-Fi

You can also connect to the development server over Wi-Fi. You'll first need to install the app on your device using a USB cable, but once that has been done you can debug wirelessly by following these instructions. You'll need your development machine's current IP address before proceeding.

Open a terminal and type /sbin/ifconfig to find your machine's IP address.

  1. Make sure your laptop and your phone are on the same Wi-Fi network.
  2. Open your React Native app on your device.
  3. You'll see a red screen with an error. This is OK. The following steps will fix that.
  4. Open the in-app Developer menu.
  5. Go to Dev Settings → Debug server host & port for device.
  6. Type in your machine's IP address and the port of the local dev server (e.g. 10.0.1.1:8081).
  7. Go back to the Developer menu and select Reload JS.

You can now enable Live reloading from the Developer menu. Your app will reload whenever your JavaScript code has changed.

Building your app for production

You have built a great app using React Native, and you are now itching to release it in the Play Store. The process is the same as any other native Android app, with some additional considerations to take into account. Follow the guide for generating a signed APK to learn more.

Edit this page
Last updated on
- + diff --git a/docs/next/running-on-simulator-ios.html b/docs/next/running-on-simulator-ios.html index da0c7ae6c88..8c4da51edd0 100644 --- a/docs/next/running-on-simulator-ios.html +++ b/docs/next/running-on-simulator-ios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Running On Simulator

Starting the simulator

Once you have your React Native project initialized, you can run npx react-native run-ios inside the newly created project directory. If everything is set up correctly, you should see your new app running in the iOS Simulator shortly.

Specifying a device

You can specify the device the simulator should run with the --simulator flag, followed by the device name as a string. The default is "iPhone 11". If you wish to run your app on an iPhone SE (1st generation), run npx react-native run-ios --simulator="iPhone SE (1st generation)".

The device names correspond to the list of devices available in Xcode. You can check your available devices by running xcrun simctl list devices from the console.

Edit this page
Last updated on
- + diff --git a/docs/next/running-on-simulator-ios/index.html b/docs/next/running-on-simulator-ios/index.html index da0c7ae6c88..8c4da51edd0 100644 --- a/docs/next/running-on-simulator-ios/index.html +++ b/docs/next/running-on-simulator-ios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Running On Simulator

Starting the simulator

Once you have your React Native project initialized, you can run npx react-native run-ios inside the newly created project directory. If everything is set up correctly, you should see your new app running in the iOS Simulator shortly.

Specifying a device

You can specify the device the simulator should run with the --simulator flag, followed by the device name as a string. The default is "iPhone 11". If you wish to run your app on an iPhone SE (1st generation), run npx react-native run-ios --simulator="iPhone SE (1st generation)".

The device names correspond to the list of devices available in Xcode. You can check your available devices by running xcrun simctl list devices from the console.

Edit this page
Last updated on
- + diff --git a/docs/next/safeareaview.html b/docs/next/safeareaview.html index 980f4c75a4a..6a849e560f6 100644 --- a/docs/next/safeareaview.html +++ b/docs/next/safeareaview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

SafeAreaView

The purpose of SafeAreaView is to render content within the safe area boundaries of a device. It is currently only applicable to iOS devices with iOS version 11 or later.

SafeAreaView renders nested content and automatically applies padding to reflect the portion of the view that is not covered by navigation bars, tab bars, toolbars, and other ancestor views. Moreover, and most importantly, Safe Area's paddings reflect the physical limitation of the screen, such as rounded corners or camera notches (i.e. the sensor housing area on iPhone X).

Example

To use, wrap your top level view with a SafeAreaView with a flex: 1 style applied to it. You may also want to use a background color that matches your application's design.

Reference

Props

View Props

Inherits View Props.

As padding is used to implement the behavior of the component, padding rules in styles applied to a SafeAreaView will be ignored and can cause different results depending on the platform. See #22211 for details.

emulateUnlessSupported

TypeRequiredDefault
boolNotrue
Edit this page
Last updated on
- + diff --git a/docs/next/safeareaview/index.html b/docs/next/safeareaview/index.html index 980f4c75a4a..6a849e560f6 100644 --- a/docs/next/safeareaview/index.html +++ b/docs/next/safeareaview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

SafeAreaView

The purpose of SafeAreaView is to render content within the safe area boundaries of a device. It is currently only applicable to iOS devices with iOS version 11 or later.

SafeAreaView renders nested content and automatically applies padding to reflect the portion of the view that is not covered by navigation bars, tab bars, toolbars, and other ancestor views. Moreover, and most importantly, Safe Area's paddings reflect the physical limitation of the screen, such as rounded corners or camera notches (i.e. the sensor housing area on iPhone X).

Example

To use, wrap your top level view with a SafeAreaView with a flex: 1 style applied to it. You may also want to use a background color that matches your application's design.

Reference

Props

View Props

Inherits View Props.

As padding is used to implement the behavior of the component, padding rules in styles applied to a SafeAreaView will be ignored and can cause different results depending on the platform. See #22211 for details.

emulateUnlessSupported

TypeRequiredDefault
boolNotrue
Edit this page
Last updated on
- + diff --git a/docs/next/scrollview.html b/docs/next/scrollview.html index e316a059cc4..e4abfb56255 100644 --- a/docs/next/scrollview.html +++ b/docs/next/scrollview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

ScrollView

Component that wraps platform ScrollView while providing integration with touch locking "responder" system.

Keep in mind that ScrollViews must have a bounded height in order to work, since they contain unbounded-height children into a bounded container (via a scroll interaction). In order to bound the height of a ScrollView, either set the height of the view directly (discouraged) or make sure all parent views have bounded height. Forgetting to transfer {flex: 1} down the view stack can lead to errors here, which the element inspector makes quick to debug.

Doesn't yet support other contained responders from blocking this scroll view from becoming the responder.

<ScrollView> vs <FlatList> - which one to use?

ScrollView renders all its react child components at once, but this has a performance downside.

Imagine you have a very long list of items you want to display, maybe several screens worth of content. Creating JS components and native views for everything all at once, much of which may not even be shown, will contribute to slow rendering and increased memory usage.

This is where FlatList comes into play. FlatList renders items lazily, when they are about to appear, and removes items that scroll way off screen to save memory and processing time.

FlatList is also handy if you want to render separators between your items, multiple columns, infinite scroll loading, or any number of other features it supports out of the box.

Example

Reference

Props

View Props

Inherits View Props.

StickyHeaderComponent

A React Component that will be used to render sticky headers, should be used together with stickyHeaderIndices. You may need to set this component if your sticky header uses custom transforms, for example, when you want your list to have an animated and hidable header. If component have not been provided, the default ScrollViewStickyHeader component will be used.

Type
component, element

alwaysBounceHorizontal
iOS

When true, the scroll view bounces horizontally when it reaches the end even if the content is smaller than the scroll view itself.

TypeDefault
booltrue when horizontal={true}
false otherwise

alwaysBounceVertical
iOS

When true, the scroll view bounces vertically when it reaches the end even if the content is smaller than the scroll view itself.

TypeDefault
boolfalse when vertical={true}
true otherwise

automaticallyAdjustContentInsets
iOS

Controls whether iOS should automatically adjust the content inset for scroll views that are placed behind a navigation bar or tab bar/toolbar.

TypeDefault
booltrue

bounces
iOS

When true, the scroll view bounces when it reaches the end of the content if the content is larger than the scroll view along the axis of the scroll direction. When false, it disables all bouncing even if the alwaysBounce* props are true.

TypeDefault
booltrue

bouncesZoom
iOS

When true, gestures can drive zoom past min/max and the zoom will animate to the min/max value at gesture end, otherwise the zoom will not exceed the limits.

TypeDefault
booltrue

canCancelContentTouches
iOS

When false, once tracking starts, won't try to drag if the touch moves.

TypeDefault
booltrue

centerContent
iOS

When true, the scroll view automatically centers the content when the content is smaller than the scroll view bounds; when the content is larger than the scroll view, this property has no effect.

TypeDefault
boolfalse

contentContainerStyle

These styles will be applied to the scroll view content container which wraps all of the child views. Example:

return (
<ScrollView contentContainerStyle={styles.contentContainer}>
</ScrollView>
);
...
const styles = StyleSheet.create({
contentContainer: {
paddingVertical: 20
}
});
Type
View Style

contentInset
iOS

The amount by which the scroll view content is inset from the edges of the scroll view.

TypeDefault
object: {top: number, left: number, bottom: number, right: number}{top: 0, left: 0, bottom: 0, right: 0}

contentInsetAdjustmentBehavior
iOS

This property specifies how the safe area insets are used to modify the content area of the scroll view. Available on iOS 11 and later.

TypeDefault
enum('automatic', 'scrollableAxes', 'never', 'always')'never'

contentOffset

Used to manually set the starting scroll offset.

TypeDefault
Point{x: 0, y: 0}

decelerationRate

A floating-point number that determines how quickly the scroll view decelerates after the user lifts their finger. You may also use string shortcuts "normal" and "fast" which match the underlying iOS settings for UIScrollViewDecelerationRateNormal and UIScrollViewDecelerationRateFast respectively.

  • 'normal' 0.998 on iOS, 0.985 on Android.
  • 'fast', 0.99 on iOS, 0.9 on Android.
TypeDefault
enum('fast', 'normal'), number'normal'

directionalLockEnabled
iOS

When true, the ScrollView will try to lock to only vertical or horizontal scrolling while dragging.

TypeDefault
boolfalse

disableIntervalMomentum

When true, the scroll view stops on the next index (in relation to scroll position at release) regardless of how fast the gesture is. This can be used for pagination when the page is less than the width of the horizontal ScrollView or the height of the vertical ScrollView.

TypeDefault
boolfalse

disableScrollViewPanResponder

When true, the default JS pan responder on the ScrollView is disabled, and full control over touches inside the ScrollView is left to its child components. This is particularly useful if snapToInterval is enabled, since it does not follow typical touch patterns. Do not use this on regular ScrollView use cases without snapToInterval as it may cause unexpected touches to occur while scrolling.

TypeDefault
boolfalse

endFillColor
Android

Sometimes a scrollview takes up more space than its content fills. When this is the case, this prop will fill the rest of the scrollview with a color to avoid setting a background and creating unnecessary overdraw. This is an advanced optimization that is not needed in the general case.

Type
color

fadingEdgeLength
Android

Fades out the edges of the the scroll content.

If the value is greater than 0, the fading edges will be set accordingly to the current scroll direction and position, indicating if there is more content to show.

TypeDefault
number0

horizontal

When true, the scroll view's children are arranged horizontally in a row instead of vertically in a column.

TypeDefault
boolfalse

indicatorStyle
iOS

The style of the scroll indicators.

  • 'default' same as black.
  • 'black', scroll indicator is black. This style is good against a light background.
  • 'white', scroll indicator is white. This style is good against a dark background.
TypeDefault
enum('default', 'black', 'white')'default'

invertStickyHeaders

If sticky headers should stick at the bottom instead of the top of the ScrollView. This is usually used with inverted ScrollViews.

TypeDefault
boolfalse

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

  • 'none', drags do not dismiss the keyboard.
  • 'on-drag', the keyboard is dismissed when a drag begins.

iOS Only

  • 'interactive', the keyboard is dismissed interactively with the drag and moves in synchrony with the touch, dragging upwards cancels the dismissal. On Android this is not supported and it will have the same behavior as 'none'.
TypeDefault
enum('none', 'on-drag')
Android
enum('none', 'on-drag', 'interactive')
iOS
'none'

keyboardShouldPersistTaps

Determines when the keyboard should stay visible after a tap.

  • 'never' tapping outside of the focused text input when the keyboard is up dismisses the keyboard. When this happens, children won't receive the tap.
  • 'always', the keyboard will not dismiss automatically, and the scroll view will not catch taps, but children of the scroll view can catch taps.
  • 'handled', the keyboard will not dismiss automatically when the tap was handled by children of the scroll view (or captured by an ancestor).
  • false, deprecated, use 'never' instead
  • true, deprecated, use 'always' instead
TypeDefault
enum('always', 'never', 'handled', false, true)'never'

maintainVisibleContentPosition
iOS

When set, the scroll view will adjust the scroll position so that the first child that is currently visible and at or beyond minIndexForVisible will not change position. This is useful for lists that are loading content in both directions, e.g. a chat thread, where new messages coming in might otherwise cause the scroll position to jump. A value of 0 is common, but other values such as 1 can be used to skip loading spinners or other content that should not maintain position.

The optional autoscrollToTopThreshold can be used to make the content automatically scroll to the top after making the adjustment if the user was within the threshold of the top before the adjustment was made. This is also useful for chat-like applications where you want to see new messages scroll into place, but not if the user has scrolled up a ways and it would be disruptive to scroll a bunch.

Caveat 1: Reordering elements in the scrollview with this enabled will probably cause jumpiness and jank. It can be fixed, but there are currently no plans to do so. For now, don't re-order the content of any ScrollViews or Lists that use this feature.

Caveat 2: This uses contentOffset and frame.origin in native code to compute visibility. Occlusion, transforms, and other complexity won't be taken into account as to whether content is "visible" or not.

Type
object: { minIndexForVisible: number, autoscrollToTopThreshold: number }

maximumZoomScale
iOS

The maximum allowed zoom scale.

TypeDefault
number1.0

minimumZoomScale
iOS

The minimum allowed zoom scale.

TypeDefault
number1.0

nestedScrollEnabled
Android

Enables nested scrolling for Android API level 21+.

TypeDefault
booltrue

onContentSizeChange

Called when scrollable content view of the ScrollView changes.

Handler function is passed the content width and content height as parameters: (contentWidth, contentHeight)

It's implemented using onLayout handler attached to the content container which this ScrollView renders.

Type
function

onMomentumScrollBegin

Called when the momentum scroll starts (scroll which occurs as the ScrollView starts gliding).

Type
function

onMomentumScrollEnd

Called when the momentum scroll ends (scroll which occurs as the ScrollView glides to a stop).

Type
function

onScroll

Fires at most once per frame during scrolling. The frequency of the events can be controlled using the scrollEventThrottle prop. The event has the following shape (all values are numbers):

{
nativeEvent: {
contentInset: {bottom, left, right, top},
contentOffset: {x, y},
contentSize: {height, width},
layoutMeasurement: {height, width},
zoomScale
}
}
Type
function

onScrollBeginDrag

Called when the user begins to drag the scroll view.

Type
function

onScrollEndDrag

Called when the user stops dragging the scroll view and it either stops or begins to glide.

Type
function

onScrollToTop
iOS

Fires when the scroll view scrolls to top after the status bar has been tapped.

Type
function

overScrollMode
Android

Used to override default value of overScroll mode.

Possible values:

  • 'auto' - Allow a user to over-scroll this view only if the content is large enough to meaningfully scroll.
  • 'always' - Always allow a user to over-scroll this view.
  • 'never' - Never allow a user to over-scroll this view.
TypeDefault
enum('auto', 'always', 'never')'auto'

pagingEnabled

When true, the scroll view stops on multiples of the scroll view's size when scrolling. This can be used for horizontal pagination.

Note: Vertical pagination is not supported on Android.

TypeDefault
boolfalse

persistentScrollbar
Android

Causes the scrollbars not to turn transparent when they are not in use.

TypeDefault
boolfalse

pinchGestureEnabled
iOS

When true, ScrollView allows use of pinch gestures to zoom in and out.

TypeDefault
booltrue

refreshControl

A RefreshControl component, used to provide pull-to-refresh functionality for the ScrollView. Only works for vertical ScrollViews (horizontal prop must be false).

See RefreshControl.

Type
element

removeClippedSubviews

Experimental: When true, offscreen child views (whose overflow value is hidden) are removed from their native backing superview when offscreen. This can improve scrolling performance on long lists.

TypeDefault
boolfalse

scrollBarThumbImage
VR

Optionally an image can be used for the scroll bar thumb. This will override the color. While the image is loading or the image fails to load the color will be used instead. Use an alpha of 0 in the color to avoid seeing it while the image is loading.

  • uri, a string representing the resource identifier for the image, which should be either a local file path or the name of a static image resource.
  • number, opaque type returned by something like import IMAGE from './image.jpg'.
Type
string, number

scrollEnabled

When false, the view cannot be scrolled via touch interaction.

Note that the view can always be scrolled by calling scrollTo.

TypeDefault
booltrue

scrollEventThrottle
iOS

This controls how often the scroll event will be fired while scrolling (as a time interval in ms). A lower number yields better accuracy for code that is tracking the scroll position, but can lead to scroll performance problems due to the volume of information being sent over the bridge. You will not notice a difference between values set between 1-16 as the JS run loop is synced to the screen refresh rate. If you do not need precise scroll position tracking, set this value higher to limit the information being sent across the bridge. The default value is 0, which results in the scroll event being sent only once each time the view is scrolled.

TypeDefault
number0

scrollIndicatorInsets
iOS

The amount by which the scroll view indicators are inset from the edges of the scroll view. This should normally be set to the same value as the contentInset.

TypeDefault
object: {top: number, left: number, bottom: number, right: number}{top: 0, left: 0, bottom: 0, right: 0}

scrollPerfTag
Android

Tag used to log scroll performance on this scroll view. Will force momentum events to be turned on (see sendMomentumEvents). This doesn't do anything out of the box and you need to implement a custom native FpsListener for it to be useful.

Type
string

scrollToOverflowEnabled
iOS

When true, the scroll view can be programmatically scrolled beyond its content size.

TypeDefault
boolfalse

scrollsToTop
iOS

When true, the scroll view scrolls to top when the status bar is tapped.

TypeDefault
booltrue

showsHorizontalScrollIndicator

When true, shows a horizontal scroll indicator.

TypeDefault
booltrue

showsVerticalScrollIndicator

When true, shows a vertical scroll indicator.

TypeDefault
booltrue

snapToAlignment
iOS

When snapToInterval is set, snapToAlignment will define the relationship of the snapping to the scroll view.

Possible values:

  • 'start' will align the snap at the left (horizontal) or top (vertical).
  • 'center' will align the snap in the center.
  • 'end' will align the snap at the right (horizontal) or bottom (vertical).
TypeDefault
enum('start', 'center', 'end')'start'

snapToEnd

Use in conjunction with snapToOffsets. By default, the end of the list counts as a snap offset. Set snapToEnd to false to disable this behavior and allow the list to scroll freely between its end and the last snapToOffsets offset.

TypeDefault
booltrue

snapToInterval

When set, causes the scroll view to stop at multiples of the value of snapToInterval. This can be used for paginating through children that have lengths smaller than the scroll view. Typically used in combination with snapToAlignment and decelerationRate="fast". Overrides less configurable pagingEnabled prop.

Type
number

snapToOffsets

When set, causes the scroll view to stop at the defined offsets. This can be used for paginating through variously sized children that have lengths smaller than the scroll view. Typically used in combination with decelerationRate="fast". Overrides less configurable pagingEnabled and snapToInterval props.

Type
array of number

snapToStart

Use in conjunction with snapToOffsets. By default, the beginning of the list counts as a snap offset. Set snapToStart to false to disable this behavior and allow the list to scroll freely between its start and the first snapToOffsets offset.

TypeDefault
booltrue

stickyHeaderIndices

An array of child indices determining which children get docked to the top of the screen when scrolling. For example, passing stickyHeaderIndices={[0]} will cause the first child to be fixed to the top of the scroll view. You can also use like [x,y,z] to make multiple items sticky when they are at the top. This property is not supported in conjunction with horizontal={true}.

Type
array of number

zoomScale
iOS

The current scale of the scroll view content.

TypeDefault
number1.0

Methods

flashScrollIndicators()

flashScrollIndicators();

Displays the scroll indicators momentarily.

scrollTo()

scrollTo(
options?: { x?: number, y?: number, animated?: boolean } | number,
deprecatedX?: number,
deprecatedAnimated?: boolean,
);

Scrolls to a given x, y offset, either immediately, with a smooth animation.

Example:

scrollTo({ x: 0, y: 0, animated: true })

Note: The weird function signature is due to the fact that, for historical reasons, the function also accepts separate arguments as an alternative to the options object. This is deprecated due to ambiguity (y before x), and SHOULD NOT BE USED.

scrollToEnd()

scrollToEnd(([options]: { animated: boolean, duration: number }));

If this is a vertical ScrollView scrolls to the bottom. If this is a horizontal ScrollView scrolls to the right.

Use scrollToEnd({ animated: true }) for smooth animated scrolling, scrollToEnd({ animated: false }) for immediate scrolling. For Android, you may specify a duration, e.g. scrollToEnd({ duration: 500 }) for a controlled duration scroll. If no options are passed, animated defaults to true.

scrollWithoutAnimationTo()

scrollWithoutAnimationTo(y, x);

Deprecated, use scrollTo instead.

Edit this page
Last updated on
- + diff --git a/docs/next/scrollview/index.html b/docs/next/scrollview/index.html index e316a059cc4..e4abfb56255 100644 --- a/docs/next/scrollview/index.html +++ b/docs/next/scrollview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

ScrollView

Component that wraps platform ScrollView while providing integration with touch locking "responder" system.

Keep in mind that ScrollViews must have a bounded height in order to work, since they contain unbounded-height children into a bounded container (via a scroll interaction). In order to bound the height of a ScrollView, either set the height of the view directly (discouraged) or make sure all parent views have bounded height. Forgetting to transfer {flex: 1} down the view stack can lead to errors here, which the element inspector makes quick to debug.

Doesn't yet support other contained responders from blocking this scroll view from becoming the responder.

<ScrollView> vs <FlatList> - which one to use?

ScrollView renders all its react child components at once, but this has a performance downside.

Imagine you have a very long list of items you want to display, maybe several screens worth of content. Creating JS components and native views for everything all at once, much of which may not even be shown, will contribute to slow rendering and increased memory usage.

This is where FlatList comes into play. FlatList renders items lazily, when they are about to appear, and removes items that scroll way off screen to save memory and processing time.

FlatList is also handy if you want to render separators between your items, multiple columns, infinite scroll loading, or any number of other features it supports out of the box.

Example

Reference

Props

View Props

Inherits View Props.

StickyHeaderComponent

A React Component that will be used to render sticky headers, should be used together with stickyHeaderIndices. You may need to set this component if your sticky header uses custom transforms, for example, when you want your list to have an animated and hidable header. If component have not been provided, the default ScrollViewStickyHeader component will be used.

Type
component, element

alwaysBounceHorizontal
iOS

When true, the scroll view bounces horizontally when it reaches the end even if the content is smaller than the scroll view itself.

TypeDefault
booltrue when horizontal={true}
false otherwise

alwaysBounceVertical
iOS

When true, the scroll view bounces vertically when it reaches the end even if the content is smaller than the scroll view itself.

TypeDefault
boolfalse when vertical={true}
true otherwise

automaticallyAdjustContentInsets
iOS

Controls whether iOS should automatically adjust the content inset for scroll views that are placed behind a navigation bar or tab bar/toolbar.

TypeDefault
booltrue

bounces
iOS

When true, the scroll view bounces when it reaches the end of the content if the content is larger than the scroll view along the axis of the scroll direction. When false, it disables all bouncing even if the alwaysBounce* props are true.

TypeDefault
booltrue

bouncesZoom
iOS

When true, gestures can drive zoom past min/max and the zoom will animate to the min/max value at gesture end, otherwise the zoom will not exceed the limits.

TypeDefault
booltrue

canCancelContentTouches
iOS

When false, once tracking starts, won't try to drag if the touch moves.

TypeDefault
booltrue

centerContent
iOS

When true, the scroll view automatically centers the content when the content is smaller than the scroll view bounds; when the content is larger than the scroll view, this property has no effect.

TypeDefault
boolfalse

contentContainerStyle

These styles will be applied to the scroll view content container which wraps all of the child views. Example:

return (
<ScrollView contentContainerStyle={styles.contentContainer}>
</ScrollView>
);
...
const styles = StyleSheet.create({
contentContainer: {
paddingVertical: 20
}
});
Type
View Style

contentInset
iOS

The amount by which the scroll view content is inset from the edges of the scroll view.

TypeDefault
object: {top: number, left: number, bottom: number, right: number}{top: 0, left: 0, bottom: 0, right: 0}

contentInsetAdjustmentBehavior
iOS

This property specifies how the safe area insets are used to modify the content area of the scroll view. Available on iOS 11 and later.

TypeDefault
enum('automatic', 'scrollableAxes', 'never', 'always')'never'

contentOffset

Used to manually set the starting scroll offset.

TypeDefault
Point{x: 0, y: 0}

decelerationRate

A floating-point number that determines how quickly the scroll view decelerates after the user lifts their finger. You may also use string shortcuts "normal" and "fast" which match the underlying iOS settings for UIScrollViewDecelerationRateNormal and UIScrollViewDecelerationRateFast respectively.

  • 'normal' 0.998 on iOS, 0.985 on Android.
  • 'fast', 0.99 on iOS, 0.9 on Android.
TypeDefault
enum('fast', 'normal'), number'normal'

directionalLockEnabled
iOS

When true, the ScrollView will try to lock to only vertical or horizontal scrolling while dragging.

TypeDefault
boolfalse

disableIntervalMomentum

When true, the scroll view stops on the next index (in relation to scroll position at release) regardless of how fast the gesture is. This can be used for pagination when the page is less than the width of the horizontal ScrollView or the height of the vertical ScrollView.

TypeDefault
boolfalse

disableScrollViewPanResponder

When true, the default JS pan responder on the ScrollView is disabled, and full control over touches inside the ScrollView is left to its child components. This is particularly useful if snapToInterval is enabled, since it does not follow typical touch patterns. Do not use this on regular ScrollView use cases without snapToInterval as it may cause unexpected touches to occur while scrolling.

TypeDefault
boolfalse

endFillColor
Android

Sometimes a scrollview takes up more space than its content fills. When this is the case, this prop will fill the rest of the scrollview with a color to avoid setting a background and creating unnecessary overdraw. This is an advanced optimization that is not needed in the general case.

Type
color

fadingEdgeLength
Android

Fades out the edges of the the scroll content.

If the value is greater than 0, the fading edges will be set accordingly to the current scroll direction and position, indicating if there is more content to show.

TypeDefault
number0

horizontal

When true, the scroll view's children are arranged horizontally in a row instead of vertically in a column.

TypeDefault
boolfalse

indicatorStyle
iOS

The style of the scroll indicators.

  • 'default' same as black.
  • 'black', scroll indicator is black. This style is good against a light background.
  • 'white', scroll indicator is white. This style is good against a dark background.
TypeDefault
enum('default', 'black', 'white')'default'

invertStickyHeaders

If sticky headers should stick at the bottom instead of the top of the ScrollView. This is usually used with inverted ScrollViews.

TypeDefault
boolfalse

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

  • 'none', drags do not dismiss the keyboard.
  • 'on-drag', the keyboard is dismissed when a drag begins.

iOS Only

  • 'interactive', the keyboard is dismissed interactively with the drag and moves in synchrony with the touch, dragging upwards cancels the dismissal. On Android this is not supported and it will have the same behavior as 'none'.
TypeDefault
enum('none', 'on-drag')
Android
enum('none', 'on-drag', 'interactive')
iOS
'none'

keyboardShouldPersistTaps

Determines when the keyboard should stay visible after a tap.

  • 'never' tapping outside of the focused text input when the keyboard is up dismisses the keyboard. When this happens, children won't receive the tap.
  • 'always', the keyboard will not dismiss automatically, and the scroll view will not catch taps, but children of the scroll view can catch taps.
  • 'handled', the keyboard will not dismiss automatically when the tap was handled by children of the scroll view (or captured by an ancestor).
  • false, deprecated, use 'never' instead
  • true, deprecated, use 'always' instead
TypeDefault
enum('always', 'never', 'handled', false, true)'never'

maintainVisibleContentPosition
iOS

When set, the scroll view will adjust the scroll position so that the first child that is currently visible and at or beyond minIndexForVisible will not change position. This is useful for lists that are loading content in both directions, e.g. a chat thread, where new messages coming in might otherwise cause the scroll position to jump. A value of 0 is common, but other values such as 1 can be used to skip loading spinners or other content that should not maintain position.

The optional autoscrollToTopThreshold can be used to make the content automatically scroll to the top after making the adjustment if the user was within the threshold of the top before the adjustment was made. This is also useful for chat-like applications where you want to see new messages scroll into place, but not if the user has scrolled up a ways and it would be disruptive to scroll a bunch.

Caveat 1: Reordering elements in the scrollview with this enabled will probably cause jumpiness and jank. It can be fixed, but there are currently no plans to do so. For now, don't re-order the content of any ScrollViews or Lists that use this feature.

Caveat 2: This uses contentOffset and frame.origin in native code to compute visibility. Occlusion, transforms, and other complexity won't be taken into account as to whether content is "visible" or not.

Type
object: { minIndexForVisible: number, autoscrollToTopThreshold: number }

maximumZoomScale
iOS

The maximum allowed zoom scale.

TypeDefault
number1.0

minimumZoomScale
iOS

The minimum allowed zoom scale.

TypeDefault
number1.0

nestedScrollEnabled
Android

Enables nested scrolling for Android API level 21+.

TypeDefault
booltrue

onContentSizeChange

Called when scrollable content view of the ScrollView changes.

Handler function is passed the content width and content height as parameters: (contentWidth, contentHeight)

It's implemented using onLayout handler attached to the content container which this ScrollView renders.

Type
function

onMomentumScrollBegin

Called when the momentum scroll starts (scroll which occurs as the ScrollView starts gliding).

Type
function

onMomentumScrollEnd

Called when the momentum scroll ends (scroll which occurs as the ScrollView glides to a stop).

Type
function

onScroll

Fires at most once per frame during scrolling. The frequency of the events can be controlled using the scrollEventThrottle prop. The event has the following shape (all values are numbers):

{
nativeEvent: {
contentInset: {bottom, left, right, top},
contentOffset: {x, y},
contentSize: {height, width},
layoutMeasurement: {height, width},
zoomScale
}
}
Type
function

onScrollBeginDrag

Called when the user begins to drag the scroll view.

Type
function

onScrollEndDrag

Called when the user stops dragging the scroll view and it either stops or begins to glide.

Type
function

onScrollToTop
iOS

Fires when the scroll view scrolls to top after the status bar has been tapped.

Type
function

overScrollMode
Android

Used to override default value of overScroll mode.

Possible values:

  • 'auto' - Allow a user to over-scroll this view only if the content is large enough to meaningfully scroll.
  • 'always' - Always allow a user to over-scroll this view.
  • 'never' - Never allow a user to over-scroll this view.
TypeDefault
enum('auto', 'always', 'never')'auto'

pagingEnabled

When true, the scroll view stops on multiples of the scroll view's size when scrolling. This can be used for horizontal pagination.

Note: Vertical pagination is not supported on Android.

TypeDefault
boolfalse

persistentScrollbar
Android

Causes the scrollbars not to turn transparent when they are not in use.

TypeDefault
boolfalse

pinchGestureEnabled
iOS

When true, ScrollView allows use of pinch gestures to zoom in and out.

TypeDefault
booltrue

refreshControl

A RefreshControl component, used to provide pull-to-refresh functionality for the ScrollView. Only works for vertical ScrollViews (horizontal prop must be false).

See RefreshControl.

Type
element

removeClippedSubviews

Experimental: When true, offscreen child views (whose overflow value is hidden) are removed from their native backing superview when offscreen. This can improve scrolling performance on long lists.

TypeDefault
boolfalse

scrollBarThumbImage
VR

Optionally an image can be used for the scroll bar thumb. This will override the color. While the image is loading or the image fails to load the color will be used instead. Use an alpha of 0 in the color to avoid seeing it while the image is loading.

  • uri, a string representing the resource identifier for the image, which should be either a local file path or the name of a static image resource.
  • number, opaque type returned by something like import IMAGE from './image.jpg'.
Type
string, number

scrollEnabled

When false, the view cannot be scrolled via touch interaction.

Note that the view can always be scrolled by calling scrollTo.

TypeDefault
booltrue

scrollEventThrottle
iOS

This controls how often the scroll event will be fired while scrolling (as a time interval in ms). A lower number yields better accuracy for code that is tracking the scroll position, but can lead to scroll performance problems due to the volume of information being sent over the bridge. You will not notice a difference between values set between 1-16 as the JS run loop is synced to the screen refresh rate. If you do not need precise scroll position tracking, set this value higher to limit the information being sent across the bridge. The default value is 0, which results in the scroll event being sent only once each time the view is scrolled.

TypeDefault
number0

scrollIndicatorInsets
iOS

The amount by which the scroll view indicators are inset from the edges of the scroll view. This should normally be set to the same value as the contentInset.

TypeDefault
object: {top: number, left: number, bottom: number, right: number}{top: 0, left: 0, bottom: 0, right: 0}

scrollPerfTag
Android

Tag used to log scroll performance on this scroll view. Will force momentum events to be turned on (see sendMomentumEvents). This doesn't do anything out of the box and you need to implement a custom native FpsListener for it to be useful.

Type
string

scrollToOverflowEnabled
iOS

When true, the scroll view can be programmatically scrolled beyond its content size.

TypeDefault
boolfalse

scrollsToTop
iOS

When true, the scroll view scrolls to top when the status bar is tapped.

TypeDefault
booltrue

showsHorizontalScrollIndicator

When true, shows a horizontal scroll indicator.

TypeDefault
booltrue

showsVerticalScrollIndicator

When true, shows a vertical scroll indicator.

TypeDefault
booltrue

snapToAlignment
iOS

When snapToInterval is set, snapToAlignment will define the relationship of the snapping to the scroll view.

Possible values:

  • 'start' will align the snap at the left (horizontal) or top (vertical).
  • 'center' will align the snap in the center.
  • 'end' will align the snap at the right (horizontal) or bottom (vertical).
TypeDefault
enum('start', 'center', 'end')'start'

snapToEnd

Use in conjunction with snapToOffsets. By default, the end of the list counts as a snap offset. Set snapToEnd to false to disable this behavior and allow the list to scroll freely between its end and the last snapToOffsets offset.

TypeDefault
booltrue

snapToInterval

When set, causes the scroll view to stop at multiples of the value of snapToInterval. This can be used for paginating through children that have lengths smaller than the scroll view. Typically used in combination with snapToAlignment and decelerationRate="fast". Overrides less configurable pagingEnabled prop.

Type
number

snapToOffsets

When set, causes the scroll view to stop at the defined offsets. This can be used for paginating through variously sized children that have lengths smaller than the scroll view. Typically used in combination with decelerationRate="fast". Overrides less configurable pagingEnabled and snapToInterval props.

Type
array of number

snapToStart

Use in conjunction with snapToOffsets. By default, the beginning of the list counts as a snap offset. Set snapToStart to false to disable this behavior and allow the list to scroll freely between its start and the first snapToOffsets offset.

TypeDefault
booltrue

stickyHeaderIndices

An array of child indices determining which children get docked to the top of the screen when scrolling. For example, passing stickyHeaderIndices={[0]} will cause the first child to be fixed to the top of the scroll view. You can also use like [x,y,z] to make multiple items sticky when they are at the top. This property is not supported in conjunction with horizontal={true}.

Type
array of number

zoomScale
iOS

The current scale of the scroll view content.

TypeDefault
number1.0

Methods

flashScrollIndicators()

flashScrollIndicators();

Displays the scroll indicators momentarily.

scrollTo()

scrollTo(
options?: { x?: number, y?: number, animated?: boolean } | number,
deprecatedX?: number,
deprecatedAnimated?: boolean,
);

Scrolls to a given x, y offset, either immediately, with a smooth animation.

Example:

scrollTo({ x: 0, y: 0, animated: true })

Note: The weird function signature is due to the fact that, for historical reasons, the function also accepts separate arguments as an alternative to the options object. This is deprecated due to ambiguity (y before x), and SHOULD NOT BE USED.

scrollToEnd()

scrollToEnd(([options]: { animated: boolean, duration: number }));

If this is a vertical ScrollView scrolls to the bottom. If this is a horizontal ScrollView scrolls to the right.

Use scrollToEnd({ animated: true }) for smooth animated scrolling, scrollToEnd({ animated: false }) for immediate scrolling. For Android, you may specify a duration, e.g. scrollToEnd({ duration: 500 }) for a controlled duration scroll. If no options are passed, animated defaults to true.

scrollWithoutAnimationTo()

scrollWithoutAnimationTo(y, x);

Deprecated, use scrollTo instead.

Edit this page
Last updated on
- + diff --git a/docs/next/sectionlist.html b/docs/next/sectionlist.html index 668ce140d87..97e9930a618 100644 --- a/docs/next/sectionlist.html +++ b/docs/next/sectionlist.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

SectionList

A performant interface for rendering sectioned lists, supporting the most handy features:

  • Fully cross-platform.
  • Configurable viewability callbacks.
  • List header support.
  • List footer support.
  • Item separator support.
  • Section header support.
  • Section separator support.
  • Heterogeneous data and item rendering support.
  • Pull to Refresh.
  • Scroll loading.

If you don't need section support and want a simpler interface, use <FlatList>.

Example

This is a convenience wrapper around <VirtualizedList>, and thus inherits its props (as well as those of <ScrollView>) that aren't explicitly listed here, along with the following caveats:

  • Internal state is not preserved when content scrolls out of the render window. Make sure all your data is captured in the item data or external stores like Flux, Redux, or Relay.
  • This is a PureComponent which means that it will not re-render if props remain shallow-equal. Make sure that everything your renderItem function depends on is passed as a prop (e.g. extraData) that is not === after updates, otherwise your UI may not update on changes. This includes the data prop and parent component state.
  • In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate and momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application, and we are working on improving it behind the scenes.
  • By default, the list looks for a key prop on each item and uses that for the React key. Alternatively, you can provide a custom keyExtractor prop.

Reference

Props

ScrollView Props

Inherits ScrollView Props.

Required
renderItem

Default renderer for every item in every section. Can be over-ridden on a per-section basis. Should return a React element.

Type
function

The render function will be passed an object with the following keys:

  • 'item' (object) - the item object as specified in this section's data key
  • 'index' (number) - Item's index within the section.
  • 'section' (object) - The full section object as specified in sections.
  • 'separators' (object) - An object with the following keys:
    • 'highlight' (function) - () => void
    • 'unhighlight' (function) - () => void
    • 'updateProps' (function) - (select, newProps) => void
      • 'select' (enum) - possible values are 'leading', 'trailing'
      • 'newProps' (object)

Required
sections

The actual data to render, akin to the data prop in FlatList.

Type
array of Sections

extraData

A marker property for telling the list to re-render (since it implements PureComponent). If any of your renderItem, Header, Footer, etc. functions depend on anything outside of the data prop, stick it here and treat it immutably.

Type
any

initialNumToRender

How many items to render in the initial batch. This should be enough to fill the screen but not much more. Note these items will never be unmounted as part of the windowed rendering in order to improve perceived performance of scroll-to-top actions.

TypeDefault
number10

inverted

Reverses the direction of scroll. Uses scale transforms of -1.

TypeDefault
booleanfalse

ItemSeparatorComponent

Rendered in between each item, but not at the top or bottom. By default, highlighted, section, and [leading/trailing][Item/Section] props are provided. renderItem provides separators.highlight/unhighlight which will update the highlighted prop, but you can also add custom props with separators.updateProps.

Type
component, element

keyExtractor

Used to extract a unique key for a given item at the specified index. Key is used for caching and as the React key to track item re-ordering. The default extractor checks item.key, then falls back to using the index, like React does. Note that this sets keys for each item, but each overall section still needs its own key.

Type
(item: object, index: number) => string

ListEmptyComponent

Rendered when the list is empty. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

Type
component, element

ListFooterComponent

Rendered at the very end of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

Type
component, element

ListHeaderComponent

Rendered at the very beginning of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

Type
component, element

onEndReached

Called once when the scroll position gets within onEndReachedThreshold of the rendered content.

Type
(info: { distanceFromEnd: number }) => void

onEndReachedThreshold

How far from the end (in units of visible length of the list) the bottom edge of the list must be from the end of the content to trigger the onEndReached callback. Thus a value of 0.5 will trigger onEndReached when the end of the content is within half the visible length of the list.

TypeDefault
number2

onRefresh

If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the refreshing prop correctly. To offset the RefreshControl from the top (e.g. by 100 pts), use progressViewOffset={100}.

Type
function

onViewableItemsChanged

Called when the viewability of rows changes, as defined by the viewabilityConfig prop.

Type
(callback: { changed: array of ViewTokens, viewableItems: array of ViewTokens }) => void

refreshing

Set this true while waiting for new data from a refresh.

TypeDefault
booleanfalse

removeClippedSubviews

Note: may have bugs (missing content) in some circumstances - use at your own risk.

This may improve scroll performance for large lists.

TypeDefault
booleanfalse

renderSectionFooter

Rendered at the bottom of each section.

Type
(info: { section: Section }) => element, null

renderSectionHeader

Rendered at the top of each section. These stick to the top of the ScrollView by default on iOS. See stickySectionHeadersEnabled.

Type
(info: { section: Section }) => element, null

SectionSeparatorComponent

Rendered at the top and bottom of each section (note this is different from ItemSeparatorComponent which is only rendered between items). These are intended to separate sections from the headers above and below and typically have the same highlight response as ItemSeparatorComponent. Also receives highlighted, [leading/trailing][Item/Section], and any custom props from separators.updateProps.

Type
component, element

stickySectionHeadersEnabled

Makes section headers stick to the top of the screen until the next one pushes it off. Only enabled by default on iOS because that is the platform standard there.

TypeDefault
booleanfalse

Methods

flashScrollIndicators()
iOS

flashScrollIndicators();

Displays the scroll indicators momentarily.

recordInteraction()

recordInteraction();

Tells the list an interaction has occurred, 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.

scrollToLocation()

scrollToLocation(params);

Scrolls to the item at the specified sectionIndex and itemIndex (within the section) positioned in the viewable area such that viewPosition 0 places it at the top (and may be covered by a sticky header), 1 at the bottom, and 0.5 centered in the middle.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout or onScrollToIndexFailed prop.

Parameters:

NameType
params
Required
object

Valid params keys are:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.
  • 'itemIndex' (number) - Index within section for the item to scroll to. Required.
  • 'sectionIndex' (number) - Index for section that contains the item to scroll to. Required.
  • 'viewOffset' (number) - A fixed number of pixels to offset the final target position, e.g. to compensate for sticky headers.
  • 'viewPosition' (number) - A value of 0 places the item specified by index at the top, 1 at the bottom, and 0.5 centered in the middle.

Type Definitions

Section

An object that identifies the data to be rendered for a given section.

Type
any

Properties:

NameTypeDescription
data
Required
arrayThe data for rendering items in this section. Array of objects, much like FlatList's data prop.
keystringOptional key to keep track of section re-ordering. If you don't plan on re-ordering sections, the array index will be used by default.
renderItemfunctionOptionally define an arbitrary item renderer for this section, overriding the default renderItem for the list.
ItemSeparatorComponentcomponent, elementOptionally define an arbitrary item separator for this section, overriding the default ItemSeparatorComponent for the list.
keyExtractorfunctionOptionally define an arbitrary key extractor for this section, overriding the default keyExtractor.
Edit this page
Last updated on
- + diff --git a/docs/next/sectionlist/index.html b/docs/next/sectionlist/index.html index 668ce140d87..97e9930a618 100644 --- a/docs/next/sectionlist/index.html +++ b/docs/next/sectionlist/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

SectionList

A performant interface for rendering sectioned lists, supporting the most handy features:

  • Fully cross-platform.
  • Configurable viewability callbacks.
  • List header support.
  • List footer support.
  • Item separator support.
  • Section header support.
  • Section separator support.
  • Heterogeneous data and item rendering support.
  • Pull to Refresh.
  • Scroll loading.

If you don't need section support and want a simpler interface, use <FlatList>.

Example

This is a convenience wrapper around <VirtualizedList>, and thus inherits its props (as well as those of <ScrollView>) that aren't explicitly listed here, along with the following caveats:

  • Internal state is not preserved when content scrolls out of the render window. Make sure all your data is captured in the item data or external stores like Flux, Redux, or Relay.
  • This is a PureComponent which means that it will not re-render if props remain shallow-equal. Make sure that everything your renderItem function depends on is passed as a prop (e.g. extraData) that is not === after updates, otherwise your UI may not update on changes. This includes the data prop and parent component state.
  • In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate and momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application, and we are working on improving it behind the scenes.
  • By default, the list looks for a key prop on each item and uses that for the React key. Alternatively, you can provide a custom keyExtractor prop.

Reference

Props

ScrollView Props

Inherits ScrollView Props.

Required
renderItem

Default renderer for every item in every section. Can be over-ridden on a per-section basis. Should return a React element.

Type
function

The render function will be passed an object with the following keys:

  • 'item' (object) - the item object as specified in this section's data key
  • 'index' (number) - Item's index within the section.
  • 'section' (object) - The full section object as specified in sections.
  • 'separators' (object) - An object with the following keys:
    • 'highlight' (function) - () => void
    • 'unhighlight' (function) - () => void
    • 'updateProps' (function) - (select, newProps) => void
      • 'select' (enum) - possible values are 'leading', 'trailing'
      • 'newProps' (object)

Required
sections

The actual data to render, akin to the data prop in FlatList.

Type
array of Sections

extraData

A marker property for telling the list to re-render (since it implements PureComponent). If any of your renderItem, Header, Footer, etc. functions depend on anything outside of the data prop, stick it here and treat it immutably.

Type
any

initialNumToRender

How many items to render in the initial batch. This should be enough to fill the screen but not much more. Note these items will never be unmounted as part of the windowed rendering in order to improve perceived performance of scroll-to-top actions.

TypeDefault
number10

inverted

Reverses the direction of scroll. Uses scale transforms of -1.

TypeDefault
booleanfalse

ItemSeparatorComponent

Rendered in between each item, but not at the top or bottom. By default, highlighted, section, and [leading/trailing][Item/Section] props are provided. renderItem provides separators.highlight/unhighlight which will update the highlighted prop, but you can also add custom props with separators.updateProps.

Type
component, element

keyExtractor

Used to extract a unique key for a given item at the specified index. Key is used for caching and as the React key to track item re-ordering. The default extractor checks item.key, then falls back to using the index, like React does. Note that this sets keys for each item, but each overall section still needs its own key.

Type
(item: object, index: number) => string

ListEmptyComponent

Rendered when the list is empty. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

Type
component, element

ListFooterComponent

Rendered at the very end of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

Type
component, element

ListHeaderComponent

Rendered at the very beginning of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

Type
component, element

onEndReached

Called once when the scroll position gets within onEndReachedThreshold of the rendered content.

Type
(info: { distanceFromEnd: number }) => void

onEndReachedThreshold

How far from the end (in units of visible length of the list) the bottom edge of the list must be from the end of the content to trigger the onEndReached callback. Thus a value of 0.5 will trigger onEndReached when the end of the content is within half the visible length of the list.

TypeDefault
number2

onRefresh

If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the refreshing prop correctly. To offset the RefreshControl from the top (e.g. by 100 pts), use progressViewOffset={100}.

Type
function

onViewableItemsChanged

Called when the viewability of rows changes, as defined by the viewabilityConfig prop.

Type
(callback: { changed: array of ViewTokens, viewableItems: array of ViewTokens }) => void

refreshing

Set this true while waiting for new data from a refresh.

TypeDefault
booleanfalse

removeClippedSubviews

Note: may have bugs (missing content) in some circumstances - use at your own risk.

This may improve scroll performance for large lists.

TypeDefault
booleanfalse

renderSectionFooter

Rendered at the bottom of each section.

Type
(info: { section: Section }) => element, null

renderSectionHeader

Rendered at the top of each section. These stick to the top of the ScrollView by default on iOS. See stickySectionHeadersEnabled.

Type
(info: { section: Section }) => element, null

SectionSeparatorComponent

Rendered at the top and bottom of each section (note this is different from ItemSeparatorComponent which is only rendered between items). These are intended to separate sections from the headers above and below and typically have the same highlight response as ItemSeparatorComponent. Also receives highlighted, [leading/trailing][Item/Section], and any custom props from separators.updateProps.

Type
component, element

stickySectionHeadersEnabled

Makes section headers stick to the top of the screen until the next one pushes it off. Only enabled by default on iOS because that is the platform standard there.

TypeDefault
booleanfalse

Methods

flashScrollIndicators()
iOS

flashScrollIndicators();

Displays the scroll indicators momentarily.

recordInteraction()

recordInteraction();

Tells the list an interaction has occurred, 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.

scrollToLocation()

scrollToLocation(params);

Scrolls to the item at the specified sectionIndex and itemIndex (within the section) positioned in the viewable area such that viewPosition 0 places it at the top (and may be covered by a sticky header), 1 at the bottom, and 0.5 centered in the middle.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout or onScrollToIndexFailed prop.

Parameters:

NameType
params
Required
object

Valid params keys are:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.
  • 'itemIndex' (number) - Index within section for the item to scroll to. Required.
  • 'sectionIndex' (number) - Index for section that contains the item to scroll to. Required.
  • 'viewOffset' (number) - A fixed number of pixels to offset the final target position, e.g. to compensate for sticky headers.
  • 'viewPosition' (number) - A value of 0 places the item specified by index at the top, 1 at the bottom, and 0.5 centered in the middle.

Type Definitions

Section

An object that identifies the data to be rendered for a given section.

Type
any

Properties:

NameTypeDescription
data
Required
arrayThe data for rendering items in this section. Array of objects, much like FlatList's data prop.
keystringOptional key to keep track of section re-ordering. If you don't plan on re-ordering sections, the array index will be used by default.
renderItemfunctionOptionally define an arbitrary item renderer for this section, overriding the default renderItem for the list.
ItemSeparatorComponentcomponent, elementOptionally define an arbitrary item separator for this section, overriding the default ItemSeparatorComponent for the list.
keyExtractorfunctionOptionally define an arbitrary key extractor for this section, overriding the default keyExtractor.
Edit this page
Last updated on
- + diff --git a/docs/next/security.html b/docs/next/security.html index f6da3d53755..7f9043ab1cd 100644 --- a/docs/next/security.html +++ b/docs/next/security.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Security

Security is often overlooked when building apps. It is true that it is impossible to build software that is completely impenetrable—we’ve yet to invent a completely impenetrable lock (bank vaults do, after all, still get broken into). However, the probability of falling victim to a malicious attack or being exposed for a security vulnerability is inversely proportional to the effort you’re willing to put in to protecting your application against any such eventuality. Although an ordinary padlock is pickable, it is still much harder to get past than a cabinet hook!

In this guide, you will learn about best practices for storing sensitive information, authentication, network security, and tools that will help you secure your app. This is not a preflight checklist—it is a catalogue of options, each of which will help further protect your app and users.

Storing Sensitive Info

Never store sensitive API keys in your app code. Anything included in your code could be accessed in plain text by anyone inspecting the app bundle. Tools like react-native-dotenv and react-native-config are great for adding environment-specific variables like API endpoints, but they should not be confused with server-side environment variables, which can often contain secrets and API keys.

If you must have an API key or a secret to access some resource from your app, the most secure way to handle this would be to build an orchestration layer between your app and the resource. This could be a serverless function (e.g. using AWS Lambda or Google Cloud Functions) which can forward the request with the required API key or secret. Secrets in server side code cannot be accessed by the API consumers the same way secrets in your app code can.

For persisted user data, choose the right type of storage based on its sensitivity. As your app is used, you’ll often find the need to save data on the device, whether to support your app being used offline, cut down on network requests or save your user’s access token between sessions so they wouldn’t have to re-authenticate each time they use the app.

Persisted vs unpersisted — persisted data is written to the device’s disk, which lets the data be read by your app across application launches without having to do another network request to fetch it or asking the user to re-enter it. But this also can make that data more vulnerable to being accessed by attackers. Unpersisted data is never written to disk—so there's no data to access!

Async Storage

Async Storage is a community-maintained module for React Native that provides an asynchronous, unencrypted, key-value store. Async Storage is not shared between apps: every app has its own sandbox environment and has no access to data from other apps.

Do use async storage when...Don't use async storage for...
Persisting non-sensitive data across app runsToken storage
Persisting Redux stateSecrets
Persisting GraphQL state
Storing global app-wide variables

Developer Notes

Async Storage is the React Native equivalent of Local Storage from the web

Secure Storage

React Native does not come bundled with any way of storing sensitive data. However, there are pre-existing solutions for Android and iOS platforms.

iOS - Keychain Services

Keychain Services allows you to securely store small chunks of sensitive info for the user. This is an ideal place to store certificates, tokens, passwords, and any other sensitive information that doesn’t belong in Async Storage.

Android - Secure Shared Preferences

Shared Preferences is the Android equivalent for a persistent key-value data store. Data in Shared Preferences is not encrypted by default, but Encrypted Shared Preferences wraps the Shared Preferences class for Android, and automatically encrypts keys and values.

Android - Keystore

The Android Keystore system lets you store cryptographic keys in a container to make it more difficult to extract from the device.

In order to use iOS Keychain services or Android Secure Shared Preferences, you can either write a bridge yourself or use a library which wraps them for you and provides a unified API at your own risk. Some libraries to consider:

Be mindful of unintentionally storing or exposing sensitive info. This could happen accidentally, for example saving sensitive form data in redux state and persisting the whole state tree in Async Storage. Or sending user tokens and personal info to an application monitoring service such as Sentry or Crashlytics.

Authentication and Deep Linking

Mobile apps have a unique vulnerability that is non-existent in the web: deep linking. Deep linking is a way of sending data directly to a native application from an outside source. A deep link looks like app:// where app is your app scheme and anything following the // could be used internally to handle the request.

For example, if you were building an ecommerce app, you could use app://products/1 to deep link to your app and open the product detail page for a product with id 1. You can think of these kind of like URLs on the web, but with one crucial distinction:

Deep links are not secure and you should never send any sensitive information in them.

The reason deep links are not secure is because there is no centralized method of registering URL schemes. As an application developer, you can use almost any url scheme you choose by configuring it in Xcode for iOS or adding an intent on Android.

There is nothing stopping a malicious application from hijacking your deep link by also registering to the same scheme and then obtaining access to the data your link contains. Sending something like app://products/1 is not harmful, but sending tokens is a security concern.

When the operating system has two or more applications to choose from when opening a link, Android will show the user a modal and ask them to choose which application to use to open the link. On iOS however, the operating system will make the choice for you, so the user will be blissfully unaware. Apple has made steps to address this issue in later iOS versions (iOS 11) where they instituted a first-come-first-served principle, although this vulnerability could still be exploited in different ways which you can read more about here. Using universal links will allow linking to content within your app securely in iOS.

OAuth2 and Redirects

The OAuth2 authentication protocol is incredibly popular nowadays, prided as the most complete and secure protocol around. The OpenID Connect protocol is also based on this. In OAuth2, the user is asked to authenticate via a third party. On successful completion, this third party redirects back to the requesting application with a verification code which can be exchanged for a JWT — a JSON Web Token. JWT is an open standard for securely transmitting information between parties on the web.

On the web, this redirect step is secure, because URLs on the web are guaranteed to be unique. This is not true for apps because, as mentioned earlier, there is no centralized method of registering URL schemes! In order to address this security concern, an additional check must be added in the form of PKCE.

PKCE, pronounced “Pixy” stands for Proof of Key Code Exchange, and is an extension to the OAuth 2 spec. This involves adding an additional layer of security which verifies that the authentication and token exchange requests come from the same client. PKCE uses the SHA 256 Cryptographic Hash Algorithm. SHA 256 creates a unique “signature” for a text or file of any size, but it is:

  • Always the same length regardless of the input file
  • Guaranteed to always produce the same result for the same input
  • One way (that is, you can’t reverse engineer it to reveal the original input)

Now you have two values:

  • code_verifier - a large random string generated by the client
  • code_challenge - the SHA 256 of the code_verifier

During the initial /authorize request, the client also sends the code_challenge for the code_verifier it keeps in memory. After the authorize request has returned correctly, the client also sends the code_verifier that was used to generate the code_challenge. The IDP will then calculate the code_challenge, see if it matches what was set on the very first /authorize request, and only send the access token if the values match.

This guarantees that only the application that triggered the initial authorization flow would be able to successfully exchange the verification code for a JWT. So even if a malicious application gets access to the verification code, it will be useless on its own. To see this in action, check out this example.

A library to consider for native OAuth is react-native-app-auth. React-native-app-auth is an SDK for communicating with OAuth2 providers. It wraps the native AppAuth-iOS and AppAuth-Android libraries and can support PKCE.

React-native-app-auth can support PKCE only if your Identity Provider supports it.

OAuth2 with PKCE

Network Security

Your APIs should always use SSL encryption. SSL encryption protects against the requested data being read in plain text between when it leaves the server and before it reaches the client. You’ll know the endpoint is secure, because it starts with https:// instead of http://.

SSL Pinning

Using https endpoints could still leave your data vulnerable to interception. With https, the client will only trust the server if it can provide a valid certificate that is signed by a trusted Certificate Authority that is pre-installed on the client. An attacker could take advantage of this by installing a malicious root CA certificate to the user’s device, so the client would trust all certificates that are signed by the attacker. Thus, relying on certificates alone could still leave you vulnerable to a man-in-the-middle attack.

SSL pinning is a technique that can be used on the client side to avoid this attack. It works by embedding (or pinning) a list of trusted certificates to the client during development, so that only the requests signed with one of the trusted certificates will be accepted, and any self-signed certificates will not be.

When using SSL pinning, you should be mindful of certificate expiry. Certificates expire every 1-2 years and when one does, it’ll need to be updated in the app as well as on the server. As soon as the certificate on the server has been updated, any apps with the old certificate embedded in them will cease to work.

Summary

There is no bulletproof way to handle security, but with conscious effort and diligence, it is possible to significantly reduce the likelihood of a security breach in your application. Invest in security proportional to the sensitivity of the data stored in your application, the number of users, and the damage a hacker could do when gaining access to their account. And remember: it’s significantly harder to access information that was never requested in the first place.

Edit this page
Last updated on
- + diff --git a/docs/next/security/index.html b/docs/next/security/index.html index f6da3d53755..7f9043ab1cd 100644 --- a/docs/next/security/index.html +++ b/docs/next/security/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Security

Security is often overlooked when building apps. It is true that it is impossible to build software that is completely impenetrable—we’ve yet to invent a completely impenetrable lock (bank vaults do, after all, still get broken into). However, the probability of falling victim to a malicious attack or being exposed for a security vulnerability is inversely proportional to the effort you’re willing to put in to protecting your application against any such eventuality. Although an ordinary padlock is pickable, it is still much harder to get past than a cabinet hook!

In this guide, you will learn about best practices for storing sensitive information, authentication, network security, and tools that will help you secure your app. This is not a preflight checklist—it is a catalogue of options, each of which will help further protect your app and users.

Storing Sensitive Info

Never store sensitive API keys in your app code. Anything included in your code could be accessed in plain text by anyone inspecting the app bundle. Tools like react-native-dotenv and react-native-config are great for adding environment-specific variables like API endpoints, but they should not be confused with server-side environment variables, which can often contain secrets and API keys.

If you must have an API key or a secret to access some resource from your app, the most secure way to handle this would be to build an orchestration layer between your app and the resource. This could be a serverless function (e.g. using AWS Lambda or Google Cloud Functions) which can forward the request with the required API key or secret. Secrets in server side code cannot be accessed by the API consumers the same way secrets in your app code can.

For persisted user data, choose the right type of storage based on its sensitivity. As your app is used, you’ll often find the need to save data on the device, whether to support your app being used offline, cut down on network requests or save your user’s access token between sessions so they wouldn’t have to re-authenticate each time they use the app.

Persisted vs unpersisted — persisted data is written to the device’s disk, which lets the data be read by your app across application launches without having to do another network request to fetch it or asking the user to re-enter it. But this also can make that data more vulnerable to being accessed by attackers. Unpersisted data is never written to disk—so there's no data to access!

Async Storage

Async Storage is a community-maintained module for React Native that provides an asynchronous, unencrypted, key-value store. Async Storage is not shared between apps: every app has its own sandbox environment and has no access to data from other apps.

Do use async storage when...Don't use async storage for...
Persisting non-sensitive data across app runsToken storage
Persisting Redux stateSecrets
Persisting GraphQL state
Storing global app-wide variables

Developer Notes

Async Storage is the React Native equivalent of Local Storage from the web

Secure Storage

React Native does not come bundled with any way of storing sensitive data. However, there are pre-existing solutions for Android and iOS platforms.

iOS - Keychain Services

Keychain Services allows you to securely store small chunks of sensitive info for the user. This is an ideal place to store certificates, tokens, passwords, and any other sensitive information that doesn’t belong in Async Storage.

Android - Secure Shared Preferences

Shared Preferences is the Android equivalent for a persistent key-value data store. Data in Shared Preferences is not encrypted by default, but Encrypted Shared Preferences wraps the Shared Preferences class for Android, and automatically encrypts keys and values.

Android - Keystore

The Android Keystore system lets you store cryptographic keys in a container to make it more difficult to extract from the device.

In order to use iOS Keychain services or Android Secure Shared Preferences, you can either write a bridge yourself or use a library which wraps them for you and provides a unified API at your own risk. Some libraries to consider:

Be mindful of unintentionally storing or exposing sensitive info. This could happen accidentally, for example saving sensitive form data in redux state and persisting the whole state tree in Async Storage. Or sending user tokens and personal info to an application monitoring service such as Sentry or Crashlytics.

Authentication and Deep Linking

Mobile apps have a unique vulnerability that is non-existent in the web: deep linking. Deep linking is a way of sending data directly to a native application from an outside source. A deep link looks like app:// where app is your app scheme and anything following the // could be used internally to handle the request.

For example, if you were building an ecommerce app, you could use app://products/1 to deep link to your app and open the product detail page for a product with id 1. You can think of these kind of like URLs on the web, but with one crucial distinction:

Deep links are not secure and you should never send any sensitive information in them.

The reason deep links are not secure is because there is no centralized method of registering URL schemes. As an application developer, you can use almost any url scheme you choose by configuring it in Xcode for iOS or adding an intent on Android.

There is nothing stopping a malicious application from hijacking your deep link by also registering to the same scheme and then obtaining access to the data your link contains. Sending something like app://products/1 is not harmful, but sending tokens is a security concern.

When the operating system has two or more applications to choose from when opening a link, Android will show the user a modal and ask them to choose which application to use to open the link. On iOS however, the operating system will make the choice for you, so the user will be blissfully unaware. Apple has made steps to address this issue in later iOS versions (iOS 11) where they instituted a first-come-first-served principle, although this vulnerability could still be exploited in different ways which you can read more about here. Using universal links will allow linking to content within your app securely in iOS.

OAuth2 and Redirects

The OAuth2 authentication protocol is incredibly popular nowadays, prided as the most complete and secure protocol around. The OpenID Connect protocol is also based on this. In OAuth2, the user is asked to authenticate via a third party. On successful completion, this third party redirects back to the requesting application with a verification code which can be exchanged for a JWT — a JSON Web Token. JWT is an open standard for securely transmitting information between parties on the web.

On the web, this redirect step is secure, because URLs on the web are guaranteed to be unique. This is not true for apps because, as mentioned earlier, there is no centralized method of registering URL schemes! In order to address this security concern, an additional check must be added in the form of PKCE.

PKCE, pronounced “Pixy” stands for Proof of Key Code Exchange, and is an extension to the OAuth 2 spec. This involves adding an additional layer of security which verifies that the authentication and token exchange requests come from the same client. PKCE uses the SHA 256 Cryptographic Hash Algorithm. SHA 256 creates a unique “signature” for a text or file of any size, but it is:

  • Always the same length regardless of the input file
  • Guaranteed to always produce the same result for the same input
  • One way (that is, you can’t reverse engineer it to reveal the original input)

Now you have two values:

  • code_verifier - a large random string generated by the client
  • code_challenge - the SHA 256 of the code_verifier

During the initial /authorize request, the client also sends the code_challenge for the code_verifier it keeps in memory. After the authorize request has returned correctly, the client also sends the code_verifier that was used to generate the code_challenge. The IDP will then calculate the code_challenge, see if it matches what was set on the very first /authorize request, and only send the access token if the values match.

This guarantees that only the application that triggered the initial authorization flow would be able to successfully exchange the verification code for a JWT. So even if a malicious application gets access to the verification code, it will be useless on its own. To see this in action, check out this example.

A library to consider for native OAuth is react-native-app-auth. React-native-app-auth is an SDK for communicating with OAuth2 providers. It wraps the native AppAuth-iOS and AppAuth-Android libraries and can support PKCE.

React-native-app-auth can support PKCE only if your Identity Provider supports it.

OAuth2 with PKCE

Network Security

Your APIs should always use SSL encryption. SSL encryption protects against the requested data being read in plain text between when it leaves the server and before it reaches the client. You’ll know the endpoint is secure, because it starts with https:// instead of http://.

SSL Pinning

Using https endpoints could still leave your data vulnerable to interception. With https, the client will only trust the server if it can provide a valid certificate that is signed by a trusted Certificate Authority that is pre-installed on the client. An attacker could take advantage of this by installing a malicious root CA certificate to the user’s device, so the client would trust all certificates that are signed by the attacker. Thus, relying on certificates alone could still leave you vulnerable to a man-in-the-middle attack.

SSL pinning is a technique that can be used on the client side to avoid this attack. It works by embedding (or pinning) a list of trusted certificates to the client during development, so that only the requests signed with one of the trusted certificates will be accepted, and any self-signed certificates will not be.

When using SSL pinning, you should be mindful of certificate expiry. Certificates expire every 1-2 years and when one does, it’ll need to be updated in the app as well as on the server. As soon as the certificate on the server has been updated, any apps with the old certificate embedded in them will cease to work.

Summary

There is no bulletproof way to handle security, but with conscious effort and diligence, it is possible to significantly reduce the likelihood of a security breach in your application. Invest in security proportional to the sensitivity of the data stored in your application, the number of users, and the damage a hacker could do when gaining access to their account. And remember: it’s significantly harder to access information that was never requested in the first place.

Edit this page
Last updated on
- + diff --git a/docs/next/segmentedcontrolios.html b/docs/next/segmentedcontrolios.html index a91f4a3c754..314d43419e2 100644 --- a/docs/next/segmentedcontrolios.html +++ b/docs/next/segmentedcontrolios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 SegmentedControlIOS

Deprecated. Use one of the community packages instead.

Uses SegmentedControlIOS to render a UISegmentedControl iOS.

Programmatically changing selected index

The selected index can be changed on the fly by assigning the selectedIndex prop to a state variable, then changing that variable. Note that the state variable would need to be updated as the user selects a value and changes the index, as shown in the example below.

Example

Reference

Props

Inherits View Props.

enabled

If false the user won't be able to interact with the control. Default value is true.

TypeRequired
boolNo

momentary

If true, then selecting a segment won't persist visually. The onValueChange callback will still work as expected.

TypeRequired
boolNo

onChange

Callback that is called when the user taps a segment; passes the event as an argument

TypeRequired
functionNo

onValueChange

Callback that is called when the user taps a segment; passes the segment's value as an argument

TypeRequired
functionNo

selectedIndex

The index in props.values of the segment to be (pre)selected.

TypeRequired
numberNo

tintColor

Note: tintColor is not supported on the iOS 13+.

Accent color of the control.

TypeRequired
stringNo

values

The labels for the control's segment buttons, in order.

TypeRequired
array of stringNo
Edit this page
Last updated on
- + diff --git a/docs/next/segmentedcontrolios/index.html b/docs/next/segmentedcontrolios/index.html index a91f4a3c754..314d43419e2 100644 --- a/docs/next/segmentedcontrolios/index.html +++ b/docs/next/segmentedcontrolios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 SegmentedControlIOS

Deprecated. Use one of the community packages instead.

Uses SegmentedControlIOS to render a UISegmentedControl iOS.

Programmatically changing selected index

The selected index can be changed on the fly by assigning the selectedIndex prop to a state variable, then changing that variable. Note that the state variable would need to be updated as the user selects a value and changes the index, as shown in the example below.

Example

Reference

Props

Inherits View Props.

enabled

If false the user won't be able to interact with the control. Default value is true.

TypeRequired
boolNo

momentary

If true, then selecting a segment won't persist visually. The onValueChange callback will still work as expected.

TypeRequired
boolNo

onChange

Callback that is called when the user taps a segment; passes the event as an argument

TypeRequired
functionNo

onValueChange

Callback that is called when the user taps a segment; passes the segment's value as an argument

TypeRequired
functionNo

selectedIndex

The index in props.values of the segment to be (pre)selected.

TypeRequired
numberNo

tintColor

Note: tintColor is not supported on the iOS 13+.

Accent color of the control.

TypeRequired
stringNo

values

The labels for the control's segment buttons, in order.

TypeRequired
array of stringNo
Edit this page
Last updated on
- + diff --git a/docs/next/settings.html b/docs/next/settings.html index 99e84caf5bb..4a069ed0c04 100644 --- a/docs/next/settings.html +++ b/docs/next/settings.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Settings

Settings serves as a wrapper for NSUserDefaults, a persistent key-value store available only on iOS.

Example

Reference

Methods

clearWatch()

static clearWatch(watchId: number)

watchId is the number returned by watchKeys() when the subscription was originally configured.

get()

static get(key: string): mixed

Get the current value for a given key in NSUserDefaults.

set()

static set(settings: object)

Set one or more values in NSUserDefaults.

watchKeys()

static watchKeys(keys: string | array<string>, callback: function): number

Subscribe to be notified when the value for any of the keys specified by the keys parameter has been changed in NSUserDefaults. Returns a watchId number that may be used with clearWatch() to unsubscribe.

Note: watchKeys() by design ignores internal set() calls and fires callback only on changes preformed outside of React Native code.

Edit this page
Last updated on
- + diff --git a/docs/next/settings/index.html b/docs/next/settings/index.html index 99e84caf5bb..4a069ed0c04 100644 --- a/docs/next/settings/index.html +++ b/docs/next/settings/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Settings

Settings serves as a wrapper for NSUserDefaults, a persistent key-value store available only on iOS.

Example

Reference

Methods

clearWatch()

static clearWatch(watchId: number)

watchId is the number returned by watchKeys() when the subscription was originally configured.

get()

static get(key: string): mixed

Get the current value for a given key in NSUserDefaults.

set()

static set(settings: object)

Set one or more values in NSUserDefaults.

watchKeys()

static watchKeys(keys: string | array<string>, callback: function): number

Subscribe to be notified when the value for any of the keys specified by the keys parameter has been changed in NSUserDefaults. Returns a watchId number that may be used with clearWatch() to unsubscribe.

Note: watchKeys() by design ignores internal set() calls and fires callback only on changes preformed outside of React Native code.

Edit this page
Last updated on
- + diff --git a/docs/next/shadow-props.html b/docs/next/shadow-props.html index 6d6f5000058..3c282cf5768 100644 --- a/docs/next/shadow-props.html +++ b/docs/next/shadow-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Shadow Props

Reference

Props

shadowColor

Sets the drop shadow color.

This property will only work on Android API 28 and above. For similar functionality on lower Android APIs, use the elevation property.

Type
color

shadowOffset
iOS

Sets the drop shadow offset.

Type
object: {width: number,height: number}

shadowOpacity
iOS

Sets the drop shadow opacity (multiplied by the color's alpha component).

Type
number

shadowRadius
iOS

Sets the drop shadow blur radius.

Type
number
Edit this page
Last updated on
- + diff --git a/docs/next/shadow-props/index.html b/docs/next/shadow-props/index.html index 6d6f5000058..3c282cf5768 100644 --- a/docs/next/shadow-props/index.html +++ b/docs/next/shadow-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Shadow Props

Reference

Props

shadowColor

Sets the drop shadow color.

This property will only work on Android API 28 and above. For similar functionality on lower Android APIs, use the elevation property.

Type
color

shadowOffset
iOS

Sets the drop shadow offset.

Type
object: {width: number,height: number}

shadowOpacity
iOS

Sets the drop shadow opacity (multiplied by the color's alpha component).

Type
number

shadowRadius
iOS

Sets the drop shadow blur radius.

Type
number
Edit this page
Last updated on
- + diff --git a/docs/next/share.html b/docs/next/share.html index 8f4a197d7db..f97c0fad301 100644 --- a/docs/next/share.html +++ b/docs/next/share.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Share

Example

Reference

Methods

share()

static share(content, options)

Open a dialog to share text content.

In iOS, returns a Promise which will be invoked with an object containing action and activityType. If the user dismissed the dialog, the Promise will still be resolved with action being Share.dismissedAction and all the other keys being undefined. Note that some share options will not appear or work on the iOS simulator.

In Android, returns a Promise which will always be resolved with action being Share.sharedAction.

Properties:

NameTypeDescription
content
Required
objectmessage - a message to share
url - a URL to share
iOS

title - title of the message
Android
At least one of url and message is required.
optionsobjectdialogTitle
Android

excludedActivityTypes
iOS

subject - a subject to share via email
iOS

tintColor
iOS

Properties

sharedAction

static sharedAction

The content was successfully shared.

dismissedAction
iOS

static dismissedAction

The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/next/share/index.html b/docs/next/share/index.html index 8f4a197d7db..f97c0fad301 100644 --- a/docs/next/share/index.html +++ b/docs/next/share/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Share

Example

Reference

Methods

share()

static share(content, options)

Open a dialog to share text content.

In iOS, returns a Promise which will be invoked with an object containing action and activityType. If the user dismissed the dialog, the Promise will still be resolved with action being Share.dismissedAction and all the other keys being undefined. Note that some share options will not appear or work on the iOS simulator.

In Android, returns a Promise which will always be resolved with action being Share.sharedAction.

Properties:

NameTypeDescription
content
Required
objectmessage - a message to share
url - a URL to share
iOS

title - title of the message
Android
At least one of url and message is required.
optionsobjectdialogTitle
Android

excludedActivityTypes
iOS

subject - a subject to share via email
iOS

tintColor
iOS

Properties

sharedAction

static sharedAction

The content was successfully shared.

dismissedAction
iOS

static dismissedAction

The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/next/signed-apk-android.html b/docs/next/signed-apk-android.html index 01777fddd19..b7454c9c270 100644 --- a/docs/next/signed-apk-android.html +++ b/docs/next/signed-apk-android.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Publishing to Google Play Store

Android requires that all apps be digitally signed with a certificate before they can be installed. In order to distribute your Android application via Google Play store it needs to be signed with a release key that then needs to be used for all future updates. Since 2017 it is possible for Google Play to manage signing releases automatically thanks to App Signing by Google Play functionality. However, before your application binary is uploaded to Google Play it needs to be signed with an upload key. The Signing Your Applications page on Android Developers documentation describes the topic in detail. This guide covers the process in brief, as well as lists the steps required to package the JavaScript bundle.

Generating an upload key

You can generate a private signing key using keytool. On Windows keytool must be run from C:\Program Files\Java\jdkx.x.x_x\bin.

keytool -genkeypair -v -storetype PKCS12 -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

This command prompts you for passwords for the keystore and key and for the Distinguished Name fields for your key. It then generates the keystore as a file called my-upload-key.keystore.

The keystore contains a single key, valid for 10000 days. The alias is a name that you will use later when signing your app, so remember to take note of the alias.

On Mac, if you're not sure where your JDK bin folder is, then perform the following command to find it:

/usr/libexec/java_home

It will output the directory of the JDK, which will look something like this:

/Library/Java/JavaVirtualMachines/jdkX.X.X_XXX.jdk/Contents/Home

Navigate to that directory by using the command cd /your/jdk/path and use the keytool command with sudo permission as shown below.

sudo keytool -genkey -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

Note: Remember to keep the keystore file private. In case you've lost upload key or it's been compromised you should follow these instructions.

Setting up Gradle variables

  1. Place the my-upload-key.keystore file under the android/app directory in your project folder.
  2. Edit the file ~/.gradle/gradle.properties or android/gradle.properties, and add the following (replace ***** with the correct keystore password, alias and key password),
MYAPP_UPLOAD_STORE_FILE=my-upload-key.keystore
MYAPP_UPLOAD_KEY_ALIAS=my-key-alias
MYAPP_UPLOAD_STORE_PASSWORD=*****
MYAPP_UPLOAD_KEY_PASSWORD=*****

These are going to be global Gradle variables, which we can later use in our Gradle config to sign our app.

Note about security: If you are not keen on storing your passwords in plaintext, and you are running macOS, you can also store your credentials in the Keychain Access app. Then you can skip the two last rows in ~/.gradle/gradle.properties.

Adding signing config to your app's Gradle config

The last configuration step that needs to be done is to setup release builds to be signed using upload key. Edit the file android/app/build.gradle in your project folder, and add the signing config,

...
android {
...
defaultConfig { ... }
signingConfigs {
release {
if (project.hasProperty('MYAPP_UPLOAD_STORE_FILE')) {
storeFile file(MYAPP_UPLOAD_STORE_FILE)
storePassword MYAPP_UPLOAD_STORE_PASSWORD
keyAlias MYAPP_UPLOAD_KEY_ALIAS
keyPassword MYAPP_UPLOAD_KEY_PASSWORD
}
}
}
buildTypes {
release {
...
signingConfig signingConfigs.release
}
}
}
...

Generating the release AAB

Run the following in a terminal:

cd android
./gradlew bundleRelease

Gradle's bundleRelease will bundle all the JavaScript needed to run your app into the AAB (Android App Bundle). If you need to change the way the JavaScript bundle and/or drawable resources are bundled (e.g. if you changed the default file/folder names or the general structure of the project), have a look at android/app/build.gradle to see how you can update it to reflect these changes.

Note: Make sure gradle.properties does not include org.gradle.configureondemand=true as that will make the release build skip bundling JS and assets into the app binary.

The generated AAB can be found under android/app/build/outputs/bundle/release/app.aab, and is ready to be uploaded to Google Play.

In order for Google Play to accept AAB format the App Signing by Google Play needs to be configured for your application on the Google Play Console. If you are updating an existing app that doesn't use App Signing by Google Play, please check our migration section to learn how to perform that configuration change.

Testing the release build of your app

Before uploading the release build to the Play Store, make sure you test it thoroughly. First uninstall any previous version of the app you already have installed. Install it on the device using the following command in the project root:

npx react-native run-android --variant=release

Note that --variant release is only available if you've set up signing as described above.

You can terminate any running bundler instances, since all your framework and JavaScript code is bundled in the APK's assets.

Publishing to other stores

By default, the generated APK has the native code for both x86 and ARMv7a CPU architectures. This makes it easier to share APKs that run on almost all Android devices. However, this has the downside that there will be some unused native code on any device, leading to unnecessarily bigger APKs.

You can create an APK for each CPU by changing the following line in android/app/build.gradle:

- ndk {
- abiFilters "armeabi-v7a", "x86"
- }
- def enableSeparateBuildPerCPUArchitecture = false
+ def enableSeparateBuildPerCPUArchitecture = true

Upload both these files to markets which support device targeting, such as Google Play and Amazon AppStore, and the users will automatically get the appropriate APK. If you want to upload to other markets, such as APKFiles, which do not support multiple APKs for a single app, change the following line as well to create the default universal APK with binaries for both CPUs.

- universalApk false // If true, also generate a universal APK
+ universalApk true // If true, also generate a universal APK

Enabling Proguard to reduce the size of the APK (optional)

Proguard is a tool that can slightly reduce the size of the APK. It does this by stripping parts of the React Native Java bytecode (and its dependencies) that your app is not using.

IMPORTANT: Make sure to thoroughly test your app if you've enabled Proguard. Proguard often requires configuration specific to each native library you're using. See app/proguard-rules.pro.

To enable Proguard, edit android/app/build.gradle:

/**
* Run Proguard to shrink the Java bytecode in release builds.
*/
def enableProguardInReleaseBuilds = true

Migrating old Android React Native apps to use App Signing by Google Play

If you are migrating from previous version of React Native chances are your app does not use App Signing by Google Play feature. We recommend you enable that in order to take advantage from things like automatic app splitting. In order to migrate from the old way of signing you need to start by generating new upload key and then replacing release signing config in android/app/build.gradle to use the upload key instead of the release one (see section about adding signing config to gradle). Once that's done you should follow the instructions from Google Play Help website in order to send your original release key to Google Play.

Default Permissions

By default, INTERNET permission is added to your Android app as pretty much all apps use it. SYSTEM_ALERT_WINDOW permission is added to your Android APK in debug mode but it will be removed in production.

Edit this page
Last updated on
- + diff --git a/docs/next/signed-apk-android/index.html b/docs/next/signed-apk-android/index.html index 01777fddd19..b7454c9c270 100644 --- a/docs/next/signed-apk-android/index.html +++ b/docs/next/signed-apk-android/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Publishing to Google Play Store

Android requires that all apps be digitally signed with a certificate before they can be installed. In order to distribute your Android application via Google Play store it needs to be signed with a release key that then needs to be used for all future updates. Since 2017 it is possible for Google Play to manage signing releases automatically thanks to App Signing by Google Play functionality. However, before your application binary is uploaded to Google Play it needs to be signed with an upload key. The Signing Your Applications page on Android Developers documentation describes the topic in detail. This guide covers the process in brief, as well as lists the steps required to package the JavaScript bundle.

Generating an upload key

You can generate a private signing key using keytool. On Windows keytool must be run from C:\Program Files\Java\jdkx.x.x_x\bin.

keytool -genkeypair -v -storetype PKCS12 -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

This command prompts you for passwords for the keystore and key and for the Distinguished Name fields for your key. It then generates the keystore as a file called my-upload-key.keystore.

The keystore contains a single key, valid for 10000 days. The alias is a name that you will use later when signing your app, so remember to take note of the alias.

On Mac, if you're not sure where your JDK bin folder is, then perform the following command to find it:

/usr/libexec/java_home

It will output the directory of the JDK, which will look something like this:

/Library/Java/JavaVirtualMachines/jdkX.X.X_XXX.jdk/Contents/Home

Navigate to that directory by using the command cd /your/jdk/path and use the keytool command with sudo permission as shown below.

sudo keytool -genkey -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

Note: Remember to keep the keystore file private. In case you've lost upload key or it's been compromised you should follow these instructions.

Setting up Gradle variables

  1. Place the my-upload-key.keystore file under the android/app directory in your project folder.
  2. Edit the file ~/.gradle/gradle.properties or android/gradle.properties, and add the following (replace ***** with the correct keystore password, alias and key password),
MYAPP_UPLOAD_STORE_FILE=my-upload-key.keystore
MYAPP_UPLOAD_KEY_ALIAS=my-key-alias
MYAPP_UPLOAD_STORE_PASSWORD=*****
MYAPP_UPLOAD_KEY_PASSWORD=*****

These are going to be global Gradle variables, which we can later use in our Gradle config to sign our app.

Note about security: If you are not keen on storing your passwords in plaintext, and you are running macOS, you can also store your credentials in the Keychain Access app. Then you can skip the two last rows in ~/.gradle/gradle.properties.

Adding signing config to your app's Gradle config

The last configuration step that needs to be done is to setup release builds to be signed using upload key. Edit the file android/app/build.gradle in your project folder, and add the signing config,

...
android {
...
defaultConfig { ... }
signingConfigs {
release {
if (project.hasProperty('MYAPP_UPLOAD_STORE_FILE')) {
storeFile file(MYAPP_UPLOAD_STORE_FILE)
storePassword MYAPP_UPLOAD_STORE_PASSWORD
keyAlias MYAPP_UPLOAD_KEY_ALIAS
keyPassword MYAPP_UPLOAD_KEY_PASSWORD
}
}
}
buildTypes {
release {
...
signingConfig signingConfigs.release
}
}
}
...

Generating the release AAB

Run the following in a terminal:

cd android
./gradlew bundleRelease

Gradle's bundleRelease will bundle all the JavaScript needed to run your app into the AAB (Android App Bundle). If you need to change the way the JavaScript bundle and/or drawable resources are bundled (e.g. if you changed the default file/folder names or the general structure of the project), have a look at android/app/build.gradle to see how you can update it to reflect these changes.

Note: Make sure gradle.properties does not include org.gradle.configureondemand=true as that will make the release build skip bundling JS and assets into the app binary.

The generated AAB can be found under android/app/build/outputs/bundle/release/app.aab, and is ready to be uploaded to Google Play.

In order for Google Play to accept AAB format the App Signing by Google Play needs to be configured for your application on the Google Play Console. If you are updating an existing app that doesn't use App Signing by Google Play, please check our migration section to learn how to perform that configuration change.

Testing the release build of your app

Before uploading the release build to the Play Store, make sure you test it thoroughly. First uninstall any previous version of the app you already have installed. Install it on the device using the following command in the project root:

npx react-native run-android --variant=release

Note that --variant release is only available if you've set up signing as described above.

You can terminate any running bundler instances, since all your framework and JavaScript code is bundled in the APK's assets.

Publishing to other stores

By default, the generated APK has the native code for both x86 and ARMv7a CPU architectures. This makes it easier to share APKs that run on almost all Android devices. However, this has the downside that there will be some unused native code on any device, leading to unnecessarily bigger APKs.

You can create an APK for each CPU by changing the following line in android/app/build.gradle:

- ndk {
- abiFilters "armeabi-v7a", "x86"
- }
- def enableSeparateBuildPerCPUArchitecture = false
+ def enableSeparateBuildPerCPUArchitecture = true

Upload both these files to markets which support device targeting, such as Google Play and Amazon AppStore, and the users will automatically get the appropriate APK. If you want to upload to other markets, such as APKFiles, which do not support multiple APKs for a single app, change the following line as well to create the default universal APK with binaries for both CPUs.

- universalApk false // If true, also generate a universal APK
+ universalApk true // If true, also generate a universal APK

Enabling Proguard to reduce the size of the APK (optional)

Proguard is a tool that can slightly reduce the size of the APK. It does this by stripping parts of the React Native Java bytecode (and its dependencies) that your app is not using.

IMPORTANT: Make sure to thoroughly test your app if you've enabled Proguard. Proguard often requires configuration specific to each native library you're using. See app/proguard-rules.pro.

To enable Proguard, edit android/app/build.gradle:

/**
* Run Proguard to shrink the Java bytecode in release builds.
*/
def enableProguardInReleaseBuilds = true

Migrating old Android React Native apps to use App Signing by Google Play

If you are migrating from previous version of React Native chances are your app does not use App Signing by Google Play feature. We recommend you enable that in order to take advantage from things like automatic app splitting. In order to migrate from the old way of signing you need to start by generating new upload key and then replacing release signing config in android/app/build.gradle to use the upload key instead of the release one (see section about adding signing config to gradle). Once that's done you should follow the instructions from Google Play Help website in order to send your original release key to Google Play.

Default Permissions

By default, INTERNET permission is added to your Android app as pretty much all apps use it. SYSTEM_ALERT_WINDOW permission is added to your Android APK in debug mode but it will be removed in production.

Edit this page
Last updated on
- + diff --git a/docs/next/slider.html b/docs/next/slider.html index a8359ddb75b..46cd09316b1 100644 --- a/docs/next/slider.html +++ b/docs/next/slider.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 Slider

Deprecated. Use one of the community packages instead.

A component used to select a single value from a range of values.

Reference

Props

Inherits View Props.

style

Used to style and layout the Slider. See StyleSheet.js and ViewStylePropTypes.js for more info.

TypeRequired
View.styleNo

disabled

If true the user won't be able to move the slider. Default value is false.

TypeRequired
boolNo

maximumValue

Initial maximum value of the slider. Default value is 1.

TypeRequired
numberNo

minimumTrackTintColor

The color used for the track to the left of the button. Overrides the default blue gradient image on iOS.

TypeRequired
colorNo

minimumValue

Initial minimum value of the slider. Default value is 0.

TypeRequired
numberNo

onSlidingComplete

Callback that is called when the user releases the slider, regardless if the value has changed. The current value is passed as an argument to the callback handler.

TypeRequired
functionNo

onValueChange

Callback continuously called while the user is dragging the slider.

TypeRequired
functionNo

step

Step value of the slider. The value should be between 0 and (maximumValue - minimumValue). Default value is 0.

TypeRequired
numberNo

maximumTrackTintColor

The color used for the track to the right of the button. Overrides the default gray gradient image on iOS.

TypeRequired
colorNo

testID

Used to locate this view in UI automation tests.

TypeRequired
stringNo

value

Initial value of the slider. The value should be between minimumValue and maximumValue, which default to 0 and 1 respectively. Default value is 0.

This is not a controlled component, you don't need to update the value during dragging.

TypeRequired
numberNo

thumbTintColor

The color used to tint the default thumb images on iOS, or the color of the foreground switch grip on Android.

TypeRequired
colorNo

maximumTrackImage

Assigns a maximum track image. Only static images are supported. The leftmost pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

minimumTrackImage

Assigns a minimum track image. Only static images are supported. The rightmost pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

thumbImage

Sets an image for the thumb. Only static images are supported.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

trackImage

Assigns a single image for the track. Only static images are supported. The center pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS
Edit this page
Last updated on
- + diff --git a/docs/next/slider/index.html b/docs/next/slider/index.html index a8359ddb75b..46cd09316b1 100644 --- a/docs/next/slider/index.html +++ b/docs/next/slider/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 Slider

Deprecated. Use one of the community packages instead.

A component used to select a single value from a range of values.

Reference

Props

Inherits View Props.

style

Used to style and layout the Slider. See StyleSheet.js and ViewStylePropTypes.js for more info.

TypeRequired
View.styleNo

disabled

If true the user won't be able to move the slider. Default value is false.

TypeRequired
boolNo

maximumValue

Initial maximum value of the slider. Default value is 1.

TypeRequired
numberNo

minimumTrackTintColor

The color used for the track to the left of the button. Overrides the default blue gradient image on iOS.

TypeRequired
colorNo

minimumValue

Initial minimum value of the slider. Default value is 0.

TypeRequired
numberNo

onSlidingComplete

Callback that is called when the user releases the slider, regardless if the value has changed. The current value is passed as an argument to the callback handler.

TypeRequired
functionNo

onValueChange

Callback continuously called while the user is dragging the slider.

TypeRequired
functionNo

step

Step value of the slider. The value should be between 0 and (maximumValue - minimumValue). Default value is 0.

TypeRequired
numberNo

maximumTrackTintColor

The color used for the track to the right of the button. Overrides the default gray gradient image on iOS.

TypeRequired
colorNo

testID

Used to locate this view in UI automation tests.

TypeRequired
stringNo

value

Initial value of the slider. The value should be between minimumValue and maximumValue, which default to 0 and 1 respectively. Default value is 0.

This is not a controlled component, you don't need to update the value during dragging.

TypeRequired
numberNo

thumbTintColor

The color used to tint the default thumb images on iOS, or the color of the foreground switch grip on Android.

TypeRequired
colorNo

maximumTrackImage

Assigns a maximum track image. Only static images are supported. The leftmost pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

minimumTrackImage

Assigns a minimum track image. Only static images are supported. The rightmost pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

thumbImage

Sets an image for the thumb. Only static images are supported.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

trackImage

Assigns a single image for the track. Only static images are supported. The center pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS
Edit this page
Last updated on
- + diff --git a/docs/next/state.html b/docs/next/state.html index 0f526fea472..41bb607bbb0 100644 --- a/docs/next/state.html +++ b/docs/next/state.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

State

There are two types of data that control a component: props and state. props are set by the parent and they are fixed throughout the lifetime of a component. For data that is going to change, we have to use state.

In general, you should initialize state in the constructor, and then call setState when you want to change it.

For example, let's say we want to make text that blinks all the time. The text itself gets set once when the blinking component gets created, so the text itself is a prop. The "whether the text is currently on or off" changes over time, so that should be kept in state.

In a real application, you probably won't be setting state with a timer. You might set state when you have new data from the server, or from user input. You can also use a state container like Redux or Mobx to control your data flow. In that case you would use Redux or Mobx to modify your state rather than calling setState directly.

When setState is called, BlinkApp will re-render its Component. By calling setState within the Timer, the component will re-render every time the Timer ticks.

State works the same way as it does in React, so for more details on handling state, you can look at the React.Component API. At this point, you may have noticed that most of our examples use the default text color. To customize the text color, you will have to learn about Style.

Edit this page
Last updated on
- + diff --git a/docs/next/state/index.html b/docs/next/state/index.html index 0f526fea472..41bb607bbb0 100644 --- a/docs/next/state/index.html +++ b/docs/next/state/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

State

There are two types of data that control a component: props and state. props are set by the parent and they are fixed throughout the lifetime of a component. For data that is going to change, we have to use state.

In general, you should initialize state in the constructor, and then call setState when you want to change it.

For example, let's say we want to make text that blinks all the time. The text itself gets set once when the blinking component gets created, so the text itself is a prop. The "whether the text is currently on or off" changes over time, so that should be kept in state.

In a real application, you probably won't be setting state with a timer. You might set state when you have new data from the server, or from user input. You can also use a state container like Redux or Mobx to control your data flow. In that case you would use Redux or Mobx to modify your state rather than calling setState directly.

When setState is called, BlinkApp will re-render its Component. By calling setState within the Timer, the component will re-render every time the Timer ticks.

State works the same way as it does in React, so for more details on handling state, you can look at the React.Component API. At this point, you may have noticed that most of our examples use the default text color. To customize the text color, you will have to learn about Style.

Edit this page
Last updated on
- + diff --git a/docs/next/statusbar.html b/docs/next/statusbar.html index 1ed16be8ce7..ab1621ad532 100644 --- a/docs/next/statusbar.html +++ b/docs/next/statusbar.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

StatusBar

Component to control the app status bar.

Usage with Navigator

It is possible to have multiple StatusBar components mounted at the same time. The props will be merged in the order the StatusBar components were mounted.

Imperative API

For cases where using a component is not ideal, there is also an imperative API exposed as static functions on the component. It is however not recommended to use the static API and the component for the same prop because any value set by the static API will get overridden by the one set by the component in the next render.

Reference

Constants

currentHeight
Android

The height of the status bar, which includes the notch height, if present.

Props

animated

If the transition between status bar property changes should be animated. Supported for backgroundColor, barStyle and hidden properties.

TypeRequiredDefault
booleanNofalse

backgroundColor
Android

The background color of the status bar.

TypeRequiredDefault
colorNodefault system StatusBar background color, or 'black' if not defined

barStyle

Sets the color of the status bar text.

On Android, this will only have an impact on API versions 23 and above.

TypeRequiredDefault
StatusBarStyleNo'default'

hidden

If the status bar is hidden.

TypeRequiredDefault
booleanNofalse

networkActivityIndicatorVisible
iOS

If the network activity indicator should be visible.

TypeDefault
booleanfalse

showHideTransition
iOS

The transition effect when showing and hiding the status bar using the hidden prop.

TypeDefault
StatusBarAnimation'fade'

translucent
Android

If the status bar is translucent. When translucent is set to true, the app will draw under the status bar. This is useful when using a semi transparent status bar color.

TypeDefault
booleanfalse

Methods

popStackEntry()

static popStackEntry(entry: any)

Get and remove the last StatusBar entry from the stack.

Parameters:

NameTypeDescription
entry
Required
anyEntry returned from pushStackEntry.

pushStackEntry()

static pushStackEntry(props: any)

Push a StatusBar entry onto the stack. The return value should be passed to popStackEntry when complete.

Parameters:

NameTypeDescription
props
Required
anyObject containing the StatusBar props to use in the stack entry.

replaceStackEntry()

static replaceStackEntry(entry: any, props: any)

Replace an existing StatusBar stack entry with new props.

Parameters:

NameTypeDescription
entry
Required
anyEntry returned from pushStackEntry to replace.
props
Required
anyObject containing the StatusBar props to use in the replacement stack entry.

setBackgroundColor()
Android

static setBackgroundColor(color: string, [animated]: boolean)

Set the background color for the status bar.

Parameters:

NameTypeDescription
color
Required
stringBackground color.
animatedbooleanAnimate the style change.

setBarStyle()

static setBarStyle(style: StatusBarStyle, [animated]: boolean)

Set the status bar style.

Parameters:

NameTypeDescription
style
Required
StatusBarStyleStatus bar style to set.
animatedbooleanAnimate the style change.

setHidden()

static setHidden(hidden: boolean, [animation]: StatusBarAnimation)

Show or hide the status bar.

Parameters:

NameTypeDescription
hidden
Required
booleanHide the status bar.
animation
iOS
StatusBarAnimationAnimation when changing the status bar hidden property.

setNetworkActivityIndicatorVisible()
iOS

static setNetworkActivityIndicatorVisible(visible: boolean)

Control the visibility of the network activity indicator.

Parameters:

NameTypeDescription
visible
Required
booleanShow the indicator.

setTranslucent()
Android

static setTranslucent(translucent: boolean)

Control the translucency of the status bar.

Parameters:

NameTypeDescription
translucent
Required
booleanSet as translucent.

Type Definitions

StatusBarAnimation

Status bar animation type for transitions on the iOS.

Type
enum

Constants:

ValueTypeDescription
'fade'stringFade animation
'slide'stringSlide animation
'none'stringNo animation

StatusBarStyle

Status bar style type.

Type
enum

Constants:

ValueTypeDescription
'default'stringDefault status bar style (dark for iOS, light for Android)
'light-content'stringDark background, white texts and icons
'dark-content'stringLight background, dark texts and icons (requires API>=23 on Android)
Edit this page
Last updated on
- + diff --git a/docs/next/statusbar/index.html b/docs/next/statusbar/index.html index 1ed16be8ce7..ab1621ad532 100644 --- a/docs/next/statusbar/index.html +++ b/docs/next/statusbar/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

StatusBar

Component to control the app status bar.

Usage with Navigator

It is possible to have multiple StatusBar components mounted at the same time. The props will be merged in the order the StatusBar components were mounted.

Imperative API

For cases where using a component is not ideal, there is also an imperative API exposed as static functions on the component. It is however not recommended to use the static API and the component for the same prop because any value set by the static API will get overridden by the one set by the component in the next render.

Reference

Constants

currentHeight
Android

The height of the status bar, which includes the notch height, if present.

Props

animated

If the transition between status bar property changes should be animated. Supported for backgroundColor, barStyle and hidden properties.

TypeRequiredDefault
booleanNofalse

backgroundColor
Android

The background color of the status bar.

TypeRequiredDefault
colorNodefault system StatusBar background color, or 'black' if not defined

barStyle

Sets the color of the status bar text.

On Android, this will only have an impact on API versions 23 and above.

TypeRequiredDefault
StatusBarStyleNo'default'

hidden

If the status bar is hidden.

TypeRequiredDefault
booleanNofalse

networkActivityIndicatorVisible
iOS

If the network activity indicator should be visible.

TypeDefault
booleanfalse

showHideTransition
iOS

The transition effect when showing and hiding the status bar using the hidden prop.

TypeDefault
StatusBarAnimation'fade'

translucent
Android

If the status bar is translucent. When translucent is set to true, the app will draw under the status bar. This is useful when using a semi transparent status bar color.

TypeDefault
booleanfalse

Methods

popStackEntry()

static popStackEntry(entry: any)

Get and remove the last StatusBar entry from the stack.

Parameters:

NameTypeDescription
entry
Required
anyEntry returned from pushStackEntry.

pushStackEntry()

static pushStackEntry(props: any)

Push a StatusBar entry onto the stack. The return value should be passed to popStackEntry when complete.

Parameters:

NameTypeDescription
props
Required
anyObject containing the StatusBar props to use in the stack entry.

replaceStackEntry()

static replaceStackEntry(entry: any, props: any)

Replace an existing StatusBar stack entry with new props.

Parameters:

NameTypeDescription
entry
Required
anyEntry returned from pushStackEntry to replace.
props
Required
anyObject containing the StatusBar props to use in the replacement stack entry.

setBackgroundColor()
Android

static setBackgroundColor(color: string, [animated]: boolean)

Set the background color for the status bar.

Parameters:

NameTypeDescription
color
Required
stringBackground color.
animatedbooleanAnimate the style change.

setBarStyle()

static setBarStyle(style: StatusBarStyle, [animated]: boolean)

Set the status bar style.

Parameters:

NameTypeDescription
style
Required
StatusBarStyleStatus bar style to set.
animatedbooleanAnimate the style change.

setHidden()

static setHidden(hidden: boolean, [animation]: StatusBarAnimation)

Show or hide the status bar.

Parameters:

NameTypeDescription
hidden
Required
booleanHide the status bar.
animation
iOS
StatusBarAnimationAnimation when changing the status bar hidden property.

setNetworkActivityIndicatorVisible()
iOS

static setNetworkActivityIndicatorVisible(visible: boolean)

Control the visibility of the network activity indicator.

Parameters:

NameTypeDescription
visible
Required
booleanShow the indicator.

setTranslucent()
Android

static setTranslucent(translucent: boolean)

Control the translucency of the status bar.

Parameters:

NameTypeDescription
translucent
Required
booleanSet as translucent.

Type Definitions

StatusBarAnimation

Status bar animation type for transitions on the iOS.

Type
enum

Constants:

ValueTypeDescription
'fade'stringFade animation
'slide'stringSlide animation
'none'stringNo animation

StatusBarStyle

Status bar style type.

Type
enum

Constants:

ValueTypeDescription
'default'stringDefault status bar style (dark for iOS, light for Android)
'light-content'stringDark background, white texts and icons
'dark-content'stringLight background, dark texts and icons (requires API>=23 on Android)
Edit this page
Last updated on
- + diff --git a/docs/next/statusbarios.html b/docs/next/statusbarios.html index 2fb8b98a4ca..6ba6da08885 100644 --- a/docs/next/statusbarios.html +++ b/docs/next/statusbarios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 StatusBarIOS

Deprecated. Use StatusBar for mutating the status bar.

Edit this page
Last updated on
- + diff --git a/docs/next/statusbarios/index.html b/docs/next/statusbarios/index.html index 2fb8b98a4ca..6ba6da08885 100644 --- a/docs/next/statusbarios/index.html +++ b/docs/next/statusbarios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 StatusBarIOS

Deprecated. Use StatusBar for mutating the status bar.

Edit this page
Last updated on
- + diff --git a/docs/next/style.html b/docs/next/style.html index 1c619d67606..b4f1a70eb16 100644 --- a/docs/next/style.html +++ b/docs/next/style.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Style

With React Native, you style your application using JavaScript. All of the core components accept a prop named style. The style names and values usually match how CSS works on the web, except names are written using camel casing, e.g. backgroundColor rather than background-color.

The style prop can be a plain old JavaScript object. That's what we usually use for example code. You can also pass an array of styles - the last style in the array has precedence, so you can use this to inherit styles.

As a component grows in complexity, it is often cleaner to use StyleSheet.create to define several styles in one place. Here's an example:

One common pattern is to make your component accept a style prop which in turn is used to style subcomponents. You can use this to make styles "cascade" the way they do in CSS.

There are a lot more ways to customize the text style. Check out the Text component reference for a complete list.

Now you can make your text beautiful. The next step in becoming a style expert is to learn how to control component size.

Edit this page
Last updated on
- + diff --git a/docs/next/style/index.html b/docs/next/style/index.html index 1c619d67606..b4f1a70eb16 100644 --- a/docs/next/style/index.html +++ b/docs/next/style/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Style

With React Native, you style your application using JavaScript. All of the core components accept a prop named style. The style names and values usually match how CSS works on the web, except names are written using camel casing, e.g. backgroundColor rather than background-color.

The style prop can be a plain old JavaScript object. That's what we usually use for example code. You can also pass an array of styles - the last style in the array has precedence, so you can use this to inherit styles.

As a component grows in complexity, it is often cleaner to use StyleSheet.create to define several styles in one place. Here's an example:

One common pattern is to make your component accept a style prop which in turn is used to style subcomponents. You can use this to make styles "cascade" the way they do in CSS.

There are a lot more ways to customize the text style. Check out the Text component reference for a complete list.

Now you can make your text beautiful. The next step in becoming a style expert is to learn how to control component size.

Edit this page
Last updated on
- + diff --git a/docs/next/stylesheet.html b/docs/next/stylesheet.html index 2b01e72c18f..4b2c9bd383c 100644 --- a/docs/next/stylesheet.html +++ b/docs/next/stylesheet.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

StyleSheet

A StyleSheet is an abstraction similar to CSS StyleSheets

Code quality tips:

  • By moving styles away from the render function, you're making the code easier to understand.
  • Naming the styles is a good way to add meaning to the low level components in the render function.

Reference

Methods

compose()

static compose(style1: object, style2: object): object | array<object>

Combines two styles such that style2 will override any styles in style1. If either style is falsy, the other one is returned without allocating an array, saving allocations and maintaining reference equality for PureComponent checks.

create()

static create(obj: object): object

Creates a StyleSheet style reference from the given object.

flatten()

static flatten(style: array<object>): object

Flattens an array of style objects, into one aggregated style object. Alternatively, this method can be used to lookup IDs, returned by StyleSheet.register.

NOTE: Exercise caution as abusing this can tax you in terms of optimizations. IDs enable optimizations through the bridge and memory in general. Referring to style objects directly will deprive you of these optimizations.

This method internally uses StyleSheetRegistry.getStyleByID(style) to resolve style objects represented by IDs. Thus, an array of style objects (instances of StyleSheet.create()), are individually resolved to, their respective objects, merged as one and then returned. This also explains the alternative use.

setStyleAttributePreprocessor()

WARNING: EXPERIMENTAL. Breaking changes will probably happen a lot and will not be reliably announced. The whole thing might be deleted, who knows? Use at your own risk.

static setStyleAttributePreprocessor(property: string, process: (propValue: any) => any)

Sets a function to use to pre-process a style property value. This is used internally to process color and transform values. You should not use this unless you really know what you are doing and have exhausted other options.

Properties

absoluteFill

A very common pattern is to create overlays with position absolute and zero positioning (position: 'absolute', left: 0, right: 0, top: 0, bottom: 0), so absoluteFill can be used for convenience and to reduce duplication of these repeated styles. If you want, absoluteFill can be used to create a customized entry in a StyleSheet, e.g.:

absoluteFillObject

Sometimes you may want absoluteFill but with a couple tweaks - absoluteFillObject can be used to create a customized entry in a StyleSheet, e.g.:

hairlineWidth

This is defined as the width of a thin line on the platform. It can be used as the thickness of a border or division between two elements. Example:

This constant will always be a round number of pixels (so a line defined by it can look crisp) and will try to match the standard width of a thin line on the underlying platform. However, you should not rely on it being a constant size, because on different platforms and screen densities its value may be calculated differently.

A line with hairline width may not be visible if your simulator is downscaled.

absoluteFill vs. absoluteFillObject

Currently, there is no difference between using absoluteFill vs. absoluteFillObject.

Edit this page
Last updated on
- + diff --git a/docs/next/stylesheet/index.html b/docs/next/stylesheet/index.html index 2b01e72c18f..4b2c9bd383c 100644 --- a/docs/next/stylesheet/index.html +++ b/docs/next/stylesheet/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

StyleSheet

A StyleSheet is an abstraction similar to CSS StyleSheets

Code quality tips:

  • By moving styles away from the render function, you're making the code easier to understand.
  • Naming the styles is a good way to add meaning to the low level components in the render function.

Reference

Methods

compose()

static compose(style1: object, style2: object): object | array<object>

Combines two styles such that style2 will override any styles in style1. If either style is falsy, the other one is returned without allocating an array, saving allocations and maintaining reference equality for PureComponent checks.

create()

static create(obj: object): object

Creates a StyleSheet style reference from the given object.

flatten()

static flatten(style: array<object>): object

Flattens an array of style objects, into one aggregated style object. Alternatively, this method can be used to lookup IDs, returned by StyleSheet.register.

NOTE: Exercise caution as abusing this can tax you in terms of optimizations. IDs enable optimizations through the bridge and memory in general. Referring to style objects directly will deprive you of these optimizations.

This method internally uses StyleSheetRegistry.getStyleByID(style) to resolve style objects represented by IDs. Thus, an array of style objects (instances of StyleSheet.create()), are individually resolved to, their respective objects, merged as one and then returned. This also explains the alternative use.

setStyleAttributePreprocessor()

WARNING: EXPERIMENTAL. Breaking changes will probably happen a lot and will not be reliably announced. The whole thing might be deleted, who knows? Use at your own risk.

static setStyleAttributePreprocessor(property: string, process: (propValue: any) => any)

Sets a function to use to pre-process a style property value. This is used internally to process color and transform values. You should not use this unless you really know what you are doing and have exhausted other options.

Properties

absoluteFill

A very common pattern is to create overlays with position absolute and zero positioning (position: 'absolute', left: 0, right: 0, top: 0, bottom: 0), so absoluteFill can be used for convenience and to reduce duplication of these repeated styles. If you want, absoluteFill can be used to create a customized entry in a StyleSheet, e.g.:

absoluteFillObject

Sometimes you may want absoluteFill but with a couple tweaks - absoluteFillObject can be used to create a customized entry in a StyleSheet, e.g.:

hairlineWidth

This is defined as the width of a thin line on the platform. It can be used as the thickness of a border or division between two elements. Example:

This constant will always be a round number of pixels (so a line defined by it can look crisp) and will try to match the standard width of a thin line on the underlying platform. However, you should not rely on it being a constant size, because on different platforms and screen densities its value may be calculated differently.

A line with hairline width may not be visible if your simulator is downscaled.

absoluteFill vs. absoluteFillObject

Currently, there is no difference between using absoluteFill vs. absoluteFillObject.

Edit this page
Last updated on
- + diff --git a/docs/next/switch.html b/docs/next/switch.html index 20462c48ae8..96a4ae18595 100644 --- a/docs/next/switch.html +++ b/docs/next/switch.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Switch

Renders a boolean input.

This is a controlled component that requires an onValueChange callback that updates the value prop in order for the component to reflect user actions. If the value prop is not updated, the component will continue to render the supplied value prop instead of the expected result of any user actions.

Example

Reference

Props

View Props

Inherits View Props.

disabled

If true the user won't be able to toggle the switch.

TypeDefault
boolfalse

ios_backgroundColor
iOS

On iOS, custom color for the background. This background color can be seen either when the switch value is false or when the switch is disabled (and the switch is translucent).

Type
color

onChange

Invoked when the user tries to change the value of the switch. Receives the change event as an argument. If you want to only receive the new value, use onValueChange instead.

Type
function

onValueChange

Invoked when the user tries to change the value of the switch. Receives the new value as an argument. If you want to instead receive an event, use onChange.

Type
function

thumbColor

Color of the foreground switch grip. If this is set on iOS, the switch grip will lose its drop shadow.

Type
color

trackColor

Custom colors for the switch track.

iOS: When the switch value is false, the track shrinks into the border. If you want to change the color of the background exposed by the shrunken track, use ios_backgroundColor.

Type
object: { false: color, true: color }

value

The value of the switch. If true the switch will be turned on. Default value is false.

Type
bool
Edit this page
Last updated on
- + diff --git a/docs/next/switch/index.html b/docs/next/switch/index.html index 20462c48ae8..96a4ae18595 100644 --- a/docs/next/switch/index.html +++ b/docs/next/switch/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Switch

Renders a boolean input.

This is a controlled component that requires an onValueChange callback that updates the value prop in order for the component to reflect user actions. If the value prop is not updated, the component will continue to render the supplied value prop instead of the expected result of any user actions.

Example

Reference

Props

View Props

Inherits View Props.

disabled

If true the user won't be able to toggle the switch.

TypeDefault
boolfalse

ios_backgroundColor
iOS

On iOS, custom color for the background. This background color can be seen either when the switch value is false or when the switch is disabled (and the switch is translucent).

Type
color

onChange

Invoked when the user tries to change the value of the switch. Receives the change event as an argument. If you want to only receive the new value, use onValueChange instead.

Type
function

onValueChange

Invoked when the user tries to change the value of the switch. Receives the new value as an argument. If you want to instead receive an event, use onChange.

Type
function

thumbColor

Color of the foreground switch grip. If this is set on iOS, the switch grip will lose its drop shadow.

Type
color

trackColor

Custom colors for the switch track.

iOS: When the switch value is false, the track shrinks into the border. If you want to change the color of the background exposed by the shrunken track, use ios_backgroundColor.

Type
object: { false: color, true: color }

value

The value of the switch. If true the switch will be turned on. Default value is false.

Type
bool
Edit this page
Last updated on
- + diff --git a/docs/next/symbolication.html b/docs/next/symbolication.html index e793a922826..f798bca3db9 100644 --- a/docs/next/symbolication.html +++ b/docs/next/symbolication.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Symbolicating a stack trace

If a React Native app throws an unhandled exception in a release build, the output may be obfuscated and hard to read:

07-15 10:58:25.820 18979 18998 E AndroidRuntime: FATAL EXCEPTION: mqt_native_modules
07-15 10:58:25.820 18979 18998 E AndroidRuntime: Process: com.awesomeproject, PID: 18979 07-15 10:58:25.820 18979 18998 E AndroidRuntime: com.facebook.react.common.JavascriptException: Failed, js engine: hermes, stack:
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132161
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132084
07-15 10:58:25.820 18979 18998 E AndroidRuntime: f@1:131854
07-15 10:58:25.820 18979 18998 E AndroidRuntime: anonymous@1:131119

The sections like p@1:132161 are minified function names and bytecode offsets. To debug the problem, you would instead want to translate it into file, line and function name: AwesomeProject/App.js:54:initializeMap. This is known as symbolication. You can symbolicate minified function names and bytecode like the above by passing metro-symbolicate a generated source map and the stack trace.

The metro-symbolicate package is installed by default in the React Native template project from setting up your development environment.

From a file containing the stacktrace:

npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map < stacktrace.txt

From adb logcatdirectly:

adb logcat -d | npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map

This will turn each minified function name and offset like p@1:132161 into the actual file- and function name AwesomeProject/App.js:54:initializeMap.

Notes on Sourcemaps

  • Multiple source maps may be generated by the build process. Make sure to used the one in the location shown in the examples.
  • Make sure that the source map you use corresponds to the exact commit of the crashing app. Small changes in source code can cause large differences in offsets.
  • If metro-symbolicate exits immediately with success, make sure the input comes from a pipe or redirection and not from a terminal.
Edit this page
Last updated on
- + diff --git a/docs/next/symbolication/index.html b/docs/next/symbolication/index.html index e793a922826..f798bca3db9 100644 --- a/docs/next/symbolication/index.html +++ b/docs/next/symbolication/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Symbolicating a stack trace

If a React Native app throws an unhandled exception in a release build, the output may be obfuscated and hard to read:

07-15 10:58:25.820 18979 18998 E AndroidRuntime: FATAL EXCEPTION: mqt_native_modules
07-15 10:58:25.820 18979 18998 E AndroidRuntime: Process: com.awesomeproject, PID: 18979 07-15 10:58:25.820 18979 18998 E AndroidRuntime: com.facebook.react.common.JavascriptException: Failed, js engine: hermes, stack:
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132161
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132084
07-15 10:58:25.820 18979 18998 E AndroidRuntime: f@1:131854
07-15 10:58:25.820 18979 18998 E AndroidRuntime: anonymous@1:131119

The sections like p@1:132161 are minified function names and bytecode offsets. To debug the problem, you would instead want to translate it into file, line and function name: AwesomeProject/App.js:54:initializeMap. This is known as symbolication. You can symbolicate minified function names and bytecode like the above by passing metro-symbolicate a generated source map and the stack trace.

The metro-symbolicate package is installed by default in the React Native template project from setting up your development environment.

From a file containing the stacktrace:

npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map < stacktrace.txt

From adb logcatdirectly:

adb logcat -d | npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map

This will turn each minified function name and offset like p@1:132161 into the actual file- and function name AwesomeProject/App.js:54:initializeMap.

Notes on Sourcemaps

  • Multiple source maps may be generated by the build process. Make sure to used the one in the location shown in the examples.
  • Make sure that the source map you use corresponds to the exact commit of the crashing app. Small changes in source code can cause large differences in offsets.
  • If metro-symbolicate exits immediately with success, make sure the input comes from a pipe or redirection and not from a terminal.
Edit this page
Last updated on
- + diff --git a/docs/next/systrace.html b/docs/next/systrace.html index 920ce41e18e..c0bb77fcf82 100644 --- a/docs/next/systrace.html +++ b/docs/next/systrace.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Systrace

Systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.

Example

Systrace allows you to mark JavaScript (JS) events with a tag and an integer value. Capture the non-Timed JS events in EasyProfiler.

Reference

Methods

installReactHook()

static installReactHook(useFiber)

setEnabled()

static setEnabled(enabled)

isEnabled()

static isEnabled()

beginEvent()

static beginEvent(profileName?, args?)

beginEvent/endEvent for starting and then ending a profile within the same call stack frame.

endEvent()

static endEvent()

beginAsyncEvent()

static beginAsyncEvent(profileName?)

beginAsyncEvent/endAsyncEvent for starting and then ending a profile where the end can either occur on another thread or out of the current stack frame, eg await the returned cookie variable should be used as input into the endAsyncEvent call to end the profile.

endAsyncEvent()

static endAsyncEvent(profileName?, cookie?)

counterEvent()

static counterEvent(profileName?, value?)

Register the value to the profileName on the systrace timeline.

Edit this page
Last updated on
- + diff --git a/docs/next/systrace/index.html b/docs/next/systrace/index.html index 920ce41e18e..c0bb77fcf82 100644 --- a/docs/next/systrace/index.html +++ b/docs/next/systrace/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Systrace

Systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.

Example

Systrace allows you to mark JavaScript (JS) events with a tag and an integer value. Capture the non-Timed JS events in EasyProfiler.

Reference

Methods

installReactHook()

static installReactHook(useFiber)

setEnabled()

static setEnabled(enabled)

isEnabled()

static isEnabled()

beginEvent()

static beginEvent(profileName?, args?)

beginEvent/endEvent for starting and then ending a profile within the same call stack frame.

endEvent()

static endEvent()

beginAsyncEvent()

static beginAsyncEvent(profileName?)

beginAsyncEvent/endAsyncEvent for starting and then ending a profile where the end can either occur on another thread or out of the current stack frame, eg await the returned cookie variable should be used as input into the endAsyncEvent call to end the profile.

endAsyncEvent()

static endAsyncEvent(profileName?, cookie?)

counterEvent()

static counterEvent(profileName?, value?)

Register the value to the profileName on the systrace timeline.

Edit this page
Last updated on
- + diff --git a/docs/next/testing-overview.html b/docs/next/testing-overview.html index 774770de641..259c4aa2b97 100644 --- a/docs/next/testing-overview.html +++ b/docs/next/testing-overview.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
const bananaElements = getAllByText('banana');
expect(bananaElements).toHaveLength(1); // expect 'banana' to be on the list
});

This example is not testing how some state changes when you call a function. It tests what happens when a user changes text in the TextInput and presses the Button!

Testing Rendered Output

Snapshot testing is an advanced kind of testing enabled by Jest. It is a very powerful and low-level tool, so extra attention is advised when using it.

A "component snapshot" is a JSX-like string created by a custom React serializer built into Jest. This serializer lets Jest translate React component trees to string that's human-readable. Put another way: a component snapshot is a textual representation of your component’s render output generated during a test run. It may look like this:

<Text
style={
Object {
"fontSize": 20,
"textAlign": "center",
}
}>
Welcome to React Native!
</Text>

With snapshot testing, you typically first implement your component and then run the snapshot test. The snapshot test then creates a snapshot and saves it to a file in your repo as a reference snapshot. The file is then committed and checked during code review. Any future changes to the component render output will change its snapshot, which will cause the test to fail. You then need to update the stored reference snapshot for the test to pass. That change again needs to be committed and reviewed.

Snapshots have several weak points:

Snapshots themselves do not ensure that your component render logic is correct, they are merely good at guarding against unexpected changes and for checking that the components in the React tree under test receive the expected props (styles and etc.).

We recommend that you only use small snapshots (see no-large-snapshots rule). If you want to test a change between two React component states, use snapshot-diff. When in doubt, prefer explicit expectations as described in the previous paragraph.

End-to-End Tests

In end-to-end (E2E) tests, you verify your app is working as expected on a device (or a simulator / emulator) from the user perspective.

This is done by building your app in the release configuration and running the tests against it. In E2E tests, you no longer think about React components, React Native APIs, Redux stores or any business logic. That is not the purpose of E2E tests and those are not even accessible to you during E2E testing.

Instead, E2E testing libraries allow you to find and control elements in the screen of your app: for example, you can actually tap buttons or insert text into TextInputs the same way a real user would. Then you can make assertions about whether or not a certain element exists in the app’s screen, whether or not it’s visible, what text it contains, and so on.

E2E tests give you the highest possible confidence that part of your app is working. The tradeoffs include:

Try to cover the vital parts of your app with E2E tests: authentication flow, core functionalities, payments, etc. Use faster JS tests for the non-vital parts of your app. The more tests you add, the higher your confidence, but also, the more time you'll spend maintaining and running them. Consider the tradeoffs and decide what's best for you.

There are several E2E testing tools available: in the React Native community, Detox is a popular framework because it’s tailored for React Native apps. Another popular library in the space of iOS and Android apps is Appium.

Summary

We hope you enjoyed reading and learned something from this guide. There are many ways you can test your apps. It may be hard to decide what to use at first. However, we believe it all will make sense once you start adding tests to your awesome React Native app. So what are you waiting for? Get your coverage up!

Links

This guide originally authored and contributed in full by Vojtech Novak.

Edit this page
Last updated on
- + diff --git a/docs/next/testing-overview/index.html b/docs/next/testing-overview/index.html index 774770de641..259c4aa2b97 100644 --- a/docs/next/testing-overview/index.html +++ b/docs/next/testing-overview/index.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
const bananaElements = getAllByText('banana');
expect(bananaElements).toHaveLength(1); // expect 'banana' to be on the list
});

This example is not testing how some state changes when you call a function. It tests what happens when a user changes text in the TextInput and presses the Button!

Testing Rendered Output

Snapshot testing is an advanced kind of testing enabled by Jest. It is a very powerful and low-level tool, so extra attention is advised when using it.

A "component snapshot" is a JSX-like string created by a custom React serializer built into Jest. This serializer lets Jest translate React component trees to string that's human-readable. Put another way: a component snapshot is a textual representation of your component’s render output generated during a test run. It may look like this:

<Text
style={
Object {
"fontSize": 20,
"textAlign": "center",
}
}>
Welcome to React Native!
</Text>

With snapshot testing, you typically first implement your component and then run the snapshot test. The snapshot test then creates a snapshot and saves it to a file in your repo as a reference snapshot. The file is then committed and checked during code review. Any future changes to the component render output will change its snapshot, which will cause the test to fail. You then need to update the stored reference snapshot for the test to pass. That change again needs to be committed and reviewed.

Snapshots have several weak points:

Snapshots themselves do not ensure that your component render logic is correct, they are merely good at guarding against unexpected changes and for checking that the components in the React tree under test receive the expected props (styles and etc.).

We recommend that you only use small snapshots (see no-large-snapshots rule). If you want to test a change between two React component states, use snapshot-diff. When in doubt, prefer explicit expectations as described in the previous paragraph.

End-to-End Tests

In end-to-end (E2E) tests, you verify your app is working as expected on a device (or a simulator / emulator) from the user perspective.

This is done by building your app in the release configuration and running the tests against it. In E2E tests, you no longer think about React components, React Native APIs, Redux stores or any business logic. That is not the purpose of E2E tests and those are not even accessible to you during E2E testing.

Instead, E2E testing libraries allow you to find and control elements in the screen of your app: for example, you can actually tap buttons or insert text into TextInputs the same way a real user would. Then you can make assertions about whether or not a certain element exists in the app’s screen, whether or not it’s visible, what text it contains, and so on.

E2E tests give you the highest possible confidence that part of your app is working. The tradeoffs include:

Try to cover the vital parts of your app with E2E tests: authentication flow, core functionalities, payments, etc. Use faster JS tests for the non-vital parts of your app. The more tests you add, the higher your confidence, but also, the more time you'll spend maintaining and running them. Consider the tradeoffs and decide what's best for you.

There are several E2E testing tools available: in the React Native community, Detox is a popular framework because it’s tailored for React Native apps. Another popular library in the space of iOS and Android apps is Appium.

Summary

We hope you enjoyed reading and learned something from this guide. There are many ways you can test your apps. It may be hard to decide what to use at first. However, we believe it all will make sense once you start adding tests to your awesome React Native app. So what are you waiting for? Get your coverage up!

Links

This guide originally authored and contributed in full by Vojtech Novak.

Edit this page
Last updated on
- + diff --git a/docs/next/text-style-props.html b/docs/next/text-style-props.html index 47a7b271e2d..2a9b2cba699 100644 --- a/docs/next/text-style-props.html +++ b/docs/next/text-style-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Text Style Props

Example

Reference

Props

color

Type
color

fontFamily

Type
string

fontSize

Type
number

fontStyle

Type
enum('normal', 'italic')

fontWeight

Specifies font weight. The values 'normal' and 'bold' are supported for most fonts. Not all fonts have a variant for each of the numeric values, in that case the closest one is chosen.

TypeDefault
enum('normal', 'bold', '100', '200', '300', '400', '500', '600', '700', '800', '900')'normal'

includeFontPadding
Android

Set to false to remove extra font padding intended to make space for certain ascenders / descenders. With some fonts, this padding can make text look slightly misaligned when centered vertically. For best results also set textAlignVertical to center.

TypeDefault
booltrue

fontVariant

TypeDefault
array of enum('small-caps', 'oldstyle-nums', 'lining-nums', 'tabular-nums', 'proportional-nums')[]

letterSpacing

Increase or decrease the spacing between characters. By default there is no extra letter spacing.

Type
number

lineHeight

Type
number

textAlign

Specifies text alignment. On Android, the value 'justify' is only supported on Oreo (8.0) or above (API level >= 26). The value will fallback to left on lower Android versions.

TypeDefault
enum('auto', 'left', 'right', 'center', 'justify')'auto'

textAlignVertical
Android

TypeDefault
enum('auto', 'top', 'bottom', 'center')'auto'

textDecorationColor
iOS

Type
color

textDecorationLine

TypeDefault
enum('none', 'underline', 'line-through', 'underline line-through')'none'

textDecorationStyle
iOS

TypeDefault
enum('solid', 'double', 'dotted', 'dashed')'solid'

textShadowColor

Type
color

textShadowOffset

Type
object: { width?: number, height?: number }

textShadowRadius

Type
number

textTransform

TypeDefault
enum('none', 'uppercase', 'lowercase', 'capitalize')'none'

writingDirection
iOS

TypeDefault
enum('auto', 'ltr', 'rtl')'auto'
Edit this page
Last updated on
- + diff --git a/docs/next/text-style-props/index.html b/docs/next/text-style-props/index.html index 47a7b271e2d..2a9b2cba699 100644 --- a/docs/next/text-style-props/index.html +++ b/docs/next/text-style-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Text Style Props

Example

Reference

Props

color

Type
color

fontFamily

Type
string

fontSize

Type
number

fontStyle

Type
enum('normal', 'italic')

fontWeight

Specifies font weight. The values 'normal' and 'bold' are supported for most fonts. Not all fonts have a variant for each of the numeric values, in that case the closest one is chosen.

TypeDefault
enum('normal', 'bold', '100', '200', '300', '400', '500', '600', '700', '800', '900')'normal'

includeFontPadding
Android

Set to false to remove extra font padding intended to make space for certain ascenders / descenders. With some fonts, this padding can make text look slightly misaligned when centered vertically. For best results also set textAlignVertical to center.

TypeDefault
booltrue

fontVariant

TypeDefault
array of enum('small-caps', 'oldstyle-nums', 'lining-nums', 'tabular-nums', 'proportional-nums')[]

letterSpacing

Increase or decrease the spacing between characters. By default there is no extra letter spacing.

Type
number

lineHeight

Type
number

textAlign

Specifies text alignment. On Android, the value 'justify' is only supported on Oreo (8.0) or above (API level >= 26). The value will fallback to left on lower Android versions.

TypeDefault
enum('auto', 'left', 'right', 'center', 'justify')'auto'

textAlignVertical
Android

TypeDefault
enum('auto', 'top', 'bottom', 'center')'auto'

textDecorationColor
iOS

Type
color

textDecorationLine

TypeDefault
enum('none', 'underline', 'line-through', 'underline line-through')'none'

textDecorationStyle
iOS

TypeDefault
enum('solid', 'double', 'dotted', 'dashed')'solid'

textShadowColor

Type
color

textShadowOffset

Type
object: { width?: number, height?: number }

textShadowRadius

Type
number

textTransform

TypeDefault
enum('none', 'uppercase', 'lowercase', 'capitalize')'none'

writingDirection
iOS

TypeDefault
enum('auto', 'ltr', 'rtl')'auto'
Edit this page
Last updated on
- + diff --git a/docs/next/text.html b/docs/next/text.html index d54ffec36b9..ce315522365 100644 --- a/docs/next/text.html +++ b/docs/next/text.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
// GOOD
<View>
<Text>
Some text
</Text>
</View>

You also lose the ability to set up a default font for an entire subtree. Meanwhile, fontFamily only accepts a single font name, which is different from font-family in CSS. The recommended way to use consistent fonts and sizes across your application is to create a component MyAppText that includes them and use this component across your app. You can also use this component to make more specific components like MyAppHeaderText for other kinds of text.

<View>
<MyAppText>
Text styled with the default font for the entire application
</MyAppText>
<MyAppHeaderText>Text styled as a header</MyAppHeaderText>
</View>

Assuming that MyAppText is a component that only renders out its children into a Text component with styling, then MyAppHeaderText can be defined as follows:

class MyAppHeaderText extends Component {
render() {
return (
<MyAppText>
<Text style={{ fontSize: 20 }}>
{this.props.children}
</Text>
</MyAppText>
);
}
}

Composing MyAppText in this way ensures that we get the styles from a top-level component, but leaves us the ability to add / override them in specific use cases.

React Native still has the concept of style inheritance, but limited to text subtrees. In this case, the second part will be both bold and red.

<Text style={{ fontWeight: 'bold' }}>
I am bold
<Text style={{ color: 'red' }}>and red</Text>
</Text>

We believe that this more constrained way to style text will yield better apps:

Reference

Props

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

Type
string

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

Type
string

accessibilityRole

Tells the screen reader to treat the currently focused on element as having a specific role.

On iOS, these roles map to corresponding Accessibility Traits. Image button has the same functionality as if the trait was set to both 'image' and 'button'. See the Accessibility guide for more information.

On Android, these roles have similar functionality on TalkBack as adding Accessibility Traits does on Voiceover in iOS

Type
AccessibilityRole

accessibilityState

Tells the screen reader to treat the currently focused on element as being in a specific state.

You can provide one state, no state, or multiple states. The states must be passed in through an object. Ex: {selected: true, disabled: true}.

Type
AccessibilityState

accessible

When set to true, indicates that the view is an accessibility element.

See the Accessibility guide for more information.

TypeDefault
booleantrue

adjustsFontSizeToFit

Specifies whether fonts should be scaled down automatically to fit given style constraints.

TypeDefault
booleanfalse

allowFontScaling

Specifies whether fonts should scale to respect Text Size accessibility settings.

TypeDefault
booleantrue

android_hyphenationFrequency
Android

Sets the frequency of automatic hyphenation to use when determining word breaks on Android API Level 23+.

TypeDefault
enum('none', 'full', 'balanced', 'high')'none'

dataDetectorType
Android

Determines the types of data converted to clickable URLs in the text element. By default no data types are detected.

You can provide only one type.

TypeDefault
enum('phoneNumber', 'link', 'email', 'none', 'all')'none'

disabled
Android

Specifies the disabled state of the text view for testing purposes.

TypeDefault
boolfalse

ellipsizeMode

When numberOfLines is set, this prop defines how text will be truncated. numberOfLines must be set in conjunction with this prop.

This can be one of the following values:

TypeDefault
enum('head', 'middle', 'tail', 'clip')tail

maxFontSizeMultiplier

Specifies largest possible scale a font can reach when allowFontScaling is enabled. Possible values:

TypeDefault
numberundefined

minimumFontScale
iOS

Specifies smallest possible scale a font can reach when adjustsFontSizeToFit is enabled. (values 0.01-1.0).

Type
number

nativeID

Used to locate this view from native code.

Type
string

numberOfLines

Used to truncate the text with an ellipsis after computing the text layout, including line wrapping, such that the total number of lines does not exceed this number. Setting this property to 0 will result in unsetiing this value, which means that no lines restriction will be applied.

This prop is commonly used with ellipsizeMode.

TypeDefault
number0

onLayout

Invoked on mount and on layout changes.

Type
(LayoutEvent) => void

onLongPress

This function is called on long press.

Type
(PressEvent) => void

onMoveShouldSetResponder

Does this view want to "claim" touch responsiveness? This is called for every touch move on the View when it is not the responder.

Type
(PressEvent) => boolean

onPress

This function is called on press.

Type
(PressEvent) => void

onResponderGrant

The View is now responding for touch events. This is the time to highlight and show the user what is happening.

Type
(PressEvent) => void

onResponderMove

The user is moving their finger.

Type
(PressEvent) => void

onResponderRelease

Fired at the end of the touch.

Type
(PressEvent) => void

onResponderTerminate

The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS)

Type
(PressEvent) => void

onResponderTerminationRequest

Some other View wants to become responder and is asking this View to release its responder. Returning true allows its release.

Type
(PressEvent) => boolean

onStartShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a touch start, it should have this handler which returns true.

Type
(PressEvent) => boolean

onTextLayout

Invoked on Text layout change.

Type
(TextLayoutEvent) => mixed

pressRetentionOffset

When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations.

Type
Rect, number

selectable

Lets the user select text, to use the native copy and paste functionality.

TypeDefault
booleanfalse

selectionColor
Android

The highlight color of the text.

Type
color

style

Type
Text Style, View Style Props

suppressHighlighting
iOS

When true, no visual change is made when text is pressed down. By default, a gray oval highlights the text on press down.

TypeDefault
booleanfalse

testID

Used to locate this view in end-to-end tests.

Type
string

textBreakStrategy
Android

Set text break strategy on Android API Level 23+, possible values are simple, highQuality, balanced.

TypeDefault
enum('simple', 'highQuality', 'balanced')highQuality

Type Definitions

TextLayout

TextLayout object is a part of TextLayoutEvent callback and contains the measurement data for Text line.

Example

{
capHeight: 10.496,
ascender: 14.624,
descender: 4,
width: 28.224,
height: 18.624,
xHeight: 6.048,
x: 0,
y: 0
}

Properties

NameTypeOptionalDescription
ascendernumberNoThe line ascender height after the text layout changes.
capHeightnumberNoHeight of capital letter above the baseline.
descendernumberNoThe line descender height after the text layout changes.
heightnumberNoHeight of the line after the text layout changes.
widthnumberNoWidth of the line after the text layout changes.
xnumberNoLine X coordinate inside the Text component.
xHeightnumberNoDistance between the baseline and median of the line (corpus size).
ynumberNoLine Y coordinate inside the Text component.

TextLayoutEvent

TextLayoutEvent object is returned in the callback as a result of component layout change. It contains a key called lines with a value which is an array containing TextLayout object corresponeded to every rendered text line.

Example

{
lines: [
TextLayout,
TextLayout
// ...
];
target: 1127;
}

Properties

NameTypeOptionalDescription
linesarray of TextLayoutsNoProvides the TextLayout data for every rendered line.
targetnumberNoThe node id of the element.

Known issues

Edit this page
Last updated on
- + diff --git a/docs/next/text/index.html b/docs/next/text/index.html index d54ffec36b9..ce315522365 100644 --- a/docs/next/text/index.html +++ b/docs/next/text/index.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
// GOOD
<View>
<Text>
Some text
</Text>
</View>

You also lose the ability to set up a default font for an entire subtree. Meanwhile, fontFamily only accepts a single font name, which is different from font-family in CSS. The recommended way to use consistent fonts and sizes across your application is to create a component MyAppText that includes them and use this component across your app. You can also use this component to make more specific components like MyAppHeaderText for other kinds of text.

<View>
<MyAppText>
Text styled with the default font for the entire application
</MyAppText>
<MyAppHeaderText>Text styled as a header</MyAppHeaderText>
</View>

Assuming that MyAppText is a component that only renders out its children into a Text component with styling, then MyAppHeaderText can be defined as follows:

class MyAppHeaderText extends Component {
render() {
return (
<MyAppText>
<Text style={{ fontSize: 20 }}>
{this.props.children}
</Text>
</MyAppText>
);
}
}

Composing MyAppText in this way ensures that we get the styles from a top-level component, but leaves us the ability to add / override them in specific use cases.

React Native still has the concept of style inheritance, but limited to text subtrees. In this case, the second part will be both bold and red.

<Text style={{ fontWeight: 'bold' }}>
I am bold
<Text style={{ color: 'red' }}>and red</Text>
</Text>

We believe that this more constrained way to style text will yield better apps:

Reference

Props

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

Type
string

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

Type
string

accessibilityRole

Tells the screen reader to treat the currently focused on element as having a specific role.

On iOS, these roles map to corresponding Accessibility Traits. Image button has the same functionality as if the trait was set to both 'image' and 'button'. See the Accessibility guide for more information.

On Android, these roles have similar functionality on TalkBack as adding Accessibility Traits does on Voiceover in iOS

Type
AccessibilityRole

accessibilityState

Tells the screen reader to treat the currently focused on element as being in a specific state.

You can provide one state, no state, or multiple states. The states must be passed in through an object. Ex: {selected: true, disabled: true}.

Type
AccessibilityState

accessible

When set to true, indicates that the view is an accessibility element.

See the Accessibility guide for more information.

TypeDefault
booleantrue

adjustsFontSizeToFit

Specifies whether fonts should be scaled down automatically to fit given style constraints.

TypeDefault
booleanfalse

allowFontScaling

Specifies whether fonts should scale to respect Text Size accessibility settings.

TypeDefault
booleantrue

android_hyphenationFrequency
Android

Sets the frequency of automatic hyphenation to use when determining word breaks on Android API Level 23+.

TypeDefault
enum('none', 'full', 'balanced', 'high')'none'

dataDetectorType
Android

Determines the types of data converted to clickable URLs in the text element. By default no data types are detected.

You can provide only one type.

TypeDefault
enum('phoneNumber', 'link', 'email', 'none', 'all')'none'

disabled
Android

Specifies the disabled state of the text view for testing purposes.

TypeDefault
boolfalse

ellipsizeMode

When numberOfLines is set, this prop defines how text will be truncated. numberOfLines must be set in conjunction with this prop.

This can be one of the following values:

TypeDefault
enum('head', 'middle', 'tail', 'clip')tail

maxFontSizeMultiplier

Specifies largest possible scale a font can reach when allowFontScaling is enabled. Possible values:

TypeDefault
numberundefined

minimumFontScale
iOS

Specifies smallest possible scale a font can reach when adjustsFontSizeToFit is enabled. (values 0.01-1.0).

Type
number

nativeID

Used to locate this view from native code.

Type
string

numberOfLines

Used to truncate the text with an ellipsis after computing the text layout, including line wrapping, such that the total number of lines does not exceed this number. Setting this property to 0 will result in unsetiing this value, which means that no lines restriction will be applied.

This prop is commonly used with ellipsizeMode.

TypeDefault
number0

onLayout

Invoked on mount and on layout changes.

Type
(LayoutEvent) => void

onLongPress

This function is called on long press.

Type
(PressEvent) => void

onMoveShouldSetResponder

Does this view want to "claim" touch responsiveness? This is called for every touch move on the View when it is not the responder.

Type
(PressEvent) => boolean

onPress

This function is called on press.

Type
(PressEvent) => void

onResponderGrant

The View is now responding for touch events. This is the time to highlight and show the user what is happening.

Type
(PressEvent) => void

onResponderMove

The user is moving their finger.

Type
(PressEvent) => void

onResponderRelease

Fired at the end of the touch.

Type
(PressEvent) => void

onResponderTerminate

The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS)

Type
(PressEvent) => void

onResponderTerminationRequest

Some other View wants to become responder and is asking this View to release its responder. Returning true allows its release.

Type
(PressEvent) => boolean

onStartShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a touch start, it should have this handler which returns true.

Type
(PressEvent) => boolean

onTextLayout

Invoked on Text layout change.

Type
(TextLayoutEvent) => mixed

pressRetentionOffset

When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations.

Type
Rect, number

selectable

Lets the user select text, to use the native copy and paste functionality.

TypeDefault
booleanfalse

selectionColor
Android

The highlight color of the text.

Type
color

style

Type
Text Style, View Style Props

suppressHighlighting
iOS

When true, no visual change is made when text is pressed down. By default, a gray oval highlights the text on press down.

TypeDefault
booleanfalse

testID

Used to locate this view in end-to-end tests.

Type
string

textBreakStrategy
Android

Set text break strategy on Android API Level 23+, possible values are simple, highQuality, balanced.

TypeDefault
enum('simple', 'highQuality', 'balanced')highQuality

Type Definitions

TextLayout

TextLayout object is a part of TextLayoutEvent callback and contains the measurement data for Text line.

Example

{
capHeight: 10.496,
ascender: 14.624,
descender: 4,
width: 28.224,
height: 18.624,
xHeight: 6.048,
x: 0,
y: 0
}

Properties

NameTypeOptionalDescription
ascendernumberNoThe line ascender height after the text layout changes.
capHeightnumberNoHeight of capital letter above the baseline.
descendernumberNoThe line descender height after the text layout changes.
heightnumberNoHeight of the line after the text layout changes.
widthnumberNoWidth of the line after the text layout changes.
xnumberNoLine X coordinate inside the Text component.
xHeightnumberNoDistance between the baseline and median of the line (corpus size).
ynumberNoLine Y coordinate inside the Text component.

TextLayoutEvent

TextLayoutEvent object is returned in the callback as a result of component layout change. It contains a key called lines with a value which is an array containing TextLayout object corresponeded to every rendered text line.

Example

{
lines: [
TextLayout,
TextLayout
// ...
];
target: 1127;
}

Properties

NameTypeOptionalDescription
linesarray of TextLayoutsNoProvides the TextLayout data for every rendered line.
targetnumberNoThe node id of the element.

Known issues

Edit this page
Last updated on
- + diff --git a/docs/next/textinput.html b/docs/next/textinput.html index 16c94a061fa..158cfad4289 100644 --- a/docs/next/textinput.html +++ b/docs/next/textinput.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

TextInput

A foundational component for inputting text into the app via a keyboard. Props provide configurability for several features, such as auto-correction, auto-capitalization, placeholder text, and different keyboard types, such as a numeric keypad.

The most basic use case is to plop down a TextInput and subscribe to the onChangeText events to read the user input. There are also other events, such as onSubmitEditing and onFocus that can be subscribed to. A minimal example:

Two methods exposed via the native element are .focus() and .blur() that will focus or blur the TextInput programmatically.

Note that some props are only available with multiline={true/false}. Additionally, border styles that apply to only one side of the element (e.g., borderBottomColor, borderLeftWidth, etc.) will not be applied if multiline=true. To achieve the same effect, you can wrap your TextInput in a View:

TextInput has by default a border at the bottom of its view. This border has its padding set by the background image provided by the system, and it cannot be changed. Solutions to avoid this are to either not set height explicitly, in which case the system will take care of displaying the border in the correct position, or to not display the border by setting underlineColorAndroid to transparent.

Note that on Android performing text selection in an input can change the app's activity windowSoftInputMode param to adjustResize. This may cause issues with components that have position: 'absolute' while the keyboard is active. To avoid this behavior either specify windowSoftInputMode in AndroidManifest.xml ( https://developer.android.com/guide/topics/manifest/activity-element.html ) or control this param programmatically with native code.

Reference

Props

View Props

Inherits View Props.

allowFontScaling

Specifies whether fonts should scale to respect Text Size accessibility settings. The default is true.

TypeRequired
boolNo

autoCapitalize

Tells TextInput to automatically capitalize certain characters. This property is not supported by some keyboard types such as name-phone-pad.

  • characters: all characters.
  • words: first letter of each word.
  • sentences: first letter of each sentence (default).
  • none: don't auto capitalize anything.
TypeRequired
enum('none', 'sentences', 'words', 'characters')No

autoCompleteType

Specifies autocomplete hints for the system, so it can provide autofill. On Android, the system will always attempt to offer autofill by using heuristics to identify the type of content. To disable autocomplete, set autoCompleteType to off.

Possible values for autoCompleteType are:

  • off
  • username
  • password
  • email
  • name
  • tel
  • street-address
  • postal-code
  • cc-number
  • cc-csc
  • cc-exp
  • cc-exp-month
  • cc-exp-year
TypeRequiredPlatform
enum('off', 'username', 'password', 'email', 'name', 'tel', 'street-address', 'postal-code', 'cc-number', 'cc-csc', 'cc-exp', 'cc-exp-month', 'cc-exp-year')NoAndroid

autoCorrect

If false, disables auto-correct. The default value is true.

TypeRequired
boolNo

autoFocus

If true, focuses the input on componentDidMount. The default value is false.

TypeRequired
boolNo

blurOnSubmit

If true, the text field will blur when submitted. The default value is true for single-line fields and false for multiline fields. Note that for multiline fields, setting blurOnSubmit to true means that pressing return will blur the field and trigger the onSubmitEditing event instead of inserting a newline into the field.

TypeRequired
boolNo

caretHidden

If true, caret is hidden. The default value is false.

TypeRequired
boolNo

clearButtonMode

When the clear button should appear on the right side of the text view. This property is supported only for single-line TextInput component. The default value is never.

TypeRequiredPlatform
enum('never', 'while-editing', 'unless-editing', 'always')NoiOS

clearTextOnFocus

If true, clears the text field automatically when editing begins.

TypeRequiredPlatform
boolNoiOS

contextMenuHidden

If true, context menu is hidden. The default value is false.

TypeRequired
boolNo

dataDetectorTypes

Determines the types of data converted to clickable URLs in the text input. Only valid if multiline={true} and editable={false}. By default no data types are detected.

You can provide one type or an array of many types.

Possible values for dataDetectorTypes are:

  • 'phoneNumber'
  • 'link'
  • 'address'
  • 'calendarEvent'
  • 'none'
  • 'all'
TypeRequiredPlatform
enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all'), ,array of enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all')NoiOS

defaultValue

Provides an initial value that will change when the user starts typing. Useful for use-cases where you do not want to deal with listening to events and updating the value prop to keep the controlled state in sync.

TypeRequired
stringNo

disableFullscreenUI

When false, if there is a small amount of space available around a text input (e.g. landscape orientation on a phone), the OS may choose to have the user edit the text inside of a full screen text input mode. When true, this feature is disabled and users will always edit the text directly inside of the text input. Defaults to false.

TypeRequiredPlatform
boolNoAndroid

editable

If false, text is not editable. The default value is true.

TypeRequired
boolNo

enablesReturnKeyAutomatically

If true, the keyboard disables the return key when there is no text and automatically enables it when there is text. The default value is false.

TypeRequiredPlatform
boolNoiOS

importantForAutofill

Tells the operating system whether the individual fields in your app should be included in a view structure for autofill purposes on Android API Level 26+. Possible values are auto, no, noExcludeDescendants, yes, and yesExcludeDescendants. The default value is auto.

  • auto: Let the Android System use its heuristics to determine if the view is important for autofill.
  • no: This view isn't important for autofill.
  • noExcludeDescendants: This view and its children aren't important for autofill.
  • yes: This view is important for autofill.
  • yesExcludeDescendants: This view is important for autofill, but its children aren't important for autofill.
TypeRequiredPlatform
enum('auto', 'no', 'noExcludeDescendants', 'yes', 'yesExcludeDescendants')NoAndroid

inlineImageLeft

If defined, the provided image resource will be rendered on the left. The image resource must be inside /android/app/src/main/res/drawable and referenced like

<TextInput
inlineImageLeft='search_icon'
/>
TypeRequiredPlatform
stringNoAndroid

inlineImagePadding

Padding between the inline image, if any, and the text input itself.

TypeRequiredPlatform
numberNoAndroid

inputAccessoryViewID

An optional identifier which links a custom InputAccessoryView to this text input. The InputAccessoryView is rendered above the keyboard when this text input is focused.

TypeRequiredPlatform
stringNoiOS

keyboardAppearance

Determines the color of the keyboard.

TypeRequiredPlatform
enum('default', 'light', 'dark')NoiOS

keyboardType

Determines which keyboard to open, e.g.numeric.

See screenshots of all the types here.

The following values work across platforms:

  • default
  • number-pad
  • decimal-pad
  • numeric
  • email-address
  • phone-pad

iOS Only

The following values work on iOS only:

  • ascii-capable
  • numbers-and-punctuation
  • url
  • name-phone-pad
  • twitter
  • web-search

Android Only

The following values work on Android only:

  • visible-password
TypeRequired
enum('default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter', 'web-search', 'visible-password')No

maxFontSizeMultiplier

Specifies largest possible scale a font can reach when allowFontScaling is enabled. Possible values:

  • null/undefined (default): inherit from the parent node or the global default (0)
  • 0: no max, ignore parent/global default
  • >= 1: sets the maxFontSizeMultiplier of this node to this value
TypeRequired
numberNo

maxLength

Limits the maximum number of characters that can be entered. Use this instead of implementing the logic in JS to avoid flicker.

TypeRequired
numberNo

multiline

If true, the text input can be multiple lines. The default value is false. It is important to note that this aligns the text to the top on iOS, and centers it on Android. Use with textAlignVertical set to top for the same behavior in both platforms.

TypeRequired
boolNo

numberOfLines

Sets the number of lines for a TextInput. Use it with multiline set to true to be able to fill the lines.

TypeRequiredPlatform
numberNoAndroid

onBlur

Callback that is called when the text input is blurred.

Note: If you are attempting to access the text value from nativeEvent keep in mind that the resulting value you get can be undefined which can cause unintended errors. If you are trying to find the last value of TextInput, you can use the onEndEditing event, which is fired upon completion of editing.

TypeRequired
functionNo

onChange

Callback that is called when the text input's text changes. This will be called with { nativeEvent: { eventCount, target, text} }

TypeRequired
functionNo

onChangeText

Callback that is called when the text input's text changes. Changed text is passed as a single string argument to the callback handler.

TypeRequired
functionNo

onContentSizeChange

Callback that is called when the text input's content size changes. This will be called with { nativeEvent: { contentSize: { width, height } } }.

Only called for multiline text inputs.

TypeRequired
functionNo

onEndEditing

Callback that is called when text input ends.

TypeRequired
functionNo

onPressIn

Callback that is called when a touch is engaged.

TypeRequired
PressEventNo

onPressOut

Callback that is called when a touch is released.

TypeRequired
PressEventNo

onFocus

Callback that is called when the text input is focused. This is called with { nativeEvent: { target } }.

TypeRequired
(LayoutEvent) => voidNo

onKeyPress

Callback that is called when a key is pressed. This will be called with { nativeEvent: { key: keyValue } } where keyValue is 'Enter' or 'Backspace' for respective keys and the typed-in character otherwise including ' ' for space. Fires before onChange callbacks. Note: on Android only the inputs from soft keyboard are handled, not the hardware keyboard inputs.

TypeRequired
functionNo

onLayout

Invoked on mount and on layout changes.

TypeRequired
functionNo

onScroll

Invoked on content scroll with { nativeEvent: { contentOffset: { x, y } } }. May also contain other properties from ScrollEvent but on Android contentSize is not provided for performance reasons.

TypeRequired
functionNo

onSelectionChange

Callback that is called when the text input selection is changed. This will be called with { nativeEvent: { selection: { start, end } } }. This prop requires multiline={true} to be set.

TypeRequired
functionNo

onSubmitEditing

Callback that is called when the text input's submit button is pressed with the argument {nativeEvent: {text, eventCount, target}}.

TypeRequired
functionNo

Note that on iOS this method isn't called when using keyboardType="phone-pad".

placeholder

The string that will be rendered before text input has been entered.

TypeRequired
stringNo

placeholderTextColor

The text color of the placeholder string.

TypeRequired
colorNo

returnKeyLabel

Sets the return key to the label. Use it instead of returnKeyType.

TypeRequiredPlatform
stringNoAndroid

returnKeyType

Determines how the return key should look. On Android you can also use returnKeyLabel.

Cross platform

The following values work across platforms:

  • done
  • go
  • next
  • search
  • send

Android Only

The following values work on Android only:

  • none
  • previous

iOS Only

The following values work on iOS only:

  • default
  • emergency-call
  • google
  • join
  • route
  • yahoo
TypeRequired
enum('done', 'go', 'next', 'search', 'send', 'none', 'previous', 'default', 'emergency-call', 'google', 'join', 'route', 'yahoo')No

rejectResponderTermination

iOS Only

If true, allows TextInput to pass touch events to the parent component. This allows components such as SwipeableListView to be swipeable from the TextInput on iOS, as is the case on Android by default. If false, TextInput always asks to handle the input (except when disabled). The default value is true.

TypeRequiredPlatform
boolNoiOS

scrollEnabled

If false, scrolling of the text view will be disabled. The default value is true. Only works with multiline={true}.

TypeRequiredPlatform
boolNoiOS

secureTextEntry

If true, the text input obscures the text entered so that sensitive text like passwords stay secure. The default value is false. Does not work with multiline={true}.

TypeRequired
boolNo

selection

The start and end of the text input's selection. Set start and end to the same value to position the cursor.

TypeRequired
object: {start: number,end: number}No

selectionColor

The highlight and cursor color of the text input.

TypeRequired
colorNo

selectTextOnFocus

If true, all text will automatically be selected on focus.

TypeRequired
boolNo

showSoftInputOnFocus

When false, it will prevent the soft keyboard from showing when the field is focused. The default value is true.

TypeRequired
boolNo

spellCheck

If false, disables spell-check style (i.e. red underlines). The default value is inherited from autoCorrect.

TypeRequiredPlatform
boolNoiOS

textAlign

Align the input text to the left, center, or right sides of the input field.

Possible values for textAlign are:

  • left
  • center
  • right
TypeRequired
enum('left', 'center', 'right')No

textContentType

Give the keyboard and the system information about the expected semantic meaning for the content that users enter.

For iOS 11+ you can set textContentType to username or password to enable autofill of login details from the device keychain.

For iOS 12+ newPassword can be used to indicate a new password input the user may want to save in the keychain, and oneTimeCode can be used to indicate that a field can be autofilled by a code arriving in an SMS.

To disable autofill, set textContentType to none.

Possible values for textContentType are:

  • none
  • URL
  • addressCity
  • addressCityAndState
  • addressState
  • countryName
  • creditCardNumber
  • emailAddress
  • familyName
  • fullStreetAddress
  • givenName
  • jobTitle
  • location
  • middleName
  • name
  • namePrefix
  • nameSuffix
  • nickname
  • organizationName
  • postalCode
  • streetAddressLine1
  • streetAddressLine2
  • sublocality
  • telephoneNumber
  • username
  • password
  • newPassword
  • oneTimeCode
TypeRequiredPlatform
enum('none', 'URL', 'addressCity', 'addressCityAndState', 'addressState', 'countryName', 'creditCardNumber', 'emailAddress', 'familyName', 'fullStreetAddress', 'givenName', 'jobTitle', 'location', 'middleName', 'name', 'namePrefix', 'nameSuffix', 'nickname', 'organizationName', 'postalCode', 'streetAddressLine1', 'streetAddressLine2', 'sublocality', 'telephoneNumber', 'username', 'password')NoiOS

passwordRules

When using textContentType as newPassword on iOS we can let the OS know the minimum requirements of the password so that it can generate one that will satisfy them. In order to create a valid string for PasswordRules take a look to the Apple Docs.

If passwords generation dialog doesn't appear please make sure that:

  • AutoFill is enabled: Settings → Passwords & Accounts → toggle "On" the AutoFill Passwords,
  • iCloud Keychain is used: Settings → Apple ID → iCloud → Keychain → toggle "On" the iCloud Keychain.
TypeRequiredPlatform
stringNoiOS

style

Note that not all Text styles are supported, an incomplete list of what is not supported includes:

  • borderLeftWidth
  • borderTopWidth
  • borderRightWidth
  • borderBottomWidth
  • borderTopLeftRadius
  • borderTopRightRadius
  • borderBottomRightRadius
  • borderBottomLeftRadius

see Issue#7070 for more detail.

Styles

TypeRequired
TextNo

textBreakStrategy

Set text break strategy on Android API Level 23+, possible values are simple, highQuality, balanced The default value is simple.

TypeRequiredPlatform
enum('simple', 'highQuality', 'balanced')NoAndroid

underlineColorAndroid

The color of the TextInput underline.

TypeRequiredPlatform
colorNoAndroid

value

The value to show for the text input. TextInput is a controlled component, which means the native value will be forced to match this value prop if provided. For most uses, this works great, but in some cases this may cause flickering - one common cause is preventing edits by keeping value the same. In addition to setting the same value, either set editable={false}, or set/update maxLength to prevent unwanted edits without flicker.

TypeRequired
stringNo

Methods

.focus()

focus();

Makes the native input request focus.

.blur()

blur();

Makes the native input lose focus.

clear()

clear();

Removes all text from the TextInput.

isFocused()

isFocused();

Returns true if the input is currently focused; false otherwise.

Known issues

  • react-native#19096: Doesn't support Android's onKeyPreIme.
  • react-native#19366: Calling .focus() after closing Android's keyboard via back button doesn't bring keyboard up again.
  • react-native#26799: Doesn't support Android's secureTextEntry when keyboardType="email-address" or keyboardType="phone-pad".
Edit this page
Last updated on
- + diff --git a/docs/next/textinput/index.html b/docs/next/textinput/index.html index 16c94a061fa..158cfad4289 100644 --- a/docs/next/textinput/index.html +++ b/docs/next/textinput/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

TextInput

A foundational component for inputting text into the app via a keyboard. Props provide configurability for several features, such as auto-correction, auto-capitalization, placeholder text, and different keyboard types, such as a numeric keypad.

The most basic use case is to plop down a TextInput and subscribe to the onChangeText events to read the user input. There are also other events, such as onSubmitEditing and onFocus that can be subscribed to. A minimal example:

Two methods exposed via the native element are .focus() and .blur() that will focus or blur the TextInput programmatically.

Note that some props are only available with multiline={true/false}. Additionally, border styles that apply to only one side of the element (e.g., borderBottomColor, borderLeftWidth, etc.) will not be applied if multiline=true. To achieve the same effect, you can wrap your TextInput in a View:

TextInput has by default a border at the bottom of its view. This border has its padding set by the background image provided by the system, and it cannot be changed. Solutions to avoid this are to either not set height explicitly, in which case the system will take care of displaying the border in the correct position, or to not display the border by setting underlineColorAndroid to transparent.

Note that on Android performing text selection in an input can change the app's activity windowSoftInputMode param to adjustResize. This may cause issues with components that have position: 'absolute' while the keyboard is active. To avoid this behavior either specify windowSoftInputMode in AndroidManifest.xml ( https://developer.android.com/guide/topics/manifest/activity-element.html ) or control this param programmatically with native code.

Reference

Props

View Props

Inherits View Props.

allowFontScaling

Specifies whether fonts should scale to respect Text Size accessibility settings. The default is true.

TypeRequired
boolNo

autoCapitalize

Tells TextInput to automatically capitalize certain characters. This property is not supported by some keyboard types such as name-phone-pad.

  • characters: all characters.
  • words: first letter of each word.
  • sentences: first letter of each sentence (default).
  • none: don't auto capitalize anything.
TypeRequired
enum('none', 'sentences', 'words', 'characters')No

autoCompleteType

Specifies autocomplete hints for the system, so it can provide autofill. On Android, the system will always attempt to offer autofill by using heuristics to identify the type of content. To disable autocomplete, set autoCompleteType to off.

Possible values for autoCompleteType are:

  • off
  • username
  • password
  • email
  • name
  • tel
  • street-address
  • postal-code
  • cc-number
  • cc-csc
  • cc-exp
  • cc-exp-month
  • cc-exp-year
TypeRequiredPlatform
enum('off', 'username', 'password', 'email', 'name', 'tel', 'street-address', 'postal-code', 'cc-number', 'cc-csc', 'cc-exp', 'cc-exp-month', 'cc-exp-year')NoAndroid

autoCorrect

If false, disables auto-correct. The default value is true.

TypeRequired
boolNo

autoFocus

If true, focuses the input on componentDidMount. The default value is false.

TypeRequired
boolNo

blurOnSubmit

If true, the text field will blur when submitted. The default value is true for single-line fields and false for multiline fields. Note that for multiline fields, setting blurOnSubmit to true means that pressing return will blur the field and trigger the onSubmitEditing event instead of inserting a newline into the field.

TypeRequired
boolNo

caretHidden

If true, caret is hidden. The default value is false.

TypeRequired
boolNo

clearButtonMode

When the clear button should appear on the right side of the text view. This property is supported only for single-line TextInput component. The default value is never.

TypeRequiredPlatform
enum('never', 'while-editing', 'unless-editing', 'always')NoiOS

clearTextOnFocus

If true, clears the text field automatically when editing begins.

TypeRequiredPlatform
boolNoiOS

contextMenuHidden

If true, context menu is hidden. The default value is false.

TypeRequired
boolNo

dataDetectorTypes

Determines the types of data converted to clickable URLs in the text input. Only valid if multiline={true} and editable={false}. By default no data types are detected.

You can provide one type or an array of many types.

Possible values for dataDetectorTypes are:

  • 'phoneNumber'
  • 'link'
  • 'address'
  • 'calendarEvent'
  • 'none'
  • 'all'
TypeRequiredPlatform
enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all'), ,array of enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all')NoiOS

defaultValue

Provides an initial value that will change when the user starts typing. Useful for use-cases where you do not want to deal with listening to events and updating the value prop to keep the controlled state in sync.

TypeRequired
stringNo

disableFullscreenUI

When false, if there is a small amount of space available around a text input (e.g. landscape orientation on a phone), the OS may choose to have the user edit the text inside of a full screen text input mode. When true, this feature is disabled and users will always edit the text directly inside of the text input. Defaults to false.

TypeRequiredPlatform
boolNoAndroid

editable

If false, text is not editable. The default value is true.

TypeRequired
boolNo

enablesReturnKeyAutomatically

If true, the keyboard disables the return key when there is no text and automatically enables it when there is text. The default value is false.

TypeRequiredPlatform
boolNoiOS

importantForAutofill

Tells the operating system whether the individual fields in your app should be included in a view structure for autofill purposes on Android API Level 26+. Possible values are auto, no, noExcludeDescendants, yes, and yesExcludeDescendants. The default value is auto.

  • auto: Let the Android System use its heuristics to determine if the view is important for autofill.
  • no: This view isn't important for autofill.
  • noExcludeDescendants: This view and its children aren't important for autofill.
  • yes: This view is important for autofill.
  • yesExcludeDescendants: This view is important for autofill, but its children aren't important for autofill.
TypeRequiredPlatform
enum('auto', 'no', 'noExcludeDescendants', 'yes', 'yesExcludeDescendants')NoAndroid

inlineImageLeft

If defined, the provided image resource will be rendered on the left. The image resource must be inside /android/app/src/main/res/drawable and referenced like

<TextInput
inlineImageLeft='search_icon'
/>
TypeRequiredPlatform
stringNoAndroid

inlineImagePadding

Padding between the inline image, if any, and the text input itself.

TypeRequiredPlatform
numberNoAndroid

inputAccessoryViewID

An optional identifier which links a custom InputAccessoryView to this text input. The InputAccessoryView is rendered above the keyboard when this text input is focused.

TypeRequiredPlatform
stringNoiOS

keyboardAppearance

Determines the color of the keyboard.

TypeRequiredPlatform
enum('default', 'light', 'dark')NoiOS

keyboardType

Determines which keyboard to open, e.g.numeric.

See screenshots of all the types here.

The following values work across platforms:

  • default
  • number-pad
  • decimal-pad
  • numeric
  • email-address
  • phone-pad

iOS Only

The following values work on iOS only:

  • ascii-capable
  • numbers-and-punctuation
  • url
  • name-phone-pad
  • twitter
  • web-search

Android Only

The following values work on Android only:

  • visible-password
TypeRequired
enum('default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter', 'web-search', 'visible-password')No

maxFontSizeMultiplier

Specifies largest possible scale a font can reach when allowFontScaling is enabled. Possible values:

  • null/undefined (default): inherit from the parent node or the global default (0)
  • 0: no max, ignore parent/global default
  • >= 1: sets the maxFontSizeMultiplier of this node to this value
TypeRequired
numberNo

maxLength

Limits the maximum number of characters that can be entered. Use this instead of implementing the logic in JS to avoid flicker.

TypeRequired
numberNo

multiline

If true, the text input can be multiple lines. The default value is false. It is important to note that this aligns the text to the top on iOS, and centers it on Android. Use with textAlignVertical set to top for the same behavior in both platforms.

TypeRequired
boolNo

numberOfLines

Sets the number of lines for a TextInput. Use it with multiline set to true to be able to fill the lines.

TypeRequiredPlatform
numberNoAndroid

onBlur

Callback that is called when the text input is blurred.

Note: If you are attempting to access the text value from nativeEvent keep in mind that the resulting value you get can be undefined which can cause unintended errors. If you are trying to find the last value of TextInput, you can use the onEndEditing event, which is fired upon completion of editing.

TypeRequired
functionNo

onChange

Callback that is called when the text input's text changes. This will be called with { nativeEvent: { eventCount, target, text} }

TypeRequired
functionNo

onChangeText

Callback that is called when the text input's text changes. Changed text is passed as a single string argument to the callback handler.

TypeRequired
functionNo

onContentSizeChange

Callback that is called when the text input's content size changes. This will be called with { nativeEvent: { contentSize: { width, height } } }.

Only called for multiline text inputs.

TypeRequired
functionNo

onEndEditing

Callback that is called when text input ends.

TypeRequired
functionNo

onPressIn

Callback that is called when a touch is engaged.

TypeRequired
PressEventNo

onPressOut

Callback that is called when a touch is released.

TypeRequired
PressEventNo

onFocus

Callback that is called when the text input is focused. This is called with { nativeEvent: { target } }.

TypeRequired
(LayoutEvent) => voidNo

onKeyPress

Callback that is called when a key is pressed. This will be called with { nativeEvent: { key: keyValue } } where keyValue is 'Enter' or 'Backspace' for respective keys and the typed-in character otherwise including ' ' for space. Fires before onChange callbacks. Note: on Android only the inputs from soft keyboard are handled, not the hardware keyboard inputs.

TypeRequired
functionNo

onLayout

Invoked on mount and on layout changes.

TypeRequired
functionNo

onScroll

Invoked on content scroll with { nativeEvent: { contentOffset: { x, y } } }. May also contain other properties from ScrollEvent but on Android contentSize is not provided for performance reasons.

TypeRequired
functionNo

onSelectionChange

Callback that is called when the text input selection is changed. This will be called with { nativeEvent: { selection: { start, end } } }. This prop requires multiline={true} to be set.

TypeRequired
functionNo

onSubmitEditing

Callback that is called when the text input's submit button is pressed with the argument {nativeEvent: {text, eventCount, target}}.

TypeRequired
functionNo

Note that on iOS this method isn't called when using keyboardType="phone-pad".

placeholder

The string that will be rendered before text input has been entered.

TypeRequired
stringNo

placeholderTextColor

The text color of the placeholder string.

TypeRequired
colorNo

returnKeyLabel

Sets the return key to the label. Use it instead of returnKeyType.

TypeRequiredPlatform
stringNoAndroid

returnKeyType

Determines how the return key should look. On Android you can also use returnKeyLabel.

Cross platform

The following values work across platforms:

  • done
  • go
  • next
  • search
  • send

Android Only

The following values work on Android only:

  • none
  • previous

iOS Only

The following values work on iOS only:

  • default
  • emergency-call
  • google
  • join
  • route
  • yahoo
TypeRequired
enum('done', 'go', 'next', 'search', 'send', 'none', 'previous', 'default', 'emergency-call', 'google', 'join', 'route', 'yahoo')No

rejectResponderTermination

iOS Only

If true, allows TextInput to pass touch events to the parent component. This allows components such as SwipeableListView to be swipeable from the TextInput on iOS, as is the case on Android by default. If false, TextInput always asks to handle the input (except when disabled). The default value is true.

TypeRequiredPlatform
boolNoiOS

scrollEnabled

If false, scrolling of the text view will be disabled. The default value is true. Only works with multiline={true}.

TypeRequiredPlatform
boolNoiOS

secureTextEntry

If true, the text input obscures the text entered so that sensitive text like passwords stay secure. The default value is false. Does not work with multiline={true}.

TypeRequired
boolNo

selection

The start and end of the text input's selection. Set start and end to the same value to position the cursor.

TypeRequired
object: {start: number,end: number}No

selectionColor

The highlight and cursor color of the text input.

TypeRequired
colorNo

selectTextOnFocus

If true, all text will automatically be selected on focus.

TypeRequired
boolNo

showSoftInputOnFocus

When false, it will prevent the soft keyboard from showing when the field is focused. The default value is true.

TypeRequired
boolNo

spellCheck

If false, disables spell-check style (i.e. red underlines). The default value is inherited from autoCorrect.

TypeRequiredPlatform
boolNoiOS

textAlign

Align the input text to the left, center, or right sides of the input field.

Possible values for textAlign are:

  • left
  • center
  • right
TypeRequired
enum('left', 'center', 'right')No

textContentType

Give the keyboard and the system information about the expected semantic meaning for the content that users enter.

For iOS 11+ you can set textContentType to username or password to enable autofill of login details from the device keychain.

For iOS 12+ newPassword can be used to indicate a new password input the user may want to save in the keychain, and oneTimeCode can be used to indicate that a field can be autofilled by a code arriving in an SMS.

To disable autofill, set textContentType to none.

Possible values for textContentType are:

  • none
  • URL
  • addressCity
  • addressCityAndState
  • addressState
  • countryName
  • creditCardNumber
  • emailAddress
  • familyName
  • fullStreetAddress
  • givenName
  • jobTitle
  • location
  • middleName
  • name
  • namePrefix
  • nameSuffix
  • nickname
  • organizationName
  • postalCode
  • streetAddressLine1
  • streetAddressLine2
  • sublocality
  • telephoneNumber
  • username
  • password
  • newPassword
  • oneTimeCode
TypeRequiredPlatform
enum('none', 'URL', 'addressCity', 'addressCityAndState', 'addressState', 'countryName', 'creditCardNumber', 'emailAddress', 'familyName', 'fullStreetAddress', 'givenName', 'jobTitle', 'location', 'middleName', 'name', 'namePrefix', 'nameSuffix', 'nickname', 'organizationName', 'postalCode', 'streetAddressLine1', 'streetAddressLine2', 'sublocality', 'telephoneNumber', 'username', 'password')NoiOS

passwordRules

When using textContentType as newPassword on iOS we can let the OS know the minimum requirements of the password so that it can generate one that will satisfy them. In order to create a valid string for PasswordRules take a look to the Apple Docs.

If passwords generation dialog doesn't appear please make sure that:

  • AutoFill is enabled: Settings → Passwords & Accounts → toggle "On" the AutoFill Passwords,
  • iCloud Keychain is used: Settings → Apple ID → iCloud → Keychain → toggle "On" the iCloud Keychain.
TypeRequiredPlatform
stringNoiOS

style

Note that not all Text styles are supported, an incomplete list of what is not supported includes:

  • borderLeftWidth
  • borderTopWidth
  • borderRightWidth
  • borderBottomWidth
  • borderTopLeftRadius
  • borderTopRightRadius
  • borderBottomRightRadius
  • borderBottomLeftRadius

see Issue#7070 for more detail.

Styles

TypeRequired
TextNo

textBreakStrategy

Set text break strategy on Android API Level 23+, possible values are simple, highQuality, balanced The default value is simple.

TypeRequiredPlatform
enum('simple', 'highQuality', 'balanced')NoAndroid

underlineColorAndroid

The color of the TextInput underline.

TypeRequiredPlatform
colorNoAndroid

value

The value to show for the text input. TextInput is a controlled component, which means the native value will be forced to match this value prop if provided. For most uses, this works great, but in some cases this may cause flickering - one common cause is preventing edits by keeping value the same. In addition to setting the same value, either set editable={false}, or set/update maxLength to prevent unwanted edits without flicker.

TypeRequired
stringNo

Methods

.focus()

focus();

Makes the native input request focus.

.blur()

blur();

Makes the native input lose focus.

clear()

clear();

Removes all text from the TextInput.

isFocused()

isFocused();

Returns true if the input is currently focused; false otherwise.

Known issues

  • react-native#19096: Doesn't support Android's onKeyPreIme.
  • react-native#19366: Calling .focus() after closing Android's keyboard via back button doesn't bring keyboard up again.
  • react-native#26799: Doesn't support Android's secureTextEntry when keyboardType="email-address" or keyboardType="phone-pad".
Edit this page
Last updated on
- + diff --git a/docs/next/timepickerandroid.html b/docs/next/timepickerandroid.html index 58e7f245063..b328988dd96 100644 --- a/docs/next/timepickerandroid.html +++ b/docs/next/timepickerandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 TimePickerAndroid

Deprecated. Use one of the community packages instead.

Opens the standard Android time picker dialog.

Example

try {
const { action, hour, minute } = await TimePickerAndroid.open({
hour: 14,
minute: 0,
is24Hour: false // Will display '2 PM'
});
if (action !== TimePickerAndroid.dismissedAction) {
// Selected hour (0-23), minute (0-59)
}
} catch ({ code, message }) {
console.warn('Cannot open time picker', message);
}

Reference

Methods

open()

static open(options)

Opens the standard Android time picker dialog.

The available keys for the options object are:

  • hour (0-23) - the hour to show, defaults to the current time
  • minute (0-59) - the minute to show, defaults to the current time
  • is24Hour (boolean) - If true, the picker uses the 24-hour format. If false, the picker shows an AM/PM chooser. If undefined, the default for the current locale is used.
  • mode (enum('clock', 'spinner', 'default')) - set the time picker mode
    • 'clock': Show a time picker in clock mode.
    • 'spinner': Show a time picker in spinner mode.
    • 'default': Show a default time picker based on Android versions.

Returns a Promise which will be invoked an object containing action, hour (0-23), minute (0-59) if the user picked a time. If the user dismissed the dialog, the Promise will still be resolved with action being TimePickerAndroid.dismissedAction and all the other keys being undefined. Always check whether the action before reading the values.

timeSetAction()

static timeSetAction()

A time has been selected.

dismissedAction()

static dismissedAction()

The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/next/timepickerandroid/index.html b/docs/next/timepickerandroid/index.html index 58e7f245063..b328988dd96 100644 --- a/docs/next/timepickerandroid/index.html +++ b/docs/next/timepickerandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

🚧 TimePickerAndroid

Deprecated. Use one of the community packages instead.

Opens the standard Android time picker dialog.

Example

try {
const { action, hour, minute } = await TimePickerAndroid.open({
hour: 14,
minute: 0,
is24Hour: false // Will display '2 PM'
});
if (action !== TimePickerAndroid.dismissedAction) {
// Selected hour (0-23), minute (0-59)
}
} catch ({ code, message }) {
console.warn('Cannot open time picker', message);
}

Reference

Methods

open()

static open(options)

Opens the standard Android time picker dialog.

The available keys for the options object are:

  • hour (0-23) - the hour to show, defaults to the current time
  • minute (0-59) - the minute to show, defaults to the current time
  • is24Hour (boolean) - If true, the picker uses the 24-hour format. If false, the picker shows an AM/PM chooser. If undefined, the default for the current locale is used.
  • mode (enum('clock', 'spinner', 'default')) - set the time picker mode
    • 'clock': Show a time picker in clock mode.
    • 'spinner': Show a time picker in spinner mode.
    • 'default': Show a default time picker based on Android versions.

Returns a Promise which will be invoked an object containing action, hour (0-23), minute (0-59) if the user picked a time. If the user dismissed the dialog, the Promise will still be resolved with action being TimePickerAndroid.dismissedAction and all the other keys being undefined. Always check whether the action before reading the values.

timeSetAction()

static timeSetAction()

A time has been selected.

dismissedAction()

static dismissedAction()

The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/next/timers.html b/docs/next/timers.html index 9f0551d5b21..0801fa8e798 100644 --- a/docs/next/timers.html +++ b/docs/next/timers.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Timers

Timers are an important part of an application and React Native implements the browser timers.

Timers

  • setTimeout, clearTimeout
  • setInterval, clearInterval
  • setImmediate, clearImmediate
  • requestAnimationFrame, cancelAnimationFrame

requestAnimationFrame(fn) is not the same as setTimeout(fn, 0) - the former will fire after all the frames have flushed, whereas the latter will fire as quickly as possible (over 1000x per second on a iPhone 5S).

setImmediate is executed at the end of the current JavaScript execution block, right before sending the batched response back to native. Note that if you call setImmediate within a setImmediate callback, it will be executed right away, it won't yield back to native in between.

The Promise implementation uses setImmediate as its asynchronicity implementation.

Note: when debugging on Android, if the times between the debugger and device have drifted; things such as animation, event behavior, etc., might not work properly or the results may not be accurate. Please correct this by running adb shell "date `date +%m%d%H%M%Y.%S%3N`" on your debugger machine. Root access is required for the use in real device.

InteractionManager

One reason why well-built native apps feel so smooth is by avoiding expensive operations during interactions and animations. In React Native, we currently have a limitation that there is only a single JS execution thread, but you can use InteractionManager to make sure long-running work is scheduled to start after any interactions/animations have completed.

Applications can schedule tasks to run after interactions with the following:

InteractionManager.runAfterInteractions(() => {
// ...long-running synchronous task...
});

Compare this to other scheduling alternatives:

  • requestAnimationFrame(): for code that animates a view over time.
  • setImmediate/setTimeout/setInterval(): run code later, note this may delay animations.
  • runAfterInteractions(): run code later, without delaying active animations.

The touch handling system considers one or more active touches to be an 'interaction' and will delay runAfterInteractions() callbacks until all touches have ended or been cancelled.

InteractionManager also allows applications to register animations by creating an interaction 'handle' on animation start, and clearing it upon completion:

var handle = InteractionManager.createInteractionHandle();
// run animation... (`runAfterInteractions` tasks are queued)
// later, on animation completion:
InteractionManager.clearInteractionHandle(handle);
// queued tasks run if all handles were cleared
Edit this page
Last updated on
- + diff --git a/docs/next/timers/index.html b/docs/next/timers/index.html index 9f0551d5b21..0801fa8e798 100644 --- a/docs/next/timers/index.html +++ b/docs/next/timers/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Timers

Timers are an important part of an application and React Native implements the browser timers.

Timers

  • setTimeout, clearTimeout
  • setInterval, clearInterval
  • setImmediate, clearImmediate
  • requestAnimationFrame, cancelAnimationFrame

requestAnimationFrame(fn) is not the same as setTimeout(fn, 0) - the former will fire after all the frames have flushed, whereas the latter will fire as quickly as possible (over 1000x per second on a iPhone 5S).

setImmediate is executed at the end of the current JavaScript execution block, right before sending the batched response back to native. Note that if you call setImmediate within a setImmediate callback, it will be executed right away, it won't yield back to native in between.

The Promise implementation uses setImmediate as its asynchronicity implementation.

Note: when debugging on Android, if the times between the debugger and device have drifted; things such as animation, event behavior, etc., might not work properly or the results may not be accurate. Please correct this by running adb shell "date `date +%m%d%H%M%Y.%S%3N`" on your debugger machine. Root access is required for the use in real device.

InteractionManager

One reason why well-built native apps feel so smooth is by avoiding expensive operations during interactions and animations. In React Native, we currently have a limitation that there is only a single JS execution thread, but you can use InteractionManager to make sure long-running work is scheduled to start after any interactions/animations have completed.

Applications can schedule tasks to run after interactions with the following:

InteractionManager.runAfterInteractions(() => {
// ...long-running synchronous task...
});

Compare this to other scheduling alternatives:

  • requestAnimationFrame(): for code that animates a view over time.
  • setImmediate/setTimeout/setInterval(): run code later, note this may delay animations.
  • runAfterInteractions(): run code later, without delaying active animations.

The touch handling system considers one or more active touches to be an 'interaction' and will delay runAfterInteractions() callbacks until all touches have ended or been cancelled.

InteractionManager also allows applications to register animations by creating an interaction 'handle' on animation start, and clearing it upon completion:

var handle = InteractionManager.createInteractionHandle();
// run animation... (`runAfterInteractions` tasks are queued)
// later, on animation completion:
InteractionManager.clearInteractionHandle(handle);
// queued tasks run if all handles were cleared
Edit this page
Last updated on
- + diff --git a/docs/next/toastandroid.html b/docs/next/toastandroid.html index 2df84faaca4..e32667e62db 100644 --- a/docs/next/toastandroid.html +++ b/docs/next/toastandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

ToastAndroid

React Native's ToastAndroid API exposes the Android platform's ToastAndroid module as a JS module. It provides the method show(message, duration) which takes the following parameters:

  • message A string with the text to toast
  • duration The duration of the toast—either ToastAndroid.SHORT or ToastAndroid.LONG

You can alternatively use showWithGravity(message, duration, gravity) to specify where the toast appears in the screen's layout. May be ToastAndroid.TOP, ToastAndroid.BOTTOM or ToastAndroid.CENTER.

The 'showWithGravityAndOffset(message, duration, gravity, xOffset, yOffset)' method adds the ability to specify an offset with in pixels.

Imperative hack

The ToastAndroid API is imperative, but there is a way to expose a declarative component from it as in this example:

Reference

Methods

show()

static show(message, duration)

showWithGravity()

static showWithGravity(message, duration, gravity)

showWithGravityAndOffset()

static showWithGravityAndOffset(message, duration, gravity, xOffset, yOffset)

Properties

SHORT

Indicates the duration on the screen.

ToastAndroid.SHORT;

LONG

Indicates the duration on the screen.

ToastAndroid.LONG;

TOP

Indicates the position on the screen.

ToastAndroid.TOP;

BOTTOM

Indicates the position on the screen.

ToastAndroid.BOTTOM;

CENTER

Indicates the position on the screen.

ToastAndroid.CENTER;
Edit this page
Last updated on
- + diff --git a/docs/next/toastandroid/index.html b/docs/next/toastandroid/index.html index 2df84faaca4..e32667e62db 100644 --- a/docs/next/toastandroid/index.html +++ b/docs/next/toastandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

ToastAndroid

React Native's ToastAndroid API exposes the Android platform's ToastAndroid module as a JS module. It provides the method show(message, duration) which takes the following parameters:

  • message A string with the text to toast
  • duration The duration of the toast—either ToastAndroid.SHORT or ToastAndroid.LONG

You can alternatively use showWithGravity(message, duration, gravity) to specify where the toast appears in the screen's layout. May be ToastAndroid.TOP, ToastAndroid.BOTTOM or ToastAndroid.CENTER.

The 'showWithGravityAndOffset(message, duration, gravity, xOffset, yOffset)' method adds the ability to specify an offset with in pixels.

Imperative hack

The ToastAndroid API is imperative, but there is a way to expose a declarative component from it as in this example:

Reference

Methods

show()

static show(message, duration)

showWithGravity()

static showWithGravity(message, duration, gravity)

showWithGravityAndOffset()

static showWithGravityAndOffset(message, duration, gravity, xOffset, yOffset)

Properties

SHORT

Indicates the duration on the screen.

ToastAndroid.SHORT;

LONG

Indicates the duration on the screen.

ToastAndroid.LONG;

TOP

Indicates the position on the screen.

ToastAndroid.TOP;

BOTTOM

Indicates the position on the screen.

ToastAndroid.BOTTOM;

CENTER

Indicates the position on the screen.

ToastAndroid.CENTER;
Edit this page
Last updated on
- + diff --git a/docs/next/touchablehighlight.html b/docs/next/touchablehighlight.html index 07e560ccad1..3d767818bfd 100644 --- a/docs/next/touchablehighlight.html +++ b/docs/next/touchablehighlight.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
<TouchableHighlight
activeOpacity={0.6}
underlayColor="#DDDDDD"
onPress={() => alert('Pressed!')}>
<MyComponent />
</TouchableHighlight>;

Example

Reference

Props

TouchableWithoutFeedback Props

Inherits TouchableWithoutFeedback Props.

activeOpacity

Determines what the opacity of the wrapped view should be when touch is active. The value should be between 0 and 1. Defaults to 0.85. Requires underlayColor to be set.

TypeRequired
numberNo

onHideUnderlay

Called immediately after the underlay is hidden.

TypeRequired
functionNo

onShowUnderlay

Called immediately after the underlay is shown.

TypeRequired
functionNo

style

TypeRequired
View.styleNo

underlayColor

The color of the underlay that will show through when the touch is active.

TypeRequired
colorNo

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

testOnly_pressed

Handy for snapshot tests.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/next/touchablehighlight/index.html b/docs/next/touchablehighlight/index.html index 07e560ccad1..3d767818bfd 100644 --- a/docs/next/touchablehighlight/index.html +++ b/docs/next/touchablehighlight/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
<TouchableHighlight
activeOpacity={0.6}
underlayColor="#DDDDDD"
onPress={() => alert('Pressed!')}>
<MyComponent />
</TouchableHighlight>;

Example

Reference

Props

TouchableWithoutFeedback Props

Inherits TouchableWithoutFeedback Props.

activeOpacity

Determines what the opacity of the wrapped view should be when touch is active. The value should be between 0 and 1. Defaults to 0.85. Requires underlayColor to be set.

TypeRequired
numberNo

onHideUnderlay

Called immediately after the underlay is hidden.

TypeRequired
functionNo

onShowUnderlay

Called immediately after the underlay is shown.

TypeRequired
functionNo

style

TypeRequired
View.styleNo

underlayColor

The color of the underlay that will show through when the touch is active.

TypeRequired
colorNo

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

testOnly_pressed

Handy for snapshot tests.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/next/touchablenativefeedback.html b/docs/next/touchablenativefeedback.html index c1a32ad8fd2..f8d5c9d0c84 100644 --- a/docs/next/touchablenativefeedback.html +++ b/docs/next/touchablenativefeedback.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

TouchableNativeFeedback

If you're looking for a more extensive and future-proof way to handle touch-based input, check out the Pressable API.

A wrapper for making views respond properly to touches (Android only). On Android this component uses native state drawable to display touch feedback.

At the moment it only supports having a single View instance as a child node, as it's implemented by replacing that View with another instance of RCTView node with some additional properties set.

Background drawable of native feedback touchable can be customized with background property.

Example

Reference

Props

TouchableWithoutFeedback Props

Inherits TouchableWithoutFeedback Props.

background

Determines the type of background drawable that's going to be used to display feedback. It takes an object with type property and extra data depending on the type. It's recommended to use one of the static methods to generate that dictionary.

TypeRequired
backgroundPropTypeNo

useForeground

Set to true to add the ripple effect to the foreground of the view, instead of the background. This is useful if one of your child views has a background of its own, or you're e.g. displaying images, and you don't want the ripple to be covered by them.

Check TouchableNativeFeedback.canUseNativeForeground() first, as this is only available on Android 6.0 and above. If you try to use this on older versions you will get a warning and fallback to background.

TypeRequired
boolNo

hasTVPreferredFocus

TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

Methods

SelectableBackground()

static SelectableBackground(rippleRadius: ?number)

Creates an object that represents android theme's default background for selectable elements (?android:attr/selectableItemBackground). rippleRadius parameter controls the radius of the ripple effect.

SelectableBackgroundBorderless()

static SelectableBackgroundBorderless(rippleRadius: ?number)

Creates an object that represent android theme's default background for borderless selectable elements (?android:attr/selectableItemBackgroundBorderless). Available on android API level 21+. rippleRadius parameter controls the radius of the ripple effect.

Ripple()

static Ripple(color: string, borderless: boolean, rippleRadius: ?number)

Creates an object that represents ripple drawable with specified color (as a string). If property borderless evaluates to true the ripple will render outside of the view bounds (see native actionbar buttons as an example of that behavior). This background type is available on Android API level 21+.

Parameters:

NameTypeRequiredDescription
colorstringYesThe ripple color
borderlessbooleanYesIf the ripple can render outside its bounds
rippleRadius?numberNocontrols the radius of the ripple effect

canUseNativeForeground()

static canUseNativeForeground()
Edit this page
Last updated on
- + diff --git a/docs/next/touchablenativefeedback/index.html b/docs/next/touchablenativefeedback/index.html index c1a32ad8fd2..f8d5c9d0c84 100644 --- a/docs/next/touchablenativefeedback/index.html +++ b/docs/next/touchablenativefeedback/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

TouchableNativeFeedback

If you're looking for a more extensive and future-proof way to handle touch-based input, check out the Pressable API.

A wrapper for making views respond properly to touches (Android only). On Android this component uses native state drawable to display touch feedback.

At the moment it only supports having a single View instance as a child node, as it's implemented by replacing that View with another instance of RCTView node with some additional properties set.

Background drawable of native feedback touchable can be customized with background property.

Example

Reference

Props

TouchableWithoutFeedback Props

Inherits TouchableWithoutFeedback Props.

background

Determines the type of background drawable that's going to be used to display feedback. It takes an object with type property and extra data depending on the type. It's recommended to use one of the static methods to generate that dictionary.

TypeRequired
backgroundPropTypeNo

useForeground

Set to true to add the ripple effect to the foreground of the view, instead of the background. This is useful if one of your child views has a background of its own, or you're e.g. displaying images, and you don't want the ripple to be covered by them.

Check TouchableNativeFeedback.canUseNativeForeground() first, as this is only available on Android 6.0 and above. If you try to use this on older versions you will get a warning and fallback to background.

TypeRequired
boolNo

hasTVPreferredFocus

TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

Methods

SelectableBackground()

static SelectableBackground(rippleRadius: ?number)

Creates an object that represents android theme's default background for selectable elements (?android:attr/selectableItemBackground). rippleRadius parameter controls the radius of the ripple effect.

SelectableBackgroundBorderless()

static SelectableBackgroundBorderless(rippleRadius: ?number)

Creates an object that represent android theme's default background for borderless selectable elements (?android:attr/selectableItemBackgroundBorderless). Available on android API level 21+. rippleRadius parameter controls the radius of the ripple effect.

Ripple()

static Ripple(color: string, borderless: boolean, rippleRadius: ?number)

Creates an object that represents ripple drawable with specified color (as a string). If property borderless evaluates to true the ripple will render outside of the view bounds (see native actionbar buttons as an example of that behavior). This background type is available on Android API level 21+.

Parameters:

NameTypeRequiredDescription
colorstringYesThe ripple color
borderlessbooleanYesIf the ripple can render outside its bounds
rippleRadius?numberNocontrols the radius of the ripple effect

canUseNativeForeground()

static canUseNativeForeground()
Edit this page
Last updated on
- + diff --git a/docs/next/touchableopacity.html b/docs/next/touchableopacity.html index e2898f0b0f7..30147bb8d17 100644 --- a/docs/next/touchableopacity.html +++ b/docs/next/touchableopacity.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

TouchableOpacity

If you're looking for a more extensive and future-proof way to handle touch-based input, check out the Pressable API.

A wrapper for making views respond properly to touches. On press down, the opacity of the wrapped view is decreased, dimming it.

Opacity is controlled by wrapping the children in an Animated.View, which is added to the view hierarchy. Be aware that this can affect layout.

Example

Reference

Props

TouchableWithoutFeedback Props

Inherits TouchableWithoutFeedback Props.

style

TypeRequired
View.styleNo

activeOpacity

Determines what the opacity of the wrapped view should be when touch is active. Defaults to 0.2.

TypeRequired
numberNo

tvParallaxProperties

(Apple TV only) Object with properties to control Apple TV parallax effects.

  • enabled: If true, parallax effects are enabled. Defaults to true.
  • shiftDistanceX: Defaults to 2.0.
  • shiftDistanceY: Defaults to 2.0.
  • tiltAngle: Defaults to 0.05.
  • magnification: Defaults to 1.0.
  • pressMagnification: Defaults to 1.0.
  • pressDuration: Defaults to 0.3.
  • pressDelay: Defaults to 0.0.
TypeRequiredPlatform
objectNoiOS

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/next/touchableopacity/index.html b/docs/next/touchableopacity/index.html index e2898f0b0f7..30147bb8d17 100644 --- a/docs/next/touchableopacity/index.html +++ b/docs/next/touchableopacity/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

TouchableOpacity

If you're looking for a more extensive and future-proof way to handle touch-based input, check out the Pressable API.

A wrapper for making views respond properly to touches. On press down, the opacity of the wrapped view is decreased, dimming it.

Opacity is controlled by wrapping the children in an Animated.View, which is added to the view hierarchy. Be aware that this can affect layout.

Example

Reference

Props

TouchableWithoutFeedback Props

Inherits TouchableWithoutFeedback Props.

style

TypeRequired
View.styleNo

activeOpacity

Determines what the opacity of the wrapped view should be when touch is active. Defaults to 0.2.

TypeRequired
numberNo

tvParallaxProperties

(Apple TV only) Object with properties to control Apple TV parallax effects.

  • enabled: If true, parallax effects are enabled. Defaults to true.
  • shiftDistanceX: Defaults to 2.0.
  • shiftDistanceY: Defaults to 2.0.
  • tiltAngle: Defaults to 0.05.
  • magnification: Defaults to 1.0.
  • pressMagnification: Defaults to 1.0.
  • pressDuration: Defaults to 0.3.
  • pressDelay: Defaults to 0.0.
TypeRequiredPlatform
objectNoiOS

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
numberNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/next/touchablewithoutfeedback.html b/docs/next/touchablewithoutfeedback.html index 5a9cc77b5b8..5ad99ecb111 100644 --- a/docs/next/touchablewithoutfeedback.html +++ b/docs/next/touchablewithoutfeedback.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
<TouchableWithoutFeedback onPress={() => alert('Pressed!')}>
<MyComponent />
</TouchableWithoutFeedback>;

Example

Reference

Props

accessibilityIgnoresInvertColors

TypeRequired
BooleanNo

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

accessibilityActions

Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The accessibilityActions property should contain a list of action objects. Each action object should contain the field name and label.

See the Accessibility guide for more information.

TypeRequired
arrayNo

onAccessibilityAction

Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform.

See the Accessibility guide for more information.

TypeRequired
functionNo

accessibilityValue

Represents the current value of a component. It can be a textual description of a component's value, or for range-based components, such as sliders and progress bars, it contains range information (minimum, current, and maximum).

See the Accessibility guide for more information.

TypeRequired
object: {min: number, max: number, now: number, text: string}No

delayLongPress

Duration (in milliseconds) from onPressIn before onLongPress is called.

TypeRequired
numberNo

delayPressIn

Duration (in milliseconds), from the start of the touch, before onPressIn is called.

TypeRequired
numberNo

delayPressOut

Duration (in milliseconds), from the release of the touch, before onPressOut is called.

TypeRequired
numberNo

disabled

If true, disable all interactions for this component.

TypeRequired
boolNo

hitSlop

This defines how far your touch can start away from the button. This is added to pressRetentionOffset when moving off of the button.

The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

TypeRequired
Rect or numberNo

onBlur

Invoked when the item loses focus.

TypeRequired
functionNo

onFocus

Invoked when the item receives focus.

TypeRequired
functionNo

onLayout

Invoked on mount and on layout changes.

TypeRequired
(LayoutEvent) => voidNo

onLongPress

Called if the time after onPressIn lasts longer than 370 milliseconds. This time period can be customized with delayLongPress.

TypeRequired
functionNo

onPress

Called when the touch is released, but not if cancelled (e.g. by a scroll that steals the responder lock). The first function argument is an event in form of PressEvent.

TypeRequired
functionNo

onPressIn

Called as soon as the touchable element is pressed and invoked even before onPress. This can be useful when making network requests. The first function argument is an event in form of PressEvent.

TypeRequired
functionNo

onPressOut

Called as soon as the touch is released even before onPress. The first function argument is an event in form of PressEvent.

TypeRequired
functionNo

pressRetentionOffset

When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations.

TypeRequired
Rect or numberNo

nativeID

TypeRequired
stringNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

touchSoundDisabled

If true, doesn't play a system sound on touch.

TypeRequiredPlatform
BooleanNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/next/touchablewithoutfeedback/index.html b/docs/next/touchablewithoutfeedback/index.html index 5a9cc77b5b8..5ad99ecb111 100644 --- a/docs/next/touchablewithoutfeedback/index.html +++ b/docs/next/touchablewithoutfeedback/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
<TouchableWithoutFeedback onPress={() => alert('Pressed!')}>
<MyComponent />
</TouchableWithoutFeedback>;

Example

Reference

Props

accessibilityIgnoresInvertColors

TypeRequired
BooleanNo

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

accessibilityActions

Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The accessibilityActions property should contain a list of action objects. Each action object should contain the field name and label.

See the Accessibility guide for more information.

TypeRequired
arrayNo

onAccessibilityAction

Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform.

See the Accessibility guide for more information.

TypeRequired
functionNo

accessibilityValue

Represents the current value of a component. It can be a textual description of a component's value, or for range-based components, such as sliders and progress bars, it contains range information (minimum, current, and maximum).

See the Accessibility guide for more information.

TypeRequired
object: {min: number, max: number, now: number, text: string}No

delayLongPress

Duration (in milliseconds) from onPressIn before onLongPress is called.

TypeRequired
numberNo

delayPressIn

Duration (in milliseconds), from the start of the touch, before onPressIn is called.

TypeRequired
numberNo

delayPressOut

Duration (in milliseconds), from the release of the touch, before onPressOut is called.

TypeRequired
numberNo

disabled

If true, disable all interactions for this component.

TypeRequired
boolNo

hitSlop

This defines how far your touch can start away from the button. This is added to pressRetentionOffset when moving off of the button.

The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

TypeRequired
Rect or numberNo

onBlur

Invoked when the item loses focus.

TypeRequired
functionNo

onFocus

Invoked when the item receives focus.

TypeRequired
functionNo

onLayout

Invoked on mount and on layout changes.

TypeRequired
(LayoutEvent) => voidNo

onLongPress

Called if the time after onPressIn lasts longer than 370 milliseconds. This time period can be customized with delayLongPress.

TypeRequired
functionNo

onPress

Called when the touch is released, but not if cancelled (e.g. by a scroll that steals the responder lock). The first function argument is an event in form of PressEvent.

TypeRequired
functionNo

onPressIn

Called as soon as the touchable element is pressed and invoked even before onPress. This can be useful when making network requests. The first function argument is an event in form of PressEvent.

TypeRequired
functionNo

onPressOut

Called as soon as the touch is released even before onPress. The first function argument is an event in form of PressEvent.

TypeRequired
functionNo

pressRetentionOffset

When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations.

TypeRequired
Rect or numberNo

nativeID

TypeRequired
stringNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

touchSoundDisabled

If true, doesn't play a system sound on touch.

TypeRequiredPlatform
BooleanNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/next/transforms.html b/docs/next/transforms.html index c9d773d8634..00cc86ffc1d 100644 --- a/docs/next/transforms.html +++ b/docs/next/transforms.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Transforms

Transforms are style properties that will help you modify the appearance and position of your components using 2D or 3D transformations. However, once you apply transforms, the layouts remain the same around the transformed component hence it might overlap with the nearby components. You can apply margin to the transformed component, the nearby components or padding to the container to prevent such overlaps.

Example

Reference

Methods

transform()

transform accepts an array of transformation objects. Each object specifies the property that will be transformed as the key, and the value to use in the transformation. Objects should not be combined. Use a single key/value pair per object.

The rotate transformations require a string so that the transform may be expressed in degrees (deg) or radians (rad). For example:

transform([{ rotateX: '45deg' }, { rotateZ: '0.785398rad' }]);

The skew transformations require a string so that the transform may be expressed in degrees (deg). For example:

transform([{ skewX: '45deg' }]);
TypeRequired
array of objects: {matrix: number[]}, {perspective: number}, {rotate: string}, {rotateX: string}, {rotateY: string}, {rotateZ: string}, {scale: number}, {scaleX: number}, {scaleY: number}, {translateX: number}, {translateY: number}, {skewX: string}, {skewY: string}No

decomposedMatrix, rotation, scaleX, scaleY, transformMatrix, translateX, translateY

Deprecated. Use the transform prop instead.

Edit this page
Last updated on
- + diff --git a/docs/next/transforms/index.html b/docs/next/transforms/index.html index c9d773d8634..00cc86ffc1d 100644 --- a/docs/next/transforms/index.html +++ b/docs/next/transforms/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Transforms

Transforms are style properties that will help you modify the appearance and position of your components using 2D or 3D transformations. However, once you apply transforms, the layouts remain the same around the transformed component hence it might overlap with the nearby components. You can apply margin to the transformed component, the nearby components or padding to the container to prevent such overlaps.

Example

Reference

Methods

transform()

transform accepts an array of transformation objects. Each object specifies the property that will be transformed as the key, and the value to use in the transformation. Objects should not be combined. Use a single key/value pair per object.

The rotate transformations require a string so that the transform may be expressed in degrees (deg) or radians (rad). For example:

transform([{ rotateX: '45deg' }, { rotateZ: '0.785398rad' }]);

The skew transformations require a string so that the transform may be expressed in degrees (deg). For example:

transform([{ skewX: '45deg' }]);
TypeRequired
array of objects: {matrix: number[]}, {perspective: number}, {rotate: string}, {rotateX: string}, {rotateY: string}, {rotateZ: string}, {scale: number}, {scaleX: number}, {scaleY: number}, {translateX: number}, {translateY: number}, {skewX: string}, {skewY: string}No

decomposedMatrix, rotation, scaleX, scaleY, transformMatrix, translateX, translateY

Deprecated. Use the transform prop instead.

Edit this page
Last updated on
- + diff --git a/docs/next/troubleshooting.html b/docs/next/troubleshooting.html index bb28ce619ce..80cffa9b453 100644 --- a/docs/next/troubleshooting.html +++ b/docs/next/troubleshooting.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Troubleshooting

These are some common issues you may run into while setting up React Native. If you encounter something that is not listed here, try searching for the issue in GitHub.

Port already in use

The Metro bundler runs on port 8081. If another process is already using that port, you can either terminate that process, or change the port that the bundler uses.

Terminating a process on port 8081

Run the following command to find the id for the process that is listening on port 8081:

sudo lsof -i :8081

Then run the following to terminate the process:

kill -9 <PID>

On Windows you can find the process using port 8081 using Resource Monitor and stop it using Task Manager.

Using a port other than 8081

You can configure the bundler to use a port other than 8081 by using the port parameter:

npx react-native start --port=8088

You will also need to update your applications to load the JavaScript bundle from the new port. If running on device from Xcode, you can do this by updating occurrences of 8081 to your chosen port in the node_modules/react-native/React/React.xcodeproj/project.pbxproj file.

NPM locking error

If you encounter an error such as npm WARN locking Error: EACCES while using the React Native CLI, try running the following:

sudo chown -R $USER ~/.npm
sudo chown -R $USER /usr/local/lib/node_modules

Missing libraries for React

If you added React Native manually to your project, make sure you have included all the relevant dependencies that you are using, like RCTText.xcodeproj, RCTImage.xcodeproj. Next, the binaries built by these dependencies have to be linked to your app binary. Use the Linked Frameworks and Binaries section in the Xcode project settings. More detailed steps are here: Linking Libraries.

If you are using CocoaPods, verify that you have added React along with the subspecs to the Podfile. For example, if you were using the <Text />, <Image /> and fetch() APIs, you would need to add these in your Podfile:

pod 'React', :path => '../node_modules/react-native', :subspecs => [
'RCTText',
'RCTImage',
'RCTNetwork',
'RCTWebSocket',
]

Next, make sure you have run pod install and that a Pods/ directory has been created in your project with React installed. CocoaPods will instruct you to use the generated .xcworkspace file henceforth to be able to use these installed dependencies.

React Native does not compile when being used as a CocoaPod

There is a CocoaPods plugin called cocoapods-fix-react-native which handles any potential post-fixing of the source code due to differences when using a dependency manager.

Argument list too long: recursive header expansion failed

In the project's build settings, User Search Header Paths and Header Search Paths are two configs that specify where Xcode should look for #import header files specified in the code. For Pods, CocoaPods uses a default array of specific folders to look in. Verify that this particular config is not overwritten, and that none of the folders configured are too large. If one of the folders is a large folder, Xcode will attempt to recursively search the entire directory and throw above error at some point.

To revert the User Search Header Paths and Header Search Paths build settings to their defaults set by CocoaPods - select the entry in the Build Settings panel, and hit delete. It will remove the custom override and return to the CocoaPod defaults.

No transports available

React Native implements a polyfill for WebSockets. These polyfills are initialized as part of the react-native module that you include in your application through import React from 'react'. If you load another module that requires WebSockets, such as Firebase, be sure to load/require it after react-native:

import React from 'react';
import Firebase from 'firebase';

Shell Command Unresponsive Exception

If you encounter a ShellCommandUnresponsiveException exception such as:

Execution failed for task ':app:installDebug'.
com.android.builder.testing.api.DeviceException: com.android.ddmlib.ShellCommandUnresponsiveException

Try downgrading your Gradle version to 1.2.3 in android/build.gradle.

react-native init hangs

If you run into issues where running npx react-native init hangs in your system, try running it again in verbose mode and referring to #2797 for common causes:

npx react-native init --verbose

Unable to start react-native package manager (on Linux)

Case 1: Error "code":"ENOSPC","errno":"ENOSPC"

Issue caused by the number of directories inotify (used by watchman on Linux) can monitor. To solve it, run this command in your terminal window

echo fs.inotify.max_user_watches=582222 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
Edit this page
Last updated on
- + diff --git a/docs/next/troubleshooting/index.html b/docs/next/troubleshooting/index.html index bb28ce619ce..80cffa9b453 100644 --- a/docs/next/troubleshooting/index.html +++ b/docs/next/troubleshooting/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Troubleshooting

These are some common issues you may run into while setting up React Native. If you encounter something that is not listed here, try searching for the issue in GitHub.

Port already in use

The Metro bundler runs on port 8081. If another process is already using that port, you can either terminate that process, or change the port that the bundler uses.

Terminating a process on port 8081

Run the following command to find the id for the process that is listening on port 8081:

sudo lsof -i :8081

Then run the following to terminate the process:

kill -9 <PID>

On Windows you can find the process using port 8081 using Resource Monitor and stop it using Task Manager.

Using a port other than 8081

You can configure the bundler to use a port other than 8081 by using the port parameter:

npx react-native start --port=8088

You will also need to update your applications to load the JavaScript bundle from the new port. If running on device from Xcode, you can do this by updating occurrences of 8081 to your chosen port in the node_modules/react-native/React/React.xcodeproj/project.pbxproj file.

NPM locking error

If you encounter an error such as npm WARN locking Error: EACCES while using the React Native CLI, try running the following:

sudo chown -R $USER ~/.npm
sudo chown -R $USER /usr/local/lib/node_modules

Missing libraries for React

If you added React Native manually to your project, make sure you have included all the relevant dependencies that you are using, like RCTText.xcodeproj, RCTImage.xcodeproj. Next, the binaries built by these dependencies have to be linked to your app binary. Use the Linked Frameworks and Binaries section in the Xcode project settings. More detailed steps are here: Linking Libraries.

If you are using CocoaPods, verify that you have added React along with the subspecs to the Podfile. For example, if you were using the <Text />, <Image /> and fetch() APIs, you would need to add these in your Podfile:

pod 'React', :path => '../node_modules/react-native', :subspecs => [
'RCTText',
'RCTImage',
'RCTNetwork',
'RCTWebSocket',
]

Next, make sure you have run pod install and that a Pods/ directory has been created in your project with React installed. CocoaPods will instruct you to use the generated .xcworkspace file henceforth to be able to use these installed dependencies.

React Native does not compile when being used as a CocoaPod

There is a CocoaPods plugin called cocoapods-fix-react-native which handles any potential post-fixing of the source code due to differences when using a dependency manager.

Argument list too long: recursive header expansion failed

In the project's build settings, User Search Header Paths and Header Search Paths are two configs that specify where Xcode should look for #import header files specified in the code. For Pods, CocoaPods uses a default array of specific folders to look in. Verify that this particular config is not overwritten, and that none of the folders configured are too large. If one of the folders is a large folder, Xcode will attempt to recursively search the entire directory and throw above error at some point.

To revert the User Search Header Paths and Header Search Paths build settings to their defaults set by CocoaPods - select the entry in the Build Settings panel, and hit delete. It will remove the custom override and return to the CocoaPod defaults.

No transports available

React Native implements a polyfill for WebSockets. These polyfills are initialized as part of the react-native module that you include in your application through import React from 'react'. If you load another module that requires WebSockets, such as Firebase, be sure to load/require it after react-native:

import React from 'react';
import Firebase from 'firebase';

Shell Command Unresponsive Exception

If you encounter a ShellCommandUnresponsiveException exception such as:

Execution failed for task ':app:installDebug'.
com.android.builder.testing.api.DeviceException: com.android.ddmlib.ShellCommandUnresponsiveException

Try downgrading your Gradle version to 1.2.3 in android/build.gradle.

react-native init hangs

If you run into issues where running npx react-native init hangs in your system, try running it again in verbose mode and referring to #2797 for common causes:

npx react-native init --verbose

Unable to start react-native package manager (on Linux)

Case 1: Error "code":"ENOSPC","errno":"ENOSPC"

Issue caused by the number of directories inotify (used by watchman on Linux) can monitor. To solve it, run this command in your terminal window

echo fs.inotify.max_user_watches=582222 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
Edit this page
Last updated on
- + diff --git a/docs/next/tutorial.html b/docs/next/tutorial.html index 02d871998ae..12e914999be 100644 --- a/docs/next/tutorial.html +++ b/docs/next/tutorial.html @@ -19,7 +19,7 @@ - + @@ -45,7 +45,7 @@
// React Native Styles
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'center',
alignItems: 'center'
}
});

As shown above, there is no difference in handling the state between React and React Native. You can use the state of your components both in classes and in functional components using hooks!

In the following example we will show the same above counter example using classes.

Edit this page
Last updated on
- + diff --git a/docs/next/tutorial/index.html b/docs/next/tutorial/index.html index 02d871998ae..12e914999be 100644 --- a/docs/next/tutorial/index.html +++ b/docs/next/tutorial/index.html @@ -19,7 +19,7 @@ - + @@ -45,7 +45,7 @@
// React Native Styles
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'center',
alignItems: 'center'
}
});

As shown above, there is no difference in handling the state between React and React Native. You can use the state of your components both in classes and in functional components using hooks!

In the following example we will show the same above counter example using classes.

Edit this page
Last updated on
- + diff --git a/docs/next/typescript.html b/docs/next/typescript.html index 2649a44f0dd..c3f4d610a20 100644 --- a/docs/next/typescript.html +++ b/docs/next/typescript.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
export default Hello;

You can explore the syntax more in the TypeScript playground.

Where to Find Useful Advice

Using Custom Path Aliases with TypeScript

To use custom path aliases with TypeScript, you need to set the path aliases to work from both Babel and TypeScript. Here's how:

  1. Edit your tsconfig.json to have your custom path mappings. Set anything in the root of src to be available with no preceding path reference, and allow any test file to be accessed by using tests/File.tsx:
"target": "esnext",
+ "baseUrl": ".",
+ "paths": {
+ "*": ["src/*"],
+ "tests": ["tests/*"],
+ "@components/*": ["src/components/*"],
+ },
}
  1. Add babel-plugin-module-resolver as a development package to your project:
npm install --save-dev babel-plugin-module-resolver
  1. Finally, configure your babel.config.js (note that the syntax for your babel.config.js is different from your tsconfig.json):
{
plugins: [
+ [
+ 'module-resolver',
+ {
+ root: ['./src'],
+ extensions: ['.ios.js', '.android.js', '.js', '.ts', '.tsx', '.json'],
+ alias: {
+ "tests": ["./tests/"],
+ "@components": "./src/components",
+ }
+ }
+ ]
]
}
Edit this page
Last updated on
- + diff --git a/docs/next/typescript/index.html b/docs/next/typescript/index.html index 2649a44f0dd..c3f4d610a20 100644 --- a/docs/next/typescript/index.html +++ b/docs/next/typescript/index.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
export default Hello;

You can explore the syntax more in the TypeScript playground.

Where to Find Useful Advice

Using Custom Path Aliases with TypeScript

To use custom path aliases with TypeScript, you need to set the path aliases to work from both Babel and TypeScript. Here's how:

  1. Edit your tsconfig.json to have your custom path mappings. Set anything in the root of src to be available with no preceding path reference, and allow any test file to be accessed by using tests/File.tsx:
"target": "esnext",
+ "baseUrl": ".",
+ "paths": {
+ "*": ["src/*"],
+ "tests": ["tests/*"],
+ "@components/*": ["src/components/*"],
+ },
}
  1. Add babel-plugin-module-resolver as a development package to your project:
npm install --save-dev babel-plugin-module-resolver
  1. Finally, configure your babel.config.js (note that the syntax for your babel.config.js is different from your tsconfig.json):
{
plugins: [
+ [
+ 'module-resolver',
+ {
+ root: ['./src'],
+ extensions: ['.ios.js', '.android.js', '.js', '.ts', '.tsx', '.json'],
+ alias: {
+ "tests": ["./tests/"],
+ "@components": "./src/components",
+ }
+ }
+ ]
]
}
Edit this page
Last updated on
- + diff --git a/docs/next/upgrading.html b/docs/next/upgrading.html index 29934082f07..459277ec91b 100644 --- a/docs/next/upgrading.html +++ b/docs/next/upgrading.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Upgrading to new versions

Upgrading to new versions of React Native will give you access to more APIs, views, developer tools and other goodies. Upgrading requires a small amount of effort, but we try to make it straightforward for you.

Expo projects

Upgrading your Expo project to a new version of React Native requires updating the react-native, react, and expo package versions in your package.json file. Please refer to this list to find out what versions are supported. You will also need to set the correct sdkVersion in your app.json file.

See the Upgrading Expo SDK Walkthrough for up-to-date information about upgrading your project.

React Native projects

Because typical React Native projects are essentially made up of an Android project, an iOS project, and a JavaScript project, upgrading can be rather tricky. There's currently two ways for upgrading your React Native project: by using React Native CLI or manually with Upgrade Helper.

React Native CLI

The React Native CLI comes with upgrade command that provides a one-step operation to upgrade the source files with a minimum of conflicts, it internally uses rn-diff-purge project to find out which files need to be created, removed or modified.

1. Run the upgrade command

The upgrade command works on top of Git by using git apply with 3-way merge, therefore it's required to use Git in order for this to work, if you don't use Git but still want to use this solution then you can check out how to do it in the Troubleshooting section.

Run the following command to start the process of upgrading to the latest version:

npx react-native upgrade

You may specify a React Native version by passing an argument, e.g. to upgrade to 0.61.0-rc.0 run:

npx react-native upgrade 0.61.0-rc.0

The project is upgraded using git apply with 3-way merge, it may happen that you'll need to resolve a few conflicts after it's finished.

2. Resolve the conflicts

Conflicted files include delimiters which make very clear where the changes come from. For example:

13B07F951A680F5B00A75B9A /* Release */ = {
isa = XCBuildConfiguration;
buildSettings = {
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
<<<<<<< ours
CODE_SIGN_IDENTITY = "iPhone Developer";
FRAMEWORK_SEARCH_PATHS = (
"$(inherited)",
"$(PROJECT_DIR)/HockeySDK.embeddedframework",
"$(PROJECT_DIR)/HockeySDK-iOS/HockeySDK.embeddedframework",
);
=======
CURRENT_PROJECT_VERSION = 1;
>>>>>>> theirs
HEADER_SEARCH_PATHS = (
"$(inherited)",
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include,
"$(SRCROOT)/../node_modules/react-native/React/**",
"$(SRCROOT)/../node_modules/react-native-code-push/ios/CodePush/**",
);

You can think of "ours" as "your team" and "theirs" as "the React Native development team".

Upgrade Helper

The Upgrade Helper is a web tool to help you out when upgrading your apps by providing the full set of changes happening between any two versions. It also shows comments on specific files to help understanding why that change is needed.

1. Select the versions

You first need to select from and to which version you wish to upgrade, by default the latest major versions are selected. After selecting you can click the button "Show me how to upgrade".

💡 Major updates will show an "useful content" section on the top with links to help you out when upgrading.

2. Upgrade dependencies

The first file that is shown is the package.json, it's good to update the dependencies that are showing in there. For example, if react-native and react appears as changes then you can install it in your project by running yarn add:

# {{VERSION}} and {{REACT_VERSION}} are the release versions showing in the diff
yarn add react-native@{{VERSION}}
yarn add react@{{REACT_VERSION}}

3. Upgrade your project files

The new release may contain updates to other files that are generated when you run npx react-native init, those files are listed after the package.json in the Upgrade Helper page. If there aren't other changes then you only need to rebuild the project to continue developing.

In case there are changes then you can either update them manually by copying and pasting from the changes in the page or you can do it with the React Native CLI upgrade command by running:

npx react-native upgrade

This will check your files against the latest template and perform the following:

  • If there is a new file in the template, it is created.
  • If a file in the template is identical to your file, it is skipped.
  • If a file is different in your project than the template, you will be prompted; you have options to keep your file or overwrite it with the template version.

Some upgrades won't be done automatically with the React Native CLI and require manual work, e.g. 0.28 to 0.29, or 0.56 to 0.57. Make sure to check the release notes when upgrading so that you can identify any manual changes your particular project may require.

Troubleshooting

I want to upgrade with React Native CLI but I don't use Git

While your project does not have to be handled by the Git versioning system -- you can use Mercurial, SVN, or nothing -- you will still need to install Git on your system in order to use npx react-native upgrade. Git will also need to be available in the PATH. If your project doesn't use Git, initialize it and commit:

git init # Initialize a Git repository
git add . # Stage all the current files
git commit -m "Upgrade react-native" # Save the current files in a commit

After you finish upgrading you may remove the .git directory.

I have done all the changes but my app is still using an old version

These sort of errors are usually related to caching, it's recommended to install react-native-clean-project to clear all your project's cache and then you can run it again.

Edit this page
Last updated on
- + diff --git a/docs/next/upgrading/index.html b/docs/next/upgrading/index.html index 29934082f07..459277ec91b 100644 --- a/docs/next/upgrading/index.html +++ b/docs/next/upgrading/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Upgrading to new versions

Upgrading to new versions of React Native will give you access to more APIs, views, developer tools and other goodies. Upgrading requires a small amount of effort, but we try to make it straightforward for you.

Expo projects

Upgrading your Expo project to a new version of React Native requires updating the react-native, react, and expo package versions in your package.json file. Please refer to this list to find out what versions are supported. You will also need to set the correct sdkVersion in your app.json file.

See the Upgrading Expo SDK Walkthrough for up-to-date information about upgrading your project.

React Native projects

Because typical React Native projects are essentially made up of an Android project, an iOS project, and a JavaScript project, upgrading can be rather tricky. There's currently two ways for upgrading your React Native project: by using React Native CLI or manually with Upgrade Helper.

React Native CLI

The React Native CLI comes with upgrade command that provides a one-step operation to upgrade the source files with a minimum of conflicts, it internally uses rn-diff-purge project to find out which files need to be created, removed or modified.

1. Run the upgrade command

The upgrade command works on top of Git by using git apply with 3-way merge, therefore it's required to use Git in order for this to work, if you don't use Git but still want to use this solution then you can check out how to do it in the Troubleshooting section.

Run the following command to start the process of upgrading to the latest version:

npx react-native upgrade

You may specify a React Native version by passing an argument, e.g. to upgrade to 0.61.0-rc.0 run:

npx react-native upgrade 0.61.0-rc.0

The project is upgraded using git apply with 3-way merge, it may happen that you'll need to resolve a few conflicts after it's finished.

2. Resolve the conflicts

Conflicted files include delimiters which make very clear where the changes come from. For example:

13B07F951A680F5B00A75B9A /* Release */ = {
isa = XCBuildConfiguration;
buildSettings = {
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
<<<<<<< ours
CODE_SIGN_IDENTITY = "iPhone Developer";
FRAMEWORK_SEARCH_PATHS = (
"$(inherited)",
"$(PROJECT_DIR)/HockeySDK.embeddedframework",
"$(PROJECT_DIR)/HockeySDK-iOS/HockeySDK.embeddedframework",
);
=======
CURRENT_PROJECT_VERSION = 1;
>>>>>>> theirs
HEADER_SEARCH_PATHS = (
"$(inherited)",
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include,
"$(SRCROOT)/../node_modules/react-native/React/**",
"$(SRCROOT)/../node_modules/react-native-code-push/ios/CodePush/**",
);

You can think of "ours" as "your team" and "theirs" as "the React Native development team".

Upgrade Helper

The Upgrade Helper is a web tool to help you out when upgrading your apps by providing the full set of changes happening between any two versions. It also shows comments on specific files to help understanding why that change is needed.

1. Select the versions

You first need to select from and to which version you wish to upgrade, by default the latest major versions are selected. After selecting you can click the button "Show me how to upgrade".

💡 Major updates will show an "useful content" section on the top with links to help you out when upgrading.

2. Upgrade dependencies

The first file that is shown is the package.json, it's good to update the dependencies that are showing in there. For example, if react-native and react appears as changes then you can install it in your project by running yarn add:

# {{VERSION}} and {{REACT_VERSION}} are the release versions showing in the diff
yarn add react-native@{{VERSION}}
yarn add react@{{REACT_VERSION}}

3. Upgrade your project files

The new release may contain updates to other files that are generated when you run npx react-native init, those files are listed after the package.json in the Upgrade Helper page. If there aren't other changes then you only need to rebuild the project to continue developing.

In case there are changes then you can either update them manually by copying and pasting from the changes in the page or you can do it with the React Native CLI upgrade command by running:

npx react-native upgrade

This will check your files against the latest template and perform the following:

  • If there is a new file in the template, it is created.
  • If a file in the template is identical to your file, it is skipped.
  • If a file is different in your project than the template, you will be prompted; you have options to keep your file or overwrite it with the template version.

Some upgrades won't be done automatically with the React Native CLI and require manual work, e.g. 0.28 to 0.29, or 0.56 to 0.57. Make sure to check the release notes when upgrading so that you can identify any manual changes your particular project may require.

Troubleshooting

I want to upgrade with React Native CLI but I don't use Git

While your project does not have to be handled by the Git versioning system -- you can use Mercurial, SVN, or nothing -- you will still need to install Git on your system in order to use npx react-native upgrade. Git will also need to be available in the PATH. If your project doesn't use Git, initialize it and commit:

git init # Initialize a Git repository
git add . # Stage all the current files
git commit -m "Upgrade react-native" # Save the current files in a commit

After you finish upgrading you may remove the .git directory.

I have done all the changes but my app is still using an old version

These sort of errors are usually related to caching, it's recommended to install react-native-clean-project to clear all your project's cache and then you can run it again.

Edit this page
Last updated on
- + diff --git a/docs/next/usecolorscheme.html b/docs/next/usecolorscheme.html index c1b14f95cd1..021fcc5ab27 100644 --- a/docs/next/usecolorscheme.html +++ b/docs/next/usecolorscheme.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

useColorScheme

import { useColorScheme } from 'react-native';

The useColorScheme React hook provides and subscribes to color scheme updates from the Appearance module. The return value indicates the current user preferred color scheme. The value may be updated later, either through direct user action (e.g. theme selection in device settings) or on a schedule (e.g. light and dark themes that follow the day/night cycle).

Supported color schemes

  • "light": The user prefers a light color theme.
  • "dark": The user prefers a dark color theme.
  • null: The user has not indicated a preferred color theme.

Example

You can find a complete example that demonstrates the use of this hook alongside a React context to add support for light and dark themes to your application in AppearanceExample.js.

Edit this page
Last updated on
- + diff --git a/docs/next/usecolorscheme/index.html b/docs/next/usecolorscheme/index.html index c1b14f95cd1..021fcc5ab27 100644 --- a/docs/next/usecolorscheme/index.html +++ b/docs/next/usecolorscheme/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

useColorScheme

import { useColorScheme } from 'react-native';

The useColorScheme React hook provides and subscribes to color scheme updates from the Appearance module. The return value indicates the current user preferred color scheme. The value may be updated later, either through direct user action (e.g. theme selection in device settings) or on a schedule (e.g. light and dark themes that follow the day/night cycle).

Supported color schemes

  • "light": The user prefers a light color theme.
  • "dark": The user prefers a dark color theme.
  • null: The user has not indicated a preferred color theme.

Example

You can find a complete example that demonstrates the use of this hook alongside a React context to add support for light and dark themes to your application in AppearanceExample.js.

Edit this page
Last updated on
- + diff --git a/docs/next/usewindowdimensions.html b/docs/next/usewindowdimensions.html index 0715708c2ef..3b75e401f8f 100644 --- a/docs/next/usewindowdimensions.html +++ b/docs/next/usewindowdimensions.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

useWindowDimensions

import { useWindowDimensions } from 'react-native';

useWindowDimensions automatically updates width and height values when screen size changes. You can get your application window's width and height like so:

const windowWidth = useWindowDimensions().width;
const windowHeight = useWindowDimensions().height;

Example

Properties

fontScale

useWindowDimensions().fontScale;

The scale of the font currently used. Some operating systems allow users to scale their font sizes larger or smaller for reading comfort. This property will let you know what is in effect.

height

useWindowDimensions().height;

The height in pixels of the window or screen your app occupies.

scale

useWindowDimensions().scale;

The pixel ratio of the device your app is running on.

A value of 1 indicates PPI/DPI of 96 (76 on some platforms). 2 indicates a Retina or high DPI display.

width

useWindowDimensions().width;

The width in pixels of the window or screen your app occupies.

Edit this page
Last updated on
- + diff --git a/docs/next/usewindowdimensions/index.html b/docs/next/usewindowdimensions/index.html index 0715708c2ef..3b75e401f8f 100644 --- a/docs/next/usewindowdimensions/index.html +++ b/docs/next/usewindowdimensions/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

useWindowDimensions

import { useWindowDimensions } from 'react-native';

useWindowDimensions automatically updates width and height values when screen size changes. You can get your application window's width and height like so:

const windowWidth = useWindowDimensions().width;
const windowHeight = useWindowDimensions().height;

Example

Properties

fontScale

useWindowDimensions().fontScale;

The scale of the font currently used. Some operating systems allow users to scale their font sizes larger or smaller for reading comfort. This property will let you know what is in effect.

height

useWindowDimensions().height;

The height in pixels of the window or screen your app occupies.

scale

useWindowDimensions().scale;

The pixel ratio of the device your app is running on.

A value of 1 indicates PPI/DPI of 96 (76 on some platforms). 2 indicates a Retina or high DPI display.

width

useWindowDimensions().width;

The width in pixels of the window or screen your app occupies.

Edit this page
Last updated on
- + diff --git a/docs/next/using-a-listview.html b/docs/next/using-a-listview.html index bd89455ac90..d0dad233a08 100644 --- a/docs/next/using-a-listview.html +++ b/docs/next/using-a-listview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Using List Views

React Native provides a suite of components for presenting lists of data. Generally, you'll want to use either FlatList or SectionList.

The FlatList component displays a scrolling list of changing, but similarly structured, data. FlatList works well for long lists of data, where the number of items might change over time. Unlike the more generic ScrollView, the FlatList only renders elements that are currently showing on the screen, not all the elements at once.

The FlatList component requires two props: data and renderItem. data is the source of information for the list. renderItem takes one item from the source and returns a formatted component to render.

This example creates a basic FlatList of hardcoded data. Each item in the data props is rendered as a Text component. The FlatListBasics component then renders the FlatList and all Text components.

If you want to render a set of data broken into logical sections, maybe with section headers, similar to UITableViews on iOS, then a SectionList is the way to go.

One of the most common uses for a list view is displaying data that you fetch from a server. To do that, you will need to learn about networking in React Native.

Edit this page
Last updated on
- + diff --git a/docs/next/using-a-listview/index.html b/docs/next/using-a-listview/index.html index bd89455ac90..d0dad233a08 100644 --- a/docs/next/using-a-listview/index.html +++ b/docs/next/using-a-listview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Using List Views

React Native provides a suite of components for presenting lists of data. Generally, you'll want to use either FlatList or SectionList.

The FlatList component displays a scrolling list of changing, but similarly structured, data. FlatList works well for long lists of data, where the number of items might change over time. Unlike the more generic ScrollView, the FlatList only renders elements that are currently showing on the screen, not all the elements at once.

The FlatList component requires two props: data and renderItem. data is the source of information for the list. renderItem takes one item from the source and returns a formatted component to render.

This example creates a basic FlatList of hardcoded data. Each item in the data props is rendered as a Text component. The FlatListBasics component then renders the FlatList and all Text components.

If you want to render a set of data broken into logical sections, maybe with section headers, similar to UITableViews on iOS, then a SectionList is the way to go.

One of the most common uses for a list view is displaying data that you fetch from a server. To do that, you will need to learn about networking in React Native.

Edit this page
Last updated on
- + diff --git a/docs/next/using-a-scrollview.html b/docs/next/using-a-scrollview.html index e622052f074..001c7e26d49 100644 --- a/docs/next/using-a-scrollview.html +++ b/docs/next/using-a-scrollview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Using a ScrollView

The ScrollView is a generic scrolling container that can contain multiple components and views. The scrollable items can be heterogeneous, and you can scroll both vertically and horizontally (by setting the horizontal property).

This example creates a vertical ScrollView with both images and text mixed together.

ScrollViews can be configured to allow paging through views using swiping gestures by using the pagingEnabled props. Swiping horizontally between views can also be implemented on Android using the ViewPager component.

On iOS a ScrollView with a single item can be used to allow the user to zoom content. Set up the maximumZoomScale and minimumZoomScale props and your user will be able to use pinch and expand gestures to zoom in and out.

The ScrollView works best to present a small amount of things of a limited size. All the elements and views of a ScrollView are rendered, even if they are not currently shown on the screen. If you have a long list of more items than can fit on the screen, you should use a FlatList instead. So let's learn about list views next.

Edit this page
Last updated on
- + diff --git a/docs/next/using-a-scrollview/index.html b/docs/next/using-a-scrollview/index.html index e622052f074..001c7e26d49 100644 --- a/docs/next/using-a-scrollview/index.html +++ b/docs/next/using-a-scrollview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Using a ScrollView

The ScrollView is a generic scrolling container that can contain multiple components and views. The scrollable items can be heterogeneous, and you can scroll both vertically and horizontally (by setting the horizontal property).

This example creates a vertical ScrollView with both images and text mixed together.

ScrollViews can be configured to allow paging through views using swiping gestures by using the pagingEnabled props. Swiping horizontally between views can also be implemented on Android using the ViewPager component.

On iOS a ScrollView with a single item can be used to allow the user to zoom content. Set up the maximumZoomScale and minimumZoomScale props and your user will be able to use pinch and expand gestures to zoom in and out.

The ScrollView works best to present a small amount of things of a limited size. All the elements and views of a ScrollView are rendered, even if they are not currently shown on the screen. If you have a long list of more items than can fit on the screen, you should use a FlatList instead. So let's learn about list views next.

Edit this page
Last updated on
- + diff --git a/docs/next/vibration.html b/docs/next/vibration.html index c072eb91fa9..201be7ad55e 100644 --- a/docs/next/vibration.html +++ b/docs/next/vibration.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Vibration

Vibrates the device.

Example

Android apps should request the android.permission.VIBRATE permission by adding <uses-permission android:name="android.permission.VIBRATE"/> to AndroidManifest.xml.

The Vibration API is implemented as a AudioServicesPlaySystemSound(kSystemSoundID_Vibrate) call on iOS.

Reference

Methods

cancel()

Vibration.cancel();

Call this to stop vibrating after having invoked vibrate() with repetition enabled.

vibrate()

Vibration.vibrate(pattern, repeat);

Triggers a vibration with a fixed duration.

On Android, the vibration duration defaults to 400 milliseconds, and an arbitrary vibration duration can be specified by passing a number as the value for the pattern argument. On iOS, the vibration duration is fixed at roughly 400 milliseconds.

The vibrate() method can take a pattern argument with an array of numbers that represent time in milliseconds. You may set repeat to true to run through the vibration pattern in a loop until cancel() is called.

On Android, the odd indices of the pattern array represent the vibration duration, while the even ones represent the separation time. On iOS, the numbers in the pattern array represent the separation time, as the vibration duration is fixed.

Parameters:

NameTypeDefaultDescription
patternnumber
Android
array of numbers		400Vibration duration in milliseconds.
Vibration pattern as an array of numbers in milliseconds.
repeatbooleanfalseRepeat vibration pattern until cancel().
Edit this page
Last updated on
- + diff --git a/docs/next/vibration/index.html b/docs/next/vibration/index.html index c072eb91fa9..201be7ad55e 100644 --- a/docs/next/vibration/index.html +++ b/docs/next/vibration/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

Vibration

Vibrates the device.

Example

Android apps should request the android.permission.VIBRATE permission by adding <uses-permission android:name="android.permission.VIBRATE"/> to AndroidManifest.xml.

The Vibration API is implemented as a AudioServicesPlaySystemSound(kSystemSoundID_Vibrate) call on iOS.

Reference

Methods

cancel()

Vibration.cancel();

Call this to stop vibrating after having invoked vibrate() with repetition enabled.

vibrate()

Vibration.vibrate(pattern, repeat);

Triggers a vibration with a fixed duration.

On Android, the vibration duration defaults to 400 milliseconds, and an arbitrary vibration duration can be specified by passing a number as the value for the pattern argument. On iOS, the vibration duration is fixed at roughly 400 milliseconds.

The vibrate() method can take a pattern argument with an array of numbers that represent time in milliseconds. You may set repeat to true to run through the vibration pattern in a loop until cancel() is called.

On Android, the odd indices of the pattern array represent the vibration duration, while the even ones represent the separation time. On iOS, the numbers in the pattern array represent the separation time, as the vibration duration is fixed.

Parameters:

NameTypeDefaultDescription
patternnumber
Android
array of numbers		400Vibration duration in milliseconds.
Vibration pattern as an array of numbers in milliseconds.
repeatbooleanfalseRepeat vibration pattern until cancel().
Edit this page
Last updated on
- + diff --git a/docs/next/view-style-props.html b/docs/next/view-style-props.html index 53fd033707b..ef2db72136b 100644 --- a/docs/next/view-style-props.html +++ b/docs/next/view-style-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

View Style Props

Example

Reference

Props

backfaceVisibility

Type
enum('visible', 'hidden')

backgroundColor

Type
color

borderBottomColor

Type
color

borderBottomEndRadius

Type
number

borderBottomLeftRadius

Type
number

borderBottomRightRadius

Type
number

borderBottomStartRadius

Type
number

borderBottomWidth

Type
number

borderColor

Type
color

borderEndColor

Type
color

borderLeftColor

Type
color

borderLeftWidth

Type
number

borderRadius

If the rounded border is not visible, try applying overflow: 'hidden' as well.

Type
number

borderRightColor

Type
color

borderRightWidth

Type
number

borderStartColor

Type
color

borderStyle

Type
enum('solid', 'dotted', 'dashed')

borderTopColor

Type
color

borderTopEndRadius

Type
number

borderTopLeftRadius

Type
number

borderTopRightRadius

Type
number

borderTopStartRadius

Type
number

borderTopWidth

Type
number

borderWidth

Type
number

elevation
Android

Sets the elevation of a view, using Android's underlying elevation API. This adds a drop shadow to the item and affects z-order for overlapping views. Only supported on Android 5.0+, has no effect on earlier versions.

Type
number

opacity

Type
number
Edit this page
Last updated on
- + diff --git a/docs/next/view-style-props/index.html b/docs/next/view-style-props/index.html index 53fd033707b..ef2db72136b 100644 --- a/docs/next/view-style-props/index.html +++ b/docs/next/view-style-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

View Style Props

Example

Reference

Props

backfaceVisibility

Type
enum('visible', 'hidden')

backgroundColor

Type
color

borderBottomColor

Type
color

borderBottomEndRadius

Type
number

borderBottomLeftRadius

Type
number

borderBottomRightRadius

Type
number

borderBottomStartRadius

Type
number

borderBottomWidth

Type
number

borderColor

Type
color

borderEndColor

Type
color

borderLeftColor

Type
color

borderLeftWidth

Type
number

borderRadius

If the rounded border is not visible, try applying overflow: 'hidden' as well.

Type
number

borderRightColor

Type
color

borderRightWidth

Type
number

borderStartColor

Type
color

borderStyle

Type
enum('solid', 'dotted', 'dashed')

borderTopColor

Type
color

borderTopEndRadius

Type
number

borderTopLeftRadius

Type
number

borderTopRightRadius

Type
number

borderTopStartRadius

Type
number

borderTopWidth

Type
number

borderWidth

Type
number

elevation
Android

Sets the elevation of a view, using Android's underlying elevation API. This adds a drop shadow to the item and affects z-order for overlapping views. Only supported on Android 5.0+, has no effect on earlier versions.

Type
number

opacity

Type
number
Edit this page
Last updated on
- + diff --git a/docs/next/view.html b/docs/next/view.html index c2fef59203c..095d48b2e68 100644 --- a/docs/next/view.html +++ b/docs/next/view.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

View

The most fundamental component for building a UI, View is a container that supports layout with flexbox, style, some touch handling, and accessibility controls. View maps directly to the native view equivalent on whatever platform React Native is running on, whether that is a UIView, <div>, android.view, etc.

View is designed to be nested inside other views and can have 0 to many children of any type.

This example creates a View that wraps two boxes with color and a text component in a row with padding.

Views are designed to be used with StyleSheet for clarity and performance, although inline styles are also supported.

Synthetic Touch Events

For View responder props (e.g., onResponderMove), the synthetic touch event passed to them are in form of PressEvent.

Reference

Props

onStartShouldSetResponder

Does this view want to become responder on the start of a touch?

View.props.onStartShouldSetResponder: (event) => [true | false], where event is a PressEvent.

TypeRequired
functionNo

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

  • 'none' - Used when the element has no role.
  • 'button' - Used when the element should be treated as a button.
  • 'link' - Used when the element should be treated as a link.
  • 'search' - Used when the text field element should also be treated as a search field.
  • 'image' - Used when the element should be treated as an image. Can be combined with button or link, for example.
  • 'keyboardkey' - Used when the element acts as a keyboard key.
  • 'text' - Used when the element should be treated as static text that cannot change.
  • 'adjustable' - Used when an element can be "adjusted" (e.g. a slider).
  • 'imagebutton' - Used when the element should be treated as a button and is also an image.
  • 'header' - Used when an element acts as a header for a content section (e.g. the title of a navigation bar).
  • 'summary' - Used when an element can be used to provide a quick summary of current conditions in the app when the app first launches.
  • 'alert' - Used when an element contains important text to be presented to the user.
  • 'checkbox' - Used when an element represents a checkbox which can be checked, unchecked, or have mixed checked state.
  • 'combobox' - Used when an element represents a combo box, which allows the user to select among several choices.
  • 'menu' - Used when the component is a menu of choices.
  • 'menubar' - Used when a component is a container of multiple menus.
  • 'menuitem' - Used to represent an item within a menu.
  • 'progressbar' - Used to represent a component which indicates progress of a task.
  • 'radio' - Used to represent a radio button.
  • 'radiogroup' - Used to represent a group of radio buttons.
  • 'scrollbar' - Used to represent a scroll bar.
  • 'spinbutton' - Used to represent a button which opens a list of choices.
  • 'switch' - Used to represent a switch which can be turned on and off.
  • 'tab' - Used to represent a tab.
  • 'tablist' - Used to represent a list of tabs.
  • 'timer' - Used to represent a timer.
  • 'toolbar' - Used to represent a tool bar (a container of action buttons or components).
TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

accessibilityValue

Represents the current value of a component. It can be a textual description of a component's value, or for range-based components, such as sliders and progress bars, it contains range information (minimum, current, and maximum).

See the Accessibility guide for more information.

TypeRequired
object: {min: number, max: number, now: number, text: string}No

accessibilityActions

Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The accessibilityActions property should contain a list of action objects. Each action object should contain the field name and label.

See the Accessibility guide for more information.

TypeRequired
arrayNo

onAccessibilityAction

Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform.

See the Accessibility guide for more information.

TypeRequired
functionNo

onAccessibilityTap

When accessible is true, the system will try to invoke this function when the user performs accessibility tap gesture.

TypeRequired
functionNo

onMagicTap

When accessible is true, the system will invoke this function when the user performs the magic tap gesture.

TypeRequiredPlatform
functionNoiOS

onAccessibilityEscape

When accessible is true, the system will invoke this function when the user performs the escape gesture.

TypeRequiredPlatform
functionNoiOS

accessibilityViewIsModal

A value indicating whether VoiceOver should ignore the elements within views that are siblings of the receiver. Default is false.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityElementsHidden

A value indicating whether the accessibility elements contained within this accessibility element are hidden. Default is false.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityIgnoresInvertColors

A value indicating this view should or should not be inverted when color inversion is turned on. A value of true will tell the view to not be inverted even if color inversion is turned on.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityLiveRegion

Indicates to accessibility services whether the user should be notified when this view changes. Works for Android API >= 19 only. Possible values:

  • 'none' - Accessibility services should not announce changes to this view.
  • 'polite'- Accessibility services should announce changes to this view.
  • 'assertive' - Accessibility services should interrupt ongoing speech to immediately announce changes to this view.

See the Android View docs for reference.

TypeRequiredPlatform
enum('none', 'polite', 'assertive')NoAndroid

importantForAccessibility

Controls how view is important for accessibility which is if it fires accessibility events and if it is reported to accessibility services that query the screen. Works for Android only.

Possible values:

  • 'auto' - The system determines whether the view is important for accessibility - default (recommended).
  • 'yes' - The view is important for accessibility.
  • 'no' - The view is not important for accessibility.
  • 'no-hide-descendants' - The view is not important for accessibility, nor are any of its descendant views.

See the Android importantForAccessibility docs for reference.

TypeRequiredPlatform
enum('auto', 'yes', 'no', 'no-hide-descendants')NoAndroid

hitSlop

This defines how far a touch event can start away from the view. Typical interface guidelines recommend touch targets that are at least 30 - 40 points/density-independent pixels.

For example, if a touchable view has a height of 20 the touchable height can be extended to 40 with hitSlop={{top: 10, bottom: 10, left: 0, right: 0}}

The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

nativeID

Used to locate this view from native classes.

This disables the 'layout-only view removal' optimization for this view!

TypeRequired
stringNo

onLayout

Invoked on mount and on layout changes.

This event is fired immediately once the layout has been calculated, but the new layout may not yet be reflected on the screen at the time the event is received, especially if a layout animation is in progress.

TypeRequired
(LayoutEvent) => voidNo

onMoveShouldSetResponder

Does this view want to "claim" touch responsiveness? This is called for every touch move on the View when it is not the responder.

View.props.onMoveShouldSetResponder: (event) => [true | false], where event is a PressEvent.

TypeRequired
functionNo

onMoveShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a move, it should have this handler which returns true.

View.props.onMoveShouldSetResponderCapture: (event) => [true | false], where event is a PressEvent.

TypeRequired
functionNo

onResponderGrant

The View is now responding for touch events. This is the time to highlight and show the user what is happening.

View.props.onResponderGrant: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderMove

The user is moving their finger.

View.props.onResponderMove: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderReject

Another responder is already active and will not release it to that View asking to be the responder.

View.props.onResponderReject: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderRelease

Fired at the end of the touch.

View.props.onResponderRelease: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderTerminate

The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS)

View.props.onResponderTerminate: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderTerminationRequest

Some other View wants to become responder and is asking this View to release its responder. Returning true allows its release.

View.props.onResponderTerminationRequest: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onStartShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a touch start, it should have this handler which returns true.

View.props.onStartShouldSetResponderCapture: (event) => [true | false], where event is a PressEvent.

TypeRequired
functionNo

pointerEvents

Controls whether the View can be the target of touch events.

  • 'auto': The View can be the target of touch events.
  • 'none': The View is never the target of touch events.
  • 'box-none': The View is never the target of touch events but its subviews can be. It behaves like if the view had the following classes in CSS:
.box-none {
pointer-events: none;
}
.box-none * {
pointer-events: auto;
}
  • 'box-only': The view can be the target of touch events but its subviews cannot be. It behaves like if the view had the following classes in CSS:
.box-only {
pointer-events: auto;
}
.box-only * {
pointer-events: none;
}

Since pointerEvents does not affect layout/appearance, and we are already deviating from the spec by adding additional modes, we opt to not include pointerEvents on style. On some platforms, we would need to implement it as a className anyways. Using style or not is an implementation detail of the platform.

TypeRequired
enum('box-none', 'none', 'box-only', 'auto')No

removeClippedSubviews

This is a reserved performance property exposed by RCTView and is useful for scrolling content when there are many subviews, most of which are offscreen. For this property to be effective, it must be applied to a view that contains many subviews that extend outside its bound. The subviews must also have overflow: hidden, as should the containing view (or one of its superviews).

TypeRequired
boolNo

style

TypeRequired
View StyleNo

testID

Used to locate this view in end-to-end tests.

This disables the 'layout-only view removal' optimization for this view!

TypeRequired
stringNo

collapsable

Views that are only used to layout their children or otherwise don't draw anything may be automatically removed from the native hierarchy as an optimization. Set this property to false to disable this optimization and ensure that this View exists in the native view hierarchy.

TypeRequiredPlatform
boolNoAndroid

needsOffscreenAlphaCompositing

Whether this View needs to rendered offscreen and composited with an alpha in order to preserve 100% correct colors and blending behavior. The default (false) falls back to drawing the component and its children with an alpha applied to the paint used to draw each element instead of rendering the full component offscreen and compositing it back with an alpha value. This default may be noticeable and undesired in the case where the View you are setting an opacity on has multiple overlapping elements (e.g. multiple overlapping Views, or text and a background).

Rendering offscreen to preserve correct alpha behavior is extremely expensive and hard to debug for non-native developers, which is why it is not turned on by default. If you do need to enable this property for an animation, consider combining it with renderToHardwareTextureAndroid if the view contents are static (i.e. it doesn't need to be redrawn each frame). If that property is enabled, this View will be rendered off-screen once, saved in a hardware texture, and then composited onto the screen with an alpha each frame without having to switch rendering targets on the GPU.

TypeRequired
boolNo

renderToHardwareTextureAndroid

Whether this View should render itself (and all of its children) into a single hardware texture on the GPU.

On Android, this is useful for animations and interactions that only modify opacity, rotation, translation, and/or scale: in those cases, the view doesn't have to be redrawn and display lists don't need to be re-executed. The texture can be re-used and re-composited with different parameters. The downside is that this can use up limited video memory, so this prop should be set back to false at the end of the interaction/animation.

TypeRequiredPlatform
boolNoAndroid

shouldRasterizeIOS

Whether this View should be rendered as a bitmap before compositing.

On iOS, this is useful for animations and interactions that do not modify this component's dimensions nor its children; for example, when translating the position of a static view, rasterization allows the renderer to reuse a cached bitmap of a static view and quickly composite it during each frame.

Rasterization incurs an off-screen drawing pass and the bitmap consumes memory. Test and measure when using this property.

TypeRequiredPlatform
boolNoiOS

nextFocusDown

Designates the next view to receive focus when the user navigates down. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusForward

Designates the next view to receive focus when the user navigates forward. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusLeft

Designates the next view to receive focus when the user navigates left. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusRight

Designates the next view to receive focus when the user navigates right. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusUp

Designates the next view to receive focus when the user navigates up. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

focusable

Whether this View should be focusable with a non-touch input device, eg. receive focus with a hardware keyboard.

TypeRequiredPlatform
booleanNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/next/view/index.html b/docs/next/view/index.html index c2fef59203c..095d48b2e68 100644 --- a/docs/next/view/index.html +++ b/docs/next/view/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

View

The most fundamental component for building a UI, View is a container that supports layout with flexbox, style, some touch handling, and accessibility controls. View maps directly to the native view equivalent on whatever platform React Native is running on, whether that is a UIView, <div>, android.view, etc.

View is designed to be nested inside other views and can have 0 to many children of any type.

This example creates a View that wraps two boxes with color and a text component in a row with padding.

Views are designed to be used with StyleSheet for clarity and performance, although inline styles are also supported.

Synthetic Touch Events

For View responder props (e.g., onResponderMove), the synthetic touch event passed to them are in form of PressEvent.

Reference

Props

onStartShouldSetResponder

Does this view want to become responder on the start of a touch?

View.props.onStartShouldSetResponder: (event) => [true | false], where event is a PressEvent.

TypeRequired
functionNo

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

  • 'none' - Used when the element has no role.
  • 'button' - Used when the element should be treated as a button.
  • 'link' - Used when the element should be treated as a link.
  • 'search' - Used when the text field element should also be treated as a search field.
  • 'image' - Used when the element should be treated as an image. Can be combined with button or link, for example.
  • 'keyboardkey' - Used when the element acts as a keyboard key.
  • 'text' - Used when the element should be treated as static text that cannot change.
  • 'adjustable' - Used when an element can be "adjusted" (e.g. a slider).
  • 'imagebutton' - Used when the element should be treated as a button and is also an image.
  • 'header' - Used when an element acts as a header for a content section (e.g. the title of a navigation bar).
  • 'summary' - Used when an element can be used to provide a quick summary of current conditions in the app when the app first launches.
  • 'alert' - Used when an element contains important text to be presented to the user.
  • 'checkbox' - Used when an element represents a checkbox which can be checked, unchecked, or have mixed checked state.
  • 'combobox' - Used when an element represents a combo box, which allows the user to select among several choices.
  • 'menu' - Used when the component is a menu of choices.
  • 'menubar' - Used when a component is a container of multiple menus.
  • 'menuitem' - Used to represent an item within a menu.
  • 'progressbar' - Used to represent a component which indicates progress of a task.
  • 'radio' - Used to represent a radio button.
  • 'radiogroup' - Used to represent a group of radio buttons.
  • 'scrollbar' - Used to represent a scroll bar.
  • 'spinbutton' - Used to represent a button which opens a list of choices.
  • 'switch' - Used to represent a switch which can be turned on and off.
  • 'tab' - Used to represent a tab.
  • 'tablist' - Used to represent a list of tabs.
  • 'timer' - Used to represent a timer.
  • 'toolbar' - Used to represent a tool bar (a container of action buttons or components).
TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

accessibilityValue

Represents the current value of a component. It can be a textual description of a component's value, or for range-based components, such as sliders and progress bars, it contains range information (minimum, current, and maximum).

See the Accessibility guide for more information.

TypeRequired
object: {min: number, max: number, now: number, text: string}No

accessibilityActions

Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The accessibilityActions property should contain a list of action objects. Each action object should contain the field name and label.

See the Accessibility guide for more information.

TypeRequired
arrayNo

onAccessibilityAction

Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform.

See the Accessibility guide for more information.

TypeRequired
functionNo

onAccessibilityTap

When accessible is true, the system will try to invoke this function when the user performs accessibility tap gesture.

TypeRequired
functionNo

onMagicTap

When accessible is true, the system will invoke this function when the user performs the magic tap gesture.

TypeRequiredPlatform
functionNoiOS

onAccessibilityEscape

When accessible is true, the system will invoke this function when the user performs the escape gesture.

TypeRequiredPlatform
functionNoiOS

accessibilityViewIsModal

A value indicating whether VoiceOver should ignore the elements within views that are siblings of the receiver. Default is false.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityElementsHidden

A value indicating whether the accessibility elements contained within this accessibility element are hidden. Default is false.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityIgnoresInvertColors

A value indicating this view should or should not be inverted when color inversion is turned on. A value of true will tell the view to not be inverted even if color inversion is turned on.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityLiveRegion

Indicates to accessibility services whether the user should be notified when this view changes. Works for Android API >= 19 only. Possible values:

  • 'none' - Accessibility services should not announce changes to this view.
  • 'polite'- Accessibility services should announce changes to this view.
  • 'assertive' - Accessibility services should interrupt ongoing speech to immediately announce changes to this view.

See the Android View docs for reference.

TypeRequiredPlatform
enum('none', 'polite', 'assertive')NoAndroid

importantForAccessibility

Controls how view is important for accessibility which is if it fires accessibility events and if it is reported to accessibility services that query the screen. Works for Android only.

Possible values:

  • 'auto' - The system determines whether the view is important for accessibility - default (recommended).
  • 'yes' - The view is important for accessibility.
  • 'no' - The view is not important for accessibility.
  • 'no-hide-descendants' - The view is not important for accessibility, nor are any of its descendant views.

See the Android importantForAccessibility docs for reference.

TypeRequiredPlatform
enum('auto', 'yes', 'no', 'no-hide-descendants')NoAndroid

hitSlop

This defines how far a touch event can start away from the view. Typical interface guidelines recommend touch targets that are at least 30 - 40 points/density-independent pixels.

For example, if a touchable view has a height of 20 the touchable height can be extended to 40 with hitSlop={{top: 10, bottom: 10, left: 0, right: 0}}

The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

nativeID

Used to locate this view from native classes.

This disables the 'layout-only view removal' optimization for this view!

TypeRequired
stringNo

onLayout

Invoked on mount and on layout changes.

This event is fired immediately once the layout has been calculated, but the new layout may not yet be reflected on the screen at the time the event is received, especially if a layout animation is in progress.

TypeRequired
(LayoutEvent) => voidNo

onMoveShouldSetResponder

Does this view want to "claim" touch responsiveness? This is called for every touch move on the View when it is not the responder.

View.props.onMoveShouldSetResponder: (event) => [true | false], where event is a PressEvent.

TypeRequired
functionNo

onMoveShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a move, it should have this handler which returns true.

View.props.onMoveShouldSetResponderCapture: (event) => [true | false], where event is a PressEvent.

TypeRequired
functionNo

onResponderGrant

The View is now responding for touch events. This is the time to highlight and show the user what is happening.

View.props.onResponderGrant: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderMove

The user is moving their finger.

View.props.onResponderMove: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderReject

Another responder is already active and will not release it to that View asking to be the responder.

View.props.onResponderReject: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderRelease

Fired at the end of the touch.

View.props.onResponderRelease: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderTerminate

The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS)

View.props.onResponderTerminate: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderTerminationRequest

Some other View wants to become responder and is asking this View to release its responder. Returning true allows its release.

View.props.onResponderTerminationRequest: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onStartShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a touch start, it should have this handler which returns true.

View.props.onStartShouldSetResponderCapture: (event) => [true | false], where event is a PressEvent.

TypeRequired
functionNo

pointerEvents

Controls whether the View can be the target of touch events.

  • 'auto': The View can be the target of touch events.
  • 'none': The View is never the target of touch events.
  • 'box-none': The View is never the target of touch events but its subviews can be. It behaves like if the view had the following classes in CSS:
.box-none {
pointer-events: none;
}
.box-none * {
pointer-events: auto;
}
  • 'box-only': The view can be the target of touch events but its subviews cannot be. It behaves like if the view had the following classes in CSS:
.box-only {
pointer-events: auto;
}
.box-only * {
pointer-events: none;
}

Since pointerEvents does not affect layout/appearance, and we are already deviating from the spec by adding additional modes, we opt to not include pointerEvents on style. On some platforms, we would need to implement it as a className anyways. Using style or not is an implementation detail of the platform.

TypeRequired
enum('box-none', 'none', 'box-only', 'auto')No

removeClippedSubviews

This is a reserved performance property exposed by RCTView and is useful for scrolling content when there are many subviews, most of which are offscreen. For this property to be effective, it must be applied to a view that contains many subviews that extend outside its bound. The subviews must also have overflow: hidden, as should the containing view (or one of its superviews).

TypeRequired
boolNo

style

TypeRequired
View StyleNo

testID

Used to locate this view in end-to-end tests.

This disables the 'layout-only view removal' optimization for this view!

TypeRequired
stringNo

collapsable

Views that are only used to layout their children or otherwise don't draw anything may be automatically removed from the native hierarchy as an optimization. Set this property to false to disable this optimization and ensure that this View exists in the native view hierarchy.

TypeRequiredPlatform
boolNoAndroid

needsOffscreenAlphaCompositing

Whether this View needs to rendered offscreen and composited with an alpha in order to preserve 100% correct colors and blending behavior. The default (false) falls back to drawing the component and its children with an alpha applied to the paint used to draw each element instead of rendering the full component offscreen and compositing it back with an alpha value. This default may be noticeable and undesired in the case where the View you are setting an opacity on has multiple overlapping elements (e.g. multiple overlapping Views, or text and a background).

Rendering offscreen to preserve correct alpha behavior is extremely expensive and hard to debug for non-native developers, which is why it is not turned on by default. If you do need to enable this property for an animation, consider combining it with renderToHardwareTextureAndroid if the view contents are static (i.e. it doesn't need to be redrawn each frame). If that property is enabled, this View will be rendered off-screen once, saved in a hardware texture, and then composited onto the screen with an alpha each frame without having to switch rendering targets on the GPU.

TypeRequired
boolNo

renderToHardwareTextureAndroid

Whether this View should render itself (and all of its children) into a single hardware texture on the GPU.

On Android, this is useful for animations and interactions that only modify opacity, rotation, translation, and/or scale: in those cases, the view doesn't have to be redrawn and display lists don't need to be re-executed. The texture can be re-used and re-composited with different parameters. The downside is that this can use up limited video memory, so this prop should be set back to false at the end of the interaction/animation.

TypeRequiredPlatform
boolNoAndroid

shouldRasterizeIOS

Whether this View should be rendered as a bitmap before compositing.

On iOS, this is useful for animations and interactions that do not modify this component's dimensions nor its children; for example, when translating the position of a static view, rasterization allows the renderer to reuse a cached bitmap of a static view and quickly composite it during each frame.

Rasterization incurs an off-screen drawing pass and the bitmap consumes memory. Test and measure when using this property.

TypeRequiredPlatform
boolNoiOS

nextFocusDown

Designates the next view to receive focus when the user navigates down. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusForward

Designates the next view to receive focus when the user navigates forward. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusLeft

Designates the next view to receive focus when the user navigates left. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusRight

Designates the next view to receive focus when the user navigates right. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusUp

Designates the next view to receive focus when the user navigates up. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

focusable

Whether this View should be focusable with a non-touch input device, eg. receive focus with a hardware keyboard.

TypeRequiredPlatform
booleanNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/next/viewpagerandroid.html b/docs/next/viewpagerandroid.html index 296b1954b34..c582da70393 100644 --- a/docs/next/viewpagerandroid.html +++ b/docs/next/viewpagerandroid.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
const styles = {
...
viewPager: {
flex: 1
},
pageStyle: {
alignItems: 'center',
padding: 20,
}
}

Reference

Props

Inherits View Props.

initialPage

Index of initial page that should be selected. Use setPage method to update the page, and onPageSelected to monitor page changes

TypeRequired
numberNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

TypeRequired
enum('none', 'on-drag')No

onPageScroll

Executed when transitioning between pages (either because of animation for the requested page change or when user is swiping/dragging between pages) The event.nativeEvent object for this callback will carry following data:

TypeRequired
functionNo

onPageScrollStateChanged

Function called when the page scrolling state has changed. The page scrolling state can be in 3 states:

TypeRequired
functionNo

onPageSelected

This callback will be called once ViewPager finish navigating to selected page (when user swipes between pages). The event.nativeEvent object passed to this callback will have following fields:

TypeRequired
functionNo

pageMargin

Blank space to show between pages. This is only visible while scrolling, pages are still edge-to-edge.

TypeRequired
numberNo

peekEnabled

Whether enable showing peekFraction or not. If this is true, the preview of last and next page will show in current screen. Defaults to false.

TypeRequired
boolNo

scrollEnabled

When false, the content does not scroll. The default value is true.

TypeRequired
boolNo

setPage

A helper function to scroll to a specific page in the ViewPager. The transition between pages will be animated.

TypeRequired
NumberYes

setPageWithoutAnimation

A helper function to scroll to a specific page in the ViewPager. The transition between pages will not be animated.

TypeRequired
NumberYes

Type Definitions

ViewPagerScrollState

Type
\$Enum

Constants:

ValueDescription
idle
dragging
settling
Edit this page
Last updated on
- + diff --git a/docs/next/viewpagerandroid/index.html b/docs/next/viewpagerandroid/index.html index 296b1954b34..c582da70393 100644 --- a/docs/next/viewpagerandroid/index.html +++ b/docs/next/viewpagerandroid/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
const styles = {
...
viewPager: {
flex: 1
},
pageStyle: {
alignItems: 'center',
padding: 20,
}
}

Reference

Props

Inherits View Props.

initialPage

Index of initial page that should be selected. Use setPage method to update the page, and onPageSelected to monitor page changes

TypeRequired
numberNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

TypeRequired
enum('none', 'on-drag')No

onPageScroll

Executed when transitioning between pages (either because of animation for the requested page change or when user is swiping/dragging between pages) The event.nativeEvent object for this callback will carry following data:

TypeRequired
functionNo

onPageScrollStateChanged

Function called when the page scrolling state has changed. The page scrolling state can be in 3 states:

TypeRequired
functionNo

onPageSelected

This callback will be called once ViewPager finish navigating to selected page (when user swipes between pages). The event.nativeEvent object passed to this callback will have following fields:

TypeRequired
functionNo

pageMargin

Blank space to show between pages. This is only visible while scrolling, pages are still edge-to-edge.

TypeRequired
numberNo

peekEnabled

Whether enable showing peekFraction or not. If this is true, the preview of last and next page will show in current screen. Defaults to false.

TypeRequired
boolNo

scrollEnabled

When false, the content does not scroll. The default value is true.

TypeRequired
boolNo

setPage

A helper function to scroll to a specific page in the ViewPager. The transition between pages will be animated.

TypeRequired
NumberYes

setPageWithoutAnimation

A helper function to scroll to a specific page in the ViewPager. The transition between pages will not be animated.

TypeRequired
NumberYes

Type Definitions

ViewPagerScrollState

Type
\$Enum

Constants:

ValueDescription
idle
dragging
settling
Edit this page
Last updated on
- + diff --git a/docs/next/viewtoken.html b/docs/next/viewtoken.html index f27fb133033..04f9bf5cc83 100644 --- a/docs/next/viewtoken.html +++ b/docs/next/viewtoken.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

ViewToken Object Type

ViewToken object is returned as one of properties in the onViewableItemsChanged callback, for example in FlatList component. It is exported by ViewabilityHelper.js.

Example

{
item: { key: "key-12" },
key: "key-12",
index: 11,
isViewable: true
}

Keys and values

index

Unique numeric identifier assigned to the data element.

TypeOptional
numberYes

isViewable

Specifies if at least some part of list element is visible in the viewport.

TypeOptional
booleanNo

item

Item data

TypeOptional
anyNo

key

Key identifier assigned of the data element extracted to the top level.

TypeOptional
stringNo

section

Item section data when used with SectionList.

TypeOptional
anyYes

Used by

Edit this page
Last updated on
- + diff --git a/docs/next/viewtoken/index.html b/docs/next/viewtoken/index.html index f27fb133033..04f9bf5cc83 100644 --- a/docs/next/viewtoken/index.html +++ b/docs/next/viewtoken/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Version: Next

ViewToken Object Type

ViewToken object is returned as one of properties in the onViewableItemsChanged callback, for example in FlatList component. It is exported by ViewabilityHelper.js.

Example

{
item: { key: "key-12" },
key: "key-12",
index: 11,
isViewable: true
}

Keys and values

index

Unique numeric identifier assigned to the data element.

TypeOptional
numberYes

isViewable

Specifies if at least some part of list element is visible in the viewport.

TypeOptional
booleanNo

item

Item data

TypeOptional
anyNo

key

Key identifier assigned of the data element extracted to the top level.

TypeOptional
stringNo

section

Item section data when used with SectionList.

TypeOptional
anyYes

Used by

Edit this page
Last updated on
- + diff --git a/docs/next/virtualizedlist.html b/docs/next/virtualizedlist.html index ea4cb4c3280..170b67399aa 100644 --- a/docs/next/virtualizedlist.html +++ b/docs/next/virtualizedlist.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
- 'animated' (boolean). Optional default is true.

scrollToIndex()

scrollToIndex((params: object));

Valid params consist of:

scrollToItem()

scrollToItem((params: object));

Valid params consist of:

scrollToOffset()

scrollToOffset((params: object));

Scroll to a specific content pixel offset in the list.

Param offset expects the offset to scroll to. In case of horizontal is true, the offset is the x-value, in any other case the offset is the y-value.

Param animated (true by default) defines whether the list should do an animation while scrolling.

recordInteraction()

recordInteraction();

setNativeProps()

setNativeProps((props: Object));
Edit this page
Last updated on
- + diff --git a/docs/next/virtualizedlist/index.html b/docs/next/virtualizedlist/index.html index ea4cb4c3280..170b67399aa 100644 --- a/docs/next/virtualizedlist/index.html +++ b/docs/next/virtualizedlist/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
- 'animated' (boolean). Optional default is true.

scrollToIndex()

scrollToIndex((params: object));

Valid params consist of:

scrollToItem()

scrollToItem((params: object));

Valid params consist of:

scrollToOffset()

scrollToOffset((params: object));

Scroll to a specific content pixel offset in the list.

Param offset expects the offset to scroll to. In case of horizontal is true, the offset is the x-value, in any other case the offset is the y-value.

Param animated (true by default) defines whether the list should do an animation while scrolling.

recordInteraction()

recordInteraction();

setNativeProps()

setNativeProps((props: Object));
Edit this page
Last updated on
- + diff --git a/docs/optimizing-flatlist-configuration.html b/docs/optimizing-flatlist-configuration.html index 97aca80de3b..a835ceaab0d 100644 --- a/docs/optimizing-flatlist-configuration.html +++ b/docs/optimizing-flatlist-configuration.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// ...
}
Edit this page
Last updated on
- + diff --git a/docs/optimizing-flatlist-configuration/index.html b/docs/optimizing-flatlist-configuration/index.html index 97aca80de3b..a835ceaab0d 100644 --- a/docs/optimizing-flatlist-configuration/index.html +++ b/docs/optimizing-flatlist-configuration/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
// ...
}
Edit this page
Last updated on
- + diff --git a/docs/out-of-tree-platforms.html b/docs/out-of-tree-platforms.html index 1a31b86d06b..9a3f5783836 100644 --- a/docs/out-of-tree-platforms.html +++ b/docs/out-of-tree-platforms.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Out-of-Tree Platforms

React Native is not only for Android and iOS - there are community-supported projects that bring it to other platforms, such as:

  • React Native Windows - React Native support for Microsoft's Universal Windows Platform (UWP) and the Windows Presentation Foundation (WPF)
  • React Native DOM - An experimental, comprehensive port of React Native to the web. (Not to be confused with React Native Web, which has different goals)
  • React Native Turbolinks - React Native adapter for building hybrid apps with Turbolinks 5.
  • React Native Desktop - A project aiming to bring React Native to the Desktop with Qt's QML. A fork of React Native Ubuntu, which is no longer maintained.
  • React Native macOS - An experimental React Native fork targeting macOS and Cocoa
  • React Native tvOS - adaptation of React Native for Apple tvOS
  • alita - An experimental, comprehensive port of React Native to mini-program(微信小程序).
  • Proton Native - A wrapper for React Native, using Qt to target Linux, MacOS, and Windows.

Creating your own React Native platform

Right now the process of creating a React Native platform from scratch is not very well documented - one of the goals of the upcoming re-architecture (Fabric) is to make maintaining a platform easier.

Bundling

As of React Native 0.57 you can now register your React Native platform with React Native's JavaScript bundler, Metro. This means you can pass --platform example to npx react-native bundle, and it will look for JavaScript files with the .example.js suffix.

To register your platform with RNPM, your module's name must match one of these patterns:

  • react-native-example - It will search all top-level modules that start with react-native-
  • @org/react-native-example - It will search for modules that start with react-native- under any scope
  • @react-native-example/module - It will search in all modules under scopes with names starting with @react-native-

You must also have an entry in your package.json like this:

{
"rnpm": {
"haste": {
"providesModuleNodeModules": ["react-native-example"],
"platforms": ["example"]
}
}
}

"providesModuleNodeModules" is an array of modules that will get added to the Haste module search path, and "platforms" is an array of platform suffixes that will be added as valid platforms.

Edit this page
Last updated on
- + diff --git a/docs/out-of-tree-platforms/index.html b/docs/out-of-tree-platforms/index.html index 1a31b86d06b..9a3f5783836 100644 --- a/docs/out-of-tree-platforms/index.html +++ b/docs/out-of-tree-platforms/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Out-of-Tree Platforms

React Native is not only for Android and iOS - there are community-supported projects that bring it to other platforms, such as:

  • React Native Windows - React Native support for Microsoft's Universal Windows Platform (UWP) and the Windows Presentation Foundation (WPF)
  • React Native DOM - An experimental, comprehensive port of React Native to the web. (Not to be confused with React Native Web, which has different goals)
  • React Native Turbolinks - React Native adapter for building hybrid apps with Turbolinks 5.
  • React Native Desktop - A project aiming to bring React Native to the Desktop with Qt's QML. A fork of React Native Ubuntu, which is no longer maintained.
  • React Native macOS - An experimental React Native fork targeting macOS and Cocoa
  • React Native tvOS - adaptation of React Native for Apple tvOS
  • alita - An experimental, comprehensive port of React Native to mini-program(微信小程序).
  • Proton Native - A wrapper for React Native, using Qt to target Linux, MacOS, and Windows.

Creating your own React Native platform

Right now the process of creating a React Native platform from scratch is not very well documented - one of the goals of the upcoming re-architecture (Fabric) is to make maintaining a platform easier.

Bundling

As of React Native 0.57 you can now register your React Native platform with React Native's JavaScript bundler, Metro. This means you can pass --platform example to npx react-native bundle, and it will look for JavaScript files with the .example.js suffix.

To register your platform with RNPM, your module's name must match one of these patterns:

  • react-native-example - It will search all top-level modules that start with react-native-
  • @org/react-native-example - It will search for modules that start with react-native- under any scope
  • @react-native-example/module - It will search in all modules under scopes with names starting with @react-native-

You must also have an entry in your package.json like this:

{
"rnpm": {
"haste": {
"providesModuleNodeModules": ["react-native-example"],
"platforms": ["example"]
}
}
}

"providesModuleNodeModules" is an array of modules that will get added to the Haste module search path, and "platforms" is an array of platform suffixes that will be added as valid platforms.

Edit this page
Last updated on
- + diff --git a/docs/panresponder.html b/docs/panresponder.html index 3e0deab189a..f7e35c84f15 100644 --- a/docs/panresponder.html +++ b/docs/panresponder.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
return <View {...panResponder.panHandlers} />;
};

Example

PanResponder works with Animated API to help build complex gestures in the UI. The following example contains an animated View component which can be dragged freely across the screen

Try the PanResponder example in RNTester.

Reference

Methods

create()

static create(config)

Parameters:

NameTypeRequiredDescription
configobjectYesRefer below

The config object provides enhanced versions of all of the responder callbacks that provide not only the PressEvent, but also the PanResponder gesture state, by replacing the word Responder with PanResponder in each of the typical onResponder* callbacks. For example, the config object would look like:

In general, for events that have capture equivalents, we update the gestureState once in the capture phase and can use it in the bubble phase as well.

Be careful with onStartShould* callbacks. They only reflect updated gestureState for start/end events that bubble/capture to the Node. Once the node is the responder, you can rely on every start/end event being processed by the gesture and gestureState being updated accordingly. (numberActiveTouches) may not be totally accurate unless you are the responder.

Edit this page
Last updated on
- + diff --git a/docs/panresponder/index.html b/docs/panresponder/index.html index 3e0deab189a..f7e35c84f15 100644 --- a/docs/panresponder/index.html +++ b/docs/panresponder/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
return <View {...panResponder.panHandlers} />;
};

Example

PanResponder works with Animated API to help build complex gestures in the UI. The following example contains an animated View component which can be dragged freely across the screen

Try the PanResponder example in RNTester.

Reference

Methods

create()

static create(config)

Parameters:

NameTypeRequiredDescription
configobjectYesRefer below

The config object provides enhanced versions of all of the responder callbacks that provide not only the PressEvent, but also the PanResponder gesture state, by replacing the word Responder with PanResponder in each of the typical onResponder* callbacks. For example, the config object would look like:

In general, for events that have capture equivalents, we update the gestureState once in the capture phase and can use it in the bubble phase as well.

Be careful with onStartShould* callbacks. They only reflect updated gestureState for start/end events that bubble/capture to the Node. Once the node is the responder, you can rely on every start/end event being processed by the gesture and gestureState being updated accordingly. (numberActiveTouches) may not be totally accurate unless you are the responder.

Edit this page
Last updated on
- + diff --git a/docs/performance.html b/docs/performance.html index 09932823237..8b66846814f 100644 --- a/docs/performance.html +++ b/docs/performance.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Performance Overview

A compelling reason for using React Native instead of WebView-based tools is to achieve 60 frames per second and a native look and feel to your apps. Where possible, we would like for React Native to do the right thing and help you to focus on your app instead of performance optimization, but there are areas where we're not quite there yet, and others where React Native (similar to writing native code directly) cannot possibly determine the best way to optimize for you and so manual intervention will be necessary. We try our best to deliver buttery-smooth UI performance by default, but sometimes that isn't possible.

This guide is intended to teach you some basics to help you to troubleshoot performance issues, as well as discuss common sources of problems and their suggested solutions.

What you need to know about frames

Your grandparents' generation called movies "moving pictures" for a reason: realistic motion in video is an illusion created by quickly changing static images at a consistent speed. We refer to each of these images as frames. The number of frames that is displayed each second has a direct impact on how smooth and ultimately life-like a video (or user interface) seems to be. iOS devices display 60 frames per second, which gives you and the UI system about 16.67ms to do all of the work needed to generate the static image (frame) that the user will see on the screen for that interval. If you are unable to do the work necessary to generate that frame within the allotted 16.67ms, then you will "drop a frame" and the UI will appear unresponsive.

Now to confuse the matter a little bit, open up the developer menu in your app and toggle Show Perf Monitor. You will notice that there are two different frame rates.

JS frame rate (JavaScript thread)

For most React Native applications, your business logic will run on the JavaScript thread. This is where your React application lives, API calls are made, touch events are processed, etc... Updates to native-backed views are batched and sent over to the native side at the end of each iteration of the event loop, before the frame deadline (if all goes well). If the JavaScript thread is unresponsive for a frame, it will be considered a dropped frame. For example, if you were to call this.setState on the root component of a complex application and it resulted in re-rendering computationally expensive component subtrees, it's conceivable that this might take 200ms and result in 12 frames being dropped. Any animations controlled by JavaScript would appear to freeze during that time. If anything takes longer than 100ms, the user will feel it.

This often happens during Navigator transitions: when you push a new route, the JavaScript thread needs to render all of the components necessary for the scene in order to send over the proper commands to the native side to create the backing views. It's common for the work being done here to take a few frames and cause jank because the transition is controlled by the JavaScript thread. Sometimes components will do additional work on componentDidMount, which might result in a second stutter in the transition.

Another example is responding to touches: if you are doing work across multiple frames on the JavaScript thread, you might notice a delay in responding to TouchableOpacity, for example. This is because the JavaScript thread is busy and cannot process the raw touch events sent over from the main thread. As a result, TouchableOpacity cannot react to the touch events and command the native view to adjust its opacity.

UI frame rate (main thread)

Many people have noticed that performance of NavigatorIOS is better out of the box than Navigator. The reason for this is that the animations for the transitions are done entirely on the main thread, and so they are not interrupted by frame drops on the JavaScript thread.

Similarly, you can happily scroll up and down through a ScrollView when the JavaScript thread is locked up because the ScrollView lives on the main thread. The scroll events are dispatched to the JS thread, but their receipt is not necessary for the scroll to occur.

Common sources of performance problems

Running in development mode (dev=true)

JavaScript thread performance suffers greatly when running in dev mode. This is unavoidable: a lot more work needs to be done at runtime to provide you with good warnings and error messages, such as validating propTypes and various other assertions. Always make sure to test performance in release builds.

Using console.log statements

When running a bundled app, these statements can cause a big bottleneck in the JavaScript thread. This includes calls from debugging libraries such as redux-logger, so make sure to remove them before bundling. You can also use this babel plugin that removes all the console.* calls. You need to install it first with npm i babel-plugin-transform-remove-console --save-dev, and then edit the .babelrc file under your project directory like this:

{
"env": {
"production": {
"plugins": ["transform-remove-console"]
}
}
}

This will automatically remove all console.* calls in the release (production) versions of your project.

ListView initial rendering is too slow or scroll performance is bad for large lists

Use the new FlatList or SectionList component instead. Besides simplifying the API, the new list components also have significant performance enhancements, the main one being nearly constant memory usage for any number of rows.

If your FlatList is rendering slow, be sure that you've implemented getItemLayout to optimize rendering speed by skipping measurement of the rendered items.

JS FPS plunges when re-rendering a view that hardly changes

If you are using a ListView, you must provide a rowHasChanged function that can reduce a lot of work by quickly determining whether or not a row needs to be re-rendered. If you are using immutable data structures, this would only need to be a reference equality check.

Similarly, you can implement shouldComponentUpdate and indicate the exact conditions under which you would like the component to re-render. If you write pure components (where the return value of the render function is entirely dependent on props and state), you can leverage PureComponent to do this for you. Once again, immutable data structures are useful to keep this fast -- if you have to do a deep comparison of a large list of objects, it may be that re-rendering your entire component would be quicker, and it would certainly require less code.

Dropping JS thread FPS because of doing a lot of work on the JavaScript thread at the same time

"Slow Navigator transitions" is the most common manifestation of this, but there are other times this can happen. Using InteractionManager can be a good approach, but if the user experience cost is too high to delay work during an animation, then you might want to consider LayoutAnimation.

The Animated API currently calculates each keyframe on-demand on the JavaScript thread unless you set useNativeDriver: true, while LayoutAnimation leverages Core Animation and is unaffected by JS thread and main thread frame drops.

One case where I have used this is for animating in a modal (sliding down from top and fading in a translucent overlay) while initializing and perhaps receiving responses for several network requests, rendering the contents of the modal, and updating the view where the modal was opened from. See the Animations guide for more information about how to use LayoutAnimation.

Caveats:

  • LayoutAnimation only works for fire-and-forget animations ("static" animations) -- if it must be interruptible, you will need to use Animated.

Moving a view on the screen (scrolling, translating, rotating) drops UI thread FPS

This is especially true when you have text with a transparent background positioned on top of an image, or any other situation where alpha compositing would be required to re-draw the view on each frame. You will find that enabling shouldRasterizeIOS or renderToHardwareTextureAndroid can help with this significantly.

Be careful not to overuse this or your memory usage could go through the roof. Profile your performance and memory usage when using these props. If you don't plan to move a view anymore, turn this property off.

Animating the size of an image drops UI thread FPS

On iOS, each time you adjust the width or height of an Image component it is re-cropped and scaled from the original image. This can be very expensive, especially for large images. Instead, use the transform: [{scale}] style property to animate the size. An example of when you might do this is when you tap an image and zoom it in to full screen.

My TouchableX view isn't very responsive

Sometimes, if we do an action in the same frame that we are adjusting the opacity or highlight of a component that is responding to a touch, we won't see that effect until after the onPress function has returned. If onPress does a setState that results in a lot of work and a few frames dropped, this may occur. A solution to this is to wrap any action inside of your onPress handler in requestAnimationFrame:

handleOnPress() {
requestAnimationFrame(() => {
this.doExpensiveAction();
});
}

Slow navigator transitions

As mentioned above, Navigator animations are controlled by the JavaScript thread. Imagine the "push from right" scene transition: each frame, the new scene is moved from the right to left, starting offscreen (let's say at an x-offset of 320) and ultimately settling when the scene sits at an x-offset of 0. Each frame during this transition, the JavaScript thread needs to send a new x-offset to the main thread. If the JavaScript thread is locked up, it cannot do this and so no update occurs on that frame and the animation stutters.

One solution to this is to allow for JavaScript-based animations to be offloaded to the main thread. If we were to do the same thing as in the above example with this approach, we might calculate a list of all x-offsets for the new scene when we are starting the transition and send them to the main thread to execute in an optimized way. Now that the JavaScript thread is freed of this responsibility, it's not a big deal if it drops a few frames while rendering the scene -- you probably won't even notice because you will be too distracted by the pretty transition.

Solving this is one of the main goals behind the new React Navigation library. The views in React Navigation use native components and the Animated library to deliver 60 FPS animations that are run on the native thread.

Edit this page
Last updated on
- + diff --git a/docs/performance/index.html b/docs/performance/index.html index 09932823237..8b66846814f 100644 --- a/docs/performance/index.html +++ b/docs/performance/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Performance Overview

A compelling reason for using React Native instead of WebView-based tools is to achieve 60 frames per second and a native look and feel to your apps. Where possible, we would like for React Native to do the right thing and help you to focus on your app instead of performance optimization, but there are areas where we're not quite there yet, and others where React Native (similar to writing native code directly) cannot possibly determine the best way to optimize for you and so manual intervention will be necessary. We try our best to deliver buttery-smooth UI performance by default, but sometimes that isn't possible.

This guide is intended to teach you some basics to help you to troubleshoot performance issues, as well as discuss common sources of problems and their suggested solutions.

What you need to know about frames

Your grandparents' generation called movies "moving pictures" for a reason: realistic motion in video is an illusion created by quickly changing static images at a consistent speed. We refer to each of these images as frames. The number of frames that is displayed each second has a direct impact on how smooth and ultimately life-like a video (or user interface) seems to be. iOS devices display 60 frames per second, which gives you and the UI system about 16.67ms to do all of the work needed to generate the static image (frame) that the user will see on the screen for that interval. If you are unable to do the work necessary to generate that frame within the allotted 16.67ms, then you will "drop a frame" and the UI will appear unresponsive.

Now to confuse the matter a little bit, open up the developer menu in your app and toggle Show Perf Monitor. You will notice that there are two different frame rates.

JS frame rate (JavaScript thread)

For most React Native applications, your business logic will run on the JavaScript thread. This is where your React application lives, API calls are made, touch events are processed, etc... Updates to native-backed views are batched and sent over to the native side at the end of each iteration of the event loop, before the frame deadline (if all goes well). If the JavaScript thread is unresponsive for a frame, it will be considered a dropped frame. For example, if you were to call this.setState on the root component of a complex application and it resulted in re-rendering computationally expensive component subtrees, it's conceivable that this might take 200ms and result in 12 frames being dropped. Any animations controlled by JavaScript would appear to freeze during that time. If anything takes longer than 100ms, the user will feel it.

This often happens during Navigator transitions: when you push a new route, the JavaScript thread needs to render all of the components necessary for the scene in order to send over the proper commands to the native side to create the backing views. It's common for the work being done here to take a few frames and cause jank because the transition is controlled by the JavaScript thread. Sometimes components will do additional work on componentDidMount, which might result in a second stutter in the transition.

Another example is responding to touches: if you are doing work across multiple frames on the JavaScript thread, you might notice a delay in responding to TouchableOpacity, for example. This is because the JavaScript thread is busy and cannot process the raw touch events sent over from the main thread. As a result, TouchableOpacity cannot react to the touch events and command the native view to adjust its opacity.

UI frame rate (main thread)

Many people have noticed that performance of NavigatorIOS is better out of the box than Navigator. The reason for this is that the animations for the transitions are done entirely on the main thread, and so they are not interrupted by frame drops on the JavaScript thread.

Similarly, you can happily scroll up and down through a ScrollView when the JavaScript thread is locked up because the ScrollView lives on the main thread. The scroll events are dispatched to the JS thread, but their receipt is not necessary for the scroll to occur.

Common sources of performance problems

Running in development mode (dev=true)

JavaScript thread performance suffers greatly when running in dev mode. This is unavoidable: a lot more work needs to be done at runtime to provide you with good warnings and error messages, such as validating propTypes and various other assertions. Always make sure to test performance in release builds.

Using console.log statements

When running a bundled app, these statements can cause a big bottleneck in the JavaScript thread. This includes calls from debugging libraries such as redux-logger, so make sure to remove them before bundling. You can also use this babel plugin that removes all the console.* calls. You need to install it first with npm i babel-plugin-transform-remove-console --save-dev, and then edit the .babelrc file under your project directory like this:

{
"env": {
"production": {
"plugins": ["transform-remove-console"]
}
}
}

This will automatically remove all console.* calls in the release (production) versions of your project.

ListView initial rendering is too slow or scroll performance is bad for large lists

Use the new FlatList or SectionList component instead. Besides simplifying the API, the new list components also have significant performance enhancements, the main one being nearly constant memory usage for any number of rows.

If your FlatList is rendering slow, be sure that you've implemented getItemLayout to optimize rendering speed by skipping measurement of the rendered items.

JS FPS plunges when re-rendering a view that hardly changes

If you are using a ListView, you must provide a rowHasChanged function that can reduce a lot of work by quickly determining whether or not a row needs to be re-rendered. If you are using immutable data structures, this would only need to be a reference equality check.

Similarly, you can implement shouldComponentUpdate and indicate the exact conditions under which you would like the component to re-render. If you write pure components (where the return value of the render function is entirely dependent on props and state), you can leverage PureComponent to do this for you. Once again, immutable data structures are useful to keep this fast -- if you have to do a deep comparison of a large list of objects, it may be that re-rendering your entire component would be quicker, and it would certainly require less code.

Dropping JS thread FPS because of doing a lot of work on the JavaScript thread at the same time

"Slow Navigator transitions" is the most common manifestation of this, but there are other times this can happen. Using InteractionManager can be a good approach, but if the user experience cost is too high to delay work during an animation, then you might want to consider LayoutAnimation.

The Animated API currently calculates each keyframe on-demand on the JavaScript thread unless you set useNativeDriver: true, while LayoutAnimation leverages Core Animation and is unaffected by JS thread and main thread frame drops.

One case where I have used this is for animating in a modal (sliding down from top and fading in a translucent overlay) while initializing and perhaps receiving responses for several network requests, rendering the contents of the modal, and updating the view where the modal was opened from. See the Animations guide for more information about how to use LayoutAnimation.

Caveats:

  • LayoutAnimation only works for fire-and-forget animations ("static" animations) -- if it must be interruptible, you will need to use Animated.

Moving a view on the screen (scrolling, translating, rotating) drops UI thread FPS

This is especially true when you have text with a transparent background positioned on top of an image, or any other situation where alpha compositing would be required to re-draw the view on each frame. You will find that enabling shouldRasterizeIOS or renderToHardwareTextureAndroid can help with this significantly.

Be careful not to overuse this or your memory usage could go through the roof. Profile your performance and memory usage when using these props. If you don't plan to move a view anymore, turn this property off.

Animating the size of an image drops UI thread FPS

On iOS, each time you adjust the width or height of an Image component it is re-cropped and scaled from the original image. This can be very expensive, especially for large images. Instead, use the transform: [{scale}] style property to animate the size. An example of when you might do this is when you tap an image and zoom it in to full screen.

My TouchableX view isn't very responsive

Sometimes, if we do an action in the same frame that we are adjusting the opacity or highlight of a component that is responding to a touch, we won't see that effect until after the onPress function has returned. If onPress does a setState that results in a lot of work and a few frames dropped, this may occur. A solution to this is to wrap any action inside of your onPress handler in requestAnimationFrame:

handleOnPress() {
requestAnimationFrame(() => {
this.doExpensiveAction();
});
}

Slow navigator transitions

As mentioned above, Navigator animations are controlled by the JavaScript thread. Imagine the "push from right" scene transition: each frame, the new scene is moved from the right to left, starting offscreen (let's say at an x-offset of 320) and ultimately settling when the scene sits at an x-offset of 0. Each frame during this transition, the JavaScript thread needs to send a new x-offset to the main thread. If the JavaScript thread is locked up, it cannot do this and so no update occurs on that frame and the animation stutters.

One solution to this is to allow for JavaScript-based animations to be offloaded to the main thread. If we were to do the same thing as in the above example with this approach, we might calculate a list of all x-offsets for the new scene when we are starting the transition and send them to the main thread to execute in an optimized way. Now that the JavaScript thread is freed of this responsibility, it's not a big deal if it drops a few frames while rendering the scene -- you probably won't even notice because you will be too distracted by the pretty transition.

Solving this is one of the main goals behind the new React Navigation library. The views in React Navigation use native components and the Animated library to deliver 60 FPS animations that are run on the native thread.

Edit this page
Last updated on
- + diff --git a/docs/permissionsandroid.html b/docs/permissionsandroid.html index 64bc5ea41ae..57b6cef014d 100644 --- a/docs/permissionsandroid.html +++ b/docs/permissionsandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

PermissionsAndroid

PermissionsAndroid provides access to Android M's new permissions model. The so-called "normal" permissions are granted by default when the application is installed as long as they appear in AndroidManifest.xml. However, "dangerous" permissions require a dialog prompt. You should use this module for those permissions.

On devices before SDK version 23, the permissions are automatically granted if they appear in the manifest, so check should always result to true and request should always resolve to PermissionsAndroid.RESULTS.GRANTED.

If a user has previously turned off a permission that you prompt for, the OS will advise your app to show a rationale for needing the permission. The optional rationale argument will show a dialog prompt only if necessary - otherwise the normal permission prompt will appear.

Example

Permissions that require prompting the user

Available as constants under PermissionsAndroid.PERMISSIONS:

  • READ_CALENDAR: 'android.permission.READ_CALENDAR'
  • WRITE_CALENDAR: 'android.permission.WRITE_CALENDAR'
  • CAMERA: 'android.permission.CAMERA'
  • READ_CONTACTS: 'android.permission.READ_CONTACTS'
  • WRITE_CONTACTS: 'android.permission.WRITE_CONTACTS'
  • GET_ACCOUNTS: 'android.permission.GET_ACCOUNTS'
  • ACCESS_FINE_LOCATION: 'android.permission.ACCESS_FINE_LOCATION'
  • ACCESS_COARSE_LOCATION: 'android.permission.ACCESS_COARSE_LOCATION'
  • RECORD_AUDIO: 'android.permission.RECORD_AUDIO'
  • READ_PHONE_STATE: 'android.permission.READ_PHONE_STATE'
  • CALL_PHONE: 'android.permission.CALL_PHONE'
  • READ_CALL_LOG: 'android.permission.READ_CALL_LOG'
  • WRITE_CALL_LOG: 'android.permission.WRITE_CALL_LOG'
  • ADD_VOICEMAIL: 'com.android.voicemail.permission.ADD_VOICEMAIL'
  • USE_SIP: 'android.permission.USE_SIP'
  • PROCESS_OUTGOING_CALLS: 'android.permission.PROCESS_OUTGOING_CALLS'
  • BODY_SENSORS: 'android.permission.BODY_SENSORS'
  • SEND_SMS: 'android.permission.SEND_SMS'
  • RECEIVE_SMS: 'android.permission.RECEIVE_SMS'
  • READ_SMS: 'android.permission.READ_SMS'
  • RECEIVE_WAP_PUSH: 'android.permission.RECEIVE_WAP_PUSH'
  • RECEIVE_MMS: 'android.permission.RECEIVE_MMS'
  • READ_EXTERNAL_STORAGE: 'android.permission.READ_EXTERNAL_STORAGE'
  • WRITE_EXTERNAL_STORAGE: 'android.permission.WRITE_EXTERNAL_STORAGE'

Result strings for requesting permissions

Available as constants under PermissionsAndroid.RESULTS:

  • GRANTED: 'granted'
  • DENIED: 'denied'
  • NEVER_ASK_AGAIN: 'never_ask_again'

Reference

Methods

constructor()

constructor();

check()

check(permission);

Returns a promise resolving to a boolean value as to whether the specified permissions has been granted.

Parameters:

NameTypeRequiredDescription
permissionstringYesThe permission to check for.

request()

request(permission, [rationale]);

Prompts the user to enable a permission and returns a promise resolving to a string value (see result strings above) indicating whether the user allowed or denied the request or does not want to be asked again.

If rationale is provided, this function checks with the OS whether it is necessary to show a dialog explaining why the permission is needed (https://developer.android.com/training/permissions/requesting.html#explain) and then shows the system permission dialog.

Parameters:

NameTypeRequiredDescription
permissionstringYesThe permission to request.
rationaleobjectNoSee rationale below.

Rationale:

NameTypeRequiredDescription
titlestringYesThe title of the dialog.
messagestringYesThe message of the dialog.
buttonPositivestringYesThe text of the positive button.
buttonNegativestringNoThe text of the negative button.
buttonNeutralstringNoThe text of the neutral button.

requestMultiple()

requestMultiple(permissions);

Prompts the user to enable multiple permissions in the same dialog and returns an object with the permissions as keys and strings as values (see result strings above) indicating whether the user allowed or denied the request or does not want to be asked again.

Parameters:

NameTypeRequiredDescription
permissionsarrayYesArray of permissions to request.
Edit this page
Last updated on
- + diff --git a/docs/permissionsandroid/index.html b/docs/permissionsandroid/index.html index 64bc5ea41ae..57b6cef014d 100644 --- a/docs/permissionsandroid/index.html +++ b/docs/permissionsandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

PermissionsAndroid

PermissionsAndroid provides access to Android M's new permissions model. The so-called "normal" permissions are granted by default when the application is installed as long as they appear in AndroidManifest.xml. However, "dangerous" permissions require a dialog prompt. You should use this module for those permissions.

On devices before SDK version 23, the permissions are automatically granted if they appear in the manifest, so check should always result to true and request should always resolve to PermissionsAndroid.RESULTS.GRANTED.

If a user has previously turned off a permission that you prompt for, the OS will advise your app to show a rationale for needing the permission. The optional rationale argument will show a dialog prompt only if necessary - otherwise the normal permission prompt will appear.

Example

Permissions that require prompting the user

Available as constants under PermissionsAndroid.PERMISSIONS:

  • READ_CALENDAR: 'android.permission.READ_CALENDAR'
  • WRITE_CALENDAR: 'android.permission.WRITE_CALENDAR'
  • CAMERA: 'android.permission.CAMERA'
  • READ_CONTACTS: 'android.permission.READ_CONTACTS'
  • WRITE_CONTACTS: 'android.permission.WRITE_CONTACTS'
  • GET_ACCOUNTS: 'android.permission.GET_ACCOUNTS'
  • ACCESS_FINE_LOCATION: 'android.permission.ACCESS_FINE_LOCATION'
  • ACCESS_COARSE_LOCATION: 'android.permission.ACCESS_COARSE_LOCATION'
  • RECORD_AUDIO: 'android.permission.RECORD_AUDIO'
  • READ_PHONE_STATE: 'android.permission.READ_PHONE_STATE'
  • CALL_PHONE: 'android.permission.CALL_PHONE'
  • READ_CALL_LOG: 'android.permission.READ_CALL_LOG'
  • WRITE_CALL_LOG: 'android.permission.WRITE_CALL_LOG'
  • ADD_VOICEMAIL: 'com.android.voicemail.permission.ADD_VOICEMAIL'
  • USE_SIP: 'android.permission.USE_SIP'
  • PROCESS_OUTGOING_CALLS: 'android.permission.PROCESS_OUTGOING_CALLS'
  • BODY_SENSORS: 'android.permission.BODY_SENSORS'
  • SEND_SMS: 'android.permission.SEND_SMS'
  • RECEIVE_SMS: 'android.permission.RECEIVE_SMS'
  • READ_SMS: 'android.permission.READ_SMS'
  • RECEIVE_WAP_PUSH: 'android.permission.RECEIVE_WAP_PUSH'
  • RECEIVE_MMS: 'android.permission.RECEIVE_MMS'
  • READ_EXTERNAL_STORAGE: 'android.permission.READ_EXTERNAL_STORAGE'
  • WRITE_EXTERNAL_STORAGE: 'android.permission.WRITE_EXTERNAL_STORAGE'

Result strings for requesting permissions

Available as constants under PermissionsAndroid.RESULTS:

  • GRANTED: 'granted'
  • DENIED: 'denied'
  • NEVER_ASK_AGAIN: 'never_ask_again'

Reference

Methods

constructor()

constructor();

check()

check(permission);

Returns a promise resolving to a boolean value as to whether the specified permissions has been granted.

Parameters:

NameTypeRequiredDescription
permissionstringYesThe permission to check for.

request()

request(permission, [rationale]);

Prompts the user to enable a permission and returns a promise resolving to a string value (see result strings above) indicating whether the user allowed or denied the request or does not want to be asked again.

If rationale is provided, this function checks with the OS whether it is necessary to show a dialog explaining why the permission is needed (https://developer.android.com/training/permissions/requesting.html#explain) and then shows the system permission dialog.

Parameters:

NameTypeRequiredDescription
permissionstringYesThe permission to request.
rationaleobjectNoSee rationale below.

Rationale:

NameTypeRequiredDescription
titlestringYesThe title of the dialog.
messagestringYesThe message of the dialog.
buttonPositivestringYesThe text of the positive button.
buttonNegativestringNoThe text of the negative button.
buttonNeutralstringNoThe text of the neutral button.

requestMultiple()

requestMultiple(permissions);

Prompts the user to enable multiple permissions in the same dialog and returns an object with the permissions as keys and strings as values (see result strings above) indicating whether the user allowed or denied the request or does not want to be asked again.

Parameters:

NameTypeRequiredDescription
permissionsarrayYesArray of permissions to request.
Edit this page
Last updated on
- + diff --git a/docs/picker-item.html b/docs/picker-item.html index 4c9d83e8749..3808402a719 100644 --- a/docs/picker-item.html +++ b/docs/picker-item.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Picker.Item

Individual selectable item in a Picker.

Props

Reference

Props

label

Text to display for this item.

TypeRequired
stringYes

color

Color of this item's text.

TypeRequired
colorNo

testID

Used to locate the item in end-to-end tests.

TypeRequired
stringNo

value

The value to be passed to picker's onValueChange callback when this item is selected. Can be a string or an integer.

TypeRequiredPlatform
anyNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/picker-item/index.html b/docs/picker-item/index.html index 4c9d83e8749..3808402a719 100644 --- a/docs/picker-item/index.html +++ b/docs/picker-item/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Picker.Item

Individual selectable item in a Picker.

Props

Reference

Props

label

Text to display for this item.

TypeRequired
stringYes

color

Color of this item's text.

TypeRequired
colorNo

testID

Used to locate the item in end-to-end tests.

TypeRequired
stringNo

value

The value to be passed to picker's onValueChange callback when this item is selected. Can be a string or an integer.

TypeRequiredPlatform
anyNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/picker-style-props.html b/docs/picker-style-props.html index 60a569b8cd5..c708d46af82 100644 --- a/docs/picker-style-props.html +++ b/docs/picker-style-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Edit this page
Last updated on
- + diff --git a/docs/picker-style-props/index.html b/docs/picker-style-props/index.html index 60a569b8cd5..c708d46af82 100644 --- a/docs/picker-style-props/index.html +++ b/docs/picker-style-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Edit this page
Last updated on
- + diff --git a/docs/picker.html b/docs/picker.html index bf739c48dbf..76041ce621d 100644 --- a/docs/picker.html +++ b/docs/picker.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 Picker

Deprecated. Use one of the community packages instead.

Renders the native picker component on Android and iOS.

Example

Reference

Props

Inherits View Props.

enabled

If set to false, the picker will be disabled, i.e. the user will not be able to make a selection.

TypeRequiredPlatform
boolNoAndroid

itemStyle

Style to apply to each of the item labels.

TypeRequiredPlatform
text stylesNoiOS

mode

On Android, specifies how to display the selection items when the user taps on the picker:

  • 'dialog': Show a modal dialog. This is the default.
  • 'dropdown': Shows a dropdown anchored to the picker view
TypeRequiredPlatform
enum('dialog', 'dropdown')NoAndroid

onValueChange

Callback for when an item is selected. This is called with the following parameters:

  • itemValue: the value prop of the item that was selected
  • itemPosition: the index of the selected item in this picker
TypeRequired
functionNo

prompt

Prompt string for this picker, used on Android in dialog mode as the title of the dialog.

TypeRequiredPlatform
stringNoAndroid

selectedValue

Value matching value of one of the items. Can be a string or an integer.

TypeRequired
anyNo

style

TypeRequired
pickerStyleTypeNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/picker/index.html b/docs/picker/index.html index bf739c48dbf..76041ce621d 100644 --- a/docs/picker/index.html +++ b/docs/picker/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 Picker

Deprecated. Use one of the community packages instead.

Renders the native picker component on Android and iOS.

Example

Reference

Props

Inherits View Props.

enabled

If set to false, the picker will be disabled, i.e. the user will not be able to make a selection.

TypeRequiredPlatform
boolNoAndroid

itemStyle

Style to apply to each of the item labels.

TypeRequiredPlatform
text stylesNoiOS

mode

On Android, specifies how to display the selection items when the user taps on the picker:

  • 'dialog': Show a modal dialog. This is the default.
  • 'dropdown': Shows a dropdown anchored to the picker view
TypeRequiredPlatform
enum('dialog', 'dropdown')NoAndroid

onValueChange

Callback for when an item is selected. This is called with the following parameters:

  • itemValue: the value prop of the item that was selected
  • itemPosition: the index of the selected item in this picker
TypeRequired
functionNo

prompt

Prompt string for this picker, used on Android in dialog mode as the title of the dialog.

TypeRequiredPlatform
stringNoAndroid

selectedValue

Value matching value of one of the items. Can be a string or an integer.

TypeRequired
anyNo

style

TypeRequired
pickerStyleTypeNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/pickerios.html b/docs/pickerios.html index 9a51ca9fe44..f8d6d110741 100644 --- a/docs/pickerios.html +++ b/docs/pickerios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 PickerIOS

Deprecated. Use one of the community packages instead.

Reference

Props

Inherits View Props.

itemStyle

TypeRequired
text stylesNo

onValueChange

TypeRequired
functionNo

onChange

TypeRequired
functionNo

selectedValue

TypeRequired
number or stringNo
Edit this page
Last updated on
- + diff --git a/docs/pickerios/index.html b/docs/pickerios/index.html index 9a51ca9fe44..f8d6d110741 100644 --- a/docs/pickerios/index.html +++ b/docs/pickerios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 PickerIOS

Deprecated. Use one of the community packages instead.

Reference

Props

Inherits View Props.

itemStyle

TypeRequired
text stylesNo

onValueChange

TypeRequired
functionNo

onChange

TypeRequired
functionNo

selectedValue

TypeRequired
number or stringNo
Edit this page
Last updated on
- + diff --git a/docs/pixelratio.html b/docs/pixelratio.html index 36636fd0400..1354ab06b34 100644 --- a/docs/pixelratio.html +++ b/docs/pixelratio.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

PixelRatio

PixelRatio gives you access to the device's pixel density and font scale.

Fetching a correctly sized image

You should get a higher resolution image if you are on a high pixel density device. A good rule of thumb is to multiply the size of the image you display by the pixel ratio.

var image = getImage({
width: PixelRatio.getPixelSizeForLayoutSize(200),
height: PixelRatio.getPixelSizeForLayoutSize(100)
});
<Image source={image} style={{ width: 200, height: 100 }} />;

Pixel grid snapping

In iOS, you can specify positions and dimensions for elements with arbitrary precision, for example 29.674825. But, ultimately the physical display only have a fixed number of pixels, for example 640×960 for iPhone 4 or 750×1334 for iPhone 6. iOS tries to be as faithful as possible to the user value by spreading one original pixel into multiple ones to trick the eye. The downside of this technique is that it makes the resulting element look blurry.

In practice, we found out that developers do not want this feature and they have to work around it by doing manual rounding in order to avoid having blurry elements. In React Native, we are rounding all the pixels automatically.

We have to be careful when to do this rounding. You never want to work with rounded and unrounded values at the same time as you're going to accumulate rounding errors. Having even one rounding error is deadly because a one pixel border may vanish or be twice as big.

In React Native, everything in JavaScript and within the layout engine works with arbitrary precision numbers. It's only when we set the position and dimensions of the native element on the main thread that we round. Also, rounding is done relative to the root rather than the parent, again to avoid accumulating rounding errors.

Example

Reference

Methods

get()

static get()

Returns the device pixel density. Some examples:

getFontScale()

static getFontScale(): number

Returns the scaling factor for font sizes. This is the ratio that is used to calculate the absolute font size, so any elements that heavily depend on that should use this to do calculations.

  • on Android value reflects the user preference set in Settings > Display > Font size
  • on iOS value reflects the user preference set in Settings > Display & Brightness > Text Size, value can also be updated in Settings > Accessibilty > Display & Test Size > Larger Text

If a font scale is not set, this returns the device pixel ratio.

getPixelSizeForLayoutSize()

static getPixelSizeForLayoutSize(layoutSize: number): number

Converts a layout size (dp) to pixel size (px).

Guaranteed to return an integer number.

roundToNearestPixel()

static roundToNearestPixel(layoutSize: number): number

Rounds a layout size (dp) to the nearest layout size that corresponds to an integer number of pixels. For example, on a device with a PixelRatio of 3, PixelRatio.roundToNearestPixel(8.4) = 8.33, which corresponds to exactly (8.33 * 3) = 25 pixels.

Edit this page
Last updated on
- + diff --git a/docs/pixelratio/index.html b/docs/pixelratio/index.html index 36636fd0400..1354ab06b34 100644 --- a/docs/pixelratio/index.html +++ b/docs/pixelratio/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

PixelRatio

PixelRatio gives you access to the device's pixel density and font scale.

Fetching a correctly sized image

You should get a higher resolution image if you are on a high pixel density device. A good rule of thumb is to multiply the size of the image you display by the pixel ratio.

var image = getImage({
width: PixelRatio.getPixelSizeForLayoutSize(200),
height: PixelRatio.getPixelSizeForLayoutSize(100)
});
<Image source={image} style={{ width: 200, height: 100 }} />;

Pixel grid snapping

In iOS, you can specify positions and dimensions for elements with arbitrary precision, for example 29.674825. But, ultimately the physical display only have a fixed number of pixels, for example 640×960 for iPhone 4 or 750×1334 for iPhone 6. iOS tries to be as faithful as possible to the user value by spreading one original pixel into multiple ones to trick the eye. The downside of this technique is that it makes the resulting element look blurry.

In practice, we found out that developers do not want this feature and they have to work around it by doing manual rounding in order to avoid having blurry elements. In React Native, we are rounding all the pixels automatically.

We have to be careful when to do this rounding. You never want to work with rounded and unrounded values at the same time as you're going to accumulate rounding errors. Having even one rounding error is deadly because a one pixel border may vanish or be twice as big.

In React Native, everything in JavaScript and within the layout engine works with arbitrary precision numbers. It's only when we set the position and dimensions of the native element on the main thread that we round. Also, rounding is done relative to the root rather than the parent, again to avoid accumulating rounding errors.

Example

Reference

Methods

get()

static get()

Returns the device pixel density. Some examples:

getFontScale()

static getFontScale(): number

Returns the scaling factor for font sizes. This is the ratio that is used to calculate the absolute font size, so any elements that heavily depend on that should use this to do calculations.

  • on Android value reflects the user preference set in Settings > Display > Font size
  • on iOS value reflects the user preference set in Settings > Display & Brightness > Text Size, value can also be updated in Settings > Accessibilty > Display & Test Size > Larger Text

If a font scale is not set, this returns the device pixel ratio.

getPixelSizeForLayoutSize()

static getPixelSizeForLayoutSize(layoutSize: number): number

Converts a layout size (dp) to pixel size (px).

Guaranteed to return an integer number.

roundToNearestPixel()

static roundToNearestPixel(layoutSize: number): number

Rounds a layout size (dp) to the nearest layout size that corresponds to an integer number of pixels. For example, on a device with a PixelRatio of 3, PixelRatio.roundToNearestPixel(8.4) = 8.33, which corresponds to exactly (8.33 * 3) = 25 pixels.

Edit this page
Last updated on
- + diff --git a/docs/platform-specific-code.html b/docs/platform-specific-code.html index a074595d804..5474d8ceeb5 100644 --- a/docs/platform-specific-code.html +++ b/docs/platform-specific-code.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
const majorVersionIOS = parseInt(Platform.Version, 10);
if (majorVersionIOS <= 9) {
console.log('Work around a change in behavior');
}

Platform-specific extensions

When your platform-specific code is more complex, you should consider splitting the code out into separate files. React Native will detect when a file has a .ios. or .android. extension and load the relevant platform file when required from other components.

For example, say you have the following files in your project:

BigButton.ios.js
BigButton.android.js

You can then require the component as follows:

import BigButton from './BigButton';

React Native will automatically pick up the right file based on the running platform.

Native-specific extensions (i.e. sharing code with NodeJS and Web)

You can also use the .native.js extension when a module needs to be shared between NodeJS/Web and React Native but it has no Android/iOS differences. This is especially useful for projects that have common code shared among React Native and ReactJS.

For example, say you have the following files in your project:

Container.js # picked up by Webpack, Rollup or any other Web bundler
Container.native.js # picked up by the React Native bundler for both Android and iOS (Metro)

You can still require it without the .native extension, as follows:

import Container from './Container';

Pro tip: Configure your Web bundler to ignore .native.js extensions in order to avoid having unused code in your production bundle, thus reducing the final bundle size.

Edit this page
Last updated on
- + diff --git a/docs/platform-specific-code/index.html b/docs/platform-specific-code/index.html index a074595d804..5474d8ceeb5 100644 --- a/docs/platform-specific-code/index.html +++ b/docs/platform-specific-code/index.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
const majorVersionIOS = parseInt(Platform.Version, 10);
if (majorVersionIOS <= 9) {
console.log('Work around a change in behavior');
}

Platform-specific extensions

When your platform-specific code is more complex, you should consider splitting the code out into separate files. React Native will detect when a file has a .ios. or .android. extension and load the relevant platform file when required from other components.

For example, say you have the following files in your project:

BigButton.ios.js
BigButton.android.js

You can then require the component as follows:

import BigButton from './BigButton';

React Native will automatically pick up the right file based on the running platform.

Native-specific extensions (i.e. sharing code with NodeJS and Web)

You can also use the .native.js extension when a module needs to be shared between NodeJS/Web and React Native but it has no Android/iOS differences. This is especially useful for projects that have common code shared among React Native and ReactJS.

For example, say you have the following files in your project:

Container.js # picked up by Webpack, Rollup or any other Web bundler
Container.native.js # picked up by the React Native bundler for both Android and iOS (Metro)

You can still require it without the .native extension, as follows:

import Container from './Container';

Pro tip: Configure your Web bundler to ignore .native.js extensions in order to avoid having unused code in your production bundle, thus reducing the final bundle size.

Edit this page
Last updated on
- + diff --git a/docs/platform.html b/docs/platform.html index 9e5f62e8be3..f8312326cd3 100644 --- a/docs/platform.html +++ b/docs/platform.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
<Component />;
Edit this page
Last updated on
- + diff --git a/docs/platform/index.html b/docs/platform/index.html index 9e5f62e8be3..f8312326cd3 100644 --- a/docs/platform/index.html +++ b/docs/platform/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@
<Component />;
Edit this page
Last updated on
- + diff --git a/docs/platformcolor.html b/docs/platformcolor.html index f170f7c7d34..6f1a5c4b12a 100644 --- a/docs/platformcolor.html +++ b/docs/platformcolor.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

PlatformColor

PlatformColor(color1, [color2, ...colorN]);

You can use the PlatformColor function to access native colors on the target platform by supplying the native color’s corresponding string value. You pass a string to the PlatformColor function and, provided it exists on that platform, it will return the corresponding native color, which you can apply in any part of your application.

If you pass more than one string value to the PlatformColor function, it will treat the first value as the default and the rest as fallback.

PlatformColor('bogusName', 'linkColor');

Since native colors can be sensitive to themes and/or high contrast, this platform specific logic also translates inside your components.

Supported colors

For a full list of the types of system colors supported, see:

Developer notes

If you’re familiar with design systems, another way of thinking about this is that PlatformColor lets you tap into the local design system's color tokens so your app can blend right in!

Example

The string value provided to the PlatformColor function must match the string as it exists on the native platform where the app is running. In order to avoid runtime errors, the function should be wrapped in a platform check, either through a Platform.OS === 'platform' or a Platform.Select(), as shown on the example above.

Note: You can find a complete example that demonstrates proper, intended use of PlatformColor in PlatformColorExample.js.

Edit this page
Last updated on
- + diff --git a/docs/platformcolor/index.html b/docs/platformcolor/index.html index f170f7c7d34..6f1a5c4b12a 100644 --- a/docs/platformcolor/index.html +++ b/docs/platformcolor/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

PlatformColor

PlatformColor(color1, [color2, ...colorN]);

You can use the PlatformColor function to access native colors on the target platform by supplying the native color’s corresponding string value. You pass a string to the PlatformColor function and, provided it exists on that platform, it will return the corresponding native color, which you can apply in any part of your application.

If you pass more than one string value to the PlatformColor function, it will treat the first value as the default and the rest as fallback.

PlatformColor('bogusName', 'linkColor');

Since native colors can be sensitive to themes and/or high contrast, this platform specific logic also translates inside your components.

Supported colors

For a full list of the types of system colors supported, see:

Developer notes

If you’re familiar with design systems, another way of thinking about this is that PlatformColor lets you tap into the local design system's color tokens so your app can blend right in!

Example

The string value provided to the PlatformColor function must match the string as it exists on the native platform where the app is running. In order to avoid runtime errors, the function should be wrapped in a platform check, either through a Platform.OS === 'platform' or a Platform.Select(), as shown on the example above.

Note: You can find a complete example that demonstrates proper, intended use of PlatformColor in PlatformColorExample.js.

Edit this page
Last updated on
- + diff --git a/docs/pressable.html b/docs/pressable.html index bf7d05afd19..06147bb2a96 100644 --- a/docs/pressable.html +++ b/docs/pressable.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Pressable

Pressable is a Core Component wrapper that can detect various stages of press interactions on any of its defined children.

<Pressable onPress={onPressFunction}>
<Text>I'm pressable!</Text>
</Pressable>

How it works

On an element wrapped by Pressable:

  • onPressIn is called when a press is activated.
  • onPressOut is called when the press gesture is deactivated.

After pressing onPressIn, one of two things will happen:

  1. The person will remove their finger, triggering onPressOut followed by onPress.
  2. If the person leaves their finger longer than 500 milliseconds before removing it, onLongPress is triggered. (onPressOut will still fire when they remove their finger.)
Diagram of the onPress events in sequence.

Fingers are not the most precise instruments, and it is common for users to accidentally activate the wrong element or miss the activation area. To help, Pressable has an optional HitRect you can use to define how far a touch can register away from the wrapped element. Presses can start anywhere within a HitRect.

PressRect allows presses to move beyond the element and its HitRect while maintaining activation and being eligible for a "press"—think of sliding your finger slowly away from a button you're pressing down on.

The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

Diagram of HitRect and PressRect and how they work.
You can set HitRect with hitSlop and set PressRect with pressRetentionOffset.

Pressable uses React Native's Pressability API. For more information around the state machine flow of Pressability and how it works, check out the implementation for Pressability.

Example

Props

android_disableSound
Android

If true, doesn't play Android system sound on press.

TypeRequiredDefault
booleanNofalse

android_ripple
Android

Enables the Android ripple effect and configures its properties.

TypeRequired
RippleConfigNo

children

Either children or a function that receives a boolean reflecting whether the component is currently pressed.

TypeRequired
React NodeNo

delayLongPress

Duration (in milliseconds) from onPressIn before onLongPress is called.

TypeRequiredDefault
numberNo500

disabled

Whether the press behavior is disabled.

TypeRequiredDefault
booleanNofalse

hitSlop

Sets additional distance outside of element in which a press can be detected.

TypeRequired
Rect or numberNo

onLongPress

Called if the time after onPressIn lasts longer than 500 milliseconds. This time period can be customized with delayLongPress.

TypeRequired
PressEventNo

onPress

Called after onPressOut.

TypeRequired
PressEventNo

onPressIn

Called immediately when a touch is engaged, before onPressOut and onPress.

TypeRequired
PressEventNo

onPressOut

Called when a touch is released.

TypeRequired
PressEventNo

pressRetentionOffset

Additional distance outside of this view in which a touch is considered a press before onPressOut is triggered.

TypeRequiredDefault
Rect or numberNo{ bottom: 30, left: 20, right: 20, top: 20 }

style

Either view styles or a function that receives a boolean reflecting whether the component is currently pressed and returns view styles.

TypeRequired
ViewStylePropNo

testOnly_pressed

Used only for documentation or testing (e.g. snapshot testing).

TypeRequiredDefault
booleanNofalse

Type Definitions

RippleConfig

Ripple effect configuration for the android_ripple property.

Type
object

Properties:

NameTypeRequiredDescription
colorcolorNoDefines the color of the ripple effect.
borderlessbooleanNoDefines if ripple effect should not include border.
radiusnumberNoDefines the radius of the ripple effect.
Edit this page
Last updated on
- + diff --git a/docs/pressable/index.html b/docs/pressable/index.html index bf7d05afd19..06147bb2a96 100644 --- a/docs/pressable/index.html +++ b/docs/pressable/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Pressable

Pressable is a Core Component wrapper that can detect various stages of press interactions on any of its defined children.

<Pressable onPress={onPressFunction}>
<Text>I'm pressable!</Text>
</Pressable>

How it works

On an element wrapped by Pressable:

  • onPressIn is called when a press is activated.
  • onPressOut is called when the press gesture is deactivated.

After pressing onPressIn, one of two things will happen:

  1. The person will remove their finger, triggering onPressOut followed by onPress.
  2. If the person leaves their finger longer than 500 milliseconds before removing it, onLongPress is triggered. (onPressOut will still fire when they remove their finger.)
Diagram of the onPress events in sequence.

Fingers are not the most precise instruments, and it is common for users to accidentally activate the wrong element or miss the activation area. To help, Pressable has an optional HitRect you can use to define how far a touch can register away from the wrapped element. Presses can start anywhere within a HitRect.

PressRect allows presses to move beyond the element and its HitRect while maintaining activation and being eligible for a "press"—think of sliding your finger slowly away from a button you're pressing down on.

The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

Diagram of HitRect and PressRect and how they work.
You can set HitRect with hitSlop and set PressRect with pressRetentionOffset.

Pressable uses React Native's Pressability API. For more information around the state machine flow of Pressability and how it works, check out the implementation for Pressability.

Example

Props

android_disableSound
Android

If true, doesn't play Android system sound on press.

TypeRequiredDefault
booleanNofalse

android_ripple
Android

Enables the Android ripple effect and configures its properties.

TypeRequired
RippleConfigNo

children

Either children or a function that receives a boolean reflecting whether the component is currently pressed.

TypeRequired
React NodeNo

delayLongPress

Duration (in milliseconds) from onPressIn before onLongPress is called.

TypeRequiredDefault
numberNo500

disabled

Whether the press behavior is disabled.

TypeRequiredDefault
booleanNofalse

hitSlop

Sets additional distance outside of element in which a press can be detected.

TypeRequired
Rect or numberNo

onLongPress

Called if the time after onPressIn lasts longer than 500 milliseconds. This time period can be customized with delayLongPress.

TypeRequired
PressEventNo

onPress

Called after onPressOut.

TypeRequired
PressEventNo

onPressIn

Called immediately when a touch is engaged, before onPressOut and onPress.

TypeRequired
PressEventNo

onPressOut

Called when a touch is released.

TypeRequired
PressEventNo

pressRetentionOffset

Additional distance outside of this view in which a touch is considered a press before onPressOut is triggered.

TypeRequiredDefault
Rect or numberNo{ bottom: 30, left: 20, right: 20, top: 20 }

style

Either view styles or a function that receives a boolean reflecting whether the component is currently pressed and returns view styles.

TypeRequired
ViewStylePropNo

testOnly_pressed

Used only for documentation or testing (e.g. snapshot testing).

TypeRequiredDefault
booleanNofalse

Type Definitions

RippleConfig

Ripple effect configuration for the android_ripple property.

Type
object

Properties:

NameTypeRequiredDescription
colorcolorNoDefines the color of the ripple effect.
borderlessbooleanNoDefines if ripple effect should not include border.
radiusnumberNoDefines the radius of the ripple effect.
Edit this page
Last updated on
- + diff --git a/docs/pressevent.html b/docs/pressevent.html index 32a6cf8ce36..470e74e3cb3 100644 --- a/docs/pressevent.html +++ b/docs/pressevent.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

PressEvent Object Type

PressEvent object is returned in the callback as a result of user press interaction, for example onPress in Button component.

Example

{
changedTouches: [PressEvent],
identifier: 1,
locationX: 8,
locationY: 4.5,
pageX: 24,
pageY: 49.5,
target: 1127,
timestamp: 85131876.58868201,
touches: []
}

Keys and values

changedTouches

Array of all PressEvents that have changed since the last event.

TypeOptional
array of PressEventsNo

force
iOS

Amount of force used during the 3D Touch press. Returns the float value in range from 0.0 to 1.0.

TypeOptional
numberYes

identifier

Unique numeric identifier assigned to the event.

TypeOptional
numberNo

locationX

Touch origin X coordinate inside touchable area (relative to the element).

TypeOptional
numberNo

locationY

Touch origin Y coordinate inside touchable area (relative to the element).

TypeOptional
numberNo

pageX

Touch origin X coordinate on the screen (relative to the root view).

TypeOptional
numberNo

pageY

Touch origin Y coordinate on the screen (relative to the root view).

TypeOptional
numberNo

target

The node id of the element receiving the PressEvent.

TypeOptional
number, null, undefinedNo

timestamp

Timestamp value when a PressEvent occurred. Value is represented in milliseconds.

TypeOptional
numberNo

touches

Array of all current PressEvents on the screen.

TypeOptional
array of PressEventsNo

Used by

Edit this page
Last updated on
- + diff --git a/docs/pressevent/index.html b/docs/pressevent/index.html index 32a6cf8ce36..470e74e3cb3 100644 --- a/docs/pressevent/index.html +++ b/docs/pressevent/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

PressEvent Object Type

PressEvent object is returned in the callback as a result of user press interaction, for example onPress in Button component.

Example

{
changedTouches: [PressEvent],
identifier: 1,
locationX: 8,
locationY: 4.5,
pageX: 24,
pageY: 49.5,
target: 1127,
timestamp: 85131876.58868201,
touches: []
}

Keys and values

changedTouches

Array of all PressEvents that have changed since the last event.

TypeOptional
array of PressEventsNo

force
iOS

Amount of force used during the 3D Touch press. Returns the float value in range from 0.0 to 1.0.

TypeOptional
numberYes

identifier

Unique numeric identifier assigned to the event.

TypeOptional
numberNo

locationX

Touch origin X coordinate inside touchable area (relative to the element).

TypeOptional
numberNo

locationY

Touch origin Y coordinate inside touchable area (relative to the element).

TypeOptional
numberNo

pageX

Touch origin X coordinate on the screen (relative to the root view).

TypeOptional
numberNo

pageY

Touch origin Y coordinate on the screen (relative to the root view).

TypeOptional
numberNo

target

The node id of the element receiving the PressEvent.

TypeOptional
number, null, undefinedNo

timestamp

Timestamp value when a PressEvent occurred. Value is represented in milliseconds.

TypeOptional
numberNo

touches

Array of all current PressEvents on the screen.

TypeOptional
array of PressEventsNo

Used by

Edit this page
Last updated on
- + diff --git a/docs/profiling.html b/docs/profiling.html index e03a149bda7..3ee2dc7e24f 100644 --- a/docs/profiling.html +++ b/docs/profiling.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Profiling

Use the built-in profiler to get detailed information about work done in the JavaScript thread and main thread side-by-side. Access it by selecting Perf Monitor from the Debug menu.

For iOS, Instruments is an invaluable tool, and on Android you should learn to use systrace.

But first, make sure that Development Mode is OFF! You should see __DEV__ === false, development-level warning are OFF, performance optimizations are ON in your application logs.

Another way to profile JavaScript is to use the Chrome profiler while debugging. This won't give you accurate results as the code is running in Chrome but will give you a general idea of where bottlenecks might be. Run the profiler under Chrome's Performance tab. A flame graph will appear under User Timing. To view more details in tabular format, click at the Bottom Up tab below and then select DedicatedWorker Thread at the top left menu.

Profiling Android UI Performance with systrace

Android supports 10k+ different phones and is generalized to support software rendering: the framework architecture and need to generalize across many hardware targets unfortunately means you get less for free relative to iOS. But sometimes, there are things you can improve -- and many times it's not native code's fault at all!

The first step for debugging this jank is to answer the fundamental question of where your time is being spent during each 16ms frame. For that, we'll be using a standard Android profiling tool called systrace.

systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.

1. Collecting a trace

First, connect a device that exhibits the stuttering you want to investigate to your computer via USB and get it to the point right before the navigation/animation you want to profile. Run systrace as follows:

$ <path_to_android_sdk>/platform-tools/systrace/systrace.py --time=10 -o trace.html sched gfx view -a <your_package_name>

A quick breakdown of this command:

  • time is the length of time the trace will be collected in seconds
  • sched, gfx, and view are the android SDK tags (collections of markers) we care about: sched gives you information about what's running on each core of your phone, gfx gives you graphics info such as frame boundaries, and view gives you information about measure, layout, and draw passes
  • -a <your_package_name> enables app-specific markers, specifically the ones built into the React Native framework. your_package_name can be found in the AndroidManifest.xml of your app and looks like com.example.app

Once the trace starts collecting, perform the animation or interaction you care about. At the end of the trace, systrace will give you a link to the trace which you can open in your browser.

2. Reading the trace

After opening the trace in your browser (preferably Chrome), you should see something like this:

Example

HINT: Use the WASD keys to strafe and zoom

If your trace .html file isn't opening correctly, check your browser console for the following:

ObjectObserveError

Since Object.observe was deprecated in recent browsers, you may have to open the file from the Google Chrome Tracing tool. You can do so by:

  • Opening tab in chrome chrome://tracing
  • Selecting load
  • Selecting the html file generated from the previous command.

Enable VSync highlighting

Check this checkbox at the top right of the screen to highlight the 16ms frame boundaries:

Enable VSync Highlighting

You should see zebra stripes as in the screenshot above. If you don't, try profiling on a different device: Samsung has been known to have issues displaying vsyncs while the Nexus series is generally pretty reliable.

3. Find your process

Scroll until you see (part of) the name of your package. In this case, I was profiling com.facebook.adsmanager, which shows up as book.adsmanager because of silly thread name limits in the kernel.

On the left side, you'll see a set of threads which correspond to the timeline rows on the right. There are a few threads we care about for our purposes: the UI thread (which has your package name or the name UI Thread), mqt_js, and mqt_native_modules. If you're running on Android 5+, we also care about the Render Thread.

  • UI Thread. This is where standard android measure/layout/draw happens. The thread name on the right will be your package name (in my case book.adsmanager) or UI Thread. The events that you see on this thread should look something like this and have to do with Choreographer, traversals, and DispatchUI:

    UI Thread Example

  • JS Thread. This is where JavaScript is executed. The thread name will be either mqt_js or <...> depending on how cooperative the kernel on your device is being. To identify it if it doesn't have a name, look for things like JSCall, Bridge.executeJSCall, etc:

    JS Thread Example

  • Native Modules Thread. This is where native module calls (e.g. the UIManager) are executed. The thread name will be either mqt_native_modules or <...>. To identify it in the latter case, look for things like NativeCall, callJavaModuleMethod, and onBatchComplete:

    Native Modules Thread Example

  • Bonus: Render Thread. If you're using Android L (5.0) and up, you will also have a render thread in your application. This thread generates the actual OpenGL commands used to draw your UI. The thread name will be either RenderThread or <...>. To identify it in the latter case, look for things like DrawFrame and queueBuffer:

    Render Thread Example

Identifying a culprit

A smooth animation should look something like the following:

Smooth Animation

Each change in color is a frame -- remember that in order to display a frame, all our UI work needs to be done by the end of that 16ms period. Notice that no thread is working close to the frame boundary. An application rendering like this is rendering at 60 FPS.

If you noticed chop, however, you might see something like this:

Choppy Animation from JS

Notice that the JS thread is executing almost all the time, and across frame boundaries! This app is not rendering at 60 FPS. In this case, the problem lies in JS.

You might also see something like this:

Choppy Animation from UI

In this case, the UI and render threads are the ones that have work crossing frame boundaries. The UI that we're trying to render on each frame is requiring too much work to be done. In this case, the problem lies in the native views being rendered.

At this point, you'll have some very helpful information to inform your next steps.

Resolving JavaScript issues

If you identified a JS problem, look for clues in the specific JS that you're executing. In the scenario above, we see RCTEventEmitter being called multiple times per frame. Here's a zoom-in of the JS thread from the trace above:

Too much JS

This doesn't seem right. Why is it being called so often? Are they actually different events? The answers to these questions will probably depend on your product code. And many times, you'll want to look into shouldComponentUpdate.

Resolving native UI Issues

If you identified a native UI problem, there are usually two scenarios:

  1. the UI you're trying to draw each frame involves too much work on the GPU, or
  2. You're constructing new UI during the animation/interaction (e.g. loading in new content during a scroll).

Too much GPU work

In the first scenario, you'll see a trace that has the UI thread and/or Render Thread looking like this:

Overloaded GPU

Notice the long amount of time spent in DrawFrame that crosses frame boundaries. This is time spent waiting for the GPU to drain its command buffer from the previous frame.

To mitigate this, you should:

  • investigate using renderToHardwareTextureAndroid for complex, static content that is being animated/transformed (e.g. the Navigator slide/alpha animations)
  • make sure that you are not using needsOffscreenAlphaCompositing, which is disabled by default, as it greatly increases the per-frame load on the GPU in most cases.

If these don't help and you want to dig deeper into what the GPU is actually doing, you can check out Tracer for OpenGL ES.

Creating new views on the UI thread

In the second scenario, you'll see something more like this:

Creating Views

Notice that first the JS thread thinks for a bit, then you see some work done on the native modules thread, followed by an expensive traversal on the UI thread.

There isn't a quick way to mitigate this unless you're able to postpone creating new UI until after the interaction, or you are able to simplify the UI you're creating. The react native team is working on an infrastructure level solution for this that will allow new UI to be created and configured off the main thread, allowing the interaction to continue smoothly.

Edit this page
Last updated on
- + diff --git a/docs/profiling/index.html b/docs/profiling/index.html index e03a149bda7..3ee2dc7e24f 100644 --- a/docs/profiling/index.html +++ b/docs/profiling/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Profiling

Use the built-in profiler to get detailed information about work done in the JavaScript thread and main thread side-by-side. Access it by selecting Perf Monitor from the Debug menu.

For iOS, Instruments is an invaluable tool, and on Android you should learn to use systrace.

But first, make sure that Development Mode is OFF! You should see __DEV__ === false, development-level warning are OFF, performance optimizations are ON in your application logs.

Another way to profile JavaScript is to use the Chrome profiler while debugging. This won't give you accurate results as the code is running in Chrome but will give you a general idea of where bottlenecks might be. Run the profiler under Chrome's Performance tab. A flame graph will appear under User Timing. To view more details in tabular format, click at the Bottom Up tab below and then select DedicatedWorker Thread at the top left menu.

Profiling Android UI Performance with systrace

Android supports 10k+ different phones and is generalized to support software rendering: the framework architecture and need to generalize across many hardware targets unfortunately means you get less for free relative to iOS. But sometimes, there are things you can improve -- and many times it's not native code's fault at all!

The first step for debugging this jank is to answer the fundamental question of where your time is being spent during each 16ms frame. For that, we'll be using a standard Android profiling tool called systrace.

systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.

1. Collecting a trace

First, connect a device that exhibits the stuttering you want to investigate to your computer via USB and get it to the point right before the navigation/animation you want to profile. Run systrace as follows:

$ <path_to_android_sdk>/platform-tools/systrace/systrace.py --time=10 -o trace.html sched gfx view -a <your_package_name>

A quick breakdown of this command:

  • time is the length of time the trace will be collected in seconds
  • sched, gfx, and view are the android SDK tags (collections of markers) we care about: sched gives you information about what's running on each core of your phone, gfx gives you graphics info such as frame boundaries, and view gives you information about measure, layout, and draw passes
  • -a <your_package_name> enables app-specific markers, specifically the ones built into the React Native framework. your_package_name can be found in the AndroidManifest.xml of your app and looks like com.example.app

Once the trace starts collecting, perform the animation or interaction you care about. At the end of the trace, systrace will give you a link to the trace which you can open in your browser.

2. Reading the trace

After opening the trace in your browser (preferably Chrome), you should see something like this:

Example

HINT: Use the WASD keys to strafe and zoom

If your trace .html file isn't opening correctly, check your browser console for the following:

ObjectObserveError

Since Object.observe was deprecated in recent browsers, you may have to open the file from the Google Chrome Tracing tool. You can do so by:

  • Opening tab in chrome chrome://tracing
  • Selecting load
  • Selecting the html file generated from the previous command.

Enable VSync highlighting

Check this checkbox at the top right of the screen to highlight the 16ms frame boundaries:

Enable VSync Highlighting

You should see zebra stripes as in the screenshot above. If you don't, try profiling on a different device: Samsung has been known to have issues displaying vsyncs while the Nexus series is generally pretty reliable.

3. Find your process

Scroll until you see (part of) the name of your package. In this case, I was profiling com.facebook.adsmanager, which shows up as book.adsmanager because of silly thread name limits in the kernel.

On the left side, you'll see a set of threads which correspond to the timeline rows on the right. There are a few threads we care about for our purposes: the UI thread (which has your package name or the name UI Thread), mqt_js, and mqt_native_modules. If you're running on Android 5+, we also care about the Render Thread.

  • UI Thread. This is where standard android measure/layout/draw happens. The thread name on the right will be your package name (in my case book.adsmanager) or UI Thread. The events that you see on this thread should look something like this and have to do with Choreographer, traversals, and DispatchUI:

    UI Thread Example

  • JS Thread. This is where JavaScript is executed. The thread name will be either mqt_js or <...> depending on how cooperative the kernel on your device is being. To identify it if it doesn't have a name, look for things like JSCall, Bridge.executeJSCall, etc:

    JS Thread Example

  • Native Modules Thread. This is where native module calls (e.g. the UIManager) are executed. The thread name will be either mqt_native_modules or <...>. To identify it in the latter case, look for things like NativeCall, callJavaModuleMethod, and onBatchComplete:

    Native Modules Thread Example

  • Bonus: Render Thread. If you're using Android L (5.0) and up, you will also have a render thread in your application. This thread generates the actual OpenGL commands used to draw your UI. The thread name will be either RenderThread or <...>. To identify it in the latter case, look for things like DrawFrame and queueBuffer:

    Render Thread Example

Identifying a culprit

A smooth animation should look something like the following:

Smooth Animation

Each change in color is a frame -- remember that in order to display a frame, all our UI work needs to be done by the end of that 16ms period. Notice that no thread is working close to the frame boundary. An application rendering like this is rendering at 60 FPS.

If you noticed chop, however, you might see something like this:

Choppy Animation from JS

Notice that the JS thread is executing almost all the time, and across frame boundaries! This app is not rendering at 60 FPS. In this case, the problem lies in JS.

You might also see something like this:

Choppy Animation from UI

In this case, the UI and render threads are the ones that have work crossing frame boundaries. The UI that we're trying to render on each frame is requiring too much work to be done. In this case, the problem lies in the native views being rendered.

At this point, you'll have some very helpful information to inform your next steps.

Resolving JavaScript issues

If you identified a JS problem, look for clues in the specific JS that you're executing. In the scenario above, we see RCTEventEmitter being called multiple times per frame. Here's a zoom-in of the JS thread from the trace above:

Too much JS

This doesn't seem right. Why is it being called so often? Are they actually different events? The answers to these questions will probably depend on your product code. And many times, you'll want to look into shouldComponentUpdate.

Resolving native UI Issues

If you identified a native UI problem, there are usually two scenarios:

  1. the UI you're trying to draw each frame involves too much work on the GPU, or
  2. You're constructing new UI during the animation/interaction (e.g. loading in new content during a scroll).

Too much GPU work

In the first scenario, you'll see a trace that has the UI thread and/or Render Thread looking like this:

Overloaded GPU

Notice the long amount of time spent in DrawFrame that crosses frame boundaries. This is time spent waiting for the GPU to drain its command buffer from the previous frame.

To mitigate this, you should:

  • investigate using renderToHardwareTextureAndroid for complex, static content that is being animated/transformed (e.g. the Navigator slide/alpha animations)
  • make sure that you are not using needsOffscreenAlphaCompositing, which is disabled by default, as it greatly increases the per-frame load on the GPU in most cases.

If these don't help and you want to dig deeper into what the GPU is actually doing, you can check out Tracer for OpenGL ES.

Creating new views on the UI thread

In the second scenario, you'll see something more like this:

Creating Views

Notice that first the JS thread thinks for a bit, then you see some work done on the native modules thread, followed by an expensive traversal on the UI thread.

There isn't a quick way to mitigate this unless you're able to postpone creating new UI until after the interaction, or you are able to simplify the UI you're creating. The react native team is working on an infrastructure level solution for this that will allow new UI to be created and configured off the main thread, allowing the interaction to continue smoothly.

Edit this page
Last updated on
- + diff --git a/docs/progressbarandroid.html b/docs/progressbarandroid.html index aba4afc0b23..6303af0fa65 100644 --- a/docs/progressbarandroid.html +++ b/docs/progressbarandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 ProgressBarAndroid

Deprecated. Use one of the community packages instead.

Android-only React component used to indicate that the app is loading or there is some activity in the app.

Example

Reference

Props

Inherits View Props.

animating

Whether to show the ProgressBar (true, the default) or hide it (false).

TypeRequired
boolNo

color

Color of the progress bar.

TypeRequired
colorNo

indeterminate

If the progress bar will show indeterminate progress. Note that this can only be false if styleAttr is Horizontal, and requires a progress value.

TypeRequired
indeterminateTypeNo

progress

The progress value (between 0 and 1).

TypeRequired
numberNo

styleAttr

Style of the ProgressBar. One of:

  • Horizontal
  • Normal (default)
  • Small
  • Large
  • Inverse
  • SmallInverse
  • LargeInverse
TypeRequired
enum('Horizontal', 'Normal', 'Small', 'Large', 'Inverse', 'SmallInverse', 'LargeInverse')No

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/progressbarandroid/index.html b/docs/progressbarandroid/index.html index aba4afc0b23..6303af0fa65 100644 --- a/docs/progressbarandroid/index.html +++ b/docs/progressbarandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 ProgressBarAndroid

Deprecated. Use one of the community packages instead.

Android-only React component used to indicate that the app is loading or there is some activity in the app.

Example

Reference

Props

Inherits View Props.

animating

Whether to show the ProgressBar (true, the default) or hide it (false).

TypeRequired
boolNo

color

Color of the progress bar.

TypeRequired
colorNo

indeterminate

If the progress bar will show indeterminate progress. Note that this can only be false if styleAttr is Horizontal, and requires a progress value.

TypeRequired
indeterminateTypeNo

progress

The progress value (between 0 and 1).

TypeRequired
numberNo

styleAttr

Style of the ProgressBar. One of:

  • Horizontal
  • Normal (default)
  • Small
  • Large
  • Inverse
  • SmallInverse
  • LargeInverse
TypeRequired
enum('Horizontal', 'Normal', 'Small', 'Large', 'Inverse', 'SmallInverse', 'LargeInverse')No

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/progressviewios.html b/docs/progressviewios.html index df3fe3ddaaf..e817ca1b6c3 100644 --- a/docs/progressviewios.html +++ b/docs/progressviewios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 ProgressViewIOS

Deprecated. Use one of the community packages instead.

Uses ProgressViewIOS to render a UIProgressView on iOS.

Example

Reference

Props

Inherits View Props.

progress

The progress value (between 0 and 1).

TypeRequired
numberNo

progressImage

A stretchable image to display as the progress bar.

TypeRequired
Image.propTypes.sourceNo

progressTintColor

The tint color of the progress bar itself.

TypeRequired
stringNo

progressViewStyle

The progress bar style.

TypeRequired
enum('default', 'bar')No

trackImage

A stretchable image to display behind the progress bar.

TypeRequired
Image.propTypes.sourceNo

trackTintColor

The tint color of the progress bar track.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/progressviewios/index.html b/docs/progressviewios/index.html index df3fe3ddaaf..e817ca1b6c3 100644 --- a/docs/progressviewios/index.html +++ b/docs/progressviewios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 ProgressViewIOS

Deprecated. Use one of the community packages instead.

Uses ProgressViewIOS to render a UIProgressView on iOS.

Example

Reference

Props

Inherits View Props.

progress

The progress value (between 0 and 1).

TypeRequired
numberNo

progressImage

A stretchable image to display as the progress bar.

TypeRequired
Image.propTypes.sourceNo

progressTintColor

The tint color of the progress bar itself.

TypeRequired
stringNo

progressViewStyle

The progress bar style.

TypeRequired
enum('default', 'bar')No

trackImage

A stretchable image to display behind the progress bar.

TypeRequired
Image.propTypes.sourceNo

trackTintColor

The tint color of the progress bar track.

TypeRequired
stringNo
Edit this page
Last updated on
- + diff --git a/docs/props.html b/docs/props.html index bff2d34df9b..1f657253a4a 100644 --- a/docs/props.html +++ b/docs/props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Props

Most components can be customized when they are created, with different parameters. These created parameters are called props, short for properties.

For example, one basic React Native component is the Image. When you create an image, you can use a prop named source to control what image it shows.

Notice the braces surrounding {pic} - these embed the variable pic into JSX. You can put any JavaScript expression inside braces in JSX.

Your own components can also use props. This lets you make a single component that is used in many different places in your app, with slightly different properties in each place by referring to props in your render function. Here's an example:

Using name as a prop lets us customize the Greeting component, so we can reuse that component for each of our greetings. This example also uses the Greeting component in JSX, similar to the Core Components. The power to do this is what makes React so cool - if you find yourself wishing that you had a different set of UI primitives to work with, you can invent new ones.

The other new thing going on here is the View component. A View is useful as a container for other components, to help control style and layout.

With props and the basic Text, Image, and View components, you can build a wide variety of static screens. To learn how to make your app change over time, you need to learn about State.

Edit this page
Last updated on
- + diff --git a/docs/props/index.html b/docs/props/index.html index bff2d34df9b..1f657253a4a 100644 --- a/docs/props/index.html +++ b/docs/props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Props

Most components can be customized when they are created, with different parameters. These created parameters are called props, short for properties.

For example, one basic React Native component is the Image. When you create an image, you can use a prop named source to control what image it shows.

Notice the braces surrounding {pic} - these embed the variable pic into JSX. You can put any JavaScript expression inside braces in JSX.

Your own components can also use props. This lets you make a single component that is used in many different places in your app, with slightly different properties in each place by referring to props in your render function. Here's an example:

Using name as a prop lets us customize the Greeting component, so we can reuse that component for each of our greetings. This example also uses the Greeting component in JSX, similar to the Core Components. The power to do this is what makes React so cool - if you find yourself wishing that you had a different set of UI primitives to work with, you can invent new ones.

The other new thing going on here is the View component. A View is useful as a container for other components, to help control style and layout.

With props and the basic Text, Image, and View components, you can build a wide variety of static screens. To learn how to make your app change over time, you need to learn about State.

Edit this page
Last updated on
- + diff --git a/docs/publishing-forks/index.html b/docs/publishing-forks/index.html index da9b92371fb..7415552a2c0 100644 --- a/docs/publishing-forks/index.html +++ b/docs/publishing-forks/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Publish your own version of react native

TL;DR

There is a docker image that helps you build the required Android sources without installing any additional tooling (other than Docker, which can be committed to a git branch as a fully functional React Native fork release.

Run this from a fork of the React Native repo.

git checkout -d release/my-react-native-release
docker run --rm --name rn-build -v $PWD:/pwd -w /pwd reactnativecommunity/react-native-android /bin/sh -c "./gradlew installArchives"
git add android --force
git commit -a -m 'my react native forked release'
git push

Install it in your app project package.json.

"dependencies": {
...
"react-native": "myName/react-native#release/my-react-native-release"
}

Rationale

The recommended approach to working with React Native is to always update to the latest version. No support is provided on older versions and if you run into issues the contributors will always ask you to upgrade to the latest version before even looking at your particular issue. Sometimes, though, you are temporarily stuck on an older React Native version, but you require some changes from newer versions urgently (bugfixes) without having to do a full upgrade right now. This situation should be short lived by definition and once you have the time, the real solution is to upgrade to the latest version.

With this goal of a shortlived fork of React Native in mind, you can publish your own version of React Native. The facebook/react-native repository contains all the dependencies required to be used directly as a git dependency, except for the Android React Native library binary (.aar).

Building

This binary needs to become available in your project's node_modules/react-native/android folder or directly in your gradle dependency of your Android app. You can achieve this in one of two ways: Git dependency branch, Android binary dependency through Maven.

To build the .aar React Native library, you can follow the steps to build from source first to install all required tooling. Then to build the actual library, you can run the following in the root of your react-native checkout:

./gradlew :ReactAndroid:installArchives --no-daemon

If you don't want to install the required toolchain for building from source, you can use a prebuilt docker image to create a react native binary;

docker run --rm --name rn-build -v $PWD:/pwd -w /pwd reactnativecommunity/react-native-android /bin/sh -c "./gradlew installArchives"

If you haven't used the Android NDK before or if you have a NDK version not exactly matching the required version for building React Native, this is the recommended approach.

The resulting binary can be made available to app projects in one of the two ways described below.

Publishing to Maven/Nexus

Upload the binaries from the android folder to maven and point your Android app project gradle dependency for React Native to your Maven/Nexus dependency.

Publishing to a git fork dependency

Instead of uploading to Maven/Nexus, you can add the binaries built in the previous steps to git, by changing the .gitignore and committing the binaries to your forked branch. This allows you to make your fork into a functioning git dependency for React Native app projects.

If you have changes that you want to actually merge to React Native, make them on another branch first and open a PR. To start making your dependency branch, make sure you are on a 'release/my-forked-release' branch, then merge any commits that you need from yourself or others into this branch. This release branch should never be merged into any other branch.

# create .aar, then:
git add android --force
git commit -m 'my release commit'
git push

Now you can use this branch as a git dependency in your app project, by pointing your package.json dependency to this branch:

"dependencies": {
...
"react-native": "my-name/react-native#release/my-forked-release,
...
}

No other modifications to your dependencies should be necessary for your native changes to be included in your project.

Edit this page
Last updated on
- + diff --git a/docs/publishing-to-app-store.html b/docs/publishing-to-app-store.html index eae7748a842..48dd700c28f 100644 --- a/docs/publishing-to-app-store.html +++ b/docs/publishing-to-app-store.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Publishing to Apple App Store

The publishing process is the same as any other native iOS app, with some additional considerations to take into account.

If you are using Expo then read the Expo Guide for Building Standalone Apps.

1. Enable App Transport Security

App Transport Security is a security feature introduced in iOS 9 that rejects all HTTP requests that are not sent over HTTPS. This can result in HTTP traffic being blocked, including the developer React Native server. ATS is disabled for localhost by default in React Native projects in order to make development easier.

You should re-enable ATS prior to building your app for production by removing the localhost entry from the NSExceptionDomains dictionary and setting NSAllowsArbitraryLoads to false in your Info.plist file in the ios/ folder. You can also re-enable ATS from within Xcode by opening your target properties under the Info pane and editing the App Transport Security Settings entry.

If your application needs to access HTTP resources on production, see this post to learn how to configure ATS on your project.

2. Configure release scheme

Building an app for distribution in the App Store requires using the Release scheme in Xcode. Apps built for Release will automatically disable the in-app Developer menu, which will prevent your users from inadvertently accessing the menu in production. It will also bundle the JavaScript locally, so you can put the app on a device and test whilst not connected to the computer.

To configure your app to be built using the Release scheme, go to Product → Scheme → Edit Scheme. Select the Run tab in the sidebar, then set the Build Configuration dropdown to Release.

Pro Tips

As your App Bundle grows in size, you may start to see a blank screen flash between your splash screen and the display of your root application view. If this is the case, you can add the following code to AppDelegate.m in order to keep your splash screen displayed during the transition.

// Place this code after "[self.window makeKeyAndVisible]" and before "return YES;"
UIStoryboard *sb = [UIStoryboard storyboardWithName:@"LaunchScreen" bundle:nil];
UIViewController *vc = [sb instantiateInitialViewController];
rootView.loadingView = vc.view;

The static bundle is built every time you target a physical device, even in Debug. If you want to save time, turn off bundle generation in Debug by adding the following to your shell script in the Xcode Build Phase Bundle React Native code and images:

if [ "${CONFIGURATION}" == "Debug" ]; then
export SKIP_BUNDLING=true
fi

3. Build app for release

You can now build your app for release by tapping ⌘B or selecting Product → Build from the menu bar. Once built for release, you'll be able to distribute the app to beta testers and submit the app to the App Store.

You can also use the React Native CLI to perform this operation using the option --configuration with the value Release (e.g. npx react-native run-ios --configuration Release).

Edit this page
Last updated on
- + diff --git a/docs/publishing-to-app-store/index.html b/docs/publishing-to-app-store/index.html index eae7748a842..48dd700c28f 100644 --- a/docs/publishing-to-app-store/index.html +++ b/docs/publishing-to-app-store/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Publishing to Apple App Store

The publishing process is the same as any other native iOS app, with some additional considerations to take into account.

If you are using Expo then read the Expo Guide for Building Standalone Apps.

1. Enable App Transport Security

App Transport Security is a security feature introduced in iOS 9 that rejects all HTTP requests that are not sent over HTTPS. This can result in HTTP traffic being blocked, including the developer React Native server. ATS is disabled for localhost by default in React Native projects in order to make development easier.

You should re-enable ATS prior to building your app for production by removing the localhost entry from the NSExceptionDomains dictionary and setting NSAllowsArbitraryLoads to false in your Info.plist file in the ios/ folder. You can also re-enable ATS from within Xcode by opening your target properties under the Info pane and editing the App Transport Security Settings entry.

If your application needs to access HTTP resources on production, see this post to learn how to configure ATS on your project.

2. Configure release scheme

Building an app for distribution in the App Store requires using the Release scheme in Xcode. Apps built for Release will automatically disable the in-app Developer menu, which will prevent your users from inadvertently accessing the menu in production. It will also bundle the JavaScript locally, so you can put the app on a device and test whilst not connected to the computer.

To configure your app to be built using the Release scheme, go to Product → Scheme → Edit Scheme. Select the Run tab in the sidebar, then set the Build Configuration dropdown to Release.

Pro Tips

As your App Bundle grows in size, you may start to see a blank screen flash between your splash screen and the display of your root application view. If this is the case, you can add the following code to AppDelegate.m in order to keep your splash screen displayed during the transition.

// Place this code after "[self.window makeKeyAndVisible]" and before "return YES;"
UIStoryboard *sb = [UIStoryboard storyboardWithName:@"LaunchScreen" bundle:nil];
UIViewController *vc = [sb instantiateInitialViewController];
rootView.loadingView = vc.view;

The static bundle is built every time you target a physical device, even in Debug. If you want to save time, turn off bundle generation in Debug by adding the following to your shell script in the Xcode Build Phase Bundle React Native code and images:

if [ "${CONFIGURATION}" == "Debug" ]; then
export SKIP_BUNDLING=true
fi

3. Build app for release

You can now build your app for release by tapping ⌘B or selecting Product → Build from the menu bar. Once built for release, you'll be able to distribute the app to beta testers and submit the app to the App Store.

You can also use the React Native CLI to perform this operation using the option --configuration with the value Release (e.g. npx react-native run-ios --configuration Release).

Edit this page
Last updated on
- + diff --git a/docs/pushnotificationios.html b/docs/pushnotificationios.html index eefb033f8a9..663d365869c 100644 --- a/docs/pushnotificationios.html +++ b/docs/pushnotificationios.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
//Called when a notification is delivered to a foreground app.
-(void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler
{
completionHandler(UNAuthorizationOptionSound | UNAuthorizationOptionAlert | UNAuthorizationOptionBadge);
}

Then enable Background Modes/Remote notifications to be able to use remote notifications properly. The easiest way to do this is via the project settings. Navigate to Targets -> Your App -> Capabilities -> Background Modes and check Remote notifications. This will automatically enable the required settings.

Reference

Methods

presentLocalNotification()

PushNotificationIOS.presentLocalNotification(details);

Schedules the localNotification for immediate presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

scheduleLocalNotification()

PushNotificationIOS.scheduleLocalNotification(details);

Schedules the localNotification for future presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

cancelAllLocalNotifications()

PushNotificationIOS.cancelAllLocalNotifications();

Cancels all scheduled localNotifications

removeAllDeliveredNotifications()

PushNotificationIOS.removeAllDeliveredNotifications();

Remove all delivered notifications from Notification Center

getDeliveredNotifications()

PushNotificationIOS.getDeliveredNotifications(callback);

Provides you with a list of the app’s notifications that are still displayed in Notification Center

Parameters:

NameTypeRequiredDescription
callbackfunctionYesFunction which receive an array of delivered notifications.

A delivered notification is an object containing:

removeDeliveredNotifications()

PushNotificationIOS.removeDeliveredNotifications(identifiers);

Removes the specified notifications from Notification Center

Parameters:

NameTypeRequiredDescription
identifiersarrayYesArray of notification identifiers.

setApplicationIconBadgeNumber()

PushNotificationIOS.setApplicationIconBadgeNumber(number);

Sets the badge number for the app icon on the home screen

Parameters:

NameTypeRequiredDescription
numbernumberYesBadge number for the app icon.

getApplicationIconBadgeNumber()

PushNotificationIOS.getApplicationIconBadgeNumber(callback);

Gets the current badge number for the app icon on the home screen

Parameters:

NameTypeRequiredDescription
callbackfunctionYesA function that will be passed the current badge number.

cancelLocalNotifications()

PushNotificationIOS.cancelLocalNotifications(userInfo);

Cancel local notifications.

Optionally restricts the set of canceled notifications to those notifications whose userInfo fields match the corresponding fields in the userInfo argument.

Parameters:

NameTypeRequiredDescription
userInfoobjectNo

getScheduledLocalNotifications()

PushNotificationIOS.getScheduledLocalNotifications(callback);

Gets the local notifications that are currently scheduled.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesA function that will be passed an array of objects describing local notifications.

addEventListener()

PushNotificationIOS.addEventListener(type, handler);

Attaches a listener to remote or local notification events while the app is running in the foreground or the background.

Parameters:

NameTypeRequiredDescription
typestringYesEvent type.
handlerfunctionYesListener.

Valid events are:

removeEventListener()

PushNotificationIOS.removeEventListener(type, handler);

Removes the event listener. Do this in componentWillUnmount to prevent memory leaks

Parameters:

NameTypeRequiredDescription
typestringYesEvent type.
handlerfunctionYesListener.

requestPermissions()

PushNotificationIOS.requestPermissions([permissions]);

Requests notification permissions from iOS, prompting the user's dialog box. By default, it will request all notification permissions, but a subset of these can be requested by passing a map of requested permissions. The following permissions are supported:

If a map is provided to the method, only the permissions with truthy values will be requested.

This method returns a promise that will resolve when the user accepts, rejects, or if the permissions were previously rejected. The promise resolves to the current state of the permission.

Parameters:

NameTypeRequiredDescription
permissionsarrayNoalert, badge, or sound

abandonPermissions()

PushNotificationIOS.abandonPermissions();

Unregister for all remote notifications received via Apple Push Notification service.

You should call this method in rare circumstances only, such as when a new version of the app removes support for all types of remote notifications. Users can temporarily prevent apps from receiving remote notifications through the Notifications section of the Settings app. Apps unregistered through this method can always re-register.

checkPermissions()

PushNotificationIOS.checkPermissions(callback);

See what push permissions are currently enabled.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesSee below.

callback will be invoked with a permissions object:

getInitialNotification()

PushNotificationIOS.getInitialNotification();

This method returns a promise. If the app was launched by a push notification, this promise resolves to an object of type PushNotificationIOS. Otherwise, it resolves to null.

constructor()

constructor(nativeNotif);

You will never need to instantiate PushNotificationIOS yourself. Listening to the notification event and invoking getInitialNotification is sufficient.

finish()

finish(fetchResult);

This method is available for remote notifications that have been received via: application:didReceiveRemoteNotification:fetchCompletionHandler: https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623013-application?language=objc

Call this to execute when the remote notification handling is complete. When calling this block, pass in the fetch result value that best describes the results of your operation. You must call this handler and should do so as soon as possible. For a list of possible values, see PushNotificationIOS.FetchResult.

If you do not call this method your background remote notifications could be throttled, to read more about it see the above documentation link.

getMessage()

getMessage();

An alias for getAlert to get the notification's main message string

getSound()

getSound();

Gets the sound string from the aps object

getCategory()

getCategory();

Gets the category string from the aps object

getAlert()

getAlert();

Gets the notification's main message from the aps object

getContentAvailable()

getContentAvailable();

Gets the content-available number from the aps object

getBadgeCount()

getBadgeCount();

Gets the badge count number from the aps object

getData()

getData();

Gets the data object on the notification

getThreadID()

getThreadID();

Gets the thread ID on the notification

Edit this page
Last updated on
- + diff --git a/docs/pushnotificationios/index.html b/docs/pushnotificationios/index.html index eefb033f8a9..663d365869c 100644 --- a/docs/pushnotificationios/index.html +++ b/docs/pushnotificationios/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
//Called when a notification is delivered to a foreground app.
-(void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler
{
completionHandler(UNAuthorizationOptionSound | UNAuthorizationOptionAlert | UNAuthorizationOptionBadge);
}

Then enable Background Modes/Remote notifications to be able to use remote notifications properly. The easiest way to do this is via the project settings. Navigate to Targets -> Your App -> Capabilities -> Background Modes and check Remote notifications. This will automatically enable the required settings.

Reference

Methods

presentLocalNotification()

PushNotificationIOS.presentLocalNotification(details);

Schedules the localNotification for immediate presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

scheduleLocalNotification()

PushNotificationIOS.scheduleLocalNotification(details);

Schedules the localNotification for future presentation.

Parameters:

NameTypeRequiredDescription
detailsobjectYesSee below.

details is an object containing:

cancelAllLocalNotifications()

PushNotificationIOS.cancelAllLocalNotifications();

Cancels all scheduled localNotifications

removeAllDeliveredNotifications()

PushNotificationIOS.removeAllDeliveredNotifications();

Remove all delivered notifications from Notification Center

getDeliveredNotifications()

PushNotificationIOS.getDeliveredNotifications(callback);

Provides you with a list of the app’s notifications that are still displayed in Notification Center

Parameters:

NameTypeRequiredDescription
callbackfunctionYesFunction which receive an array of delivered notifications.

A delivered notification is an object containing:

removeDeliveredNotifications()

PushNotificationIOS.removeDeliveredNotifications(identifiers);

Removes the specified notifications from Notification Center

Parameters:

NameTypeRequiredDescription
identifiersarrayYesArray of notification identifiers.

setApplicationIconBadgeNumber()

PushNotificationIOS.setApplicationIconBadgeNumber(number);

Sets the badge number for the app icon on the home screen

Parameters:

NameTypeRequiredDescription
numbernumberYesBadge number for the app icon.

getApplicationIconBadgeNumber()

PushNotificationIOS.getApplicationIconBadgeNumber(callback);

Gets the current badge number for the app icon on the home screen

Parameters:

NameTypeRequiredDescription
callbackfunctionYesA function that will be passed the current badge number.

cancelLocalNotifications()

PushNotificationIOS.cancelLocalNotifications(userInfo);

Cancel local notifications.

Optionally restricts the set of canceled notifications to those notifications whose userInfo fields match the corresponding fields in the userInfo argument.

Parameters:

NameTypeRequiredDescription
userInfoobjectNo

getScheduledLocalNotifications()

PushNotificationIOS.getScheduledLocalNotifications(callback);

Gets the local notifications that are currently scheduled.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesA function that will be passed an array of objects describing local notifications.

addEventListener()

PushNotificationIOS.addEventListener(type, handler);

Attaches a listener to remote or local notification events while the app is running in the foreground or the background.

Parameters:

NameTypeRequiredDescription
typestringYesEvent type.
handlerfunctionYesListener.

Valid events are:

removeEventListener()

PushNotificationIOS.removeEventListener(type, handler);

Removes the event listener. Do this in componentWillUnmount to prevent memory leaks

Parameters:

NameTypeRequiredDescription
typestringYesEvent type.
handlerfunctionYesListener.

requestPermissions()

PushNotificationIOS.requestPermissions([permissions]);

Requests notification permissions from iOS, prompting the user's dialog box. By default, it will request all notification permissions, but a subset of these can be requested by passing a map of requested permissions. The following permissions are supported:

If a map is provided to the method, only the permissions with truthy values will be requested.

This method returns a promise that will resolve when the user accepts, rejects, or if the permissions were previously rejected. The promise resolves to the current state of the permission.

Parameters:

NameTypeRequiredDescription
permissionsarrayNoalert, badge, or sound

abandonPermissions()

PushNotificationIOS.abandonPermissions();

Unregister for all remote notifications received via Apple Push Notification service.

You should call this method in rare circumstances only, such as when a new version of the app removes support for all types of remote notifications. Users can temporarily prevent apps from receiving remote notifications through the Notifications section of the Settings app. Apps unregistered through this method can always re-register.

checkPermissions()

PushNotificationIOS.checkPermissions(callback);

See what push permissions are currently enabled.

Parameters:

NameTypeRequiredDescription
callbackfunctionYesSee below.

callback will be invoked with a permissions object:

getInitialNotification()

PushNotificationIOS.getInitialNotification();

This method returns a promise. If the app was launched by a push notification, this promise resolves to an object of type PushNotificationIOS. Otherwise, it resolves to null.

constructor()

constructor(nativeNotif);

You will never need to instantiate PushNotificationIOS yourself. Listening to the notification event and invoking getInitialNotification is sufficient.

finish()

finish(fetchResult);

This method is available for remote notifications that have been received via: application:didReceiveRemoteNotification:fetchCompletionHandler: https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623013-application?language=objc

Call this to execute when the remote notification handling is complete. When calling this block, pass in the fetch result value that best describes the results of your operation. You must call this handler and should do so as soon as possible. For a list of possible values, see PushNotificationIOS.FetchResult.

If you do not call this method your background remote notifications could be throttled, to read more about it see the above documentation link.

getMessage()

getMessage();

An alias for getAlert to get the notification's main message string

getSound()

getSound();

Gets the sound string from the aps object

getCategory()

getCategory();

Gets the category string from the aps object

getAlert()

getAlert();

Gets the notification's main message from the aps object

getContentAvailable()

getContentAvailable();

Gets the content-available number from the aps object

getBadgeCount()

getBadgeCount();

Gets the badge count number from the aps object

getData()

getData();

Gets the data object on the notification

getThreadID()

getThreadID();

Gets the thread ID on the notification

Edit this page
Last updated on
- + diff --git a/docs/ram-bundles-inline-requires.html b/docs/ram-bundles-inline-requires.html index 2edfc6f0248..48738828a6c 100644 --- a/docs/ram-bundles-inline-requires.html +++ b/docs/ram-bundles-inline-requires.html @@ -19,7 +19,7 @@ - + @@ -45,7 +45,7 @@
module.exports = config;

The preloadedModules entry in the config indicates which modules should be marked as preloaded when building a RAM bundle. When the bundle is loaded, those modules are immediately loaded, before any requires have even executed. The blacklist entry indicates that those modules should not be required inline. Because they are preloaded, there is no performance benefit from using an inline require. In fact the javascript spends extra time resolving the inline require every time the imports are referenced.

Test and Measure Improvements

You should now be ready to build your app using the RAM format and inline requires. Make sure you measure the before and after startup times.

Edit this page
Last updated on
- + diff --git a/docs/ram-bundles-inline-requires/index.html b/docs/ram-bundles-inline-requires/index.html index 2edfc6f0248..48738828a6c 100644 --- a/docs/ram-bundles-inline-requires/index.html +++ b/docs/ram-bundles-inline-requires/index.html @@ -19,7 +19,7 @@ - + @@ -45,7 +45,7 @@
module.exports = config;

The preloadedModules entry in the config indicates which modules should be marked as preloaded when building a RAM bundle. When the bundle is loaded, those modules are immediately loaded, before any requires have even executed. The blacklist entry indicates that those modules should not be required inline. Because they are preloaded, there is no performance benefit from using an inline require. In fact the javascript spends extra time resolving the inline require every time the imports are referenced.

Test and Measure Improvements

You should now be ready to build your app using the RAM format and inline requires. Make sure you measure the before and after startup times.

Edit this page
Last updated on
- + diff --git a/docs/react-node.html b/docs/react-node.html index 4329ac3ea23..b53245c614a 100644 --- a/docs/react-node.html +++ b/docs/react-node.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

React Node Object Type

A React Node is one of the following types:

  • Boolean (which is ignored)
  • null or undefined (which is ignored)
  • Number
  • String
  • A React element (result of JSX)
  • An array of any of the above, possibly a nested one
Edit this page
Last updated on
- + diff --git a/docs/react-node/index.html b/docs/react-node/index.html index 4329ac3ea23..b53245c614a 100644 --- a/docs/react-node/index.html +++ b/docs/react-node/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

React Node Object Type

A React Node is one of the following types:

  • Boolean (which is ignored)
  • null or undefined (which is ignored)
  • Number
  • String
  • A React element (result of JSX)
  • An array of any of the above, possibly a nested one
Edit this page
Last updated on
- + diff --git a/docs/rect.html b/docs/rect.html index 867f90ad5fc..58dcd614fcd 100644 --- a/docs/rect.html +++ b/docs/rect.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Rect Object Type

Rect accepts numeric pixel values to describe how far to extend a rectangular area. These values are added to the original area's size to expand it.

Example

{
bottom: 20,
left: null,
right: undefined,
top: 50
}

Keys and values

bottom

TypeRequired
number, null, undefinedNo

left

TypeRequired
number, null, undefinedNo

right

TypeRequired
number, null, undefinedNo

top

TypeRequired
number, null, undefinedNo

Used by

Edit this page
Last updated on
- + diff --git a/docs/rect/index.html b/docs/rect/index.html index 867f90ad5fc..58dcd614fcd 100644 --- a/docs/rect/index.html +++ b/docs/rect/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Rect Object Type

Rect accepts numeric pixel values to describe how far to extend a rectangular area. These values are added to the original area's size to expand it.

Example

{
bottom: 20,
left: null,
right: undefined,
top: 50
}

Keys and values

bottom

TypeRequired
number, null, undefinedNo

left

TypeRequired
number, null, undefinedNo

right

TypeRequired
number, null, undefinedNo

top

TypeRequired
number, null, undefinedNo

Used by

Edit this page
Last updated on
- + diff --git a/docs/refreshcontrol.html b/docs/refreshcontrol.html index 5548d89d2f9..02adce971cc 100644 --- a/docs/refreshcontrol.html +++ b/docs/refreshcontrol.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

RefreshControl

This component is used inside a ScrollView or ListView to add pull to refresh functionality. When the ScrollView is at scrollY: 0, swiping down triggers an onRefresh event.

Example

Note: refreshing is a controlled prop, this is why it needs to be set to true in the onRefresh function otherwise the refresh indicator will stop immediately.

Reference

Props

Inherits View Props.

refreshing

Whether the view should be indicating an active refresh.

TypeRequired
boolYes

onRefresh

Called when the view starts refreshing.

TypeRequired
functionNo

colors

The colors (at least one) that will be used to draw the refresh indicator.

TypeRequiredPlatform
array of colorNoAndroid

enabled

Whether the pull to refresh functionality is enabled.

TypeRequiredPlatform
boolNoAndroid

progressBackgroundColor

The background color of the refresh indicator.

TypeRequiredPlatform
colorNoAndroid

progressViewOffset

Progress view top offset

TypeRequiredPlatform
numberNoAndroid

size

Size of the refresh indicator, see RefreshControl.SIZE.

TypeRequiredPlatform
enum(RefreshLayoutConsts.SIZE.DEFAULT, RefreshLayoutConsts.SIZE.LARGE)NoAndroid

tintColor

The color of the refresh indicator.

TypeRequiredPlatform
colorNoiOS

title

The title displayed under the refresh indicator.

TypeRequiredPlatform
stringNoiOS

titleColor

Title color.

TypeRequiredPlatform
colorNoiOS
Edit this page
Last updated on
- + diff --git a/docs/refreshcontrol/index.html b/docs/refreshcontrol/index.html index 5548d89d2f9..02adce971cc 100644 --- a/docs/refreshcontrol/index.html +++ b/docs/refreshcontrol/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

RefreshControl

This component is used inside a ScrollView or ListView to add pull to refresh functionality. When the ScrollView is at scrollY: 0, swiping down triggers an onRefresh event.

Example

Note: refreshing is a controlled prop, this is why it needs to be set to true in the onRefresh function otherwise the refresh indicator will stop immediately.

Reference

Props

Inherits View Props.

refreshing

Whether the view should be indicating an active refresh.

TypeRequired
boolYes

onRefresh

Called when the view starts refreshing.

TypeRequired
functionNo

colors

The colors (at least one) that will be used to draw the refresh indicator.

TypeRequiredPlatform
array of colorNoAndroid

enabled

Whether the pull to refresh functionality is enabled.

TypeRequiredPlatform
boolNoAndroid

progressBackgroundColor

The background color of the refresh indicator.

TypeRequiredPlatform
colorNoAndroid

progressViewOffset

Progress view top offset

TypeRequiredPlatform
numberNoAndroid

size

Size of the refresh indicator, see RefreshControl.SIZE.

TypeRequiredPlatform
enum(RefreshLayoutConsts.SIZE.DEFAULT, RefreshLayoutConsts.SIZE.LARGE)NoAndroid

tintColor

The color of the refresh indicator.

TypeRequiredPlatform
colorNoiOS

title

The title displayed under the refresh indicator.

TypeRequiredPlatform
stringNoiOS

titleColor

Title color.

TypeRequiredPlatform
colorNoiOS
Edit this page
Last updated on
- + diff --git a/docs/removing-default-permissions.html b/docs/removing-default-permissions.html index f17f5dbab4b..2122105619f 100644 --- a/docs/removing-default-permissions.html +++ b/docs/removing-default-permissions.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Removing Default Permissions

By default, some permissions are added to your Android APK.

The default permissions that get added are:

  • android.permission.INTERNET - Required for debug mode.
  • android.permission.SYSTEM_ALERT_WINDOW - Required for debug mode.
  • android.permission.READ_PHONE_STATE - Not required for debug or production.
  • android.permission.WRITE_EXTERNAL_STORAGE - Not required for debug or production.
  • android.permission.READ_EXTERNAL_STORAGE - Not required for debug or production.

  1. Let's start by removing READ_PHONE_STATE, WRITE_EXTERNAL_STORAGE, and READ_EXTERNAL_STORAGE from both production and debug APKs, as it is not required in either. These storage permissions are still not needed if AsyncStorage module is in use, so it is safe to remove from both production and debug.

  2. Open your android/app/src/main/AndroidManifest.xml file.

  3. Even though these three permissions are not listed in the manifest they get added in. We add the three permissions with tools:node="remove" attribute, to make sure it gets removed during build. Note that the package identifier will be different, for below it is "com.myapp" because the project was created with npx react-native init myapp.

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.myappid"
    + xmlns:tools="http://schemas.android.com/tools"
    >
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
    + <uses-permission tools:node="remove" android:name="android.permission.READ_PHONE_STATE" />
    + <uses-permission tools:node="remove" android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    + <uses-permission tools:node="remove" android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <application
    android:name=".MainApplication"
    android:label="@string/app_name"
    android:icon="@mipmap/ic_launcher"
    android:allowBackup="false"
    android:theme="@style/AppTheme">
    <activity
    android:name=".MainActivity"
    android:label="@string/app_name"
    android:configChanges="keyboard|keyboardHidden|orientation|screenSize"
    android:windowSoftInputMode="adjustResize">
    <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    </activity>
    <activity android:name="com.facebook.react.devsupport.DevSettingsActivity" />
    </application>
    </manifest>

That's it. We did not remove the INTERNET permission as pretty much all apps use it. Now whenever you create a production APK, these 3 permissions will be removed. When you create a debug APK (npx react-native run-android) it will install the APK with these permissions added.

Hint

If your App is free to use in the App-Store and there is no "In-App-Purchase" possible in your App, you also can remove:

  • android.vending.CHECK_LICENSE
Edit this page
Last updated on
- + diff --git a/docs/removing-default-permissions/index.html b/docs/removing-default-permissions/index.html index f17f5dbab4b..2122105619f 100644 --- a/docs/removing-default-permissions/index.html +++ b/docs/removing-default-permissions/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Removing Default Permissions

By default, some permissions are added to your Android APK.

The default permissions that get added are:

  • android.permission.INTERNET - Required for debug mode.
  • android.permission.SYSTEM_ALERT_WINDOW - Required for debug mode.
  • android.permission.READ_PHONE_STATE - Not required for debug or production.
  • android.permission.WRITE_EXTERNAL_STORAGE - Not required for debug or production.
  • android.permission.READ_EXTERNAL_STORAGE - Not required for debug or production.

  1. Let's start by removing READ_PHONE_STATE, WRITE_EXTERNAL_STORAGE, and READ_EXTERNAL_STORAGE from both production and debug APKs, as it is not required in either. These storage permissions are still not needed if AsyncStorage module is in use, so it is safe to remove from both production and debug.

  2. Open your android/app/src/main/AndroidManifest.xml file.

  3. Even though these three permissions are not listed in the manifest they get added in. We add the three permissions with tools:node="remove" attribute, to make sure it gets removed during build. Note that the package identifier will be different, for below it is "com.myapp" because the project was created with npx react-native init myapp.

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.myappid"
    + xmlns:tools="http://schemas.android.com/tools"
    >
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
    + <uses-permission tools:node="remove" android:name="android.permission.READ_PHONE_STATE" />
    + <uses-permission tools:node="remove" android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    + <uses-permission tools:node="remove" android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <application
    android:name=".MainApplication"
    android:label="@string/app_name"
    android:icon="@mipmap/ic_launcher"
    android:allowBackup="false"
    android:theme="@style/AppTheme">
    <activity
    android:name=".MainActivity"
    android:label="@string/app_name"
    android:configChanges="keyboard|keyboardHidden|orientation|screenSize"
    android:windowSoftInputMode="adjustResize">
    <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    </activity>
    <activity android:name="com.facebook.react.devsupport.DevSettingsActivity" />
    </application>
    </manifest>

That's it. We did not remove the INTERNET permission as pretty much all apps use it. Now whenever you create a production APK, these 3 permissions will be removed. When you create a debug APK (npx react-native run-android) it will install the APK with these permissions added.

Hint

If your App is free to use in the App-Store and there is no "In-App-Purchase" possible in your App, you also can remove:

  • android.vending.CHECK_LICENSE
Edit this page
Last updated on
- + diff --git a/docs/running-on-device.html b/docs/running-on-device.html index 1fe64379593..c14155ea84e 100644 --- a/docs/running-on-device.html +++ b/docs/running-on-device.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Running On Device

It's always a good idea to test your app on an actual device before releasing it to your users. This document will guide you through the necessary steps to run your React Native app on a device and to get it ready for production.

If you used Expo CLI or Create React Native App to set up your project, you can preview your app on a device by scanning the QR code with the Expo app—but in order to build and run your app on a device, you will need to eject and install the native code dependencies from the environment setup guide.

Running your app on Android devices

Development OS

1. Enable Debugging over USB

Most Android devices can only install and run apps downloaded from Google Play, by default. You will need to enable USB Debugging on your device in order to install your app during development.

To enable USB debugging on your device, you will first need to enable the "Developer options" menu by going to Settings → About phone → Software information and then tapping the Build number row at the bottom seven times. You can then go back to Settings → Developer options to enable "USB debugging".

2. Plug in your device via USB

Let's now set up an Android device to run our React Native projects. Go ahead and plug in your device via USB to your development machine.

Next, check the manufacturer code by using lsusb (on mac, you must first install lsusb). lsusb should output something like this:

$ lsusb
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 003: ID 22b8:2e76 Motorola PCS
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

These lines represent the USB devices currently connected to your machine.

You want the line that represents your phone. If you're in doubt, try unplugging your phone and running the command again:

$ lsusb
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

You'll see that after removing the phone, the line which has the phone model ("Motorola PCS" in this case) disappeared from the list. This is the line that we care about.

Bus 001 Device 003: ID 22b8:2e76 Motorola PCS

From the above line, you want to grab the first four digits from the device ID:

22b8:2e76

In this case, it's 22b8. That's the identifier for Motorola.

You'll need to input this into your udev rules in order to get up and running:

echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="22b8", MODE="0666", GROUP="plugdev"' | sudo tee /etc/udev/rules.d/51-android-usb.rules

Make sure that you replace 22b8 with the identifier you get in the above command.

Now check that your device is properly connecting to ADB, the Android Debug Bridge, by running adb devices.

$ adb devices
List of devices attached
emulator-5554 offline # Google emulator
14ed2fcc device # Physical device

Seeing device in the right column means the device is connected. You must have only one device connected at a time.

3. Run your app

Type the following in your command prompt to install and launch your app on the device:

$ npx react-native run-android

If you get a "bridge configuration isn't available" error, see Using adb reverse.

Hint: You can also use the React Native CLI to generate and run a Release build (e.g. npx react-native run-android --variant=release).

Connecting to the development server

You can also iterate quickly on a device by connecting to the development server running on your development machine. There are several ways of accomplishing this, depending on whether you have access to a USB cable or a Wi-Fi network.

Method 1: Using adb reverse (recommended)

You can use this method if your device is running Android 5.0 (Lollipop) or newer, it has USB debugging enabled, and it is connected via USB to your development machine.

Run the following in a command prompt:

$ adb -s <device name> reverse tcp:8081 tcp:8081

To find the device name, run the following adb command:

$ adb devices

You can now enable Live reloading from the Developer menu. Your app will reload whenever your JavaScript code has changed.

Method 2: Connect via Wi-Fi

You can also connect to the development server over Wi-Fi. You'll first need to install the app on your device using a USB cable, but once that has been done you can debug wirelessly by following these instructions. You'll need your development machine's current IP address before proceeding.

Open a terminal and type /sbin/ifconfig to find your machine's IP address.

  1. Make sure your laptop and your phone are on the same Wi-Fi network.
  2. Open your React Native app on your device.
  3. You'll see a red screen with an error. This is OK. The following steps will fix that.
  4. Open the in-app Developer menu.
  5. Go to Dev Settings → Debug server host & port for device.
  6. Type in your machine's IP address and the port of the local dev server (e.g. 10.0.1.1:8081).
  7. Go back to the Developer menu and select Reload JS.

You can now enable Live reloading from the Developer menu. Your app will reload whenever your JavaScript code has changed.

Building your app for production

You have built a great app using React Native, and you are now itching to release it in the Play Store. The process is the same as any other native Android app, with some additional considerations to take into account. Follow the guide for generating a signed APK to learn more.

Edit this page
Last updated on
- + diff --git a/docs/running-on-device/index.html b/docs/running-on-device/index.html index 1fe64379593..c14155ea84e 100644 --- a/docs/running-on-device/index.html +++ b/docs/running-on-device/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Running On Device

It's always a good idea to test your app on an actual device before releasing it to your users. This document will guide you through the necessary steps to run your React Native app on a device and to get it ready for production.

If you used Expo CLI or Create React Native App to set up your project, you can preview your app on a device by scanning the QR code with the Expo app—but in order to build and run your app on a device, you will need to eject and install the native code dependencies from the environment setup guide.

Running your app on Android devices

Development OS

1. Enable Debugging over USB

Most Android devices can only install and run apps downloaded from Google Play, by default. You will need to enable USB Debugging on your device in order to install your app during development.

To enable USB debugging on your device, you will first need to enable the "Developer options" menu by going to Settings → About phone → Software information and then tapping the Build number row at the bottom seven times. You can then go back to Settings → Developer options to enable "USB debugging".

2. Plug in your device via USB

Let's now set up an Android device to run our React Native projects. Go ahead and plug in your device via USB to your development machine.

Next, check the manufacturer code by using lsusb (on mac, you must first install lsusb). lsusb should output something like this:

$ lsusb
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 003: ID 22b8:2e76 Motorola PCS
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

These lines represent the USB devices currently connected to your machine.

You want the line that represents your phone. If you're in doubt, try unplugging your phone and running the command again:

$ lsusb
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

You'll see that after removing the phone, the line which has the phone model ("Motorola PCS" in this case) disappeared from the list. This is the line that we care about.

Bus 001 Device 003: ID 22b8:2e76 Motorola PCS

From the above line, you want to grab the first four digits from the device ID:

22b8:2e76

In this case, it's 22b8. That's the identifier for Motorola.

You'll need to input this into your udev rules in order to get up and running:

echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="22b8", MODE="0666", GROUP="plugdev"' | sudo tee /etc/udev/rules.d/51-android-usb.rules

Make sure that you replace 22b8 with the identifier you get in the above command.

Now check that your device is properly connecting to ADB, the Android Debug Bridge, by running adb devices.

$ adb devices
List of devices attached
emulator-5554 offline # Google emulator
14ed2fcc device # Physical device

Seeing device in the right column means the device is connected. You must have only one device connected at a time.

3. Run your app

Type the following in your command prompt to install and launch your app on the device:

$ npx react-native run-android

If you get a "bridge configuration isn't available" error, see Using adb reverse.

Hint: You can also use the React Native CLI to generate and run a Release build (e.g. npx react-native run-android --variant=release).

Connecting to the development server

You can also iterate quickly on a device by connecting to the development server running on your development machine. There are several ways of accomplishing this, depending on whether you have access to a USB cable or a Wi-Fi network.

Method 1: Using adb reverse (recommended)

You can use this method if your device is running Android 5.0 (Lollipop) or newer, it has USB debugging enabled, and it is connected via USB to your development machine.

Run the following in a command prompt:

$ adb -s <device name> reverse tcp:8081 tcp:8081

To find the device name, run the following adb command:

$ adb devices

You can now enable Live reloading from the Developer menu. Your app will reload whenever your JavaScript code has changed.

Method 2: Connect via Wi-Fi

You can also connect to the development server over Wi-Fi. You'll first need to install the app on your device using a USB cable, but once that has been done you can debug wirelessly by following these instructions. You'll need your development machine's current IP address before proceeding.

Open a terminal and type /sbin/ifconfig to find your machine's IP address.

  1. Make sure your laptop and your phone are on the same Wi-Fi network.
  2. Open your React Native app on your device.
  3. You'll see a red screen with an error. This is OK. The following steps will fix that.
  4. Open the in-app Developer menu.
  5. Go to Dev Settings → Debug server host & port for device.
  6. Type in your machine's IP address and the port of the local dev server (e.g. 10.0.1.1:8081).
  7. Go back to the Developer menu and select Reload JS.

You can now enable Live reloading from the Developer menu. Your app will reload whenever your JavaScript code has changed.

Building your app for production

You have built a great app using React Native, and you are now itching to release it in the Play Store. The process is the same as any other native Android app, with some additional considerations to take into account. Follow the guide for generating a signed APK to learn more.

Edit this page
Last updated on
- + diff --git a/docs/running-on-simulator-ios.html b/docs/running-on-simulator-ios.html index 59b29ad067e..fe18ff35ed0 100644 --- a/docs/running-on-simulator-ios.html +++ b/docs/running-on-simulator-ios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Running On Simulator

Starting the simulator

Once you have your React Native project initialized, you can run npx react-native run-ios inside the newly created project directory. If everything is set up correctly, you should see your new app running in the iOS Simulator shortly.

Specifying a device

You can specify the device the simulator should run with the --simulator flag, followed by the device name as a string. The default is "iPhone 11". If you wish to run your app on an iPhone SE, run npx react-native run-ios --simulator="iPhone SE".

The device names correspond to the list of devices available in Xcode. You can check your available devices by running xcrun simctl list devices from the console.

Edit this page
Last updated on
- + diff --git a/docs/running-on-simulator-ios/index.html b/docs/running-on-simulator-ios/index.html index 59b29ad067e..fe18ff35ed0 100644 --- a/docs/running-on-simulator-ios/index.html +++ b/docs/running-on-simulator-ios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Running On Simulator

Starting the simulator

Once you have your React Native project initialized, you can run npx react-native run-ios inside the newly created project directory. If everything is set up correctly, you should see your new app running in the iOS Simulator shortly.

Specifying a device

You can specify the device the simulator should run with the --simulator flag, followed by the device name as a string. The default is "iPhone 11". If you wish to run your app on an iPhone SE, run npx react-native run-ios --simulator="iPhone SE".

The device names correspond to the list of devices available in Xcode. You can check your available devices by running xcrun simctl list devices from the console.

Edit this page
Last updated on
- + diff --git a/docs/safeareaview.html b/docs/safeareaview.html index fbd811f2112..f61b715660e 100644 --- a/docs/safeareaview.html +++ b/docs/safeareaview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

SafeAreaView

The purpose of SafeAreaView is to render content within the safe area boundaries of a device. It is currently only applicable to iOS devices with iOS version 11 or later.

SafeAreaView renders nested content and automatically applies padding to reflect the portion of the view that is not covered by navigation bars, tab bars, toolbars, and other ancestor views. Moreover, and most importantly, Safe Area's paddings reflect the physical limitation of the screen, such as rounded corners or camera notches (i.e. the sensor housing area on iPhone X).

Example

To use, wrap your top level view with a SafeAreaView with a flex: 1 style applied to it. You may also want to use a background color that matches your application's design.

Reference

Props

Inherits View Props.

As padding is used to implement the behavior of the component, padding rules in styles applied to a SafeAreaView will be ignored and can cause different results depending on the platform. See #22211 for details.

emulateUnlessSupported

TypeRequiredDefault
boolNotrue
Edit this page
Last updated on
- + diff --git a/docs/safeareaview/index.html b/docs/safeareaview/index.html index fbd811f2112..f61b715660e 100644 --- a/docs/safeareaview/index.html +++ b/docs/safeareaview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

SafeAreaView

The purpose of SafeAreaView is to render content within the safe area boundaries of a device. It is currently only applicable to iOS devices with iOS version 11 or later.

SafeAreaView renders nested content and automatically applies padding to reflect the portion of the view that is not covered by navigation bars, tab bars, toolbars, and other ancestor views. Moreover, and most importantly, Safe Area's paddings reflect the physical limitation of the screen, such as rounded corners or camera notches (i.e. the sensor housing area on iPhone X).

Example

To use, wrap your top level view with a SafeAreaView with a flex: 1 style applied to it. You may also want to use a background color that matches your application's design.

Reference

Props

Inherits View Props.

As padding is used to implement the behavior of the component, padding rules in styles applied to a SafeAreaView will be ignored and can cause different results depending on the platform. See #22211 for details.

emulateUnlessSupported

TypeRequiredDefault
boolNotrue
Edit this page
Last updated on
- + diff --git a/docs/scrollview.html b/docs/scrollview.html index e3345f23a93..471234e672d 100644 --- a/docs/scrollview.html +++ b/docs/scrollview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

ScrollView

Component that wraps platform ScrollView while providing integration with touch locking "responder" system.

Keep in mind that ScrollViews must have a bounded height in order to work, since they contain unbounded-height children into a bounded container (via a scroll interaction). In order to bound the height of a ScrollView, either set the height of the view directly (discouraged) or make sure all parent views have bounded height. Forgetting to transfer {flex: 1} down the view stack can lead to errors here, which the element inspector makes quick to debug.

Doesn't yet support other contained responders from blocking this scroll view from becoming the responder.

<ScrollView> vs <FlatList> - which one to use?

ScrollView renders all its react child components at once, but this has a performance downside.

Imagine you have a very long list of items you want to display, maybe several screens worth of content. Creating JS components and native views for everything all at once, much of which may not even be shown, will contribute to slow rendering and increased memory usage.

This is where FlatList comes into play. FlatList renders items lazily, when they are about to appear, and removes items that scroll way off screen to save memory and processing time.

FlatList is also handy if you want to render separators between your items, multiple columns, infinite scroll loading, or any number of other features it supports out of the box.

Example

Reference

Props

Inherits View Props.

StickyHeaderComponent

A React Component that will be used to render sticky headers, should be used together with stickyHeaderIndices. You may need to set this component if your sticky header uses custom transforms, for example, when you want your list to have an animated and hidable header. If component have not been provided, the default ScrollViewStickyHeader component will be used.

TypeRequired
component, elementNo

alwaysBounceHorizontal

When true, the scroll view bounces horizontally when it reaches the end even if the content is smaller than the scroll view itself. The default value is true when horizontal={true} and false otherwise.

TypeRequiredPlatform
boolNoiOS

alwaysBounceVertical

When true, the scroll view bounces vertically when it reaches the end even if the content is smaller than the scroll view itself. The default value is false when vertical={true} and true otherwise.

TypeRequiredPlatform
boolNoiOS

automaticallyAdjustContentInsets

Controls whether iOS should automatically adjust the content inset for scroll views that are placed behind a navigation bar or tab bar/ toolbar. The default value is true.

TypeRequiredPlatform
boolNoiOS

bounces

When true, the scroll view bounces when it reaches the end of the content if the content is larger then the scroll view along the axis of the scroll direction. When false, it disables all bouncing even if the alwaysBounce* props are true. The default value is true.

TypeRequiredPlatform
boolNoiOS

bouncesZoom

When true, gestures can drive zoom past min/max and the zoom will animate to the min/max value at gesture end, otherwise the zoom will not exceed the limits.

TypeRequiredPlatform
boolNoiOS

canCancelContentTouches

When false, once tracking starts, won't try to drag if the touch moves. The default value is true.

TypeRequiredPlatform
boolNoiOS

centerContent

When true, the scroll view automatically centers the content when the content is smaller than the scroll view bounds; when the content is larger than the scroll view, this property has no effect. The default value is false.

TypeRequiredPlatform
boolNoiOS

contentContainerStyle

These styles will be applied to the scroll view content container which wraps all of the child views. Example:

return (
<ScrollView contentContainerStyle={styles.contentContainer}>
</ScrollView>
);
...
const styles = StyleSheet.create({
contentContainer: {
paddingVertical: 20
}
});
TypeRequired
StyleSheetPropType(View Style props)No

contentInset

The amount by which the scroll view content is inset from the edges of the scroll view. Defaults to {top: 0, left: 0, bottom: 0, right: 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

contentInsetAdjustmentBehavior

This property specifies how the safe area insets are used to modify the content area of the scroll view. The default value of this property is "never". Available on iOS 11 and later.

TypeRequiredPlatform
enum('automatic', 'scrollableAxes', 'never', 'always')NoiOS

contentOffset

Used to manually set the starting scroll offset. The default value is {x: 0, y: 0}.

TypeRequiredPlatform
PointPropTypeNoiOS

decelerationRate

A floating-point number that determines how quickly the scroll view decelerates after the user lifts their finger. You may also use string shortcuts "normal" and "fast" which match the underlying iOS settings for UIScrollViewDecelerationRateNormal and UIScrollViewDecelerationRateFast respectively.

  • 'normal' (the default), 0.998 on iOS, 0.985 on Android.
  • 'fast', 0.99 on iOS, 0.9 on Android.
TypeRequired
enum('fast', 'normal'), ,numberNo

directionalLockEnabled

When true, the ScrollView will try to lock to only vertical or horizontal scrolling while dragging. The default value is false.

TypeRequiredPlatform
boolNoiOS

disableIntervalMomentum

When true, the scroll view stops on the next index (in relation to scroll position at release) regardless of how fast the gesture is. This can be used for horizontal pagination when the page is less than the width of the ScrollView. The default value is false.

TypeRequired
boolNo

disableScrollViewPanResponder

When true, the default JS pan responder on the ScrollView is disabled, and full control over touches inside the ScrollView is left to its child components. This is particularly useful if snapToInterval is enabled, since it does not follow typical touch patterns. Do not use this on regular ScrollView use cases without snapToInterval as it may cause unexpected touches to occur while scrolling. The default value is false.

TypeRequired
boolNo

endFillColor

Sometimes a scrollview takes up more space than its content fills. When this is the case, this prop will fill the rest of the scrollview with a color to avoid setting a background and creating unnecessary overdraw. This is an advanced optimization that is not needed in the general case.

TypeRequiredPlatform
colorNoAndroid

fadingEdgeLength

Fades out the edges of the the scroll content.

If the value is greater than 0, the fading edges will be set accordingly to the current scroll direction and position, indicating if there is more content to show.

TypeRequiredDefaultPlatform
numberNo0Android

horizontal

When true, the scroll view's children are arranged horizontally in a row instead of vertically in a column. The default value is false.

TypeRequired
boolNo

indicatorStyle

The style of the scroll indicators.

  • 'default' (the default), same as black.
  • 'black', scroll indicator is black. This style is good against a light background.
  • 'white', scroll indicator is white. This style is good against a dark background.
TypeRequiredPlatform
enum('default', 'black', 'white')NoiOS

invertStickyHeaders

If sticky headers should stick at the bottom instead of the top of the ScrollView. This is usually used with inverted ScrollViews.

TypeRequired
boolNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

Cross platform

  • 'none' (the default), drags do not dismiss the keyboard.
  • 'on-drag', the keyboard is dismissed when a drag begins.

iOS Only

  • 'interactive', the keyboard is dismissed interactively with the drag and moves in synchrony with the touch; dragging upwards cancels the dismissal. On android this is not supported and it will have the same behavior as 'none'.
TypeRequired
enum('none', 'on-drag', 'interactive')No

keyboardShouldPersistTaps

Determines when the keyboard should stay visible after a tap.

  • 'never' (the default), tapping outside of the focused text input when the keyboard is up dismisses the keyboard. When this happens, children won't receive the tap.
  • 'always', the keyboard will not dismiss automatically, and the scroll view will not catch taps, but children of the scroll view can catch taps.
  • 'handled', the keyboard will not dismiss automatically when the tap was handled by children of the scroll view (or captured by an ancestor).
  • false, deprecated, use 'never' instead
  • true, deprecated, use 'always' instead
TypeRequired
enum('always', 'never', 'handled', false, true)No

maintainVisibleContentPosition

When set, the scroll view will adjust the scroll position so that the first child that is currently visible and at or beyond minIndexForVisible will not change position. This is useful for lists that are loading content in both directions, e.g. a chat thread, where new messages coming in might otherwise cause the scroll position to jump. A value of 0 is common, but other values such as 1 can be used to skip loading spinners or other content that should not maintain position.

The optional autoscrollToTopThreshold can be used to make the content automatically scroll to the top after making the adjustment if the user was within the threshold of the top before the adjustment was made. This is also useful for chat-like applications where you want to see new messages scroll into place, but not if the user has scrolled up a ways and it would be disruptive to scroll a bunch.

Caveat 1: Reordering elements in the scrollview with this enabled will probably cause jumpiness and jank. It can be fixed, but there are currently no plans to do so. For now, don't re-order the content of any ScrollViews or Lists that use this feature.

Caveat 2: This uses contentOffset and frame.origin in native code to compute visibility. Occlusion, transforms, and other complexity won't be taken into account as to whether content is "visible" or not.

TypeRequiredPlatform
object: { minIndexForVisible: number, autoscrollToTopThreshold: number }NoiOS

maximumZoomScale

The maximum allowed zoom scale. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

minimumZoomScale

The minimum allowed zoom scale. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

nestedScrollEnabled

Enables nested scrolling for Android API level 21+. Nested scrolling is supported by default on iOS.

TypeRequiredPlatform
boolNoAndroid

onContentSizeChange

Called when scrollable content view of the ScrollView changes.

Handler function is passed the content width and content height as parameters: (contentWidth, contentHeight)

It's implemented using onLayout handler attached to the content container which this ScrollView renders.

TypeRequired
functionNo

onMomentumScrollBegin

Called when the momentum scroll starts (scroll which occurs as the ScrollView starts gliding).

TypeRequired
functionNo

onMomentumScrollEnd

Called when the momentum scroll ends (scroll which occurs as the ScrollView glides to a stop).

TypeRequired
functionNo

onScroll

Fires at most once per frame during scrolling. The frequency of the events can be controlled using the scrollEventThrottle prop. The event has the following shape (all values are numbers):

{
nativeEvent: {
contentInset: {bottom, left, right, top},
contentOffset: {x, y},
contentSize: {height, width},
layoutMeasurement: {height, width},
zoomScale
}
}
TypeRequired
functionNo

onScrollBeginDrag

Called when the user begins to drag the scroll view.

TypeRequired
functionNo

onScrollEndDrag

Called when the user stops dragging the scroll view and it either stops or begins to glide.

TypeRequired
functionNo

onScrollToTop

Fires when the scroll view scrolls to top after the status bar has been tapped.

TypeRequiredPlatform
functionNoiOS

overScrollMode

Used to override default value of overScroll mode.

Possible values:

  • 'auto' - Default value, allow a user to over-scroll this view only if the content is large enough to meaningfully scroll.
  • 'always' - Always allow a user to over-scroll this view.
  • 'never' - Never allow a user to over-scroll this view.
TypeRequiredPlatform
enum('auto', 'always', 'never')NoAndroid

pagingEnabled

When true, the scroll view stops on multiples of the scroll view's size when scrolling. This can be used for horizontal pagination. The default value is false.

Note: Vertical pagination is not supported on Android.

TypeRequired
boolNo

persistentScrollbar

Causes the scrollbars not to turn transparent when they are not in use. The default value is false.

TypeRequiredPlatform
boolNoAndroid

pinchGestureEnabled

When true, ScrollView allows use of pinch gestures to zoom in and out. The default value is true.

TypeRequiredPlatform
boolNoiOS

refreshControl

A RefreshControl component, used to provide pull-to-refresh functionality for the ScrollView. Only works for vertical ScrollViews (horizontal prop must be false).

See RefreshControl.

TypeRequired
elementNo

removeClippedSubviews

Experimental: When true, offscreen child views (whose overflow value is hidden) are removed from their native backing superview when offscreen. This can improve scrolling performance on long lists.

TypeRequired
boolNo

scrollBarThumbImage

Optionally an image can be used for the scroll bar thumb. This will override the color. While the image is loading or the image fails to load the color will be used instead. Use an alpha of 0 in the color to avoid seeing it while the image is loading.

  • uri, a string representing the resource identifier for the image, which should be either a local file path or the name of a static image resource.
  • number, opaque type returned by something like import IMAGE from './image.jpg'.
TypeRequiredPlatform
numberNoVR

scrollEnabled

When false, the view cannot be scrolled via touch interaction. The default value is true.

Note that the view can always be scrolled by calling scrollTo.

TypeRequired
boolNo

scrollEventThrottle

This controls how often the scroll event will be fired while scrolling (as a time interval in ms). A lower number yields better accuracy for code that is tracking the scroll position, but can lead to scroll performance problems due to the volume of information being sent over the bridge. You will not notice a difference between values set between 1-16 as the JS run loop is synced to the screen refresh rate. If you do not need precise scroll position tracking, set this value higher to limit the information being sent across the bridge. The default value is zero, which results in the scroll event being sent only once each time the view is scrolled.

TypeRequiredPlatform
numberNoiOS

scrollIndicatorInsets

The amount by which the scroll view indicators are inset from the edges of the scroll view. This should normally be set to the same value as the contentInset. Defaults to {0, 0, 0, 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

scrollPerfTag

Tag used to log scroll performance on this scroll view. Will force momentum events to be turned on (see sendMomentumEvents). This doesn't do anything out of the box and you need to implement a custom native FpsListener for it to be useful.

TypeRequiredPlatform
stringNoAndroid

scrollToOverflowEnabled

When true, the scroll view can be programmatically scrolled beyond its content size. The default value is false.

TypeRequiredPlatform
boolNoiOS

scrollsToTop

When true, the scroll view scrolls to top when the status bar is tapped. The default value is true.

TypeRequiredPlatform
boolNoiOS

DEPRECATED_sendUpdatedChildFrames

When true, ScrollView will emit updateChildFrames data in scroll events, otherwise will not compute or emit child frame data. This only exists to support legacy issues, onLayout should be used instead to retrieve frame data. The default value is false.

TypeRequiredPlatform
boolNoiOS

showsHorizontalScrollIndicator

When true, shows a horizontal scroll indicator. The default value is true.

TypeRequired
boolNo

showsVerticalScrollIndicator

When true, shows a vertical scroll indicator. The default value is true.

TypeRequired
boolNo

snapToAlignment

When snapToInterval is set, snapToAlignment will define the relationship of the snapping to the scroll view.

  • 'start' (the default) will align the snap at the left (horizontal) or top (vertical).
  • 'center' will align the snap in the center.
  • 'end' will align the snap at the right (horizontal) or bottom (vertical).
TypeRequiredPlatform
enum('start', 'center', 'end')NoiOS

snapToEnd

Use in conjunction with snapToOffsets. By default, the end of the list counts as a snap offset. Set snapToEnd to false to disable this behavior and allow the list to scroll freely between its end and the last snapToOffsets offset. The default value is true.

TypeRequired
booleanNo

snapToInterval

When set, causes the scroll view to stop at multiples of the value of snapToInterval. This can be used for paginating through children that have lengths smaller than the scroll view. Typically used in combination with snapToAlignment and decelerationRate="fast". Overrides less configurable pagingEnabled prop.

TypeRequired
numberNo

snapToOffsets

When set, causes the scroll view to stop at the defined offsets. This can be used for paginating through variously sized children that have lengths smaller than the scroll view. Typically used in combination with decelerationRate="fast". Overrides less configurable pagingEnabled and snapToInterval props.

TypeRequired
array of numberNo

snapToStart

Use in conjunction with snapToOffsets. By default, the beginning of the list counts as a snap offset. Set snapToStart to false to disable this behavior and allow the list to scroll freely between its start and the first snapToOffsets offset. The default value is true.

TypeRequired
booleanNo

stickyHeaderIndices

An array of child indices determining which children get docked to the top of the screen when scrolling. For example, passing stickyHeaderIndices={[0]} will cause the first child to be fixed to the top of the scroll view. You can also use like [x,y,z] to make multiple items sticky when they are at the top. This property is not supported in conjunction with horizontal={true}.

TypeRequired
array of numberNo

zoomScale

The current scale of the scroll view content. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

Methods

flashScrollIndicators()

flashScrollIndicators();

Displays the scroll indicators momentarily.

scrollTo()

scrollTo(
options?: {x?: number, y?: number, animated?: boolean} | number,
deprecatedX?: number,
deprecatedAnimated?: boolean,
);

Scrolls to a given x, y offset, either immediately, with a smooth animation.

Example:

scrollTo({x: 0, y: 0, animated: true})

Note: The weird function signature is due to the fact that, for historical reasons, the function also accepts separate arguments as an alternative to the options object. This is deprecated due to ambiguity (y before x), and SHOULD NOT BE USED.

scrollToEnd()

scrollToEnd(([options]: { animated: boolean, duration: number }));

If this is a vertical ScrollView scrolls to the bottom. If this is a horizontal ScrollView scrolls to the right.

Use scrollToEnd({animated: true}) for smooth animated scrolling, scrollToEnd({animated: false}) for immediate scrolling. For Android, you may specify a duration, e.g. scrollToEnd({duration: 500}) for a controlled duration scroll. If no options are passed, animated defaults to true.

scrollWithoutAnimationTo()

scrollWithoutAnimationTo(y, x);

Deprecated, use scrollTo instead.

Edit this page
Last updated on
- + diff --git a/docs/scrollview/index.html b/docs/scrollview/index.html index e3345f23a93..471234e672d 100644 --- a/docs/scrollview/index.html +++ b/docs/scrollview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

ScrollView

Component that wraps platform ScrollView while providing integration with touch locking "responder" system.

Keep in mind that ScrollViews must have a bounded height in order to work, since they contain unbounded-height children into a bounded container (via a scroll interaction). In order to bound the height of a ScrollView, either set the height of the view directly (discouraged) or make sure all parent views have bounded height. Forgetting to transfer {flex: 1} down the view stack can lead to errors here, which the element inspector makes quick to debug.

Doesn't yet support other contained responders from blocking this scroll view from becoming the responder.

<ScrollView> vs <FlatList> - which one to use?

ScrollView renders all its react child components at once, but this has a performance downside.

Imagine you have a very long list of items you want to display, maybe several screens worth of content. Creating JS components and native views for everything all at once, much of which may not even be shown, will contribute to slow rendering and increased memory usage.

This is where FlatList comes into play. FlatList renders items lazily, when they are about to appear, and removes items that scroll way off screen to save memory and processing time.

FlatList is also handy if you want to render separators between your items, multiple columns, infinite scroll loading, or any number of other features it supports out of the box.

Example

Reference

Props

Inherits View Props.

StickyHeaderComponent

A React Component that will be used to render sticky headers, should be used together with stickyHeaderIndices. You may need to set this component if your sticky header uses custom transforms, for example, when you want your list to have an animated and hidable header. If component have not been provided, the default ScrollViewStickyHeader component will be used.

TypeRequired
component, elementNo

alwaysBounceHorizontal

When true, the scroll view bounces horizontally when it reaches the end even if the content is smaller than the scroll view itself. The default value is true when horizontal={true} and false otherwise.

TypeRequiredPlatform
boolNoiOS

alwaysBounceVertical

When true, the scroll view bounces vertically when it reaches the end even if the content is smaller than the scroll view itself. The default value is false when vertical={true} and true otherwise.

TypeRequiredPlatform
boolNoiOS

automaticallyAdjustContentInsets

Controls whether iOS should automatically adjust the content inset for scroll views that are placed behind a navigation bar or tab bar/ toolbar. The default value is true.

TypeRequiredPlatform
boolNoiOS

bounces

When true, the scroll view bounces when it reaches the end of the content if the content is larger then the scroll view along the axis of the scroll direction. When false, it disables all bouncing even if the alwaysBounce* props are true. The default value is true.

TypeRequiredPlatform
boolNoiOS

bouncesZoom

When true, gestures can drive zoom past min/max and the zoom will animate to the min/max value at gesture end, otherwise the zoom will not exceed the limits.

TypeRequiredPlatform
boolNoiOS

canCancelContentTouches

When false, once tracking starts, won't try to drag if the touch moves. The default value is true.

TypeRequiredPlatform
boolNoiOS

centerContent

When true, the scroll view automatically centers the content when the content is smaller than the scroll view bounds; when the content is larger than the scroll view, this property has no effect. The default value is false.

TypeRequiredPlatform
boolNoiOS

contentContainerStyle

These styles will be applied to the scroll view content container which wraps all of the child views. Example:

return (
<ScrollView contentContainerStyle={styles.contentContainer}>
</ScrollView>
);
...
const styles = StyleSheet.create({
contentContainer: {
paddingVertical: 20
}
});
TypeRequired
StyleSheetPropType(View Style props)No

contentInset

The amount by which the scroll view content is inset from the edges of the scroll view. Defaults to {top: 0, left: 0, bottom: 0, right: 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

contentInsetAdjustmentBehavior

This property specifies how the safe area insets are used to modify the content area of the scroll view. The default value of this property is "never". Available on iOS 11 and later.

TypeRequiredPlatform
enum('automatic', 'scrollableAxes', 'never', 'always')NoiOS

contentOffset

Used to manually set the starting scroll offset. The default value is {x: 0, y: 0}.

TypeRequiredPlatform
PointPropTypeNoiOS

decelerationRate

A floating-point number that determines how quickly the scroll view decelerates after the user lifts their finger. You may also use string shortcuts "normal" and "fast" which match the underlying iOS settings for UIScrollViewDecelerationRateNormal and UIScrollViewDecelerationRateFast respectively.

  • 'normal' (the default), 0.998 on iOS, 0.985 on Android.
  • 'fast', 0.99 on iOS, 0.9 on Android.
TypeRequired
enum('fast', 'normal'), ,numberNo

directionalLockEnabled

When true, the ScrollView will try to lock to only vertical or horizontal scrolling while dragging. The default value is false.

TypeRequiredPlatform
boolNoiOS

disableIntervalMomentum

When true, the scroll view stops on the next index (in relation to scroll position at release) regardless of how fast the gesture is. This can be used for horizontal pagination when the page is less than the width of the ScrollView. The default value is false.

TypeRequired
boolNo

disableScrollViewPanResponder

When true, the default JS pan responder on the ScrollView is disabled, and full control over touches inside the ScrollView is left to its child components. This is particularly useful if snapToInterval is enabled, since it does not follow typical touch patterns. Do not use this on regular ScrollView use cases without snapToInterval as it may cause unexpected touches to occur while scrolling. The default value is false.

TypeRequired
boolNo

endFillColor

Sometimes a scrollview takes up more space than its content fills. When this is the case, this prop will fill the rest of the scrollview with a color to avoid setting a background and creating unnecessary overdraw. This is an advanced optimization that is not needed in the general case.

TypeRequiredPlatform
colorNoAndroid

fadingEdgeLength

Fades out the edges of the the scroll content.

If the value is greater than 0, the fading edges will be set accordingly to the current scroll direction and position, indicating if there is more content to show.

TypeRequiredDefaultPlatform
numberNo0Android

horizontal

When true, the scroll view's children are arranged horizontally in a row instead of vertically in a column. The default value is false.

TypeRequired
boolNo

indicatorStyle

The style of the scroll indicators.

  • 'default' (the default), same as black.
  • 'black', scroll indicator is black. This style is good against a light background.
  • 'white', scroll indicator is white. This style is good against a dark background.
TypeRequiredPlatform
enum('default', 'black', 'white')NoiOS

invertStickyHeaders

If sticky headers should stick at the bottom instead of the top of the ScrollView. This is usually used with inverted ScrollViews.

TypeRequired
boolNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

Cross platform

  • 'none' (the default), drags do not dismiss the keyboard.
  • 'on-drag', the keyboard is dismissed when a drag begins.

iOS Only

  • 'interactive', the keyboard is dismissed interactively with the drag and moves in synchrony with the touch; dragging upwards cancels the dismissal. On android this is not supported and it will have the same behavior as 'none'.
TypeRequired
enum('none', 'on-drag', 'interactive')No

keyboardShouldPersistTaps

Determines when the keyboard should stay visible after a tap.

  • 'never' (the default), tapping outside of the focused text input when the keyboard is up dismisses the keyboard. When this happens, children won't receive the tap.
  • 'always', the keyboard will not dismiss automatically, and the scroll view will not catch taps, but children of the scroll view can catch taps.
  • 'handled', the keyboard will not dismiss automatically when the tap was handled by children of the scroll view (or captured by an ancestor).
  • false, deprecated, use 'never' instead
  • true, deprecated, use 'always' instead
TypeRequired
enum('always', 'never', 'handled', false, true)No

maintainVisibleContentPosition

When set, the scroll view will adjust the scroll position so that the first child that is currently visible and at or beyond minIndexForVisible will not change position. This is useful for lists that are loading content in both directions, e.g. a chat thread, where new messages coming in might otherwise cause the scroll position to jump. A value of 0 is common, but other values such as 1 can be used to skip loading spinners or other content that should not maintain position.

The optional autoscrollToTopThreshold can be used to make the content automatically scroll to the top after making the adjustment if the user was within the threshold of the top before the adjustment was made. This is also useful for chat-like applications where you want to see new messages scroll into place, but not if the user has scrolled up a ways and it would be disruptive to scroll a bunch.

Caveat 1: Reordering elements in the scrollview with this enabled will probably cause jumpiness and jank. It can be fixed, but there are currently no plans to do so. For now, don't re-order the content of any ScrollViews or Lists that use this feature.

Caveat 2: This uses contentOffset and frame.origin in native code to compute visibility. Occlusion, transforms, and other complexity won't be taken into account as to whether content is "visible" or not.

TypeRequiredPlatform
object: { minIndexForVisible: number, autoscrollToTopThreshold: number }NoiOS

maximumZoomScale

The maximum allowed zoom scale. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

minimumZoomScale

The minimum allowed zoom scale. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

nestedScrollEnabled

Enables nested scrolling for Android API level 21+. Nested scrolling is supported by default on iOS.

TypeRequiredPlatform
boolNoAndroid

onContentSizeChange

Called when scrollable content view of the ScrollView changes.

Handler function is passed the content width and content height as parameters: (contentWidth, contentHeight)

It's implemented using onLayout handler attached to the content container which this ScrollView renders.

TypeRequired
functionNo

onMomentumScrollBegin

Called when the momentum scroll starts (scroll which occurs as the ScrollView starts gliding).

TypeRequired
functionNo

onMomentumScrollEnd

Called when the momentum scroll ends (scroll which occurs as the ScrollView glides to a stop).

TypeRequired
functionNo

onScroll

Fires at most once per frame during scrolling. The frequency of the events can be controlled using the scrollEventThrottle prop. The event has the following shape (all values are numbers):

{
nativeEvent: {
contentInset: {bottom, left, right, top},
contentOffset: {x, y},
contentSize: {height, width},
layoutMeasurement: {height, width},
zoomScale
}
}
TypeRequired
functionNo

onScrollBeginDrag

Called when the user begins to drag the scroll view.

TypeRequired
functionNo

onScrollEndDrag

Called when the user stops dragging the scroll view and it either stops or begins to glide.

TypeRequired
functionNo

onScrollToTop

Fires when the scroll view scrolls to top after the status bar has been tapped.

TypeRequiredPlatform
functionNoiOS

overScrollMode

Used to override default value of overScroll mode.

Possible values:

  • 'auto' - Default value, allow a user to over-scroll this view only if the content is large enough to meaningfully scroll.
  • 'always' - Always allow a user to over-scroll this view.
  • 'never' - Never allow a user to over-scroll this view.
TypeRequiredPlatform
enum('auto', 'always', 'never')NoAndroid

pagingEnabled

When true, the scroll view stops on multiples of the scroll view's size when scrolling. This can be used for horizontal pagination. The default value is false.

Note: Vertical pagination is not supported on Android.

TypeRequired
boolNo

persistentScrollbar

Causes the scrollbars not to turn transparent when they are not in use. The default value is false.

TypeRequiredPlatform
boolNoAndroid

pinchGestureEnabled

When true, ScrollView allows use of pinch gestures to zoom in and out. The default value is true.

TypeRequiredPlatform
boolNoiOS

refreshControl

A RefreshControl component, used to provide pull-to-refresh functionality for the ScrollView. Only works for vertical ScrollViews (horizontal prop must be false).

See RefreshControl.

TypeRequired
elementNo

removeClippedSubviews

Experimental: When true, offscreen child views (whose overflow value is hidden) are removed from their native backing superview when offscreen. This can improve scrolling performance on long lists.

TypeRequired
boolNo

scrollBarThumbImage

Optionally an image can be used for the scroll bar thumb. This will override the color. While the image is loading or the image fails to load the color will be used instead. Use an alpha of 0 in the color to avoid seeing it while the image is loading.

  • uri, a string representing the resource identifier for the image, which should be either a local file path or the name of a static image resource.
  • number, opaque type returned by something like import IMAGE from './image.jpg'.
TypeRequiredPlatform
numberNoVR

scrollEnabled

When false, the view cannot be scrolled via touch interaction. The default value is true.

Note that the view can always be scrolled by calling scrollTo.

TypeRequired
boolNo

scrollEventThrottle

This controls how often the scroll event will be fired while scrolling (as a time interval in ms). A lower number yields better accuracy for code that is tracking the scroll position, but can lead to scroll performance problems due to the volume of information being sent over the bridge. You will not notice a difference between values set between 1-16 as the JS run loop is synced to the screen refresh rate. If you do not need precise scroll position tracking, set this value higher to limit the information being sent across the bridge. The default value is zero, which results in the scroll event being sent only once each time the view is scrolled.

TypeRequiredPlatform
numberNoiOS

scrollIndicatorInsets

The amount by which the scroll view indicators are inset from the edges of the scroll view. This should normally be set to the same value as the contentInset. Defaults to {0, 0, 0, 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

scrollPerfTag

Tag used to log scroll performance on this scroll view. Will force momentum events to be turned on (see sendMomentumEvents). This doesn't do anything out of the box and you need to implement a custom native FpsListener for it to be useful.

TypeRequiredPlatform
stringNoAndroid

scrollToOverflowEnabled

When true, the scroll view can be programmatically scrolled beyond its content size. The default value is false.

TypeRequiredPlatform
boolNoiOS

scrollsToTop

When true, the scroll view scrolls to top when the status bar is tapped. The default value is true.

TypeRequiredPlatform
boolNoiOS

DEPRECATED_sendUpdatedChildFrames

When true, ScrollView will emit updateChildFrames data in scroll events, otherwise will not compute or emit child frame data. This only exists to support legacy issues, onLayout should be used instead to retrieve frame data. The default value is false.

TypeRequiredPlatform
boolNoiOS

showsHorizontalScrollIndicator

When true, shows a horizontal scroll indicator. The default value is true.

TypeRequired
boolNo

showsVerticalScrollIndicator

When true, shows a vertical scroll indicator. The default value is true.

TypeRequired
boolNo

snapToAlignment

When snapToInterval is set, snapToAlignment will define the relationship of the snapping to the scroll view.

  • 'start' (the default) will align the snap at the left (horizontal) or top (vertical).
  • 'center' will align the snap in the center.
  • 'end' will align the snap at the right (horizontal) or bottom (vertical).
TypeRequiredPlatform
enum('start', 'center', 'end')NoiOS

snapToEnd

Use in conjunction with snapToOffsets. By default, the end of the list counts as a snap offset. Set snapToEnd to false to disable this behavior and allow the list to scroll freely between its end and the last snapToOffsets offset. The default value is true.

TypeRequired
booleanNo

snapToInterval

When set, causes the scroll view to stop at multiples of the value of snapToInterval. This can be used for paginating through children that have lengths smaller than the scroll view. Typically used in combination with snapToAlignment and decelerationRate="fast". Overrides less configurable pagingEnabled prop.

TypeRequired
numberNo

snapToOffsets

When set, causes the scroll view to stop at the defined offsets. This can be used for paginating through variously sized children that have lengths smaller than the scroll view. Typically used in combination with decelerationRate="fast". Overrides less configurable pagingEnabled and snapToInterval props.

TypeRequired
array of numberNo

snapToStart

Use in conjunction with snapToOffsets. By default, the beginning of the list counts as a snap offset. Set snapToStart to false to disable this behavior and allow the list to scroll freely between its start and the first snapToOffsets offset. The default value is true.

TypeRequired
booleanNo

stickyHeaderIndices

An array of child indices determining which children get docked to the top of the screen when scrolling. For example, passing stickyHeaderIndices={[0]} will cause the first child to be fixed to the top of the scroll view. You can also use like [x,y,z] to make multiple items sticky when they are at the top. This property is not supported in conjunction with horizontal={true}.

TypeRequired
array of numberNo

zoomScale

The current scale of the scroll view content. The default value is 1.0.

TypeRequiredPlatform
numberNoiOS

Methods

flashScrollIndicators()

flashScrollIndicators();

Displays the scroll indicators momentarily.

scrollTo()

scrollTo(
options?: {x?: number, y?: number, animated?: boolean} | number,
deprecatedX?: number,
deprecatedAnimated?: boolean,
);

Scrolls to a given x, y offset, either immediately, with a smooth animation.

Example:

scrollTo({x: 0, y: 0, animated: true})

Note: The weird function signature is due to the fact that, for historical reasons, the function also accepts separate arguments as an alternative to the options object. This is deprecated due to ambiguity (y before x), and SHOULD NOT BE USED.

scrollToEnd()

scrollToEnd(([options]: { animated: boolean, duration: number }));

If this is a vertical ScrollView scrolls to the bottom. If this is a horizontal ScrollView scrolls to the right.

Use scrollToEnd({animated: true}) for smooth animated scrolling, scrollToEnd({animated: false}) for immediate scrolling. For Android, you may specify a duration, e.g. scrollToEnd({duration: 500}) for a controlled duration scroll. If no options are passed, animated defaults to true.

scrollWithoutAnimationTo()

scrollWithoutAnimationTo(y, x);

Deprecated, use scrollTo instead.

Edit this page
Last updated on
- + diff --git a/docs/sectionlist.html b/docs/sectionlist.html index 0984cd167b6..4ae2d92e1b7 100644 --- a/docs/sectionlist.html +++ b/docs/sectionlist.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

SectionList

A performant interface for rendering sectioned lists, supporting the most handy features:

  • Fully cross-platform.
  • Configurable viewability callbacks.
  • List header support.
  • List footer support.
  • Item separator support.
  • Section header support.
  • Section separator support.
  • Heterogeneous data and item rendering support.
  • Pull to Refresh.
  • Scroll loading.

If you don't need section support and want a simpler interface, use <FlatList>.

Example

This is a convenience wrapper around <VirtualizedList>, and thus inherits its props (as well as those of <ScrollView>) that aren't explicitly listed here, along with the following caveats:

  • Internal state is not preserved when content scrolls out of the render window. Make sure all your data is captured in the item data or external stores like Flux, Redux, or Relay.
  • This is a PureComponent which means that it will not re-render if props remain shallow-equal. Make sure that everything your renderItem function depends on is passed as a prop (e.g. extraData) that is not === after updates, otherwise your UI may not update on changes. This includes the data prop and parent component state.
  • In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate and momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application, and we are working on improving it behind the scenes.
  • By default, the list looks for a key prop on each item and uses that for the React key. Alternatively, you can provide a custom keyExtractor prop.

Reference

Props

Inherits ScrollView Props.

renderItem

Default renderer for every item in every section. Can be over-ridden on a per-section basis. Should return a React element.

TypeRequired
functionYes

The render function will be passed an object with the following keys:

  • 'item' (object) - the item object as specified in this section's data key
  • 'index' (number) - Item's index within the section.
  • 'section' (object) - The full section object as specified in sections.
  • 'separators' (object) - An object with the following keys:
    • 'highlight' (function) - () => void
    • 'unhighlight' (function) - () => void
    • 'updateProps' (function) - (select, newProps) => void
      • 'select' (enum) - possible values are 'leading', 'trailing'
      • 'newProps' (object)

sections

The actual data to render, akin to the data prop in FlatList.

TypeRequired
array of SectionsYes

extraData

A marker property for telling the list to re-render (since it implements PureComponent). If any of your renderItem, Header, Footer, etc. functions depend on anything outside of the data prop, stick it here and treat it immutably.

TypeRequired
anyNo

initialNumToRender

How many items to render in the initial batch. This should be enough to fill the screen but not much more. Note these items will never be unmounted as part of the windowed rendering in order to improve perceived performance of scroll-to-top actions.

TypeRequired
numberNo

inverted

Reverses the direction of scroll. Uses scale transforms of -1.

TypeRequired
[boolean]No

ItemSeparatorComponent

Rendered in between each item, but not at the top or bottom. By default, highlighted, section, and [leading/trailing][Item/Section] props are provided. renderItem provides separators.highlight/unhighlight which will update the highlighted prop, but you can also add custom props with separators.updateProps.

TypeRequired
[component, element]No

keyExtractor

Used to extract a unique key for a given item at the specified index. Key is used for caching and as the React key to track item re-ordering. The default extractor checks item.key, then falls back to using the index, like React does. Note that this sets keys for each item, but each overall section still needs its own key.

TypeRequired
(item: Item, index: number) => stringYes

ListEmptyComponent

Rendered when the list is empty. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
[component, element]No

ListFooterComponent

Rendered at the very end of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
[component, element]No

ListHeaderComponent

Rendered at the very beginning of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
component, elementNo

onEndReached

Called once when the scroll position gets within onEndReachedThreshold of the rendered content.

TypeRequired
[(info: {distanceFromEnd: number}) => void]No

onEndReachedThreshold

How far from the end (in units of visible length of the list) the bottom edge of the list must be from the end of the content to trigger the onEndReached callback. Thus a value of 0.5 will trigger onEndReached when the end of the content is within half the visible length of the list.

TypeRequired
[number]No

onRefresh

If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the refreshing prop correctly. To offset the RefreshControl from the top (e.g. by 100 pts), use progressViewOffset={100}.

TypeRequired
[() => void]No

onViewableItemsChanged

Called when the viewability of rows changes, as defined by the viewabilityConfig prop.

TypeRequired
functionNo

The function will be passed an object with the following keys:

  • 'viewableItems' (array of ViewTokens)
  • 'changed' (array of ViewTokens)

The ViewToken type is exported by ViewabilityHelper.js:

NameTypeRequired
itemanyYes
keystringYes
indexnumberNo
isViewablebooleanYes
sectionanyNo

refreshing

Set this true while waiting for new data from a refresh.

TypeRequired
[boolean]No

removeClippedSubviews

Note: may have bugs (missing content) in some circumstances - use at your own risk.

This may improve scroll performance for large lists.

TypeRequired
booleanNo

renderSectionFooter

Rendered at the bottom of each section.

TypeRequired
[(info: {section: SectionT}) => ?React.Element<any>]No

renderSectionHeader

Rendered at the top of each section. These stick to the top of the ScrollView by default on iOS. See stickySectionHeadersEnabled.

TypeRequired
[(info: {section: SectionT}) => ?React.Element<any>]No

SectionSeparatorComponent

Rendered at the top and bottom of each section (note this is different from ItemSeparatorComponent which is only rendered between items). These are intended to separate sections from the headers above and below and typically have the same highlight response as ItemSeparatorComponent. Also receives highlighted, [leading/trailing][Item/Section], and any custom props from separators.updateProps.

TypeRequired
[ReactClass<any>]No

stickySectionHeadersEnabled

Makes section headers stick to the top of the screen until the next one pushes it off. Only enabled by default on iOS because that is the platform standard there.

TypeRequired
booleanNo

Methods

scrollToLocation()

scrollToLocation(params);

Scrolls to the item at the specified sectionIndex and itemIndex (within the section) positioned in the viewable area such that viewPosition 0 places it at the top (and may be covered by a sticky header), 1 at the bottom, and 0.5 centered in the middle.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout or onScrollToIndexFailed prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.
  • 'itemIndex' (number) - Index within section for the item to scroll to. Required.
  • 'sectionIndex' (number) - Index for section that contains the item to scroll to. Required.
  • 'viewOffset' (number) - A fixed number of pixels to offset the final target position, e.g. to compensate for sticky headers.
  • 'viewPosition' (number) - A value of 0 places the item specified by index at the top, 1 at the bottom, and 0.5 centered in the middle.

recordInteraction()

recordInteraction();

Tells the list an interaction has occurred, 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()

flashScrollIndicators();

Displays the scroll indicators momentarily.

Platform
iOS

Type Definitions

Section

An object that identifies the data to be rendered for a given section.

Type
any

Properties:

NameTypeDescription
dataarrayThe data for rendering items in this section. Array of objects, much like FlatList's data prop.
[key]stringOptional key to keep track of section re-ordering. If you don't plan on re-ordering sections, the array index will be used by default.
[renderItem]functionOptionally define an arbitrary item renderer for this section, overriding the default renderItem for the list.
[ItemSeparatorComponent]component, elementOptionally define an arbitrary item separator for this section, overriding the default ItemSeparatorComponent for the list.
[keyExtractor]functionOptionally define an arbitrary key extractor for this section, overriding the default keyExtractor.
Edit this page
Last updated on
- + diff --git a/docs/sectionlist/index.html b/docs/sectionlist/index.html index 0984cd167b6..4ae2d92e1b7 100644 --- a/docs/sectionlist/index.html +++ b/docs/sectionlist/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

SectionList

A performant interface for rendering sectioned lists, supporting the most handy features:

  • Fully cross-platform.
  • Configurable viewability callbacks.
  • List header support.
  • List footer support.
  • Item separator support.
  • Section header support.
  • Section separator support.
  • Heterogeneous data and item rendering support.
  • Pull to Refresh.
  • Scroll loading.

If you don't need section support and want a simpler interface, use <FlatList>.

Example

This is a convenience wrapper around <VirtualizedList>, and thus inherits its props (as well as those of <ScrollView>) that aren't explicitly listed here, along with the following caveats:

  • Internal state is not preserved when content scrolls out of the render window. Make sure all your data is captured in the item data or external stores like Flux, Redux, or Relay.
  • This is a PureComponent which means that it will not re-render if props remain shallow-equal. Make sure that everything your renderItem function depends on is passed as a prop (e.g. extraData) that is not === after updates, otherwise your UI may not update on changes. This includes the data prop and parent component state.
  • In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate and momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application, and we are working on improving it behind the scenes.
  • By default, the list looks for a key prop on each item and uses that for the React key. Alternatively, you can provide a custom keyExtractor prop.

Reference

Props

Inherits ScrollView Props.

renderItem

Default renderer for every item in every section. Can be over-ridden on a per-section basis. Should return a React element.

TypeRequired
functionYes

The render function will be passed an object with the following keys:

  • 'item' (object) - the item object as specified in this section's data key
  • 'index' (number) - Item's index within the section.
  • 'section' (object) - The full section object as specified in sections.
  • 'separators' (object) - An object with the following keys:
    • 'highlight' (function) - () => void
    • 'unhighlight' (function) - () => void
    • 'updateProps' (function) - (select, newProps) => void
      • 'select' (enum) - possible values are 'leading', 'trailing'
      • 'newProps' (object)

sections

The actual data to render, akin to the data prop in FlatList.

TypeRequired
array of SectionsYes

extraData

A marker property for telling the list to re-render (since it implements PureComponent). If any of your renderItem, Header, Footer, etc. functions depend on anything outside of the data prop, stick it here and treat it immutably.

TypeRequired
anyNo

initialNumToRender

How many items to render in the initial batch. This should be enough to fill the screen but not much more. Note these items will never be unmounted as part of the windowed rendering in order to improve perceived performance of scroll-to-top actions.

TypeRequired
numberNo

inverted

Reverses the direction of scroll. Uses scale transforms of -1.

TypeRequired
[boolean]No

ItemSeparatorComponent

Rendered in between each item, but not at the top or bottom. By default, highlighted, section, and [leading/trailing][Item/Section] props are provided. renderItem provides separators.highlight/unhighlight which will update the highlighted prop, but you can also add custom props with separators.updateProps.

TypeRequired
[component, element]No

keyExtractor

Used to extract a unique key for a given item at the specified index. Key is used for caching and as the React key to track item re-ordering. The default extractor checks item.key, then falls back to using the index, like React does. Note that this sets keys for each item, but each overall section still needs its own key.

TypeRequired
(item: Item, index: number) => stringYes

ListEmptyComponent

Rendered when the list is empty. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
[component, element]No

ListFooterComponent

Rendered at the very end of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
[component, element]No

ListHeaderComponent

Rendered at the very beginning of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

TypeRequired
component, elementNo

onEndReached

Called once when the scroll position gets within onEndReachedThreshold of the rendered content.

TypeRequired
[(info: {distanceFromEnd: number}) => void]No

onEndReachedThreshold

How far from the end (in units of visible length of the list) the bottom edge of the list must be from the end of the content to trigger the onEndReached callback. Thus a value of 0.5 will trigger onEndReached when the end of the content is within half the visible length of the list.

TypeRequired
[number]No

onRefresh

If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the refreshing prop correctly. To offset the RefreshControl from the top (e.g. by 100 pts), use progressViewOffset={100}.

TypeRequired
[() => void]No

onViewableItemsChanged

Called when the viewability of rows changes, as defined by the viewabilityConfig prop.

TypeRequired
functionNo

The function will be passed an object with the following keys:

  • 'viewableItems' (array of ViewTokens)
  • 'changed' (array of ViewTokens)

The ViewToken type is exported by ViewabilityHelper.js:

NameTypeRequired
itemanyYes
keystringYes
indexnumberNo
isViewablebooleanYes
sectionanyNo

refreshing

Set this true while waiting for new data from a refresh.

TypeRequired
[boolean]No

removeClippedSubviews

Note: may have bugs (missing content) in some circumstances - use at your own risk.

This may improve scroll performance for large lists.

TypeRequired
booleanNo

renderSectionFooter

Rendered at the bottom of each section.

TypeRequired
[(info: {section: SectionT}) => ?React.Element<any>]No

renderSectionHeader

Rendered at the top of each section. These stick to the top of the ScrollView by default on iOS. See stickySectionHeadersEnabled.

TypeRequired
[(info: {section: SectionT}) => ?React.Element<any>]No

SectionSeparatorComponent

Rendered at the top and bottom of each section (note this is different from ItemSeparatorComponent which is only rendered between items). These are intended to separate sections from the headers above and below and typically have the same highlight response as ItemSeparatorComponent. Also receives highlighted, [leading/trailing][Item/Section], and any custom props from separators.updateProps.

TypeRequired
[ReactClass<any>]No

stickySectionHeadersEnabled

Makes section headers stick to the top of the screen until the next one pushes it off. Only enabled by default on iOS because that is the platform standard there.

TypeRequired
booleanNo

Methods

scrollToLocation()

scrollToLocation(params);

Scrolls to the item at the specified sectionIndex and itemIndex (within the section) positioned in the viewable area such that viewPosition 0 places it at the top (and may be covered by a sticky header), 1 at the bottom, and 0.5 centered in the middle.

Note: Cannot scroll to locations outside the render window without specifying the getItemLayout or onScrollToIndexFailed prop.

Parameters:

NameTypeRequiredDescription
paramsobjectYesSee below.

Valid params keys are:

  • 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.
  • 'itemIndex' (number) - Index within section for the item to scroll to. Required.
  • 'sectionIndex' (number) - Index for section that contains the item to scroll to. Required.
  • 'viewOffset' (number) - A fixed number of pixels to offset the final target position, e.g. to compensate for sticky headers.
  • 'viewPosition' (number) - A value of 0 places the item specified by index at the top, 1 at the bottom, and 0.5 centered in the middle.

recordInteraction()

recordInteraction();

Tells the list an interaction has occurred, 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()

flashScrollIndicators();

Displays the scroll indicators momentarily.

Platform
iOS

Type Definitions

Section

An object that identifies the data to be rendered for a given section.

Type
any

Properties:

NameTypeDescription
dataarrayThe data for rendering items in this section. Array of objects, much like FlatList's data prop.
[key]stringOptional key to keep track of section re-ordering. If you don't plan on re-ordering sections, the array index will be used by default.
[renderItem]functionOptionally define an arbitrary item renderer for this section, overriding the default renderItem for the list.
[ItemSeparatorComponent]component, elementOptionally define an arbitrary item separator for this section, overriding the default ItemSeparatorComponent for the list.
[keyExtractor]functionOptionally define an arbitrary key extractor for this section, overriding the default keyExtractor.
Edit this page
Last updated on
- + diff --git a/docs/security.html b/docs/security.html index de31c8a4ba7..1691a2110fc 100644 --- a/docs/security.html +++ b/docs/security.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Security

Security is often overlooked when building apps. It is true that it is impossible to build software that is completely impenetrable—we’ve yet to invent a completely impenetrable lock (bank vaults do, after all, still get broken into). However, the probability of falling victim to a malicious attack or being exposed for a security vulnerability is inversely proportional to the effort you’re willing to put in to protecting your application against any such eventuality. Although an ordinary padlock is pickable, it is still much harder to get past than a cabinet hook!

In this guide, you will learn about best practices for storing sensitive information, authentication, network security, and tools that will help you secure your app. This is not a preflight checklist—it is a catalogue of options, each of which will help further protect your app and users.

Storing Sensitive Info

Never store sensitive API keys in your app code. Anything included in your code could be accessed in plain text by anyone inspecting the app bundle. Tools like react-native-dotenv and react-native-config are great for adding environment-specific variables like API endpoints, but they should not be confused with server-side environment variables, which can often contain secrets and API keys.

If you must have an API key or a secret to access some resource from your app, the most secure way to handle this would be to build an orchestration layer between your app and the resource. This could be a serverless function (e.g. using AWS Lambda or Google Cloud Functions) which can forward the request with the required API key or secret. Secrets in server side code cannot be accessed by the API consumers the same way secrets in your app code can.

For persisted user data, choose the right type of storage based on its sensitivity. As your app is used, you’ll often find the need to save data on the device, whether to support your app being used offline, cut down on network requests or save your user’s access token between sessions so they wouldn’t have to re-authenticate each time they use the app.

Persisted vs unpersisted — persisted data is written to the device’s memory, which lets the data be read by your app across application launches without having to do another network request to fetch it or asking the user to re-enter it. But this also can make that data more vulnerable to being accessed by attackers. Unpersisted data is never written to memory—so there's no data to access!

Async Storage

Async Storage is a community-maintained module for React Native that provides an asynchronous, unencrypted, key-value store. Async Storage is not shared between apps: every app has its own sandbox environment and has no access to data from other apps.

Do use async storage when...Don't use async storage for...
Persisting non-sensitive data across app runsToken storage
Persisting Redux stateSecrets
Persisting GraphQL state
Storing global app-wide variables

Developer Notes

Async Storage is the React Native equivalent of Local Storage from the web

Secure Storage

React Native does not come bundled with any way of storing sensitive data. However, there are pre-existing solutions for Android and iOS platforms.

iOS - Keychain Services

Keychain Services allows you to securely store small chunks of sensitive info for the user. This is an ideal place to store certificates, tokens, passwords, and any other sensitive information that doesn’t belong in Async Storage.

Android - Secure Shared Preferences

Shared Preferences is the Android equivalent for a persistent key-value data store. Data in Shared Preferences is not encrypted by default, but Encrypted Shared Preferences wraps the Shared Preferences class for Android, and automatically encrypts keys and values.

Android - Keystore

The Android Keystore system lets you store cryptographic keys in a container to make it more difficult to extract from the device.

In order to use iOS Keychain services or Android Secure Shared Preferences, you can either write a bridge yourself or use a library which wraps them for you and provides a unified API at your own risk. Some libraries to consider:

Be mindful of unintentionally storing or exposing sensitive info. This could happen accidentally, for example saving sensitive form data in redux state and persisting the whole state tree in Async Storage. Or sending user tokens and personal info to an application monitoring service such as Sentry or Crashlytics.

Authentication and Deep Linking

Mobile apps have a unique vulnerability that is non-existent in the web: deep linking. Deep linking is a way of sending data directly to a native application from an outside source. A deep link looks like app:// where app is your app scheme and anything following the // could be used internally to handle the request.

For example, if you were building an ecommerce app, you could use app://products/1 to deep link to your app and open the product detail page for a product with id 1. You can think of these kind of like URLs on the web, but with one crucial distinction:

Deep links are not secure and you should never send any sensitive information in them.

The reason deep links are not secure is because there is no centralized method of registering URL schemes. As an application developer, you can use almost any url scheme you choose by configuring it in Xcode for iOS or adding an intent on Android.

There is nothing stopping a malicious application from hijacking your deep link by also registering to the same scheme and then obtaining access to the data your link contains. Sending something like app://products/1 is not harmful, but sending tokens is a security concern.

When the operating system has two or more applications to choose from when opening a link, Android will show the user a modal and ask them to choose which application to use to open the link. On iOS however, the operating system will make the choice for you, so the user will be blissfully unaware. Apple has made steps to address this issue in later iOS versions (iOS 11) where they instituted a first-come-first-served principle, although this vulnerability could still be exploited in different ways which you can read more about here. Using universal links will allow linking to content within your app securely in iOS.

OAuth2 and Redirects

The OAuth2 authentication protocol is incredibly popular nowadays, prided as the most complete and secure protocol around. The OpenID Connect protocol is also based on this. In OAuth2, the user is asked to authenticate via a third party. On successful completion, this third party redirects back to the requesting application with a verification code which can be exchanged for a JWT — a JSON Web Token. JWT is an open standard for securely transmitting information between parties on the web.

On the web, this redirect step is secure, because URLs on the web are guaranteed to be unique. This is not true for apps because, as mentioned earlier, there is no centralized method of registering URL schemes! In order to address this security concern, an additional check must be added in the form of PKCE.

PKCE, pronounced “Pixy” stands for Proof of Key Code Exchange, and is an extension to the OAuth 2 spec. This involves adding an additional layer of security which verifies that the authentication and token exchange requests come from the same client. PKCE uses the SHA 256 Cryptographic Hash Algorithm. SHA 256 creates a unique “signature” for a text or file of any size, but it is:

  • Always the same length regardless of the input file
  • Guaranteed to always produce the same result for the same input
  • One way (that is, you can’t reverse engineer it to reveal the original input)

Now you have two values:

  • code_verifier - a large random string generated by the client
  • code_challenge - the SHA 256 of the code_verifier

During the initial /authorize request, the client also sends the code_challenge for the code_verifier it keeps in memory. After the authorize request has returned correctly, the client also sends the code_verifier that was used to generate the code_challenge. The IDP will then calculate the code_challenge, see if it matches what was set on the very first /authorize request, and only send the access token if the values match.

This guarantees that only the application that triggered the initial authorization flow would be able to successfully exchange the verification code for a JWT. So even if a malicious application gets access to the verification code, it will be useless on its own. To see this in action, check out this example.

A library to consider for native OAuth is react-native-app-auth. React-native-app-auth is an SDK for communicating with OAuth2 providers. It wraps the native AppAuth-iOS and AppAuth-Android libraries and can support PKCE.

React-native-app-auth can support PKCE only if your Identity Provider supports it.

OAuth2 with PKCE

Network Security

Your APIs should always use SSL encryption. SSL encryption protects against the requested data being read in plain text between when it leaves the server and before it reaches the client. You’ll know the endpoint is secure, because it starts with https:// instead of http://.

SSL Pinning

Using https endpoints could still leave your data vulnerable to interception. With https, the client will only trust the server if it can provide a valid certificate that is signed by a trusted Certificate Authority that is pre-installed on the client. An attacker could take advantage of this by installing a malicious root CA certificate to the user’s device, so the client would trust all certificates that are signed by the attacker. Thus, relying on certificates alone could still leave you vulnerable to a man-in-the-middle attack.

SSL pinning is a technique that can be used on the client side to avoid this attack. It works by embedding (or pinning) a list of trusted certificates to the client during development, so that only the requests signed with one of the trusted certificates will be accepted, and any self-signed certificates will not be.

When using SSL pinning, you should be mindful of certificate expiry. Certificates expire every 1-2 years and when one does, it’ll need to be updated in the app as well as on the server. As soon as the certificate on the server has been updated, any apps with the old certificate embedded in them will cease to work.

Summary

There is no bulletproof way to handle security, but with conscious effort and diligence, it is possible to significantly reduce the likelihood of a security breach in your application. Invest in security proportional to the sensitivity of the data stored in your application, the number of users, and the damage a hacker could do when gaining access to their account. And remember: it’s significantly harder to access information that was never requested in the first place.

Edit this page
Last updated on
- + diff --git a/docs/security/index.html b/docs/security/index.html index de31c8a4ba7..1691a2110fc 100644 --- a/docs/security/index.html +++ b/docs/security/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Security

Security is often overlooked when building apps. It is true that it is impossible to build software that is completely impenetrable—we’ve yet to invent a completely impenetrable lock (bank vaults do, after all, still get broken into). However, the probability of falling victim to a malicious attack or being exposed for a security vulnerability is inversely proportional to the effort you’re willing to put in to protecting your application against any such eventuality. Although an ordinary padlock is pickable, it is still much harder to get past than a cabinet hook!

In this guide, you will learn about best practices for storing sensitive information, authentication, network security, and tools that will help you secure your app. This is not a preflight checklist—it is a catalogue of options, each of which will help further protect your app and users.

Storing Sensitive Info

Never store sensitive API keys in your app code. Anything included in your code could be accessed in plain text by anyone inspecting the app bundle. Tools like react-native-dotenv and react-native-config are great for adding environment-specific variables like API endpoints, but they should not be confused with server-side environment variables, which can often contain secrets and API keys.

If you must have an API key or a secret to access some resource from your app, the most secure way to handle this would be to build an orchestration layer between your app and the resource. This could be a serverless function (e.g. using AWS Lambda or Google Cloud Functions) which can forward the request with the required API key or secret. Secrets in server side code cannot be accessed by the API consumers the same way secrets in your app code can.

For persisted user data, choose the right type of storage based on its sensitivity. As your app is used, you’ll often find the need to save data on the device, whether to support your app being used offline, cut down on network requests or save your user’s access token between sessions so they wouldn’t have to re-authenticate each time they use the app.

Persisted vs unpersisted — persisted data is written to the device’s memory, which lets the data be read by your app across application launches without having to do another network request to fetch it or asking the user to re-enter it. But this also can make that data more vulnerable to being accessed by attackers. Unpersisted data is never written to memory—so there's no data to access!

Async Storage

Async Storage is a community-maintained module for React Native that provides an asynchronous, unencrypted, key-value store. Async Storage is not shared between apps: every app has its own sandbox environment and has no access to data from other apps.

Do use async storage when...Don't use async storage for...
Persisting non-sensitive data across app runsToken storage
Persisting Redux stateSecrets
Persisting GraphQL state
Storing global app-wide variables

Developer Notes

Async Storage is the React Native equivalent of Local Storage from the web

Secure Storage

React Native does not come bundled with any way of storing sensitive data. However, there are pre-existing solutions for Android and iOS platforms.

iOS - Keychain Services

Keychain Services allows you to securely store small chunks of sensitive info for the user. This is an ideal place to store certificates, tokens, passwords, and any other sensitive information that doesn’t belong in Async Storage.

Android - Secure Shared Preferences

Shared Preferences is the Android equivalent for a persistent key-value data store. Data in Shared Preferences is not encrypted by default, but Encrypted Shared Preferences wraps the Shared Preferences class for Android, and automatically encrypts keys and values.

Android - Keystore

The Android Keystore system lets you store cryptographic keys in a container to make it more difficult to extract from the device.

In order to use iOS Keychain services or Android Secure Shared Preferences, you can either write a bridge yourself or use a library which wraps them for you and provides a unified API at your own risk. Some libraries to consider:

Be mindful of unintentionally storing or exposing sensitive info. This could happen accidentally, for example saving sensitive form data in redux state and persisting the whole state tree in Async Storage. Or sending user tokens and personal info to an application monitoring service such as Sentry or Crashlytics.

Authentication and Deep Linking

Mobile apps have a unique vulnerability that is non-existent in the web: deep linking. Deep linking is a way of sending data directly to a native application from an outside source. A deep link looks like app:// where app is your app scheme and anything following the // could be used internally to handle the request.

For example, if you were building an ecommerce app, you could use app://products/1 to deep link to your app and open the product detail page for a product with id 1. You can think of these kind of like URLs on the web, but with one crucial distinction:

Deep links are not secure and you should never send any sensitive information in them.

The reason deep links are not secure is because there is no centralized method of registering URL schemes. As an application developer, you can use almost any url scheme you choose by configuring it in Xcode for iOS or adding an intent on Android.

There is nothing stopping a malicious application from hijacking your deep link by also registering to the same scheme and then obtaining access to the data your link contains. Sending something like app://products/1 is not harmful, but sending tokens is a security concern.

When the operating system has two or more applications to choose from when opening a link, Android will show the user a modal and ask them to choose which application to use to open the link. On iOS however, the operating system will make the choice for you, so the user will be blissfully unaware. Apple has made steps to address this issue in later iOS versions (iOS 11) where they instituted a first-come-first-served principle, although this vulnerability could still be exploited in different ways which you can read more about here. Using universal links will allow linking to content within your app securely in iOS.

OAuth2 and Redirects

The OAuth2 authentication protocol is incredibly popular nowadays, prided as the most complete and secure protocol around. The OpenID Connect protocol is also based on this. In OAuth2, the user is asked to authenticate via a third party. On successful completion, this third party redirects back to the requesting application with a verification code which can be exchanged for a JWT — a JSON Web Token. JWT is an open standard for securely transmitting information between parties on the web.

On the web, this redirect step is secure, because URLs on the web are guaranteed to be unique. This is not true for apps because, as mentioned earlier, there is no centralized method of registering URL schemes! In order to address this security concern, an additional check must be added in the form of PKCE.

PKCE, pronounced “Pixy” stands for Proof of Key Code Exchange, and is an extension to the OAuth 2 spec. This involves adding an additional layer of security which verifies that the authentication and token exchange requests come from the same client. PKCE uses the SHA 256 Cryptographic Hash Algorithm. SHA 256 creates a unique “signature” for a text or file of any size, but it is:

  • Always the same length regardless of the input file
  • Guaranteed to always produce the same result for the same input
  • One way (that is, you can’t reverse engineer it to reveal the original input)

Now you have two values:

  • code_verifier - a large random string generated by the client
  • code_challenge - the SHA 256 of the code_verifier

During the initial /authorize request, the client also sends the code_challenge for the code_verifier it keeps in memory. After the authorize request has returned correctly, the client also sends the code_verifier that was used to generate the code_challenge. The IDP will then calculate the code_challenge, see if it matches what was set on the very first /authorize request, and only send the access token if the values match.

This guarantees that only the application that triggered the initial authorization flow would be able to successfully exchange the verification code for a JWT. So even if a malicious application gets access to the verification code, it will be useless on its own. To see this in action, check out this example.

A library to consider for native OAuth is react-native-app-auth. React-native-app-auth is an SDK for communicating with OAuth2 providers. It wraps the native AppAuth-iOS and AppAuth-Android libraries and can support PKCE.

React-native-app-auth can support PKCE only if your Identity Provider supports it.

OAuth2 with PKCE

Network Security

Your APIs should always use SSL encryption. SSL encryption protects against the requested data being read in plain text between when it leaves the server and before it reaches the client. You’ll know the endpoint is secure, because it starts with https:// instead of http://.

SSL Pinning

Using https endpoints could still leave your data vulnerable to interception. With https, the client will only trust the server if it can provide a valid certificate that is signed by a trusted Certificate Authority that is pre-installed on the client. An attacker could take advantage of this by installing a malicious root CA certificate to the user’s device, so the client would trust all certificates that are signed by the attacker. Thus, relying on certificates alone could still leave you vulnerable to a man-in-the-middle attack.

SSL pinning is a technique that can be used on the client side to avoid this attack. It works by embedding (or pinning) a list of trusted certificates to the client during development, so that only the requests signed with one of the trusted certificates will be accepted, and any self-signed certificates will not be.

When using SSL pinning, you should be mindful of certificate expiry. Certificates expire every 1-2 years and when one does, it’ll need to be updated in the app as well as on the server. As soon as the certificate on the server has been updated, any apps with the old certificate embedded in them will cease to work.

Summary

There is no bulletproof way to handle security, but with conscious effort and diligence, it is possible to significantly reduce the likelihood of a security breach in your application. Invest in security proportional to the sensitivity of the data stored in your application, the number of users, and the damage a hacker could do when gaining access to their account. And remember: it’s significantly harder to access information that was never requested in the first place.

Edit this page
Last updated on
- + diff --git a/docs/segmentedcontrolios.html b/docs/segmentedcontrolios.html index bf781f90b62..b54ae166143 100644 --- a/docs/segmentedcontrolios.html +++ b/docs/segmentedcontrolios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 SegmentedControlIOS

Deprecated. Use one of the community packages instead.

Uses SegmentedControlIOS to render a UISegmentedControl iOS.

Programmatically changing selected index

The selected index can be changed on the fly by assigning the selectedIndex prop to a state variable, then changing that variable. Note that the state variable would need to be updated as the user selects a value and changes the index, as shown in the example below.

Example

Reference

Props

Inherits View Props.

enabled

If false the user won't be able to interact with the control. Default value is true.

TypeRequired
boolNo

momentary

If true, then selecting a segment won't persist visually. The onValueChange callback will still work as expected.

TypeRequired
boolNo

onChange

Callback that is called when the user taps a segment; passes the event as an argument

TypeRequired
functionNo

onValueChange

Callback that is called when the user taps a segment; passes the segment's value as an argument

TypeRequired
functionNo

selectedIndex

The index in props.values of the segment to be (pre)selected.

TypeRequired
numberNo

tintColor

Note: tintColor is not supported on the iOS 13+.

Accent color of the control.

TypeRequired
stringNo

values

The labels for the control's segment buttons, in order.

TypeRequired
array of stringNo
Edit this page
Last updated on
- + diff --git a/docs/segmentedcontrolios/index.html b/docs/segmentedcontrolios/index.html index bf781f90b62..b54ae166143 100644 --- a/docs/segmentedcontrolios/index.html +++ b/docs/segmentedcontrolios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 SegmentedControlIOS

Deprecated. Use one of the community packages instead.

Uses SegmentedControlIOS to render a UISegmentedControl iOS.

Programmatically changing selected index

The selected index can be changed on the fly by assigning the selectedIndex prop to a state variable, then changing that variable. Note that the state variable would need to be updated as the user selects a value and changes the index, as shown in the example below.

Example

Reference

Props

Inherits View Props.

enabled

If false the user won't be able to interact with the control. Default value is true.

TypeRequired
boolNo

momentary

If true, then selecting a segment won't persist visually. The onValueChange callback will still work as expected.

TypeRequired
boolNo

onChange

Callback that is called when the user taps a segment; passes the event as an argument

TypeRequired
functionNo

onValueChange

Callback that is called when the user taps a segment; passes the segment's value as an argument

TypeRequired
functionNo

selectedIndex

The index in props.values of the segment to be (pre)selected.

TypeRequired
numberNo

tintColor

Note: tintColor is not supported on the iOS 13+.

Accent color of the control.

TypeRequired
stringNo

values

The labels for the control's segment buttons, in order.

TypeRequired
array of stringNo
Edit this page
Last updated on
- + diff --git a/docs/settings.html b/docs/settings.html index df9b188db4f..f827979349f 100644 --- a/docs/settings.html +++ b/docs/settings.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Settings

Settings serves as a wrapper for NSUserDefaults, a persistent key-value store available only on iOS.

Example

Reference

Methods

clearWatch()

static clearWatch(watchId: number)

watchId is the number returned by watchKeys() when the subscription was originally configured.

get()

static get(key: string): mixed

Get the current value for a given key in NSUserDefaults.

set()

static set(settings: object)

Set one or more values in NSUserDefaults.

watchKeys()

static watchKeys(keys: string | array<string>, callback: function): number

Subscribe to be notified when the value for any of the keys specified by the keys parameter has been changed in NSUserDefaults. Returns a watchId number that may be used with clearWatch() to unsubscribe.

Note: watchKeys() by design ignores internal set() calls and fires callback only on changes preformed outside of React Native code.

Edit this page
Last updated on
- + diff --git a/docs/settings/index.html b/docs/settings/index.html index df9b188db4f..f827979349f 100644 --- a/docs/settings/index.html +++ b/docs/settings/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Settings

Settings serves as a wrapper for NSUserDefaults, a persistent key-value store available only on iOS.

Example

Reference

Methods

clearWatch()

static clearWatch(watchId: number)

watchId is the number returned by watchKeys() when the subscription was originally configured.

get()

static get(key: string): mixed

Get the current value for a given key in NSUserDefaults.

set()

static set(settings: object)

Set one or more values in NSUserDefaults.

watchKeys()

static watchKeys(keys: string | array<string>, callback: function): number

Subscribe to be notified when the value for any of the keys specified by the keys parameter has been changed in NSUserDefaults. Returns a watchId number that may be used with clearWatch() to unsubscribe.

Note: watchKeys() by design ignores internal set() calls and fires callback only on changes preformed outside of React Native code.

Edit this page
Last updated on
- + diff --git a/docs/shadow-props.html b/docs/shadow-props.html index dfb6032a8f8..dd56112ad2f 100644 --- a/docs/shadow-props.html +++ b/docs/shadow-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Shadow Props

Reference

These properties are iOS only - for similar functionality on Android, use the elevation property.

Props

shadowColor

Sets the drop shadow color

TypeRequiredPlatform
colorNoiOS

shadowOffset

Sets the drop shadow offset

TypeRequiredPlatform
object: {width: number,height: number}NoiOS

shadowOpacity

Sets the drop shadow opacity (multiplied by the color's alpha component)

TypeRequiredPlatform
numberNoiOS

shadowRadius

Sets the drop shadow blur radius

TypeRequiredPlatform
numberNoiOS
Edit this page
Last updated on
- + diff --git a/docs/shadow-props/index.html b/docs/shadow-props/index.html index dfb6032a8f8..dd56112ad2f 100644 --- a/docs/shadow-props/index.html +++ b/docs/shadow-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Shadow Props

Reference

These properties are iOS only - for similar functionality on Android, use the elevation property.

Props

shadowColor

Sets the drop shadow color

TypeRequiredPlatform
colorNoiOS

shadowOffset

Sets the drop shadow offset

TypeRequiredPlatform
object: {width: number,height: number}NoiOS

shadowOpacity

Sets the drop shadow opacity (multiplied by the color's alpha component)

TypeRequiredPlatform
numberNoiOS

shadowRadius

Sets the drop shadow blur radius

TypeRequiredPlatform
numberNoiOS
Edit this page
Last updated on
- + diff --git a/docs/share.html b/docs/share.html index f4b0fa1db3b..daf7ac8b801 100644 --- a/docs/share.html +++ b/docs/share.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Share

Example

Reference

Methods

share()

static share(content, options)

Open a dialog to share text content.

In iOS, returns a Promise which will be invoked with an object containing action and activityType. If the user dismissed the dialog, the Promise will still be resolved with action being Share.dismissedAction and all the other keys being undefined. Note that some share options will not appear or work on the iOS simulator.

In Android, returns a Promise which will always be resolved with action being Share.sharedAction.

Content

  • message - a message to share

iOS

  • url - an URL to share

At least one of URL and message is required.

Android

  • title - title of the message

Options

iOS

  • subject - a subject to share via email
  • excludedActivityTypes
  • tintColor

Android

  • dialogTitle

sharedAction

static sharedAction

The content was successfully shared.

dismissedAction

static dismissedAction

iOS Only. The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/share/index.html b/docs/share/index.html index f4b0fa1db3b..daf7ac8b801 100644 --- a/docs/share/index.html +++ b/docs/share/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Share

Example

Reference

Methods

share()

static share(content, options)

Open a dialog to share text content.

In iOS, returns a Promise which will be invoked with an object containing action and activityType. If the user dismissed the dialog, the Promise will still be resolved with action being Share.dismissedAction and all the other keys being undefined. Note that some share options will not appear or work on the iOS simulator.

In Android, returns a Promise which will always be resolved with action being Share.sharedAction.

Content

  • message - a message to share

iOS

  • url - an URL to share

At least one of URL and message is required.

Android

  • title - title of the message

Options

iOS

  • subject - a subject to share via email
  • excludedActivityTypes
  • tintColor

Android

  • dialogTitle

sharedAction

static sharedAction

The content was successfully shared.

dismissedAction

static dismissedAction

iOS Only. The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/signed-apk-android.html b/docs/signed-apk-android.html index 1c1cc6b8c06..7744e118577 100644 --- a/docs/signed-apk-android.html +++ b/docs/signed-apk-android.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Publishing to Google Play Store

Android requires that all apps be digitally signed with a certificate before they can be installed. In order to distribute your Android application via Google Play store it needs to be signed with a release key that then needs to be used for all future updates. Since 2017 it is possible for Google Play to manage signing releases automatically thanks to App Signing by Google Play functionality. However, before your application binary is uploaded to Google Play it needs to be signed with an upload key. The Signing Your Applications page on Android Developers documentation describes the topic in detail. This guide covers the process in brief, as well as lists the steps required to package the JavaScript bundle.

Generating an upload key

You can generate a private signing key using keytool. On Windows keytool must be run from C:\Program Files\Java\jdkx.x.x_x\bin.

$ keytool -genkeypair -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

This command prompts you for passwords for the keystore and key and for the Distinguished Name fields for your key. It then generates the keystore as a file called my-upload-key.keystore.

The keystore contains a single key, valid for 10000 days. The alias is a name that you will use later when signing your app, so remember to take note of the alias.

On Mac, if you're not sure where your JDK bin folder is, then perform the following command to find it:

$ /usr/libexec/java_home

It will output the directory of the JDK, which will look something like this:

/Library/Java/JavaVirtualMachines/jdkX.X.X_XXX.jdk/Contents/Home

Navigate to that directory by using the command $ cd /your/jdk/path and use the keytool command with sudo permission as shown below.

$ sudo keytool -genkey -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

Note: Remember to keep the keystore file private. In case you've lost upload key or it's been compromised you should follow these instructions.

Setting up Gradle variables

  1. Place the my-upload-key.keystore file under the android/app directory in your project folder.
  2. Edit the file ~/.gradle/gradle.properties or android/gradle.properties, and add the following (replace ***** with the correct keystore password, alias and key password),
MYAPP_UPLOAD_STORE_FILE=my-upload-key.keystore
MYAPP_UPLOAD_KEY_ALIAS=my-key-alias
MYAPP_UPLOAD_STORE_PASSWORD=*****
MYAPP_UPLOAD_KEY_PASSWORD=*****

These are going to be global Gradle variables, which we can later use in our Gradle config to sign our app.

Note about security: If you are not keen on storing your passwords in plaintext, and you are running OSX, you can also store your credentials in the Keychain Access app. Then you can skip the two last rows in ~/.gradle/gradle.properties.

Adding signing config to your app's Gradle config

The last configuration step that needs to be done is to setup release builds to be signed using upload key. Edit the file android/app/build.gradle in your project folder, and add the signing config,

...
android {
...
defaultConfig { ... }
signingConfigs {
release {
if (project.hasProperty('MYAPP_UPLOAD_STORE_FILE')) {
storeFile file(MYAPP_UPLOAD_STORE_FILE)
storePassword MYAPP_UPLOAD_STORE_PASSWORD
keyAlias MYAPP_UPLOAD_KEY_ALIAS
keyPassword MYAPP_UPLOAD_KEY_PASSWORD
}
}
}
buildTypes {
release {
...
signingConfig signingConfigs.release
}
}
}
...

Generating the release APK

Run the following in a terminal:

$ cd android
$ ./gradlew bundleRelease

Gradle's bundleRelease will bundle all the JavaScript needed to run your app into the AAB (Android App Bundle). If you need to change the way the JavaScript bundle and/or drawable resources are bundled (e.g. if you changed the default file/folder names or the general structure of the project), have a look at android/app/build.gradle to see how you can update it to reflect these changes.

Note: Make sure gradle.properties does not include org.gradle.configureondemand=true as that will make the release build skip bundling JS and assets into the app binary.

The generated AAB can be found under android/app/build/outputs/bundle/release/app.aab, and is ready to be uploaded to Google Play.

Note: In order for Google Play to accept AAB format the App Signing by Google Play needs to be configured for your application on the Google Play Console. If you are updating an existing app that doesn't use App Signing by Google Play, please check our migration section to learn how to perform that configuration change.

Testing the release build of your app

Before uploading the release build to the Play Store, make sure you test it thoroughly. First uninstall any previous version of the app you already have installed. Install it on the device using the following command in the project root:

$ npx react-native run-android --variant=release

Note that --variant=release is only available if you've set up signing as described above.

You can terminate any running bundler instances, since all your framework and JavaScript code is bundled in the APK's assets.

Publishing to other stores

By default, the generated APK has the native code for both x86 and ARMv7a CPU architectures. This makes it easier to share APKs that run on almost all Android devices. However, this has the downside that there will be some unused native code on any device, leading to unnecessarily bigger APKs.

You can create an APK for each CPU by changing the following line in android/app/build.gradle:

- ndk {
- abiFilters "armeabi-v7a", "x86"
- }
- def enableSeparateBuildPerCPUArchitecture = false
+ def enableSeparateBuildPerCPUArchitecture = true

Upload both these files to markets which support device targeting, such as Google Play and Amazon AppStore, and the users will automatically get the appropriate APK. If you want to upload to other markets, such as APKFiles, which do not support multiple APKs for a single app, change the following line as well to create the default universal APK with binaries for both CPUs.

- universalApk false // If true, also generate a universal APK
+ universalApk true // If true, also generate a universal APK

Enabling Proguard to reduce the size of the APK (optional)

Proguard is a tool that can slightly reduce the size of the APK. It does this by stripping parts of the React Native Java bytecode (and its dependencies) that your app is not using.

IMPORTANT: Make sure to thoroughly test your app if you've enabled Proguard. Proguard often requires configuration specific to each native library you're using. See app/proguard-rules.pro.

To enable Proguard, edit android/app/build.gradle:

/**
* Run Proguard to shrink the Java bytecode in release builds.
*/
def enableProguardInReleaseBuilds = true

Migrating old Android React Native apps to use App Signing by Google Play

If you are migrating from previous version of React Native chances are your app does not use App Signing by Google Play feature. We recommend you enable that in order to take advantage from things like automatic app splitting. In order to migrate from the old way of signing you need to start by generating new upload key and then replacing release signing config in android/app/build.gradle to use the upload key instead of the release one (see section about adding signing config to gradle). Once that's done you should follow the instructions from Google Play Help website in order to send your original release key to Google Play.

Edit this page
Last updated on
- + diff --git a/docs/signed-apk-android/index.html b/docs/signed-apk-android/index.html index 1c1cc6b8c06..7744e118577 100644 --- a/docs/signed-apk-android/index.html +++ b/docs/signed-apk-android/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Publishing to Google Play Store

Android requires that all apps be digitally signed with a certificate before they can be installed. In order to distribute your Android application via Google Play store it needs to be signed with a release key that then needs to be used for all future updates. Since 2017 it is possible for Google Play to manage signing releases automatically thanks to App Signing by Google Play functionality. However, before your application binary is uploaded to Google Play it needs to be signed with an upload key. The Signing Your Applications page on Android Developers documentation describes the topic in detail. This guide covers the process in brief, as well as lists the steps required to package the JavaScript bundle.

Generating an upload key

You can generate a private signing key using keytool. On Windows keytool must be run from C:\Program Files\Java\jdkx.x.x_x\bin.

$ keytool -genkeypair -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

This command prompts you for passwords for the keystore and key and for the Distinguished Name fields for your key. It then generates the keystore as a file called my-upload-key.keystore.

The keystore contains a single key, valid for 10000 days. The alias is a name that you will use later when signing your app, so remember to take note of the alias.

On Mac, if you're not sure where your JDK bin folder is, then perform the following command to find it:

$ /usr/libexec/java_home

It will output the directory of the JDK, which will look something like this:

/Library/Java/JavaVirtualMachines/jdkX.X.X_XXX.jdk/Contents/Home

Navigate to that directory by using the command $ cd /your/jdk/path and use the keytool command with sudo permission as shown below.

$ sudo keytool -genkey -v -keystore my-upload-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

Note: Remember to keep the keystore file private. In case you've lost upload key or it's been compromised you should follow these instructions.

Setting up Gradle variables

  1. Place the my-upload-key.keystore file under the android/app directory in your project folder.
  2. Edit the file ~/.gradle/gradle.properties or android/gradle.properties, and add the following (replace ***** with the correct keystore password, alias and key password),
MYAPP_UPLOAD_STORE_FILE=my-upload-key.keystore
MYAPP_UPLOAD_KEY_ALIAS=my-key-alias
MYAPP_UPLOAD_STORE_PASSWORD=*****
MYAPP_UPLOAD_KEY_PASSWORD=*****

These are going to be global Gradle variables, which we can later use in our Gradle config to sign our app.

Note about security: If you are not keen on storing your passwords in plaintext, and you are running OSX, you can also store your credentials in the Keychain Access app. Then you can skip the two last rows in ~/.gradle/gradle.properties.

Adding signing config to your app's Gradle config

The last configuration step that needs to be done is to setup release builds to be signed using upload key. Edit the file android/app/build.gradle in your project folder, and add the signing config,

...
android {
...
defaultConfig { ... }
signingConfigs {
release {
if (project.hasProperty('MYAPP_UPLOAD_STORE_FILE')) {
storeFile file(MYAPP_UPLOAD_STORE_FILE)
storePassword MYAPP_UPLOAD_STORE_PASSWORD
keyAlias MYAPP_UPLOAD_KEY_ALIAS
keyPassword MYAPP_UPLOAD_KEY_PASSWORD
}
}
}
buildTypes {
release {
...
signingConfig signingConfigs.release
}
}
}
...

Generating the release APK

Run the following in a terminal:

$ cd android
$ ./gradlew bundleRelease

Gradle's bundleRelease will bundle all the JavaScript needed to run your app into the AAB (Android App Bundle). If you need to change the way the JavaScript bundle and/or drawable resources are bundled (e.g. if you changed the default file/folder names or the general structure of the project), have a look at android/app/build.gradle to see how you can update it to reflect these changes.

Note: Make sure gradle.properties does not include org.gradle.configureondemand=true as that will make the release build skip bundling JS and assets into the app binary.

The generated AAB can be found under android/app/build/outputs/bundle/release/app.aab, and is ready to be uploaded to Google Play.

Note: In order for Google Play to accept AAB format the App Signing by Google Play needs to be configured for your application on the Google Play Console. If you are updating an existing app that doesn't use App Signing by Google Play, please check our migration section to learn how to perform that configuration change.

Testing the release build of your app

Before uploading the release build to the Play Store, make sure you test it thoroughly. First uninstall any previous version of the app you already have installed. Install it on the device using the following command in the project root:

$ npx react-native run-android --variant=release

Note that --variant=release is only available if you've set up signing as described above.

You can terminate any running bundler instances, since all your framework and JavaScript code is bundled in the APK's assets.

Publishing to other stores

By default, the generated APK has the native code for both x86 and ARMv7a CPU architectures. This makes it easier to share APKs that run on almost all Android devices. However, this has the downside that there will be some unused native code on any device, leading to unnecessarily bigger APKs.

You can create an APK for each CPU by changing the following line in android/app/build.gradle:

- ndk {
- abiFilters "armeabi-v7a", "x86"
- }
- def enableSeparateBuildPerCPUArchitecture = false
+ def enableSeparateBuildPerCPUArchitecture = true

Upload both these files to markets which support device targeting, such as Google Play and Amazon AppStore, and the users will automatically get the appropriate APK. If you want to upload to other markets, such as APKFiles, which do not support multiple APKs for a single app, change the following line as well to create the default universal APK with binaries for both CPUs.

- universalApk false // If true, also generate a universal APK
+ universalApk true // If true, also generate a universal APK

Enabling Proguard to reduce the size of the APK (optional)

Proguard is a tool that can slightly reduce the size of the APK. It does this by stripping parts of the React Native Java bytecode (and its dependencies) that your app is not using.

IMPORTANT: Make sure to thoroughly test your app if you've enabled Proguard. Proguard often requires configuration specific to each native library you're using. See app/proguard-rules.pro.

To enable Proguard, edit android/app/build.gradle:

/**
* Run Proguard to shrink the Java bytecode in release builds.
*/
def enableProguardInReleaseBuilds = true

Migrating old Android React Native apps to use App Signing by Google Play

If you are migrating from previous version of React Native chances are your app does not use App Signing by Google Play feature. We recommend you enable that in order to take advantage from things like automatic app splitting. In order to migrate from the old way of signing you need to start by generating new upload key and then replacing release signing config in android/app/build.gradle to use the upload key instead of the release one (see section about adding signing config to gradle). Once that's done you should follow the instructions from Google Play Help website in order to send your original release key to Google Play.

Edit this page
Last updated on
- + diff --git a/docs/slider.html b/docs/slider.html index 11a86e5400d..d4cbfb321c9 100644 --- a/docs/slider.html +++ b/docs/slider.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 Slider

Deprecated. Use one of the community packages instead.

A component used to select a single value from a range of values.

Reference

Props

Inherits View Props.

style

Used to style and layout the Slider. See StyleSheet.js and ViewStylePropTypes.js for more info.

TypeRequired
View.styleNo

disabled

If true the user won't be able to move the slider. Default value is false.

TypeRequired
boolNo

maximumValue

Initial maximum value of the slider. Default value is 1.

TypeRequired
numberNo

minimumTrackTintColor

The color used for the track to the left of the button. Overrides the default blue gradient image on iOS.

TypeRequired
colorNo

minimumValue

Initial minimum value of the slider. Default value is 0.

TypeRequired
numberNo

onSlidingComplete

Callback that is called when the user releases the slider, regardless if the value has changed. The current value is passed as an argument to the callback handler.

TypeRequired
functionNo

onValueChange

Callback continuously called while the user is dragging the slider.

TypeRequired
functionNo

step

Step value of the slider. The value should be between 0 and (maximumValue - minimumValue). Default value is 0.

TypeRequired
numberNo

maximumTrackTintColor

The color used for the track to the right of the button. Overrides the default gray gradient image on iOS.

TypeRequired
colorNo

testID

Used to locate this view in UI automation tests.

TypeRequired
stringNo

value

Initial value of the slider. The value should be between minimumValue and maximumValue, which default to 0 and 1 respectively. Default value is 0.

This is not a controlled component, you don't need to update the value during dragging.

TypeRequired
numberNo

thumbTintColor

The color used to tint the default thumb images on iOS, or the color of the foreground switch grip on Android.

TypeRequired
colorNo

maximumTrackImage

Assigns a maximum track image. Only static images are supported. The leftmost pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

minimumTrackImage

Assigns a minimum track image. Only static images are supported. The rightmost pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

thumbImage

Sets an image for the thumb. Only static images are supported.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

trackImage

Assigns a single image for the track. Only static images are supported. The center pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS
Edit this page
Last updated on
- + diff --git a/docs/slider/index.html b/docs/slider/index.html index 11a86e5400d..d4cbfb321c9 100644 --- a/docs/slider/index.html +++ b/docs/slider/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 Slider

Deprecated. Use one of the community packages instead.

A component used to select a single value from a range of values.

Reference

Props

Inherits View Props.

style

Used to style and layout the Slider. See StyleSheet.js and ViewStylePropTypes.js for more info.

TypeRequired
View.styleNo

disabled

If true the user won't be able to move the slider. Default value is false.

TypeRequired
boolNo

maximumValue

Initial maximum value of the slider. Default value is 1.

TypeRequired
numberNo

minimumTrackTintColor

The color used for the track to the left of the button. Overrides the default blue gradient image on iOS.

TypeRequired
colorNo

minimumValue

Initial minimum value of the slider. Default value is 0.

TypeRequired
numberNo

onSlidingComplete

Callback that is called when the user releases the slider, regardless if the value has changed. The current value is passed as an argument to the callback handler.

TypeRequired
functionNo

onValueChange

Callback continuously called while the user is dragging the slider.

TypeRequired
functionNo

step

Step value of the slider. The value should be between 0 and (maximumValue - minimumValue). Default value is 0.

TypeRequired
numberNo

maximumTrackTintColor

The color used for the track to the right of the button. Overrides the default gray gradient image on iOS.

TypeRequired
colorNo

testID

Used to locate this view in UI automation tests.

TypeRequired
stringNo

value

Initial value of the slider. The value should be between minimumValue and maximumValue, which default to 0 and 1 respectively. Default value is 0.

This is not a controlled component, you don't need to update the value during dragging.

TypeRequired
numberNo

thumbTintColor

The color used to tint the default thumb images on iOS, or the color of the foreground switch grip on Android.

TypeRequired
colorNo

maximumTrackImage

Assigns a maximum track image. Only static images are supported. The leftmost pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

minimumTrackImage

Assigns a minimum track image. Only static images are supported. The rightmost pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

thumbImage

Sets an image for the thumb. Only static images are supported.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS

trackImage

Assigns a single image for the track. Only static images are supported. The center pixel of the image will be stretched to fill the track.

TypeRequiredPlatform
Image.propTypes.sourceNoiOS
Edit this page
Last updated on
- + diff --git a/docs/snapshotviewios.html b/docs/snapshotviewios.html index cc10c06cde0..e705573cf02 100644 --- a/docs/snapshotviewios.html +++ b/docs/snapshotviewios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Edit this page
Last updated on
- + diff --git a/docs/snapshotviewios/index.html b/docs/snapshotviewios/index.html index cc10c06cde0..e705573cf02 100644 --- a/docs/snapshotviewios/index.html +++ b/docs/snapshotviewios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@
Edit this page
Last updated on
- + diff --git a/docs/state.html b/docs/state.html index 66db60f2cf1..98faef9940e 100644 --- a/docs/state.html +++ b/docs/state.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

State

There are two types of data that control a component: props and state. props are set by the parent and they are fixed throughout the lifetime of a component. For data that is going to change, we have to use state.

In general, you should initialize state in the constructor, and then call setState when you want to change it.

For example, let's say we want to make text that blinks all the time. The text itself gets set once when the blinking component gets created, so the text itself is a prop. The "whether the text is currently on or off" changes over time, so that should be kept in state.

In a real application, you probably won't be setting state with a timer. You might set state when you have new data from the server, or from user input. You can also use a state container like Redux or Mobx to control your data flow. In that case you would use Redux or Mobx to modify your state rather than calling setState directly.

When setState is called, BlinkApp will re-render its Component. By calling setState within the Timer, the component will re-render every time the Timer ticks.

State works the same way as it does in React, so for more details on handling state, you can look at the React.Component API. At this point, you may have noticed that most of our examples use the default text color. To customize the text color, you will have to learn about Style.

Edit this page
Last updated on
- + diff --git a/docs/state/index.html b/docs/state/index.html index 66db60f2cf1..98faef9940e 100644 --- a/docs/state/index.html +++ b/docs/state/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

State

There are two types of data that control a component: props and state. props are set by the parent and they are fixed throughout the lifetime of a component. For data that is going to change, we have to use state.

In general, you should initialize state in the constructor, and then call setState when you want to change it.

For example, let's say we want to make text that blinks all the time. The text itself gets set once when the blinking component gets created, so the text itself is a prop. The "whether the text is currently on or off" changes over time, so that should be kept in state.

In a real application, you probably won't be setting state with a timer. You might set state when you have new data from the server, or from user input. You can also use a state container like Redux or Mobx to control your data flow. In that case you would use Redux or Mobx to modify your state rather than calling setState directly.

When setState is called, BlinkApp will re-render its Component. By calling setState within the Timer, the component will re-render every time the Timer ticks.

State works the same way as it does in React, so for more details on handling state, you can look at the React.Component API. At this point, you may have noticed that most of our examples use the default text color. To customize the text color, you will have to learn about Style.

Edit this page
Last updated on
- + diff --git a/docs/statusbar.html b/docs/statusbar.html index a20c81addb1..ccca4d85f67 100644 --- a/docs/statusbar.html +++ b/docs/statusbar.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

StatusBar

Component to control the app status bar.

Usage with Navigator

It is possible to have multiple StatusBar components mounted at the same time. The props will be merged in the order the StatusBar components were mounted.

Imperative API

For cases where using a component is not ideal, there is also an imperative API exposed as static functions on the component. It is however not recommended to use the static API and the component for the same prop because any value set by the static API will get overridden by the one set by the component in the next render.

Reference

Constants

currentHeight (Android only) The height of the status bar.

Props

animated

If the transition between status bar property changes should be animated. Supported for backgroundColor, barStyle and hidden.

TypeRequired
boolNo

backgroundColor

The background color of the status bar.

TypeRequiredPlatform
colorNoAndroid

barStyle

Sets the color of the status bar text.

On Android, this will only have an impact on API versions 23 and above.

TypeRequired
enum('default', 'light-content', 'dark-content')No

hidden

If the status bar is hidden.

TypeRequired
boolNo

networkActivityIndicatorVisible

If the network activity indicator should be visible.

TypeRequiredPlatform
boolNoiOS

showHideTransition

The transition effect when showing and hiding the status bar using the hidden prop. Defaults to 'fade'.

TypeRequiredPlatform
enum('fade', 'slide')NoiOS

translucent

If the status bar is translucent. When translucent is set to true, the app will draw under the status bar. This is useful when using a semi transparent status bar color.

TypeRequiredPlatform
boolNoAndroid

Methods

popStackEntry()

static popStackEntry(entry: any)

Get and remove the last StatusBar entry from the stack.

Parameters:

NameTypeRequiredDescription
entryanyYesEntry returned from pushStackEntry.

pushStackEntry()

static pushStackEntry(props: any)

Push a StatusBar entry onto the stack. The return value should be passed to popStackEntry when complete.

Parameters:

NameTypeRequiredDescription
propsanyYesObject containing the StatusBar props to use in the stack entry.

replaceStackEntry()

static replaceStackEntry(entry: any, props: any)

Replace an existing StatusBar stack entry with new props.

Parameters:

NameTypeRequiredDescription
entryanyYesEntry returned from pushStackEntry to replace.
propsanyYesObject containing the StatusBar props to use in the replacement stack entry.

setBackgroundColor()

static setBackgroundColor(color: string, [animated]: boolean)

Set the background color for the status bar. Android-only

Parameters:

NameTypeRequiredDescription
colorstringYesBackground color.
animatedbooleanNoAnimate the style change.

setBarStyle()

static setBarStyle(style: StatusBarStyle, [animated]: boolean)

Set the status bar style

Parameters:

NameTypeRequiredDescription
styleStatusBarStyleYesStatus bar style to set
animatedbooleanNoAnimate the style change.

setHidden()

static setHidden(hidden: boolean, [animation]: StatusBarAnimation)

Show or hide the status bar

Parameters:

NameTypeRequiredDescription
hiddenbooleanYesHide the status bar.
animationStatusBarAnimationNoOptional animation when changing the status bar hidden property.

setNetworkActivityIndicatorVisible()

static setNetworkActivityIndicatorVisible(visible: boolean)

Control the visibility of the network activity indicator. iOS-only.

Parameters:

NameTypeRequiredDescription
visiblebooleanYesShow the indicator.

setTranslucent()

static setTranslucent(translucent: boolean)

Control the translucency of the status bar. Android-only.

Parameters:

NameTypeRequiredDescription
translucentbooleanYesSet as translucent.

Type Definitions

StatusBarAnimation

Status bar animation

Type
\$Enum

Constants:

ValueDescription
noneNo animation
fadeFade animation
slideSlide animation

StatusBarStyle

Status bar style

Type
\$Enum

Constants:

ValueDescription
defaultDefault status bar style (dark for iOS, light for Android)
light-contentDark background, white texts and icons
dark-contentLight background, dark texts and icons (requires API>=23 on Android)
Edit this page
Last updated on
- + diff --git a/docs/statusbar/index.html b/docs/statusbar/index.html index a20c81addb1..ccca4d85f67 100644 --- a/docs/statusbar/index.html +++ b/docs/statusbar/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

StatusBar

Component to control the app status bar.

Usage with Navigator

It is possible to have multiple StatusBar components mounted at the same time. The props will be merged in the order the StatusBar components were mounted.

Imperative API

For cases where using a component is not ideal, there is also an imperative API exposed as static functions on the component. It is however not recommended to use the static API and the component for the same prop because any value set by the static API will get overridden by the one set by the component in the next render.

Reference

Constants

currentHeight (Android only) The height of the status bar.

Props

animated

If the transition between status bar property changes should be animated. Supported for backgroundColor, barStyle and hidden.

TypeRequired
boolNo

backgroundColor

The background color of the status bar.

TypeRequiredPlatform
colorNoAndroid

barStyle

Sets the color of the status bar text.

On Android, this will only have an impact on API versions 23 and above.

TypeRequired
enum('default', 'light-content', 'dark-content')No

hidden

If the status bar is hidden.

TypeRequired
boolNo

networkActivityIndicatorVisible

If the network activity indicator should be visible.

TypeRequiredPlatform
boolNoiOS

showHideTransition

The transition effect when showing and hiding the status bar using the hidden prop. Defaults to 'fade'.

TypeRequiredPlatform
enum('fade', 'slide')NoiOS

translucent

If the status bar is translucent. When translucent is set to true, the app will draw under the status bar. This is useful when using a semi transparent status bar color.

TypeRequiredPlatform
boolNoAndroid

Methods

popStackEntry()

static popStackEntry(entry: any)

Get and remove the last StatusBar entry from the stack.

Parameters:

NameTypeRequiredDescription
entryanyYesEntry returned from pushStackEntry.

pushStackEntry()

static pushStackEntry(props: any)

Push a StatusBar entry onto the stack. The return value should be passed to popStackEntry when complete.

Parameters:

NameTypeRequiredDescription
propsanyYesObject containing the StatusBar props to use in the stack entry.

replaceStackEntry()

static replaceStackEntry(entry: any, props: any)

Replace an existing StatusBar stack entry with new props.

Parameters:

NameTypeRequiredDescription
entryanyYesEntry returned from pushStackEntry to replace.
propsanyYesObject containing the StatusBar props to use in the replacement stack entry.

setBackgroundColor()

static setBackgroundColor(color: string, [animated]: boolean)

Set the background color for the status bar. Android-only

Parameters:

NameTypeRequiredDescription
colorstringYesBackground color.
animatedbooleanNoAnimate the style change.

setBarStyle()

static setBarStyle(style: StatusBarStyle, [animated]: boolean)

Set the status bar style

Parameters:

NameTypeRequiredDescription
styleStatusBarStyleYesStatus bar style to set
animatedbooleanNoAnimate the style change.

setHidden()

static setHidden(hidden: boolean, [animation]: StatusBarAnimation)

Show or hide the status bar

Parameters:

NameTypeRequiredDescription
hiddenbooleanYesHide the status bar.
animationStatusBarAnimationNoOptional animation when changing the status bar hidden property.

setNetworkActivityIndicatorVisible()

static setNetworkActivityIndicatorVisible(visible: boolean)

Control the visibility of the network activity indicator. iOS-only.

Parameters:

NameTypeRequiredDescription
visiblebooleanYesShow the indicator.

setTranslucent()

static setTranslucent(translucent: boolean)

Control the translucency of the status bar. Android-only.

Parameters:

NameTypeRequiredDescription
translucentbooleanYesSet as translucent.

Type Definitions

StatusBarAnimation

Status bar animation

Type
\$Enum

Constants:

ValueDescription
noneNo animation
fadeFade animation
slideSlide animation

StatusBarStyle

Status bar style

Type
\$Enum

Constants:

ValueDescription
defaultDefault status bar style (dark for iOS, light for Android)
light-contentDark background, white texts and icons
dark-contentLight background, dark texts and icons (requires API>=23 on Android)
Edit this page
Last updated on
- + diff --git a/docs/statusbarios.html b/docs/statusbarios.html index aefdd5328ac..203715a2d6e 100644 --- a/docs/statusbarios.html +++ b/docs/statusbarios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 StatusBarIOS

Deprecated. Use StatusBar for mutating the status bar.

Edit this page
Last updated on
- + diff --git a/docs/statusbarios/index.html b/docs/statusbarios/index.html index aefdd5328ac..203715a2d6e 100644 --- a/docs/statusbarios/index.html +++ b/docs/statusbarios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 StatusBarIOS

Deprecated. Use StatusBar for mutating the status bar.

Edit this page
Last updated on
- + diff --git a/docs/style.html b/docs/style.html index 7397e52b1b8..c0b3aefb8e0 100644 --- a/docs/style.html +++ b/docs/style.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Style

With React Native, you style your application using JavaScript. All of the core components accept a prop named style. The style names and values usually match how CSS works on the web, except names are written using camel casing, e.g. backgroundColor rather than background-color.

The style prop can be a plain old JavaScript object. That's what we usually use for example code. You can also pass an array of styles - the last style in the array has precedence, so you can use this to inherit styles.

As a component grows in complexity, it is often cleaner to use StyleSheet.create to define several styles in one place. Here's an example:

One common pattern is to make your component accept a style prop which in turn is used to style subcomponents. You can use this to make styles "cascade" the way they do in CSS.

There are a lot more ways to customize text style. Check out the Text component reference for a complete list.

Now you can make your text beautiful. The next step in becoming a style expert is to learn how to control component size.

Edit this page
Last updated on
- + diff --git a/docs/style/index.html b/docs/style/index.html index 7397e52b1b8..c0b3aefb8e0 100644 --- a/docs/style/index.html +++ b/docs/style/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Style

With React Native, you style your application using JavaScript. All of the core components accept a prop named style. The style names and values usually match how CSS works on the web, except names are written using camel casing, e.g. backgroundColor rather than background-color.

The style prop can be a plain old JavaScript object. That's what we usually use for example code. You can also pass an array of styles - the last style in the array has precedence, so you can use this to inherit styles.

As a component grows in complexity, it is often cleaner to use StyleSheet.create to define several styles in one place. Here's an example:

One common pattern is to make your component accept a style prop which in turn is used to style subcomponents. You can use this to make styles "cascade" the way they do in CSS.

There are a lot more ways to customize text style. Check out the Text component reference for a complete list.

Now you can make your text beautiful. The next step in becoming a style expert is to learn how to control component size.

Edit this page
Last updated on
- + diff --git a/docs/stylesheet.html b/docs/stylesheet.html index d9fea7f25e8..c4bb460fd32 100644 --- a/docs/stylesheet.html +++ b/docs/stylesheet.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

StyleSheet

A StyleSheet is an abstraction similar to CSS StyleSheets

Code quality tips:

  • By moving styles away from the render function, you're making the code easier to understand.
  • Naming the styles is a good way to add meaning to the low level components in the render function.

Reference

Methods

compose()

static compose(style1: object, style2: object): object | array<object>

Combines two styles such that style2 will override any styles in style1. If either style is falsy, the other one is returned without allocating an array, saving allocations and maintaining reference equality for PureComponent checks.

create()

static create(obj: object): object

Creates a StyleSheet style reference from the given object.

flatten()

static flatten(style: array<object>): object

Flattens an array of style objects, into one aggregated style object. Alternatively, this method can be used to lookup IDs, returned by StyleSheet.register.

NOTE: Exercise caution as abusing this can tax you in terms of optimizations. IDs enable optimizations through the bridge and memory in general. Referring to style objects directly will deprive you of these optimizations.

This method internally uses StyleSheetRegistry.getStyleByID(style) to resolve style objects represented by IDs. Thus, an array of style objects (instances of StyleSheet.create()), are individually resolved to, their respective objects, merged as one and then returned. This also explains the alternative use.

setStyleAttributePreprocessor()

WARNING: EXPERIMENTAL. Breaking changes will probably happen a lot and will not be reliably announced. The whole thing might be deleted, who knows? Use at your own risk.

static setStyleAttributePreprocessor(property: string, process: (propValue: any) => any)

Sets a function to use to pre-process a style property value. This is used internally to process color and transform values. You should not use this unless you really know what you are doing and have exhausted other options.

Properties

absoluteFill

A very common pattern is to create overlays with position absolute and zero positioning (position: 'absolute', left: 0, right: 0, top: 0, bottom: 0), so absoluteFill can be used for convenience and to reduce duplication of these repeated styles. If you want, absoluteFill can be used to create a customized entry in a StyleSheet, e.g.:

absoluteFillObject

Sometimes you may want absoluteFill but with a couple tweaks - absoluteFillObject can be used to create a customized entry in a StyleSheet, e.g.:

hairlineWidth

This is defined as the width of a thin line on the platform. It can be used as the thickness of a border or division between two elements. Example:

This constant will always be a round number of pixels (so a line defined by it can look crisp) and will try to match the standard width of a thin line on the underlying platform. However, you should not rely on it being a constant size, because on different platforms and screen densities its value may be calculated differently.

A line with hairline width may not be visible if your simulator is downscaled.

absoluteFill vs. absoluteFillObject

Currently, there is no difference between using absoluteFill vs. absoluteFillObject.

Edit this page
Last updated on
- + diff --git a/docs/stylesheet/index.html b/docs/stylesheet/index.html index d9fea7f25e8..c4bb460fd32 100644 --- a/docs/stylesheet/index.html +++ b/docs/stylesheet/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

StyleSheet

A StyleSheet is an abstraction similar to CSS StyleSheets

Code quality tips:

  • By moving styles away from the render function, you're making the code easier to understand.
  • Naming the styles is a good way to add meaning to the low level components in the render function.

Reference

Methods

compose()

static compose(style1: object, style2: object): object | array<object>

Combines two styles such that style2 will override any styles in style1. If either style is falsy, the other one is returned without allocating an array, saving allocations and maintaining reference equality for PureComponent checks.

create()

static create(obj: object): object

Creates a StyleSheet style reference from the given object.

flatten()

static flatten(style: array<object>): object

Flattens an array of style objects, into one aggregated style object. Alternatively, this method can be used to lookup IDs, returned by StyleSheet.register.

NOTE: Exercise caution as abusing this can tax you in terms of optimizations. IDs enable optimizations through the bridge and memory in general. Referring to style objects directly will deprive you of these optimizations.

This method internally uses StyleSheetRegistry.getStyleByID(style) to resolve style objects represented by IDs. Thus, an array of style objects (instances of StyleSheet.create()), are individually resolved to, their respective objects, merged as one and then returned. This also explains the alternative use.

setStyleAttributePreprocessor()

WARNING: EXPERIMENTAL. Breaking changes will probably happen a lot and will not be reliably announced. The whole thing might be deleted, who knows? Use at your own risk.

static setStyleAttributePreprocessor(property: string, process: (propValue: any) => any)

Sets a function to use to pre-process a style property value. This is used internally to process color and transform values. You should not use this unless you really know what you are doing and have exhausted other options.

Properties

absoluteFill

A very common pattern is to create overlays with position absolute and zero positioning (position: 'absolute', left: 0, right: 0, top: 0, bottom: 0), so absoluteFill can be used for convenience and to reduce duplication of these repeated styles. If you want, absoluteFill can be used to create a customized entry in a StyleSheet, e.g.:

absoluteFillObject

Sometimes you may want absoluteFill but with a couple tweaks - absoluteFillObject can be used to create a customized entry in a StyleSheet, e.g.:

hairlineWidth

This is defined as the width of a thin line on the platform. It can be used as the thickness of a border or division between two elements. Example:

This constant will always be a round number of pixels (so a line defined by it can look crisp) and will try to match the standard width of a thin line on the underlying platform. However, you should not rely on it being a constant size, because on different platforms and screen densities its value may be calculated differently.

A line with hairline width may not be visible if your simulator is downscaled.

absoluteFill vs. absoluteFillObject

Currently, there is no difference between using absoluteFill vs. absoluteFillObject.

Edit this page
Last updated on
- + diff --git a/docs/switch.html b/docs/switch.html index a5cbea971f8..7f14ccf1b80 100644 --- a/docs/switch.html +++ b/docs/switch.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Switch

Renders a boolean input.

This is a controlled component that requires an onValueChange callback that updates the value prop in order for the component to reflect user actions. If the value prop is not updated, the component will continue to render the supplied value prop instead of the expected result of any user actions.

Example

Reference

Props

Inherits View Props.

disabled

If true the user won't be able to toggle the switch. Default value is false.

TypeRequired
boolNo

ios_backgroundColor

On iOS, custom color for the background. This background color can be seen either when the switch value is false or when the switch is disabled (and the switch is translucent).

TypeRequired
colorNo

onChange

Invoked when the user tries to change the value of the switch. Receives the change event as an argument. If you want to only receive the new value, use onValueChange instead.

TypeRequired
functionNo

onValueChange

Invoked when the user tries to change the value of the switch. Receives the new value as an argument. If you want to instead receive an event, use onChange.

TypeRequired
functionNo

thumbColor

Color of the foreground switch grip. If this is set on iOS, the switch grip will lose its drop shadow.

TypeRequired
colorNo

trackColor

Custom colors for the switch track.

iOS: When the switch value is false, the track shrinks into the border. If you want to change the color of the background exposed by the shrunken track, use ios_backgroundColor.

TypeRequired
object: {false: color, true: color}No

value

The value of the switch. If true the switch will be turned on. Default value is false.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/switch/index.html b/docs/switch/index.html index a5cbea971f8..7f14ccf1b80 100644 --- a/docs/switch/index.html +++ b/docs/switch/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Switch

Renders a boolean input.

This is a controlled component that requires an onValueChange callback that updates the value prop in order for the component to reflect user actions. If the value prop is not updated, the component will continue to render the supplied value prop instead of the expected result of any user actions.

Example

Reference

Props

Inherits View Props.

disabled

If true the user won't be able to toggle the switch. Default value is false.

TypeRequired
boolNo

ios_backgroundColor

On iOS, custom color for the background. This background color can be seen either when the switch value is false or when the switch is disabled (and the switch is translucent).

TypeRequired
colorNo

onChange

Invoked when the user tries to change the value of the switch. Receives the change event as an argument. If you want to only receive the new value, use onValueChange instead.

TypeRequired
functionNo

onValueChange

Invoked when the user tries to change the value of the switch. Receives the new value as an argument. If you want to instead receive an event, use onChange.

TypeRequired
functionNo

thumbColor

Color of the foreground switch grip. If this is set on iOS, the switch grip will lose its drop shadow.

TypeRequired
colorNo

trackColor

Custom colors for the switch track.

iOS: When the switch value is false, the track shrinks into the border. If you want to change the color of the background exposed by the shrunken track, use ios_backgroundColor.

TypeRequired
object: {false: color, true: color}No

value

The value of the switch. If true the switch will be turned on. Default value is false.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/symbolication.html b/docs/symbolication.html index 024366ec371..bf90321525d 100644 --- a/docs/symbolication.html +++ b/docs/symbolication.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Symbolicating a stack trace

If a React Native app throws an unhandled exception in a release build, the output may be obfuscated and hard to read:

07-15 10:58:25.820 18979 18998 E AndroidRuntime: FATAL EXCEPTION: mqt_native_modules
07-15 10:58:25.820 18979 18998 E AndroidRuntime: Process: com.awesomeproject, PID: 18979 07-15 10:58:25.820 18979 18998 E AndroidRuntime: com.facebook.react.common.JavascriptException: Failed, js engine: hermes, stack:
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132161
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132084
07-15 10:58:25.820 18979 18998 E AndroidRuntime: f@1:131854
07-15 10:58:25.820 18979 18998 E AndroidRuntime: anonymous@1:131119

The sections like p@1:132161 are minified function names and bytecode offsets. To debug the problem, you would instead want to translate it into file, line and function name: AwesomeProject/App.js:54:initializeMap. This is known as symbolication. You can symbolicate minified function names and bytecode like the above by passing metro-symbolicate a generated source map and the stack trace.

The metro-symbolicate package is installed by default in the React Native template project from setting up your development environment.

From a file containing the stacktrace:

npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map < stacktrace.txt

From adb logcatdirectly:

adb logcat -d | npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map

This will turn each minified function name and offset like p@1:132161 into the actual file- and function name AwesomeProject/App.js:54:initializeMap.

Notes on Sourcemaps

  • Multiple source maps may be generated by the build process. Make sure to used the one in the location shown in the examples.
  • Make sure that the source map you use corresponds to the exact commit of the crashing app. Small changes in source code can cause large differences in offsets.
  • If metro-symbolicate exits immediately with success, make sure the input comes from a pipe or redirection and not from a terminal.
Edit this page
Last updated on
- + diff --git a/docs/symbolication/index.html b/docs/symbolication/index.html index 024366ec371..bf90321525d 100644 --- a/docs/symbolication/index.html +++ b/docs/symbolication/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Symbolicating a stack trace

If a React Native app throws an unhandled exception in a release build, the output may be obfuscated and hard to read:

07-15 10:58:25.820 18979 18998 E AndroidRuntime: FATAL EXCEPTION: mqt_native_modules
07-15 10:58:25.820 18979 18998 E AndroidRuntime: Process: com.awesomeproject, PID: 18979 07-15 10:58:25.820 18979 18998 E AndroidRuntime: com.facebook.react.common.JavascriptException: Failed, js engine: hermes, stack:
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132161
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132084
07-15 10:58:25.820 18979 18998 E AndroidRuntime: f@1:131854
07-15 10:58:25.820 18979 18998 E AndroidRuntime: anonymous@1:131119

The sections like p@1:132161 are minified function names and bytecode offsets. To debug the problem, you would instead want to translate it into file, line and function name: AwesomeProject/App.js:54:initializeMap. This is known as symbolication. You can symbolicate minified function names and bytecode like the above by passing metro-symbolicate a generated source map and the stack trace.

The metro-symbolicate package is installed by default in the React Native template project from setting up your development environment.

From a file containing the stacktrace:

npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map < stacktrace.txt

From adb logcatdirectly:

adb logcat -d | npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map

This will turn each minified function name and offset like p@1:132161 into the actual file- and function name AwesomeProject/App.js:54:initializeMap.

Notes on Sourcemaps

  • Multiple source maps may be generated by the build process. Make sure to used the one in the location shown in the examples.
  • Make sure that the source map you use corresponds to the exact commit of the crashing app. Small changes in source code can cause large differences in offsets.
  • If metro-symbolicate exits immediately with success, make sure the input comes from a pipe or redirection and not from a terminal.
Edit this page
Last updated on
- + diff --git a/docs/systrace.html b/docs/systrace.html index 834dc875786..fbc831c2b3c 100644 --- a/docs/systrace.html +++ b/docs/systrace.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Systrace

Systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.

Example

Systrace allows you to mark JavaScript (JS) events with a tag and an integer value. Capture the non-Timed JS events in EasyProfiler.

Reference

Methods

installReactHook()

static installReactHook(useFiber)

setEnabled()

static setEnabled(enabled)

isEnabled()

static isEnabled()

beginEvent()

static beginEvent(profileName?, args?)

beginEvent/endEvent for starting and then ending a profile within the same call stack frame.

endEvent()

static endEvent()

beginAsyncEvent()

static beginAsyncEvent(profileName?)

beginAsyncEvent/endAsyncEvent for starting and then ending a profile where the end can either occur on another thread or out of the current stack frame, eg await the returned cookie variable should be used as input into the endAsyncEvent call to end the profile.

endAsyncEvent()

static endAsyncEvent(profileName?, cookie?)

counterEvent()

static counterEvent(profileName?, value?)

Register the value to the profileName on the systrace timeline.

Edit this page
Last updated on
- + diff --git a/docs/systrace/index.html b/docs/systrace/index.html index 834dc875786..fbc831c2b3c 100644 --- a/docs/systrace/index.html +++ b/docs/systrace/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Systrace

Systrace is a standard Android marker-based profiling tool (and is installed when you install the Android platform-tools package). Profiled code blocks are surrounded by start/end markers which are then visualized in a colorful chart format. Both the Android SDK and React Native framework provide standard markers that you can visualize.

Example

Systrace allows you to mark JavaScript (JS) events with a tag and an integer value. Capture the non-Timed JS events in EasyProfiler.

Reference

Methods

installReactHook()

static installReactHook(useFiber)

setEnabled()

static setEnabled(enabled)

isEnabled()

static isEnabled()

beginEvent()

static beginEvent(profileName?, args?)

beginEvent/endEvent for starting and then ending a profile within the same call stack frame.

endEvent()

static endEvent()

beginAsyncEvent()

static beginAsyncEvent(profileName?)

beginAsyncEvent/endAsyncEvent for starting and then ending a profile where the end can either occur on another thread or out of the current stack frame, eg await the returned cookie variable should be used as input into the endAsyncEvent call to end the profile.

endAsyncEvent()

static endAsyncEvent(profileName?, cookie?)

counterEvent()

static counterEvent(profileName?, value?)

Register the value to the profileName on the systrace timeline.

Edit this page
Last updated on
- + diff --git a/docs/tabbarios-item.html b/docs/tabbarios-item.html index 4a31857f375..212eef470e9 100644 --- a/docs/tabbarios-item.html +++ b/docs/tabbarios-item.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

TabBarIOS.Item

Props

Reference

Props

selected

It specifies whether the children are visible or not. If you see a blank content, you probably forgot to add a selected one.

TypeRequired
boolNo

badge

Little red bubble that sits at the top right of the icon.

TypeRequired
string, ,numberNo

icon

A custom icon for the tab. It is ignored when a system icon is defined.

TypeRequired
Image.propTypes.sourceNo

onPress

Callback when this tab is being selected, you should change the state of your component to set selected={true}.

TypeRequired
functionNo

renderAsOriginal

If set to true it renders the image as original, it defaults to being displayed as a template

TypeRequired
boolNo

badgeColor

Background color for the badge. Available since iOS 10.

TypeRequired
colorNo

selectedIcon

A custom icon when the tab is selected. It is ignored when a system icon is defined. If left empty, the icon will be tinted in blue.

TypeRequired
Image.propTypes.sourceNo

style

React style object.

TypeRequired
View.styleNo

systemIcon

Items comes with a few predefined system icons. Note that if you are using them, the title and selectedIcon will be overridden with the system ones.

TypeRequired
enum('bookmarks', 'contacts', 'downloads', 'favorites', 'featured', 'history', 'more', 'most-recent', 'most-viewed', 'recents', 'search', 'top-rated')No

title

Text that appears under the icon. It is ignored when a system icon is defined.

TypeRequired
stringNo

isTVSelectable

(Apple TV only)* When set to true, this view will be focusable and navigable using the Apple TV remote.

TypeRequiredPlatform
boolNoiOS
Edit this page
Last updated on
- + diff --git a/docs/tabbarios-item/index.html b/docs/tabbarios-item/index.html index 4a31857f375..212eef470e9 100644 --- a/docs/tabbarios-item/index.html +++ b/docs/tabbarios-item/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

TabBarIOS.Item

Props

Reference

Props

selected

It specifies whether the children are visible or not. If you see a blank content, you probably forgot to add a selected one.

TypeRequired
boolNo

badge

Little red bubble that sits at the top right of the icon.

TypeRequired
string, ,numberNo

icon

A custom icon for the tab. It is ignored when a system icon is defined.

TypeRequired
Image.propTypes.sourceNo

onPress

Callback when this tab is being selected, you should change the state of your component to set selected={true}.

TypeRequired
functionNo

renderAsOriginal

If set to true it renders the image as original, it defaults to being displayed as a template

TypeRequired
boolNo

badgeColor

Background color for the badge. Available since iOS 10.

TypeRequired
colorNo

selectedIcon

A custom icon when the tab is selected. It is ignored when a system icon is defined. If left empty, the icon will be tinted in blue.

TypeRequired
Image.propTypes.sourceNo

style

React style object.

TypeRequired
View.styleNo

systemIcon

Items comes with a few predefined system icons. Note that if you are using them, the title and selectedIcon will be overridden with the system ones.

TypeRequired
enum('bookmarks', 'contacts', 'downloads', 'favorites', 'featured', 'history', 'more', 'most-recent', 'most-viewed', 'recents', 'search', 'top-rated')No

title

Text that appears under the icon. It is ignored when a system icon is defined.

TypeRequired
stringNo

isTVSelectable

(Apple TV only)* When set to true, this view will be focusable and navigable using the Apple TV remote.

TypeRequiredPlatform
boolNoiOS
Edit this page
Last updated on
- + diff --git a/docs/tabbarios.html b/docs/tabbarios.html index 6de67900618..8269eb63342 100644 --- a/docs/tabbarios.html +++ b/docs/tabbarios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

TabBarIOS

Props

Reference

Props

barStyle

The style of the tab bar. Supported values are 'default', 'black'. Use 'black' instead of setting barTintColor to black. This produces a tab bar with the native iOS style with higher translucency.

TypeRequired
enum('default', 'black')No

barTintColor

Background color of the tab bar

TypeRequired
colorNo

itemPositioning

Specifies tab bar item positioning. Available values are:

  • fill - distributes items across the entire width of the tab bar
  • center - centers item in the available tab bar space
  • auto (default) - distributes items dynamically according to the user interface idiom. In a horizontally compact environment (e.g. iPhone 5) this value defaults to fill, in a horizontally regular one (e.g. iPad) it defaults to center.
TypeRequired
enum('fill', 'center', 'auto')No

style

TypeRequired
View.styleNo

tintColor

Color of the currently selected tab icon

TypeRequired
colorNo

translucent

A Boolean value that indicates whether the tab bar is translucent

TypeRequired
boolNo

unselectedItemTintColor

Color of unselected tab icons. Available since iOS 10.

TypeRequired
colorNo

unselectedTintColor

Color of text on unselected tabs

TypeRequired
colorNo
Edit this page
Last updated on
- + diff --git a/docs/tabbarios/index.html b/docs/tabbarios/index.html index 6de67900618..8269eb63342 100644 --- a/docs/tabbarios/index.html +++ b/docs/tabbarios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

TabBarIOS

Props

Reference

Props

barStyle

The style of the tab bar. Supported values are 'default', 'black'. Use 'black' instead of setting barTintColor to black. This produces a tab bar with the native iOS style with higher translucency.

TypeRequired
enum('default', 'black')No

barTintColor

Background color of the tab bar

TypeRequired
colorNo

itemPositioning

Specifies tab bar item positioning. Available values are:

  • fill - distributes items across the entire width of the tab bar
  • center - centers item in the available tab bar space
  • auto (default) - distributes items dynamically according to the user interface idiom. In a horizontally compact environment (e.g. iPhone 5) this value defaults to fill, in a horizontally regular one (e.g. iPad) it defaults to center.
TypeRequired
enum('fill', 'center', 'auto')No

style

TypeRequired
View.styleNo

tintColor

Color of the currently selected tab icon

TypeRequired
colorNo

translucent

A Boolean value that indicates whether the tab bar is translucent

TypeRequired
boolNo

unselectedItemTintColor

Color of unselected tab icons. Available since iOS 10.

TypeRequired
colorNo

unselectedTintColor

Color of text on unselected tabs

TypeRequired
colorNo
Edit this page
Last updated on
- + diff --git a/docs/testing-overview.html b/docs/testing-overview.html index 1cf60ca70c4..784011bbb84 100644 --- a/docs/testing-overview.html +++ b/docs/testing-overview.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
const bananaElements = getAllByText('banana');
expect(bananaElements).toHaveLength(1); // expect 'banana' to be on the list
});

This example is not testing how some state changes when you call a function. It tests what happens when a user changes text in the TextInput and presses the Button!

Testing Rendered Output

Snapshot testing is an advanced kind of testing enabled by Jest. It is a very powerful and low-level tool, so extra attention is advised when using it.

A "component snapshot" is a JSX-like string created by a custom React serializer built into Jest. This serializer lets Jest translate React component trees to string that's human-readable. Put another way: a component snapshot is a textual representation of your component’s render output generated during a test run. It may look like this:

<Text
style={
Object {
"fontSize": 20,
"textAlign": "center",
}
}>
Welcome to React Native!
</Text>

With snapshot testing, you typically first implement your component and then run the snapshot test. The snapshot test then creates a snapshot and saves it to a file in your repo as a reference snapshot. The file is then committed and checked during code review. Any future changes to the component render output will change its snapshot, which will cause the test to fail. You then need to update the stored reference snapshot for the test to pass. That change again needs to be committed and reviewed.

Snapshots have several weak points:

Snapshots themselves do not ensure that your component render logic is correct, they are merely good at guarding against unexpected changes and for checking that the components in the React tree under test receive the expected props (styles and etc.).

We recommend that you only use small snapshots (see no-large-snapshots rule). If you want to test a change between two React component states, use snapshot-diff. When in doubt, prefer explicit expectations as described in the previous paragraph.

End-to-End Tests

In end-to-end (E2E) tests, you verify your app is working as expected on a device (or a simulator / emulator) from the user perspective.

This is done by building your app in the release configuration and running the tests against it. In E2E tests, you no longer think about React components, React Native APIs, Redux stores or any business logic. That is not the purpose of E2E tests and those are not even accessible to you during E2E testing.

Instead, E2E testing libraries allow you to find and control elements in the screen of your app: for example, you can actually tap buttons or insert text into TextInputs the same way a real user would. Then you can make assertions about whether or not a certain element exists in the app’s screen, whether or not it’s visible, what text it contains, and so on.

E2E tests give you the highest possible confidence that part of your app is working. The tradeoffs include:

Try to cover the vital parts of your app with E2E tests: authentication flow, core functionalities, payments, etc. Use faster JS tests for the non-vital parts of your app. The more tests you add, the higher your confidence, but also, the more time you'll spend maintaining and running them. Consider the tradeoffs and decide what's best for you.

There are several E2E testing tools available: in the React Native community, Detox is a popular framework because it’s tailored for React Native apps. Another popular library in the space of iOS and Android apps is Appium.

Summary

We hope you enjoyed reading and learned something from this guide. There are many ways you can test your apps. It may be hard to decide what to use at first. However, we believe it all will make sense once you start adding tests to your awesome React Native app. So what are you waiting for? Get your coverage up!

Links

This guide originally authored and contributed in full by Vojtech Novak.

Edit this page
Last updated on
- + diff --git a/docs/testing-overview/index.html b/docs/testing-overview/index.html index 1cf60ca70c4..784011bbb84 100644 --- a/docs/testing-overview/index.html +++ b/docs/testing-overview/index.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
const bananaElements = getAllByText('banana');
expect(bananaElements).toHaveLength(1); // expect 'banana' to be on the list
});

This example is not testing how some state changes when you call a function. It tests what happens when a user changes text in the TextInput and presses the Button!

Testing Rendered Output

Snapshot testing is an advanced kind of testing enabled by Jest. It is a very powerful and low-level tool, so extra attention is advised when using it.

A "component snapshot" is a JSX-like string created by a custom React serializer built into Jest. This serializer lets Jest translate React component trees to string that's human-readable. Put another way: a component snapshot is a textual representation of your component’s render output generated during a test run. It may look like this:

<Text
style={
Object {
"fontSize": 20,
"textAlign": "center",
}
}>
Welcome to React Native!
</Text>

With snapshot testing, you typically first implement your component and then run the snapshot test. The snapshot test then creates a snapshot and saves it to a file in your repo as a reference snapshot. The file is then committed and checked during code review. Any future changes to the component render output will change its snapshot, which will cause the test to fail. You then need to update the stored reference snapshot for the test to pass. That change again needs to be committed and reviewed.

Snapshots have several weak points:

Snapshots themselves do not ensure that your component render logic is correct, they are merely good at guarding against unexpected changes and for checking that the components in the React tree under test receive the expected props (styles and etc.).

We recommend that you only use small snapshots (see no-large-snapshots rule). If you want to test a change between two React component states, use snapshot-diff. When in doubt, prefer explicit expectations as described in the previous paragraph.

End-to-End Tests

In end-to-end (E2E) tests, you verify your app is working as expected on a device (or a simulator / emulator) from the user perspective.

This is done by building your app in the release configuration and running the tests against it. In E2E tests, you no longer think about React components, React Native APIs, Redux stores or any business logic. That is not the purpose of E2E tests and those are not even accessible to you during E2E testing.

Instead, E2E testing libraries allow you to find and control elements in the screen of your app: for example, you can actually tap buttons or insert text into TextInputs the same way a real user would. Then you can make assertions about whether or not a certain element exists in the app’s screen, whether or not it’s visible, what text it contains, and so on.

E2E tests give you the highest possible confidence that part of your app is working. The tradeoffs include:

Try to cover the vital parts of your app with E2E tests: authentication flow, core functionalities, payments, etc. Use faster JS tests for the non-vital parts of your app. The more tests you add, the higher your confidence, but also, the more time you'll spend maintaining and running them. Consider the tradeoffs and decide what's best for you.

There are several E2E testing tools available: in the React Native community, Detox is a popular framework because it’s tailored for React Native apps. Another popular library in the space of iOS and Android apps is Appium.

Summary

We hope you enjoyed reading and learned something from this guide. There are many ways you can test your apps. It may be hard to decide what to use at first. However, we believe it all will make sense once you start adding tests to your awesome React Native app. So what are you waiting for? Get your coverage up!

Links

This guide originally authored and contributed in full by Vojtech Novak.

Edit this page
Last updated on
- + diff --git a/docs/text-style-props.html b/docs/text-style-props.html index a0a0989f576..2198f4f4c1d 100644 --- a/docs/text-style-props.html +++ b/docs/text-style-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Text Style Props

Example

Reference

Props

textShadowOffset

TypeRequired
object: {width: number,height: number}No

color

TypeRequired
colorNo

fontSize

TypeRequired
numberNo

fontStyle

TypeRequired
enum('normal', 'italic')No

fontWeight

Specifies font weight. The values 'normal' and 'bold' are supported for most fonts. Not all fonts have a variant for each of the numeric values, in that case the closest one is chosen.

TypeRequired
enum('normal', 'bold', '100', '200', '300', '400', '500', '600', '700', '800', '900')No

lineHeight

TypeRequired
numberNo

textAlign

Specifies text alignment. The value 'justify' is only supported on iOS and fallbacks to left on Android.

TypeRequired
enum('auto', 'left', 'right', 'center', 'justify')No

textDecorationLine

TypeRequired
enum('none', 'underline', 'line-through', 'underline line-through')No

textShadowColor

TypeRequired
colorNo

fontFamily

TypeRequired
stringNo

textShadowRadius

TypeRequired
numberNo

includeFontPadding

Set to false to remove extra font padding intended to make space for certain ascenders / descenders. With some fonts, this padding can make text look slightly misaligned when centered vertically. For best results also set textAlignVertical to center. Default is true.

TypeRequiredPlatform
boolNoAndroid

textAlignVertical

TypeRequiredPlatform
enum('auto', 'top', 'bottom', 'center')NoAndroid

fontVariant

TypeRequiredPlatform
array of enum('small-caps', 'oldstyle-nums', 'lining-nums', 'tabular-nums', 'proportional-nums')NoiOS, Android >= 5.0

letterSpacing

TypeRequiredPlatform
numberNoiOS, Android >= 5.0

textDecorationColor

TypeRequiredPlatform
colorNoiOS

textDecorationStyle

TypeRequiredPlatform
enum('solid', 'double', 'dotted', 'dashed')NoiOS

textTransform

TypeRequired
enum('none', 'uppercase', 'lowercase', 'capitalize')No

writingDirection

TypeRequiredPlatform
enum('auto', 'ltr', 'rtl')NoiOS
Edit this page
Last updated on
- + diff --git a/docs/text-style-props/index.html b/docs/text-style-props/index.html index a0a0989f576..2198f4f4c1d 100644 --- a/docs/text-style-props/index.html +++ b/docs/text-style-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Text Style Props

Example

Reference

Props

textShadowOffset

TypeRequired
object: {width: number,height: number}No

color

TypeRequired
colorNo

fontSize

TypeRequired
numberNo

fontStyle

TypeRequired
enum('normal', 'italic')No

fontWeight

Specifies font weight. The values 'normal' and 'bold' are supported for most fonts. Not all fonts have a variant for each of the numeric values, in that case the closest one is chosen.

TypeRequired
enum('normal', 'bold', '100', '200', '300', '400', '500', '600', '700', '800', '900')No

lineHeight

TypeRequired
numberNo

textAlign

Specifies text alignment. The value 'justify' is only supported on iOS and fallbacks to left on Android.

TypeRequired
enum('auto', 'left', 'right', 'center', 'justify')No

textDecorationLine

TypeRequired
enum('none', 'underline', 'line-through', 'underline line-through')No

textShadowColor

TypeRequired
colorNo

fontFamily

TypeRequired
stringNo

textShadowRadius

TypeRequired
numberNo

includeFontPadding

Set to false to remove extra font padding intended to make space for certain ascenders / descenders. With some fonts, this padding can make text look slightly misaligned when centered vertically. For best results also set textAlignVertical to center. Default is true.

TypeRequiredPlatform
boolNoAndroid

textAlignVertical

TypeRequiredPlatform
enum('auto', 'top', 'bottom', 'center')NoAndroid

fontVariant

TypeRequiredPlatform
array of enum('small-caps', 'oldstyle-nums', 'lining-nums', 'tabular-nums', 'proportional-nums')NoiOS, Android >= 5.0

letterSpacing

TypeRequiredPlatform
numberNoiOS, Android >= 5.0

textDecorationColor

TypeRequiredPlatform
colorNoiOS

textDecorationStyle

TypeRequiredPlatform
enum('solid', 'double', 'dotted', 'dashed')NoiOS

textTransform

TypeRequired
enum('none', 'uppercase', 'lowercase', 'capitalize')No

writingDirection

TypeRequiredPlatform
enum('auto', 'ltr', 'rtl')NoiOS
Edit this page
Last updated on
- + diff --git a/docs/text.html b/docs/text.html index 0408382af3d..1d3627c6a99 100644 --- a/docs/text.html +++ b/docs/text.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
// GOOD
<View>
<Text>
Some text
</Text>
</View>

You also lose the ability to set up a default font for an entire subtree. Meanwhile, fontFamily only accepts a single font name, which is different from font-family in CSS. The recommended way to use consistent fonts and sizes across your application is to create a component MyAppText that includes them and use this component across your app. You can also use this component to make more specific components like MyAppHeaderText for other kinds of text.

<View>
<MyAppText>
Text styled with the default font for the entire application
</MyAppText>
<MyAppHeaderText>Text styled as a header</MyAppHeaderText>
</View>

Assuming that MyAppText is a component that only renders out its children into a Text component with styling, then MyAppHeaderText can be defined as follows:

class MyAppHeaderText extends Component {
render() {
return (
<MyAppText>
<Text style={{ fontSize: 20 }}>
{this.props.children}
</Text>
</MyAppText>
);
}
}

Composing MyAppText in this way ensures that we get the styles from a top-level component, but leaves us the ability to add / override them in specific use cases.

React Native still has the concept of style inheritance, but limited to text subtrees. In this case, the second part will be both bold and red.

<Text style={{ fontWeight: 'bold' }}>
I am bold
<Text style={{ color: 'red' }}>and red</Text>
</Text>

We believe that this more constrained way to style text will yield better apps:

Reference

Props

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityRole

Tells the screen reader to treat the currently focused on element as having a specific role.

Possible values for AccessibilityRole is one of:

On iOS, these roles map to corresponding Accessibility Traits. Image button has the same functionality as if the trait was set to both 'image' and 'button'. See the Accessibility guide for more information.

On Android, these roles have similar functionality on TalkBack as adding Accessibility Traits does on Voiceover in iOS

TypeRequired
AccessibilityRoleNo

accessibilityState

Tells the screen reader to treat the currently focused on element as being in a specific state.

You can provide one state, no state, or multiple states. The states must be passed in through an object. Ex: {selected: true, disabled: true}.

Possible values for AccessibilityState are:

TypeRequired
objectNo

accessible

When set to true, indicates that the view is an accessibility element. The default value for a Text element is true.

See the Accessibility guide for more information.

TypeRequired
boolNo

adjustsFontSizeToFit

Specifies whether fonts should be scaled down automatically to fit given style constraints.

TypeRequired
boolNo

allowFontScaling

Specifies whether fonts should scale to respect Text Size accessibility settings. The default is true.

TypeRequired
boolNo

dataDetectorType

Determines the types of data converted to clickable URLs in the text element. By default no data types are detected.

You can provide only one type.

Possible values for dataDetectorType are:

TypeRequiredPlatform
enum('phoneNumber', 'link', 'email', 'none', 'all')NoAndroid

disabled

Specifies the disabled state of the text view for testing purposes

TypeRequiredPlatform
boolNoAndroid

ellipsizeMode

When numberOfLines is set, this prop defines how text will be truncated. numberOfLines must be set in conjunction with this prop.

This can be one of the following values:

The default is tail.

TypeRequired
enum('head', 'middle', 'tail', 'clip')No

maxFontSizeMultiplier

Specifies largest possible scale a font can reach when allowFontScaling is enabled. Possible values:

TypeRequired
numberNo

minimumFontScale

Specifies smallest possible scale a font can reach when adjustsFontSizeToFit is enabled. (values 0.01-1.0).

TypeRequiredPlatform
numberNoiOS

nativeID

Used to locate this view from native code.

TypeRequired
stringNo

numberOfLines

Used to truncate the text with an ellipsis after computing the text layout, including line wrapping, such that the total number of lines does not exceed this number.

This prop is commonly used with ellipsizeMode.

TypeRequired
numberNo

onLayout

Invoked on mount and layout changes with

{nativeEvent: {layout: {x, y, width, height}}}

TypeRequired
functionNo

onLongPress

This function is called on long press.

e.g., onLongPress={this.increaseSize}>

TypeRequired
functionNo

onMoveShouldSetResponder

Does this view want to "claim" touch responsiveness? This is called for every touch move on the View when it is not the responder.

View.props.onMoveShouldSetResponder: (event) => [true | false], where event is a PressEvent.

TypeRequired
functionNo

onPress

This function is called on press. The first function argument is an event in form of PressEvent.

e.g., onPress={() => console.log('1st')}

TypeRequired
functionNo

onResponderGrant

The View is now responding for touch events. This is the time to highlight and show the user what is happening.

View.props.onResponderGrant: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderMove

The user is moving their finger.

View.props.onResponderMove: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderRelease

Fired at the end of the touch.

View.props.onResponderRelease: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderTerminate

The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS)

View.props.onResponderTerminate: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderTerminationRequest

Some other View wants to become responder and is asking this View to release its responder. Returning true allows its release.

View.props.onResponderTerminationRequest: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onStartShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a touch start, it should have this handler which returns true.

View.props.onStartShouldSetResponderCapture: (event) => [true | false], where event is a PressEvent.

TypeRequired
functionNo

onTextLayout

Invoked on Text layout

TypeRequired
function: (event: TextLayoutEvent) => mixedNo

pressRetentionOffset

When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations.

TypeRequired
Rect or numberNo

selectable

Lets the user select text, to use the native copy and paste functionality.

TypeRequired
boolNo

selectionColor

The highlight color of the text.

TypeRequiredPlatform
colorNoAndroid

style

TypeRequired
Text Style Props, View Style PropsNo

suppressHighlighting

When true, no visual change is made when text is pressed down. By default, a gray oval highlights the text on press down.

TypeRequiredPlatform
boolNoiOS

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

textBreakStrategy

Set text break strategy on Android API Level 23+, possible values are simple, highQuality, balanced The default value is highQuality.

TypeRequiredPlatform
enum('simple', 'highQuality', 'balanced')NoAndroid

Known issues

Edit this page
Last updated on
- + diff --git a/docs/text/index.html b/docs/text/index.html index 0408382af3d..1d3627c6a99 100644 --- a/docs/text/index.html +++ b/docs/text/index.html @@ -19,7 +19,7 @@ - + @@ -37,7 +37,7 @@
// GOOD
<View>
<Text>
Some text
</Text>
</View>

You also lose the ability to set up a default font for an entire subtree. Meanwhile, fontFamily only accepts a single font name, which is different from font-family in CSS. The recommended way to use consistent fonts and sizes across your application is to create a component MyAppText that includes them and use this component across your app. You can also use this component to make more specific components like MyAppHeaderText for other kinds of text.

<View>
<MyAppText>
Text styled with the default font for the entire application
</MyAppText>
<MyAppHeaderText>Text styled as a header</MyAppHeaderText>
</View>

Assuming that MyAppText is a component that only renders out its children into a Text component with styling, then MyAppHeaderText can be defined as follows:

class MyAppHeaderText extends Component {
render() {
return (
<MyAppText>
<Text style={{ fontSize: 20 }}>
{this.props.children}
</Text>
</MyAppText>
);
}
}

Composing MyAppText in this way ensures that we get the styles from a top-level component, but leaves us the ability to add / override them in specific use cases.

React Native still has the concept of style inheritance, but limited to text subtrees. In this case, the second part will be both bold and red.

<Text style={{ fontWeight: 'bold' }}>
I am bold
<Text style={{ color: 'red' }}>and red</Text>
</Text>

We believe that this more constrained way to style text will yield better apps:

Reference

Props

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityRole

Tells the screen reader to treat the currently focused on element as having a specific role.

Possible values for AccessibilityRole is one of:

On iOS, these roles map to corresponding Accessibility Traits. Image button has the same functionality as if the trait was set to both 'image' and 'button'. See the Accessibility guide for more information.

On Android, these roles have similar functionality on TalkBack as adding Accessibility Traits does on Voiceover in iOS

TypeRequired
AccessibilityRoleNo

accessibilityState

Tells the screen reader to treat the currently focused on element as being in a specific state.

You can provide one state, no state, or multiple states. The states must be passed in through an object. Ex: {selected: true, disabled: true}.

Possible values for AccessibilityState are:

TypeRequired
objectNo

accessible

When set to true, indicates that the view is an accessibility element. The default value for a Text element is true.

See the Accessibility guide for more information.

TypeRequired
boolNo

adjustsFontSizeToFit

Specifies whether fonts should be scaled down automatically to fit given style constraints.

TypeRequired
boolNo

allowFontScaling

Specifies whether fonts should scale to respect Text Size accessibility settings. The default is true.

TypeRequired
boolNo

dataDetectorType

Determines the types of data converted to clickable URLs in the text element. By default no data types are detected.

You can provide only one type.

Possible values for dataDetectorType are:

TypeRequiredPlatform
enum('phoneNumber', 'link', 'email', 'none', 'all')NoAndroid

disabled

Specifies the disabled state of the text view for testing purposes

TypeRequiredPlatform
boolNoAndroid

ellipsizeMode

When numberOfLines is set, this prop defines how text will be truncated. numberOfLines must be set in conjunction with this prop.

This can be one of the following values:

The default is tail.

TypeRequired
enum('head', 'middle', 'tail', 'clip')No

maxFontSizeMultiplier

Specifies largest possible scale a font can reach when allowFontScaling is enabled. Possible values:

TypeRequired
numberNo

minimumFontScale

Specifies smallest possible scale a font can reach when adjustsFontSizeToFit is enabled. (values 0.01-1.0).

TypeRequiredPlatform
numberNoiOS

nativeID

Used to locate this view from native code.

TypeRequired
stringNo

numberOfLines

Used to truncate the text with an ellipsis after computing the text layout, including line wrapping, such that the total number of lines does not exceed this number.

This prop is commonly used with ellipsizeMode.

TypeRequired
numberNo

onLayout

Invoked on mount and layout changes with

{nativeEvent: {layout: {x, y, width, height}}}

TypeRequired
functionNo

onLongPress

This function is called on long press.

e.g., onLongPress={this.increaseSize}>

TypeRequired
functionNo

onMoveShouldSetResponder

Does this view want to "claim" touch responsiveness? This is called for every touch move on the View when it is not the responder.

View.props.onMoveShouldSetResponder: (event) => [true | false], where event is a PressEvent.

TypeRequired
functionNo

onPress

This function is called on press. The first function argument is an event in form of PressEvent.

e.g., onPress={() => console.log('1st')}

TypeRequired
functionNo

onResponderGrant

The View is now responding for touch events. This is the time to highlight and show the user what is happening.

View.props.onResponderGrant: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderMove

The user is moving their finger.

View.props.onResponderMove: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderRelease

Fired at the end of the touch.

View.props.onResponderRelease: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderTerminate

The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS)

View.props.onResponderTerminate: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderTerminationRequest

Some other View wants to become responder and is asking this View to release its responder. Returning true allows its release.

View.props.onResponderTerminationRequest: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onStartShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a touch start, it should have this handler which returns true.

View.props.onStartShouldSetResponderCapture: (event) => [true | false], where event is a PressEvent.

TypeRequired
functionNo

onTextLayout

Invoked on Text layout

TypeRequired
function: (event: TextLayoutEvent) => mixedNo

pressRetentionOffset

When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations.

TypeRequired
Rect or numberNo

selectable

Lets the user select text, to use the native copy and paste functionality.

TypeRequired
boolNo

selectionColor

The highlight color of the text.

TypeRequiredPlatform
colorNoAndroid

style

TypeRequired
Text Style Props, View Style PropsNo

suppressHighlighting

When true, no visual change is made when text is pressed down. By default, a gray oval highlights the text on press down.

TypeRequiredPlatform
boolNoiOS

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

textBreakStrategy

Set text break strategy on Android API Level 23+, possible values are simple, highQuality, balanced The default value is highQuality.

TypeRequiredPlatform
enum('simple', 'highQuality', 'balanced')NoAndroid

Known issues

Edit this page
Last updated on
- + diff --git a/docs/textinput.html b/docs/textinput.html index f4fa07df2cf..f28b172633b 100644 --- a/docs/textinput.html +++ b/docs/textinput.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

TextInput

A foundational component for inputting text into the app via a keyboard. Props provide configurability for several features, such as auto-correction, auto-capitalization, placeholder text, and different keyboard types, such as a numeric keypad.

The most basic use case is to plop down a TextInput and subscribe to the onChangeText events to read the user input. There are also other events, such as onSubmitEditing and onFocus that can be subscribed to. A minimal example:

Two methods exposed via the native element are .focus() and .blur() that will focus or blur the TextInput programmatically.

Note that some props are only available with multiline={true/false}. Additionally, border styles that apply to only one side of the element (e.g., borderBottomColor, borderLeftWidth, etc.) will not be applied if multiline=true. To achieve the same effect, you can wrap your TextInput in a View:

TextInput has by default a border at the bottom of its view. This border has its padding set by the background image provided by the system, and it cannot be changed. Solutions to avoid this are to either not set height explicitly, in which case the system will take care of displaying the border in the correct position, or to not display the border by setting underlineColorAndroid to transparent.

Note that on Android performing text selection in an input can change the app's activity windowSoftInputMode param to adjustResize. This may cause issues with components that have position: 'absolute' while the keyboard is active. To avoid this behavior either specify windowSoftInputMode in AndroidManifest.xml ( https://developer.android.com/guide/topics/manifest/activity-element.html ) or control this param programmatically with native code.

Reference

Props

Inherits View Props.

allowFontScaling

Specifies whether fonts should scale to respect Text Size accessibility settings. The default is true.

TypeRequired
boolNo

autoCapitalize

Can tell TextInput to automatically capitalize certain characters. This property is not supported by some keyboard types such as name-phone-pad.

  • characters: all characters.
  • words: first letter of each word.
  • sentences: first letter of each sentence (default).
  • none: don't auto capitalize anything.
TypeRequired
enum('none', 'sentences', 'words', 'characters')No

autoCompleteType

Specifies autocomplete hints for the system, so it can provide autofill. On Android, the system will always attempt to offer autofill by using heuristics to identify the type of content. To disable autocomplete, set autoCompleteType to off.

Possible values for autoCompleteType are:

  • off
  • username
  • password
  • email
  • name
  • tel
  • street-address
  • postal-code
  • cc-number
  • cc-csc
  • cc-exp
  • cc-exp-month
  • cc-exp-year
TypeRequiredPlatform
enum('off', 'username', 'password', 'email', 'name', 'tel', 'street-address', 'postal-code', 'cc-number', 'cc-csc', 'cc-exp', 'cc-exp-month', 'cc-exp-year')NoAndroid

autoCorrect

If false, disables auto-correct. The default value is true.

TypeRequired
boolNo

autoFocus

If true, focuses the input on componentDidMount. The default value is false.

TypeRequired
boolNo

blurOnSubmit

If true, the text field will blur when submitted. The default value is true for single-line fields and false for multiline fields. Note that for multiline fields, setting blurOnSubmit to true means that pressing return will blur the field and trigger the onSubmitEditing event instead of inserting a newline into the field.

TypeRequired
boolNo

caretHidden

If true, caret is hidden. The default value is false.

TypeRequired
boolNo

clearButtonMode

When the clear button should appear on the right side of the text view. This property is supported only for single-line TextInput component. The default value is never.

TypeRequiredPlatform
enum('never', 'while-editing', 'unless-editing', 'always')NoiOS

clearTextOnFocus

If true, clears the text field automatically when editing begins.

TypeRequiredPlatform
boolNoiOS

contextMenuHidden

If true, context menu is hidden. The default value is false.

TypeRequired
boolNo

dataDetectorTypes

Determines the types of data converted to clickable URLs in the text input. Only valid if multiline={true} and editable={false}. By default no data types are detected.

You can provide one type or an array of many types.

Possible values for dataDetectorTypes are:

  • 'phoneNumber'
  • 'link'
  • 'address'
  • 'calendarEvent'
  • 'none'
  • 'all'
TypeRequiredPlatform
enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all'), ,array of enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all')NoiOS

defaultValue

Provides an initial value that will change when the user starts typing. Useful for use-cases where you do not want to deal with listening to events and updating the value prop to keep the controlled state in sync.

TypeRequired
stringNo

disableFullscreenUI

When false, if there is a small amount of space available around a text input (e.g. landscape orientation on a phone), the OS may choose to have the user edit the text inside of a full screen text input mode. When true, this feature is disabled and users will always edit the text directly inside of the text input. Defaults to false.

TypeRequiredPlatform
boolNoAndroid

editable

If false, text is not editable. The default value is true.

TypeRequired
boolNo

enablesReturnKeyAutomatically

If true, the keyboard disables the return key when there is no text and automatically enables it when there is text. The default value is false.

TypeRequiredPlatform
boolNoiOS

importantForAutofill

Tells the operating system whether the individual fields in your app should be included in a view structure for autofill purposes on Android API Level 26+. Possible values are auto, no, noExcludeDescendants, yes, and yesExcludeDescendants. The default value is auto.

  • auto: Let the Android System use its heuristics to determine if the view is important for autofill.
  • no: This view isn't important for autofill.
  • noExcludeDescendants: This view and its children aren't important for autofill.
  • yes: This view is important for autofill.
  • yesExcludeDescendants: This view is important for autofill, but its children aren't important for autofill.
TypeRequiredPlatform
enum('auto', 'no', 'noExcludeDescendants', 'yes', 'yesExcludeDescendants')NoAndroid

inlineImageLeft

If defined, the provided image resource will be rendered on the left. The image resource must be inside /android/app/src/main/res/drawable and referenced like

<TextInput
inlineImageLeft='search_icon'
/>
TypeRequiredPlatform
stringNoAndroid

inlineImagePadding

Padding between the inline image, if any, and the text input itself.

TypeRequiredPlatform
numberNoAndroid

inputAccessoryViewID

An optional identifier which links a custom InputAccessoryView to this text input. The InputAccessoryView is rendered above the keyboard when this text input is focused.

TypeRequiredPlatform
stringNoiOS

keyboardAppearance

Determines the color of the keyboard.

TypeRequiredPlatform
enum('default', 'light', 'dark')NoiOS

keyboardType

Determines which keyboard to open, e.g.numeric.

See screenshots of all the types here.

The following values work across platforms:

  • default
  • number-pad
  • decimal-pad
  • numeric
  • email-address
  • phone-pad

iOS Only

The following values work on iOS only:

  • ascii-capable
  • numbers-and-punctuation
  • url
  • name-phone-pad
  • twitter
  • web-search

Android Only

The following values work on Android only:

  • visible-password
TypeRequired
enum('default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter', 'web-search', 'visible-password')No

maxFontSizeMultiplier

Specifies largest possible scale a font can reach when allowFontScaling is enabled. Possible values:

  • null/undefined (default): inherit from the parent node or the global default (0)
  • 0: no max, ignore parent/global default
  • >= 1: sets the maxFontSizeMultiplier of this node to this value
TypeRequired
numberNo

maxLength

Limits the maximum number of characters that can be entered. Use this instead of implementing the logic in JS to avoid flicker.

TypeRequired
numberNo

multiline

If true, the text input can be multiple lines. The default value is false. It is important to note that this aligns the text to the top on iOS, and centers it on Android. Use with textAlignVertical set to top for the same behavior in both platforms.

TypeRequired
boolNo

numberOfLines

Sets the number of lines for a TextInput. Use it with multiline set to true to be able to fill the lines.

TypeRequiredPlatform
numberNoAndroid

onBlur

Callback that is called when the text input is blurred.

TypeRequired
functionNo

onChange

Callback that is called when the text input's text changes. This will be called with { nativeEvent: { eventCount, target, text} }

TypeRequired
functionNo

onChangeText

Callback that is called when the text input's text changes. Changed text is passed as a single string argument to the callback handler.

TypeRequired
functionNo

onContentSizeChange

Callback that is called when the text input's content size changes. This will be called with { nativeEvent: { contentSize: { width, height } } }.

Only called for multiline text inputs.

TypeRequired
functionNo

onEndEditing

Callback that is called when text input ends.

TypeRequired
functionNo

onFocus

Callback that is called when the text input is focused. This is called with { nativeEvent: { target } }.

TypeRequired
functionNo

onKeyPress

Callback that is called when a key is pressed. This will be called with { nativeEvent: { key: keyValue } } where keyValue is 'Enter' or 'Backspace' for respective keys and the typed-in character otherwise including ' ' for space. Fires before onChange callbacks. Note: on Android only the inputs from soft keyboard are handled, not the hardware keyboard inputs.

TypeRequired
functionNo

onLayout

Invoked on mount and layout changes with { nativeEvent: {layout: {x, y, width, height}, target } }.

TypeRequired
functionNo

onScroll

Invoked on content scroll with { nativeEvent: { contentOffset: { x, y } } }. May also contain other properties from ScrollEvent but on Android contentSize is not provided for performance reasons.

TypeRequired
functionNo

onSelectionChange

Callback that is called when the text input selection is changed. This will be called with { nativeEvent: { selection: { start, end } } }. This prop requires multiline={true} to be set.

TypeRequired
functionNo

onSubmitEditing

Callback that is called when the text input's submit button is pressed with the argument {nativeEvent: {text, eventCount, target}}.

TypeRequired
functionNo

Note that on iOS this method isn't called when using keyboardType="phone-pad".

placeholder

The string that will be rendered before text input has been entered.

TypeRequired
stringNo

placeholderTextColor

The text color of the placeholder string.

TypeRequired
colorNo

returnKeyLabel

Sets the return key to the label. Use it instead of returnKeyType.

TypeRequiredPlatform
stringNoAndroid

returnKeyType

Determines how the return key should look. On Android you can also use returnKeyLabel.

Cross platform

The following values work across platforms:

  • done
  • go
  • next
  • search
  • send

Android Only

The following values work on Android only:

  • none
  • previous

iOS Only

The following values work on iOS only:

  • default
  • emergency-call
  • google
  • join
  • route
  • yahoo
TypeRequired
enum('done', 'go', 'next', 'search', 'send', 'none', 'previous', 'default', 'emergency-call', 'google', 'join', 'route', 'yahoo')No

rejectResponderTermination

iOS Only

If true, allows TextInput to pass touch events to the parent component. This allows components such as SwipeableListView to be swipeable from the TextInput on iOS, as is the case on Android by default. If false, TextInput always asks to handle the input (except when disabled). The default value is true.

TypeRequiredPlatform
boolNoiOS

scrollEnabled

If false, scrolling of the text view will be disabled. The default value is true. Only works with multiline={true}.

TypeRequiredPlatform
boolNoiOS

secureTextEntry

If true, the text input obscures the text entered so that sensitive text like passwords stay secure. The default value is false. Does not work with multiline={true}.

TypeRequired
boolNo

selection

The start and end of the text input's selection. Set start and end to the same value to position the cursor.

TypeRequired
object: {start: number,end: number}No

selectionColor

The highlight and cursor color of the text input.

TypeRequired
colorNo

selectTextOnFocus

If true, all text will automatically be selected on focus.

TypeRequired
boolNo

showSoftInputOnFocus

When false, it will prevent the soft keyboard from showing when the field is focused. The default value is true.

TypeRequiredPlatform
boolNoAndroid

spellCheck

If false, disables spell-check style (i.e. red underlines). The default value is inherited from autoCorrect.

TypeRequiredPlatform
boolNoiOS

textAlign

Align the input text to the left, center, or right sides of the input field.

Possible values for textAlign are:

  • left
  • center
  • right
TypeRequired
enum('left', 'center', 'right')No

textContentType

Give the keyboard and the system information about the expected semantic meaning for the content that users enter.

For iOS 11+ you can set textContentType to username or password to enable autofill of login details from the device keychain.

For iOS 12+ newPassword can be used to indicate a new password input the user may want to save in the keychain, and oneTimeCode can be used to indicate that a field can be autofilled by a code arriving in an SMS.

To disable autofill, set textContentType to none.

Possible values for textContentType are:

  • none
  • URL
  • addressCity
  • addressCityAndState
  • addressState
  • countryName
  • creditCardNumber
  • emailAddress
  • familyName
  • fullStreetAddress
  • givenName
  • jobTitle
  • location
  • middleName
  • name
  • namePrefix
  • nameSuffix
  • nickname
  • organizationName
  • postalCode
  • streetAddressLine1
  • streetAddressLine2
  • sublocality
  • telephoneNumber
  • username
  • password
  • newPassword
  • oneTimeCode
TypeRequiredPlatform
enum('none', 'URL', 'addressCity', 'addressCityAndState', 'addressState', 'countryName', 'creditCardNumber', 'emailAddress', 'familyName', 'fullStreetAddress', 'givenName', 'jobTitle', 'location', 'middleName', 'name', 'namePrefix', 'nameSuffix', 'nickname', 'organizationName', 'postalCode', 'streetAddressLine1', 'streetAddressLine2', 'sublocality', 'telephoneNumber', 'username', 'password')NoiOS

passwordRules

When using textContentType as newPassword on iOS we can let the OS know the minimum requirements of the password so that it can generate one that will satisfy them. In order to create a valid string for PasswordRules take a look to the Apple Docs.

TypeRequiredPlatform
stringNoiOS

style

Note that not all Text styles are supported, an incomplete list of what is not supported includes:

  • borderLeftWidth
  • borderTopWidth
  • borderRightWidth
  • borderBottomWidth
  • borderTopLeftRadius
  • borderTopRightRadius
  • borderBottomRightRadius
  • borderBottomLeftRadius

see Issue#7070 for more detail.

Styles

TypeRequired
TextNo

textBreakStrategy

Set text break strategy on Android API Level 23+, possible values are simple, highQuality, balanced The default value is simple.

TypeRequiredPlatform
enum('simple', 'highQuality', 'balanced')NoAndroid

underlineColorAndroid

The color of the TextInput underline.

TypeRequiredPlatform
colorNoAndroid

value

The value to show for the text input. TextInput is a controlled component, which means the native value will be forced to match this value prop if provided. For most uses, this works great, but in some cases this may cause flickering - one common cause is preventing edits by keeping value the same. In addition to setting the same value, either set editable={false}, or set/update maxLength to prevent unwanted edits without flicker.

TypeRequired
stringNo

Methods

.focus()

focus();

Makes the native input request focus.

.blur()

blur();

Makes the native input lose focus.

clear()

clear();

Removes all text from the TextInput.

isFocused()

isFocused();

Returns true if the input is currently focused; false otherwise.

Known issues

  • react-native#19096: Doesn't support Android's onKeyPreIme.
  • react-native#19366: Calling .focus() after closing Android's keyboard via back button doesn't bring keyboard up again.
  • react-native#26799: Doesn't support Android's secureTextEntry when keyboardType="email-address" or keyboardType="phone-pad".
Edit this page
Last updated on
- + diff --git a/docs/textinput/index.html b/docs/textinput/index.html index f4fa07df2cf..f28b172633b 100644 --- a/docs/textinput/index.html +++ b/docs/textinput/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

TextInput

A foundational component for inputting text into the app via a keyboard. Props provide configurability for several features, such as auto-correction, auto-capitalization, placeholder text, and different keyboard types, such as a numeric keypad.

The most basic use case is to plop down a TextInput and subscribe to the onChangeText events to read the user input. There are also other events, such as onSubmitEditing and onFocus that can be subscribed to. A minimal example:

Two methods exposed via the native element are .focus() and .blur() that will focus or blur the TextInput programmatically.

Note that some props are only available with multiline={true/false}. Additionally, border styles that apply to only one side of the element (e.g., borderBottomColor, borderLeftWidth, etc.) will not be applied if multiline=true. To achieve the same effect, you can wrap your TextInput in a View:

TextInput has by default a border at the bottom of its view. This border has its padding set by the background image provided by the system, and it cannot be changed. Solutions to avoid this are to either not set height explicitly, in which case the system will take care of displaying the border in the correct position, or to not display the border by setting underlineColorAndroid to transparent.

Note that on Android performing text selection in an input can change the app's activity windowSoftInputMode param to adjustResize. This may cause issues with components that have position: 'absolute' while the keyboard is active. To avoid this behavior either specify windowSoftInputMode in AndroidManifest.xml ( https://developer.android.com/guide/topics/manifest/activity-element.html ) or control this param programmatically with native code.

Reference

Props

Inherits View Props.

allowFontScaling

Specifies whether fonts should scale to respect Text Size accessibility settings. The default is true.

TypeRequired
boolNo

autoCapitalize

Can tell TextInput to automatically capitalize certain characters. This property is not supported by some keyboard types such as name-phone-pad.

  • characters: all characters.
  • words: first letter of each word.
  • sentences: first letter of each sentence (default).
  • none: don't auto capitalize anything.
TypeRequired
enum('none', 'sentences', 'words', 'characters')No

autoCompleteType

Specifies autocomplete hints for the system, so it can provide autofill. On Android, the system will always attempt to offer autofill by using heuristics to identify the type of content. To disable autocomplete, set autoCompleteType to off.

Possible values for autoCompleteType are:

  • off
  • username
  • password
  • email
  • name
  • tel
  • street-address
  • postal-code
  • cc-number
  • cc-csc
  • cc-exp
  • cc-exp-month
  • cc-exp-year
TypeRequiredPlatform
enum('off', 'username', 'password', 'email', 'name', 'tel', 'street-address', 'postal-code', 'cc-number', 'cc-csc', 'cc-exp', 'cc-exp-month', 'cc-exp-year')NoAndroid

autoCorrect

If false, disables auto-correct. The default value is true.

TypeRequired
boolNo

autoFocus

If true, focuses the input on componentDidMount. The default value is false.

TypeRequired
boolNo

blurOnSubmit

If true, the text field will blur when submitted. The default value is true for single-line fields and false for multiline fields. Note that for multiline fields, setting blurOnSubmit to true means that pressing return will blur the field and trigger the onSubmitEditing event instead of inserting a newline into the field.

TypeRequired
boolNo

caretHidden

If true, caret is hidden. The default value is false.

TypeRequired
boolNo

clearButtonMode

When the clear button should appear on the right side of the text view. This property is supported only for single-line TextInput component. The default value is never.

TypeRequiredPlatform
enum('never', 'while-editing', 'unless-editing', 'always')NoiOS

clearTextOnFocus

If true, clears the text field automatically when editing begins.

TypeRequiredPlatform
boolNoiOS

contextMenuHidden

If true, context menu is hidden. The default value is false.

TypeRequired
boolNo

dataDetectorTypes

Determines the types of data converted to clickable URLs in the text input. Only valid if multiline={true} and editable={false}. By default no data types are detected.

You can provide one type or an array of many types.

Possible values for dataDetectorTypes are:

  • 'phoneNumber'
  • 'link'
  • 'address'
  • 'calendarEvent'
  • 'none'
  • 'all'
TypeRequiredPlatform
enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all'), ,array of enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all')NoiOS

defaultValue

Provides an initial value that will change when the user starts typing. Useful for use-cases where you do not want to deal with listening to events and updating the value prop to keep the controlled state in sync.

TypeRequired
stringNo

disableFullscreenUI

When false, if there is a small amount of space available around a text input (e.g. landscape orientation on a phone), the OS may choose to have the user edit the text inside of a full screen text input mode. When true, this feature is disabled and users will always edit the text directly inside of the text input. Defaults to false.

TypeRequiredPlatform
boolNoAndroid

editable

If false, text is not editable. The default value is true.

TypeRequired
boolNo

enablesReturnKeyAutomatically

If true, the keyboard disables the return key when there is no text and automatically enables it when there is text. The default value is false.

TypeRequiredPlatform
boolNoiOS

importantForAutofill

Tells the operating system whether the individual fields in your app should be included in a view structure for autofill purposes on Android API Level 26+. Possible values are auto, no, noExcludeDescendants, yes, and yesExcludeDescendants. The default value is auto.

  • auto: Let the Android System use its heuristics to determine if the view is important for autofill.
  • no: This view isn't important for autofill.
  • noExcludeDescendants: This view and its children aren't important for autofill.
  • yes: This view is important for autofill.
  • yesExcludeDescendants: This view is important for autofill, but its children aren't important for autofill.
TypeRequiredPlatform
enum('auto', 'no', 'noExcludeDescendants', 'yes', 'yesExcludeDescendants')NoAndroid

inlineImageLeft

If defined, the provided image resource will be rendered on the left. The image resource must be inside /android/app/src/main/res/drawable and referenced like

<TextInput
inlineImageLeft='search_icon'
/>
TypeRequiredPlatform
stringNoAndroid

inlineImagePadding

Padding between the inline image, if any, and the text input itself.

TypeRequiredPlatform
numberNoAndroid

inputAccessoryViewID

An optional identifier which links a custom InputAccessoryView to this text input. The InputAccessoryView is rendered above the keyboard when this text input is focused.

TypeRequiredPlatform
stringNoiOS

keyboardAppearance

Determines the color of the keyboard.

TypeRequiredPlatform
enum('default', 'light', 'dark')NoiOS

keyboardType

Determines which keyboard to open, e.g.numeric.

See screenshots of all the types here.

The following values work across platforms:

  • default
  • number-pad
  • decimal-pad
  • numeric
  • email-address
  • phone-pad

iOS Only

The following values work on iOS only:

  • ascii-capable
  • numbers-and-punctuation
  • url
  • name-phone-pad
  • twitter
  • web-search

Android Only

The following values work on Android only:

  • visible-password
TypeRequired
enum('default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter', 'web-search', 'visible-password')No

maxFontSizeMultiplier

Specifies largest possible scale a font can reach when allowFontScaling is enabled. Possible values:

  • null/undefined (default): inherit from the parent node or the global default (0)
  • 0: no max, ignore parent/global default
  • >= 1: sets the maxFontSizeMultiplier of this node to this value
TypeRequired
numberNo

maxLength

Limits the maximum number of characters that can be entered. Use this instead of implementing the logic in JS to avoid flicker.

TypeRequired
numberNo

multiline

If true, the text input can be multiple lines. The default value is false. It is important to note that this aligns the text to the top on iOS, and centers it on Android. Use with textAlignVertical set to top for the same behavior in both platforms.

TypeRequired
boolNo

numberOfLines

Sets the number of lines for a TextInput. Use it with multiline set to true to be able to fill the lines.

TypeRequiredPlatform
numberNoAndroid

onBlur

Callback that is called when the text input is blurred.

TypeRequired
functionNo

onChange

Callback that is called when the text input's text changes. This will be called with { nativeEvent: { eventCount, target, text} }

TypeRequired
functionNo

onChangeText

Callback that is called when the text input's text changes. Changed text is passed as a single string argument to the callback handler.

TypeRequired
functionNo

onContentSizeChange

Callback that is called when the text input's content size changes. This will be called with { nativeEvent: { contentSize: { width, height } } }.

Only called for multiline text inputs.

TypeRequired
functionNo

onEndEditing

Callback that is called when text input ends.

TypeRequired
functionNo

onFocus

Callback that is called when the text input is focused. This is called with { nativeEvent: { target } }.

TypeRequired
functionNo

onKeyPress

Callback that is called when a key is pressed. This will be called with { nativeEvent: { key: keyValue } } where keyValue is 'Enter' or 'Backspace' for respective keys and the typed-in character otherwise including ' ' for space. Fires before onChange callbacks. Note: on Android only the inputs from soft keyboard are handled, not the hardware keyboard inputs.

TypeRequired
functionNo

onLayout

Invoked on mount and layout changes with { nativeEvent: {layout: {x, y, width, height}, target } }.

TypeRequired
functionNo

onScroll

Invoked on content scroll with { nativeEvent: { contentOffset: { x, y } } }. May also contain other properties from ScrollEvent but on Android contentSize is not provided for performance reasons.

TypeRequired
functionNo

onSelectionChange

Callback that is called when the text input selection is changed. This will be called with { nativeEvent: { selection: { start, end } } }. This prop requires multiline={true} to be set.

TypeRequired
functionNo

onSubmitEditing

Callback that is called when the text input's submit button is pressed with the argument {nativeEvent: {text, eventCount, target}}.

TypeRequired
functionNo

Note that on iOS this method isn't called when using keyboardType="phone-pad".

placeholder

The string that will be rendered before text input has been entered.

TypeRequired
stringNo

placeholderTextColor

The text color of the placeholder string.

TypeRequired
colorNo

returnKeyLabel

Sets the return key to the label. Use it instead of returnKeyType.

TypeRequiredPlatform
stringNoAndroid

returnKeyType

Determines how the return key should look. On Android you can also use returnKeyLabel.

Cross platform

The following values work across platforms:

  • done
  • go
  • next
  • search
  • send

Android Only

The following values work on Android only:

  • none
  • previous

iOS Only

The following values work on iOS only:

  • default
  • emergency-call
  • google
  • join
  • route
  • yahoo
TypeRequired
enum('done', 'go', 'next', 'search', 'send', 'none', 'previous', 'default', 'emergency-call', 'google', 'join', 'route', 'yahoo')No

rejectResponderTermination

iOS Only

If true, allows TextInput to pass touch events to the parent component. This allows components such as SwipeableListView to be swipeable from the TextInput on iOS, as is the case on Android by default. If false, TextInput always asks to handle the input (except when disabled). The default value is true.

TypeRequiredPlatform
boolNoiOS

scrollEnabled

If false, scrolling of the text view will be disabled. The default value is true. Only works with multiline={true}.

TypeRequiredPlatform
boolNoiOS

secureTextEntry

If true, the text input obscures the text entered so that sensitive text like passwords stay secure. The default value is false. Does not work with multiline={true}.

TypeRequired
boolNo

selection

The start and end of the text input's selection. Set start and end to the same value to position the cursor.

TypeRequired
object: {start: number,end: number}No

selectionColor

The highlight and cursor color of the text input.

TypeRequired
colorNo

selectTextOnFocus

If true, all text will automatically be selected on focus.

TypeRequired
boolNo

showSoftInputOnFocus

When false, it will prevent the soft keyboard from showing when the field is focused. The default value is true.

TypeRequiredPlatform
boolNoAndroid

spellCheck

If false, disables spell-check style (i.e. red underlines). The default value is inherited from autoCorrect.

TypeRequiredPlatform
boolNoiOS

textAlign

Align the input text to the left, center, or right sides of the input field.

Possible values for textAlign are:

  • left
  • center
  • right
TypeRequired
enum('left', 'center', 'right')No

textContentType

Give the keyboard and the system information about the expected semantic meaning for the content that users enter.

For iOS 11+ you can set textContentType to username or password to enable autofill of login details from the device keychain.

For iOS 12+ newPassword can be used to indicate a new password input the user may want to save in the keychain, and oneTimeCode can be used to indicate that a field can be autofilled by a code arriving in an SMS.

To disable autofill, set textContentType to none.

Possible values for textContentType are:

  • none
  • URL
  • addressCity
  • addressCityAndState
  • addressState
  • countryName
  • creditCardNumber
  • emailAddress
  • familyName
  • fullStreetAddress
  • givenName
  • jobTitle
  • location
  • middleName
  • name
  • namePrefix
  • nameSuffix
  • nickname
  • organizationName
  • postalCode
  • streetAddressLine1
  • streetAddressLine2
  • sublocality
  • telephoneNumber
  • username
  • password
  • newPassword
  • oneTimeCode
TypeRequiredPlatform
enum('none', 'URL', 'addressCity', 'addressCityAndState', 'addressState', 'countryName', 'creditCardNumber', 'emailAddress', 'familyName', 'fullStreetAddress', 'givenName', 'jobTitle', 'location', 'middleName', 'name', 'namePrefix', 'nameSuffix', 'nickname', 'organizationName', 'postalCode', 'streetAddressLine1', 'streetAddressLine2', 'sublocality', 'telephoneNumber', 'username', 'password')NoiOS

passwordRules

When using textContentType as newPassword on iOS we can let the OS know the minimum requirements of the password so that it can generate one that will satisfy them. In order to create a valid string for PasswordRules take a look to the Apple Docs.

TypeRequiredPlatform
stringNoiOS

style

Note that not all Text styles are supported, an incomplete list of what is not supported includes:

  • borderLeftWidth
  • borderTopWidth
  • borderRightWidth
  • borderBottomWidth
  • borderTopLeftRadius
  • borderTopRightRadius
  • borderBottomRightRadius
  • borderBottomLeftRadius

see Issue#7070 for more detail.

Styles

TypeRequired
TextNo

textBreakStrategy

Set text break strategy on Android API Level 23+, possible values are simple, highQuality, balanced The default value is simple.

TypeRequiredPlatform
enum('simple', 'highQuality', 'balanced')NoAndroid

underlineColorAndroid

The color of the TextInput underline.

TypeRequiredPlatform
colorNoAndroid

value

The value to show for the text input. TextInput is a controlled component, which means the native value will be forced to match this value prop if provided. For most uses, this works great, but in some cases this may cause flickering - one common cause is preventing edits by keeping value the same. In addition to setting the same value, either set editable={false}, or set/update maxLength to prevent unwanted edits without flicker.

TypeRequired
stringNo

Methods

.focus()

focus();

Makes the native input request focus.

.blur()

blur();

Makes the native input lose focus.

clear()

clear();

Removes all text from the TextInput.

isFocused()

isFocused();

Returns true if the input is currently focused; false otherwise.

Known issues

  • react-native#19096: Doesn't support Android's onKeyPreIme.
  • react-native#19366: Calling .focus() after closing Android's keyboard via back button doesn't bring keyboard up again.
  • react-native#26799: Doesn't support Android's secureTextEntry when keyboardType="email-address" or keyboardType="phone-pad".
Edit this page
Last updated on
- + diff --git a/docs/timepickerandroid.html b/docs/timepickerandroid.html index 5668eac609f..cd93f8f05e2 100644 --- a/docs/timepickerandroid.html +++ b/docs/timepickerandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 TimePickerAndroid

Deprecated. Use one of the community packages instead.

Opens the standard Android time picker dialog.

Example

try {
const { action, hour, minute } = await TimePickerAndroid.open({
hour: 14,
minute: 0,
is24Hour: false // Will display '2 PM'
});
if (action !== TimePickerAndroid.dismissedAction) {
// Selected hour (0-23), minute (0-59)
}
} catch ({ code, message }) {
console.warn('Cannot open time picker', message);
}

Reference

Methods

open()

static open(options)

Opens the standard Android time picker dialog.

The available keys for the options object are:

  • hour (0-23) - the hour to show, defaults to the current time
  • minute (0-59) - the minute to show, defaults to the current time
  • is24Hour (boolean) - If true, the picker uses the 24-hour format. If false, the picker shows an AM/PM chooser. If undefined, the default for the current locale is used.
  • mode (enum('clock', 'spinner', 'default')) - set the time picker mode
    • 'clock': Show a time picker in clock mode.
    • 'spinner': Show a time picker in spinner mode.
    • 'default': Show a default time picker based on Android versions.

Returns a Promise which will be invoked an object containing action, hour (0-23), minute (0-59) if the user picked a time. If the user dismissed the dialog, the Promise will still be resolved with action being TimePickerAndroid.dismissedAction and all the other keys being undefined. Always check whether the action before reading the values.

timeSetAction()

static timeSetAction()

A time has been selected.

dismissedAction()

static dismissedAction()

The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/timepickerandroid/index.html b/docs/timepickerandroid/index.html index 5668eac609f..cd93f8f05e2 100644 --- a/docs/timepickerandroid/index.html +++ b/docs/timepickerandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

🚧 TimePickerAndroid

Deprecated. Use one of the community packages instead.

Opens the standard Android time picker dialog.

Example

try {
const { action, hour, minute } = await TimePickerAndroid.open({
hour: 14,
minute: 0,
is24Hour: false // Will display '2 PM'
});
if (action !== TimePickerAndroid.dismissedAction) {
// Selected hour (0-23), minute (0-59)
}
} catch ({ code, message }) {
console.warn('Cannot open time picker', message);
}

Reference

Methods

open()

static open(options)

Opens the standard Android time picker dialog.

The available keys for the options object are:

  • hour (0-23) - the hour to show, defaults to the current time
  • minute (0-59) - the minute to show, defaults to the current time
  • is24Hour (boolean) - If true, the picker uses the 24-hour format. If false, the picker shows an AM/PM chooser. If undefined, the default for the current locale is used.
  • mode (enum('clock', 'spinner', 'default')) - set the time picker mode
    • 'clock': Show a time picker in clock mode.
    • 'spinner': Show a time picker in spinner mode.
    • 'default': Show a default time picker based on Android versions.

Returns a Promise which will be invoked an object containing action, hour (0-23), minute (0-59) if the user picked a time. If the user dismissed the dialog, the Promise will still be resolved with action being TimePickerAndroid.dismissedAction and all the other keys being undefined. Always check whether the action before reading the values.

timeSetAction()

static timeSetAction()

A time has been selected.

dismissedAction()

static dismissedAction()

The dialog has been dismissed.

Edit this page
Last updated on
- + diff --git a/docs/timers.html b/docs/timers.html index fb66bd1eb66..c71caa8980c 100644 --- a/docs/timers.html +++ b/docs/timers.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Timers

Timers are an important part of an application and React Native implements the browser timers.

Timers

  • setTimeout, clearTimeout
  • setInterval, clearInterval
  • setImmediate, clearImmediate
  • requestAnimationFrame, cancelAnimationFrame

requestAnimationFrame(fn) is not the same as setTimeout(fn, 0) - the former will fire after all the frame has flushed, whereas the latter will fire as quickly as possible (over 1000x per second on a iPhone 5S).

setImmediate is executed at the end of the current JavaScript execution block, right before sending the batched response back to native. Note that if you call setImmediate within a setImmediate callback, it will be executed right away, it won't yield back to native in between.

The Promise implementation uses setImmediate as its asynchronicity implementation.

InteractionManager

One reason why well-built native apps feel so smooth is by avoiding expensive operations during interactions and animations. In React Native, we currently have a limitation that there is only a single JS execution thread, but you can use InteractionManager to make sure long-running work is scheduled to start after any interactions/animations have completed.

Applications can schedule tasks to run after interactions with the following:

InteractionManager.runAfterInteractions(() => {
// ...long-running synchronous task...
});

Compare this to other scheduling alternatives:

  • requestAnimationFrame(): for code that animates a view over time.
  • setImmediate/setTimeout/setInterval(): run code later, note this may delay animations.
  • runAfterInteractions(): run code later, without delaying active animations.

The touch handling system considers one or more active touches to be an 'interaction' and will delay runAfterInteractions() callbacks until all touches have ended or been cancelled.

InteractionManager also allows applications to register animations by creating an interaction 'handle' on animation start, and clearing it upon completion:

var handle = InteractionManager.createInteractionHandle();
// run animation... (`runAfterInteractions` tasks are queued)
// later, on animation completion:
InteractionManager.clearInteractionHandle(handle);
// queued tasks run if all handles were cleared
Edit this page
Last updated on
- + diff --git a/docs/timers/index.html b/docs/timers/index.html index fb66bd1eb66..c71caa8980c 100644 --- a/docs/timers/index.html +++ b/docs/timers/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Timers

Timers are an important part of an application and React Native implements the browser timers.

Timers

  • setTimeout, clearTimeout
  • setInterval, clearInterval
  • setImmediate, clearImmediate
  • requestAnimationFrame, cancelAnimationFrame

requestAnimationFrame(fn) is not the same as setTimeout(fn, 0) - the former will fire after all the frame has flushed, whereas the latter will fire as quickly as possible (over 1000x per second on a iPhone 5S).

setImmediate is executed at the end of the current JavaScript execution block, right before sending the batched response back to native. Note that if you call setImmediate within a setImmediate callback, it will be executed right away, it won't yield back to native in between.

The Promise implementation uses setImmediate as its asynchronicity implementation.

InteractionManager

One reason why well-built native apps feel so smooth is by avoiding expensive operations during interactions and animations. In React Native, we currently have a limitation that there is only a single JS execution thread, but you can use InteractionManager to make sure long-running work is scheduled to start after any interactions/animations have completed.

Applications can schedule tasks to run after interactions with the following:

InteractionManager.runAfterInteractions(() => {
// ...long-running synchronous task...
});

Compare this to other scheduling alternatives:

  • requestAnimationFrame(): for code that animates a view over time.
  • setImmediate/setTimeout/setInterval(): run code later, note this may delay animations.
  • runAfterInteractions(): run code later, without delaying active animations.

The touch handling system considers one or more active touches to be an 'interaction' and will delay runAfterInteractions() callbacks until all touches have ended or been cancelled.

InteractionManager also allows applications to register animations by creating an interaction 'handle' on animation start, and clearing it upon completion:

var handle = InteractionManager.createInteractionHandle();
// run animation... (`runAfterInteractions` tasks are queued)
// later, on animation completion:
InteractionManager.clearInteractionHandle(handle);
// queued tasks run if all handles were cleared
Edit this page
Last updated on
- + diff --git a/docs/toastandroid.html b/docs/toastandroid.html index 01d324e8416..47a9d0dc0f5 100644 --- a/docs/toastandroid.html +++ b/docs/toastandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

ToastAndroid

React Native's ToastAndroid API exposes the Android platform's ToastAndroid module as a JS module. It provides the method show(message, duration) which takes the following parameters:

  • message A string with the text to toast
  • duration The duration of the toast—either ToastAndroid.SHORT or ToastAndroid.LONG

You can alternatively use showWithGravity(message, duration, gravity) to specify where the toast appears in the screen's layout. May be ToastAndroid.TOP, ToastAndroid.BOTTOM or ToastAndroid.CENTER.

The 'showWithGravityAndOffset(message, duration, gravity, xOffset, yOffset)' method adds the ability to specify an offset with in pixels.

Imperative hack

The ToastAndroid API is imperative, but there is a way to expose a declarative component from it as in this example:

Reference

Methods

show()

static show(message, duration)

showWithGravity()

static showWithGravity(message, duration, gravity)

showWithGravityAndOffset()

static showWithGravityAndOffset(message, duration, gravity, xOffset, yOffset)

Properties

SHORT

Indicates the duration on the screen.

ToastAndroid.SHORT;

LONG

Indicates the duration on the screen.

ToastAndroid.LONG;

TOP

Indicates the position on the screen.

ToastAndroid.TOP;

BOTTOM

Indicates the position on the screen.

ToastAndroid.BOTTOM;

CENTER

Indicates the position on the screen.

ToastAndroid.CENTER;
Edit this page
Last updated on
- + diff --git a/docs/toastandroid/index.html b/docs/toastandroid/index.html index 01d324e8416..47a9d0dc0f5 100644 --- a/docs/toastandroid/index.html +++ b/docs/toastandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

ToastAndroid

React Native's ToastAndroid API exposes the Android platform's ToastAndroid module as a JS module. It provides the method show(message, duration) which takes the following parameters:

  • message A string with the text to toast
  • duration The duration of the toast—either ToastAndroid.SHORT or ToastAndroid.LONG

You can alternatively use showWithGravity(message, duration, gravity) to specify where the toast appears in the screen's layout. May be ToastAndroid.TOP, ToastAndroid.BOTTOM or ToastAndroid.CENTER.

The 'showWithGravityAndOffset(message, duration, gravity, xOffset, yOffset)' method adds the ability to specify an offset with in pixels.

Imperative hack

The ToastAndroid API is imperative, but there is a way to expose a declarative component from it as in this example:

Reference

Methods

show()

static show(message, duration)

showWithGravity()

static showWithGravity(message, duration, gravity)

showWithGravityAndOffset()

static showWithGravityAndOffset(message, duration, gravity, xOffset, yOffset)

Properties

SHORT

Indicates the duration on the screen.

ToastAndroid.SHORT;

LONG

Indicates the duration on the screen.

ToastAndroid.LONG;

TOP

Indicates the position on the screen.

ToastAndroid.TOP;

BOTTOM

Indicates the position on the screen.

ToastAndroid.BOTTOM;

CENTER

Indicates the position on the screen.

ToastAndroid.CENTER;
Edit this page
Last updated on
- + diff --git a/docs/toolbarandroid.html b/docs/toolbarandroid.html index 4f9ce371c51..49b7e1b512f 100644 --- a/docs/toolbarandroid.html +++ b/docs/toolbarandroid.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

ToolbarAndroid

NOTE: Toolbar Android has been deprecated and removed from the package since React Native v0.61.0. Use @react-native-community/toolbar-android instead.

React component that wraps the Android-only Toolbar widget. A Toolbar can display a logo, navigation icon (e.g. hamburger menu), a title & subtitle and a list of actions. The title and subtitle are expanded so the logo and navigation icons are displayed on the left, title and subtitle in the middle and the actions on the right.

If the toolbar has an only child, it will be displayed between the title and actions.

Although the Toolbar supports remote images for the logo, navigation and action icons, this should only be used in DEV mode where require('./some_icon.png') translates into a bundler URL. In release mode you should always use a drawable resource for these icons. Using require('./some_icon.png') will do this automatically for you, so as long as you don't explicitly use e.g. {uri: 'http://...'}, you will be good.

Example:

render: function() {
return (
<ToolbarAndroid
logo={require('./app_logo.png')}
title="AwesomeApp"
actions={[{title: 'Settings', icon: require('./icon_settings.png'), show: 'always'}]}
onActionSelected={this.onActionSelected} />
)
},
onActionSelected: function(position) {
if (position === 0) { // index of 'Settings'
showSettings();
}
}

Reference

Props

Inherits View Props.

actions

Sets possible actions on the toolbar as part of the action menu. These are displayed as icons or text on the right side of the widget. If they don't fit they are placed in an 'overflow' menu.

This property takes an array of objects, where each object has the following keys:

  • title: required, the title of this action
  • icon: the icon for this action, e.g. require('./some_icon.png')
  • show: when to show this action as an icon or hide it in the overflow menu: always, ifRoom or never
  • showWithText: boolean, whether to show text alongside the icon or not
TypeRequired
array of object: {title: string,icon: optionalImageSource,show: enum('always', 'ifRoom', 'never'),showWithText: bool}No

contentInsetStart

Sets the content inset for the toolbar starting edge.

The content inset affects the valid area for Toolbar content other than the navigation button and menu. Insets define the minimum margin for these components and can be used to effectively align Toolbar content along well-known gridlines.

TypeRequired
numberNo

contentInsetEnd

Sets the content inset for the toolbar ending edge.

The content inset affects the valid area for Toolbar content other than the navigation button and menu. Insets define the minimum margin for these components and can be used to effectively align Toolbar content along well-known gridlines.

TypeRequired
numberNo

logo

Sets the toolbar logo.

TypeRequired
optionalImageSourceNo

navIcon

Sets the navigation icon.

TypeRequired
optionalImageSourceNo

onActionSelected

Callback that is called when an action is selected. The only argument that is passed to the callback is the position of the action in the actions array.

TypeRequired
functionNo

onIconClicked

Callback called when the icon is selected.

TypeRequired
functionNo

overflowIcon

Sets the overflow icon.

TypeRequired
optionalImageSourceNo

rtl

Used to set the toolbar direction to RTL. In addition to this property you need to add

android:supportsRtl="true"

to your application AndroidManifest.xml and then call setLayoutDirection(LayoutDirection.RTL) in your MainActivity onCreate method.

TypeRequired
boolNo

subtitle

Sets the toolbar subtitle.

TypeRequired
stringNo

subtitleColor

Sets the toolbar subtitle color.

TypeRequired
colorNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

title

Sets the toolbar title.

TypeRequired
stringNo

titleColor

Sets the toolbar title color.

TypeRequired
colorNo
Edit this page
Last updated on
- + diff --git a/docs/toolbarandroid/index.html b/docs/toolbarandroid/index.html index 4f9ce371c51..49b7e1b512f 100644 --- a/docs/toolbarandroid/index.html +++ b/docs/toolbarandroid/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

ToolbarAndroid

NOTE: Toolbar Android has been deprecated and removed from the package since React Native v0.61.0. Use @react-native-community/toolbar-android instead.

React component that wraps the Android-only Toolbar widget. A Toolbar can display a logo, navigation icon (e.g. hamburger menu), a title & subtitle and a list of actions. The title and subtitle are expanded so the logo and navigation icons are displayed on the left, title and subtitle in the middle and the actions on the right.

If the toolbar has an only child, it will be displayed between the title and actions.

Although the Toolbar supports remote images for the logo, navigation and action icons, this should only be used in DEV mode where require('./some_icon.png') translates into a bundler URL. In release mode you should always use a drawable resource for these icons. Using require('./some_icon.png') will do this automatically for you, so as long as you don't explicitly use e.g. {uri: 'http://...'}, you will be good.

Example:

render: function() {
return (
<ToolbarAndroid
logo={require('./app_logo.png')}
title="AwesomeApp"
actions={[{title: 'Settings', icon: require('./icon_settings.png'), show: 'always'}]}
onActionSelected={this.onActionSelected} />
)
},
onActionSelected: function(position) {
if (position === 0) { // index of 'Settings'
showSettings();
}
}

Reference

Props

Inherits View Props.

actions

Sets possible actions on the toolbar as part of the action menu. These are displayed as icons or text on the right side of the widget. If they don't fit they are placed in an 'overflow' menu.

This property takes an array of objects, where each object has the following keys:

  • title: required, the title of this action
  • icon: the icon for this action, e.g. require('./some_icon.png')
  • show: when to show this action as an icon or hide it in the overflow menu: always, ifRoom or never
  • showWithText: boolean, whether to show text alongside the icon or not
TypeRequired
array of object: {title: string,icon: optionalImageSource,show: enum('always', 'ifRoom', 'never'),showWithText: bool}No

contentInsetStart

Sets the content inset for the toolbar starting edge.

The content inset affects the valid area for Toolbar content other than the navigation button and menu. Insets define the minimum margin for these components and can be used to effectively align Toolbar content along well-known gridlines.

TypeRequired
numberNo

contentInsetEnd

Sets the content inset for the toolbar ending edge.

The content inset affects the valid area for Toolbar content other than the navigation button and menu. Insets define the minimum margin for these components and can be used to effectively align Toolbar content along well-known gridlines.

TypeRequired
numberNo

logo

Sets the toolbar logo.

TypeRequired
optionalImageSourceNo

navIcon

Sets the navigation icon.

TypeRequired
optionalImageSourceNo

onActionSelected

Callback that is called when an action is selected. The only argument that is passed to the callback is the position of the action in the actions array.

TypeRequired
functionNo

onIconClicked

Callback called when the icon is selected.

TypeRequired
functionNo

overflowIcon

Sets the overflow icon.

TypeRequired
optionalImageSourceNo

rtl

Used to set the toolbar direction to RTL. In addition to this property you need to add

android:supportsRtl="true"

to your application AndroidManifest.xml and then call setLayoutDirection(LayoutDirection.RTL) in your MainActivity onCreate method.

TypeRequired
boolNo

subtitle

Sets the toolbar subtitle.

TypeRequired
stringNo

subtitleColor

Sets the toolbar subtitle color.

TypeRequired
colorNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

title

Sets the toolbar title.

TypeRequired
stringNo

titleColor

Sets the toolbar title color.

TypeRequired
colorNo
Edit this page
Last updated on
- + diff --git a/docs/touchablehighlight.html b/docs/touchablehighlight.html index bcbed5f1351..0fb433b87df 100644 --- a/docs/touchablehighlight.html +++ b/docs/touchablehighlight.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
<TouchableHighlight
activeOpacity={0.6}
underlayColor="#DDDDDD"
onPress={() => alert('Pressed!')}>
<MyComponent />
</TouchableHighlight>;

Example

Reference

Props

Inherits TouchableWithoutFeedback Props.

activeOpacity

Determines what the opacity of the wrapped view should be when touch is active. The value should be between 0 and 1. Defaults to 0.85. Requires underlayColor to be set.

TypeRequired
numberNo

onHideUnderlay

Called immediately after the underlay is hidden.

TypeRequired
functionNo

onShowUnderlay

Called immediately after the underlay is shown.

TypeRequired
functionNo

style

TypeRequired
View.styleNo

underlayColor

The color of the underlay that will show through when the touch is active.

TypeRequired
colorNo

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

testOnly_pressed

Handy for snapshot tests.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/touchablehighlight/index.html b/docs/touchablehighlight/index.html index bcbed5f1351..0fb433b87df 100644 --- a/docs/touchablehighlight/index.html +++ b/docs/touchablehighlight/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
<TouchableHighlight
activeOpacity={0.6}
underlayColor="#DDDDDD"
onPress={() => alert('Pressed!')}>
<MyComponent />
</TouchableHighlight>;

Example

Reference

Props

Inherits TouchableWithoutFeedback Props.

activeOpacity

Determines what the opacity of the wrapped view should be when touch is active. The value should be between 0 and 1. Defaults to 0.85. Requires underlayColor to be set.

TypeRequired
numberNo

onHideUnderlay

Called immediately after the underlay is hidden.

TypeRequired
functionNo

onShowUnderlay

Called immediately after the underlay is shown.

TypeRequired
functionNo

style

TypeRequired
View.styleNo

underlayColor

The color of the underlay that will show through when the touch is active.

TypeRequired
colorNo

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

testOnly_pressed

Handy for snapshot tests.

TypeRequired
boolNo
Edit this page
Last updated on
- + diff --git a/docs/touchablenativefeedback.html b/docs/touchablenativefeedback.html index 23b47870447..dec8dceb2f4 100644 --- a/docs/touchablenativefeedback.html +++ b/docs/touchablenativefeedback.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

TouchableNativeFeedback

If you're looking for a more extensive and future-proof way to handle touch-based input, check out the Pressable API.

A wrapper for making views respond properly to touches (Android only). On Android this component uses native state drawable to display touch feedback.

At the moment it only supports having a single View instance as a child node, as it's implemented by replacing that View with another instance of RCTView node with some additional properties set.

Background drawable of native feedback touchable can be customized with background property.

Example

Reference

Props

Inherits TouchableWithoutFeedback Props.

background

Determines the type of background drawable that's going to be used to display feedback. It takes an object with type property and extra data depending on the type. It's recommended to use one of the static methods to generate that dictionary.

TypeRequired
backgroundPropTypeNo

useForeground

Set to true to add the ripple effect to the foreground of the view, instead of the background. This is useful if one of your child views has a background of its own, or you're e.g. displaying images, and you don't want the ripple to be covered by them.

Check TouchableNativeFeedback.canUseNativeForeground() first, as this is only available on Android 6.0 and above. If you try to use this on older versions you will get a warning and fallback to background.

TypeRequired
boolNo

hasTVPreferredFocus

TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

Methods

SelectableBackground()

static SelectableBackground(rippleRadius: ?number)

Creates an object that represents android theme's default background for selectable elements (?android:attr/selectableItemBackground). rippleRadius parameter controls the radius of the ripple effect.

SelectableBackgroundBorderless()

static SelectableBackgroundBorderless(rippleRadius: ?number)

Creates an object that represent android theme's default background for borderless selectable elements (?android:attr/selectableItemBackgroundBorderless). Available on android API level 21+. rippleRadius parameter controls the radius of the ripple effect.

Ripple()

static Ripple(color: string, borderless: boolean, rippleRadius: ?number)

Creates an object that represents ripple drawable with specified color (as a string). If property borderless evaluates to true the ripple will render outside of the view bounds (see native actionbar buttons as an example of that behavior). This background type is available on Android API level 21+.

Parameters:

NameTypeRequiredDescription
colorstringYesThe ripple color
borderlessbooleanYesIf the ripple can render outside its bounds
rippleRadius?numberNocontrols the radius of the ripple effect

canUseNativeForeground()

static canUseNativeForeground()
Edit this page
Last updated on
- + diff --git a/docs/touchablenativefeedback/index.html b/docs/touchablenativefeedback/index.html index 23b47870447..dec8dceb2f4 100644 --- a/docs/touchablenativefeedback/index.html +++ b/docs/touchablenativefeedback/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

TouchableNativeFeedback

If you're looking for a more extensive and future-proof way to handle touch-based input, check out the Pressable API.

A wrapper for making views respond properly to touches (Android only). On Android this component uses native state drawable to display touch feedback.

At the moment it only supports having a single View instance as a child node, as it's implemented by replacing that View with another instance of RCTView node with some additional properties set.

Background drawable of native feedback touchable can be customized with background property.

Example

Reference

Props

Inherits TouchableWithoutFeedback Props.

background

Determines the type of background drawable that's going to be used to display feedback. It takes an object with type property and extra data depending on the type. It's recommended to use one of the static methods to generate that dictionary.

TypeRequired
backgroundPropTypeNo

useForeground

Set to true to add the ripple effect to the foreground of the view, instead of the background. This is useful if one of your child views has a background of its own, or you're e.g. displaying images, and you don't want the ripple to be covered by them.

Check TouchableNativeFeedback.canUseNativeForeground() first, as this is only available on Android 6.0 and above. If you try to use this on older versions you will get a warning and fallback to background.

TypeRequired
boolNo

hasTVPreferredFocus

TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

Methods

SelectableBackground()

static SelectableBackground(rippleRadius: ?number)

Creates an object that represents android theme's default background for selectable elements (?android:attr/selectableItemBackground). rippleRadius parameter controls the radius of the ripple effect.

SelectableBackgroundBorderless()

static SelectableBackgroundBorderless(rippleRadius: ?number)

Creates an object that represent android theme's default background for borderless selectable elements (?android:attr/selectableItemBackgroundBorderless). Available on android API level 21+. rippleRadius parameter controls the radius of the ripple effect.

Ripple()

static Ripple(color: string, borderless: boolean, rippleRadius: ?number)

Creates an object that represents ripple drawable with specified color (as a string). If property borderless evaluates to true the ripple will render outside of the view bounds (see native actionbar buttons as an example of that behavior). This background type is available on Android API level 21+.

Parameters:

NameTypeRequiredDescription
colorstringYesThe ripple color
borderlessbooleanYesIf the ripple can render outside its bounds
rippleRadius?numberNocontrols the radius of the ripple effect

canUseNativeForeground()

static canUseNativeForeground()
Edit this page
Last updated on
- + diff --git a/docs/touchableopacity.html b/docs/touchableopacity.html index 6cc469997b8..cef6954cdfa 100644 --- a/docs/touchableopacity.html +++ b/docs/touchableopacity.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

TouchableOpacity

If you're looking for a more extensive and future-proof way to handle touch-based input, check out the Pressable API.

A wrapper for making views respond properly to touches. On press down, the opacity of the wrapped view is decreased, dimming it.

Opacity is controlled by wrapping the children in an Animated.View, which is added to the view hierarchy. Be aware that this can affect layout.

Example

Reference

Props

Inherits TouchableWithoutFeedback Props.

style

TypeRequired
View.styleNo

activeOpacity

Determines what the opacity of the wrapped view should be when touch is active. Defaults to 0.2.

TypeRequired
numberNo

tvParallaxProperties

(Apple TV only) Object with properties to control Apple TV parallax effects.

  • enabled: If true, parallax effects are enabled. Defaults to true.
  • shiftDistanceX: Defaults to 2.0.
  • shiftDistanceY: Defaults to 2.0.
  • tiltAngle: Defaults to 0.05.
  • magnification: Defaults to 1.0.
  • pressMagnification: Defaults to 1.0.
  • pressDuration: Defaults to 0.3.
  • pressDelay: Defaults to 0.0.
TypeRequiredPlatform
objectNoiOS

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/touchableopacity/index.html b/docs/touchableopacity/index.html index 6cc469997b8..cef6954cdfa 100644 --- a/docs/touchableopacity/index.html +++ b/docs/touchableopacity/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

TouchableOpacity

If you're looking for a more extensive and future-proof way to handle touch-based input, check out the Pressable API.

A wrapper for making views respond properly to touches. On press down, the opacity of the wrapped view is decreased, dimming it.

Opacity is controlled by wrapping the children in an Animated.View, which is added to the view hierarchy. Be aware that this can affect layout.

Example

Reference

Props

Inherits TouchableWithoutFeedback Props.

style

TypeRequired
View.styleNo

activeOpacity

Determines what the opacity of the wrapped view should be when touch is active. Defaults to 0.2.

TypeRequired
numberNo

tvParallaxProperties

(Apple TV only) Object with properties to control Apple TV parallax effects.

  • enabled: If true, parallax effects are enabled. Defaults to true.
  • shiftDistanceX: Defaults to 2.0.
  • shiftDistanceY: Defaults to 2.0.
  • tiltAngle: Defaults to 0.05.
  • magnification: Defaults to 1.0.
  • pressMagnification: Defaults to 1.0.
  • pressDuration: Defaults to 0.3.
  • pressDelay: Defaults to 0.0.
TypeRequiredPlatform
objectNoiOS

hasTVPreferredFocus

(Apple TV only) TV preferred focus (see documentation for the View component).

TypeRequiredPlatform
boolNoiOS

nextFocusDown

TV next focus down (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusForward

TV next focus forward (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusLeft

TV next focus left (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusRight

TV next focus right (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid

nextFocusUp

TV next focus up (see documentation for the View component).

TypeRequiredPlatform
boolNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/touchablewithoutfeedback.html b/docs/touchablewithoutfeedback.html index 14d58e8e730..56874f7756b 100644 --- a/docs/touchablewithoutfeedback.html +++ b/docs/touchablewithoutfeedback.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
<TouchableWithoutFeedback onPress={() => alert('Pressed!')}>
<MyComponent />
</TouchableWithoutFeedback>;

Example

Reference

Props

accessibilityIgnoresInvertColors

TypeRequired
BooleanNo

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

accessibilityActions

Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The accessibilityActions property should contain a list of action objects. Each action object should contain the field name and label.

See the Accessibility guide for more information.

TypeRequired
arrayNo

onAccessibilityAction

Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform.

See the Accessibility guide for more information.

TypeRequired
functionNo

accessibilityValue

Represents the current value of a component. It can be a textual description of a component's value, or for range-based components, such as sliders and progress bars, it contains range information (minimum, current, and maximum).

See the Accessibility guide for more information.

TypeRequired
object: {min: number, max: number, now: number, text: string}No

delayLongPress

Duration (in milliseconds) from onPressIn before onLongPress is called.

TypeRequired
numberNo

delayPressIn

Duration (in milliseconds), from the start of the touch, before onPressIn is called.

TypeRequired
numberNo

delayPressOut

Duration (in milliseconds), from the release of the touch, before onPressOut is called.

TypeRequired
numberNo

disabled

If true, disable all interactions for this component.

TypeRequired
boolNo

hitSlop

This defines how far your touch can start away from the button. This is added to pressRetentionOffset when moving off of the button.

The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

TypeRequired
Rect or numberNo

onBlur

Invoked when the item loses focus.

TypeRequired
functionNo

onFocus

Invoked when the item receives focus.

TypeRequired
functionNo

onLayout

Invoked on mount and layout changes with

{nativeEvent: {layout: {x, y, width, height}}}

TypeRequired
functionNo

onLongPress

Called if the time after onPressIn lasts longer than 370 milliseconds. This time period can be customized with delayLongPress.

TypeRequired
functionNo

onPress

Called when the touch is released, but not if cancelled (e.g. by a scroll that steals the responder lock). The first function argument is an event in form of PressEvent.

TypeRequired
functionNo

onPressIn

Called as soon as the touchable element is pressed and invoked even before onPress. This can be useful when making network requests. The first function argument is an event in form of PressEvent.

TypeRequired
functionNo

onPressOut

Called as soon as the touch is released even before onPress. The first function argument is an event in form of PressEvent.

TypeRequired
functionNo

pressRetentionOffset

When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations.

TypeRequired
Rect or numberNo

nativeID

TypeRequired
stringNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

touchSoundDisabled

If true, doesn't play a system sound on touch.

TypeRequiredPlatform
BooleanNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/touchablewithoutfeedback/index.html b/docs/touchablewithoutfeedback/index.html index 14d58e8e730..56874f7756b 100644 --- a/docs/touchablewithoutfeedback/index.html +++ b/docs/touchablewithoutfeedback/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
<TouchableWithoutFeedback onPress={() => alert('Pressed!')}>
<MyComponent />
</TouchableWithoutFeedback>;

Example

Reference

Props

accessibilityIgnoresInvertColors

TypeRequired
BooleanNo

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

accessibilityActions

Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The accessibilityActions property should contain a list of action objects. Each action object should contain the field name and label.

See the Accessibility guide for more information.

TypeRequired
arrayNo

onAccessibilityAction

Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform.

See the Accessibility guide for more information.

TypeRequired
functionNo

accessibilityValue

Represents the current value of a component. It can be a textual description of a component's value, or for range-based components, such as sliders and progress bars, it contains range information (minimum, current, and maximum).

See the Accessibility guide for more information.

TypeRequired
object: {min: number, max: number, now: number, text: string}No

delayLongPress

Duration (in milliseconds) from onPressIn before onLongPress is called.

TypeRequired
numberNo

delayPressIn

Duration (in milliseconds), from the start of the touch, before onPressIn is called.

TypeRequired
numberNo

delayPressOut

Duration (in milliseconds), from the release of the touch, before onPressOut is called.

TypeRequired
numberNo

disabled

If true, disable all interactions for this component.

TypeRequired
boolNo

hitSlop

This defines how far your touch can start away from the button. This is added to pressRetentionOffset when moving off of the button.

The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

TypeRequired
Rect or numberNo

onBlur

Invoked when the item loses focus.

TypeRequired
functionNo

onFocus

Invoked when the item receives focus.

TypeRequired
functionNo

onLayout

Invoked on mount and layout changes with

{nativeEvent: {layout: {x, y, width, height}}}

TypeRequired
functionNo

onLongPress

Called if the time after onPressIn lasts longer than 370 milliseconds. This time period can be customized with delayLongPress.

TypeRequired
functionNo

onPress

Called when the touch is released, but not if cancelled (e.g. by a scroll that steals the responder lock). The first function argument is an event in form of PressEvent.

TypeRequired
functionNo

onPressIn

Called as soon as the touchable element is pressed and invoked even before onPress. This can be useful when making network requests. The first function argument is an event in form of PressEvent.

TypeRequired
functionNo

onPressOut

Called as soon as the touch is released even before onPress. The first function argument is an event in form of PressEvent.

TypeRequired
functionNo

pressRetentionOffset

When the scroll view is disabled, this defines how far your touch may move off of the button, before deactivating the button. Once deactivated, try moving it back and you'll see that the button is once again reactivated! Move it back and forth several times while the scroll view is disabled. Ensure you pass in a constant to reduce memory allocations.

TypeRequired
Rect or numberNo

nativeID

TypeRequired
stringNo

testID

Used to locate this view in end-to-end tests.

TypeRequired
stringNo

touchSoundDisabled

If true, doesn't play a system sound on touch.

TypeRequiredPlatform
BooleanNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/transforms.html b/docs/transforms.html index 9a2ef17858f..6835447ad82 100644 --- a/docs/transforms.html +++ b/docs/transforms.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Transforms

Transforms are style properties that will help you modify the appearance and position of your components using 2D or 3D transformations. However, once you apply transforms, the layouts remain the same around the transformed component hence it might overlap with the nearby components. You can apply margin to the transformed component, the nearby components or padding to the container to prevent such overlaps.

Example

Reference

Methods

transform()

transform accepts an array of transformation objects. Each object specifies the property that will be transformed as the key, and the value to use in the transformation. Objects should not be combined. Use a single key/value pair per object.

The rotate transformations require a string so that the transform may be expressed in degrees (deg) or radians (rad). For example:

transform([{ rotateX: '45deg' }, { rotateZ: '0.785398rad' }]);

The skew transformations require a string so that the transform may be expressed in degrees (deg). For example:

transform([{ skewX: '45deg' }]);
TypeRequired
array of objects: {matrix: number[]}, {perspective: number}, {rotate: string}, {rotateX: string}, {rotateY: string}, {rotateZ: string}, {scale: number}, {scaleX: number}, {scaleY: number}, {translateX: number}, {translateY: number}, {skewX: string}, {skewY: string}No

decomposedMatrix, rotation, scaleX, scaleY, transformMatrix, translateX, translateY

Deprecated. Use the transform prop instead.

Edit this page
Last updated on
- + diff --git a/docs/transforms/index.html b/docs/transforms/index.html index 9a2ef17858f..6835447ad82 100644 --- a/docs/transforms/index.html +++ b/docs/transforms/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Transforms

Transforms are style properties that will help you modify the appearance and position of your components using 2D or 3D transformations. However, once you apply transforms, the layouts remain the same around the transformed component hence it might overlap with the nearby components. You can apply margin to the transformed component, the nearby components or padding to the container to prevent such overlaps.

Example

Reference

Methods

transform()

transform accepts an array of transformation objects. Each object specifies the property that will be transformed as the key, and the value to use in the transformation. Objects should not be combined. Use a single key/value pair per object.

The rotate transformations require a string so that the transform may be expressed in degrees (deg) or radians (rad). For example:

transform([{ rotateX: '45deg' }, { rotateZ: '0.785398rad' }]);

The skew transformations require a string so that the transform may be expressed in degrees (deg). For example:

transform([{ skewX: '45deg' }]);
TypeRequired
array of objects: {matrix: number[]}, {perspective: number}, {rotate: string}, {rotateX: string}, {rotateY: string}, {rotateZ: string}, {scale: number}, {scaleX: number}, {scaleY: number}, {translateX: number}, {translateY: number}, {skewX: string}, {skewY: string}No

decomposedMatrix, rotation, scaleX, scaleY, transformMatrix, translateX, translateY

Deprecated. Use the transform prop instead.

Edit this page
Last updated on
- + diff --git a/docs/troubleshooting.html b/docs/troubleshooting.html index 113900b2431..c6349573a4e 100644 --- a/docs/troubleshooting.html +++ b/docs/troubleshooting.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Troubleshooting

These are some common issues you may run into while setting up React Native. If you encounter something that is not listed here, try searching for the issue in GitHub.

Port already in use

The Metro bundler runs on port 8081. If another process is already using that port, you can either terminate that process, or change the port that the bundler uses.

Terminating a process on port 8081

Run the following command to find the id for the process that is listening on port 8081:

$ sudo lsof -i :8081

Then run the following to terminate the process:

$ kill -9 <PID>

On Windows you can find the process using port 8081 using Resource Monitor and stop it using Task Manager.

Using a port other than 8081

You can configure the bundler to use a port other than 8081 by using the port parameter:

$ npx react-native start --port=8088

You will also need to update your applications to load the JavaScript bundle from the new port. If running on device from Xcode, you can do this by updating occurrences of 8081 to your chosen port in the node_modules/react-native/React/React.xcodeproj/project.pbxproj file.

NPM locking error

If you encounter an error such as npm WARN locking Error: EACCES while using the React Native CLI, try running the following:

sudo chown -R $USER ~/.npm
sudo chown -R $USER /usr/local/lib/node_modules

Missing libraries for React

If you added React Native manually to your project, make sure you have included all the relevant dependencies that you are using, like RCTText.xcodeproj, RCTImage.xcodeproj. Next, the binaries built by these dependencies have to be linked to your app binary. Use the Linked Frameworks and Binaries section in the Xcode project settings. More detailed steps are here: Linking Libraries.

If you are using CocoaPods, verify that you have added React along with the subspecs to the Podfile. For example, if you were using the <Text />, <Image /> and fetch() APIs, you would need to add these in your Podfile:

pod 'React', :path => '../node_modules/react-native', :subspecs => [
'RCTText',
'RCTImage',
'RCTNetwork',
'RCTWebSocket',
]

Next, make sure you have run pod install and that a Pods/ directory has been created in your project with React installed. CocoaPods will instruct you to use the generated .xcworkspace file henceforth to be able to use these installed dependencies.

React Native does not compile when being used as a CocoaPod

There is a CocoaPods plugin called cocoapods-fix-react-native which handles any potential post-fixing of the source code due to differences when using a dependency manager.

Argument list too long: recursive header expansion failed

In the project's build settings, User Search Header Paths and Header Search Paths are two configs that specify where Xcode should look for #import header files specified in the code. For Pods, CocoaPods uses a default array of specific folders to look in. Verify that this particular config is not overwritten, and that none of the folders configured are too large. If one of the folders is a large folder, Xcode will attempt to recursively search the entire directory and throw above error at some point.

To revert the User Search Header Paths and Header Search Paths build settings to their defaults set by CocoaPods - select the entry in the Build Settings panel, and hit delete. It will remove the custom override and return to the CocoaPod defaults.

No transports available

React Native implements a polyfill for WebSockets. These polyfills are initialized as part of the react-native module that you include in your application through import React from 'react'. If you load another module that requires WebSockets, such as Firebase, be sure to load/require it after react-native:

import React from 'react';
import Firebase from 'firebase';

Shell Command Unresponsive Exception

If you encounter a ShellCommandUnresponsiveException exception such as:

Execution failed for task ':app:installDebug'.
com.android.builder.testing.api.DeviceException: com.android.ddmlib.ShellCommandUnresponsiveException

Try downgrading your Gradle version to 1.2.3 in android/build.gradle.

react-native init hangs

If you run into issues where running npx react-native init hangs in your system, try running it again in verbose mode and referring to #2797 for common causes:

npx react-native init --verbose

Unable to start react-native package manager (on Linux)

Case 1: Error "code":"ENOSPC","errno":"ENOSPC"

Issue caused by the number of directories inotify (used by watchman on Linux) can monitor. To solve it, run this command in your terminal window

echo fs.inotify.max_user_watches=582222 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
Edit this page
Last updated on
- + diff --git a/docs/troubleshooting/index.html b/docs/troubleshooting/index.html index 113900b2431..c6349573a4e 100644 --- a/docs/troubleshooting/index.html +++ b/docs/troubleshooting/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Troubleshooting

These are some common issues you may run into while setting up React Native. If you encounter something that is not listed here, try searching for the issue in GitHub.

Port already in use

The Metro bundler runs on port 8081. If another process is already using that port, you can either terminate that process, or change the port that the bundler uses.

Terminating a process on port 8081

Run the following command to find the id for the process that is listening on port 8081:

$ sudo lsof -i :8081

Then run the following to terminate the process:

$ kill -9 <PID>

On Windows you can find the process using port 8081 using Resource Monitor and stop it using Task Manager.

Using a port other than 8081

You can configure the bundler to use a port other than 8081 by using the port parameter:

$ npx react-native start --port=8088

You will also need to update your applications to load the JavaScript bundle from the new port. If running on device from Xcode, you can do this by updating occurrences of 8081 to your chosen port in the node_modules/react-native/React/React.xcodeproj/project.pbxproj file.

NPM locking error

If you encounter an error such as npm WARN locking Error: EACCES while using the React Native CLI, try running the following:

sudo chown -R $USER ~/.npm
sudo chown -R $USER /usr/local/lib/node_modules

Missing libraries for React

If you added React Native manually to your project, make sure you have included all the relevant dependencies that you are using, like RCTText.xcodeproj, RCTImage.xcodeproj. Next, the binaries built by these dependencies have to be linked to your app binary. Use the Linked Frameworks and Binaries section in the Xcode project settings. More detailed steps are here: Linking Libraries.

If you are using CocoaPods, verify that you have added React along with the subspecs to the Podfile. For example, if you were using the <Text />, <Image /> and fetch() APIs, you would need to add these in your Podfile:

pod 'React', :path => '../node_modules/react-native', :subspecs => [
'RCTText',
'RCTImage',
'RCTNetwork',
'RCTWebSocket',
]

Next, make sure you have run pod install and that a Pods/ directory has been created in your project with React installed. CocoaPods will instruct you to use the generated .xcworkspace file henceforth to be able to use these installed dependencies.

React Native does not compile when being used as a CocoaPod

There is a CocoaPods plugin called cocoapods-fix-react-native which handles any potential post-fixing of the source code due to differences when using a dependency manager.

Argument list too long: recursive header expansion failed

In the project's build settings, User Search Header Paths and Header Search Paths are two configs that specify where Xcode should look for #import header files specified in the code. For Pods, CocoaPods uses a default array of specific folders to look in. Verify that this particular config is not overwritten, and that none of the folders configured are too large. If one of the folders is a large folder, Xcode will attempt to recursively search the entire directory and throw above error at some point.

To revert the User Search Header Paths and Header Search Paths build settings to their defaults set by CocoaPods - select the entry in the Build Settings panel, and hit delete. It will remove the custom override and return to the CocoaPod defaults.

No transports available

React Native implements a polyfill for WebSockets. These polyfills are initialized as part of the react-native module that you include in your application through import React from 'react'. If you load another module that requires WebSockets, such as Firebase, be sure to load/require it after react-native:

import React from 'react';
import Firebase from 'firebase';

Shell Command Unresponsive Exception

If you encounter a ShellCommandUnresponsiveException exception such as:

Execution failed for task ':app:installDebug'.
com.android.builder.testing.api.DeviceException: com.android.ddmlib.ShellCommandUnresponsiveException

Try downgrading your Gradle version to 1.2.3 in android/build.gradle.

react-native init hangs

If you run into issues where running npx react-native init hangs in your system, try running it again in verbose mode and referring to #2797 for common causes:

npx react-native init --verbose

Unable to start react-native package manager (on Linux)

Case 1: Error "code":"ENOSPC","errno":"ENOSPC"

Issue caused by the number of directories inotify (used by watchman on Linux) can monitor. To solve it, run this command in your terminal window

echo fs.inotify.max_user_watches=582222 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
Edit this page
Last updated on
- + diff --git a/docs/tutorial.html b/docs/tutorial.html index ec5fe7d2354..b68a6024681 100644 --- a/docs/tutorial.html +++ b/docs/tutorial.html @@ -19,7 +19,7 @@ - + @@ -45,7 +45,7 @@
// React Native Styles
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'center',
alignItems: 'center'
}
});

As shown in the image, there is no difference in handling the state between React and React Native. You can use the state of your components both in classes and in functional components using hooks!

In the following example we will show the same above counter example using classes.

Edit this page
Last updated on
- + diff --git a/docs/tutorial/index.html b/docs/tutorial/index.html index ec5fe7d2354..b68a6024681 100644 --- a/docs/tutorial/index.html +++ b/docs/tutorial/index.html @@ -19,7 +19,7 @@ - + @@ -45,7 +45,7 @@
// React Native Styles
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'center',
alignItems: 'center'
}
});

As shown in the image, there is no difference in handling the state between React and React Native. You can use the state of your components both in classes and in functional components using hooks!

In the following example we will show the same above counter example using classes.

Edit this page
Last updated on
- + diff --git a/docs/typescript.html b/docs/typescript.html index 9751dc33cd8..ad8c20e5af8 100644 --- a/docs/typescript.html +++ b/docs/typescript.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
export default Hello;

You can explore the syntax more in the TypeScript playground.

Where to Find Useful Advice

Using Custom Path Aliases with TypeScript

To use custom path aliases with TypeScript, you need to set the path aliases to work from both Babel and TypeScript. Here's how:

  1. Edit your tsconfig.json to have your custom path mappings. Set anything in the root of src to be available with no preceding path reference, and allow any test file to be accessed by using tests/File.tsx:
"target": "esnext",
+ "baseUrl": ".",
+ "paths": {
+ "*": ["src/*"],
+ "tests": ["tests/*"],
+ "@components/*": ["src/components/*"],
+ },
}
  1. Add babel-plugin-module-resolver as a development package to your project:
npm install --save-dev babel-plugin-module-resolver
  1. Finally, configure your babel.config.js (note that the syntax for your babel.config.js is different from your tsconfig.json):
{
plugins: [
+ [
+ 'module-resolver',
+ {
+ root: ['./src'],
+ extensions: ['.ios.js', '.android.js', '.js', '.ts', '.tsx', '.json'],
+ alias: {
+ "tests": ["./tests/"],
+ "@components": "./src/components",
+ }
+ }
+ ]
]
}
Edit this page
Last updated on
- + diff --git a/docs/typescript/index.html b/docs/typescript/index.html index 9751dc33cd8..ad8c20e5af8 100644 --- a/docs/typescript/index.html +++ b/docs/typescript/index.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@
export default Hello;

You can explore the syntax more in the TypeScript playground.

Where to Find Useful Advice

Using Custom Path Aliases with TypeScript

To use custom path aliases with TypeScript, you need to set the path aliases to work from both Babel and TypeScript. Here's how:

  1. Edit your tsconfig.json to have your custom path mappings. Set anything in the root of src to be available with no preceding path reference, and allow any test file to be accessed by using tests/File.tsx:
"target": "esnext",
+ "baseUrl": ".",
+ "paths": {
+ "*": ["src/*"],
+ "tests": ["tests/*"],
+ "@components/*": ["src/components/*"],
+ },
}
  1. Add babel-plugin-module-resolver as a development package to your project:
npm install --save-dev babel-plugin-module-resolver
  1. Finally, configure your babel.config.js (note that the syntax for your babel.config.js is different from your tsconfig.json):
{
plugins: [
+ [
+ 'module-resolver',
+ {
+ root: ['./src'],
+ extensions: ['.ios.js', '.android.js', '.js', '.ts', '.tsx', '.json'],
+ alias: {
+ "tests": ["./tests/"],
+ "@components": "./src/components",
+ }
+ }
+ ]
]
}
Edit this page
Last updated on
- + diff --git a/docs/upgrading.html b/docs/upgrading.html index 53a03c08d2b..b1324469d46 100644 --- a/docs/upgrading.html +++ b/docs/upgrading.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Upgrading to new React Native versions

Upgrading to new versions of React Native will give you access to more APIs, views, developer tools and other goodies. Upgrading requires a small amount of effort, but we try to make it straightforward for you.

Expo projects

Upgrading your Expo project to a new version of React Native requires updating the react-native, react, and expo package versions in your package.json file. Please refer to this list to find out what versions are supported. You will also need to set the correct sdkVersion in your app.json file.

See the Upgrading Expo SDK Walkthrough for up-to-date information about upgrading your project.

React Native projects

Because typical React Native projects are essentially made up of an Android project, an iOS project, and a JavaScript project, upgrading can be rather tricky. There's currently two ways for upgrading your React Native project: by using React Native CLI or manually with Upgrade Helper.

React Native CLI

The React Native CLI comes with upgrade command that provides a one-step operation to upgrade the source files with a minimum of conflicts, it internally uses rn-diff-purge project to find out which files need to be created, removed or modified.

1. Run the upgrade command

The upgrade command works on top of Git by using git apply with 3-way merge, therefore it's required to use Git in order for this to work, if you don't use Git but still want to use this solution then you can check out how to do it in the Troubleshooting section.

Run the following command to start the process of upgrading to the latest version:

npx react-native upgrade

You may specify a React Native version by passing an argument, e.g. to upgrade to 0.61.0-rc.0 run:

npx react-native upgrade 0.61.0-rc.0

The project is upgraded using git apply with 3-way merge, it may happen that you'll need to resolve a few conflicts after it's finished.

2. Resolve the conflicts

Conflicted files include delimiters which make very clear where the changes come from. For example:

13B07F951A680F5B00A75B9A /* Release */ = {
isa = XCBuildConfiguration;
buildSettings = {
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
<<<<<<< ours
CODE_SIGN_IDENTITY = "iPhone Developer";
FRAMEWORK_SEARCH_PATHS = (
"$(inherited)",
"$(PROJECT_DIR)/HockeySDK.embeddedframework",
"$(PROJECT_DIR)/HockeySDK-iOS/HockeySDK.embeddedframework",
);
=======
CURRENT_PROJECT_VERSION = 1;
>>>>>>> theirs
HEADER_SEARCH_PATHS = (
"$(inherited)",
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include,
"$(SRCROOT)/../node_modules/react-native/React/**",
"$(SRCROOT)/../node_modules/react-native-code-push/ios/CodePush/**",
);

You can think of "ours" as "your team" and "theirs" as "the React Native development team".

Upgrade Helper

The Upgrade Helper is a web tool to help you out when upgrading your apps by providing the full set of changes happening between any two versions. It also shows comments on specific files to help understanding why that change is needed.

1. Select the versions

You first need to select from and to which version you wish to upgrade, by default the latest major versions are selected. After selecting you can click the button "Show me how to upgrade".

💡 Major updates will show an "useful content" section on the top with links to help you out when upgrading.

2. Upgrade dependencies

The first file that is shown is the package.json, it's good to update the dependencies that are showing in there. For example, if react-native and react appears as changes then you can install it in your project by running yarn add:

# {{VERSION}} and {{REACT_VERSION}} are the release versions showing in the diff
yarn add react-native@{{VERSION}}
yarn add react@{{REACT_VERSION}}

3. Upgrade your project files

The new release may contain updates to other files that are generated when you run npx react-native init, those files are listed after the package.json in the Upgrade Helper page. If there aren't other changes then you only need to rebuild the project to continue developing.

In case there are changes then you can either update them manually by copying and pasting from the changes in the page or you can do it with the React Native CLI upgrade command by running:

npx react-native upgrade

This will check your files against the latest template and perform the following:

  • If there is a new file in the template, it is created.
  • If a file in the template is identical to your file, it is skipped.
  • If a file is different in your project than the template, you will be prompted; you have options to keep your file or overwrite it with the template version.

Some upgrades won't be done automatically with the React Native CLI and require manual work, e.g. 0.28 to 0.29, or 0.56 to 0.57. Make sure to check the release notes when upgrading so that you can identify any manual changes your particular project may require.

Troubleshooting

I want to upgrade with React Native CLI but I don't use Git

While your project does not have to be handled by the Git versioning system -- you can use Mercurial, SVN, or nothing -- you will still need to install Git on your system in order to use npx react-native upgrade. Git will also need to be available in the PATH. If your project doesn't use Git, initialize it and commit:

git init # Initialize a Git repository
git add . # Stage all the current files
git commit -m "Upgrade react-native" # Save the current files in a commit

After you finish upgrading you may remove the .git directory.

I have done all the changes but my app is still using an old version

These sort of errors are usually related to caching, it's recommended to install react-native-clean-project to clear all your project's cache and then you can run it again.

Edit this page
Last updated on
- + diff --git a/docs/upgrading/index.html b/docs/upgrading/index.html index 53a03c08d2b..b1324469d46 100644 --- a/docs/upgrading/index.html +++ b/docs/upgrading/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Upgrading to new React Native versions

Upgrading to new versions of React Native will give you access to more APIs, views, developer tools and other goodies. Upgrading requires a small amount of effort, but we try to make it straightforward for you.

Expo projects

Upgrading your Expo project to a new version of React Native requires updating the react-native, react, and expo package versions in your package.json file. Please refer to this list to find out what versions are supported. You will also need to set the correct sdkVersion in your app.json file.

See the Upgrading Expo SDK Walkthrough for up-to-date information about upgrading your project.

React Native projects

Because typical React Native projects are essentially made up of an Android project, an iOS project, and a JavaScript project, upgrading can be rather tricky. There's currently two ways for upgrading your React Native project: by using React Native CLI or manually with Upgrade Helper.

React Native CLI

The React Native CLI comes with upgrade command that provides a one-step operation to upgrade the source files with a minimum of conflicts, it internally uses rn-diff-purge project to find out which files need to be created, removed or modified.

1. Run the upgrade command

The upgrade command works on top of Git by using git apply with 3-way merge, therefore it's required to use Git in order for this to work, if you don't use Git but still want to use this solution then you can check out how to do it in the Troubleshooting section.

Run the following command to start the process of upgrading to the latest version:

npx react-native upgrade

You may specify a React Native version by passing an argument, e.g. to upgrade to 0.61.0-rc.0 run:

npx react-native upgrade 0.61.0-rc.0

The project is upgraded using git apply with 3-way merge, it may happen that you'll need to resolve a few conflicts after it's finished.

2. Resolve the conflicts

Conflicted files include delimiters which make very clear where the changes come from. For example:

13B07F951A680F5B00A75B9A /* Release */ = {
isa = XCBuildConfiguration;
buildSettings = {
ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
<<<<<<< ours
CODE_SIGN_IDENTITY = "iPhone Developer";
FRAMEWORK_SEARCH_PATHS = (
"$(inherited)",
"$(PROJECT_DIR)/HockeySDK.embeddedframework",
"$(PROJECT_DIR)/HockeySDK-iOS/HockeySDK.embeddedframework",
);
=======
CURRENT_PROJECT_VERSION = 1;
>>>>>>> theirs
HEADER_SEARCH_PATHS = (
"$(inherited)",
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include,
"$(SRCROOT)/../node_modules/react-native/React/**",
"$(SRCROOT)/../node_modules/react-native-code-push/ios/CodePush/**",
);

You can think of "ours" as "your team" and "theirs" as "the React Native development team".

Upgrade Helper

The Upgrade Helper is a web tool to help you out when upgrading your apps by providing the full set of changes happening between any two versions. It also shows comments on specific files to help understanding why that change is needed.

1. Select the versions

You first need to select from and to which version you wish to upgrade, by default the latest major versions are selected. After selecting you can click the button "Show me how to upgrade".

💡 Major updates will show an "useful content" section on the top with links to help you out when upgrading.

2. Upgrade dependencies

The first file that is shown is the package.json, it's good to update the dependencies that are showing in there. For example, if react-native and react appears as changes then you can install it in your project by running yarn add:

# {{VERSION}} and {{REACT_VERSION}} are the release versions showing in the diff
yarn add react-native@{{VERSION}}
yarn add react@{{REACT_VERSION}}

3. Upgrade your project files

The new release may contain updates to other files that are generated when you run npx react-native init, those files are listed after the package.json in the Upgrade Helper page. If there aren't other changes then you only need to rebuild the project to continue developing.

In case there are changes then you can either update them manually by copying and pasting from the changes in the page or you can do it with the React Native CLI upgrade command by running:

npx react-native upgrade

This will check your files against the latest template and perform the following:

  • If there is a new file in the template, it is created.
  • If a file in the template is identical to your file, it is skipped.
  • If a file is different in your project than the template, you will be prompted; you have options to keep your file or overwrite it with the template version.

Some upgrades won't be done automatically with the React Native CLI and require manual work, e.g. 0.28 to 0.29, or 0.56 to 0.57. Make sure to check the release notes when upgrading so that you can identify any manual changes your particular project may require.

Troubleshooting

I want to upgrade with React Native CLI but I don't use Git

While your project does not have to be handled by the Git versioning system -- you can use Mercurial, SVN, or nothing -- you will still need to install Git on your system in order to use npx react-native upgrade. Git will also need to be available in the PATH. If your project doesn't use Git, initialize it and commit:

git init # Initialize a Git repository
git add . # Stage all the current files
git commit -m "Upgrade react-native" # Save the current files in a commit

After you finish upgrading you may remove the .git directory.

I have done all the changes but my app is still using an old version

These sort of errors are usually related to caching, it's recommended to install react-native-clean-project to clear all your project's cache and then you can run it again.

Edit this page
Last updated on
- + diff --git a/docs/usecolorscheme.html b/docs/usecolorscheme.html index dea46cce5f1..6cc44edf594 100644 --- a/docs/usecolorscheme.html +++ b/docs/usecolorscheme.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
const MyComponent = () => {
const colorScheme = useColorScheme();
return <Text>useColorScheme(): {colorScheme}</Text>;
};

You can find a complete example that demonstrates the use of this hook alongside a React context to add support for light and dark themes to your application in AppearanceExample.js.

Edit this page
Last updated on
- + diff --git a/docs/usecolorscheme/index.html b/docs/usecolorscheme/index.html index dea46cce5f1..6cc44edf594 100644 --- a/docs/usecolorscheme/index.html +++ b/docs/usecolorscheme/index.html @@ -19,7 +19,7 @@ - + @@ -34,7 +34,7 @@
const MyComponent = () => {
const colorScheme = useColorScheme();
return <Text>useColorScheme(): {colorScheme}</Text>;
};

You can find a complete example that demonstrates the use of this hook alongside a React context to add support for light and dark themes to your application in AppearanceExample.js.

Edit this page
Last updated on
- + diff --git a/docs/usewindowdimensions.html b/docs/usewindowdimensions.html index 39c7892d673..be7932a0330 100644 --- a/docs/usewindowdimensions.html +++ b/docs/usewindowdimensions.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

useWindowDimensions

import { useWindowDimensions } from 'react-native';

useWindowDimensions automatically updates width and height values when screen size changes. You can get your application window's width and height like so:

const windowWidth = useWindowDimensions().width;
const windowHeight = useWindowDimensions().height;

Example

Properties

fontScale

The scale of the font currently used. Some operating systems allow users to scale their font sizes larger or smaller for reading comfort. This property will let you know what is in effect.

useWindowDimensions().fontScale;

height

The height in pixels of the window or screen your app occupies.

useWindowDimensions().height;

scale

The pixel ratio of the device your app is running on.

useWindowDimensions().scale;

A value of 1 indicates PPI/DPI of 96 (76 on some platforms). 2 indicates a Retina or high DPI display.

width

The width in pixels of the window or screen your app occupies.

useWindowDimensions().width;
Edit this page
Last updated on
- + diff --git a/docs/usewindowdimensions/index.html b/docs/usewindowdimensions/index.html index 39c7892d673..be7932a0330 100644 --- a/docs/usewindowdimensions/index.html +++ b/docs/usewindowdimensions/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

useWindowDimensions

import { useWindowDimensions } from 'react-native';

useWindowDimensions automatically updates width and height values when screen size changes. You can get your application window's width and height like so:

const windowWidth = useWindowDimensions().width;
const windowHeight = useWindowDimensions().height;

Example

Properties

fontScale

The scale of the font currently used. Some operating systems allow users to scale their font sizes larger or smaller for reading comfort. This property will let you know what is in effect.

useWindowDimensions().fontScale;

height

The height in pixels of the window or screen your app occupies.

useWindowDimensions().height;

scale

The pixel ratio of the device your app is running on.

useWindowDimensions().scale;

A value of 1 indicates PPI/DPI of 96 (76 on some platforms). 2 indicates a Retina or high DPI display.

width

The width in pixels of the window or screen your app occupies.

useWindowDimensions().width;
Edit this page
Last updated on
- + diff --git a/docs/using-a-listview.html b/docs/using-a-listview.html index 8c5f52bc401..462bfe8249a 100644 --- a/docs/using-a-listview.html +++ b/docs/using-a-listview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Using List Views

React Native provides a suite of components for presenting lists of data. Generally, you'll want to use either FlatList or SectionList.

The FlatList component displays a scrolling list of changing, but similarly structured, data. FlatList works well for long lists of data, where the number of items might change over time. Unlike the more generic ScrollView, the FlatList only renders elements that are currently showing on the screen, not all the elements at once.

The FlatList component requires two props: data and renderItem. data is the source of information for the list. renderItem takes one item from the source and returns a formatted component to render.

This example creates a basic FlatList of hardcoded data. Each item in the data props is rendered as a Text component. The FlatListBasics component then renders the FlatList and all Text components.

If you want to render a set of data broken into logical sections, maybe with section headers, similar to UITableViews on iOS, then a SectionList is the way to go.

One of the most common uses for a list view is displaying data that you fetch from a server. To do that, you will need to learn about networking in React Native.

Edit this page
Last updated on
- + diff --git a/docs/using-a-listview/index.html b/docs/using-a-listview/index.html index 8c5f52bc401..462bfe8249a 100644 --- a/docs/using-a-listview/index.html +++ b/docs/using-a-listview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Using List Views

React Native provides a suite of components for presenting lists of data. Generally, you'll want to use either FlatList or SectionList.

The FlatList component displays a scrolling list of changing, but similarly structured, data. FlatList works well for long lists of data, where the number of items might change over time. Unlike the more generic ScrollView, the FlatList only renders elements that are currently showing on the screen, not all the elements at once.

The FlatList component requires two props: data and renderItem. data is the source of information for the list. renderItem takes one item from the source and returns a formatted component to render.

This example creates a basic FlatList of hardcoded data. Each item in the data props is rendered as a Text component. The FlatListBasics component then renders the FlatList and all Text components.

If you want to render a set of data broken into logical sections, maybe with section headers, similar to UITableViews on iOS, then a SectionList is the way to go.

One of the most common uses for a list view is displaying data that you fetch from a server. To do that, you will need to learn about networking in React Native.

Edit this page
Last updated on
- + diff --git a/docs/using-a-scrollview.html b/docs/using-a-scrollview.html index 9d9b627a22d..b07b8acb1ff 100644 --- a/docs/using-a-scrollview.html +++ b/docs/using-a-scrollview.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Using a ScrollView

The ScrollView is a generic scrolling container that can contain multiple components and views. The scrollable items need not be homogeneous, and you can scroll both vertically and horizontally (by setting the horizontal property).

This example creates a vertical ScrollView with both images and text mixed together.

ScrollViews can be configured to allow paging through views using swiping gestures by using the pagingEnabled props. Swiping horizontally between views can also be implemented on Android using the ViewPager component.

On iOS a ScrollView with a single item can be used to allow the user to zoom content. Set up the maximumZoomScale and minimumZoomScale props and your user will be able to use pinch and expand gestures to zoom in and out.

The ScrollView works best to present a small amount of things of a limited size. All the elements and views of a ScrollView are rendered, even if they are not currently shown on the screen. If you have a long list of more items than can fit on the screen, you should use a FlatList instead. So let's learn about list views next.

Edit this page
Last updated on
- + diff --git a/docs/using-a-scrollview/index.html b/docs/using-a-scrollview/index.html index 9d9b627a22d..b07b8acb1ff 100644 --- a/docs/using-a-scrollview/index.html +++ b/docs/using-a-scrollview/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Using a ScrollView

The ScrollView is a generic scrolling container that can contain multiple components and views. The scrollable items need not be homogeneous, and you can scroll both vertically and horizontally (by setting the horizontal property).

This example creates a vertical ScrollView with both images and text mixed together.

ScrollViews can be configured to allow paging through views using swiping gestures by using the pagingEnabled props. Swiping horizontally between views can also be implemented on Android using the ViewPager component.

On iOS a ScrollView with a single item can be used to allow the user to zoom content. Set up the maximumZoomScale and minimumZoomScale props and your user will be able to use pinch and expand gestures to zoom in and out.

The ScrollView works best to present a small amount of things of a limited size. All the elements and views of a ScrollView are rendered, even if they are not currently shown on the screen. If you have a long list of more items than can fit on the screen, you should use a FlatList instead. So let's learn about list views next.

Edit this page
Last updated on
- + diff --git a/docs/vibration.html b/docs/vibration.html index 98aa08a2dad..df9bf122798 100644 --- a/docs/vibration.html +++ b/docs/vibration.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Vibration

Vibrates the device.

Example

Android apps should request the android.permission.VIBRATE permission by adding <uses-permission android:name="android.permission.VIBRATE"/> to AndroidManifest.xml.

The Vibration API is implemented as a AudioServicesPlaySystemSound(kSystemSoundID_Vibrate) call on iOS.

Reference

Methods

vibrate()

Vibration.vibrate(?pattern: number | Array<number>, ?repeat: boolean)

Triggers a vibration with a fixed duration.

On Android, the vibration duration defaults to 400 milliseconds, and an arbitrary vibration duration can be specified by passing a number as the value for the pattern argument. On iOS, the vibration duration is fixed at roughly 400 milliseconds.

The vibrate() method can take a pattern argument with an array of numbers that represent time in milliseconds. You may set repeat to true to run through the vibration pattern in a loop until cancel() is called.

On Android, the odd indices of the pattern array represent the vibration duration, while the even ones represent the separation time. On iOS, the numbers in the pattern array represent the separation time, as the vibration duration is fixed.

Parameters:

NameTypeRequiredDescriptionPlatform
patternnumberNoVibration duration in milliseconds. Defaults to 400 ms.Android
patternArray of numbersNoVibration pattern as an array of numbers in milliseconds.Android, iOS
repeatbooleanNoRepeat vibration pattern until cancel(), default to false.Android, iOS

cancel()

Vibration.cancel();

Call this to stop vibrating after having invoked vibrate() with repetition enabled.

Edit this page
Last updated on
- + diff --git a/docs/vibration/index.html b/docs/vibration/index.html index 98aa08a2dad..df9bf122798 100644 --- a/docs/vibration/index.html +++ b/docs/vibration/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

Vibration

Vibrates the device.

Example

Android apps should request the android.permission.VIBRATE permission by adding <uses-permission android:name="android.permission.VIBRATE"/> to AndroidManifest.xml.

The Vibration API is implemented as a AudioServicesPlaySystemSound(kSystemSoundID_Vibrate) call on iOS.

Reference

Methods

vibrate()

Vibration.vibrate(?pattern: number | Array<number>, ?repeat: boolean)

Triggers a vibration with a fixed duration.

On Android, the vibration duration defaults to 400 milliseconds, and an arbitrary vibration duration can be specified by passing a number as the value for the pattern argument. On iOS, the vibration duration is fixed at roughly 400 milliseconds.

The vibrate() method can take a pattern argument with an array of numbers that represent time in milliseconds. You may set repeat to true to run through the vibration pattern in a loop until cancel() is called.

On Android, the odd indices of the pattern array represent the vibration duration, while the even ones represent the separation time. On iOS, the numbers in the pattern array represent the separation time, as the vibration duration is fixed.

Parameters:

NameTypeRequiredDescriptionPlatform
patternnumberNoVibration duration in milliseconds. Defaults to 400 ms.Android
patternArray of numbersNoVibration pattern as an array of numbers in milliseconds.Android, iOS
repeatbooleanNoRepeat vibration pattern until cancel(), default to false.Android, iOS

cancel()

Vibration.cancel();

Call this to stop vibrating after having invoked vibrate() with repetition enabled.

Edit this page
Last updated on
- + diff --git a/docs/vibrationios.html b/docs/vibrationios.html index 0d4e6f4930e..0e547db89ee 100644 --- a/docs/vibrationios.html +++ b/docs/vibrationios.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

VibrationIOS

NOTE: VibrationIOS is being deprecated. Use Vibration instead.

The Vibration API is exposed at VibrationIOS.vibrate(). On iOS, calling this function will trigger a one second vibration. The vibration is synchronous so this method will return immediately.

There will be no effect on devices that do not support Vibration, eg. the iOS simulator.

Vibration patterns are currently unsupported.

Methods

Reference

Methods

vibrate()

static vibrate()

@deprecated

Edit this page
Last updated on
- + diff --git a/docs/vibrationios/index.html b/docs/vibrationios/index.html index 0d4e6f4930e..0e547db89ee 100644 --- a/docs/vibrationios/index.html +++ b/docs/vibrationios/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

VibrationIOS

NOTE: VibrationIOS is being deprecated. Use Vibration instead.

The Vibration API is exposed at VibrationIOS.vibrate(). On iOS, calling this function will trigger a one second vibration. The vibration is synchronous so this method will return immediately.

There will be no effect on devices that do not support Vibration, eg. the iOS simulator.

Vibration patterns are currently unsupported.

Methods

Reference

Methods

vibrate()

static vibrate()

@deprecated

Edit this page
Last updated on
- + diff --git a/docs/view-style-props.html b/docs/view-style-props.html index f3bd34bf0dd..2ebcc23ae40 100644 --- a/docs/view-style-props.html +++ b/docs/view-style-props.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

View Style Props

Example

Reference

Props

borderRightColor

TypeRequired
colorNo

backfaceVisibility

TypeRequired
enum('visible', 'hidden')No

borderBottomColor

TypeRequired
colorNo

borderBottomEndRadius

TypeRequired
numberNo

borderBottomLeftRadius

TypeRequired
numberNo

borderBottomRightRadius

TypeRequired
numberNo

borderBottomStartRadius

TypeRequired
numberNo

borderBottomWidth

TypeRequired
numberNo

borderColor

TypeRequired
colorNo

borderEndColor

TypeRequired
colorNo

borderLeftColor

TypeRequired
colorNo

borderLeftWidth

TypeRequired
numberNo

borderRadius

If the rounded border is not visible, try applying overflow: 'hidden' as well.

TypeRequired
numberNo

backgroundColor

TypeRequired
colorNo

borderRightWidth

TypeRequired
numberNo

borderStartColor

TypeRequired
colorNo

borderStyle

TypeRequired
enum('solid', 'dotted', 'dashed')No

borderTopColor

TypeRequired
colorNo

borderTopEndRadius

TypeRequired
numberNo

borderTopLeftRadius

TypeRequired
numberNo

borderTopRightRadius

TypeRequired
numberNo

borderTopStartRadius

TypeRequired
numberNo

borderTopWidth

TypeRequired
numberNo

borderWidth

TypeRequired
numberNo

opacity

TypeRequired
numberNo

elevation

(Android-only) Sets the elevation of a view, using Android's underlying elevation API. This adds a drop shadow to the item and affects z-order for overlapping views. Only supported on Android 5.0+, has no effect on earlier versions.

TypeRequiredPlatform
numberNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/view-style-props/index.html b/docs/view-style-props/index.html index f3bd34bf0dd..2ebcc23ae40 100644 --- a/docs/view-style-props/index.html +++ b/docs/view-style-props/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

View Style Props

Example

Reference

Props

borderRightColor

TypeRequired
colorNo

backfaceVisibility

TypeRequired
enum('visible', 'hidden')No

borderBottomColor

TypeRequired
colorNo

borderBottomEndRadius

TypeRequired
numberNo

borderBottomLeftRadius

TypeRequired
numberNo

borderBottomRightRadius

TypeRequired
numberNo

borderBottomStartRadius

TypeRequired
numberNo

borderBottomWidth

TypeRequired
numberNo

borderColor

TypeRequired
colorNo

borderEndColor

TypeRequired
colorNo

borderLeftColor

TypeRequired
colorNo

borderLeftWidth

TypeRequired
numberNo

borderRadius

If the rounded border is not visible, try applying overflow: 'hidden' as well.

TypeRequired
numberNo

backgroundColor

TypeRequired
colorNo

borderRightWidth

TypeRequired
numberNo

borderStartColor

TypeRequired
colorNo

borderStyle

TypeRequired
enum('solid', 'dotted', 'dashed')No

borderTopColor

TypeRequired
colorNo

borderTopEndRadius

TypeRequired
numberNo

borderTopLeftRadius

TypeRequired
numberNo

borderTopRightRadius

TypeRequired
numberNo

borderTopStartRadius

TypeRequired
numberNo

borderTopWidth

TypeRequired
numberNo

borderWidth

TypeRequired
numberNo

opacity

TypeRequired
numberNo

elevation

(Android-only) Sets the elevation of a view, using Android's underlying elevation API. This adds a drop shadow to the item and affects z-order for overlapping views. Only supported on Android 5.0+, has no effect on earlier versions.

TypeRequiredPlatform
numberNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/view.html b/docs/view.html index 312b1efa73c..e420328470f 100644 --- a/docs/view.html +++ b/docs/view.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

View

The most fundamental component for building a UI, View is a container that supports layout with flexbox, style, some touch handling, and accessibility controls. View maps directly to the native view equivalent on whatever platform React Native is running on, whether that is a UIView, <div>, android.view, etc.

View is designed to be nested inside other views and can have 0 to many children of any type.

This example creates a View that wraps two boxes with color and a text component in a row with padding.

Views are designed to be used with StyleSheet for clarity and performance, although inline styles are also supported.

Synthetic Touch Events

For View responder props (e.g., onResponderMove), the synthetic touch event passed to them are in form of PressEvent.

Reference

Props

onStartShouldSetResponder

Does this view want to become responder on the start of a touch?

View.props.onStartShouldSetResponder: (event) => [true | false], where event is a PressEvent.

TypeRequired
functionNo

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

  • 'none' - Used when the element has no role.
  • 'button' - Used when the element should be treated as a button.
  • 'link' - Used when the element should be treated as a link.
  • 'search' - Used when the text field element should also be treated as a search field.
  • 'image' - Used when the element should be treated as an image. Can be combined with button or link, for example.
  • 'keyboardkey' - Used when the element acts as a keyboard key.
  • 'text' - Used when the element should be treated as static text that cannot change.
  • 'adjustable' - Used when an element can be "adjusted" (e.g. a slider).
  • 'imagebutton' - Used when the element should be treated as a button and is also an image.
  • 'header' - Used when an element acts as a header for a content section (e.g. the title of a navigation bar).
  • 'summary' - Used when an element can be used to provide a quick summary of current conditions in the app when the app first launches.
  • 'alert' - Used when an element contains important text to be presented to the user.
  • 'checkbox' - Used when an element represents a checkbox which can be checked, unchecked, or have mixed checked state.
  • 'combobox' - Used when an element represents a combo box, which allows the user to select among several choices.
  • 'menu' - Used when the component is a menu of choices.
  • 'menubar' - Used when a component is a container of multiple menus.
  • 'menuitem' - Used to represent an item within a menu.
  • 'progressbar' - Used to represent a component which indicates progress of a task.
  • 'radio' - Used to represent a radio button.
  • 'radiogroup' - Used to represent a group of radio buttons.
  • 'scrollbar' - Used to represent a scroll bar.
  • 'spinbutton' - Used to represent a button which opens a list of choices.
  • 'switch' - Used to represent a switch which can be turned on and off.
  • 'tab' - Used to represent a tab.
  • 'tablist' - Used to represent a list of tabs.
  • 'timer' - Used to represent a timer.
  • 'toolbar' - Used to represent a tool bar (a container of action buttons or components).
TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

accessibilityValue

Represents the current value of a component. It can be a textual description of a component's value, or for range-based components, such as sliders and progress bars, it contains range information (minimum, current, and maximum).

See the Accessibility guide for more information.

TypeRequired
object: {min: number, max: number, now: number, text: string}No

accessibilityActions

Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The accessibilityActions property should contain a list of action objects. Each action object should contain the field name and label.

See the Accessibility guide for more information.

TypeRequired
arrayNo

onAccessibilityAction

Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform.

See the Accessibility guide for more information.

TypeRequired
functionNo

onAccessibilityTap

When accessible is true, the system will try to invoke this function when the user performs accessibility tap gesture.

TypeRequired
functionNo

onMagicTap

When accessible is true, the system will invoke this function when the user performs the magic tap gesture.

TypeRequiredPlatform
functionNoiOS

onAccessibilityEscape

When accessible is true, the system will invoke this function when the user performs the escape gesture.

TypeRequiredPlatform
functionNoiOS

accessibilityViewIsModal

A value indicating whether VoiceOver should ignore the elements within views that are siblings of the receiver. Default is false.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityElementsHidden

A value indicating whether the accessibility elements contained within this accessibility element are hidden. Default is false.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityIgnoresInvertColors

A value indicating this view should or should not be inverted when color inversion is turned on. A value of true will tell the view to not be inverted even if color inversion is turned on.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityLiveRegion

Indicates to accessibility services whether the user should be notified when this view changes. Works for Android API >= 19 only. Possible values:

  • 'none' - Accessibility services should not announce changes to this view.
  • 'polite'- Accessibility services should announce changes to this view.
  • 'assertive' - Accessibility services should interrupt ongoing speech to immediately announce changes to this view.

See the Android View docs for reference.

TypeRequiredPlatform
enum('none', 'polite', 'assertive')NoAndroid

importantForAccessibility

Controls how view is important for accessibility which is if it fires accessibility events and if it is reported to accessibility services that query the screen. Works for Android only.

Possible values:

  • 'auto' - The system determines whether the view is important for accessibility - default (recommended).
  • 'yes' - The view is important for accessibility.
  • 'no' - The view is not important for accessibility.
  • 'no-hide-descendants' - The view is not important for accessibility, nor are any of its descendant views.

See the Android importantForAccessibility docs for reference.

TypeRequiredPlatform
enum('auto', 'yes', 'no', 'no-hide-descendants')NoAndroid

hitSlop

This defines how far a touch event can start away from the view. Typical interface guidelines recommend touch targets that are at least 30 - 40 points/density-independent pixels.

For example, if a touchable view has a height of 20 the touchable height can be extended to 40 with hitSlop={{top: 10, bottom: 10, left: 0, right: 0}}

The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

nativeID

Used to locate this view from native classes.

This disables the 'layout-only view removal' optimization for this view!

TypeRequired
stringNo

onLayout

Invoked on mount and layout changes with:

{nativeEvent: { layout: {x, y, width, height}}}

This event is fired immediately once the layout has been calculated, but the new layout may not yet be reflected on the screen at the time the event is received, especially if a layout animation is in progress.

TypeRequired
functionNo

onMoveShouldSetResponder

Does this view want to "claim" touch responsiveness? This is called for every touch move on the View when it is not the responder.

View.props.onMoveShouldSetResponder: (event) => [true | false], where event is a PressEvent.

TypeRequired
functionNo

onMoveShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a move, it should have this handler which returns true.

View.props.onMoveShouldSetResponderCapture: (event) => [true | false], where event is a PressEvent.

TypeRequired
functionNo

onResponderGrant

The View is now responding for touch events. This is the time to highlight and show the user what is happening.

View.props.onResponderGrant: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderMove

The user is moving their finger.

View.props.onResponderMove: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderReject

Another responder is already active and will not release it to that View asking to be the responder.

View.props.onResponderReject: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderRelease

Fired at the end of the touch.

View.props.onResponderRelease: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderTerminate

The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS)

View.props.onResponderTerminate: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderTerminationRequest

Some other View wants to become responder and is asking this View to release its responder. Returning true allows its release.

View.props.onResponderTerminationRequest: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onStartShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a touch start, it should have this handler which returns true.

View.props.onStartShouldSetResponderCapture: (event) => [true | false], where event is a PressEvent.

TypeRequired
functionNo

pointerEvents

Controls whether the View can be the target of touch events.

  • 'auto': The View can be the target of touch events.
  • 'none': The View is never the target of touch events.
  • 'box-none': The View is never the target of touch events but its subviews can be. It behaves like if the view had the following classes in CSS:
.box-none {
pointer-events: none;
}
.box-none * {
pointer-events: auto;
}
  • 'box-only': The view can be the target of touch events but its subviews cannot be. It behaves like if the view had the following classes in CSS:
.box-only {
pointer-events: auto;
}
.box-only * {
pointer-events: none;
}

Since pointerEvents does not affect layout/appearance, and we are already deviating from the spec by adding additional modes, we opt to not include pointerEvents on style. On some platforms, we would need to implement it as a className anyways. Using style or not is an implementation detail of the platform.

TypeRequired
enum('box-none', 'none', 'box-only', 'auto')No

removeClippedSubviews

This is a reserved performance property exposed by RCTView and is useful for scrolling content when there are many subviews, most of which are offscreen. For this property to be effective, it must be applied to a view that contains many subviews that extend outside its bound. The subviews must also have overflow: hidden, as should the containing view (or one of its superviews).

TypeRequired
boolNo

style

TypeRequired
view stylesNo

testID

Used to locate this view in end-to-end tests.

This disables the 'layout-only view removal' optimization for this view!

TypeRequired
stringNo

collapsable

Views that are only used to layout their children or otherwise don't draw anything may be automatically removed from the native hierarchy as an optimization. Set this property to false to disable this optimization and ensure that this View exists in the native view hierarchy.

TypeRequiredPlatform
boolNoAndroid

needsOffscreenAlphaCompositing

Whether this View needs to rendered offscreen and composited with an alpha in order to preserve 100% correct colors and blending behavior. The default (false) falls back to drawing the component and its children with an alpha applied to the paint used to draw each element instead of rendering the full component offscreen and compositing it back with an alpha value. This default may be noticeable and undesired in the case where the View you are setting an opacity on has multiple overlapping elements (e.g. multiple overlapping Views, or text and a background).

Rendering offscreen to preserve correct alpha behavior is extremely expensive and hard to debug for non-native developers, which is why it is not turned on by default. If you do need to enable this property for an animation, consider combining it with renderToHardwareTextureAndroid if the view contents are static (i.e. it doesn't need to be redrawn each frame). If that property is enabled, this View will be rendered off-screen once, saved in a hardware texture, and then composited onto the screen with an alpha each frame without having to switch rendering targets on the GPU.

TypeRequired
boolNo

renderToHardwareTextureAndroid

Whether this View should render itself (and all of its children) into a single hardware texture on the GPU.

On Android, this is useful for animations and interactions that only modify opacity, rotation, translation, and/or scale: in those cases, the view doesn't have to be redrawn and display lists don't need to be re-executed. The texture can be re-used and re-composited with different parameters. The downside is that this can use up limited video memory, so this prop should be set back to false at the end of the interaction/animation.

TypeRequiredPlatform
boolNoAndroid

shouldRasterizeIOS

Whether this View should be rendered as a bitmap before compositing.

On iOS, this is useful for animations and interactions that do not modify this component's dimensions nor its children; for example, when translating the position of a static view, rasterization allows the renderer to reuse a cached bitmap of a static view and quickly composite it during each frame.

Rasterization incurs an off-screen drawing pass and the bitmap consumes memory. Test and measure when using this property.

TypeRequiredPlatform
boolNoiOS

nextFocusDown

Designates the next view to receive focus when the user navigates down. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusForward

Designates the next view to receive focus when the user navigates forward. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusLeft

Designates the next view to receive focus when the user navigates left. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusRight

Designates the next view to receive focus when the user navigates right. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusUp

Designates the next view to receive focus when the user navigates up. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

focusable

Whether this View should be focusable with a non-touch input device, eg. receive focus with a hardware keyboard.

TypeRequiredPlatform
booleanNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/view/index.html b/docs/view/index.html index 312b1efa73c..e420328470f 100644 --- a/docs/view/index.html +++ b/docs/view/index.html @@ -19,7 +19,7 @@ - + @@ -33,7 +33,7 @@

View

The most fundamental component for building a UI, View is a container that supports layout with flexbox, style, some touch handling, and accessibility controls. View maps directly to the native view equivalent on whatever platform React Native is running on, whether that is a UIView, <div>, android.view, etc.

View is designed to be nested inside other views and can have 0 to many children of any type.

This example creates a View that wraps two boxes with color and a text component in a row with padding.

Views are designed to be used with StyleSheet for clarity and performance, although inline styles are also supported.

Synthetic Touch Events

For View responder props (e.g., onResponderMove), the synthetic touch event passed to them are in form of PressEvent.

Reference

Props

onStartShouldSetResponder

Does this view want to become responder on the start of a touch?

View.props.onStartShouldSetResponder: (event) => [true | false], where event is a PressEvent.

TypeRequired
functionNo

accessible

When true, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.

TypeRequired
boolNo

accessibilityLabel

Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the Text nodes separated by space.

TypeRequired
stringNo

accessibilityHint

An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.

TypeRequired
stringNo

accessibilityRole

accessibilityRole communicates the purpose of a component to the user of an assistive technology.

accessibilityRole can be one of the following:

  • 'none' - Used when the element has no role.
  • 'button' - Used when the element should be treated as a button.
  • 'link' - Used when the element should be treated as a link.
  • 'search' - Used when the text field element should also be treated as a search field.
  • 'image' - Used when the element should be treated as an image. Can be combined with button or link, for example.
  • 'keyboardkey' - Used when the element acts as a keyboard key.
  • 'text' - Used when the element should be treated as static text that cannot change.
  • 'adjustable' - Used when an element can be "adjusted" (e.g. a slider).
  • 'imagebutton' - Used when the element should be treated as a button and is also an image.
  • 'header' - Used when an element acts as a header for a content section (e.g. the title of a navigation bar).
  • 'summary' - Used when an element can be used to provide a quick summary of current conditions in the app when the app first launches.
  • 'alert' - Used when an element contains important text to be presented to the user.
  • 'checkbox' - Used when an element represents a checkbox which can be checked, unchecked, or have mixed checked state.
  • 'combobox' - Used when an element represents a combo box, which allows the user to select among several choices.
  • 'menu' - Used when the component is a menu of choices.
  • 'menubar' - Used when a component is a container of multiple menus.
  • 'menuitem' - Used to represent an item within a menu.
  • 'progressbar' - Used to represent a component which indicates progress of a task.
  • 'radio' - Used to represent a radio button.
  • 'radiogroup' - Used to represent a group of radio buttons.
  • 'scrollbar' - Used to represent a scroll bar.
  • 'spinbutton' - Used to represent a button which opens a list of choices.
  • 'switch' - Used to represent a switch which can be turned on and off.
  • 'tab' - Used to represent a tab.
  • 'tablist' - Used to represent a list of tabs.
  • 'timer' - Used to represent a timer.
  • 'toolbar' - Used to represent a tool bar (a container of action buttons or components).
TypeRequired
stringNo

accessibilityState

Describes the current state of a component to the user of an assistive technology.

See the Accessibility guide for more information.

TypeRequired
object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool}No

accessibilityValue

Represents the current value of a component. It can be a textual description of a component's value, or for range-based components, such as sliders and progress bars, it contains range information (minimum, current, and maximum).

See the Accessibility guide for more information.

TypeRequired
object: {min: number, max: number, now: number, text: string}No

accessibilityActions

Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The accessibilityActions property should contain a list of action objects. Each action object should contain the field name and label.

See the Accessibility guide for more information.

TypeRequired
arrayNo

onAccessibilityAction

Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform.

See the Accessibility guide for more information.

TypeRequired
functionNo

onAccessibilityTap

When accessible is true, the system will try to invoke this function when the user performs accessibility tap gesture.

TypeRequired
functionNo

onMagicTap

When accessible is true, the system will invoke this function when the user performs the magic tap gesture.

TypeRequiredPlatform
functionNoiOS

onAccessibilityEscape

When accessible is true, the system will invoke this function when the user performs the escape gesture.

TypeRequiredPlatform
functionNoiOS

accessibilityViewIsModal

A value indicating whether VoiceOver should ignore the elements within views that are siblings of the receiver. Default is false.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityElementsHidden

A value indicating whether the accessibility elements contained within this accessibility element are hidden. Default is false.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityIgnoresInvertColors

A value indicating this view should or should not be inverted when color inversion is turned on. A value of true will tell the view to not be inverted even if color inversion is turned on.

See the Accessibility guide for more information.

TypeRequiredPlatform
boolNoiOS

accessibilityLiveRegion

Indicates to accessibility services whether the user should be notified when this view changes. Works for Android API >= 19 only. Possible values:

  • 'none' - Accessibility services should not announce changes to this view.
  • 'polite'- Accessibility services should announce changes to this view.
  • 'assertive' - Accessibility services should interrupt ongoing speech to immediately announce changes to this view.

See the Android View docs for reference.

TypeRequiredPlatform
enum('none', 'polite', 'assertive')NoAndroid

importantForAccessibility

Controls how view is important for accessibility which is if it fires accessibility events and if it is reported to accessibility services that query the screen. Works for Android only.

Possible values:

  • 'auto' - The system determines whether the view is important for accessibility - default (recommended).
  • 'yes' - The view is important for accessibility.
  • 'no' - The view is not important for accessibility.
  • 'no-hide-descendants' - The view is not important for accessibility, nor are any of its descendant views.

See the Android importantForAccessibility docs for reference.

TypeRequiredPlatform
enum('auto', 'yes', 'no', 'no-hide-descendants')NoAndroid

hitSlop

This defines how far a touch event can start away from the view. Typical interface guidelines recommend touch targets that are at least 30 - 40 points/density-independent pixels.

For example, if a touchable view has a height of 20 the touchable height can be extended to 40 with hitSlop={{top: 10, bottom: 10, left: 0, right: 0}}

The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views.

TypeRequired
object: {top: number, left: number, bottom: number, right: number}No

nativeID

Used to locate this view from native classes.

This disables the 'layout-only view removal' optimization for this view!

TypeRequired
stringNo

onLayout

Invoked on mount and layout changes with:

{nativeEvent: { layout: {x, y, width, height}}}

This event is fired immediately once the layout has been calculated, but the new layout may not yet be reflected on the screen at the time the event is received, especially if a layout animation is in progress.

TypeRequired
functionNo

onMoveShouldSetResponder

Does this view want to "claim" touch responsiveness? This is called for every touch move on the View when it is not the responder.

View.props.onMoveShouldSetResponder: (event) => [true | false], where event is a PressEvent.

TypeRequired
functionNo

onMoveShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a move, it should have this handler which returns true.

View.props.onMoveShouldSetResponderCapture: (event) => [true | false], where event is a PressEvent.

TypeRequired
functionNo

onResponderGrant

The View is now responding for touch events. This is the time to highlight and show the user what is happening.

View.props.onResponderGrant: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderMove

The user is moving their finger.

View.props.onResponderMove: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderReject

Another responder is already active and will not release it to that View asking to be the responder.

View.props.onResponderReject: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderRelease

Fired at the end of the touch.

View.props.onResponderRelease: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderTerminate

The responder has been taken from the View. Might be taken by other views after a call to onResponderTerminationRequest, or might be taken by the OS without asking (e.g., happens with control center/ notification center on iOS)

View.props.onResponderTerminate: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onResponderTerminationRequest

Some other View wants to become responder and is asking this View to release its responder. Returning true allows its release.

View.props.onResponderTerminationRequest: (event) => {}, where event is a PressEvent.

TypeRequired
functionNo

onStartShouldSetResponderCapture

If a parent View wants to prevent a child View from becoming responder on a touch start, it should have this handler which returns true.

View.props.onStartShouldSetResponderCapture: (event) => [true | false], where event is a PressEvent.

TypeRequired
functionNo

pointerEvents

Controls whether the View can be the target of touch events.

  • 'auto': The View can be the target of touch events.
  • 'none': The View is never the target of touch events.
  • 'box-none': The View is never the target of touch events but its subviews can be. It behaves like if the view had the following classes in CSS:
.box-none {
pointer-events: none;
}
.box-none * {
pointer-events: auto;
}
  • 'box-only': The view can be the target of touch events but its subviews cannot be. It behaves like if the view had the following classes in CSS:
.box-only {
pointer-events: auto;
}
.box-only * {
pointer-events: none;
}

Since pointerEvents does not affect layout/appearance, and we are already deviating from the spec by adding additional modes, we opt to not include pointerEvents on style. On some platforms, we would need to implement it as a className anyways. Using style or not is an implementation detail of the platform.

TypeRequired
enum('box-none', 'none', 'box-only', 'auto')No

removeClippedSubviews

This is a reserved performance property exposed by RCTView and is useful for scrolling content when there are many subviews, most of which are offscreen. For this property to be effective, it must be applied to a view that contains many subviews that extend outside its bound. The subviews must also have overflow: hidden, as should the containing view (or one of its superviews).

TypeRequired
boolNo

style

TypeRequired
view stylesNo

testID

Used to locate this view in end-to-end tests.

This disables the 'layout-only view removal' optimization for this view!

TypeRequired
stringNo

collapsable

Views that are only used to layout their children or otherwise don't draw anything may be automatically removed from the native hierarchy as an optimization. Set this property to false to disable this optimization and ensure that this View exists in the native view hierarchy.

TypeRequiredPlatform
boolNoAndroid

needsOffscreenAlphaCompositing

Whether this View needs to rendered offscreen and composited with an alpha in order to preserve 100% correct colors and blending behavior. The default (false) falls back to drawing the component and its children with an alpha applied to the paint used to draw each element instead of rendering the full component offscreen and compositing it back with an alpha value. This default may be noticeable and undesired in the case where the View you are setting an opacity on has multiple overlapping elements (e.g. multiple overlapping Views, or text and a background).

Rendering offscreen to preserve correct alpha behavior is extremely expensive and hard to debug for non-native developers, which is why it is not turned on by default. If you do need to enable this property for an animation, consider combining it with renderToHardwareTextureAndroid if the view contents are static (i.e. it doesn't need to be redrawn each frame). If that property is enabled, this View will be rendered off-screen once, saved in a hardware texture, and then composited onto the screen with an alpha each frame without having to switch rendering targets on the GPU.

TypeRequired
boolNo

renderToHardwareTextureAndroid

Whether this View should render itself (and all of its children) into a single hardware texture on the GPU.

On Android, this is useful for animations and interactions that only modify opacity, rotation, translation, and/or scale: in those cases, the view doesn't have to be redrawn and display lists don't need to be re-executed. The texture can be re-used and re-composited with different parameters. The downside is that this can use up limited video memory, so this prop should be set back to false at the end of the interaction/animation.

TypeRequiredPlatform
boolNoAndroid

shouldRasterizeIOS

Whether this View should be rendered as a bitmap before compositing.

On iOS, this is useful for animations and interactions that do not modify this component's dimensions nor its children; for example, when translating the position of a static view, rasterization allows the renderer to reuse a cached bitmap of a static view and quickly composite it during each frame.

Rasterization incurs an off-screen drawing pass and the bitmap consumes memory. Test and measure when using this property.

TypeRequiredPlatform
boolNoiOS

nextFocusDown

Designates the next view to receive focus when the user navigates down. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusForward

Designates the next view to receive focus when the user navigates forward. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusLeft

Designates the next view to receive focus when the user navigates left. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusRight

Designates the next view to receive focus when the user navigates right. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

nextFocusUp

Designates the next view to receive focus when the user navigates up. See the Android documentation.

TypeRequiredPlatform
numberNoAndroid

focusable

Whether this View should be focusable with a non-touch input device, eg. receive focus with a hardware keyboard.

TypeRequiredPlatform
booleanNoAndroid
Edit this page
Last updated on
- + diff --git a/docs/viewpagerandroid.html b/docs/viewpagerandroid.html index 072e0ea9eaa..24ed3fd49b0 100644 --- a/docs/viewpagerandroid.html +++ b/docs/viewpagerandroid.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
const styles = {
...
viewPager: {
flex: 1
},
pageStyle: {
alignItems: 'center',
padding: 20,
}
}

Reference

Props

Inherits View Props.

initialPage

Index of initial page that should be selected. Use setPage method to update the page, and onPageSelected to monitor page changes

TypeRequired
numberNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

TypeRequired
enum('none', 'on-drag')No

onPageScroll

Executed when transitioning between pages (either because of animation for the requested page change or when user is swiping/dragging between pages) The event.nativeEvent object for this callback will carry following data:

TypeRequired
functionNo

onPageScrollStateChanged

Function called when the page scrolling state has changed. The page scrolling state can be in 3 states:

TypeRequired
functionNo

onPageSelected

This callback will be called once ViewPager finish navigating to selected page (when user swipes between pages). The event.nativeEvent object passed to this callback will have following fields:

TypeRequired
functionNo

pageMargin

Blank space to show between pages. This is only visible while scrolling, pages are still edge-to-edge.

TypeRequired
numberNo

peekEnabled

Whether enable showing peekFraction or not. If this is true, the preview of last and next page will show in current screen. Defaults to false.

TypeRequired
boolNo

scrollEnabled

When false, the content does not scroll. The default value is true.

TypeRequired
boolNo

setPage

A helper function to scroll to a specific page in the ViewPager. The transition between pages will be animated.

TypeRequired
NumberYes

setPageWithoutAnimation

A helper function to scroll to a specific page in the ViewPager. The transition between pages will not be animated.

TypeRequired
NumberYes

Type Definitions

ViewPagerScrollState

Type
\$Enum

Constants:

ValueDescription
idle
dragging
settling
Edit this page
Last updated on
- + diff --git a/docs/viewpagerandroid/index.html b/docs/viewpagerandroid/index.html index 072e0ea9eaa..24ed3fd49b0 100644 --- a/docs/viewpagerandroid/index.html +++ b/docs/viewpagerandroid/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
const styles = {
...
viewPager: {
flex: 1
},
pageStyle: {
alignItems: 'center',
padding: 20,
}
}

Reference

Props

Inherits View Props.

initialPage

Index of initial page that should be selected. Use setPage method to update the page, and onPageSelected to monitor page changes

TypeRequired
numberNo

keyboardDismissMode

Determines whether the keyboard gets dismissed in response to a drag.

TypeRequired
enum('none', 'on-drag')No

onPageScroll

Executed when transitioning between pages (either because of animation for the requested page change or when user is swiping/dragging between pages) The event.nativeEvent object for this callback will carry following data:

TypeRequired
functionNo

onPageScrollStateChanged

Function called when the page scrolling state has changed. The page scrolling state can be in 3 states:

TypeRequired
functionNo

onPageSelected

This callback will be called once ViewPager finish navigating to selected page (when user swipes between pages). The event.nativeEvent object passed to this callback will have following fields:

TypeRequired
functionNo

pageMargin

Blank space to show between pages. This is only visible while scrolling, pages are still edge-to-edge.

TypeRequired
numberNo

peekEnabled

Whether enable showing peekFraction or not. If this is true, the preview of last and next page will show in current screen. Defaults to false.

TypeRequired
boolNo

scrollEnabled

When false, the content does not scroll. The default value is true.

TypeRequired
boolNo

setPage

A helper function to scroll to a specific page in the ViewPager. The transition between pages will be animated.

TypeRequired
NumberYes

setPageWithoutAnimation

A helper function to scroll to a specific page in the ViewPager. The transition between pages will not be animated.

TypeRequired
NumberYes

Type Definitions

ViewPagerScrollState

Type
\$Enum

Constants:

ValueDescription
idle
dragging
settling
Edit this page
Last updated on
- + diff --git a/docs/virtualizedlist.html b/docs/virtualizedlist.html index deeca9c8662..34cdc5f9da1 100644 --- a/docs/virtualizedlist.html +++ b/docs/virtualizedlist.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@

scrollToIndex()

scrollToIndex((params: object));

Valid params consist of:

scrollToItem()

scrollToItem((params: object));

Valid params consist of:

scrollToOffset()

scrollToOffset((params: object));

Scroll to a specific content pixel offset in the list.

Param offset expects the offset to scroll to. In case of horizontal is true, the offset is the x-value, in any other case the offset is the y-value.

Param animated (true by default) defines whether the list should do an animation while scrolling.

recordInteraction()

recordInteraction();

flashScrollIndicators()

flashScrollIndicators();

getScrollResponder()

getScrollResponder () => ?ScrollResponderType;

Provides a handle to the underlying scroll responder. Note that this._scrollRef might not be a ScrollView, so we need to check that it responds to getScrollResponder before calling it.

getScrollableNode()

getScrollableNode () => ?number;

getScrollRef()

getScrollRef () => | ?React.ElementRef<typeof ScrollView>
| ?React.ElementRef<typeof View>;

setNativeProps()

setNativeProps((props: Object));

getChildContext()

getChildContext () => Object;

The Object returned consist of:

hasMore()

hasMore () => boolean;
Edit this page
Last updated on
- + diff --git a/docs/virtualizedlist/index.html b/docs/virtualizedlist/index.html index deeca9c8662..34cdc5f9da1 100644 --- a/docs/virtualizedlist/index.html +++ b/docs/virtualizedlist/index.html @@ -19,7 +19,7 @@ - + @@ -36,7 +36,7 @@

scrollToIndex()

scrollToIndex((params: object));

Valid params consist of:

scrollToItem()

scrollToItem((params: object));

Valid params consist of:

scrollToOffset()

scrollToOffset((params: object));

Scroll to a specific content pixel offset in the list.

Param offset expects the offset to scroll to. In case of horizontal is true, the offset is the x-value, in any other case the offset is the y-value.

Param animated (true by default) defines whether the list should do an animation while scrolling.

recordInteraction()

recordInteraction();

flashScrollIndicators()

flashScrollIndicators();

getScrollResponder()

getScrollResponder () => ?ScrollResponderType;

Provides a handle to the underlying scroll responder. Note that this._scrollRef might not be a ScrollView, so we need to check that it responds to getScrollResponder before calling it.

getScrollableNode()

getScrollableNode () => ?number;

getScrollRef()

getScrollRef () => | ?React.ElementRef<typeof ScrollView>
| ?React.ElementRef<typeof View>;

setNativeProps()

setNativeProps((props: Object));

getChildContext()

getChildContext () => Object;

The Object returned consist of:

hasMore()

hasMore () => boolean;
Edit this page
Last updated on
- + diff --git a/docs/webview.html b/docs/webview.html index 45821395b13..572e3822b26 100644 --- a/docs/webview.html +++ b/docs/webview.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
class MyInlineWeb extends Component {
render() {
return (
<WebView
originWhitelist={['*']}
source={{ html: '<h1>Hello world</h1>' }}
/>
);
}
}

You can use this component to navigate back and forth in the web view's history and configure various properties for the web content.

On iOS, the useWebKit prop can be used to opt into a WKWebView-backed implementation.

Security Warning: Currently, onMessage and postMessage do not allow specifying an origin. This can lead to cross-site scripting attacks if an unexpected document is loaded within a WebView instance. Please refer to the MDN documentation for Window.postMessage() for more details on the security implications of this.

Reference

Props

Inherits View Props.

source

Loads static HTML or a URI (with optional headers) in the WebView. Note that static HTML will require setting originWhitelist to ["*"].

The object passed to source can have either of the following shapes:

Load uri

Static HTML

TypeRequired
objectNo

automaticallyAdjustContentInsets

Controls whether to adjust the content inset for web views that are placed behind a navigation bar, tab bar, or toolbar. The default value is true.

TypeRequired
boolNo

injectJavaScript

Function that accepts a string that will be passed to the WebView and executed immediately as JavaScript.

TypeRequired
functionNo

injectedJavaScript

Set this to provide JavaScript that will be injected into the web page when the view loads.

TypeRequired
stringNo

mediaPlaybackRequiresUserAction

Boolean that determines whether HTML5 audio and video requires the user to tap them before they start playing. The default value is true.

TypeRequired
boolNo

nativeConfig

Override the native component used to render the WebView. Enables a custom native WebView which uses the same JavaScript as the original WebView.

The nativeConfig prop expects an object with the following keys:

TypeRequired
objectNo

onError

Function that is invoked when the WebView load fails.

TypeRequired
functionNo

onLoad

Function that is invoked when the WebView has finished loading.

TypeRequired
functionNo

onLoadEnd

Function that is invoked when the WebView load succeeds or fails.

TypeRequired
functionNo

onLoadStart

Function that is invoked when the WebView starts loading.

TypeRequired
functionNo

onMessage

A function that is invoked when the webview calls window.postMessage. Setting this property will inject a postMessage global into your webview, but will still call pre-existing values of postMessage.

window.postMessage accepts one argument, data, which will be available on the event object, event.nativeEvent.data. data must be a string.

TypeRequired
functionNo

onNavigationStateChange

Function that is invoked when the WebView loading starts or ends.

TypeRequired
functionNo

originWhitelist

List of origin strings to allow being navigated to. The strings allow wildcards and get matched against only the origin (not the full URL). If the user taps to navigate to a new page but the new page is not in this safelist, the URL will be handled by the OS. The default safelistlisted origins are "http://*" and "https://*".

TypeRequired
array of stringsNo

renderError

Function that returns a view to show if there's an error.

TypeRequired
functionNo

renderLoading

Function that returns a loading indicator. The startInLoadingState prop must be set to true in order to use this prop.

TypeRequired
functionNo

scalesPageToFit

Boolean that controls whether the web content is scaled to fit the view and enables the user to change the scale. The default value is true.

On iOS, when useWebKit=true, this prop will not work.

TypeRequired
boolNo

onShouldStartLoadWithRequest

Function that allows custom handling of any web view requests. Return true from the function to continue loading the request and false to stop loading.

TypeRequiredPlatform
functionNoiOS

startInLoadingState

Boolean value that forces the WebView to show the loading view on the first load. This prop must be set to true in order for the renderLoading prop to work.

TypeRequired
boolNo

decelerationRate

A floating-point number that determines how quickly the scroll view decelerates after the user lifts their finger. You may also use the string shortcuts "normal" and "fast" which match the underlying iOS settings for UIScrollViewDecelerationRateNormal and UIScrollViewDecelerationRateFast respectively:

TypeRequiredPlatform
numberNoiOS

domStorageEnabled

Boolean value to control whether DOM Storage is enabled. Used only in Android.

TypeRequiredPlatform
boolNoAndroid

javaScriptEnabled

Boolean value to enable JavaScript in the WebView. Used on Android only as JavaScript is enabled by default on iOS. The default value is true.

TypeRequiredPlatform
boolNoAndroid

mixedContentMode

Specifies the mixed content mode. i.e WebView will allow a secure origin to load content from any other origin.

Possible values for mixedContentMode are:

TypeRequiredPlatform
stringNoAndroid

thirdPartyCookiesEnabled

Boolean value to enable third party cookies in the WebView. Used on Android Lollipop and above only as third party cookies are enabled by default on Android Kitkat and below and on iOS. The default value is true.

TypeRequiredPlatform
boolNoAndroid

userAgent

Sets the user-agent for the WebView.

TypeRequiredPlatform
stringNoAndroid

allowsInlineMediaPlayback

Boolean that determines whether HTML5 videos play inline or use the native full-screen controller. The default value is false.

NOTE

In order for video to play inline, not only does this property need to be set to true, but the video element in the HTML document must also include the webkit-playsinline attribute.

TypeRequiredPlatform
boolNoiOS

bounces

Boolean value that determines whether the web view bounces when it reaches the edge of the content. The default value is true.

TypeRequiredPlatform
boolNoiOS

contentInset

The amount by which the web view content is inset from the edges of the scroll view. Defaults to {top: 0, left: 0, bottom: 0, right: 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

dataDetectorTypes

Determines the types of data converted to clickable URLs in the web view's content. By default only phone numbers are detected.

You can provide one type or an array of many types.

Possible values for dataDetectorTypes are:

With the new WebKit implementation, we have three new values:

TypeRequiredPlatform
string, or arrayNoiOS

scrollEnabled

Boolean value that determines whether scrolling is enabled in the WebView. The default value is true.

TypeRequiredPlatform
boolNoiOS

geolocationEnabled

Set whether Geolocation is enabled in the WebView. The default value is false. Used only in Android.

TypeRequiredPlatform
boolNoAndroid

allowUniversalAccessFromFileURLs

Boolean that sets whether JavaScript running in the context of a file scheme URL should be allowed to access content from any origin. Including accessing content from other file scheme URLs. The default value is false.

TypeRequiredPlatform
boolNoAndroid

allowFileAccess

Boolean that sets whether the WebView has access to the file system. The default value is false.

TypeRequiredPlatform
boolNoAndroid

useWebKit

If true, use WKWebView instead of UIWebView.

TypeRequiredPlatform
booleanNoiOS

url

Deprecated. Use the source prop instead.

TypeRequired
stringNo

html

Deprecated. Use the source prop instead.

TypeRequired
stringNo

Methods

extraNativeComponentConfig()

static extraNativeComponentConfig()

goForward()

goForward();

Go forward one page in the web view's history.

goBack()

goBack();

Go back one page in the web view's history.

reload()

reload();

Reloads the current page.

stopLoading()

stopLoading();

Stop loading the current page.

Edit this page
Last updated on
- + diff --git a/docs/webview/index.html b/docs/webview/index.html index 45821395b13..572e3822b26 100644 --- a/docs/webview/index.html +++ b/docs/webview/index.html @@ -19,7 +19,7 @@ - + @@ -35,7 +35,7 @@
class MyInlineWeb extends Component {
render() {
return (
<WebView
originWhitelist={['*']}
source={{ html: '<h1>Hello world</h1>' }}
/>
);
}
}

You can use this component to navigate back and forth in the web view's history and configure various properties for the web content.

On iOS, the useWebKit prop can be used to opt into a WKWebView-backed implementation.

Security Warning: Currently, onMessage and postMessage do not allow specifying an origin. This can lead to cross-site scripting attacks if an unexpected document is loaded within a WebView instance. Please refer to the MDN documentation for Window.postMessage() for more details on the security implications of this.

Reference

Props

Inherits View Props.

source

Loads static HTML or a URI (with optional headers) in the WebView. Note that static HTML will require setting originWhitelist to ["*"].

The object passed to source can have either of the following shapes:

Load uri

Static HTML

TypeRequired
objectNo

automaticallyAdjustContentInsets

Controls whether to adjust the content inset for web views that are placed behind a navigation bar, tab bar, or toolbar. The default value is true.

TypeRequired
boolNo

injectJavaScript

Function that accepts a string that will be passed to the WebView and executed immediately as JavaScript.

TypeRequired
functionNo

injectedJavaScript

Set this to provide JavaScript that will be injected into the web page when the view loads.

TypeRequired
stringNo

mediaPlaybackRequiresUserAction

Boolean that determines whether HTML5 audio and video requires the user to tap them before they start playing. The default value is true.

TypeRequired
boolNo

nativeConfig

Override the native component used to render the WebView. Enables a custom native WebView which uses the same JavaScript as the original WebView.

The nativeConfig prop expects an object with the following keys:

TypeRequired
objectNo

onError

Function that is invoked when the WebView load fails.

TypeRequired
functionNo

onLoad

Function that is invoked when the WebView has finished loading.

TypeRequired
functionNo

onLoadEnd

Function that is invoked when the WebView load succeeds or fails.

TypeRequired
functionNo

onLoadStart

Function that is invoked when the WebView starts loading.

TypeRequired
functionNo

onMessage

A function that is invoked when the webview calls window.postMessage. Setting this property will inject a postMessage global into your webview, but will still call pre-existing values of postMessage.

window.postMessage accepts one argument, data, which will be available on the event object, event.nativeEvent.data. data must be a string.

TypeRequired
functionNo

onNavigationStateChange

Function that is invoked when the WebView loading starts or ends.

TypeRequired
functionNo

originWhitelist

List of origin strings to allow being navigated to. The strings allow wildcards and get matched against only the origin (not the full URL). If the user taps to navigate to a new page but the new page is not in this safelist, the URL will be handled by the OS. The default safelistlisted origins are "http://*" and "https://*".

TypeRequired
array of stringsNo

renderError

Function that returns a view to show if there's an error.

TypeRequired
functionNo

renderLoading

Function that returns a loading indicator. The startInLoadingState prop must be set to true in order to use this prop.

TypeRequired
functionNo

scalesPageToFit

Boolean that controls whether the web content is scaled to fit the view and enables the user to change the scale. The default value is true.

On iOS, when useWebKit=true, this prop will not work.

TypeRequired
boolNo

onShouldStartLoadWithRequest

Function that allows custom handling of any web view requests. Return true from the function to continue loading the request and false to stop loading.

TypeRequiredPlatform
functionNoiOS

startInLoadingState

Boolean value that forces the WebView to show the loading view on the first load. This prop must be set to true in order for the renderLoading prop to work.

TypeRequired
boolNo

decelerationRate

A floating-point number that determines how quickly the scroll view decelerates after the user lifts their finger. You may also use the string shortcuts "normal" and "fast" which match the underlying iOS settings for UIScrollViewDecelerationRateNormal and UIScrollViewDecelerationRateFast respectively:

TypeRequiredPlatform
numberNoiOS

domStorageEnabled

Boolean value to control whether DOM Storage is enabled. Used only in Android.

TypeRequiredPlatform
boolNoAndroid

javaScriptEnabled

Boolean value to enable JavaScript in the WebView. Used on Android only as JavaScript is enabled by default on iOS. The default value is true.

TypeRequiredPlatform
boolNoAndroid

mixedContentMode

Specifies the mixed content mode. i.e WebView will allow a secure origin to load content from any other origin.

Possible values for mixedContentMode are:

TypeRequiredPlatform
stringNoAndroid

thirdPartyCookiesEnabled

Boolean value to enable third party cookies in the WebView. Used on Android Lollipop and above only as third party cookies are enabled by default on Android Kitkat and below and on iOS. The default value is true.

TypeRequiredPlatform
boolNoAndroid

userAgent

Sets the user-agent for the WebView.

TypeRequiredPlatform
stringNoAndroid

allowsInlineMediaPlayback

Boolean that determines whether HTML5 videos play inline or use the native full-screen controller. The default value is false.

NOTE

In order for video to play inline, not only does this property need to be set to true, but the video element in the HTML document must also include the webkit-playsinline attribute.

TypeRequiredPlatform
boolNoiOS

bounces

Boolean value that determines whether the web view bounces when it reaches the edge of the content. The default value is true.

TypeRequiredPlatform
boolNoiOS

contentInset

The amount by which the web view content is inset from the edges of the scroll view. Defaults to {top: 0, left: 0, bottom: 0, right: 0}.

TypeRequiredPlatform
object: {top: number, left: number, bottom: number, right: number}NoiOS

dataDetectorTypes

Determines the types of data converted to clickable URLs in the web view's content. By default only phone numbers are detected.

You can provide one type or an array of many types.

Possible values for dataDetectorTypes are:

With the new WebKit implementation, we have three new values:

TypeRequiredPlatform
string, or arrayNoiOS

scrollEnabled

Boolean value that determines whether scrolling is enabled in the WebView. The default value is true.

TypeRequiredPlatform
boolNoiOS

geolocationEnabled

Set whether Geolocation is enabled in the WebView. The default value is false. Used only in Android.

TypeRequiredPlatform
boolNoAndroid

allowUniversalAccessFromFileURLs

Boolean that sets whether JavaScript running in the context of a file scheme URL should be allowed to access content from any origin. Including accessing content from other file scheme URLs. The default value is false.

TypeRequiredPlatform
boolNoAndroid

allowFileAccess

Boolean that sets whether the WebView has access to the file system. The default value is false.

TypeRequiredPlatform
boolNoAndroid

useWebKit

If true, use WKWebView instead of UIWebView.

TypeRequiredPlatform
booleanNoiOS

url

Deprecated. Use the source prop instead.

TypeRequired
stringNo

html

Deprecated. Use the source prop instead.

TypeRequired
stringNo

Methods

extraNativeComponentConfig()

static extraNativeComponentConfig()

goForward()

goForward();

Go forward one page in the web view's history.

goBack()

goBack();

Go back one page in the web view's history.

reload()

reload();

Reloads the current page.

stopLoading()

stopLoading();

Stop loading the current page.

Edit this page
Last updated on
- + diff --git a/help.html b/help.html index 10f8afc25e4..78ffd973fa0 100644 --- a/help.html +++ b/help.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@

The React Native Community

There are a lot of developers around the world using React Native. This is a brief overview of where you can find them.

Where To Get Help

If you need help with your React Native app, the right place to go depends on the type of help that you need.

Repository

The core of React Native is worked on full-time by Facebook's React Native team. But there are far more people in the community who make key contributions and fix things. If the issue you are facing is code related, you should consider checking the open issues in the main repository. If you cannot find an existing issue, please use the Bug Report template to create an issue with a minimal example.

Stack Overflow

Many members of the community use Stack Overflow to ask questions. Read through the existing questions tagged with react-native or ask your own!

Staying up to date

Official channels

The React Twitter account covers both React and React Native. Follow the React Native Twitter account and blog to find out what's happening in the world of React Native.

Proposals

React Native is still a young framework, and its rapid release cycle leaves the door open for discussing how it can evolve at every step of the way. If you want to know what the current proposals and RFCs are talking about, you can read through the Discussions and Proposals repository.

Conferences

There are a lot of React Native Meetups that happen around the world. Often there is React Native content in React meetups as well. React Native has been covered often in past React Conf talks. Videos for these talks can be found online in the following playlists: React Conf 2019, React Conf 2018, React Conf 2017, React Conf 2016 and React Conf 2015. The next React Conf is yet to be announced. You can also find a list of dedicated React Native conferences here.

Communities

Reactiflux Chat

If you need an answer right away, check out the Reactiflux Discord community. There are usually a number of React Native experts there who can help out or point you to somewhere you might want to look.

Forum-like groups

If you want to create less temporary conversations, check out the React Native Spectrum community or the React Native Facebook Group, which is more focused on post announcements, blog posts, talks, videos, cool new libraries, and apps. The Expo Forums are a good place to get help if you are using Expo.

Company-based Communities

Some companies actively involved in the React Native have also their own communication channels focused towards the projects they maintain, like Callstack.io's Discord server, Invertase.io's Discord server (e.g. React Native Firebase), Infinite Red's Slack Group and The Expo Slack Group.

Content sharing

DevTo community's and Medium's React Native tag are places where you can share React Native projects, articles and tutorials as well as start discussions and ask for feedback on React Native related topics. (but remember to give some love to the main documentation too!)

- + diff --git a/help/index.html b/help/index.html index 10f8afc25e4..78ffd973fa0 100644 --- a/help/index.html +++ b/help/index.html @@ -19,7 +19,7 @@ - + @@ -39,7 +39,7 @@

The React Native Community

There are a lot of developers around the world using React Native. This is a brief overview of where you can find them.

Where To Get Help

If you need help with your React Native app, the right place to go depends on the type of help that you need.

Repository

The core of React Native is worked on full-time by Facebook's React Native team. But there are far more people in the community who make key contributions and fix things. If the issue you are facing is code related, you should consider checking the open issues in the main repository. If you cannot find an existing issue, please use the Bug Report template to create an issue with a minimal example.

Stack Overflow

Many members of the community use Stack Overflow to ask questions. Read through the existing questions tagged with react-native or ask your own!

Staying up to date

Official channels

The React Twitter account covers both React and React Native. Follow the React Native Twitter account and blog to find out what's happening in the world of React Native.

Proposals

React Native is still a young framework, and its rapid release cycle leaves the door open for discussing how it can evolve at every step of the way. If you want to know what the current proposals and RFCs are talking about, you can read through the Discussions and Proposals repository.

Conferences

There are a lot of React Native Meetups that happen around the world. Often there is React Native content in React meetups as well. React Native has been covered often in past React Conf talks. Videos for these talks can be found online in the following playlists: React Conf 2019, React Conf 2018, React Conf 2017, React Conf 2016 and React Conf 2015. The next React Conf is yet to be announced. You can also find a list of dedicated React Native conferences here.

Communities

Reactiflux Chat

If you need an answer right away, check out the Reactiflux Discord community. There are usually a number of React Native experts there who can help out or point you to somewhere you might want to look.

Forum-like groups

If you want to create less temporary conversations, check out the React Native Spectrum community or the React Native Facebook Group, which is more focused on post announcements, blog posts, talks, videos, cool new libraries, and apps. The Expo Forums are a good place to get help if you are using Expo.

Company-based Communities

Some companies actively involved in the React Native have also their own communication channels focused towards the projects they maintain, like Callstack.io's Discord server, Invertase.io's Discord server (e.g. React Native Firebase), Infinite Red's Slack Group and The Expo Slack Group.

Content sharing

DevTo community's and Medium's React Native tag are places where you can share React Native projects, articles and tutorials as well as start discussions and ask for feedback on React Native related topics. (but remember to give some love to the main documentation too!)

- + diff --git a/index.html b/index.html index aab9ad591b7..2f3e2b0d294 100644 --- a/index.html +++ b/index.html @@ -19,7 +19,7 @@ - + @@ -66,10 +66,10 @@ Save, see, repeat. Members of the React Native team frequently speak at various conferences.

You can follow the latest news from the React Native team on Twitter -

Facebook Supported, Community Driven

Facebook released React Native in 2015 and has been maintaining it ever since.

In 2018, React Native had the 2nd highest number of contributors for any repository in GitHub. Today, React Native is supported by contributions from individuals and companies around the world including Callstack, Expo, Infinite Red, Microsoft and Software Mansion.

Our community is always shipping exciting new projects and exploring platforms beyond Android and iOS with repos like React Native Windows, React Native macOS and React Native Web.

React Native is being used in thousands of apps, but it's likely you've already used it in one of these apps:

  • Facebook
  • Facebook Ads Manager
  • Facebook Analytics
  • Instagram
  • Oculus
  • Coinbase
  • Shopify
  • Tableau
  • FlipKart
  • Mercari
  • NerdWallet
  • Discord
  • Skype
  • Bloomberg
  • Pinterest
  • Tesla
  • Uber Eats
  • Walmart
  • Wix.com
  • Salesforce
  • Words with Friends
  • Call of Duty Companion App
  • Foreca
  • LendMN
  • Artsy
  • Tencent QQ

and many more.

Give it a try

  1. Run this

    npx react-native init MyTestApp

  2. Read these

    Get startedLearn basics
+

Facebook Supported, Community Driven

Facebook released React Native in 2015 and has been maintaining it ever since.

In 2018, React Native had the 2nd highest number of contributors for any repository in GitHub. Today, React Native is supported by contributions from individuals and companies around the world including Callstack, Expo, Infinite Red, Microsoft and Software Mansion.

Our community is always shipping exciting new projects and exploring platforms beyond Android and iOS with repos like React Native Windows, React Native macOS and React Native Web.

React Native is being used in thousands of apps, but it's likely you've already used it in one of these apps:

  • Facebook
  • Facebook Ads Manager
  • Facebook Analytics
  • Instagram
  • Oculus
  • Coinbase
  • Shopify
  • Tableau
  • FlipKart
  • Mercari
  • NerdWallet
  • Discord
  • Skype
  • Bloomberg
  • Pinterest
  • Tesla
  • Uber Eats
  • Walmart
  • Wix.com
  • Salesforce
  • Words with Friends
  • Call of Duty Companion App
  • Foreca
  • LendMN
  • Artsy
  • Tencent QQ

and many more.

Give it a try

  1. Run this

    npx react-native init MyTestApp

  2. Read these

    Get startedLearn basics
- + diff --git a/main.259a8b48.js b/main.259a8b48.js deleted file mode 100644 index b68880d5d16..00000000000 --- a/main.259a8b48.js +++ /dev/null @@ -1,2 +0,0 @@ -/*! For license information please see main.259a8b48.js.LICENSE.txt */ -(window.webpackJsonp=window.webpackJsonp||[]).push([[936],[function(e,n,t){"use strict";e.exports=t(30)},function(e,n,t){"use strict";t.d(n,"a",(function(){return g})),t.d(n,"b",(function(){return y})),t.d(n,"c",(function(){return E})),t.d(n,"d",(function(){return C})),t.d(n,"e",(function(){return v})),t.d(n,"f",(function(){return I})),t.d(n,"g",(function(){return L})),t.d(n,"h",(function(){return h})),t.d(n,"i",(function(){return _})),t.d(n,"j",(function(){return P})),t.d(n,"k",(function(){return z})),t.d(n,"l",(function(){return M})),t.d(n,"m",(function(){return U})),t.d(n,"n",(function(){return $})),t.d(n,"o",(function(){return F}));var o=t(3),i=t(0),a=t.n(i),s=(t(9),t(5)),r=t(17),c=t(4),d=t(2),l=t(18),u=t.n(l),p=(t(23),t(7)),m=t(27),f=t.n(m),b=function(e){var n=Object(r.a)();return n.displayName=e,n}("Router-History"),h=function(e){var n=Object(r.a)();return n.displayName=e,n}("Router"),v=function(e){function n(n){var t;return(t=e.call(this,n)||this).state={location:n.history.location},t._isMounted=!1,t._pendingLocation=null,n.staticContext||(t.unlisten=n.history.listen((function(e){t._isMounted?t.setState({location:e}):t._pendingLocation=e}))),t}Object(o.a)(n,e),n.computeRootMatch=function(e){return{path:"/",url:"/",params:{},isExact:"/"===e}};var t=n.prototype;return t.componentDidMount=function(){this._isMounted=!0,this._pendingLocation&&this.setState({location:this._pendingLocation})},t.componentWillUnmount=function(){this.unlisten&&this.unlisten()},t.render=function(){return a.a.createElement(h.Provider,{value:{history:this.props.history,location:this.state.location,match:n.computeRootMatch(this.state.location.pathname),staticContext:this.props.staticContext}},a.a.createElement(b.Provider,{children:this.props.children||null,value:this.props.history}))},n}(a.a.Component);var g=function(e){function n(){for(var n,t=arguments.length,o=new Array(t),i=0;i=0;p--){var m=s[p];"."===m?a(s,p):".."===m?(a(s,p),u++):u&&(a(s,p),u--)}if(!d)for(;u--;u)s.unshift("..");!d||""===s[0]||s[0]&&i(s[0])||s.unshift("");var f=s.join("/");return t&&"/"!==f.substr(-1)&&(f+="/"),f};function r(e){return e.valueOf?e.valueOf():Object.prototype.valueOf.call(e)}var c=function e(n,t){if(n===t)return!0;if(null==n||null==t)return!1;if(Array.isArray(n))return Array.isArray(t)&&n.length===t.length&&n.every((function(n,o){return e(n,t[o])}));if("object"==typeof n||"object"==typeof t){var o=r(n),i=r(t);return o!==n||i!==t?e(o,i):Object.keys(Object.assign({},n,t)).every((function(o){return e(n[o],t[o])}))}return!1},d=t(4);function l(e){return"/"===e.charAt(0)?e:"/"+e}function u(e){return"/"===e.charAt(0)?e.substr(1):e}function p(e,n){return function(e,n){return 0===e.toLowerCase().indexOf(n.toLowerCase())&&-1!=="/?#".indexOf(e.charAt(n.length))}(e,n)?e.substr(n.length):e}function m(e){return"/"===e.charAt(e.length-1)?e.slice(0,-1):e}function f(e){var n=e.pathname,t=e.search,o=e.hash,i=n||"/";return t&&"?"!==t&&(i+="?"===t.charAt(0)?t:"?"+t),o&&"#"!==o&&(i+="#"===o.charAt(0)?o:"#"+o),i}function b(e,n,t,i){var a;"string"==typeof e?(a=function(e){var n=e||"/",t="",o="",i=n.indexOf("#");-1!==i&&(o=n.substr(i),n=n.substr(0,i));var a=n.indexOf("?");return-1!==a&&(t=n.substr(a),n=n.substr(0,a)),{pathname:n,search:"?"===t?"":t,hash:"#"===o?"":o}}(e)).state=n:(void 0===(a=Object(o.a)({},e)).pathname&&(a.pathname=""),a.search?"?"!==a.search.charAt(0)&&(a.search="?"+a.search):a.search="",a.hash?"#"!==a.hash.charAt(0)&&(a.hash="#"+a.hash):a.hash="",void 0!==n&&void 0===a.state&&(a.state=n));try{a.pathname=decodeURI(a.pathname)}catch(r){throw r instanceof URIError?new URIError('Pathname "'+a.pathname+'" could not be decoded. This is likely caused by an invalid percent-encoding.'):r}return t&&(a.key=t),i?a.pathname?"/"!==a.pathname.charAt(0)&&(a.pathname=s(a.pathname,i.pathname)):a.pathname=i.pathname:a.pathname||(a.pathname="/"),a}function h(e,n){return e.pathname===n.pathname&&e.search===n.search&&e.hash===n.hash&&e.key===n.key&&c(e.state,n.state)}function v(){var e=null;var n=[];return{setPrompt:function(n){return e=n,function(){e===n&&(e=null)}},confirmTransitionTo:function(n,t,o,i){if(null!=e){var a="function"==typeof e?e(n,t):e;"string"==typeof a?"function"==typeof o?o(a,i):i(!0):i(!1!==a)}else i(!0)},appendListener:function(e){var t=!0;function o(){t&&e.apply(void 0,arguments)}return n.push(o),function(){t=!1,n=n.filter((function(e){return e!==o}))}},notifyListeners:function(){for(var e=arguments.length,t=new Array(e),o=0;on?t.splice(n,t.length-n,i):t.push(i),u({action:o,location:i,index:n,entries:t})}}))},replace:function(e,n){var o="REPLACE",i=b(e,n,p(),y.location);l.confirmTransitionTo(i,o,t,(function(e){e&&(y.entries[y.index]=i,u({action:o,location:i}))}))},go:x,goBack:function(){x(-1)},goForward:function(){x(1)},canGo:function(e){var n=y.index+e;return n>=0&&n=0||(i[t]=e[t]);return i}t.d(n,"a",(function(){return o}))},function(e,n,t){"use strict";t.r(n),n.default={title:"React Native",tagline:"A framework for building native apps using React",organizationName:"facebook",projectName:"react-native",url:"https://reactnative.dev",baseUrl:"/",clientModules:["/home/circleci/react-native-website/website/snackPlayerInitializer.js"],scripts:[{src:"https://cdn.jsdelivr.net/npm/focus-visible@5.2.0/dist/focus-visible.min.js",defer:!0},{src:"https://snack.expo.io/embed.js",defer:!0}],favicon:"img/favicon.ico",titleDelimiter:"\xb7",customFields:{users:[{name:"Facebook",icon:"facebook.png",linkAppStore:"https://itunes.apple.com/app/facebook/id284882215",linkPlayStore:"https://play.google.com/store/apps/details?id=com.facebook.katana",infoLink:"https://code.facebook.com/posts/895897210527114/dive-into-react-native-performance/",infoTitle:"Using React Native in the Facebook App",pinned:!0},{name:"Facebook Ads Manager",icon:"adsmanager.png",linkAppStore:"https://itunes.apple.com/us/app/facebook-ads-manager/id964397083?mt=8",linkPlayStore:"https://play.google.com/store/apps/details?id=com.facebook.adsmanager",infoLink:"https://code.facebook.com/posts/1189117404435352/react-native-for-android-how-we-built-the-first-cross-platform-react-native-app/",infoTitle:"How We Built the First Cross-Platform React Native App",pinned:!0},{name:"Facebook Analytics",icon:"fba.png",linkAppStore:"https://itunes.apple.com/us/app/facebook/id1266461465",linkPlayStore:"https://play.google.com/store/apps/details?id=com.facebook.analytics",infoLink:"https://analytics.facebook.com/blog",infoTitle:"",pinned:!0},{name:"Instagram",icon:"instagram.png",linkAppStore:"https://itunes.apple.com/app/instagram/id389801252?pt=428156&ct=igweb.unifiedHome.badge&mt=8",linkPlayStore:"https://play.google.com/store/apps/details?id=com.instagram.android&referrer=utm_source%3Dinstagramweb%26utm_campaign%3DunifiedHome%26utm_medium%3Dbadge",infoLink:"https://engineering.instagram.com/react-native-at-instagram-dd828a9a90c7#.3h4wir4zr",infoTitle:"React Native at Instagram",pinned:!0},{name:"Oculus",icon:"oculus.png",linkAppStore:"https://apps.apple.com/us/app/oculus/id1366478176",linkPlayStore:"https://play.google.com/store/apps/details?id=com.oculus.twilight&hl=en_US",infoLink:"",infoTitle:"",pinned:!0},{name:"Coinbase",icon:"coinbase.png",linkAppStore:"https://apps.apple.com/us/app/coinbase-buy-sell-bitcoin/id886427730",linkPlayStore:"https://play.google.com/store/apps/details?id=com.coinbase.android",infoLink:"https://blog.coinbase.com/onboarding-thousands-of-users-with-react-native-361219066df4",infoTitle:"Onboarding thousands of users with React Native",pinned:!0},{name:"Shopify",icon:"shopify.png",linkAppStore:"https://apps.apple.com/ca/app/shop-package-order-tracker/id1223471316",linkPlayStore:"https://play.google.com/store/apps/details?id=com.shopify.arrive&hl=en_US&gl=US",infoLink:"https://engineering.shopify.com/blogs/engineering/react-native-future-mobile-shopify",infoTitle:"React Native is the Future of Mobile at Shopify",pinned:!0},{name:"Tableau",icon:"tableau.png",linkAppStore:"https://apps.apple.com/us/app/tableau-mobile/id434633927",linkPlayStore:"https://play.google.com/store/apps/details?id=com.Tableau.TableauApp&hl=en_US",infoLink:"https://engineering.tableau.com/react-native-at-tableau-3-years-in-89d43c38354c",infoTitle:"React Native at Tableau 3 Years in",pinned:!0},{name:"FlipKart",icon:"flipkart.png",linkAppStore:"https://apps.apple.com/in/app/flipkart-online-shopping-app/id742044692",linkPlayStore:"https://play.google.com/store/apps/details?id=com.flipkart.android&hl=en_US&gl=US",infoLink:"https://tech.flipkart.com/the-journey-of-react-native-flipkart-47dcd0c3d1c6",infoTitle:"The Journey of React Native @ FlipKart",pinned:!0},{name:"Mercari",icon:"mercari.png",linkAppStore:"https://apps.apple.com/us/app/mercari-your-marketplace/id896130944",linkPlayStore:"https://play.google.com/store/apps/details?id=com.mercariapp.mercari",pinned:!0},{name:"NerdWallet",icon:"nerdwallet.png",linkAppStore:"https://apps.apple.com/us/app/nerdwallet/id1174471607",linkPlayStore:"https://play.google.com/store/apps/details?id=com.mobilecreditcards&hl=en_US",infoLink:"https://www.nerdwallet.com/",infoTitle:"",pinned:!0},{name:"Discord",icon:"discord.png",linkAppStore:"https://itunes.apple.com/us/app/discord-chat-for-gamers/id985746746?mt=8",infoLink:"https://blog.discord.com/how-discord-achieves-native-ios-performance-with-react-native-390c84dcd502",infoTitle:"How Discord achieves native iOS performance with React Native",pinned:!0},{name:"Skype",icon:"skype.png",linkAppStore:"https://itunes.apple.com/us/app/skype-for-iphone/id304878510?mt=8",linkPlayStore:"https://play.google.com/store/apps/details?id=com.skype.raider",infoLink:"https://dev.skype.com/react",infoTitle:"",pinned:!0},{name:"Bloomberg",icon:"bloomberg.png",linkAppStore:"https://itunes.apple.com/us/app/bloomberg/id281941097?mt=8",linkPlayStore:"https://play.google.com/store/apps/details?id=com.bloomberg.android.plus",infoLink:"https://www.techatbloomberg.com/blog/bloomberg-used-react-native-develop-new-consumer-app/",infoTitle:"How Bloomberg Used React Native to Develop its new Consumer App",pinned:!0},{name:"Pinterest",icon:"pinterest.png",linkAppStore:"https://itunes.apple.com/us/app/pinterest/id429047995?mt=8",linkPlayStore:"https://play.google.com/store/apps/details?id=com.pinterest",infoLink:"https://medium.com/@Pinterest_Engineering/supporting-react-native-at-pinterest-f8c2233f90e6",infoTitle:"Supporting React Native at Pinterest",pinned:!0},{name:"Tesla",icon:"tesla.png",linkPlayStore:"https://play.google.com/store/apps/details?id=com.teslamotors.tesla",linkAppStore:"https://itunes.apple.com/us/app/tesla-motors/id582007913?mt=8",infoLink:"https://www.tesla.com/blog",infoTitle:"",pinned:!0},{name:"Uber Eats",icon:"ubereats.png",infoLink:"https://eng.uber.com/ubereats-react-native/",infoTitle:"Powering Uber Eats with React Native",pinned:!0},{name:"Walmart",icon:"walmart.png",linkAppStore:"https://itunes.apple.com/us/app/walmart-app-shopping-savings/id338137227?mt=8",linkPlayStore:"https://play.google.com/store/apps/details?id=com.walmart.android",infoLink:" https://medium.com/walmartlabs/react-native-at-walmartlabs-cdd140589560#.ueonqqloc",infoTitle:"React Native at Walmart Labs",pinned:!0},{name:"Wix.com",icon:"wix.png",linkAppStore:"https://itunes.apple.com/us/app/wix-com/id1099748482?mt=8",linkPlayStore:"https://play.google.com/store/apps/details?id=com.wix.android",infoLink:"https://medium.com/wix-engineering/react-native-at-wix-the-architecture-db6361764da6",infoTitle:"React Native at Wix \u2014 The Architecture",pinned:!0},{name:"Salesforce",icon:"salesforce.png",linkAppStore:"https://itunes.apple.com/us/app/salesforce/id404249815?mt=8",linkPlayStore:"https://play.google.com/store/apps/details?id=com.salesforce.chatter",infoLink:"https://www.salesforce.com/products/einstein/einstein-voice/",infoTitle:"Einstein Voice Assistant: Voice Activated AI",pinned:!0},{name:"Words with Friends",icon:"words2.png",linkAppStore:"https://apps.apple.com/app/words-with-friends-2-word-game/id1196764367",linkPlayStore:"https://play.google.com/store/apps/details?id=com.zynga.words3&hl=en_US&gl=US",infoLink:"https://medium.com/zynga-engineering/why-how-words-with-friends-is-adopting-react-native-b24a405f421c",infoTitle:"Why & How Words With Friends Is Adopting React Native",pinned:!0},{name:"Call of Duty Companion App",icon:"callofduty_companion.png",linkAppStore:"https://apps.apple.com/us/app/call-of-duty-companion-app/id1405837628?ls=1",linkPlayStore:"https://play.google.com/store/apps/details?id=com.activision.callofduty.companion",infoLink:"https://www.callofduty.com/app",infoTitle:"",pinned:!0},{name:"Foreca",icon:"foreca.png",linkAppStore:"https://apps.apple.com/app/foreca-weather/id525994479",linkPlayStore:"https://play.google.com/store/apps/details?id=com.foreca.android.weather",infoLink:"https://corporate.foreca.com/en/news/how-to-make-a-global-weather-app-serving-both-ios-and-android-users",infoTitle:"How to make a global weather app serving both iOS and Android users",pinned:!0},{name:"LendMN",icon:"lendmn.png",linkAppStore:"https://apps.apple.com/mn/app/lendmn/id1167495761?ls=1",linkPlayStore:"https://play.google.com/store/apps/details?id=com.lendmn.lendmn",infoLink:"https://medium.com/@and.global/providing-financial-access-to-the-underbanked-through-react-native-a8473691d06",infoTitle:"Providing financial access to the underbanked through React Native",pinned:!0},{name:"Artsy",icon:"https://raw.githubusercontent.com/artsy/eigen/master/Artsy/Resources/Images.xcassets/AppIcon.appiconset/AppIcon167.png",linkAppStore:"https://itunes.apple.com/us/app/artsy-collect-bid-on-fine/id703796080?mt=8",infoLink:"https://artsy.github.io/series/react-native-at-artsy/",infoTitle:"React Native at Artsy",pinned:!0},{name:"Baidu Mobile (\u624b\u673a\u767e\u5ea6)",icon:"baidu.png",linkPlayStore:"http://shouji.baidu.com/software/9896302.html",linkAppStore:"https://itunes.apple.com/us/app/%E6%89%8B%E6%9C%BA%E7%99%BE%E5%BA%A6-%E7%99%BE%E5%BA%A6%E4%B8%80%E4%B8%8B%E4%BD%A0%E5%B0%B1%E5%BE%97%E5%88%B0/id382201985?mt=8",infoLink:"http://baike.baidu.com/link?url=TW8YhcVN4tO_Jz5VqMclCjGhf12EEqMD_TeVC6efe2REZlx80r6T0dX96hdmNl36XogLyExXzrvFU9rFeqxg_K",infoTitle:"Baidu Mobile is a search engine used by over 600 million people in China",pinned:!1},{name:"CBS Sports Franchise Football",icon:"cbssports.png",linkPlayStore:"https://play.google.com/store/apps/details?id=com.cbssports.fantasy.franchisefootball2015",infoLink:"http://www.cbssports.com/fantasy/football/games/franchise/2015",infoTitle:"Award winning Fantasy Football league manager built with React Native",pinned:!1},{name:"Chop",icon:"chop.png",linkAppStore:"http://apple.co/2dfkYH9",infoLink:"http://blog.getchop.io/2016/10/13/how-we-built-chop/",infoTitle:"How we built Chop using React Native",pinned:!1},{name:"Delivery.com",icon:"delivery.png",linkAppStore:"https://itunes.apple.com/us/app/delivery.com-food-alcohol/id435168129?mt=8",linkPlayStore:"https://play.google.com/store/apps/details?id=com.deliverycom",infoLink:"https://medium.com/delivery-com-engineering/react-native-in-an-existing-ios-app-delivered-874ba95a3c52#.37qruw6ck",infoTitle:"React Native in an Existing iOS App: Getting Started",pinned:!1},{name:"F8",icon:"f8.png",linkAppStore:"https://itunes.apple.com/it/app/f8/id853467066?l=en&mt=8",linkPlayStore:"https://play.google.com/store/apps/details?id=com.facebook.f8",infoLink:"http://makeitopen.com/docs/en/1-1-planning.html",infoTitle:"Tutorial: Building the F8 conference app",pinned:!1},{name:"Gyroscope",icon:"gyroscope.png",linkAppStore:"https://itunes.apple.com/app/apple-store/id1104085053?pt=117927205&ct=website&mt=8",linkPlayStore:"https://play.google.com/store/apps/details?id=com.gyroscope.gyroscope",infoLink:"https://blog.gyrosco.pe/building-the-app-1dac1a97d253",infoTitle:"Building a visualization experience with React Native",pinned:!1},{name:"Huiseoul (\u60e0\u9996\u5c14)",icon:"huiseoul.png",linkAppStore:"https://itunes.apple.com/us/app/hui-shou-er-ni-si-ren-mei/id1127150360?ls=1&mt=8",infoLink:"https://engineering.huiseoul.com/building-a-conversational-e-commerce-app-in-6-weeks-with-react-native-c35d46637e07",infoTitle:"Building a conversational E-commerce app in 6 weeks with React Native",pinned:!1},{name:"JD\uff08\u624b\u673a\u4eac\u4e1c\uff09",icon:"jdcom.png",linkAppStore:"https://itunes.apple.com/cn/app/shou-ji-jing-dong-xin-ren/id414245413?mt=8",linkPlayStore:"https://app.jd.com/android.html",infoLink:"http://ir.jd.com/phoenix.zhtml?c=253315&p=irol-homeProfile",infoTitle:"JD.com is China\u2019s largest ecommerce company by revenue and a member of the Fortune Global 500.",pinned:!1},{name:"SoundCloud Pulse",icon:"soundcloud_pulse.jpg",linkAppStore:"https://itunes.apple.com/us/app/soundcloud-pulse-for-creators/id1074278256?mt=8",infoLink:"https://developers.soundcloud.com/blog/react-native-at-soundcloud",infoTitle:"Why React Native worked well for us",pinned:!1},{name:"Tencent QQ",icon:"qq.png",linkPlayStore:"http://android.myapp.com/myapp/detail.htm?apkName=com.tencent.mobileqq",infoLink:"https://www.tencent.com/en-us/system.html",infoTitle:"QQ is China's largest messaging platform, with over 829 million active accounts",pinned:!0},{name:"Townske",icon:"townske.png",linkAppStore:"https://itunes.apple.com/us/app/townske-stunning-city-guides/id1018136179?ls=1&mt=8",infoLink:"https://hackernoon.com/townske-app-in-react-native-6ad557de7a7c",infoTitle:"The experience of a web developer building an app using React Native",pinned:!1},{name:"Vogue",icon:"vogue.jpeg",linkAppStore:"https://itunes.apple.com/app/apple-store/id1087973225?pt=45076&ct=site-promo&mt=8",infoLink:"http://www.vogue.com/app",infoTitle:"",pinned:!1},{name:"adidas GLITCH",icon:"glitch.png",linkAppStore:"https://itunes.apple.com/gb/app/adidas-glitch-interchangeable/id1166181522?mt=8&cm_sp=FOOTBALL-_-UNDEFINED-_-CTA-DOWNLOAD-IPHONE",linkPlayStore:"https://play.google.com/store/apps/details?id=com.adidas.glitch&cm_sp=FOOTBALL-_-UNDEFINED-_-CTA-DOWNLOAD-ANDROID",infoLink:"https://medium.com/possible-cee/how-we-have-been-breaking-patterns-with-the-adidas-glitch-d734340fd40e",infoTitle:"Building Adidas GLITCH app with React Native",pinned:!1}],facebookAppId:"1677033832619985"},onBrokenLinks:"throw",presets:[["@docusaurus/preset-classic",{docs:{showLastUpdateAuthor:!1,showLastUpdateTime:!0,editUrl:"https://github.com/facebook/react-native-website/blob/master/website/",path:"../docs",sidebarPath:"/home/circleci/react-native-website/website/sidebars.json",remarkPlugins:[null]},blog:{path:"blog",blogSidebarCount:"ALL",blogSidebarTitle:"All Blog Posts",feedOptions:{type:"all",copyright:"Copyright \xa9 2021 Facebook, Inc."}},theme:{customCss:["/home/circleci/react-native-website/website/src/css/customTheme.scss","/home/circleci/react-native-website/website/src/css/index.scss","/home/circleci/react-native-website/website/src/css/showcase.scss","/home/circleci/react-native-website/website/src/css/versions.scss"]}}]],plugins:["docusaurus-plugin-sass","./sitePlugin"],themeConfig:{prism:{defaultLanguage:"jsx",theme:{plain:{color:"#FFFFFF",background:"#282C34"},styles:[{types:["property"],style:{color:"#2aa198"}},{types:["attr-name","comment","prolog","doctype","cdata"],style:{color:"#93a1a1"}},{types:["punctuation"],style:{color:"#657b83"}},{types:["namespace"],style:{opacity:.7}},{types:["selector","char","builtin","url"],style:{color:"#2aa198"}},{types:["entity"],style:{color:"#2aa198"}},{types:["atrule","inserted"],style:{color:"#859900"}},{types:["important","variable","deleted"],style:{color:"#cb4b16"}},{types:["important","bold"],style:{fontWeight:"bold"}},{types:["italic"],style:{fontStyle:"italic"}},{types:["entity"],style:{cursor:"help"}},{types:["attr-name","keyword"],style:{color:"#c5a5c5"}},{types:["string","regex","attr-value"],style:{color:"#8dc891"}},{types:["number","constant","symbol"],style:{color:"#5a9bcf"}},{types:["boolean"],style:{color:"#ff8b50"}},{types:["class-name"],style:{color:"#fac863"}},{types:["function"],style:{color:"#79b6f2"}},{types:["operator","tag"],style:{color:"#fc929e"}}]},additionalLanguages:["java","kotlin","objectivec","swift","groovy"]},navbar:{title:"React Native",logo:{src:"img/header_logo.svg",alt:"React Native"},style:"dark",items:[{label:"Docs",type:"doc",docId:"getting-started",position:"right",activeSidebarClassName:"navbar__link--active"},{label:"Components",type:"doc",docId:"components-and-apis",position:"right",activeSidebarClassName:"navbar__link--active"},{label:"API",type:"doc",docId:"accessibilityinfo",position:"right",activeSidebarClassName:"navbar__link--active"},{to:"/help",label:"Community",position:"right"},{to:"/blog",label:"Blog",position:"right"},{type:"docsVersionDropdown",position:"left",dropdownActiveClassDisabled:!0,dropdownItemsAfter:[{to:"/versions",label:"All versions"}],dropdownItemsBefore:[]},{href:"https://github.com/facebook/react-native","aria-label":"GitHub repository",position:"right",className:"navbar-github-link"}],hideOnScroll:!1},image:"img/logo-og.png",footer:{style:"dark",links:[{title:"Docs",items:[{label:"Getting Started",to:"docs/getting-started"},{label:"Tutorial",to:"docs/tutorial"},{label:"Components and APIs",to:"docs/components-and-apis"},{label:"More Resources",to:"docs/more-resources"}]},{title:"Community",items:[{label:"The React Native Community",to:"help"},{label:"Who's using React Native?",to:"showcase"},{label:"Ask Questions on Stack Overflow",to:"https://stackoverflow.com/questions/tagged/react-native"},{label:"Contributor Guide",to:"https://github.com/facebook/react-native/blob/master/CONTRIBUTING.md"},{label:"DEV Community",to:"https://dev.to/t/reactnative"}]},{title:"Find us",items:[{label:"Blog",to:"blog"},{label:"Twitter",href:"https://twitter.com/reactnative"},{label:"GitHub",href:"https://github.com/facebook/react-native"}]},{title:"More",items:[{label:"React",href:"https://reactjs.org/"},{label:"Privacy Policy",to:"https://opensource.facebook.com/legal/privacy"},{label:"Terms of Service",href:"https://opensource.facebook.com/legal/terms"}]}],logo:{alt:"Facebook Open Source Logo",src:"img/oss_logo.png",href:"https://opensource.facebook.com"},copyright:"Copyright \xa9 2021 Facebook, Inc."},algolia:{apiKey:"2c98749b4a1e588efec53b2acec13025",indexName:"react-native-v2",contextualSearch:!0,appId:"BH4D9OD16A",searchParameters:{}},googleAnalytics:{trackingID:"UA-41298772-2"},gtag:{trackingID:"UA-41298772-2"},metadatas:[{name:"description",content:"A framework for building native apps using React"},{property:"og:title",content:"React Native"},{property:"og:description",content:"A framework for building native apps using React"},{property:"og:url",content:"https://reactnative.dev/"},{property:"og:image",content:"https://reactnative.dev/img/logo-og.png"},{name:"twitter:card",content:"summary"},{name:"twitter:image",content:"https://reactnative.dev/img/logo-og.png"}],colorMode:{defaultMode:"light",disableSwitch:!1,respectPrefersColorScheme:!1,switchConfig:{darkIcon:"\ud83c\udf1c",darkIconStyle:{},lightIcon:"\ud83c\udf1e",lightIconStyle:{}}},docs:{versionPersistence:"localStorage"}},onDuplicateRoutes:"warn",themes:[],noIndex:!1}},function(e,n,t){e.exports=t(34)()},function(e,n,t){"use strict";t.d(n,"a",(function(){return r})),t.d(n,"b",(function(){return c}));var o=t(1),i=t(2),a=t(0),s=t.n(a);function r(e,n,t){return void 0===t&&(t=[]),e.some((function(e){var i=e.path?Object(o.j)(n,e):t.length?t[t.length-1].match:o.e.computeRootMatch(n);return i&&(t.push({route:e,match:i}),e.routes&&r(e.routes,n,t)),i})),t}function c(e,n,t){return void 0===n&&(n={}),void 0===t&&(t={}),e?s.a.createElement(o.g,t,e.map((function(e,t){return s.a.createElement(o.d,{key:e.key||t,path:e.path,exact:e.exact,strict:e.strict,render:function(t){return e.render?e.render(Object(i.a)({},t,{},n,{route:e})):s.a.createElement(e.component,Object(i.a)({},t,n,{route:e}))}})}))):null}},function(e){e.exports=JSON.parse('{"/-deb":{"component":"c4f5d8e4","config":"5e9f5e1a"},"/blog-add":{"component":"a6aa9e1f","sidebar":"e4eeaf16","items":[{"content":"1b94994a"},{"content":"f80d3992"},{"content":"8415f7e8"},{"content":"5860a2aa"},{"content":"3e16fe84"},{"content":"10a433e1"},{"content":"000e4255"},{"content":"474240c1"},{"content":"c02586a2"},{"content":"fb39fd3f"}],"metadata":"b2b675dd"},"/blog/2015/03/26/react-native-bringing-modern-web-techniques-to-mobile-028":{"component":"ccc49370","sidebar":"e4eeaf16","content":"c5f92c9d"},"/blog/2015/09/14/react-native-for-android-1c6":{"component":"ccc49370","sidebar":"e4eeaf16","content":"fccc6009"},"/blog/2015/11/23/making-react-native-apps-accessible-970":{"component":"ccc49370","sidebar":"e4eeaf16","content":"d0b5637a"},"/blog/2016/03/24/introducing-hot-reloading-71a":{"component":"ccc49370","sidebar":"e4eeaf16","content":"8551c45d"},"/blog/2016/03/28/dive-into-react-native-performance-a3a":{"component":"ccc49370","sidebar":"e4eeaf16","content":"14dcd83a"},"/blog/2016/04/13/react-native-a-year-in-review-767":{"component":"ccc49370","sidebar":"e4eeaf16","content":"58c2ea8e"},"/blog/2016/07/06/toward-better-documentation-461":{"component":"ccc49370","sidebar":"e4eeaf16","content":"2d24a4bd"},"/blog/2016/08/12/react-native-meetup-san-francisco-fa6":{"component":"ccc49370","sidebar":"e4eeaf16","content":"8d2a3815"},"/blog/2016/08/19/right-to-left-support-for-react-native-apps-29f":{"component":"ccc49370","sidebar":"e4eeaf16","content":"7389a049"},"/blog/2016/09/08/exponent-talks-unraveling-navigation-615":{"component":"ccc49370","sidebar":"e4eeaf16","content":"599c3eae"},"/blog/2016/10/25/0.36-headless-js-the-keyboard-api-and-more-86b":{"component":"ccc49370","sidebar":"e4eeaf16","content":"705161da"},"/blog/2016/11/08/introducing-button-yarn-and-a-public-roadmap-89e":{"component":"ccc49370","sidebar":"e4eeaf16","content":"ea850b32"},"/blog/2016/12/05/easier-upgrades-f3b":{"component":"ccc49370","sidebar":"e4eeaf16","content":"0e1c8cbf"},"/blog/2017/01/07/monthly-release-cadence-4c4":{"component":"ccc49370","sidebar":"e4eeaf16","content":"06dbeeca"},"/blog/2017/02/14/using-native-driver-for-animated-522":{"component":"ccc49370","sidebar":"e4eeaf16","content":"bc0a67c5"},"/blog/2017/03/13/better-list-views-d6c":{"component":"ccc49370","sidebar":"e4eeaf16","content":"2e429d93"},"/blog/2017/03/13/idx-the-existential-function-169":{"component":"ccc49370","sidebar":"e4eeaf16","content":"58714218"},"/blog/2017/03/13/introducing-create-react-native-app-d69":{"component":"ccc49370","sidebar":"e4eeaf16","content":"1d122a8c"},"/blog/2017/06/21/react-native-monthly-1-7f5":{"component":"ccc49370","sidebar":"e4eeaf16","content":"02a2ec6a"},"/blog/2017/07/28/react-native-monthly-2-eb9":{"component":"ccc49370","sidebar":"e4eeaf16","content":"cc804fb8"},"/blog/2017/08/07/react-native-performance-in-marketplace-739":{"component":"ccc49370","sidebar":"e4eeaf16","content":"96127592"},"/blog/2017/08/30/react-native-monthly-3-959":{"component":"ccc49370","sidebar":"e4eeaf16","content":"d4a41a82"},"/blog/2017/09/21/react-native-monthly-4-a62":{"component":"ccc49370","sidebar":"e4eeaf16","content":"16a87f3b"},"/blog/2017/11/06/react-native-monthly-5-01d":{"component":"ccc49370","sidebar":"e4eeaf16","content":"d84426ff"},"/blog/2018/01/09/react-native-monthly-6-acf":{"component":"ccc49370","sidebar":"e4eeaf16","content":"56a1ca5f"},"/blog/2018/01/18/implementing-twitters-app-loading-animation-in-react-native-7c3":{"component":"ccc49370","sidebar":"e4eeaf16","content":"36156fac"},"/blog/2018/03/05/AWS-app-sync-f6e":{"component":"ccc49370","sidebar":"e4eeaf16","content":"ca7fc1c2"},"/blog/2018/03/22/building-input-accessory-view-for-react-native-f69":{"component":"ccc49370","sidebar":"e4eeaf16","content":"dcb7c7d4"},"/blog/2018/04/09/build-com-app-376":{"component":"ccc49370","sidebar":"e4eeaf16","content":"7d610914"},"/blog/2018/05/07/using-typescript-with-react-native-26c":{"component":"ccc49370","sidebar":"e4eeaf16","content":"851d21db"},"/blog/2018/06/14/state-of-react-native-2018-98e":{"component":"ccc49370","sidebar":"e4eeaf16","content":"c6529506"},"/blog/2018/07/04/releasing-react-native-056-d80":{"component":"ccc49370","sidebar":"e4eeaf16","content":"819c19cf"},"/blog/2018/08/13/react-native-accessibility-updates-c45":{"component":"ccc49370","sidebar":"e4eeaf16","content":"a94ff3e6"},"/blog/2018/08/27/wkwebview-4ac":{"component":"ccc49370","sidebar":"e4eeaf16","content":"9420bffc"},"/blog/2018/11/01/oss-roadmap-a0e":{"component":"ccc49370","sidebar":"e4eeaf16","content":"d8261dc7"},"/blog/2019/01/07/state-of-react-native-community-640":{"component":"ccc49370","sidebar":"e4eeaf16","content":"5ea7d713"},"/blog/2019/03/01/react-native-open-source-update-9b9":{"component":"ccc49370","sidebar":"e4eeaf16","content":"79606415"},"/blog/2019/03/12/releasing-react-native-059-90e":{"component":"ccc49370","sidebar":"e4eeaf16","content":"c99f9fa0"},"/blog/2019/05/01/react-native-at-f8-and-podcast-28c":{"component":"ccc49370","sidebar":"e4eeaf16","content":"2cbf21ba"},"/blog/2019/06/12/react-native-open-source-update-a4c":{"component":"ccc49370","sidebar":"e4eeaf16","content":"b03d46ef"},"/blog/2019/07/03/version-60-9b3":{"component":"ccc49370","sidebar":"e4eeaf16","content":"6a043830"},"/blog/2019/07/17/hermes-3d1":{"component":"ccc49370","sidebar":"e4eeaf16","content":"46c3d0a9"},"/blog/2019/09/18/version-0.61-88e":{"component":"ccc49370","sidebar":"e4eeaf16","content":"41a5ae70"},"/blog/2019/11/18/react-native-doctor-92e":{"component":"ccc49370","sidebar":"e4eeaf16","content":"7f13d796"},"/blog/2020/03/26/version-0.62-e6d":{"component":"ccc49370","sidebar":"e4eeaf16","content":"d9dd717a"},"/blog/2020/07/06/version-0.63-596":{"component":"ccc49370","sidebar":"e4eeaf16","content":"883f9a8d"},"/blog/2020/07/17/react-native-principles-dba":{"component":"ccc49370","sidebar":"e4eeaf16","content":"bb6e8fd1"},"/blog/2020/07/23/docs-update-52e":{"component":"ccc49370","sidebar":"e4eeaf16","content":"d8f0f300"},"/blog/page/2-d73":{"component":"a6aa9e1f","sidebar":"e4eeaf16","items":[{"content":"09d6acad"},{"content":"aafb9113"},{"content":"f0781116"},{"content":"12ed7ed3"},{"content":"75cbc657"},{"content":"3ec5142c"},{"content":"ca515ec2"},{"content":"a55d8781"},{"content":"c8459538"},{"content":"95b3fd20"}],"metadata":"8eb4e46b"},"/blog/page/3-b82":{"component":"a6aa9e1f","sidebar":"e4eeaf16","items":[{"content":"ef5977c1"},{"content":"e2632152"},{"content":"7dac272e"},{"content":"90fb1d19"},{"content":"b6c98dba"},{"content":"e82978d2"},{"content":"25872cd8"},{"content":"9638e746"},{"content":"f1e5627d"},{"content":"548ca8d1"}],"metadata":"92999a1c"},"/blog/page/4-5ee":{"component":"a6aa9e1f","sidebar":"e4eeaf16","items":[{"content":"a79934fa"},{"content":"af4eba23"},{"content":"4d5605c5"},{"content":"6b9475f3"},{"content":"34190e7c"},{"content":"5bc2ca03"},{"content":"3c5dc301"},{"content":"a2e4a5c5"},{"content":"7dc5c003"},{"content":"255d8fe2"}],"metadata":"7d9726a8"},"/blog/page/5-f2e":{"component":"a6aa9e1f","sidebar":"e4eeaf16","items":[{"content":"6212ddc1"},{"content":"d61f1138"},{"content":"e39a9b1a"},{"content":"3478d373"},{"content":"c65bab12"},{"content":"edbd10a7"},{"content":"b05010f3"},{"content":"deeb80dd"}],"metadata":"11ce4159"},"/blog/tags-5cb":{"component":"01a85c17","sidebar":"e4eeaf16","tags":"a7023ddc"},"/blog/tags/announcement-fde":{"component":"6875c492","sidebar":"e4eeaf16","items":[{"content":"1b94994a"},{"content":"f80d3992"},{"content":"8415f7e8"},{"content":"5860a2aa"},{"content":"3e16fe84"},{"content":"10a433e1"},{"content":"000e4255"},{"content":"474240c1"},{"content":"c02586a2"},{"content":"fb39fd3f"},{"content":"09d6acad"},{"content":"aafb9113"},{"content":"f0781116"},{"content":"12ed7ed3"},{"content":"ca515ec2"},{"content":"34190e7c"},{"content":"5bc2ca03"},{"content":"3c5dc301"},{"content":"a2e4a5c5"},{"content":"d61f1138"},{"content":"e39a9b1a"},{"content":"b05010f3"},{"content":"deeb80dd"}],"metadata":"283e63f8"},"/blog/tags/engineering-1af":{"component":"6875c492","sidebar":"e4eeaf16","items":[{"content":"75cbc657"},{"content":"3ec5142c"},{"content":"a55d8781"},{"content":"c8459538"},{"content":"ef5977c1"},{"content":"e2632152"},{"content":"7dac272e"},{"content":"90fb1d19"},{"content":"b6c98dba"},{"content":"e82978d2"},{"content":"25872cd8"},{"content":"9638e746"},{"content":"f1e5627d"},{"content":"548ca8d1"},{"content":"a79934fa"},{"content":"af4eba23"},{"content":"4d5605c5"},{"content":"6b9475f3"},{"content":"255d8fe2"},{"content":"3478d373"},{"content":"c65bab12"},{"content":"edbd10a7"}],"metadata":"4035650f"},"/blog/tags/events-c31":{"component":"6875c492","sidebar":"e4eeaf16","items":[{"content":"6212ddc1"}],"metadata":"4e71f1c0"},"/blog/tags/release-609":{"component":"6875c492","sidebar":"e4eeaf16","items":[{"content":"8415f7e8"},{"content":"5860a2aa"},{"content":"10a433e1"},{"content":"474240c1"},{"content":"09d6acad"},{"content":"ca515ec2"}],"metadata":"83d480e9"},"/blog/tags/showcase-f2c":{"component":"6875c492","sidebar":"e4eeaf16","items":[{"content":"95b3fd20"}],"metadata":"c92e126f"},"/blog/tags/videos-233":{"component":"6875c492","sidebar":"e4eeaf16","items":[{"content":"7dc5c003"}],"metadata":"4b164ac8"},"/help-ae4":{"component":"1f391b9e","content":"7d87cf11"},"/search-1a1":{"component":"52cb2878"},"/showcase-8cd":{"component":"5fc994c2","config":"5e9f5e1a"},"/versions-b27":{"component":"18b93cb3","config":"5e9f5e1a"},"/docs/0.60-de1":{"component":"1be78505","versionMetadata":"ae345423"},"/docs/0.60/_getting-started-linux-android-7a9":{"component":"17896441","content":"da7d2e01"},"/docs/0.60/_getting-started-macos-android-319":{"component":"17896441","content":"0610fcaf"},"/docs/0.60/_getting-started-macos-ios-036":{"component":"17896441","content":"491006ae"},"/docs/0.60/_getting-started-windows-android-836":{"component":"17896441","content":"1b91f9f9"},"/docs/0.60/_integration-with-exisiting-apps-java-cbf":{"component":"17896441","content":"cd9f97bf"},"/docs/0.60/_integration-with-exisiting-apps-objc-805":{"component":"17896441","content":"435d64c5"},"/docs/0.60/_integration-with-exisiting-apps-swift-310":{"component":"17896441","content":"6d155fa0"},"/docs/0.60/accessibility-57e":{"component":"17896441","content":"15d19118"},"/docs/0.60/accessibilityinfo-167":{"component":"17896441","content":"351c927a"},"/docs/0.60/actionsheetios-c95":{"component":"17896441","content":"c20a56fd"},"/docs/0.60/activityindicator-fd3":{"component":"17896441","content":"1561c8ea"},"/docs/0.60/alert-7b8":{"component":"17896441","content":"b6980d09"},"/docs/0.60/alertios-c66":{"component":"17896441","content":"24332428"},"/docs/0.60/animated-61b":{"component":"17896441","content":"a4260d7a"},"/docs/0.60/animatedvalue-1f3":{"component":"17896441","content":"59b0c720"},"/docs/0.60/animatedvaluexy-ce8":{"component":"17896441","content":"13756c11"},"/docs/0.60/animations-162":{"component":"17896441","content":"14f08b99"},"/docs/0.60/app-extensions-f69":{"component":"17896441","content":"5e8e47ba"},"/docs/0.60/appregistry-eea":{"component":"17896441","content":"890f4ebb"},"/docs/0.60/appstate-4a3":{"component":"17896441","content":"07152dc2"},"/docs/0.60/asyncstorage-8e0":{"component":"17896441","content":"2a8c8580"},"/docs/0.60/backandroid-3f3":{"component":"17896441","content":"5274ce0c"},"/docs/0.60/backhandler-10e":{"component":"17896441","content":"665d2e54"},"/docs/0.60/building-for-tv-96e":{"component":"17896441","content":"1147be69"},"/docs/0.60/button-340":{"component":"17896441","content":"91845232"},"/docs/0.60/cameraroll-454":{"component":"17896441","content":"433f015f"},"/docs/0.60/checkbox-d95":{"component":"17896441","content":"400d0868"},"/docs/0.60/clipboard-1a8":{"component":"17896441","content":"36ba514d"},"/docs/0.60/colors-39d":{"component":"17896441","content":"10239b30"},"/docs/0.60/communication-android-114":{"component":"17896441","content":"31aa6a86"},"/docs/0.60/communication-ios-d9d":{"component":"17896441","content":"c321eebe"},"/docs/0.60/components-and-apis-71e":{"component":"17896441","content":"13ecb700"},"/docs/0.60/custom-webview-android-786":{"component":"17896441","content":"7ab16337"},"/docs/0.60/custom-webview-ios-2c3":{"component":"17896441","content":"4ed6b092"},"/docs/0.60/datepickerandroid-e43":{"component":"17896441","content":"b08da7b7"},"/docs/0.60/datepickerios-e89":{"component":"17896441","content":"e56d60d7"},"/docs/0.60/debugging-1cd":{"component":"17896441","content":"ae33aba6"},"/docs/0.60/devsettings-5d6":{"component":"17896441","content":"7e663a40"},"/docs/0.60/dimensions-eb2":{"component":"17896441","content":"e0228dab"},"/docs/0.60/direct-manipulation-6d6":{"component":"17896441","content":"13be8d72"},"/docs/0.60/drawerlayoutandroid-553":{"component":"17896441","content":"752794cb"},"/docs/0.60/easing-21a":{"component":"17896441","content":"6514134c"},"/docs/0.60/enviroment-setup-2b0":{"component":"17896441","content":"3d2b15b1"},"/docs/0.60/fast-refresh-dbe":{"component":"17896441","content":"60a37cc6"},"/docs/0.60/flatlist-32b":{"component":"17896441","content":"f8c44249"},"/docs/0.60/flexbox-388":{"component":"17896441","content":"cf28e639"},"/docs/0.60/geolocation-51a":{"component":"17896441","content":"aec2dffd"},"/docs/0.60/gesture-responder-system-51a":{"component":"17896441","content":"566efbf4"},"/docs/0.60/getting-started-a00":{"component":"17896441","content":"3b9a58b8"},"/docs/0.60/handling-text-input-453":{"component":"17896441","content":"bc6da410"},"/docs/0.60/handling-touches-349":{"component":"17896441","content":"508f6430"},"/docs/0.60/headless-js-android-24f":{"component":"17896441","content":"9191b784"},"/docs/0.60/height-and-width-c10":{"component":"17896441","content":"8350f025"},"/docs/0.60/hermes-897":{"component":"17896441","content":"f519b310"},"/docs/0.60/image-1ab":{"component":"17896441","content":"ca5b83e6"},"/docs/0.60/image-style-props-a6f":{"component":"17896441","content":"687652c4"},"/docs/0.60/imagebackground-c70":{"component":"17896441","content":"9292c4a8"},"/docs/0.60/imageeditor-e98":{"component":"17896441","content":"fb4c6c4c"},"/docs/0.60/imagepickerios-95e":{"component":"17896441","content":"685a5cd5"},"/docs/0.60/images-782":{"component":"17896441","content":"3dbe00bf"},"/docs/0.60/imagestore-8b6":{"component":"17896441","content":"3c4e2907"},"/docs/0.60/improvingux-0e2":{"component":"17896441","content":"afca9f7c"},"/docs/0.60/inputaccessoryview-f1f":{"component":"17896441","content":"6a4b0ed9"},"/docs/0.60/integration-with-existing-apps-894":{"component":"17896441","content":"4e780783"},"/docs/0.60/interactionmanager-dac":{"component":"17896441","content":"f42d8d60"},"/docs/0.60/intro-react-615":{"component":"17896441","content":"2c270f1a"},"/docs/0.60/intro-react-native-components-e74":{"component":"17896441","content":"576007d6"},"/docs/0.60/javascript-environment-272":{"component":"17896441","content":"2064acd8"},"/docs/0.60/keyboard-476":{"component":"17896441","content":"7b4915c5"},"/docs/0.60/keyboardavoidingview-d7c":{"component":"17896441","content":"5c947ade"},"/docs/0.60/layout-props-c9c":{"component":"17896441","content":"69f06ced"},"/docs/0.60/layoutanimation-231":{"component":"17896441","content":"78dc06fe"},"/docs/0.60/libraries-11b":{"component":"17896441","content":"c5e6a9af"},"/docs/0.60/linking-4b1":{"component":"17896441","content":"34ae458d"},"/docs/0.60/linking-libraries-ios-d2a":{"component":"17896441","content":"158dc741"},"/docs/0.60/listview-7b4":{"component":"17896441","content":"2e67e7ab"},"/docs/0.60/listviewdatasource-2eb":{"component":"17896441","content":"b9929f14"},"/docs/0.60/maskedviewios-fbc":{"component":"17896441","content":"c32b9dc3"},"/docs/0.60/modal-7da":{"component":"17896441","content":"a5246a0f"},"/docs/0.60/more-resources-75b":{"component":"17896441","content":"b0602442"},"/docs/0.60/native-components-android-517":{"component":"17896441","content":"3685bfea"},"/docs/0.60/native-components-ios-6bd":{"component":"17896441","content":"934bbb17"},"/docs/0.60/native-modules-android-fd9":{"component":"17896441","content":"3720ec3a"},"/docs/0.60/native-modules-ios-46e":{"component":"17896441","content":"462596d8"},"/docs/0.60/native-modules-setup-80f":{"component":"17896441","content":"3b2ebaf9"},"/docs/0.60/navigation-0c1":{"component":"17896441","content":"bb0fb218"},"/docs/0.60/netinfo-d14":{"component":"17896441","content":"33d13b30"},"/docs/0.60/network-eb0":{"component":"17896441","content":"d5522ccd"},"/docs/0.60/optimizing-flatlist-configuration-abb":{"component":"17896441","content":"d2f5085f"},"/docs/0.60/out-of-tree-platforms-c24":{"component":"17896441","content":"a801d718"},"/docs/0.60/panresponder-7f1":{"component":"17896441","content":"9b11f5a6"},"/docs/0.60/performance-647":{"component":"17896441","content":"7b11c63d"},"/docs/0.60/permissionsandroid-48a":{"component":"17896441","content":"debbf373"},"/docs/0.60/picker-b27":{"component":"17896441","content":"785b1bcc"},"/docs/0.60/picker-item-a75":{"component":"17896441","content":"2a274c01"},"/docs/0.60/picker-style-props-077":{"component":"17896441","content":"30407f84"},"/docs/0.60/pickerios-b4e":{"component":"17896441","content":"2a0b0f52"},"/docs/0.60/pixelratio-eb9":{"component":"17896441","content":"a1bd78c0"},"/docs/0.60/platform-specific-code-ab7":{"component":"17896441","content":"1dec4f13"},"/docs/0.60/profiling-2a2":{"component":"17896441","content":"14564956"},"/docs/0.60/progressbarandroid-89f":{"component":"17896441","content":"c3f15ad0"},"/docs/0.60/progressviewios-035":{"component":"17896441","content":"f45ef84e"},"/docs/0.60/props-934":{"component":"17896441","content":"eef269ea"},"/docs/0.60/publishing-forks-347":{"component":"17896441","content":"f8ba5ee3"},"/docs/0.60/publishing-to-app-store-094":{"component":"17896441","content":"357a2542"},"/docs/0.60/pushnotificationios-257":{"component":"17896441","content":"7e297770"},"/docs/0.60/ram-bundles-inline-requires-f95":{"component":"17896441","content":"e54b24ba"},"/docs/0.60/react-node-ed5":{"component":"17896441","content":"e68cd9bb"},"/docs/0.60/refreshcontrol-c51":{"component":"17896441","content":"220214ae"},"/docs/0.60/removing-default-permissions-e55":{"component":"17896441","content":"3197591e"},"/docs/0.60/running-on-device-d96":{"component":"17896441","content":"5ab9f23e"},"/docs/0.60/running-on-simulator-ios-0ad":{"component":"17896441","content":"25a14669"},"/docs/0.60/safeareaview-a76":{"component":"17896441","content":"a005b0de"},"/docs/0.60/scrollview-310":{"component":"17896441","content":"5d6b555e"},"/docs/0.60/sectionlist-f5f":{"component":"17896441","content":"c8a1aba7"},"/docs/0.60/segmentedcontrolios-dd9":{"component":"17896441","content":"04880f05"},"/docs/0.60/settings-eb3":{"component":"17896441","content":"f376c1ba"},"/docs/0.60/shadow-props-288":{"component":"17896441","content":"04d026e1"},"/docs/0.60/share-5e9":{"component":"17896441","content":"9a4b2383"},"/docs/0.60/signed-apk-android-b9a":{"component":"17896441","content":"1d42b9bf"},"/docs/0.60/slider-fd8":{"component":"17896441","content":"6d55b064"},"/docs/0.60/snapshotviewios-571":{"component":"17896441","content":"061be8cb"},"/docs/0.60/state-edf":{"component":"17896441","content":"ae6557f2"},"/docs/0.60/statusbar-20c":{"component":"17896441","content":"f709df44"},"/docs/0.60/statusbarios-88d":{"component":"17896441","content":"3850c699"},"/docs/0.60/style-93f":{"component":"17896441","content":"e71f3e9f"},"/docs/0.60/stylesheet-f0f":{"component":"17896441","content":"e8954212"},"/docs/0.60/switch-114":{"component":"17896441","content":"6ee07ff2"},"/docs/0.60/symbolication-83a":{"component":"17896441","content":"f99a4625"},"/docs/0.60/systrace-0ee":{"component":"17896441","content":"d17ff59a"},"/docs/0.60/tabbarios-821":{"component":"17896441","content":"86f6bb70"},"/docs/0.60/tabbarios-item-714":{"component":"17896441","content":"347c574c"},"/docs/0.60/testing-overview-02d":{"component":"17896441","content":"1e32ca81"},"/docs/0.60/text-019":{"component":"17896441","content":"7f1405b3"},"/docs/0.60/text-style-props-a56":{"component":"17896441","content":"b781af53"},"/docs/0.60/textinput-bb9":{"component":"17896441","content":"ab758848"},"/docs/0.60/timepickerandroid-b24":{"component":"17896441","content":"90174253"},"/docs/0.60/timers-869":{"component":"17896441","content":"05fe862d"},"/docs/0.60/toastandroid-7e9":{"component":"17896441","content":"e63d275a"},"/docs/0.60/toolbarandroid-075":{"component":"17896441","content":"f369b317"},"/docs/0.60/touchablehighlight-f2a":{"component":"17896441","content":"5c59779f"},"/docs/0.60/touchablenativefeedback-cb5":{"component":"17896441","content":"8468d755"},"/docs/0.60/touchableopacity-5d5":{"component":"17896441","content":"241094f9"},"/docs/0.60/touchablewithoutfeedback-b50":{"component":"17896441","content":"773809e7"},"/docs/0.60/transforms-332":{"component":"17896441","content":"f8c820b0"},"/docs/0.60/troubleshooting-4ba":{"component":"17896441","content":"47009838"},"/docs/0.60/tutorial-cec":{"component":"17896441","content":"016893df"},"/docs/0.60/typescript-8f1":{"component":"17896441","content":"cf739439"},"/docs/0.60/upgrading-2fa":{"component":"17896441","content":"60f6ab14"},"/docs/0.60/usewindowdimensions-be0":{"component":"17896441","content":"31a8e6d9"},"/docs/0.60/using-a-listview-177":{"component":"17896441","content":"fb07f6d6"},"/docs/0.60/using-a-scrollview-baa":{"component":"17896441","content":"ed17c357"},"/docs/0.60/vibration-fb4":{"component":"17896441","content":"e86218d7"},"/docs/0.60/vibrationios-60c":{"component":"17896441","content":"f377f687"},"/docs/0.60/view-d24":{"component":"17896441","content":"095361ad"},"/docs/0.60/view-style-props-0d4":{"component":"17896441","content":"f86e9d92"},"/docs/0.60/viewpagerandroid-a68":{"component":"17896441","content":"83591413"},"/docs/0.60/virtualizedlist-8bd":{"component":"17896441","content":"1991f1d0"},"/docs/0.60/webview-386":{"component":"17896441","content":"0cb4e403"},"/docs/0.61-e59":{"component":"1be78505","versionMetadata":"612acc40"},"/docs/0.61/_getting-started-linux-android-a7d":{"component":"17896441","content":"d9771061"},"/docs/0.61/_getting-started-macos-android-686":{"component":"17896441","content":"013df8ee"},"/docs/0.61/_getting-started-macos-ios-0cc":{"component":"17896441","content":"14579441"},"/docs/0.61/_getting-started-windows-android-d98":{"component":"17896441","content":"b43b894e"},"/docs/0.61/_integration-with-exisiting-apps-java-855":{"component":"17896441","content":"876ebd82"},"/docs/0.61/_integration-with-exisiting-apps-objc-d2d":{"component":"17896441","content":"0bd8fd30"},"/docs/0.61/_integration-with-exisiting-apps-swift-140":{"component":"17896441","content":"12f573d6"},"/docs/0.61/accessibility-23b":{"component":"17896441","content":"f9b25962"},"/docs/0.61/accessibilityinfo-0b3":{"component":"17896441","content":"28bf564b"},"/docs/0.61/actionsheetios-378":{"component":"17896441","content":"e1733d89"},"/docs/0.61/activityindicator-570":{"component":"17896441","content":"22b09219"},"/docs/0.61/alert-c26":{"component":"17896441","content":"1183167e"},"/docs/0.61/alertios-761":{"component":"17896441","content":"1649557f"},"/docs/0.61/animated-35b":{"component":"17896441","content":"e4de61da"},"/docs/0.61/animatedvalue-f09":{"component":"17896441","content":"886c1841"},"/docs/0.61/animatedvaluexy-64a":{"component":"17896441","content":"a0708242"},"/docs/0.61/animations-e00":{"component":"17896441","content":"5cdba12f"},"/docs/0.61/app-extensions-1ff":{"component":"17896441","content":"e4e6d7d0"},"/docs/0.61/appregistry-461":{"component":"17896441","content":"bb7fe61c"},"/docs/0.61/appstate-6f9":{"component":"17896441","content":"992395f5"},"/docs/0.61/asyncstorage-6f2":{"component":"17896441","content":"c3405a9e"},"/docs/0.61/backandroid-9f7":{"component":"17896441","content":"5bb9585a"},"/docs/0.61/backhandler-bb2":{"component":"17896441","content":"3c785462"},"/docs/0.61/building-for-tv-46a":{"component":"17896441","content":"b48c743c"},"/docs/0.61/button-352":{"component":"17896441","content":"d7eeaabd"},"/docs/0.61/cameraroll-bc4":{"component":"17896441","content":"73c59645"},"/docs/0.61/checkbox-2e0":{"component":"17896441","content":"d213e613"},"/docs/0.61/clipboard-459":{"component":"17896441","content":"d6f4afd5"},"/docs/0.61/colors-fb9":{"component":"17896441","content":"ac8ac2a8"},"/docs/0.61/communication-android-7a6":{"component":"17896441","content":"4569122b"},"/docs/0.61/communication-ios-730":{"component":"17896441","content":"79637e08"},"/docs/0.61/components-and-apis-5a8":{"component":"17896441","content":"47f483a2"},"/docs/0.61/custom-webview-android-9e1":{"component":"17896441","content":"da23c34e"},"/docs/0.61/custom-webview-ios-d4a":{"component":"17896441","content":"206335ed"},"/docs/0.61/datepickerandroid-39a":{"component":"17896441","content":"5413b951"},"/docs/0.61/datepickerios-e03":{"component":"17896441","content":"437ab0f1"},"/docs/0.61/debugging-a49":{"component":"17896441","content":"fffc8891"},"/docs/0.61/devsettings-7b3":{"component":"17896441","content":"7f578686"},"/docs/0.61/dimensions-94c":{"component":"17896441","content":"4af3dae9"},"/docs/0.61/direct-manipulation-258":{"component":"17896441","content":"41c9d80a"},"/docs/0.61/drawerlayoutandroid-909":{"component":"17896441","content":"6a7b96b4"},"/docs/0.61/easing-297":{"component":"17896441","content":"4d7e552b"},"/docs/0.61/enviroment-setup-c81":{"component":"17896441","content":"46238ea4"},"/docs/0.61/fast-refresh-b1c":{"component":"17896441","content":"61c3ef92"},"/docs/0.61/flatlist-a32":{"component":"17896441","content":"e75c8dcf"},"/docs/0.61/flexbox-65e":{"component":"17896441","content":"bd95ffcf"},"/docs/0.61/geolocation-469":{"component":"17896441","content":"1436dd61"},"/docs/0.61/gesture-responder-system-be4":{"component":"17896441","content":"84845ea3"},"/docs/0.61/getting-started-108":{"component":"17896441","content":"e134cd68"},"/docs/0.61/handling-text-input-058":{"component":"17896441","content":"834b7c6c"},"/docs/0.61/handling-touches-d80":{"component":"17896441","content":"d86f448b"},"/docs/0.61/headless-js-android-a4f":{"component":"17896441","content":"85b948c0"},"/docs/0.61/height-and-width-3a4":{"component":"17896441","content":"96563b6f"},"/docs/0.61/hermes-5a5":{"component":"17896441","content":"7475196c"},"/docs/0.61/image-57c":{"component":"17896441","content":"4cd0d644"},"/docs/0.61/image-style-props-0cb":{"component":"17896441","content":"14072d63"},"/docs/0.61/imagebackground-319":{"component":"17896441","content":"04d8b36f"},"/docs/0.61/imageeditor-912":{"component":"17896441","content":"43321b76"},"/docs/0.61/imagepickerios-d60":{"component":"17896441","content":"254896da"},"/docs/0.61/images-be5":{"component":"17896441","content":"48ac76d0"},"/docs/0.61/imagestore-3c2":{"component":"17896441","content":"1e76d198"},"/docs/0.61/improvingux-7ee":{"component":"17896441","content":"f72da453"},"/docs/0.61/inputaccessoryview-02f":{"component":"17896441","content":"54b3046f"},"/docs/0.61/integration-with-existing-apps-024":{"component":"17896441","content":"242085a9"},"/docs/0.61/interactionmanager-c0a":{"component":"17896441","content":"19a5b1d2"},"/docs/0.61/intro-react-24e":{"component":"17896441","content":"5ea12eed"},"/docs/0.61/intro-react-native-components-bbb":{"component":"17896441","content":"d9fc0c3b"},"/docs/0.61/javascript-environment-c58":{"component":"17896441","content":"be044482"},"/docs/0.61/keyboard-190":{"component":"17896441","content":"5bde6ca0"},"/docs/0.61/keyboardavoidingview-af7":{"component":"17896441","content":"75a2f75c"},"/docs/0.61/layout-props-caf":{"component":"17896441","content":"bade5be2"},"/docs/0.61/layoutanimation-19f":{"component":"17896441","content":"7d7c4550"},"/docs/0.61/libraries-469":{"component":"17896441","content":"aedeae28"},"/docs/0.61/linking-627":{"component":"17896441","content":"322434af"},"/docs/0.61/linking-libraries-ios-0a9":{"component":"17896441","content":"a4840fd9"},"/docs/0.61/listview-999":{"component":"17896441","content":"7dc22993"},"/docs/0.61/listviewdatasource-d9b":{"component":"17896441","content":"468562ab"},"/docs/0.61/maskedviewios-a8d":{"component":"17896441","content":"93e1756f"},"/docs/0.61/modal-c5d":{"component":"17896441","content":"897c3130"},"/docs/0.61/more-resources-bd9":{"component":"17896441","content":"c765398d"},"/docs/0.61/native-components-android-b2d":{"component":"17896441","content":"7e2a8c83"},"/docs/0.61/native-components-ios-281":{"component":"17896441","content":"331027c4"},"/docs/0.61/native-modules-android-fcd":{"component":"17896441","content":"fb7890ac"},"/docs/0.61/native-modules-ios-7bc":{"component":"17896441","content":"974128a0"},"/docs/0.61/native-modules-setup-efa":{"component":"17896441","content":"deff4c36"},"/docs/0.61/navigation-257":{"component":"17896441","content":"64ae864e"},"/docs/0.61/netinfo-8c7":{"component":"17896441","content":"a59afaf3"},"/docs/0.61/network-467":{"component":"17896441","content":"d23b9a88"},"/docs/0.61/optimizing-flatlist-configuration-657":{"component":"17896441","content":"510d0fde"},"/docs/0.61/out-of-tree-platforms-e06":{"component":"17896441","content":"41a318d4"},"/docs/0.61/panresponder-7b6":{"component":"17896441","content":"e99bf285"},"/docs/0.61/performance-d53":{"component":"17896441","content":"5a88c0c4"},"/docs/0.61/permissionsandroid-ac0":{"component":"17896441","content":"9a0438c0"},"/docs/0.61/picker-ab5":{"component":"17896441","content":"9f229b56"},"/docs/0.61/picker-item-44d":{"component":"17896441","content":"aa94539e"},"/docs/0.61/picker-style-props-25a":{"component":"17896441","content":"f38824e0"},"/docs/0.61/pickerios-29f":{"component":"17896441","content":"8db40315"},"/docs/0.61/pixelratio-8bf":{"component":"17896441","content":"3ae130fb"},"/docs/0.61/platform-specific-code-35d":{"component":"17896441","content":"323f7597"},"/docs/0.61/profiling-7d9":{"component":"17896441","content":"f50ecffe"},"/docs/0.61/progressbarandroid-abb":{"component":"17896441","content":"81bf7b52"},"/docs/0.61/progressviewios-3d4":{"component":"17896441","content":"b18116ec"},"/docs/0.61/props-692":{"component":"17896441","content":"28c3dbb0"},"/docs/0.61/publishing-forks-f72":{"component":"17896441","content":"40e4fe25"},"/docs/0.61/publishing-to-app-store-ff9":{"component":"17896441","content":"c1375958"},"/docs/0.61/pushnotificationios-fb8":{"component":"17896441","content":"367a1439"},"/docs/0.61/ram-bundles-inline-requires-bf5":{"component":"17896441","content":"bb9ba8d2"},"/docs/0.61/react-node-249":{"component":"17896441","content":"f13e3f54"},"/docs/0.61/refreshcontrol-e11":{"component":"17896441","content":"cde73c6c"},"/docs/0.61/removing-default-permissions-4ba":{"component":"17896441","content":"e74e5362"},"/docs/0.61/running-on-device-137":{"component":"17896441","content":"af03a8a7"},"/docs/0.61/running-on-simulator-ios-424":{"component":"17896441","content":"bcbd47e6"},"/docs/0.61/safeareaview-9bb":{"component":"17896441","content":"c04f20ac"},"/docs/0.61/scrollview-9bf":{"component":"17896441","content":"195918eb"},"/docs/0.61/sectionlist-00f":{"component":"17896441","content":"5e95e760"},"/docs/0.61/segmentedcontrolios-945":{"component":"17896441","content":"0162b7d8"},"/docs/0.61/settings-8bd":{"component":"17896441","content":"ad643e90"},"/docs/0.61/shadow-props-f14":{"component":"17896441","content":"17246e92"},"/docs/0.61/share-5e0":{"component":"17896441","content":"6c03c280"},"/docs/0.61/signed-apk-android-2d1":{"component":"17896441","content":"c0b69977"},"/docs/0.61/slider-65c":{"component":"17896441","content":"894b41b7"},"/docs/0.61/snapshotviewios-b42":{"component":"17896441","content":"b895e222"},"/docs/0.61/state-27c":{"component":"17896441","content":"1776f9a8"},"/docs/0.61/statusbar-b1a":{"component":"17896441","content":"0113de48"},"/docs/0.61/statusbarios-9ba":{"component":"17896441","content":"f5d4e6c0"},"/docs/0.61/style-29e":{"component":"17896441","content":"c471ee40"},"/docs/0.61/stylesheet-dd2":{"component":"17896441","content":"e54e158b"},"/docs/0.61/switch-a1b":{"component":"17896441","content":"22bd5062"},"/docs/0.61/symbolication-93d":{"component":"17896441","content":"9d7841a6"},"/docs/0.61/systrace-106":{"component":"17896441","content":"b65e3879"},"/docs/0.61/tabbarios-d0c":{"component":"17896441","content":"ebb9924f"},"/docs/0.61/tabbarios-item-b49":{"component":"17896441","content":"f6aa657d"},"/docs/0.61/testing-overview-bbb":{"component":"17896441","content":"6facc053"},"/docs/0.61/text-b06":{"component":"17896441","content":"2abfc8e9"},"/docs/0.61/text-style-props-626":{"component":"17896441","content":"5f11f436"},"/docs/0.61/textinput-f90":{"component":"17896441","content":"cbde5814"},"/docs/0.61/timepickerandroid-1bf":{"component":"17896441","content":"2064796d"},"/docs/0.61/timers-5ac":{"component":"17896441","content":"9ce8c857"},"/docs/0.61/toastandroid-298":{"component":"17896441","content":"482f33d1"},"/docs/0.61/toolbarandroid-002":{"component":"17896441","content":"368862d5"},"/docs/0.61/touchablehighlight-5be":{"component":"17896441","content":"111dce5a"},"/docs/0.61/touchablenativefeedback-1e6":{"component":"17896441","content":"03823c9e"},"/docs/0.61/touchableopacity-4f4":{"component":"17896441","content":"b13f7081"},"/docs/0.61/touchablewithoutfeedback-054":{"component":"17896441","content":"19decc0f"},"/docs/0.61/transforms-bc6":{"component":"17896441","content":"ec0cef18"},"/docs/0.61/troubleshooting-83f":{"component":"17896441","content":"8f1bc33b"},"/docs/0.61/tutorial-f96":{"component":"17896441","content":"88d46e6b"},"/docs/0.61/typescript-768":{"component":"17896441","content":"8433fd06"},"/docs/0.61/upgrading-b25":{"component":"17896441","content":"3a16d1b3"},"/docs/0.61/usewindowdimensions-22a":{"component":"17896441","content":"3ef8cb4c"},"/docs/0.61/using-a-listview-b4f":{"component":"17896441","content":"72bc9b35"},"/docs/0.61/using-a-scrollview-d8f":{"component":"17896441","content":"1cffdbb6"},"/docs/0.61/vibration-2d2":{"component":"17896441","content":"3a09cd40"},"/docs/0.61/vibrationios-45a":{"component":"17896441","content":"ab30cbd3"},"/docs/0.61/view-338":{"component":"17896441","content":"821ec642"},"/docs/0.61/view-style-props-4a3":{"component":"17896441","content":"e27312cf"},"/docs/0.61/viewpagerandroid-17e":{"component":"17896441","content":"18b06fce"},"/docs/0.61/virtualizedlist-929":{"component":"17896441","content":"d95c8f46"},"/docs/0.61/webview-cd9":{"component":"17896441","content":"17d2b0bf"},"/docs/0.62-67a":{"component":"1be78505","versionMetadata":"3225cd47"},"/docs/0.62/_getting-started-linux-android-b12":{"component":"17896441","content":"dd977e17"},"/docs/0.62/_getting-started-macos-android-dd9":{"component":"17896441","content":"0682dcf3"},"/docs/0.62/_getting-started-macos-ios-730":{"component":"17896441","content":"09380ea4"},"/docs/0.62/_getting-started-windows-android-b16":{"component":"17896441","content":"b1958e88"},"/docs/0.62/_integration-with-exisiting-apps-java-f0c":{"component":"17896441","content":"f409b16a"},"/docs/0.62/_integration-with-exisiting-apps-objc-2f9":{"component":"17896441","content":"3989dd08"},"/docs/0.62/_integration-with-exisiting-apps-swift-3ec":{"component":"17896441","content":"4187460b"},"/docs/0.62/accessibility-572":{"component":"17896441","content":"2b74fe53"},"/docs/0.62/accessibilityinfo-0a1":{"component":"17896441","content":"1b7a1c97"},"/docs/0.62/actionsheetios-4fc":{"component":"17896441","content":"573e343a"},"/docs/0.62/activityindicator-67c":{"component":"17896441","content":"0134e503"},"/docs/0.62/alert-7c8":{"component":"17896441","content":"27c287d5"},"/docs/0.62/alertios-b7b":{"component":"17896441","content":"e6affce3"},"/docs/0.62/animated-2b1":{"component":"17896441","content":"823d0021"},"/docs/0.62/animatedvalue-9e9":{"component":"17896441","content":"8f410f86"},"/docs/0.62/animatedvaluexy-be5":{"component":"17896441","content":"c6ccdd92"},"/docs/0.62/animations-156":{"component":"17896441","content":"b572ea45"},"/docs/0.62/app-extensions-46d":{"component":"17896441","content":"1341ea5f"},"/docs/0.62/appearance-b8b":{"component":"17896441","content":"6b0c2131"},"/docs/0.62/appregistry-1b8":{"component":"17896441","content":"e0e7e471"},"/docs/0.62/appstate-95e":{"component":"17896441","content":"926a67e2"},"/docs/0.62/asyncstorage-29f":{"component":"17896441","content":"90e4c999"},"/docs/0.62/backandroid-65f":{"component":"17896441","content":"761d7b6c"},"/docs/0.62/backhandler-896":{"component":"17896441","content":"63661315"},"/docs/0.62/building-for-tv-9ef":{"component":"17896441","content":"17e8229c"},"/docs/0.62/button-f3f":{"component":"17896441","content":"e5db101b"},"/docs/0.62/cameraroll-d07":{"component":"17896441","content":"308fea9d"},"/docs/0.62/checkbox-f47":{"component":"17896441","content":"d20cca0a"},"/docs/0.62/clipboard-9cd":{"component":"17896441","content":"5067ce67"},"/docs/0.62/colors-e4c":{"component":"17896441","content":"c6452bdd"},"/docs/0.62/communication-android-729":{"component":"17896441","content":"205f25c5"},"/docs/0.62/communication-ios-9aa":{"component":"17896441","content":"eedb97d6"},"/docs/0.62/components-and-apis-31c":{"component":"17896441","content":"4500b8eb"},"/docs/0.62/custom-webview-android-9f5":{"component":"17896441","content":"fd431123"},"/docs/0.62/custom-webview-ios-c4f":{"component":"17896441","content":"06617ce3"},"/docs/0.62/datepickerandroid-15f":{"component":"17896441","content":"6264de50"},"/docs/0.62/datepickerios-2c4":{"component":"17896441","content":"c919342f"},"/docs/0.62/debugging-0f4":{"component":"17896441","content":"7f3700e5"},"/docs/0.62/devsettings-5c2":{"component":"17896441","content":"ab8034c4"},"/docs/0.62/dimensions-02b":{"component":"17896441","content":"4278d658"},"/docs/0.62/direct-manipulation-07a":{"component":"17896441","content":"a6cfd53a"},"/docs/0.62/drawerlayoutandroid-2c4":{"component":"17896441","content":"2b318ba9"},"/docs/0.62/easing-355":{"component":"17896441","content":"383b8701"},"/docs/0.62/environment-setup-74b":{"component":"17896441","content":"c6324ea2"},"/docs/0.62/fast-refresh-150":{"component":"17896441","content":"0b8eb888"},"/docs/0.62/flatlist-8c9":{"component":"17896441","content":"7d5ea29d"},"/docs/0.62/flexbox-011":{"component":"17896441","content":"0381e10c"},"/docs/0.62/geolocation-3c2":{"component":"17896441","content":"f7a07462"},"/docs/0.62/gesture-responder-system-dcb":{"component":"17896441","content":"6dee30e3"},"/docs/0.62/getting-started-45c":{"component":"17896441","content":"c30b7302"},"/docs/0.62/handling-text-input-72a":{"component":"17896441","content":"8a81d9fb"},"/docs/0.62/handling-touches-155":{"component":"17896441","content":"8d200fe2"},"/docs/0.62/headless-js-android-269":{"component":"17896441","content":"dc851d74"},"/docs/0.62/height-and-width-624":{"component":"17896441","content":"b6f4c1b5"},"/docs/0.62/hermes-f26":{"component":"17896441","content":"b3efa165"},"/docs/0.62/image-ebc":{"component":"17896441","content":"7b11743b"},"/docs/0.62/image-style-props-101":{"component":"17896441","content":"85d88de8"},"/docs/0.62/imagebackground-93e":{"component":"17896441","content":"bdca5f7d"},"/docs/0.62/imageeditor-1d1":{"component":"17896441","content":"f20eb978"},"/docs/0.62/imagepickerios-717":{"component":"17896441","content":"0f17e2b5"},"/docs/0.62/images-1e8":{"component":"17896441","content":"6110e44e"},"/docs/0.62/imagestore-fe9":{"component":"17896441","content":"ec58a1a2"},"/docs/0.62/improvingux-89f":{"component":"17896441","content":"180ecd18"},"/docs/0.62/inputaccessoryview-4a5":{"component":"17896441","content":"9e7a737a"},"/docs/0.62/integration-with-existing-apps-d89":{"component":"17896441","content":"aa48c9a9"},"/docs/0.62/interactionmanager-ae8":{"component":"17896441","content":"3166412f"},"/docs/0.62/intro-react-ce9":{"component":"17896441","content":"1238c218"},"/docs/0.62/intro-react-native-components-075":{"component":"17896441","content":"df977b50"},"/docs/0.62/javascript-environment-d81":{"component":"17896441","content":"63afa6f3"},"/docs/0.62/keyboard-ac6":{"component":"17896441","content":"8108b2a0"},"/docs/0.62/keyboardavoidingview-648":{"component":"17896441","content":"47b6d344"},"/docs/0.62/layout-props-1a0":{"component":"17896441","content":"929868a8"},"/docs/0.62/layoutanimation-301":{"component":"17896441","content":"7466d0a0"},"/docs/0.62/libraries-36e":{"component":"17896441","content":"c739809a"},"/docs/0.62/linking-4b7":{"component":"17896441","content":"aa970452"},"/docs/0.62/linking-libraries-ios-59b":{"component":"17896441","content":"d5328ad9"},"/docs/0.62/listview-1d5":{"component":"17896441","content":"b8331aea"},"/docs/0.62/listviewdatasource-fca":{"component":"17896441","content":"dd87eb86"},"/docs/0.62/maskedviewios-2b8":{"component":"17896441","content":"ebd90c78"},"/docs/0.62/modal-a68":{"component":"17896441","content":"5ed9707f"},"/docs/0.62/more-resources-c4b":{"component":"17896441","content":"ed46505b"},"/docs/0.62/native-components-android-bca":{"component":"17896441","content":"c979e9a2"},"/docs/0.62/native-components-ios-3d0":{"component":"17896441","content":"03afeb21"},"/docs/0.62/native-modules-android-a2a":{"component":"17896441","content":"db3a23d3"},"/docs/0.62/native-modules-ios-f69":{"component":"17896441","content":"dc52bde6"},"/docs/0.62/native-modules-setup-c87":{"component":"17896441","content":"37b07cc8"},"/docs/0.62/navigation-77a":{"component":"17896441","content":"fcfc7edb"},"/docs/0.62/netinfo-8c8":{"component":"17896441","content":"314f6b69"},"/docs/0.62/network-f72":{"component":"17896441","content":"9b4de234"},"/docs/0.62/optimizing-flatlist-configuration-b11":{"component":"17896441","content":"236d20a0"},"/docs/0.62/out-of-tree-platforms-748":{"component":"17896441","content":"1d9b24c5"},"/docs/0.62/panresponder-d4b":{"component":"17896441","content":"a324edc4"},"/docs/0.62/performance-de9":{"component":"17896441","content":"7b9f5c43"},"/docs/0.62/permissionsandroid-164":{"component":"17896441","content":"2dbeca2b"},"/docs/0.62/picker-75f":{"component":"17896441","content":"d0f7f320"},"/docs/0.62/picker-item-398":{"component":"17896441","content":"23caeb76"},"/docs/0.62/picker-style-props-b3c":{"component":"17896441","content":"767dbf5c"},"/docs/0.62/pickerios-8f1":{"component":"17896441","content":"4dde660e"},"/docs/0.62/pixelratio-77e":{"component":"17896441","content":"7013eb56"},"/docs/0.62/platform-specific-code-b83":{"component":"17896441","content":"fa0076d2"},"/docs/0.62/profiling-7a8":{"component":"17896441","content":"e96346cb"},"/docs/0.62/progressbarandroid-db7":{"component":"17896441","content":"ff052b88"},"/docs/0.62/progressviewios-ffb":{"component":"17896441","content":"96c0febb"},"/docs/0.62/props-ad5":{"component":"17896441","content":"16b989c8"},"/docs/0.62/publishing-forks-79f":{"component":"17896441","content":"e9ccf5c1"},"/docs/0.62/publishing-to-app-store-9e0":{"component":"17896441","content":"71a25ccc"},"/docs/0.62/pushnotificationios-fb7":{"component":"17896441","content":"18a36238"},"/docs/0.62/ram-bundles-inline-requires-e79":{"component":"17896441","content":"e7be48af"},"/docs/0.62/react-node-f8a":{"component":"17896441","content":"c55a72fd"},"/docs/0.62/refreshcontrol-b31":{"component":"17896441","content":"b169afdc"},"/docs/0.62/removing-default-permissions-9b7":{"component":"17896441","content":"e30d5e13"},"/docs/0.62/running-on-device-8f3":{"component":"17896441","content":"adb6fec0"},"/docs/0.62/running-on-simulator-ios-b55":{"component":"17896441","content":"73a98413"},"/docs/0.62/safeareaview-749":{"component":"17896441","content":"4d914cb8"},"/docs/0.62/scrollview-89c":{"component":"17896441","content":"59d3f50c"},"/docs/0.62/sectionlist-2d0":{"component":"17896441","content":"96d80b62"},"/docs/0.62/security-04e":{"component":"17896441","content":"251bb219"},"/docs/0.62/segmentedcontrolios-f54":{"component":"17896441","content":"b729b43d"},"/docs/0.62/settings-d06":{"component":"17896441","content":"167ab2c1"},"/docs/0.62/shadow-props-fbe":{"component":"17896441","content":"f982d982"},"/docs/0.62/share-7c0":{"component":"17896441","content":"9a377d24"},"/docs/0.62/signed-apk-android-b0d":{"component":"17896441","content":"da29fa18"},"/docs/0.62/slider-5a0":{"component":"17896441","content":"fecd2c75"},"/docs/0.62/snapshotviewios-f6f":{"component":"17896441","content":"afc5c42c"},"/docs/0.62/state-bd3":{"component":"17896441","content":"74725330"},"/docs/0.62/statusbar-cfd":{"component":"17896441","content":"16f2163f"},"/docs/0.62/statusbarios-69e":{"component":"17896441","content":"e11a1dea"},"/docs/0.62/style-003":{"component":"17896441","content":"a3cb7940"},"/docs/0.62/stylesheet-97c":{"component":"17896441","content":"e6a1d6e1"},"/docs/0.62/switch-395":{"component":"17896441","content":"89572050"},"/docs/0.62/symbolication-e48":{"component":"17896441","content":"ed345fd3"},"/docs/0.62/systrace-953":{"component":"17896441","content":"94ca852c"},"/docs/0.62/tabbarios-ba3":{"component":"17896441","content":"63089b0f"},"/docs/0.62/tabbarios-item-804":{"component":"17896441","content":"58352d7c"},"/docs/0.62/testing-overview-8a0":{"component":"17896441","content":"031dadc3"},"/docs/0.62/text-f1a":{"component":"17896441","content":"266e9e0d"},"/docs/0.62/text-style-props-c8a":{"component":"17896441","content":"ac18e48f"},"/docs/0.62/textinput-3eb":{"component":"17896441","content":"80e09ee0"},"/docs/0.62/timepickerandroid-ec0":{"component":"17896441","content":"32648f1f"},"/docs/0.62/timers-b84":{"component":"17896441","content":"d152400d"},"/docs/0.62/toastandroid-394":{"component":"17896441","content":"935f22f9"},"/docs/0.62/toolbarandroid-44e":{"component":"17896441","content":"a9b2e890"},"/docs/0.62/touchablehighlight-386":{"component":"17896441","content":"ecb749fb"},"/docs/0.62/touchablenativefeedback-0ba":{"component":"17896441","content":"fad5a9d8"},"/docs/0.62/touchableopacity-401":{"component":"17896441","content":"0ee7189f"},"/docs/0.62/touchablewithoutfeedback-206":{"component":"17896441","content":"e523b5d2"},"/docs/0.62/transforms-61a":{"component":"17896441","content":"97eab971"},"/docs/0.62/troubleshooting-29a":{"component":"17896441","content":"917c7445"},"/docs/0.62/tutorial-c4e":{"component":"17896441","content":"eecf3277"},"/docs/0.62/typescript-97d":{"component":"17896441","content":"aa5e9ce5"},"/docs/0.62/upgrading-74d":{"component":"17896441","content":"4e53bc35"},"/docs/0.62/usecolorscheme-afd":{"component":"17896441","content":"7fd2fe43"},"/docs/0.62/usewindowdimensions-fbc":{"component":"17896441","content":"c24f6877"},"/docs/0.62/using-a-listview-f1e":{"component":"17896441","content":"41fd3644"},"/docs/0.62/using-a-scrollview-70d":{"component":"17896441","content":"ab0efe48"},"/docs/0.62/vibration-02f":{"component":"17896441","content":"b9644d85"},"/docs/0.62/vibrationios-a9c":{"component":"17896441","content":"c3d853d2"},"/docs/0.62/view-609":{"component":"17896441","content":"df0f44cc"},"/docs/0.62/view-style-props-91d":{"component":"17896441","content":"cd9d21a8"},"/docs/0.62/viewpagerandroid-2cc":{"component":"17896441","content":"cd596740"},"/docs/0.62/virtualizedlist-efa":{"component":"17896441","content":"c9019225"},"/docs/0.62/webview-0a2":{"component":"17896441","content":"5454f477"},"/docs/next-b82":{"component":"1be78505","versionMetadata":"935f2afb"},"/docs/next/_getting-started-linux-android-514":{"component":"17896441","content":"27ab3e5c"},"/docs/next/_getting-started-macos-android-cd2":{"component":"17896441","content":"cd82ed0c"},"/docs/next/_getting-started-macos-ios-7e0":{"component":"17896441","content":"0db00fd5"},"/docs/next/_getting-started-windows-android-0ad":{"component":"17896441","content":"8958cfa5"},"/docs/next/_integration-with-exisiting-apps-java-61a":{"component":"17896441","content":"fef033aa"},"/docs/next/_integration-with-exisiting-apps-objc-3c3":{"component":"17896441","content":"5643c4b6"},"/docs/next/_integration-with-exisiting-apps-swift-27c":{"component":"17896441","content":"9923d56c"},"/docs/next/accessibility-9a3":{"component":"17896441","content":"bbfb3da7"},"/docs/next/accessibilityinfo-ea2":{"component":"17896441","content":"0a45b3b8"},"/docs/next/actionsheetios-4da":{"component":"17896441","content":"3be176d8"},"/docs/next/activityindicator-fe8":{"component":"17896441","content":"28a6fbe0"},"/docs/next/alert-6b5":{"component":"17896441","content":"9411c98e"},"/docs/next/alertios-70b":{"component":"17896441","content":"3a352c47"},"/docs/next/animated-9ad":{"component":"17896441","content":"3f346abc"},"/docs/next/animatedvalue-e7e":{"component":"17896441","content":"b4f312c9"},"/docs/next/animatedvaluexy-aa3":{"component":"17896441","content":"98827d55"},"/docs/next/animations-db2":{"component":"17896441","content":"d2244b4f"},"/docs/next/app-extensions-477":{"component":"17896441","content":"139f0f71"},"/docs/next/appearance-546":{"component":"17896441","content":"35f94fe6"},"/docs/next/appregistry-b51":{"component":"17896441","content":"512a65de"},"/docs/next/appstate-bc4":{"component":"17896441","content":"1133700b"},"/docs/next/asyncstorage-3aa":{"component":"17896441","content":"69fd90d1"},"/docs/next/backhandler-211":{"component":"17896441","content":"e144acb5"},"/docs/next/building-for-tv-b85":{"component":"17896441","content":"8809b0cf"},"/docs/next/button-516":{"component":"17896441","content":"c8714a34"},"/docs/next/checkbox-443":{"component":"17896441","content":"eed5134c"},"/docs/next/clipboard-43e":{"component":"17896441","content":"68ec835b"},"/docs/next/colors-44a":{"component":"17896441","content":"b7610e1d"},"/docs/next/communication-android-cf8":{"component":"17896441","content":"7d4f3f69"},"/docs/next/communication-ios-54a":{"component":"17896441","content":"fcb2821f"},"/docs/next/components-and-apis-e78":{"component":"17896441","content":"30931ae2"},"/docs/next/custom-webview-android-fef":{"component":"17896441","content":"d2e2363f"},"/docs/next/custom-webview-ios-14f":{"component":"17896441","content":"36a41bf6"},"/docs/next/datepickerandroid-7df":{"component":"17896441","content":"f394f53e"},"/docs/next/datepickerios-a03":{"component":"17896441","content":"11ab2b2a"},"/docs/next/debugging-cae":{"component":"17896441","content":"03abeb31"},"/docs/next/devsettings-c4e":{"component":"17896441","content":"b8532dfe"},"/docs/next/dimensions-89b":{"component":"17896441","content":"e59c7b81"},"/docs/next/direct-manipulation-8fb":{"component":"17896441","content":"c5f28506"},"/docs/next/drawerlayoutandroid-a74":{"component":"17896441","content":"8c3f6154"},"/docs/next/dynamiccolorios-768":{"component":"17896441","content":"24902f7b"},"/docs/next/easing-2e1":{"component":"17896441","content":"1824828e"},"/docs/next/environment-setup-fa7":{"component":"17896441","content":"8d0344ba"},"/docs/next/fast-refresh-b36":{"component":"17896441","content":"31f827f6"},"/docs/next/flatlist-385":{"component":"17896441","content":"e532ff9a"},"/docs/next/flexbox-b20":{"component":"17896441","content":"2164b80c"},"/docs/next/gesture-responder-system-2b7":{"component":"17896441","content":"187601ca"},"/docs/next/getting-started-50d":{"component":"17896441","content":"53e18611"},"/docs/next/handling-text-input-f8b":{"component":"17896441","content":"6f9c78b3"},"/docs/next/handling-touches-44f":{"component":"17896441","content":"704041cf"},"/docs/next/headless-js-android-c22":{"component":"17896441","content":"041c8a3a"},"/docs/next/height-and-width-8cf":{"component":"17896441","content":"d46848ea"},"/docs/next/hermes-b77":{"component":"17896441","content":"8138966c"},"/docs/next/image-4e1":{"component":"17896441","content":"4261946e"},"/docs/next/image-style-props-cae":{"component":"17896441","content":"a8348dc4"},"/docs/next/imagebackground-5a9":{"component":"17896441","content":"c9794e3d"},"/docs/next/imageeditor-957":{"component":"17896441","content":"31628381"},"/docs/next/imagepickerios-b17":{"component":"17896441","content":"94950cdb"},"/docs/next/images-cdd":{"component":"17896441","content":"4077767d"},"/docs/next/improvingux-1be":{"component":"17896441","content":"72ec4586"},"/docs/next/inputaccessoryview-b8f":{"component":"17896441","content":"9ad9f1c5"},"/docs/next/integration-with-android-fragment-f4c":{"component":"17896441","content":"f8837b93"},"/docs/next/integration-with-existing-apps-e68":{"component":"17896441","content":"64917a7d"},"/docs/next/interactionmanager-1a4":{"component":"17896441","content":"73b25ad1"},"/docs/next/intro-react-554":{"component":"17896441","content":"6ae83c29"},"/docs/next/intro-react-native-components-43f":{"component":"17896441","content":"6dbdb7cc"},"/docs/next/javascript-environment-c36":{"component":"17896441","content":"3d5c671e"},"/docs/next/keyboard-540":{"component":"17896441","content":"4634eb62"},"/docs/next/keyboardavoidingview-d4c":{"component":"17896441","content":"089b6170"},"/docs/next/layout-props-b0c":{"component":"17896441","content":"d7e83092"},"/docs/next/layoutanimation-423":{"component":"17896441","content":"41d2484e"},"/docs/next/layoutevent-b04":{"component":"17896441","content":"495376dd"},"/docs/next/libraries-161":{"component":"17896441","content":"4ec33e7a"},"/docs/next/linking-b7e":{"component":"17896441","content":"e6601706"},"/docs/next/linking-libraries-ios-007":{"component":"17896441","content":"9298a130"},"/docs/next/modal-f34":{"component":"17896441","content":"9195600f"},"/docs/next/more-resources-2a8":{"component":"17896441","content":"60a7adbd"},"/docs/next/native-components-android-70e":{"component":"17896441","content":"3c7ff13b"},"/docs/next/native-components-ios-99f":{"component":"17896441","content":"7b081642"},"/docs/next/native-modules-android-bb3":{"component":"17896441","content":"f0b9a8a6"},"/docs/next/native-modules-intro-190":{"component":"17896441","content":"f4be639c"},"/docs/next/native-modules-ios-bd3":{"component":"17896441","content":"51cfd875"},"/docs/next/native-modules-setup-17c":{"component":"17896441","content":"63d21e01"},"/docs/next/navigation-26a":{"component":"17896441","content":"2b33dcf6"},"/docs/next/network-bad":{"component":"17896441","content":"91478e86"},"/docs/next/optimizing-flatlist-configuration-64f":{"component":"17896441","content":"13399709"},"/docs/next/out-of-tree-platforms-447":{"component":"17896441","content":"8987e215"},"/docs/next/panresponder-2d8":{"component":"17896441","content":"f6bc61d0"},"/docs/next/performance-a0a":{"component":"17896441","content":"cfacefa6"},"/docs/next/permissionsandroid-77c":{"component":"17896441","content":"c398d642"},"/docs/next/picker-ae5":{"component":"17896441","content":"1588eb58"},"/docs/next/picker-item-ffe":{"component":"17896441","content":"6d2bdc62"},"/docs/next/picker-style-props-738":{"component":"17896441","content":"3669acd0"},"/docs/next/pickerios-97c":{"component":"17896441","content":"37fdd7bf"},"/docs/next/pixelratio-0ad":{"component":"17896441","content":"8a310b1d"},"/docs/next/platform-62f":{"component":"17896441","content":"bb7cbc4b"},"/docs/next/platform-specific-code-0bd":{"component":"17896441","content":"2366281d"},"/docs/next/platformcolor-a28":{"component":"17896441","content":"bf1e316e"},"/docs/next/pressable-c2d":{"component":"17896441","content":"92a3e3bb"},"/docs/next/pressevent-e7d":{"component":"17896441","content":"77920eb3"},"/docs/next/profile-hermes-3db":{"component":"17896441","content":"2fdae619"},"/docs/next/profiling-337":{"component":"17896441","content":"81e47845"},"/docs/next/progressbarandroid-b0c":{"component":"17896441","content":"c45967cb"},"/docs/next/progressviewios-120":{"component":"17896441","content":"2b4d430a"},"/docs/next/props-f02":{"component":"17896441","content":"b77126b8"},"/docs/next/publishing-to-app-store-60c":{"component":"17896441","content":"11c82506"},"/docs/next/pushnotificationios-99a":{"component":"17896441","content":"296ec483"},"/docs/next/ram-bundles-inline-requires-2b0":{"component":"17896441","content":"789f38e0"},"/docs/next/react-node-adc":{"component":"17896441","content":"b58c7434"},"/docs/next/rect-a08":{"component":"17896441","content":"4d34b260"},"/docs/next/refreshcontrol-674":{"component":"17896441","content":"873f60ed"},"/docs/next/running-on-device-cac":{"component":"17896441","content":"a7bb15ad"},"/docs/next/running-on-simulator-ios-76c":{"component":"17896441","content":"ebec3e54"},"/docs/next/safeareaview-632":{"component":"17896441","content":"d7726b69"},"/docs/next/scrollview-796":{"component":"17896441","content":"03fd51a3"},"/docs/next/sectionlist-882":{"component":"17896441","content":"2b12bc5f"},"/docs/next/security-a97":{"component":"17896441","content":"60a977b1"},"/docs/next/segmentedcontrolios-633":{"component":"17896441","content":"3762ffa5"},"/docs/next/settings-ab1":{"component":"17896441","content":"b75ea2fb"},"/docs/next/shadow-props-7a3":{"component":"17896441","content":"467bdfa9"},"/docs/next/share-9b6":{"component":"17896441","content":"468651de"},"/docs/next/signed-apk-android-bbd":{"component":"17896441","content":"9824da51"},"/docs/next/slider-21f":{"component":"17896441","content":"bdd4bf38"},"/docs/next/state-d70":{"component":"17896441","content":"90eaf4cd"},"/docs/next/statusbar-846":{"component":"17896441","content":"dd0cbcb2"},"/docs/next/statusbarios-122":{"component":"17896441","content":"3034c8f9"},"/docs/next/style-3d0":{"component":"17896441","content":"13449cd2"},"/docs/next/stylesheet-214":{"component":"17896441","content":"57d64bb2"},"/docs/next/switch-f03":{"component":"17896441","content":"93dc5430"},"/docs/next/symbolication-0e8":{"component":"17896441","content":"234829c8"},"/docs/next/systrace-839":{"component":"17896441","content":"f20c8d0e"},"/docs/next/testing-overview-505":{"component":"17896441","content":"f0f5403d"},"/docs/next/text-14d":{"component":"17896441","content":"5ba54f88"},"/docs/next/text-style-props-fe0":{"component":"17896441","content":"9e078d04"},"/docs/next/textinput-d1c":{"component":"17896441","content":"01e140f1"},"/docs/next/timepickerandroid-0f3":{"component":"17896441","content":"65325b57"},"/docs/next/timers-e0a":{"component":"17896441","content":"7ae8f3d3"},"/docs/next/toastandroid-c7a":{"component":"17896441","content":"1e175987"},"/docs/next/touchablehighlight-62a":{"component":"17896441","content":"614891e6"},"/docs/next/touchablenativefeedback-ef2":{"component":"17896441","content":"4eada83d"},"/docs/next/touchableopacity-cd1":{"component":"17896441","content":"f9c7b57c"},"/docs/next/touchablewithoutfeedback-733":{"component":"17896441","content":"ae4d52d0"},"/docs/next/transforms-8ce":{"component":"17896441","content":"1a71f62b"},"/docs/next/troubleshooting-b06":{"component":"17896441","content":"992518d4"},"/docs/next/tutorial-127":{"component":"17896441","content":"1ddf62ae"},"/docs/next/typescript-a30":{"component":"17896441","content":"dcee48ed"},"/docs/next/upgrading-c7c":{"component":"17896441","content":"71cdd40c"},"/docs/next/usecolorscheme-c6f":{"component":"17896441","content":"09759bdb"},"/docs/next/usewindowdimensions-f4f":{"component":"17896441","content":"5c3b0b70"},"/docs/next/using-a-listview-b96":{"component":"17896441","content":"29c99528"},"/docs/next/using-a-scrollview-0e6":{"component":"17896441","content":"a895c325"},"/docs/next/vibration-60a":{"component":"17896441","content":"39466136"},"/docs/next/view-21e":{"component":"17896441","content":"ec5c1e05"},"/docs/next/view-style-props-b19":{"component":"17896441","content":"75bf218c"},"/docs/next/viewpagerandroid-519":{"component":"17896441","content":"6d4da42f"},"/docs/next/viewtoken-d43":{"component":"17896441","content":"51add9d5"},"/docs/next/virtualizedlist-55c":{"component":"17896441","content":"0ac5e248"},"/docs-9de":{"component":"1be78505","versionMetadata":"ee5b3385"},"/docs/_getting-started-linux-android-3df":{"component":"17896441","content":"f88ba1af"},"/docs/_getting-started-macos-android-7f6":{"component":"17896441","content":"ce1e8d66"},"/docs/_getting-started-macos-ios-466":{"component":"17896441","content":"54bb7018"},"/docs/_getting-started-windows-android-711":{"component":"17896441","content":"1acce278"},"/docs/_integration-with-exisiting-apps-java-2d1":{"component":"17896441","content":"0871a232"},"/docs/_integration-with-exisiting-apps-objc-978":{"component":"17896441","content":"f290acc2"},"/docs/_integration-with-exisiting-apps-swift-d98":{"component":"17896441","content":"d4ca8d6a"},"/docs/accessibility-ff6":{"component":"17896441","content":"07bdfcc3"},"/docs/accessibilityinfo-7a6":{"component":"17896441","content":"b96b26f3"},"/docs/actionsheetios-b71":{"component":"17896441","content":"cce98cca"},"/docs/activityindicator-308":{"component":"17896441","content":"5acd8a78"},"/docs/alert-c8b":{"component":"17896441","content":"15c1c5e2"},"/docs/alertios-3dc":{"component":"17896441","content":"10c566d0"},"/docs/animated-715":{"component":"17896441","content":"f09787dc"},"/docs/animatedvalue-2ba":{"component":"17896441","content":"21e9f77a"},"/docs/animatedvaluexy-51a":{"component":"17896441","content":"e1f7ad4b"},"/docs/animations-89a":{"component":"17896441","content":"6c857c7c"},"/docs/app-extensions-234":{"component":"17896441","content":"4a843443"},"/docs/appearance-c44":{"component":"17896441","content":"081809cb"},"/docs/appregistry-162":{"component":"17896441","content":"049c47b0"},"/docs/appstate-c3f":{"component":"17896441","content":"496cd466"},"/docs/asyncstorage-1d9":{"component":"17896441","content":"9a097b11"},"/docs/backandroid-6f4":{"component":"17896441","content":"36f929d6"},"/docs/backhandler-9d6":{"component":"17896441","content":"d9d3a309"},"/docs/building-for-tv-646":{"component":"17896441","content":"fca44d23"},"/docs/button-1b5":{"component":"17896441","content":"8c5b2f52"},"/docs/cameraroll-cfd":{"component":"17896441","content":"0179d13e"},"/docs/checkbox-efd":{"component":"17896441","content":"9ab854dd"},"/docs/clipboard-6a1":{"component":"17896441","content":"5f9252a1"},"/docs/colors-d1e":{"component":"17896441","content":"7e281924"},"/docs/communication-android-fe7":{"component":"17896441","content":"c2d0f160"},"/docs/communication-ios-1dd":{"component":"17896441","content":"3e6ff066"},"/docs/components-and-apis-400":{"component":"17896441","content":"d6aba5ec"},"/docs/custom-webview-android-e39":{"component":"17896441","content":"65e7c155"},"/docs/custom-webview-ios-bc3":{"component":"17896441","content":"b385597a"},"/docs/datepickerandroid-ede":{"component":"17896441","content":"cf72f041"},"/docs/datepickerios-d35":{"component":"17896441","content":"af85c070"},"/docs/debugging-ef4":{"component":"17896441","content":"5d22711b"},"/docs/devsettings-024":{"component":"17896441","content":"b59ad042"},"/docs/dimensions-952":{"component":"17896441","content":"cf8a6c0c"},"/docs/direct-manipulation-b7d":{"component":"17896441","content":"c32aaf8e"},"/docs/drawerlayoutandroid-bf1":{"component":"17896441","content":"77fdf7ea"},"/docs/dynamiccolorios-bbf":{"component":"17896441","content":"2fb10c0f"},"/docs/easing-049":{"component":"17896441","content":"97b6b8d1"},"/docs/environment-setup-00d":{"component":"17896441","content":"f612f9dd"},"/docs/fast-refresh-d55":{"component":"17896441","content":"9cdda500"},"/docs/flatlist-77e":{"component":"17896441","content":"37cd4896"},"/docs/flexbox-5d9":{"component":"17896441","content":"3e769fe9"},"/docs/geolocation-f96":{"component":"17896441","content":"18abb92e"},"/docs/gesture-responder-system-b85":{"component":"17896441","content":"44d90755"},"/docs/getting-started-f6d":{"component":"17896441","content":"5fb1f368"},"/docs/handling-text-input-fac":{"component":"17896441","content":"0f48ff72"},"/docs/handling-touches-d28":{"component":"17896441","content":"5e5ffb34"},"/docs/headless-js-android-c0e":{"component":"17896441","content":"74335664"},"/docs/height-and-width-1e6":{"component":"17896441","content":"419fb327"},"/docs/hermes-fe0":{"component":"17896441","content":"dba6ab6f"},"/docs/image-dba":{"component":"17896441","content":"11b5c5a7"},"/docs/image-style-props-fe5":{"component":"17896441","content":"a2cb7017"},"/docs/imagebackground-c7a":{"component":"17896441","content":"d14b9649"},"/docs/imageeditor-c58":{"component":"17896441","content":"7f1cd19d"},"/docs/imagepickerios-018":{"component":"17896441","content":"24e5011f"},"/docs/images-ee1":{"component":"17896441","content":"00b71a4a"},"/docs/imagestore-3c1":{"component":"17896441","content":"5dd7058f"},"/docs/improvingux-baf":{"component":"17896441","content":"2eab7818"},"/docs/inputaccessoryview-0b4":{"component":"17896441","content":"b727d426"},"/docs/integration-with-existing-apps-29c":{"component":"17896441","content":"347ab973"},"/docs/interactionmanager-e69":{"component":"17896441","content":"0d77a4cd"},"/docs/intro-react-b87":{"component":"17896441","content":"0a17ef92"},"/docs/intro-react-native-components-c50":{"component":"17896441","content":"c7ddbcda"},"/docs/javascript-environment-7c3":{"component":"17896441","content":"5a722926"},"/docs/keyboard-3c3":{"component":"17896441","content":"28f24eb7"},"/docs/keyboardavoidingview-d15":{"component":"17896441","content":"58da195b"},"/docs/layout-props-2f5":{"component":"17896441","content":"47fc824a"},"/docs/layoutanimation-5e1":{"component":"17896441","content":"d13f564c"},"/docs/libraries-aaa":{"component":"17896441","content":"f4a2c192"},"/docs/linking-bd7":{"component":"17896441","content":"e9cbc253"},"/docs/linking-libraries-ios-b42":{"component":"17896441","content":"4d141f8f"},"/docs/listview-0ba":{"component":"17896441","content":"ffc0709f"},"/docs/listviewdatasource-91e":{"component":"17896441","content":"991a6912"},"/docs/maskedviewios-74a":{"component":"17896441","content":"70fb98aa"},"/docs/modal-084":{"component":"17896441","content":"4dfbc6a9"},"/docs/more-resources-828":{"component":"17896441","content":"fb0ec27d"},"/docs/native-components-android-60b":{"component":"17896441","content":"72396113"},"/docs/native-components-ios-ac7":{"component":"17896441","content":"e4edd88a"},"/docs/native-modules-android-4a1":{"component":"17896441","content":"bb7d3856"},"/docs/native-modules-intro-d69":{"component":"17896441","content":"7709983e"},"/docs/native-modules-ios-b26":{"component":"17896441","content":"54bb2e43"},"/docs/native-modules-setup-e57":{"component":"17896441","content":"d9423fea"},"/docs/navigation-22a":{"component":"17896441","content":"4c8e27ab"},"/docs/netinfo-0db":{"component":"17896441","content":"458f857c"},"/docs/network-173":{"component":"17896441","content":"df2d9a68"},"/docs/optimizing-flatlist-configuration-fe4":{"component":"17896441","content":"9528f0f4"},"/docs/out-of-tree-platforms-ba3":{"component":"17896441","content":"ed1e6177"},"/docs/panresponder-f5e":{"component":"17896441","content":"aaec36e1"},"/docs/performance-4a5":{"component":"17896441","content":"4c732965"},"/docs/permissionsandroid-92d":{"component":"17896441","content":"038eb46d"},"/docs/picker-6de":{"component":"17896441","content":"3a8a71d9"},"/docs/picker-item-4f7":{"component":"17896441","content":"7e96c4b3"},"/docs/picker-style-props-232":{"component":"17896441","content":"492cb388"},"/docs/pickerios-d07":{"component":"17896441","content":"d1f43cf2"},"/docs/pixelratio-fe0":{"component":"17896441","content":"6870e88c"},"/docs/platform-a11":{"component":"17896441","content":"5e9272da"},"/docs/platform-specific-code-46b":{"component":"17896441","content":"7c01aded"},"/docs/platformcolor-551":{"component":"17896441","content":"85945992"},"/docs/pressable-81c":{"component":"17896441","content":"d13ff743"},"/docs/pressevent-193":{"component":"17896441","content":"6ed44d23"},"/docs/profiling-798":{"component":"17896441","content":"5621abae"},"/docs/progressbarandroid-f19":{"component":"17896441","content":"68ed5ab7"},"/docs/progressviewios-969":{"component":"17896441","content":"54ffb88c"},"/docs/props-32e":{"component":"17896441","content":"6980fcf7"},"/docs/publishing-forks-820":{"component":"17896441","content":"18d91bb6"},"/docs/publishing-to-app-store-b72":{"component":"17896441","content":"a6ebc515"},"/docs/pushnotificationios-018":{"component":"17896441","content":"d88e3ac7"},"/docs/ram-bundles-inline-requires-7d6":{"component":"17896441","content":"995aaf28"},"/docs/react-node-203":{"component":"17896441","content":"f409e96c"},"/docs/rect-089":{"component":"17896441","content":"c14d4ced"},"/docs/refreshcontrol-551":{"component":"17896441","content":"2c4dbd2d"},"/docs/removing-default-permissions-bfd":{"component":"17896441","content":"52c61d4a"},"/docs/running-on-device-7c3":{"component":"17896441","content":"ab23b990"},"/docs/running-on-simulator-ios-c18":{"component":"17896441","content":"0753495c"},"/docs/safeareaview-e7d":{"component":"17896441","content":"e0f5ac09"},"/docs/scrollview-0ed":{"component":"17896441","content":"f9b8463d"},"/docs/sectionlist-ee8":{"component":"17896441","content":"edc6fa98"},"/docs/security-e0b":{"component":"17896441","content":"d842fc1f"},"/docs/segmentedcontrolios-f44":{"component":"17896441","content":"641a13cc"},"/docs/settings-53c":{"component":"17896441","content":"181dbc2b"},"/docs/shadow-props-26e":{"component":"17896441","content":"e2b11f61"},"/docs/share-13b":{"component":"17896441","content":"b06f5db1"},"/docs/signed-apk-android-23e":{"component":"17896441","content":"9e424ee7"},"/docs/slider-26d":{"component":"17896441","content":"727e95be"},"/docs/snapshotviewios-d17":{"component":"17896441","content":"22a4f512"},"/docs/state-d6a":{"component":"17896441","content":"3be85856"},"/docs/statusbar-d36":{"component":"17896441","content":"2fb24f85"},"/docs/statusbarios-466":{"component":"17896441","content":"5943bbc6"},"/docs/style-0c5":{"component":"17896441","content":"ed80608d"},"/docs/stylesheet-0f3":{"component":"17896441","content":"f0757a86"},"/docs/switch-b0a":{"component":"17896441","content":"73254b49"},"/docs/symbolication-0e5":{"component":"17896441","content":"096e1fcf"},"/docs/systrace-d82":{"component":"17896441","content":"6a56d899"},"/docs/tabbarios-b7c":{"component":"17896441","content":"256963a4"},"/docs/tabbarios-item-29e":{"component":"17896441","content":"725df2bb"},"/docs/testing-overview-459":{"component":"17896441","content":"76593922"},"/docs/text-ec1":{"component":"17896441","content":"b0c8f754"},"/docs/text-style-props-a13":{"component":"17896441","content":"ced3f12c"},"/docs/textinput-cc3":{"component":"17896441","content":"0fc9f0f5"},"/docs/timepickerandroid-021":{"component":"17896441","content":"9a232475"},"/docs/timers-840":{"component":"17896441","content":"ecbe54e8"},"/docs/toastandroid-dd1":{"component":"17896441","content":"e4588a3f"},"/docs/toolbarandroid-108":{"component":"17896441","content":"eb040101"},"/docs/touchablehighlight-6e1":{"component":"17896441","content":"947a7f10"},"/docs/touchablenativefeedback-4d8":{"component":"17896441","content":"214989ea"},"/docs/touchableopacity-360":{"component":"17896441","content":"c50442d6"},"/docs/touchablewithoutfeedback-981":{"component":"17896441","content":"a59cd994"},"/docs/transforms-9a2":{"component":"17896441","content":"c9aa9a7e"},"/docs/troubleshooting-d75":{"component":"17896441","content":"25a5c279"},"/docs/tutorial-0c4":{"component":"17896441","content":"78a42ea2"},"/docs/typescript-7a0":{"component":"17896441","content":"516ae6d6"},"/docs/upgrading-de1":{"component":"17896441","content":"0ed30eb7"},"/docs/usecolorscheme-929":{"component":"17896441","content":"91d1b0ec"},"/docs/usewindowdimensions-b39":{"component":"17896441","content":"e25f7b4d"},"/docs/using-a-listview-829":{"component":"17896441","content":"daf31841"},"/docs/using-a-scrollview-707":{"component":"17896441","content":"4a05e046"},"/docs/vibration-0f6":{"component":"17896441","content":"65a965b7"},"/docs/vibrationios-391":{"component":"17896441","content":"0b254871"},"/docs/view-0ef":{"component":"17896441","content":"f2dc4d96"},"/docs/view-style-props-900":{"component":"17896441","content":"d4b71d34"},"/docs/viewpagerandroid-f3a":{"component":"17896441","content":"9462c58f"},"/docs/virtualizedlist-517":{"component":"17896441","content":"7b1ca64a"},"/docs/webview-5e2":{"component":"17896441","content":"3d8443ce"}}')},function(e,n,t){var o,i;void 0===(i="function"==typeof(o=function(){var e,n,t={version:"0.2.0"},o=t.settings={minimum:.08,easing:"ease",positionUsing:"",speed:200,trickle:!0,trickleRate:.02,trickleSpeed:800,showSpinner:!0,barSelector:'[role="bar"]',spinnerSelector:'[role="spinner"]',parent:"body",template:'
'};function i(e,n,t){return et?t:e}function a(e){return 100*(-1+e)}function s(e,n,t){var i;return(i="translate3d"===o.positionUsing?{transform:"translate3d("+a(e)+"%,0,0)"}:"translate"===o.positionUsing?{transform:"translate("+a(e)+"%,0)"}:{"margin-left":a(e)+"%"}).transition="all "+n+"ms "+t,i}t.configure=function(e){var n,t;for(n in e)void 0!==(t=e[n])&&e.hasOwnProperty(n)&&(o[n]=t);return this},t.status=null,t.set=function(e){var n=t.isStarted();e=i(e,o.minimum,1),t.status=1===e?null:e;var a=t.render(!n),d=a.querySelector(o.barSelector),l=o.speed,u=o.easing;return a.offsetWidth,r((function(n){""===o.positionUsing&&(o.positionUsing=t.getPositioningCSS()),c(d,s(e,l,u)),1===e?(c(a,{transition:"none",opacity:1}),a.offsetWidth,setTimeout((function(){c(a,{transition:"all "+l+"ms linear",opacity:0}),setTimeout((function(){t.remove(),n()}),l)}),l)):setTimeout(n,l)})),this},t.isStarted=function(){return"number"==typeof t.status},t.start=function(){t.status||t.set(0);var e=function(){setTimeout((function(){t.status&&(t.trickle(),e())}),o.trickleSpeed)};return o.trickle&&e(),this},t.done=function(e){return e||t.status?t.inc(.3+.5*Math.random()).set(1):this},t.inc=function(e){var n=t.status;return n?("number"!=typeof e&&(e=(1-n)*i(Math.random()*n,.1,.95)),n=i(n+e,0,.994),t.set(n)):t.start()},t.trickle=function(){return t.inc(Math.random()*o.trickleRate)},e=0,n=0,t.promise=function(o){return o&&"resolved"!==o.state()?(0===n&&t.start(),e++,n++,o.always((function(){0==--n?(e=0,t.done()):t.set((e-n)/e)})),this):this},t.render=function(e){if(t.isRendered())return document.getElementById("nprogress");l(document.documentElement,"nprogress-busy");var n=document.createElement("div");n.id="nprogress",n.innerHTML=o.template;var i,s=n.querySelector(o.barSelector),r=e?"-100":a(t.status||0),d=document.querySelector(o.parent);return c(s,{transition:"all 0 linear",transform:"translate3d("+r+"%,0,0)"}),o.showSpinner||(i=n.querySelector(o.spinnerSelector))&&m(i),d!=document.body&&l(d,"nprogress-custom-parent"),d.appendChild(n),n},t.remove=function(){u(document.documentElement,"nprogress-busy"),u(document.querySelector(o.parent),"nprogress-custom-parent");var e=document.getElementById("nprogress");e&&m(e)},t.isRendered=function(){return!!document.getElementById("nprogress")},t.getPositioningCSS=function(){var e=document.body.style,n="WebkitTransform"in e?"Webkit":"MozTransform"in e?"Moz":"msTransform"in e?"ms":"OTransform"in e?"O":"";return n+"Perspective"in e?"translate3d":n+"Transform"in e?"translate":"margin"};var r=function(){var e=[];function n(){var t=e.shift();t&&t(n)}return function(t){e.push(t),1==e.length&&n()}}(),c=function(){var e=["Webkit","O","Moz","ms"],n={};function t(e){return e.replace(/^-ms-/,"ms-").replace(/-([\da-z])/gi,(function(e,n){return n.toUpperCase()}))}function o(n){var t=document.body.style;if(n in t)return n;for(var o,i=e.length,a=n.charAt(0).toUpperCase()+n.slice(1);i--;)if((o=e[i]+a)in t)return o;return n}function i(e){return e=t(e),n[e]||(n[e]=o(e))}function a(e,n,t){n=i(n),e.style[n]=t}return function(e,n){var t,o,i=arguments;if(2==i.length)for(t in n)void 0!==(o=n[t])&&n.hasOwnProperty(t)&&a(e,t,o);else a(e,i[1],i[2])}}();function d(e,n){return("string"==typeof e?e:p(e)).indexOf(" "+n+" ")>=0}function l(e,n){var t=p(e),o=t+n;d(t,n)||(e.className=o.substring(1))}function u(e,n){var t,o=p(e);d(e,n)&&(t=o.replace(" "+n+" "," "),e.className=t.substring(1,t.length-1))}function p(e){return(" "+(e.className||"")+" ").replace(/\s+/gi," ")}function m(e){e&&e.parentNode&&e.parentNode.removeChild(e)}return t})?o.call(n,t,n,e):o)||(e.exports=i)},function(e,n,t){"use strict";t.d(n,"a",(function(){return u})),t.d(n,"b",(function(){return p})),t.d(n,"c",(function(){return g})),t.d(n,"e",(function(){return w}));var o=t(1);t.d(n,"d",(function(){return o.a})),t.d(n,"f",(function(){return o.b})),t.d(n,"g",(function(){return o.c})),t.d(n,"h",(function(){return o.d})),t.d(n,"i",(function(){return o.e})),t.d(n,"j",(function(){return o.f})),t.d(n,"k",(function(){return o.g})),t.d(n,"l",(function(){return o.i})),t.d(n,"m",(function(){return o.j})),t.d(n,"n",(function(){return o.k})),t.d(n,"o",(function(){return o.l})),t.d(n,"p",(function(){return o.m})),t.d(n,"q",(function(){return o.n})),t.d(n,"r",(function(){return o.o}));var i=t(3),a=t(0),s=t.n(a),r=t(5),c=(t(9),t(2)),d=t(7),l=t(4),u=function(e){function n(){for(var n,t=arguments.length,o=new Array(t),i=0;ie.length)return;if(!(w instanceof c)){if(b&&x!=n.length-1){if(p.lastIndex=y,!(P=p.exec(e)))break;for(var k=P.index+(f?P[1].length:0),_=P.index+P[0].length,E=x,S=y,T=n.length;E=(S+=n[E].length)&&(++x,y=S);if(n[x]instanceof c)continue;C=E-x,w=e.slice(y,S),P.index-=y}else{p.lastIndex=0;var P=p.exec(w),C=1}if(P){f&&(h=P[1]?P[1].length:0),_=(k=P.index+h)+(P=P[0].slice(h)).length;var O=w.slice(0,k),A=w.slice(_),N=[x,C];O&&(++x,y+=O.length,N.push(O));var R=new c(d,m?i.tokenize(P,m):P,v,P,b);if(N.push(R),A&&N.push(A),Array.prototype.splice.apply(n,N),1!=C&&i.matchGrammar(e,n,t,x,y,!0,d),s)break}else if(s)break}}}}},hooks:{add:function(){}},tokenize:function(e,n,t){var o=[e],a=n.rest;if(a){for(var s in a)n[s]=a[s];delete n.rest}return i.matchGrammar(e,o,n,0,0,!1),o}},(a=i.Token=function(e,n,t,o,i){this.type=e,this.content=n,this.alias=t,this.length=0|(o||"").length,this.greedy=!!i}).stringify=function(e,n,t){if("string"==typeof e)return e;if("Array"===i.util.type(e))return e.map((function(t){return a.stringify(t,n,e)})).join("");var o={type:e.type,content:a.stringify(e.content,n,t),tag:"span",classes:["token",e.type],attributes:{},language:n,parent:t};if(e.alias){var s="Array"===i.util.type(e.alias)?e.alias:[e.alias];Array.prototype.push.apply(o.classes,s)}var r=Object.keys(o.attributes).map((function(e){return e+'="'+(o.attributes[e]||"").replace(/"/g,""")+'"'})).join(" ");return"<"+o.tag+' class="'+o.classes.join(" ")+'"'+(r?" "+r:"")+">"+o.content+""},i);s.languages.markup={comment://,prolog:/<\?[\s\S]+?\?>/,doctype://i,cdata://i,tag:{pattern:/<\/?(?!\d)[^\s>\/=$<%]+(?:\s(?:\s*[^\s>\/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s'">=]+(?=[\s>]))|(?=[\s/>])))+)?\s*\/?>/i,greedy:!0,inside:{tag:{pattern:/^<\/?[^\s>\/]+/i,inside:{punctuation:/^<\/?/,namespace:/^[^\s>\/:]+:/}},"attr-value":{pattern:/=\s*(?:"[^"]*"|'[^']*'|[^\s'">=]+)/i,inside:{punctuation:[/^=/,{pattern:/^(\s*)["']|["']$/,lookbehind:!0}]}},punctuation:/\/?>/,"attr-name":{pattern:/[^\s>\/]+/,inside:{namespace:/^[^\s>\/:]+:/}}}},entity:/&#?[\da-z]{1,8};/i},s.languages.markup.tag.inside["attr-value"].inside.entity=s.languages.markup.entity,s.hooks.add("wrap",(function(e){"entity"===e.type&&(e.attributes.title=e.content.replace(/&/,"&"))})),Object.defineProperty(s.languages.markup.tag,"addInlined",{value:function(e,n){var t={};t["language-"+n]={pattern:/(^$)/i,lookbehind:!0,inside:s.languages[n]},t.cdata=/^$/i;var o={"included-cdata":{pattern://i,inside:t}};o["language-"+n]={pattern:/[\s\S]+/,inside:s.languages[n]};var i={};i[e]={pattern:RegExp(/(<__[\s\S]*?>)(?:\s*|[\s\S])*?(?=<\/__>)/.source.replace(/__/g,e),"i"),lookbehind:!0,greedy:!0,inside:o},s.languages.insertBefore("markup","cdata",i)}}),s.languages.xml=s.languages.extend("markup",{}),s.languages.html=s.languages.markup,s.languages.mathml=s.languages.markup,s.languages.svg=s.languages.markup,function(e){var n="\\b(?:BASH|BASHOPTS|BASH_ALIASES|BASH_ARGC|BASH_ARGV|BASH_CMDS|BASH_COMPLETION_COMPAT_DIR|BASH_LINENO|BASH_REMATCH|BASH_SOURCE|BASH_VERSINFO|BASH_VERSION|COLORTERM|COLUMNS|COMP_WORDBREAKS|DBUS_SESSION_BUS_ADDRESS|DEFAULTS_PATH|DESKTOP_SESSION|DIRSTACK|DISPLAY|EUID|GDMSESSION|GDM_LANG|GNOME_KEYRING_CONTROL|GNOME_KEYRING_PID|GPG_AGENT_INFO|GROUPS|HISTCONTROL|HISTFILE|HISTFILESIZE|HISTSIZE|HOME|HOSTNAME|HOSTTYPE|IFS|INSTANCE|JOB|LANG|LANGUAGE|LC_ADDRESS|LC_ALL|LC_IDENTIFICATION|LC_MEASUREMENT|LC_MONETARY|LC_NAME|LC_NUMERIC|LC_PAPER|LC_TELEPHONE|LC_TIME|LESSCLOSE|LESSOPEN|LINES|LOGNAME|LS_COLORS|MACHTYPE|MAILCHECK|MANDATORY_PATH|NO_AT_BRIDGE|OLDPWD|OPTERR|OPTIND|ORBIT_SOCKETDIR|OSTYPE|PAPERSIZE|PATH|PIPESTATUS|PPID|PS1|PS2|PS3|PS4|PWD|RANDOM|REPLY|SECONDS|SELINUX_INIT|SESSION|SESSIONTYPE|SESSION_MANAGER|SHELL|SHELLOPTS|SHLVL|SSH_AUTH_SOCK|TERM|UID|UPSTART_EVENTS|UPSTART_INSTANCE|UPSTART_JOB|UPSTART_SESSION|USER|WINDOWID|XAUTHORITY|XDG_CONFIG_DIRS|XDG_CURRENT_DESKTOP|XDG_DATA_DIRS|XDG_GREETER_DATA_DIR|XDG_MENU_PREFIX|XDG_RUNTIME_DIR|XDG_SEAT|XDG_SEAT_PATH|XDG_SESSION_DESKTOP|XDG_SESSION_ID|XDG_SESSION_PATH|XDG_SESSION_TYPE|XDG_VTNR|XMODIFIERS)\\b",t={environment:{pattern:RegExp("\\$"+n),alias:"constant"},variable:[{pattern:/\$?\(\([\s\S]+?\)\)/,greedy:!0,inside:{variable:[{pattern:/(^\$\(\([\s\S]+)\)\)/,lookbehind:!0},/^\$\(\(/],number:/\b0x[\dA-Fa-f]+\b|(?:\b\d+\.?\d*|\B\.\d+)(?:[Ee]-?\d+)?/,operator:/--?|-=|\+\+?|\+=|!=?|~|\*\*?|\*=|\/=?|%=?|<<=?|>>=?|<=?|>=?|==?|&&?|&=|\^=?|\|\|?|\|=|\?|:/,punctuation:/\(\(?|\)\)?|,|;/}},{pattern:/\$\((?:\([^)]+\)|[^()])+\)|`[^`]+`/,greedy:!0,inside:{variable:/^\$\(|^`|\)$|`$/}},{pattern:/\$\{[^}]+\}/,greedy:!0,inside:{operator:/:[-=?+]?|[!\/]|##?|%%?|\^\^?|,,?/,punctuation:/[\[\]]/,environment:{pattern:RegExp("(\\{)"+n),lookbehind:!0,alias:"constant"}}},/\$(?:\w+|[#?*!@$])/],entity:/\\(?:[abceEfnrtv\\"]|O?[0-7]{1,3}|x[0-9a-fA-F]{1,2}|u[0-9a-fA-F]{4}|U[0-9a-fA-F]{8})/};e.languages.bash={shebang:{pattern:/^#!\s*\/.*/,alias:"important"},comment:{pattern:/(^|[^"{\\$])#.*/,lookbehind:!0},"function-name":[{pattern:/(\bfunction\s+)\w+(?=(?:\s*\(?:\s*\))?\s*\{)/,lookbehind:!0,alias:"function"},{pattern:/\b\w+(?=\s*\(\s*\)\s*\{)/,alias:"function"}],"for-or-select":{pattern:/(\b(?:for|select)\s+)\w+(?=\s+in\s)/,alias:"variable",lookbehind:!0},"assign-left":{pattern:/(^|[\s;|&]|[<>]\()\w+(?=\+?=)/,inside:{environment:{pattern:RegExp("(^|[\\s;|&]|[<>]\\()"+n),lookbehind:!0,alias:"constant"}},alias:"variable",lookbehind:!0},string:[{pattern:/((?:^|[^<])<<-?\s*)(\w+?)\s*(?:\r?\n|\r)(?:[\s\S])*?(?:\r?\n|\r)\2/,lookbehind:!0,greedy:!0,inside:t},{pattern:/((?:^|[^<])<<-?\s*)(["'])(\w+)\2\s*(?:\r?\n|\r)(?:[\s\S])*?(?:\r?\n|\r)\3/,lookbehind:!0,greedy:!0},{pattern:/(["'])(?:\\[\s\S]|\$\([^)]+\)|`[^`]+`|(?!\1)[^\\])*\1/,greedy:!0,inside:t}],environment:{pattern:RegExp("\\$?"+n),alias:"constant"},variable:t.variable,function:{pattern:/(^|[\s;|&]|[<>]\()(?:add|apropos|apt|aptitude|apt-cache|apt-get|aspell|automysqlbackup|awk|basename|bash|bc|bconsole|bg|bzip2|cal|cat|cfdisk|chgrp|chkconfig|chmod|chown|chroot|cksum|clear|cmp|column|comm|cp|cron|crontab|csplit|curl|cut|date|dc|dd|ddrescue|debootstrap|df|diff|diff3|dig|dir|dircolors|dirname|dirs|dmesg|du|egrep|eject|env|ethtool|expand|expect|expr|fdformat|fdisk|fg|fgrep|file|find|fmt|fold|format|free|fsck|ftp|fuser|gawk|git|gparted|grep|groupadd|groupdel|groupmod|groups|grub-mkconfig|gzip|halt|head|hg|history|host|hostname|htop|iconv|id|ifconfig|ifdown|ifup|import|install|ip|jobs|join|kill|killall|less|link|ln|locate|logname|logrotate|look|lpc|lpr|lprint|lprintd|lprintq|lprm|ls|lsof|lynx|make|man|mc|mdadm|mkconfig|mkdir|mke2fs|mkfifo|mkfs|mkisofs|mknod|mkswap|mmv|more|most|mount|mtools|mtr|mutt|mv|nano|nc|netstat|nice|nl|nohup|notify-send|npm|nslookup|op|open|parted|passwd|paste|pathchk|ping|pkill|pnpm|popd|pr|printcap|printenv|ps|pushd|pv|quota|quotacheck|quotactl|ram|rar|rcp|reboot|remsync|rename|renice|rev|rm|rmdir|rpm|rsync|scp|screen|sdiff|sed|sendmail|seq|service|sftp|sh|shellcheck|shuf|shutdown|sleep|slocate|sort|split|ssh|stat|strace|su|sudo|sum|suspend|swapon|sync|tac|tail|tar|tee|time|timeout|top|touch|tr|traceroute|tsort|tty|umount|uname|unexpand|uniq|units|unrar|unshar|unzip|update-grub|uptime|useradd|userdel|usermod|users|uudecode|uuencode|v|vdir|vi|vim|virsh|vmstat|wait|watch|wc|wget|whereis|which|who|whoami|write|xargs|xdg-open|yarn|yes|zenity|zip|zsh|zypper)(?=$|[)\s;|&])/,lookbehind:!0},keyword:{pattern:/(^|[\s;|&]|[<>]\()(?:if|then|else|elif|fi|for|while|in|case|esac|function|select|do|done|until)(?=$|[)\s;|&])/,lookbehind:!0},builtin:{pattern:/(^|[\s;|&]|[<>]\()(?:\.|:|break|cd|continue|eval|exec|exit|export|getopts|hash|pwd|readonly|return|shift|test|times|trap|umask|unset|alias|bind|builtin|caller|command|declare|echo|enable|help|let|local|logout|mapfile|printf|read|readarray|source|type|typeset|ulimit|unalias|set|shopt)(?=$|[)\s;|&])/,lookbehind:!0,alias:"class-name"},boolean:{pattern:/(^|[\s;|&]|[<>]\()(?:true|false)(?=$|[)\s;|&])/,lookbehind:!0},"file-descriptor":{pattern:/\B&\d\b/,alias:"important"},operator:{pattern:/\d?<>|>\||\+=|==?|!=?|=~|<<[<-]?|[&\d]?>>|\d?[<>]&?|&[>&]?|\|[&|]?|<=?|>=?/,inside:{"file-descriptor":{pattern:/^\d/,alias:"important"}}},punctuation:/\$?\(\(?|\)\)?|\.\.|[{}[\];\\]/,number:{pattern:/(^|\s)(?:[1-9]\d*|0)(?:[.,]\d+)?\b/,lookbehind:!0}};for(var o=["comment","function-name","for-or-select","assign-left","string","environment","function","keyword","builtin","boolean","file-descriptor","operator","punctuation","number"],i=t.variable[1].inside,a=0;a=?|==?=?|&&?|\|\|?|\?|\*|\/|~|\^|%/,punctuation:/[{}[\];(),.:]/},s.languages.c=s.languages.extend("clike",{"class-name":{pattern:/(\b(?:enum|struct)\s+)\w+/,lookbehind:!0},keyword:/\b(?:_Alignas|_Alignof|_Atomic|_Bool|_Complex|_Generic|_Imaginary|_Noreturn|_Static_assert|_Thread_local|asm|typeof|inline|auto|break|case|char|const|continue|default|do|double|else|enum|extern|float|for|goto|if|int|long|register|return|short|signed|sizeof|static|struct|switch|typedef|union|unsigned|void|volatile|while)\b/,operator:/>>=?|<<=?|->|([-+&|:])\1|[?:~]|[-+*/%&|^!=<>]=?/,number:/(?:\b0x(?:[\da-f]+\.?[\da-f]*|\.[\da-f]+)(?:p[+-]?\d+)?|(?:\b\d+\.?\d*|\B\.\d+)(?:e[+-]?\d+)?)[ful]*/i}),s.languages.insertBefore("c","string",{macro:{pattern:/(^\s*)#\s*[a-z]+(?:[^\r\n\\]|\\(?:\r\n|[\s\S]))*/im,lookbehind:!0,alias:"property",inside:{string:{pattern:/(#\s*include\s*)(?:<.+?>|("|')(?:\\?.)+?\2)/,lookbehind:!0},directive:{pattern:/(#\s*)\b(?:define|defined|elif|else|endif|error|ifdef|ifndef|if|import|include|line|pragma|undef|using)\b/,lookbehind:!0,alias:"keyword"}}},constant:/\b(?:__FILE__|__LINE__|__DATE__|__TIME__|__TIMESTAMP__|__func__|EOF|NULL|SEEK_CUR|SEEK_END|SEEK_SET|stdin|stdout|stderr)\b/}),delete s.languages.c.boolean,s.languages.cpp=s.languages.extend("c",{"class-name":{pattern:/(\b(?:class|enum|struct)\s+)\w+/,lookbehind:!0},keyword:/\b(?:alignas|alignof|asm|auto|bool|break|case|catch|char|char16_t|char32_t|class|compl|const|constexpr|const_cast|continue|decltype|default|delete|do|double|dynamic_cast|else|enum|explicit|export|extern|float|for|friend|goto|if|inline|int|int8_t|int16_t|int32_t|int64_t|uint8_t|uint16_t|uint32_t|uint64_t|long|mutable|namespace|new|noexcept|nullptr|operator|private|protected|public|register|reinterpret_cast|return|short|signed|sizeof|static|static_assert|static_cast|struct|switch|template|this|thread_local|throw|try|typedef|typeid|typename|union|unsigned|using|virtual|void|volatile|wchar_t|while)\b/,number:{pattern:/(?:\b0b[01']+|\b0x(?:[\da-f']+\.?[\da-f']*|\.[\da-f']+)(?:p[+-]?[\d']+)?|(?:\b[\d']+\.?[\d']*|\B\.[\d']+)(?:e[+-]?[\d']+)?)[ful]*/i,greedy:!0},operator:/>>=?|<<=?|->|([-+&|:])\1|[?:~]|[-+*/%&|^!=<>]=?|\b(?:and|and_eq|bitand|bitor|not|not_eq|or|or_eq|xor|xor_eq)\b/,boolean:/\b(?:true|false)\b/}),s.languages.insertBefore("cpp","string",{"raw-string":{pattern:/R"([^()\\ ]{0,16})\([\s\S]*?\)\1"/,alias:"string",greedy:!0}}),function(e){var n=/("|')(?:\\(?:\r\n|[\s\S])|(?!\1)[^\\\r\n])*\1/;e.languages.css={comment:/\/\*[\s\S]*?\*\//,atrule:{pattern:/@[\w-]+[\s\S]*?(?:;|(?=\s*\{))/,inside:{rule:/@[\w-]+/}},url:{pattern:RegExp("url\\((?:"+n.source+"|[^\n\r()]*)\\)","i"),inside:{function:/^url/i,punctuation:/^\(|\)$/}},selector:RegExp("[^{}\\s](?:[^{};\"']|"+n.source+")*?(?=\\s*\\{)"),string:{pattern:n,greedy:!0},property:/[-_a-z\xA0-\uFFFF][-\w\xA0-\uFFFF]*(?=\s*:)/i,important:/!important\b/i,function:/[-a-z0-9]+(?=\()/i,punctuation:/[(){};:,]/},e.languages.css.atrule.inside.rest=e.languages.css;var t=e.languages.markup;t&&(t.tag.addInlined("style","css"),e.languages.insertBefore("inside","attr-value",{"style-attr":{pattern:/\s*style=("|')(?:\\[\s\S]|(?!\1)[^\\])*\1/i,inside:{"attr-name":{pattern:/^\s*style/i,inside:t.tag.inside},punctuation:/^\s*=\s*['"]|['"]\s*$/,"attr-value":{pattern:/.+/i,inside:e.languages.css}},alias:"language-css"}},t.tag))}(s),s.languages.css.selector={pattern:s.languages.css.selector,inside:{"pseudo-element":/:(?:after|before|first-letter|first-line|selection)|::[-\w]+/,"pseudo-class":/:[-\w]+/,class:/\.[-:.\w]+/,id:/#[-:.\w]+/,attribute:{pattern:/\[(?:[^[\]"']|("|')(?:\\(?:\r\n|[\s\S])|(?!\1)[^\\\r\n])*\1)*\]/,greedy:!0,inside:{punctuation:/^\[|\]$/,"case-sensitivity":{pattern:/(\s)[si]$/i,lookbehind:!0,alias:"keyword"},namespace:{pattern:/^(\s*)[-*\w\xA0-\uFFFF]*\|(?!=)/,lookbehind:!0,inside:{punctuation:/\|$/}},attribute:{pattern:/^(\s*)[-\w\xA0-\uFFFF]+/,lookbehind:!0},value:[/("|')(?:\\(?:\r\n|[\s\S])|(?!\1)[^\\\r\n])*\1/,{pattern:/(=\s*)[-\w\xA0-\uFFFF]+(?=\s*$)/,lookbehind:!0}],operator:/[|~*^$]?=/}},"n-th":[{pattern:/(\(\s*)[+-]?\d*[\dn](?:\s*[+-]\s*\d+)?(?=\s*\))/,lookbehind:!0,inside:{number:/[\dn]+/,operator:/[+-]/}},{pattern:/(\(\s*)(?:even|odd)(?=\s*\))/i,lookbehind:!0}],punctuation:/[()]/}},s.languages.insertBefore("css","property",{variable:{pattern:/(^|[^-\w\xA0-\uFFFF])--[-_a-z\xA0-\uFFFF][-\w\xA0-\uFFFF]*/i,lookbehind:!0}}),s.languages.insertBefore("css","function",{operator:{pattern:/(\s)[+\-*\/](?=\s)/,lookbehind:!0},hexcode:/#[\da-f]{3,8}/i,entity:/\\[\da-f]{1,8}/i,unit:{pattern:/(\d)(?:%|[a-z]+)/,lookbehind:!0},number:/-?[\d.]+/}),s.languages.javascript=s.languages.extend("clike",{"class-name":[s.languages.clike["class-name"],{pattern:/(^|[^$\w\xA0-\uFFFF])[_$A-Z\xA0-\uFFFF][$\w\xA0-\uFFFF]*(?=\.(?:prototype|constructor))/,lookbehind:!0}],keyword:[{pattern:/((?:^|})\s*)(?:catch|finally)\b/,lookbehind:!0},{pattern:/(^|[^.])\b(?:as|async(?=\s*(?:function\b|\(|[$\w\xA0-\uFFFF]|$))|await|break|case|class|const|continue|debugger|default|delete|do|else|enum|export|extends|for|from|function|get|if|implements|import|in|instanceof|interface|let|new|null|of|package|private|protected|public|return|set|static|super|switch|this|throw|try|typeof|undefined|var|void|while|with|yield)\b/,lookbehind:!0}],number:/\b(?:(?:0[xX](?:[\dA-Fa-f](?:_[\dA-Fa-f])?)+|0[bB](?:[01](?:_[01])?)+|0[oO](?:[0-7](?:_[0-7])?)+)n?|(?:\d(?:_\d)?)+n|NaN|Infinity)\b|(?:\b(?:\d(?:_\d)?)+\.?(?:\d(?:_\d)?)*|\B\.(?:\d(?:_\d)?)+)(?:[Ee][+-]?(?:\d(?:_\d)?)+)?/,function:/#?[_$a-zA-Z\xA0-\uFFFF][$\w\xA0-\uFFFF]*(?=\s*(?:\.\s*(?:apply|bind|call)\s*)?\()/,operator:/-[-=]?|\+[+=]?|!=?=?|<>?>?=?|=(?:==?|>)?|&[&=]?|\|[|=]?|\*\*?=?|\/=?|~|\^=?|%=?|\?|\.{3}/}),s.languages.javascript["class-name"][0].pattern=/(\b(?:class|interface|extends|implements|instanceof|new)\s+)[\w.\\]+/,s.languages.insertBefore("javascript","keyword",{regex:{pattern:/((?:^|[^$\w\xA0-\uFFFF."'\])\s])\s*)\/(\[(?:[^\]\\\r\n]|\\.)*]|\\.|[^/\\\[\r\n])+\/[gimyus]{0,6}(?=\s*($|[\r\n,.;})\]]))/,lookbehind:!0,greedy:!0},"function-variable":{pattern:/#?[_$a-zA-Z\xA0-\uFFFF][$\w\xA0-\uFFFF]*(?=\s*[=:]\s*(?:async\s*)?(?:\bfunction\b|(?:\((?:[^()]|\([^()]*\))*\)|[_$a-zA-Z\xA0-\uFFFF][$\w\xA0-\uFFFF]*)\s*=>))/,alias:"function"},parameter:[{pattern:/(function(?:\s+[_$A-Za-z\xA0-\uFFFF][$\w\xA0-\uFFFF]*)?\s*\(\s*)(?!\s)(?:[^()]|\([^()]*\))+?(?=\s*\))/,lookbehind:!0,inside:s.languages.javascript},{pattern:/[_$a-z\xA0-\uFFFF][$\w\xA0-\uFFFF]*(?=\s*=>)/i,inside:s.languages.javascript},{pattern:/(\(\s*)(?!\s)(?:[^()]|\([^()]*\))+?(?=\s*\)\s*=>)/,lookbehind:!0,inside:s.languages.javascript},{pattern:/((?:\b|\s|^)(?!(?:as|async|await|break|case|catch|class|const|continue|debugger|default|delete|do|else|enum|export|extends|finally|for|from|function|get|if|implements|import|in|instanceof|interface|let|new|null|of|package|private|protected|public|return|set|static|super|switch|this|throw|try|typeof|undefined|var|void|while|with|yield)(?![$\w\xA0-\uFFFF]))(?:[_$A-Za-z\xA0-\uFFFF][$\w\xA0-\uFFFF]*\s*)\(\s*)(?!\s)(?:[^()]|\([^()]*\))+?(?=\s*\)\s*\{)/,lookbehind:!0,inside:s.languages.javascript}],constant:/\b[A-Z](?:[A-Z_]|\dx?)*\b/}),s.languages.insertBefore("javascript","string",{"template-string":{pattern:/`(?:\\[\s\S]|\${(?:[^{}]|{(?:[^{}]|{[^}]*})*})+}|(?!\${)[^\\`])*`/,greedy:!0,inside:{"template-punctuation":{pattern:/^`|`$/,alias:"string"},interpolation:{pattern:/((?:^|[^\\])(?:\\{2})*)\${(?:[^{}]|{(?:[^{}]|{[^}]*})*})+}/,lookbehind:!0,inside:{"interpolation-punctuation":{pattern:/^\${|}$/,alias:"punctuation"},rest:s.languages.javascript}},string:/[\s\S]+/}}}),s.languages.markup&&s.languages.markup.tag.addInlined("script","javascript"),s.languages.js=s.languages.javascript,function(e){var n=e.util.clone(e.languages.javascript);e.languages.jsx=e.languages.extend("markup",n),e.languages.jsx.tag.pattern=/<\/?(?:[\w.:-]+\s*(?:\s+(?:[\w.:-]+(?:=(?:("|')(?:\\[\s\S]|(?!\1)[^\\])*\1|[^\s{'">=]+|\{(?:\{(?:\{[^}]*\}|[^{}])*\}|[^{}])+\}))?|\{\.{3}[a-z_$][\w$]*(?:\.[a-z_$][\w$]*)*\}))*\s*\/?)?>/i,e.languages.jsx.tag.inside.tag.pattern=/^<\/?[^\s>\/]*/i,e.languages.jsx.tag.inside["attr-value"].pattern=/=(?!\{)(?:("|')(?:\\[\s\S]|(?!\1)[^\\])*\1|[^\s'">]+)/i,e.languages.jsx.tag.inside.tag.inside["class-name"]=/^[A-Z]\w*(?:\.[A-Z]\w*)*$/,e.languages.insertBefore("inside","attr-name",{spread:{pattern:/\{\.{3}[a-z_$][\w$]*(?:\.[a-z_$][\w$]*)*\}/,inside:{punctuation:/\.{3}|[{}.]/,"attr-value":/\w+/}}},e.languages.jsx.tag),e.languages.insertBefore("inside","attr-value",{script:{pattern:/=(\{(?:\{(?:\{[^}]*\}|[^}])*\}|[^}])+\})/i,inside:{"script-punctuation":{pattern:/^=(?={)/,alias:"punctuation"},rest:e.languages.jsx},alias:"language-javascript"}},e.languages.jsx.tag);var t=function(e){return e?"string"==typeof e?e:"string"==typeof e.content?e.content:e.content.map(t).join(""):""},o=function(n){for(var i=[],a=0;a0&&i[i.length-1].tagName===t(s.content[0].content[1])&&i.pop():"/>"===s.content[s.content.length-1].content||i.push({tagName:t(s.content[0].content[1]),openedBraces:0}):i.length>0&&"punctuation"===s.type&&"{"===s.content?i[i.length-1].openedBraces++:i.length>0&&i[i.length-1].openedBraces>0&&"punctuation"===s.type&&"}"===s.content?i[i.length-1].openedBraces--:r=!0),(r||"string"==typeof s)&&i.length>0&&0===i[i.length-1].openedBraces){var c=t(s);a0&&("string"==typeof n[a-1]||"plain-text"===n[a-1].type)&&(c=t(n[a-1])+c,n.splice(a-1,1),a--),n[a]=new e.Token("plain-text",c,null,c)}s.content&&"string"!=typeof s.content&&o(s.content)}};e.hooks.add("after-tokenize",(function(e){"jsx"!==e.language&&"tsx"!==e.language||o(e.tokens)}))}(s),function(e){var n=e.languages.javadoclike={parameter:{pattern:/(^\s*(?:\/{3}|\*|\/\*\*)\s*@(?:param|arg|arguments)\s+)\w+/m,lookbehind:!0},keyword:{pattern:/(^\s*(?:\/{3}|\*|\/\*\*)\s*|\{)@[a-z][a-zA-Z-]+\b/m,lookbehind:!0},punctuation:/[{}]/};Object.defineProperty(n,"addSupport",{value:function(n,t){"string"==typeof n&&(n=[n]),n.forEach((function(n){!function(n,t){var o="doc-comment",i=e.languages[n];if(i){var a=i[o];if(!a){var s={"doc-comment":{pattern:/(^|[^\\])\/\*\*[^/][\s\S]*?(?:\*\/|$)/,alias:"comment"}};a=(i=e.languages.insertBefore(n,"comment",s))[o]}if(a instanceof RegExp&&(a=i[o]={pattern:a}),Array.isArray(a))for(var r=0,c=a.length;r>>?=?|->|([-+&|])\2|[?:~]|[-+*/%&|^!=<>]=?)/m,lookbehind:!0}}),e.languages.insertBefore("java","class-name",{annotation:{alias:"punctuation",pattern:/(^|[^.])@\w+/,lookbehind:!0},namespace:{pattern:/(\b(?:exports|import(?:\s+static)?|module|open|opens|package|provides|requires|to|transitive|uses|with)\s+)[a-z]\w*(\.[a-z]\w*)+/,lookbehind:!0,inside:{punctuation:/\./}},generics:{pattern:/<(?:[\w\s,.&?]|<(?:[\w\s,.&?]|<(?:[\w\s,.&?]|<[\w\s,.&?]*>)*>)*>)*>/,inside:{"class-name":t,keyword:n,punctuation:/[<>(),.:]/,operator:/[?&|]/}}})}(s),function(e){function n(e,n){return"___"+e.toUpperCase()+n+"___"}Object.defineProperties(e.languages["markup-templating"]={},{buildPlaceholders:{value:function(t,o,i,a){if(t.language===o){var s=t.tokenStack=[];t.code=t.code.replace(i,(function(e){if("function"==typeof a&&!a(e))return e;for(var i,r=s.length;-1!==t.code.indexOf(i=n(o,r));)++r;return s[r]=e,i})),t.grammar=e.languages.markup}}},tokenizePlaceholders:{value:function(t,o){if(t.language===o&&t.tokenStack){t.grammar=e.languages[o];var i=0,a=Object.keys(t.tokenStack);!function s(r){for(var c=0;c=a.length);c++){var d=r[c];if("string"==typeof d||d.content&&"string"==typeof d.content){var l=a[i],u=t.tokenStack[l],p="string"==typeof d?d:d.content,m=n(o,l),f=p.indexOf(m);if(f>-1){++i;var b=p.substring(0,f),h=new e.Token(o,e.tokenize(u,t.grammar),"language-"+o,u),v=p.substring(f+m.length),g=[];b&&g.push.apply(g,s([b])),g.push(h),v&&g.push.apply(g,s([v])),"string"==typeof d?r.splice.apply(r,[c,1].concat(g)):d.content=g}}else d.content&&s(d.content)}return r}(t.tokens)}}}})}(s),function(e){e.languages.php=e.languages.extend("clike",{keyword:/\b(?:__halt_compiler|abstract|and|array|as|break|callable|case|catch|class|clone|const|continue|declare|default|die|do|echo|else|elseif|empty|enddeclare|endfor|endforeach|endif|endswitch|endwhile|eval|exit|extends|final|finally|for|foreach|function|global|goto|if|implements|include|include_once|instanceof|insteadof|interface|isset|list|namespace|new|or|parent|print|private|protected|public|require|require_once|return|static|switch|throw|trait|try|unset|use|var|while|xor|yield)\b/i,boolean:{pattern:/\b(?:false|true)\b/i,alias:"constant"},constant:[/\b[A-Z_][A-Z0-9_]*\b/,/\b(?:null)\b/i],comment:{pattern:/(^|[^\\])(?:\/\*[\s\S]*?\*\/|\/\/.*)/,lookbehind:!0}}),e.languages.insertBefore("php","string",{"shell-comment":{pattern:/(^|[^\\])#.*/,lookbehind:!0,alias:"comment"}}),e.languages.insertBefore("php","comment",{delimiter:{pattern:/\?>$|^<\?(?:php(?=\s)|=)?/i,alias:"important"}}),e.languages.insertBefore("php","keyword",{variable:/\$+(?:\w+\b|(?={))/i,package:{pattern:/(\\|namespace\s+|use\s+)[\w\\]+/,lookbehind:!0,inside:{punctuation:/\\/}}}),e.languages.insertBefore("php","operator",{property:{pattern:/(->)[\w]+/,lookbehind:!0}});var n={pattern:/{\$(?:{(?:{[^{}]+}|[^{}]+)}|[^{}])+}|(^|[^\\{])\$+(?:\w+(?:\[.+?]|->\w+)*)/,lookbehind:!0,inside:{rest:e.languages.php}};e.languages.insertBefore("php","string",{"nowdoc-string":{pattern:/<<<'([^']+)'(?:\r\n?|\n)(?:.*(?:\r\n?|\n))*?\1;/,greedy:!0,alias:"string",inside:{delimiter:{pattern:/^<<<'[^']+'|[a-z_]\w*;$/i,alias:"symbol",inside:{punctuation:/^<<<'?|[';]$/}}}},"heredoc-string":{pattern:/<<<(?:"([^"]+)"(?:\r\n?|\n)(?:.*(?:\r\n?|\n))*?\1;|([a-z_]\w*)(?:\r\n?|\n)(?:.*(?:\r\n?|\n))*?\2;)/i,greedy:!0,alias:"string",inside:{delimiter:{pattern:/^<<<(?:"[^"]+"|[a-z_]\w*)|[a-z_]\w*;$/i,alias:"symbol",inside:{punctuation:/^<<<"?|[";]$/}},interpolation:n}},"single-quoted-string":{pattern:/'(?:\\[\s\S]|[^\\'])*'/,greedy:!0,alias:"string"},"double-quoted-string":{pattern:/"(?:\\[\s\S]|[^\\"])*"/,greedy:!0,alias:"string",inside:{interpolation:n}}}),delete e.languages.php.string,e.hooks.add("before-tokenize",(function(n){if(/<\?/.test(n.code)){e.languages["markup-templating"].buildPlaceholders(n,"php",/<\?(?:[^"'/#]|\/(?![*/])|("|')(?:\\[\s\S]|(?!\1)[^\\])*\1|(?:\/\/|#)(?:[^?\n\r]|\?(?!>))*|\/\*[\s\S]*?(?:\*\/|$))*?(?:\?>|$)/gi)}})),e.hooks.add("after-tokenize",(function(n){e.languages["markup-templating"].tokenizePlaceholders(n,"php")}))}(s),function(e){var n=e.languages.javascript,t=/{(?:[^{}]|{(?:[^{}]|{[^{}]*})*})+}/.source,o="(@(?:param|arg|argument|property)\\s+(?:"+t+"\\s+)?)";e.languages.jsdoc=e.languages.extend("javadoclike",{parameter:{pattern:RegExp(o+/[$\w\xA0-\uFFFF.]+(?=\s|$)/.source),lookbehind:!0,inside:{punctuation:/\./}}}),e.languages.insertBefore("jsdoc","keyword",{"optional-parameter":{pattern:RegExp(o+/\[[$\w\xA0-\uFFFF.]+(?:=[^[\]]+)?\](?=\s|$)/.source),lookbehind:!0,inside:{parameter:{pattern:/(^\[)[$\w\xA0-\uFFFF\.]+/,lookbehind:!0,inside:{punctuation:/\./}},code:{pattern:/(=)[\s\S]*(?=\]$)/,lookbehind:!0,inside:n,alias:"language-javascript"},punctuation:/[=[\]]/}},"class-name":[{pattern:RegExp("(@[a-z]+\\s+)"+t),lookbehind:!0,inside:{punctuation:/[.,:?=<>|{}()[\]]/}},{pattern:/(@(?:augments|extends|class|interface|memberof!?|this)\s+)[A-Z]\w*(?:\.[A-Z]\w*)*/,lookbehind:!0,inside:{punctuation:/\./}}],example:{pattern:/(@example\s+)[^@]+?(?=\s*(?:\*\s*)?(?:@\w|\*\/))/,lookbehind:!0,inside:{code:{pattern:/^(\s*(?:\*\s*)?).+$/m,lookbehind:!0,inside:n,alias:"language-javascript"}}}}),e.languages.javadoclike.addSupport("javascript",e.languages.jsdoc)}(s),s.languages.actionscript=s.languages.extend("javascript",{keyword:/\b(?:as|break|case|catch|class|const|default|delete|do|else|extends|finally|for|function|if|implements|import|in|instanceof|interface|internal|is|native|new|null|package|private|protected|public|return|super|switch|this|throw|try|typeof|use|var|void|while|with|dynamic|each|final|get|include|namespace|native|override|set|static)\b/,operator:/\+\+|--|(?:[+\-*\/%^]|&&?|\|\|?|<>?>?|[!=]=?)=?|[~?@]/}),s.languages.actionscript["class-name"].alias="function",s.languages.markup&&s.languages.insertBefore("actionscript","string",{xml:{pattern:/(^|[^.])<\/?\w+(?:\s+[^\s>\/=]+=("|')(?:\\[\s\S]|(?!\2)[^\\])*\2)*\s*\/?>/,lookbehind:!0,inside:{rest:s.languages.markup}}}),function(e){var n=/#(?!\{).+/,t={pattern:/#\{[^}]+\}/,alias:"variable"};e.languages.coffeescript=e.languages.extend("javascript",{comment:n,string:[{pattern:/'(?:\\[\s\S]|[^\\'])*'/,greedy:!0},{pattern:/"(?:\\[\s\S]|[^\\"])*"/,greedy:!0,inside:{interpolation:t}}],keyword:/\b(?:and|break|by|catch|class|continue|debugger|delete|do|each|else|extend|extends|false|finally|for|if|in|instanceof|is|isnt|let|loop|namespace|new|no|not|null|of|off|on|or|own|return|super|switch|then|this|throw|true|try|typeof|undefined|unless|until|when|while|window|with|yes|yield)\b/,"class-member":{pattern:/@(?!\d)\w+/,alias:"variable"}}),e.languages.insertBefore("coffeescript","comment",{"multiline-comment":{pattern:/###[\s\S]+?###/,alias:"comment"},"block-regex":{pattern:/\/{3}[\s\S]*?\/{3}/,alias:"regex",inside:{comment:n,interpolation:t}}}),e.languages.insertBefore("coffeescript","string",{"inline-javascript":{pattern:/`(?:\\[\s\S]|[^\\`])*`/,inside:{delimiter:{pattern:/^`|`$/,alias:"punctuation"},rest:e.languages.javascript}},"multiline-string":[{pattern:/'''[\s\S]*?'''/,greedy:!0,alias:"string"},{pattern:/"""[\s\S]*?"""/,greedy:!0,alias:"string",inside:{interpolation:t}}]}),e.languages.insertBefore("coffeescript","keyword",{property:/(?!\d)\w+(?=\s*:(?!:))/}),delete e.languages.coffeescript["template-string"],e.languages.coffee=e.languages.coffeescript}(s),function(e){e.languages.insertBefore("javascript","function-variable",{"method-variable":{pattern:RegExp("(\\.\\s*)"+e.languages.javascript["function-variable"].pattern.source),lookbehind:!0,alias:["function-variable","method","function","property-access"]}}),e.languages.insertBefore("javascript","function",{method:{pattern:RegExp("(\\.\\s*)"+e.languages.javascript.function.source),lookbehind:!0,alias:["function","property-access"]}}),e.languages.insertBefore("javascript","constant",{"known-class-name":[{pattern:/\b(?:(?:(?:Uint|Int)(?:8|16|32)|Uint8Clamped|Float(?:32|64))?Array|ArrayBuffer|BigInt|Boolean|DataView|Date|Error|Function|Intl|JSON|Math|Number|Object|Promise|Proxy|Reflect|RegExp|String|Symbol|(?:Weak)?(?:Set|Map)|WebAssembly)\b/,alias:"class-name"},{pattern:/\b(?:[A-Z]\w*)Error\b/,alias:"class-name"}]}),e.languages.javascript.keyword.unshift({pattern:/\b(?:as|default|export|from|import)\b/,alias:"module"},{pattern:/\bnull\b/,alias:["null","nil"]},{pattern:/\bundefined\b/,alias:"nil"}),e.languages.insertBefore("javascript","operator",{spread:{pattern:/\.{3}/,alias:"operator"},arrow:{pattern:/=>/,alias:"operator"}}),e.languages.insertBefore("javascript","punctuation",{"property-access":{pattern:/(\.\s*)#?[_$a-zA-Z\xA0-\uFFFF][$\w\xA0-\uFFFF]*/,lookbehind:!0},"maybe-class-name":{pattern:/(^|[^$\w\xA0-\uFFFF])[A-Z][$\w\xA0-\uFFFF]+/,lookbehind:!0},dom:{pattern:/\b(?:document|location|navigator|performance|(?:local|session)Storage|window)\b/,alias:"variable"},console:{pattern:/\bconsole(?=\s*\.)/,alias:"class-name"}});for(var n=["function","function-variable","method","method-variable","property-access"],t=0;t))/i,delete e.languages.flow.parameter,e.languages.insertBefore("flow","operator",{"flow-punctuation":{pattern:/\{\||\|\}/,alias:"punctuation"}}),Array.isArray(e.languages.flow.keyword)||(e.languages.flow.keyword=[e.languages.flow.keyword]),e.languages.flow.keyword.unshift({pattern:/(^|[^$]\b)(?:type|opaque|declare|Class)\b(?!\$)/,lookbehind:!0},{pattern:/(^|[^$]\B)\$(?:await|Diff|Exact|Keys|ObjMap|PropertyType|Shape|Record|Supertype|Subtype|Enum)\b(?!\$)/,lookbehind:!0})}(s),s.languages.n4js=s.languages.extend("javascript",{keyword:/\b(?:any|Array|boolean|break|case|catch|class|const|constructor|continue|debugger|declare|default|delete|do|else|enum|export|extends|false|finally|for|from|function|get|if|implements|import|in|instanceof|interface|let|module|new|null|number|package|private|protected|public|return|set|static|string|super|switch|this|throw|true|try|typeof|var|void|while|with|yield)\b/}),s.languages.insertBefore("n4js","constant",{annotation:{pattern:/@+\w+/,alias:"operator"}}),s.languages.n4jsd=s.languages.n4js,s.languages.typescript=s.languages.extend("javascript",{keyword:/\b(?:abstract|as|async|await|break|case|catch|class|const|constructor|continue|debugger|declare|default|delete|do|else|enum|export|extends|finally|for|from|function|get|if|implements|import|in|instanceof|interface|is|keyof|let|module|namespace|new|null|of|package|private|protected|public|readonly|return|require|set|static|super|switch|this|throw|try|type|typeof|var|void|while|with|yield)\b/,builtin:/\b(?:string|Function|any|number|boolean|Array|symbol|console|Promise|unknown|never)\b/}),s.languages.ts=s.languages.typescript,function(e){var n=e.languages.javascript["template-string"],t=n.pattern.source,o=n.inside.interpolation,i=o.inside["interpolation-punctuation"],a=o.pattern.source;function s(n,o){if(e.languages[n])return{pattern:RegExp("((?:"+o+")\\s*)"+t),lookbehind:!0,greedy:!0,inside:{"template-punctuation":{pattern:/^`|`$/,alias:"string"},"embedded-code":{pattern:/[\s\S]+/,alias:n}}}}function r(e,n){return"___"+n.toUpperCase()+"_"+e+"___"}function c(n,t,o){var i={code:n,grammar:t,language:o};return e.hooks.run("before-tokenize",i),i.tokens=e.tokenize(i.code,i.grammar),e.hooks.run("after-tokenize",i),i.tokens}function d(n){var t={};t["interpolation-punctuation"]=i;var a=e.tokenize(n,t);if(3===a.length){var s=[1,1];s.push.apply(s,c(a[1],e.languages.javascript,"javascript")),a.splice.apply(a,s)}return new e.Token("interpolation",a,o.alias,n)}function l(n,t,o){var i=e.tokenize(n,{interpolation:{pattern:RegExp(a),lookbehind:!0}}),s=0,l={},u=c(i.map((function(e){if("string"==typeof e)return e;for(var t,i=e.content;-1!==n.indexOf(t=r(s++,o)););return l[t]=i,t})).join(""),t,o),p=Object.keys(l);return s=0,function e(n){for(var t=0;t=p.length)return;var o=n[t];if("string"==typeof o||"string"==typeof o.content){var i=p[s],a="string"==typeof o?o:o.content,r=a.indexOf(i);if(-1!==r){++s;var c=a.substring(0,r),u=d(l[i]),m=a.substring(r+i.length),f=[];if(c&&f.push(c),f.push(u),m){var b=[m];e(b),f.push.apply(f,b)}"string"==typeof o?(n.splice.apply(n,[t,1].concat(f)),t+=f.length-1):o.content=f}}else{var h=o.content;Array.isArray(h)?e(h):e([h])}}}(u),new e.Token(o,u,"language-"+o,n)}e.languages.javascript["template-string"]=[s("css",/\b(?:styled(?:\([^)]*\))?(?:\s*\.\s*\w+(?:\([^)]*\))*)*|css(?:\s*\.\s*(?:global|resolve))?|createGlobalStyle|keyframes)/.source),s("html",/\bhtml|\.\s*(?:inner|outer)HTML\s*\+?=/.source),s("svg",/\bsvg/.source),s("markdown",/\b(?:md|markdown)/.source),s("graphql",/\b(?:gql|graphql(?:\s*\.\s*experimental)?)/.source),n].filter(Boolean);var u={javascript:!0,js:!0,typescript:!0,ts:!0,jsx:!0,tsx:!0};function p(e){return"string"==typeof e?e:Array.isArray(e)?e.map(p).join(""):p(e.content)}e.hooks.add("after-tokenize",(function(n){n.language in u&&function n(t){for(var o=0,i=t.length;o/g,n),t&&(e=e+"|"+e.replace(/_/g,"\\*")),RegExp(/((?:^|[^\\])(?:\\{2})*)/.source+"(?:"+e+")")}var o=/(?:\\.|``.+?``|`[^`\r\n]+`|[^\\|\r\n`])+/.source,i=/\|?__(?:\|__)+\|?(?:(?:\r?\n|\r)|$)/.source.replace(/__/g,o),a=/\|?[ \t]*:?-{3,}:?[ \t]*(?:\|[ \t]*:?-{3,}:?[ \t]*)+\|?(?:\r?\n|\r)/.source;e.languages.markdown=e.languages.extend("markup",{}),e.languages.insertBefore("markdown","prolog",{blockquote:{pattern:/^>(?:[\t ]*>)*/m,alias:"punctuation"},table:{pattern:RegExp("^"+i+a+"(?:"+i+")*","m"),inside:{"table-data-rows":{pattern:RegExp("^("+i+a+")(?:"+i+")*$"),lookbehind:!0,inside:{"table-data":{pattern:RegExp(o),inside:e.languages.markdown},punctuation:/\|/}},"table-line":{pattern:RegExp("^("+i+")"+a+"$"),lookbehind:!0,inside:{punctuation:/\||:?-{3,}:?/}},"table-header-row":{pattern:RegExp("^"+i+"$"),inside:{"table-header":{pattern:RegExp(o),alias:"important",inside:e.languages.markdown},punctuation:/\|/}}}},code:[{pattern:/(^[ \t]*(?:\r?\n|\r))(?: {4}|\t).+(?:(?:\r?\n|\r)(?: {4}|\t).+)*/m,lookbehind:!0,alias:"keyword"},{pattern:/``.+?``|`[^`\r\n]+`/,alias:"keyword"},{pattern:/^```[\s\S]*?^```$/m,greedy:!0,inside:{"code-block":{pattern:/^(```.*(?:\r?\n|\r))[\s\S]+?(?=(?:\r?\n|\r)^```$)/m,lookbehind:!0},"code-language":{pattern:/^(```).+/,lookbehind:!0},punctuation:/```/}}],title:[{pattern:/\S.*(?:\r?\n|\r)(?:==+|--+)(?=[ \t]*$)/m,alias:"important",inside:{punctuation:/==+$|--+$/}},{pattern:/(^\s*)#+.+/m,lookbehind:!0,alias:"important",inside:{punctuation:/^#+|#+$/}}],hr:{pattern:/(^\s*)([*-])(?:[\t ]*\2){2,}(?=\s*$)/m,lookbehind:!0,alias:"punctuation"},list:{pattern:/(^\s*)(?:[*+-]|\d+\.)(?=[\t ].)/m,lookbehind:!0,alias:"punctuation"},"url-reference":{pattern:/!?\[[^\]]+\]:[\t ]+(?:\S+|<(?:\\.|[^>\\])+>)(?:[\t ]+(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|\((?:\\.|[^)\\])*\)))?/,inside:{variable:{pattern:/^(!?\[)[^\]]+/,lookbehind:!0},string:/(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|\((?:\\.|[^)\\])*\))$/,punctuation:/^[\[\]!:]|[<>]/},alias:"url"},bold:{pattern:t(/__(?:(?!_)|_(?:(?!_))+_)+__/.source,!0),lookbehind:!0,greedy:!0,inside:{content:{pattern:/(^..)[\s\S]+(?=..$)/,lookbehind:!0,inside:{}},punctuation:/\*\*|__/}},italic:{pattern:t(/_(?:(?!_)|__(?:(?!_))+__)+_/.source,!0),lookbehind:!0,greedy:!0,inside:{content:{pattern:/(^.)[\s\S]+(?=.$)/,lookbehind:!0,inside:{}},punctuation:/[*_]/}},strike:{pattern:t(/(~~?)(?:(?!~))+?\2/.source,!1),lookbehind:!0,greedy:!0,inside:{content:{pattern:/(^~~?)[\s\S]+(?=\1$)/,lookbehind:!0,inside:{}},punctuation:/~~?/}},url:{pattern:t(/!?\[(?:(?!\]))+\](?:\([^\s)]+(?:[\t ]+"(?:\\.|[^"\\])*")?\)| ?\[(?:(?!\]))+\])/.source,!1),lookbehind:!0,greedy:!0,inside:{variable:{pattern:/(\[)[^\]]+(?=\]$)/,lookbehind:!0},content:{pattern:/(^!?\[)[^\]]+(?=\])/,lookbehind:!0,inside:{}},string:{pattern:/"(?:\\.|[^"\\])*"(?=\)$)/}}}}),["url","bold","italic","strike"].forEach((function(n){["url","bold","italic","strike"].forEach((function(t){n!==t&&(e.languages.markdown[n].inside.content.inside[t]=e.languages.markdown[t])}))})),e.hooks.add("after-tokenize",(function(e){"markdown"!==e.language&&"md"!==e.language||function e(n){if(n&&"string"!=typeof n)for(var t=0,o=n.length;t",unchanged:" ",diff:"!"};Object.keys(n).forEach((function(t){var o=n[t],i=[];/^\w+$/.test(t)||i.push(/\w+/.exec(t)[0]),"diff"===t&&i.push("bold"),e.languages.diff[t]={pattern:RegExp("^(?:["+o+"].*(?:\r\n?|\n|(?![\\s\\S])))+","m"),alias:i}})),Object.defineProperty(e.languages.diff,"PREFIXES",{value:n})}(s),s.languages.git={comment:/^#.*/m,deleted:/^[-\u2013].*/m,inserted:/^\+.*/m,string:/("|')(?:\\.|(?!\1)[^\\\r\n])*\1/m,command:{pattern:/^.*\$ git .*$/m,inside:{parameter:/\s--?\w+/m}},coord:/^@@.*@@$/m,commit_sha1:/^commit \w{40}$/m},s.languages.go=s.languages.extend("clike",{keyword:/\b(?:break|case|chan|const|continue|default|defer|else|fallthrough|for|func|go(?:to)?|if|import|interface|map|package|range|return|select|struct|switch|type|var)\b/,builtin:/\b(?:bool|byte|complex(?:64|128)|error|float(?:32|64)|rune|string|u?int(?:8|16|32|64)?|uintptr|append|cap|close|complex|copy|delete|imag|len|make|new|panic|print(?:ln)?|real|recover)\b/,boolean:/\b(?:_|iota|nil|true|false)\b/,operator:/[*\/%^!=]=?|\+[=+]?|-[=-]?|\|[=|]?|&(?:=|&|\^=?)?|>(?:>=?|=)?|<(?:<=?|=|-)?|:=|\.\.\./,number:/(?:\b0x[a-f\d]+|(?:\b\d+\.?\d*|\B\.\d+)(?:e[-+]?\d+)?)i?/i,string:{pattern:/(["'`])(\\[\s\S]|(?!\1)[^\\])*\1/,greedy:!0}}),delete s.languages.go["class-name"],function(e){e.languages.handlebars={comment:/\{\{![\s\S]*?\}\}/,delimiter:{pattern:/^\{\{\{?|\}\}\}?$/i,alias:"punctuation"},string:/(["'])(?:\\.|(?!\1)[^\\\r\n])*\1/,number:/\b0x[\dA-Fa-f]+\b|(?:\b\d+\.?\d*|\B\.\d+)(?:[Ee][+-]?\d+)?/,boolean:/\b(?:true|false)\b/,block:{pattern:/^(\s*~?\s*)[#\/]\S+?(?=\s*~?\s*$|\s)/i,lookbehind:!0,alias:"keyword"},brackets:{pattern:/\[[^\]]+\]/,inside:{punctuation:/\[|\]/,variable:/[\s\S]+/}},punctuation:/[!"#%&'()*+,.\/;<=>@\[\\\]^`{|}~]/,variable:/[^!"#%&'()*+,.\/;<=>@\[\\\]^`{|}~\s]+/},e.hooks.add("before-tokenize",(function(n){e.languages["markup-templating"].buildPlaceholders(n,"handlebars",/\{\{\{[\s\S]+?\}\}\}|\{\{[\s\S]+?\}\}/g)})),e.hooks.add("after-tokenize",(function(n){e.languages["markup-templating"].tokenizePlaceholders(n,"handlebars")}))}(s),s.languages.json={property:{pattern:/"(?:\\.|[^\\"\r\n])*"(?=\s*:)/,greedy:!0},string:{pattern:/"(?:\\.|[^\\"\r\n])*"(?!\s*:)/,greedy:!0},comment:/\/\/.*|\/\*[\s\S]*?(?:\*\/|$)/,number:/-?\d+\.?\d*(e[+-]?\d+)?/i,punctuation:/[{}[\],]/,operator:/:/,boolean:/\b(?:true|false)\b/,null:{pattern:/\bnull\b/,alias:"keyword"}},s.languages.less=s.languages.extend("css",{comment:[/\/\*[\s\S]*?\*\//,{pattern:/(^|[^\\])\/\/.*/,lookbehind:!0}],atrule:{pattern:/@[\w-]+?(?:\([^{}]+\)|[^(){};])*?(?=\s*\{)/i,inside:{punctuation:/[:()]/}},selector:{pattern:/(?:@\{[\w-]+\}|[^{};\s@])(?:@\{[\w-]+\}|\([^{}]*\)|[^{};@])*?(?=\s*\{)/,inside:{variable:/@+[\w-]+/}},property:/(?:@\{[\w-]+\}|[\w-])+(?:\+_?)?(?=\s*:)/i,operator:/[+\-*\/]/}),s.languages.insertBefore("less","property",{variable:[{pattern:/@[\w-]+\s*:/,inside:{punctuation:/:/}},/@@?[\w-]+/],"mixin-usage":{pattern:/([{;]\s*)[.#](?!\d)[\w-]+.*?(?=[(;])/,lookbehind:!0,alias:"function"}}),s.languages.makefile={comment:{pattern:/(^|[^\\])#(?:\\(?:\r\n|[\s\S])|[^\\\r\n])*/,lookbehind:!0},string:{pattern:/(["'])(?:\\(?:\r\n|[\s\S])|(?!\1)[^\\\r\n])*\1/,greedy:!0},builtin:/\.[A-Z][^:#=\s]+(?=\s*:(?!=))/,symbol:{pattern:/^[^:=\r\n]+(?=\s*:(?!=))/m,inside:{variable:/\$+(?:[^(){}:#=\s]+|(?=[({]))/}},variable:/\$+(?:[^(){}:#=\s]+|\([@*%<^+?][DF]\)|(?=[({]))/,keyword:[/-include\b|\b(?:define|else|endef|endif|export|ifn?def|ifn?eq|include|override|private|sinclude|undefine|unexport|vpath)\b/,{pattern:/(\()(?:addsuffix|abspath|and|basename|call|dir|error|eval|file|filter(?:-out)?|findstring|firstword|flavor|foreach|guile|if|info|join|lastword|load|notdir|or|origin|patsubst|realpath|shell|sort|strip|subst|suffix|value|warning|wildcard|word(?:s|list)?)(?=[ \t])/,lookbehind:!0}],operator:/(?:::|[?:+!])?=|[|@]/,punctuation:/[:;(){}]/},s.languages.objectivec=s.languages.extend("c",{keyword:/\b(?:asm|typeof|inline|auto|break|case|char|const|continue|default|do|double|else|enum|extern|float|for|goto|if|int|long|register|return|short|signed|sizeof|static|struct|switch|typedef|union|unsigned|void|volatile|while|in|self|super)\b|(?:@interface|@end|@implementation|@protocol|@class|@public|@protected|@private|@property|@try|@catch|@finally|@throw|@synthesize|@dynamic|@selector)\b/,string:/("|')(?:\\(?:\r\n|[\s\S])|(?!\1)[^\\\r\n])*\1|@"(?:\\(?:\r\n|[\s\S])|[^"\\\r\n])*"/,operator:/-[->]?|\+\+?|!=?|<>?=?|==?|&&?|\|\|?|[~^%?*\/@]/}),delete s.languages.objectivec["class-name"],s.languages.ocaml={comment:/\(\*[\s\S]*?\*\)/,string:[{pattern:/"(?:\\.|[^\\\r\n"])*"/,greedy:!0},{pattern:/(['`])(?:\\(?:\d+|x[\da-f]+|.)|(?!\1)[^\\\r\n])\1/i,greedy:!0}],number:/\b(?:0x[\da-f][\da-f_]+|(?:0[bo])?\d[\d_]*\.?[\d_]*(?:e[+-]?[\d_]+)?)/i,type:{pattern:/\B['`]\w*/,alias:"variable"},directive:{pattern:/\B#\w+/,alias:"function"},keyword:/\b(?:as|assert|begin|class|constraint|do|done|downto|else|end|exception|external|for|fun|function|functor|if|in|include|inherit|initializer|lazy|let|match|method|module|mutable|new|object|of|open|prefix|private|rec|then|sig|struct|to|try|type|val|value|virtual|where|while|with)\b/,boolean:/\b(?:false|true)\b/,operator:/:=|[=<>@^|&+\-*\/$%!?~][!$%&*+\-.\/:<=>?@^|~]*|\b(?:and|asr|land|lor|lxor|lsl|lsr|mod|nor|or)\b/,punctuation:/[(){}\[\]|_.,:;]/},s.languages.python={comment:{pattern:/(^|[^\\])#.*/,lookbehind:!0},"string-interpolation":{pattern:/(?:f|rf|fr)(?:("""|''')[\s\S]+?\1|("|')(?:\\.|(?!\2)[^\\\r\n])*\2)/i,greedy:!0,inside:{interpolation:{pattern:/((?:^|[^{])(?:{{)*){(?!{)(?:[^{}]|{(?!{)(?:[^{}]|{(?!{)(?:[^{}])+})+})+}/,lookbehind:!0,inside:{"format-spec":{pattern:/(:)[^:(){}]+(?=}$)/,lookbehind:!0},"conversion-option":{pattern:/![sra](?=[:}]$)/,alias:"punctuation"},rest:null}},string:/[\s\S]+/}},"triple-quoted-string":{pattern:/(?:[rub]|rb|br)?("""|''')[\s\S]+?\1/i,greedy:!0,alias:"string"},string:{pattern:/(?:[rub]|rb|br)?("|')(?:\\.|(?!\1)[^\\\r\n])*\1/i,greedy:!0},function:{pattern:/((?:^|\s)def[ \t]+)[a-zA-Z_]\w*(?=\s*\()/g,lookbehind:!0},"class-name":{pattern:/(\bclass\s+)\w+/i,lookbehind:!0},decorator:{pattern:/(^\s*)@\w+(?:\.\w+)*/i,lookbehind:!0,alias:["annotation","punctuation"],inside:{punctuation:/\./}},keyword:/\b(?:and|as|assert|async|await|break|class|continue|def|del|elif|else|except|exec|finally|for|from|global|if|import|in|is|lambda|nonlocal|not|or|pass|print|raise|return|try|while|with|yield)\b/,builtin:/\b(?:__import__|abs|all|any|apply|ascii|basestring|bin|bool|buffer|bytearray|bytes|callable|chr|classmethod|cmp|coerce|compile|complex|delattr|dict|dir|divmod|enumerate|eval|execfile|file|filter|float|format|frozenset|getattr|globals|hasattr|hash|help|hex|id|input|int|intern|isinstance|issubclass|iter|len|list|locals|long|map|max|memoryview|min|next|object|oct|open|ord|pow|property|range|raw_input|reduce|reload|repr|reversed|round|set|setattr|slice|sorted|staticmethod|str|sum|super|tuple|type|unichr|unicode|vars|xrange|zip)\b/,boolean:/\b(?:True|False|None)\b/,number:/(?:\b(?=\d)|\B(?=\.))(?:0[bo])?(?:(?:\d|0x[\da-f])[\da-f]*\.?\d*|\.\d+)(?:e[+-]?\d+)?j?\b/i,operator:/[-+%=]=?|!=|\*\*?=?|\/\/?=?|<[<=>]?|>[=>]?|[&|^~]/,punctuation:/[{}[\];(),.:]/},s.languages.python["string-interpolation"].inside.interpolation.inside.rest=s.languages.python,s.languages.py=s.languages.python,s.languages.reason=s.languages.extend("clike",{comment:{pattern:/(^|[^\\])\/\*[\s\S]*?\*\//,lookbehind:!0},string:{pattern:/"(?:\\(?:\r\n|[\s\S])|[^\\\r\n"])*"/,greedy:!0},"class-name":/\b[A-Z]\w*/,keyword:/\b(?:and|as|assert|begin|class|constraint|do|done|downto|else|end|exception|external|for|fun|function|functor|if|in|include|inherit|initializer|lazy|let|method|module|mutable|new|nonrec|object|of|open|or|private|rec|sig|struct|switch|then|to|try|type|val|virtual|when|while|with)\b/,operator:/\.{3}|:[:=]|\|>|->|=(?:==?|>)?|<=?|>=?|[|^?'#!~`]|[+\-*\/]\.?|\b(?:mod|land|lor|lxor|lsl|lsr|asr)\b/}),s.languages.insertBefore("reason","class-name",{character:{pattern:/'(?:\\x[\da-f]{2}|\\o[0-3][0-7][0-7]|\\\d{3}|\\.|[^'\\\r\n])'/,alias:"string"},constructor:{pattern:/\b[A-Z]\w*\b(?!\s*\.)/,alias:"variable"},label:{pattern:/\b[a-z]\w*(?=::)/,alias:"symbol"}}),delete s.languages.reason.function,function(e){e.languages.sass=e.languages.extend("css",{comment:{pattern:/^([ \t]*)\/[\/*].*(?:(?:\r?\n|\r)\1[ \t]+.+)*/m,lookbehind:!0}}),e.languages.insertBefore("sass","atrule",{"atrule-line":{pattern:/^(?:[ \t]*)[@+=].+/m,inside:{atrule:/(?:@[\w-]+|[+=])/m}}}),delete e.languages.sass.atrule;var n=/\$[-\w]+|#\{\$[-\w]+\}/,t=[/[+*\/%]|[=!]=|<=?|>=?|\b(?:and|or|not)\b/,{pattern:/(\s+)-(?=\s)/,lookbehind:!0}];e.languages.insertBefore("sass","property",{"variable-line":{pattern:/^[ \t]*\$.+/m,inside:{punctuation:/:/,variable:n,operator:t}},"property-line":{pattern:/^[ \t]*(?:[^:\s]+ *:.*|:[^:\s]+.*)/m,inside:{property:[/[^:\s]+(?=\s*:)/,{pattern:/(:)[^:\s]+/,lookbehind:!0}],punctuation:/:/,variable:n,operator:t,important:e.languages.sass.important}}}),delete e.languages.sass.property,delete e.languages.sass.important,e.languages.insertBefore("sass","punctuation",{selector:{pattern:/([ \t]*)\S(?:,?[^,\r\n]+)*(?:,(?:\r?\n|\r)\1[ \t]+\S(?:,?[^,\r\n]+)*)*/,lookbehind:!0}})}(s),s.languages.scss=s.languages.extend("css",{comment:{pattern:/(^|[^\\])(?:\/\*[\s\S]*?\*\/|\/\/.*)/,lookbehind:!0},atrule:{pattern:/@[\w-]+(?:\([^()]+\)|[^(])*?(?=\s+[{;])/,inside:{rule:/@[\w-]+/}},url:/(?:[-a-z]+-)?url(?=\()/i,selector:{pattern:/(?=\S)[^@;{}()]?(?:[^@;{}()]|#\{\$[-\w]+\})+(?=\s*\{(?:\}|\s|[^}]+[:{][^}]+))/m,inside:{parent:{pattern:/&/,alias:"important"},placeholder:/%[-\w]+/,variable:/\$[-\w]+|#\{\$[-\w]+\}/}},property:{pattern:/(?:[\w-]|\$[-\w]+|#\{\$[-\w]+\})+(?=\s*:)/,inside:{variable:/\$[-\w]+|#\{\$[-\w]+\}/}}}),s.languages.insertBefore("scss","atrule",{keyword:[/@(?:if|else(?: if)?|for|each|while|import|extend|debug|warn|mixin|include|function|return|content)/i,{pattern:/( +)(?:from|through)(?= )/,lookbehind:!0}]}),s.languages.insertBefore("scss","important",{variable:/\$[-\w]+|#\{\$[-\w]+\}/}),s.languages.insertBefore("scss","function",{placeholder:{pattern:/%[-\w]+/,alias:"selector"},statement:{pattern:/\B!(?:default|optional)\b/i,alias:"keyword"},boolean:/\b(?:true|false)\b/,null:{pattern:/\bnull\b/,alias:"keyword"},operator:{pattern:/(\s)(?:[-+*\/%]|[=!]=|<=?|>=?|and|or|not)(?=\s)/,lookbehind:!0}}),s.languages.scss.atrule.inside.rest=s.languages.scss,s.languages.sql={comment:{pattern:/(^|[^\\])(?:\/\*[\s\S]*?\*\/|(?:--|\/\/|#).*)/,lookbehind:!0},variable:[{pattern:/@(["'`])(?:\\[\s\S]|(?!\1)[^\\])+\1/,greedy:!0},/@[\w.$]+/],string:{pattern:/(^|[^@\\])("|')(?:\\[\s\S]|(?!\2)[^\\]|\2\2)*\2/,greedy:!0,lookbehind:!0},function:/\b(?:AVG|COUNT|FIRST|FORMAT|LAST|LCASE|LEN|MAX|MID|MIN|MOD|NOW|ROUND|SUM|UCASE)(?=\s*\()/i,keyword:/\b(?:ACTION|ADD|AFTER|ALGORITHM|ALL|ALTER|ANALYZE|ANY|APPLY|AS|ASC|AUTHORIZATION|AUTO_INCREMENT|BACKUP|BDB|BEGIN|BERKELEYDB|BIGINT|BINARY|BIT|BLOB|BOOL|BOOLEAN|BREAK|BROWSE|BTREE|BULK|BY|CALL|CASCADED?|CASE|CHAIN|CHAR(?:ACTER|SET)?|CHECK(?:POINT)?|CLOSE|CLUSTERED|COALESCE|COLLATE|COLUMNS?|COMMENT|COMMIT(?:TED)?|COMPUTE|CONNECT|CONSISTENT|CONSTRAINT|CONTAINS(?:TABLE)?|CONTINUE|CONVERT|CREATE|CROSS|CURRENT(?:_DATE|_TIME|_TIMESTAMP|_USER)?|CURSOR|CYCLE|DATA(?:BASES?)?|DATE(?:TIME)?|DAY|DBCC|DEALLOCATE|DEC|DECIMAL|DECLARE|DEFAULT|DEFINER|DELAYED|DELETE|DELIMITERS?|DENY|DESC|DESCRIBE|DETERMINISTIC|DISABLE|DISCARD|DISK|DISTINCT|DISTINCTROW|DISTRIBUTED|DO|DOUBLE|DROP|DUMMY|DUMP(?:FILE)?|DUPLICATE|ELSE(?:IF)?|ENABLE|ENCLOSED|END|ENGINE|ENUM|ERRLVL|ERRORS|ESCAPED?|EXCEPT|EXEC(?:UTE)?|EXISTS|EXIT|EXPLAIN|EXTENDED|FETCH|FIELDS|FILE|FILLFACTOR|FIRST|FIXED|FLOAT|FOLLOWING|FOR(?: EACH ROW)?|FORCE|FOREIGN|FREETEXT(?:TABLE)?|FROM|FULL|FUNCTION|GEOMETRY(?:COLLECTION)?|GLOBAL|GOTO|GRANT|GROUP|HANDLER|HASH|HAVING|HOLDLOCK|HOUR|IDENTITY(?:_INSERT|COL)?|IF|IGNORE|IMPORT|INDEX|INFILE|INNER|INNODB|INOUT|INSERT|INT|INTEGER|INTERSECT|INTERVAL|INTO|INVOKER|ISOLATION|ITERATE|JOIN|KEYS?|KILL|LANGUAGE|LAST|LEAVE|LEFT|LEVEL|LIMIT|LINENO|LINES|LINESTRING|LOAD|LOCAL|LOCK|LONG(?:BLOB|TEXT)|LOOP|MATCH(?:ED)?|MEDIUM(?:BLOB|INT|TEXT)|MERGE|MIDDLEINT|MINUTE|MODE|MODIFIES|MODIFY|MONTH|MULTI(?:LINESTRING|POINT|POLYGON)|NATIONAL|NATURAL|NCHAR|NEXT|NO|NONCLUSTERED|NULLIF|NUMERIC|OFF?|OFFSETS?|ON|OPEN(?:DATASOURCE|QUERY|ROWSET)?|OPTIMIZE|OPTION(?:ALLY)?|ORDER|OUT(?:ER|FILE)?|OVER|PARTIAL|PARTITION|PERCENT|PIVOT|PLAN|POINT|POLYGON|PRECEDING|PRECISION|PREPARE|PREV|PRIMARY|PRINT|PRIVILEGES|PROC(?:EDURE)?|PUBLIC|PURGE|QUICK|RAISERROR|READS?|REAL|RECONFIGURE|REFERENCES|RELEASE|RENAME|REPEAT(?:ABLE)?|REPLACE|REPLICATION|REQUIRE|RESIGNAL|RESTORE|RESTRICT|RETURNS?|REVOKE|RIGHT|ROLLBACK|ROUTINE|ROW(?:COUNT|GUIDCOL|S)?|RTREE|RULE|SAVE(?:POINT)?|SCHEMA|SECOND|SELECT|SERIAL(?:IZABLE)?|SESSION(?:_USER)?|SET(?:USER)?|SHARE|SHOW|SHUTDOWN|SIMPLE|SMALLINT|SNAPSHOT|SOME|SONAME|SQL|START(?:ING)?|STATISTICS|STATUS|STRIPED|SYSTEM_USER|TABLES?|TABLESPACE|TEMP(?:ORARY|TABLE)?|TERMINATED|TEXT(?:SIZE)?|THEN|TIME(?:STAMP)?|TINY(?:BLOB|INT|TEXT)|TOP?|TRAN(?:SACTIONS?)?|TRIGGER|TRUNCATE|TSEQUAL|TYPES?|UNBOUNDED|UNCOMMITTED|UNDEFINED|UNION|UNIQUE|UNLOCK|UNPIVOT|UNSIGNED|UPDATE(?:TEXT)?|USAGE|USE|USER|USING|VALUES?|VAR(?:BINARY|CHAR|CHARACTER|YING)|VIEW|WAITFOR|WARNINGS|WHEN|WHERE|WHILE|WITH(?: ROLLUP|IN)?|WORK|WRITE(?:TEXT)?|YEAR)\b/i,boolean:/\b(?:TRUE|FALSE|NULL)\b/i,number:/\b0x[\da-f]+\b|\b\d+\.?\d*|\B\.\d+\b/i,operator:/[-+*\/=%^~]|&&?|\|\|?|!=?|<(?:=>?|<|>)?|>[>=]?|\b(?:AND|BETWEEN|IN|LIKE|NOT|OR|IS|DIV|REGEXP|RLIKE|SOUNDS LIKE|XOR)\b/i,punctuation:/[;[\]()`,.]/},function(e){var n={url:/url\((["']?).*?\1\)/i,string:{pattern:/("|')(?:(?!\1)[^\\\r\n]|\\(?:\r\n|[\s\S]))*\1/,greedy:!0},interpolation:null,func:null,important:/\B!(?:important|optional)\b/i,keyword:{pattern:/(^|\s+)(?:(?:if|else|for|return|unless)(?=\s+|$)|@[\w-]+)/,lookbehind:!0},hexcode:/#[\da-f]{3,6}/i,number:/\b\d+(?:\.\d+)?%?/,boolean:/\b(?:true|false)\b/,operator:[/~|[+!\/%<>?=]=?|[-:]=|\*[*=]?|\.+|&&|\|\||\B-\B|\b(?:and|in|is(?: a| defined| not|nt)?|not|or)\b/],punctuation:/[{}()\[\];:,]/};n.interpolation={pattern:/\{[^\r\n}:]+\}/,alias:"variable",inside:{delimiter:{pattern:/^{|}$/,alias:"punctuation"},rest:n}},n.func={pattern:/[\w-]+\([^)]*\).*/,inside:{function:/^[^(]+/,rest:n}},e.languages.stylus={comment:{pattern:/(^|[^\\])(\/\*[\s\S]*?\*\/|\/\/.*)/,lookbehind:!0},"atrule-declaration":{pattern:/(^\s*)@.+/m,lookbehind:!0,inside:{atrule:/^@[\w-]+/,rest:n}},"variable-declaration":{pattern:/(^[ \t]*)[\w$-]+\s*.?=[ \t]*(?:(?:\{[^}]*\}|.+)|$)/m,lookbehind:!0,inside:{variable:/^\S+/,rest:n}},statement:{pattern:/(^[ \t]*)(?:if|else|for|return|unless)[ \t]+.+/m,lookbehind:!0,inside:{keyword:/^\S+/,rest:n}},"property-declaration":{pattern:/((?:^|\{)([ \t]*))(?:[\w-]|\{[^}\r\n]+\})+(?:\s*:\s*|[ \t]+)[^{\r\n]*(?:;|[^{\r\n,](?=$)(?!(\r?\n|\r)(?:\{|\2[ \t]+)))/m,lookbehind:!0,inside:{property:{pattern:/^[^\s:]+/,inside:{interpolation:n.interpolation}},rest:n}},selector:{pattern:/(^[ \t]*)(?:(?=\S)(?:[^{}\r\n:()]|::?[\w-]+(?:\([^)\r\n]*\))?|\{[^}\r\n]+\})+)(?:(?:\r?\n|\r)(?:\1(?:(?=\S)(?:[^{}\r\n:()]|::?[\w-]+(?:\([^)\r\n]*\))?|\{[^}\r\n]+\})+)))*(?:,$|\{|(?=(?:\r?\n|\r)(?:\{|\1[ \t]+)))/m,lookbehind:!0,inside:{interpolation:n.interpolation,punctuation:/[{},]/}},func:n.func,string:n.string,interpolation:n.interpolation,punctuation:/[{}()\[\];:.]/}}(s);var r=s.util.clone(s.languages.typescript);s.languages.tsx=s.languages.extend("jsx",r),s.languages.wasm={comment:[/\(;[\s\S]*?;\)/,{pattern:/;;.*/,greedy:!0}],string:{pattern:/"(?:\\[\s\S]|[^"\\])*"/,greedy:!0},keyword:[{pattern:/\b(?:align|offset)=/,inside:{operator:/=/}},{pattern:/\b(?:(?:f32|f64|i32|i64)(?:\.(?:abs|add|and|ceil|clz|const|convert_[su]\/i(?:32|64)|copysign|ctz|demote\/f64|div(?:_[su])?|eqz?|extend_[su]\/i32|floor|ge(?:_[su])?|gt(?:_[su])?|le(?:_[su])?|load(?:(?:8|16|32)_[su])?|lt(?:_[su])?|max|min|mul|nearest|neg?|or|popcnt|promote\/f32|reinterpret\/[fi](?:32|64)|rem_[su]|rot[lr]|shl|shr_[su]|store(?:8|16|32)?|sqrt|sub|trunc(?:_[su]\/f(?:32|64))?|wrap\/i64|xor))?|memory\.(?:grow|size))\b/,inside:{punctuation:/\./}},/\b(?:anyfunc|block|br(?:_if|_table)?|call(?:_indirect)?|data|drop|elem|else|end|export|func|get_(?:global|local)|global|if|import|local|loop|memory|module|mut|nop|offset|param|result|return|select|set_(?:global|local)|start|table|tee_local|then|type|unreachable)\b/],variable:/\$[\w!#$%&'*+\-./:<=>?@\\^_`|~]+/i,number:/[+-]?\b(?:\d(?:_?\d)*(?:\.\d(?:_?\d)*)?(?:[eE][+-]?\d(?:_?\d)*)?|0x[\da-fA-F](?:_?[\da-fA-F])*(?:\.[\da-fA-F](?:_?[\da-fA-D])*)?(?:[pP][+-]?\d(?:_?\d)*)?)\b|\binf\b|\bnan(?::0x[\da-fA-F](?:_?[\da-fA-D])*)?\b/,punctuation:/[()]/},s.languages.yaml={scalar:{pattern:/([\-:]\s*(?:![^\s]+)?[ \t]*[|>])[ \t]*(?:((?:\r?\n|\r)[ \t]+)[^\r\n]+(?:\2[^\r\n]+)*)/,lookbehind:!0,alias:"string"},comment:/#.*/,key:{pattern:/(\s*(?:^|[:\-,[{\r\n?])[ \t]*(?:![^\s]+)?[ \t]*)[^\r\n{[\]},#\s]+?(?=\s*:\s)/,lookbehind:!0,alias:"atrule"},directive:{pattern:/(^[ \t]*)%.+/m,lookbehind:!0,alias:"important"},datetime:{pattern:/([:\-,[{]\s*(?:![^\s]+)?[ \t]*)(?:\d{4}-\d\d?-\d\d?(?:[tT]|[ \t]+)\d\d?:\d{2}:\d{2}(?:\.\d*)?[ \t]*(?:Z|[-+]\d\d?(?::\d{2})?)?|\d{4}-\d{2}-\d{2}|\d\d?:\d{2}(?::\d{2}(?:\.\d*)?)?)(?=[ \t]*(?:$|,|]|}))/m,lookbehind:!0,alias:"number"},boolean:{pattern:/([:\-,[{]\s*(?:![^\s]+)?[ \t]*)(?:true|false)[ \t]*(?=$|,|]|})/im,lookbehind:!0,alias:"important"},null:{pattern:/([:\-,[{]\s*(?:![^\s]+)?[ \t]*)(?:null|~)[ \t]*(?=$|,|]|})/im,lookbehind:!0,alias:"important"},string:{pattern:/([:\-,[{]\s*(?:![^\s]+)?[ \t]*)("|')(?:(?!\2)[^\\\r\n]|\\.)*\2(?=[ \t]*(?:$|,|]|}|\s*#))/m,lookbehind:!0,greedy:!0},number:{pattern:/([:\-,[{]\s*(?:![^\s]+)?[ \t]*)[+-]?(?:0x[\da-f]+|0o[0-7]+|(?:\d+\.?\d*|\.?\d+)(?:e[+-]?\d+)?|\.inf|\.nan)[ \t]*(?=$|,|]|})/im,lookbehind:!0},tag:/![^\s]+/,important:/[&*][\w]+/,punctuation:/---|[:[\]{}\-,|>?]|\.\.\./},s.languages.yml=s.languages.yaml,n.a=s},function(e,n,t){"use strict";var o=Object.getOwnPropertySymbols,i=Object.prototype.hasOwnProperty,a=Object.prototype.propertyIsEnumerable;function s(e){if(null==e)throw new TypeError("Object.assign cannot be called with null or undefined");return Object(e)}e.exports=function(){try{if(!Object.assign)return!1;var e=new String("abc");if(e[5]="de","5"===Object.getOwnPropertyNames(e)[0])return!1;for(var n={},t=0;t<10;t++)n["_"+String.fromCharCode(t)]=t;if("0123456789"!==Object.getOwnPropertyNames(n).map((function(e){return n[e]})).join(""))return!1;var o={};return"abcdefghijklmnopqrst".split("").forEach((function(e){o[e]=e})),"abcdefghijklmnopqrst"===Object.keys(Object.assign({},o)).join("")}catch(i){return!1}}()?Object.assign:function(e,n){for(var t,r,c=s(e),d=1;dA.length&&A.push(e)}function j(e,n,t,o){var i=typeof e;"undefined"!==i&&"boolean"!==i||(e=null);var r=!1;if(null===e)r=!0;else switch(i){case"string":case"number":r=!0;break;case"object":switch(e.$$typeof){case a:case s:r=!0}}if(r)return t(o,e,""===n?"."+L(e,0):n),1;if(r=0,n=""===n?".":n+":",Array.isArray(e))for(var c=0;c